diff --git a/DEVELOPING.md b/DEVELOPING.md
new file mode 100644
--- /dev/null
+++ b/DEVELOPING.md
@@ -0,0 +1,703 @@
+# Developing wireform-parquet
+
+This guide is for maintainers working on compatibility, validation and performance.
+For installation and everyday use, start with the [README](README.md). The
+repository's [development guidelines](https://github.com/iand675/wireform-/blob/main/AGENTS.md) cover the toolchain,
+generated sources, C harness and benchmark discipline.
+
+## Build and test
+
+Run these commands from the repository root:
+
+```sh
+cabal build wireform-parquet:tests \
+  wireform-parquet:exe:wireform-parquet-interop-probe \
+  wireform-parquet:exe:wireform-parquet-reverse-probe -fbrotli
+cabal test wireform-parquet:tests --test-show-details=direct
+```
+
+Validate the default and minimal codec builds too; enabling every optional
+codec does not check their disabled branches. Native library setup is covered
+in the repository guidelines and the README.
+
+## External compatibility checks
+
+The scripts in [`scripts/`](scripts/) exercise the public APIs against
+independent implementations, primarily Arrow C++, arrow-rs, DuckDB and Polars.
+They require their respective Python/Rust dependencies and built native probes.
+Obtain probe paths with `cabal list-bin` for the executable targets above.
+
+| Area | Driver |
+| --- | --- |
+| Standard corpus, including malformed files | [`parquet_corpus.py`](scripts/parquet_corpus.py) |
+| Compression and malformed streams | [`parquet_codec_interop.py`](scripts/parquet_codec_interop.py), [`parquet_lzo_interop.py`](scripts/parquet_lzo_interop.py) |
+| Schema boundaries and projections | [`parquet_schema_interop.py`](scripts/parquet_schema_interop.py), [`parquet_projection_interop.py`](scripts/parquet_projection_interop.py) |
+| Large offsets and the large-map fixture | [`parquet_large_offset_interop.py`](scripts/parquet_large_offset_interop.py), [`parquet_large_map_interop.py`](scripts/parquet_large_map_interop.py) |
+| Nested values and timestamps | [`parquet_nested_types_interop.py`](scripts/parquet_nested_types_interop.py), [`parquet_timestamp_interop.py`](scripts/parquet_timestamp_interop.py) |
+| Variant values and shredding | [`parquet_variant_interop.py`](scripts/parquet_variant_interop.py), [`parquet_variant_typed_interop.py`](scripts/parquet_variant_typed_interop.py), [`parquet_variant_write_interop.py`](scripts/parquet_variant_write_interop.py) |
+| Encrypted writes | [`parquet_encryption_interop.py`](scripts/parquet_encryption_interop.py) |
+
+The ordinary corpus driver uses heap, timeout and uncompressed-size limits.
+Use `--include-bad-data` for adversarial fixtures and `--include-large-map` to
+verify the large-map fixture through 64-bit Arrow offsets. That check needs
+several GiB of RAM. It compares complete buffers using hashes and one-row C++
+batches rather than constructing gigabyte Python strings.
+
+The ordinary corpus glob does **not** include `.parquet.encrypted` fixtures.
+Those require separate encryption coverage. A green ordinary-corpus run, a
+successful round-trip, or a reference implementation rejecting a value does
+not establish complete Parquet conformance. Record resource limits and
+reference limitations explicitly, and compare actual values as well as schemas.
+
+## Implementation and compatibility notes
+
+Both flat writers honor compression, V1/V2 pages, requested bloom filters and
+the page-index toggle. Page indexes are generated by default from the actual
+page offsets, sizes and statistics. Unsupported codecs return errors instead
+of silently changing the requested compression. The lower-level mixed writer
+`buildParquetFileMixedWithAux` returns `Either String ByteString`; the pure
+high-level writer reports invalid inputs with a descriptive exception.
+
+`LZO` reads and writes raw LZO1X page blocks without an external LZO library
+or extra framing. Both page versions and dictionary pages are supported;
+V2 definition and repetition levels remain uncompressed. The shared
+`Columnar.LZO` decoder checks the stream and output budget before allocating
+its result. `scripts/parquet_lzo_interop.py` checks both directions against
+liblzo2 and PyArrow, including nested, nullable and empty columns.
+
+Page readers check the exact decoded size against the page header. GZip,
+Snappy, Zstandard, LZ4_RAW, LZO and optional Brotli reject an output that
+exceeds that destination before allocating the full expanded value stream.
+All-null V2 pages may omit their value section; a nonempty section is still
+validated. Empty LZ4_RAW sections use the standard final zero token.
+`scripts/parquet_codec_interop.py` compares enabled codecs with Apache Arrow
+C++, in both page versions, with dictionaries, nulls and malformed streams.
+
+Checked file/Arrow schema planning requires a root child count, a repetition
+type on every non-root node, child counts on groups and no child count on
+primitives. The root repetition marker does not add a level. The default
+checked schema nesting limit is 128; low-level column-path level lookup is
+iterative and does not impose that limit. `scripts/parquet_schema_interop.py`
+checks these boundaries using independent Apache Thrift serialization.
+
+For columns whose combined value bytes exceed Arrow's signed 32-bit offset
+range, request `ALargeUtf8` or `ALargeBinary` in the target schema passed to
+`parquetRowGroupToArrow`. Offset widening works for flat columns and nested
+struct/list/map leaves, including indexed selection; it preserves UTF-8 versus
+opaque-binary semantics. The ordinary inferred schema keeps its 32-bit storage
+and reports an error when that representation cannot hold a whole row group.
+The lower-level `Parquet.Read` APIs expose `LargeBinaryBuffers`,
+`decodePlainLargeBinaryBuffers`, and the `readLargeBinaryBuffers*` family.
+Both widths validate aggregate sizes before copying output payloads.
+
+`scripts/parquet_large_offset_interop.py` checks these projections against
+Arrow C++. `scripts/parquet_large_map_interop.py` exercises the official
+`large_string_map.brotli.parquet` fixture (two 1 GiB keys), comparing complete
+buffer hashes with an independent C++ reader using one-row batches. It needs
+several GiB of available memory and is kept separate from the ordinary suite.
+
+`Parquet.File` exposes FILE logical references, subset schemas with field IDs,
+and pure resolution plans. Use `NSFile` / `NRFile` with `Parquet.Nested` to
+write annotated groups. `parseFileSchema` validates named OPTIONAL children;
+`compileFileReader` caches their typed column views for `fileReferenceAt`.
+Empty strings retain their raw values, while empty inline bytes remain a valid
+source. A present offset (including zero) requires both URI and size. Resolution
+prefers inline bytes and retains any external locator as an alternative; it
+never applies that locator's range to the inline bytes.
+
+Arrow schema inference preserves FILE identity using arrow-rs's experimental
+`arrow.parquet.file` extension (not yet standardized), with empty extension
+parameters and parent/child field IDs. `arrowFieldToNestedSchema` and
+`columnArrayToNestedRows` lower the extension back into `NSFile` / `NRFile`,
+including ordinary, large and view-backed strings/bytes. A plain struct remains
+unannotated, and unsupported extension parameters return an error.
+
+`scripts/build_parquet_file_reference.py --output /tmp/parquet-file-reference`
+builds an independent reference from a hash-verified upstream source snapshot
+and a committed dependency lock (Python 3.12+, Rust/Cargo required; use
+`--allow-network` if locked dependencies are not cached). Pass its reported
+binary to `scripts/parquet_file_arrow_interop.py --reference <binary>` alongside
+the native writer/reader probes. The check covers every nonempty FILE field
+subset in all three storage representations, nested lists/structs, IDs, nulls,
+and repeated Arrow/Parquet roundtrips.
+
+URI retrieval, relative-URI policy, MIME interpretation and checksum verification
+belong to the caller. Recognized checksum tokens are parsed and validated for
+encoding; unknown algorithms are ignored. ETAG refers to the whole external
+object. The writer rejects inline/locator length disagreements it can prove
+locally, without fetching external data.
+
+A zero-field FILE group is retained as a nullable empty struct: it cannot
+contain a valid non-null reference, so its rows resolve to null. The writer
+supports null FILE rows without inventing dummy fields. Required struct
+parents have known presence; optional parents and repeated containers use
+sibling leaves to recover their boundaries. Positive-row containers with no
+physical leaf to encode their presence/multiplicity are rejected explicitly;
+zero-row schemas remain supported. `parquetRowGroupToArrowWithLimits` accepts
+`ReadLimits`; the default aggregate budget is 1,048,576 synthesized FILE values.
+Callers can raise it for larger valid null-only columns.
+
+`scripts/parquet_file_zero_interop.py` checks independently framed Thrift
+footers, native null/anchored-container roundtrips and physical PyArrow values.
+It reports upstream limitations explicitly: Rust rejects empty-struct writes
+and drops these fields on read; C++ cannot handle several nested empty-group
+shapes. PyArrow 26 does not recognize the FILE annotation; `scripts/parquet_file_interop.py` checks it with
+independent Apache Thrift and compares the physical values after removing only
+that annotation for PyArrow.
+
+Encrypted writes use `Parquet.HighLevel.encodeParquetIO`, which returns
+`IO (Either String ByteString)` and generates fresh random module nonces.
+Create a new `Parquet.Write.newFooterEncryption` configuration for each file;
+share its file identifier and AAD prefix with any encrypted columns. The
+supported file mode has an encrypted footer and columns encrypted with the
+same footer key, using one file-level AES-GCM or AES-GCM-CTR algorithm.
+Separate column keys and signed plaintext footers are rejected. The pure
+writer and the mixed nullable writer reject encryption options.
+
+`loadParquetFileEncrypted` authenticates encrypted footers and signed plaintext
+footers using the supplied key, file identifier and AAD prefix. Stored identity
+fields must agree with the supplied values; an omitted AAD prefix must be
+supplied by the caller. `Parquet.Encryption.readFooterCryptoMetadata` exposes
+untrusted, opaque key metadata for application-specific key resolution. The
+ordinary reader, without a decryption configuration, does not verify signatures.
+`ReadOptions.readDecryptionConfig` accepts `Parquet.Decryption.DecryptionConfig`:
+explicit footer/column keys or keys resolved by the application from opaque
+key metadata, with an optional expected AAD prefix. Schema-path keys use vectors
+of path components, so names containing dots stay distinct from nested paths.
+Unavailable or incorrect keys for unrequested columns do not block projection;
+their statistics remain unavailable. `encryptedColumnKeyMetadata` discovers
+authenticated per-column paths and opaque key metadata after opening with a
+footer key, without requiring callers to parse Thrift. Requested modules authenticate
+under their file, row-group, column and page identities. GCM/CTR data modes,
+V1/V2 pages, dictionary pages, nullable/nested columns, encrypted indexes and
+separate bloom headers/bitsets use the same file context. Page CRCs cover the
+on-disk encrypted bytes and are checked before decrypting the body. CTR page bodies do
+not have GCM authentication tags, as defined by the format. The
+`scripts/parquet_encryption_interop.py` check reads generated encrypted files
+with PyArrow, covering both page versions, both algorithms, selective column
+encryption and multiple row groups.
+
+The official encrypted-footer check uses the unmodified C++ library from a
+PyArrow 26 wheel, including its mock KMS for the external-key-material fixture:
+
+```sh
+python3 scripts/build_parquet_encrypted_reference.py --output /tmp/parquet-encrypted-reference
+python3 scripts/parquet_encrypted_read_interop.py \
+  --reference /tmp/parquet-encrypted-reference \
+  --reader /path/to/wireform-parquet-reverse-probe \
+  --corpus /path/to/parquet-testing --output /tmp/encrypted-reads.json
+python3 scripts/parquet_encryption_interop.py \
+  --reference /tmp/parquet-encrypted-reference \
+  --probe /path/to/wireform-parquet-interop-probe
+```
+
+The reader driver compares every physical value and level plus Arrow values,
+indexes and bloom filters against C++. It tests explicit and metadata-based
+keys, projections without unrelated keys, and page pruning with damaged skipped
+and retained headers. The writer driver covers AES-128/192/256, both page
+versions and both data ciphers, checking actual column-encryption metadata as
+well as values; a successful round trip alone cannot detect an ignored option.
+Java fixtures with zero padding inside authenticated metadata are accepted only
+after the complete module has been authenticated. The narrower
+`parquet_encrypted_footer_interop.py` remains available for footer-only checks.
+
+Floating-point statistics count NaNs separately, omit NaNs from bounds, and
+write zero bounds as `-0`/`+0` under `TYPE_ORDER`. Metadata readers preserve
+column-order positions; unsupported orders disable that column's min/max
+bounds and column index instead of using them for filtering.
+
+Decimal byte-array bounds use signed numeric order across different widths.
+Row-group pruning takes `FileMetadata`; column and page checks take a
+`StatisticsContext` obtained with `statisticsContext metadata columnIndex`.
+This preserves logical decimal and unsigned order and the file's declared
+sort order. Modern bounds without a supported sort order are ignored;
+compatible legacy signed numeric bounds remain usable. Bloom checks take
+the matching `SchemaElement`. Use `PVDecimal` with an exact `Rational` and `PVUnsigned` for those
+predicate values. Aggregate min/max use the same logical decoding. Geometry,
+geography, interval and unknown logical-type bounds are ignored because their order is undefined.
+Readers reject column chunks stored in an external file; load that data file
+directly rather than reading its offsets against a summary metadata file.
+
+`LTGeometry` and `LTGeography` carry `GeometryParameters` and
+`GeographyParameters`, retaining optional CRS and edge-interpolation fields.
+Absent parameters retain the specification's OGC:CRS84/spherical defaults;
+explicit defaults and unknown future interpolation codes survive metadata
+round trips. `LTFile` preserves a FILE group annotation over its ordinary
+inline/locator columns. Applications resolve external FILE URIs.
+
+`FileMetadata.fmKeyValueMetadata` retains ordered `KeyValue` entries,
+including duplicate keys, missing values, empty values and opaque bytes.
+The Arrow bridge exports geometry/geography as `geoarrow.wkb`, keeping
+CRS and edge-interpolation semantics. Inline PROJJSON becomes a JSON object;
+`projjson:<key>` references resolve against the file's metadata, and SRIDs
+retain their representation hint. No external CRS resources are fetched.
+
+When writing GeoArrow WKB, provide a known CRS: GeoArrow's omitted CRS means
+unknown, while Parquet's omitted CRS means `OGC:CRS84`. The conversion returns
+an error when it cannot preserve that distinction or an edge algorithm.
+Future Parquet edge algorithms remain available in the native footer and
+fall back to ordinary binary storage in the Arrow projection.
+
+Page readers verify optional CRC32 checksums over each serialized page body
+they read, before decompression. Indexed selection leaves skipped pages and
+unused dictionaries untouched. Required selected columns use a dense path;
+nullable paths retain definition levels, including nullable ancestors.
+Logical annotations and checked widening apply to selected values as well.
+Pruning returns whole retained pages; apply a row filter for exact matches.
+Byte/text assembly reuses the defined-value buffer and gives null rows empty
+offset ranges, including for repeated elements. Null rows never duplicate a
+long first value or artificially exhaust the 32-bit offset range.
+The header-only parsing functions remain available for encryption framing.
+
+The Arrow bridge preserves modern signed96 TIMESTAMP and legacy INT96 as
+distinct lossless extension fields backed by FixedSizeBinary(12). Their full
+payloads and timestamp parameters survive schema inference and nested writing.
+Conversion to ordinary Arrow timestamps checks range and precision explicitly;
+it never wraps or silently drops sub-unit digits.
+
+## Predicate pushdown
+
+`Parquet.Predicate` evaluates a `Columnar.Predicate.Predicate` against:
+
+- per-row-group column statistics from the footer,
+- per-page column / offset index entries (Parquet 2.5+),
+- split-block bloom filters where available.
+
+The `Wireform.Columnar.decodeFilteredIter` facade entry point in the
+umbrella package combines this evaluator with the streaming reader so
+callers get only the row groups (and pages, with `PageIndex`) that
+the predicate didn't rule out.
+
+`Parquet.Aggregate` short-circuits the entire scan for `count(*)`,
+`count(<col>)`, `min(<col>)`, and `max(<col>)` queries when the
+required statistics are present in the footer; the reader returns
+the aggregate without reading any column data.
+
+Modern min/max bounds must be marked exact for aggregate pushdown; compact
+or unmarked bounds remain useful for filtering. Compatible legacy numeric
+extrema are also accepted. Empty and all-null row groups are skipped, while
+floating extrema require a known zero NaN count. `count(col)` returns
+`Nothing` for repeated paths, missing null counts or inconsistent metadata.
+`fileRowCountChecked` checks the file total against its row groups without
+overflow and returns `Nothing` for invalid counts.
+
+## Arrow bridge
+
+`Parquet.Arrow` converts Parquet column reads to Arrow `ColumnArray`s
+and vice versa. The `Wireform.Columnar` facade in `wireform-columnar`
+layers a uniform Arrow-shaped API on top of both formats, so a
+caller working with Arrow `ColumnArray`s can pick Parquet (or ORC, or
+Arrow IPC) by switching the `Format` argument.
+
+The schema-aware writers normalize Arrow millisecond dates to Parquet's
+INT32 days, and second-resolution times/timestamps to milliseconds. They
+reject fractional-day dates, out-of-day times, timestamp overflow, and
+durations without a standard Parquet logical type. Read back using the
+inferred Parquet schema to obtain those normalized units.
+
+For nested Arrow columns, pass the same field to
+`arrowFieldToNestedSchema field` and `columnArrayToNestedRows field column`,
+then use `encodeParquetNested`. This preserves narrow/unsigned integer,
+date, time, and timestamp annotations through structs, lists, and maps.
+Both Arrow list widths use Parquet's standard LIST layout. Conversion
+ignores values beneath null parents and outside referenced child ranges;
+visible required nulls and null map keys are rejected. Boolean leaves use
+bit-packed PLAIN values. `scripts/parquet_nested_types_interop.py` checks
+these paths with PyArrow, DuckDB, and Polars.
+
+Nested files use one V2 page per leaf. The writer checks row/event counts
+and the complete page payload against Parquet's signed 32-bit limits.
+It bounds cumulative binary/UTF-8/Variant value bytes while shredding and
+plans every leaf's level streams before materializing value buffers.
+For pre-shredded optional lists, prefer `buildOptionalListFileEither`;
+it also checks level ranges, row boundaries, paths, and PLAIN payload sizes.
+The older `buildOptionalListFile` raises an error for invalid input.
+`Parquet.Footer.writeFooterEither` and `writeRawFooterEither` report footer
+length/trailer errors explicitly; the older footer helpers raise errors.
+Typed metadata is measured before UTF-8 conversion or output allocation.
+Encrypted footers include crypto metadata, the nonce, and authentication
+tag in the same checked budget.
+
+The reader preserves fixed byte widths and supports Decimal128/256,
+FLOAT16, and fixed binary values through PLAIN, dictionary, and applicable
+delta/byte-stream-split encodings. Legacy INT96 timestamps retain their exact
+12-byte representation, including dates outside Arrow's Int64 nanosecond range.
+
+Use `parquetFileArrowSchemaChecked` to infer the complete Arrow schema,
+then `parquetRowGroupToArrow` to read structs, lists and maps. A target
+schema can project/reorder struct children by name, widen `Int32` to `Int64`
+and `Float` to `Double` recursively, and request `LargeList` output with
+64-bit offsets. List/map wrapper names are matched by position. Unselected
+physical leaves are not decoded. A required target rejects visible nulls;
+null children hidden beneath null ancestors do not count as visible values.
+The reader
+preserves null containers, empty containers, null elements and repeated
+leaf names under different parents; legacy list and BIT_PACKED level
+layouts are supported. Direct physical-leaf reads reject repeated paths.
+Legacy timestamp annotations infer UTC, and JSON columns carry Arrow's
+canonical `arrow.json` extension metadata.
+
+`scripts/parquet_corpus.py --include-bad-data` also runs Apache's adversarial
+fixtures with a per-process heap cap. The malformed Variant fixtures use
+unannotated binary metadata/value columns. The corpus check verifies that
+ordinary reads preserve those bytes, then explicitly interprets the payloads
+through the Variant API and reports `variant-payload-rejected` separately.
+
+### Lossless wide and legacy timestamps
+
+`Parquet.Timestamp` exposes `Timestamp96`, checked integer conversion, modern
+little-endian encoding/decoding, and a legacy Julian-day decoder. Modern
+`TIMESTAMP` fixed12 storage is signed96 Unix-epoch counts, with independent
+millisecond/microsecond/nanosecond and adjusted/local parameters. Legacy INT96
+is a distinct signed Julian-day plus signed nanoseconds representation; even
+non-normalized nanoseconds remain intact.
+
+The inferred Arrow fields use wireform-specific extensions, not canonical
+Apache Arrow extension names. `timestampField` constructs these fields and
+`timestampEncoding` validates them. The modern name is
+`wireform.parquet.timestamp96`, with metadata `millis:utc`, `millis:local`,
+`micros:utc`, `micros:local`, `nanos:utc` or `nanos:local`. Legacy storage uses
+`wireform.parquet.int96` with empty metadata. Both use FixedSizeBinary(12);
+the original payload bytes are independent of Arrow buffer endianness.
+
+Use `LtTimestamp96 adjusted unit` with `LvFixedBinary` in the nested writer,
+or lower an extension field using `arrowFieldToNestedSchema` and
+`columnArrayToNestedRows`. `LtInt96` is available for exact legacy copying;
+new data should use standard Int64 or modern signed96 TIMESTAMP storage.
+
+`projectTimestampColumn`, row-group schema projection, and page-pruning reads
+share checked narrowing. Signed96 can project to an Arrow timestamp with the
+same unit and adjusted/local semantics if every present count fits Int64.
+Legacy INT96 can project exactly to seconds, milliseconds, microseconds or
+nanoseconds. Overflow or discarded sub-unit precision fails. Null payloads
+are ignored, including values masked by nullable ancestors. Retaining an
+extension requires identical encoding/parameters; removing it explicitly
+permits raw fixed12 access.
+
+The independent timestamp suite uses Apache Thrift to adapt only timestamp
+schema/type metadata in a temporary copy, then decodes its byte-identical
+pages with unmodified PyArrow/C++. This avoids unsupported modern96 semantics
+and overflowing legacy conversions in the reference. Full-width Python
+integers and published Apache fixtures supply separate semantic checks.
+A Spark fixture's extreme legacy payload disagrees with its documented value
+and C++ conversion; the original bytes remain exact and overflowing Int64
+projection is rejected. This reference discrepancy is reported explicitly.
+
+### Variant binary values and native columns
+
+`Parquet.Variant` implements the v1 metadata/value codec, including all
+primitive tags, nested objects/arrays, decimal bounds and IEEE payload bits.
+It validates dictionary UTF-8/order flags, key uniqueness/order and each
+child's byte boundary. Object values may appear in a different physical
+order from their keys. `VariantMetadata` can be compiled or built once and
+shared with value-only encoders/decoders; every binary fragment of a shredded
+Variant must use that same dictionary.
+
+`Parquet.Variant.Parquet` provides `buildVariantParquetFile`,
+`readVariantColumn`, and a compiled unshredded `VariantReader`. File reads
+reconstruct both unshredded and typed Variant groups, including recursive
+objects, arrays and partial objects. They access fields by name and distinguish
+a missing column slot from a present Variant null. Native `NSVariant` writes now require valid payloads and emit
+the `VARIANT(1)` logical annotation. Ordinary Arrow conversion continues to
+expose the physical storage; use the explicit semantic API to interpret it.
+
+`VariantLimits` bounds nesting depth, total tree values and dictionary entries.
+Defaults are 500 levels and 1,048,576 values/entries. The `WithLimits` helpers
+and `NSVariantWithLimits` allow callers to raise those bounds for larger valid
+data. The default depth follows Apache's adversarial corpus policy.
+
+`scripts/parquet_variant_interop.py` compares native unshredded files with
+PyArrow physical values, Apache Thrift annotations, independently annotated
+foreign files, and pinned upstream Rust binary semantics. Build that oracle
+with `scripts/build_parquet_variant_reference.py` (Python 3.12+, Cargo and
+the locked dependency cache; `--allow-network` can fetch missing dependencies).
+The driver records reference limitations rather than treating unsupported
+cases as successes.
+
+`Parquet.Variant.Schema` checks canonical `arrow.parquet.variant` storage
+fields, including exact primitive mappings, decimal precision bands,
+non-null object/list wrappers, and dictionary/run-end encoded metadata.
+Schema validation alone does not reconstruct a shredded value.
+
+The nested writer supports `LtDecimal precision scale` through precision 76,
+using INT32, INT64, fixed 16-byte, or fixed 32-byte storage according to the
+precision. Fixed-byte values use `LvFixedBinary` with `LtFixedBinary` or
+`LtUuid`; they are emitted without a BYTE_ARRAY length prefix. The Arrow
+nested helpers retain decimal precision/scale and UUID annotations and ignore
+poisoned child storage beneath null parents.
+
+`Parquet.Variant.Arrow` reconstructs canonical Arrow Variant columns with
+`compileVariantArrowReader` and `variantArrowAt`. It covers every canonical
+primitive, recursive objects/arrays, partial objects and value-only/typed-only
+wrappers. Metadata may use binary/large/view storage, dictionary keys or run-end
+encoding; encoded metadata is resolved by logical index without expansion.
+One value/depth budget covers typed nodes and all fallback fragments. Missing
+object fields, present Variant nulls and null root slots remain distinct.
+
+`scripts/parquet_variant_typed_interop.py` verifies raw encoded semantics and
+compares with the pinned arrow-rs reconstruction kernel. It explicitly checks
+reference date/timestamp range limits and nanosecond tag narrowing, while
+requiring Haskell to preserve the complete raw domain and exact Variant type.
+Build that oracle with `build_parquet_variant_reference.py --typed`.
+
+Native `VARIANT(1)` inference preserves the canonical Arrow extension and exact
+primitive identity, including Decimal32/64, nanosecond timestamps and UUIDs.
+Typed layouts enforce the published physical types and repetition rules;
+retaining the Variant extension during projection requires the complete,
+unchanged semantic storage tree. Field reordering is allowed. Remove the
+extension explicitly for raw physical projections that drop or widen fields.
+Optional zero-leaf typed objects have no observable presence for nonempty
+native files and are rejected; zero-row schemas remain representable.
+
+`scripts/parquet_variant_native_interop.py` lowers the shared typed fixtures
+into foreign-written Parquet pages and checks native reads plus Rust
+reconstruction from the inferred Arrow schema. It reports metadata storage
+normalization and the two empty-object cases' unshredded representation.
+Malformed native carriers, repetitions and list wrappers are rejected even
+when the file has no rows. `scripts/parquet_narrow_integer_interop.py` checks
+signed/unsigned 8/16-bit boundaries in flat and nested, required and optional
+columns; out-of-domain physical values fail instead of wrapping.
+
+`compileVariantStorageSchema` compiles a canonical Arrow Variant field into
+an opaque schema for `NSVariantTyped`. `columnArrayToNestedRows` and the
+nested writer preserve typed storage, the native annotation, all field IDs,
+and the exact original metadata and supplied fallback bytes. Named Variant
+children bind before validation and row lowering, so their in-memory order
+may differ from the field. Binary views,
+dictionary/run-end encoded metadata and list views are resolved by logical
+index. Typed-only wrappers gain a native binary fallback column; missing
+required root/array values become explicit Variant nulls, while missing object
+fields stay absent. Required children are checked only below present parents.
+All native leaf byte/count preflights precede semantic fragment decoding.
+
+`Parquet.Variant.Shred` builds native rows from semantic Variant values.
+Compile a declared shape with `compileVariantShredder`, use
+`shredVariantWithMetadata` to retain an existing dictionary (including fully
+shredded names), and pass `variantShredSchema` plus the returned rows to
+`buildNestedFile`. `shredVariant` creates one complete dictionary per root
+value when no original dictionary exists. Every fallback fragment shares it.
+A primitive enters typed storage only when its Variant constructor matches
+exactly. Decimals also require the same scale and a fitting coefficient;
+integer width, timestamp unit/time zone and decimal width/scale mismatches
+keep their original binary tag and value. No rescaling or widening is done.
+
+`scripts/parquet_variant_write_interop.py` checks both physical storage
+forwarding and semantic shredding, with independent raw-value expectations,
+PyArrow storage checks and the pinned Rust reconstruction kernel. Supplied
+metadata/fallback blobs are checked byte for byte in the forwarding path.
+PyArrow's zero-row empty-group rejection is an explicitly asserted reference
+limitation; nonempty unobservable typed layouts are rejected by the writer.
+
+The remaining full-format release checks and final comparative throughput /
+allocation measurements are still open. These APIs alone do not establish
+full Parquet conformance or performance parity.
+
+## Benchmarks
+
+The file throughput and indexed-selection comparisons are declared in
+`scripts/bench-manifest.json` at the repository root. Run them sequentially:
+
+```bash
+python3 scripts/run-benchmarks.py --only parquet-throughput
+python3 scripts/run-benchmarks.py --only selection-throughput
+```
+
+The whole-file harness checks all 400,000 values, schema and page layout
+before timing. Reads return fully decoded Arrow batches, and Boolean inputs
+are forced before the clock starts. The three writers use required PLAIN V2
+columns and one 100,000-row page per column; the C++ comparison explicitly
+sets both `column_encoding="PLAIN"` and `max_rows_per_page=100000` because
+its defaults differ. The Python-bound C++ writer also emits page statistics;
+wireform and the configured Rust writer emit chunk statistics.
+
+`scripts/parquet_file_preflight.py` takes `--wireform-bench` and `--rust-bench`
+paths to the built benchmark binaries. It verifies nine independently written
+files and nine rejection controls, including last-row corruption and different
+page/group layouts. The Haskell benchmark also provides `--verify-fixtures DIR`;
+the Rust benchmark provides `--write-fixtures DIR`. Pass `--wireform-bench` to
+`scripts/parquet_bench_compare.py` to verify C++ output layout before timing.
+
+The selection comparison requires PyArrow and Apache Thrift in the Python
+environment. Its fixture generator creates six multipage integer/text cases
+with required/nullable values, plain/dictionary encoding, and three codecs.
+Haskell and parquet-rs read identical bytes, evaluate the same page maximum
+predicate, and return whole retained pages. Each harness checks every returned
+value against independently sliced PyArrow output before timing. Timings
+include footer/index parsing and materialization; file IO and fixture generation
+are excluded. Haskell also records allocated bytes. These workloads complement
+the flat required file baseline; they do not establish performance for every
+supported type or generated record helper.
+
+A criterion harness in [`bench/Bench.hs`](bench/Bench.hs) measures
+the C-vs-pure speedup on the XXH64 hash that Parquet bloom filters
+key off:
+
+```bash
+cabal bench wireform-parquet:parquet-bench
+```
+
+The recorded XXH64 measurements and chart sources remain in
+[`bench-results/summary/parquet-xxh64-c-vs-pure.json`](https://github.com/iand675/wireform-/blob/main/wireform-parquet/bench-results/summary/parquet-xxh64-c-vs-pure.json).
+They describe the toolchain and capture date recorded in that file; they are
+not a whole-library performance claim. Charts and tables are generated by
+`regen-stats`; do not edit their measured values by hand.
+
+
+For cross-language comparisons (file-format-level):
+
+- Haskell:
+  [`parquet-hs`](https://hackage.haskell.org/package/parquet-hs) (the
+  established Hackage Parquet library) and
+  [`parquet`](https://hackage.haskell.org/package/parquet).
+- C++: [arrow-cpp](https://github.com/apache/arrow/tree/main/cpp/src/parquet),
+  the de facto reference. DuckDB also ships a high-quality reader.
+- Rust: [`parquet`](https://crates.io/crates/parquet), used by
+  Datafusion and Polars.
+- Python: [`pyarrow.parquet`](https://arrow.apache.org/docs/python/parquet.html).
+
+## Specification references
+
+- [Apache Parquet specification](https://github.com/apache/parquet-format)
+- [Parquet Thrift schema](https://github.com/apache/parquet-format/blob/master/src/main/thrift/parquet.thrift)
+- [Modular encryption](https://github.com/apache/parquet-format/blob/master/Encryption.md)
+- [Bloom filters](https://github.com/apache/parquet-format/blob/master/BloomFilter.md)
+
+
+## Nested writer options
+
+`encodeParquetNested` preserves the original uncompressed V2 layout.
+`encodeParquetNestedWith` selects compression, V1/V2 pages and generated
+indexes through `WriteOptions`. The lower-level `buildNestedFileWithAux`
+also accepts pre-built bloom filters and explicit single-page indexes per
+physical leaf. Repetition/definition streams are compressed with values in
+V1; V2 compresses values only. Metadata sizes include the actual serialized
+header. Unsupported encryption and name-based bloom options are rejected.
+Automatic min/max bounds for non-null nested leaves remain open; all-null
+column indexes and offset indexes are generated now.
+
+Run the independent full-codec matrix with all optional codecs enabled:
+
+```sh
+python3 scripts/parquet_nested_options_interop.py --probe /path/to/writer-probe \
+  --lzo-reference /path/to/columnar-lzo-throughput --output-dir /tmp/nested-check \
+  --aux-fixtures /path/to/unit-fixtures --reference /path/to/encrypted-reference
+```
+
+The LZO reference is the `columnar-lzo-throughput` executable linked to
+unmodified liblzo2. It converts compression only before independent value
+reads; page versions, sizes and offset-index entries are checked on the
+original file through Apache Thrift. PyArrow, DuckDB and Polars compare all
+logical values/types against independent Arrow models. The old nested type
+catalogue additionally checks byte-for-byte preservation of the legacy path.
+
+
+## Generated nested bloom filters
+
+`encodeParquetNestedWith` accepts `writeBloomFilters`. Each name identifies a
+literal top-level field (including names containing dots), and selects every
+physical leaf below that field. Unknown names return `Left`; nulls and empty
+containers contribute no values. `buildNestedFileWithBloomFilters` combines
+this selection with explicit per-leaf auxiliary options; supplied filters
+win over generated filters.
+
+Construction hashes PLAIN values with XXH64 seed zero. Byte-array length
+prefixes are excluded, and Boolean page bits are expanded to individual 0/1
+bytes for hashing. V2 compression and bloom construction share a materialized
+values buffer. Unrequested leaves retain their existing direct builder path.
+
+The independent checker uses unmodified Apache Arrow C++ to decode every
+present value and probe its filter. LZO files additionally use unmodified
+liblzo2 for compression-only conversion; their original bloom bytes must
+match the corresponding uncompressed control.
+
+```sh
+python3 scripts/parquet_nested_bloom_interop.py \
+  --fixtures /path/to/regression-fixtures --reference /path/to/reference \
+  --lzo-reference /path/to/columnar-lzo-throughput --output /tmp/bloom-check.json
+```
+
+Bloom throughput is a deferred follow-up. This functionality does not imply
+completion of nested min/max generation or the remaining encrypted writers.
+
+
+## Nested statistics and explicit orderings
+
+The writer with auxiliary options generates column-chunk statistics even when
+page indexes are disabled. `caGeneratePageIndex` controls the additional
+column/offset indexes. The legacy no-options entry point retains its original
+bytes. PLAIN values are materialized once and shared with bloom generation
+and V2 compression; the bounds scan retains offsets without decoded vectors
+or per-value slices.
+
+Bounds use the actual emitted schema, including unsigned integers, wide
+signed decimals, UUIDs and signed96 little-endian timestamps. Floating-point
+columns use `IEEE_754_TOTAL_ORDER`: NaNs are counted, bounds exclude them when
+numeric values exist, and NaN-only pages contain their IEEE-ordered NaN
+extrema. Signed zero and NaN payload bits are preserved. FLOAT16 uses the
+native `LtFloat16` / `LvFloat16 Word16` surface and the nested Arrow bridge.
+Legacy INT96 uses `INT96_TIMESTAMP_ORDER`, comparing the signed Julian-day
+part first and the signed nanoseconds part second. This differs from signed96
+Unix timestamp ordering. Types without a defined logical order get no
+ordered bounds.
+
+`scripts/parquet_nested_statistics_interop.py` checks the literal footer and
+page-index fields through Apache Thrift, recomputes extrema using independent
+Python scalar models, and checks values/bloom membership with unmodified
+Arrow C++. Its binary16 bridge checks retain raw signed-zero bits through
+PyArrow. LZO conversion changes compression only, through unmodified liblzo2;
+original indexes and bloom regions are checked before conversion.
+
+
+## Encrypted nullable/nested writing
+
+The IO writers share the existing pure encoders and compress before encrypting
+page bodies. The required-column/footer-key path retains its existing direct
+builder. The new private `Parquet.Write.Encrypted` assembly seam supports the
+single-data-page layout produced by the mixed and nested writers; it is not a
+public rewriter for arbitrary third-party files. It relocates page, bloom and
+index regions, rebuilds offset indexes, and measures metadata before encoding.
+Column keys use their actual physical schema paths. Separate-key metadata is
+encrypted; signed plaintext footers retain only statistics-free legacy column
+metadata. Both GCM and GCM/CTR authenticate headers, metadata, indexes and blooms.
+Every module gets a fresh nonce and physical row-group/column/page AAD.
+
+`parquet_encrypted_writer_interop.py` requires Python `cryptography` alongside
+the existing PyArrow26/Apache Thrift dependencies. It authenticates/decrypts
+all module types independently, compares exact compressed bytes and metadata
+to plaintext controls, rejects repeated key/nonce pairs, and reads non-LZO
+files directly through unmodified Arrow C++. For LZO it checks every original
+encrypted module, then uses unmodified liblzo2 and C++ on plaintext controls.
+The grid covers 672files: two layouts, seven codecs, three AES widths, two
+algorithms, two footer modes, two key routes and two page versions. Native
+regressions also check tampering, missing/wrong keys and public projections.
+
+
+## Encrypted writer benchmarks
+
+Run the matched whole-file comparison sequentially from the repository root:
+
+```sh
+python3 scripts/run-benchmarks.py --only encryption-throughput
+```
+
+The native Criterion target is `parquet-encryption-throughput`; its independent
+reference is the pinned parquet-rs harness in `interop/parquet-encryption-reference`.
+Both write nullable scalar or optional-list/optional-element INT64 columns at
+64 and 8192 rows, with separate column keys, 128-bit AES-GCM, stored AAD prefixes,
+V2 pages, page statistics and both indexes. They use uncompressed single-page
+columns and exercise encrypted and signed plaintext footers. Input construction
+is outside the timed region; encryption configuration and fresh randomness are
+included. Bloom performance remains a separate follow-up.
+
+The nested native API validates dynamically shaped `NestedRow` values before
+allocating exact-size buffers. Its reference starts with typed, validated Arrow
+arrays. Keep that semantic difference explicit when interpreting whole-file
+timings. Inspect Core and allocation regressions alongside elapsed time: the
+row/element cursors and fixed-width count loop should stay unboxed, and no
+per-value temporary list or validation result should be allocated. Large accepted
+plans must retain lazy payloads, as exercised by the size-boundary regressions.
+
+The writer uses crypton's cached AES-GCM key context and system RNG. Keep the
+`crypton` and `ram` bounds consistent in the workspace and Nix package sets when
+upgrading them; reader/writer interoperability and existing authentication/hash
+vectors must pass against the same dependency versions.
diff --git a/LICENSE b/LICENSE
new file mode 100644
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,26 @@
+Copyright 2026 Ian Duncan
+
+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.
diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,146 @@
+# wireform-parquet
+
+Read and write [Apache Parquet](https://parquet.apache.org/) files in Haskell.
+Work with records or Arrow columns, including nullable fields, structs, lists
+and maps. Compression, column projection and statistics-based filtering are
+available for analytical workloads.
+
+## Install
+
+Requires **GHC 9.10 or newer**. Add `wireform-parquet` to your application's dependencies. The example below
+also uses `wireform-arrow` for record conversion:
+
+```cabal
+build-depends:
+  base,
+  bytestring,
+  text,
+  vector,
+  wireform-arrow,
+  wireform-parquet
+```
+
+The default build enables Snappy, Zstandard and LZ4 and needs their native
+development libraries, together with zlib. Brotli is optional:
+
+```sh
+cabal build wireform-parquet -fbrotli
+```
+
+Brotli also requires the native Brotli 1.x development libraries and
+`pkg-config`. Individual optional codecs can be disabled with `-f-snappy`,
+`-f-zstd`, `-f-lz4` and `-f-brotli`. Uncompressed, GZip and LZO support is
+always available. If you disable Snappy, set `writeCompression` to another
+enabled codec.
+
+## Write and read a file
+
+This example derives an Arrow table for a Haskell record, writes it to
+Parquet with the default Snappy compression, then reads the records back.
+Nullable fields are preserved.
+
+```haskell
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE TemplateHaskell #-}
+
+import qualified Arrow.Derive as Derive
+import qualified Arrow.Record as Arrow
+import qualified Data.ByteString as BS
+import Data.Int (Int64)
+import Data.Text (Text)
+import qualified Data.Vector as V
+import qualified Parquet as P
+
+data Person = Person
+  { personId :: Int64
+  , personName :: Text
+  , personEmail :: Maybe Text
+  } deriving (Eq, Show)
+
+Derive.deriveArrow ''Person
+
+main :: IO ()
+main = do
+  let people = V.fromList
+        [ Person 1 "Ada" (Just "ada@example.com")
+        , Person 2 "Grace" Nothing
+        ]
+      (schema, columns) = Arrow.encodeTable Derive.hasTable people
+
+  (fileSchema, rowGroups) <- either fail pure $
+    P.arrowToParquetMixed schema [columns]
+  BS.writeFile "people.parquet" $
+    P.encodeParquetMixed P.defaultWriteOptions fileSchema rowGroups
+
+  bytes <- BS.readFile "people.parquet"
+  file <- either fail pure (P.decodeParquet P.defaultReadOptions bytes)
+  storedSchema <- either fail pure (P.parquetFileArrowSchemaChecked file)
+  storedColumns <- either (fail . show) pure $
+    P.parquetRowGroupToArrow storedSchema file 0
+  decoded <- either fail pure $
+    Arrow.decodeTable Derive.hasTable storedSchema storedColumns
+  print (decoded :: V.Vector Person)
+```
+
+If you already have Arrow columns, start with `arrowToParquetMixed`.
+Use `streamRowGroupsIter` to decode row groups as they are consumed.
+For nested data, `encodeParquetNestedWith` accepts writer options for
+compression, page version and indexes, with automatic min/max statistics.
+Set `writeBloomFilters` to top-level field names to generate filters for all of their physical leaves. For
+individual leaf control, use `buildNestedFileWithAux`.
+
+## Choosing an API
+
+Import `Parquet` for the main file, Arrow and record APIs. More specialized
+modules are available when you need them:
+
+| Task | API |
+| --- | --- |
+| Read or write files and choose compression | [`Parquet.HighLevel`](https://hackage.haskell.org/package/wireform-parquet/docs/Parquet-HighLevel.html) |
+| Convert Arrow columns, project fields or read row groups | [`Parquet.Arrow`](https://hackage.haskell.org/package/wireform-parquet/docs/Parquet-Arrow.html) |
+| Write nested structs, lists and maps | [`Parquet.Nested`](https://hackage.haskell.org/package/wireform-parquet/docs/Parquet-Nested.html) |
+| Derive Parquet schemas and row conversions | [`Parquet.Derive`](https://hackage.haskell.org/package/wireform-parquet/docs/Parquet-Derive.html) |
+| Skip data using predicates, indexes and bloom filters | [`Parquet.Predicate`](https://hackage.haskell.org/package/wireform-parquet/docs/Parquet-Predicate.html) |
+| Answer counts and extrema from available statistics | [`Parquet.Aggregate`](https://hackage.haskell.org/package/wireform-parquet/docs/Parquet-Aggregate.html) |
+| Work with Variant values | [`Parquet.Variant`](https://hackage.haskell.org/package/wireform-parquet/docs/Parquet-Variant.html), [`Parquet.Variant.Parquet`](https://hackage.haskell.org/package/wireform-parquet/docs/Parquet-Variant-Parquet.html) |
+
+The Arrow bridge supports decimals, UUIDs, dates and timestamps alongside
+ordinary numeric, Boolean, text and binary columns. The nested bridge also
+preserves binary16 values. Wide and legacy timestamps
+can be preserved losslessly; conversions to ordinary Arrow timestamps check
+range and precision.
+
+Target schemas can select and reorder fields, widen numeric types, and request
+large strings, binary columns or lists. Filtering with page indexes retains
+whole matching pages; apply a row filter when you need exact matching rows.
+
+Use `encodeParquetIO`, `encodeParquetMixedIO` or `encodeParquetNestedIO` to
+write encrypted files with required, nullable or nested columns. Set
+`writeFooterEncryption` and select columns with `writeColumnEncryption`;
+columns can share the footer key or use separate keys. Set `writeFooterMode`
+to `SignedPlaintextFooter` to keep the footer readable and authenticate it
+with the supplied signing key. Generate a fresh footer configuration with
+`newFooterEncryption` for every file.
+
+Use `readDecryptionConfig` in the read options to supply footer and column
+keys for encrypted files and to verify signed plaintext footers. See
+[`Parquet.Decryption`](https://hackage.haskell.org/package/wireform-parquet/docs/Parquet-Decryption.html) for key routing.
+
+For applications working across Parquet, Arrow IPC and ORC, the separate
+[`wireform-columnar`](https://github.com/iand675/wireform-/tree/main/wireform-columnar) package provides a shared API.
+
+## Current limitations
+
+- Readers do not follow column chunks into external files. Read the individual
+  data files rather than a metadata-only file that refers to them.
+- For a text or binary column with 2 GiB or more of decoded value bytes in a
+  row group, request `ALargeUtf8` or `ALargeBinary` in the target Arrow schema.
+
+## Development
+
+See the [developer guide](https://hackage.haskell.org/package/wireform-parquet-0.1.0.0/src/DEVELOPING.md) for build and test commands,
+compatibility checks, benchmarks and implementation notes.
+
+## License
+
+[BSD-3-Clause](https://hackage.haskell.org/package/wireform-parquet-0.1.0.0/src/LICENSE).
diff --git a/bench/AlpThroughput.hs b/bench/AlpThroughput.hs
new file mode 100644
--- /dev/null
+++ b/bench/AlpThroughput.hs
@@ -0,0 +1,93 @@
+module Main (main) where
+
+import Control.DeepSeq (NFData (..))
+import Control.Exception (evaluate)
+import Control.Monad (unless)
+import Criterion.Main (Benchmark, bench, bgroup, defaultMain, whnf)
+import Data.Bits (shiftL, (.|.))
+import Data.ByteString qualified as BS
+import Data.List (isPrefixOf)
+import Data.Vector.Primitive qualified as P
+import Data.Word (Word32, Word64)
+import GHC.Float (castDoubleToWord64, castFloatToWord32)
+import Parquet.Alp qualified as Alp
+import System.Environment (getArgs, getEnv)
+import System.FilePath ((</>))
+
+
+data Fixture = Fixture
+  { fixtureName :: !String
+  , fixtureWidth :: {-# UNPACK #-} !Int
+  , fixtureCount :: {-# UNPACK #-} !Int
+  , fixtureEncoded :: !BS.ByteString
+  }
+
+
+instance NFData Fixture where
+  rnf (Fixture name width count encoded) = rnf name `seq` rnf width `seq` rnf count `seq` rnf encoded
+
+
+decode32 :: Int -> BS.ByteString -> P.Vector Float
+decode32 count = either error id . Alp.decodeAlpFloat count
+
+
+decode64 :: Int -> BS.ByteString -> P.Vector Double
+decode64 count = either error id . Alp.decodeAlpDouble count
+
+
+loadFixture :: FilePath -> String -> IO Fixture
+loadFixture root line = case splitTab line of
+  [stem, widthText, countText, name] -> do
+    let width = read widthText
+        count = read countText
+    encoded <- BS.readFile (root </> stem ++ ".alp")
+    expected <- BS.readFile (root </> stem ++ ".plain")
+    unless (BS.length expected == count * width) (fail "ALP benchmark oracle size differs")
+    if width == 4
+      then
+        unless
+          (P.map castFloatToWord32 (decode32 count encoded) == P.generate count (read32 expected))
+          (fail (name ++ ": FLOAT IEEE bits differ from independent PLAIN oracle"))
+      else do
+        unless (width == 8) (fail "ALP benchmark physical width differs")
+        unless
+          (P.map castDoubleToWord64 (decode64 count encoded) == P.generate count (read64 expected))
+          (fail (name ++ ": DOUBLE IEEE bits differ from independent PLAIN oracle"))
+    evaluate $ Fixture name width count encoded
+  _ -> fail "ALP benchmark fixture plan must have four tab-separated fields"
+  where
+    splitTab input = case break (== '\t') input of
+      (field, []) -> [field]
+      (field, _ : rest) -> field : splitTab rest
+
+
+read32 :: BS.ByteString -> Int -> Word32
+read32 bytes row = foldl' (\value lane -> value .|. (fromIntegral (BS.index bytes (row * 4 + lane)) `shiftL` (lane * 8))) 0 [0 .. 3]
+
+
+read64 :: BS.ByteString -> Int -> Word64
+read64 bytes row = foldl' (\value lane -> value .|. (fromIntegral (BS.index bytes (row * 8 + lane)) `shiftL` (lane * 8))) 0 [0 .. 7]
+
+
+benchmark :: Fixture -> Benchmark
+benchmark fixture =
+  bgroup
+    (fixtureName fixture)
+    [ if fixtureWidth fixture == 4
+        then bench "decode" (whnf (decode32 (fixtureCount fixture)) (fixtureEncoded fixture))
+        else bench "decode" (whnf (decode64 (fixtureCount fixture)) (fixtureEncoded fixture))
+    ]
+
+
+main :: IO ()
+main = do
+  root <- getEnv "WIREFORM_PARQUET_ALP_FIXTURES"
+  plan <- readFile (root </> "cases.tsv")
+  fixtures <- mapM (loadFixture root) (lines plan)
+  unless
+    (length fixtures == 30 && all (\f -> "FLOAT " `isPrefixOf` fixtureName f || "DOUBLE " `isPrefixOf` fixtureName f) fixtures)
+    (fail "ALP benchmark fixture set differs")
+  args <- getArgs
+  case args of
+    ["--check"] -> putStrLn "30 ALP pages match independent PLAIN IEEE bit oracles"
+    _ -> defaultMain [bgroup "ALP" (map benchmark fixtures)]
diff --git a/bench/Bench.hs b/bench/Bench.hs
new file mode 100644
--- /dev/null
+++ b/bench/Bench.hs
@@ -0,0 +1,57 @@
+{- | Microbenchmark comparing the Parquet bloom filter's XXH64 hot path
+between the C/SIMDe kernel ("Wireform.Hash") and the pure Haskell
+reference ("XXH64Pure"). Pure version lives in the bench tree only.
+
+Run with:
+
+@
+cabal bench wireform-parquet:parquet-bench
+@
+-}
+module Main (main) where
+
+import Criterion.Main (bench, bgroup, defaultMain, env, whnf)
+import Data.ByteString qualified as BS
+import Data.List (foldl')
+import Data.Word (Word64)
+import Parquet.BloomFilter qualified as BF
+import Wireform.Hash qualified as Hash
+import XXH64Pure qualified as Pure
+
+
+deterministic :: Int -> BS.ByteString
+deterministic n = BS.pack (take n (cycle [0 .. 255]))
+
+
+filledFilter :: BF.Sbbf
+filledFilter =
+  let !bf0 = BF.newSbbf (BF.optimalNumBytes 1024 0.01)
+      !hashes = take 1024 ([fromIntegral i :: Word64 | i <- [(1 :: Int) ..]])
+  in foldl' (flip BF.sbbfInsertHash) bf0 hashes
+
+
+main :: IO ()
+main =
+  defaultMain
+    [ bgroup
+        "Parquet XXH64"
+        [ env (pure (deterministic 8)) $ \bs -> bgroup "8 B" (xs bs)
+        , env (pure (deterministic 64)) $ \bs -> bgroup "64 B" (xs bs)
+        , env (pure (deterministic 1024)) $ \bs -> bgroup "1 KiB" (xs bs)
+        , env (pure (deterministic 65536)) $ \bs -> bgroup "64 KiB" (xs bs)
+        ]
+    , bgroup
+        "Parquet bloom filter"
+        [ bench "sbbfInsert (8 B value)" $
+            whnf (\bs -> BF.sbbfInsert bs (BF.newSbbf 1024)) (deterministic 8)
+        , bench "sbbfCheck hit" $
+            whnf (\h -> BF.sbbfCheckHash h filledFilter) (1 :: Word64)
+        , bench "sbbfCheck miss" $
+            whnf (\h -> BF.sbbfCheckHash h filledFilter) (0xdeadbeef :: Word64)
+        ]
+    ]
+  where
+    xs bs =
+      [ bench "C" $ whnf (Hash.xxh64 0) bs
+      , bench "pure" $ whnf Pure.xxh64_pure bs
+      ]
diff --git a/bench/ByteStreamSplitThroughput.hs b/bench/ByteStreamSplitThroughput.hs
new file mode 100644
--- /dev/null
+++ b/bench/ByteStreamSplitThroughput.hs
@@ -0,0 +1,118 @@
+module Main (main) where
+
+import Control.DeepSeq (NFData (..))
+import Control.Exception (evaluate)
+import Control.Monad (unless)
+import Criterion.Main (Benchmark, bench, bgroup, defaultMain, env, whnf)
+import Data.Bits (shiftR)
+import Data.ByteString qualified as BS
+import Data.Vector.Primitive qualified as P
+import Data.Word (Word32, Word64)
+import GHC.Float (castDoubleToWord64, castFloatToWord32, castWord32ToFloat, castWord64ToDouble)
+import Parquet.ByteStreamSplit qualified as Write
+import Parquet.Read qualified as Read
+import System.Environment (getArgs)
+
+
+data Fixture a = Fixture
+  { fixtureValues :: !(P.Vector a)
+  , fixtureEncoded :: !BS.ByteString
+  }
+
+
+instance NFData (Fixture a) where
+  rnf (Fixture values encoded) = rnf values `seq` rnf encoded
+
+
+counts :: [Int]
+counts = [17, 1024, 65536]
+
+
+word32At :: Int -> Word32
+word32At i = case i of
+  0 -> 0
+  1 -> 0x80000000
+  2 -> 0x7f800000
+  3 -> 0xff800000
+  4 -> 0x7fc12345
+  5 -> 0x7f812345
+  6 -> 1
+  7 -> 0x7f7fffff
+  _ -> fromIntegral i * 1664525 + 1013904223
+
+
+word64At :: Int -> Word64
+word64At i = case i of
+  0 -> 0
+  1 -> 0x8000000000000000
+  2 -> 0x7ff0000000000000
+  3 -> 0xfff0000000000000
+  4 -> 0x7ff8123456789abc
+  5 -> 0x7ff0123456789abc
+  6 -> 1
+  7 -> 0x7fefffffffffffff
+  _ -> fromIntegral i * 6364136223846793005 + 1442695040888963407
+
+
+-- Independent specification model: byte lane first, then value index.
+golden32 :: Int -> BS.ByteString
+golden32 n = BS.pack (concatMap (\lane -> map (\i -> fromIntegral (word32At i `shiftR` (lane * 8))) [0 .. n - 1]) [0 .. 3])
+
+
+golden64 :: Int -> BS.ByteString
+golden64 n = BS.pack (concatMap (\lane -> map (\i -> fromIntegral (word64At i `shiftR` (lane * 8))) [0 .. n - 1]) [0 .. 7])
+
+
+decode32 :: Int -> BS.ByteString -> P.Vector Float
+decode32 n = either error id . Read.decodeByteStreamSplitFloat n
+
+
+decode64 :: Int -> BS.ByteString -> P.Vector Double
+decode64 n = either error id . Read.decodeByteStreamSplitDouble n
+
+
+fixture32 :: Int -> IO (Fixture Float)
+fixture32 n = do
+  values <- evaluate (P.generate n (castWord32ToFloat . word32At))
+  encoded <- evaluate (Write.encodeByteStreamSplitFloat values)
+  unless (encoded == golden32 n) (fail "FLOAT byte-stream-split bytes differ from specification model")
+  unless (P.map castFloatToWord32 (decode32 n encoded) == P.generate n word32At) (fail "FLOAT byte-stream-split bits differ")
+  pure (Fixture values encoded)
+
+
+fixture64 :: Int -> IO (Fixture Double)
+fixture64 n = do
+  values <- evaluate (P.generate n (castWord64ToDouble . word64At))
+  encoded <- evaluate (Write.encodeByteStreamSplitDouble values)
+  unless (encoded == golden64 n) (fail "DOUBLE byte-stream-split bytes differ from specification model")
+  unless (P.map castDoubleToWord64 (decode64 n encoded) == P.generate n word64At) (fail "DOUBLE byte-stream-split bits differ")
+  pure (Fixture values encoded)
+
+
+case32 :: Int -> Benchmark
+case32 n = env (fixture32 n) $ \fixture ->
+  bgroup
+    ("FLOAT " ++ show n ++ " values")
+    [ bench "encode" (whnf Write.encodeByteStreamSplitFloat (fixtureValues fixture))
+    , bench "decode" (whnf (decode32 n) (fixtureEncoded fixture))
+    ]
+
+
+case64 :: Int -> Benchmark
+case64 n = env (fixture64 n) $ \fixture ->
+  bgroup
+    ("DOUBLE " ++ show n ++ " values")
+    [ bench "encode" (whnf Write.encodeByteStreamSplitDouble (fixtureValues fixture))
+    , bench "decode" (whnf (decode64 n) (fixtureEncoded fixture))
+    ]
+
+
+main :: IO ()
+main = do
+  args <- getArgs
+  case args of
+    ["--check"] -> do
+      mapM_ fixture32 counts
+      mapM_ fixture64 counts
+      putStrLn "6 BYTE_STREAM_SPLIT fixtures match independent encoded-byte and IEEE bit models"
+    _ -> defaultMain [bgroup "byte stream split" (map case32 counts ++ map case64 counts)]
diff --git a/bench/DeltaThroughput.hs b/bench/DeltaThroughput.hs
new file mode 100644
--- /dev/null
+++ b/bench/DeltaThroughput.hs
@@ -0,0 +1,72 @@
+module Main (main) where
+
+import Control.DeepSeq (NFData, force)
+import Control.Exception (evaluate)
+import Control.Monad (unless)
+import Criterion.Main (bench, bgroup, defaultMain, nf)
+import Data.Bits ((.&.))
+import Data.Int (Int32, Int64)
+import Data.Vector.Primitive qualified as P
+import Data.Word (Word32, Word64)
+import GHC.Generics (Generic)
+import Parquet.Delta qualified as Read
+import Parquet.DeltaEncode qualified as Write
+
+
+data Inputs = Inputs
+  { ascending32 :: !(P.Vector Int32)
+  , bounded32 :: !(P.Vector Int32)
+  , full32 :: !(P.Vector Int32)
+  , wrapping32 :: !(P.Vector Int32)
+  , ascending64 :: !(P.Vector Int64)
+  , bounded64 :: !(P.Vector Int64)
+  , full64 :: !(P.Vector Int64)
+  , wrapping64 :: !(P.Vector Int64)
+  }
+  deriving stock (Generic)
+  deriving anyclass (NFData)
+
+
+rowCount :: Int
+rowCount = 65536
+
+
+inputs :: Inputs
+inputs =
+  Inputs
+    (P.generate rowCount fromIntegral)
+    (P.generate rowCount (fromIntegral . bounded))
+    (P.map fromIntegral (P.iterateN rowCount (\value -> value * 1664525 + 1013904223) (0x12345678 :: Word32)))
+    (P.generate rowCount (\i -> if even i then minBound else maxBound))
+    (P.generate rowCount fromIntegral)
+    (P.generate rowCount (fromIntegral . bounded))
+    (P.map fromIntegral (P.iterateN rowCount (\value -> value * 6364136223846793005 + 1442695040888963407) (0x123456789abcdef0 :: Word64)))
+    (P.generate rowCount (\i -> if even i then minBound else maxBound))
+  where
+    bounded i = (fromIntegral i * 1103515245 + 12345) .&. 0xffff :: Word32
+
+
+main :: IO ()
+main = do
+  values <- evaluate (force inputs)
+  let cases32 = [("INT32 ascending", ascending32 values), ("INT32 bounded", bounded32 values), ("INT32 full", full32 values), ("INT32 wrapping", wrapping32 values)]
+      cases64 = [("INT64 ascending", ascending64 values), ("INT64 bounded", bounded64 values), ("INT64 full", full64 values), ("INT64 wrapping", wrapping64 values)]
+  mapM_
+    ( \(name, column) -> do
+        let encoded = Write.encodeDeltaBinaryPackedInt32 column
+        decoded <- either fail (evaluate . force) (Read.decodeDeltaBinaryPackedInt32 rowCount encoded)
+        unless (decoded == column) (fail (name ++ ": encoder values differ"))
+    )
+    cases32
+  mapM_
+    ( \(name, column) -> do
+        let encoded = Write.encodeDeltaBinaryPackedInt64 column
+        decoded <- either fail (evaluate . force) (Read.decodeDeltaBinaryPackedInt64 rowCount encoded)
+        unless (decoded == column) (fail (name ++ ": encoder values differ"))
+    )
+    cases64
+  defaultMain
+    [ bgroup "delta encode" $
+        map (\(name, column) -> bench name (nf Write.encodeDeltaBinaryPackedInt32 column)) cases32
+          ++ map (\(name, column) -> bench name (nf Write.encodeDeltaBinaryPackedInt64 column)) cases64
+    ]
diff --git a/bench/DictionaryThroughput.hs b/bench/DictionaryThroughput.hs
new file mode 100644
--- /dev/null
+++ b/bench/DictionaryThroughput.hs
@@ -0,0 +1,208 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE ImportQualifiedPost #-}
+
+module Main (main) where
+
+import Control.DeepSeq (NFData (..))
+import Control.Exception (evaluate)
+import Control.Monad (unless)
+import Criterion.Main (bench, bgroup, defaultMain, env, whnf)
+import Data.Bits (shiftR, (.&.), (.|.))
+import Data.ByteString qualified as BS
+import Data.ByteString.Internal qualified as BSI
+import Data.Primitive.Types (Prim)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as P
+import Data.Vector.Primitive.Mutable qualified as M
+import Data.Word (Word32, Word64, Word8)
+import Foreign.Marshal.Utils (fillBytes)
+import Foreign.Ptr (Ptr)
+import Foreign.Storable (pokeByteOff)
+import GHC.Float (castWord32ToFloat, castWord64ToDouble)
+import Parquet.Write qualified as W
+import System.Mem (performMajorGC)
+
+
+rowCount :: Int
+rowCount = 8192
+
+
+data Input = Input
+  { inputName :: !String
+  , inputColumn :: !W.ColumnData
+  , inputUniques :: !W.ColumnData
+  , inputIndices :: !(P.Vector Int)
+  }
+
+
+data Spacing = Dense | Sparse
+
+
+data Kind
+  = Int32Keys !Spacing
+  | Int64Keys !Spacing
+  | FloatKeys !Spacing
+  | DoubleKeys !Spacing
+  | BinaryKeys {-# UNPACK #-} !Int
+  | ShortTextKeys
+  | CommonEndKeys
+  | MultipleMiddleKeys
+
+
+data InputSpec = InputSpec
+  { specName :: !String
+  , specCardinality :: {-# UNPACK #-} !Int
+  , specKind :: !Kind
+  }
+
+
+-- Recipes contain no input buffers. Criterion keeps only its current
+-- fixture alive, matching the reference harness's per-case lifetime.
+inputSpecs :: [InputSpec]
+inputSpecs = concatMap shapes [8, 1024, rowCount]
+  where
+    shapes cardinality =
+      let sample label kind = InputSpec (label ++ " " ++ show cardinality ++ " unique") cardinality kind
+      in [ sample "INT32" (Int32Keys Dense)
+         , sample "INT64" (Int64Keys Dense)
+         , sample "FLOAT" (FloatKeys Dense)
+         , sample "DOUBLE" (DoubleKeys Dense)
+         , sample "BYTE_ARRAY" (BinaryKeys 8)
+         , sample "INT32 sparse" (Int32Keys Sparse)
+         , sample "INT64 sparse" (Int64Keys Sparse)
+         , sample "FLOAT sparse" (FloatKeys Sparse)
+         , sample "DOUBLE sparse" (DoubleKeys Sparse)
+         , sample "BYTE_ARRAY 64 bytes" (BinaryKeys 64)
+         , sample "BYTE_ARRAY 4096 bytes" (BinaryKeys 4096)
+         , sample "BYTE_ARRAY common ends 64 bytes" CommonEndKeys
+         , sample "BYTE_ARRAY short text" ShortTextKeys
+         , sample "BYTE_ARRAY common ends multiple words 64 bytes" MultipleMiddleKeys
+         ]
+
+
+-- Explicit IO allocation prevents a recipe from retaining a pure vector
+-- shared between its preflight and later Criterion environment.
+newPrimitiveVector :: (Prim a) => (Int -> a) -> IO (P.Vector a)
+newPrimitiveVector valueAt = do
+  values <- M.unsafeNew rowCount
+  let fill !row
+        | row == rowCount = P.unsafeFreeze values
+        | otherwise = M.unsafeWrite values row (valueAt row) >> fill (row + 1)
+  fill 0
+
+
+spread32 :: Int -> Word32
+spread32 key = fromIntegral key * 1664525 + 1013904223
+
+
+spread64 :: Int -> Word64
+spread64 key = fromIntegral key * 6364136223846793005 + 1442695040888963407
+
+
+putWordLE :: Ptr Word8 -> Int -> Word64 -> IO ()
+putWordLE ptr offset value = fill 0
+  where
+    fill !byte
+      | byte == 8 = pure ()
+      | otherwise = do
+          pokeByteOff ptr (offset + byte) (fromIntegral (value `shiftR` (byte * 8)) :: Word8)
+          fill (byte + 1)
+
+
+newByteValue :: Kind -> Word64 -> IO BS.ByteString
+newByteValue kind key = case kind of
+  BinaryKeys width -> filled width (\ptr -> putWordLE ptr 0 key)
+  CommonEndKeys -> filled 64 (\ptr -> putWordLE ptr 24 key)
+  MultipleMiddleKeys ->
+    let (high, low) = key `quotRem` 4
+    in filled 64 (\ptr -> putWordLE ptr 16 low >> putWordLE ptr 24 high)
+  ShortTextKeys -> do
+    let digits !count !value
+          | value < 10 = count
+          | otherwise = digits (count + 1) (value `quot` 10)
+        count = digits 1 key
+    BSI.create count $ \ptr ->
+      let writeDigit !offset !value = do
+            let (remaining, digit) = value `quotRem` 10
+            pokeByteOff ptr offset (48 + fromIntegral digit :: Word8)
+            if offset == 0 then pure () else writeDigit (offset - 1) remaining
+      in writeDigit (count - 1) key
+  _ -> error "numeric recipe passed to newByteValue"
+  where
+    filled size fields = BSI.create size $ \ptr -> fillBytes ptr 97 size >> fields ptr
+
+
+newInput :: InputSpec -> IO Input
+newInput spec = do
+  let cardinality = specCardinality spec
+      keyAt row = (row * 104729) `rem` cardinality
+  indices <- newPrimitiveVector (`rem` cardinality)
+  column <- case specKind spec of
+    Int32Keys spacing -> W.ColInt32 <$> newPrimitiveVector (\row -> case spacing of Dense -> fromIntegral (keyAt row); Sparse -> fromIntegral (spread32 (keyAt row)))
+    Int64Keys spacing -> W.ColInt64 <$> newPrimitiveVector (\row -> case spacing of Dense -> fromIntegral (keyAt row); Sparse -> fromIntegral (spread64 (keyAt row)))
+    FloatKeys spacing -> W.ColFloat <$> newPrimitiveVector (\row -> castWord32ToFloat (0x3f000000 .|. case spacing of Dense -> fromIntegral (keyAt row); Sparse -> spread32 (keyAt row) .&. 0x007fffff))
+    DoubleKeys spacing -> W.ColDouble <$> newPrimitiveVector (\row -> castWord64ToDouble (0x3fe0000000000000 .|. case spacing of Dense -> fromIntegral (keyAt row); Sparse -> spread64 (keyAt row) .&. 0x000fffffffffffff))
+    kind -> W.ColByteArray <$> V.generateM rowCount (\row -> newByteValue kind (fromIntegral (keyAt row)))
+  pure (Input (specName spec) column (takeColumn cardinality column) indices)
+
+
+takeColumn :: Int -> W.ColumnData -> W.ColumnData
+takeColumn count column = case column of
+  W.ColInt32 values -> W.ColInt32 (P.take count values)
+  W.ColInt64 values -> W.ColInt64 (P.take count values)
+  W.ColFloat values -> W.ColFloat (P.take count values)
+  W.ColDouble values -> W.ColDouble (P.take count values)
+  W.ColBool values -> W.ColBool (V.take count values)
+  W.ColByteArray values -> W.ColByteArray (V.take count values)
+
+
+forceColumn :: W.ColumnData -> ()
+forceColumn column = case column of
+  W.ColByteArray values -> V.foldl' (\count value -> count + BS.length value) 0 values `seq` ()
+  W.ColBool values -> V.foldl' (\count value -> if value then count + 1 else count) (0 :: Int) values `seq` ()
+  _ -> W.columnDataLength column `seq` ()
+
+
+validateInput :: Input -> IO ()
+validateInput sample = do
+  _ <- evaluate (forceColumn (inputColumn sample))
+  let dictionary = W.buildDictionary (inputColumn sample)
+  unless
+    (W.dictUniques dictionary == inputUniques sample && W.dictIndices dictionary == P.map fromIntegral (inputIndices sample))
+    (fail (inputName sample ++ ": dictionary values/first-appearance indices differ"))
+
+
+-- Return only the source column; expected outputs and preflight results
+-- must not become part of the live heap scanned during timed iterations.
+newtype PreparedInput = PreparedInput W.ColumnData
+
+
+instance NFData PreparedInput where
+  rnf (PreparedInput column) = forceColumn column
+
+
+prepareInput :: InputSpec -> IO PreparedInput
+prepareInput spec = do
+  performMajorGC
+  prepared <- do
+    sample <- newInput spec
+    validateInput sample
+    column <- evaluate (inputColumn sample)
+    pure (PreparedInput column)
+  _ <- evaluate (rnf prepared)
+  performMajorGC
+  pure prepared
+
+
+main :: IO ()
+main = do
+  -- Validate every recipe even for --list, but discard each input before
+  -- preparing the next one. Environments allocate fresh timed fixtures.
+  mapM_ (\spec -> newInput spec >>= validateInput) inputSpecs
+  performMajorGC
+  defaultMain
+    [ bgroup "dictionary build" $
+        map
+          (\spec -> env (prepareInput spec) (\(PreparedInput column) -> bench (specName spec) (whnf W.buildDictionary column)))
+          inputSpecs
+    ]
diff --git a/bench/EncryptionThroughput.hs b/bench/EncryptionThroughput.hs
new file mode 100644
--- /dev/null
+++ b/bench/EncryptionThroughput.hs
@@ -0,0 +1,91 @@
+module Main (main) where
+
+import Control.Monad (forM_)
+import Criterion.Main
+import Data.ByteString qualified as BS
+import Data.Int (Int64)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Parquet.Encryption qualified as E
+import Parquet.HighLevel qualified as H
+import Parquet.Types
+import Parquet.Write qualified as W
+import System.Directory (createDirectoryIfMissing)
+import System.Environment (getArgs)
+import System.FilePath ((</>))
+
+
+data Workload = Workload
+  { workloadName :: !String
+  , workloadSize :: {-# UNPACK #-} !Int
+  , workloadAction :: !(H.FooterMode -> IO BS.ByteString)
+  }
+
+
+main :: IO ()
+main = do
+  let workloads = concatMap (\n -> [mixed n, nested n]) [64, 8192]
+      modes = [H.EncryptedFooter, H.SignedPlaintextFooter]
+  -- Materialize every input before Criterion starts: NestedRow elements are
+  -- intentionally shared across iterations, just like the Rust Arrow arrays.
+  forM_ workloads $ \work -> workloadAction work H.EncryptedFooter >>= \bytes -> BS.length bytes `seq` pure ()
+  getArgs >>= \case
+    ["--write-fixtures", directory] -> do
+      createDirectoryIfMissing True directory
+      forM_ workloads $ \work -> forM_ modes $ \mode -> do
+        bytes <- workloadAction work mode
+        BS.writeFile (directory </> (workloadName work ++ "-" ++ show (workloadSize work) ++ "-" ++ modeName mode ++ ".parquet")) bytes
+    _ -> defaultMain $ map (\work -> bgroup (workloadName work ++ "/" ++ show (workloadSize work)) (map (\mode -> bench (modeName mode) (nfIO (workloadAction work mode))) modes)) workloads
+
+
+modeName :: H.FooterMode -> String
+modeName H.EncryptedFooter = "encrypted"
+modeName H.SignedPlaintextFooter = "signed"
+
+
+options :: H.FooterMode -> IO H.WriteOptions
+options mode = do
+  footer <- W.newFooterEncryption (BS.replicate 16 0x42) "writer-regression" "kf"
+  let secret = W.ColumnEncryption E.AesGcmV1 (BS.replicate 16 0x44) (W.feFileId footer) "writer-regression" "kc2" 1
+  pure
+    H.defaultWriteOptions
+      { H.writeCompression = Uncompressed
+      , H.writePageVersion = W.PageV2
+      , H.writePageIndex = True
+      , H.writeFooterMode = mode
+      , H.writeFooterEncryption = Just footer
+      , H.writeColumnEncryption = V.fromList [Nothing, Just secret]
+      }
+
+
+mixed :: Int -> Workload
+mixed n =
+  let schema =
+        V.fromList
+          [ SchemaElement "schema" Nothing Nothing (Just 2) Nothing Nothing Nothing Nothing
+          , SchemaElement "public" (Just Required) (Just PTInt64) Nothing Nothing Nothing Nothing Nothing
+          , SchemaElement "secret" (Just Optional) (Just PTInt64) Nothing Nothing Nothing Nothing Nothing
+          ]
+      rows = [V.fromList [W.PCRequired (W.ColInt64 (VP.generate n fromIntegral)), W.PCOptional (W.OptInt64 (V.generate n (\i -> if i `rem` 5 == 0 then Nothing else Just (fromIntegral i * 3))))]]
+  in Workload "mixed" n (\mode -> options mode >>= \opts -> H.encodeParquetMixedIO opts schema rows >>= either fail pure)
+
+
+nested :: Int -> Workload
+nested n =
+  let schema =
+        V.fromList
+          [ ("public", H.NSRequired (H.NSPrimitive H.LtInt64))
+          , ("secret", H.NSOptional (H.NSList (H.NSOptional (H.NSPrimitive H.LtInt64))))
+          ]
+      rows =
+        V.fromList
+          [ V.generate n (H.NRLeaf . H.LvInt64 . fromIntegral)
+          , V.generate n $ \i ->
+              if i `rem` 11 == 0
+                then H.NRNull
+                else
+                  if i `rem` 7 == 0
+                    then H.NRList V.empty
+                    else H.NRList (V.generate 3 (\j -> if j == 0 && i `rem` 5 == 0 then H.NRNull else H.NRLeaf (H.LvInt64 (fromIntegral i * 3 + fromIntegral j :: Int64))))
+          ]
+  in Workload "nested" n (\mode -> options mode >>= \opts -> H.encodeParquetNestedIO opts schema rows >>= either fail pure)
diff --git a/bench/RleThroughput.hs b/bench/RleThroughput.hs
new file mode 100644
--- /dev/null
+++ b/bench/RleThroughput.hs
@@ -0,0 +1,65 @@
+module Main (main) where
+
+import Control.Exception (evaluate)
+import Control.Monad (unless)
+import Criterion.Main (bench, bgroup, defaultMain, whnf)
+import Data.Bits (shiftL, (.&.))
+import Data.ByteString qualified as BS
+import Data.Int (Int32)
+import Data.Vector.Primitive qualified as P
+import Data.Word (Word32, Word64)
+import Parquet.LevelsEncode qualified as Levels
+import Parquet.Read qualified as Read
+import System.Environment (getArgs)
+
+
+rowCount :: Int
+rowCount = 65536
+
+
+data Input = Input
+  { inputName :: !String
+  , inputWidth :: {-# UNPACK #-} !Int
+  , inputValues :: !(P.Vector Int32)
+  }
+
+
+inputs :: [Input]
+inputs = concatMap forWidth [0, 1, 2, 4, 8, 9, 16, 24, 31, 32]
+  where
+    forWidth width =
+      let mask = fromIntegral (((1 :: Word64) `shiftL` width) - 1) :: Word32
+          sample :: String -> (Word32 -> Word32) -> Input
+          sample label value = Input ("width " ++ show width ++ "/" ++ label ++ " 65536 values") width (P.generate rowCount (\i -> fromIntegral (value (fromIntegral i) .&. mask)))
+          constant = sample "constant" (const mask)
+      in if width == 0
+           then [constant]
+           else
+             [ constant
+             , sample "cycle" id
+             , sample "random" (\i -> i * 1664525 + 1013904223)
+             , sample "blocks8" (`quot` 8)
+             , sample "blocks24" (`quot` 24)
+             , sample "blocks64" (`quot` 64)
+             , sample "prefix" (\i -> if i == fromIntegral rowCount - 1 then mask else 0)
+             , sample "misaligned64" (\i -> if i < 3 then i else (i - 3) `quot` 64)
+             ]
+
+
+main :: IO ()
+main = do
+  mapM_
+    ( \sample -> do
+        let values = inputValues sample
+            width = inputWidth sample
+        _ <- evaluate (P.foldl' (+) 0 values)
+        let encoded = Levels.encodeRLEHybrid width values
+        unless
+          (Read.decodeDictionaryIndices rowCount (BS.cons (fromIntegral width) encoded) == Right values)
+          (fail (inputName sample ++ ": hybrid round trip failed"))
+    )
+    inputs
+  args <- getArgs
+  case args of
+    ["--sizes"] -> mapM_ (\sample -> putStrLn ("hybrid-size " ++ inputName sample ++ ": " ++ show (BS.length (Levels.encodeRLEHybrid (inputWidth sample) (inputValues sample))))) inputs
+    _ -> defaultMain [bgroup "hybrid encode" (map (\sample -> bench (inputName sample) (whnf (Levels.encodeRLEHybrid (inputWidth sample)) (inputValues sample))) inputs)]
diff --git a/bench/SelectionThroughput.hs b/bench/SelectionThroughput.hs
new file mode 100644
--- /dev/null
+++ b/bench/SelectionThroughput.hs
@@ -0,0 +1,266 @@
+-- Shared PyArrow fixtures and independent expected values are generated by
+-- scripts/parquet_selection_fixtures.py; see the benchmark manifest.
+module Main (main) where
+
+import Arrow.Column qualified as AC
+import Arrow.Column.Buffer qualified as Buffer
+import Arrow.Types qualified as AT
+import Control.DeepSeq (NFData, force)
+import Control.Exception (evaluate)
+import Control.Monad (unless)
+import Criterion.Main (bench, bgroup, defaultMain, nf)
+import Data.ByteString qualified as BS
+import Data.Int (Int32, Int64)
+import Data.Maybe (isJust)
+import Data.Text qualified as Text
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Storable qualified as VS
+import GHC.Generics (Generic)
+import Parquet.Arrow qualified as Arrow
+import Parquet.HighLevel qualified as HighLevel
+import Parquet.PageIndex qualified as PageIndex
+import Parquet.Predicate qualified as Predicate
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+import System.Environment (getEnv, lookupEnv)
+import System.FilePath ((</>))
+import Text.Read (readMaybe)
+
+
+data Fixture = Fixture
+  { fixtureName :: !String
+  , fixtureBytes :: !BS.ByteString
+  , fixturePredicate :: !Predicate.PColPredicate
+  , fixtureFile :: !Read.ParquetFile
+  , fixtureField :: !AT.Field
+  , fixtureCodec :: !P.Compression
+  , fixtureSelection :: !Read.PageSelection
+  }
+
+
+data RawValues = RawInt64 !(VP.Vector Int64) | RawBytes !(V.Vector BS.ByteString)
+  deriving stock (Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data RawColumn = RawColumn
+  { rawRepetition :: !(VP.Vector Int32)
+  , rawDefinition :: !(VP.Vector Int32)
+  , rawValues :: !RawValues
+  }
+  deriving stock (Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data BufferColumn = BufferColumn
+  { bufferRepetition :: !(VP.Vector Int32)
+  , bufferDefinition :: !(VP.Vector Int32)
+  , bufferOffsets :: !(VS.Vector Int32)
+  , bufferValues :: !BS.ByteString
+  }
+  deriving stock (Eq, Generic)
+  deriving anyclass (NFData)
+
+
+-- Time the native buffer readers used by Arrow, with metadata/index planning
+-- prepared. The legacy vector group remains an independent control.
+selectedBuffers :: Fixture -> BS.ByteString -> BufferColumn
+selectedBuffers fixture bytes = either error id $ case AT.fieldType field of
+  AT.AInt 64 True
+    | nullable -> leveled scalar (Read.readScalarBuffersSelectedLevels P.PTInt64 codec 0 1 bytes selection)
+    | otherwise -> dense scalar (Read.readScalarBuffersSelectedValues P.PTInt64 codec bytes selection)
+  AT.AUtf8
+    | nullable -> leveled binary (Read.readBinaryBuffersSelectedLevels codec 0 1 bytes selection)
+    | otherwise -> dense binary (Read.readBinaryBuffersSelectedValues codec bytes selection)
+  _ -> Left "unsupported buffer selection benchmark type"
+  where
+    field = fixtureField fixture
+    nullable = AT.fieldNullable field
+    codec = fixtureCodec fixture
+    selection = fixtureSelection fixture
+    scalar reps defs values = BufferColumn reps defs VS.empty (Read.scalarData values)
+    binary reps defs values = BufferColumn reps defs (Read.binaryOffsets values) (Read.binaryData values)
+    dense wrap decoded = wrap VP.empty VP.empty <$> decoded
+    leveled wrap decoded = do
+      levels <- decoded
+      Right (wrap (Read.clRepetition levels) (Read.clDefinition levels) (Read.clValues levels))
+
+
+expectedBuffers :: RawColumn -> BufferColumn
+expectedBuffers raw = case rawValues raw of
+  RawInt64 values -> BufferColumn reps defs VS.empty (Buffer.storableToBytes (VP.convert values :: VS.Vector Int64))
+  RawBytes values -> case AC.fromByteStrings values of
+    AC.ColBinary Nothing offsets bytes -> BufferColumn reps defs offsets bytes
+    _ -> error "expected dense binary reference buffers"
+  where
+    reps = rawRepetition raw
+    defs = rawDefinition raw
+
+
+-- Profile the legacy public vector readers, independently of the contiguous
+-- binary-buffer path used by Arrow. Only metadata and selection planning are
+-- prepared: headers, decompression, levels, dictionaries and values are
+-- decoded on every iteration, without constructing an Arrow column.
+selectedRaw :: Fixture -> BS.ByteString -> RawColumn
+selectedRaw fixture bytes = either error id $
+  case AT.fieldType field of
+    AT.AInt 64 True
+      | nullable -> leveled RawInt64 (Read.readInt64SelectedLevels codec 0 1 bytes selection)
+      | otherwise -> dense RawInt64 (Read.readInt64SelectedValues codec bytes selection)
+    AT.AUtf8
+      | nullable -> leveled RawBytes (Read.readByteArraySelectedLevels codec 0 1 bytes selection)
+      | otherwise -> dense RawBytes (Read.readByteArraySelectedValues codec bytes selection)
+    _ -> Left "unsupported raw selection benchmark type"
+  where
+    field = fixtureField fixture
+    nullable = AT.fieldNullable field
+    codec = fixtureCodec fixture
+    selection = fixtureSelection fixture
+    dense wrap decoded = RawColumn VP.empty VP.empty . wrap <$> decoded
+    leveled wrap decoded = do
+      levels <- decoded
+      Right (RawColumn (Read.clRepetition levels) (Read.clDefinition levels) (wrap (Read.clValues levels)))
+
+
+expectedRaw :: AT.Field -> AC.ColumnArray -> Either String RawColumn
+expectedRaw field column = case AT.fieldType field of
+  AT.AInt 64 True -> do
+    array <- maybe (Left "expected INT64 array") Right (AC.asPrim AC.PInt64 column)
+    Right (fromRows (RawInt64 . VP.convert) (V.generate count (AC.unsafePrimAt array)))
+  AT.AUtf8 -> do
+    array <- maybe (Left "expected byte array") Right (AC.asBinary column)
+    Right (fromRows RawBytes (V.generate count (AC.unsafeBytesAt array)))
+  _ -> Left "unsupported expected raw benchmark type"
+  where
+    count = AC.columnLength column
+    fromRows wrap rows =
+      RawColumn
+        (if AT.fieldNullable field then VP.replicate count 0 else VP.empty)
+        (if AT.fieldNullable field then VP.generate count (\i -> if isJust (rows V.! i) then 1 else 0) else VP.empty)
+        (wrap (V.mapMaybe id rows))
+
+
+data SelectionPlan = SelectionPlan
+  { planCodec :: !P.Compression
+  , planSelection :: !Read.PageSelection
+  }
+
+
+prepareSelection :: Predicate.PColPredicate -> Read.ParquetFile -> Either String SelectionPlan
+prepareSelection predicate file = do
+  bounds <- PageIndex.readColumnIndex file 0 0 >>= maybe (Left "missing column index") Right
+  offsets <- PageIndex.readOffsetIndex file 0 0 >>= maybe (Left "missing offset index") Right
+  let footer = Read.pfFooter file
+  group <- maybe (Left "missing row group") Right (P.fmRowGroups footer V.!? 0)
+  metadata <- maybe (Left "missing column metadata") Right (P.rgColumns group V.!? 0 >>= P.ccMetadata)
+  context <- maybe (Left "missing statistics context") Right (Predicate.statisticsContext footer 0)
+  let keep = (== Predicate.PMaybeKeep) <$> Predicate.evalPagesByColumnIndex context bounds predicate
+  Right (SelectionPlan (P.cmCodec metadata) (Read.PageSelection (P.oiPageLocations offsets) keep (P.cmDictionaryPageOffset metadata) (Just (P.rgNumRows group))))
+
+
+selected :: Predicate.PColPredicate -> BS.ByteString -> AC.ColumnArray
+selected predicate bytes = either error id $ do
+  file <- HighLevel.decodeParquet HighLevel.defaultReadOptions bytes
+  schema <- Arrow.parquetFileArrowSchemaChecked file
+  field <- maybe (Left "selection fixture has no column") Right (AT.arrowFields schema V.!? 0)
+  snd <$> Arrow.readParquetColumnWithPagePruning file 0 0 field predicate
+
+
+-- File/schema planning is forced and value-checked during fixture loading.
+-- This still times index parsing, page selection, decoding and Arrow assembly.
+selectedPlanned :: Predicate.PColPredicate -> AT.Field -> Read.ParquetFile -> AC.ColumnArray
+selectedPlanned predicate field file =
+  either error snd $
+    Arrow.readParquetColumnWithPagePruning file 0 0 field predicate
+
+
+-- Force both index readers and every pruning decision without decoding pages.
+-- Summing retained page row ranges gives a check against the independent output.
+selectedIndexRows :: Predicate.PColPredicate -> Read.ParquetFile -> Int64
+selectedIndexRows predicate file = either error id $ do
+  bounds <- PageIndex.readColumnIndex file 0 0 >>= maybe (Left "missing column index") Right
+  offsets <- PageIndex.readOffsetIndex file 0 0 >>= maybe (Left "missing offset index") Right
+  let metadata = Read.pfFooter file
+      locations = P.oiPageLocations offsets
+  group <- maybe (Left "missing row group") Right (P.fmRowGroups metadata V.!? 0)
+  context <- maybe (Left "missing statistics context") Right (Predicate.statisticsContext metadata 0)
+  let keep = (== Predicate.PMaybeKeep) <$> Predicate.evalPagesByColumnIndex context bounds predicate
+      rows total i retained
+        | not retained = total
+        | otherwise =
+            let start = P.plFirstRowIndex (locations V.! i)
+                end = maybe (P.rgNumRows group) P.plFirstRowIndex (locations V.!? (i + 1))
+            in total + end - start
+  if V.length locations /= V.length keep
+    then Left "page index lengths disagree"
+    else Right (V.ifoldl' rows 0 keep)
+
+
+loadFixtures :: IO [Fixture]
+loadFixtures = do
+  root <- getEnv "WIREFORM_PARQUET_SELECTION_FIXTURES"
+  plans <- lines <$> readFile (root </> "selection-plan.txt")
+  traverse (load root . words) plans
+  where
+    load root [name, typ, literal] = do
+      value <- case typ of
+        "text" -> pure (Predicate.PVText (Text.pack literal))
+        "int" -> maybe (fail "invalid integer selection pivot") (pure . Predicate.PVInt64) (readMaybe literal)
+        _ -> fail "invalid selection fixture type"
+      bytes <- BS.readFile (root </> (name ++ ".parquet"))
+      expectedBytes <- BS.readFile (root </> (name ++ "-expected.parquet"))
+      expected <- evaluate $ force $ either error id $ do
+        file <- HighLevel.decodeParquet HighLevel.defaultReadOptions expectedBytes
+        schema <- Arrow.parquetFileArrowSchemaChecked file
+        field <- maybe (Left "expected fixture has no column") Right (AT.arrowFields schema V.!? 0)
+        Arrow.readParquetColumn file 0 0 field
+      let predicate = Predicate.PGtEq value
+      actual <- evaluate (force (selected predicate bytes))
+      unless (actual == expected) (fail ("selection value mismatch: " ++ name))
+      file <- either fail pure (HighLevel.decodeParquet HighLevel.defaultReadOptions bytes)
+      schema <- either fail pure (Arrow.parquetFileArrowSchemaChecked file)
+      field <- maybe (fail "selection fixture has no column") pure (AT.arrowFields schema V.!? 0)
+      planned <- evaluate (force (selectedPlanned predicate field file))
+      unless (planned == expected) (fail ("planned selection value mismatch: " ++ name))
+      indexedRows <- evaluate (selectedIndexRows predicate file)
+      unless (indexedRows == fromIntegral (AC.columnLength expected)) (fail ("index row count mismatch: " ++ name))
+      plan <- either fail pure (prepareSelection predicate file)
+      let fixture = Fixture name bytes predicate file field (planCodec plan) (planSelection plan)
+      raw <- evaluate (force (selectedRaw fixture bytes))
+      expectedValues <- either fail (evaluate . force) (expectedRaw field expected)
+      unless (raw == expectedValues) (fail ("raw selection value/level mismatch: " ++ name))
+      buffers <- evaluate (force (selectedBuffers fixture bytes))
+      referenceBuffers <- evaluate (force (expectedBuffers expectedValues))
+      unless (buffers == referenceBuffers) (fail ("native buffer selection value/level mismatch: " ++ name))
+      pure fixture
+    load _ _ = fail "invalid selection plan"
+
+
+main :: IO ()
+main = do
+  fixtures <- loadFixtures
+  profile <- (== Just "1") <$> lookupEnv "WIREFORM_PARQUET_PROFILE_PHASES"
+  let planned =
+        if profile
+          then
+            [ bgroup "selected pages planned" (plannedBenchmark <$> fixtures)
+            , bgroup "selected pages index" (indexBenchmark <$> fixtures)
+            , bgroup "selected pages raw" (rawBenchmark <$> fixtures)
+            , bgroup "selected pages buffers" (bufferBenchmark <$> fixtures)
+            ]
+          else []
+  defaultMain ([bgroup "selected pages" (benchmark <$> fixtures)] ++ planned)
+  where
+    benchmark fixture = bench (fixtureName fixture) (nf (selected (fixturePredicate fixture)) (fixtureBytes fixture))
+    bufferBenchmark fixture = bench (fixtureName fixture) (nf (selectedBuffers fixture) (fixtureBytes fixture))
+    plannedBenchmark fixture =
+      bench
+        (fixtureName fixture)
+        (nf (selectedPlanned (fixturePredicate fixture) (fixtureField fixture)) (fixtureFile fixture))
+    indexBenchmark fixture =
+      bench
+        (fixtureName fixture)
+        (nf (selectedIndexRows (fixturePredicate fixture)) (fixtureFile fixture))
+    rawBenchmark fixture =
+      bench (fixtureName fixture) (nf (selectedRaw fixture) (fixtureBytes fixture))
diff --git a/bench/Throughput.hs b/bench/Throughput.hs
new file mode 100644
--- /dev/null
+++ b/bench/Throughput.hs
@@ -0,0 +1,272 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | End-to-end Parquet write + read throughput baseline for
+wireform-parquet, measured on a synthetic dataset of
+realistic shape and size. Output goes through criterion +
+a JSON report so the matching Python driver can compare
+against pyarrow on the same shape.
+
+Usage:
+
+@
+cabal bench wireform-parquet:parquet-throughput
+
+# or, with explicit options for the JSON reporter:
+cabal bench wireform-parquet:parquet-throughput \\
+  -- --json wireform_throughput.json
+@
+
+The dataset:
+
+  * 100,000 rows
+  * 4 columns: int64 id, double score, utf8 names drawn from 1000 values, bool active
+  * single row group and one required PLAIN V2 page per column
+  * uncompressed, Snappy and Zstd at level 3
+
+Each measurement is one full encode (or decode) of the
+complete dataset; criterion divides the wall-clock time by
+the iteration count so the raw seconds are per-encode.
+-}
+module Main (main) where
+
+import Arrow.Column qualified as AC
+import Arrow.Types qualified as AT
+import Control.DeepSeq (NFData (..), deepseq)
+import Control.Monad (unless)
+import Criterion.Main (bench, bgroup, defaultMain, env, nf, whnf)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as BB
+import Data.ByteString.Lazy qualified as BL
+import Data.Text.Encoding qualified as TE
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Storable qualified as VS
+import Parquet.Arrow qualified as PArrow
+import Parquet.HighLevel qualified as PHL
+import Parquet.Page qualified as Page
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+import Parquet.Write (ColumnData (..))
+import System.Directory (createDirectoryIfMissing)
+import System.Environment (getArgs)
+import System.FilePath ((</>))
+
+
+{- | 100k rows is enough to push past per-call overhead while
+keeping each criterion sample under a second.
+-}
+nRows :: Int
+nRows = 100_000
+
+
+{- | Generate the same 4-column dataset every run.
+
+id      = increasing Int64 0..N-1
+score   = i * 0.5
+name    = "name_<i_mod_1000>" (so dict encoding has work to do)
+active  = i `rem` 2 == 0
+-}
+mkDataset :: Int -> V.Vector ColumnData
+mkDataset n =
+  V.fromList
+    [ ColInt64 (VP.generate n fromIntegral)
+    , ColDouble (VP.generate n (\i -> fromIntegral i * 0.5))
+    , ColByteArray $ V.generate n $ \i -> V.unsafeIndex names (i `rem` 1000)
+    , ColBool (V.generate n (\i -> i `rem` 2 == 0))
+    ]
+  where
+    names = V.generate 1000 (BL.toStrict . BB.toLazyByteString . ("name_" <>) . BB.intDec)
+
+
+mkSchema :: V.Vector P.SchemaElement
+mkSchema =
+  V.fromList
+    [ P.SchemaElement "schema" Nothing Nothing (Just 4) Nothing Nothing Nothing Nothing
+    , P.SchemaElement "id" (Just P.Required) (Just P.PTInt64) Nothing Nothing Nothing Nothing Nothing
+    , P.SchemaElement "score" (Just P.Required) (Just P.PTDouble) Nothing Nothing Nothing Nothing Nothing
+    , P.SchemaElement "name" (Just P.Required) (Just P.PTByteArray) Nothing (Just P.CTUtf8) Nothing Nothing Nothing
+    , P.SchemaElement "active" (Just P.Required) (Just P.PTBoolean) Nothing Nothing Nothing Nothing Nothing
+    ]
+
+
+writeFile_ :: V.Vector ColumnData -> BS.ByteString
+writeFile_ cols =
+  PHL.encodeParquet
+    PHL.defaultWriteOptions {PHL.writeCompression = P.Uncompressed, PHL.writePageIndex = False}
+    mkSchema
+    [cols]
+
+
+writeFileZstd :: V.Vector ColumnData -> BS.ByteString
+writeFileZstd cols =
+  PHL.encodeParquet
+    PHL.defaultWriteOptions {PHL.writeCompression = P.ZSTD, PHL.writePageIndex = False}
+    mkSchema
+    [cols]
+
+
+writeFileSnappy :: V.Vector ColumnData -> BS.ByteString
+writeFileSnappy cols =
+  PHL.encodeParquet
+    PHL.defaultWriteOptions {PHL.writeCompression = P.Snappy, PHL.writePageIndex = False}
+    mkSchema
+    [cols]
+
+
+-- Retain the decoded batches just as the Rust/C++ public readers do.
+-- Criterion forces every buffer; timing a row count could discard columns
+-- earlier and would not check that the requested values were reconstructed.
+data DecodedFixture = DecodedFixture
+  { fixtureSchema :: !AT.Schema
+  , fixtureBatches :: ![V.Vector AC.ColumnArray]
+  }
+
+
+decodeFixture :: BS.ByteString -> Either String DecodedFixture
+decodeFixture bs = do
+  file <- PHL.decodeParquet PHL.defaultReadOptions bs
+  schema <- PArrow.parquetFileArrowSchemaChecked file
+  batches <-
+    mapM
+      (\i -> either (Left . show) Right (PArrow.parquetRowGroupToArrow schema file i))
+      [0 .. PArrow.numRowGroups file - 1]
+  Right (DecodedFixture schema batches)
+
+
+readBack :: BS.ByteString -> [V.Vector AC.ColumnArray]
+readBack = either error fixtureBatches . decodeFixture
+
+
+data FileCase = FileCase
+  { fileLabel :: !FilePath
+  , fileCodec :: !P.Compression
+  , fileEncode :: !(V.Vector ColumnData -> BS.ByteString)
+  }
+
+
+fileCases :: [FileCase]
+fileCases = [FileCase "uncompressed" P.Uncompressed writeFile_, FileCase "snappy" P.Snappy writeFileSnappy, FileCase "zstd" P.ZSTD writeFileZstd]
+
+
+expectedSchema :: AT.Schema
+expectedSchema =
+  AT.Schema
+    (V.fromList [field "id" (AT.AInt 64 True), field "score" (AT.AFloatingPoint AT.DoublePrecision), field "name" AT.AUtf8, field "active" AT.ABool])
+    AT.Little
+    V.empty
+    V.empty
+  where
+    field name typ = AT.Field name False typ V.empty Nothing V.empty
+
+
+expectedColumns :: V.Vector AC.ColumnArray
+expectedColumns =
+  V.fromList
+    [ AC.primColumn AC.PInt64 (VS.generate nRows fromIntegral)
+    , AC.primColumn AC.PDouble (VS.generate nRows (\i -> fromIntegral i * 0.5))
+    , AC.fromTexts (V.generate nRows (\i -> V.unsafeIndex names (i `rem` 1000)))
+    , AC.fromBools (V.generate nRows even)
+    ]
+  where
+    names = V.generate 1000 (TE.decodeUtf8 . BL.toStrict . BB.toLazyByteString . ("name_" <>) . BB.intDec)
+
+
+validateFixture :: P.Compression -> BS.ByteString -> Either String ()
+validateFixture codec bytes = do
+  decoded <- decodeFixture bytes
+  require (AT.schemaEquivalent (fixtureSchema decoded) expectedSchema) "schema differs from the required four-column model"
+  require (fixtureBatches decoded == [expectedColumns]) "decoded values differ from the 100000-row model"
+  file <- PHL.decodeParquet PHL.defaultReadOptions bytes
+  let footer = Read.pfFooter file
+      groups = P.fmRowGroups footer
+  require (P.fmNumRows footer == fromIntegral nRows && V.length groups == 1) "layout must have one 100000-row group"
+  group <- maybe (Left "fixture: missing row group") Right (groups V.!? 0)
+  require (P.rgNumRows group == fromIntegral nRows && V.length (P.rgColumns group) == 4) "layout must have four required columns"
+  V.imapM_ (validateColumn file) (P.rgColumns group)
+  where
+    require condition message = unless condition (Left ("benchmark fixture: " ++ message))
+    validateColumn file index chunk = do
+      metadata <- maybe (Left "benchmark fixture: missing column metadata") Right (P.ccMetadata chunk)
+      require (P.cmCodec metadata == codec) "codec differs from benchmark label"
+      require (P.cmNumValues metadata == fromIntegral nRows) "column event count differs from model"
+      require (P.cmDictionaryPageOffset metadata == Nothing && not (V.any (`elem` [P.PlainDictionary, P.RLEDictionary]) (P.cmEncodings metadata))) "layout must disable dictionary encoding"
+      require (P.ccOffsetIndexOffset chunk == Nothing && P.ccColumnIndexOffset chunk == Nothing) "layout must disable page indexes"
+      body <- Read.columnChunkSlice file 0 index
+      (header, offset) <- Page.readPageHeaderAt body 0
+      case Page.phType header of
+        Page.PtDataPageV2 page -> do
+          require (Page.dph2NumValues page == fromIntegral nRows && Page.dph2NumRows page == fromIntegral nRows && Page.dph2NumNulls page == 0) "V2 page row/null counts differ from model"
+          require (Page.dph2Encoding page == 0 && Page.dph2DefLevelsLen page == 0 && Page.dph2RepLevelsLen page == 0) "layout must use required PLAIN V2 values without level streams"
+          require (Page.dph2IsCompressed page == (codec /= P.Uncompressed)) "page compression flag differs from benchmark label"
+        _ -> Left "benchmark fixture: layout must use V2 data pages"
+      size <- maybe (Left "benchmark fixture: missing page size") (Right . fromIntegral) (Page.phCompressedPageSize header)
+      require (offset + size == BS.length body) "layout must have exactly one page per column"
+
+
+verifyGenerated :: V.Vector ColumnData -> IO ()
+verifyGenerated dataset = do
+  dataset `deepseq` pure ()
+  mapM_ (\sample -> either (fail . ((fileLabel sample ++ ": ") ++)) pure (validateFixture (fileCodec sample) (fileEncode sample dataset))) fileCases
+
+
+verifyFiles :: FilePath -> IO ()
+verifyFiles dir =
+  mapM_
+    ( \sample -> do
+        bytes <- BS.readFile (dir </> fileLabel sample ++ ".parquet")
+        either (fail . ((fileLabel sample ++ ": ") ++)) pure (validateFixture (fileCodec sample) bytes)
+    )
+    fileCases
+
+
+instance NFData ColumnData where
+  rnf (ColInt32 v) = v `seq` ()
+  rnf (ColInt64 v) = v `seq` ()
+  rnf (ColFloat v) = v `seq` ()
+  rnf (ColDouble v) = v `seq` ()
+  rnf (ColBool v) = v `deepseq` ()
+  rnf (ColByteArray v) = v `deepseq` ()
+
+
+main :: IO ()
+main = do
+  args <- getArgs
+  case args of
+    ["--verify-fixtures", dir] -> verifyFiles dir
+    ["--write-fixtures", dir] -> do
+      createDirectoryIfMissing True dir
+      let !dataset = mkDataset nRows
+      verifyGenerated dataset
+      mapM_ (\sample -> BS.writeFile (dir </> fileLabel sample ++ ".parquet") (fileEncode sample dataset)) fileCases
+    _ -> do
+      verifyGenerated (mkDataset nRows)
+      runBenchmarks
+
+
+runBenchmarks :: IO ()
+runBenchmarks =
+  let !dataset = mkDataset nRows
+  in defaultMain
+       [ env (pure dataset) $ \cols ->
+           bgroup
+             ("write " ++ show nRows ++ " rows x 4 cols")
+             [ bench "uncompressed" $ whnf (BS.length . writeFile_) cols
+             , bench "snappy" $ whnf (BS.length . writeFileSnappy) cols
+             , bench "zstd" $ whnf (BS.length . writeFileZstd) cols
+             ]
+       , env (pure (writeFile_ dataset)) $ \bs ->
+           bgroup
+             ("read " ++ show nRows ++ " rows x 4 cols (uncompressed)")
+             [ bench "decode" $ nf readBack bs
+             ]
+       , env (pure (writeFileSnappy dataset)) $ \bs ->
+           bgroup
+             ("read " ++ show nRows ++ " rows x 4 cols (snappy)")
+             [ bench "decode" $ nf readBack bs
+             ]
+       , env (pure (writeFileZstd dataset)) $ \bs ->
+           bgroup
+             ("read " ++ show nRows ++ " rows x 4 cols (zstd)")
+             [ bench "decode" $ nf readBack bs
+             ]
+       ]
diff --git a/bench/XXH64Pure.hs b/bench/XXH64Pure.hs
new file mode 100644
--- /dev/null
+++ b/bench/XXH64Pure.hs
@@ -0,0 +1,130 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | Pure-Haskell XXH64 reference implementation, used /only/ by the
+criterion benchmark suite to measure the speedup of the C/SIMDe
+kernel in "Wireform.Hash". Not a public API.
+-}
+module XXH64Pure (xxh64_pure, xxh64Seed_pure) where
+
+import Data.Bits (rotateL, shiftR, unsafeShiftL, xor, (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Word (Word32, Word64)
+
+
+prime1, prime2, prime3, prime4, prime5 :: Word64
+prime1 = 0x9E3779B185EBCA87
+prime2 = 0xC2B2AE3D27D4EB4F
+prime3 = 0x165667B19E3779F9
+prime4 = 0x85EBCA77C2B2AE63
+prime5 = 0x27D4EB2F165667C5
+
+
+xxh64_pure :: ByteString -> Word64
+xxh64_pure = xxh64Seed_pure 0
+
+
+xxh64Seed_pure :: Word64 -> ByteString -> Word64
+xxh64Seed_pure seed bs =
+  let !len = BS.length bs
+      !nStripes = len `shiftR` 5
+      !tailOff = nStripes `unsafeShiftL` 5
+      !h0 = if len >= 32 then bulkPhase seed bs nStripes else seed + prime5
+      !h1 = h0 + fromIntegral len
+  in finalize h1 tailOff bs len
+
+
+bulkPhase :: Word64 -> ByteString -> Int -> Word64
+bulkPhase seed bs nStripes =
+  let !v1_0 = seed + prime1 + prime2
+      !v2_0 = seed + prime2
+      !v3_0 = seed
+      !v4_0 = seed - prime1
+      go !i !off !a1 !a2 !a3 !a4
+        | i >= nStripes = (a1, a2, a3, a4)
+        | otherwise =
+            let !w1 = readLE64 bs off
+                !w2 = readLE64 bs (off + 8)
+                !w3 = readLE64 bs (off + 16)
+                !w4 = readLE64 bs (off + 24)
+            in go
+                 (i + 1)
+                 (off + 32)
+                 (round_ a1 w1)
+                 (round_ a2 w2)
+                 (round_ a3 w3)
+                 (round_ a4 w4)
+      (!fv1, !fv2, !fv3, !fv4) = go 0 0 v1_0 v2_0 v3_0 v4_0
+      !merged =
+        rotateL fv1 1
+          + rotateL fv2 7
+          + rotateL fv3 12
+          + rotateL fv4 18
+      !m1 = mergeAccumulator merged fv1
+      !m2 = mergeAccumulator m1 fv2
+      !m3 = mergeAccumulator m2 fv3
+      !m4 = mergeAccumulator m3 fv4
+  in m4
+
+
+finalize :: Word64 -> Int -> ByteString -> Int -> Word64
+finalize !h0 !startOff bs !len = avalanche (go h0 startOff)
+  where
+    go !h !off
+      | off + 8 <= len =
+          let !k1raw = readLE64 bs off
+              !k1 = round_ 0 k1raw
+              !h' = rotateL (h `xor` k1) 27 * prime1 + prime4
+          in go h' (off + 8)
+      | off + 4 <= len =
+          let !w = fromIntegral (readLE32 bs off) :: Word64
+              !h' = rotateL (h `xor` (w * prime1)) 23 * prime2 + prime3
+          in go h' (off + 4)
+      | off < len =
+          let !b = fromIntegral (BSU.unsafeIndex bs off) :: Word64
+              !h' = rotateL (h `xor` (b * prime5)) 11 * prime1
+          in go h' (off + 1)
+      | otherwise = h
+
+
+avalanche :: Word64 -> Word64
+avalanche !h0 =
+  let !h1 = h0 `xor` (h0 `shiftR` 33)
+      !h2 = h1 * prime2
+      !h3 = h2 `xor` (h2 `shiftR` 29)
+      !h4 = h3 * prime3
+      !h5 = h4 `xor` (h4 `shiftR` 32)
+  in h5
+
+
+round_ :: Word64 -> Word64 -> Word64
+round_ !acc !w = rotateL (acc + w * prime2) 31 * prime1
+
+
+mergeAccumulator :: Word64 -> Word64 -> Word64
+mergeAccumulator !merged !v =
+  let !v' = round_ 0 v
+  in (merged `xor` v') * prime1 + prime4
+
+
+readLE64 :: ByteString -> Int -> Word64
+readLE64 bs !off =
+  let rd i = fromIntegral (BSU.unsafeIndex bs (off + i)) :: Word64
+  in rd 0
+       .|. (rd 1 `unsafeShiftL` 8)
+       .|. (rd 2 `unsafeShiftL` 16)
+       .|. (rd 3 `unsafeShiftL` 24)
+       .|. (rd 4 `unsafeShiftL` 32)
+       .|. (rd 5 `unsafeShiftL` 40)
+       .|. (rd 6 `unsafeShiftL` 48)
+       .|. (rd 7 `unsafeShiftL` 56)
+
+
+readLE32 :: ByteString -> Int -> Word32
+readLE32 bs !off =
+  let rd i = fromIntegral (BSU.unsafeIndex bs (off + i)) :: Word32
+  in rd 0
+       .|. (rd 1 `unsafeShiftL` 8)
+       .|. (rd 2 `unsafeShiftL` 16)
+       .|. (rd 3 `unsafeShiftL` 24)
diff --git a/probe/Probe.hs b/probe/Probe.hs
new file mode 100644
--- /dev/null
+++ b/probe/Probe.hs
@@ -0,0 +1,1380 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+{- | wireform-parquet -> pyarrow / duckdb / polars round-trip
+probe.
+
+Writes a fixed catalogue of one-file-per-shape Parquet files
+under the directory passed as @argv[1]@. The companion
+'scripts/parquet_interop.py' driver opens each one with
+pyarrow, then with duckdb, then with polars and asserts the
+contents match what we expect.
+
+The default catalogue uses 'Parquet.HighLevel.encodeParquet' /
+'encodeParquetMixed'. The @--delta-int32@ / @--delta-int64@ modes export
+raw codec output for independently framed cross-reader checks.
+-}
+module Main (main) where
+
+import Arrow.Column qualified as AC
+import Arrow.File qualified as ArrowFile
+import Arrow.Read.Columns qualified as ArrowRead
+import Arrow.Types qualified as AT
+import Control.Monad (forM_, when)
+import Crypto.Random.Types qualified as RNG
+import Data.Bits (shiftL, shiftR, (.&.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int32, Int64)
+import Data.Text (Text)
+import Data.Text.Encoding qualified as TE
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Storable qualified as VS
+import Data.Word (Word32, Word64, Word8)
+import Foreign.Storable (Storable)
+import GHC.Float (castWord32ToFloat, castWord64ToDouble)
+import Parquet qualified as PHL
+import Parquet.Compress qualified as Compress
+import Parquet.DeltaEncode qualified as Delta
+import Parquet.Encryption qualified as Enc
+import Parquet.File qualified as File
+import Parquet.Footer qualified as Footer
+import Parquet.Nested qualified as PN
+import Parquet.PageIndex qualified as PageIndex
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+import Parquet.Variant qualified as Variant
+import Parquet.Variant.Arrow qualified as VariantArrow
+import Parquet.Variant.Parquet qualified as VariantParquet
+import Parquet.Variant.Shred qualified as VariantShred
+import Parquet.Write (
+  ColumnData (..),
+  OptionalColumn (..),
+  ParquetColumn (..),
+ )
+import Parquet.Write qualified as PW
+import System.Directory (createDirectoryIfMissing, listDirectory)
+import System.Environment (getArgs)
+import System.Exit (exitFailure)
+import System.FilePath (takeBaseName, takeExtension, (</>))
+
+
+main :: IO ()
+main = do
+  args <- getArgs
+  case args of
+    ["--variant-from-binary", sourceDir, outDir] -> writeVariantInputs sourceDir outDir
+    ["--file", outDir] -> writeFileProbes outDir
+    ["--file-check", sourceDir] -> checkFileReferences sourceDir
+    ["--from-arrow", sourceDir, outDir] -> writeArrowInputs sourceDir outDir
+    ["--nested-from-arrow", sourceDir, outDir] -> writeNestedArrowInputs sourceDir outDir
+    ["--nested-options-from-arrow", sourceDir, outDir] -> writeNestedOptionsArrowInputs sourceDir outDir
+    ["--variant-shred-from-arrow", sourceDir, outDir] -> writeShreddedVariantInputs sourceDir outDir
+    ["--metadata", outDir] -> writeMetadataProbes outDir
+    ["--copy-footers", sourceDir, outDir] -> copyMetadataFooters sourceDir outDir
+    ["--lzo", outDir] -> writeLzoProbes outDir
+    ["--codec-profiles", outDir] -> writeCodecProfiles outDir
+    ["--logical-metadata", outDir] -> writeLogicalMetadataProbes outDir
+    ["--nested-types", outDir] -> writeNestedTypeProbes outDir
+    ["--dictionary-bytes", outDir] -> writeDictionaryBytesProbes outDir
+    ["--dictionary-ieee", outDir] -> writeDictionaryIEEEProbes outDir
+    ["--delta-int32", outDir] -> writeDeltaInt32Probes outDir
+    ["--delta-int64", outDir] -> writeDeltaInt64Probes outDir
+    ["--decimal", outDir] -> writeDecimalProbes outDir
+    ["--writer-options", outDir] -> writeOptionsProbes outDir
+    ["--statistics", outDir] -> writeStatisticsProbes outDir
+    ["--encrypted", outDir, metadataPath, keyWidth] -> do
+      width <- case keyWidth of
+        "16" -> pure 16
+        "24" -> pure 24
+        "32" -> pure 32
+        _ -> fail "fixture AES key width must be 16, 24 or 32 bytes"
+      createDirectoryIfMissing True outDir
+      metadata <- BS.readFile metadataPath
+      writeEncryptedProbes width outDir metadata
+    ["--encrypted", outDir, metadataPath] -> do
+      metadata <- BS.readFile metadataPath
+      writeEncryptedProbes 16 outDir metadata
+    [outDir] -> do
+      writeAllProbes outDir
+      putStrLn ("wrote parquet probe outputs to " ++ outDir)
+    _ -> do
+      putStrLn "usage: wireform-parquet-interop-probe [--encrypted] <output-dir> [test-key-metadata-json]"
+      exitFailure
+
+
+writeVariantInputs :: FilePath -> FilePath -> IO ()
+writeVariantInputs sourceDir outDir = do
+  createDirectoryIfMissing True outDir
+  names <- filter ((== ".meta") . takeExtension) <$> listDirectory sourceDir
+  mapM_
+    ( \name -> do
+        metadata <- BS.readFile (sourceDir </> name)
+        payload <- BS.readFile (sourceDir </> takeBaseName name ++ ".value")
+        value <- either fail pure (Variant.decodeVariant metadata payload)
+        bytes <- either fail pure (VariantParquet.buildVariantParquetFile "v" (V.fromList [Just value, Nothing, Just Variant.VNull]))
+        BS.writeFile (outDir </> takeBaseName name ++ ".parquet") bytes
+    )
+    names
+
+
+writeArrowInputs :: FilePath -> FilePath -> IO ()
+writeArrowInputs sourceDir outDir = do
+  createDirectoryIfMissing True outDir
+  names <- listDirectory sourceDir
+  mapM_
+    ( \name -> when (takeExtension name == ".arrow") $ do
+        bytes <- BS.readFile (sourceDir </> name)
+        (schema, batches) <- either fail pure (ArrowFile.readArrowFileColumns ArrowRead.defaultReadOptions bytes)
+        (target, groups) <- either fail pure (PHL.arrowToParquetMixed schema (V.toList batches))
+        let options = PHL.defaultWriteOptions {PHL.writeCompression = P.Uncompressed, PHL.writePageVersion = PW.PageV2}
+        BS.writeFile (outDir </> takeBaseName name <> ".parquet") (PHL.encodeParquetMixed options target groups)
+    )
+    names
+
+
+writeMetadataProbes :: FilePath -> IO ()
+writeMetadataProbes outDir = do
+  createDirectoryIfMissing True outDir
+  let schema =
+        V.fromList
+          [ P.SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+          , P.SchemaElement "x" (Just P.Required) (Just P.PTInt32) Nothing Nothing Nothing Nothing Nothing
+          ]
+      bytes =
+        PHL.encodeParquet
+          (PHL.defaultWriteOptions {PHL.writeCompression = P.Uncompressed})
+          schema
+          [V.singleton (ColInt32 (VP.fromList [minBound, 0, maxBound]))]
+      entries =
+        V.fromList
+          [ P.KeyValue "same" Nothing
+          , P.KeyValue "same" (Just "")
+          , P.KeyValue "same" (Just "last")
+          , P.KeyValue (TE.encodeUtf8 "κλειδί") (Just (TE.encodeUtf8 "世界"))
+          , P.KeyValue "opaque" (Just (BS.pack [255, 0, 128]))
+          ]
+  mapM_
+    ( \(name, values) -> do
+        metadata <- either fail pure (Footer.readFooter bytes)
+        trailer <- either fail pure (Footer.readFooterTrailer bytes)
+        let prefix = BS.take (BS.length bytes - 8 - BS.length (Footer.ftBytes trailer)) bytes
+        BS.writeFile
+          (outDir </> name <> ".parquet")
+          (prefix <> Footer.writeFooter (metadata {P.fmKeyValueMetadata = values}))
+    )
+    [("absent", Nothing), ("empty", Just V.empty), ("entries", Just entries)]
+
+
+copyMetadataFooters :: FilePath -> FilePath -> IO ()
+copyMetadataFooters sourceDir outDir = do
+  createDirectoryIfMissing True outDir
+  names <- listDirectory sourceDir
+  mapM_
+    ( \name -> when (takeExtension name == ".parquet") $ do
+        bytes <- BS.readFile (sourceDir </> name)
+        metadata <- either fail pure (Footer.readFooter bytes)
+        trailer <- either fail pure (Footer.readFooterTrailer bytes)
+        let prefix = BS.take (BS.length bytes - 8 - BS.length (Footer.ftBytes trailer)) bytes
+        BS.writeFile (outDir </> name) (prefix <> Footer.writeFooter metadata)
+    )
+    names
+
+
+-- Broad native codec coverage; availability is checked by the external
+-- driver against its explicitly requested build profile.
+writeCodecProfiles :: FilePath -> IO ()
+writeCodecProfiles directory = do
+  createDirectoryIfMissing True directory
+  let many = V.fromList . concat . replicate 16
+      schema repetition =
+        V.fromList
+          [ P.SchemaElement "schema" Nothing Nothing (Just 4) Nothing Nothing Nothing Nothing
+          , P.SchemaElement "i" (Just repetition) (Just P.PTInt32) Nothing Nothing Nothing Nothing Nothing
+          , P.SchemaElement "s" (Just repetition) (Just P.PTByteArray) Nothing (Just P.CTUtf8) (Just P.LTString) Nothing Nothing
+          , P.SchemaElement "b" (Just repetition) (Just P.PTBoolean) Nothing Nothing Nothing Nothing Nothing
+          , P.SchemaElement "d" (Just repetition) (Just P.PTDouble) Nothing Nothing Nothing Nothing Nothing
+          ]
+      ordinary =
+        V.fromList
+          [ PCOptional (OptInt32 (many [Just minBound, Nothing, Just 0, Just maxBound, Nothing]))
+          , PCOptional (OptByteArray (many [Just (TE.encodeUtf8 "κόσμε"), Nothing, Just "", Just "alpha", Nothing]))
+          , PCOptional (OptBool (many [Just True, Nothing, Just False, Just True, Nothing]))
+          , PCOptional (OptDouble (many [Just (-1.5), Nothing, Just 0, Just 1.25, Nothing]))
+          ]
+      required =
+        V.fromList
+          [ PCRequired (ColInt32 (VP.fromList (concat (replicate 16 [minBound, -1, 0, maxBound, 1]))))
+          , PCRequired (ColByteArray (many [TE.encodeUtf8 "κόσμε", "beta", "", "alpha", "omega"]))
+          , PCRequired (ColBool (many [True, False, False, True, False]))
+          , PCRequired (ColDouble (VP.fromList (concat (replicate 16 [-1.5, -1, 0, 1.25, 2]))))
+          ]
+      nulls n = V.fromList [PCOptional (OptInt32 (V.replicate n Nothing)), PCOptional (OptByteArray (V.replicate n Nothing)), PCOptional (OptBool (V.replicate n Nothing)), PCOptional (OptDouble (V.replicate n Nothing))]
+  mapM_
+    ( \(label, codec) -> case Compress.validateCompression codec of
+        Left _ -> pure ()
+        Right () ->
+          mapM_
+            ( \(versionName, version) ->
+                mapM_
+                  ( \indexed ->
+                      mapM_
+                        ( \(shape, repetition, columns) -> do
+                            let options = PHL.defaultWriteOptions {PHL.writeCompression = codec, PHL.writePageVersion = version, PHL.writePageIndex = indexed}
+                                name = label ++ "-" ++ versionName ++ "-" ++ shape ++ (if indexed then "-indexed" else "-plain") ++ ".parquet"
+                            BS.writeFile (directory </> name) (PHL.encodeParquetMixed options (schema repetition) [columns, columns])
+                        )
+                        [("required", P.Required, required), ("mixed", P.Optional, ordinary), ("allnull", P.Optional, nulls 80), ("empty", P.Optional, nulls 0)]
+                  )
+                  [False, True]
+            )
+            [("v1", PW.PageV1), ("v2", PW.PageV2)]
+    )
+    [("uncompressed", P.Uncompressed), ("gzip", P.GZip), ("snappy", P.Snappy), ("zstd", P.ZSTD), ("lz4", P.LZ4Raw), ("brotli", P.Brotli)]
+
+
+writeLzoProbes :: FilePath -> IO ()
+writeLzoProbes outDir = do
+  createDirectoryIfMissing True outDir
+  let many values = V.fromList (concat (replicate 20 values))
+      fields repetition =
+        V.fromList
+          [ P.SchemaElement "schema" Nothing Nothing (Just 3) Nothing Nothing Nothing Nothing
+          , P.SchemaElement "i32" (Just repetition) (Just P.PTInt32) Nothing Nothing Nothing Nothing Nothing
+          , P.SchemaElement "flag" (Just repetition) (Just P.PTBoolean) Nothing Nothing Nothing Nothing Nothing
+          , P.SchemaElement "bytes" (Just repetition) (Just P.PTByteArray) Nothing Nothing Nothing Nothing Nothing
+          ]
+      required =
+        V.fromList
+          [ PCRequired (ColInt32 (VP.fromList (concat (replicate 20 [minBound, -1, 0, 1, maxBound]))))
+          , PCRequired (ColBool (many [True, False, False, True, True]))
+          , PCRequired (ColByteArray (many ["alpha", "", BS.singleton 0, BS.singleton 255, BS.replicate 128 97]))
+          ]
+      optional =
+        V.fromList
+          [ PCOptional (OptInt32 (many [Just minBound, Nothing, Just 0, Just maxBound, Nothing]))
+          , PCOptional (OptBool (many [Just True, Nothing, Just False, Just True, Nothing]))
+          , PCOptional (OptByteArray (many [Just "alpha", Nothing, Just "", Just (BS.singleton 255), Nothing]))
+          ]
+      allNull = V.fromList [PCOptional (OptInt32 (V.replicate 100 Nothing)), PCOptional (OptBool (V.replicate 100 Nothing)), PCOptional (OptByteArray (V.replicate 100 Nothing))]
+      empty = V.fromList [PCRequired (ColInt32 VP.empty), PCRequired (ColBool V.empty), PCRequired (ColByteArray V.empty)]
+  mapM_
+    ( \(label, version) ->
+        mapM_
+          ( \(name, repetition, columns) -> do
+              let options = PHL.defaultWriteOptions {PHL.writeCompression = P.LZO, PHL.writePageVersion = version, PHL.writePageIndex = False}
+              BS.writeFile
+                (outDir </> label <> "-" <> name <> ".parquet")
+                (PHL.encodeParquetMixed options (fields repetition) [columns, columns])
+          )
+          [("required", P.Required, required), ("nullable", P.Optional, optional), ("all-null", P.Optional, allNull), ("empty", P.Required, empty)]
+    )
+    [("v1", PW.PageV1), ("v2", PW.PageV2)]
+
+
+writeLogicalMetadataProbes :: FilePath -> IO ()
+writeLogicalMetadataProbes outDir = do
+  createDirectoryIfMissing True outDir
+  let point = BS.pack [1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 248, 63, 0, 0, 0, 0, 0, 0, 4, 64]
+      cases =
+        [ ("geometry-default", P.LTGeometry P.defaultGeometryParameters)
+        , ("geometry-custom", P.LTGeometry (P.GeometryParameters (Just "EPSG:3857")))
+        , ("geography-default", P.LTGeography P.defaultGeographyParameters)
+        ]
+          ++ map
+            ( \(name, algorithm) ->
+                ( "geography-" <> name
+                , P.LTGeography (P.GeographyParameters (Just "EPSG:4326") (Just algorithm))
+                )
+            )
+            [("spherical", P.Spherical), ("vincenty", P.Vincenty), ("thomas", P.Thomas), ("andoyer", P.Andoyer), ("karney", P.Karney)]
+  mapM_
+    ( \(name, logical) -> do
+        let schema =
+              V.fromList
+                [ P.SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+                , P.SchemaElement "geometry" (Just P.Required) (Just P.PTByteArray) Nothing Nothing (Just logical) Nothing Nothing
+                ]
+        result <-
+          PHL.encodeParquetIO
+            (PHL.defaultWriteOptions {PHL.writeCompression = P.Uncompressed})
+            schema
+            [V.singleton (ColByteArray (V.singleton point))]
+        either (fail . ("logical metadata: " <>)) (BS.writeFile (outDir </> name <> ".parquet")) result
+    )
+    cases
+
+
+writeDictionaryIEEEProbes :: FilePath -> IO ()
+writeDictionaryIEEEProbes outDir = do
+  createDirectoryIfMissing True outDir
+  let bits32 = [0x3f800000, 0x7fc01234, 0xffa05678, 0x7fc01234, 0, 0x80000000, 0, 0x80000000, 0x7f800000, 0xff800000, 1, 0xffffffff]
+      bits64 = [0x3ff0000000000000, 0x7ff8123456789abc, 0xfff056789abcdef0, 0x7ff8123456789abc, 0, 0x8000000000000000, 0, 0x8000000000000000, 0x7ff0000000000000, 0xfff0000000000000, 1, 0xffffffffffffffff]
+      values32 = bits32 ++ take 129 (iterate (\value -> value * 1664525 + 1013904223) (0x12345678 :: Word32))
+      values64 = bits64 ++ take 129 (iterate (\value -> value * 6364136223846793005 + 1442695040888963407) (0x123456789abcdef0 :: Word64))
+  writeDictionaryFragments outDir "f32" (ColFloat (VP.fromList (map castWord32ToFloat (values32 ++ reverse values32))))
+  writeDictionaryFragments outDir "f64" (ColDouble (VP.fromList (map castWord64ToDouble (values64 ++ reverse values64))))
+
+
+writeDictionaryFragments :: FilePath -> FilePath -> ColumnData -> IO ()
+writeDictionaryFragments outDir name column = do
+  let dictionary = PW.buildDictionary column
+  BS.writeFile (outDir </> name ++ ".dictionary.bin") (PW.encodeDictPage dictionary)
+  BS.writeFile (outDir </> name ++ ".data.bin") (PW.encodeDictDataPage dictionary)
+
+
+writeDictionaryBytesProbes :: FilePath -> IO ()
+writeDictionaryBytesProbes outDir = do
+  createDirectoryIfMissing True outDir
+  let shortValues maximumSize = map (\size -> BS.replicate size 0) [0 .. maximumSize] ++ map (\size -> BS.pack (take size (cycle [0 .. 255]))) [0 .. maximumSize]
+      allRandomValues = take 257 (iterate (\value -> value * 6364136223846793005 + 1442695040888963407) (0x123456789abcdef0 :: Word64))
+      randomValues = take 129 allRandomValues
+      wordBytes :: Word64 -> ByteString
+      wordBytes value = BS.pack (map (\shift -> fromIntegral (value `shiftR` shift)) [0, 8 .. 56])
+      wide i value = let width = [64, 256, 4096] !! (i `rem` 3) in wordBytes value <> BS.replicate (width - 8) 97
+      sliced i bytes = let prefix = i `rem` 8 in BS.take (BS.length bytes) (BS.drop prefix (BS.replicate prefix 0xa5 <> bytes <> BS.replicate 8 0x5a))
+      write name values = writeDictionaryFragments outDir name (ColByteArray (V.fromList (zipWith sliced [0 ..] (values ++ reverse values))))
+  write "short" (shortValues 8)
+  write "tagged-short" (shortValues 7)
+  write "mixed" (shortValues 40)
+  write "sparse8" (map wordBytes randomValues)
+  write "wide" (zipWith wide [0 ..] randomValues)
+  write "common-ends" (map (\value -> BS.replicate 24 97 <> wordBytes value <> BS.replicate 32 97) randomValues)
+  let ordinary value = wordBytes value <> BS.replicate 56 97
+      ambiguous = wordBytes 0x123456789abcdef0 <> BS.replicate 16 97 <> BS.replicate 8 98 <> BS.replicate 32 97
+      secondAmbiguous = wordBytes 0x123456789abcdef0 <> BS.replicate 32 97 <> BS.replicate 8 99 <> BS.replicate 16 97
+  write "late-promotion" (map ordinary randomValues ++ [ambiguous] ++ map ordinary (drop 129 allRandomValues) ++ [secondAmbiguous])
+  let mixed cardinality =
+        map (wordBytes . fromIntegral) [0 .. cardinality - 1]
+          ++ concat
+            (zipWith (\key count -> replicate count (wordBytes (fromIntegral (key `rem` cardinality))) ++ map (wordBytes . fromIntegral) [0, 1, 0]) [0 ..] [7, 8, 9, 15, 16, 17, 23, 24, 31, 32, 33, 63, 64, 65])
+  write "rle-binary" (mixed (2 :: Int))
+  write "rle-mixed" (mixed (16 :: Int))
+  write "rle-wide" (mixed (257 :: Int))
+
+
+data DeltaProbe = DeltaProbe
+  { deltaProbeName :: !FilePath
+  , deltaProbeValues :: ![Integer]
+  }
+
+
+-- Raw encoder output lets Apache Thrift supply independent page/footer
+-- framing in parquet_delta_interop.py, isolating the encoding contract.
+writeDeltaInt32Probes :: FilePath -> IO ()
+writeDeltaInt32Probes outDir =
+  writeDeltaProbes
+    outDir
+    (toInteger (minBound :: Int32))
+    (toInteger (maxBound :: Int32))
+    randomValues
+    (Delta.encodeDeltaBinaryPackedInt32 . VP.fromList . map fromInteger)
+  where
+    randomValues = map (toInteger . (fromIntegral :: Word32 -> Int32)) (take 513 (iterate (\value -> value * 1664525 + 1013904223) (0x12345678 :: Word32)))
+
+
+writeDeltaInt64Probes :: FilePath -> IO ()
+writeDeltaInt64Probes outDir =
+  writeDeltaProbes
+    outDir
+    (toInteger (minBound :: Int64))
+    (toInteger (maxBound :: Int64))
+    randomValues
+    (Delta.encodeDeltaBinaryPackedInt64 . VP.fromList . map fromInteger)
+  where
+    randomValues = map (toInteger . (fromIntegral :: Word64 -> Int64)) (take 513 (iterate (\value -> value * 6364136223846793005 + 1442695040888963407) (0x123456789abcdef0 :: Word64)))
+
+
+writeDeltaProbes :: FilePath -> Integer -> Integer -> [Integer] -> ([Integer] -> ByteString) -> IO ()
+writeDeltaProbes outDir low high randomValues encode = do
+  createDirectoryIfMissing True outDir
+  let series name count patternValues = DeltaProbe name (take count (cycle patternValues))
+      fixed =
+        [ DeltaProbe "wrap-up" [low, high, low]
+        , DeltaProbe "wrap-down" [high, low, high]
+        , DeltaProbe "step-up" [low, high]
+        , DeltaProbe "step-down" [high, low]
+        , DeltaProbe "minimum" [low]
+        , DeltaProbe "maximum" [high]
+        , DeltaProbe "mixed-sign-delta" [0, low, low + 1]
+        , series "edges-257" 257 [low, low + 1, high, high - 1, 0, -1, 1]
+        , series "constant-129" 129 [low]
+        , DeltaProbe "random-513" randomValues
+        ]
+      alternating count = series ("alternating-" ++ show count) count [low, high]
+      bits = if high <= toInteger (maxBound :: Int32) then 32 else 64
+      packed width =
+        let mask = (1 `shiftL` width) - 1
+            count = 2 + width `rem` 31
+            offsets = take count ([0, 1 `shiftL` (width - 1), mask] ++ cycle [104729 .&. mask, 7 .&. mask])
+            wrapped value = (value - low) `mod` (high - low + 1) + low
+            rows = map wrapped (scanl (+) 0 (map (low +) offsets))
+        in DeltaProbe ("bitwidth-" ++ show width) rows
+      probes = fixed ++ map alternating [31, 32, 33, 127, 128, 129, 130] ++ map packed [1 .. bits]
+  mapM_ (\probe -> BS.writeFile (outDir </> deltaProbeName probe ++ ".bin") (encode (deltaProbeValues probe))) probes
+
+
+writeDecimalProbes :: FilePath -> IO ()
+writeDecimalProbes outDir = do
+  createDirectoryIfMissing True outDir
+  let groups =
+        [ [(1, [1]), (127, [127]), (128, [0, 128]), (255, [0, 255]), (256, [1, 0]), (1000, [3, 232])]
+        , [(-1000, [252, 24]), (-256, [255, 0]), (-129, [255, 127]), (-128, [128]), (-1, [255, 255])]
+        , [(-999999, [240, 189, 193]), (0, [0]), (999999, [15, 66, 63])]
+        ]
+          :: [[(Int64, [Word8])]]
+  mapM_
+    ( \storage ->
+        mapM_
+          ( \nullable ->
+              mapM_
+                ( \version ->
+                    mapM_
+                      ( \(codecName, codec) -> do
+                          let physical = case storage of "i32" -> P.PTInt32; "i64" -> P.PTInt64; _ -> P.PTByteArray
+                              schema =
+                                V.fromList
+                                  [ P.SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+                                  , P.SchemaElement
+                                      "x"
+                                      (Just (if nullable then P.Optional else P.Required))
+                                      (Just physical)
+                                      Nothing
+                                      (Just P.CTDecimal)
+                                      (Just (P.LTDecimal 6 2))
+                                      Nothing
+                                      Nothing
+                                  ]
+                              required values = case storage of
+                                "i32" -> PW.ColInt32 (VP.fromList (fromIntegral . fst <$> values))
+                                "i64" -> PW.ColInt64 (VP.fromList (fst <$> values))
+                                _ -> PW.ColByteArray (V.fromList (BS.pack . snd <$> values))
+                              optional values =
+                                let rows convert = V.fromList (Nothing : ((Just . convert) <$> values) ++ [Nothing])
+                                in case storage of
+                                     "i32" -> PW.OptInt32 (rows (fromIntegral . fst))
+                                     "i64" -> PW.OptInt64 (rows fst)
+                                     _ -> PW.OptByteArray (rows (BS.pack . snd))
+                              opts =
+                                PHL.defaultWriteOptions
+                                  { PHL.writeCompression = codec
+                                  , PHL.writePageVersion = version
+                                  , PHL.writeBloomFilters = ["x"]
+                                  }
+                              bytes =
+                                if nullable
+                                  then
+                                    PHL.encodeParquetMixed
+                                      opts
+                                      schema
+                                      ((\values -> V.singleton (PW.PCOptional (optional values))) <$> groups)
+                                  else PHL.encodeParquet opts schema ((V.singleton . required) <$> groups)
+                              name =
+                                storage
+                                  <> (if nullable then "-optional" else "-required")
+                                  <> (if version == PW.PageV1 then "-v1-" else "-v2-")
+                                  <> codecName
+                                  <> ".parquet"
+                          BS.writeFile (outDir </> name) bytes
+                      )
+                      [("uncompressed", P.Uncompressed), ("gzip", P.GZip)]
+                )
+                [PW.PageV1, PW.PageV2]
+          )
+          [False, True]
+    )
+    ["i32", "i64", "bytes"]
+
+
+writeOptionsProbes :: FilePath -> IO ()
+writeOptionsProbes outDir = do
+  createDirectoryIfMissing True outDir
+  mapM_
+    ( \nullable ->
+        mapM_
+          ( \version ->
+              mapM_
+                ( \(codecName, codec) ->
+                    mapM_
+                      ( \indexed -> do
+                          let schema =
+                                V.fromList
+                                  [ P.SchemaElement "schema" Nothing Nothing (Just 2) Nothing Nothing Nothing Nothing
+                                  , P.SchemaElement "r" (Just P.Required) (Just P.PTInt32) Nothing Nothing Nothing Nothing Nothing
+                                  , P.SchemaElement "o" (Just (if nullable then P.Optional else P.Required)) (Just P.PTInt64) Nothing Nothing Nothing Nothing Nothing
+                                  ]
+                              required = PW.ColInt32 (VP.fromList [1, 2, 3])
+                              values = PW.ColInt64 (VP.fromList [10, 20, 30])
+                              mixed =
+                                V.fromList
+                                  [ PW.PCRequired required
+                                  , PW.PCOptional (PW.OptInt64 (V.fromList [Just 10, Nothing, Just 30]))
+                                  ]
+                              opts =
+                                PHL.defaultWriteOptions
+                                  { PHL.writeCompression = codec
+                                  , PHL.writePageVersion = version
+                                  , PHL.writePageIndex = indexed
+                                  , PHL.writeBloomFilters = ["o"]
+                                  }
+                              bytes =
+                                if nullable
+                                  then PHL.encodeParquetMixed opts schema [mixed, mixed]
+                                  else PHL.encodeParquet opts schema (replicate 2 (V.fromList [required, values]))
+                              name =
+                                (if nullable then "mixed" else "required")
+                                  <> "-"
+                                  <> (if version == PW.PageV1 then "v1" else "v2")
+                                  <> "-"
+                                  <> codecName
+                                  <> (if indexed then "-index.parquet" else "-noindex.parquet")
+                          BS.writeFile (outDir </> name) bytes
+                      )
+                      [False, True]
+                )
+                [("uncompressed", P.Uncompressed), ("gzip", P.GZip), ("snappy", P.Snappy), ("zstd", P.ZSTD)]
+          )
+          [PW.PageV1, PW.PageV2]
+    )
+    [False, True]
+
+
+writeStatisticsProbes :: FilePath -> IO ()
+writeStatisticsProbes outDir =
+  mapM_
+    ( \precision ->
+        mapM_
+          ( \(name, values) -> do
+              let physical = if precision == "float" then P.PTFloat else P.PTDouble
+                  column =
+                    if precision == "float"
+                      then ColFloat (VP.fromList (realToFrac <$> values))
+                      else ColDouble (VP.fromList values)
+                  schema =
+                    V.fromList
+                      [ P.SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+                      , P.SchemaElement "x" (Just P.Required) (Just physical) Nothing Nothing Nothing Nothing Nothing
+                      ]
+                  bytes = PHL.encodeParquet PHL.defaultWriteOptions schema [V.singleton column]
+              BS.writeFile (outDir </> precision <> "-" <> name <> ".parquet") bytes
+          )
+          [ ("mixed", [0 / 0, -2, 3, 0 / 0])
+          , ("nan", [0 / 0, 0 / 0])
+          , ("positive-zero", [0])
+          , ("negative-zero", [-0.0])
+          , ("infinities", [negate (1 / 0), 1 / 0, 0 / 0])
+          , ("empty", [])
+          ]
+    )
+    ["float", "double"]
+    >> BS.writeFile
+      (outDir </> "statistics-index.bin")
+      ( PageIndex.encodeColumnIndex
+          P.ColumnIndex
+            { P.ciNullPages = V.fromList [False, False, True]
+            , P.ciMinValues = V.fromList [BS.pack [0, 0, 0, 0x80], BS.pack [0, 0, 0, 0xc0], BS.empty]
+            , P.ciMaxValues = V.fromList [BS.replicate 4 0, BS.pack [0, 0, 0x40, 0x40], BS.empty]
+            , P.ciBoundaryOrder = P.OrderUnordered
+            , P.ciNullCounts = Just (V.fromList [0, 0, 4])
+            , P.ciNanCounts = Just (V.fromList [1, 0, 0])
+            , P.ciRepetitionLevelHistograms = Nothing
+            , P.ciDefinitionLevelHistograms = Nothing
+            }
+      )
+    >> writeReq
+      outDir
+      "binary-boundaries.parquet"
+      ( [rootElem 1, leafElem P.PTByteArray Nothing "x"]
+      , V.singleton (ColByteArray (V.fromList [BS.pack [0x80], BS.pack [0x7f], BS.empty, BS.pack [0xff]]))
+      )
+    >> writeReq
+      outDir
+      "utf8-boundaries.parquet"
+      ( [rootElem 1, leafElem P.PTByteArray (Just P.CTUtf8) "x"]
+      , V.singleton (ColByteArray (TE.encodeUtf8 <$> V.fromList ["é", "z", "", "🙂"]))
+      )
+    >> writeStatisticsTraversalProbes outDir
+
+
+writeStatisticsTraversalProbes :: FilePath -> IO ()
+writeStatisticsTraversalProbes outDir = do
+  let write name physical column =
+        writeReq outDir name ([rootElem 1, leafElem physical Nothing "x"], V.singleton column)
+  mapM_
+    (\(name, values) -> write ("int32-" <> name <> ".parquet") P.PTInt32 (ColInt32 (VP.fromList values)))
+    [ ("empty", [])
+    , ("bounds", [maxBound, minBound, 0, -1, 1, maxBound])
+    , ("descending", [19, 7, 0, -5, -23])
+    ]
+  mapM_
+    (\(name, values) -> write ("int64-" <> name <> ".parquet") P.PTInt64 (ColInt64 (VP.fromList values)))
+    [ ("empty", [])
+    , ("bounds", [maxBound, minBound, 0, -1, 1, (1 `shiftL` 54) + 1, maxBound])
+    , ("descending", [19, 7, 0, -5, -23])
+    ]
+  let initial = take 40 (cycle ["name_0", "name_7", "name_19"])
+      short = [BS.empty, BS.pack [0], BS.pack [0, 0], BS.pack [1], BS.pack [1, 0], BS.pack [255], BS.pack [255, 0], "abcdefgh"]
+      sliced ordinal bytes = BS.take (BS.length bytes) (BS.drop 5 (BS.replicate 5 ordinal <> bytes <> BS.singleton ordinal))
+  mapM_
+    (\(name, values) -> write ("binary-" <> name <> ".parquet") P.PTByteArray (ColByteArray (V.fromList values)))
+    [ ("empty", [])
+    , ("short-prefix", short)
+    , ("zero-prefix", map (`BS.replicate` 0) [0 .. 16])
+    , ("late-min", initial ++ [BS.replicate 9 0, "m", "z"])
+    , ("late-max", initial ++ [BS.replicate 9 255, "a", "m"])
+    , ("long-first", map (\key -> BS.replicate 32 97 <> BS.singleton key) [255, 0, 128, 1, 127])
+    , ("short-slice", zipWith sliced [0 ..] short)
+    ]
+
+
+-- Deliberately public test key: no production credentials or KMS are used.
+-- Two row groups and one plaintext column exercise ordinals and selective
+-- encryption independently of our own encrypted-reader implementation.
+writeEncryptedProbes :: Int -> FilePath -> ByteString -> IO ()
+writeEncryptedProbes keyBytes outDir metadata =
+  mapM_
+    ( \algorithm ->
+        mapM_
+          ( \version ->
+              mapM_
+                ( \encrypted -> do
+                    fileId <- RNG.getRandomBytes 8
+                    let key = BS.replicate keyBytes 0x42
+                        footer = PW.FooterEncryption key fileId BS.empty metadata
+                        column = PW.ColumnEncryption algorithm key fileId BS.empty BS.empty 0
+                        schema =
+                          V.fromList
+                            [ P.SchemaElement "schema" Nothing Nothing (Just 2) Nothing Nothing Nothing Nothing
+                            , P.SchemaElement "x" (Just P.Required) (Just P.PTInt32) Nothing Nothing Nothing Nothing Nothing
+                            , P.SchemaElement "y" (Just P.Required) (Just P.PTByteArray) Nothing (Just P.CTUtf8) (Just P.LTString) Nothing Nothing
+                            ]
+                        groups =
+                          [ V.fromList [ColInt32 (VP.fromList [1, 2, 3]), ColByteArray (V.fromList ["a", "b", "c"])]
+                          , V.fromList [ColInt32 (VP.fromList [4, 5]), ColByteArray (V.fromList ["d", "e"])]
+                          ]
+                        opts =
+                          PHL.defaultWriteOptions
+                            { PHL.writeCompression = P.Snappy
+                            , PHL.writePageVersion = version
+                            , PHL.writeFooterEncryption = Just footer
+                            , PHL.writeColumnEncryption = V.fromList [if encrypted then Just column else Nothing, Nothing]
+                            , PHL.writeBloomFilters = ["x"]
+                            }
+                        filename = show algorithm <> "-" <> show version <> (if encrypted then "-column" else "-footer") <> ".parquet"
+                    result <- PHL.encodeParquetIO opts schema groups
+                    bytes <- either (ioError . userError) pure result
+                    BS.writeFile (outDir </> filename) bytes
+                )
+                [False, True]
+          )
+          [PW.PageV1, PW.PageV2]
+    )
+    [Enc.AesGcmV1, Enc.AesGcmCtrV1]
+
+
+-- ============================================================
+-- Probe catalogue
+-- ============================================================
+
+writeAllProbes :: FilePath -> IO ()
+writeAllProbes outDir = do
+  -- Required-only columns through encodeParquet (PageV1).
+  writeReq outDir "int32_required.parquet" reqInt32
+  writeReq outDir "int64_required.parquet" reqInt64
+  writeReq outDir "float_required.parquet" reqFloat
+  writeReq outDir "double_required.parquet" reqDouble
+  writeReq outDir "bool_required.parquet" reqBool
+  writeReq outDir "byte_array_required.parquet" reqByteArray
+  writeReq outDir "utf8_required.parquet" reqUtf8
+
+  -- Logical-type-annotated primitives. The physical type is
+  -- the underlying integer / binary; the ConvertedType
+  -- annotation tells the reader to surface it as a
+  -- date / time / decimal / etc. Every modern engine has to
+  -- reconstruct these annotations correctly from our footer.
+  writeReq outDir "date32_required.parquet" reqDate32
+  writeReq outDir "time_millis_required.parquet" reqTimeMillis
+  writeReq outDir "timestamp_millis_required.parquet" reqTimestampMillis
+  writeReq outDir "uint32_required.parquet" reqUInt32
+  writeReq outDir "json_required.parquet" reqJson
+
+  -- Compressed required-only.
+  writeReqCompressed outDir "int64_zstd.parquet" P.ZSTD reqInt64
+  writeReqCompressed outDir "int64_snappy.parquet" P.Snappy reqInt64
+  writeReqCompressed outDir "int64_gzip.parquet" P.GZip reqInt64
+  writeReqCompressed outDir "int64_lz4_raw.parquet" P.LZ4Raw reqInt64
+
+  -- Mixed required + optional through encodeParquetMixed.
+  writeMixed outDir "mixed_optional.parquet" mixedSchema mixedRow
+
+  -- All-nullable optional columns covering each OptionalColumn
+  -- variant, exercising definition-level streams for every
+  -- physical type.
+  writeMixed outDir "optional_int32.parquet" optInt32Schema optInt32Row
+  writeMixed outDir "optional_int64.parquet" optInt64Schema optInt64Row
+  writeMixed outDir "optional_float.parquet" optFloatSchema optFloatRow
+  writeMixed outDir "optional_bool.parquet" optBoolSchema optBoolRow
+
+  -- Multi-row-group: same column twice in two row groups.
+  writeReqMultiRG outDir "int64_two_row_groups.parquet" reqInt64Twice
+  writeTemporalProbes outDir
+
+
+writeTemporalProbes :: FilePath -> IO ()
+writeTemporalProbes outDir =
+  mapM_
+    ( \version ->
+        mapM_
+          ( \nullable -> do
+              let field name typ = AT.Field name nullable typ V.empty Nothing V.empty
+                  schema =
+                    AT.Schema
+                      ( V.fromList
+                          [ field "date" (AT.ADate AT.DateMillisecond)
+                          , field "time" (AT.ATime AT.Second 32)
+                          , field "stamp" (AT.ATimestamp AT.Second Nothing)
+                          ]
+                      )
+                      AT.Little
+                      V.empty
+                      V.empty
+                  column tag values =
+                    if nullable
+                      then AC.fromMaybes tag (V.imap (\i value -> if i == 1 then Nothing else Just value) (V.fromList values))
+                      else AC.primColumn tag (VS.fromList values)
+                  batch =
+                    V.fromList
+                      [ column AC.PDate64 [-86400000, 0, 86400000]
+                      , column AC.PTime32 [0, 1, 86399]
+                      , column AC.PTimestamp [-1, 0, 1700000000]
+                      ]
+                  opts = PHL.defaultWriteOptions {PHL.writePageVersion = version}
+                  name =
+                    "arrow_temporal_"
+                      <> (if nullable then "optional_" else "required_")
+                      <> (if version == PW.PageV1 then "v1" else "v2")
+                      <> ".parquet"
+                  encoded =
+                    if nullable
+                      then do
+                        (parquetSchema, groups) <- PHL.arrowToParquetMixed schema [batch]
+                        Right (PHL.encodeParquetMixed opts parquetSchema groups)
+                      else do
+                        (parquetSchema, groups) <- PHL.arrowToParquet schema [batch]
+                        Right (PHL.encodeParquet opts parquetSchema groups)
+              case encoded of
+                Left err -> fail err
+                Right bytes -> BS.writeFile (outDir </> name) bytes
+          )
+          [False, True]
+    )
+    [PW.PageV1, PW.PageV2]
+
+
+writeReq
+  :: FilePath
+  -> FilePath
+  -> ([P.SchemaElement], V.Vector ColumnData)
+  -> IO ()
+writeReq outDir fname (schema, cols) = do
+  let !bs =
+        PHL.encodeParquet
+          PHL.defaultWriteOptions
+          (V.fromList schema)
+          [cols]
+  BS.writeFile (outDir </> fname) bs
+
+
+writeReqMultiRG
+  :: FilePath
+  -> FilePath
+  -> ([P.SchemaElement], [V.Vector ColumnData])
+  -> IO ()
+writeReqMultiRG outDir fname (schema, rgs) = do
+  let !bs =
+        PHL.encodeParquet
+          PHL.defaultWriteOptions
+          (V.fromList schema)
+          rgs
+  BS.writeFile (outDir </> fname) bs
+
+
+writeReqCompressed
+  :: FilePath
+  -> FilePath
+  -> P.Compression
+  -> ([P.SchemaElement], V.Vector ColumnData)
+  -> IO ()
+writeReqCompressed outDir fname codec (schema, cols) = do
+  let !bs =
+        PHL.encodeParquet
+          PHL.defaultWriteOptions {PHL.writeCompression = codec}
+          (V.fromList schema)
+          [cols]
+  BS.writeFile (outDir </> fname) bs
+
+
+writeMixed
+  :: FilePath
+  -> FilePath
+  -> [P.SchemaElement]
+  -> V.Vector ParquetColumn
+  -> IO ()
+writeMixed outDir fname schema cols = do
+  let !bs =
+        PHL.encodeParquetMixed
+          PHL.defaultWriteOptions
+          (V.fromList schema)
+          [cols]
+  BS.writeFile (outDir </> fname) bs
+
+
+-- ============================================================
+-- Schemas + payloads
+-- ============================================================
+
+rootElem :: Int32 -> P.SchemaElement
+rootElem n =
+  P.SchemaElement
+    "schema"
+    Nothing
+    Nothing
+    (Just n)
+    Nothing
+    Nothing
+    Nothing
+    Nothing
+
+
+leafElem :: P.ParquetType -> Maybe P.ConvertedType -> Text -> P.SchemaElement
+leafElem ty conv name =
+  P.SchemaElement name (Just P.Required) (Just ty) Nothing conv Nothing Nothing Nothing
+
+
+reqInt32 :: ([P.SchemaElement], V.Vector ColumnData)
+reqInt32 =
+  ( [rootElem 1, leafElem P.PTInt32 Nothing "x"]
+  , V.singleton (ColInt32 (VP.fromList [1, 2, 3, 4, 5 :: Int32]))
+  )
+
+
+reqInt64 :: ([P.SchemaElement], V.Vector ColumnData)
+reqInt64 =
+  ( [rootElem 1, leafElem P.PTInt64 Nothing "x"]
+  , V.singleton (ColInt64 (VP.fromList [10, 20, 30, 40, 50 :: Int64]))
+  )
+
+
+reqInt64Twice :: ([P.SchemaElement], [V.Vector ColumnData])
+reqInt64Twice =
+  ( [rootElem 1, leafElem P.PTInt64 Nothing "x"]
+  ,
+    [ V.singleton (ColInt64 (VP.fromList [1, 2, 3 :: Int64]))
+    , V.singleton (ColInt64 (VP.fromList [4, 5, 6 :: Int64]))
+    ]
+  )
+
+
+reqFloat :: ([P.SchemaElement], V.Vector ColumnData)
+reqFloat =
+  ( [rootElem 1, leafElem P.PTFloat Nothing "x"]
+  , V.singleton (ColFloat (VP.fromList [1.5, 2.5, 3.5 :: Float]))
+  )
+
+
+reqDouble :: ([P.SchemaElement], V.Vector ColumnData)
+reqDouble =
+  ( [rootElem 1, leafElem P.PTDouble Nothing "x"]
+  , V.singleton (ColDouble (VP.fromList [1.5, -2.5, 3.14159 :: Double]))
+  )
+
+
+reqBool :: ([P.SchemaElement], V.Vector ColumnData)
+reqBool =
+  ( [rootElem 1, leafElem P.PTBoolean Nothing "x"]
+  , V.singleton (ColBool (V.fromList [True, False, True, True, False]))
+  )
+
+
+reqByteArray :: ([P.SchemaElement], V.Vector ColumnData)
+reqByteArray =
+  ( [rootElem 1, leafElem P.PTByteArray Nothing "x"]
+  , V.singleton
+      (ColByteArray (V.fromList ["alpha", "beta", "gamma" :: ByteString]))
+  )
+
+
+reqUtf8 :: ([P.SchemaElement], V.Vector ColumnData)
+reqUtf8 =
+  -- Use Text -> UTF-8 explicitly. ByteString's IsString
+  -- truncates each Char to 8 bits which silently mangles
+  -- non-ASCII string literals; downstream Parquet readers
+  -- (pyarrow / duckdb / polars) then refuse the file because
+  -- the bytes aren't valid UTF-8.
+  ( [rootElem 1, leafElem P.PTByteArray (Just P.CTUtf8) "name"]
+  , V.singleton
+      ( ColByteArray
+          ( V.fromList
+              [ TE.encodeUtf8 "Alice"
+              , TE.encodeUtf8 "Bob"
+              , TE.encodeUtf8 "Carol"
+              , TE.encodeUtf8 "Δοε" -- Greek "doe"
+              ]
+          )
+      )
+  )
+
+
+-- Mixed required + optional in one row group.
+mixedSchema :: [P.SchemaElement]
+mixedSchema =
+  [ rootElem 3
+  , P.SchemaElement "id" (Just P.Required) (Just P.PTInt64) Nothing Nothing Nothing Nothing Nothing
+  , P.SchemaElement "name" (Just P.Optional) (Just P.PTByteArray) Nothing (Just P.CTUtf8) Nothing Nothing Nothing
+  , P.SchemaElement "score" (Just P.Optional) (Just P.PTDouble) Nothing Nothing Nothing Nothing Nothing
+  ]
+
+
+mixedRow :: V.Vector ParquetColumn
+mixedRow =
+  V.fromList
+    [ PCRequired (ColInt64 (VP.fromList [10, 20, 30 :: Int64]))
+    , PCOptional
+        ( OptByteArray
+            ( V.fromList
+                [Just "alice", Nothing, Just "carol" :: Maybe ByteString]
+            )
+        )
+    , PCOptional
+        ( OptDouble
+            ( V.fromList
+                [Just 1.5, Just 2.5, Nothing :: Maybe Double]
+            )
+        )
+    ]
+
+
+-- ============================================================
+-- Logical-type variants (Int32 / Int64 / ByteArray with
+-- ConvertedType annotations). Every modern Parquet reader
+-- has to honour the annotation and surface the column as a
+-- date / time / decimal / unsigned int / json string.
+-- ============================================================
+
+reqDate32 :: ([P.SchemaElement], V.Vector ColumnData)
+reqDate32 =
+  ( [rootElem 1, leafElem P.PTInt32 (Just P.CTDate) "d"]
+  , -- Days since 1970-01-01. 18000 days ~ 2019-04-13.
+    V.singleton (ColInt32 (VP.fromList [0, 18000, 19000 :: Int32]))
+  )
+
+
+reqTimeMillis :: ([P.SchemaElement], V.Vector ColumnData)
+reqTimeMillis =
+  ( [rootElem 1, leafElem P.PTInt32 (Just P.CTTimeMillis) "t"]
+  , V.singleton
+      (ColInt32 (VP.fromList [0, 12345, 86400000 - 1 :: Int32]))
+  )
+
+
+reqTimestampMillis :: ([P.SchemaElement], V.Vector ColumnData)
+reqTimestampMillis =
+  ( [rootElem 1, leafElem P.PTInt64 (Just P.CTTimestampMillis) "ts"]
+  , V.singleton
+      (ColInt64 (VP.fromList [0, 1700000000000 :: Int64]))
+  )
+
+
+reqUInt32 :: ([P.SchemaElement], V.Vector ColumnData)
+reqUInt32 =
+  ( [rootElem 1, leafElem P.PTInt32 (Just P.CTUInt32) "u"]
+  , -- Stored as Int32 with an unsigned reinterpretation;
+    -- maxBound :: Int32 = 2_147_483_647, fromIntegral
+    -- (maxBound :: Word32) wraps to -1.
+    V.singleton
+      ( ColInt32
+          ( VP.fromList
+              [ 0
+              , 1
+              , maxBound :: Int32 -- = 2_147_483_647 unsigned
+              , -1 :: Int32 -- = 4_294_967_295 unsigned
+              ]
+          )
+      )
+  )
+
+
+reqJson :: ([P.SchemaElement], V.Vector ColumnData)
+reqJson =
+  ( [rootElem 1, leafElem P.PTByteArray (Just P.CTJson) "doc"]
+  , V.singleton
+      ( ColByteArray
+          ( V.fromList
+              [ TE.encodeUtf8 "{\"k\":1}"
+              , TE.encodeUtf8 "{\"k\":2,\"j\":\"hi\"}"
+              ]
+          )
+      )
+  )
+
+
+-- ============================================================
+-- Optional-column-only schemas (one column each).
+-- ============================================================
+
+optColSchema :: P.ParquetType -> Maybe P.ConvertedType -> Text -> [P.SchemaElement]
+optColSchema ty conv name =
+  [ rootElem 1
+  , P.SchemaElement name (Just P.Optional) (Just ty) Nothing conv Nothing Nothing Nothing
+  ]
+
+
+optInt32Schema, optInt64Schema, optFloatSchema, optBoolSchema :: [P.SchemaElement]
+optInt32Schema = optColSchema P.PTInt32 Nothing "x"
+optInt64Schema = optColSchema P.PTInt64 Nothing "x"
+optFloatSchema = optColSchema P.PTFloat Nothing "x"
+optBoolSchema = optColSchema P.PTBoolean Nothing "x"
+
+
+optInt32Row, optInt64Row, optFloatRow, optBoolRow :: V.Vector ParquetColumn
+optInt32Row =
+  V.singleton $
+    PCOptional $
+      OptInt32
+        ( V.fromList
+            [Just 1, Nothing, Just 3, Just (-1)]
+        )
+optInt64Row =
+  V.singleton $
+    PCOptional $
+      OptInt64
+        ( V.fromList
+            [Just 100, Nothing, Just 300]
+        )
+optFloatRow =
+  V.singleton $
+    PCOptional $
+      OptFloat
+        ( V.fromList
+            [Just 1.5, Just 2.5, Nothing, Just 4.5]
+        )
+optBoolRow =
+  V.singleton $
+    PCOptional $
+      OptBool
+        ( V.fromList
+            [Just True, Nothing, Just False, Just True, Nothing]
+        )
+
+
+data NestedProbeCase = NestedProbeCase
+  { nestedProbeName :: !String
+  , nestedProbeType :: !AT.ArrowType
+  , nestedProbeColumn :: !AC.ColumnArray
+  }
+
+
+writeNestedTypeProbes :: FilePath -> IO ()
+writeNestedTypeProbes outDir = do
+  createDirectoryIfMissing True outDir
+  let scalar name typ = AT.Field name False typ V.empty Nothing V.empty
+      sample = NestedProbeCase
+      cases =
+        [ sample "i8" (AT.AInt 8 True) (AC.primColumn AC.PInt8 (VS.fromList [-128, -1, 0, 127]))
+        , sample "i16" (AT.AInt 16 True) (AC.primColumn AC.PInt16 (VS.fromList [-32768, -1, 0, 32767]))
+        , sample "i32" (AT.AInt 32 True) (AC.primColumn AC.PInt32 (VS.fromList [minBound, -1, 0, maxBound]))
+        , sample "i64" (AT.AInt 64 True) (AC.primColumn AC.PInt64 (VS.fromList [minBound, -1, 0, maxBound]))
+        , sample "u8" (AT.AInt 8 False) (AC.primColumn AC.PUInt8 (VS.fromList [0, 127, 128, 255]))
+        , sample "u16" (AT.AInt 16 False) (AC.primColumn AC.PUInt16 (VS.fromList [0, 32767, 32768, 65535]))
+        , sample "u32" (AT.AInt 32 False) (AC.primColumn AC.PUInt32 (VS.fromList [0, 2147483647, 2147483648, maxBound]))
+        , sample "u64" (AT.AInt 64 False) (AC.primColumn AC.PUInt64 (VS.fromList [0, 9223372036854775807, 9223372036854775808, maxBound]))
+        , sample "date32" (AT.ADate AT.DateDay) (AC.primColumn AC.PDate32 (VS.fromList [-1, 0, 1, 20000]))
+        , sample "date64" (AT.ADate AT.DateMillisecond) (AC.primColumn AC.PDate64 (VS.fromList [-86400000, 0, 86400000, 172800000]))
+        , sample "time_s" (AT.ATime AT.Second 32) (AC.primColumn AC.PTime32 (VS.fromList [0, 1, 43200, 86399]))
+        , sample "time_ms" (AT.ATime AT.Millisecond 32) (AC.primColumn AC.PTime32 (VS.fromList [0, 1, 43200000, 86399999]))
+        , sample "time_us" (AT.ATime AT.Microsecond 64) (AC.primColumn AC.PTime64 (VS.fromList [0, 1, 43200000000, 86399999999]))
+        , sample "time_ns" (AT.ATime AT.Nanosecond 64) (AC.primColumn AC.PTime64 (VS.fromList [0, 1, 43200000000000, 86399999999999]))
+        , sample "bool" AT.ABool (AC.fromBools (V.fromList [True, False, True, True]))
+        ]
+          ++ concatMap
+            ( \(zoneName, zone) ->
+                map
+                  ( \(unitName, unit) ->
+                      sample
+                        ("timestamp_" ++ unitName ++ "_" ++ zoneName)
+                        (AT.ATimestamp unit zone)
+                        (AC.primColumn AC.PTimestamp (VS.fromList [-1, 0, 1, 1700000000]))
+                  )
+                  [("s", AT.Second), ("ms", AT.Millisecond), ("us", AT.Microsecond), ("ns", AT.Nanosecond)]
+            )
+            [("local", Nothing), ("utc", Just "UTC")]
+      emit name field column = do
+        schema <- either fail pure (PHL.arrowFieldToNestedSchema field)
+        rows <- either fail pure (PHL.columnArrayToNestedRows field column)
+        bytes <- either fail pure (PHL.encodeParquetNested (V.singleton ("v", schema)) (V.singleton rows))
+        BS.writeFile (outDir </> name ++ ".parquet") bytes
+  mapM_
+    ( \entry -> do
+        let name = nestedProbeName entry
+            typ = nestedProbeType entry
+            column = nestedProbeColumn entry
+            valueField = scalar "v" typ
+        emit (name ++ "_scalar") valueField column
+        let parentMask = AC.validityFromBools (V.fromList [True, False, True, True])
+            parentField = AT.Field "v" True AT.AStruct (V.singleton valueField) Nothing V.empty
+        parent <- either fail pure (AC.mkStruct 4 parentMask (V.singleton ("v", column)))
+        emit (name ++ "_struct") parentField parent
+        let element = scalar "element" typ
+            listField = AT.Field "v" False AT.AList (V.singleton element) Nothing V.empty
+        list <- either fail pure (AC.mkList Nothing (VS.fromList [1, 3, 3, 4]) column)
+        emit (name ++ "_list") listField list
+        let key = scalar "key" (AT.AInt 32 False)
+            value = scalar "value" typ
+            mapField =
+              AT.Field
+                "v"
+                False
+                (AT.AMap False)
+                (V.singleton (AT.Field "entries" False AT.AStruct (V.fromList [key, value]) Nothing V.empty))
+                Nothing
+                V.empty
+            keys = AC.primColumn AC.PUInt32 (VS.fromList [1, 2, 3, 4])
+        mapColumn <- either fail pure (AC.mkMap Nothing (VS.fromList [1, 3, 3, 4]) keys column)
+        emit (name ++ "_map") mapField mapColumn
+    )
+    cases
+  mapM_
+    ( \count -> do
+        let values = V.generate count (\i -> if i `rem` 4 == 0 then Nothing else Just (i `rem` 3 == 0))
+        emit ("bool_tail_" ++ show count) ((scalar "v" AT.ABool) {AT.fieldNullable = True}) (AC.fromMaybeBools values)
+    )
+    [0 .. 65]
+  let parentMask = AC.validityFromBools (V.fromList [True, False, True])
+      dateField = scalar "date" (AT.ADate AT.DateMillisecond)
+      parentField = AT.Field "v" True AT.AStruct (V.singleton dateField) Nothing V.empty
+  dates <- either fail pure (AC.mkPrim AC.PDate64 parentMask (VS.fromList [-86400000, 1, 86400000]))
+  parent <- either fail pure (AC.mkStruct 3 parentMask (V.singleton ("date", dates)))
+  emit "poison_struct" parentField parent
+  let timeField = scalar "element" (AT.ATime AT.Second 32)
+      listField = AT.Field "v" False AT.AList (V.singleton timeField) Nothing V.empty
+  times <- either fail pure (AC.mkList Nothing (VS.fromList [1, 3]) (AC.primColumn AC.PTime32 (VS.fromList [maxBound, 0, 1, minBound])))
+  emit "poison_list" listField times
+  let keys = AC.primColumn AC.PInt32 (VS.fromList [1, 2])
+      keyField = scalar "key" (AT.AInt 32 True)
+      valueField = scalar "value" (AT.ADate AT.DateMillisecond)
+      mapField =
+        AT.Field
+          "v"
+          True
+          (AT.AMap False)
+          (V.singleton (AT.Field "entries" False AT.AStruct (V.fromList [keyField, valueField]) Nothing V.empty))
+          Nothing
+          V.empty
+      mapMask = AC.validityFromBools (V.fromList [False, True])
+  hiddenKeys <- either fail pure (AC.maskValidity mapMask keys)
+  hiddenMap <- either fail pure (AC.mkMap mapMask (VS.fromList [0, 1, 2]) hiddenKeys (AC.primColumn AC.PDate64 (VS.fromList [1, 86400000])))
+  emit "poison_map" mapField hiddenMap
+  let optionalMapField =
+        AT.Field
+          "v"
+          False
+          (AT.AMap False)
+          ( V.singleton
+              ( AT.Field
+                  "entries"
+                  False
+                  AT.AStruct
+                  (V.fromList [scalar "key" (AT.AInt 32 False), (scalar "value" (AT.AInt 64 False)) {AT.fieldNullable = True}])
+                  Nothing
+                  V.empty
+              )
+          )
+          Nothing
+          V.empty
+  optionalValues <- either fail pure (AC.mkPrim AC.PUInt64 (AC.validityFromBools (V.fromList [True, False, True])) (VS.fromList [maxBound, 0, 9223372036854775808]))
+  optionalMap <- either fail pure (AC.mkMap Nothing (VS.fromList [0, 2, 2, 3]) (AC.primColumn AC.PUInt32 (VS.fromList [1, 2, 3])) optionalValues)
+  emit "map_optional_values" optionalMapField optionalMap
+  let nestedListSchema = PN.NSOptional (PN.NSList (PN.NSOptional (PN.NSList (PN.NSOptional (PN.NSPrimitive PN.LtInt32)))))
+      int = PN.NRLeaf . PN.LvInt32
+      list = PN.NRList . V.fromList
+      nestedListRows =
+        V.fromList
+          [ list [list [int 1, PN.NRNull], PN.NRNull, list [], list [int 2]]
+          , PN.NRNull
+          , list []
+          , list [list [], list [PN.NRNull]]
+          ]
+  nestedListBytes <- either fail pure (PHL.encodeParquetNested (V.singleton ("v", nestedListSchema)) (V.singleton nestedListRows))
+  BS.writeFile (outDir </> "list_of_lists.parquet") nestedListBytes
+  mapM_
+    ( \entry -> do
+        let name = nestedProbeName entry
+            typ = nestedProbeType entry
+        primitive <- either fail pure (PHL.arrowFieldToNestedSchema (scalar "element" typ))
+        core <- case primitive of
+          PN.NSRequired child -> pure child
+          _ -> fail "legacy probe needs a required primitive field"
+        values <- either fail pure (PHL.columnArrayToNestedRows (scalar "element" typ) (nestedProbeColumn entry))
+        let schema = PN.NSOptional (PN.NSList (PN.NSOptional core))
+            rows =
+              V.fromList
+                [ PN.NRList (V.fromList [values V.! 0, PN.NRNull, values V.! 1])
+                , PN.NRNull
+                , PN.NRList V.empty
+                , PN.NRList (V.fromList [values V.! 2, values V.! 3])
+                ]
+        leaves <- either fail pure (PN.shred schema rows)
+        let physicalSchema = V.last (PN.nestedSchemaToFlatSchema (V.singleton ("v", primitive)))
+        physical <- maybe (fail "legacy probe needs a physical type") pure (P.seType physicalSchema)
+        let leaf = (V.head leaves) {PN.nlPath = V.fromList ["v", "list", "element"]}
+        bytes <- either fail pure (PN.buildOptionalListFileEither physical leaf 4)
+        BS.writeFile (outDir </> name ++ ".parquet") bytes
+    )
+    [ sample "legacy_i32" (AT.AInt 32 True) (AC.primColumn AC.PInt32 (VS.fromList [minBound, -1, 0, maxBound]))
+    , sample "legacy_i64" (AT.AInt 64 True) (AC.primColumn AC.PInt64 (VS.fromList [minBound, -1, 0, maxBound]))
+    , sample "legacy_double" (AT.AFloatingPoint AT.DoublePrecision) (AC.primColumn AC.PDouble (VS.fromList [-1.5, 0, 1.5, 1e100]))
+    , sample "legacy_bool" AT.ABool (AC.fromBools (V.fromList [True, False, True, True]))
+    , sample "legacy_binary" AT.ABinary (AC.fromByteStrings (V.fromList ["", "abc", BS.pack [0, 255], "tail"]))
+    ]
+
+
+-- FILE logical groups: subset schemas, reordered names/IDs, nulls, and nesting.
+writeFileProbes :: FilePath -> IO ()
+writeFileProbes outDir = do
+  createDirectoryIfMissing True outDir
+  let empty = File.emptyFileReference
+      inline = empty {File.fileInline = Just ""}
+      uri = empty {File.fileUri = Just "../images/a%20b.png?raw=1#part"}
+      both = uri {File.fileOffset = Just 0, File.fileSize = Just (fromIntegral (BS.length "whole inline payload")), File.fileInline = Just "whole inline payload"}
+      maximum = uri {File.fileOffset = Just maxBound, File.fileSize = Just maxBound}
+      fullRows = V.fromList [PN.NRNull, PN.NRFile inline, PN.NRFile uri, PN.NRFile both, PN.NRFile maximum, PN.NRFile inline {File.fileUri = Just "", File.fileContentType = Just "", File.fileChecksum = Just ""}]
+      emit name fields rows = do
+        schema <- either fail pure (File.mkFileSchema (V.fromList fields))
+        bytes <- either fail pure (PN.buildNestedFile (V.singleton ("f", PN.NSOptional (PN.NSFile schema))) (V.singleton rows))
+        BS.writeFile (outDir </> name <> ".parquet") bytes
+      specs = map (\field -> File.FileFieldSpec field (Just (fromIntegral (fromEnum field + 10)))) [minBound .. maxBound]
+  emit "full" specs fullRows
+  emit "reordered" (reverse specs) fullRows
+  emit "inline" [File.FileFieldSpec File.FileInline Nothing] (V.fromList [PN.NRNull, PN.NRFile inline, PN.NRFile inline {File.fileInline = Just "bytes"}])
+  emit "uri" [File.FileFieldSpec File.FileUri Nothing] (V.fromList [PN.NRNull, PN.NRFile uri, PN.NRFile empty {File.fileUri = Just "uri.parquet"}])
+  emit "metadata-only" [File.FileFieldSpec File.FileContentType Nothing] (V.fromList [PN.NRNull, PN.NRNull])
+  schema <- either fail pure (File.mkFileSchema (V.fromList specs))
+  let list = PN.NSOptional (PN.NSList (PN.NSOptional (PN.NSFile schema)))
+      rows = V.fromList [PN.NRNull, PN.NRList V.empty, PN.NRList (V.fromList [PN.NRNull, PN.NRFile uri, PN.NRFile inline])]
+  bytes <- either fail pure (PN.buildNestedFile (V.singleton ("files", list)) (V.singleton rows))
+  BS.writeFile (outDir </> "list.parquet") bytes
+
+
+checkFileReferences :: FilePath -> IO ()
+checkFileReferences sourceDir = do
+  names <- listDirectory sourceDir
+  V.forM_ (V.fromList (filter ((== ".parquet") . takeExtension) names)) $ \name -> do
+    bytes <- BS.readFile (sourceDir </> name)
+    file <- either fail pure (Read.loadParquetFile bytes)
+    let elements = P.fmSchema (Read.pfFooter file)
+    schema <- either fail pure (File.parseFileSchema (elements V.! 1) (V.drop 2 elements))
+    arrow <- either fail pure (PHL.parquetFileArrowSchemaChecked file)
+    columns <- either (fail . show) pure (PHL.parquetRowGroupToArrow arrow file 0)
+    reader <- either fail pure (File.compileFileReader schema (V.head columns))
+    V.forM_ (V.generate (AC.columnLength (V.head columns)) id) $ \index -> do
+      reference <- either fail pure (File.fileReferenceAt reader index)
+      case reference of
+        Nothing -> pure ()
+        Just value -> either fail (const (pure ())) (File.resolveFileReference value)
+    putStrLn ("FILE checked " ++ name)
+
+
+writeNestedArrowInputs :: FilePath -> FilePath -> IO ()
+writeNestedArrowInputs = writeNestedArrowInputsWith Nothing
+
+
+writeNestedOptionsArrowInputs :: FilePath -> FilePath -> IO ()
+writeNestedOptionsArrowInputs sourceDir outDir =
+  forM_ [P.Uncompressed, P.GZip, P.Snappy, P.ZSTD, P.LZ4Raw, P.LZO, P.Brotli] $ \codec ->
+    forM_ [PW.PageV1, PW.PageV2] $ \version -> do
+      let options = PHL.defaultWriteOptions {PHL.writeCompression = codec, PHL.writePageVersion = version}
+      writeNestedArrowInputsWith (Just options) sourceDir (outDir </> show codec <> "-" <> show version)
+
+
+writeNestedArrowInputsWith :: Maybe PHL.WriteOptions -> FilePath -> FilePath -> IO ()
+writeNestedArrowInputsWith options sourceDir outDir = do
+  createDirectoryIfMissing True outDir
+  names <- listDirectory sourceDir
+  mapM_
+    ( \name -> when (takeExtension name == ".arrow") $ do
+        bytes <- BS.readFile (sourceDir </> name)
+        (schema, batches) <- either fail pure (ArrowFile.readArrowFileColumns ArrowRead.defaultReadOptions bytes)
+        let fields = AT.arrowFields schema
+        nested <- either fail pure (V.mapM PHL.arrowFieldToNestedSchema fields)
+        rows <- either fail pure (V.imapM (\index field -> V.concatMap id <$> V.mapM (\batch -> PHL.columnArrayToNestedRows field (batch V.! index)) batches) fields)
+        let columns = V.zip (AT.fieldName <$> fields) nested
+        output <- either fail pure (case options of Nothing -> PHL.encodeParquetNested columns rows; Just opts -> PHL.encodeParquetNestedWith opts columns rows)
+        BS.writeFile (outDir </> takeBaseName name <> ".parquet") output
+    )
+    names
+
+
+-- Semantic shreds are checked separately from physical storage forwarding.
+-- Keep the source metadata bytes so fallback fragments cannot accidentally
+-- acquire a fresh, incompatible dictionary.
+writeShreddedVariantInputs :: FilePath -> FilePath -> IO ()
+writeShreddedVariantInputs sourceDir outDir = do
+  createDirectoryIfMissing True outDir
+  names <- listDirectory sourceDir
+  mapM_
+    ( \name -> when (takeExtension name == ".arrow") $ do
+        bytes <- BS.readFile (sourceDir </> name)
+        (schema, batches) <- either fail pure (ArrowFile.readArrowFileColumns ArrowRead.defaultReadOptions bytes)
+        when (V.length (AT.arrowFields schema) /= 1) (fail "Variant semantic probe expects one column")
+        let field = V.head (AT.arrowFields schema)
+        shredder <- either fail pure (VariantShred.compileVariantShredder field)
+        rows <-
+          V.concat . V.toList
+            <$> V.mapM
+              ( \columns -> do
+                  let column = V.head columns
+                  reader <- either fail pure (VariantArrow.compileVariantArrowReader field column)
+                  metadata <- case column of
+                    AC.ColStruct _ _ children -> maybe (fail "missing metadata") (pure . snd) (V.find ((== "metadata") . fst) children)
+                    _ -> fail "expected Variant struct"
+                  V.generateM
+                    (AC.columnLength column)
+                    ( \index -> do
+                        value <- either fail pure (VariantArrow.variantArrowAt reader index)
+                        case value of
+                          Nothing -> either fail pure (VariantShred.shredVariant shredder Nothing)
+                          Just present -> do
+                            raw <- maybe (fail "missing metadata bytes") pure (probeMetadata metadata index)
+                            dictionary <- either fail pure (Variant.compileVariantMetadata raw)
+                            either fail pure (VariantShred.shredVariantWithMetadata shredder dictionary (Just present))
+                    )
+              )
+              batches
+        output <- either fail pure (PHL.encodeParquetNested (V.singleton (AT.fieldName field, VariantShred.variantShredSchema shredder)) (V.singleton rows))
+        BS.writeFile (outDir </> takeBaseName name <> ".parquet") output
+    )
+    names
+
+
+probeMetadata :: AC.ColumnArray -> Int -> Maybe ByteString
+probeMetadata column index = case column of
+  AC.ColDictionary _ _ values -> AC.dictKeyAt column index >>= probeMetadata values
+  AC.ColRunEndEncoded offset _ ends values -> do
+    run <- case ends of
+      AC.ColInt16 _ vector -> findRun vector (offset + index)
+      AC.ColInt32 _ vector -> findRun vector (offset + index)
+      AC.ColInt64 _ vector -> findRun vector (offset + index)
+      _ -> Nothing
+    probeMetadata values run
+  _ -> AC.anyBytesAt column index
+  where
+    findRun :: (Storable a, Integral a) => VS.Vector a -> Int -> Maybe Int
+    findRun ends position = search 0 (VS.length ends)
+      where
+        search low high
+          | low == high = if low < VS.length ends then Just low else Nothing
+          | fromIntegral (VS.unsafeIndex ends middle) <= position = search (middle + 1) high
+          | otherwise = search low middle
+          where
+            middle = low + (high - low) `quot` 2
diff --git a/probe/Reverse.hs b/probe/Reverse.hs
new file mode 100644
--- /dev/null
+++ b/probe/Reverse.hs
@@ -0,0 +1,555 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+{- | Read external Parquet files and optionally export the decoded values as
+Arrow IPC so the external reader can compare them with its original input.
+-}
+module Main (main) where
+
+import Arrow.Column qualified as AC
+import Arrow.File qualified as ArrowFile
+import Arrow.Stream qualified as AS
+import Arrow.Types qualified as AT
+import Control.DeepSeq (force)
+import Control.Exception (SomeException, catch, evaluate)
+import Control.Monad (forM_, when)
+import Crypto.Hash (Digest, SHA256, hash)
+import Data.Aeson (FromJSON (..), object, withObject, (.:), (.:?), (.=))
+import Data.Aeson qualified as Aeson
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as Builder
+import Data.ByteString.Lazy qualified as BL
+import Data.Int (Int32, Int64)
+import Data.List (sort)
+import Data.Map.Strict qualified as Map
+import Data.Text qualified as Text
+import Data.Text.Read qualified as TextRead
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Storable qualified as S
+import Data.Word (Word64)
+import Numeric (showHex)
+import Parquet.Aggregate qualified as Aggregate
+import Parquet.Arrow qualified as PArrow
+import Parquet.BloomFilter qualified as Bloom
+import Parquet.Decryption qualified as Decryption
+import Parquet.Encryption qualified as Encryption
+import Parquet.Footer qualified as Footer
+import Parquet.HighLevel qualified as PHL
+import Parquet.Levels qualified as Levels
+import Parquet.PageIndex qualified as PageIndex
+import Parquet.Predicate qualified as Predicate
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as Parquet
+import Parquet.Variant qualified as Variant
+import Parquet.Variant.Arrow qualified as VariantArrow
+import Parquet.Variant.Parquet qualified as VariantParquet
+import System.Directory (createDirectoryIfMissing, listDirectory)
+import System.Environment (getArgs)
+import System.Exit (ExitCode (..), exitFailure, exitWith)
+import System.FilePath (takeExtension, (</>))
+
+
+data ProbeResult = ProbeResult
+  { probeName :: !FilePath
+  , probeError :: !(Maybe String)
+  }
+
+
+main :: IO ()
+main = do
+  args <- getArgs
+  case args of
+    ["--encrypted-read", path, keys, output] -> encryptedRead path keys output
+    ["--authenticate-footer", path, key, prefix] -> authenticateFooter path (Text.pack key) (Text.pack prefix)
+    ["--large-map-summary", path] -> largeMapSummary path
+    ["--variant-arrow-export", path, out] -> variantArrowExport path out
+    ["--variant-payloads", path] -> variantPayloads path
+    ["--variant-export", path, name, out] -> variantExport path (Text.pack name) out
+    ["--prune", path, literal, out] -> prune path literal out
+    ["--aggregate", path] -> aggregate path
+    ["--project", path, schemaPath, output] -> project path schemaPath output
+    ["--help"] -> putStrLn "usage: wireform-parquet-reverse-probe <dir> [--arrow-output <dir>] | --authenticate-footer <file> <public-fixture-key-hex> <prefix-hex-or-dash> | --aggregate <file> | --project <file> <schema-stream> <arrow-output> | --prune <file> <lower-bound> <arrow-output>"
+    [dir] -> run dir Nothing
+    [dir, "--arrow-output", out] -> do
+      createDirectoryIfMissing True out
+      run dir (Just out)
+    _ -> do
+      putStrLn "usage: wireform-parquet-reverse-probe <dir> [--arrow-output <dir>] | --authenticate-footer <file> <public-fixture-key-hex> <prefix-hex-or-dash> | --aggregate <file> | --project <file> <schema-stream> <arrow-output> | --prune <file> <lower-bound> <arrow-output>"
+      exitFailure
+
+
+-- Fixture-only authentication mode. The conformance driver supplies public
+-- test keys, resolves external key material through the C++ reference, and
+-- compares footer counts independently of column-page decoding.
+authenticateFooter :: FilePath -> Text.Text -> Text.Text -> IO ()
+authenticateFooter path keyHex prefixHex = do
+  key <- either fail pure (hexBytes keyHex)
+  prefix <- if prefixHex == "-" then pure Nothing else Just <$> either fail pure (hexBytes prefixHex)
+  bytes <- BS.readFile path
+  authenticated <- either fail pure (Encryption.authenticateFooter key prefix Nothing bytes)
+  metadata <- either fail pure (Footer.thriftToFileMetadata (Encryption.afValue authenticated))
+  case Encryption.afCryptoMetadata authenticated of
+    Nothing -> fail "probe: expected an encrypted fixture"
+    Just info -> do
+      let actualPrefix = maybe (maybe BS.empty id (Encryption.fcmStoredAadPrefix info)) id prefix
+      loaded <- either fail pure (Read.loadParquetFileEncrypted (Read.FooterDecryption key (Encryption.fcmFileId info) actualPrefix) bytes)
+      when (Parquet.fmSchema (Read.pfFooter loaded) /= Parquet.fmSchema metadata || Parquet.fmNumRows (Read.pfFooter loaded) /= Parquet.fmNumRows metadata) (fail "probe: authenticated footer identity differs from public loader")
+  putStrLn
+    ( "{\"rows\":"
+        ++ show (Parquet.fmNumRows metadata)
+        ++ ",\"rowGroups\":"
+        ++ show (V.length (Parquet.fmRowGroups metadata))
+        ++ ",\"columns\":"
+        ++ show (map (V.length . Parquet.rgColumns) (V.toList (Parquet.fmRowGroups metadata)))
+        ++ "}"
+    )
+
+
+hexBytes :: Text.Text -> Either String BS.ByteString
+hexBytes text
+  | odd (Text.length text) = Left "probe: odd hexadecimal byte count"
+  | otherwise = BS.pack <$> traverse decode (Text.chunksOf 2 text)
+  where
+    decode pair = do
+      (value, trailing) <- TextRead.hexadecimal pair
+      if Text.null trailing then Right value else Left "probe: invalid hexadecimal bytes"
+
+
+data FixtureKeys = FixtureKeys
+  { fixtureFooter :: !Text.Text
+  , fixtureFooterMetadata :: !Text.Text
+  , fixturePrefix :: !(Maybe Text.Text)
+  , fixtureMode :: !Text.Text
+  , fixtureColumns :: !(V.Vector FixtureColumnKey)
+  , fixtureProjection :: !(Maybe (V.Vector Text.Text))
+  , fixturePruneLower :: !(Maybe Text.Text)
+  }
+
+
+data FixtureColumnKey = FixtureColumnKey
+  { fixtureColumnPath :: !(V.Vector Text.Text)
+  , fixtureColumnKey :: !Text.Text
+  , fixtureColumnMetadata :: !Text.Text
+  }
+
+
+instance FromJSON FixtureKeys where
+  parseJSON = withObject "public fixture keys" $ \o ->
+    FixtureKeys
+      <$> o .: "footer"
+      <*> o .: "footerMetadata"
+      <*> o .:? "prefix"
+      <*> o .: "mode"
+      <*> o .: "columns"
+      <*> o .:? "projection"
+      <*> o .:? "prune"
+
+
+instance FromJSON FixtureColumnKey where
+  parseJSON = withObject "public fixture column key" $ \o ->
+    FixtureColumnKey
+      <$> o .: "path"
+      <*> o .: "key"
+      <*> o .: "metadata"
+
+
+encryptedRead :: FilePath -> FilePath -> FilePath -> IO ()
+encryptedRead path keyPath output = do
+  keyBytes <- BS.readFile keyPath
+  keys <- either fail pure (Aeson.eitherDecodeStrict' keyBytes)
+  footer <- either fail pure (hexBytes (fixtureFooter keys))
+  footerMetadata <- either fail pure (hexBytes (fixtureFooterMetadata keys))
+  prefix <- traverse (either fail pure . hexBytes) (fixturePrefix keys)
+  columns <-
+    V.mapM
+      ( \entry -> do
+          key <- either fail pure (hexBytes (fixtureColumnKey entry))
+          metadata <- either fail pure (hexBytes (fixtureColumnMetadata entry))
+          pure (ResolvedFixtureKey (fixtureColumnPath entry) key metadata)
+      )
+      (fixtureColumns keys)
+  let explicit = fixtureMode keys == "explicit"
+      config =
+        Decryption.defaultDecryptionConfig
+          { Decryption.dcFooterKey = if explicit then Just footer else Nothing
+          , Decryption.dcColumnKeys = if explicit then V.foldl' (\m c -> Map.insert (resolvedPath c) (resolvedKey c) m) Map.empty columns else Map.empty
+          , Decryption.dcKeyMetadataKeys = if explicit then Map.empty else V.foldl' (\m c -> Map.insert (resolvedMetadata c) (resolvedKey c) m) (Map.singleton footerMetadata footer) columns
+          , Decryption.dcAadPrefix = prefix
+          }
+  bytes <- BS.readFile path
+  file <- either fail pure (PHL.decodeParquet PHL.defaultReadOptions {PHL.readDecryptionConfig = Just config} bytes)
+  native <- either fail pure (PArrow.parquetFileArrowSchemaChecked file)
+  selected <- case fixtureProjection keys of
+    Nothing -> pure (AT.arrowFields native)
+    Just names -> V.mapM (\name -> maybe (fail "probe: projected field missing") pure (V.find ((== name) . AT.fieldName) (AT.arrowFields native))) names
+  let schema = native {AT.arrowFields = selected}
+      metadata = Read.pfFooter file
+      groups = Parquet.fmRowGroups metadata
+      leaves = V.filter (maybe False (const True) . Parquet.seType) (Parquet.fmSchema metadata)
+  batches <- case fixturePruneLower keys of
+    Nothing -> either (fail . show) pure (V.generateM (V.length groups) (PArrow.parquetRowGroupToArrow schema file))
+    Just lower -> do
+      when (V.length selected /= 1) (fail "probe: pruning needs one selected field")
+      let field = V.head selected
+      literal <- either fail pure (predicateValue (AT.fieldType field) lower)
+      V.generateM (V.length groups) $ \groupIndex -> do
+        let group = groups V.! groupIndex
+        index <- maybe (fail "probe: pruning column missing") pure (V.findIndex (\column -> maybe False ((== V.singleton (AT.fieldName field)) . Parquet.cmPathInSchema) (Parquet.ccMetadata column)) (Parquet.rgColumns group))
+        (_, values) <- either fail pure (PArrow.readParquetColumnWithPagePruning file groupIndex index field (Predicate.PGtEq literal))
+        pure (V.singleton values)
+  _ <- evaluate (force batches)
+  encoded <- either fail pure (AS.encodeArrowStream AS.defaultWriteOptions schema (V.toList batches))
+  BS.writeFile output encoded
+  BL.putStr (Aeson.encode (object ["rows" .= Parquet.fmNumRows metadata, "rowGroups" .= V.length groups, "columns" .= V.length leaves]))
+  putStrLn ""
+  V.imapM_
+    ( \groupIndex group ->
+        V.imapM_
+          ( \columnIndex column -> case Parquet.ccMetadata column of
+              Nothing -> pure ()
+              Just columnMetadata -> do
+                let pathParts = Parquet.cmPathInSchema columnMetadata
+                    wanted = case fixtureProjection keys of
+                      Nothing -> True
+                      Just names -> not (V.null pathParts) && V.head pathParts `V.elem` names
+                when (wanted && fixturePruneLower keys == Nothing) $ do
+                  chunk <- either fail pure (Read.columnChunkSlice file groupIndex columnIndex)
+                  (maxRep, maxDef) <- either fail pure (Levels.maxLevelsForColumnPath (Parquet.fmSchema metadata) pathParts)
+                  leaf <- maybe (fail "probe: missing physical leaf") pure (leaves V.!? columnIndex)
+                  physical <- either fail pure (physicalColumn leaf columnMetadata maxRep maxDef chunk)
+                  bounds <- either fail pure (PageIndex.readColumnIndex file groupIndex columnIndex)
+                  offsets <- either fail pure (PageIndex.readOffsetIndex file groupIndex columnIndex)
+                  bloom <- either fail pure (Bloom.readBloomFilter file groupIndex columnIndex)
+                  BL.putStr
+                    ( Aeson.encode
+                        ( object
+                            [ "rowGroup" .= groupIndex
+                            , "column" .= columnIndex
+                            , "path" .= Text.intercalate "." (V.toList pathParts)
+                            , "type" .= Parquet.parquetTypeToInt (Parquet.cmType columnMetadata)
+                            , "maxDefinition" .= maxDef
+                            , "maxRepetition" .= maxRep
+                            , "columnIndex" .= maybe False (const True) bounds
+                            , "offsetPages" .= maybe 0 (V.length . Parquet.oiPageLocations) offsets
+                            , "bloomBytes" .= maybe 0 Bloom.sbbfNumBytes bloom
+                            , "events" .= VP.length (physicalDefinitions physical)
+                            , "present" .= V.length (physicalValues physical)
+                            , "definitions" .= VP.toList (physicalDefinitions physical)
+                            , "repetitions" .= VP.toList (physicalRepetitions physical)
+                            , "values" .= V.map hexString (physicalValues physical)
+                            ]
+                        )
+                    )
+                  putStrLn ""
+          )
+          (Parquet.rgColumns group)
+    )
+    groups
+
+
+data ResolvedFixtureKey = ResolvedFixtureKey
+  { resolvedPath :: !(V.Vector Text.Text)
+  , resolvedKey :: !BS.ByteString
+  , resolvedMetadata :: !BS.ByteString
+  }
+
+
+data PhysicalColumn = PhysicalColumn
+  { physicalRepetitions :: !(VP.Vector Int32)
+  , physicalDefinitions :: !(VP.Vector Int32)
+  , physicalValues :: !(V.Vector BS.ByteString)
+  }
+
+
+physicalColumn :: Parquet.SchemaElement -> Parquet.ColumnMetadata -> Int -> Int -> BS.ByteString -> Either String PhysicalColumn
+physicalColumn leaf metadata maxRep maxDef bytes = case Parquet.cmType metadata of
+  Parquet.PTBoolean -> convert (V.map (BS.singleton . \value -> if value then 1 else 0)) (Read.readBoolLevels codec maxRep maxDef bytes)
+  Parquet.PTInt32 -> convert (primitive Builder.int32LE) (Read.readInt32Levels codec maxRep maxDef bytes)
+  Parquet.PTInt64 -> convert (primitive Builder.int64LE) (Read.readInt64Levels codec maxRep maxDef bytes)
+  Parquet.PTFloat -> convert (primitive Builder.floatLE) (Read.readFloatLevels codec maxRep maxDef bytes)
+  Parquet.PTDouble -> convert (primitive Builder.doubleLE) (Read.readDoubleLevels codec maxRep maxDef bytes)
+  Parquet.PTInt96 -> convert id (Read.readFixedLevels 12 codec maxRep maxDef bytes)
+  Parquet.PTByteArray -> convert id (Read.readByteArrayLevels codec maxRep maxDef bytes)
+  Parquet.PTFixedLenByteArray -> do
+    width <- maybe (Left "probe: missing fixed-byte width") Right (Parquet.seTypeLength leaf)
+    convert id (Read.readFixedLevels (fromIntegral width) codec maxRep maxDef bytes)
+  where
+    codec = Parquet.cmCodec metadata
+    convert values decoded = do
+      levels <- decoded
+      Right (PhysicalColumn (Read.clRepetition levels) (Read.clDefinition levels) (values (Read.clValues levels)))
+    primitive encode values = V.generate (VP.length values) (BL.toStrict . Builder.toLazyByteString . encode . (values VP.!))
+
+
+hexString :: BS.ByteString -> String
+hexString = concatMap (\byte -> let digits = showHex byte "" in if length digits == 1 then '0' : digits else digits) . BS.unpack
+
+
+variantArrowExport :: FilePath -> FilePath -> IO ()
+variantArrowExport path out = do
+  bytes <- BS.readFile path
+  (schema, batches) <- either fail pure (ArrowFile.readArrowFileColumns AS.defaultReadOptions bytes)
+  when (V.length (AT.arrowFields schema) /= 1) (fail "Variant Arrow probe expects one column")
+  createDirectoryIfMissing True out
+  _ <-
+    V.foldM'
+      ( \base columns -> do
+          when (V.length columns /= 1) (fail "Variant Arrow probe expects one column")
+          reader <- either fail pure (VariantArrow.compileVariantArrowReader (V.head (AT.arrowFields schema)) (V.head columns))
+          forM_ [0 .. VariantArrow.variantArrowLength reader - 1] $ \row -> do
+            value <- either fail pure (VariantArrow.variantArrowAt reader row)
+            let digits = show (base + row)
+                stem = out </> replicate (max 0 (6 - length digits)) '0' ++ digits
+            case value of
+              Nothing -> BS.writeFile (stem ++ ".null") BS.empty
+              Just present -> do
+                encoded <- either fail pure (Variant.encodeVariant present)
+                BS.writeFile (stem ++ ".meta") (Variant.variantMetadata encoded)
+                BS.writeFile (stem ++ ".value") (Variant.variantValue encoded)
+          pure (base + VariantArrow.variantArrowLength reader)
+      )
+      0
+      batches
+  pure ()
+
+
+-- Explicit semantic mode for corpus fixtures containing unannotated binary
+-- metadata/value columns. Ordinary binary reads must preserve these bytes.
+variantPayloads :: FilePath -> IO ()
+variantPayloads path = do
+  bytes <- BS.readFile path
+  let result = do
+        file <- PHL.decodeParquet PHL.defaultReadOptions bytes
+        schema <- PArrow.parquetFileArrowSchemaChecked file
+        fields <- V.mapM (\name -> maybe (Left "variant probe: missing metadata/value field") Right (V.find ((== name) . AT.fieldName) (AT.arrowFields schema))) (V.fromList ["metadata", "value"])
+        let group i = do
+              columns <- either (Left . show) Right (PArrow.parquetRowGroupToArrow schema {AT.arrowFields = fields} file i)
+              let count = AC.columnLength (V.head columns)
+              column <- AC.mkStruct count Nothing (V.zip (AT.fieldName <$> fields) columns)
+              reader <- VariantParquet.compileVariantReader column
+              let loop row
+                    | row == count = Right count
+                    | otherwise = VariantParquet.variantAt reader row >> loop (row + 1)
+              loop 0
+        sum <$> mapM group [0 .. PArrow.numRowGroups file - 1]
+  checked <- evaluate (force result)
+  case checked of
+    Left message -> putStrLn message >> exitFailure
+    Right count -> putStrLn ("Variant payloads validated: " ++ show count)
+
+
+variantExport :: FilePath -> Text.Text -> FilePath -> IO ()
+variantExport path name out = do
+  bytes <- BS.readFile path
+  file <- either fail pure (PHL.decodeParquet PHL.defaultReadOptions bytes)
+  createDirectoryIfMissing True out
+  forM_ [0 .. PArrow.numRowGroups file - 1] $ \group -> do
+    values <- either fail pure (VariantParquet.readVariantColumn file group name)
+    V.imapM_
+      ( \row value -> do
+          let stem = out </> show group ++ "-" ++ show row
+          case value of
+            Nothing -> BS.writeFile (stem ++ ".null") BS.empty
+            Just present -> do
+              encoded <- either fail pure (Variant.encodeVariant present)
+              BS.writeFile (stem ++ ".meta") (Variant.variantMetadata encoded)
+              BS.writeFile (stem ++ ".value") (Variant.variantValue encoded)
+      )
+      values
+
+
+-- Exercise the public indexed Arrow reader, retaining whole matching pages.
+prune :: FilePath -> String -> FilePath -> IO ()
+prune path literal output = do
+  bytes <- BS.readFile path
+  either
+    (\err -> putStrLn err >> exitFailure)
+    ( \(kept, encoded) -> do
+        BS.writeFile output encoded
+        putStrLn ("pages=" ++ show kept)
+    )
+    $ do
+      file <- PHL.decodeParquet PHL.defaultReadOptions bytes
+      schema <- PArrow.parquetFileArrowSchemaChecked file
+      let fields = flattenFields (AT.arrowFields schema)
+      native <- maybe (Left "probe: no leaf field") Right (fields V.!? 0)
+      value <- predicateValue (AT.fieldType native) (Text.pack literal)
+      let target = native {AT.fieldNullable = True}
+      (kept, column) <- PArrow.readParquetColumnWithPagePruning file 0 0 target (Predicate.PGtEq value)
+      encoded <-
+        AS.encodeArrowStream
+          AS.defaultWriteOptions
+          (schema {AT.arrowFields = V.singleton target})
+          [V.singleton column]
+      Right (kept, encoded)
+  where
+    flattenFields =
+      V.concatMap
+        ( \field ->
+            if V.null (AT.fieldChildren field) then V.singleton field else flattenFields (AT.fieldChildren field)
+        )
+
+
+predicateValue :: AT.ArrowType -> Text.Text -> Either String Predicate.PValue
+predicateValue typ input = case typ of
+  AT.AInt width signed
+    | not signed -> do
+        integer <- integral
+        if integer < 0 || integer > toInteger (maxBound :: Word64)
+          then Left "probe: unsigned literal out of range"
+          else Right (Predicate.PVUnsigned (fromInteger integer))
+    | width <= 32 -> do
+        integer <- integral
+        if integer < toInteger (minBound :: Int32) || integer > toInteger (maxBound :: Int32)
+          then Left "probe: INT32 literal out of range"
+          else Right (Predicate.PVInt32 (fromInteger integer))
+    | otherwise -> int64
+  AT.AFloatingPoint AT.Single -> Predicate.PVFloat <$> fractional
+  AT.AFloatingPoint _ -> Predicate.PVDouble <$> fractional
+  AT.ADecimal {} -> Predicate.PVDecimal <$> fractional
+  AT.ADecimal256 {} -> Predicate.PVDecimal <$> fractional
+  AT.AUtf8 -> Right (Predicate.PVText input)
+  AT.ABinary -> binary
+  AT.AFixedSizeBinary _ -> binary
+  AT.ABool -> case Text.toLower input of
+    "true" -> Right (Predicate.PVBool True)
+    "false" -> Right (Predicate.PVBool False)
+    _ -> Left "probe: invalid boolean literal"
+  AT.ADate _ -> Predicate.PVInt32 . fromInteger <$> integral
+  AT.ATime _ 32 -> Predicate.PVInt32 . fromInteger <$> integral
+  AT.ATime _ _ -> int64
+  AT.ATimestamp {} -> int64
+  _ -> Left "probe: unsupported predicate type"
+  where
+    entire parsed = do
+      (value, trailing) <- parsed
+      if Text.null trailing then Right value else Left "probe: trailing literal text"
+    integral = entire (TextRead.signed TextRead.decimal input) :: Either String Integer
+    fractional :: Fractional a => Either String a
+    fractional = entire (TextRead.signed TextRead.rational input)
+    int64 = do
+      integer <- integral
+      if integer < toInteger (minBound :: Int64) || integer > toInteger (maxBound :: Int64)
+        then Left "probe: INT64 literal out of range"
+        else Right (Predicate.PVInt64 (fromInteger integer))
+    binary
+      | odd (Text.length input) = Left "probe: odd hexadecimal byte count"
+      | otherwise =
+          Predicate.PVBinary . BS.pack
+            <$> traverse
+              (\pair -> entire (TextRead.hexadecimal pair))
+              (Text.chunksOf 2 input)
+
+
+-- A metadata-only mode lets an independent Thrift implementation exercise
+-- compact bounds without relying on this probe's value decoder.
+aggregate :: FilePath -> IO ()
+aggregate path = do
+  bytes <- BS.readFile path
+  case Footer.readFooter bytes of
+    Left err -> putStrLn err >> exitFailure
+    Right metadata -> do
+      putStrLn ("rows=" ++ show (Aggregate.fileRowCountChecked metadata))
+      putStrLn ("non_null=" ++ show (Aggregate.columnNonNullCount metadata 0))
+      putStrLn ("minimum=" ++ show (Aggregate.columnMin metadata 0))
+      putStrLn ("maximum=" ++ show (Aggregate.columnMax metadata 0))
+
+
+run :: FilePath -> Maybe FilePath -> IO ()
+run dir out = do
+  files <- sort . filter ((== ".parquet") . takeExtension) <$> listDirectory dir
+  when (null files) $ do
+    putStrLn "FAIL: no Parquet files found"
+    exitFailure
+  results <- mapM (probe dir out) files
+  let !nFail = length (filter hasError results)
+  forM_ results $ \result ->
+    case probeError result of
+      Nothing -> putStrLn ("  OK   " ++ probeName result)
+      Just err -> putStrLn ("  FAIL " ++ probeName result ++ ": " ++ err)
+  putStrLn (show (length results) ++ " files, " ++ show nFail ++ " failed")
+  when (nFail /= 0) (exitWith (ExitFailure (min 99 nFail)))
+  where
+    hasError result = case probeError result of
+      Nothing -> False
+      Just _ -> True
+
+
+probe :: FilePath -> Maybe FilePath -> FilePath -> IO ProbeResult
+probe dir out name =
+  check `catch` \err -> pure (ProbeResult name (Just (show (err :: SomeException))))
+  where
+    check = do
+      bytes <- BS.readFile (dir </> name)
+      -- Force within the exception handler: a lazy decoder exception must
+      -- count as a failed file, rather than escaping while printing results.
+      decoded <- evaluate (force (decodeOnce bytes))
+      case decoded of
+        Left err -> pure (ProbeResult name (Just err))
+        Right arrowBytes -> do
+          forM_ out $ \path -> BS.writeFile (path </> (name ++ ".arrows")) arrowBytes
+          pure (ProbeResult name Nothing)
+
+
+decodeOnce :: BS.ByteString -> Either String BS.ByteString
+decodeOnce bytes = do
+  pf <- PHL.decodeParquet PHL.defaultReadOptions bytes
+  schema <- PArrow.parquetFileArrowSchemaChecked pf
+  batches <- mapM (readGroup schema pf) [0 .. PArrow.numRowGroups pf - 1]
+  AS.encodeArrowStream AS.defaultWriteOptions schema batches
+  where
+    readGroup schema pf i = case PArrow.parquetRowGroupToArrow schema pf i of
+      Left err -> Left ("row group " ++ show i ++ ": " ++ show err)
+      Right batch -> Right batch
+
+
+-- The target schema is supplied as an Arrow IPC stream, avoiding a second
+-- ad-hoc schema vocabulary in the external conformance harness.
+project :: FilePath -> FilePath -> FilePath -> IO ()
+project path schemaPath output = do
+  bytes <- BS.readFile path
+  schemaBytes <- BS.readFile schemaPath
+  let result = do
+        (schema, _) <- AS.decodeArrowStream AS.defaultReadOptions schemaBytes
+        file <- PHL.decodeParquet PHL.defaultReadOptions bytes
+        batches <-
+          mapM
+            (\i -> either (Left . show) Right (PArrow.parquetRowGroupToArrow schema file i))
+            [0 .. PArrow.numRowGroups file - 1]
+        AS.encodeArrowStream AS.defaultWriteOptions schema batches
+  encoded <- evaluate (force result)
+  case encoded of
+    Left err -> putStrLn err >> exitFailure
+    Right arrowBytes -> BS.writeFile output arrowBytes
+
+
+-- The official large-map fixture has two1GiB keys. Summarize validated Arrow
+-- buffers directly so the oracle never needs a multi-gigabyte IPC temporary
+-- or Python string objects. The public projection requests64-bit key offsets.
+largeMapSummary :: FilePath -> IO ()
+largeMapSummary path = do
+  bytes <- BS.readFile path
+  file <- either fail pure (PHL.decodeParquet PHL.defaultReadOptions bytes)
+  native <- either fail pure (PArrow.parquetFileArrowSchemaChecked file)
+  let wide field =
+        field
+          { AT.fieldType = case AT.fieldType field of AT.AUtf8 -> AT.ALargeUtf8; AT.ABinary -> AT.ALargeBinary; typ -> typ
+          , AT.fieldChildren = wide <$> AT.fieldChildren field
+          }
+      target = native {AT.arrowFields = wide <$> AT.arrowFields native}
+  columns <- either (fail . show) pure (PArrow.parquetRowGroupToArrow target file 0)
+  case V.toList columns of
+    [column@(AC.ColMap _ offsets keys values)] -> case (keys, values) of
+      (AC.ColLargeUtf8 _ keyOffsets payload, AC.ColInt32 _ integers) -> do
+        putStrLn ("rows=" ++ show (AC.columnLength column))
+        putStrLn ("map_nulls=" ++ show (AC.nullCount column))
+        putStrLn ("map_offsets=" ++ show (S.toList offsets))
+        putStrLn ("key_nulls=" ++ show (AC.nullCount keys))
+        putStrLn ("key_offsets=" ++ show (S.toList keyOffsets))
+        putStrLn ("key_bytes=" ++ show (BS.length payload))
+        putStrLn ("key_sha256=" ++ show (hash payload :: Digest SHA256))
+        putStrLn ("value_nulls=" ++ show (AC.nullCount values))
+        putStrLn ("values=" ++ show (S.toList integers))
+      _ -> fail "large-map probe expected LargeUtf8 keys and Int32 values"
+    _ -> fail "large-map probe expected one Map column"
diff --git a/scripts/build_parquet_encrypted_reference.py b/scripts/build_parquet_encrypted_reference.py
new file mode 100644
--- /dev/null
+++ b/scripts/build_parquet_encrypted_reference.py
@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Build the fixture oracle against PyArrow 26's unmodified C++ library.
+
+Requires a C++20 compiler and the PyArrow 26 wheel. No library source is
+modified or downloaded. The adapter uses public parquet-testing keys only.
+"""
+
+import argparse
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+import pyarrow as pa
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    if pa.__version__.split(".")[0] != "26":
+        raise SystemExit("this adapter requires PyArrow 26's C++ ABI")
+    if sys.platform not in ("darwin", "linux"):
+        raise SystemExit("the fixture adapter currently builds on macOS and Linux")
+    compiler = os.environ.get("CXX") or shutil.which("clang++") or shutil.which("c++")
+    if not compiler:
+        raise SystemExit("a C++20 compiler is required")
+    library = Path(pa.get_library_dirs()[0])
+    suffix = ".2600.dylib" if sys.platform == "darwin" else ".so.2600"
+    libraries = [library / ("lib" + name + suffix) for name in ("parquet", "arrow")]
+    for path in libraries:
+        if not path.is_file():
+            raise SystemExit(f"missing PyArrow C++ library: {path}")
+    output = args.output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run([
+        compiler, "-std=c++20", "-O2", "-I", pa.get_include(),
+        str(Path(__file__).with_name("parquet_encrypted_reference.cc")),
+        *map(str, libraries), f"-Wl,-rpath,{library}", "-o", str(output),
+    ], check=True)
+    print(f"Built {output} against PyArrow {pa.__version__}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/build_parquet_file_reference.py b/scripts/build_parquet_file_reference.py
new file mode 100644
--- /dev/null
+++ b/scripts/build_parquet_file_reference.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Build the pinned, unmodified upstream Arrow FILE interoperability reference.
+
+Requires Python 3.12+, Cargo and Rust 1.88+. The small Rust command adapter and
+generated dependency lock are shipped beside this script. No Rust dependency
+is added to the production Haskell package.
+"""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.request
+
+
+REVISION = "cc58320c2da359b757814db5a9651397d829b601"
+ARCHIVE_SHA256 = "8bf1f8eafe3651093c43dad7d905a725473b0a2928436e267526298fe987e21a"
+
+
+def sha256(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", required=True, type=Path)
+    parser.add_argument("--archive", type=Path, help="Use an existing source archive instead of downloading it")
+    parser.add_argument("--cargo", default=os.environ.get("CARGO", "cargo"))
+    parser.add_argument("--allow-network", action="store_true", help="Allow Cargo to fetch missing locked dependencies")
+    args = parser.parse_args()
+    if sys.version_info < (3, 12):
+        parser.error("the reference builder requires Python 3.12 or newer")
+    output = args.output.resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    archive = args.archive.resolve() if args.archive else output / "arrow-rs.tar.gz"
+    if not args.archive:
+        urllib.request.urlretrieve(f"https://codeload.github.com/apache/arrow-rs/tar.gz/{REVISION}", archive)
+    if sha256(archive) != ARCHIVE_SHA256:
+        raise RuntimeError("upstream source archive hash differs from the pinned reference")
+    # A fresh directory prevents stale or locally edited upstream sources from
+    # influencing the reference; keep it for inspection after the build.
+    checkout = Path(tempfile.mkdtemp(prefix="upstream-", dir=output))
+    with tarfile.open(archive) as source:
+        source.extractall(checkout, filter="data")
+    upstream = checkout / ("arrow-rs-" + REVISION)
+    project = output / "oracle"
+    (project / "src").mkdir(parents=True, exist_ok=True)
+    scripts = Path(__file__).resolve().parent
+    shutil.copyfile(scripts / "parquet_file_reference.rs", project / "src/main.rs")
+    shutil.copyfile(scripts / "parquet_file_reference.lock", project / "Cargo.lock")
+    dependencies = {
+        "parquet": "{ path = " + json.dumps(str(upstream / "parquet")) + ', default-features = false, features = ["arrow", "file_experimental", "snap", "zstd", "lz4"] }',
+        "arrow-array": "{ path = " + json.dumps(str(upstream / "arrow-array")) + " }",
+        "arrow-ipc": "{ path = " + json.dumps(str(upstream / "arrow-ipc")) + " }",
+    }
+    manifest = '[package]\nname = "wireform-parquet-file-reference"\nversion = "0.1.0"\nedition = "2024"\n\n[workspace]\n\n[dependencies]\n'
+    manifest += "".join(name + " = " + value + "\n" for name, value in dependencies.items())
+    (project / "Cargo.toml").write_text(manifest)
+    command = [args.cargo, "build", "--release", "--locked", "--manifest-path", str(project / "Cargo.toml"), "--target-dir", str(output / "target")]
+    if not args.allow_network:
+        command.append("--offline")
+    subprocess.run(command, check=True)
+    binary = output / "target/release/wireform-parquet-file-reference"
+    report = {"revision": REVISION, "archiveSHA256": ARCHIVE_SHA256, "upstreamSource": str(upstream),
+              "adapterSHA256": sha256(project / "src/main.rs"), "lockSHA256": sha256(project / "Cargo.lock"),
+              "binary": str(binary), "binarySHA256": sha256(binary), "features": ["arrow", "file_experimental", "snap", "zstd", "lz4"]}
+    (output / "reference.json").write_text(json.dumps(report, indent=2) + "\n")
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/build_parquet_variant_reference.py b/scripts/build_parquet_variant_reference.py
new file mode 100644
--- /dev/null
+++ b/scripts/build_parquet_variant_reference.py
@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Build the pinned, unmodified upstream Arrow Variant interoperability reference.
+
+Requires Python 3.12+, Cargo and Rust 1.88+. The small Rust command adapter and
+generated dependency lock are shipped beside this script. No Rust dependency
+is added to the production Haskell package.
+"""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.request
+
+
+REVISION = "cc58320c2da359b757814db5a9651397d829b601"
+ARCHIVE_SHA256 = "8bf1f8eafe3651093c43dad7d905a725473b0a2928436e267526298fe987e21a"
+
+
+def sha256(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", required=True, type=Path)
+    parser.add_argument("--archive", type=Path, help="Use an existing source archive instead of downloading it")
+    parser.add_argument("--cargo", default=os.environ.get("CARGO", "cargo"))
+    parser.add_argument("--allow-network", action="store_true", help="Allow Cargo to fetch missing locked dependencies")
+    parser.add_argument("--typed", action="store_true", help="Build the typed Arrow IPC reconstruction oracle")
+    args = parser.parse_args()
+    if sys.version_info < (3, 12):
+        parser.error("the reference builder requires Python 3.12 or newer")
+    output = args.output.resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    archive = args.archive.resolve() if args.archive else output / "arrow-rs.tar.gz"
+    if not args.archive:
+        urllib.request.urlretrieve(f"https://codeload.github.com/apache/arrow-rs/tar.gz/{REVISION}", archive)
+    if sha256(archive) != ARCHIVE_SHA256:
+        raise RuntimeError("upstream source archive hash differs from the pinned reference")
+    # A fresh directory prevents stale or locally edited upstream sources from
+    # influencing the reference; keep it for inspection after the build.
+    checkout = Path(tempfile.mkdtemp(prefix="upstream-", dir=output))
+    with tarfile.open(archive) as source:
+        source.extractall(checkout, filter="data")
+    upstream = checkout / ("arrow-rs-" + REVISION)
+    project = output / "oracle"
+    (project / "src").mkdir(parents=True, exist_ok=True)
+    scripts = Path(__file__).resolve().parent
+    adapter = "parquet_variant_typed_reference" if args.typed else "parquet_variant_reference"
+    shutil.copyfile(scripts / (adapter + ".rs"), project / "src/main.rs")
+    shutil.copyfile(scripts / (adapter + ".lock"), project / "Cargo.lock")
+    names = ["parquet-variant"]
+    if args.typed:
+        names += ["arrow-array", "arrow-ipc", "parquet-variant-compute"]
+    dependencies = {}
+    for name in names:
+        dependencies[name] = "{ path = " + json.dumps(str(upstream / name)) + " }"
+    package = "wireform-typed-variant-reference" if args.typed else "wireform-variant-reference"
+    manifest = '[package]\nname = ' + json.dumps(package) + '\nversion = "0.1.0"\nedition = "2024"\n\n[workspace]\n\n[dependencies]\n'
+    manifest += "".join(name + " = " + value + "\n" for name, value in dependencies.items())
+    (project / "Cargo.toml").write_text(manifest)
+    command = [args.cargo, "build", "--release", "--locked", "--manifest-path", str(project / "Cargo.toml"), "--target-dir", str(output / "target")]
+    if not args.allow_network:
+        command.append("--offline")
+    subprocess.run(command, check=True)
+    binary = output / "target/release" / package
+    report = {"revision": REVISION, "archiveSHA256": ARCHIVE_SHA256, "upstreamSource": str(upstream),
+              "adapterSHA256": sha256(project / "src/main.rs"), "lockSHA256": sha256(project / "Cargo.lock"),
+              "binary": str(binary), "binarySHA256": sha256(binary), "features": ["parquet-variant default SIMD UTF8 validation"] + (["Arrow IPC typed Variant recursive unshred kernel"] if args.typed else [])}
+    (output / "reference.json").write_text(json.dumps(report, indent=2) + "\n")
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_aggregate_interop.py b/scripts/parquet_aggregate_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_aggregate_interop.py
@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""Exercise exact aggregates using PyArrow files and Apache Thrift mutations.
+
+The typed footer tree retains the original Thrift wire kinds, so rewriting a
+flag cannot silently change another field's type. Page bytes remain untouched.
+"""
+
+import argparse
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import duckdb
+import polars as pl
+import pyarrow as pa
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from thrift.protocol.TCompactProtocol import TCompactProtocol
+from thrift.transport.TTransport import TMemoryBuffer
+
+
+def read_node(protocol, kind):
+    if kind == TType.STRUCT:
+        protocol.readStructBegin()
+        fields = {}
+        while True:
+            _, field_kind, field_id = protocol.readFieldBegin()
+            if field_kind == TType.STOP:
+                break
+            fields[field_id] = read_node(protocol, field_kind)
+            protocol.readFieldEnd()
+        protocol.readStructEnd()
+        return kind, fields
+    if kind == TType.LIST:
+        item_kind, count = protocol.readListBegin()
+        items = [read_node(protocol, item_kind) for _ in range(count)]
+        protocol.readListEnd()
+        return kind, (item_kind, items)
+    scalar = {
+        TType.BOOL: protocol.readBool, TType.BYTE: protocol.readByte,
+        TType.I16: protocol.readI16, TType.I32: protocol.readI32,
+        TType.I64: protocol.readI64, TType.DOUBLE: protocol.readDouble,
+        TType.STRING: protocol.readBinary,
+    }
+    return kind, scalar[kind]()
+
+
+def write_node(protocol, node):
+    kind, value = node
+    if kind == TType.STRUCT:
+        protocol.writeStructBegin('')
+        entries = value.items() if isinstance(value, dict) else value
+        for field_id, child in sorted(entries):
+            protocol.writeFieldBegin('', child[0], field_id)
+            write_node(protocol, child)
+            protocol.writeFieldEnd()
+        protocol.writeFieldStop()
+        protocol.writeStructEnd()
+    elif kind == TType.LIST:
+        item_kind, items = value
+        protocol.writeListBegin(item_kind, len(items))
+        for child in items:
+            write_node(protocol, child)
+        protocol.writeListEnd()
+    else:
+        scalar = {
+            TType.BOOL: protocol.writeBool, TType.BYTE: protocol.writeByte,
+            TType.I16: protocol.writeI16, TType.I32: protocol.writeI32,
+            TType.I64: protocol.writeI64, TType.DOUBLE: protocol.writeDouble,
+            TType.STRING: protocol.writeBinary,
+        }
+        scalar[kind](value)
+
+
+def footer(path):
+    raw = path.read_bytes()
+    size = int.from_bytes(raw[-8:-4], 'little')
+    start = len(raw) - 8 - size
+    node = read_node(TCompactProtocol(TMemoryBuffer(raw[start:-8])), TType.STRUCT)
+    return raw[:start], node
+
+
+def groups(node):
+    return node[1][4][1][1]
+
+
+def column_metadata(node, index=0):
+    return groups(node)[index][1][1][1][1][0][1][3][1]
+
+
+def stats(node, index=0):
+    # FileMetaData.row_groups[index].columns[0].meta_data.statistics
+    return column_metadata(node, index)[12][1]
+
+
+def duplicate_exactness(node):
+    fields = stats(node)
+    fields.pop(8, None)
+    entries = [*fields.items(), (8, (TType.BOOL, False)), (8, (TType.BOOL, True))]
+    column_metadata(node)[12] = TType.STRUCT, entries
+
+
+def rewrite(source, destination, edit):
+    prefix, node = footer(source)
+    edit(node)
+    transport = TMemoryBuffer()
+    write_node(TCompactProtocol(transport), node)
+    encoded = transport.getvalue()
+    destination.write_bytes(prefix + encoded + len(encoded).to_bytes(4, 'little') + b'PAR1')
+
+
+def check(probe, path, **expected):
+    result = subprocess.run([str(probe), '--aggregate', str(path)],
+                            check=True, capture_output=True, text=True)
+    actual = dict(line.split('=', 1) for line in result.stdout.splitlines())
+    for key, value in expected.items():
+        assert actual[key] == value, (path.name, key, actual, expected)
+    print('PASS', path.name)
+
+
+def bounds(node, lower, upper, min_exact, max_exact):
+    fields = stats(node)
+    for tag in (1, 2, 7, 8):
+        fields.pop(tag, None)
+    fields[6], fields[5] = (TType.STRING, lower), (TType.STRING, upper)
+    if max_exact is not None:
+        fields[7] = TType.BOOL, max_exact
+    if min_exact is not None:
+        fields[8] = TType.BOOL, min_exact
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--reader', type=Path, required=True)
+    parser.add_argument('--writer', type=Path, required=True)
+    args = parser.parse_args()
+    reader, writer = args.reader.resolve(), args.writer.resolve()
+    with tempfile.TemporaryDirectory(prefix='wireform-parquet-aggregate-') as directory:
+        root = Path(directory)
+        original = root / 'original.parquet'
+        table = pa.table({'x': pa.array(['Baker', 'Barn'], pa.string())})
+        pq.write_table(table, original)
+        for name, low, high, min_exact, max_exact, minimum, maximum in [
+            ('compact', b'B', b'C', False, False, 'Nothing', 'Nothing'),
+            ('unknown', b'B', b'C', None, None, 'Nothing', 'Nothing'),
+            ('exact', b'Baker', b'Barn', True, True,
+             'Just (PVText "Baker")', 'Just (PVText "Barn")'),
+            ('minimum-only', b'Baker', b'C', True, False, 'Just (PVText "Baker")', 'Nothing'),
+            ('maximum-only', b'B', b'Barn', False, True, 'Nothing', 'Just (PVText "Barn")'),
+        ]:
+            target = root / f'{name}.parquet'
+            rewrite(original, target, lambda node: bounds(node, low, high, min_exact, max_exact))
+            assert pq.read_table(target).equals(table), name
+            check(reader, target, rows='Just 2', non_null='Just 2', minimum=minimum, maximum=maximum)
+
+        integers = root / 'integers.parquet'
+        pq.write_table(pa.table({'x': pa.array([7, 9], pa.int64())}), integers)
+        legacy = root / 'legacy-exact.parquet'
+
+        def legacy_bounds(node):
+            bounds(node, struct.pack('<q', 0), struct.pack('<q', 10), False, False)
+            stats(node)[2] = TType.STRING, struct.pack('<q', 7)
+            stats(node)[1] = TType.STRING, struct.pack('<q', 9)
+
+        rewrite(integers, legacy, legacy_bounds)
+        check(reader, legacy, minimum='Just (PVInt64 7)', maximum='Just (PVInt64 9)')
+
+        all_null = root / 'null-group.parquet'
+        pq.write_table(pa.table({'x': pa.array([None, None, 'Baker', 'Barn'], pa.string())}),
+                       all_null, row_group_size=2)
+        target = root / 'null-group-exact.parquet'
+
+        def exact_second_group(node):
+            stats(node, 1)[7] = TType.BOOL, True
+            stats(node, 1)[8] = TType.BOOL, True
+
+        rewrite(all_null, target, exact_second_group)
+        check(reader, target, rows='Just 4', non_null='Just 2',
+              minimum='Just (PVText "Baker")', maximum='Just (PVText "Barn")')
+
+        nested = root / 'nullable-ancestor.parquet'
+        child = pa.field('x', pa.int32(), nullable=False)
+        array = pa.array([None, {'x': 7}, {'x': 9}], pa.struct([child]))
+        pq.write_table(pa.table({'record': array}), nested)
+        check(reader, nested, rows='Just 3', non_null='Just 2')
+
+        repeated = root / 'repeated.parquet'
+        pq.write_table(pa.table({'x': pa.array([None, [], [7, 9], [None]], pa.list_(pa.int32()))}), repeated)
+        check(reader, repeated, rows='Just 4', non_null='Nothing')
+
+        empty = root / 'empty.parquet'
+        pq.write_table(pa.table({'x': pa.array([], pa.string())}), empty)
+        check(reader, empty, rows='Just 0', non_null='Just 0', minimum='Nothing', maximum='Nothing')
+
+        for name, edit, message in [
+            ('negative-count', lambda node: node[1].__setitem__(3, (TType.I64, -1)), 'row count'),
+            ('wrong-flag-type', lambda node: stats(node).__setitem__(7, (TType.I32, 1)), 'exactness flag'),
+            ('duplicate-flag', duplicate_exactness, 'exactness flag'),
+        ]:
+            target = root / f'{name}.parquet'
+            rewrite(original, target, edit)
+            result = subprocess.run([str(reader), '--aggregate', str(target)], capture_output=True, text=True)
+            assert result.returncode != 0 and message in result.stdout, (name, result)
+            print('PASS', name, 'rejected')
+
+        stale = root / 'stale-total.parquet'
+        rewrite(original, stale, lambda node: node[1].__setitem__(3, (TType.I64, 0)))
+        assert pq.read_table(stale).equals(table)
+        check(reader, stale, rows='Nothing', non_null='Nothing', minimum='Nothing', maximum='Nothing')
+
+        generated = root / 'generated'
+        generated.mkdir()
+        subprocess.run([str(writer), '--statistics', str(generated)], check=True)
+        for name, values, low, high in [
+            ('binary', [b'\x80', b'\x7f', b'', b'\xff'], b'', b'\xff'),
+            ('utf8', ['é', 'z', '', '🙂'], b'', '🙂'.encode()),
+        ]:
+            path = generated / f'{name}-boundaries.parquet'
+            fields = stats(footer(path)[1])
+            assert 1 not in fields and 2 not in fields, (name, 'legacy byte bounds')
+            assert fields[6][1] == low and fields[5][1] == high, (name, 'modern byte bounds')
+            assert fields[7] == (TType.BOOL, True) and fields[8] == (TType.BOOL, True)
+            assert pq.read_table(path)['x'].to_pylist() == values, name
+            assert pl.read_parquet(path)['x'].to_list() == values, name
+            connection = duckdb.connect()
+            try:
+                actual = connection.execute('SELECT x FROM read_parquet(?)', [str(path)]).fetchall()
+                assert actual == [(value,) for value in values], name
+            finally:
+                connection.close()
+            print('PASS', name, 'writer bounds and values in three engines')
+    print('Independent exact/compact bounds, null groups, nested counts, invalid metadata and binary boundaries passed')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_alp_fixtures.py b/scripts/parquet_alp_fixtures.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_alp_fixtures.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Extract matched raw ALP benchmark pages from Apache's official fixture.
+
+Both readers consume the same decompressed page bytes. Expected IEEE bytes
+come from independently decoded PLAIN columns; extraction and validation are
+outside measurements. No Python float conversion touches NaN payloads.
+"""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import struct
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+from parquet_statistics_interop import read_value, TCompactProtocol, TMemoryBuffer, TType
+
+
+def header_at(raw, offset):
+    transport = TMemoryBuffer(raw[offset:])
+    header = read_value(TCompactProtocol(transport), TType.STRUCT)
+    return header, offset + transport.cstringio_buf.tell()
+
+
+def plain_bits(array, width):
+    array = array.combine_chunks()
+    data = memoryview(array.buffers()[1])
+    output = bytearray()
+    for row in range(len(array)):
+        if array[row].is_valid:
+            start = (array.offset + row) * width
+            output.extend(data[start:start + width])
+    return bytes(output)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--corpus", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    args = parser.parse_args()
+    source = args.corpus / "data/alp_extended.zstd.parquet"
+    raw = source.read_bytes()
+    reference = pq.ParquetFile(source)
+    root = args.output_dir
+    root.mkdir(parents=True, exist_ok=True)
+    records, provenance = [], []
+    for rg in range(reference.metadata.num_row_groups):
+        plain = reference.read_row_group(rg, columns=["float_plain", "double_plain"])
+        group = reference.metadata.row_group(rg)
+        for col in range(group.num_columns):
+            meta = group.column(col)
+            name = meta.path_in_schema
+            if "_alp_" not in name:
+                continue
+            kind, _, vector_size = name.split("_")
+            width = 4 if kind == "float" else 8
+            schema = reference.schema.column(col)
+            assert schema.max_repetition_level == 0 and schema.max_definition_level in (0, 1)
+            assert meta.compression in ("ZSTD", "UNCOMPRESSED") and not meta.has_dictionary_page
+            offset, row, page = meta.data_page_offset, 0, 0
+            while row < group.num_rows:
+                header, body = header_at(raw, offset)
+                assert header[1] == 0 and header[5][2] == 10, (rg, name, header)
+                count = header[5][1]
+                decoded = raw[body:body + header[3]]
+                if meta.compression == "ZSTD":
+                    decoded = bytes(pa.Codec("zstd").decompress(decoded, header[2]))
+                assert len(decoded) == header[2]
+                values_start = 0
+                if schema.max_definition_level:
+                    values_start = 4 + struct.unpack_from("<I", decoded)[0]
+                payload = decoded[values_start:]
+                expected = plain_bits(plain[kind + "_plain"].slice(row, count), width)
+                nonnull = len(expected) // width
+                assert len(payload) >= 7 and struct.unpack_from("<i", payload, 3)[0] == nonnull
+                assert (1 << payload[2]) == int(vector_size)
+                stem = f"{kind}-rg{rg}-v{vector_size}-p{page}"
+                (root / (stem + ".alp")).write_bytes(payload)
+                (root / (stem + ".plain")).write_bytes(expected)
+                label = f"{kind.upper()} rg{rg} vector{vector_size} {nonnull} values"
+                records.append(f"{stem}\t{width}\t{nonnull}\t{label}")
+                provenance.append({"name": label, "file": stem, "width": width, "count": nonnull,
+                                   "encodedSha256": hashlib.sha256(payload).hexdigest(),
+                                   "plainSha256": hashlib.sha256(expected).hexdigest()})
+                row += count
+                page += 1
+                offset = body + header[3]
+            assert row == group.num_rows
+    assert len(records) == 30, len(records)
+    (root / "cases.tsv").write_text("\n".join(records) + "\n")
+    (root / "provenance.json").write_text(json.dumps({"source": str(source),
+        "sourceSha256": hashlib.sha256(raw).hexdigest(), "pyarrowVersion": pa.__version__,
+        "oracle": "selective PLAIN decode; exact buffer bits from nonnull rows", "cases": provenance}, indent=2) + "\n")
+    print("Extracted 30 official ALP pages and independent PLAIN bit oracles")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_alp_interop.py b/scripts/parquet_alp_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_alp_interop.py
@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Bit-compare the official ALP fixture with its independently written PLAIN columns.
+
+PyArrow need only decode the two PLAIN columns. This still provides an oracle
+when its Parquet reader does not implement ALP. Float values are compared as
+buffer bits, preserving negative zero and NaN signs/payloads.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+
+
+def check_column(actual, expected, width):
+    actual = actual.combine_chunks()
+    expected = expected.combine_chunks()
+    if actual.type != expected.type or len(actual) != len(expected):
+        raise AssertionError("ALP column type or length differs from PLAIN")
+    left = memoryview(actual.buffers()[1])
+    right = memoryview(expected.buffers()[1])
+    word = struct.Struct("<I" if width == 4 else "<Q")
+    checked = 0
+    for row in range(len(expected)):
+        if actual[row].is_valid != expected[row].is_valid:
+            raise AssertionError(f"validity differs at row {row}")
+        if not expected[row].is_valid:
+            continue
+        a = word.unpack_from(left, (actual.offset + row) * width)[0]
+        b = word.unpack_from(right, (expected.offset + row) * width)[0]
+        if a != b:
+            raise AssertionError(f"IEEE bits differ at row {row}: {a:#x} != {b:#x}")
+        checked += 1
+    return {"rows": len(expected), "nonnullBitComparisons": checked,
+            "nulls": expected.null_count}
+
+
+def compare_alp_table(actual, expected):
+    names = {"float_plain", "float_alp_32", "float_alp_1024", "float_alp_4096",
+             "double_plain", "double_alp_32", "double_alp_1024", "double_alp_4096"}
+    if set(actual.column_names) != names:
+        raise AssertionError("unexpected ALP fixture columns")
+    results = {}
+    for kind, width, data_type in [("float", 4, pa.float32()), ("double", 8, pa.float64())]:
+        reference = expected[kind + "_plain"]
+        if reference.type != data_type:
+            raise AssertionError("unexpected reference physical type")
+        for suffix in ["plain", "alp_32", "alp_1024", "alp_4096"]:
+            name = f"{kind}_{suffix}"
+            results[name] = check_column(actual[name], reference, width)
+    return results
+
+
+def check_oracle():
+    for width, data_type, pairs in [
+        (4, pa.float32(), [(0, 0x80000000), (0x7fc0dead, 0x7fc0deae)]),
+        (8, pa.float64(), [(0, 0x8000000000000000), (0x7ff800deadbeef00, 0x7ff800deadbeef01)]),
+    ]:
+        pack = struct.Struct("<I" if width == 4 else "<Q")
+        for left, right in pairs:
+            a = pa.chunked_array([pa.Array.from_buffers(data_type, 1, [None, pa.py_buffer(pack.pack(left))])])
+            b = pa.chunked_array([pa.Array.from_buffers(data_type, 1, [None, pa.py_buffer(pack.pack(right))])])
+            try:
+                check_column(a, b, width)
+            except AssertionError:
+                continue
+            raise AssertionError("bitwise oracle accepted a sign/payload mismatch")
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--corpus", type=Path, required=True)
+    parser.add_argument("--probe", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    check_oracle()
+    source = args.corpus / "data/alp_extended.zstd.parquet"
+    expected = pq.read_table(source, columns=["float_plain", "double_plain"],
+                             page_checksum_verification=True)
+    results = {}
+    with tempfile.TemporaryDirectory(prefix="wireform-parquet-alp-") as directory:
+        work = Path(directory)
+        inputs = work / "inputs"
+        inputs.mkdir()
+        (inputs / source.name).symlink_to(source.resolve())
+        output = work / "decoded"
+        process = subprocess.run([str(args.probe.resolve()), str(inputs),
+                                  "--arrow-output", str(output), "+RTS", "-M512m", "-RTS"],
+                                 capture_output=True, text=True, timeout=60)
+        if process.returncode:
+            raise RuntimeError(process.stdout + process.stderr)
+        with ipc.open_stream(output / (source.name + ".arrows")) as reader:
+            actual = reader.read_all()
+        results = compare_alp_table(actual, expected)
+    report = {"fixture": str(source), "fixtureSha256": hashlib.sha256(source.read_bytes()).hexdigest(),
+              "oracle": "PyArrow selective PLAIN decoding; IEEE buffer bits and nulls compared",
+              "pyarrowVersion": pa.__version__, "columns": results, "passed": True}
+    args.output.write_text(json.dumps(report, indent=2) + "\n")
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_bench_compare.py b/scripts/parquet_bench_compare.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_bench_compare.py
@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Compare the committed Criterion workload with Apache Arrow C++ via pyarrow.
+
+Run the manifest-driven parquet-throughput benchmark first, then export its
+inputs with the benchmark binary's --write-fixtures DIR mode. This driver
+checks the file codec and every value before timing, uses the identical bytes
+for reads, and matches the writer's encoding, nullability, and page settings.
+All timings run sequentially; run with no competing benchmarks or builds.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import statistics
+import subprocess
+import tempfile
+import time
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+N_ROWS = 100_000
+CODECS = ("uncompressed", "snappy", "zstd")
+
+
+def make_dataset() -> pa.Table:
+    schema = pa.schema([
+        pa.field("id", pa.int64(), nullable=False),
+        pa.field("score", pa.float64(), nullable=False),
+        pa.field("name", pa.string(), nullable=False),
+        pa.field("active", pa.bool_(), nullable=False),
+    ])
+    return pa.Table.from_arrays([
+        pa.array(range(N_ROWS), pa.int64()),
+        pa.array([i * 0.5 for i in range(N_ROWS)], pa.float64()),
+        pa.array([f"name_{i % 1000}" for i in range(N_ROWS)], pa.string()),
+        pa.array([i % 2 == 0 for i in range(N_ROWS)], pa.bool_()),
+    ], schema=schema)
+
+
+def load_criterion(path: Path) -> dict[str, float]:
+    doc = json.loads(path.read_text())
+    return {
+        report["reportName"]: report["reportAnalysis"]["anMean"]["estPoint"]
+        for report in doc[2]
+    }
+
+
+def measure(action, iterations: int) -> float:
+    for _ in range(3):
+        action()
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        action()
+        times.append(time.perf_counter() - start)
+    return statistics.mean(times)
+
+
+def write_table(table: pa.Table, codec: str) -> pa.Buffer:
+    sink = pa.BufferOutputStream()
+    kwargs = {"compression_level": 3} if codec == "zstd" else {}
+    pq.write_table(
+        table, sink, compression="none" if codec == "uncompressed" else codec,
+        use_dictionary=False, column_encoding="PLAIN", data_page_version="2.0", write_page_index=False, store_schema=False,
+        row_group_size=N_ROWS, max_rows_per_page=N_ROWS, data_page_size=8 * 1024 * 1024, **kwargs,
+    )
+    return sink.getvalue()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--criterion-json", type=Path,
+                        default=Path("dist-stats/bench-raw/parquet-throughput.json"))
+    parser.add_argument("--fixtures", type=Path, required=True)
+    parser.add_argument("--iterations", type=int, default=25)
+    parser.add_argument("--output", type=Path)
+    parser.add_argument("--parquet-rs-json", type=Path,
+                        help="optional manifest-generated parquet-rs-throughput.json")
+    parser.add_argument("--wireform-bench", type=Path,
+                        help="benchmark binary: also verify C++ output layout and all values before timing")
+    args = parser.parse_args()
+    if args.iterations < 1:
+        parser.error("--iterations must be positive")
+    reference = load_criterion(args.criterion_json)
+    parquet_rs = load_criterion(args.parquet_rs_json) if args.parquet_rs_json else None
+    expected = make_dataset()
+    results = []
+    # Validate reference writer output, not just wireform's input to reads.
+    # Native layout verification runs before any clock starts.
+    with tempfile.TemporaryDirectory(prefix="wireform-cpp-bench-check-") as tmp:
+        for codec in CODECS:
+            encoded = write_table(expected, codec)
+            decoded = pq.read_table(pa.BufferReader(encoded), use_threads=False, pre_buffer=False)
+            if not decoded.equals(expected):
+                raise AssertionError(f"C++ {codec} writer output differs from the full model")
+            (Path(tmp) / f"{codec}.parquet").write_bytes(encoded.to_pybytes())
+        if args.wireform_bench:
+            subprocess.run([str(args.wireform_bench.resolve()), "--verify-fixtures", tmp], check=True)
+    for codec in CODECS:
+        blob = pa.py_buffer((args.fixtures / f"{codec}.parquet").read_bytes())
+        metadata = pq.ParquetFile(pa.BufferReader(blob)).metadata
+        actual_codec = metadata.row_group(0).column(0).compression.lower()
+        if actual_codec != codec:
+            raise AssertionError(f"{codec} fixture actually uses {actual_codec}")
+        if not pq.read_table(pa.BufferReader(blob), use_threads=False, pre_buffer=False).equals(expected):
+            raise AssertionError(f"{codec} fixture has incorrect data")
+        for operation in ("write", "read"):
+            if operation == "write":
+                key = f"write {N_ROWS} rows x 4 cols/{codec}"
+                action = lambda: write_table(expected, codec)
+            else:
+                key = f"read {N_ROWS} rows x 4 cols ({codec})/decode"
+                action = lambda: pq.read_table(pa.BufferReader(blob), use_threads=False,
+                                               pre_buffer=False)
+            wireform_seconds = reference[key]  # Missing evidence must fail.
+            arrow_seconds = measure(action, args.iterations)
+            result = {
+                "operation": operation, "codec": codec,
+                "wireformSeconds": wireform_seconds, "pyarrowSeconds": arrow_seconds,
+                "wireformOverPyarrow": wireform_seconds / arrow_seconds,
+            }
+            if parquet_rs is not None:
+                result.update(parquetRsSeconds=parquet_rs[key],
+                              wireformOverParquetRs=wireform_seconds / parquet_rs[key])
+            results.append(result)
+            print(f"{operation:5} {codec:12} wireform={wireform_seconds * 1000:9.3f} ms "
+                  f"pyarrow={arrow_seconds * 1000:9.3f} ms "
+                  f"ratio={result['wireformOverPyarrow']:.2f}x")
+            if parquet_rs is not None:
+                print(f"      parquet-rs={parquet_rs[key] * 1000:9.3f} ms "
+                      f"wireform/parquet-rs={result['wireformOverParquetRs']:.2f}x")
+    report = {"pyarrowVersion": pa.__version__, "rows": N_ROWS,
+              "iterations": args.iterations,
+              "workload": {"rowGroups": 1, "rowsPerPage": N_ROWS,
+                           "columnsRequired": True, "encoding": "PLAIN",
+                           "dataPageVersion": "2.0", "pageIndex": False,
+                           "readOutput": "materialized Arrow batches",
+                           "statistics": {"wireform": "chunk", "parquetRs": "chunk",
+                                          "pyarrow": "page and chunk"}},
+              "results": results}
+    if args.output:
+        args.output.write_text(json.dumps(report, indent=2) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/parquet_boolean_interop.py b/scripts/parquet_boolean_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_boolean_interop.py
@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Check packed BOOLEAN PLAIN/RLE/dictionary pages against independent readers.
+
+The Boolean payloads and hybrid streams below are built directly from the
+published encoding grammar, independently of wireform's writer. DuckDB
+validates all cases; PyArrow validates PLAIN/RLE and reports its Boolean
+dictionary limitation explicitly. wireform output is compared through IPC.
+"""
+import argparse
+import itertools
+from pathlib import Path
+import subprocess
+import tempfile
+
+import duckdb
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from parquet_aggregate_interop import TType, column_metadata, footer, groups
+from parquet_delta_interop import encoded_struct
+
+
+def varint(value):
+    out = bytearray()
+    while value >= 128:
+        out.append((value & 127) | 128)
+        value >>= 7
+    out.append(value)
+    return bytes(out)
+
+
+def bits(values):
+    out = bytearray((len(values) + 7) // 8)
+    for index, value in enumerate(values):
+        if value:
+            byte_index, bit_index = divmod(index, 8)
+            out[byte_index] |= 1 << bit_index
+    if values and len(values) % 8:
+        out[-1] |= (255 << (len(values) % 8)) & 255  # Nonzero unused padding.
+    return bytes(out)
+
+
+def hybrid(values):
+    out = bytearray()
+    for value, run in itertools.groupby(values):
+        length = sum(map(lambda _: 1, run))
+        out.extend(varint(length << 1))
+        out.append(int(value))
+    return bytes(out)
+
+
+def length_prefix(data):
+    return len(data).to_bytes(4, 'little') + data
+
+
+def page(version, encoding, nullable, values):
+    present = list(filter(lambda x: x is not None, values))
+    definitions = list(map(lambda x: x is not None, values))
+    levels = hybrid(definitions) if nullable else b''
+    if encoding == 0:
+        payload = bits(present)
+    elif encoding == 3:
+        payload = length_prefix(hybrid(present))
+    else:
+        payload = b'\x01' + hybrid(present)  # Entry 0=False, entry 1=True.
+    if version == 1:
+        body = (length_prefix(levels) if nullable else b'') + payload
+        header = {1: (TType.I32, 0), 5: (TType.STRUCT, {
+            1: (TType.I32, len(values)), 2: (TType.I32, encoding),
+            3: (TType.I32, 3), 4: (TType.I32, 3)})}
+    else:
+        body = levels + payload
+        header = {1: (TType.I32, 3), 8: (TType.STRUCT, {
+            1: (TType.I32, len(values)), 2: (TType.I32, len(values)-len(present)),
+            3: (TType.I32, len(values)), 4: (TType.I32, encoding),
+            5: (TType.I32, len(levels)), 6: (TType.I32, 0),
+            7: (TType.BOOL, False)})}
+    header[2] = header[3] = TType.I32, len(body)
+    return encoded_struct(header) + body
+
+
+def write_case(root, name, version, encoding, nullable, sizes):
+    values = []
+    pages = []
+    for size in sizes:
+        start = len(values)
+        part = []
+        for index in range(start, start + size):
+            part.append(None if nullable and index % 5 == 0 else bool((index // 19) % 2))
+        pages.append(page(version, encoding, nullable, part))
+        values.extend(part)
+    expected = pa.Table.from_arrays([pa.array(values, type=pa.bool_())], schema=pa.schema([pa.field('x', pa.bool_(), nullable=nullable)]))
+    seed = root / 'seed.parquet'
+    pq.write_table(expected, seed, compression='NONE', use_dictionary=False, write_statistics=False)
+    _, metadata = footer(seed)
+    dictionary = b''
+    if encoding in (2, 8):
+        dictionary = encoded_struct({1: (TType.I32, 2), 2: (TType.I32, 1), 3: (TType.I32, 1), 7: (TType.STRUCT, {1: (TType.I32, 2), 2: (TType.I32, 0)})}) + b'\x02'
+    content = dictionary + b''.join(pages)
+    column = column_metadata(metadata)
+    encodings = {encoding}
+    if dictionary:
+        encodings.add(0)
+    if nullable:
+        encodings.add(3)
+    column[2] = TType.LIST, (TType.I32, list(map(lambda value: (TType.I32, value), sorted(encodings))))
+    column[6] = column[7] = TType.I64, len(content)
+    column[9] = TType.I64, 4 + len(dictionary)
+    column.pop(13, None)
+    if dictionary:
+        column[11] = TType.I64, 4
+    else:
+        column.pop(11, None)
+    group = groups(metadata)[0][1]
+    group[2] = group[6] = TType.I64, len(content)
+    encoded = encoded_struct(metadata[1])
+    path = root / (name + '.parquet')
+    path.write_bytes(b'PAR1' + content + encoded + len(encoded).to_bytes(4, 'little') + b'PAR1')
+    return path, expected
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--reader', type=Path, required=True)
+    args = parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix='wireform-boolean-interop-') as directory:
+        root = Path(directory)
+        inputs = root / 'inputs'
+        inputs.mkdir()
+        cases = []
+        for version, encoding, nullable, size in itertools.product((1, 2), (0, 3, 8, 2), (False, True), (1, 7, 8, 9, 65, 1025)):
+            name = f'v{version}-enc{encoding}-null{int(nullable)}-n{size}'
+            cases.append(write_case(inputs, name, version, encoding, nullable, (size, size+1, 2)))
+        (inputs / 'seed.parquet').unlink()
+        for version, nullable, size in itertools.product(('1.0', '2.0'), (False, True), (7, 129)):
+            vals = []
+            for index in range(size):
+                vals.append(None if nullable and index % 5 == 0 else bool((index // 19) % 2))
+            expected = pa.Table.from_arrays([pa.array(vals, type=pa.bool_())], schema=pa.schema([pa.field('x', pa.bool_(), nullable=nullable)]))
+            path = inputs / f'pyarrow-rle-v{version}-null{int(nullable)}-n{size}.parquet'
+            pq.write_table(expected, path, compression='NONE', use_dictionary=False, column_encoding={'x': 'RLE'}, data_page_version=version, max_rows_per_page=17, write_batch_size=17)
+            cases.append((path, expected))
+        con = duckdb.connect(config={'threads': 1})
+        limitations = 0
+        try:
+            for path, expected in cases:
+                actual = list(map(lambda row: row[0], con.execute('SELECT x FROM read_parquet(?)', [str(path)]).fetchall()))
+                assert actual == expected['x'].to_pylist(), path.name
+                try:
+                    assert pq.read_table(path).equals(expected), path.name
+                except (pa.ArrowNotImplementedError, OSError) as error:
+                    assert '-enc2-' in path.name or '-enc8-' in path.name, str(error)
+                    assert 'boolean' in str(error).lower() and 'not implemented' in str(error).lower(), str(error)
+                    limitations += 1
+        finally:
+            con.close()
+        output = root / 'ipc'
+        subprocess.run([str(args.reader.resolve()), str(inputs), '--arrow-output', str(output)], check=True)
+        for path, expected in cases:
+            with ipc.open_stream(output / (path.name + '.arrows')) as reader:
+                actual = reader.read_all()
+            assert actual.equals(expected), path.name
+        print(f'{len(cases)} BOOLEAN fixtures verified against DuckDB and wireform IPC; {len(cases)-limitations} also verified by PyArrow; {limitations} PyArrow Boolean-dictionary limitations')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_codec_interop.py b/scripts/parquet_codec_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_codec_interop.py
@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""All enabled codecs: independent C++ pages, native writer pages and errors.
+
+LZO/Hadoop LZ4 have their own independent interop drivers. This suite covers
+UNCOMPRESSED, GZIP, SNAPPY, ZSTD, LZ4_RAW and BROTLI, including dictionaries,
+both page versions and explicit uncompressed V2 value sections.
+"""
+import argparse
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from parquet_lzo_interop import Node, decode, encode, transcode, signed_crc
+from parquet_metadata_interop import parse
+
+CODECS = {"uncompressed":0,"snappy":1,"gzip":2,"brotli":4,"zstd":6,"lz4":7}
+
+
+def run(command, succeeds=True):
+    result = subprocess.run(list(map(str, command)),capture_output=True,text=True,timeout=120)
+    if succeeds:
+        assert result.returncode == 0, (command,result.stdout,result.stderr)
+    else:
+        assert result.returncode > 0 and "FAIL" in result.stdout, (command,result.stdout,result.stderr)
+    return result
+
+
+def read_output(directory, name):
+    with ipc.open_stream(directory / (name + ".arrows")) as reader:
+        table = reader.read_all()
+    table.validate(full=True)
+    return table
+
+
+def same_type(left, right):
+    if pa.types.is_list(left) and pa.types.is_list(right):
+        return left.value_field.nullable == right.value_field.nullable and same_type(left.value_type,right.value_type)
+    if pa.types.is_struct(left) and pa.types.is_struct(right):
+        return len(left)==len(right) and all(a.name==b.name and a.nullable==b.nullable and same_type(a.type,b.type) for a,b in zip(left,right))
+    return left == right
+
+
+def same_table(actual, expected):
+    # Standard Parquet LIST wrapper names are positional; preserve all logical
+    # types, nullable declarations, struct names and actual values.
+    return actual.column_names==expected.column_names and all(a.nullable==b.nullable and same_type(a.type,b.type) for a,b in zip(actual.schema,expected.schema)) and actual.to_pylist()==expected.to_pylist()
+
+
+def native_expected(shape):
+    nullable = shape != "required"
+    schema = pa.schema([pa.field("i",pa.int32(),nullable),pa.field("s",pa.string(),nullable),pa.field("b",pa.bool_(),nullable),pa.field("d",pa.float64(),nullable)])
+    if shape == "empty":
+        values=[[],[],[],[]]
+    elif shape == "allnull":
+        values=list(map(lambda _: [None]*160, schema))
+    elif shape == "mixed":
+        values=[[-2**31,None,0,2**31-1,None]*32,["κόσμε",None,"","alpha",None]*32,[True,None,False,True,None]*32,[-1.5,None,0,1.25,None]*32]
+    else:
+        values=[[-2**31,-1,0,2**31-1,1]*32,["κόσμε","beta","","alpha","omega"]*32,[True,False,False,True,False]*32,[-1.5,-1,0,1.25,2]*32]
+    return pa.Table.from_arrays(list(map(lambda pair: pa.array(pair[0],type=pair[1].type),zip(values,schema))),schema=schema)
+
+
+def corrupt_page(source,target,mode,codec):
+    parsed=parse(source)
+    metadata=parsed.footer
+    column=metadata.value[4].value[0].value[1].value[0].value[3].value
+    offset=column[9].value
+    assert offset == 4 and 11 not in column
+    decoded=decode(parsed.prefix[offset:]);header=decoded.node
+    body=parsed.prefix[offset+decoded.consumed:offset+decoded.consumed+header.value[3].value]
+    if mode == "large-size":
+        header.value[2].value += 1
+    elif mode == "small-size":
+        header.value[2].value -= 1
+    elif mode == "truncated":
+        body=body[:-1]
+    elif mode == "trailing":
+        body += b"trailing"
+    else:
+        assert mode in ("null-raw","null-compressed")
+        body=b"\x06\x00invalid codec bytes"
+        header.value[1]=Node(TType.I32,3)
+        header.value.pop(5,None)
+        header.value[8]=Node(TType.STRUCT,{1:Node(TType.I32,3),2:Node(TType.I32,3),3:Node(TType.I32,3),4:Node(TType.I32,0),5:Node(TType.I32,2),6:Node(TType.I32,0),7:Node(TType.BOOL,mode=="null-compressed")})
+        header.value[2]=Node(TType.I32,2)
+        if 12 in column:
+            column[12]=Node(TType.STRUCT,{3:Node(TType.I64,3)})
+    header.value[3]=Node(TType.I32,len(body))
+    header.value[4]=Node(TType.I32,signed_crc(body))
+    encoded=encode(header)
+    column[6]=Node(TType.I64,len(encoded)+header.value[2].value)
+    column[7]=Node(TType.I64,len(encoded)+len(body))
+    column[4]=Node(TType.I32,codec)
+    group=metadata.value[4].value[0].value
+    group[2]=Node(TType.I64,column[6].value)
+    group[6]=Node(TType.I64,column[7].value)
+    footer=encode(metadata)
+    target.write_bytes(b"PAR1"+encoded+body+footer+struct.pack("<I",len(footer))+b"PAR1")
+
+
+def main():
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reader",type=Path,required=True)
+    parser.add_argument("--writer",type=Path,required=True)
+    parser.add_argument("--output",type=Path,required=True)
+    parser.add_argument("--expect-codecs",nargs="+",default=list(CODECS))
+    args=parser.parse_args()
+    codecs=args.expect_codecs
+    assert set(codecs)<=CODECS.keys()
+    for name in codecs:
+        if name != "uncompressed":
+            assert pa.Codec.is_available("lz4_raw" if name=="lz4" else name),name
+    with tempfile.TemporaryDirectory(prefix="codec-interop-") as directory:
+        work=Path(directory)
+        incoming,decoded,native,scratch=(work/name for name in ("incoming","decoded","native","scratch"))
+        for path in (incoming,decoded,native,scratch):path.mkdir()
+        tables={
+            "scalar":pa.table({"i":pa.array([-2**31,None,0,2**31-1,-1]*8,pa.int32()),"s":pa.array(["κόσμε",None,"","alpha","omega"]*8),"b":pa.array([True,None,False,True,False]*8)}),
+            "nested":pa.table({"items":pa.array([None,[],[None,1,2],[3]]*8,pa.list_(pa.int32())),"s":pa.array([None,{"x":1},{"x":None},{"x":-1}]*8,pa.struct([("x",pa.int64())]))}),
+            "allnull":pa.table({"x":pa.array([None]*40,pa.int32())}),
+            "empty":pa.table({"x":pa.array([],pa.int32())}),
+        }
+        expected={}
+        for codec in codecs:
+            for family,table in tables.items():
+                for version in ("1.0","2.0"):
+                    for dictionary in (False,True):
+                        name=f"{codec}-{family}-v{version}-dict{int(dictionary)}"
+                        path=incoming/(name+".parquet")
+                        pq.write_table(table,path,compression="NONE" if codec=="uncompressed" else codec,data_page_version=version,use_dictionary=dictionary,row_group_size=13,write_batch_size=5,max_rows_per_page=5,write_page_index=False,write_page_checksum=True)
+                        expected[path.name]=table
+                        if version=="2.0":
+                            raw=incoming/(name+"-raw-values.parquet")
+                            transcode(path,raw,CODECS[codec],None,scratch,v2_uncompressed=True,require_source_codec=CODECS[codec],expected_version=2)
+                            assert pq.read_table(raw).equals(table,check_metadata=False)
+                            expected[raw.name]=table
+        run([args.reader,incoming,"--arrow-output",decoded])
+        for name,table in expected.items():
+            actual=read_output(decoded,name)
+            assert same_table(actual,table),(name,actual,table)
+        run([args.writer,"--codec-profiles",native])
+        paths=sorted(native.glob("*.parquet"))
+        assert len(paths)==len(codecs)*16,(len(paths),len(codecs)*16)
+        for path in paths:
+            codec,version,shape,indexed=path.stem.split("-")
+            assert codec in codecs
+            wanted=native_expected(shape)
+            actual=pq.read_table(path)
+            actual.validate(full=True)
+            assert actual.equals(wanted,check_metadata=False),(path.name,actual,wanted)
+            metadata=parse(path).footer
+            for group in metadata.value[4].value:
+                for chunk in group.value[1].value:
+                    assert chunk.value[3].value[4].value==CODECS[codec]
+        invalid=work/"invalid";invalid.mkdir()
+        rejected=0
+        for codec in codecs:
+            seed=work/(codec+"-seed.parquet")
+            pq.write_table(pa.table({"x":pa.array([1,2,3],pa.int32())}),seed,compression="NONE" if codec=="uncompressed" else codec,use_dictionary=False,write_page_index=False,write_page_checksum=True)
+            for mode in ("large-size","small-size","truncated","trailing","null-raw","null-compressed"):
+                path=invalid/(codec+"-"+mode+".parquet")
+                corrupt_page(seed,path,mode,CODECS[codec])
+                # Isolate each failure; an invalid file must produce a handled
+                # decoder failure, not a signal, timeout or partial output.
+                one=work/("case-"+str(rejected));one.mkdir();(one/path.name).symlink_to(path)
+                run([args.reader,one],False)
+                rejected+=1
+        report={"pyarrow":pa.__version__,"codecs":codecs,"incomingFiles":len(expected),"nativeWriterFiles":len(paths),"malformedRejected":rejected,"failures":0,"skips":0}
+        args.output.write_text(json.dumps(report,indent=2)+"\n");print(json.dumps(report,indent=2))
+
+if __name__=="__main__":main()
diff --git a/scripts/parquet_corpus.py b/scripts/parquet_corpus.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_corpus.py
@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Compare Wireform with pyarrow on Apache's parquet-testing/data corpus.
+
+Pass a built wireform-parquet-reverse-probe binary and a checkout of
+https://github.com/apache/parquet-testing. Every discovered fixture gets a
+result, including explicit reference rejections and resource-limit skips.
+A successful decoder call alone is insufficient: values must also agree.
+"""
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+from dataclasses import dataclass
+import json
+import math
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from parquet_alp_interop import compare_alp_table
+from parquet_timestamp_interop import physical_timestamp_copy
+
+# These normal corpus entries deliberately violate integrity/schema rules.
+# Other reference rejections (new encodings or wide timestamps) remain unknown,
+# and must not be reported as evidence that a file is malformed.
+KNOWN_INVALID = {
+    "data/datapage_v1-corrupt-checksum.parquet",
+    "data/rle-dict-uncompressed-corrupt-checksum.parquet",
+    "data/incorrect_map_schema.parquet",
+}
+
+
+@dataclass
+class Difference:
+    status: str
+    detail: str
+
+
+def same_value(left, right):
+    if isinstance(left, float) and isinstance(right, float):
+        return left == right or (math.isnan(left) and math.isnan(right))
+    if isinstance(left, dict) and isinstance(right, dict):
+        return left.keys() == right.keys() and all(same_value(left[k], right[k]) for k in left)
+    if isinstance(left, (list, tuple)) and isinstance(right, (list, tuple)):
+        return len(left) == len(right) and all(same_value(a, b) for a, b in zip(left, right))
+    return left == right
+
+
+def compare(actual, expected):
+    if actual.column_names != expected.column_names:
+        return Difference("schema-mismatch", f"column names differ: {actual.column_names} != {expected.column_names}")
+    if actual.num_rows != expected.num_rows:
+        return Difference("value-mismatch", f"row counts differ: {actual.num_rows} != {expected.num_rows}")
+    for name in expected.column_names:
+        left, right = actual[name], expected[name]
+        compatible_strings = (
+            (pa.types.is_string(left.type) or pa.types.is_large_string(left.type))
+            and (pa.types.is_string(right.type) or pa.types.is_large_string(right.type))
+        )
+        compatible_binary = (
+            (pa.types.is_binary(left.type) or pa.types.is_large_binary(left.type))
+            and (pa.types.is_binary(right.type) or pa.types.is_large_binary(right.type))
+        )
+        if left.type != right.type and not (compatible_strings or compatible_binary):
+            return Difference("schema-mismatch", f"{name}: logical types differ: {left.type} != {right.type}")
+        if left.equals(right):
+            continue
+        for row, (a, b) in enumerate(zip(left.to_pylist(), right.to_pylist())):
+            if not same_value(a, b):
+                return Difference("value-mismatch", f"{name}, row {row}: {a!r} != {b!r}")
+    return None
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--corpus", type=Path, required=True)
+    parser.add_argument("--probe", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--max-uncompressed-mib", type=int, default=128)
+    parser.add_argument("--timeout", type=float, default=30)
+    parser.add_argument("--include-large-map", action="store_true",
+                        help="also verify the >2GiB map through LargeUtf8 projection and one-row C++ buffer hashes (several GiB RAM)")
+    parser.add_argument("--include-bad-data", action="store_true",
+                        help="also probe adversarial fixtures, even when the reference rejects them")
+    parser.add_argument("--max-heap-mib", type=int, default=512,
+                        help="GHC heap cap for each probe process (requires its -rtsopts build)")
+    args = parser.parse_args()
+    paths = sorted((args.corpus / "data").rglob("*.parquet"))
+    if args.include_bad_data:
+        paths += sorted((args.corpus / "bad_data").rglob("*.parquet"))
+    if args.max_heap_mib <= 0:
+        parser.error("--max-heap-mib must be positive")
+    preflight = subprocess.run([str(args.probe.resolve()), "--help", "+RTS",
+                               f"-M{args.max_heap_mib}m", "-RTS"], capture_output=True, text=True)
+    if preflight.returncode:
+        parser.error("probe cannot enable its memory cap: " + preflight.stderr.strip())
+    if not paths:
+        parser.error("no corpus Parquet fixtures found")
+    results = []
+    with tempfile.TemporaryDirectory(prefix="wireform-parquet-corpus-") as directory:
+        work = Path(directory)
+        for number, source in enumerate(paths):
+            result = {"file": str(source.relative_to(args.corpus))}
+            bad_data = (args.corpus / "bad_data") in source.parents
+            expected_invalid = bad_data or result["file"] in KNOWN_INVALID
+            expected = None
+            try:
+                metadata = pq.ParquetFile(source).metadata
+                size = sum(metadata.row_group(r).total_byte_size for r in range(metadata.num_row_groups))
+                if args.include_large_map and source.name == "large_string_map.brotli.parquet":
+                    large_report = work / "large-map-result.json"
+                    large = subprocess.run(
+                        [sys.executable, str(Path(__file__).with_name("parquet_large_map_interop.py")),
+                         "--reader", str(args.probe.resolve()), "--fixture", str(source.resolve()),
+                         "--output", str(large_report)], capture_output=True, text=True, timeout=360)
+                    if large.returncode == 0:
+                        evidence = json.loads(large_report.read_text())
+                        assert evidence["nativeAndReferenceAgree"] and evidence["failures"] == 0 and evidence["skips"] == 0
+                        result.update(status="passed", largeOffsetProjection=evidence)
+                    else:
+                        result.update(status="decode-failed", detail=(large.stdout + large.stderr)[-4000:])
+                    results.append(result)
+                    print(result, flush=True)
+                    continue
+                if size > args.max_uncompressed_mib * 1024 * 1024:
+                    result.update(status="resource-limit", detail=f"{size} uncompressed bytes")
+                    results.append(result)
+                    print(result, flush=True)
+                    continue
+                alp_fixture = source.name == "alp_extended.zstd.parquet"
+                physical_timestamp = work / f"physical-timestamps-{number}.parquet"
+                timestamp_storage = physical_timestamp_copy(source, physical_timestamp)
+                if timestamp_storage:
+                    result["timestampPhysicalOracle"] = "original pages; annotation/type-only adaptation decoded by C++"
+                expected = pq.read_table(physical_timestamp if timestamp_storage else source, page_checksum_verification=True,
+                                         columns=["float_plain", "double_plain"] if alp_fixture else None)
+            except Exception as error:
+                result["referenceError"] = str(error)
+            root = work / str(number)
+            root.mkdir()
+            (root / source.name).symlink_to(source.resolve())
+            output = root / "decoded"
+            try:
+                process = subprocess.run([str(args.probe.resolve()), str(root), "--arrow-output", str(output),
+                                          "+RTS", f"-M{args.max_heap_mib}m", "-RTS"],
+                                         capture_output=True, text=True, timeout=args.timeout)
+                if process.returncode:
+                    detail = (process.stdout + process.stderr)[-4000:]
+                    resource_failure = any(message in detail.lower() for message in
+                                           ("heap exhausted", "heap overflow", "heap limit")) or process.returncode < 0
+                    status = ("resource-failed" if resource_failure else "harness-failed"
+                              if "  FAIL " not in detail else "invalid-rejected"
+                              if expected_invalid and expected is None else "reference-rejected"
+                              if expected is None else "decode-failed")
+                    result.update(status=status, detail=detail)
+                elif expected is None:
+                    result.update(status="invalid-accepted" if expected_invalid else "unverified-accepted",
+                                  detail="reference rejected this fixture; no reference values are available")
+                else:
+                    with ipc.open_stream(output / (source.name + ".arrows")) as reader:
+                        actual = reader.read_all()
+                    if alp_fixture:
+                        result["bitwisePlainOracle"] = compare_alp_table(actual, expected)
+                        difference = None
+                    else:
+                        difference = compare(actual, expected)
+                    result.update(status=difference.status if difference else "passed")
+                    if difference:
+                        result["detail"] = difference.detail
+                    elif bad_data and source.parent.name == "variants":
+                        # These files deliberately store unannotated binary
+                        # pairs. Raw reads must preserve their bytes; opt in
+                        # to Variant semantics in a separate production API.
+                        semantic = subprocess.run(
+                            [str(args.probe.resolve()), "--variant-payloads", str(source.resolve()),
+                             "+RTS", f"-M{args.max_heap_mib}m", "-RTS"],
+                            capture_output=True, text=True, timeout=args.timeout)
+                        message = semantic.stdout + semantic.stderr
+                        if semantic.returncode == 1 and "Parquet.Variant:" in message:
+                            result.update(status="variant-payload-rejected", rawStorage="passed",
+                                          variantPayload="resource-rejected" if "limit exceeded" in message else "invalid-rejected",
+                                          detail=message.strip())
+                        else:
+                            result.update(status="variant-semantic-failed", detail=message.strip(),
+                                          semanticReturnCode=semantic.returncode)
+            except subprocess.TimeoutExpired:
+                result.update(status="timeout")
+            except Exception as error:
+                result.update(status="comparison-failed", detail=str(error))
+            results.append(result)
+            print(result, flush=True)
+    counts = dict(Counter(r["status"] for r in results))
+    revision = subprocess.run(["git", "-C", str(args.corpus), "rev-parse", "HEAD"],
+                              capture_output=True, text=True, check=True).stdout.strip()
+    report = {"corpusRevision": revision, "pyarrowVersion": pa.__version__,
+              "counts": counts, "results": results}
+    args.output.write_text(json.dumps(report, indent=2) + "\n")
+    print(counts)
+    return int(any(r["status"] not in ("passed", "reference-rejected", "invalid-rejected", "variant-payload-rejected") for r in results))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/parquet_decimal_interop.py b/scripts/parquet_decimal_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_decimal_interop.py
@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Check decimal values, signed bounds, indexes and filtering in three engines."""
+import argparse
+from decimal import Decimal
+from pathlib import Path
+import subprocess
+import tempfile
+
+import duckdb
+import polars as pl
+import pyarrow.parquet as pq
+from parquet_statistics_interop import read_value, TCompactProtocol, TMemoryBuffer, TType
+
+GROUPS = [[1,127,128,255,256,1000],[-1000,-256,-129,-128,-1],[-999999,0,999999]]
+
+
+def read_struct(raw, offset):
+    return read_value(TCompactProtocol(TMemoryBuffer(raw[offset:])), TType.STRUCT)
+
+
+def physical(integer, storage):
+    if storage in ('i32', 'i64'):
+        return integer.to_bytes(4 if storage == 'i32' else 8, 'little', signed=True)
+    # The fixture intentionally sign-extends -1 to test equivalent encodings.
+    if integer == -1:
+        return b'\xff\xff'
+    width = max(1, (integer.bit_length() + 8) // 8)
+    while True:
+        try:
+            encoded = integer.to_bytes(width, 'big', signed=True)
+        except OverflowError:
+            width += 1
+            continue
+        if width > 1:
+            try:
+                integer.to_bytes(width - 1, 'big', signed=True)
+            except OverflowError:
+                return encoded
+            width -= 1
+        else:
+            return encoded
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--probe', required=True, type=Path)
+    args = parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix='wireform-parquet-decimal-') as directory:
+        root = Path(directory)
+        subprocess.run([str(args.probe.resolve()), '--decimal', str(root)], check=True)
+        paths = sorted(root.glob('*.parquet'))
+        assert len(paths) == 24, len(paths)
+        for path in paths:
+            storage, nullability, version, codec = path.stem.split('-')
+            nullable = nullability == 'optional'
+            expected_groups = [[Decimal(n).scaleb(-2) for n in numbers] for numbers in GROUPS]
+            if nullable:
+                expected_groups = [[None, *values, None] for values in expected_groups]
+            expected = [value for group in expected_groups for value in group]
+            table = pq.read_table(path)
+            assert table['x'].to_pylist() == expected, path.name
+            assert table.schema.field('x').nullable == nullable, path.name
+            polars = pl.read_parquet(path)
+            assert polars['x'].to_list() == expected, path.name
+            raw = path.read_bytes()
+            footer_size = int.from_bytes(raw[-8:-4], 'little')
+            footer = read_struct(raw, len(raw) - 8 - footer_size)
+            leaf = footer[2][1]
+            assert leaf[6] == 5 and leaf[7] == 2 and leaf[8] == 6, (path.name, leaf)
+            metadata = pq.ParquetFile(path).metadata
+            for number, group in enumerate(footer[4]):
+                chunk = group[1][0]
+                stats = chunk[3][12]
+                assert stats[7] is True and stats[8] is True, (path.name, "exact bounds")
+                low, high = min(GROUPS[number]), max(GROUPS[number])
+                assert (stats[6], stats[5]) == (physical(low, storage), physical(high, storage)), (path.name, stats)
+                assert stats[3] == (2 if nullable else 0), path.name
+                if storage == 'bytes':
+                    assert 1 not in stats and 2 not in stats, path.name
+                column_index = read_struct(raw, chunk[6])
+                assert column_index[2] == [stats[6]] and column_index[3] == [stats[5]], path.name
+                reference = metadata.row_group(number).column(0).statistics
+                assert (reference.min, reference.max) == (Decimal(low).scaleb(-2), Decimal(high).scaleb(-2)), path.name
+            connection = duckdb.connect()
+            try:
+                assert connection.execute('SELECT x FROM read_parquet(?)', [str(path)]).fetchall() == [(v,) for v in expected], path.name
+                # These literals cross sign and byte-width boundaries. Incorrect
+                # lexicographic bounds would discard row groups containing them.
+                for operator, literal in [('=', Decimal('1.28')),('=', Decimal('-1.29')),
+                                          ('=', Decimal('-0.01')),('>=', Decimal('0.01')),
+                                          ('<', Decimal('0')),('>', Decimal('9999'))]:
+                    comparison = {'=': lambda a,b:a==b, '>=':lambda a,b:a>=b,
+                                  '<':lambda a,b:a<b, '>':lambda a,b:a>b}[operator]
+                    wanted = [v for v in expected if v is not None and comparison(v,literal)]
+                    arrow_operator = '==' if operator == '=' else operator
+                    assert pq.read_table(path, filters=[('x',arrow_operator,literal)])['x'].to_pylist() == wanted, (path.name,operator,literal,'pyarrow')
+                    assert connection.execute(f'SELECT x FROM read_parquet(?) WHERE x {operator} ?', [str(path),literal]).fetchall() == [(v,) for v in wanted], (path.name,operator,literal,'duckdb')
+                    expression = {'=':pl.col('x')==literal, '>=':pl.col('x')>=literal,
+                                  '<':pl.col('x')<literal, '>':pl.col('x')>literal}[operator]
+                    assert pl.scan_parquet(path).filter(expression).collect()['x'].to_list() == wanted, (path.name,operator,literal,'polars')
+            finally:
+                connection.close()
+            print('PASS', path.name)
+        print('24 decimal files: values, signed bounds, page indexes and six pushed filters verified with Apache Thrift, PyArrow, DuckDB and Polars')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_delta_interop.py b/scripts/parquet_delta_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_delta_interop.py
@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Check real integer delta encoder bytes with three independent readers.
+
+Apache Thrift supplies the page framing. Expected signed and unsigned values
+come from separate Python boundary/LCG fixtures, never Wireform's decoder.
+"""
+
+import argparse
+from pathlib import Path
+import subprocess
+import tempfile
+
+import duckdb
+import polars as pl
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+
+from parquet_aggregate_interop import (
+    TCompactProtocol, TMemoryBuffer, TType, column_metadata, footer, groups,
+    write_node,
+)
+
+
+def datasets(bits):
+    low, high = -(2**(bits - 1)), 2**(bits - 1) - 1
+    cases = {
+        'minimum': [low],
+        'maximum': [high],
+        'constant-129': [low] * 129,
+        'mixed-sign-delta': [0, low, low + 1],
+        'wrap-up': [low, high, low],
+        'wrap-down': [high, low, high],
+        'step-up': [low, high],
+        'step-down': [high, low],
+        'edges-257': ([low, low + 1, high, high - 1, 0, -1, 1] * 37)[:257],
+    }
+    random_values = []
+    state = 0x12345678 if bits == 32 else 0x123456789abcdef0
+    multiplier = 1664525 if bits == 32 else 6364136223846793005
+    increment = 1013904223 if bits == 32 else 1442695040888963407
+    mask = 2**bits - 1
+    for _ in range(513):
+        random_values.append(state if state < 2**(bits - 1) else state - 2**bits)
+        state = (state * multiplier + increment) & mask
+    cases['random-513'] = random_values
+    for count in (31, 32, 33, 127, 128, 129, 130):
+        cases[f'alternating-{count}'] = ([low, high] * ((count + 1) // 2))[:count]
+    for width in range(1, bits + 1):
+        mask = 2**width - 1
+        count = 2 + width % 31
+        offsets = [0, 2**(width - 1), mask] + [104729 & mask, 7 & mask] * 16
+        rows = [0]
+        for offset in offsets[:count]:
+            rows.append((rows[-1] + low + offset - low) % (2**bits) + low)
+        cases[f'bitwidth-{width}'] = rows
+    return cases
+
+
+def encoded_struct(fields):
+    transport = TMemoryBuffer()
+    write_node(TCompactProtocol(transport), (TType.STRUCT, fields))
+    return transport.getvalue()
+
+
+def framed_file(seed, destination, payload, count, version):
+    _, metadata = footer(seed)
+    if version == 1:
+        page = {1: (TType.I32, count), 2: (TType.I32, 5),
+                3: (TType.I32, 3), 4: (TType.I32, 3)}
+        header = {1: (TType.I32, 0), 5: (TType.STRUCT, page)}
+    else:
+        page = {1: (TType.I32, count), 2: (TType.I32, 0),
+                3: (TType.I32, count), 4: (TType.I32, 5),
+                5: (TType.I32, 0), 6: (TType.I32, 0),
+                7: (TType.BOOL, False)}
+        header = {1: (TType.I32, 3), 8: (TType.STRUCT, page)}
+    header[2] = TType.I32, len(payload)
+    header[3] = TType.I32, len(payload)
+    chunk = encoded_struct(header) + payload
+    column = column_metadata(metadata)
+    column[2] = TType.LIST, (TType.I32, [(TType.I32, 5), (TType.I32, 3)])
+    column[6] = TType.I64, len(chunk)
+    column[7] = TType.I64, len(chunk)
+    column[9] = TType.I64, 4
+    column.pop(11, None)  # No dictionary page.
+    column.pop(13, None)  # Discard the seed's PLAIN encoding statistics.
+    group = groups(metadata)[0][1]
+    group[2] = TType.I64, len(chunk)
+    group[6] = TType.I64, len(chunk)
+    encoded_footer = encoded_struct(metadata[1])
+    destination.write_bytes(b'PAR1' + chunk + encoded_footer
+                            + len(encoded_footer).to_bytes(4, 'little') + b'PAR1')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--probe', required=True, type=Path)
+    parser.add_argument('--reader', type=Path)
+    args = parser.parse_args()
+    checked = 0
+    expected_tables = {}
+    with tempfile.TemporaryDirectory(prefix='wireform-parquet-delta-') as directory:
+        root = Path(directory)
+        connection = duckdb.connect(config={'threads': 1})
+        try:
+            for bits in (32, 64):
+                cases = datasets(bits)
+                raw = root / f'raw{bits}'
+                subprocess.run([str(args.probe.resolve()), f'--delta-int{bits}', str(raw)], check=True)
+                assert len(list(raw.glob('*.bin'))) == len(cases)
+                for name, signed_values in cases.items():
+                    payload = (raw / (name + '.bin')).read_bytes()
+                    for unsigned in (False, True):
+                        typ = getattr(pa, f'uint{bits}' if unsigned else f'int{bits}')()
+                        expected = list(map(lambda value: value & (2**bits - 1), signed_values)) if unsigned else signed_values
+                        table = pa.Table.from_arrays([pa.array(expected, typ)],
+                            schema=pa.schema([pa.field('x', typ, nullable=False)]))
+                        seed = root / 'seed.parquet'
+                        pq.write_table(table, seed, version='2.6', compression='NONE',
+                                       use_dictionary=False, write_statistics=False)
+                        for version in (1, 2):
+                            path = root / f'{name}-{"u" if unsigned else "i"}{bits}-v{version}.parquet'
+                            framed_file(seed, path, payload, len(expected), version)
+                            try:
+                                actual = pq.read_table(path, use_threads=False)
+                            except Exception as error:
+                                raise AssertionError(f'{path.name}: PyArrow could not decode encoder output') from error
+                            assert actual.equals(table), (path.name, 'PyArrow values/types', actual.to_pydict(), table.to_pydict())
+                            rows = connection.execute('SELECT x FROM read_parquet(?)', [str(path)]).fetchall()
+                            assert list(map(lambda row: row[0], rows)) == expected, (path.name, 'DuckDB values')
+                            actual = pl.read_parquet(path)
+                            assert actual.schema['x'] == getattr(pl, f'UInt{bits}' if unsigned else f'Int{bits}'), path.name
+                            assert actual['x'].to_list() == expected, (path.name, 'Polars values')
+                            checked += 1
+                            expected_tables[path.name] = table
+                            print('PASS', path.name)
+            if args.reader:
+                seed.unlink()
+                decoded = root / 'decoded'
+                subprocess.run([str(args.reader.resolve()), str(root), '--arrow-output', str(decoded)], check=True)
+                for name, expected_table in expected_tables.items():
+                    with ipc.open_stream(decoded / (name + '.arrows')) as reader:
+                        actual = reader.read_all()
+                    assert actual.equals(expected_table), (name, 'Wireform values/types')
+        finally:
+            connection.close()
+    print(f'{checked} integer delta files verified by PyArrow, DuckDB and Polars')
+    if args.reader:
+        print(f'{checked} integer delta files also matched Wireform Arrow output')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_dictionary_bytes_interop.py b/scripts/parquet_dictionary_bytes_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_dictionary_bytes_interop.py
@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Check dictionary byte keys, slice boundaries and larger payloads independently."""
+import argparse
+from pathlib import Path
+import subprocess
+import tempfile
+
+import duckdb
+import polars as pl
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+
+from parquet_dictionary_ieee_interop import dictionary_file
+from parquet_writer_options_interop import thrift_at
+
+
+def fixtures():
+    def short_values(maximum):
+        return list(map(lambda size: bytes(size), range(maximum + 1))) + list(map(
+            lambda size: bytes(range(size)), range(maximum + 1)))
+    random = []
+    value = 0x123456789abcdef0
+    for _ in range(257):
+        random.append(value)
+        value = (value * 6364136223846793005 + 1442695040888963407) & (2**64 - 1)
+    sparse = list(map(lambda word: word.to_bytes(8, 'little'), random[:129]))
+    wide = []
+    for index, word in enumerate(random[:129]):
+        width = (64, 256, 4096)[index % 3]
+        wide.append(word.to_bytes(8, 'little') + b'a' * (width - 8))
+    common_ends = list(map(lambda word: b'a' * 24 + word.to_bytes(8, 'little') + b'a' * 32,
+                           random[:129]))
+    late = list(map(lambda word: word.to_bytes(8, 'little') + b'a' * 56, random[:129]))
+    late.append(random[0].to_bytes(8, 'little') + b'a' * 16 + b'b' * 8 + b'a' * 32)
+    late.extend(map(lambda word: word.to_bytes(8, 'little') + b'a' * 56, random[129:]))
+    late.append(random[0].to_bytes(8, 'little') + b'a' * 32 + b'c' * 8 + b'a' * 16)
+    cases = {'short': short_values(8), 'tagged-short': short_values(7), 'mixed': short_values(40),
+             'sparse8': sparse, 'wide': wide, 'common-ends': common_ends,
+             'late-promotion': late}
+    for name, cardinality in [('rle-binary', 2), ('rle-mixed', 16), ('rle-wide', 257)]:
+        values = list(range(cardinality))
+        for key, count in enumerate((7, 8, 9, 15, 16, 17, 23, 24, 31, 32, 33, 63, 64, 65)):
+            values.extend([key % cardinality] * count)
+            values.extend((0, 1, 0))
+        cases[name] = list(map(lambda value: value.to_bytes(8, 'little'), values))
+    for name, values in cases.items():
+        cases[name] = values + list(reversed(values))
+    return cases
+
+
+def run_kinds(body):
+    """Inspect run framing independently of Wireform and the external engines."""
+    width, offset, kinds = body[0], 1, set()
+    assert 0 <= width <= 32
+    while offset < len(body):
+        header, shift = 0, 0
+        while True:
+            byte = body[offset]
+            offset += 1
+            header |= (byte & 127) << shift
+            if byte < 128:
+                break
+            shift += 7
+            assert shift < 35
+        assert header > 0
+        packed = bool(header & 1)
+        count = header >> 1
+        assert 0 < count * (8 if packed else 1) <= 2**31 - 1
+        offset += count * width if packed else (width + 7) // 8
+        assert offset <= len(body)
+        kinds.add(packed)
+    assert offset == len(body)
+    return kinds
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--probe', type=Path, required=True)
+    parser.add_argument('--reader', type=Path)
+    args = parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix='wireform-parquet-dict-bytes-') as directory:
+        root = Path(directory)
+        subprocess.run([str(args.probe.resolve()), '--dictionary-bytes', str(root)], check=True)
+        cases = fixtures()
+        for name, values in cases.items():
+            expected = pa.array(values, pa.binary())
+            table = pa.Table.from_arrays([expected], schema=pa.schema([
+                pa.field('x', pa.binary(), nullable=False)]))
+            seed = root / 'seed.parquet'
+            pq.write_table(table, seed, compression='NONE', use_dictionary=False,
+                           write_statistics=False)
+            dictionary = (root / f'{name}.dictionary.bin').read_bytes()
+            data = (root / f'{name}.data.bin').read_bytes()
+            header, _ = thrift_at(dictionary, 0)
+            assert header[1] == 2 and header[7][2] == 0
+            if name.startswith('rle-'):
+                _, payload_start = thrift_at(data, 0)
+                assert run_kinds(data[payload_start:]) == {False, True}, name
+            path = root / f'{name}.parquet'
+            dictionary_file(seed, path, dictionary, data)
+            assert pq.read_table(path, use_threads=False)['x'].to_pylist() == values
+            assert pl.read_parquet(path)['x'].to_list() == values
+            connection = duckdb.connect(config={'threads': 1})
+            try:
+                actual = connection.execute('SELECT x FROM read_parquet(?)', [str(path)]).fetchall()
+                assert list(map(lambda row: row[0], actual)) == values
+            finally:
+                connection.close()
+            print(f'PASS {name}: exact byte arrays in PyArrow, DuckDB and Polars')
+        seed.unlink()
+        if args.reader:
+            decoded = root / 'decoded'
+            subprocess.run([str(args.reader.resolve()), str(root), '--arrow-output', str(decoded)], check=True)
+            for name, values in cases.items():
+                with ipc.open_stream(decoded / (name + '.parquet.arrows')) as reader:
+                    actual = reader.read_all()['x'].to_pylist()
+                assert actual == values
+            print(f'PASS Wireform Arrow output: exact bytes in all {len(cases)} dictionary files')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_dictionary_ieee_interop.py b/scripts/parquet_dictionary_ieee_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_dictionary_ieee_interop.py
@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Check dictionary NaNs, signed zero and IEEE payloads with reference readers."""
+import argparse
+import math
+from pathlib import Path
+import subprocess
+import tempfile
+
+import duckdb
+import polars as pl
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+
+from parquet_aggregate_interop import TType, column_metadata, footer, groups
+from parquet_delta_interop import encoded_struct
+from parquet_writer_options_interop import thrift_at
+
+
+def fixture(bits):
+    if bits == 32:
+        values = [0x3f800000, 0x7fc01234, 0xffa05678, 0x7fc01234, 0,
+                  0x80000000, 0, 0x80000000, 0x7f800000, 0xff800000, 1, 0xffffffff]
+        state, multiplier, increment = 0x12345678, 1664525, 1013904223
+    else:
+        values = [0x3ff0000000000000, 0x7ff8123456789abc, 0xfff056789abcdef0,
+                  0x7ff8123456789abc, 0, 0x8000000000000000, 0,
+                  0x8000000000000000, 0x7ff0000000000000, 0xfff0000000000000,
+                  1, 0xffffffffffffffff]
+        state, multiplier, increment = (0x123456789abcdef0,
+                                       6364136223846793005, 1442695040888963407)
+    for _ in range(129):
+        values.append(state)
+        state = (state * multiplier + increment) & (2**bits - 1)
+    return values + list(reversed(values))
+
+
+def check_semantics(actual, expected):
+    assert len(actual) == len(expected)
+    for left, right in zip(actual, expected, strict=True):
+        if math.isnan(right):
+            assert math.isnan(left)
+        else:
+            assert left == right
+            if right == 0:
+                assert math.copysign(1, left) == math.copysign(1, right)
+
+
+def dictionary_file(seed, path, dictionary, data):
+    _, metadata = footer(seed)
+    column = column_metadata(metadata)
+    column[2] = TType.LIST, (TType.I32, [(TType.I32, 0), (TType.I32, 8)])
+    column[6] = column[7] = TType.I64, len(dictionary) + len(data)
+    column[9] = TType.I64, 4 + len(dictionary)
+    column[11] = TType.I64, 4
+    column.pop(13, None)
+    group = groups(metadata)[0][1]
+    group[2] = group[6] = TType.I64, len(dictionary) + len(data)
+    encoded_footer = encoded_struct(metadata[1])
+    path.write_bytes(b'PAR1' + dictionary + data + encoded_footer
+                     + len(encoded_footer).to_bytes(4, 'little') + b'PAR1')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--probe', type=Path, required=True)
+    parser.add_argument('--reader', type=Path)
+    args = parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix='wireform-parquet-dict-ieee-') as directory:
+        root = Path(directory)
+        subprocess.run([str(args.probe.resolve()), '--dictionary-ieee', str(root)], check=True)
+        expected_bits = {}
+        for bits in (32, 64):
+            values = fixture(bits)
+            uint_type = getattr(pa, f'uint{bits}')()
+            float_type = getattr(pa, f'float{bits}')()
+            expected = pa.array(values, uint_type).view(float_type)
+            seed = root / 'seed.parquet'
+            table = pa.Table.from_arrays([expected], schema=pa.schema([
+                pa.field('x', float_type, nullable=False)]))
+            pq.write_table(table, seed, compression='NONE',
+                           use_dictionary=False, write_statistics=False)
+            dictionary = (root / f'f{bits}.dictionary.bin').read_bytes()
+            data = (root / f'f{bits}.data.bin').read_bytes()
+            header, _ = thrift_at(dictionary, 0)
+            assert header[1] == 2 and header[7][2] == 0, 'dictionary page must use PLAIN'
+            path = root / f'f{bits}.parquet'
+            dictionary_file(seed, path, dictionary, data)
+            actual = pq.read_table(path, use_threads=False)['x'].combine_chunks()
+            assert actual.type == float_type and actual.view(uint_type).to_pylist() == values
+            polars = pl.read_parquet(path)['x'].to_arrow()
+            assert polars.type == float_type
+            check_semantics(polars.to_pylist(), expected.to_pylist())
+            connection = duckdb.connect(config={'threads': 1})
+            try:
+                result = connection.execute('SELECT x FROM read_parquet(?)', [str(path)]).to_arrow_table()['x'].combine_chunks()
+                assert result.type == float_type
+                check_semantics(result.to_pylist(), expected.to_pylist())
+            finally:
+                connection.close()
+            expected_bits[path.name] = bits, values
+            print(f'PASS f{bits}: PyArrow exact IEEE bits; Polars/DuckDB NaNs, infinities, signed zero and finite values')
+        seed.unlink()
+        if args.reader:
+            decoded = root / 'decoded'
+            subprocess.run([str(args.reader.resolve()), str(root), '--arrow-output', str(decoded)], check=True)
+            for name, (bits, values) in expected_bits.items():
+                with ipc.open_stream(decoded / (name + '.arrows')) as reader:
+                    actual = reader.read_all()['x'].combine_chunks()
+                assert actual.view(getattr(pa, f'uint{bits}')()).to_pylist() == values
+            print('PASS Wireform Arrow output: exact IEEE bits in both dictionary files')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_encrypted_footer_interop.py b/scripts/parquet_encrypted_footer_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_encrypted_footer_interop.py
@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Authenticate all official encrypted-file footers against Arrow C++.
+
+The reference reads every physical value, definition/repetition level, index,
+and bloom filter. The native check covers FOOTERS ONLY; a passing result does
+not claim native encrypted-column or encrypted-index support. Fixture keys are
+public test data. External key material is resolved by Arrow's local mock KMS.
+"""
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+
+import pyarrow as pa
+
+
+def digest(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def execute(command, *, success=True):
+    result = subprocess.run(list(map(str, command)), capture_output=True, text=True, timeout=60)
+    if success != (result.returncode == 0):
+        raise AssertionError(f"unexpected exit {result.returncode}: {command[0]}: {result.stderr}")
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reference", type=Path, required=True)
+    parser.add_argument("--reader", type=Path, required=True)
+    parser.add_argument("--corpus", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    reference, reader = args.reference.resolve(), args.reader.resolve()
+    root = args.corpus.resolve() / "data"
+    fixtures = sorted(root.rglob("*.parquet.encrypted"))
+    if len(fixtures) < 14:
+        raise AssertionError(f"incomplete encrypted corpus: {len(fixtures)} fixtures, expected at least 14")
+    results = []
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    oracle_dir = args.output.with_suffix(".reference")
+    oracle_dir.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="wireform-encrypted-footers-") as tmp:
+        for fixture in fixtures:
+            name = fixture.relative_to(root)
+            decoded = execute([reference, fixture]).stdout
+            output = oracle_dir / Path(str(name) + ".jsonl")
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(decoded)
+            header, *columns = map(json.loads, decoded.splitlines())
+            assert len(columns) == header["rowGroups"] * header["columns"], name
+            for column in columns:
+                assert len(column["definitions"]) == len(column["repetitions"]) == column["events"], name
+                assert len(column["values"]) == column["present"], name
+            key = header["publicFixtureFooterKeyHex"]
+            prefix = "746573746572" if header["prefixRequired"] else header["storedPrefixHex"]
+
+            def native(path=fixture, test_key=key, test_prefix=prefix, success=True):
+                return execute([reader, "--authenticate-footer", path, test_key, test_prefix], success=success)
+
+            metadata = json.loads(native().stdout)
+            assert metadata["rows"] == header["rows"], name
+            assert metadata["rowGroups"] == header["rowGroups"], name
+            assert metadata["columns"] == [header["columns"]] * header["rowGroups"], name
+            native(test_key="00" * len(bytes.fromhex(key)), success=False)
+            native(test_prefix="6f74686572", success=False)
+            native(test_prefix="-", success=not header["prefixRequired"])
+            tampered = bytearray(fixture.read_bytes())
+            tampered[-9] ^= 1
+            changed = Path(tmp) / name
+            changed.parent.mkdir(parents=True, exist_ok=True)
+            changed.write_bytes(tampered)
+            sidecar = fixture.with_name("_KEY_MATERIAL_FOR_" + fixture.name + ".json")
+            if sidecar.exists():
+                shutil.copy2(sidecar, changed.with_name(sidecar.name))
+            native(path=changed, success=False)
+            execute([reference, changed], success=False)
+            results.append({
+                "fixture": str(name), "sha256": digest(fixture),
+                "rows": header["rows"], "rowGroups": header["rowGroups"], "columns": header["columns"],
+                "nativeFooterMatchesReference": True, "tamperedFooterRejectedByBoth": True,
+                "wrongKeyRejected": True, "wrongPrefixRejected": True,
+                "omittedPrefixRequired": header["prefixRequired"],
+                "referenceColumnIndexes": sum(c["columnIndex"] for c in columns),
+                "referenceOffsetIndexes": sum(c["offsetPages"] > 0 for c in columns),
+                "referenceBlooms": sum(c["bloomBytes"] > 0 for c in columns),
+                "referenceOutputSHA256": digest(output),
+            })
+            print(f"PASS footer {name}", flush=True)
+    args.output.write_text(json.dumps({
+        "scope": "Native footer authentication only; C++ independently reads complete files",
+        "fullNativeEncryptedReadsValidated": False, "pyarrowVersion": pa.__version__,
+        "referenceBinarySHA256": digest(reference), "readerBinarySHA256": digest(reader),
+        "referenceSourceSHA256": digest(Path(__file__).with_name("parquet_encrypted_reference.cc")),
+        "fixtures": results,
+    }, indent=2) + "\n")
+    print(f"All {len(results)} encrypted footers authenticated; native encrypted-column reads remain unvalidated")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_encrypted_read_interop.py b/scripts/parquet_encrypted_read_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_encrypted_read_interop.py
@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""Check complete native encrypted reads against unmodified Arrow C++.
+
+Compares every physical value and level, Arrow values (INT96 is checked as raw
+physical bytes), indexes and bloom filters with the official encrypted corpus.
+Exercises explicit/metadata key routing, projections without unrelated keys,
+and whole-page predicates with damaged skipped/retained headers. All keys are
+public fixture data and external material uses a local mock KMS.
+"""
+
+import argparse
+import hashlib
+import json
+import math
+from pathlib import Path
+import struct
+import subprocess
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+
+def same(a,b):
+    if isinstance(a,float) and isinstance(b,float):return a==b or math.isnan(a) and math.isnan(b)
+    if isinstance(a,list) and isinstance(b,list):return len(a)==len(b) and all(same(x,y) for x,y in zip(a,b))
+    if isinstance(a,dict) and isinstance(b,dict):return a.keys()==b.keys() and all(same(a[k],b[k]) for k in a)
+    return a==b
+
+
+def selected_checks(r, root, reader):
+    results = []
+    def run(name,case,config,path,expected=None,fail=False):
+        dest=r/'selection'/name/case;dest.parent.mkdir(parents=True,exist_ok=True)
+        keys=dest.with_suffix('.keys.json');keys.write_text(json.dumps(config,indent=2)+'\n')
+        proc=subprocess.run([str(reader),'--encrypted-read',str(path),str(keys),str(dest)+'.arrow'],capture_output=True,text=True,timeout=60)
+        Path(str(dest)+'.stdout').write_text(proc.stdout);Path(str(dest)+'.stderr').write_text(proc.stderr)
+        if fail:assert proc.returncode!=0,(name,case)
+        else:
+            assert proc.returncode==0,(name,case,proc.stderr)
+            actual=ipc.open_stream(str(dest)+'.arrow').read_all()
+            assert actual.column_names==expected.column_names,(name,case,'columns')
+            assert same(actual.to_pylist(),expected.to_pylist()),(name,case,'values')
+        record={'fixture':name,'case':case,'exit':proc.returncode,'expectedFailure':fail,'passed':True};results.append(record)
+        (r/'selection-results.json').write_text(json.dumps(results,indent=2)+'\n')
+        print(json.dumps(record),flush=True)
+    
+    for name in json.loads((r/'oracle-fixtures.json').read_text()):
+        oracle=r/'oracle'/name;header,*columns=map(json.loads,Path(str(oracle)+'.jsonl').read_text().splitlines())
+        config=json.loads(Path(str(oracle)+'.keys.json').read_text());table=ipc.open_stream(str(oracle)+'.arrow').read_all();path=root/name
+        eligible=filter(lambda c: c['encrypted'] and c['columnIndex'] and c['type'] in [1,2,4,5] and c['maxRepetition']==0 and len(c['pathParts'])==1, columns)
+        seen = set()
+        for column in eligible:
+            identity = (column['column'], tuple(column['pathParts']))
+            if identity in seen:
+                continue
+            seen.add(identity)
+            related = sorted((item for item in columns if item['column'] == column['column']), key=lambda item: item['rowGroup'])
+            def decode(hex_string):
+                raw=bytes.fromhex(hex_string)
+                return int.from_bytes(raw,'little',signed=True) if column['type'] in [1,2] else struct.unpack('<f' if column['type']==4 else '<d',raw)[0]
+            maxima = []
+            for item in related:
+                for value, null in zip(item['pageMaxima'], item['nullPages']):
+                    if not null:
+                        maxima.append(decode(value))
+            assert maxima and all(math.isfinite(v) for v in maxima)
+            thresholds=[('all',min(maxima)-1),('none',max(maxima)+1)]
+            if len(set(maxima))>1:thresholds.append(('partial',sorted(set(maxima))[len(set(maxima))//2]))
+            field=column['pathParts'][0]
+            for label,threshold in thresholds:
+                case=f"column-{column['column']}-{label}";plan={**config,'projection':[field],'prune':str(threshold)}
+                plans = []
+                parts = []
+                base = 0
+                for item in related:
+                    kept = list(map(lambda pair: not pair[1] and decode(pair[0]) >= threshold, zip(item['pageMaxima'], item['nullPages'])))
+                    plans.append((item, kept))
+                    for index, (offset, size, start) in enumerate(item['pageLocations']):
+                        if kept[index]:
+                            end = item['pageLocations'][index+1][2] if index+1 < len(kept) else item['events']
+                            parts.append(table.select([field]).slice(base+start, end-start))
+                    base += item['events']
+                expected = pa.concat_tables(parts) if parts else table.select([field]).slice(0, 0)
+                run(name, case, plan, path, expected)
+                skipped, retained = [], []
+                for item, kept in plans:
+                    for index, retain in enumerate(kept):
+                        (retained if retain else skipped).append((item, index))
+                if skipped:
+                    altered = bytearray(path.read_bytes())
+                    for item, index in skipped:
+                        altered[item['pageLocations'][index][0]] ^= 1
+                    changed = r/'selection-damaged'/name/(case+'.parquet.encrypted')
+                    changed.parent.mkdir(parents=True, exist_ok=True)
+                    changed.write_bytes(altered)
+                    run(name, case+'-damaged-skipped', plan, changed, expected)
+                if retained:
+                    altered = bytearray(path.read_bytes())
+                    item, index = retained[0]
+                    altered[item['pageLocations'][index][0]] ^= 1
+                    changed = r/'selection-damaged'/name/(case+'-retained.parquet.encrypted')
+                    changed.parent.mkdir(parents=True, exist_ok=True)
+                    changed.write_bytes(altered)
+                    run(name, case+'-damaged-retained', plan, changed, fail=True)
+        plaintext=next((c for c in columns if not c['encrypted'] and len(c['pathParts'])==1 and c['type']!=3 and all(not item['encrypted'] for item in columns if item['column']==c['column'])),None)
+        encrypted=next((c for c in columns if c['encrypted'] and len(c['pathParts'])==1 and c['keyMetadataHex'] and c['keyMetadataHex']!=header['footerKeyMetadataHex']),None)
+        if plaintext and encrypted:
+            without_keys={**config,'columns':[],'projection':[plaintext['pathParts'][0]]}
+            expected=table.select([plaintext['pathParts'][0]])
+            run(name,'project-public-without-column-keys',without_keys,path,expected)
+            missing={**without_keys,'projection':[encrypted['pathParts'][0]]}
+            run(name,'missing-requested-column-key',missing,path,fail=True)
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reference", type=Path, required=True)
+    parser.add_argument("--reader", type=Path, required=True)
+    parser.add_argument("--corpus", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    r = args.output.resolve().with_suffix(".artifacts")
+    r.mkdir(parents=True, exist_ok=True)
+    root = args.corpus.resolve() / "data"
+    reader = args.reader.resolve()
+    names = []
+    for path in sorted(root.rglob("*.parquet.encrypted")):
+        name = path.relative_to(root)
+        dest = r / "oracle" / name
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        process = subprocess.run([str(args.reference.resolve()), str(path), str(dest)+".arrow"],
+                                 capture_output=True, text=True, timeout=60)
+        if process.returncode:
+            raise AssertionError(f"reference rejected {name}: {process.stderr}")
+        Path(str(dest)+".jsonl").write_text(process.stdout)
+        header, *columns = map(json.loads, process.stdout.splitlines())
+        assert all(column["pathParts"] for column in columns), name
+        keys = {"footer": header["publicFixtureFooterKeyHex"], "footerMetadata": header["footerKeyMetadataHex"],
+                "prefix": "746573746572" if header["prefixRequired"] else header["storedPrefixHex"],
+                "mode": "metadata", "columns": []}
+        for column in columns:
+            if column["encrypted"]:
+                keys["columns"].append({"path": column["pathParts"], "key": column["publicFixtureColumnKeyHex"],
+                                        "metadata": column["keyMetadataHex"]})
+        Path(str(dest)+".keys.json").write_text(json.dumps(keys, indent=2)+"\n")
+        names.append(str(name))
+    if len(names) < 14:
+        raise AssertionError(f"incomplete encrypted corpus: {len(names)} fixtures")
+    (r/"oracle-fixtures.json").write_text(json.dumps(names, indent=2)+"\n")
+    results = []
+    fields = ['rowGroup','column','path','type','maxDefinition','maxRepetition','columnIndex','offsetPages','bloomBytes','events','present','definitions','repetitions','values']
+    for name in json.loads((r/'oracle-fixtures.json').read_text()):
+        oracle=r/'oracle'/name
+        reference=list(map(json.loads, Path(str(oracle)+'.jsonl').read_text().splitlines()))
+        for mode in ['metadata','explicit']:
+            dest=r/f'native-{mode}'/name;dest.parent.mkdir(parents=True,exist_ok=True)
+            config=json.loads(Path(str(oracle)+'.keys.json').read_text());config['mode']=mode
+            keyfile=Path(str(dest)+'.keys.json');keyfile.write_text(json.dumps(config,indent=2)+'\n')
+            result=subprocess.run([str(reader),'--encrypted-read',str(root/name),str(keyfile),str(dest)+'.arrow'],capture_output=True,text=True,timeout=60)
+            Path(str(dest)+'.stdout').write_text(result.stdout);Path(str(dest)+'.stderr').write_text(result.stderr)
+            record={'fixture':name,'mode':mode,'exit':result.returncode,'stderr':result.stderr.strip()}
+            if result.returncode==0:
+                try:
+                    actual=list(map(json.loads, result.stdout.splitlines()))
+                    assert all(actual[0][key]==reference[0][key] for key in ['rows','rowGroups','columns'])
+                    assert len(actual)==len(reference)
+                    for left,right in zip(actual[1:],reference[1:]):
+                        for key in fields:assert left[key]==right[key],(key,left['column'],str(left[key])[:120],str(right[key])[:120])
+                    expected=ipc.open_stream(str(oracle)+'.arrow').read_all();native=ipc.open_stream(str(dest)+'.arrow').read_all()
+                    assert native.num_rows==expected.num_rows
+                    for field in expected.column_names:
+                        assert same(native[field].to_pylist(),expected[field].to_pylist()),('Arrow value mismatch',field)
+                    record.update(physicalValuesMatch=True,arrowValuesMatch=True)
+                except Exception as error:record['comparisonFailure']=str(error)
+            results.append(record);print(json.dumps(record),flush=True)
+            (r/'first-encrypted-results.json').write_text(json.dumps(results,indent=2)+'\n')
+    assert len(results) == 2 * len(names)
+    assert all(result.get("physicalValuesMatch") and result.get("arrowValuesMatch") for result in results), results
+    selected_results = selected_checks(r, root, reader)
+    revision = subprocess.check_output(["git", "-C", str(args.corpus.resolve()), "rev-parse", "HEAD"], text=True).strip()
+    digest = lambda path: hashlib.sha256(Path(path).read_bytes()).hexdigest()
+    args.output.write_text(json.dumps({
+        "scope": "Complete native physical/Arrow reads plus encrypted index/bloom and selective/projection checks",
+        "fullNativeEncryptedReadsValidated": True, "corpusRevision": revision,
+        "pyarrowVersion": pa.__version__, "referenceSHA256": digest(args.reference), "readerSHA256": digest(reader),
+        "referenceSourceSHA256": digest(Path(__file__).with_name("parquet_encrypted_reference.cc")),
+        "fullReads": results, "selectiveChecks": selected_results,
+    }, indent=2)+"\n")
+    print(f"Passed {len(results)} complete encrypted reads and {len(selected_results)} selective/projection checks", flush=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_encrypted_reference.cc b/scripts/parquet_encrypted_reference.cc
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_encrypted_reference.cc
@@ -0,0 +1,305 @@
+// Independent fixture oracle: decode with the unmodified Apache Arrow C++
+// library shipped by PyArrow. Keys below are PUBLIC parquet-testing fixtures.
+#include <array>
+#include <bit>
+#include <cstdint>
+#include <cstring>
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+#include <sstream>
+#include <string_view>
+#include <unordered_map>
+#include "arrow/filesystem/localfs.h"
+#include "arrow/io/file.h"
+#include "arrow/ipc/api.h"
+#include "arrow/table.h"
+#include "arrow/util/secure_string.h"
+#include "parquet/arrow/reader.h"
+#include "parquet/bloom_filter.h"
+#include "parquet/bloom_filter_reader.h"
+#include "parquet/column_reader.h"
+#include "parquet/encryption/crypto_factory.h"
+#include "parquet/encryption/kms_client_factory.h"
+#include "parquet/file_reader.h"
+#include "parquet/page_index.h"
+
+// This exported library helper implements Apache's mock InMemoryKMS wrapping.
+// Its declaration matches parquet/encryption/key_toolkit_internal.h; that
+// internal header is not distributed in PyArrow's public include directory.
+namespace parquet::encryption::internal {
+::arrow::util::SecureString DecryptKeyLocally(const std::string&,
+    const ::arrow::util::SecureString&, const std::string&);
+}
+using arrow::util::SecureString;
+using Keys = std::unordered_map<std::string, SecureString>;
+
+Keys FixtureKeys(bool wide) {
+  Keys keys;
+  keys.emplace("kf", SecureString(std::string(wide ? "01234567890123456789012345678901" : "0123456789012345")));
+  for (int n = 1; n <= (wide ? 8 : 2); ++n) {
+    auto key = wide ? "123456789012345678901234567890" + std::to_string(n + 11)
+                    : "123456789012345" + std::to_string(n - 1);
+    keys.emplace("kc" + std::to_string(n), SecureString(std::move(key)));
+  }
+  return keys;
+}
+
+class FixtureKms : public parquet::encryption::KmsClient {
+  Keys keys_ = FixtureKeys(false);
+ public:
+  std::string WrapKey(const SecureString&, const std::string&) override {
+    throw std::runtime_error("read-only fixture KMS");
+  }
+  SecureString UnwrapKey(const std::string& wrapped, const std::string& id) override {
+    if (id == "wireform-test" && wrapped == "test-key") return SecureString(16, 0x42);
+    if (id == "wireform-test") {
+      for (int bytes : {16,24,32}) {
+        if (wrapped == "test-key-" + std::to_string(bytes)) return SecureString(bytes, 0x42);
+      }
+    }
+    return parquet::encryption::internal::DecryptKeyLocally(wrapped, keys_.at(id), id);
+  }
+};
+class FixtureKmsFactory : public parquet::encryption::KmsClientFactory {
+ public:
+  std::shared_ptr<parquet::encryption::KmsClient> CreateKmsClient(
+      const parquet::encryption::KmsConnectionConfig&) override {
+    return std::make_shared<FixtureKms>();
+  }
+};
+
+std::string Hex(const void* raw, size_t size) {
+  const auto* data = static_cast<const uint8_t*>(raw);
+  constexpr char digits[] = "0123456789abcdef";
+  std::string out; out.reserve(size * 2);
+  for (size_t i = 0; i < size; ++i) {
+    out += digits[data[i] >> 4]; out += digits[data[i] & 15];
+  }
+  return out;
+}
+
+std::string JsonString(const std::string& text) {
+  constexpr char hex[] = "0123456789abcdef";
+  std::string out = "\"";
+  for (uint8_t byte : text) {
+    if (byte == '"' || byte == '\\') { out += '\\'; out += byte; }
+    else if (byte < 32) { out += "\\u00"; out += hex[byte >> 4]; out += hex[byte & 15]; }
+    else out += byte;
+  }
+  return out + '"';
+}
+template<class T> std::string PlainValue(T value, int) {
+  static_assert(std::endian::native == std::endian::little);
+  return std::string(reinterpret_cast<const char*>(&value), sizeof(T));
+}
+template<> std::string PlainValue(bool value, int) {
+  return std::string(1, value ? '\1' : '\0');
+}
+template<> std::string PlainValue(parquet::ByteArray value, int) {
+  return value.len ? std::string(reinterpret_cast<const char*>(value.ptr), value.len) : std::string();
+}
+template<> std::string PlainValue(parquet::FixedLenByteArray value, int width) {
+  return std::string(reinterpret_cast<const char*>(value.ptr), width);
+}
+
+template<class Type> void Dump(parquet::ColumnReader* raw, std::ostream& out, const parquet::BloomFilter* bloom) {
+  auto* reader = dynamic_cast<parquet::TypedColumnReader<Type>*>(raw);
+  if (!reader) throw std::runtime_error("physical reader mismatch");
+  const auto* schema = reader->descr();
+  using T = typename Type::c_type;
+  std::array<T, 128> values;
+  std::array<int16_t, 128> defs{}, reps{};
+  std::ostringstream definitions, repetitions, payloads;
+  bool first_level = true, first_value = true;
+  int64_t events = 0, present = 0;
+  while (reader->HasNext()) {
+    int64_t count = 0;
+    auto levels = reader->ReadBatch(values.size(), defs.data(), reps.data(), values.data(), &count);
+    if (levels <= 0) throw std::runtime_error("reader made no progress");
+    for (int64_t i = 0; i < levels; ++i) {
+      if (!first_level) { definitions << ','; repetitions << ','; }
+      first_level = false;
+      definitions << (schema->max_definition_level() ? defs[i] : 0);
+      repetitions << (schema->max_repetition_level() ? reps[i] : 0);
+    }
+    for (int64_t i = 0; i < count; ++i) {
+      if (!first_value) payloads << ',';
+      first_value = false;
+      const auto plain = PlainValue(values[i], schema->type_length());
+      if (bloom && !bloom->FindHash(bloom->Hash(std::string_view(plain)))) {
+        throw std::runtime_error("bloom false negative for an independently decoded value");
+      }
+      payloads << '\"' << Hex(plain.data(), plain.size()) << '\"';
+    }
+    events += levels; present += count;
+  }
+  out << ",\"bloomValuesChecked\":" << (bloom ? present : 0)
+      << ",\"events\":" << events << ",\"present\":" << present
+      << ",\"definitions\":[" << definitions.str() << "]"
+      << ",\"repetitions\":[" << repetitions.str() << "]"
+      << ",\"values\":[" << payloads.str() << "]";
+}
+
+int main(int argc, char** argv) {
+ try {
+  if (argc != 2 && argc != 3 && argc != 4) throw std::runtime_error("usage: reference <encrypted fixture> [arrow-output [native-forward|plaintext]]");
+  const bool native_forward = argc == 4 && std::string(argv[3]) == "native-forward";
+  const bool plaintext = argc == 4 && std::string(argv[3]) == "plaintext";
+  const bool writer_features = argc == 4 && std::string(argv[3]).starts_with("writer-");
+  if (argc == 4 && !native_forward && !plaintext && !writer_features) throw std::runtime_error("unknown fixture key configuration");
+  const std::string path = argv[1];
+  parquet::ReaderProperties properties;
+  properties.set_page_checksum_verification(true);
+  std::shared_ptr<parquet::FileDecryptionProperties> decryption;
+  const bool external = path.find("external_key_material") != std::string::npos;
+  if (writer_features) {
+    const int width = std::stoi(std::string(argv[3]).substr(7));
+    if (width != 16 && width != 24 && width != 32) throw std::runtime_error("invalid public fixture key width");
+    auto retriever = std::make_shared<parquet::StringKeyIdRetriever>();
+    retriever->PutKey("kf", SecureString(width, 0x42));
+    retriever->PutKey("kc1", SecureString(width, 0x43));
+    retriever->PutKey("kc2", SecureString(width, 0x44));
+    parquet::FileDecryptionProperties::Builder builder;
+    builder.key_retriever(retriever);
+    builder.aad_prefix("writer-regression");
+    decryption = builder.build();
+  } else if (external || native_forward) {
+    parquet::encryption::CryptoFactory factory;
+    factory.RegisterKmsClientFactory(std::make_shared<FixtureKmsFactory>());
+    parquet::encryption::KmsConnectionConfig connection;
+    if (native_forward) connection.kms_instance_id = "wireform-test";
+    parquet::encryption::DecryptionConfiguration config;
+    decryption = factory.GetFileDecryptionProperties(connection, config, path,
+        std::make_shared<arrow::fs::LocalFileSystem>());
+  } else {
+    auto retriever = std::make_shared<parquet::StringKeyIdRetriever>();
+    for (const auto& [id, key] : FixtureKeys(path.find("aes256/") != std::string::npos)) {
+      retriever->PutKey(id, key);
+    }
+    parquet::FileDecryptionProperties::Builder builder;
+    builder.key_retriever(retriever);
+    if (path.find("_aad") != std::string::npos) builder.aad_prefix("tester");
+    decryption = builder.build();
+  }
+  if (!plaintext) properties.file_decryption_properties(decryption);
+  auto file = parquet::ParquetFileReader::OpenFile(path, false, properties);
+  auto metadata = file->metadata();
+  std::ifstream input(path, std::ios::binary);
+  const std::string raw((std::istreambuf_iterator<char>(input)), std::istreambuf_iterator<char>());
+  if (raw.size() < 12) throw std::runtime_error("short fixture");
+  auto length = static_cast<uint32_t>(static_cast<uint8_t>(raw[raw.size()-8]))
+      | static_cast<uint32_t>(static_cast<uint8_t>(raw[raw.size()-7])) << 8
+      | static_cast<uint32_t>(static_cast<uint8_t>(raw[raw.size()-6])) << 16
+      | static_cast<uint32_t>(static_cast<uint8_t>(raw[raw.size()-5])) << 24;
+  if (length > raw.size()-12) throw std::runtime_error("fixture footer out of bounds");
+  parquet::EncryptionAlgorithm algorithm{};
+  std::string footer_key_metadata;
+  if (raw.substr(raw.size()-4) == "PARE") {
+    auto crypto = parquet::FileCryptoMetaData::Make(
+        reinterpret_cast<const uint8_t*>(raw.data()+raw.size()-8-length), static_cast<int64_t>(length));
+    algorithm = crypto->encryption_algorithm(); footer_key_metadata = crypto->key_metadata();
+  } else if (!plaintext) {
+    algorithm = metadata->encryption_algorithm(); footer_key_metadata = metadata->footer_signing_key_metadata();
+  }
+  auto footer_key = decryption->key_retriever()->GetKey(plaintext ? "kf" : footer_key_metadata);
+  auto indexes = file->GetPageIndexReader();
+  std::cout << "{\"rows\":" << metadata->num_rows() << ",\"rowGroups\":"
+            << metadata->num_row_groups() << ",\"columns\":" << metadata->num_columns()
+            << ",\"fileIdHex\":\"" << Hex(algorithm.aad.aad_file_unique.data(), algorithm.aad.aad_file_unique.size())
+            << "\",\"storedPrefixHex\":\"" << Hex(algorithm.aad.aad_prefix.data(), algorithm.aad.aad_prefix.size())
+            << "\",\"prefixRequired\":" << (algorithm.aad.supply_aad_prefix ? "true" : "false")
+            << ",\"algorithm\":" << algorithm.algorithm
+            << ",\"footerKeyMetadataHex\":\"" << Hex(footer_key_metadata.data(), footer_key_metadata.size()) << "\""
+            << ",\"publicFixtureFooterKeyHex\":\"" << Hex(footer_key.as_span().data(), footer_key.size()) << "\"}\n";
+  for (int rg = 0; rg < metadata->num_row_groups(); ++rg) {
+    auto group = file->RowGroup(rg);
+    auto rg_indexes = indexes ? indexes->RowGroup(rg) : nullptr;
+    auto rg_blooms = file->GetBloomFilterReader().RowGroup(rg);
+    for (int col = 0; col < metadata->num_columns(); ++col) {
+      auto reader = group->Column(col);
+      auto* schema = reader->descr();
+      auto ci = rg_indexes ? rg_indexes->GetColumnIndex(col) : nullptr;
+      auto oi = rg_indexes ? rg_indexes->GetOffsetIndex(col) : nullptr;
+      auto bloom = rg_blooms ? rg_blooms->GetColumnBloomFilter(col) : nullptr;
+      auto crypto = metadata->RowGroup(rg)->ColumnChunk(col)->crypto_metadata();
+      std::string key_metadata;
+      SecureString column_key;
+      if (crypto) {
+        key_metadata = crypto->key_metadata();
+        column_key = crypto->encrypted_with_footer_key() ? footer_key : decryption->key_retriever()->GetKey(key_metadata);
+      }
+      std::cout << "{\"rowGroup\":" << rg << ",\"column\":" << col
+        << ",\"path\":\"" << schema->path()->ToDotString() << "\",\"type\":" << schema->physical_type()
+        << ",\"maxDefinition\":" << schema->max_definition_level()
+        << ",\"maxRepetition\":" << schema->max_repetition_level()
+        << ",\"columnIndex\":" << (ci ? "true" : "false")
+        << ",\"offsetPages\":" << (oi ? oi->page_locations().size() : 0)
+        << ",\"bloomBytes\":" << (bloom ? bloom->GetBitsetSize() : 0);
+      std::cout << ",\"encrypted\":" << (crypto ? "true" : "false")
+        << ",\"keyMetadataHex\":\"" << Hex(key_metadata.data(), key_metadata.size())
+        << "\",\"publicFixtureColumnKeyHex\":\"" << Hex(column_key.as_span().data(), column_key.size()) << "\",\"pathParts\":[";
+      bool first_part = true;
+      const auto schema_path = schema->path();
+      for (const auto& part : schema_path->ToDotVector()) {
+        if (!first_part) std::cout << ',';
+        first_part = false;
+        std::cout << JsonString(part);
+      }
+      std::cout << ']';
+      std::cout << ",\"pageLocations\":[";
+      bool first_page = true;
+      if (oi) for (const auto& location : oi->page_locations()) {
+        if (!first_page) std::cout << ',';
+        first_page = false;
+        std::cout << '[' << location.offset << ',' << location.compressed_page_size << ',' << location.first_row_index << ']';
+      }
+      std::cout << "],\"pageMaxima\":[";
+      first_page = true;
+      if (ci) for (const auto& value : ci->encoded_max_values()) {
+        if (!first_page) std::cout << ',';
+        first_page = false;
+        std::cout << '"' << Hex(value.data(), value.size()) << '"';
+      }
+      std::cout << "],\"nullPages\":[";
+      first_page = true;
+      if (ci) for (bool value : ci->null_pages()) {
+        if (!first_page) std::cout << ',';
+        first_page = false;
+        std::cout << (value ? "true" : "false");
+      }
+      std::cout << ']';
+      switch (schema->physical_type()) {
+        case parquet::Type::BOOLEAN: Dump<parquet::BooleanType>(reader.get(), std::cout, bloom.get()); break;
+        case parquet::Type::INT32: Dump<parquet::Int32Type>(reader.get(), std::cout, bloom.get()); break;
+        case parquet::Type::INT64: Dump<parquet::Int64Type>(reader.get(), std::cout, bloom.get()); break;
+        case parquet::Type::INT96: Dump<parquet::Int96Type>(reader.get(), std::cout, bloom.get()); break;
+        case parquet::Type::FLOAT: Dump<parquet::FloatType>(reader.get(), std::cout, bloom.get()); break;
+        case parquet::Type::DOUBLE: Dump<parquet::DoubleType>(reader.get(), std::cout, bloom.get()); break;
+        case parquet::Type::BYTE_ARRAY: Dump<parquet::ByteArrayType>(reader.get(), std::cout, bloom.get()); break;
+        case parquet::Type::FIXED_LEN_BYTE_ARRAY: Dump<parquet::FLBAType>(reader.get(), std::cout, bloom.get()); break;
+        default: throw std::runtime_error("unsupported physical type");
+      }
+      std::cout << "}\n";
+    }
+  }
+  if (argc >= 3 && std::string(argv[2]) != "-") {
+    // Keep raw INT96 comparisons in the physical oracle: converting the
+    // deliberately extreme fixture values to Arrow timestamps can overflow.
+    std::vector<int> columns;
+    for (int i = 0; i < metadata->num_columns(); ++i) {
+      if (metadata->schema()->Column(i)->physical_type() != parquet::Type::INT96) columns.push_back(i);
+    }
+    auto reader = parquet::arrow::FileReader::Make(arrow::default_memory_pool(), std::move(file)).ValueOrDie();
+    auto table = reader->ReadTable(columns).ValueOrDie();
+    auto sink = arrow::io::FileOutputStream::Open(argv[2]).ValueOrDie();
+    auto output = arrow::ipc::MakeStreamWriter(sink, table->schema()).ValueOrDie();
+    PARQUET_THROW_NOT_OK(output->WriteTable(*table));
+    PARQUET_THROW_NOT_OK(output->Close());
+    PARQUET_THROW_NOT_OK(sink->Close());
+  }
+  return 0;
+ } catch (const std::exception& error) {
+  std::cerr << error.what() << '\n'; return 1;
+ }
+}
diff --git a/scripts/parquet_encrypted_writer_interop.py b/scripts/parquet_encrypted_writer_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_encrypted_writer_interop.py
@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""Check writer encryption using Apache Thrift, independent AES and Arrow C++.
+
+Only public fixture keys are used. For LZO, authenticate/decrypt every module
+with cryptography, compare the compressed bytes to plaintext controls, then
+decode control compression with unmodified liblzo2 before Arrow C++ reads it.
+"""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+import parquet_lzo_interop as thrift
+from parquet_nested_bloom_interop import strip_auxiliary
+
+
+def canonical(node):
+    # Compact Protocol requires a struct root, including for scalar/list comparisons.
+    return thrift.encode(thrift.Node(thrift.TType.STRUCT, {1: node}))
+
+
+def framed(data, start):
+    assert 0 <= start <= len(data)-4
+    size = int.from_bytes(data[start:start+4], 'little')
+    assert size >= 12 and size <= len(data)-start-4
+    return data[start+4:start+4+size], start+4+size
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--fixtures', type=Path, required=True)
+    parser.add_argument('--reference', type=Path, required=True)
+    parser.add_argument('--lzo-reference', type=Path, required=True)
+    parser.add_argument('--output', type=Path, required=True)
+    args = parser.parse_args()
+    root = args.fixtures / 'encryption-writer'
+    files = sorted(root.glob('feature-*.parquet'))
+    assert len(files) == 672, ('complete 7-codec/3-width/2-algorithm/2-mode/2-key-route/2-page/2-layout grid',len(files))
+    nonces = set()
+    module_count = 0
+    cpp_queries = 0
+    lzo_calls = 0
+    records = []
+    controls = {}
+    with tempfile.TemporaryDirectory(prefix='encrypted-writer-oracle-') as directory:
+        scratch = Path(directory)
+
+        def cpp(path, mode, output):
+            proc = subprocess.run([str(args.reference),str(path),str(output),mode],capture_output=True,text=True)
+            assert proc.returncode == 0,(path.name,proc.stderr)
+            head,*columns = map(json.loads,proc.stdout.splitlines())
+            return head,columns
+
+        for control in sorted(root.glob('plain-*.parquet')):
+            _,shape,codec,version = control.stem.split('-')
+            readable = control
+            if codec == 'LZO':
+                stripped = scratch / 'stripped.parquet'
+                readable = scratch / 'lzo-control.parquet'
+                strip_auxiliary(control,stripped)
+                lzo_calls += thrift.transcode(stripped,readable,0,args.lzo_reference,scratch,require_source_codec=3,expected_version=1 if version=='PageV1' else 2)
+            arrow = scratch/'control.arrow'
+            head,columns = cpp(readable,'plaintext',arrow)
+            controls[(shape,codec,version)] = pa.ipc.open_stream(arrow).read_all()
+            assert head['rows'] == (3 if shape=='nested' else 6)
+        for shape in ('mixed','nested'):
+            for codec in ('Uncompressed','GZip','Snappy','ZSTD','LZ4Raw','LZO','Brotli'):
+                for version in ('PageV1','PageV2'):
+                    assert controls[(shape,codec,version)].equals(controls[(shape,'Uncompressed',version)],check_metadata=False)
+
+        for path in files:
+            _,shape,width,algorithm,mode,route,codec,version = path.stem.split('-')
+            width = int(width)
+            keys = {'kf':bytes([0x42])*width,'kc1':bytes([0x43])*width,'kc2':bytes([0x44])*width}
+            raw = path.read_bytes()
+            assert raw[:4] == raw[-4:] == (b'PARE' if mode=='EncryptedFooter' else b'PAR1')
+            length = int.from_bytes(raw[-8:-4],'little')
+            assert length <= len(raw)-12
+            tail = raw[-8-length:-8]
+            first = thrift.decode(tail)
+            if mode == 'EncryptedFooter':
+                crypto = first.node.value
+                encoded_algorithm = crypto[1].value
+                assert crypto[2].value == b'kf'
+            else:
+                encoded_algorithm = first.node.value[8].value
+                assert first.node.value[9].value == b'kf'
+            assert list(encoded_algorithm) == [1 if algorithm=='AesGcmV1' else 2]
+            context = next(iter(encoded_algorithm.values())).value
+            assert context[1].value == b'writer-regression'
+            file_id = context[2].value
+            assert len(file_id)>0
+
+            def aad(kind,rg=0,col=0):
+                return b'writer-regression'+file_id+bytes([kind])+(b'' if kind==0 else struct.pack('<hh',rg,col))+(b'\0\0' if kind in (2,4) else b'')
+
+            def unique(key,nonce):
+                nonlocal module_count
+                assert len(nonce)==12 and (key,nonce) not in nonces,(path.name,'reused nonce')
+                nonces.add((key,nonce));module_count+=1
+
+            def gcm(key,kind,payload,rg=0,col=0):
+                assert len(payload)>=28
+                unique(key,payload[:12])
+                return AESGCM(key).decrypt(payload[:12],payload[12:],aad(kind,rg,col))
+
+            def module(key,kind,buffer,offset=0,rg=0,col=0):
+                payload,end = framed(buffer,offset)
+                return gcm(key,kind,payload,rg,col),end
+
+            if mode == 'EncryptedFooter':
+                plain,end = module(keys['kf'],0,tail,first.consumed)
+                assert end == len(tail)
+                decoded = thrift.decode(plain)
+                assert decoded.consumed == len(plain)
+                footer = decoded.node
+            else:
+                assert len(tail)-first.consumed == 28
+                nonce,tag = tail[first.consumed:first.consumed+12],tail[-16:]
+                unique(keys['kf'],nonce)
+                assert AESGCM(keys['kf']).encrypt(nonce,tail[:first.consumed],aad(0))[-16:] == tag
+                footer = first.node
+            control = root/f'plain-{shape}-{codec}-{version}.parquet'
+            source = control.read_bytes()
+            source_length = int.from_bytes(source[-8:-4],'little')
+            source_footer = thrift.decode(source[-8-source_length:-8]).node
+            assert canonical(footer.value[2])==canonical(source_footer.value[2])
+            assert footer.value[3].value==source_footer.value[3].value
+            assert len(footer.value[4].value)==len(source_footer.value[4].value)
+            for rg,(group,source_group) in enumerate(zip(footer.value[4].value,source_footer.value[4].value)):
+                assert group.value[7].value==rg
+                for col,(chunk,source_chunk) in enumerate(zip(group.value[1].value,source_group.value[1].value)):
+                    original=source_chunk.value[3].value
+                    key=keys['kf'] if route=='footer' else keys['kc1' if col%2==0 else 'kc2']
+                    encrypted=col!=0
+                    if encrypted:
+                        crypto=chunk.value[8].value
+                        assert list(crypto)==([1] if route=='footer' else [2])
+                        if route=='split':
+                            assert canonical(crypto[2].value[1])==canonical(original[3])
+                            assert crypto[2].value[2].value==('kc1' if col%2==0 else 'kc2').encode()
+                        if mode=='SignedPlaintextFooter' or route=='split':
+                            metadata,end=module(key,1,chunk.value[9].value,rg=rg,col=col)
+                            assert end==len(chunk.value[9].value)
+                            cm=thrift.decode(metadata).node.value
+                            if mode=='SignedPlaintextFooter':
+                                assert 3 in chunk.value and 12 not in chunk.value[3].value
+                            else:
+                                assert 3 not in chunk.value
+                        else:
+                            assert 9 not in chunk.value
+                            cm=chunk.value[3].value
+                    else:
+                        assert 8 not in chunk.value and 9 not in chunk.value
+                        cm=chunk.value[3].value
+                    for field in (1,2,3,4,5,12):
+                        assert (field in cm)==(field in original)
+                        if field in original:assert canonical(cm[field])==canonical(original[field]),(path.name,col,field)
+                    old_start=original[9].value
+                    old_header=thrift.decode(source[old_start:])
+                    old_body=source[old_start+old_header.consumed:old_start+original[7].value]
+                    start=cm[9].value
+                    if encrypted:
+                        header_bytes,after_header=module(key,4,raw,start,rg,col)
+                        header=thrift.decode(header_bytes).node
+                        body_payload,end=framed(raw,after_header)
+                        if algorithm=='AesGcmV1':
+                            body=gcm(key,2,body_payload,rg,col)
+                        else:
+                            unique(key,body_payload[:12])
+                            decryptor=Cipher(algorithms.AES(key),modes.CTR(body_payload[:12]+b'\0\0\0\1')).decryptor()
+                            body=decryptor.update(body_payload[12:])+decryptor.finalize()
+                        assert header.value[3].value==end-after_header
+                    else:
+                        decoded=thrift.decode(raw[start:]);header=decoded.node
+                        after_header=start+decoded.consumed
+                        end=after_header+header.value[3].value
+                        body=raw[after_header:end]
+                    assert body==old_body,(path.name,col,'compressed page body')
+                    assert cm[7].value==end-start
+                    assert cm[6].value==original[6].value+(after_header-start)-old_header.consumed
+                    for field in (1,2,5,8):
+                        if field in old_header.node.value:assert canonical(header.value[field])==canonical(old_header.node.value[field])
+                    for offset_field,length_field,kind in ((4,5,7),(6,7,6)):
+                        assert (offset_field in chunk.value)==(offset_field in source_chunk.value)
+                        if offset_field not in chunk.value:continue
+                        offset,size=chunk.value[offset_field].value,chunk.value[length_field].value
+                        data=raw[offset:offset+size]
+                        if encrypted:
+                            data,used=module(key,kind,data,rg=rg,col=col);assert used==size
+                        old_offset,old_size=source_chunk.value[offset_field].value,source_chunk.value[length_field].value
+                        old_data=source[old_offset:old_offset+old_size]
+                        if kind==6:
+                            assert data==old_data
+                        else:
+                            oi,old_oi=thrift.decode(data).node,thrift.decode(old_data).node
+                            page=oi.value[1].value[0].value
+                            assert page[1].value==start and page[2].value==end-start and page[3].value==0
+                            page[1],page[2]=old_oi.value[1].value[0].value[1],old_oi.value[1].value[0].value[2]
+                            assert canonical(oi)==canonical(old_oi)
+                    assert (14 in cm)==(14 in original)
+                    if 14 in cm:
+                        offset=cm[14].value
+                        old=source[original[14].value:original[14].value+original[15].value]
+                        parsed=thrift.decode(old)
+                        if encrypted:
+                            bloom_header,after=module(key,8,raw,offset,rg,col)
+                            bloom_bits,after_bits=module(key,9,raw,after,rg,col)
+                            assert bloom_header==old[:parsed.consumed] and bloom_bits==old[parsed.consumed:]
+                            assert cm[15].value==after_bits-offset
+                        else:
+                            assert raw[offset:offset+cm[15].value]==old
+            if codec!='LZO':
+                arrow=scratch/'decoded.arrow'
+                head,columns=cpp(path,f'writer-{width}',arrow)
+                assert pa.ipc.open_stream(arrow).read_all().equals(controls[(shape,codec,version)],check_metadata=False),(path.name,'C++ values')
+                for column in columns:
+                    assert column['encrypted']==(column['column']!=0)
+                    cpp_queries+=column['bloomValuesChecked']
+                direct=True
+            else:
+                direct=False
+            records.append({'file':path.name,'independentCryptoAndLiteralMetadataMatch':True,'allModulePlaintextsMatchControls':True,'cppEncryptedValuesIndexesAndBlooms':direct,'lzoViaIndependentControl':codec=='LZO'})
+    proof={'fileCount':len(records),'files':records,'allPassed':True,'uniqueKeyNoncePairs':len(nonces),'authenticatedOrCtrModules':module_count,'cppEncryptedFiles':sum(r['cppEncryptedValuesIndexesAndBlooms'] for r in records),'cppBloomQueries':cpp_queries,'liblzo2ControlOperations':lzo_calls,'controls':len(controls),'referenceSHA256':hashlib.sha256(args.reference.read_bytes()).hexdigest()}
+    args.output.write_text(json.dumps(proof,indent=2)+'\n')
+    print(f'PASS: {len(records)} encrypted files, {module_count} independent module checks, {proof["cppEncryptedFiles"]} direct C++ reads, {cpp_queries} bloom probes',flush=True)
+
+
+if __name__=='__main__':
+    main()
diff --git a/scripts/parquet_encryption_interop.py b/scripts/parquet_encryption_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_encryption_interop.py
@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Read Wireform's encrypted output with Apache Arrow's independent C++ reader.
+
+Uses a deliberately public test key and a local mock KMS. Covers both page
+versions, AES128/192/256, GCM/CTR, footer-only/selective column encryption,
+and two row groups. Independent C++ metadata checks prove that requested
+column encryption is present, in addition to checking decoded values.
+No real KMS, account, or credentials are used.
+"""
+
+import argparse
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+import pyarrow.parquet.encryption as pe
+
+
+class TestKms(pe.KmsClient):
+    def unwrap_key(self, wrapped_key, master_key_identifier):
+        widths = {"test-key": 16, "test-key-16": 16, "test-key-24": 24, "test-key-32": 32}
+        if master_key_identifier != "wireform-test" or wrapped_key not in widths:
+            raise ValueError("unexpected test key metadata")
+        return bytes([0x42]) * widths[wrapped_key]
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--probe", type=Path, required=True)
+    parser.add_argument("--reference", type=Path, required=True,
+                        help="C++ fixture oracle built by build_parquet_encrypted_reference.py")
+    args = parser.parse_args()
+    factory = pe.CryptoFactory(lambda config: TestKms())
+    connection = pe.KmsConnectionConfig(kms_instance_id="wireform-test")
+    properties = factory.file_decryption_properties(connection)
+    schema = pa.schema([pa.field("x", pa.int32(), nullable=False), pa.field("y", pa.string(), nullable=False)])
+    expected = pa.table({"x": [1, 2, 3, 4, 5], "y": ["a", "b", "c", "d", "e"]}, schema=schema)
+    with tempfile.TemporaryDirectory(prefix="wireform-parquet-encryption-") as tmp:
+        root = Path(tmp)
+        for width in (16, 24, 32):
+            directory = root / str(width)
+            directory.mkdir()
+            metadata = directory / "test-key.json"
+            metadata.write_text(json.dumps({
+                "keyMaterialType": "PKMT1", "internalStorage": True,
+                "isFooterKey": True, "kmsInstanceID": "wireform-test", "kmsInstanceURL": "",
+                "masterKeyID": "wireform-test", "wrappedDEK": f"test-key-{width}",
+                "doubleWrapping": False,
+            }))
+            subprocess.run([str(args.probe.resolve()), "--encrypted", str(directory), str(metadata), str(width)], check=True)
+        fixtures = sorted(root.rglob("*.parquet"))
+        if len(fixtures) != 24:
+            raise AssertionError(f"expected 24 encryption fixtures, got {len(fixtures)}")
+        for path in fixtures:
+            assert path.read_bytes()[:4] == b"PARE", path.name
+            file = pq.ParquetFile(path, decryption_properties=properties)
+            assert file.num_row_groups == 2, path.name
+            table = file.read(use_threads=False)
+            if not table.equals(expected, check_metadata=False):
+                raise AssertionError(f"{path.name}: unexpected decoded values/types: {table}")
+            # Matching values alone cannot prove requested column encryption:
+            # a writer that ignores the option still round-trips through a
+            # reader with the footer key. Inspect independent C++ crypto
+            # metadata and read every page/index/bloom through that library.
+            arrow_output = root / (path.name + ".arrow")
+            reference = subprocess.run([str(args.reference.resolve()), str(path), str(arrow_output), "native-forward"],
+                                       capture_output=True, text=True, check=True)
+            header, *columns = map(json.loads, reference.stdout.splitlines())
+            assert header["rowGroups"] == 2, path.name
+            for column in columns:
+                requested = "-column" in path.name and column["column"] == 0
+                assert column["encrypted"] == requested, (path.name, column["column"], "column encryption option ignored")
+                assert column["columnIndex"] and column["offsetPages"] == 1, path.name
+                if column["column"] == 0:
+                    assert column["bloomBytes"] > 0, path.name
+            independent = pa.ipc.open_stream(arrow_output).read_all()
+            assert independent.equals(expected, check_metadata=False), path.name
+            # Corrupt the final footer authentication-tag byte. Even files
+            # using CTR for pages must authenticate their footer with GCM.
+            tampered = bytearray(path.read_bytes())
+            tampered[-9] ^= 1
+            try:
+                pq.ParquetFile(pa.BufferReader(tampered), decryption_properties=properties)
+            except (OSError, pa.ArrowException):
+                pass
+            else:
+                raise AssertionError(f"{path.name}: accepted a tampered footer")
+            print(f"PASS {path.name}")
+        print(f"{len(fixtures)} encrypted files verified with PyArrow {pa.__version__}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_file_arrow_interop.py b/scripts/parquet_file_arrow_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_file_arrow_interop.py
@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""FILE extension interoperability with a pinned upstream arrow-rs reader/writer.
+
+The reference must enable parquet/file_experimental. PyArrow is used only for
+Arrow IPC fixture construction and comparison, not to interpret Parquet FILE.
+"""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import subprocess
+import shutil
+import tempfile
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+from parquet_file_interop import check_annotations, footer
+
+
+NAMES = ("uri", "offset", "size", "content_type", "checksum", "inline")
+EXTENSION = b"arrow.parquet.file"
+
+
+def run(*args):
+    subprocess.run(list(map(str, args)), check=True)
+
+
+def file_info(field):
+    metadata = field.metadata or {}
+    assert metadata[b"ARROW:extension:name"] == EXTENSION, field
+    assert metadata.get(b"ARROW:extension:metadata", b"") == b"", field
+    ident = metadata.get(b"PARQUET:field_id")
+    children = {child.name: (child.metadata or {}).get(b"PARQUET:field_id") for child in field.type}
+    return ident, children
+
+
+def file_infos(schema):
+    result = {}
+    def visit(field, path):
+        if (field.metadata or {}).get(b"ARROW:extension:name") == EXTENSION:
+            result[path] = file_info(field)
+        if pa.types.is_struct(field.type):
+            for child in field.type:
+                visit(child, path + "." + child.name)
+        elif pa.types.is_list(field.type):
+            visit(field.type.value_field, path + "." + field.type.value_field.name)
+    for field in schema:
+        visit(field, field.name)
+    return result
+
+
+def check_file(path, schema):
+    info = file_infos(schema)
+    assert len(info) == 1
+    parent_id, children = next(iter(info.values()))
+    check_annotations(path, {name: int(ident) for name, ident in children.items()})
+    _, metadata = footer(path)
+    groups = [element for element in metadata.value[2].value if 10 in element.value and 19 in element.value[10].value]
+    assert len(groups) == 1 and groups[0].value[9].value == int(parent_id)
+
+
+def read_file(path):
+    with ipc.open_file(str(path)) as reader:
+        return reader.read_all()
+
+
+def read_stream(path):
+    with ipc.open_stream(str(path)) as reader:
+        return reader.read_all()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--writer", required=True, type=Path)
+    parser.add_argument("--reader", required=True, type=Path)
+    parser.add_argument("--reference", required=True, type=Path)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    profiles = {
+        "ordinary": (pa.string(), pa.binary()),
+        "large": (pa.large_string(), pa.large_binary()),
+        "view": (pa.string_view(), pa.binary_view()),
+    }
+    with tempfile.TemporaryDirectory(prefix="parquet-file-arrow-") as directory:
+        root = Path(directory)
+        incoming = root / "incoming"
+        incoming.mkdir()
+        expected = {}
+        for profile, (string_type, binary_type) in profiles.items():
+            for mask in range(1, 64):
+                selected = [name for index, name in enumerate(NAMES) if mask & (1 << index)]
+                selected.reverse()
+                fields = []
+                for name in selected:
+                    ty = binary_type if name == "inline" else pa.int64() if name in ("offset", "size") else string_type
+                    fields.append(pa.field(name, ty, nullable=True, metadata={b"PARQUET:field_id": str(NAMES.index(name) + 21).encode()}))
+                metadata = {b"ARROW:extension:name": EXTENSION, b"PARQUET:field_id": b"-91"}
+                if mask % 2:
+                    metadata[b"ARROW:extension:metadata"] = b""
+                field = pa.field("f", pa.struct(fields), nullable=True, metadata=metadata)
+                rows = [None]
+                for index in range(3):
+                    if "uri" not in selected and "inline" not in selected:
+                        rows.append(None)
+                        continue
+                    value = {}
+                    payload = b"" if index == 0 else bytes(range(80))
+                    if "inline" in selected:
+                        value["inline"] = payload
+                    has_uri = "uri" in selected and not ("inline" in selected and index == 2)
+                    if "uri" in selected:
+                        value["uri"] = "../assets/a%20b-long-name.bin?raw=1#part" if has_uri else ""
+                    if has_uri:
+                        if "size" in selected:
+                            value["size"] = len(payload) if "inline" in selected else index * 17
+                        if "offset" in selected and "size" in selected:
+                            value["offset"] = 0 if index == 0 else 2**63-1
+                    if "content_type" in selected:
+                        value["content_type"] = "" if index == 0 else "application/octet-stream"
+                    if "checksum" in selected:
+                        value["checksum"] = "MD5:" + hashlib.md5(payload).hexdigest() if "inline" in selected else "ETAG:opaque:token"
+                    rows.append(value)
+                table = pa.Table.from_arrays([pa.array(rows, field.type)], schema=pa.schema([field]))
+                name = f"{profile}-{mask:02}"
+                expected[name] = table
+                with ipc.new_file(str(incoming / (name + ".arrow")), table.schema) as writer:
+                    for batch in table.to_batches(max_chunksize=2):
+                        writer.write_batch(batch)
+        full = expected["view-63"]
+        values = full.column(0).to_pylist()
+        element = full.schema.field(0).with_name("element")
+        list_field = pa.field("files", pa.list_(element))
+        struct_field = pa.field("wrapper", pa.struct([full.schema.field(0), pa.field("side", pa.int32())]))
+        for name, field, rows in (
+            ("nested-list", list_field, [None, [], [None, values[1]], [values[2], values[3]]]),
+            ("nested-struct", struct_field, [None, {"f": values[1], "side": 7}, {"f": None, "side": 9}, {"f": values[3], "side": None}]),
+        ):
+            table = pa.Table.from_arrays([pa.array(rows, field.type)], schema=pa.schema([field]))
+            expected[name] = table
+            with ipc.new_file(str(incoming / (name + ".arrow")), table.schema) as writer:
+                for batch in table.to_batches(max_chunksize=2):
+                    writer.write_batch(batch)
+        native, rust, rust_arrow, native_arrow = (root / name for name in ("native", "rust", "rust-arrow", "native-arrow"))
+        run(args.writer, "--nested-from-arrow", incoming, native)
+        run(args.reference, "from-arrow", incoming, rust)
+        run(args.reference, "to-arrow", native, rust_arrow)
+        run(args.reader, rust, "--arrow-output", native_arrow)
+        for source in (native, rust):
+            flat = root / (source.name + "-flat")
+            flat.mkdir()
+            for path in source.glob("*.parquet"):
+                if not path.name.startswith("nested-"):
+                    shutil.copyfile(path, flat / path.name)
+            run(args.writer, "--file-check", flat)
+        for name, table in expected.items():
+            for folder in (native, rust):
+                check_file(folder / (name + ".parquet"), table.schema)
+            for actual in (read_file(rust_arrow / (name + ".arrow")), read_stream(native_arrow / (name + ".parquet.arrows"))):
+                assert actual.to_pydict() == table.to_pydict(), name
+                assert file_infos(actual.schema) == file_infos(table.schema), name
+        # Exercise inferred FILE metadata as input to both writers, including
+        # child/group IDs rather than relying on the original embedded schema.
+        restored_native, restored_rust = root / "restored-native", root / "restored-rust"
+        run(args.writer, "--nested-from-arrow", rust_arrow, restored_native)
+        run(args.reference, "from-stream", native_arrow, restored_rust)
+        for name, table in expected.items():
+            for folder in (restored_native, restored_rust):
+                check_file(folder / (name + ".parquet"), table.schema)
+        run(args.reader, restored_rust, "--arrow-output", root / "restored-arrow")
+        run(args.reference, "to-arrow", restored_native, root / "restored-rust-arrow")
+        for name, table in expected.items():
+            for actual in (read_stream(root / "restored-arrow" / (name + ".parquet.arrows")), read_file(root / "restored-rust-arrow" / (name + ".arrow"))):
+                assert actual.to_pydict() == table.to_pydict(), name
+                assert file_infos(actual.schema) == file_infos(table.schema), name
+        # Nonempty future extension metadata must not silently become a plain
+        # struct in the native writer.
+        invalid = root / "invalid"
+        invalid.mkdir()
+        table = expected["ordinary-01"]
+        field = table.schema.field(0).with_metadata({b"ARROW:extension:name": EXTENSION, b"ARROW:extension:metadata": b"v2"})
+        table = pa.Table.from_arrays(table.columns, schema=pa.schema([field]))
+        with ipc.new_file(str(invalid / "invalid.arrow"), table.schema) as writer:
+            writer.write_table(table)
+        result = subprocess.run([str(args.writer), "--nested-from-arrow", str(invalid), str(root / "rejected")], capture_output=True, text=True)
+        assert result.returncode != 0 and "FILE extension" in result.stdout + result.stderr
+    report = {"status": "passed", "fieldSubsets": 63, "storageProfiles": list(profiles), "flatInputs": 189, "nestedInputs": 2, "inputFiles": len(expected),
+              "crossReaderComparisons": len(expected) * 4, "annotationChecks": len(expected) * 4,
+              "reference": "Pinned upstream arrow-rs with file_experimental; skips embedded Arrow metadata on read",
+              "referenceBinarySHA256": hashlib.sha256(args.reference.read_bytes()).hexdigest(),
+              "covered": "FILE identity, empty metadata, optional named fields, child/group IDs, values/nulls, multi-batch IPC, ordinary/large/view arrays, both readers/writers and roundtrips"}
+    if args.output:
+        args.output.write_text(json.dumps(report, indent=2) + "\n")
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_file_interop.py b/scripts/parquet_file_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_file_interop.py
@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Independently frame FILE logical groups using Apache Thrift and PyArrow."""
+import argparse
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from parquet_lzo_interop import Node, decode, encode
+
+
+FIELD_TYPES = {
+    "uri": pa.string(), "offset": pa.int64(), "size": pa.int64(),
+    "content_type": pa.string(), "checksum": pa.string(), "inline": pa.binary(),
+}
+URI = "../images/a%20b.png?raw=1#part"
+
+
+def footer(path):
+    data = path.read_bytes()
+    length = struct.unpack("<I", data[-8:-4])[0]
+    parsed = decode(data[-8-length:-8])
+    assert parsed.consumed == length
+    return data[:-8-length], parsed.node
+
+
+def set_file_annotation(path):
+    prefix, metadata = footer(path)
+    elements = metadata.value[2].value
+    group = elements[1]
+    assert group.value[4].value == b"f" and 1 not in group.value
+    group.value[10] = Node(TType.STRUCT, {19: Node(TType.STRUCT, {})})
+    raw = encode(metadata)
+    path.write_bytes(prefix + raw + struct.pack("<I", len(raw)) + b"PAR1")
+
+
+def check_annotations(path, expected_ids):
+    _, metadata = footer(path)
+    elements = metadata.value[2].value
+    groups = [e for e in elements if 10 in e.value and 19 in e.value[10].value]
+    assert len(groups) == 1, path
+    assert groups[0].value[10].value[19].value == {}, path
+    fields = {e.value[4].value.decode(): e for e in elements if 1 in e.value}
+    for name, field_id in expected_ids.items():
+        element = fields[name]
+        assert element.value[3].value == 1, (path, name, "not OPTIONAL")
+        assert (element.value[9].value if 9 in element.value else None) == field_id
+
+
+def physical_copy(source, output):
+    """PyArrow 26 rejects FILE; remove only that annotation for its value oracle.
+
+    The original annotated files are independently inspected with Apache Thrift
+    and decoded by the native reader. This is not a PyArrow FILE semantic test.
+    """
+    prefix, metadata = footer(source)
+    for element in metadata.value[2].value:
+        annotation = element.value.get(10)
+        if annotation is not None and 19 in annotation.value:
+            assert len(annotation.value) == 1
+            del element.value[10]
+    raw = encode(metadata)
+    output.write_bytes(prefix + raw + struct.pack("<I", len(raw)) + b"PAR1")
+    assert output.read_bytes()[:len(prefix)] == prefix
+    return pq.read_table(output)
+
+
+def read_export(path):
+    with ipc.open_stream(str(path)) as reader:
+        return reader.read_all()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--writer", required=True, type=Path)
+    parser.add_argument("--reader", required=True, type=Path)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    names = list(FIELD_TYPES)
+    with tempfile.TemporaryDirectory(prefix="parquet-file-") as directory:
+        root = Path(directory)
+        native, foreign, exported = (root / name for name in ("native", "foreign", "exported"))
+        foreign.mkdir()
+        physical = root / "physical"
+        physical.mkdir()
+        subprocess.run([str(args.writer), "--file", str(native)], check=True)
+        full_rows = [None, {"inline": b""}, {"uri": URI},
+                     {"uri": URI, "offset": 0, "size": len(b"whole inline payload"), "inline": b"whole inline payload"},
+                     {"uri": URI, "offset": 2**63-1, "size": 2**63-1},
+                     {"inline": b"", "uri": "", "content_type": "", "checksum": ""}]
+        def complete(rows, fields):
+            return [None if row is None else {name: row.get(name) for name in fields} for row in rows]
+        expected = {
+            "full": {"f": complete(full_rows, names)},
+            "reordered": {"f": complete(full_rows, list(reversed(names)))},
+            "inline": {"f": [None, {"inline": b""}, {"inline": b"bytes"}]},
+            "uri": {"f": [None, {"uri": URI}, {"uri": "uri.parquet"}]},
+            "metadata-only": {"f": [None, None]},
+            "list": {"files": [None, [], [None, complete([{"uri": URI}], names)[0], complete([{"inline": b""}], names)[0]]]},
+        }
+        for name, values in expected.items():
+            path = native / (name + ".parquet")
+            ids = {field: index + 10 for index, field in enumerate(names)} if name in ("full", "reordered", "list") else {field: None for field in next(iter(values.values()))[-1] or []}
+            if name == "metadata-only": ids = {"content_type": None}
+            check_annotations(path, ids)
+            table = physical_copy(path, physical / (name + ".parquet"))
+            assert table.to_pydict() == values, (name, table.to_pydict(), values)
+        subprocess.run([str(args.reader), str(native), "--arrow-output", str(root / "native-arrow")], check=True)
+        for name, values in expected.items():
+            assert read_export(root / "native-arrow" / (name + ".parquet.arrows")).to_pydict() == values, name
+        expected_foreign = {}
+        # Every nonempty field subset. Reverse selected names to ensure the
+        # reader cannot interpret a field by its fixed ordinal position.
+        for mask in range(1, 64):
+            selected = [name for index, name in enumerate(names) if mask & (1 << index)]
+            selected.reverse()
+            fields = [pa.field(name, FIELD_TYPES[name], nullable=True,
+                               metadata={b"PARQUET:field_id": str(names.index(name) + 40).encode()}) for name in selected]
+            value = {}
+            if "inline" in selected: value["inline"] = b""
+            if "uri" in selected:
+                value["uri"] = URI
+                if "size" in selected: value["size"] = 0
+                if "offset" in selected and "size" in selected: value["offset"] = 0
+            if "content_type" in selected: value["content_type"] = "application/octet-stream"
+            if "checksum" in selected: value["checksum"] = "future:opaque:a"
+            rows = [None, value if ("inline" in selected or "uri" in selected) else None, None]
+            typ = pa.struct(fields)
+            table = pa.Table.from_arrays([pa.array(rows, typ)], names=["f"])
+            path = foreign / (f"subset-{mask:02}.parquet")
+            pq.write_table(table, path, compression=("NONE", "ZSTD", "SNAPPY")[mask % 3],
+                           data_page_version="2.0" if mask % 2 else "1.0", use_dictionary=bool(mask % 2),
+                           store_schema=False, write_page_checksum=True)
+            set_file_annotation(path)
+            check_annotations(path, {name: names.index(name) + 40 for name in selected})
+            assert physical_copy(path, physical / path.name).to_pydict() == table.to_pydict()
+            expected_foreign[path.stem] = table.to_pydict()
+        subprocess.run([str(args.writer), "--file-check", str(foreign)], check=True)
+        subprocess.run([str(args.reader), str(foreign), "--arrow-output", str(exported)], check=True)
+        for name, values in expected_foreign.items():
+            actual = read_export(exported / (name + ".parquet.arrows")).to_pydict()
+            assert actual == values, (name, actual, values)
+        # A recognized FILE annotation must not hide malformed child layouts.
+        invalid = root / "invalid"
+        invalid.mkdir()
+        template = foreign / "subset-01.parquet"
+        prefix, metadata = footer(template)
+        metadata.value[2].value[2].value[4] = Node(TType.STRING, b"URI")
+        raw = encode(metadata)
+        (invalid / "wrong-case.parquet").write_bytes(prefix + raw + struct.pack("<I", len(raw)) + b"PAR1")
+        result = subprocess.run([str(args.reader), str(invalid)], capture_output=True, text=True)
+        assert result.returncode != 0 and "FILE field" in result.stdout + result.stderr
+        try:
+            pq.read_table(native / "full.parquet")
+        except OSError as error:
+            assert "Logical type Undefined cannot be applied to group node" in str(error)
+            reference_status = "PyArrow rejects unknown FILE tag; only unannotated physical values compared"
+        else:
+            reference_status = "PyArrow reads annotated FILE values"
+    report = {"status": "passed", "nativeFiles": 6, "foreignSubsets": 63,
+              "annotationOracle": "independent Apache Thrift tag19, exact names, OPTIONAL children and IDs",
+              "valueOracle": "PyArrow physical storage with only FILE annotation removed",
+              "nativeReader": "annotated FILE values and typed resolution",
+              "pyarrowVersion": pa.__version__, "pyarrowFileSupport": reference_status,
+              "emptyFieldSubset": "not covered: zero-leaf group support remains a separate release gate"}
+    if args.output: args.output.write_text(json.dumps(report, indent=2) + "\n")
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_file_preflight.py b/scripts/parquet_file_preflight.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_file_preflight.py
@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Check whole-file benchmark values/layouts and prove rejection controls.
+
+Call before measurements. Positive fixtures come independently from wireform,
+parquet-rs and Arrow C++. Negative fixtures retain100000rows but change values,
+schema, compression, page version, dictionary mode or page/group boundaries.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+from parquet_bench_compare import CODECS, N_ROWS, make_dataset, write_table
+
+
+def verify(binary, directory, success=True, message=None):
+    result = subprocess.run([str(binary), "--verify-fixtures", str(directory)],
+                            capture_output=True, text=True)
+    if success:
+        assert result.returncode == 0, (directory.name, result.stdout, result.stderr)
+    else:
+        assert result.returncode != 0, (directory.name, "unexpected verification success")
+        assert "benchmark fixture:" in result.stderr, (directory.name, result.stderr)
+        if message:
+            assert message in result.stderr, (directory.name, result.stderr)
+
+
+def reference_write(table, path, **overrides):
+    options = dict(compression="NONE", use_dictionary=False, column_encoding="PLAIN", data_page_version="2.0",
+                   write_page_index=False, store_schema=False, row_group_size=N_ROWS,
+                   data_page_size=8 * 1024 * 1024, max_rows_per_page=N_ROWS)
+    options.update(overrides)
+    if options["use_dictionary"]:
+        options.pop("column_encoding", None)
+    pq.write_table(table, path, **options)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--wireform-bench", type=Path, required=True)
+    parser.add_argument("--rust-bench", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path)
+    args = parser.parse_args()
+    native, rust = args.wireform_bench.resolve(), args.rust_bench.resolve()
+    temporary = tempfile.TemporaryDirectory(prefix="wireform-parquet-file-preflight-")
+    root = args.output_dir or Path(temporary.name)
+    root.mkdir(parents=True, exist_ok=True)
+    expected = make_dataset()
+    for label, binary in (("native", native), ("rust", rust)):
+        subprocess.run([str(binary), "--write-fixtures", str(root / label)], check=True)
+    cpp = root / "cpp"
+    cpp.mkdir(exist_ok=True)
+    for codec in CODECS:
+        (cpp / f"{codec}.parquet").write_bytes(write_table(expected, codec).to_pybytes())
+    for label in ("native", "rust", "cpp"):
+        directory = root / label
+        verify(native, directory)
+        for codec in CODECS:
+            actual = pq.read_table(directory / f"{codec}.parquet", use_threads=False, pre_buffer=False)
+            actual.validate(full=True)
+            assert actual.equals(expected), (label, codec, "full values/schema differ")
+        print("PASS full values/schema/layout:", label)
+    changed_id = pa.concat_arrays([expected.column(0).combine_chunks().slice(0, N_ROWS - 1), pa.array([-999999], type=pa.int64())])
+    changed_bool = pa.concat_arrays([expected.column(3).combine_chunks().slice(0, N_ROWS - 1), pa.array([True], type=pa.bool_())])
+    changed_schema = pa.schema([pa.field("id", pa.int64(), nullable=True), *list(expected.schema)[1:]])
+    cases = [
+        ("last-id", expected.set_column(0, expected.schema.field(0), changed_id), {}, "decoded values differ"),
+        ("last-bool", expected.set_column(3, expected.schema.field(3), changed_bool), {}, "decoded values differ"),
+        ("nullable-schema", pa.Table.from_arrays(expected.columns, schema=changed_schema), {}, "schema differs"),
+        ("codec", expected, {"compression": "snappy"}, "codec differs"),
+        ("dictionary", expected, {"use_dictionary": True}, "disable dictionary"),
+        ("v1-pages", expected, {"data_page_version": "1.0"}, "V2 data pages"),
+        ("row-groups", expected, {"row_group_size": 20000}, None),
+        ("multiple-pages", expected, {"max_rows_per_page": 8192}, None),
+        ("page-index", expected, {"write_page_index": True}, "disable page indexes"),
+    ]
+    for label, table, options, message in cases:
+        destination = root / ("wrong-" + label)
+        shutil.copytree(root / "native", destination, dirs_exist_ok=True)
+        reference_write(table, destination / "uncompressed.parquet", **options)
+        verify(native, destination, success=False, message=message)
+        print("PASS rejection:", label)
+    print("PASS:9 independently-written valid fixtures and9 rejection controls;400000values checked per file")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_file_reference.lock b/scripts/parquet_file_reference.lock
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_file_reference.lock
@@ -0,0 +1,743 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "const-random",
+ "getrandom 0.3.4",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "arrow-array"
+version = "60.1.0"
+dependencies = [
+ "ahash",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "chrono",
+ "half",
+ "hashbrown",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-buffer"
+version = "60.1.0"
+dependencies = [
+ "bytes",
+ "half",
+ "num-bigint",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-cmp"
+version = "60.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-schema",
+]
+
+[[package]]
+name = "arrow-data"
+version = "60.1.0"
+dependencies = [
+ "arrow-buffer",
+ "arrow-schema",
+ "half",
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-ipc"
+version = "60.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "arrow-select",
+ "flatbuffers",
+]
+
+[[package]]
+name = "arrow-schema"
+version = "60.1.0"
+
+[[package]]
+name = "arrow-select"
+version = "60.1.0"
+dependencies = [
+ "ahash",
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-cmp",
+ "arrow-data",
+ "arrow-schema",
+ "num-traits",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "base64"
+version = "0.23.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
+
+[[package]]
+name = "bitflags"
+version = "2.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cc"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "375989decec1a0fa424442bed520fa12ede43a48475ce8c7417d2c69b32b5f6b"
+dependencies = [
+ "find-msvc-tools",
+ "jobserver",
+ "libc",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "num-traits",
+ "windows-link",
+]
+
+[[package]]
+name = "const-random"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "87e00182fe74b066627d63b85fd550ac2998d4b0bd86bfed477a0ae4c7c71359"
+dependencies = [
+ "const-random-macro",
+]
+
+[[package]]
+name = "const-random-macro"
+version = "0.1.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9d839f2a20b0aee515dc581a6172f2321f96cab76c1a38a4c584a194955390e"
+dependencies = [
+ "getrandom 0.2.17",
+ "once_cell",
+ "tiny-keccak",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48"
+
+[[package]]
+name = "flatbuffers"
+version = "25.12.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35f6839d7b3b98adde531effaf34f0c2badc6f4735d26fe74709d8e513a96ef3"
+dependencies = [
+ "bitflags",
+ "rustc_version",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
+
+[[package]]
+name = "futures-task"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
+
+[[package]]
+name = "futures-util"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 5.3.0",
+ "wasip2",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 6.0.0",
+]
+
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "num-traits",
+ "zerocopy",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "jobserver"
+version = "0.1.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c00acbd29eabad4a2392fa0e921c874934dbbf4194312ad20f04a0ed67a3cb3"
+dependencies = [
+ "getrandom 0.4.3",
+ "libc",
+]
+
+[[package]]
+name = "js-sys"
+version = "0.3.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
+[[package]]
+name = "log"
+version = "0.4.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d15f86d12da44cd8d4ec3c73984537eb7f4cadcb9776a575a0a8a05ca11005c"
+
+[[package]]
+name = "lz4_flex"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ecbdfe44b1bd960b68170b417450a628c43f7cf56bb3c5317e61cb230ee7f226"
+dependencies = [
+ "twox-hash",
+]
+
+[[package]]
+name = "num-bigint"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93e7820bc0a80a0238e650327316f929ba18d5be054b647490a3a6a339f3e7c0"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+ "libm",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "parquet"
+version = "60.1.0"
+dependencies = [
+ "ahash",
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-ipc",
+ "arrow-schema",
+ "arrow-select",
+ "base64",
+ "bytes",
+ "chrono",
+ "half",
+ "hashbrown",
+ "lz4_flex",
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+ "seq-macro",
+ "snap",
+ "twox-hash",
+ "zstd",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "pkg-config"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "rustc_version"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
+dependencies = [
+ "semver",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "snap"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "199905e6153d6405f9728fe44daace35f8f837bbf830bb6e85fbd5828709a886"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "tiny-keccak"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c9d3793400a45f954c52e73d068316d76b6f4e36977e3fcebb13a2721e80237"
+dependencies = [
+ "crunchy",
+]
+
+[[package]]
+name = "twox-hash"
+version = "2.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "86a801b3cea342a06d468c8710662aa29e5e05e4f5c0d62f00bbb7f2ad7941c2"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c"
+dependencies = [
+ "cfg-if",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "wireform-parquet-file-reference"
+version = "0.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-ipc",
+ "parquet",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zstd"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf06bd8162af0734b344780deb55b42a2429ae430870d13fcc12f238e880fe6e"
+dependencies = [
+ "zstd-safe",
+]
+
+[[package]]
+name = "zstd-safe"
+version = "8.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae42c0555055784c70058d19ba8e275528e8a99a706684868ace5da4e716a4ab"
+dependencies = [
+ "zstd-sys",
+]
+
+[[package]]
+name = "zstd-sys"
+version = "2.1.0+zstd.1.5.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ef0a8027ec3ee71300ab3bcbcd0393f434aa72b91ca6d635a39941deae8eea0"
+dependencies = [
+ "cc",
+ "pkg-config",
+]
diff --git a/scripts/parquet_file_reference.rs b/scripts/parquet_file_reference.rs
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_file_reference.rs
@@ -0,0 +1,45 @@
+use std::{env, fs, fs::File, path::Path};
+use arrow_array::RecordBatchReader;
+use arrow_ipc::{reader::{FileReader, StreamReader}, writer::FileWriter};
+use parquet::arrow::{ArrowWriter, arrow_reader::{ArrowReaderOptions, ParquetRecordBatchReaderBuilder}};
+use parquet::file::properties::WriterProperties;
+
+fn convert(mode: &str, input: &Path, output: &Path) -> Result<(), Box<dyn std::error::Error>> {
+    if mode == "to-arrow" {
+        let options = ArrowReaderOptions::new().with_skip_arrow_metadata(true);
+        let reader = ParquetRecordBatchReaderBuilder::try_new_with_options(File::open(input)?, options)?.build()?;
+        let schema = reader.schema().clone();
+        let mut writer = FileWriter::try_new(File::create(output)?, &schema)?;
+        for batch in reader { writer.write(&batch?)?; }
+        writer.finish()?;
+    } else if mode == "from-arrow" {
+        let reader = FileReader::try_new(File::open(input)?, None)?;
+        let mut writer = ArrowWriter::try_new(File::create(output)?, reader.schema(), Some(WriterProperties::builder().build()))?;
+        for batch in reader { writer.write(&batch?)?; }
+        writer.close()?;
+    } else if mode == "from-stream" {
+        let reader = StreamReader::try_new(File::open(input)?, None)?;
+        let mut writer = ArrowWriter::try_new(File::create(output)?, reader.schema(), Some(WriterProperties::builder().build()))?;
+        for batch in reader { writer.write(&batch?)?; }
+        writer.close()?;
+    } else { return Err("mode must be to-arrow, from-arrow or from-stream".into()); }
+    Ok(())
+}
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let args: Vec<_> = env::args().collect();
+    if args.len() != 4 { return Err("usage: parquet-file-reference MODE INPUT_DIR OUTPUT_DIR".into()); }
+    fs::create_dir_all(&args[3])?;
+    let mut entries = fs::read_dir(&args[2])?.collect::<Result<Vec<_>, _>>()?;
+    entries.sort_by_key(|entry| entry.path());
+    for entry in entries {
+        let input = entry.path();
+        let wanted = if args[1] == "to-arrow" { "parquet" } else if args[1] == "from-stream" { "arrows" } else { "arrow" };
+        if input.extension().and_then(|ext| ext.to_str()) != Some(wanted) { continue; }
+        let extension = if args[1] == "to-arrow" { "arrow" } else { "parquet" };
+        let output = Path::new(&args[3]).join(input.file_stem().ok_or("missing file stem")?).with_extension(extension);
+        convert(&args[1], &input, &output)?;
+        println!("OK {}", input.display());
+    }
+    Ok(())
+}
diff --git a/scripts/parquet_file_zero_interop.py b/scripts/parquet_file_zero_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_file_zero_interop.py
@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Zero-leaf FILE schemas: independent footer fixtures and physical value oracle.
+
+PyArrow cannot interpret FILE itself; Apache Thrift checks the annotation,
+and PyArrow reads a copy with only FILE annotations removed. Upstream Rust
+currently rejects zero-field writes and drops the FILE on read, so its
+limitation is reported separately rather than used as the expected result.
+"""
+import argparse
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from thrift.Thrift import TType as T
+from parquet_lzo_interop import Node, encode
+from parquet_file_interop import footer
+from parquet_file_arrow_interop import file_infos, read_stream
+
+
+def node(kind, value):
+    return Node(kind, value)
+
+
+def element(name, repetition=None, children=None, file=False):
+    fields = {4: node(T.STRING, name.encode())}
+    if repetition is not None:
+        fields[3] = node(T.I32, repetition)
+    if children is not None:
+        fields[5] = node(T.I32, children)
+    if file:
+        fields[10] = node(T.STRUCT, {19: node(T.STRUCT, {})})
+    return node(T.STRUCT, fields)
+
+
+def write_footer(path, prefix, metadata):
+    raw = encode(metadata)
+    path.write_bytes(prefix + raw + struct.pack("<I", len(raw)) + b"PAR1")
+
+
+def physical_copy(path, output):
+    prefix, metadata = footer(path)
+    found = 0
+    for field in metadata.value[2].value:
+        logical = field.value.get(10)
+        if logical is not None and 19 in logical.value:
+            assert field.value[5].value == 0, path
+            assert 1 not in field.value, path
+            del field.value[10]
+            found += 1
+    assert found == 1, path
+    write_footer(output, prefix, metadata)
+    return pq.read_table(output)
+
+
+def project_physical_fields(path, output):
+    """Remove only zero-leaf FILE nodes; physical column bytes stay identical.
+
+    This lets C++ independently check the surviving parent/list boundaries
+    when its schema converter cannot handle a nested empty group.
+    """
+    prefix, metadata = footer(path)
+    fields = metadata.value[2].value
+    def walk(index, root=False):
+        field = fields[index]
+        index += 1
+        logical = field.value.get(10)
+        if logical is not None and 19 in logical.value:
+            assert field.value[5].value == 0
+            return [], index
+        if 1 in field.value:
+            return [field], index
+        children = []
+        count = 0
+        for _ in range(field.value[5].value):
+            nodes, index = walk(index)
+            if nodes:
+                count += 1
+                children.extend(nodes)
+        if not root and count == 0:
+            return [], index
+        field.value[5] = node(T.I32, count)
+        return [field] + children, index
+    projected, end = walk(0, root=True)
+    assert end == len(fields)
+    metadata.value[2].value = projected
+    write_footer(output, prefix, metadata)
+    return pq.read_table(output)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--writer", required=True, type=Path)
+    parser.add_argument("--reader", required=True, type=Path)
+    parser.add_argument("--reference", required=True, type=Path)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    metadata = {b"ARROW:extension:name": b"arrow.parquet.file", b"ARROW:extension:metadata": b"", b"PARQUET:field_id": b"27"}
+    optional = pa.field("empty", pa.struct([]), nullable=True, metadata=metadata)
+    required = optional.with_nullable(False)
+    anchor = pa.field("anchor", pa.int32(), nullable=False)
+    cases = {}
+    def case(name, field, rows):
+        cases[name] = pa.Table.from_arrays([pa.array(rows, field.type)], schema=pa.schema([field]))
+    case("root-nulls", optional.with_name("f"), [None] * 3)
+    case("root-empty-optional", optional.with_name("f"), [])
+    case("root-empty-required", required.with_name("f"), [])
+    cases["root-with-anchor"] = pa.Table.from_arrays([pa.array([None]*3, optional.type), pa.array([10,20,30], pa.int32())], schema=pa.schema([optional.with_name("f"), anchor]))
+    case("required-parent", pa.field("f", pa.struct([optional]), nullable=False), [{"empty": None}] * 3)
+    for fields in ([optional, anchor], [anchor, optional]):
+        name = "optional-parent-first" if fields[0].name == "empty" else "optional-parent-last"
+        case(name, pa.field("f", pa.struct(fields)), [None, {"empty": None, "anchor": 10}, {"empty": None, "anchor": 20}])
+    entry = pa.field("element", pa.struct([optional, anchor]), nullable=False)
+    case("list-anchored", pa.field("f", pa.list_(entry)), [None, [], [{"empty": None, "anchor": value} for value in range(5)]])
+    case("map-value", pa.field("f", pa.map_(pa.int32(), optional.with_name("value"))), [None, [], [(1, None), (2, None)]])
+    case("map-key-empty", pa.field("f", pa.map_(required.with_name("key"), pa.int32())), [None, [], []])
+    case("zero-row-list", pa.field("f", pa.list_(optional.with_name("element"))), [])
+    reference_limitations = {}
+    physical_compared = []
+    boundary_compared = []
+    with tempfile.TemporaryDirectory(prefix="parquet-file-zero-") as directory:
+        root = Path(directory)
+        incoming, native, exported, foreign, foreign_export = (root/name for name in ("incoming", "native", "exported", "foreign", "foreign-export"))
+        incoming.mkdir()
+        foreign.mkdir()
+        for name, table in cases.items():
+            with ipc.new_file(str(incoming/(name+".arrow")), table.schema) as writer:
+                writer.write_table(table)
+        subprocess.run([str(args.writer), "--nested-from-arrow", str(incoming), str(native)], check=True)
+        subprocess.run([str(args.reader), str(native), "--arrow-output", str(exported)], check=True)
+        for name, table in cases.items():
+            actual = read_stream(exported/(name+".parquet.arrows"))
+            assert actual.to_pydict() == table.to_pydict(), (name, actual.to_pydict(), table.to_pydict())
+            assert file_infos(actual.schema) == file_infos(table.schema), name
+            path = native/(name+".parquet")
+            _, parsed = footer(path)
+            assert parsed.value[3].value == table.num_rows
+            for group in parsed.value[4].value:
+                assert group.value[3].value == table.num_rows
+            try:
+                physical = physical_copy(path, root/(name+"-physical.parquet"))
+            except (OSError, pa.ArrowException) as error:
+                reference_limitations[name] = str(error)
+            else:
+                if physical.to_pydict() == table.to_pydict():
+                    physical_compared.append(name)
+                else:
+                    reference_limitations[name] = {"expected": table.to_pydict(), "physicalPyArrow": physical.to_pydict()}
+        # These baseline cases independently pin the no-data, null-value and
+        # anchored-row interpretation, regardless of container limitations.
+        assert {"root-nulls", "root-empty-optional", "root-empty-required", "root-with-anchor"} <= set(physical_compared), reference_limitations
+        boundary_expected = {
+            "optional-parent-first": {"f": [None, {"anchor": 10}, {"anchor": 20}]},
+            "optional-parent-last": {"f": [None, {"anchor": 10}, {"anchor": 20}]},
+            "list-anchored": {"f": [None, [], [{"anchor": value} for value in range(5)]]},
+        }
+        for name, expected in boundary_expected.items():
+            actual = project_physical_fields(native/(name+".parquet"), root/(name+"-projected.parquet"))
+            assert actual.to_pydict() == expected, (name, actual.to_pydict(), expected)
+            boundary_compared.append(name)
+        # Independently frame a positive-row FILE with no physical columns.
+        for repetition in (0, 1):
+            schema = Node(T.LIST, [element("schema", children=1), element("f", repetition=repetition, children=0, file=True)], T.STRUCT)
+            group = node(T.STRUCT, {1: Node(T.LIST, [], T.STRUCT), 2: node(T.I64, 0), 3: node(T.I64, 3)})
+            parsed = node(T.STRUCT, {1: node(T.I32, 1), 2: schema, 3: node(T.I64, 3), 4: Node(T.LIST, [group], T.STRUCT)})
+            write_footer(foreign/(f"foreign-{repetition}.parquet"), b"PAR1", parsed)
+        subprocess.run([str(args.reader), str(foreign), "--arrow-output", str(foreign_export)], check=True)
+        for path in foreign.glob("*.parquet"):
+            actual = read_stream(foreign_export/(path.name+".arrows"))
+            assert actual.to_pydict() == {"f": [None]*3}
+            assert file_infos(actual.schema)
+        # Keep the independent Rust failure explicit: treating a dropped field
+        # as successful FILE interoperability would hide the very regression.
+        rust_input = root/"rust-input"
+        rust_input.mkdir()
+        (rust_input/"nulls.arrow").write_bytes((incoming/"root-nulls.arrow").read_bytes())
+        result = subprocess.run([str(args.reference), "from-arrow", str(rust_input), str(root/"rust")], capture_output=True, text=True)
+        assert result.returncode != 0 and "does not support writing empty structs" in result.stderr
+    report = {"status": "passed", "nativeRoundtrips": len(cases), "independentForeignFiles": 2,
+              "physicalPyArrowComparisons": physical_compared, "physicalReferenceLimitations": reference_limitations,
+              "independentParentListBoundaryComparisons": boundary_compared,
+              "rustWriting": "rejects empty structs; not a zero-leaf FILE oracle",
+              "sourceOracles": "Apache Thrift FILE group0/row counts; PyArrow physical empty groups; published FILE invalid-reference null policy"}
+    if args.output:
+        args.output.write_text(json.dumps(report, indent=2)+"\n")
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_geoarrow_interop.py b/scripts/parquet_geoarrow_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_geoarrow_interop.py
@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Check Parquet geospatial/GeoArrow metadata and WKB values independently."""
+import argparse
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from parquet_lzo_interop import Node, decode, encode
+
+
+@dataclass
+class Case:
+    name: str
+    crs: object
+    edges: str | None = None
+    hint: str | None = None
+    large: bool = False
+
+
+def arrow_metadata(field):
+    metadata = field.metadata or {}
+    assert metadata[b"ARROW:extension:name"] == b"geoarrow.wkb", field
+    return json.loads(metadata[b"ARROW:extension:metadata"])
+
+
+def logical(path):
+    data = path.read_bytes()
+    count = struct.unpack("<I", data[-8:-4])[0]
+    parsed = decode(data[-8-count:-8])
+    assert parsed.consumed == count
+    return parsed.node.value[2].value[1].value[10].value
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--writer", type=Path, required=True)
+    parser.add_argument("--reader", type=Path, required=True)
+    args = parser.parse_args()
+    projjson = {"type":"GeographicCRS","name":"WGS 84","datum":{"type":"GeodeticReferenceFrame","name":"World Geodetic System 1984","ellipsoid":{"name":"WGS 84","semi_major_axis":6378137,"inverse_flattening":298.257223563}},"coordinate_system":{"subtype":"ellipsoidal","axis":[{"name":"Longitude","abbreviation":"lon","direction":"east","unit":"degree"},{"name":"Latitude","abbreviation":"lat","direction":"north","unit":"degree"}]}}
+    cases = [Case("planar","EPSG:3857"),Case("authority","OGC:CRS84",hint="authority_code"),Case("projjson",projjson,hint="projjson"),Case("srid","42",hint="srid"),Case("large","EPSG:3857",large=True)]
+    for edges in ("spherical","vincenty","thomas","andoyer","karney"):
+        cases.append(Case("geography-"+edges,"EPSG:4326",edges))
+    points = [struct.pack("<BIdd",1,1,1.5,2.5),None,struct.pack("<BIdd",1,1,-10.5,20.5)]
+    with tempfile.TemporaryDirectory(prefix="parquet-geoarrow-") as directory:
+        root = Path(directory)
+        incoming, files, native, out = (root/name for name in ("incoming","files","native","out"))
+        incoming.mkdir()
+        for case in cases:
+            metadata = {"crs":case.crs}
+            if case.edges is not None: metadata["edges"] = case.edges
+            if case.hint is not None: metadata["crs_type"] = case.hint
+            storage = pa.large_binary() if case.large else pa.binary()
+            field = pa.field("g",storage,metadata={b"ARROW:extension:name":b"geoarrow.wkb",b"ARROW:extension:metadata":json.dumps(metadata).encode()})
+            table = pa.Table.from_arrays([pa.array(points,storage)],schema=pa.schema([field]))
+            with ipc.new_file(str(incoming/(case.name+".arrow")),table.schema) as writer:writer.write_table(table)
+        subprocess.run([str(args.writer),"--from-arrow",str(incoming),str(files)],check=True)
+        assert len(list(files.glob("*.parquet"))) == len(cases)
+        for case in cases:
+            path = files/(case.name+".parquet")
+            annotation = logical(path)
+            tag = 18 if case.edges is not None else 17
+            assert set(annotation) == {tag}, (case.name,annotation)
+            parameters = annotation[tag].value
+            raw_crs = parameters[1].value.decode()
+            if isinstance(case.crs,dict):assert json.loads(raw_crs)==case.crs
+            else:assert raw_crs == ("srid:"+case.crs if case.hint=="srid" else case.crs)
+            if case.edges is None:assert 2 not in parameters
+            else:assert parameters[2].value == ("spherical","vincenty","thomas","andoyer","karney").index(case.edges)
+            assert pq.read_table(path,arrow_extensions_enabled=False).column("g").to_pylist() == points
+        subprocess.run([str(args.writer),"--logical-metadata",str(native)],check=True)
+        reference = native/"geometry-custom.parquet"
+        data = reference.read_bytes();count = struct.unpack("<I",data[-8:-4])[0];footer = decode(data[-8-count:-8]).node
+        footer.value[2].value[1].value[10].value[17].value[1] = Node(TType.STRING,b"projjson:crs-definition")
+        footer.value[5] = Node(TType.LIST,[Node(TType.STRUCT,{1:Node(TType.STRING,b"crs-definition"),2:Node(TType.STRING,json.dumps(projjson).encode())})],element_kind=TType.STRUCT)
+        raw = encode(footer);(native/"geometry-reference.parquet").write_bytes(data[:-8-count]+raw+struct.pack("<I",len(raw))+b"PAR1")
+        subprocess.run([str(args.reader),str(native),"--arrow-output",str(out)],check=True)
+        for source in native.glob("*.parquet"):
+            with pa.memory_map(str(out/(source.name+".arrows")),"r") as data:
+                table = ipc.open_stream(data).read_all()
+            metadata = arrow_metadata(table.schema.field(0));name = source.stem
+            if name=="geometry-reference":assert metadata["crs"]==projjson
+            elif name=="geometry-custom":assert metadata["crs"]=="EPSG:3857"
+            elif name.endswith("default"):assert metadata["crs"]=="OGC:CRS84"
+            else:assert metadata["crs"]=="EPSG:4326"
+            if name.startswith("geometry-"):assert "edges" not in metadata
+            else:assert metadata["edges"] == ("spherical" if name=="geography-default" else name.removeprefix("geography-"))
+            assert table.column(0).to_pylist()==[points[0]]
+        bad, rejected = root/"bad",root/"rejected";bad.mkdir()
+        field = pa.field("g",pa.binary(),metadata={b"ARROW:extension:name":b"geoarrow.wkb",b"ARROW:extension:metadata":b"{}"})
+        table = pa.Table.from_arrays([pa.array(points,pa.binary())],schema=pa.schema([field]))
+        with ipc.new_file(str(bad/"unknown-crs.arrow"),table.schema) as writer:writer.write_table(table)
+        result = subprocess.run([str(args.writer),"--from-arrow",str(bad),str(rejected)],capture_output=True,text=True)
+        assert result.returncode!=0 and "unknown GeoArrow CRS" in result.stderr
+        assert not list(rejected.glob("*.parquet"))
+    print(f"PASS: {len(cases)} independent Arrow inputs,9 native/reference Parquet inputs,all5 edges,PROJJSON/SRID/default CRS,large binary,nulls,WKB andunknown-CRS rejection")
+
+
+if __name__=="__main__":main()
diff --git a/scripts/parquet_interop.py b/scripts/parquet_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_interop.py
@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""Cross-engine Parquet interop driver.
+
+Workflow per file:
+
+  1. Read with pyarrow -> assert against expected.
+  2. Read with duckdb  -> assert against expected.
+  3. Read with polars  -> assert against expected.
+
+Each file is associated with a Python expectations dict that
+the engine-specific reader is checked against. A file is OK
+only if every engine accepts it AND every engine returns the
+same data we wrote.
+
+Run:
+    python3 wireform-parquet/scripts/parquet_interop.py [--regen]
+
+`--regen` additionally writes pyarrow / duckdb / polars
+reference files /into/ a temp dir and tries to read them
+with wireform-parquet (round-trip-the-other-way coverage).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+import duckdb
+import polars as pl
+from parquet_statistics_interop import read_value, TCompactProtocol, TMemoryBuffer, TType
+
+ROOT = Path(__file__).resolve().parent.parent
+
+# --- Each entry: (filename, expected pa.Table)
+import datetime as _dt
+
+def temporal_expected(nullable: bool) -> pa.Table:
+    def values(items):
+        return [item if not nullable or i != 1 else None for i, item in enumerate(items)]
+    return pa.table({
+        "date": pa.array(values([-1, 0, 1]), pa.date32()),
+        "time": pa.array(values([0, 1000, 86399000]), pa.time32("ms")),
+        "stamp": pa.array(values([-1000, 0, 1700000000000]), pa.timestamp("ms")),
+    })
+
+def expected_files() -> list[tuple[str, pa.Table]]:
+    return [
+        ( "int32_required.parquet"
+        , pa.table({"x": pa.array([1, 2, 3, 4, 5], pa.int32())}) )
+      , ( "int64_required.parquet"
+        , pa.table({"x": pa.array([10, 20, 30, 40, 50], pa.int64())}) )
+      , ( "float_required.parquet"
+        , pa.table({"x": pa.array([1.5, 2.5, 3.5], pa.float32())}) )
+      , ( "double_required.parquet"
+        , pa.table({"x": pa.array([1.5, -2.5, 3.14159], pa.float64())}) )
+      , ( "bool_required.parquet"
+        , pa.table({"x": pa.array([True, False, True, True, False], pa.bool_())}) )
+      , ( "byte_array_required.parquet"
+        , pa.table({"x": pa.array([b"alpha", b"beta", b"gamma"], pa.binary())}) )
+      , ( "utf8_required.parquet"
+        , pa.table({"name": pa.array(["Alice", "Bob", "Carol", "Δοε"], pa.string())}) )
+
+      # Logical-type-annotated primitives
+      , ( "date32_required.parquet"
+        , pa.table({"d": pa.array(
+            [ _dt.date(1970, 1, 1)
+            , _dt.date(1970, 1, 1) + _dt.timedelta(days=18000)
+            , _dt.date(1970, 1, 1) + _dt.timedelta(days=19000)
+            ], pa.date32())}) )
+      , ( "time_millis_required.parquet"
+        , pa.table({"t": pa.array(
+            [ _dt.time(0, 0, 0)
+            , _dt.time(0, 0, 12, 345_000)
+            , _dt.time(23, 59, 59, 999_000)
+            ], pa.time32("ms"))}) )
+      , ( "timestamp_millis_required.parquet"
+          # pyarrow attaches UTC tz when the Parquet
+          # ConvertedType.TIMESTAMP_MILLIS surfaces (matches
+          # the spec's isAdjustedToUTC=true default for the
+          # legacy converted type). duckdb / polars read it as
+          # a tz-naive instant. We pin the pyarrow behaviour
+          # in the expectation; the per-engine asserter is
+          # tolerant of duckdb / polars's tz-naive value.
+        , pa.table({"ts": pa.array(
+            [ _dt.datetime(1970, 1, 1, 0, 0, 0, tzinfo=_dt.timezone.utc)
+            , _dt.datetime(2023, 11, 14, 22, 13, 20, tzinfo=_dt.timezone.utc)
+            ], pa.timestamp("ms", tz="UTC"))}) )
+      , ( "uint32_required.parquet"
+        , pa.table({"u": pa.array([0, 1, 2_147_483_647, 4_294_967_295],
+                                  pa.uint32())}) )
+      , ( "json_required.parquet"
+          # pyarrow surfaces JSON as plain string column (the
+          # JSON LogicalType doesn't widen the physical type).
+        , pa.table({"doc": pa.array(['{"k":1}', '{"k":2,"j":"hi"}'],
+                                    pa.string())}) )
+
+      , ( "int64_zstd.parquet"
+        , pa.table({"x": pa.array([10, 20, 30, 40, 50], pa.int64())}) )
+      , ( "int64_snappy.parquet"
+        , pa.table({"x": pa.array([10, 20, 30, 40, 50], pa.int64())}) )
+      , ( "int64_gzip.parquet"
+        , pa.table({"x": pa.array([10, 20, 30, 40, 50], pa.int64())}) )
+      , ( "int64_lz4_raw.parquet"
+        , pa.table({"x": pa.array([10, 20, 30, 40, 50], pa.int64())}) )
+
+      , ( "int64_two_row_groups.parquet"
+        , pa.table({"x": pa.array([1, 2, 3, 4, 5, 6], pa.int64())}) )
+      , ( "mixed_optional.parquet"
+        , pa.table({
+            "id":    pa.array([10, 20, 30], pa.int64()),
+            "name":  pa.array(["alice", None, "carol"], pa.string()),
+            "score": pa.array([1.5, 2.5, None], pa.float64()),
+          }) )
+
+      # All-nullable single-column variants exercising
+      # definition-level streams for each physical type.
+      , ( "optional_int32.parquet"
+        , pa.table({"x": pa.array([1, None, 3, -1], pa.int32())}) )
+      , ( "optional_int64.parquet"
+        , pa.table({"x": pa.array([100, None, 300], pa.int64())}) )
+      , ( "optional_float.parquet"
+        , pa.table({"x": pa.array([1.5, 2.5, None, 4.5], pa.float32())}) )
+      , ( "optional_bool.parquet"
+        , pa.table({"x": pa.array([True, None, False, True, None], pa.bool_())}) )
+      , ("arrow_temporal_required_v1.parquet", temporal_expected(False))
+      , ("arrow_temporal_required_v2.parquet", temporal_expected(False))
+      , ("arrow_temporal_optional_v1.parquet", temporal_expected(True))
+      , ("arrow_temporal_optional_v2.parquet", temporal_expected(True))
+    ]
+
+def _normalise_value(v):
+    """Per-engine quirk normaliser:
+
+    * pyarrow returns tz-aware datetime for TIMESTAMP_MILLIS;
+      duckdb / polars return tz-naive. We compare against the
+      tz-aware expectation by stripping tzinfo on both sides.
+    * polars returns JSON columns as bytes; pyarrow as str.
+      Decode bytes -> utf-8 so they compare equal.
+    """
+    if isinstance(v, bytes):
+        try:
+            return v.decode("utf-8")
+        except UnicodeDecodeError:
+            return v
+    if hasattr(v, "tzinfo") and v.tzinfo is not None:
+        return v.replace(tzinfo=None)
+    return v
+
+def _normalise_list(xs):
+    return [_normalise_value(x) for x in xs]
+
+def assert_table_eq(name: str, actual: pa.Table, expected: pa.Table) -> str | None:
+    if actual.num_rows != expected.num_rows:
+        return f"row count {actual.num_rows} != {expected.num_rows}"
+    if actual.num_columns != expected.num_columns:
+        return f"column count {actual.num_columns} != {expected.num_columns}"
+    for col_name in expected.column_names:
+        if col_name not in actual.column_names:
+            return f"missing column {col_name!r}"
+        a = _normalise_list(actual.column(col_name).combine_chunks().to_pylist())
+        e = _normalise_list(expected.column(col_name).combine_chunks().to_pylist())
+        if a != e:
+            return f"column {col_name!r}: got {a} != expected {e}"
+    return None
+
+def read_pyarrow(path: Path) -> pa.Table:
+    return pq.read_table(path)
+
+def read_duckdb(path: Path) -> pa.Table:
+    con = duckdb.connect()
+    result = con.execute(f"SELECT * FROM read_parquet('{path}')")
+    rbr = result.to_arrow_table() if hasattr(result, "to_arrow_table") else result.arrow()
+    if isinstance(rbr, pa.Table):
+        return rbr
+    # duckdb 1.5+ returns a RecordBatchReader from .arrow() in
+    # some configurations; coalesce it.
+    return rbr.read_all() if hasattr(rbr, "read_all") else pa.Table.from_batches(list(rbr))
+
+def read_polars(path: Path) -> pa.Table:
+    df = pl.read_parquet(path)
+    return df.to_arrow()
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--regen", action="store_true",
+        help="also generate engine-emitted Parquet files for reverse round-trip")
+    args = parser.parse_args()
+
+    out = Path(tempfile.mkdtemp(prefix="wireform-parquet-probe-"))
+    print(f"== writing wireform-parquet probe outputs to {out}")
+    probe = os.environ.get("WIREFORM_PARQUET_FORWARD_PROBE")
+    command = [probe] if probe else ["cabal", "run", "wireform-parquet:wireform-parquet-interop-probe", "--"]
+    subprocess.run(
+        [*command, str(out)],
+        cwd=ROOT.parent, check=True
+    )
+
+    print("\n== reading wireform-parquet output with pyarrow / duckdb / polars")
+    failures = []
+    for fname, expected in expected_files():
+        path = out / fname
+        if not path.exists():
+            failures.append((fname, "probe didn't write"))
+            continue
+
+        # These probes write one data page per leaf/group. Check V2's literal
+        # num_rows field independently, especially when repeated events differ.
+        raw = path.read_bytes()
+        metadata = pq.ParquetFile(path).metadata
+        for group_number in range(metadata.num_row_groups):
+            group = metadata.row_group(group_number)
+            for column_number in range(group.num_columns):
+                offset = group.column(column_number).data_page_offset
+                header = read_value(TCompactProtocol(TMemoryBuffer(raw[offset:])), TType.STRUCT)
+                if header[1] == 3:
+                    assert header[8][3] == group.num_rows, (fname, 'V2 rows vs repeated events', header[8], group.num_rows)
+
+        for engine, reader in [("pyarrow", read_pyarrow),
+                               ("duckdb",  read_duckdb),
+                               ("polars",  read_polars)]:
+            try:
+                got = reader(path)
+                err = assert_table_eq(fname, got, expected)
+                if err:
+                    failures.append((f"{fname}::{engine}", err))
+                else:
+                    print(f"  OK   {fname:40s} via {engine}")
+            except Exception as e:
+                failures.append((f"{fname}::{engine}", repr(e)))
+
+    if args.regen:
+        print("\n== reverse round-trip: engines write, wireform reads")
+        # Currently the wireform-parquet reader is exercised by the
+        # main test suite + the Iceberg goldens; this script is the
+        # write-side audit. The reverse direction is tested by
+        # the iceberg golden corpus + parquet-test.
+
+    if failures:
+        print(f"\n{len(failures)} failures:")
+        for k, v in failures:
+            print(f"  FAIL {k}: {v}")
+        return 1
+    print("\nAll engines accepted every wireform-parquet probe output.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/parquet_large_map_interop.py b/scripts/parquet_large_map_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_large_map_interop.py
@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Read the official >2GiB map fixture through64-bit native Arrow offsets.
+
+The reference reads one row per batch. Hash buffer spans directly, never
+materializing gigabyte Python strings or a second full IPC copy on disk.
+Native and reference processes run sequentially to bound peak memory.
+"""
+import argparse
+import ast
+import hashlib
+import json
+from pathlib import Path
+import struct
+import subprocess
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+
+def reference(path):
+    digest = hashlib.sha256()
+    key_offsets = [0]
+    values = []
+    rows = 0
+    for batch in pq.ParquetFile(path).iter_batches(batch_size=1, use_threads=False):
+        batch.validate(full=True)
+        assert batch.num_rows == 1 and batch.num_columns == 1
+        mapping = batch.column(0)
+        assert pa.types.is_map(mapping.type) and mapping.null_count == 0
+        assert mapping.offsets.to_pylist() == [0, 1]
+        keys = mapping.keys
+        assert pa.types.is_string(keys.type) and keys.null_count == 0 and len(keys) == 1
+        start, end = struct.unpack_from('<ii', memoryview(keys.buffers()[1]), keys.offset * 4)
+        span = memoryview(keys.buffers()[2])[start:end]
+        digest.update(span)
+        key_offsets.append(key_offsets[-1] + len(span))
+        values.extend(mapping.items.to_pylist())
+        rows += 1
+    return {'rows': rows, 'map_nulls': 0, 'map_offsets': list(range(rows + 1)), 'key_nulls': 0, 'key_offsets': key_offsets, 'key_bytes': key_offsets[-1], 'key_sha256': digest.hexdigest(), 'value_nulls': 0, 'values': values}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--reader', type=Path, required=True)
+    parser.add_argument('--fixture', type=Path, required=True)
+    parser.add_argument('--output', type=Path, required=True)
+    parser.add_argument('--max-heap-mib', type=int, default=6144)
+    args = parser.parse_args()
+    assert args.fixture.stat().st_size < 10000
+    native = subprocess.run([str(args.reader), '--large-map-summary', str(args.fixture), '+RTS', f'-M{args.max_heap_mib}m', '-RTS'], capture_output=True, text=True, timeout=300)
+    assert native.returncode == 0, (native.returncode, native.stdout, native.stderr)
+    actual = {}
+    for line in native.stdout.splitlines():
+        key, value = line.split('=', 1)
+        actual[key] = value if key == 'key_sha256' else ast.literal_eval(value)
+    expected = reference(args.fixture)
+    assert actual == expected, (actual, expected)
+    assert actual['rows'] == 2 and actual['key_offsets'] == [0, 2**30, 2**31] and actual['values'] == [1, 1]
+    report = {'pyarrow': pa.__version__, 'fixture': args.fixture.name, 'nativeProjection': 'LargeUtf8 map keys, standard Map offsets', 'decodedKeyBytes': actual['key_bytes'], 'rows': actual['rows'], 'keySHA256': actual['key_sha256'], 'nativeAndReferenceAgree': True, 'failures': 0, 'skips': 0}
+    args.output.write_text(json.dumps(report, indent=2) + '\n')
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_large_offset_interop.py b/scripts/parquet_large_offset_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_large_offset_interop.py
@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Public LargeUtf8/LargeBinary projections against unmodified Arrow C++."""
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import tempfile
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+
+
+def widen(field):
+    typ = field.type
+    if pa.types.is_string(typ):
+        typ = pa.large_string()
+    elif pa.types.is_binary(typ):
+        typ = pa.large_binary()
+    elif pa.types.is_struct(typ):
+        typ = pa.struct(list(map(widen, typ)))
+    elif pa.types.is_list(typ):
+        typ = pa.large_list(widen(typ.value_field))
+    elif pa.types.is_map(typ):
+        typ = pa.map_(widen(typ.key_field), widen(typ.item_field), keys_sorted=typ.keys_sorted)
+    return pa.field(field.name, typ, nullable=field.nullable, metadata=field.metadata)
+
+
+def project(reader, source, schema, output):
+    request = output.with_suffix('.schema.arrows')
+    with ipc.new_stream(request, schema):
+        pass
+    return subprocess.run(list(map(str, [reader, '--project', source, request, output])), capture_output=True, text=True, timeout=60)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--reader', type=Path, required=True)
+    parser.add_argument('--output', type=Path, required=True)
+    parser.add_argument('--codecs', nargs='+', default=['NONE', 'gzip', 'snappy', 'zstd', 'lz4', 'brotli'])
+    args = parser.parse_args()
+    cases = 0
+    rejected = 0
+    with tempfile.TemporaryDirectory(prefix='large-offset-interop-') as directory:
+        root = Path(directory)
+        required_schema = pa.schema([pa.field('text', pa.string(), nullable=False), pa.field('bytes', pa.binary(), nullable=False)])
+        tables = {
+            'required': pa.Table.from_arrays([pa.array(['alpha', '', 'κόσμε'] * 9), pa.array([b'\x00\xff', b'', b'bytes'] * 9)], schema=required_schema),
+            'nullable': pa.table({'text': pa.array(['alpha', None, '', 'κόσμε'] * 9), 'bytes': pa.array([b'\x00\xff', None, b'', b'bytes'] * 9)}),
+            'nested': pa.table({'values': pa.array([None, [], [None, 'alpha', 'κόσμε'], ['']] * 9, pa.list_(pa.string())), 'record': pa.array([None, {'x': b'\xff', 'y': 'κόσμε'}, {'x': None, 'y': None}] * 12, pa.struct([('x', pa.binary()), ('y', pa.string())]))}),
+            'map': pa.table({'mapping': pa.array([None, [], [('alpha', [b'\x00\xff', None])], [('κόσμε', []), ('', None)]] * 9, pa.map_(pa.string(), pa.list_(pa.binary())))}),
+            'empty': pa.table({'text': pa.array([], pa.string()), 'mapping': pa.array([], pa.map_(pa.binary(), pa.string()))}),
+        }
+        for codec in args.codecs:
+            for version in ['1.0', '2.0']:
+                for dictionary in [False, True]:
+                    for name, table in tables.items():
+                        stem = f'{codec}-{version}-{dictionary}-{name}'
+                        source = root / (stem + '.parquet')
+                        output = root / (stem + '.arrows')
+                        pq.write_table(table, source, compression=codec, data_page_version=version, use_dictionary=dictionary, row_group_size=11, write_batch_size=3, max_rows_per_page=3, write_page_index=True, write_page_checksum=True)
+                        target = pa.schema(list(map(widen, table.schema)))
+                        result = project(args.reader, source, target, output)
+                        assert result.returncode == 0, (stem, result.stdout, result.stderr)
+                        with ipc.open_stream(output) as reader:
+                            actual = reader.read_all()
+                        actual.validate(full=True)
+                        expected = table.cast(target)
+                        assert actual.equals(expected, check_metadata=False), (stem, actual, expected)
+                        cases += 1
+        # Offset widening never changes UTF-8 into opaque bytes, or vice versa.
+        for source_type, target_type, values in [(pa.string(), pa.large_binary(), ['alpha']), (pa.binary(), pa.large_string(), [b'alpha'])]:
+            source = root / f'invalid-{rejected}.parquet'
+            pq.write_table(pa.table({'v': pa.array(values, source_type)}), source, compression='NONE')
+            result = project(args.reader, source, pa.schema([('v', target_type)]), root / f'invalid-{rejected}.arrows')
+            assert result.returncode > 0 and 'IncompatibleType' in result.stdout, result
+            rejected += 1
+        report = {'pyarrow': pa.__version__, 'cases': cases, 'incompatibleRejected': rejected, 'failures': 0, 'skips': 0}
+        args.output.write_text(json.dumps(report, indent=2) + '\n')
+        print(json.dumps(report, indent=2))
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_logical_metadata_interop.py b/scripts/parquet_logical_metadata_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_logical_metadata_interop.py
@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Check geospatial metadata with Apache Thrift and PyArrow independently.
+
+The writer must preserve CRS/interpolation fields, including their absence,
+while retaining valid WKB pages and omitting unordered min/max statistics.
+"""
+
+import argparse
+import struct
+import subprocess
+import tempfile
+from pathlib import Path
+
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from thrift.protocol.TCompactProtocol import TCompactProtocol
+from thrift.transport.TTransport import TMemoryBuffer
+
+from parquet_statistics_interop import read_value
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--probe", type=Path, required=True)
+    args = parser.parse_args()
+    cases = {
+        "geometry-default": (17, {}),
+        "geometry-custom": (17, {1: b"EPSG:3857"}),
+        "geography-default": (18, {}),
+    }
+    for code, name in enumerate(("spherical", "vincenty", "thomas", "andoyer", "karney")):
+        cases["geography-" + name] = (18, {1: b"EPSG:4326", 2: code})
+    point = struct.pack("<BIdd", 1, 1, 1.5, 2.5)
+    with tempfile.TemporaryDirectory(prefix="parquet-logical-metadata-") as directory:
+        root = Path(directory)
+        subprocess.run([str(args.probe.resolve()), "--logical-metadata", str(root)], check=True)
+        assert {p.stem for p in root.glob("*.parquet")} == set(cases)
+        for name, (tag, parameters) in cases.items():
+            path = root / (name + ".parquet")
+            data = path.read_bytes()
+            assert data[:4] == data[-4:] == b"PAR1"
+            length = struct.unpack("<I", data[-8:-4])[0]
+            protocol = TCompactProtocol(TMemoryBuffer(data[-8 - length:-8]))
+            footer = read_value(protocol, TType.STRUCT)
+            assert footer[2][1][10] == {tag: parameters}, (name, footer[2][1])
+            statistics = footer[4][0][1][0][3].get(12, {})
+            assert not {1, 2, 5, 6}.intersection(statistics), (name, statistics)
+            metadata = pq.read_metadata(path)
+            kind = "GEOMETRY" if tag == 17 else "GEOGRAPHY"
+            assert kind in str(metadata.schema.column(0).logical_type).upper()
+            assert pq.read_table(path, arrow_extensions_enabled=False).to_pylist() == [{"geometry": point}]
+    print(f"PASS: {len(cases)} geospatial metadata cases (Apache Thrift + PyArrow)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_lzo_interop.py b/scripts/parquet_lzo_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_lzo_interop.py
@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""Independent raw-LZO Parquet interop using Apache Thrift, liblzo2 and PyArrow.
+
+The codec is unavailable in ordinary PyArrow builds. Transcode only page
+compression with the independent reference library, preserving logical data,
+levels, encodings and statistics. PyArrow then supplies the value oracle.
+"""
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+import zlib
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from thrift.protocol.TCompactProtocol import TCompactProtocol
+from thrift.transport.TTransport import TMemoryBuffer
+
+
+@dataclass
+class Node:
+    kind: int
+    value: object
+    element_kind: int = 0
+    key_kind: int = 0
+    value_kind: int = 0
+
+
+@dataclass
+class Entry:
+    key: Node
+    value: Node
+
+
+@dataclass
+class Decoded:
+    node: Node
+    consumed: int
+
+
+def read_node(protocol, kind):
+    if kind == TType.STRUCT:
+        protocol.readStructBegin()
+        fields = {}
+        while True:
+            _, field_kind, field_id = protocol.readFieldBegin()
+            if field_kind == TType.STOP:
+                break
+            assert field_id not in fields, "duplicate metadata field"
+            fields[field_id] = read_node(protocol, field_kind)
+            protocol.readFieldEnd()
+        protocol.readStructEnd()
+        return Node(kind, fields)
+    if kind in (TType.LIST, TType.SET):
+        element, count = (protocol.readListBegin() if kind == TType.LIST else protocol.readSetBegin())
+        items = []
+        for _ in range(count):
+            items.append(read_node(protocol, element))
+        (protocol.readListEnd if kind == TType.LIST else protocol.readSetEnd)()
+        return Node(kind, items, element_kind=element)
+    if kind == TType.MAP:
+        key, value, count = protocol.readMapBegin()
+        entries = []
+        for _ in range(count):
+            entries.append(Entry(read_node(protocol, key), read_node(protocol, value)))
+        protocol.readMapEnd()
+        return Node(kind, entries, key_kind=key, value_kind=value)
+    readers = {TType.BOOL: protocol.readBool, TType.BYTE: protocol.readByte,
+               TType.I16: protocol.readI16, TType.I32: protocol.readI32,
+               TType.I64: protocol.readI64, TType.DOUBLE: protocol.readDouble,
+               TType.STRING: protocol.readBinary}
+    return Node(kind, readers[kind]())
+
+
+def write_node(protocol, node):
+    if node.kind == TType.STRUCT:
+        protocol.writeStructBegin("metadata")
+        for field_id, value in node.value.items():
+            protocol.writeFieldBegin("field", value.kind, field_id)
+            write_node(protocol, value)
+            protocol.writeFieldEnd()
+        protocol.writeFieldStop()
+        protocol.writeStructEnd()
+    elif node.kind in (TType.LIST, TType.SET):
+        (protocol.writeListBegin if node.kind == TType.LIST else protocol.writeSetBegin)(node.element_kind, len(node.value))
+        for item in node.value:
+            write_node(protocol, item)
+        (protocol.writeListEnd if node.kind == TType.LIST else protocol.writeSetEnd)()
+    elif node.kind == TType.MAP:
+        protocol.writeMapBegin(node.key_kind, node.value_kind, len(node.value))
+        for item in node.value:
+            write_node(protocol, item.key)
+            write_node(protocol, item.value)
+        protocol.writeMapEnd()
+    else:
+        writers = {TType.BOOL: protocol.writeBool, TType.BYTE: protocol.writeByte,
+                   TType.I16: protocol.writeI16, TType.I32: protocol.writeI32,
+                   TType.I64: protocol.writeI64, TType.DOUBLE: protocol.writeDouble,
+                   TType.STRING: protocol.writeBinary}
+        writers[node.kind](node.value)
+
+
+def decode(data):
+    transport = TMemoryBuffer(data)
+    node = read_node(TCompactProtocol(transport), TType.STRUCT)
+    return Decoded(node, transport.cstringio_buf.tell())
+
+
+def encode(node):
+    transport = TMemoryBuffer()
+    write_node(TCompactProtocol(transport), node)
+    return transport.getvalue()
+
+
+def signed_crc(body):
+    value = zlib.crc32(body)
+    return value if value < 2**31 else value - 2**32
+
+
+def transcode(source, target, codec, oracle, scratch, v2_uncompressed=False,
+              require_source_codec=None, expected_version=None):
+    data = source.read_bytes()
+    assert data[:4] == data[-4:] == b"PAR1"
+    length = struct.unpack("<I", data[-8:-4])[0]
+    parsed = decode(data[-8-length:-8])
+    footer = parsed.node
+    assert parsed.consumed == length
+    result = bytearray(b"PAR1")
+    calls = 0
+
+    codec_names = {1: "snappy", 2: "gzip", 4: "brotli", 6: "zstd", 7: "lz4_raw"}
+
+    def convert(body, old_codec, expected, output_codec=codec):
+        nonlocal calls
+        if old_codec == 0 or (expected == 0 and not body):
+            raw = body
+        elif old_codec == 3:
+            src, dst = scratch / "compressed", scratch / "plain"
+            src.write_bytes(body)
+            subprocess.run([str(oracle), "--reference-decompress", str(expected), str(src), str(dst)], check=True)
+            raw = dst.read_bytes()
+            calls += 1
+        else:
+            raw = bytes(pa.Codec(codec_names[old_codec]).decompress(body, expected))
+        assert len(raw) == expected
+        if output_codec == 0:
+            return raw
+        if output_codec != 3:
+            return bytes(pa.Codec(codec_names[output_codec]).compress(raw))
+        src, dst = scratch / "plain", scratch / "compressed"
+        src.write_bytes(raw)
+        subprocess.run([str(oracle), "--reference-compress", str(src), str(dst)], check=True)
+        calls += 1
+        return dst.read_bytes()
+
+    for group in footer.value[4].value:
+        group_start = len(result)
+        total_raw, total_packed = 0, 0
+        for chunk in group.value[1].value:
+            assert not {1, 4, 5, 6, 7}.intersection(chunk.value), "external chunks/indexes excluded from fixture"
+            column = chunk.value[3].value
+            old_codec = column[4].value
+            assert old_codec in (0, 1, 2, 3, 4, 6, 7)
+            if require_source_codec is not None and column[5].value > 0:
+                assert old_codec == require_source_codec, (source, old_codec)
+            offsets = [column[9].value]
+            if 11 in column:
+                offsets.append(column[11].value)
+            # PyArrow's empty dictionary column has a real dictionary page
+            # and a zero data-page offset because no data page was written.
+            assert all(offset >= 4 or (offset == 0 and column[5].value == 0)
+                       for offset in offsets), (source, offsets)
+            start = min((offset for offset in offsets if offset >= 4), default=0)
+            assert start != 0 or column[7].value == 0, (source, column)
+            stop = start + column[7].value
+            cursor = start
+            new_start = len(result)
+            raw_size = 0
+            first_data, first_dictionary = None, None
+            while cursor < stop:
+                parsed = decode(data[cursor:stop])
+                header, header_size = parsed.node, parsed.consumed
+                fields = header.value
+                assert {1, 2, 3}.issubset(fields), (source.name, start, stop, cursor, fields)
+                kind, expected, size = fields[1].value, fields[2].value, fields[3].value
+                if kind in (0, 3) and expected_version is not None:
+                    values = fields[5 if kind == 0 else 8].value[1].value
+                    if values > 0:
+                        assert kind == (0 if expected_version == 1 else 3), (source, kind)
+                body = data[cursor+header_size:cursor+header_size+size]
+                assert len(body) == size
+                if 4 in fields:
+                    assert fields[4].value == signed_crc(body)
+                if kind == 3:
+                    page = fields[8].value
+                    level_bytes = page[5].value + page[6].value
+                    assert 0 <= level_bytes <= len(body)
+                    values = body[level_bytes:]
+                    previous = old_codec if page.get(7, Node(TType.BOOL, True)).value else 0
+                    if codec != 0 and v2_uncompressed:
+                        converted = convert(values, previous, expected-level_bytes, 0)
+                        page[7] = Node(TType.BOOL, False)
+                    else:
+                        converted = convert(values, previous, expected-level_bytes)
+                        page[7] = Node(TType.BOOL, codec != 0)
+                    new_body = body[:level_bytes] + converted
+                else:
+                    assert kind in (0, 2), (source, kind)
+                    new_body = convert(body, old_codec, expected)
+                position = len(result)
+                if kind == 2:
+                    assert first_dictionary is None
+                    first_dictionary = position
+                elif first_data is None:
+                    first_data = position
+                fields[3] = Node(TType.I32, len(new_body))
+                if 4 in fields:
+                    fields[4] = Node(TType.I32, signed_crc(new_body))
+                serialized = encode(header)
+                result.extend(serialized)
+                result.extend(new_body)
+                raw_size += len(serialized) + expected
+                cursor += header_size + size
+            assert cursor == stop
+            column[4] = Node(TType.I32, codec)
+            column[6] = Node(TType.I64, raw_size)
+            column[7] = Node(TType.I64, len(result)-new_start)
+            column[9] = Node(TType.I64, first_data if first_data is not None else 0)
+            if first_dictionary is not None:
+                column[11] = Node(TType.I64, first_dictionary)
+            else:
+                column.pop(11, None)
+            assert 10 not in column and 14 not in column, "index pages/bloom filters excluded from fixture"
+            chunk.value[2] = Node(TType.I64, new_start)
+            total_raw += raw_size
+            total_packed += len(result)-new_start
+        group.value[2] = Node(TType.I64, total_raw)
+        if 5 in group.value:
+            group.value[5] = Node(TType.I64, group_start)
+        group.value[6] = Node(TType.I64, total_packed)
+    serialized = encode(footer)
+    result.extend(serialized)
+    result.extend(struct.pack("<I", len(serialized)))
+    result.extend(b"PAR1")
+    target.write_bytes(result)
+    return calls
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--writer", required=True, type=Path)
+    parser.add_argument("--reader", required=True, type=Path)
+    parser.add_argument("--oracle", required=True, type=Path)
+    args = parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix="parquet-lzo-interop-") as directory:
+        root = Path(directory)
+        controls, incoming, outgoing, decoded, arrow, scratch = (root / name for name in ("controls", "incoming", "outgoing", "decoded", "arrow", "scratch"))
+        for path in (controls, incoming, outgoing, decoded, arrow, scratch):
+            path.mkdir()
+        tables = {
+            "scalars": pa.table({"i32": pa.array([-2**31,None,0,2**31-1,-1]*6,pa.int32()),
+                                 "flag": pa.array([True,None,False,False,True]*6),
+                                 "bytes": pa.array([b"a",None,b"",b"\x00\xff",b"abc"*30]*6,pa.binary())}),
+            "nested": pa.table({"items": pa.array([None,[],[None,1,2],[3]]*6,pa.list_(pa.int32())),
+                                "obj": pa.array([None,{"x":1,"s":"a"},{"x":None,"s":None},{"x":-3,"s":""}]*6,pa.struct([("x",pa.int64()),("s",pa.string())]))}),
+            "allnull": pa.table({"x": pa.array([None]*16,pa.int32())}),
+            "empty": pa.table({"x": pa.array([],pa.int32())}),
+        }
+        expected, calls = {}, 0
+        for family, table in tables.items():
+            for version in ("1.0", "2.0"):
+                for dictionary in (False, True):
+                    name = f"{family}-v{version}-dict{int(dictionary)}"
+                    plain = controls / (name + ".parquet")
+                    pq.write_table(table, plain, compression="NONE", data_page_version=version,
+                                   use_dictionary=dictionary, row_group_size=11, max_rows_per_page=5,
+                                   write_batch_size=5, write_page_index=False, write_page_checksum=True)
+                    # First independently check metadata/header rewriting without codec work.
+                    copy = decoded / (name + ".parquet")
+                    transcode(plain, copy, 0, args.oracle, scratch, require_source_codec=0,
+                              expected_version=1 if version == "1.0" else 2)
+                    assert pq.read_table(copy).to_pylist() == table.to_pylist(), name
+                    packed = incoming / (name + ".parquet")
+                    calls += transcode(plain, packed, 3, args.oracle, scratch, require_source_codec=0)
+                    expected[packed.stem] = table.to_pylist()
+                    if version == "2.0":
+                        variant = incoming / (name + "-raw-values.parquet")
+                        calls += transcode(plain, variant, 3, args.oracle, scratch, v2_uncompressed=True)
+                        expected[variant.stem] = table.to_pylist()
+        subprocess.run([str(args.reader), str(incoming), "--arrow-output", str(arrow), "+RTS", "-M128m", "-RTS"], check=True)
+        for name, rows in expected.items():
+            with pa.memory_map(str(arrow / (name + ".parquet.arrows")), "r") as source:
+                table = ipc.open_stream(source).read_all()
+            assert table.to_pylist() == rows, name
+        subprocess.run([str(args.writer), "--lzo", str(outgoing)], check=True)
+        assert len(list(outgoing.glob("*.parquet"))) == 8
+        for source in outgoing.glob("*.parquet"):
+            target = decoded / ("native-" + source.name)
+            calls += transcode(source, target, 0, args.oracle, scratch, require_source_codec=3,
+                               expected_version=1 if source.stem.startswith("v1") else 2)
+            table = pq.read_table(target)
+            nullable = "nullable" in source.stem
+            if "empty" in source.stem:
+                rows = []
+            elif "all-null" in source.stem:
+                rows = [{"i32":None,"flag":None,"bytes":None}]*200
+            else:
+                integers = [-2**31,None,0,2**31-1,None] if nullable else [-2**31,-1,0,1,2**31-1]
+                flags = [True,None,False,True,None] if nullable else [True,False,False,True,True]
+                binary = [b"alpha",None,b"",b"\xff",None] if nullable else [b"alpha",b"",b"\x00",b"\xff",b"a"*128]
+                rows = []
+                for i in range(200):
+                    rows.append({"i32":integers[i%5],"flag":flags[i%5],"bytes":binary[i%5]})
+            assert table.to_pylist() == rows, source.name
+        print(f"PASS: {len(expected)} independent LZO input files,8 native output files,{calls} liblzo2 page operations; V1/V2,dictionaries,nesting,null/empty,CRC andrawV2values")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_metadata_interop.py b/scripts/parquet_metadata_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_metadata_interop.py
@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Check file metadata with independent Apache Thrift and PyArrow codecs."""
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from parquet_lzo_interop import Node, decode, encode
+
+
+@dataclass
+class Entry:
+    key: bytes
+    value: bytes | None
+
+
+@dataclass
+class ParsedFile:
+    prefix: bytes
+    footer: Node
+
+
+def parse(path):
+    data = path.read_bytes()
+    assert data[:4] == data[-4:] == b"PAR1"
+    length = struct.unpack("<I", data[-8:-4])[0]
+    result = decode(data[-8-length:-8])
+    assert result.consumed == length
+    return ParsedFile(data[:-8-length], result.node)
+
+
+def metadata(path):
+    footer = parse(path).footer
+    if 5 not in footer.value:
+        return None
+    field = footer.value[5]
+    assert field.kind == TType.LIST and field.element_kind == TType.STRUCT
+    result = []
+    for item in field.value:
+        assert item.kind == TType.STRUCT and item.value[1].kind == TType.STRING
+        value = item.value.get(2)
+        assert value is None or value.kind == TType.STRING
+        result.append(Entry(item.value[1].value, value.value if value is not None else None))
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--probe", required=True, type=Path)
+    args = parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix="parquet-metadata-") as directory:
+        root = Path(directory)
+        source, copied = root / "source", root / "copied"
+        source.mkdir()
+        subprocess.run([str(args.probe), "--metadata", str(source)], check=True)
+        expected = [Entry(b"same", None), Entry(b"same", b""), Entry(b"same", b"last"),
+                    Entry("κλειδί".encode(), "世界".encode()), Entry(b"opaque", b"\xff\x00\x80")]
+        assert metadata(source / "absent.parquet") is None
+        assert metadata(source / "empty.parquet") == []
+        assert metadata(source / "entries.parquet") == expected
+        schema = pa.schema([pa.field("x", pa.int32())], metadata={b"custom": b"\xff\x00", "name".encode(): "世界".encode()})
+        table = pa.Table.from_arrays([pa.array([-2**31, 0, 2**31-1], pa.int32())], schema=schema)
+        foreign = source / "foreign.parquet"
+        pq.write_table(table, foreign, compression="NONE", write_page_index=False, write_page_checksum=True)
+        assert any(entry.key == b"ARROW:schema" for entry in metadata(foreign))
+        parsed = parse(foreign)
+        fields = parsed.footer.value
+        fields[5].value.extend([
+            Node(TType.STRUCT, {1: Node(TType.STRING, b"duplicate")}),
+            Node(TType.STRUCT, {1: Node(TType.STRING, b"duplicate"), 2: Node(TType.STRING, b"")}),
+            Node(TType.STRUCT, {1: Node(TType.STRING, b"duplicate"), 2: Node(TType.STRING, b"last")})])
+        raw = encode(parsed.footer)
+        (source / "foreign-duplicate.parquet").write_bytes(parsed.prefix + raw + struct.pack("<I", len(raw)) + b"PAR1")
+        files = sorted(source.glob("*.parquet"))
+        assert len(files) == 5
+        before = {path.name: metadata(path) for path in files}
+        subprocess.run([str(args.probe), "--copy-footers", str(source), str(copied)], check=True)
+        assert {p.name for p in copied.glob("*.parquet")} == set(before)
+        for path in files:
+            assert pq.read_table(path).column("x").to_pylist() == [-2**31, 0, 2**31-1], path.name
+            output = copied / path.name
+            assert metadata(output) == before[path.name], path.name
+            assert pq.read_table(output).column("x").to_pylist() == [-2**31, 0, 2**31-1], path.name
+    print("PASS: 3 native metadata states and5 footer copies; Apache Thrift +PyArrow values,order,duplicates,absent/empty/opaquevalues andARROW:schema")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_narrow_integer_interop.py b/scripts/parquet_narrow_integer_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_narrow_integer_interop.py
@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Check logical integer domains against independently annotated physical values."""
+import argparse
+from pathlib import Path
+import struct
+import tempfile
+import json
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from parquet_variant_interop import footer, run
+from parquet_lzo_interop import encode
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--reader', required=True, type=Path)
+    parser.add_argument('--output', required=True, type=Path)
+    args = parser.parse_args()
+    results = []
+    with tempfile.TemporaryDirectory(prefix='parquet-narrow-integers-') as folder:
+        root = Path(folder)
+        def write(path, typ, values, nested, nullable):
+            array = pa.array(values, type=typ)
+            field = pa.field('a', typ, nullable=nullable)
+            if nested:
+                array = pa.StructArray.from_arrays([array], fields=[field])
+                field = pa.field('v', array.type, nullable=False)
+            pq.write_table(pa.Table.from_arrays([array], schema=pa.schema([field])), path, compression='NONE', use_dictionary=False, store_schema=False)
+        for signed in (True, False):
+            for width in (8, 16):
+                typ = getattr(pa, ('int' if signed else 'uint') + str(width))()
+                low = -(2 ** (width-1)) if signed else 0
+                high = 2 ** (width - (1 if signed else 0)) - 1
+                prototype = root/'prototype'
+                write(prototype, typ, [0], False, False)
+                _, model = footer(prototype)
+                annotation = model.value[2].value[-1].value
+                for nested in (False, True):
+                    for nullable in (False, True):
+                        for label, values, valid in [('bounds', [low, high, 0, 1] + ([None] if nullable else []), True), ('underflow', [low-1], False), ('overflow', [high+1], False)]:
+                            name = f'{typ}-{nested}-{nullable}-{label}'
+                            inputs, output = root/name, root/(name+'-arrow')
+                            inputs.mkdir()
+                            path = inputs/'case.parquet'
+                            write(path, pa.int32(), values, nested, nullable)
+                            prefix, meta = footer(path)
+                            leaf = meta.value[2].value[-1].value
+                            for key in (6, 10):
+                                if key in annotation:
+                                    leaf[key] = annotation[key]
+                            raw = encode(meta)
+                            path.write_bytes(prefix+raw+struct.pack('<I',len(raw))+b'PAR1')
+                            result = run([args.reader, inputs, '--arrow-output', output], expected=0 if valid else 1)
+                            if valid:
+                                table = ipc.open_stream(output/'case.parquet.arrows').read_all()
+                                actual = table.column(0).combine_chunks()
+                                if nested:
+                                    actual = actual.field('a')
+                                assert actual.type == typ and actual.to_pylist() == values, (name, actual)
+                            else:
+                                assert 'annotated value exceeds its physical/logical range' in result.stdout, (name, result.stdout, result.stderr)
+                            results.append({'case':name,'invalidRejected':not valid})
+    report={'cases':len(results),'validBoundaryCases':sum(not x['invalidRejected'] for x in results),'invalidRejected':sum(x['invalidRejected'] for x in results),'failures':0,'skips':0,'results':results}
+    args.output.write_text(json.dumps(report,indent=2)+'\n')
+    print(json.dumps({k:v for k,v in report.items() if k!='results'}))
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_nested_bloom_interop.py b/scripts/parquet_nested_bloom_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_nested_bloom_interop.py
@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Check generated nested blooms with unmodified Arrow C++ and liblzo2."""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import parquet_lzo_interop as lzo
+
+
+def values():
+    return [
+        list(map(lambda x: struct.pack('<i', x).hex(), [-7, 0, 42])),
+        list(map(lambda x: struct.pack('<q', x).hex(), [-1099511627776, 1099511627776])),
+        list(map(lambda x: struct.pack('<I', x).hex(), [0x7fc00001, 0x80000000, 0, 0x7f800000])),
+        list(map(lambda x: struct.pack('<d', x).hex(), [-0.0, 0.0, float('inf'), -3.5])),
+        list(map(lambda x: bytes([x % 2]).hex(), range(17))),
+        list(map(lambda x: x.encode().hex(), ['', 'alpha', 'λ\0β'])),
+        ['', b'abc'.hex(), bytes([0, 255, 4, 0, 0, 0]).hex()],
+        [(b'\0' * 9).hex(), (b'\xff' * 9).hex()],
+        [bytes(range(16)).hex()],
+        [bytes(range(12)).hex()],
+        [(b'\xff' * 12).hex()],
+        [(b'\xff' * 16).hex(), (b'\0' * 16).hex()],
+        [(b'\xff' * 32).hex()],
+        [], ['01'], ['00'] * 8,
+    ]
+
+
+def metadata(path):
+    data = path.read_bytes()
+    length = int.from_bytes(data[-8:-4], 'little')
+    start = len(data) - 8 - length
+    footer = lzo.decode(data[start:-8]).node
+    return {'bytes': data, 'footer': footer, 'footerStart': start}
+
+
+def bloom_bytes(path):
+    record = metadata(path)
+    group = record['footer'].value[4].value[0]
+    columns = group.value[1].value
+    assert len(columns) == 2, path
+    cm = columns[0].value[3].value
+    offset, size = cm[14].value, cm[15].value
+    assert offset >= 4 and size > 0 and offset + size <= record['footerStart'], path
+    assert 14 not in columns[1].value[3].value, ('unrequested bloom', path)
+    return record['bytes'][offset:offset + size]
+
+
+def strip_auxiliary(source, target):
+    record = metadata(source)
+    for group in record['footer'].value[4].value:
+        for chunk in group.value[1].value:
+            for field in (4, 5, 6, 7):
+                chunk.value.pop(field, None)
+            column = chunk.value[3].value
+            column.pop(14, None)
+            column.pop(15, None)
+    footer = lzo.encode(record['footer'])
+    target.write_bytes(record['bytes'][:record['footerStart']] + footer + struct.pack('<I', len(footer)) + b'PAR1')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--fixtures', type=Path, required=True)
+    parser.add_argument('--reference', type=Path, required=True)
+    parser.add_argument('--lzo-reference', type=Path, required=True)
+    parser.add_argument('--output', type=Path, required=True)
+    args = parser.parse_args()
+    files = sorted(args.fixtures.glob('nested-generated-bloom-*.parquet'))
+    assert len(files) == 224, ('full seven-codec/two-page/16-model coverage', len(files))
+    expected = values()
+    records = []
+    cpp_queries = 0
+    operations = 0
+    with tempfile.TemporaryDirectory(prefix='nested-bloom-interop-') as temp:
+        scratch = Path(temp)
+        for path in files:
+            index, codec, version = path.stem.removeprefix('nested-generated-bloom-').split('-')
+            case = int(index)
+            canonical = args.fixtures / f'nested-generated-bloom-{case}-Uncompressed-{version}.parquet'
+            assert bloom_bytes(path) == bloom_bytes(canonical), ('codec-independent bloom bytes', path)
+            readable = path
+            if codec == 'LZO':
+                stripped, readable = scratch / 'stripped.parquet', scratch / 'decoded.parquet'
+                strip_auxiliary(path, stripped)
+                operations += lzo.transcode(stripped, readable, 0, args.lzo_reference, scratch,
+                                            require_source_codec=3, expected_version=1 if version == 'PageV1' else 2)
+            proc = subprocess.run([str(args.reference), str(readable), '-', 'plaintext'], capture_output=True, text=True)
+            assert proc.returncode == 0, (path, proc.stderr)
+            header, *columns = map(json.loads, proc.stdout.splitlines())
+            assert header['rowGroups'] == 1 and len(columns) == 2, path
+            assert columns[0]['pathParts'] == ['values.with.dot', 'list', 'element'], path
+            assert columns[0]['values'] == expected[case], ('physical values', path, columns[0]['values'])
+            assert columns[1]['values'] == list(map(lambda x: struct.pack('<i', x).hex(), [1, 2, 3])), path
+            assert columns[1]['bloomBytes'] == 0, path
+            if codec != 'LZO':
+                assert columns[0]['bloomBytes'] > 0, path
+                assert columns[0]['bloomValuesChecked'] == len(expected[case]), path
+                cpp_queries += len(expected[case])
+            else:
+                # Unmodified C++ lacks LZO. liblzo2 decodes only compression;
+                # C++ then proves exact physical values. Original bloom bytes
+                # equal the matching uncompressed fixture checked above.
+                assert columns[0]['bloomBytes'] == 0, path
+            records.append({'file': path.name, 'physicalValuesMatchIndependentModel': True,
+                            'bloomMatchesUncompressedControl': True,
+                            'cppDirectBloomProbes': len(expected[case]) if codec != 'LZO' else 0,
+                            'lzoValuesViaIndependentLiblzo2': codec == 'LZO'})
+    proof = {'files': records, 'fileCount': len(records), 'cppBloomValueQueries': cpp_queries,
+             'independentLzoPageOperations': operations,
+             'referenceSHA256': hashlib.sha256(args.reference.read_bytes()).hexdigest(),
+             'allPassed': True}
+    args.output.write_text(json.dumps(proof, indent=2) + '\n')
+    print(f'PASS: {len(records)} files, {cpp_queries} C++ membership probes, {operations} liblzo2 page operations')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_nested_options_interop.py b/scripts/parquet_nested_options_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_nested_options_interop.py
@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Independent nested compression/page-version/index checks.
+
+Requires all optional codecs enabled. LZO pages are decoded through an
+unmodified liblzo2 oracle, then read by PyArrow, DuckDB and Polars; the
+ordinary PyArrow build does not include LZO. Index metadata is verified on
+the original files before that codec-only conversion.
+"""
+import argparse
+from pathlib import Path
+import hashlib,json,struct,subprocess
+import duckdb
+import polars as pl
+import pyarrow as pa
+import pyarrow.parquet as pq
+import parquet_nested_types_interop as typed
+import parquet_lzo_interop as lzo
+
+
+def without_indexes(source,target):
+    data=source.read_bytes();length=int.from_bytes(data[-8:-4],'little');start=len(data)-8-length
+    footer=lzo.decode(data[start:-8]).node
+    for group in footer.value[4].value:
+        for chunk in group.value[1].value:
+            for field in (4,5,6,7):chunk.value.pop(field,None)
+    encoded=lzo.encode(footer)
+    target.write_bytes(data[:start]+encoded+struct.pack('<I',len(encoded))+b'PAR1')
+
+
+def main():
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--probe',type=Path,required=True)
+    parser.add_argument('--lzo-reference',type=Path,required=True)
+    parser.add_argument('--output-dir',type=Path,required=True)
+    parser.add_argument('--aux-fixtures',type=Path,required=True)
+    parser.add_argument('--reference',type=Path,required=True)
+    args=parser.parse_args();root=args.output_dir;root.mkdir(parents=True,exist_ok=True)
+    inputs=root/'inputs';outputs=root/'outputs';references=root/'references';scratch=root/'scratch'
+    for folder in (inputs,references,scratch):folder.mkdir(exist_ok=True)
+    expected=dict(typed.catalogue())
+    extra=pa.Table.from_pylist([
+        {'s':None,'l':None,'b':b''},
+        {'s':{'x':None,'t':'日本語'},'l':[],'b':None},
+        {'s':{'x':-7,'t':None},'l':[None,True,False],'b':b'\x00\xff'},
+    ],schema=pa.schema([('s',pa.struct([('x',pa.int32()),('t',pa.string())])),('l',pa.list_(pa.bool_())),('b',pa.binary())]))
+    expected['mixed_nested']=extra
+    expected['all_null']=pa.table({'v':pa.array([None,None,None],type=pa.int32())})
+    for name,table in expected.items():
+        with pa.OSFile(str(inputs/(name+'.arrow')),'wb') as sink:
+            with pa.ipc.new_file(sink,table.schema) as stream:stream.write_table(table)
+        pq.write_table(table,references/(name+'.parquet'))
+    subprocess.run([str(args.probe),'--nested-options-from-arrow',str(inputs),str(outputs)],check=True)
+    aux_results=[]
+    for name in ('nested-bloom-with-options','nested-all-null-with-options'):
+        path=args.aux_fixtures/(name+'.parquet');output=root/(name+'.arrow')
+        proc=subprocess.run([str(args.reference),str(path),str(output),'plaintext'],capture_output=True,text=True)
+        assert proc.returncode==0,(name,proc.stderr)
+        header,*columns=map(json.loads,proc.stdout.splitlines())
+        assert header['rowGroups']==1 and len(columns)==1,name
+        assert columns[0]['bloomBytes']>0 and columns[0]['offsetPages']==1,name
+        if 'all-null' in name:
+            assert columns[0]['columnIndex'] and columns[0]['nullPages']==[True],name
+            expected_aux=pa.table({'v':pa.array([None,None,None],type=pa.int32())})
+        else:
+            expected_aux=pa.table({'v':pa.array([None,[],[42,None,-7],[9]],type=pa.list_(pa.field('element',pa.int32())))})
+        typed.assert_equal(name,pa.ipc.open_stream(output).read_all(),expected_aux)
+        aux_results.append({'file':name,'cppValuesIndexBloomPass':True})
+    results=[];codec_names={'Uncompressed':'UNCOMPRESSED','GZip':'GZIP','Snappy':'SNAPPY','ZSTD':'ZSTD','LZ4Raw':'LZ4','LZO':'LZO','Brotli':'BROTLI'}
+    with duckdb.connect() as db:
+        for codec,metadata_codec in codec_names.items():
+            for version in (1,2):
+                directory=outputs/(codec+'-PageV'+str(version));files=sorted(directory.glob('*.parquet'))
+                assert set(map(lambda p:p.stem,files))==set(expected),(codec,version,'case coverage')
+                operations=0
+                for path in files:
+                    metadata=pq.ParquetFile(path).metadata
+                    assert metadata.num_row_groups==1,path
+                    group=metadata.row_group(0)
+                    assert group.total_byte_size==sum(group.column(i).total_uncompressed_size for i in range(group.num_columns)),path
+                    data=path.read_bytes();footer_length=int.from_bytes(data[-8:-4],'little')
+                    footer=lzo.decode(data[-8-footer_length:-8]).node
+                    chunks=footer.value[4].value[0].value[1].value
+                    for index in range(group.num_columns):
+                        column=group.column(index)
+                        header=lzo.decode(data[column.data_page_offset:])
+                        assert header.node.value[1].value==(0 if version==1 else 3),(path,'page version')
+                        assert header.consumed+header.node.value[3].value==column.total_compressed_size,(path,'compressed size')
+                        assert header.consumed+header.node.value[2].value==column.total_uncompressed_size,(path,'uncompressed size')
+                        chunk=chunks[index].value
+                        offset_index=lzo.decode(data[chunk[4].value:chunk[4].value+chunk[5].value])
+                        assert offset_index.consumed==chunk[5].value,(path,'offset index size')
+                        pages=offset_index.node.value[1].value
+                        assert len(pages)==1,(path,'page count')
+                        page=pages[0].value
+                        assert page[1].value==column.data_page_offset and page[2].value==column.total_compressed_size and page[3].value==0,(path,'offset index locations')
+                        assert column.compression==metadata_codec,(path,column.compression)
+                        assert column.has_offset_index,(path,'offset index missing')
+                    readable=path
+                    if codec=='LZO':
+                        stripped=scratch/'stripped.parquet';readable=scratch/'decoded.parquet'
+                        without_indexes(path,stripped)
+                        operations+=lzo.transcode(stripped,readable,0,args.lzo_reference,scratch,require_source_codec=3,expected_version=version)
+                    actual=pq.ParquetFile(readable).read(use_threads=False)
+                    typed.assert_equal(str(path),actual,expected[path.stem])
+                    reference=references/(path.stem+'.parquet')
+                    own=db.execute('SELECT * FROM read_parquet(?)',[str(readable)]).to_arrow_table()
+                    ref=db.execute('SELECT * FROM read_parquet(?)',[str(reference)]).to_arrow_table()
+                    typed.assert_equal('DuckDB '+str(path),own,ref)
+                    typed.assert_equal('Polars '+str(path),pl.read_parquet(readable).to_arrow(),pl.read_parquet(reference).to_arrow())
+                results.append({'codec':codec,'pageVersion':version,'files':len(files),'engines':['PyArrow','DuckDB','Polars'],'independentLzoPageOperations':operations,'passed':True})
+                (root/'results.json').write_text(json.dumps({'probeSHA256':hashlib.sha256(args.probe.read_bytes()).hexdigest(),'pyarrowVersion':pa.__version__,'auxiliaryFixtures':aux_results,'groups':results},indent=2)+'\n')
+                print(codec,version,len(files),'PASS',flush=True)
+    print('PASS',sum(x['files'] for x in results),'nested option files across three independent readers',flush=True)
+
+
+if __name__=='__main__':main()
diff --git a/scripts/parquet_nested_statistics_interop.py b/scripts/parquet_nested_statistics_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_nested_statistics_interop.py
@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""Validate nested bounds, orderings and NaN counts with independent readers.
+
+Literal metadata is decoded with Apache Thrift. Arrow C++ supplies physical
+values and checks bloom membership; Python supplies independent scalar/order
+models. LZO changes compression only through unmodified liblzo2.
+"""
+import argparse
+import hashlib
+import json
+import math
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+import parquet_lzo_interop as lzo
+import parquet_nested_bloom_interop as bloom
+
+
+def floating_width(kind):
+    return {'LtFloat16': 2, 'LtFloat': 4, 'LtDouble': 8}.get(kind)
+
+
+def expected_bounds(model):
+    values = list(map(bytes.fromhex, model['values']))
+    if not values:
+        return {'min': None, 'max': None, 'nans': 0 if floating_width(model['type']) else None}
+    kind = model['type']
+    width = floating_width(kind)
+    if width:
+        fmt = {2: '<e', 4: '<f', 8: '<d'}[width]
+        numeric = list(filter(lambda value: not math.isnan(struct.unpack(fmt, value)[0]), values))
+        nans = len(values) - len(numeric)
+        if numeric:
+            def key(value):
+                number = struct.unpack(fmt, value)[0]
+                zero_sign = 0 if int.from_bytes(value, 'little') >> (width * 8 - 1) else 1
+                return (number, zero_sign if number == 0 else 0)
+            ordered = sorted(numeric, key=key)
+        else:
+            # IEEE totalOrder orders negative quiet NaNs before negative
+            # signaling NaNs, with reversed payload order; positive NaNs use
+            # the opposite ordering. Keep the original bytes throughout.
+            def nan_key(value):
+                bits = int.from_bytes(value, 'little')
+                mantissa_bits = {2: 10, 4: 23, 8: 52}[width]
+                negative = bool(bits >> (width * 8 - 1))
+                quiet = (bits >> (mantissa_bits - 1)) & 1
+                payload = bits & ((1 << (mantissa_bits - 1)) - 1)
+                return (0, -quiet, -payload) if negative else (1, quiet, payload)
+            ordered = sorted(values, key=nan_key)
+        return {'min': ordered[0].hex(), 'max': ordered[-1].hex(), 'nans': nans}
+    if model['order'] == 'Int96TimestampOrder':
+        def key(value):
+            nanos, day = struct.unpack('<qi', value)
+            return (day, nanos)
+    elif kind.startswith('LtTimestamp96'):
+        key = lambda value: int.from_bytes(value, 'little', signed=True)
+    elif kind.startswith('LtDecimal'):
+        precision = int(kind.split()[1])
+        key = lambda value: int.from_bytes(value, 'little' if precision <= 18 else 'big', signed=True)
+    elif kind.startswith('LtInteger'):
+        signed = kind.split()[-1] == 'True'
+        key = lambda value: int.from_bytes(value, 'little', signed=signed)
+    elif kind in ('LtInt32', 'LtInt64'):
+        key = lambda value: int.from_bytes(value, 'little', signed=True)
+    else:
+        key = lambda value: value
+    ordered = sorted(values, key=key)
+    return {'min': ordered[0].hex(), 'max': ordered[-1].hex(), 'nans': None}
+
+
+def check_metadata(path, model, indexed):
+    record = bloom.metadata(path)
+    footer = record['footer'].value
+    orders = footer[7].value
+    assert len(orders) == 1, path
+    expected_order = {'TypeDefinedOrder': 1, 'IEEE754TotalOrder': 2, 'Int96TimestampOrder': 3}[model['order']]
+    assert set(orders[0].value) == {expected_order}, ('column ordering', path)
+    group = footer[4].value[0].value
+    assert group[3].value == 3, path
+    chunk = group[1].value[0].value
+    column = chunk[3].value
+    assert column[5].value == len(model['values']) + 3, path
+    stats = column[12].value
+    assert stats[3].value == 3, ('null count', path)
+    assert 1 not in stats and 2 not in stats, ('deprecated bounds must stay absent', path)
+    for field, name in [(6, 'min'), (5, 'max')]:
+        if model[name] is None:
+            assert field not in stats, (path, name)
+        else:
+            assert stats[field].value.hex() == model[name], (path, name, stats[field].value.hex(), model[name])
+    for field in (7, 8):
+        assert (stats[field].value if field in stats else None) == (True if model['min'] is not None else None), (path, 'exact bound marker')
+    assert (stats[9].value if 9 in stats else None) == model['nans'], ('NaN count', path)
+    assert (6 in chunk and 7 in chunk and 4 in chunk and 5 in chunk) == indexed, path
+    if indexed:
+        ci = lzo.decode(record['bytes'][chunk[6].value:chunk[6].value+chunk[7].value]).node.value
+        assert list(map(lambda entry: entry.value, ci[1].value)) == [not model['values']], ('null page', path)
+        assert list(map(lambda entry: entry.value, ci[2].value)) == [bytes.fromhex(model['min']) if model['min'] is not None else b''], ('page minimum', path)
+        assert list(map(lambda entry: entry.value, ci[3].value)) == [bytes.fromhex(model['max']) if model['max'] is not None else b''], ('page maximum', path)
+        assert list(map(lambda entry: entry.value, ci[5].value)) == [3], ('page null count', path)
+        assert (list(map(lambda entry: entry.value, ci[8].value)) if 8 in ci else None) == ([model['nans']] if model['nans'] is not None else None), ('page NaN count', path)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--fixtures', type=Path, required=True)
+    parser.add_argument('--reference', type=Path, required=True)
+    parser.add_argument('--lzo-reference', type=Path, required=True)
+    parser.add_argument('--half-output', type=Path, required=True)
+    parser.add_argument('--output', type=Path, required=True)
+    args = parser.parse_args()
+    models = json.loads((args.fixtures/'nested-stats-models.json').read_text())
+    named = {}
+    for model in models:
+        actual = expected_bounds(model)
+        assert actual == {name: model[name] for name in ('min', 'max', 'nans')}, ('independent model', model['name'], actual)
+        named[model['name']] = model
+    files = sorted(args.fixtures.glob('nested-stats-*.parquet'))
+    assert len(files) == len(models)*7*2*2, ('full codec/page/index matrix', len(files))
+    records = []
+    probes = operations = 0
+    with tempfile.TemporaryDirectory(prefix='nested-statistics-interop-') as temp:
+        scratch = Path(temp)
+        for path in files:
+            name, codec, version, indexed = path.stem.removeprefix('nested-stats-').rsplit('-', 3)
+            model = named[name]
+            indexed = indexed == 'True'
+            check_metadata(path, model, indexed)
+            def stored_bloom(source):
+                record = bloom.metadata(source)
+                cm = record['footer'].value[4].value[0].value[1].value[0].value[3].value
+                offset, size = cm[14].value, cm[15].value
+                return record['bytes'][offset:offset+size]
+            control = args.fixtures / f'nested-stats-{name}-Uncompressed-{version}-{indexed}.parquet'
+            assert stored_bloom(path) == stored_bloom(control), ('codec-independent bloom bytes', path)
+            readable = path
+            if codec == 'LZO':
+                stripped, readable = scratch/'stripped.parquet', scratch/'decoded.parquet'
+                bloom.strip_auxiliary(path, stripped)
+                operations += lzo.transcode(stripped, readable, 0, args.lzo_reference, scratch,
+                                            require_source_codec=3, expected_version=1 if version == 'PageV1' else 2)
+            proc = subprocess.run([str(args.reference),str(readable),'-','plaintext'],capture_output=True,text=True)
+            assert proc.returncode == 0, (path, proc.stderr)
+            header, column = map(json.loads,proc.stdout.splitlines())
+            assert header['rows'] == 3 and header['columns'] == 1, path
+            assert column['values'] == model['values'], ('physical values',path,column['values'],model['values'])
+            if codec != 'LZO':
+                assert column['bloomValuesChecked'] == len(model['values']), path
+                assert column['columnIndex'] == indexed, path
+                if indexed:
+                    assert column['pageMaxima'] == [model['max'] or ''], path
+                probes += len(model['values'])
+            records.append({'file':path.name,'literalMetadataAndOrderMatch':True,'independentScalarModelMatches':True,'cppValuesMatch':True,'lzoCompressionOnly':codec=='LZO'})
+        half_files = sorted(args.half_output.glob('*/*.parquet'))
+        assert len(half_files) == 14, len(half_files)
+        for path in half_files:
+            readable = path
+            if path.parent.name.startswith('LZO-'):
+                stripped, readable = scratch/'half-stripped.parquet',scratch/'half-decoded.parquet'
+                bloom.strip_auxiliary(path,stripped)
+                operations += lzo.transcode(stripped,readable,0,args.lzo_reference,scratch,require_source_codec=3,expected_version=1 if 'PageV1' in path.parent.name else 2)
+            table = pq.read_table(readable)
+            assert table.schema.field(0).type == pa.float16(), (path,table.schema)
+            assert table.column(0).to_pylist() == [1.0,None,-0.0], path
+            raw = table.column(0).combine_chunks().buffers()[1].to_pybytes()
+            assert raw[:2] == b'\x00\x3c' and raw[4:6] == b'\x00\x80', ('half bits',path,raw.hex())
+    proof={'files':records,'fileCount':len(records),'models':len(models),'cppBloomProbes':probes,'liblzo2PageOperations':operations,'halfArrowFiles':14,'referenceSHA256':hashlib.sha256(args.reference.read_bytes()).hexdigest(),'allPassed':True}
+    args.output.write_text(json.dumps(proof,indent=2)+'\n')
+    print(f'PASS: {len(records)} nested statistics files, {len(models)} independent scalar models, {probes} C++ probes,14 Arrow binary16 round-trips')
+
+
+if __name__=='__main__':main()
diff --git a/scripts/parquet_nested_types_interop.py b/scripts/parquet_nested_types_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_nested_types_interop.py
@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Check typed nested output against independent Arrow models and writers.
+
+PyArrow must preserve exact logical types and values, including nanoseconds.
+DuckDB and Polars compare the wireform file with a PyArrow-written reference
+of that same table, allowing each engine its own canonical Arrow types.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import subprocess
+import tempfile
+
+import duckdb
+import polars as pl
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+
+def catalogue():
+    cases = {
+        "i8": (pa.int8(), [-128, -1, 0, 127]),
+        "i16": (pa.int16(), [-32768, -1, 0, 32767]),
+        "i32": (pa.int32(), [-(2**31), -1, 0, 2**31 - 1]),
+        "i64": (pa.int64(), [-(2**63), -1, 0, 2**63 - 1]),
+        "u8": (pa.uint8(), [0, 127, 128, 255]),
+        "u16": (pa.uint16(), [0, 32767, 32768, 65535]),
+        "u32": (pa.uint32(), [0, 2**31 - 1, 2**31, 2**32 - 1]),
+        "u64": (pa.uint64(), [0, 2**63 - 1, 2**63, 2**64 - 1]),
+        "date32": (pa.date32(), [-1, 0, 1, 20000]),
+        "date64": (pa.date32(), [-1, 0, 1, 2]),
+        "time_s": (pa.time32("ms"), [0, 1000, 43200000, 86399000]),
+        "time_ms": (pa.time32("ms"), [0, 1, 43200000, 86399999]),
+        "time_us": (pa.time64("us"), [0, 1, 43200000000, 86399999999]),
+        "time_ns": (pa.time64("ns"), [0, 1, 43200000000000, 86399999999999]),
+        "bool": (pa.bool_(), [True, False, True, True]),
+    }
+    for zone_label, zone in [("local", None), ("utc", "UTC")]:
+        for unit in ["s", "ms", "us", "ns"]:
+            data = [-1, 0, 1, 1700000000]
+            if unit == "s":
+                data = list(map(lambda value: value * 1000, data))
+            cases[f"timestamp_{unit}_{zone_label}"] = (
+                pa.timestamp("ms" if unit == "s" else unit, tz=zone), data
+            )
+    for label, (typ, data) in cases.items():
+        values = pa.array(data, type=typ)
+        yield label + "_scalar", table(values, nullable=False)
+        parent = pa.StructArray.from_arrays(
+            [values], fields=[pa.field("v", typ, nullable=False)],
+            mask=pa.array([False, True, False, False]),
+        )
+        yield label + "_struct", table(parent, nullable=True)
+        element = pa.field("element", typ, nullable=False)
+        lists = pa.ListArray.from_arrays(
+            pa.array([0, 2, 2, 3], type=pa.int32()), values.slice(1, 3),
+            type=pa.list_(element),
+        )
+        yield label + "_list", table(lists, nullable=False)
+        maps = pa.MapArray.from_arrays(
+            pa.array([0, 2, 2, 3], type=pa.int32()),
+            pa.array([2, 3, 4], type=pa.uint32()), values.slice(1, 3),
+            type=pa.map_(pa.field("key", pa.uint32(), nullable=False),
+                         pa.field("value", typ, nullable=False)),
+        )
+        yield label + "_map", table(maps, nullable=False)
+    for count in range(66):
+        values = pa.array(list(map(lambda i: None if i % 4 == 0 else i % 3 == 0,
+                                   range(count))), type=pa.bool_())
+        yield f"bool_tail_{count}", table(values, nullable=True)
+    parent = pa.StructArray.from_arrays(
+        # A filler beneath the null parent is logically absent. PyArrow's
+        # writer rejects a physical null in a required child even there;
+        # the probe still supplies that hidden null/poison to wireform.
+        [pa.array([-1, 0, 1], type=pa.date32())],
+        fields=[pa.field("date", pa.date32(), nullable=False)],
+        mask=pa.array([False, True, False]),
+    )
+    yield "poison_struct", table(parent, nullable=True)
+    lists = pa.ListArray.from_arrays(
+        pa.array([0, 2], type=pa.int32()), pa.array([0, 1000], type=pa.time32("ms")),
+        type=pa.list_(pa.field("element", pa.time32("ms"), nullable=False)),
+    )
+    yield "poison_list", table(lists, nullable=False)
+    maps = pa.MapArray.from_arrays(
+        pa.array([0, 0, 1], type=pa.int32()), pa.array([2], type=pa.int32()),
+        pa.array([1], type=pa.date32()), mask=pa.array([True, False]),
+        type=pa.map_(pa.field("key", pa.int32(), nullable=False),
+                     pa.field("value", pa.date32(), nullable=False)),
+    )
+    yield "poison_map", table(maps, nullable=True)
+    maps = pa.MapArray.from_arrays(
+        pa.array([0, 2, 2, 3], type=pa.int32()), pa.array([1, 2, 3], type=pa.uint32()),
+        pa.array([2**64 - 1, None, 2**63], type=pa.uint64()),
+        type=pa.map_(pa.field("key", pa.uint32(), nullable=False),
+                     pa.field("value", pa.uint64(), nullable=True)),
+    )
+    yield "map_optional_values", table(maps, nullable=False)
+    nested = pa.array(
+        [[[1, None], None, [], [2]], None, [], [[], [None]]],
+        type=pa.list_(pa.field("element", pa.list_(pa.field("element", pa.int32(), nullable=True)), nullable=True)),
+    )
+    yield "list_of_lists", table(nested, nullable=True)
+    legacy = {
+        "i32": (pa.int32(), [-(2**31), -1, 0, 2**31 - 1]),
+        "i64": (pa.int64(), [-(2**63), -1, 0, 2**63 - 1]),
+        "double": (pa.float64(), [-1.5, 0, 1.5, 1e100]),
+        "bool": (pa.bool_(), [True, False, True, True]),
+        "binary": (pa.binary(), [b"", b"abc", b"\x00\xff", b"tail"]),
+    }
+    for label, (typ, data) in legacy.items():
+        values = pa.array(
+            [[data[0], None, data[1]], None, [], [data[2], data[3]]],
+            type=pa.list_(pa.field("element", typ, nullable=True)),
+        )
+        yield "legacy_" + label, table(values, nullable=True)
+
+
+def table(values, *, nullable):
+    return pa.Table.from_arrays([values], schema=pa.schema([pa.field("v", values.type, nullable=nullable)]))
+
+
+def assert_equal(label, actual, expected):
+    if not actual.equals(expected, check_metadata=False):
+        raise AssertionError(f"{label}: logical values/types differ\nactual: {actual}\nexpected: {expected}")
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--probe", required=True)
+    parser.add_argument("--output-dir")
+    args = parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix="wireform-parquet-nested-types-") as temporary:
+        root = Path(args.output_dir or temporary)
+        outputs = root / "actual"
+        references = root / "reference"
+        outputs.mkdir(parents=True, exist_ok=True)
+        references.mkdir(parents=True, exist_ok=True)
+        subprocess.run([args.probe, "--nested-types", str(outputs)], check=True)
+        expected = dict(catalogue())
+        produced = {path.stem for path in outputs.glob("*.parquet")}
+        if produced != expected.keys():
+            raise AssertionError(f"catalogue mismatch: missing={expected.keys()-produced}, extra={produced-expected.keys()}")
+        checks = 0
+        with duckdb.connect() as connection:
+            for name, model in expected.items():
+                actual_path = outputs / f"{name}.parquet"
+                parquet_file = pq.ParquetFile(actual_path)
+                for column in range(parquet_file.metadata.num_columns):
+                    schema_column = parquet_file.schema.column(column)
+                    encodings = parquet_file.metadata.row_group(0).column(column).encodings
+                    if (schema_column.max_definition_level or schema_column.max_repetition_level) and "RLE" not in encodings:
+                        raise AssertionError(f"{name}: column {column} omits level RLE from encodings")
+                assert_equal(name + ": PyArrow", pq.read_table(actual_path), model)
+                reference_path = references / f"{name}.parquet"
+                pq.write_table(model, reference_path, store_schema=False, use_dictionary=False,
+                               data_page_version="2.0", version="2.6")
+                assert_equal(name + ": DuckDB",
+                             connection.read_parquet(str(actual_path)).to_arrow_table(),
+                             connection.read_parquet(str(reference_path)).to_arrow_table())
+                assert_equal(name + ": Polars", pl.read_parquet(actual_path).to_arrow(),
+                             pl.read_parquet(reference_path).to_arrow())
+                checks += 3
+                print(f"PASS {name}: PyArrow exact + DuckDB/Polars reference compatibility", flush=True)
+        print(f"PASS {len(expected)} nested files / {checks} engine checks; "
+              f"pyarrow={pa.__version__}, duckdb={duckdb.__version__}, polars={pl.__version__}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_primitive_interop.py b/scripts/parquet_primitive_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_primitive_interop.py
@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Independently verify native decimal/fixed/UUID files through PyArrow.
+
+Input files are emitted by NestedPrimitiveRegression with
+WIREFORM_PARQUET_PRIMITIVE_OUTPUT set. Missing fixtures and unsupported
+reference behavior fail; this driver does not skip cases.
+"""
+import decimal
+import json
+from pathlib import Path
+import sys
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+
+def decimal_value(raw, scale):
+    with decimal.localcontext() as context:
+        context.prec = 100
+        return decimal.Decimal(raw).scaleb(-scale)
+
+
+def check(directory):
+    checks = 0
+    for precision in range(1, 77):
+        path = directory / f"decimal-{precision}.parquet"
+        table = pq.read_table(path)
+        table.validate(full=True)
+        datatype = table.schema.field(0).type
+        assert datatype.precision == precision and datatype.scale == precision, path
+        bound = 10 ** precision - 1
+        assert table.column(0).to_pylist() == [decimal_value(-bound, precision), None, decimal_value(0, precision), decimal_value(bound, precision)], path
+        physical = pq.ParquetFile(path).schema.column(0).physical_type
+        assert physical == ("INT32" if precision <= 9 else "INT64" if precision <= 18 else "FIXED_LEN_BYTE_ARRAY"), (path, physical)
+        checks += 1
+    for width in (1, 2, 3, 16, 31, 32, 64):
+        path = directory / f"fixed-{width}.parquet"
+        table = pq.read_table(path)
+        table.validate(full=True)
+        assert table.column(0).to_pylist() == [bytes(range(width)), None, bytes([255]) * width], path
+        assert pa.types.is_fixed_size_binary(table.schema.field(0).type), path
+        assert table.schema.field(0).type.byte_width == width, path
+        checks += 1
+    path = directory / "uuid.parquet"
+    table = pq.read_table(path)
+    table.validate(full=True)
+    value = table.column(0).to_pylist()[0]
+    assert (value.bytes if hasattr(value, "bytes") else value) == bytes(range(16)), path
+    assert pq.ParquetFile(path).schema.column(0).logical_type.type == "UUID", path
+    checks += 1
+    for bits, precision in ((32, 9), (64, 18), (128, 38), (256, 76)):
+        wanted = [decimal_value(-(10 ** precision - 1), 2), decimal_value(0, 2), decimal_value(123, 2)]
+        for shape in ("flat", "list"):
+            path = directory / f"arrow-{shape}-{bits}.parquet"
+            table = pq.read_table(path)
+            table.validate(full=True)
+            assert table.column(0).to_pylist() == (wanted if shape == "flat" else [wanted[:1], wanted[1:]]), path
+            checks += 1
+    return {"pyarrow": pa.__version__, "semantic_file_checks": checks, "failures": 0, "skips": 0}
+
+
+if __name__ == "__main__":
+    assert len(sys.argv) == 2, "usage: parquet_primitive_interop.py FIXTURE_DIRECTORY"
+    print(json.dumps(check(Path(sys.argv[1])), indent=2))
diff --git a/scripts/parquet_projection_interop.py b/scripts/parquet_projection_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_projection_interop.py
@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""Check nested schema projection against independent PyArrow files and models.
+
+The target is delivered as a schema-only Arrow IPC stream. Positive checks
+compare output schema and values, not just successful decoding. Cases vary
+page versions, dictionary encoding, compression, storage wrapper names and
+row-group boundaries (including null-only groups).
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+from parquet_aggregate_interop import groups, rewrite
+
+
+def field(name, typ, nullable=True):
+    return pa.field(name, typ, nullable=nullable)
+
+
+def schema(typ, nullable=True):
+    return pa.schema([field("v", typ, nullable)])
+
+
+def catalogue():
+    source_list = pa.list_(field("source_item", pa.int32()))
+    source_struct = pa.struct([
+        field("unused", pa.int32(), False), field("small", pa.int32()),
+        field("float", pa.float32()),
+    ])
+    selected = pa.struct([field("float", pa.float64()), field("small", pa.int64(), False)])
+    records = [
+        {"unused": 9, "small": 1, "float": 1.5}, None,
+        {"unused": 7, "small": 2, "float": None},
+        {"unused": 5, "small": 3, "float": 4.5},
+    ]
+    lists = [[1, None, 2], None, [], [3]]
+    yield "list", schema(source_list), lists, schema(pa.list_(field("custom", pa.int64())))
+    yield "large-list", schema(source_list), lists, schema(pa.large_list(field("custom", pa.int64())))
+    yield "struct", schema(source_struct), records, schema(selected)
+    yield "empty-struct", schema(source_struct), records, schema(pa.struct([]))
+    yield "list-struct", schema(pa.list_(field("source_item", source_struct))), [records[:3], None, [], records[3:]], schema(pa.large_list(field("requested_item", selected)))
+    source_map = pa.map_(field("key", pa.int32(), False), field("value", pa.float32()))
+    target_map = pa.map_(field("k", pa.int64(), False), field("x", pa.float64()))
+    yield "map", schema(source_map), [[(1, 1.5), (2, None)], None, [], [(3, 3.5)]], schema(target_map)
+    yield "lists-of-lists", schema(pa.list_(field("outer", source_list))), [[[1], None, [], [2, None]], None, [], [[3]]], schema(pa.large_list(field("out", pa.large_list(field("in", pa.int64())))))
+    yield "list-of-maps", schema(pa.list_(field("source", source_map))), [[[(1, 1.5)], None, []], None, [], [[(2, None)]]], schema(pa.large_list(field("target", target_map)))
+    yield "map-of-structs", schema(pa.map_(field("key", pa.int32(), False), field("value", source_struct))), [[(1, records[0]), (2, None)], None, [], [(3, records[2])]], schema(pa.map_(field("id", pa.int64(), False), field("record", selected)))
+    yield "struct-list", schema(pa.struct([field("unused", pa.int32(), False), field("items", source_list)])), [{"unused": 1, "items": [1, None]}, None, {"unused": 2, "items": []}, {"unused": 3, "items": None}], schema(pa.struct([field("items", pa.large_list(field("renamed", pa.int64())))]))
+
+
+def project_value(source, target, value):
+    """A logical model independent of Dremel levels and wireform's reader."""
+    if value is None:
+        if not target.nullable:
+            raise ValueError("visible null in required target")
+        return None
+    actual, requested = source.type, target.type
+    if pa.types.is_struct(actual):
+        result = {}
+        for child in requested:
+            result[child.name] = project_value(actual.field(child.name), child, value[child.name])
+        return result
+    if pa.types.is_list(actual) or pa.types.is_large_list(actual):
+        result = []
+        for item in value:
+            result.append(project_value(actual.value_field, requested.value_field, item))
+        return result
+    if pa.types.is_map(actual):
+        result = []
+        for key, item in value:
+            result.append((project_value(actual.key_field, requested.key_field, key),
+                           project_value(actual.item_field, requested.item_field, item)))
+        return result
+    if actual != requested and not (
+        actual == pa.int32() and requested == pa.int64()
+        or actual == pa.float32() and requested == pa.float64()
+    ):
+        raise ValueError("incompatible leaf projection")
+    return value
+
+
+def write_target(path, target):
+    with pa.OSFile(str(path), "wb") as sink:
+        with pa.ipc.new_stream(sink, target):
+            pass
+
+
+def projected(probe, source, target_path, output, expected, success=True):
+    result = subprocess.run([str(probe), "--project", str(source), str(target_path), str(output)],
+                            text=True, capture_output=True)
+    if not success:
+        assert result.returncode != 0, (source.name, "unexpected projection success")
+        assert "IncompatibleType" in result.stdout or "MissingColumn" in result.stdout, result.stdout
+        return
+    assert result.returncode == 0, (source.name, result.stdout, result.stderr)
+    actual = pa.ipc.open_stream(output).read_all()
+    actual.validate(full=True)
+    assert actual.schema.equals(expected.schema, check_metadata=True), (source.name, actual.schema, expected.schema)
+    assert actual.equals(expected), (source.name, actual.to_pylist(), expected.to_pylist())
+
+
+def remove_first_metadata(node):
+    for group in groups(node):
+        # RowGroup.columns[0].meta_data is optional in the Thrift schema.
+        columns = group[1][1][1][1]
+        columns[0][1].pop(3, None)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reader", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path)
+    args = parser.parse_args()
+    probe = args.reader.resolve()
+    temporary = tempfile.TemporaryDirectory(prefix="wireform-parquet-projection-")
+    root = args.output_dir or Path(temporary.name)
+    root.mkdir(parents=True, exist_ok=True)
+    successes = rejections = poisoned = reference = 0
+    for label, native, values, target in catalogue():
+        source_table = pa.Table.from_pylist(list(map(lambda value: {"v": value}, values)), schema=native)
+        target_path = root / (label + ".schema.arrows")
+        write_target(target_path, target)
+        # PyArrow's own IPC roundtrip canonicalizes map key/value names.
+        # Compare the schema actually delivered by the reference IPC reader.
+        target = pa.ipc.open_stream(target_path).schema
+        expected_rows = []
+        for value in values:
+            expected_rows.append({"v": project_value(native.field(0), target.field(0), value)})
+        expected = pa.Table.from_pylist(expected_rows, schema=target)
+        # C++ performs the same safe widening and wrapper-name conversion.
+        # It conservatively rejects nullable->required children even when all
+        # null children are hidden beneath null parents; the model above checks
+        # that additional wireform case independently.
+        for version, dictionary, codec, group_size, compliant in [
+            ("1.0", False, "NONE", 4, False),
+            ("2.0", True, "snappy", 1, True),
+            ("2.0", False, "zstd", 2, False),
+        ]:
+            name = f"{label}-{version}-{dictionary}-{codec}"
+            source = root / (name + ".parquet")
+            pq.write_table(source_table, source, data_page_version=version,
+                           use_dictionary=dictionary, compression=codec,
+                           row_group_size=group_size, store_schema=False,
+                           use_compliant_nested_type=compliant)
+            projected(probe, source, target_path, root / (name + ".arrows"), expected)
+            successes += 1
+            if label in ("list", "large-list", "map", "lists-of-lists", "list-of-maps", "struct-list"):
+                actual = pq.read_table(source, schema=target)
+                assert actual.equals(expected), (name, "PyArrow projection differs from independent model")
+                reference += 1
+            if label in ("struct", "struct-list"):
+                broken = root / (name + "-omitted-broken.parquet")
+                rewrite(source, broken, remove_first_metadata)
+                projected(probe, broken, target_path, root / (name + "-omitted-broken.arrows"), expected)
+                poisoned += 1
+        print("PASS", label)
+    negative_source = root / "list-1.0-False-NONE.parquet"
+    for label, target in [
+        ("required-element", schema(pa.list_(field("item", pa.int64(), False)))),
+        ("required-parent", schema(pa.list_(field("item", pa.int64())), False)),
+        ("incompatible-leaf", schema(pa.list_(field("item", pa.float64())))),
+        ("missing-parent", pa.schema([field("missing", pa.list_(field("item", pa.int64())))])),
+    ]:
+        path = root / (label + ".schema.arrows")
+        write_target(path, target)
+        projected(probe, negative_source, path, root / (label + ".arrows"), None, success=False)
+        rejections += 1
+    print(f"PASS: {successes} nested projections, {poisoned} omitted broken columns, {rejections} invalid requests; {reference} C++ cross-checks")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_reverse_interop.py b/scripts/parquet_reverse_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_reverse_interop.py
@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""Reverse-direction Parquet interop driver.
+
+Generates Parquet files with each of pyarrow, duckdb, polars
+(emitting different encodings, compression codecs, and shapes)
+then invokes a wireform-side reader probe and reports which
+files wireform-parquet successfully decoded vs failed.
+
+Goal: catalogue exactly which engine-produced shapes we can't
+read today.
+
+Usage:
+    python3 wireform-parquet/scripts/parquet_reverse_interop.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from decimal import Decimal, localcontext
+from pathlib import Path
+from typing import Any
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+import duckdb
+import polars as pl
+
+ROOT = Path(__file__).resolve().parent.parent
+
+def write_pyarrow(out: Path) -> list[Path]:
+    """Generate a variety of pyarrow Parquet files."""
+    written = []
+
+    def write(name: str, table: pa.Table, **kwargs):
+        path = out / name
+        kwargs.setdefault("write_page_checksum", True)
+        pq.write_table(table, path, **kwargs)
+        written.append(path)
+
+    # 1. Plain int32 + int64 + double + utf8 + bool
+    t1 = pa.table({
+        "i32":  pa.array([1, 2, 3], pa.int32()),
+        "i64":  pa.array([10, 20, 30], pa.int64()),
+        "f64":  pa.array([1.5, 2.5, 3.5], pa.float64()),
+        "s":    pa.array(["a", "b", "c"], pa.string()),
+        "b":    pa.array([True, False, True], pa.bool_()),
+    })
+    write("pyarrow_basic_v1.parquet", t1, version="1.0")
+    write("pyarrow_basic_v2.parquet", t1, version="2.6", data_page_version="2.0")
+
+    # 2. With compression
+    write("pyarrow_snappy.parquet", t1, compression="snappy")
+    write("pyarrow_zstd.parquet",   t1, compression="zstd")
+    write("pyarrow_gzip.parquet",   t1, compression="gzip")
+
+    # 3. Nullable columns
+    t2 = pa.table({
+        "id":    pa.array([1, None, 3], pa.int64()),
+        "name":  pa.array(["alice", None, "carol"], pa.string()),
+    })
+    write("pyarrow_nullable.parquet", t2)
+
+    # 4. Dictionary encoding
+    write("pyarrow_dict.parquet",
+          pa.table({"x": pa.array(["a", "b", "a", "c", "b", "a"], pa.string())}),
+          use_dictionary=True)
+
+    # 5. Multiple row groups
+    big = pa.table({"x": pa.array(list(range(100)), pa.int64())})
+    write("pyarrow_multi_rg.parquet", big, row_group_size=25)
+
+    # Logical integer widths and unsigned values above the signed maximum.
+    integers = pa.table({
+        "i8": pa.array([-128, None, 127], pa.int8()),
+        "i16": pa.array([-32768, None, 32767], pa.int16()),
+        "u8": pa.array([0, None, 255], pa.uint8()),
+        "u16": pa.array([0, None, 65535], pa.uint16()),
+        "u32": pa.array([0, None, 2**32 - 1], pa.uint32()),
+        "u64": pa.array([0, None, 2**64 - 1], pa.uint64()),
+    })
+    write("pyarrow_integer_widths.parquet", integers)
+
+    # Annotated fixed-width values: preserve physical widths, signed decimal
+    # bytes, scales, half-float payloads and nulls across page encodings.
+    fixed = pa.table({
+        f"w{width}": pa.array([
+            bytes(width), None, bytes([255]) * width,
+            bytes((lane * 37 + width) % 256 for lane in range(width)),
+        ], pa.binary(width))
+        for width in (1, 2, 7, 12, 16, 32)
+    })
+    half = pa.table({"half": pa.array([0.0, -0.0, None, 1.5, -65504.0, float("inf")], pa.float16())})
+    with localcontext() as context:
+        context.prec = 80
+        decimals = pa.table({
+            f"d{precision}_{scale}": pa.array([
+                Decimal(value).scaleb(-scale) if value is not None else None
+                for value in (0, None, -(10**precision - 1), 10**precision - 1, -1, 1)
+            ], pa.decimal128(precision, scale) if precision <= 38 else pa.decimal256(precision, scale))
+            for precision, scale in ((2, 0), (9, 2), (18, 6), (38, 10), (76, 30))
+        })
+    for version in ("1.0", "2.0"):
+        for dictionary in (False, True):
+            settings = dict(data_page_version=version, use_dictionary=dictionary,
+                            compression="zstd", max_rows_per_page=2, write_batch_size=2)
+            suffix = f"v{version}_dict{int(dictionary)}"
+            write(f"pyarrow_fixed_{suffix}.parquet", fixed, **settings)
+            write(f"pyarrow_half_{suffix}.parquet", half, **settings)
+            write(f"pyarrow_decimal_{suffix}.parquet", decimals, **settings)
+    write("pyarrow_decimal_integer.parquet", decimals, store_decimal_as_integer=True,
+          use_dictionary=False)
+    write("pyarrow_fixed_split.parquet", fixed, use_dictionary=False,
+          column_encoding="BYTE_STREAM_SPLIT")
+    write("pyarrow_fixed_delta.parquet", fixed, use_dictionary=False,
+          column_encoding="DELTA_BYTE_ARRAY")
+    write("pyarrow_half_split.parquet", half, use_dictionary=False,
+          column_encoding="BYTE_STREAM_SPLIT")
+    split_integers = pa.table({
+        "i32": pa.array([-(2**31), None, 2**31-1, 0], pa.int32()),
+        "i64": pa.array([-(2**63), None, 2**63-1, 0], pa.int64()),
+    })
+    write("pyarrow_integer_split.parquet", split_integers, use_dictionary=False,
+          column_encoding="BYTE_STREAM_SPLIT")
+
+    required_int = pa.field("same", pa.int64(), nullable=False)
+    nested = pa.table({
+        "left": pa.array([
+            None, {"same": 1, "items": None}, {"same": 2, "items": []},
+            {"same": 3, "items": [None, 4]}, {"same": 4, "items": [5]},
+            {"same": 5, "items": list(range(97))},
+        ], pa.struct([required_int, pa.field("items", pa.list_(pa.int32()))])),
+        "right": pa.array([
+            {"same": "a", "price": Decimal("-12.345")}, None,
+            {"same": None, "price": None}, {"same": "b", "price": Decimal("0.001")},
+            {"same": "c", "price": Decimal("999999999.999")}, None,
+        ], pa.struct([("same", pa.string()), ("price", pa.decimal128(12, 3))])),
+        "lists": pa.array([
+            None, [], [None], [[]], [[None, "x"], [], None, ["y"]], [["z"]],
+        ], pa.list_(pa.list_(pa.string()))),
+        "maps": pa.array([
+            None, [], [("a", None)], [("b", {"same": None, "items": []})],
+            [("c", {"same": 3, "items": [b"x", None]}), ("d", None)],
+            [("e", {"same": 4, "items": None})],
+        ], pa.map_(pa.string(), pa.struct([("same", pa.int64()), ("items", pa.list_(pa.binary()))]))),
+        "nulls": pa.array([None, [], [None], [None, None], [], None], pa.list_(pa.null())),
+    })
+    for version in ("1.0", "2.0"):
+        for dictionary in (False, True):
+            write(f"pyarrow_nested_v{version}_dict{int(dictionary)}.parquet", nested,
+                  data_page_version=version, use_dictionary=dictionary,
+                  max_rows_per_page=2, write_batch_size=2, compression="zstd")
+    write("pyarrow_json_extension.parquet", pa.table({
+        "doc": pa.array(['{"a":1}', None, '[true,null,"x"]'], pa.json_()),
+    }))
+
+    return written
+
+
+def write_duckdb(out: Path) -> list[Path]:
+    written = []
+    con = duckdb.connect()
+    # Use COPY to write a Parquet file from a SQL query
+    base = "(SELECT * FROM (VALUES (1::INT, 10::BIGINT, 1.5::DOUBLE, 'a', TRUE), (2, 20, 2.5, 'b', FALSE), (3, 30, 3.5, 'c', TRUE)) AS t(i32, i64, f64, s, b))"
+    p = out / "duckdb_basic.parquet"
+    con.execute(f"COPY {base} TO '{p}' (FORMAT 'parquet')")
+    written.append(p)
+    p = out / "duckdb_snappy.parquet"
+    con.execute(f"COPY {base} TO '{p}' (FORMAT 'parquet', COMPRESSION 'snappy')")
+    written.append(p)
+    p = out / "duckdb_zstd.parquet"
+    con.execute(f"COPY {base} TO '{p}' (FORMAT 'parquet', COMPRESSION 'zstd')")
+    written.append(p)
+    return written
+
+
+def write_polars(out: Path) -> list[Path]:
+    written = []
+    df = pl.DataFrame({
+        "i32": pl.Series("i32", [1, 2, 3], dtype=pl.Int32),
+        "i64": pl.Series("i64", [10, 20, 30], dtype=pl.Int64),
+        "f64": pl.Series("f64", [1.5, 2.5, 3.5], dtype=pl.Float64),
+        "s":   pl.Series("s",   ["a", "b", "c"]),
+        "b":   pl.Series("b",   [True, False, True]),
+    })
+    p = out / "polars_basic.parquet"
+    df.write_parquet(p)
+    written.append(p)
+    p = out / "polars_zstd.parquet"
+    df.write_parquet(p, compression="zstd")
+    written.append(p)
+    # Polars's "lz4" maps to the legacy CompressionCodec.LZ4
+    # (codec 5) which is the Hadoop-frame variant. Modern
+    # writers use LZ4_RAW (codec 7); we test that via the
+    # 'lz4_raw' name which both pyarrow and polars accept.
+    p = out / "polars_lz4_raw.parquet"
+    try:
+        df.write_parquet(p, compression="lz4_raw")
+        written.append(p)
+    except Exception:
+        pass
+    p = out / "pyarrow_lz4_raw.parquet"
+    try:
+        pq.write_table(
+            pa.table({
+                "i32": pa.array([1, 2, 3], pa.int32()),
+                "s":   pa.array(["a", "b", "c"], pa.string()),
+            }),
+            p,
+            compression="lz4_raw",
+        )
+        written.append(p)
+    except Exception:
+        pass
+    return written
+
+
+def main() -> int:
+    out = Path(tempfile.mkdtemp(prefix="parquet-reverse-"))
+    print(f"== generating engine-emitted Parquet files in {out}")
+
+    all_files = []
+    all_files += write_pyarrow(out)
+    all_files += write_duckdb(out)
+    all_files += write_polars(out)
+    print(f"== {len(all_files)} files written")
+
+    # Run the wireform-side reader probe.
+    print(f"\n== reading with wireform-parquet")
+    decoded = out / "decoded"
+    probe = os.environ.get("WIREFORM_PARQUET_REVERSE_PROBE")
+    command = [probe] if probe else ["cabal", "run", "wireform-parquet:wireform-parquet-reverse-probe", "--"]
+    result = subprocess.run(
+        [*command, str(out), "--arrow-output", str(decoded)],
+        cwd=ROOT.parent, capture_output=True, text=True
+    )
+    print(result.stdout)
+    if result.returncode != 0:
+        print("STDERR:", result.stderr)
+    failures = 0
+    for source in all_files:
+        output = decoded / (source.name + ".arrows")
+        try:
+            with ipc.open_stream(output) as reader:
+                actual = reader.read_all()
+            expected = pq.read_table(source)
+            # Parquet STRING/BYTE_ARRAY does not encode Arrow offset width;
+            # Polars' Arrow schema metadata can restore large_string, while
+            # the native bridge legitimately constructs 32-bit offsets.
+            expected = expected.cast(pa.schema([
+                pa.field(field.name,
+                         pa.string() if pa.types.is_large_string(field.type)
+                         else pa.binary() if pa.types.is_large_binary(field.type)
+                         else field.type,
+                         nullable=field.nullable)
+                for field in expected.schema
+            ]))
+            if not actual.equals(expected):
+                raise AssertionError(
+                    f"decoded values differ\nexpected: {expected}\nactual: {actual}"
+                )
+            print(f"  VALUES OK {source.name}")
+        except Exception as exc:
+            failures += 1
+            print(f"  VALUES FAIL {source.name}: {exc}")
+    return 1 if failures or result.returncode else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/parquet_schema_interop.py b/scripts/parquet_schema_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_schema_interop.py
@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Schema-shape boundaries using independent Apache Thrift serialization.
+
+C++ writes the valid scalar/struct controls. Malformed cases follow the
+published SchemaElement requirements; permissive reference readers need not
+reject them for the native checked boundary to reject them correctly.
+"""
+import argparse
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+import pyarrow as pa
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from parquet_lzo_interop import Node,encode
+from parquet_metadata_interop import parse
+
+
+def write(path,parsed):
+    raw=encode(parsed.footer)
+    path.write_bytes(parsed.prefix+raw+struct.pack("<I",len(raw))+b"PAR1")
+
+
+def probe(reader,path,succeeds,root):
+    directory=root/path.stem;directory.mkdir();(directory/path.name).symlink_to(path)
+    result=subprocess.run([str(reader),str(directory)],capture_output=True,text=True,timeout=120)
+    assert (result.returncode==0 if succeeds else result.returncode>0 and "FAIL" in result.stdout),(path,result.stdout,result.stderr)
+
+
+def main():
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reader",type=Path,required=True)
+    parser.add_argument("--output",type=Path,required=True)
+    args=parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix="schema-boundary-") as directory:
+        root=Path(directory)
+        scalar=root/"scalar.parquet";nested=root/"nested.parquet"
+        pq.write_table(pa.table({"x":pa.array([],pa.int32())}),scalar)
+        pq.write_table(pa.table({"g":pa.array([],pa.struct([("x",pa.int32())]))}),nested)
+        controls=2;rejected=0
+        for path in (scalar,nested):probe(args.reader,path,True,root)
+        for index,marker in enumerate((None,0,1,2)):
+            parsed=parse(nested)
+            if marker is None:parsed.footer.value[2].value[0].value.pop(3,None)
+            else:parsed.footer.value[2].value[0].value[3]=Node(TType.I32,marker)
+            path=root/f"root-marker-{index}.parquet";write(path,parsed);probe(args.reader,path,True,root);controls+=1
+        cases=[
+            (scalar,"missing-leaf-repetition",1,3,None),
+            (nested,"missing-group-repetition",1,3,None),
+            (nested,"missing-nested-repetition",2,3,None),
+            (scalar,"primitive-count-zero",1,5,0),
+            (scalar,"primitive-count-positive",1,5,1),
+            (scalar,"primitive-count-negative",1,5,-1),
+            (nested,"missing-group-count",1,5,None),
+            (scalar,"negative-root-count",0,5,-1),
+            (scalar,"oversized-root-count",0,5,2**31-1),
+            (nested,"negative-group-count",1,5,-1),
+            (scalar,"unknown-repetition-enum",1,3,99),
+            (scalar,"unknown-physical-enum",1,1,99),
+        ]
+        for seed,name,element,key,value in cases:
+            parsed=parse(seed);fields=parsed.footer.value[2].value[element].value
+            if value is None:fields.pop(key,None)
+            else:fields[key]=Node(TType.I32,value)
+            path=root/(name+".parquet");write(path,parsed);probe(args.reader,path,False,root);rejected+=1
+        # A legal empty schema needs an explicit root child count of zero.
+        # Remove that field only after verifying the canonical native control.
+        parsed=parse(scalar);parsed.prefix=b"PAR1";fields=parsed.footer.value
+        fields[2].value=fields[2].value[:1];fields[2].value[0].value[5]=Node(TType.I32,0)
+        fields[3]=Node(TType.I64,0);fields[4].value=[];fields.pop(5,None);fields.pop(7,None)
+        control=root/"empty-root-control.parquet";write(control,parsed);probe(args.reader,control,True,root);controls+=1
+        fields[2].value[0].value.pop(5)
+        bad=root/"missing-empty-root-count.parquet";write(bad,parsed);probe(args.reader,bad,False,root);rejected+=1
+        report={"pyarrow":pa.__version__,"controls":controls,"malformedRejected":rejected,"failures":0,"skips":0}
+        args.output.write_text(json.dumps(report,indent=2)+"\n");print(json.dumps(report,indent=2))
+
+if __name__=="__main__":main()
diff --git a/scripts/parquet_selection_fixtures.py b/scripts/parquet_selection_fixtures.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_selection_fixtures.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Generate shared PyArrow input and independent expected page-selection values.
+
+Both benchmark harnesses parse the footer and page indexes on every iteration,
+retain whole pages whose maximum meets the predicate, and materialize the same
+rows. File IO and this fixture generation are outside the timed region.
+"""
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+from parquet_selection_interop import Dataset, index_info
+
+ROWS = 131072
+
+
+@dataclass(frozen=True)
+class Plan:
+    name: str
+    text: bool
+    nullable: bool
+    dictionary: bool
+    codec: str
+    rows: int = ROWS
+    width: int = 0
+    batch: int = 1024
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('directory', type=Path)
+    parser.add_argument('--extended', action='store_true', help='also measure 4 KiB strings across many pages')
+    args = parser.parse_args()
+    root = args.directory
+    root.mkdir(parents=True, exist_ok=True)
+    cases = [
+        Plan('int-required-plain', False, False, False, 'NONE'),
+        Plan('int-required-dictionary', False, False, True, 'ZSTD'),
+        Plan('int-nullable-plain', False, True, False, 'NONE'),
+        Plan('int-nullable-dictionary', False, True, True, 'ZSTD'),
+        Plan('text-required-plain', True, False, False, 'SNAPPY'),
+        Plan('text-nullable-dictionary', True, True, True, 'ZSTD'),
+    ]
+    if args.extended:
+        for nullable in (False, True):
+            for dictionary in (False, True):
+                name = f'text-{"nullable" if nullable else "required"}-{"dictionary" if dictionary else "plain"}-4k'
+                cases.append(Plan(name, True, nullable, dictionary, 'ZSTD' if dictionary else 'NONE', rows=4096, width=4096, batch=16))
+    plans = []
+    for plan in cases:
+        def value_at(i):
+            if plan.width:
+                prefix = f'long_{i//32:05d}_'
+                return prefix + 'x' * (plan.width - len(prefix))
+            if plan.text:
+                return f'name_{i//32:05d}'
+            return i//32 if plan.dictionary else i
+
+        values = [None if plan.nullable and i % 17 == 0 else value_at(i) for i in range(plan.rows)]
+        typ = pa.string() if plan.text else pa.int64()
+        table = pa.Table.from_arrays([pa.array(values, typ)], schema=pa.schema([pa.field('x', typ, plan.nullable)]))
+        path = root / f'{plan.name}.parquet'
+        pq.write_table(table, path, compression=plan.codec, data_page_version='2.0',
+                       use_dictionary=plan.dictionary, dictionary_pagesize_limit=2**20,
+                       # Dictionary indices are much smaller than the wide
+                       # strings; use a smaller target to retain several pages.
+                       data_page_size=128 if plan.width and plan.dictionary else 4096,
+                       write_batch_size=plan.batch, row_group_size=plan.rows,
+                       write_page_index=True, write_page_checksum=False)
+        pivot = value_at(plan.rows//2)
+        decode = (lambda raw: raw.decode()) if plan.text else (lambda raw: int.from_bytes(raw, 'little', signed=True))
+        dataset = Dataset(plan.name, typ, values, str(pivot), pivot, decode)
+        _, _, locations, keep, encodings = index_info(path, dataset)
+        assert any(keep) and not all(keep) and len(locations) > 1
+        if plan.dictionary:
+            assert any(encoding in (2, 8) for encoding in encodings)
+        parts = []
+        for index, ((_, _, start), retained) in enumerate(zip(locations, keep)):
+            if retained:
+                end = locations[index+1][2] if index+1 < len(locations) else plan.rows
+                parts.append(table.slice(start, end-start))
+        expected = pa.concat_tables(parts)
+        pq.write_table(expected, root / f'{plan.name}-expected.parquet', compression='NONE', use_dictionary=False)
+        plans.append(f'{plan.name} {"text" if plan.text else "int"} {pivot}')
+        print(f'{plan.name}: {sum(keep)}/{len(keep)} pages, {expected.num_rows}/{plan.rows} rows')
+    (root / 'selection-plan.txt').write_text('\n'.join(plans)+'\n')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_selection_interop.py b/scripts/parquet_selection_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_selection_interop.py
@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""Compare indexed reads with independently decoded PyArrow page ranges.
+
+Apache Thrift reads the offset/column indexes and page encoding tags. Expected
+values come from the original Arrow arrays, not from Wireform's full reader.
+"""
+
+import argparse
+from dataclasses import dataclass
+from decimal import Decimal, localcontext
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from parquet_aggregate_interop import footer, groups, read_node, TCompactProtocol, TMemoryBuffer, TType
+
+ROWS = 4096
+
+
+@dataclass
+class Dataset:
+    name: str
+    typ: object
+    values: list
+    literal: str
+    pivot: object
+    decode: object
+
+
+def datasets():
+    signed = lambda raw: int.from_bytes(raw, 'little', signed=True)
+    unsigned = lambda raw: int.from_bytes(raw, 'little')
+    decimal = lambda raw: int.from_bytes(raw, 'big', signed=True)
+    with localcontext() as context:
+        context.prec = 90
+        return [
+            Dataset('int32', pa.int32(), list(range(-2048, 2048)), '0', 0, signed),
+            Dataset('int64', pa.int64(), [2**40+i for i in range(ROWS)], str(2**40+2048), 2**40+2048, signed),
+            Dataset('uint32', pa.uint32(), [2**31+i for i in range(ROWS)], str(2**31+2048), 2**31+2048, unsigned),
+            Dataset('uint64', pa.uint64(), [2**63+i for i in range(ROWS)], str(2**63+2048), 2**63+2048, unsigned),
+            Dataset('int8', pa.int8(), [i//32-64 for i in range(ROWS)], '0', 0, signed),
+            Dataset('float32', pa.float32(), [(i-2048)*0.5 for i in range(ROWS)], '0', 0, lambda raw: struct.unpack('<f', raw)[0]),
+            Dataset('float64', pa.float64(), [(i-2048)*0.5 for i in range(ROWS)], '0', 0, lambda raw: struct.unpack('<d', raw)[0]),
+            Dataset('float16', pa.float16(), list(range(-2048, 2048)), '0', 0, lambda raw: struct.unpack('<e', raw)[0]),
+            Dataset('bool', pa.bool_(), [i >= 2048 for i in range(ROWS)], 'true', True, lambda raw: bool(raw[0])),
+            Dataset('utf8', pa.string(), [f'item-{i//32:03d}-é' for i in range(ROWS)], 'item-064-é', 'item-064-é', lambda raw: raw.decode()),
+            Dataset('binary', pa.binary(), [(i//32).to_bytes(2, 'big')+b'\xff\x00' for i in range(ROWS)], '0040ff00', b'\x00\x40\xff\x00', lambda raw: raw),
+            Dataset('fixed', pa.binary(4), [i.to_bytes(4, 'big') for i in range(ROWS)], '00000800', b'\x00\x00\x08\x00', lambda raw: raw),
+            Dataset('decimal9', pa.decimal128(9, 2), [Decimal(i-2048).scaleb(-2) for i in range(ROWS)], '0', 0, decimal),
+            Dataset('decimal30', pa.decimal128(30, 7), [Decimal(10**25+i).scaleb(-7) for i in range(ROWS)], str(Decimal(10**25+2048).scaleb(-7)), 10**25+2048, decimal),
+            Dataset('decimal50', pa.decimal256(50, 20), [Decimal(10**45+i).scaleb(-20) for i in range(ROWS)], str(Decimal(10**45+2048).scaleb(-20)), 10**45+2048, decimal),
+            Dataset('date32', pa.date32(), list(range(-2048, 2048)), '0', 0, signed),
+            Dataset('time64', pa.time64('us'), list(range(ROWS)), '2048', 2048, signed),
+            Dataset('timestamp', pa.timestamp('ns'), [1_700_000_000_000_000_000+i for i in range(ROWS)], '1700000000000002048', 1_700_000_000_000_002_048, signed),
+        ]
+
+
+def struct_at(raw, offset):
+    return read_node(TCompactProtocol(TMemoryBuffer(raw[offset:])), TType.STRUCT)[1]
+
+
+def index_info(path, dataset):
+    raw = path.read_bytes()
+    metadata = footer(path)[1]
+    chunk = groups(metadata)[0][1][1][1][1][0][1]
+    column = chunk[3][1]
+    offsets = struct_at(raw, chunk[4][1])[1][1][1]
+    bounds = struct_at(raw, chunk[6][1])
+    nulls = [entry[1] for entry in bounds[1][1][1]]
+    maxima = [entry[1] for entry in bounds[3][1][1]]
+    locations = [(entry[1][1][1], entry[1][2][1], entry[1][3][1]) for entry in offsets]
+    keep = [not null and dataset.decode(high) >= dataset.pivot for null, high in zip(nulls, maxima)]
+    assert len(locations) == len(keep) and len(locations) > 1, path.name
+    encodings = []
+    for retained, (offset, _, _) in zip(keep, locations):
+        if retained:
+            header = struct_at(raw, offset)
+            encodings.append(header[5][1][2][1] if header[1][1] == 0 else header[8][1][4][1])
+    return raw, column, locations, keep, encodings
+
+
+def check(reader, path, dataset, array, output):
+    raw, column, locations, keep, encodings = index_info(path, dataset)
+    parts = []
+    for index, (retained, (_, _, start)) in enumerate(zip(keep, locations)):
+        if retained:
+            end = locations[index+1][2] if index+1 < len(locations) else len(array)
+            parts.append(array.slice(start, end-start))
+    expected_array = pa.concat_arrays(parts) if parts else array.slice(0, 0)
+    expected = pa.Table.from_arrays([expected_array], schema=pa.schema([pa.field('x', array.type, nullable=True)]))
+    result = subprocess.run([str(reader), '--prune', str(path), dataset.literal, str(output)],
+                            capture_output=True, text=True)
+    assert result.returncode == 0, (path.name, result.stdout, result.stderr)
+    assert result.stdout.strip() == f'pages=Just ({sum(keep)},{len(keep)})', (path.name, result.stdout)
+    with ipc.open_stream(output) as stream:
+        actual = stream.read_all()
+    assert actual.schema.field(0).type == expected.schema.field(0).type, (path.name, actual.schema, expected.schema)
+    assert actual.equals(expected), (path.name, actual.to_pydict(), expected.to_pydict())
+    return raw, column, locations, keep, encodings
+
+
+def check_sparse(reader, root):
+    """Null rows must not duplicate the first long string or binary value.
+
+    The source holds only a few MiB. Gathering value0 for every null would
+    manufacture GiB of output and incorrectly reject a valid input file.
+    """
+    nested = root / 'sparse-nested'
+    nested.mkdir()
+    expected_nested = {}
+    for name, typ, large, low, high, literal, decode in [
+        ('utf8', pa.string(), 'm' * (1024 * 1024), 'a', 'z', 'a', lambda raw: raw.decode()),
+        ('binary', pa.binary(), b'm' * (1024 * 1024), b'a', b'z', '61', lambda raw: raw),
+    ]:
+        block = [large] + [None] * 4096 + [low, high]
+        array = pa.array(block + block, typ)
+        table = pa.table({'x': array})
+        path = root / f'sparse-{name}.parquet'
+        pq.write_table(table, path, use_dictionary=False, compression='NONE', data_page_version='2.0',
+                       write_page_index=True, data_page_size=4096, write_batch_size=len(block),
+                       row_group_size=len(array))
+        dataset = Dataset(name, typ, [], literal, low, decode)
+        check(reader, path, dataset, array, root / 'sparse.arrows')
+        # Repeated nullable elements exercise the generic nested assembler,
+        # whose output rows are selected from definition/repetition events.
+        list_type = pa.list_(pa.field('element', typ, nullable=True))
+        list_table = pa.table({'x': pa.array([block], list_type)})
+        nested_path = nested / f'{name}.parquet'
+        pq.write_table(list_table, nested_path, use_dictionary=False, compression='NONE',
+                       data_page_version='2.0', data_page_size=2 * 1024 * 1024,
+                       write_batch_size=len(block), row_group_size=1)
+        expected_nested[nested_path.name] = list_table
+        print('PASS sparse nullable', name, 'indexed selection', flush=True)
+    output = root / 'sparse-nested-output'
+    result = subprocess.run([str(reader), str(nested), '--arrow-output', str(output)],
+                            capture_output=True, text=True)
+    assert result.returncode == 0, result.stdout + result.stderr
+    for name, expected in expected_nested.items():
+        with ipc.open_stream(output / (name + '.arrows')) as stream:
+            actual = stream.read_all()
+        assert actual.equals(expected), (name, actual.schema, expected.schema)
+        print('PASS sparse nullable nested', name, flush=True)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--reader', type=Path, required=True)
+    args = parser.parse_args()
+    reader = args.reader.resolve()
+    checked = dictionary_selections = 0
+    poison_sources = {}
+    with tempfile.TemporaryDirectory(prefix='wireform-parquet-selection-') as directory:
+        root = Path(directory)
+        output = root / 'selected.arrows'
+        for dataset in datasets():
+            for nullable in (False, True):
+                values = [None if nullable and (i < 64 or i % 17 == 0) else value for i, value in enumerate(dataset.values)]
+                array = pa.array(values, dataset.typ)
+                table = pa.Table.from_arrays([array], schema=pa.schema([pa.field('x', dataset.typ, nullable=nullable)]))
+                for version in ('1.0', '2.0'):
+                    for codec in ('NONE', 'SNAPPY', 'ZSTD'):
+                        for mode in ('plain', 'dictionary', 'fallback'):
+                            name = f'{dataset.name}-{nullable}-{version}-{codec}-{mode}'
+                            path = root / f'{name}.parquet'
+                            pq.write_table(table, path, data_page_version=version, compression=codec,
+                                           use_dictionary=mode != 'plain', dictionary_pagesize_limit=512 if mode == 'fallback' else 2**20,
+                                           data_page_size=128, write_batch_size=64, row_group_size=ROWS,
+                                           write_page_index=True, write_page_checksum=True)
+                            info = check(reader, path, dataset, array, output)
+                            checked += 1
+                            dictionary_selections += any(encoding in (2, 8) for encoding in info[-1])
+                            if dataset.name == 'int32' and not nullable and version == '2.0' and codec == 'NONE':
+                                poison_sources[mode] = path, dataset, array, info
+                            if checked % 36 == 0:
+                                print('PASS', dataset.name, 'nullable='+str(nullable), flush=True)
+        assert dictionary_selections > 0
+        # Poisoning a skipped page proves the public path really skips it.
+        source, dataset, array, info = poison_sources['dictionary']
+        raw, column, locations, keep, _ = info
+        skipped = next(location for location, retained in zip(locations, keep) if not retained)
+        poisoned = bytearray(raw)
+        poisoned[skipped[0]:skipped[0]+skipped[1]] = b'\xff' * skipped[1]
+        target = root / 'poisoned-skipped-page.parquet'
+        target.write_bytes(poisoned)
+        # Use the unchanged indexes; parsing the poisoned header is intentionally forbidden.
+        result = subprocess.run([str(reader), '--prune', str(target), dataset.literal, str(output)], capture_output=True, text=True)
+        assert result.returncode == 0, result.stdout + result.stderr
+        with ipc.open_stream(output) as stream:
+            poisoned_result = stream.read_all()
+        check(reader, source, dataset, array, output)
+        with ipc.open_stream(output) as stream:
+            assert poisoned_result.equals(stream.read_all())
+        # Dictionary fallback pages can retain only PLAIN pages. Their unused
+        # dictionary must not be decoded or checksummed.
+        source, dataset, array, info = poison_sources['fallback']
+        raw, column, _, keep, encodings = info
+        assert any(keep) and all(encoding not in (2, 8) for encoding in encodings)
+        dictionary_start, data_start = column[11][1], column[9][1]
+        poisoned = bytearray(raw)
+        poisoned[dictionary_start:data_start] = b'\xff' * (data_start-dictionary_start)
+        target = root / 'poisoned-unused-dictionary.parquet'
+        target.write_bytes(poisoned)
+        result = subprocess.run([str(reader), '--prune', str(target), dataset.literal, str(output)], capture_output=True, text=True)
+        assert result.returncode == 0, result.stdout + result.stderr
+        with ipc.open_stream(output) as stream:
+            poisoned_result = stream.read_all()
+        check(reader, source, dataset, array, output)
+        with ipc.open_stream(output) as stream:
+            assert poisoned_result.equals(stream.read_all())
+        check_sparse(reader, root)
+    print(f'{checked} indexed files matched independently selected Arrow rows; {dictionary_selections} selections required dictionaries; skipped-page and unused-dictionary poison checks and four sparse byte/text regressions passed')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_statistics_interop.py b/scripts/parquet_statistics_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_statistics_interop.py
@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Verify integer, floating and binary statistics with Apache Thrift and PyArrow (pip install thrift pyarrow).
+
+The generic Thrift reader deliberately uses Apache's compact codec and the
+published field IDs, independently of Wireform's metadata reader/field names.
+"""
+
+import argparse
+import math
+import struct
+import subprocess
+import tempfile
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from thrift.protocol.TCompactProtocol import TCompactProtocol
+from thrift.transport.TTransport import TMemoryBuffer
+
+
+def read_value(protocol, kind):
+    scalar = {
+        TType.BOOL: protocol.readBool, TType.BYTE: protocol.readByte,
+        TType.I16: protocol.readI16, TType.I32: protocol.readI32,
+        TType.I64: protocol.readI64, TType.DOUBLE: protocol.readDouble,
+        TType.STRING: protocol.readBinary,
+    }
+    if kind in scalar:
+        return scalar[kind]()
+    if kind == TType.STRUCT:
+        protocol.readStructBegin()
+        fields = {}
+        while True:
+            _, field_type, field_id = protocol.readFieldBegin()
+            if field_type == TType.STOP:
+                break
+            fields[field_id] = read_value(protocol, field_type)
+            protocol.readFieldEnd()
+        protocol.readStructEnd()
+        return fields
+    if kind in (TType.LIST, TType.SET):
+        begin = protocol.readListBegin if kind == TType.LIST else protocol.readSetBegin
+        end = protocol.readListEnd if kind == TType.LIST else protocol.readSetEnd
+        item_type, length = begin()
+        result = []
+        for _ in range(length):
+            result.append(read_value(protocol, item_type))
+        end()
+        return result
+    if kind == TType.MAP:
+        key_type, value_type, length = protocol.readMapBegin()
+        result = {}
+        for _ in range(length):
+            key = read_value(protocol, key_type)
+            result[key] = read_value(protocol, value_type)
+        protocol.readMapEnd()
+        return result
+    raise ValueError(f"unsupported Thrift value kind {kind}")
+
+
+def verify_other_statistics(root):
+    initial = [b"name_0", b"name_7", b"name_19"] * 14
+    initial = initial[:40]
+    short = [b"", b"\0", b"\0\0", b"\1", b"\1\0", b"\xff", b"\xff\0", b"abcdefgh"]
+    cases = {
+        "int32-empty.parquet": ([], pa.int32()),
+        "int32-bounds.parquet": ([2**31-1, -2**31, 0, -1, 1, 2**31-1], pa.int32()),
+        "int32-descending.parquet": ([19, 7, 0, -5, -23], pa.int32()),
+        "int64-empty.parquet": ([], pa.int64()),
+        "int64-bounds.parquet": ([2**63-1, -2**63, 0, -1, 1, 2**54+1, 2**63-1], pa.int64()),
+        "int64-descending.parquet": ([19, 7, 0, -5, -23], pa.int64()),
+        "binary-boundaries.parquet": ([b"\x80", b"\x7f", b"", b"\xff"], pa.binary()),
+        "utf8-boundaries.parquet": (["é", "z", "", "🙂"], pa.string()),
+        "binary-empty.parquet": ([], pa.binary()),
+        "binary-short-prefix.parquet": (short, pa.binary()),
+        "binary-zero-prefix.parquet": ([b"\0" * n for n in range(17)], pa.binary()),
+        "binary-late-min.parquet": (initial + [b"\0" * 9, b"m", b"z"], pa.binary()),
+        "binary-late-max.parquet": (initial + [b"\xff" * 9, b"a", b"m"], pa.binary()),
+        "binary-long-first.parquet": ([b"a" * 32 + bytes([key]) for key in (255, 0, 128, 1, 127)], pa.binary()),
+        "binary-short-slice.parquet": (short, pa.binary()),
+    }
+    for name, (values, arrow_type) in cases.items():
+        path = root / name
+        raw = path.read_bytes()
+        length = int.from_bytes(raw[-8:-4], "little")
+        metadata = read_value(TCompactProtocol(TMemoryBuffer(raw[-8-length:-8])), TType.STRUCT)
+        stats = metadata[4][0][1][0][3][12]
+        assert stats[3] == 0 and 9 not in stats, (name, "counts", stats)
+        assert metadata[7] == [{1: {}}], (name, "TYPE_ORDER")
+        legacy = pa.types.is_integer(arrow_type)
+        if not values:
+            assert all(field not in stats for field in (1, 2, 5, 6)), (name, stats)
+        else:
+            low, high = min(values), max(values)
+            if legacy:
+                code = "<i" if arrow_type == pa.int32() else "<q"
+                expected_low, expected_high = struct.pack(code, low), struct.pack(code, high)
+                assert stats[2] == expected_low and stats[1] == expected_high, (name, "legacy", stats)
+            else:
+                expected_low = low.encode("utf-8") if isinstance(low, str) else low
+                expected_high = high.encode("utf-8") if isinstance(high, str) else high
+                assert 1 not in stats and 2 not in stats, (name, "binary legacy bounds", stats)
+            assert stats[6] == expected_low and stats[5] == expected_high, (name, "modern", stats)
+            assert stats[7] is True and stats[8] is True, (name, "exact", stats)
+        file = pq.ParquetFile(path)
+        actual = file.read()["x"]
+        assert actual.type == arrow_type and actual.to_pylist() == values, (name, "values")
+        reference = file.metadata.row_group(0).column(0).statistics
+        assert reference.has_min_max == bool(values), (name, "reference bounds")
+        if values:
+            assert (reference.min, reference.max) == (min(values), max(values)), (name, reference)
+        print(f"PASS {name}")
+    return set(cases)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--probe", type=Path, required=True)
+    args = parser.parse_args()
+    cases = {
+        "mixed": ([math.nan, -2, 3, math.nan], 2, (-2, 3)),
+        "nan": ([math.nan, math.nan], 2, None),
+        "positive-zero": ([0.0], 0, (-0.0, 0.0)),
+        "negative-zero": ([-0.0], 0, (-0.0, 0.0)),
+        "infinities": ([-math.inf, math.inf, math.nan], 1, (-math.inf, math.inf)),
+        "empty": ([], 0, None),
+    }
+    with tempfile.TemporaryDirectory(prefix="wireform-parquet-statistics-") as tmp:
+        root = Path(tmp)
+        subprocess.run([str(args.probe.resolve()), "--statistics", str(root)], check=True)
+        index = read_value(TCompactProtocol(TMemoryBuffer((root / "statistics-index.bin").read_bytes())), TType.STRUCT)
+        assert index[8] == [1, 0, 0] and index[5] == [0, 0, 4], index
+        checked_names = set()
+        for precision, arrow_type, binary_type in [("float", pa.float32(), "<f"), ("double", pa.float64(), "<d")]:
+            for name, (expected_values, nan_count, bounds) in cases.items():
+                path = root / f"{precision}-{name}.parquet"
+                raw = path.read_bytes()
+                footer_length = int.from_bytes(raw[-8:-4], "little")
+                metadata = read_value(TCompactProtocol(TMemoryBuffer(raw[-8-footer_length:-8])), TType.STRUCT)
+                # FileMetaData.row_groups[0].columns[0].meta_data.statistics
+                stats = metadata[4][0][1][0][3][12]
+                assert stats[9] == nan_count, (path.name, "nan_count", stats)
+                assert stats[3] == 0, (path.name, "null_count", stats)
+                assert metadata[7] == [{1: {}}], (path.name, "TYPE_ORDER")
+                if bounds is not None:
+                    assert stats[7] is True and stats[8] is True, (path.name, "exact bounds")
+                if bounds is None:
+                    assert all(field not in stats for field in (1, 2, 5, 6)), (path.name, stats)
+                else:
+                    low, high = bounds
+                    for field, value in [(2, low), (6, low), (1, high), (5, high)]:
+                        assert stats[field] == struct.pack(binary_type, value), (path.name, field, stats)
+                file = pq.ParquetFile(path)
+                column = file.metadata.row_group(0).column(0)
+                assert column.has_offset_index, path.name
+                # TYPE_ORDER forbids a column index when a page has only NaNs.
+                assert column.has_column_index == (name != "nan"), path.name
+                actual = file.read()["x"]
+                assert actual.type == arrow_type and len(actual) == len(expected_values), path.name
+                for value, expected in zip(actual.to_pylist(), expected_values):
+                    if math.isnan(expected):
+                        assert math.isnan(value), path.name
+                    else:
+                        assert value == expected and math.copysign(1, value) == math.copysign(1, expected), path.name
+                reference_stats = file.metadata.row_group(0).column(0).statistics
+                assert reference_stats.has_min_max == (bounds is not None), path.name
+                if bounds is not None:
+                    assert (reference_stats.min, reference_stats.max) == bounds, path.name
+                checked_names.add(path.name)
+                print(f"PASS {path.name}")
+        checked_names.update(verify_other_statistics(root))
+        actual_names = {path.name for path in root.glob("*.parquet")}
+        assert actual_names == checked_names, ("unverified or missing statistics fixtures", actual_names ^ checked_names)
+        print(f"{len(checked_names)} statistics fixtures verified with Apache Thrift and PyArrow {pa.__version__}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_timestamp_interop.py b/scripts/parquet_timestamp_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_timestamp_interop.py
@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""Lossless timestamp interop with independent Apache Thrift and PyArrow.
+
+PyArrow cannot interpret modern signed96 TIMESTAMP and its ordinary INT96
+projection can overflow. The physical oracle changes only schema/type metadata
+in a temporary copy to FixedSizeBinary(12), then asks unmodified C++ to decode
+the original pages, dictionaries, compression and levels. The body is asserted
+byte-identical. Python integers independently verify full-width semantics.
+"""
+import argparse
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from parquet_lzo_interop import Node, encode
+from parquet_metadata_interop import parse
+
+NAME = b"ARROW:extension:name"
+PARAMETERS = b"ARROW:extension:metadata"
+SIGNED = b"wireform.parquet.timestamp96"
+JULIAN = b"wireform.parquet.int96"
+UNITS = {"millis": (1, "ms"), "micros": (2, "us"), "nanos": (3, "ns")}
+
+
+def timestamp_leaves(footer):
+    leaves = [node for node in footer.value[2].value if 1 in node.value]
+    result = []
+    for ordinal, node in enumerate(leaves):
+        physical = node.value[1].value
+        logical = node.value.get(10)
+        timestamp = logical.value.get(8) if logical else None
+        if physical == 3:
+            result.append((ordinal, node, "julian", None, None))
+        elif physical == 7 and node.value.get(2) and node.value[2].value == 12 and timestamp:
+            parameters = timestamp.value
+            unit = next(iter(parameters[2].value))
+            result.append((ordinal, node, "signed", bool(parameters[1].value), {1:"millis", 2:"micros", 3:"nanos"}[unit]))
+    return result
+
+
+def write_footer(path, prefix, footer):
+    encoded = encode(footer)
+    path.write_bytes(prefix + encoded + struct.pack("<I", len(encoded)) + b"PAR1")
+
+
+def physical_timestamp_copy(source, target):
+    """Return changed leaf descriptors, or [] without writing for ordinary files."""
+    parsed = parse(source)
+    changed = timestamp_leaves(parsed.footer)
+    if not changed:
+        return []
+    legacy = set()
+    for ordinal, node, kind, _, _ in changed:
+        node.value[1] = Node(TType.I32, 7)
+        node.value[2] = Node(TType.I32, 12)
+        node.value.pop(10, None)
+        node.value.pop(6, None)
+        if kind == "julian":
+            legacy.add(ordinal)
+    for group in parsed.footer.value[4].value:
+        for ordinal, chunk in enumerate(group.value[1].value):
+            if ordinal in legacy:
+                chunk.value[3].value[1] = Node(TType.I32, 7)
+    # Stored Arrow schema may otherwise force the original timestamp type.
+    if 5 in parsed.footer.value:
+        parsed.footer.value[5].value[:] = [entry for entry in parsed.footer.value[5].value if entry.value[1].value != b"ARROW:schema"]
+    parsed.footer.value.pop(7, None)
+    write_footer(target, parsed.prefix, parsed.footer)
+    assert parse(target).prefix == parsed.prefix
+    return [(ordinal, kind, adjusted, unit) for ordinal, _, kind, adjusted, unit in changed]
+
+
+def annotate(path, encoding, adjusted=False, unit="nanos"):
+    parsed = parse(path)
+    leaves = [node for node in parsed.footer.value[2].value if 1 in node.value]
+    assert len(leaves) == 1 and leaves[0].value[1].value == 7 and leaves[0].value[2].value == 12
+    leaf = leaves[0]
+    if encoding == "signed":
+        leaf.value[10] = Node(TType.STRUCT, {8: Node(TType.STRUCT, {
+            1: Node(TType.BOOL, adjusted),
+            2: Node(TType.STRUCT, {UNITS[unit][0]: Node(TType.STRUCT, {})})})})
+    else:
+        leaf.value[1] = Node(TType.I32, 3)
+        leaf.value.pop(2, None)
+        for group in parsed.footer.value[4].value:
+            group.value[1].value[0].value[3].value[1] = Node(TType.I32, 3)
+    parsed.footer.value.pop(7, None)
+    write_footer(path, parsed.prefix, parsed.footer)
+
+
+def extension_field(name, encoding, adjusted=False, unit="nanos", nullable=True):
+    metadata = {NAME: SIGNED if encoding == "signed" else JULIAN,
+                PARAMETERS: (unit + (":utc" if adjusted else ":local")).encode() if encoding == "signed" else b""}
+    return pa.field(name, pa.binary(12), nullable=nullable, metadata=metadata)
+
+
+def shape_table(values, shape, field):
+    if shape == "flat":
+        field = field.with_name("v")
+        data = values
+    elif shape == "list":
+        field = pa.field("v", pa.list_(field.with_name("element")))
+        data = [values[:2], None, [], values[2:], [None]]
+    else:
+        field = pa.field("v", pa.struct([field.with_name("t")]))
+        data = [{"t": value} for value in values] + [None]
+    return pa.Table.from_arrays([pa.array(data, type=field.type)], schema=pa.schema([field]))
+
+
+def leaf_fields(field):
+    if pa.types.is_struct(field.type):
+        for child in field.type:
+            yield from leaf_fields(child)
+    elif pa.types.is_list(field.type) or pa.types.is_large_list(field.type):
+        yield from leaf_fields(field.type.value_field)
+    else:
+        yield field
+
+
+def verify_extension(table, descriptors):
+    fields = [leaf for field in table.schema for leaf in leaf_fields(field)]
+    for ordinal, kind, adjusted, unit in descriptors:
+        wanted = extension_field("", kind, adjusted, unit)
+        actual = fields[ordinal]
+        assert actual.type == pa.binary(12)
+        assert actual.metadata[NAME] == wanted.metadata[NAME]
+        assert actual.metadata[PARAMETERS] == wanted.metadata[PARAMETERS]
+
+
+def checked(command):
+    process = subprocess.run(list(map(str, command)), capture_output=True, text=True)
+    assert process.returncode == 0, (command, process.stdout, process.stderr)
+
+
+def read_native(reader, path, output):
+    directory = output / "source"
+    directory.mkdir(parents=True)
+    (directory / path.name).symlink_to(path.resolve())
+    dest = output / "decoded"
+    checked([reader, directory, "--arrow-output", dest])
+    with ipc.open_stream(dest / (path.name + ".arrows")) as stream:
+        return stream.read_all()
+
+
+def verify_file(reader, path, root):
+    root.mkdir(parents=True)
+    physical = root / "physical.parquet"
+    descriptors = physical_timestamp_copy(path, physical)
+    assert descriptors
+    expected = pq.read_table(physical, page_checksum_verification=True)
+    expected.validate(full=True)
+    actual = read_native(reader, path, root / "native")
+    actual.validate(full=True)
+    verify_extension(actual, descriptors)
+    assert actual.equals(expected, check_metadata=False), (path, actual, expected)
+    return actual, descriptors
+
+
+def project(reader, path, target, root, expected=None):
+    schema_path, result = root / "target.arrows", root / "projected.arrows"
+    with ipc.new_stream(schema_path, target) as stream:
+        pass
+    process = subprocess.run([str(reader), "--project", str(path), str(schema_path), str(result)], capture_output=True, text=True)
+    if expected is None:
+        assert process.returncode != 0 and not result.exists(), (path, process.stdout, process.stderr)
+        return
+    assert process.returncode == 0, (path, process.stdout, process.stderr)
+    with ipc.open_stream(result) as stream:
+        actual = stream.read_all()
+    assert actual.column(0).cast(pa.int64()).to_pylist() == expected
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reader", type=Path, required=True)
+    parser.add_argument("--writer", type=Path, required=True)
+    parser.add_argument("--native-fixtures", type=Path, required=True)
+    parser.add_argument("--corpus", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    wide_counts = [-(1<<95), -(1<<63)-1, -(1<<63), -1, 0, (1<<63)-1, 1<<63, (1<<95)-1, None]
+    narrow_counts = [-(1<<63), -1, 0, (1<<63)-1, None]
+    legacy = [struct.pack("<Qi", nanos, day) for day, nanos in [(-(1<<31),0), (-1,86399999999999), (2440588,0), ((1<<31)-1,86399999999999)]] + [None, struct.pack("<qi", -(1<<63), 2440588), struct.pack("<qi", (1<<63)-1, 2440588)]
+    cases = []
+    for unit in UNITS:
+        for adjusted in (False, True):
+            for profile in ("plain-v1", "dictionary-v2"):
+                for shape in ("flat", "list", "struct"):
+                    cases.append((f"{unit}-{adjusted}-{profile}-{shape}", "signed", unit, adjusted, profile, shape, wide_counts, False))
+                cases.append((f"{unit}-{adjusted}-{profile}-narrow", "signed", unit, adjusted, profile, "flat", narrow_counts, True))
+    for profile in ("plain-v1", "dictionary-v2"):
+        for shape in ("flat", "list", "struct"):
+            cases.append((f"julian-{profile}-{shape}", "julian", "nanos", False, profile, shape, legacy, False))
+    with tempfile.TemporaryDirectory(prefix="timestamp-interop-") as directory:
+        work = Path(directory)
+        rows = files = projections = 0
+        for number, (name, kind, unit, adjusted, profile, shape, values, narrows) in enumerate(cases):
+            root = work / str(number)
+            root.mkdir()
+            payloads = [value.to_bytes(12, "little", signed=True) if value is not None else None for value in values] if kind == "signed" else values
+            field = extension_field("v", kind, adjusted, unit)
+            table = shape_table(payloads, shape, field)
+            original = root / (name + ".parquet")
+            pq.write_table(table, original, compression="SNAPPY" if profile == "dictionary-v2" else "NONE", use_dictionary=profile == "dictionary-v2", data_page_version="2.0" if profile == "dictionary-v2" else "1.0", row_group_size=3, write_page_checksum=True)
+            annotate(original, kind, adjusted, unit)
+            actual, descriptors = verify_file(args.reader, original, root / "forward")
+            assert actual.equals(table, check_metadata=False)
+            rows += actual.num_rows
+            source = root / "arrow"
+            source.mkdir()
+            with ipc.new_file(source / "source.arrow", actual.schema) as sink:
+                sink.write_table(actual)
+            dest = root / "rewritten"
+            checked([args.writer, "--nested-from-arrow", source, dest])
+            copied, copied_descriptors = verify_file(args.reader, dest / "source.parquet", root / "reverse")
+            assert copied.equals(actual, check_metadata=False)
+            assert copied_descriptors == descriptors
+            files += 2
+            if shape == "flat":
+                target = pa.schema([pa.field("v", pa.timestamp(UNITS[unit][1], tz="UTC" if adjusted else None))])
+                project(args.reader, original, target, root, values if narrows else None)
+                projections += 1
+        # Native Haskell-produced extrema and nulls, independently decoded by C++.
+        native = sorted(args.native_fixtures.glob("timestamp96-*.parquet")) + [args.native_fixtures / "int96-full.parquet"]
+        assert len(native) == 7 and all(path.is_file() for path in native)
+        for index, path in enumerate(native):
+            actual, descriptors = verify_file(args.reader, path, work / f"haskell-{index}")
+            files += 1
+            rows += actual.num_rows
+            payloads = actual.column(0).to_pylist()
+            if path.name.startswith("timestamp96"):
+                assert [int.from_bytes(value,"little",signed=True) if value is not None else None for value in payloads] == wide_counts
+            else:
+                assert payloads == legacy[:3] + [None, legacy[3]] + legacy[5:]
+        # Published Apache fixtures: use the documented integer values, avoiding
+        # datetime ranges and the overflowing default PyArrow INT96 projection.
+        for name in ("flba12_timestamp.parquet", "int96_from_spark.parquet", "int96_timestamp_order.parquet"):
+            path = args.corpus / "data" / name
+            actual, descriptors = verify_file(args.reader, path, work / name)
+            files += 1
+            rows += actual.num_rows
+            if name == "flba12_timestamp.parquet":
+                seconds = [0,1,-1,9223372036,253402300799,-62135596800]
+                for ordinal, _, _, unit in descriptors:
+                    scale = {"millis":1000,"micros":1000000,"nanos":1000000000}[unit]
+                    assert [int.from_bytes(value,"little",signed=True) for value in actual.column(ordinal).to_pylist()] == [value*scale for value in seconds]
+            if name == "int96_from_spark.parquet":
+                expected = [1704141296123456,1704070800000000,253402225200000000,1735599600000000,None,9089380393200000000]
+                target = pa.schema([pa.field("a", pa.timestamp("us"))])
+                payloads = actual.column(0).to_pylist()
+                exact = [None if value is None else ((struct.unpack("<qi", value)[1]-2440588)*86400000000000 + struct.unpack("<qi", value)[0]) for value in payloads]
+                assert [None if value is None else value//1000 for value in exact[:5]] == expected[:5]
+                assert exact[-1]//1000 < -(1<<63)
+                project(args.reader, path, target, work / name)
+                legacy_difference = {"fixture":name, "exactSignedDayAndNanosMicroseconds":str(exact[-1]//1000), "documentedMicroseconds":str(expected[-1]), "pyarrowMicroseconds":str(pq.read_table(path,coerce_int96_timestamp_unit="us").column(0).cast(pa.int64()).to_pylist()[-1]), "behavior":"original12bytes preserved; overflowing Int64 projection rejected"}
+                projections += 1
+        report = {"cases":len(cases)+10, "nativeFiles":files, "rows":rows, "checkedProjections":projections, "pyarrow":pa.__version__, "physicalOracle":"original body byte-identical; Thrift annotation/type-only adaptation then unmodified C++ decoding", "legacyReferenceDifferences":[legacy_difference], "failures":0, "skips":0}
+        args.output.write_text(json.dumps(report,indent=2)+"\n")
+        print(json.dumps(report,indent=2))
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_variant_interop.py b/scripts/parquet_variant_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_variant_interop.py
@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Variant binary semantics and unshredded Parquet interoperability.
+
+The official malformed fixtures are unannotated binary column pairs. Check
+their raw bytes separately from explicit Variant payload interpretation.
+"""
+import argparse
+import json
+from pathlib import Path
+import shutil
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+from parquet_file_interop import footer
+from parquet_lzo_interop import Node, encode
+
+
+def binary_cases():
+    empty = bytes([1, 0, 0])
+    cases = {}
+
+    def primitive(name, tag, payload=b""):
+        cases[name] = (empty, bytes([tag << 2]) + payload)
+
+    primitive("null", 0)
+    primitive("true", 1)
+    primitive("false", 2)
+    primitive("int8", 3, struct.pack("<b", -128))
+    primitive("int16", 4, struct.pack("<h", -32768))
+    primitive("int32", 5, struct.pack("<i", -(2**31)))
+    primitive("int64", 6, struct.pack("<q", -(2**63)))
+    primitive("double-nan-bits", 7, struct.pack("<Q", 0x7FF8123456789012))
+    primitive("double-negative-zero", 7, struct.pack("<Q", 1 << 63))
+    primitive("decimal4", 8, bytes([9]) + struct.pack("<i", -999999999))
+    primitive("decimal8", 9, bytes([18]) + struct.pack("<q", -999999999999999999))
+    primitive("decimal16", 10, bytes([38]) + (-(10**38-1)).to_bytes(16, "little", signed=True))
+    primitive("date", 11, struct.pack("<i", -40000))
+    primitive("timestamp", 12, struct.pack("<q", -1))
+    primitive("timestamp-ntz", 13, struct.pack("<q", -1))
+    primitive("float-nan-bits", 14, struct.pack("<I", 0x7FC12345))
+    primitive("float-negative-zero", 14, struct.pack("<I", 1 << 31))
+    binary = bytes(range(256))
+    primitive("binary", 15, struct.pack("<I", len(binary)) + binary)
+    text = ("λ🦊" * 20).encode()
+    primitive("string", 16, struct.pack("<I", len(text)) + text)
+    primitive("time", 17, struct.pack("<q", 86399999999))
+    primitive("timestamp-nanos", 18, struct.pack("<q", 2**63-1))
+    primitive("timestamp-ntz-nanos", 19, struct.pack("<q", -(2**63)))
+    primitive("uuid", 20, bytes(range(16)))
+    cases["short-string"] = (empty, bytes([9]) + "λ".encode())
+    cases["array"] = (empty, bytes([3, 2, 0, 1, 3, 0, 12, 255]))
+    cases["array-reserved"] = (empty, bytes([227, 1, 0, 1, 0]))
+    cases["large-small-array"] = (empty, bytes([19, 1, 0, 0, 0, 0, 1, 0]))
+    metadata = bytes([1, 2, 0, 1, 2, 97, 98])
+    value = bytes([2, 2, 0, 1, 2, 0, 4, 12, 2, 12, 1])
+    cases["object-reordered-values"] = (metadata, value)
+    cases["object-reserved"] = (bytes([33]) + metadata[1:], bytes([130]) + value[1:])
+    cases["unsorted-nonunique-dictionary"] = (bytes([1, 3, 0, 1, 2, 3, 98, 97, 97]), bytes([2, 1, 2, 0, 1, 0]))
+    for width in range(1, 5):
+        def word(n):
+            return n.to_bytes(width, "little")
+        metadata = bytes([1 + (width-1)*64]) + word(1) + word(0) + word(1) + b"a"
+        value = bytes([2 + (width-1)*4 + (width-1)*16, 1]) + word(0) + word(0) + word(1) + b"\0"
+        cases[f"width-{width}"] = (metadata, value)
+    return cases
+
+
+def annotate_variant(source, target, reverse=False):
+    prefix, metadata = footer(source)
+    elements = metadata.value[2].value
+    group = elements[1]
+    group.value[10] = Node(TType.STRUCT, {16: Node(TType.STRUCT, {1: Node(TType.BYTE, 1)})})
+    if reverse:
+        assert len(elements) == 4
+        elements[2], elements[3] = elements[3], elements[2]
+        for row_group in metadata.value[4].value:
+            row_group.value[1].value.reverse()
+    raw = encode(metadata)
+    target.write_bytes(prefix + raw + struct.pack("<I", len(raw)) + b"PAR1")
+
+
+def check_annotation(path):
+    _, metadata = footer(path)
+    elements = metadata.value[2].value
+    assert len(elements) == 4
+    assert elements[1].value[10].value[16].value[1].value == 1
+    assert elements[1].value[5].value == 2
+    for element in elements[2:]:
+        assert element.value[1].value == 6  # BYTE_ARRAY
+        assert element.value[3].value == 0  # REQUIRED
+    assert {e.value[4].value for e in elements[2:]} == {b"metadata", b"value"}
+
+
+def run(command, expected=0):
+    result = subprocess.run(list(map(str, command)), capture_output=True, text=True, timeout=60)
+    assert result.returncode == expected, (command, result.returncode, result.stdout, result.stderr)
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--writer", required=True, type=Path)
+    parser.add_argument("--reader", required=True, type=Path)
+    parser.add_argument("--reference", required=True, type=Path)
+    parser.add_argument("--corpus", type=Path)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    cases = binary_cases()
+    with tempfile.TemporaryDirectory(prefix="parquet-variant-") as directory:
+        root = Path(directory)
+        inputs, native, compare = (root / name for name in ("inputs", "native", "compare"))
+        inputs.mkdir()
+        compare.mkdir()
+        for name, (metadata, value) in cases.items():
+            (inputs / (name + ".meta")).write_bytes(metadata)
+            (inputs / (name + ".value")).write_bytes(value)
+            shutil.copyfile(inputs / (name + ".meta"), compare / (name + ".meta"))
+            shutil.copyfile(inputs / (name + ".value"), compare / (name + ".value"))
+        run([args.writer, "--variant-from-binary", inputs, native])
+        for name in cases:
+            path = native / (name + ".parquet")
+            check_annotation(path)
+            physical = pq.read_table(path).to_pylist()
+            assert physical[1] == {"v": None}
+            assert physical[2]["v"]["value"] == b"\0"
+            exported = root / (name + "-export")
+            run([args.reader, "--variant-export", path, "v", exported])
+            assert (exported / "0-1.null").exists()
+            for ext in ("meta", "value"):
+                assert (exported / ("0-0." + ext)).read_bytes() == physical[0]["v"]["metadata" if ext == "meta" else "value"]
+                shutil.copyfile(exported / ("0-0." + ext), compare / (name + "-native." + ext))
+        # Foreign Parquet pages are written by PyArrow; only the logical
+        # annotation (and one child's schema/descriptor order) is Thrift-edited.
+        foreign_checks = 0
+        for reverse in (False, True):
+            name = "object-reordered-values"
+            metadata, value = cases[name]
+            schema = pa.schema([pa.field("v", pa.struct([pa.field("metadata", pa.binary(), False), pa.field("value", pa.binary(), False)]), True)])
+            table = pa.Table.from_pylist([{"v": {"metadata": metadata, "value": value}}, {"v": None}, {"v": {"metadata": b"\1\0\0", "value": b"\0"}}], schema=schema)
+            raw, annotated = root / "foreign-raw.parquet", root / f"foreign-{reverse}.parquet"
+            pq.write_table(table, raw)
+            annotate_variant(raw, annotated, reverse)
+            check_annotation(annotated)
+            exported = root / f"foreign-export-{reverse}"
+            run([args.reader, "--variant-export", annotated, "v", exported])
+            assert (exported / "0-1.null").exists()
+            for ext in ("meta", "value"):
+                shutil.copyfile(exported / ("0-0." + ext), compare / (name + f"-foreign-{reverse}." + ext))
+            foreign_checks += 1
+        run([args.reference, compare])
+        semantic_checks = 0
+        for name in cases:
+            assert (compare / (name + ".rust-status")).read_text().startswith("OK")
+            for ext in ("rust-meta", "rust-value"):
+                assert (compare / (name + "." + ext)).read_bytes() == (compare / (name + "-native." + ext)).read_bytes(), name
+            semantic_checks += 1
+        for reverse in (False, True):
+            for ext in ("rust-meta", "rust-value"):
+                assert (compare / ("object-reordered-values." + ext)).read_bytes() == (compare / (f"object-reordered-values-foreign-{reverse}." + ext)).read_bytes()
+        malformed = 0
+        if args.corpus:
+            for path in sorted((args.corpus / "bad_data/variants").glob("*.parquet")):
+                # First prove ordinary raw reads still succeed.
+                work = root / ("raw-" + path.stem)
+                work.mkdir()
+                (work / path.name).symlink_to(path.resolve())
+                run([args.reader, work])
+                rejected = subprocess.run([str(args.reader), "--variant-payloads", str(path)], capture_output=True, text=True, timeout=60)
+                assert rejected.returncode == 1 and "Parquet.Variant:" in rejected.stdout, (path, rejected)
+                malformed += 1
+            assert malformed == 14
+        report = {"status": "passed", "nativeSemanticRoundtrips": semantic_checks,
+                  "independentAnnotatedParquetFiles": foreign_checks, "apacheThriftAnnotationChecks": len(cases)+foreign_checks,
+                  "physicalPyArrowComparisons": len(cases), "ordinaryMalformedFixtureReadsPreserved": malformed,
+                  "explicitVariantPayloadRejections": malformed,
+                  "referenceLimitations": "Rust rejects decimal4/8 scale 38 despite binary spec [0,38]; covered by native regression, not claimed as Rust passes.",
+                  "scope": "Binary Variant semantics and unshredded files; typed shredding/canonical Arrow extension integration remain separate release gates."}
+        if args.output:
+            args.output.write_text(json.dumps(report, indent=2) + "\n")
+        print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_variant_native_interop.py b/scripts/parquet_variant_native_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_variant_native_interop.py
@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Foreign-written native Variant files, exact typed values and Rust unshredding.
+
+The shared Arrow fixtures are lowered to the native storage types specified
+by Parquet. Only footer annotations missing from PyArrow's writer are added;
+all encoded data pages are produced by PyArrow without alteration.
+"""
+import argparse
+import json
+from pathlib import Path
+import struct
+import tempfile
+
+import pyarrow as pa
+import pyarrow.compute as pc
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+from thrift.Thrift import TType
+
+from parquet_lzo_interop import Node, encode
+from parquet_variant_interop import annotate_variant, footer
+from parquet_variant_typed_interop import EMPTY, generate_cases, outputs, run
+
+
+def native_storage(field, array, visible=None):
+    """Normalize physical storage without narrowing through Python scalars."""
+    if visible is None:
+        visible = pa.array([True] * len(array), type=pa.bool_())
+    nulls = array.is_null()
+    present = pc.and_(visible, pc.invert(nulls))
+    if not field.nullable:
+        assert not pc.any(pc.and_(visible, nulls)).as_py(), field
+    typ = array.type
+    if pa.types.is_dictionary(typ):
+        values = array.dictionary
+        if pa.types.is_binary_view(values.type):
+            values = values.cast(pa.binary())
+        decoded = pc.take(values, array.indices)
+        return native_storage(field.with_type(decoded.type), decoded, visible)
+    if pa.types.is_run_end_encoded(typ):
+        values = array.values
+        if pa.types.is_binary_view(values.type):
+            values = values.cast(pa.binary())
+        encoded = pa.RunEndEncodedArray.from_arrays(array.run_ends, values)
+        decoded = pc.run_end_decode(encoded)
+        return native_storage(field.with_type(decoded.type), decoded, visible)
+    if pa.types.is_struct(typ):
+        fields, children = [], []
+        for index, child_field in enumerate(typ):
+            child_field, child = native_storage(child_field, array.field(index), present)
+            fields.append(child_field)
+            children.append(child)
+        # Required wrappers below a null ancestor carry arbitrary storage;
+        # some writers reject the masked null bitmap before seeing the parent.
+        result = pa.StructArray.from_arrays(children, fields=fields, mask=nulls if field.nullable else None)
+    elif pa.types.is_list(typ) or pa.types.is_large_list(typ) or pa.types.is_list_view(typ):
+        child = array.values
+        offsets = array.offsets
+        if pa.types.is_list_view(typ):
+            indices, normalized = [], [0]
+            for start, size in zip(offsets.to_pylist(), array.sizes.to_pylist()):
+                indices.extend(range(start, start + size))
+                normalized.append(len(indices))
+            child = pc.take(child, pa.array(indices, type=pa.int64()))
+            offsets = pa.array(normalized, type=pa.int32())
+        else:
+            offsets = offsets.cast(pa.int32(), safe=True)
+        child_field, child = native_storage(typ.value_field, child)
+        result = pa.ListArray.from_arrays(offsets, child, type=pa.list_(child_field), mask=nulls)
+    elif pa.types.is_binary(typ) or pa.types.is_large_binary(typ) or pa.types.is_binary_view(typ):
+        result = array.cast(pa.binary())
+    elif pa.types.is_string(typ) or pa.types.is_large_string(typ) or pa.types.is_string_view(typ):
+        result = array.cast(pa.string())
+    elif field.metadata and field.metadata.get(b"ARROW:extension:name") == b"arrow.uuid":
+        result = pa.ExtensionArray.from_storage(pa.uuid(), array)
+    else:
+        result = array
+    return field.with_type(result.type), result
+
+
+def annotations(source, target):
+    annotate_variant(source, target)
+    prefix, meta = footer(target)
+    for item in meta.value[2].value:
+        logical = item.value.get(10)
+        if logical and 7 in logical.value:  # TIME: Arrow time64(us) has no zone
+            logical.value[7].value[1] = Node(TType.BOOL, False)
+    raw = encode(meta)
+    target.write_bytes(prefix + raw + struct.pack("<I", len(raw)) + b"PAR1")
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reader", type=Path, required=True)
+    parser.add_argument("--reference", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--dictionary-v2", action="store_true", help="dictionary-encoded Snappy data pages v2")
+    args = parser.parse_args()
+    results = []
+    with tempfile.TemporaryDirectory(prefix="parquet-native-variant-") as folder:
+        root = Path(folder)
+
+        def fixture(name, fields, arrays, expected, mask=None, invalid=False, reference_error=None, reference_expected=None):
+            shape_note = None
+            # Empty typed objects have no physical leaf with which to record
+            # presence. Test the exact semantic object via its unshredded form;
+            # zero-leaf typed native layouts are separately rejected/zero-row tested.
+            if name in ("empty-object", "zero-rows"):
+                size = len(expected)
+                fields = [pa.field("metadata", pa.binary(), False), pa.field("value", pa.binary(), False)]
+                arrays = [pa.array([EMPTY] * size, type=pa.binary()), pa.array([bytes([2, 0, 0])] * size, type=pa.binary())]
+                shape_note = "unshredded empty object; zero-leaf presence is unobservable"
+            column = pa.StructArray.from_arrays(arrays, fields=fields, mask=mask)
+            field, column = native_storage(pa.field("v", column.type), column)
+            raw, path = root / (name + ".raw"), root / (name + ".parquet")
+            pq.write_table(pa.Table.from_arrays([column], schema=pa.schema([field])), raw, compression="SNAPPY" if args.dictionary_v2 else "NONE", data_page_version="2.0" if args.dictionary_v2 else "1.0", store_decimal_as_integer=True, store_schema=False, use_dictionary=args.dictionary_v2)
+            annotations(raw, path)
+            native = root / (name + "-values")
+            actual = run([args.reader, "--variant-export", path, "v", native])
+            if invalid:
+                assert actual.returncode != 0, (name, actual.stdout, actual.stderr)
+            else:
+                assert actual.returncode == 0, (name, actual.stdout, actual.stderr)
+                for i in range(len(expected)):
+                    for suffix in ("meta", "value", "null"):
+                        original = native / f"0-{i}.{suffix}"
+                        if original.exists():
+                            original.rename(native / f"{i:06}.{suffix}")
+                outputs(native, expected)
+                # Infer the Arrow schema from the real native footer, then
+                # send that schema and data to the independent Rust kernel.
+                inputs, exported = root / (name + "-input"), root / (name + "-arrow")
+                inputs.mkdir()
+                path.rename(inputs / "case.parquet")
+                run([args.reader, inputs, "--arrow-output", exported], expected=0)
+                table = ipc.open_stream(exported / "case.parquet.arrows").read_all()
+                arrow = root / (name + "-inferred.arrow")
+                with ipc.new_file(arrow, table.schema) as writer:
+                    writer.write_table(table)
+                reference = root / (name + "-rust")
+                rust = run([args.reference, arrow, reference])
+                if reference_error:
+                    assert rust.returncode != 0 and reference_error in rust.stderr, (name, rust.returncode, rust.stderr)
+                else:
+                    assert rust.returncode == 0, (name, rust.stdout, rust.stderr)
+                    outputs(reference, reference_expected if reference_expected is not None else expected)
+            results.append({"name": name, "rows": len(expected), "invalidRejected": invalid, "storageNormalization": shape_note, "referenceLimitation": reference_error, "referenceSemanticDifference": reference_expected is not None})
+
+        generate_cases(fixture)
+        malformed = []
+        def rejected(name, typ, *, integer_decimal=True, edit=None):
+            fields = [pa.field("metadata", pa.binary(), False), pa.field("typed_value", typ)]
+            column = pa.StructArray.from_arrays([pa.array([], type=pa.binary()), pa.array([], type=typ)], fields=fields)
+            raw, path = root / (name + ".raw"), root / (name + ".parquet")
+            pq.write_table(pa.table({"v": column}), raw, compression="NONE", store_decimal_as_integer=integer_decimal, store_schema=False)
+            annotations(raw, path)
+            if edit:
+                prefix, meta = footer(path)
+                edit(meta.value[2].value)
+                data = encode(meta)
+                path.write_bytes(prefix + data + struct.pack("<I", len(data)) + b"PAR1")
+            result = run([args.reader, "--variant-export", path, "v", root / (name + "-out")])
+            assert result.returncode != 0, (name, result.stdout, result.stderr)
+            malformed.append(name)
+        for typ in [pa.uint8(), pa.uint16(), pa.uint32(), pa.uint64(), pa.float16(), pa.binary(16), pa.timestamp("ms"), pa.time32("ms")]:
+            rejected("forbidden-" + str(typ), typ)
+        rejected("small-decimal-fixed-carrier", pa.decimal32(9, 0), integer_decimal=False)
+        rejected("medium-decimal-fixed-carrier", pa.decimal64(18, 2), integer_decimal=False)
+        rejected("metadata-optional", pa.int32(), edit=lambda schema: schema[2].value.__setitem__(3, Node(TType.I32, 1)))
+        rejected("typed-required", pa.int32(), edit=lambda schema: schema[3].value.__setitem__(3, Node(TType.I32, 0)))
+        rejected("missing-metadata-name", pa.int32(), edit=lambda schema: schema[2].value.__setitem__(4, Node(TType.STRING, b"other")))
+        list_type = pa.list_(pa.field("element", pa.struct([pa.field("typed_value", pa.int32())]), False))
+        rejected("list-element-optional", list_type, edit=lambda schema: schema[5].value.__setitem__(3, Node(TType.I32, 1)))
+        rejected("list-wrapper-optional", list_type, edit=lambda schema: schema[4].value.__setitem__(3, Node(TType.I32, 1)))
+        rejected("list-outer-required", list_type, edit=lambda schema: schema[3].value.__setitem__(3, Node(TType.I32, 0)))
+    report = {"pyarrow": pa.__version__, "cases": len(results), "rows": sum(case["rows"] for case in results), "failures": 0, "skips": 0, "results": results, "malformedSchemasRejected": malformed}
+    args.output.write_text(json.dumps(report, indent=2) + "\n")
+    print(json.dumps({key: value for key, value in report.items() if key != "results"}))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_variant_reference.lock b/scripts/parquet_variant_reference.lock
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_variant_reference.lock
@@ -0,0 +1,496 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "arrow-schema"
+version = "60.1.0"
+dependencies = [
+ "serde_core",
+ "serde_json",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "cc"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "375989decec1a0fa424442bed520fa12ede43a48475ce8c7417d2c69b32b5f6b"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "num-traits",
+ "windows-link",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
+[[package]]
+name = "equivalent"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48"
+
+[[package]]
+name = "futures-core"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
+
+[[package]]
+name = "futures-task"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
+
+[[package]]
+name = "futures-util"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+]
+
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "zerocopy",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "js-sys"
+version = "0.3.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "log"
+version = "0.4.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d15f86d12da44cd8d4ec3c73984537eb7f4cadcb9776a575a0a8a05ca11005c"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "parquet-variant"
+version = "60.1.0"
+dependencies = [
+ "arrow-schema",
+ "chrono",
+ "half",
+ "indexmap",
+ "simdutf8",
+ "uuid",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.154"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "simdutf8"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "uuid"
+version = "1.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a0e2d11620c50695fe12bbbfde96b3477fe606e7284c22d505c12ce51214514"
+dependencies = [
+ "getrandom",
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c"
+dependencies = [
+ "cfg-if",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "wireform-variant-reference"
+version = "0.1.0"
+dependencies = [
+ "parquet-variant",
+]
+
+[[package]]
+name = "zerocopy"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/scripts/parquet_variant_reference.rs b/scripts/parquet_variant_reference.rs
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_variant_reference.rs
@@ -0,0 +1,29 @@
+use parquet_variant::{Variant, VariantBuilder};
+use std::{env, fs, path::Path};
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let args: Vec<_> = env::args().collect();
+    let root = Path::new(&args[1]);
+    for entry in fs::read_dir(root)? {
+        let path = entry?.path();
+        if path.extension().and_then(|x| x.to_str()) != Some("meta") {
+            continue;
+        }
+        let metadata = fs::read(&path)?;
+        let value = fs::read(path.with_extension("value"))?;
+        match Variant::try_new(&metadata, &value) {
+            Ok(v) => {
+                let debug = format!("{:?}", v);
+                let mut builder = VariantBuilder::new();
+                builder.try_append_value(v)?;
+                let (m, b) = builder.finish();
+                fs::write(path.with_extension("rust-meta"), m)?;
+                fs::write(path.with_extension("rust-value"), b)?;
+                fs::write(path.with_extension("rust-status"), format!("OK {}", debug))?;
+            }
+            Err(e) => {
+                fs::write(path.with_extension("rust-status"), format!("ERROR {}", e))?;
+            }
+        }
+    }
+    Ok(())
+}
diff --git a/scripts/parquet_variant_typed_interop.py b/scripts/parquet_variant_typed_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_variant_typed_interop.py
@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""Canonical typed Variant reconstruction against raw encodings and arrow-rs.
+
+All Haskell outputs are compared with independent, type-preserving expected
+values. Reference limits/differences are asserted and reported explicitly;
+they never relax the Haskell expectation or silently skip a native case.
+"""
+import argparse
+import decimal
+import json
+from pathlib import Path
+import struct
+import subprocess
+import tempfile
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+
+
+NULL = ("null",)
+EMPTY = bytes([1, 0, 0])
+
+
+def dictionary(names):
+    names = sorted(set(names), key=lambda text: text.encode())
+    payload = bytearray()
+    offsets = [0]
+    for name in names:
+        payload.extend(name.encode())
+        offsets.append(len(payload))
+    width = max(1, (max(len(names),len(payload)).bit_length()+7)//8)
+    result = bytearray([1 + ((width-1)<<6)])
+    result.extend(len(names).to_bytes(width,"little"))
+    for offset in offsets:
+        result.extend(offset.to_bytes(width,"little"))
+    result.extend(payload)
+    return bytes(result), names
+
+
+def object_bytes(names, fields):
+    keys = sorted(fields, key=lambda text: text.encode())
+    ids, offsets = [], [0]
+    body = bytearray()
+    for key in keys:
+        ids.append(names.index(key))
+        body.extend(fields[key])
+        offsets.append(len(body))
+    iw = max(1, (max(ids,default=0).bit_length()+7)//8)
+    ow = max(1, (len(body).bit_length()+7)//8)
+    large = len(keys)>=256
+    header = 2 | (((iw-1)<<2 | (ow-1) | (16 if large else 0))<<2)
+    result=bytearray([header])
+    result.extend(len(keys).to_bytes(4 if large else 1,"little"))
+    for index in ids:
+        result.extend(index.to_bytes(iw,"little"))
+    for offset in offsets:
+        result.extend(offset.to_bytes(ow,"little"))
+    result.extend(body)
+    return bytes(result)
+
+
+def decode(metadata, data):
+    def word(buf, start, width):
+        assert start >= 0 and start + width <= len(buf)
+        return int.from_bytes(buf[start:start + width], "little")
+    width = (metadata[0] >> 6) + 1
+    count = word(metadata, 1, width)
+    offset_start = 1 + width
+    start = offset_start + (count + 1) * width
+    names = []
+    for i in range(count):
+        lo = word(metadata, offset_start + i * width, width)
+        hi = word(metadata, offset_start + (i + 1) * width, width)
+        names.append(metadata[start + lo:start + hi].decode())
+
+    def value(buf):
+        assert buf
+        kind, header = buf[0] & 3, buf[0] >> 2
+        if kind == 1:
+            assert len(buf) == header + 1
+            return ("string", buf[1:].decode())
+        if kind == 0:
+            if header == 0:
+                assert len(buf) == 1
+                return NULL
+            if header in (1, 2):
+                assert len(buf) == 1
+                return ("bool", header == 1)
+            integer_types = {3: ("int8", 1), 4: ("int16", 2), 5: ("int32", 4), 6: ("int64", 8), 11: ("date", 4), 12: ("timestamp", 8), 13: ("timestamp-ntz", 8), 17: ("time", 8), 18: ("timestamp-nanos", 8), 19: ("timestamp-ntz-nanos", 8)}
+            if header in integer_types:
+                tag, size = integer_types[header]
+                assert len(buf) == size + 1
+                return (tag, int.from_bytes(buf[1:], "little", signed=True))
+            if header in (7, 14):
+                size = 8 if header == 7 else 4
+                assert len(buf) == size + 1
+                return ("double-bits" if header == 7 else "float-bits", int.from_bytes(buf[1:], "little"))
+            if header in (8, 9, 10):
+                size = {8: 4, 9: 8, 10: 16}[header]
+                assert len(buf) == size + 2
+                return (f"decimal{size}", buf[1], int.from_bytes(buf[2:], "little", signed=True))
+            if header == 20:
+                assert len(buf) == 17
+                return ("uuid", buf[1:])
+            assert header in (15, 16)
+            n = word(buf, 1, 4)
+            assert len(buf) == 5 + n
+            return ("binary", buf[5:]) if header == 15 else ("string", buf[5:].decode())
+        if kind == 2:
+            ow, iw, cw = (header & 3) + 1, ((header >> 2) & 3) + 1, 4 if header & 16 else 1
+            n = word(buf, 1, cw)
+            ids = 1 + cw
+            offsets = ids + n * iw
+            body = offsets + (n + 1) * ow
+            result = {}
+            for i in range(n):
+                name = names[word(buf, ids + i * iw, iw)]
+                assert name not in result
+                lo = word(buf, offsets + i * ow, ow)
+                hi = word(buf, offsets + (i + 1) * ow, ow)
+                result[name] = value(buf[body + lo:body + hi])
+            assert body + word(buf, offsets + n * ow, ow) == len(buf)
+            return result
+        ow, cw = (header & 3) + 1, 4 if header & 4 else 1
+        n = word(buf, 1, cw)
+        offsets = 1 + cw
+        body = offsets + (n + 1) * ow
+        result = []
+        for i in range(n):
+            lo = word(buf, offsets + i * ow, ow)
+            hi = word(buf, offsets + (i + 1) * ow, ow)
+            result.append(value(buf[body + lo:body + hi]))
+        assert body + word(buf, offsets + n * ow, ow) == len(buf)
+        return result
+    return value(data)
+
+
+def run(args, expected=None):
+    result = subprocess.run(list(map(str, args)), capture_output=True, text=True, timeout=60)
+    if expected is not None:
+        assert result.returncode == expected, (args, result.returncode, result.stdout, result.stderr)
+    return result
+
+
+def outputs(folder, expected):
+    actual = []
+    for i, value in enumerate(expected):
+        stem = folder / f"{i:06}"
+        if value is None:
+            assert stem.with_suffix(".null").is_file()
+            assert not stem.with_suffix(".value").exists()
+            actual.append(None)
+        else:
+            assert not stem.with_suffix(".null").exists()
+            actual.append(decode(stem.with_suffix(".meta").read_bytes(), stem.with_suffix(".value").read_bytes()))
+    assert actual == expected, (folder, actual, expected)
+
+
+def generate_cases(fixture):
+    def primitive(name, typ, array, expected, reference_error=None, reference_expected=None, field_metadata=None):
+        field = pa.field("typed_value", typ, metadata=field_metadata)
+        fixture(name, [pa.field("metadata", pa.binary(), False), field], [pa.array([EMPTY] * len(array)), array], expected, reference_error=reference_error, reference_expected=reference_expected)
+
+    primitive("bool", pa.bool_(), pa.array([True, False, None]), [("bool", True), ("bool", False), NULL])
+    for width in (8, 16, 32, 64):
+        typ = getattr(pa, f"int{width}")()
+        values = [-(2 ** (width - 1)), 2 ** (width - 1) - 1, 0]
+        expected = list(map(lambda n: (f"int{width}", n), values))
+        primitive(f"int{width}", typ, pa.array(values, type=typ), expected)
+    for size, typ, bits in [(4, pa.float32(), [0x80000000, 0, 1, 0x7FC12345, 0x7F812345, 0x7F800000, 0xFF800000]), (8, pa.float64(), [0x8000000000000000, 0, 1, 0x7FF8123456789012, 0x7FF0123456789012, 0x7FF0000000000000, 0xFFF0000000000000])]:
+        payload = bytearray()
+        for raw in bits:
+            payload.extend(raw.to_bytes(size, "little"))
+        array = pa.Array.from_buffers(typ, len(bits), [None, pa.py_buffer(payload)])
+        primitive(f"float{size * 8}", typ, array, list(map(lambda n: ("float-bits" if size == 4 else "double-bits", n), bits)))
+    for precision in range(1, 39):
+        size, make = (4, pa.decimal32) if precision <= 9 else (8, pa.decimal64) if precision <= 18 else (16, pa.decimal128)
+        for scale in (0, precision):
+            values = [-(10 ** precision - 1), 0, 10 ** precision - 1]
+            decimal_values = []
+            with decimal.localcontext() as context:
+                context.prec = 100
+                for value in values:
+                    decimal_values.append(decimal.Decimal(value).scaleb(-scale))
+            typ = make(precision, scale)
+            primitive(f"decimal-{precision}-{scale}", typ, pa.array(decimal_values, type=typ), list(map(lambda n: (f"decimal{size}", scale, n), values)))
+    for typ, label, values in [(pa.date32(), "date", [-40000, 0, 40000]), (pa.time64("us"), "time", [0, 1, 86399999999])]:
+        raw = pa.array(values, type=pa.int32() if label == "date" else pa.int64()).cast(typ)
+        primitive(label, typ, raw, list(map(lambda n: (label, n), values)))
+    extreme = [-(2 ** 31), 2 ** 31 - 1]
+    primitive("date-full-domain", pa.date32(), pa.array(extreme, type=pa.int32()).cast(pa.date32()), list(map(lambda n: ("date", n), extreme)), reference_error="Invalid Date32 value")
+    for timezone in (None, "UTC"):
+        for unit in ("us", "ns"):
+            typ = pa.timestamp(unit, tz=timezone)
+            label = "timestamp" if timezone else "timestamp-ntz"
+            if unit == "ns":
+                label += "-nanos"
+            values = [-1, 0, 1]
+            expected = list(map(lambda n: (label, n), values))
+            narrower = None
+            if unit == "ns":
+                narrower = [(label, -1), ("timestamp" if timezone else "timestamp-ntz", 0), (label, 1)]
+            primitive(label, typ, pa.array(values, type=pa.int64()).cast(typ), expected, reference_expected=narrower)
+            extreme = [-(2 ** 63), 2 ** 63 - 1]
+            primitive(label + "-full-domain", typ, pa.array(extreme, type=pa.int64()).cast(typ), list(map(lambda n: (label, n), extreme)), reference_error="Invalid timestamp microsecond value" if unit == "us" else None)
+    for typ in (pa.binary(), pa.large_binary(), pa.binary_view()):
+        values = [b"", bytes(range(256)), b"long enough for a referenced view"]
+        primitive(str(typ), typ, pa.array(values, type=typ), list(map(lambda value: ("binary", value), values)))
+    for typ in (pa.string(), pa.large_string(), pa.string_view()):
+        values = ["", "λ🦊", "a long string outside an inline view"]
+        primitive(str(typ), typ, pa.array(values, type=typ), list(map(lambda value: ("string", value), values)))
+    uuid = bytes(range(16))
+    primitive("uuid", pa.binary(16), pa.array([uuid], type=pa.binary(16)), [("uuid", uuid)], field_metadata={b"ARROW:extension:name": b"arrow.uuid", b"ARROW:extension:metadata": b""})
+    # Partial object with both fully shredded and fallback-only names.
+    metadata, names = dictionary(["a", "rest"])
+    wrapper_fields = [pa.field("typed_value", pa.int64()), pa.field("value", pa.binary())]
+    child = pa.StructArray.from_arrays([pa.array([34, None, None], type=pa.int64()), pa.array([None, b"\0", None])], fields=wrapper_fields)
+    typed = pa.StructArray.from_arrays([child], fields=[pa.field("a", child.type, False)])
+    fallback = object_bytes(names, {"rest": bytes([12, 9])})
+    fields = [pa.field("typed_value", typed.type), pa.field("value", pa.binary()), pa.field("metadata", pa.binary(), False)]
+    fixture("partial-object", fields, [typed, pa.array([fallback, None, None]), pa.array([metadata] * 3)], [{"a": ("int64", 34), "rest": ("int8", 9)}, {"a": NULL}, {}])
+    fixture("overlapping-object", fields, [typed, pa.array([object_bytes(names, {"a": bytes([12, 9])}), None, None]), pa.array([metadata] * 3)], [], invalid=True)
+    fixture("primitive-conflict", [pa.field("metadata", pa.binary(), False), pa.field("value", pa.binary()), pa.field("typed_value", pa.int64())], [pa.array([EMPTY]), pa.array([b"\0"]), pa.array([34], type=pa.int64())], [], invalid=True)
+    # Missing required elements are materialized as nulls, never dropped.
+    for label in ("list", "large-list", "list-view"):
+        if label == "list":
+            array = pa.ListArray.from_arrays(pa.array([0, 3], type=pa.int32()), child, type=pa.list_(pa.field("element", child.type, False)))
+        elif label == "large-list":
+            array = pa.LargeListArray.from_arrays(pa.array([0, 3], type=pa.int64()), child, type=pa.large_list(pa.field("element", child.type, False)))
+        else:
+            array = pa.ListViewArray.from_arrays(pa.array([0], type=pa.int32()), pa.array([3], type=pa.int32()), child, type=pa.list_view(pa.field("element", child.type, False)))
+        fixture(label, [pa.field("metadata", pa.binary(), False), pa.field("typed_value", array.type)], [pa.array([metadata]), array], [[("int64", 34), NULL, NULL]])
+    # An array of partially shredded objects nested in a shredded
+    # object. Poisoned children below a null typed object stay masked.
+    metadata, names = dictionary(["arr", "rest", "x", "y"])
+    x_fields = [pa.field("typed_value", pa.int32()), pa.field("value", pa.binary())]
+    x = pa.StructArray.from_arrays([pa.array([3, 999, None, None], type=pa.int32()), pa.array([None, b"poison", b"\0", None])], fields=x_fields, mask=pa.array([False, True, False, False]))
+    objects = pa.StructArray.from_arrays([x], fields=[pa.field("x", x.type, False)], mask=pa.array([False, True, False, False]))
+    fragment = object_bytes(names, {"y": bytes([13]) + b"abc"})
+    element_fields = [pa.field("value", pa.binary()), pa.field("typed_value", objects.type)]
+    elements = pa.StructArray.from_arrays([pa.array([fragment, b"\0", None, None]), objects], fields=element_fields)
+    array = pa.ListArray.from_arrays(pa.array([0, 4], type=pa.int32()), elements, type=pa.list_(pa.field("element", elements.type, False)))
+    arr = pa.StructArray.from_arrays([array], fields=[pa.field("typed_value", array.type)])
+    typed = pa.StructArray.from_arrays([arr], fields=[pa.field("arr", arr.type, False)])
+    remainder = object_bytes(names, {"rest": bytes([12, 9])})
+    fixture("recursive-object-array-partial", [pa.field("metadata", pa.binary(), False), pa.field("typed_value", typed.type), pa.field("value", pa.binary())], [pa.array([metadata]), typed, pa.array([remainder])], [{"arr": [{"x": ("int32", 3), "y": ("string", "abc")}, NULL, {"x": NULL}, {}], "rest": ("int8", 9)}])
+    fixture("missing-shared-name", [pa.field("metadata", pa.binary(), False), pa.field("typed_value", typed.type)], [pa.array([EMPTY]), typed], [], invalid=True)
+    # All binary metadata profiles, every legal dictionary key width and
+    # signed run-end width. A root null masks a poisoned metadata value.
+    for typ in (pa.binary(), pa.large_binary(), pa.binary_view()):
+        metadata_array = pa.array([EMPTY, b"poison"], type=typ)
+        for signed in (True, False):
+            for width in (8, 16, 32, 64):
+                key_type = getattr(pa, ("int" if signed else "uint") + str(width))()
+                encoded = pa.DictionaryArray.from_arrays(pa.array([0, 1], type=key_type), metadata_array)
+                fixture(f"metadata-{typ}-{key_type}", [pa.field("metadata", encoded.type, False), pa.field("typed_value", pa.int64())], [encoded, pa.array([7, 999], type=pa.int64())], [("int64", 7), None], mask=pa.array([False, True]))
+        for width in (16, 32, 64):
+            ends = pa.array([1, 2], type=getattr(pa, f"int{width}")())
+            encoded = pa.RunEndEncodedArray.from_arrays(ends, metadata_array)
+            fixture(f"metadata-{typ}-ree{width}", [pa.field("metadata", encoded.type, False), pa.field("typed_value", pa.int64())], [encoded, pa.array([7, 999], type=pa.int64())], [("int64", 7), None], mask=pa.array([False, True]))
+    # Unequal object ID/offset widths: these used to be swapped in
+    # this driver's independent parser while all-small fixtures hid it.
+    metadata,names=dictionary(["a","long"])
+    text="x"*300
+    payload=bytes([64])+len(text).to_bytes(4,"little")+text.encode()
+    a=pa.StructArray.from_arrays([pa.array([7],type=pa.int64())],fields=[pa.field("typed_value",pa.int64())])
+    typed=pa.StructArray.from_arrays([a],fields=[pa.field("a",a.type,False)])
+    fixture("wide-offset-narrow-id",[pa.field("metadata",pa.binary(),False),pa.field("value",pa.binary()),pa.field("typed_value",typed.type)],[pa.array([metadata]),pa.array([object_bytes(names,{"long":payload})]),typed],[{"a":("int64",7),"long":("string",text)}])
+    names=[]
+    for i in range(256):names.append(f"k{i:03}")
+    metadata,keys=dictionary(names+["inner","zzzz"])
+    scalar=pa.StructArray.from_arrays([pa.array([b"\0"])],fields=[pa.field("value",pa.binary())])
+    z=pa.StructArray.from_arrays([scalar],fields=[pa.field("zzzz",scalar.type,False)])
+    inner=pa.StructArray.from_arrays([z],fields=[pa.field("typed_value",z.type)])
+    arrays,fields,expected=[],[],{"inner":{"zzzz":NULL}}
+    for name in names:
+        arrays.append(scalar);fields.append(pa.field(name,scalar.type,False));expected[name]=NULL
+    arrays.append(inner);fields.append(pa.field("inner",inner.type,False))
+    typed=pa.StructArray.from_arrays(arrays,fields=fields)
+    fixture("wide-id-narrow-offset-nested",[pa.field("metadata",pa.binary(),False),pa.field("typed_value",typed.type)],[pa.array([metadata]),typed],[expected])
+    # Zero rows still compile typed-only/empty-object shapes, and an empty
+    # typed object is a present object rather than a missing value.
+    empty_object = pa.StructArray.from_arrays([], fields=[], mask=pa.array([False]))
+    fixture("empty-object", [pa.field("metadata", pa.binary(), False), pa.field("typed_value", empty_object.type)], [pa.array([EMPTY]), empty_object], [{}])
+    empty = pa.StructArray.from_arrays([], fields=[], mask=pa.array([], type=pa.bool_()))
+    fixture("zero-rows", [pa.field("metadata", pa.binary(), False), pa.field("typed_value", empty.type)], [pa.array([], type=pa.binary()), empty], [])
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reader", required=True, type=Path)
+    parser.add_argument("--reference", required=True, type=Path)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    results = []
+    with tempfile.TemporaryDirectory(prefix="parquet-typed-variant-") as directory:
+        root = Path(directory)
+
+        def fixture(name, fields, arrays, expected, mask=None, invalid=False, reference_error=None, reference_expected=None):
+            column = pa.StructArray.from_arrays(arrays, fields=fields, mask=mask)
+            field = pa.field("v", column.type, nullable=True, metadata={b"ARROW:extension:name": b"arrow.parquet.variant", b"ARROW:extension:metadata": b""})
+            schema = pa.schema([field])
+            path = root / (name + ".arrow")
+            with ipc.new_file(path, schema) as writer:
+                writer.write_batch(pa.record_batch([column], schema=schema))
+            native, reference = root / (name + "-native"), root / (name + "-rust")
+            actual = run([args.reader, "--variant-arrow-export", path, native])
+            rust = run([args.reference, path, reference])
+            if invalid:
+                assert actual.returncode != 0 and rust.returncode != 0, (name, actual, rust)
+            else:
+                assert actual.returncode == 0, (name, actual.stderr)
+                outputs(native, expected)
+                if reference_error:
+                    assert rust.returncode != 0 and reference_error in rust.stderr, (name, rust.returncode, rust.stderr)
+                else:
+                    assert rust.returncode == 0, (name, rust.stderr)
+                    outputs(reference, reference_expected if reference_expected is not None else expected)
+            results.append({"name": name, "rows": len(expected), "invalidRejected": invalid, "referenceLimitation": reference_error, "referenceSemanticDifference": reference_expected is not None})
+
+        generate_cases(fixture)
+    report = {"pyarrow": pa.__version__, "cases": len(results), "rows": sum(item["rows"] for item in results), "failures": 0, "skips": 0, "results": results}
+    if args.output:
+        args.output.write_text(json.dumps(report, indent=2) + "\n")
+    print(json.dumps({key: value for key, value in report.items() if key != "results"}, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/parquet_variant_typed_reference.lock b/scripts/parquet_variant_typed_reference.lock
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_variant_typed_reference.lock
@@ -0,0 +1,977 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "const-random",
+ "getrandom 0.3.4",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "arrow"
+version = "60.1.0"
+dependencies = [
+ "arrow-arith",
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-cast",
+ "arrow-data",
+ "arrow-ord",
+ "arrow-row",
+ "arrow-schema",
+ "arrow-select",
+ "arrow-string",
+]
+
+[[package]]
+name = "arrow-arith"
+version = "60.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "chrono",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-array"
+version = "60.1.0"
+dependencies = [
+ "ahash",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "chrono",
+ "half",
+ "hashbrown",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-buffer"
+version = "60.1.0"
+dependencies = [
+ "bytes",
+ "half",
+ "num-bigint",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-cast"
+version = "60.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-ord",
+ "arrow-schema",
+ "arrow-select",
+ "atoi",
+ "base64",
+ "chrono",
+ "half",
+ "lexical-core",
+ "num-traits",
+ "ryu",
+]
+
+[[package]]
+name = "arrow-cmp"
+version = "60.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-schema",
+]
+
+[[package]]
+name = "arrow-data"
+version = "60.1.0"
+dependencies = [
+ "arrow-buffer",
+ "arrow-schema",
+ "half",
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-ipc"
+version = "60.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "arrow-select",
+ "flatbuffers",
+]
+
+[[package]]
+name = "arrow-ord"
+version = "60.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-cmp",
+ "arrow-data",
+ "arrow-schema",
+ "arrow-select",
+]
+
+[[package]]
+name = "arrow-row"
+version = "60.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "half",
+]
+
+[[package]]
+name = "arrow-schema"
+version = "60.1.0"
+dependencies = [
+ "serde_core",
+ "serde_json",
+]
+
+[[package]]
+name = "arrow-select"
+version = "60.1.0"
+dependencies = [
+ "ahash",
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-cmp",
+ "arrow-data",
+ "arrow-schema",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-string"
+version = "60.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "arrow-select",
+ "memchr",
+ "num-traits",
+ "regex",
+ "regex-syntax",
+]
+
+[[package]]
+name = "atoi"
+version = "3.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d12c37257553c19e9aee6cba77814fdc9e07844abfc8b3a2c377cd920ee5a993"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "base64"
+version = "0.23.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
+
+[[package]]
+name = "bitflags"
+version = "2.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cc"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "375989decec1a0fa424442bed520fa12ede43a48475ce8c7417d2c69b32b5f6b"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "num-traits",
+ "windows-link",
+]
+
+[[package]]
+name = "const-random"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "87e00182fe74b066627d63b85fd550ac2998d4b0bd86bfed477a0ae4c7c71359"
+dependencies = [
+ "const-random-macro",
+]
+
+[[package]]
+name = "const-random-macro"
+version = "0.1.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9d839f2a20b0aee515dc581a6172f2321f96cab76c1a38a4c584a194955390e"
+dependencies = [
+ "getrandom 0.2.17",
+ "once_cell",
+ "tiny-keccak",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
+[[package]]
+name = "equivalent"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48"
+
+[[package]]
+name = "flatbuffers"
+version = "25.12.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35f6839d7b3b98adde531effaf34f0c2badc6f4735d26fe74709d8e513a96ef3"
+dependencies = [
+ "bitflags",
+ "rustc_version",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
+
+[[package]]
+name = "futures-task"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
+
+[[package]]
+name = "futures-util"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 5.3.0",
+ "wasip2",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 6.0.0",
+]
+
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "num-traits",
+ "zerocopy",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "js-sys"
+version = "0.3.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "lexical-core"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d8d125a277f807e55a77304455eb7b1cb52f2b18c143b60e766c120bd64a594"
+dependencies = [
+ "lexical-parse-float",
+ "lexical-parse-integer",
+ "lexical-util",
+ "lexical-write-float",
+ "lexical-write-integer",
+]
+
+[[package]]
+name = "lexical-parse-float"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52a9f232fbd6f550bc0137dcb5f99ab674071ac2d690ac69704593cb4abbea56"
+dependencies = [
+ "lexical-parse-integer",
+ "lexical-util",
+]
+
+[[package]]
+name = "lexical-parse-integer"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a7a039f8fb9c19c996cd7b2fcce303c1b2874fe1aca544edc85c4a5f8489b34"
+dependencies = [
+ "lexical-util",
+]
+
+[[package]]
+name = "lexical-util"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2604dd126bb14f13fb5d1bd6a66155079cb9fa655b37f875b3a742c705dbed17"
+
+[[package]]
+name = "lexical-write-float"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50c438c87c013188d415fbabbb1dceb44249ab81664efbd31b14ae55dabb6361"
+dependencies = [
+ "lexical-util",
+ "lexical-write-integer",
+]
+
+[[package]]
+name = "lexical-write-integer"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "409851a618475d2d5796377cad353802345cba92c867d9fbcde9cf4eac4e14df"
+dependencies = [
+ "lexical-util",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
+[[package]]
+name = "log"
+version = "0.4.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d15f86d12da44cd8d4ec3c73984537eb7f4cadcb9776a575a0a8a05ca11005c"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "num-bigint"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93e7820bc0a80a0238e650327316f929ba18d5be054b647490a3a6a339f3e7c0"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+ "libm",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "parquet-variant"
+version = "60.1.0"
+dependencies = [
+ "arrow-schema",
+ "chrono",
+ "half",
+ "indexmap",
+ "simdutf8",
+ "uuid",
+]
+
+[[package]]
+name = "parquet-variant-compute"
+version = "60.1.0"
+dependencies = [
+ "arrow",
+ "arrow-schema",
+ "chrono",
+ "half",
+ "indexmap",
+ "num-traits",
+ "parquet-variant",
+ "parquet-variant-json",
+ "uuid",
+]
+
+[[package]]
+name = "parquet-variant-json"
+version = "60.1.0"
+dependencies = [
+ "arrow-schema",
+ "base64",
+ "chrono",
+ "parquet-variant",
+ "ryu",
+ "serde_json",
+ "uuid",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rustc_version"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
+dependencies = [
+ "semver",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.154"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "simdutf8"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "tiny-keccak"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c9d3793400a45f954c52e73d068316d76b6f4e36977e3fcebb13a2721e80237"
+dependencies = [
+ "crunchy",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "uuid"
+version = "1.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a0e2d11620c50695fe12bbbfde96b3477fe606e7284c22d505c12ce51214514"
+dependencies = [
+ "getrandom 0.4.3",
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c"
+dependencies = [
+ "cfg-if",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "wireform-typed-variant-reference"
+version = "0.1.0"
+dependencies = [
+ "arrow-array",
+ "arrow-ipc",
+ "parquet-variant",
+ "parquet-variant-compute",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/scripts/parquet_variant_typed_reference.rs b/scripts/parquet_variant_typed_reference.rs
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_variant_typed_reference.rs
@@ -0,0 +1,44 @@
+use arrow_array::Array;
+use arrow_ipc::reader::FileReader;
+use parquet_variant::VariantBuilder;
+use parquet_variant_compute::{unshred_variant, VariantArray};
+use std::{env, fs, path::Path};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let args: Vec<_> = env::args().collect();
+    if args.len() != 3 {
+        return Err("usage: wireform-typed-variant-reference INPUT.arrow OUTPUT_DIRECTORY".into());
+    }
+    let reader = FileReader::try_new(fs::File::open(&args[1])?, None)?;
+    let output = Path::new(&args[2]);
+    fs::create_dir_all(output)?;
+    let mut row = 0;
+    for batch in reader {
+        let batch = batch?;
+        if batch.num_columns() != 1 {
+            return Err("expected one Variant column".into());
+        }
+        let storage = batch.column(0);
+        let array = VariantArray::try_new(storage.as_ref())?;
+        // try_value alone does not merge the fallback object fields. Use the
+        // real recursive reconstruction kernel before materializing each row.
+        let full = unshred_variant(&array)?;
+        for i in 0..batch.num_rows() {
+            let prefix = output.join(format!("{row:06}"));
+            if storage.is_null(i) {
+                fs::write(prefix.with_extension("null"), [])?;
+            } else {
+                let value = full.try_value(i)?;
+                fs::write(prefix.with_extension("debug"), format!("{value:?}"))?;
+                let mut builder = VariantBuilder::new();
+                builder.try_append_value(value)?;
+                let (metadata, value) = builder.finish();
+                fs::write(prefix.with_extension("meta"), metadata)?;
+                fs::write(prefix.with_extension("value"), value)?;
+            }
+            row += 1;
+        }
+    }
+    println!("reconstructed {row} rows with pinned arrow-rs");
+    Ok(())
+}
diff --git a/scripts/parquet_variant_write_interop.py b/scripts/parquet_variant_write_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_variant_write_interop.py
@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Canonical typed Arrow -> native Parquet, checked by PyArrow and Rust.
+
+Every source metadata blob and supplied fallback fragment must survive
+verbatim. Native-only fallback slots encode implicit root/array nulls.
+"""
+import argparse
+import json
+from pathlib import Path
+import tempfile
+import struct
+
+from parquet_variant_typed_interop import EMPTY
+from parquet_variant_interop import footer
+
+import pyarrow as pa
+import pyarrow.ipc as ipc
+import pyarrow.parquet as pq
+
+from parquet_variant_typed_interop import generate_cases, outputs, run
+
+
+def child(array, name):
+    return array.field(name) if array.type.get_field_index(name) >= 0 else None
+
+
+def binary_at(array):
+    return None if array is None or not array[0].is_valid else array[0].as_py()
+
+
+def check_fragments(source, native, required=True):
+    assert len(source) == len(native) == 1
+    if not source[0].is_valid:
+        assert not native[0].is_valid
+        return
+    assert native[0].is_valid
+    metadata = child(source, 'metadata')
+    if metadata is not None:
+        assert binary_at(metadata) == binary_at(child(native, 'metadata'))
+    fallback, typed = child(source, 'value'), child(source, 'typed_value')
+    present = typed is not None and typed[0].is_valid
+    expected = binary_at(fallback)
+    if expected is None and not present and required:
+        expected = b'\x00'
+    assert binary_at(child(native, 'value')) == expected
+    if typed is None:
+        return
+    actual = child(native, 'typed_value')
+    assert actual is not None and actual[0].is_valid == present
+    if not present:
+        return
+    if pa.types.is_struct(typed.type):
+        for field in typed.type:
+            check_fragments(typed.field(field.name), actual.field(field.name), False)
+    elif pa.types.is_list(typed.type) or pa.types.is_large_list(typed.type) or pa.types.is_list_view(typed.type):
+        expected_values, actual_values = typed[0].values, actual[0].values
+        assert len(expected_values) == len(actual_values)
+        for i in range(len(expected_values)):
+            check_fragments(expected_values.slice(i, 1), actual_values.slice(i, 1), True)
+
+
+def check_schema(source, actual, root=True):
+    assert pa.types.is_struct(actual.type)
+    if root:
+        assert actual.metadata and actual.metadata.get(b'ARROW:extension:name') == b'arrow.parquet.variant'
+    expected_names = set(source.type.names) | {'value'}
+    assert set(actual.type.names) == expected_names, (source, actual)
+    for field in source.type:
+        target = actual.type.field(field.name)
+        if field.name in ('metadata', 'value'):
+            assert target.type == pa.binary()
+        elif field.name == 'typed_value':
+            source_type, target_type = field.type, target.type
+            if pa.types.is_struct(source_type):
+                assert pa.types.is_struct(target_type) and source_type.names == target_type.names
+                for child_field in source_type:
+                    check_schema(child_field, target_type.field(child_field.name), False)
+            elif pa.types.is_list(source_type) or pa.types.is_large_list(source_type) or pa.types.is_list_view(source_type):
+                assert pa.types.is_list(target_type) and not target_type.value_field.nullable
+                check_schema(source_type.value_field, target_type.value_field, False)
+            else:
+                if pa.types.is_large_binary(source_type) or pa.types.is_binary_view(source_type):
+                    source_type = pa.binary()
+                if pa.types.is_large_string(source_type) or pa.types.is_string_view(source_type):
+                    source_type = pa.string()
+                uuid_extension = isinstance(target_type, pa.BaseExtensionType) and target_type.extension_name == 'arrow.uuid'
+                if uuid_extension:
+                    target_type = target_type.storage_type
+                assert source_type == target_type, (field, target)
+                if field.metadata and field.metadata.get(b'ARROW:extension:name') == b'arrow.uuid':
+                    assert uuid_extension or (target.metadata and target.metadata[b'ARROW:extension:name'] == b'arrow.uuid')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--writer', type=Path, required=True)
+    parser.add_argument('--reader', type=Path, required=True)
+    parser.add_argument('--reference', type=Path, required=True)
+    parser.add_argument('--output', type=Path, required=True)
+    parser.add_argument('--semantic', action='store_true', help='shred decoded Variant values back to their declared shape')
+    args = parser.parse_args()
+    results = []
+    with tempfile.TemporaryDirectory(prefix='parquet-variant-write-') as directory:
+        root = Path(directory)
+        def fixture(name, fields, arrays, expected, mask=None, invalid=False, reference_error=None, reference_expected=None, root_metadata_extra=None, expected_ids=None):
+            inputs, written = root/(name+'-input'), root/(name+'-written')
+            inputs.mkdir()
+            source = pa.StructArray.from_arrays(arrays, fields=fields, mask=mask)
+            extension = {b'ARROW:extension:name':b'arrow.parquet.variant',b'ARROW:extension:metadata':b''}
+            extension.update(root_metadata_extra or {})
+            field = pa.field('v', source.type, nullable=True, metadata=extension)
+            schema = pa.schema([field])
+            with ipc.new_file(inputs/'case.arrow', schema) as output:
+                output.write_batch(pa.record_batch([source], schema=schema))
+            result = run([args.writer, '--variant-shred-from-arrow' if args.semantic else '--nested-from-arrow', inputs, written])
+            unobservable = name == 'empty-object'
+            pyarrow_limitation = None
+            if invalid or unobservable:
+                assert result.returncode != 0, (name, result.stdout, result.stderr)
+                if unobservable:
+                    assert 'no physical leaf' in result.stderr, result.stderr
+                assert not (written/'case.parquet').exists()
+            else:
+                assert result.returncode == 0, (name, result.stdout, result.stderr)
+                path = written/'case.parquet'
+                if expected_ids is not None:
+                    _, native_metadata = footer(path)
+                    actual_ids = [(node.value[4].value, node.value[9].value) for node in native_metadata.value[2].value if 9 in node.value]
+                    assert actual_ids == expected_ids, (name, actual_ids, expected_ids)
+                if name == 'zero-rows':
+                    try:
+                        pq.read_table(path)
+                    except pa.ArrowInvalid as error:
+                        assert 'Parquet non-leaf node has no children' in str(error)
+                        pyarrow_limitation = str(error)
+                    else:
+                        raise AssertionError('PyArrow zero-leaf limitation changed; refresh this explicit expectation')
+                else:
+                    physical = pq.read_table(path).column(0).combine_chunks()
+                    assert len(physical) == len(source)
+                    for row in range(len(source)):
+                        if args.semantic:
+                            if source[row].is_valid:
+                                assert binary_at(child(source.slice(row, 1), 'metadata')) == binary_at(child(physical.slice(row, 1), 'metadata'))
+                        else:
+                            check_fragments(source.slice(row, 1), physical.slice(row, 1))
+                values = root/(name+'-values')
+                run([args.reader, '--variant-export', path, 'v', values], expected=0)
+                for row in range(len(expected)):
+                    for suffix in ('meta','value','null'):
+                        old = values/f'0-{row}.{suffix}'
+                        if old.exists():
+                            old.rename(values/f'{row:06}.{suffix}')
+                outputs(values, expected)
+                exported = root/(name+'-arrow')
+                run([args.reader, written, '--arrow-output', exported], expected=0)
+                table = ipc.open_stream(exported/'case.parquet.arrows').read_all()
+                check_schema(field, table.schema.field('v'))
+                reference_input = root/(name+'-inferred.arrow')
+                with ipc.new_file(reference_input, table.schema) as output:
+                    output.write_table(table)
+                reference = root/(name+'-rust')
+                rust = run([args.reference, reference_input, reference])
+                if reference_error:
+                    assert rust.returncode != 0 and reference_error in rust.stderr, (name, rust.returncode, rust.stderr)
+                else:
+                    assert rust.returncode == 0, (name, rust.stdout, rust.stderr)
+                    outputs(reference, reference_expected if reference_expected is not None else expected)
+            results.append({'name':name,'rows':len(expected),'invalidRejected':invalid,'unobservableStorageRejected':unobservable,'pyarrowLimitation':pyarrow_limitation,'referenceLimitation':reference_error,'referenceSemanticDifference':reference_expected is not None})
+        generate_cases(fixture)
+        def fallback_case(name, typ, encoded, expected):
+            fields = [pa.field('metadata', pa.binary(), False), pa.field('value', pa.binary()), pa.field('typed_value', typ)]
+            fixture(name, fields, [pa.array([EMPTY]*len(encoded)), pa.array(encoded, type=pa.binary()), pa.array([None]*len(encoded), type=typ)], expected)
+        fallback_case('exact-signed-integer-tags', pa.int64(), [bytes([12,1]),bytes([16])+struct.pack('<h',1),bytes([20])+struct.pack('<i',1),bytes([24])+struct.pack('<q',1)], [('int8',1),('int16',1),('int32',1),('int64',1)])
+        fallback_case('decimal-scale-and-precision-fallback',pa.decimal32(8,2),[bytes([32,3])+struct.pack('<i',123),bytes([32,2])+struct.pack('<i',100000000)],[('decimal4',3,123),('decimal4',2,100000000)])
+        fallback_case('decimal-width-fallback',pa.decimal64(10,2),[bytes([32,2])+struct.pack('<i',1)],[('decimal4',2,1)])
+        fallback_case('timestamp-unit-and-zone-fallback',pa.timestamp('us',tz='UTC'),[bytes([72])+struct.pack('<q',1),bytes([52])+struct.pack('<q',1)],[('timestamp-nanos',1),('timestamp-ntz',1)])
+
+        element_type = pa.struct([pa.field('typed_value',pa.int32())])
+        element = pa.StructArray.from_arrays([pa.array([None], type=pa.int32())], fields=list(element_type))
+        array_type = pa.list_(pa.field('element',element_type,False))
+        array = pa.ListArray.from_arrays(pa.array([0,0,0,0,1],type=pa.int32()),element,type=array_type,mask=pa.array([False,True,True,False]))
+        fixture('empty-null-and-missing-arrays',[pa.field('metadata',pa.binary(),False),pa.field('value',pa.binary()),pa.field('typed_value',array_type)],[pa.array([EMPTY]*4),pa.array([None,b'\x00',None,None],type=pa.binary()),array],[[],('null',),('null',),[('null',)]])
+        ids=lambda number:{b'PARQUET:field_id':str(number).encode()}
+        identified_element_type=pa.struct([pa.field('typed_value',pa.int32(),metadata=ids(14))])
+        identified_element=pa.StructArray.from_arrays([pa.array([1],type=pa.int32())],fields=list(identified_element_type))
+        identified_array_type=pa.list_(pa.field('element',identified_element_type,False,metadata=ids(13)))
+        identified_array=pa.ListArray.from_arrays(pa.array([0,1],type=pa.int32()),identified_element,type=identified_array_type)
+        fixture('nested-field-ids',[pa.field('metadata',pa.binary(),False,metadata=ids(11)),pa.field('typed_value',identified_array_type,metadata=ids(12))],[pa.array([EMPTY]),identified_array],[[('int32',1)]],root_metadata_extra=ids(10),expected_ids=[(b'v',10),(b'metadata',11),(b'typed_value',12),(b'element',13),(b'typed_value',14)])
+        fixture('visible-required-typed-null',[pa.field('metadata',pa.binary(),False),pa.field('typed_value',pa.int32(),False)],[pa.array([EMPTY]),pa.array([None],type=pa.int32())],[],invalid=True)
+    report={'semantic':args.semantic,'pyarrow':pa.__version__,'cases':len(results),'nativeFiles':sum(not case['invalidRejected'] and not case['unobservableStorageRejected'] for case in results),'rows':sum(case['rows'] for case in results if not case['unobservableStorageRejected']),'failures':0,'skips':0,'results':results}
+    args.output.write_text(json.dumps(report,indent=2)+'\n')
+    print(json.dumps({key:value for key,value in report.items() if key!='results'}))
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/parquet_writer_options_interop.py b/scripts/parquet_writer_options_interop.py
new file mode 100644
--- /dev/null
+++ b/scripts/parquet_writer_options_interop.py
@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Verify writer settings and page indexes with Apache Thrift and three engines."""
+import argparse
+from pathlib import Path
+import subprocess
+import tempfile
+
+import duckdb
+import polars as pl
+import pyarrow as pa
+import pyarrow.parquet as pq
+from parquet_statistics_interop import read_value, TCompactProtocol, TMemoryBuffer, TType
+
+
+def thrift_at(raw, offset):
+    transport = TMemoryBuffer(raw[offset:])
+    value = read_value(TCompactProtocol(transport), TType.STRUCT)
+    return value, transport.cstringio_buf.tell()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--probe', required=True, type=Path)
+    args = parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix='wireform-parquet-options-') as directory:
+        root = Path(directory)
+        subprocess.run([str(args.probe.resolve()), '--writer-options', str(root)], check=True)
+        files = sorted(root.glob('*.parquet'))
+        assert len(files) == 32, len(files)
+        for path in files:
+            shape, version, codec, index_mode = path.stem.split('-')
+            nullable, indexed = shape == 'mixed', index_mode == 'index'
+            expected = pa.Table.from_arrays([pa.array([1,2,3] * 2, pa.int32()),
+                pa.array(([10,None,30] if nullable else [10,20,30]) * 2, pa.int64())],
+                schema=pa.schema([pa.field('r', pa.int32(), nullable=False),
+                                  pa.field('o', pa.int64(), nullable=nullable)]))
+            assert pq.read_table(path).equals(expected), path.name
+            polars = pl.read_parquet(path).to_arrow()
+            assert polars.schema.types == expected.schema.types and polars.cast(expected.schema).equals(expected), path.name
+            con = duckdb.connect()
+            try:
+                duck = con.execute('SELECT * FROM read_parquet(?)', [str(path)]).to_arrow_table()
+                assert duck.schema.types == expected.schema.types and duck.cast(expected.schema).equals(expected), path.name
+            finally:
+                con.close()
+            raw = path.read_bytes()
+            footer_size = int.from_bytes(raw[-8:-4], 'little')
+            footer_start = len(raw) - 8 - footer_size
+            footer, _ = thrift_at(raw, footer_start)
+            metadata = pq.ParquetFile(path).metadata
+            assert metadata.num_row_groups == 2
+            page_ends = []
+            for rg, group in enumerate(footer[4]):
+                assert group[2] == sum(chunk[3][6] for chunk in group[1]), (path.name, 'row-group uncompressed size')
+                for col, chunk in enumerate(group[1]):
+                    assert chunk[2] == 0, (path.name, 'deprecated file_offset must be zero')
+                    column = chunk[3]
+                    assert column[12][7] is True and column[12][8] is True, (path.name, "exact bounds")
+                    reference = metadata.row_group(rg).column(col)
+                    assert reference.compression.lower() == codec, (path.name, reference.compression)
+                    offset = column[9]
+                    header, header_length = thrift_at(raw, offset)
+                    assert header[1] == (0 if version == 'v1' else 3), path.name
+                    page_end = offset + header_length + header[3]
+                    page_ends.append(page_end)
+                    assert page_end - offset == column[7], (path.name, 'compressed size')
+                    assert header_length + header[2] == column[6], (path.name, 'uncompressed size')
+                    assert (14 in column and 15 in column) == (col == 1), (path.name, 'bloom')
+                    assert reference.has_offset_index == indexed and reference.has_column_index == indexed, path.name
+                    assert all((field in chunk) == indexed for field in (4,5,6,7)), (path.name, chunk)
+                    if not indexed:
+                        continue
+                    # ColumnChunk IDs: offset index=(4,5), column index=(6,7).
+                    offset_index, used = thrift_at(raw, chunk[4])
+                    assert used == chunk[5] and offset_index[1] == [{1: offset, 2: page_end-offset, 3: 0}], path.name
+                    column_index, used = thrift_at(raw, chunk[6])
+                    assert used == chunk[7] and column_index[1] == [False], path.name
+                    assert column_index[5] == [int(nullable and col == 1)], path.name
+                    width = 4 if col == 0 else 8
+                    assert column_index[2] == [(1 if col == 0 else 10).to_bytes(width, 'little', signed=True)], path.name
+                    assert column_index[3] == [(3 if col == 0 else 30).to_bytes(width, 'little', signed=True)], path.name
+                    assert page_end <= chunk[4] < chunk[6] < footer_start, path.name
+            assert max(page_ends) <= footer_start
+            print('PASS', path.name)
+        print('32 files: values verified in PyArrow, DuckDB and Polars; page versions, codecs, blooms and indexes independently checked')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/verify_parquet_decimal_capacity.py b/scripts/verify_parquet_decimal_capacity.py
new file mode 100644
--- /dev/null
+++ b/scripts/verify_parquet_decimal_capacity.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Prove the bounded DECIMAL-capacity arithmetic in Parquet.Decimal.
+
+Only exact integer/Fraction arithmetic is used. The logarithm bounds come
+from convergent atanh series with geometric tail bounds. Farey neighbors
+then rule out every floor ambiguity for the full signed32-bit width domain.
+No runtime decimal precision or byte-width limit is substituted for the spec.
+"""
+from dataclasses import dataclass
+from fractions import Fraction
+import json
+from pathlib import Path
+import re
+
+
+@dataclass(frozen=True)
+class Bounds:
+    lower: Fraction
+    upper: Fraction
+
+
+def logarithm_bounds(x, terms):
+    total = Fraction(0)
+    for k in range(terms):
+        total += 2 * x ** (2 * k + 1) / (2 * k + 1)
+    tail = 2 * x ** (2 * terms + 1) / ((2 * terms + 1) * (1 - x * x))
+    return Bounds(total, total + tail)
+
+
+def verify():
+    source = (Path(__file__).resolve().parents[1] / "src/Parquet/Decimal.hs").read_text()
+    assert re.search(r"decimalPrecisionFits\s*::\s*Int32\s*->\s*Int32\s*->\s*Bool", source)
+    numerator = int(re.search(r"log10TwoLowerNumerator\s*=\s*(\d+)", source).group(1))
+    denominator = int(re.search(r"log10TwoDenominator\s*=\s*(\d+)", source).group(1))
+    ln2 = logarithm_bounds(Fraction(1, 3), 100)
+    ln_five_fourths = logarithm_bounds(Fraction(1, 9), 100)
+    exact_lower = ln2.lower / (3 * ln2.lower + ln_five_fourths.upper)
+    exact_upper = ln2.upper / (3 * ln2.upper + ln_five_fourths.lower)
+    lower = Fraction(numerator, denominator)
+    upper = Fraction(numerator + 1, denominator)
+    assert lower < exact_lower < exact_upper < upper
+    left = Fraction(5107137094, 16965542197)
+    right = Fraction(579001193, 1923400330)
+    maximum_bits = 8 * ((1 << 31) - 1) - 1
+    assert left < lower < upper < right
+    assert right.numerator * left.denominator - left.numerator * right.denominator == 1
+    assert left.denominator + right.denominator > maximum_bits
+    # Every interior k/n has n >= b+d. Thus no integer boundary can
+    # separate n*lower from n*upper in the entire admitted width domain.
+    for width in range(1, 4097):
+        bits = 8 * width - 1
+        actual = bits * numerator // denominator
+        # Independent exact powers, bounded to 4KiB integers in this check.
+        assert 10 ** actual <= 2 ** bits < 10 ** (actual + 1)
+    return {"log_bounds_proved": True, "farey_floor_certificate_proved": True,
+            "full_width_domain_max": (1 << 31) - 1, "maximum_bits": maximum_bits,
+            "small_width_exact_power_checks": 4096,
+            "minimum_interior_denominator": left.denominator + right.denominator}
+
+
+if __name__ == "__main__":
+    print(json.dumps(verify(), indent=2))
diff --git a/src/Parquet.hs b/src/Parquet.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet.hs
@@ -0,0 +1,29 @@
+{- | Public Parquet codec surface: file IO, Arrow conversion, and record derivation.
+Specialized page, metadata, encoding, and encryption APIs live in @Parquet.*@.
+-}
+module Parquet (
+  module Parquet.HighLevel,
+  module Parquet.Arrow,
+  module Parquet.Derive,
+  module Parquet.Types,
+  module Parquet.Timestamp,
+  module Parquet.File,
+  module Parquet.Variant,
+  module Parquet.Variant.Parquet,
+  module Parquet.Variant.Schema,
+  module Parquet.Variant.Shred,
+  module Parquet.Variant.Arrow,
+) where
+
+import Parquet.Arrow
+import Parquet.Derive
+import Parquet.File
+import Parquet.HighLevel
+import Parquet.Timestamp
+import Parquet.Types
+import Parquet.Variant
+import Parquet.Variant.Arrow
+import Parquet.Variant.Parquet
+import Parquet.Variant.Schema
+import Parquet.Variant.Shred
+
diff --git a/src/Parquet/Aggregate.hs b/src/Parquet/Aggregate.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Aggregate.hs
@@ -0,0 +1,201 @@
+{-# LANGUAGE LambdaCase #-}
+
+{- | Aggregate pushdown for Parquet.
+
+Many analytical queries reduce to one of:
+
+  * @count(*)@ — number of rows in the whole file.
+  * @count(col)@ — number of non-null rows in a column.
+  * @min/max(col)@ — exact extrema of a column's defined values.
+
+Counts and exact extrema can be answered from validated footer metadata
+when the necessary statistics are available. Compact bounds are useful
+for pruning, but cannot establish an exact aggregate. Floating-point
+extrema require a known zero NaN count; scan when another NaN policy is
+needed. Repeated leaves cannot supply a non-null /row/ count.
+
+These functions trust the supplied statistics after checking their shape;
+callers needing to verify a writer's claims must scan the data.
+-}
+module Parquet.Aggregate (
+  -- * count(*)
+  fileRowCount,
+  fileRowCountChecked,
+  rowGroupRowCount,
+
+  -- * count(col)
+  columnNonNullCount,
+
+  -- * min / max
+  columnMin,
+  columnMax,
+
+  -- * Note on @sum(col)@
+  -- $sum
+) where
+
+-- \$sum
+--
+-- Parquet's @Statistics@ message intentionally doesn't carry
+-- per-row-group sums (the spec authors decided sums are too
+-- easy to overflow + lose precision to be safely cached). To
+-- compute @sum(col)@ from a Parquet file you have to scan the
+-- column values; there is no pushdown helper.
+--
+-- ORC /does/ carry @IntegerStatistics.sum@ — see
+-- "ORC.Aggregate.columnSum" for the parallel helper that
+-- works with ORC files.
+
+import Columnar.Predicate qualified as Pred
+import Control.Monad (guard)
+import Data.Int (Int64)
+import Data.Vector qualified as V
+import Parquet.Levels qualified as Levels
+import Parquet.Predicate qualified as PPred
+import Parquet.Types qualified as P
+
+
+{- | Sum of the row-group counts, retaining compatibility with older files
+whose file-wide total is stale. Negative or overflowing group counts raise
+an error; 'fileRowCountChecked' safely checks both the groups and file total.
+-}
+fileRowCount :: P.FileMetadata -> Int64
+fileRowCount = maybe (error "Parquet.Aggregate: negative or overflowing row counts") id . rowGroupSum
+
+
+-- | Reject negative, overflowing or inconsistent file/row-group counts.
+fileRowCountChecked :: P.FileMetadata -> Maybe Int64
+fileRowCountChecked fm = do
+  total <- rowGroupSum fm
+  guard (total == P.fmNumRows fm)
+  Just total
+
+
+rowGroupSum :: P.FileMetadata -> Maybe Int64
+rowGroupSum fm = V.foldM addRows 0 (P.fmRowGroups fm)
+  where
+    addRows total group = do
+      let rows = P.rgNumRows group
+      guard (rows >= 0 && rows <= maxBound - total)
+      Just (total + rows)
+
+
+-- | Row count of one row group.
+rowGroupRowCount :: P.RowGroup -> Int64
+rowGroupRowCount = P.rgNumRows
+
+
+{- | @count(col)@ — non-null rows for a non-repeated leaf, including
+nullable ancestors. Returns 'Nothing' for repeated paths, missing counts,
+or inconsistent metadata. Definition events equal rows only for paths
+without repeated ancestors.
+-}
+columnNonNullCount :: P.FileMetadata -> Int -> Maybe Int64
+columnNonNullCount fm colIdx = do
+  _ <- fileRowCountChecked fm
+  context <- PPred.statisticsContext fm colIdx
+  V.foldM (step context) 0 (P.fmRowGroups fm)
+  where
+    step context acc group = do
+      column <- P.rgColumns group V.!? colIdx
+      metadata <- P.ccMetadata column
+      guard (P.seType (PPred.statisticsField context) == Just (P.cmType metadata))
+      (maxRep, maxDef) <-
+        either
+          (const Nothing)
+          Just
+          (Levels.maxLevelsForColumnPath (P.fmSchema fm) (P.cmPathInSchema metadata))
+      guard (maxRep == 0 && P.cmNumValues metadata == P.rgNumRows group)
+      if P.rgNumRows group == 0
+        then Just acc
+        else do
+          statistics <- P.cmStatistics metadata
+          nulls <- P.statNullCount statistics
+          guard (nulls >= 0 && nulls <= P.rgNumRows group && (maxDef /= 0 || nulls == 0))
+          let present = P.rgNumRows group - nulls
+          guard (acc <= maxBound - present)
+          Just (acc + present)
+
+
+{- | Minimum value of a column across the whole file. Reads
+each row group's @min_value@ (or legacy @min@) statistic
+and folds them under the 'PValue' ordering. Returns
+'Nothing' if /any/ contributing row group lacks min stats —
+otherwise the result might be the min over a strict subset
+of the row groups.
+-}
+columnMin :: P.FileMetadata -> Int -> Maybe Pred.PValue
+columnMin = aggCmp takeMinStat (\acc v -> if Pred.pvLess v acc then v else acc)
+
+
+{- | Maximum value of a column across the whole file. Same
+soundness rule as 'columnMin': any row group without max
+stats poisons the result to 'Nothing'.
+-}
+columnMax :: P.FileMetadata -> Int -> Maybe Pred.PValue
+columnMax = aggCmp takeMaxStat (\acc v -> if Pred.pvLess acc v then v else acc)
+
+
+{- | Common driver for column-wise stat aggregation. Polls the
+supplied stat extractor on every row group; if any returns
+'Nothing' the whole result is 'Nothing' (we can't be sound
+about a min / max otherwise).
+-}
+aggCmp
+  :: (PPred.StatisticsContext -> P.Statistics -> Maybe Pred.PValue)
+  -> (Pred.PValue -> Pred.PValue -> Pred.PValue)
+  -> P.FileMetadata
+  -> Int
+  -> Maybe Pred.PValue
+aggCmp takeStat combine fm colIdx = do
+  _ <- fileRowCountChecked fm
+  context <- PPred.statisticsContext fm colIdx
+  V.foldM (step context) Nothing (P.fmRowGroups fm) >>= id
+  where
+    step context acc group = do
+      column <- P.rgColumns group V.!? colIdx
+      metadata <- P.ccMetadata column
+      guard (P.seType (PPred.statisticsField context) == Just (P.cmType metadata))
+      (maxRep, _) <-
+        either
+          (const Nothing)
+          Just
+          (Levels.maxLevelsForColumnPath (P.fmSchema fm) (P.cmPathInSchema metadata))
+      guard
+        ( if maxRep == 0
+            then P.cmNumValues metadata == P.rgNumRows group
+            else P.cmNumValues metadata >= P.rgNumRows group
+        )
+      if P.rgNumRows group == 0
+        then do
+          guard (P.cmNumValues metadata == 0)
+          Just acc
+        else do
+          statistics <- P.cmStatistics metadata
+          guard (maybe True (\n -> n >= 0 && n <= P.cmNumValues metadata) (P.statNullCount statistics))
+          if P.statNullCount statistics == Just (P.cmNumValues metadata)
+            then Just acc
+            else do
+              guard (nanFree (PPred.statisticsField context) statistics)
+              value <- takeStat context statistics
+              Just (Just (maybe value (`combine` value) acc))
+
+    nanFree field statistics
+      | P.seType field `elem` [Just P.PTFloat, Just P.PTDouble]
+          || P.seLogicalType field == Just P.LTFloat16 =
+          P.statNanCount statistics == Just 0
+      | otherwise = True
+
+
+takeMinStat :: PPred.StatisticsContext -> P.Statistics -> Maybe Pred.PValue
+takeMinStat context statistics =
+  PPred.minimumStatistic
+    context
+    (if P.statMinValueExact statistics == Just True then statistics else statistics {P.statMinValue = Nothing})
+
+
+takeMaxStat :: PPred.StatisticsContext -> P.Statistics -> Maybe Pred.PValue
+takeMaxStat context statistics =
+  PPred.maximumStatistic
+    context
+    (if P.statMaxValueExact statistics == Just True then statistics else statistics {P.statMaxValue = Nothing})
diff --git a/src/Parquet/Alp.hs b/src/Parquet/Alp.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Alp.hs
@@ -0,0 +1,255 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | Adaptive Lossless floating-Point page decoding (encoding 10).
+
+The layout and two-step decimal reconstruction follow Apache Parquet's
+AlpEncoding.md. Validation precedes output allocation. Exceptions are copied
+as IEEE bits, including negative zero and noncanonical NaN payloads.
+-}
+module Parquet.Alp (decodeAlpFloat, decodeAlpDouble) where
+
+import Columnar.SIMD qualified as SIMD
+import Data.Bits (shiftL, shiftR, (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Internal qualified as BSI
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Int (Int32)
+import Data.Primitive.Types (Prim)
+import Data.Vector.Primitive qualified as P
+import Data.Vector.Primitive.Mutable qualified as M
+import Data.Word (Word16, Word32, Word64, byteSwap16, byteSwap32, byteSwap64)
+import Foreign.Ptr (castPtr, plusPtr)
+import Foreign.Storable (peekByteOff)
+import GHC.ByteOrder (ByteOrder (LittleEndian), targetByteOrder)
+import GHC.ForeignPtr (unsafeWithForeignPtr)
+import System.IO.Unsafe (unsafeDupablePerformIO)
+
+
+decodeAlpFloat :: Int -> ByteString -> Either String (P.Vector Float)
+decodeAlpFloat = decodeAlp 4 10
+{-# INLINE decodeAlpFloat #-}
+
+
+decodeAlpDouble :: Int -> ByteString -> Either String (P.Vector Double)
+decodeAlpDouble = decodeAlp 8 18
+{-# INLINE decodeAlpDouble #-}
+
+
+data PageInfo = PageInfo
+  { pageVectorSize :: {-# UNPACK #-} !Int
+  , pageVectors :: {-# UNPACK #-} !Int
+  }
+
+
+data VectorInfo = VectorInfo
+  { vectorExponent :: {-# UNPACK #-} !Int
+  , vectorFactor :: {-# UNPACK #-} !Int
+  , vectorExceptions :: {-# UNPACK #-} !Int
+  , vectorFrame :: {-# UNPACK #-} !Word64
+  , vectorWidth :: {-# UNPACK #-} !Int
+  , vectorPacked :: {-# UNPACK #-} !Int
+  , vectorPositions :: {-# UNPACK #-} !Int
+  , vectorValues :: {-# UNPACK #-} !Int
+  , vectorEnd :: {-# UNPACK #-} !Int
+  }
+
+
+decodeAlp :: Prim a => Int -> Int -> Int -> ByteString -> Either String (P.Vector a)
+decodeAlp width maxExponent count bytes = do
+  page <- validatePage width maxExponent count bytes
+  -- Source ownership spans every bounded unsafe call. The output remains a
+  -- movable array: each call receives its current ByteArray# directly, and
+  -- no raw destination pointer survives a GC point between chunks.
+  Right $ unsafeDupablePerformIO $ BSU.unsafeUseAsCString bytes $ \rawInput -> do
+    output@(M.MVector _ _ array) <- M.unsafeNew count
+    let input = castPtr rawInput
+        chunkLimit = SIMD.unsafeCallBytes `quot` width
+        exceptionLimit = SIMD.unsafeCallBytes `quot` (width + 2)
+        vectors !index !written
+          | index == pageVectors page = P.unsafeFreeze output
+          | otherwise = do
+              let !offset = 7 + fromIntegral (readLE bytes (7 + index * 4) 4)
+                  !size = min (pageVectorSize page) (count - written)
+                  info = inspectVector width bytes offset size
+                  !packed = input `plusPtr` vectorPacked info
+                  !packedSize = vectorPositions info - vectorPacked info
+                  !bits = vectorWidth info
+                  !e = vectorExponent info
+                  !f = vectorFactor info
+                  values !first
+                    | first == size = pure ()
+                    | otherwise = do
+                        let !n = min chunkLimit (size - first)
+                            !destination = (written + first) * width
+                        if width == 4
+                          then SIMD.unpackFloat32Array (SIMD.PackedFloat32 bits (fromIntegral (vectorFrame info)) (positivePower f) (negativePower e)) packed packedSize array destination first n
+                          else SIMD.unpackFloat64Array (SIMD.PackedFloat64 bits (vectorFrame info) (positivePower f) (negativePower e)) packed packedSize array destination first n
+                        values (first + n)
+                  exceptions !first
+                    | first == vectorExceptions info = pure ()
+                    | otherwise = do
+                        let !n = min exceptionLimit (vectorExceptions info - first)
+                            !positions = input `plusPtr` (vectorPositions info + first * 2)
+                            !valuesPtr = input `plusPtr` (vectorValues info + first * width)
+                            !destination = written * width
+                        if width == 4
+                          then SIMD.scatterFloat32Array positions valuesPtr array destination size n
+                          else SIMD.scatterFloat64Array positions valuesPtr array destination size n
+                        exceptions (first + n)
+              values 0
+              exceptions 0
+              vectors (index + 1) (written + size)
+    vectors 0 0
+{-# INLINE decodeAlp #-}
+
+
+validatePage :: Int -> Int -> Int -> ByteString -> Either String PageInfo
+validatePage width maxExponent count bytes
+  | count < 0 || count > fromIntegral (maxBound :: Int32) = invalid "invalid value count"
+  | count > maxBound `quot` width = invalid "output exceeds addressable size"
+  | BS.length bytes < 7 = invalid "truncated page header"
+  | BSU.unsafeIndex bytes 0 /= 0 = invalid "unsupported compression mode"
+  | BSU.unsafeIndex bytes 1 /= 0 = invalid "unsupported integer encoding"
+  | logSize < 3 || logSize > 15 = invalid "invalid vector size"
+  | readLE bytes 3 4 /= fromIntegral count = invalid "value count differs from page header"
+  | vectorCount > (BS.length bytes - 7) `quot` 4 = invalid "truncated offset array"
+  | otherwise = do
+      vectors 0 0 (7 + vectorCount * 4)
+      Right (PageInfo vectorSize vectorCount)
+  where
+    logSize = fromIntegral (BSU.unsafeIndex bytes 2)
+    vectorSize = 1 `shiftL` logSize
+    vectorCount = if count == 0 then 0 else (count - 1) `quot` vectorSize + 1
+    vectors !index !written !expected
+      | index == vectorCount =
+          if expected == BS.length bytes then Right () else invalid "trailing page bytes"
+      | readLE bytes (7 + index * 4) 4 /= fromIntegral (expected - 7) =
+          invalid "vector offsets are not contiguous"
+      | BS.length bytes - expected < width + 5 = invalid "truncated vector header"
+      | otherwise = do
+          let !size = min vectorSize (count - written)
+              info = inspectVector width bytes expected size
+          if vectorExponent info > maxExponent || vectorFactor info > vectorExponent info
+            then invalid "invalid decimal parameters"
+            else Right ()
+          if vectorWidth info > width * 8
+            then invalid "invalid bit width"
+            else Right ()
+          if vectorEnd info > BS.length bytes
+            then invalid "truncated vector data"
+            else Right ()
+          let !usedBits = size * vectorWidth info
+              !padding = usedBits `rem` 8
+          if padding /= 0 && BSU.unsafeIndex bytes (vectorPositions info - 1) `shiftR` padding /= 0
+            then invalid "nonzero packed padding bits"
+            else Right ()
+          let positions !i
+                | i == vectorExceptions info = Right ()
+                | readLE bytes (vectorPositions info + i * 2) 2 >= fromIntegral size =
+                    invalid "exception position exceeds vector"
+                | otherwise = positions (i + 1)
+          positions 0
+          vectors (index + 1) (written + size) (vectorEnd info)
+
+
+-- Only called after checking the fixed header. Sizes are bounded by a
+-- 32768-element vector, byte-sized bit width, and uint16 exception count.
+inspectVector :: Int -> ByteString -> Int -> Int -> VectorInfo
+inspectVector width bytes offset size =
+  let !exceptions = fromIntegral (readLE bytes (offset + 2) 2)
+      !bits = fromIntegral (BSU.unsafeIndex bytes (offset + 4 + width))
+      !packed = offset + 5 + width
+      !positions = packed + (size * bits + 7) `quot` 8
+      !values = positions + exceptions * 2
+  in VectorInfo
+       (fromIntegral (BSU.unsafeIndex bytes offset))
+       (fromIntegral (BSU.unsafeIndex bytes (offset + 1)))
+       exceptions
+       (readLE bytes (offset + 4) width)
+       bits
+       packed
+       positions
+       values
+       (values + exceptions * width)
+{-# INLINE inspectVector #-}
+
+
+-- The caller has validated each complete field before reaching this helper.
+-- Reading whole unaligned words avoids rebuilding uint16 exception positions
+-- and uint32 offsets byte by byte. The ByteString owner stays live throughout
+-- each load; every access remains within the validated field itself.
+readLE :: ByteString -> Int -> Int -> Word64
+readLE bytes offset width = case BSI.toForeignPtr bytes of
+  (owner, base, _) -> BSI.accursedUnutterablePerformIO $ unsafeWithForeignPtr owner $ \input ->
+    let fieldOffset = base + offset
+    in case width of
+         2 -> do
+           value <- peekByteOff input fieldOffset :: IO Word16
+           pure (fromIntegral (if targetByteOrder == LittleEndian then value else byteSwap16 value))
+         4 -> do
+           value <- peekByteOff input fieldOffset :: IO Word32
+           pure (fromIntegral (if targetByteOrder == LittleEndian then value else byteSwap32 value))
+         8 -> do
+           value <- peekByteOff input fieldOffset :: IO Word64
+           pure (if targetByteOrder == LittleEndian then value else byteSwap64 value)
+         _ -> pure (go 0 0)
+  where
+    go !i !acc
+      | i == width = acc
+      | otherwise = go (i + 1) (acc .|. (fromIntegral (BSU.unsafeIndex bytes (offset + i)) `shiftL` (i * 8)))
+{-# INLINE readLE #-}
+
+
+-- Literal conversion supplies correctly rounded binary32/binary64 values.
+-- Runtime exponentiation and combining the two powers are not conformant.
+positivePower :: Fractional a => Int -> a
+positivePower n = case n of
+  0 -> 1e0
+  1 -> 1e1
+  2 -> 1e2
+  3 -> 1e3
+  4 -> 1e4
+  5 -> 1e5
+  6 -> 1e6
+  7 -> 1e7
+  8 -> 1e8
+  9 -> 1e9
+  10 -> 1e10
+  11 -> 1e11
+  12 -> 1e12
+  13 -> 1e13
+  14 -> 1e14
+  15 -> 1e15
+  16 -> 1e16
+  17 -> 1e17
+  _ -> 1e18
+{-# INLINE positivePower #-}
+
+
+negativePower :: Fractional a => Int -> a
+negativePower n = case n of
+  0 -> 1e0
+  1 -> 1e-1
+  2 -> 1e-2
+  3 -> 1e-3
+  4 -> 1e-4
+  5 -> 1e-5
+  6 -> 1e-6
+  7 -> 1e-7
+  8 -> 1e-8
+  9 -> 1e-9
+  10 -> 1e-10
+  11 -> 1e-11
+  12 -> 1e-12
+  13 -> 1e-13
+  14 -> 1e-14
+  15 -> 1e-15
+  16 -> 1e-16
+  17 -> 1e-17
+  _ -> 1e-18
+{-# INLINE negativePower #-}
+
+
+invalid :: String -> Either String a
+invalid message = Left ("Parquet.Alp: " <> message)
diff --git a/src/Parquet/Arrow.hs b/src/Parquet/Arrow.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Arrow.hs
@@ -0,0 +1,2552 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Arrow ↔ Parquet column-data bridge.
+
+Lets callers keep a single in-memory representation
+('Arrow.Column.ColumnArray') and choose Parquet at the wire-
+format level, mirroring how
+@pyarrow.parquet.write_table(table, path)@ works in Python: a
+'pa.Table' goes in, Parquet bytes come out.
+
+@
+-- Arrow → Parquet
+let !(schema, rowGroups) = 'arrowToParquet' arrowSchema arrowBatches
+    bytes                = 'Parquet.HighLevel.encodeParquet'
+                             'Parquet.HighLevel.defaultWriteOptions'
+                             schema rowGroups
+
+-- Parquet → Arrow (one row group at a time)
+pf <- 'Parquet.HighLevel.decodeParquet' bytes
+batch <- 'parquetRowGroupToArrow' arrowSchema pf 0
+@
+
+The bridge currently covers the flat-primitive shape Parquet's
+writer ('Parquet.Write.ColumnData') natively supports: 'Int8',
+'Int16', 'Int32', 'Int64', 'UInt8'..'UInt64', 'Float', 'Double',
+'Bool', 'Utf8', 'Binary', plus their nullable variants. Use the
+"Parquet.Nested" writer helpers for structs, lists and maps. The
+reader reconstructs those containers from physical schema paths and
+Dremel levels, including legacy list layouts and nullable ancestors.
+-}
+module Parquet.Arrow (
+  -- * Arrow → Parquet (flat, required + nullable)
+  arrowToParquet,
+  arrowToParquetMixed,
+  columnArrayToColumnData,
+  columnArrayToParquetColumn,
+
+  -- * Arrow → Parquet (nested, via Parquet.Nested)
+  arrowFieldToNestedSchema,
+  columnArrayToNestedRows,
+
+  -- * Parquet → Arrow
+  parquetRowGroupToArrow,
+  ReadLimits (..),
+  defaultReadLimits,
+  parquetRowGroupToArrowWithLimits,
+  parquetRowGroupToArrowProjected,
+  readParquetColumn,
+  parquetFileArrowSchema,
+  parquetFileArrowSchemaChecked,
+  ProjectionError (..),
+
+  -- * Streaming reader (one row group at a time)
+  streamRowGroups,
+  streamRowGroupsIter,
+  streamRowGroupsProjectedIter,
+  streamRowGroupsFilteredIter,
+  streamRowGroupsProjectedFilteredIter,
+  numRowGroups,
+
+  -- * Page-index-driven page skipping
+  readParquetColumnWithPagePruning,
+) where
+
+import Arrow.Column qualified as AC
+import Arrow.Column.Buffer qualified as Buffer
+import Arrow.Types qualified as AT
+import Arrow.Write.Columns (validateColumns)
+import Columnar.Stream qualified as IS
+import Control.Monad.ST (runST)
+import Data.Bits (shiftL, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString.Internal qualified as BSI
+import Data.ByteString qualified as BS
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Int (Int32, Int64)
+import Data.IntMap.Strict qualified as IntMap
+import Data.Map.Strict qualified as Map
+import Data.Primitive.ByteArray (copyByteArrayToAddr)
+import Data.Text (Text)
+import Data.Text qualified as T
+import Data.Vector qualified as V
+import Data.Vector.Mutable qualified as VM
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Primitive.Mutable qualified as VPM
+import Data.Vector.Storable qualified as VS
+import Data.Vector.Storable.Mutable qualified as VSM
+import Data.Word (byteSwap64, Word16, Word32, Word64, Word8)
+import Foreign.Ptr (castPtr)
+import Foreign.Storable (pokeByteOff, Storable, sizeOf)
+import GHC.ByteOrder (ByteOrder (..), targetByteOrder)
+import GHC.Exts (Int (I#), Int#, (+#))
+import Parquet.Arrow.Geospatial qualified as Geo
+import Parquet.Arrow.File qualified as FileArrow
+import Parquet.File qualified as File
+import Parquet.Arrow.Nested qualified as AN
+import Parquet.Levels qualified as Levels
+import Parquet.Nested qualified as PN
+import Parquet.Nested.Generate qualified as Generate
+import Parquet.Page qualified as Page
+import Parquet.PageIndex qualified as PI
+import Parquet.Predicate qualified as Pred
+import Parquet.Read qualified as PR
+import Parquet.Types qualified as P
+import Parquet.Timestamp.Internal qualified as Timestamp
+import Parquet.Write qualified as PW
+import Parquet.Variant.Schema qualified as VariantSchema
+import Parquet.Variant.Array qualified as VariantArray
+import System.IO.Unsafe (unsafeDupablePerformIO)
+
+
+-- ============================================================
+-- Arrow → Parquet
+-- ============================================================
+
+{- | Lower an Arrow schema + a sequence of column-major batches
+to the inputs 'Parquet.HighLevel.encodeParquet' expects.
+
+Each Arrow batch becomes one Parquet row group. Returns 'Left'
+if any column type isn't representable in Parquet's flat data
+plane (struct / list / dictionary / view / REE — see the
+module docs for the supported subset), the batch disagrees with the
+schema, or a column contains nulls. This dense path writes required
+fields even when an input field permits nulls; use
+'arrowToParquetMixed' to preserve nullable schema declarations.
+-}
+arrowToParquet
+  :: AT.Schema
+  -> [V.Vector AC.ColumnArray]
+  -> Either String (V.Vector P.SchemaElement, [V.Vector PW.ColumnData])
+arrowToParquet sch batches = do
+  mapM_ (validateColumns (AT.arrowFields sch)) batches
+  mapM_ (V.mapM_ rejectNulls) batches
+  let !leafFields = AT.arrowFields sch
+      !rootElem =
+        P.SchemaElement
+          { P.seTypeLength = Nothing
+          , P.seName = "schema"
+          , P.seRepetition = Nothing
+          , P.seType = Nothing
+          , P.seNumChildren = Just (fromIntegral (V.length leafFields))
+          , P.seConvertedType = Nothing
+          , P.seLogicalType = Nothing
+          , P.seFieldId = Nothing
+          }
+  schemaElems <- V.mapM (\field -> arrowFieldToSchemaElement field {AT.fieldNullable = False}) leafFields
+  let !pSchema = V.cons rootElem schemaElems
+  rgData <-
+    mapM
+      ( V.zipWithM
+          (\field col -> normalizeTemporal field col >>= columnArrayToColumnData)
+          leafFields
+      )
+      batches
+  Right (pSchema, rgData)
+  where
+    rejectNulls col
+      | AC.nullCount col == 0 = Right ()
+      | otherwise = Left "Parquet.Arrow.arrowToParquet: use arrowToParquetMixed to preserve null values"
+
+
+{- | Like 'arrowToParquet' but returns 'PW.ParquetColumn' values
+so nullable Arrow columns lower to 'PW.PCOptional' instead of
+being dropped through 'optionalColumnPresentValues'. Pair with
+'Parquet.HighLevel.encodeParquetMixed' to write a Parquet file
+that carries the nulls and definition levels.
+-}
+arrowToParquetMixed
+  :: AT.Schema
+  -> [V.Vector AC.ColumnArray]
+  -> Either String (V.Vector P.SchemaElement, [V.Vector PW.ParquetColumn])
+arrowToParquetMixed sch batches = do
+  mapM_ (validateColumns (AT.arrowFields sch)) batches
+  let !leafFields = AT.arrowFields sch
+      !rootElem =
+        P.SchemaElement
+          { P.seTypeLength = Nothing
+          , P.seName = "schema"
+          , P.seRepetition = Nothing
+          , P.seType = Nothing
+          , P.seNumChildren = Just (fromIntegral (V.length leafFields))
+          , P.seConvertedType = Nothing
+          , P.seLogicalType = Nothing
+          , P.seFieldId = Nothing
+          }
+  schemaElems <- V.mapM arrowFieldToSchemaElement leafFields
+  let !pSchema = V.cons rootElem schemaElems
+  rgData <- mapM (V.zipWithM columnArrayToParquetColumn leafFields) batches
+  Right (pSchema, rgData)
+
+
+{- | Dispatch a single Arrow column onto the 'PW.ParquetColumn'
+sum, driven by the schema field: a nullable field maps to
+'PW.PCOptional' (definition levels carry the nulls), a required
+field reuses 'columnArrayToColumnData' and wraps the result in
+'PW.PCRequired'. A column holding nulls under a required field is
+a 'Left': the Parquet schema element would claim every value is
+present.
+-}
+columnArrayToParquetColumn
+  :: AT.Field -> AC.ColumnArray -> Either String PW.ParquetColumn
+columnArrayToParquetColumn fld input = do
+  validateColumns (V.singleton fld) (V.singleton input)
+  col <- normalizeTemporal fld input
+  columnArrayToParquetColumnRaw fld col
+
+
+columnArrayToParquetColumnRaw :: AT.Field -> AC.ColumnArray -> Either String PW.ParquetColumn
+columnArrayToParquetColumnRaw fld col
+  | not (AT.fieldNullable fld) =
+      if AC.nullCount col > 0
+        then
+          Left $
+            "Parquet.Arrow: column "
+              <> show (AT.fieldName fld)
+              <> " has "
+              <> show (AC.nullCount col)
+              <> " nulls but its field is not nullable"
+        else PW.PCRequired <$> columnArrayToColumnData col
+  | otherwise = PW.PCOptional <$> columnArrayToOptionalColumn col
+
+
+-- Parquet DATE is INT32 days; TIME/TIMESTAMP have no second unit.
+-- Normalize the payload together with its annotation, rejecting lossy or
+-- overflowing conversions. Null slots have no value and are ignored.
+normalizeTemporal :: AT.Field -> AC.ColumnArray -> Either String AC.ColumnArray
+normalizeTemporal field column = case (AT.fieldType field, column) of
+  (AT.ADate AT.DateMillisecond, AC.ColDate64 validity values) ->
+    checkedTemporal AC.PDate32 validDay (fromIntegral . (`quot` dayMillis)) validity values
+  (AT.ATime AT.Second 32, AC.ColTime32 validity values) ->
+    checkedTemporal AC.PTime32 (withinDay 86400) (* 1000) validity values
+  (AT.ATime AT.Millisecond 32, AC.ColTime32 validity values) ->
+    checkTime 86400000 validity values
+  (AT.ATime AT.Microsecond 64, AC.ColTime64 validity values) ->
+    checkTime 86400000000 validity values
+  (AT.ATime AT.Nanosecond 64, AC.ColTime64 validity values) ->
+    checkTime 86400000000000 validity values
+  (AT.ATime _ _, _) -> Left "Parquet.Arrow: invalid time unit/bit-width combination"
+  (AT.ATimestamp AT.Second _, AC.ColTimestamp validity values) ->
+    checkedTemporal
+      AC.PTimestamp
+      (\value -> value >= (minBound :: Int64) `quot` 1000 && value <= (maxBound :: Int64) `quot` 1000)
+      (* 1000)
+      validity
+      values
+  (AT.ADuration _, _) -> Left "Parquet.Arrow: duration has no standard Parquet logical type"
+  _ -> Right column
+  where
+    dayMillis = 86400000 :: Int64
+    validDay value =
+      let (days, remainder) = value `quotRem` dayMillis
+      in remainder == 0
+           && days >= fromIntegral (minBound :: Int32)
+           && days <= fromIntegral (maxBound :: Int32)
+    withinDay limit value = value >= 0 && value < limit
+    checkTime limit validity values
+      | VS.ifoldl' (\ok i value -> ok && (not (AC.isValidAt validity i) || withinDay limit value)) True values = Right column
+      | otherwise = Left "Parquet.Arrow: time is outside one day"
+
+
+checkedTemporal
+  :: (Storable a, Storable b)
+  => AC.PrimType b
+  -> (a -> Bool)
+  -> (a -> b)
+  -> Maybe AC.Validity
+  -> VS.Vector a
+  -> Either String AC.ColumnArray
+checkedTemporal tag valid convert validity values
+  | VS.ifoldl' (\ok i value -> ok && (not (AC.isValidAt validity i) || valid value)) True values =
+      AC.mkPrim tag validity (VS.map convert values)
+  | otherwise = Left "Parquet.Arrow: temporal conversion loses precision or exceeds its range"
+
+
+{- | Lower one Arrow column to Parquet's nullable column shape.
+Narrow and unsigned integers widen to INT32 / INT64 as in
+'columnArrayToColumnData'; temporal columns use their integer
+payload. Parquet's optional writer takes boxed @Maybe@ vectors, so
+this is one boxing pass per column.
+-}
+columnArrayToOptionalColumn
+  :: AC.ColumnArray -> Either String PW.OptionalColumn
+columnArrayToOptionalColumn = \case
+  AC.ColInt8 mv xs -> Right $ PW.OptInt32 (maybeVector fromIntegral mv xs)
+  AC.ColInt16 mv xs -> Right $ PW.OptInt32 (maybeVector fromIntegral mv xs)
+  AC.ColInt32 mv xs -> Right $ PW.OptInt32 (maybeVector id mv xs)
+  AC.ColInt64 mv xs -> Right $ PW.OptInt64 (maybeVector id mv xs)
+  AC.ColUInt8 mv xs -> Right $ PW.OptInt32 (maybeVector (fromIntegral :: Word8 -> Int32) mv xs)
+  AC.ColUInt16 mv xs -> Right $ PW.OptInt32 (maybeVector (fromIntegral :: Word16 -> Int32) mv xs)
+  AC.ColUInt32 mv xs -> Right $ PW.OptInt32 (maybeVector (fromIntegral :: Word32 -> Int32) mv xs)
+  AC.ColUInt64 mv xs -> Right $ PW.OptInt64 (maybeVector (fromIntegral :: Word64 -> Int64) mv xs)
+  AC.ColFloat mv xs -> Right $ PW.OptFloat (maybeVector id mv xs)
+  AC.ColDouble mv xs -> Right $ PW.OptDouble (maybeVector id mv xs)
+  AC.ColDate32 mv xs -> Right $ PW.OptInt32 (maybeVector id mv xs)
+  AC.ColDate64 mv xs -> Right $ PW.OptInt64 (maybeVector id mv xs)
+  AC.ColTime32 mv xs -> Right $ PW.OptInt32 (maybeVector id mv xs)
+  AC.ColTime64 mv xs -> Right $ PW.OptInt64 (maybeVector id mv xs)
+  AC.ColTimestamp mv xs -> Right $ PW.OptInt64 (maybeVector id mv xs)
+  AC.ColDuration mv xs -> Right $ PW.OptInt64 (maybeVector id mv xs)
+  col
+    | Just ba <- AC.asBool col ->
+        Right $ PW.OptBool (V.generate (AC.columnLength col) (AC.boolArrayAt ba))
+    | Just ba <- AC.asBinary col ->
+        Right $ PW.OptByteArray (V.generate (AC.bytesArrayLength ba) (AC.unsafeBytesAt ba))
+    | Just ba <- AC.asLargeBinary col ->
+        Right $ PW.OptByteArray (V.generate (AC.bytesArrayLength ba) (AC.unsafeBytesAt ba))
+    | otherwise -> Left (noFlatEquivalent col)
+
+
+{- | Translate an Arrow leaf 'Field' into a Parquet
+'SchemaElement'.
+-}
+arrowFieldToSchemaElement
+  :: AT.Field -> Either String P.SchemaElement
+arrowFieldToSchemaElement f = do
+  pType <- case AT.fieldType f of
+    AT.AInt 8 _ -> Right P.PTInt32
+    AT.AInt 16 _ -> Right P.PTInt32
+    AT.AInt 32 _ -> Right P.PTInt32
+    AT.AInt 64 _ -> Right P.PTInt64
+    AT.ABool -> Right P.PTBoolean
+    AT.AFloatingPoint AT.Half -> Right P.PTFixedLenByteArray
+    AT.AFloatingPoint AT.Single -> Right P.PTFloat
+    AT.AFloatingPoint AT.DoublePrecision -> Right P.PTDouble
+    AT.AUtf8 -> Right P.PTByteArray
+    AT.ABinary -> Right P.PTByteArray
+    AT.ALargeUtf8 -> Right P.PTByteArray
+    AT.ALargeBinary -> Right P.PTByteArray
+    -- Dates normalize to INT32 days and seconds normalize to milliseconds.
+    AT.ADate AT.DateDay -> Right P.PTInt32
+    AT.ADate AT.DateMillisecond -> Right P.PTInt32
+    AT.ATime AT.Second 32 -> Right P.PTInt32
+    AT.ATime AT.Millisecond 32 -> Right P.PTInt32
+    AT.ATime AT.Microsecond 64 -> Right P.PTInt64
+    AT.ATime AT.Nanosecond 64 -> Right P.PTInt64
+    AT.ATimestamp _ _ -> Right P.PTInt64
+    other ->
+      Left $
+        "Parquet.Arrow: Arrow type "
+          <> show other
+          <> " has no Parquet flat-primitive equivalent"
+  geospatial <- Geo.fromArrowField f
+  let !rep = if AT.fieldNullable f then P.Optional else P.Required
+      !logical = case geospatial of
+        Just annotation -> Just annotation
+        Nothing -> baseLogical
+      baseLogical = case AT.fieldType f of
+        AT.AFloatingPoint AT.Half -> Just P.LTFloat16
+        AT.AInt w signed -> Just (P.LTInteger (fromIntegral w) signed)
+        AT.AUtf8 -> Just (if isJsonField f then P.LTJson else P.LTString)
+        AT.ALargeUtf8 -> Just (if isJsonField f then P.LTJson else P.LTString)
+        AT.ADate _ -> Just P.LTDate
+        AT.ATime AT.Millisecond _ -> Just (P.LTTime False P.LtMillis)
+        AT.ATime AT.Microsecond _ -> Just (P.LTTime False P.LtMicros)
+        AT.ATime AT.Nanosecond _ -> Just (P.LTTime False P.LtNanos)
+        AT.ATime AT.Second _ -> Just (P.LTTime False P.LtMillis)
+        -- Parquet doesn't model second precision; widen.
+        AT.ATimestamp AT.Millisecond mtz ->
+          Just (P.LTTimestamp (isJustUtc mtz) P.LtMillis)
+        AT.ATimestamp AT.Microsecond mtz ->
+          Just (P.LTTimestamp (isJustUtc mtz) P.LtMicros)
+        AT.ATimestamp AT.Nanosecond mtz ->
+          Just (P.LTTimestamp (isJustUtc mtz) P.LtNanos)
+        AT.ATimestamp AT.Second mtz ->
+          Just (P.LTTimestamp (isJustUtc mtz) P.LtMillis)
+        _ -> Nothing
+      isJustUtc Nothing = False
+      isJustUtc (Just _) = True
+  Right
+    P.SchemaElement
+      { P.seTypeLength = if AT.fieldType f == AT.AFloatingPoint AT.Half then Just 2 else Nothing
+      , P.seName = AT.fieldName f
+      , P.seRepetition = Just rep
+      , P.seType = Just pType
+      , P.seNumChildren = Nothing
+      , P.seConvertedType = case AT.fieldType f of
+          AT.AInt 8 True -> Just P.CTInt8
+          AT.AInt 16 True -> Just P.CTInt16
+          AT.AInt 32 True -> Just P.CTInt32
+          AT.AInt 64 True -> Just P.CTInt64
+          AT.AInt 8 False -> Just P.CTUInt8
+          AT.AInt 16 False -> Just P.CTUInt16
+          AT.AInt 32 False -> Just P.CTUInt32
+          AT.AInt 64 False -> Just P.CTUInt64
+          AT.AUtf8 -> Just (if isJsonField f then P.CTJson else P.CTUtf8)
+          AT.ALargeUtf8 -> Just (if isJsonField f then P.CTJson else P.CTUtf8)
+          AT.ADate _ -> Just P.CTDate
+          AT.ATime AT.Second 32 -> Just P.CTTimeMillis
+          AT.ATime AT.Millisecond 32 -> Just P.CTTimeMillis
+          AT.ATime AT.Microsecond 64 -> Just P.CTTimeMicros
+          AT.ATimestamp AT.Millisecond _ -> Just P.CTTimestampMillis
+          AT.ATimestamp AT.Microsecond _ -> Just P.CTTimestampMicros
+          _ -> Nothing
+      , P.seLogicalType = logical
+      , P.seFieldId = Nothing
+      }
+
+
+{- | Lower one Arrow column to Parquet's required 'ColumnData'.
+Nulls are dropped: the result holds the present values only (the
+shape Parquet's required writer takes). Use
+'columnArrayToParquetColumn' to keep the nulls through definition
+levels.
+-}
+columnArrayToColumnData
+  :: AC.ColumnArray -> Either String PW.ColumnData
+columnArrayToColumnData = \case
+  AC.ColInt8 mv xs -> Right $ PW.ColInt32 (presentPrim fromIntegral mv xs)
+  AC.ColInt16 mv xs -> Right $ PW.ColInt32 (presentPrim fromIntegral mv xs)
+  AC.ColInt32 mv xs -> Right $ PW.ColInt32 (presentPrim id mv xs)
+  AC.ColInt64 mv xs -> Right $ PW.ColInt64 (presentPrim id mv xs)
+  AC.ColUInt8 mv xs -> Right $ PW.ColInt32 (presentPrim (fromIntegral :: Word8 -> Int32) mv xs)
+  AC.ColUInt16 mv xs -> Right $ PW.ColInt32 (presentPrim (fromIntegral :: Word16 -> Int32) mv xs)
+  AC.ColUInt32 mv xs -> Right $ PW.ColInt32 (presentPrim (fromIntegral :: Word32 -> Int32) mv xs)
+  AC.ColUInt64 mv xs -> Right $ PW.ColInt64 (presentPrim (fromIntegral :: Word64 -> Int64) mv xs)
+  AC.ColFloat mv xs -> Right $ PW.ColFloat (presentPrim id mv xs)
+  AC.ColDouble mv xs -> Right $ PW.ColDouble (presentPrim id mv xs)
+  -- Temporal types: lower to the natural Parquet physical type
+  -- the schema element declared (Int32 for Date32 / Time32, Int64
+  -- for Date64 / Time64 / Timestamp / Duration).
+  AC.ColDate32 mv xs -> Right $ PW.ColInt32 (presentPrim id mv xs)
+  AC.ColDate64 mv xs -> Right $ PW.ColInt64 (presentPrim id mv xs)
+  AC.ColTime32 mv xs -> Right $ PW.ColInt32 (presentPrim id mv xs)
+  AC.ColTime64 mv xs -> Right $ PW.ColInt64 (presentPrim id mv xs)
+  AC.ColTimestamp mv xs -> Right $ PW.ColInt64 (presentPrim id mv xs)
+  AC.ColDuration mv xs -> Right $ PW.ColInt64 (presentPrim id mv xs)
+  col
+    | Just ba <- AC.asBool col ->
+        Right $ PW.ColBool (presentBoxed (AC.columnLength col) (AC.nullCount col) (AC.boolArrayAt ba))
+    | Just ba <- AC.asBinary col ->
+        Right $ PW.ColByteArray (presentBoxed (AC.bytesArrayLength ba) (AC.nullCount col) (AC.unsafeBytesAt ba))
+    | Just ba <- AC.asLargeBinary col ->
+        Right $ PW.ColByteArray (presentBoxed (AC.bytesArrayLength ba) (AC.nullCount col) (AC.unsafeBytesAt ba))
+    | otherwise -> Left (noFlatEquivalent col)
+
+
+isJsonField :: AT.Field -> Bool
+isJsonField field = V.elem ("ARROW:extension:name", "arrow.json") (AT.fieldMetadata field)
+
+
+noFlatEquivalent :: AC.ColumnArray -> String
+noFlatEquivalent col =
+  "Parquet.Arrow: Arrow column shape "
+    <> AC.columnTag col
+    <> " has no flat Parquet equivalent (nested types "
+    <> "go through Parquet.Nested, dictionary columns "
+    <> "should pre-resolve to their values column)"
+
+
+{- | Present values of a fixed-width column, cast to the Parquet
+physical type, in one pass (one compaction pass when the column
+has nulls).
+-}
+presentPrim
+  :: (Storable a, VP.Prim b)
+  => (a -> b) -> Maybe AC.Validity -> VS.Vector a -> VP.Vector b
+presentPrim f mv xs = case mv of
+  Nothing -> VP.generate n (\i -> f (VS.unsafeIndex xs i))
+  Just v -> runST $ do
+    out <- VPM.unsafeNew (n - AC.validityNullCount v)
+    let go !i !j
+          | i >= n = pure ()
+          | otherwise = case AC.unsafePrimAt pa i of
+              Just x -> VPM.unsafeWrite out j (f x) *> go (i + 1) (j + 1)
+              Nothing -> go (i + 1) j
+    go 0 0
+    VP.unsafeFreeze out
+  where
+    !n = VS.length xs
+    !pa = AC.PrimArray mv xs
+{-# INLINE presentPrim #-}
+
+
+{- | Present values of a boxed-row view (bool, bytes): @n@ rows,
+@nulls@ of them null, read through @at@.
+-}
+presentBoxed :: Int -> Int -> (Int -> Maybe a) -> V.Vector a
+presentBoxed n nulls at = runST $ do
+  out <- VM.unsafeNew (n - nulls)
+  let go !i !j
+        | i >= n = pure ()
+        | otherwise = case at i of
+            Just x -> VM.unsafeWrite out j x *> go (i + 1) (j + 1)
+            Nothing -> go (i + 1) j
+  go 0 0
+  V.unsafeFreeze out
+{-# INLINE presentBoxed #-}
+
+
+-- | Boxed @Maybe@ rows of a fixed-width column (Parquet's optional writer input).
+maybeVector
+  :: Storable a => (a -> b) -> Maybe AC.Validity -> VS.Vector a -> V.Vector (Maybe b)
+maybeVector f mv xs =
+  let !pa = AC.PrimArray mv xs
+  in V.generate (VS.length xs) (\i -> f <$> AC.unsafePrimAt pa i)
+{-# INLINE maybeVector #-}
+
+
+-- ============================================================
+-- Parquet → Arrow
+-- ============================================================
+
+{- | Read columns of a Parquet row group and lift them to Arrow
+column shapes, driven by the caller-supplied /target/ Arrow
+schema.
+
+Lookup is by top-level column name; nested leaf names remain scoped
+to their parents. The target schema may be narrower than the file
+(projection), in a different order than the file (reordering),
+or request wider types than the file (coercion: see
+'coerceColumn' below for the supported widening rules). Struct children
+are projected recursively by name; list/map wrappers use positional child
+matching and may use caller-selected names. Lists may request 64-bit offsets.
+A required target is rejected if a visible source value is null.
+
+Error cases:
+
+  * 'MissingColumn' — the target requests a column name that
+    isn't present in the file. Callers that want null-fill
+    semantics should catch this constructor and synthesize a
+    null column.
+  * 'IncompatibleType' — the file carries the column but the
+    target's type isn't reachable by the coercion table.
+-}
+parquetRowGroupToArrow
+  :: AT.Schema
+  -- ^ Target Arrow schema
+  -> PR.ParquetFile
+  -> Int
+  -- ^ Row group index
+  -> Either ProjectionError (V.Vector AC.ColumnArray)
+parquetRowGroupToArrow = parquetRowGroupToArrowWithLimits defaultReadLimits
+
+
+-- | Budget for values synthesized without any physical FILE leaf. Ordinary
+-- column-page decoding retains its existing encoded-size and page bounds.
+data ReadLimits = ReadLimits
+  { readMaxUnbackedValues :: {-# UNPACK #-} !Int64
+  }
+  deriving (Show, Eq)
+
+
+defaultReadLimits :: ReadLimits
+defaultReadLimits = ReadLimits {readMaxUnbackedValues = 1048576}
+
+
+-- | Like 'parquetRowGroupToArrow', with a caller-selected aggregate budget for
+-- synthesized zero-field FILE values (one value per output slot per FILE).
+parquetRowGroupToArrowWithLimits :: ReadLimits -> AT.Schema -> PR.ParquetFile -> Int -> Either ProjectionError (V.Vector AC.ColumnArray)
+parquetRowGroupToArrowWithLimits limits target pf rgIdx = do
+  if readMaxUnbackedValues limits < 0
+    then Left (ColumnDecodeFailed "<limits>" "negative unbacked-value budget")
+    else Right ()
+  plans <-
+    either (Left . ColumnDecodeFailed "<schema>") Right $
+      AN.plans schemaElementToArrowField (P.fmSchema (PR.pfFooter pf))
+  columns <-
+    if V.any isNested plans
+      then readNestedGroup limits target pf rgIdx plans
+      else readFlatGroup target pf rgIdx
+  either
+    (Left . ColumnDecodeFailed "<target-schema>")
+    Right
+    (validateColumns (AT.arrowFields target) columns)
+  Right columns
+  where
+    isNested plan = case AN.planKind plan of AN.Primitive -> False; _ -> True
+
+
+readFlatGroup :: AT.Schema -> PR.ParquetFile -> Int -> Either ProjectionError (V.Vector AC.ColumnArray)
+readFlatGroup target pf rgIdx = do
+  let !fileLeaves =
+        V.filter
+          (maybe False (const True) . P.seType)
+          (P.fmSchema (PR.pfFooter pf))
+      !nameToIdx =
+        Map.fromList
+          [(P.seName se, i) | (i, se) <- V.toList (V.indexed fileLeaves)]
+  if Map.size nameToIdx /= V.length fileLeaves
+    then Left (ColumnDecodeFailed "<schema>" "duplicate top-level column names")
+    else V.mapM (readOneProjected pf rgIdx fileLeaves nameToIdx) (AT.arrowFields target)
+
+
+readNestedGroup :: ReadLimits -> AT.Schema -> PR.ParquetFile -> Int -> V.Vector AN.Plan -> Either ProjectionError (V.Vector AC.ColumnArray)
+readNestedGroup limits target pf rgIdx plans = do
+  group <-
+    maybe
+      (Left (ColumnDecodeFailed "<row-group>" "row group index out of range"))
+      Right
+      (P.fmRowGroups (PR.pfFooter pf) V.!? rgIdx)
+  if P.rgNumRows group < 0 || toInteger (P.rgNumRows group) > toInteger (maxBound :: Int) - 7
+    then Left (ColumnDecodeFailed "<row-group>" "row count cannot be represented safely")
+    else Right ()
+  let named = Map.fromList (V.toList (V.map (\p -> (AT.fieldName (AN.planField p), p)) plans))
+      rows = fromIntegral (P.rgNumRows group)
+      nativeFields = V.foldl' collectTimestampFields IntMap.empty plans
+  if Map.size named /= V.length plans
+    then Left (ColumnDecodeFailed "<schema>" "duplicate top-level column names")
+    else do
+      -- Select requested storage widths before any physical leaf is forced.
+      -- A preliminary type-only projection leaves nullability checks to the
+      -- normal projection below, which has the decoded definition levels.
+      storagePlans <-
+        V.mapM
+          ( \field -> do
+              plan <- maybe (Left (MissingColumn (AT.fieldName field))) Right (Map.lookup (AT.fieldName field) named)
+              projectNestedPlan True V.empty 0 (AT.fieldName field) field plan
+          )
+          (AT.arrowFields target)
+      let overrides = V.foldl' collectNarrow IntMap.empty storagePlans
+          physical = V.generate (V.length (P.rgColumns group)) (readLeveledLeaf overrides pf rgIdx)
+      selected <-
+        V.mapM
+          ( \field -> do
+              plan <- maybe (Left (MissingColumn (AT.fieldName field))) Right (Map.lookup (AT.fieldName field) named)
+              projectNestedPlan (rows == 0) physical 0 (AT.fieldName field) field plan
+          )
+          (AT.arrowFields target)
+      _ <-
+        V.foldM
+          ( \total plan -> do
+              cost <- either (Left . ColumnDecodeFailed "<unbacked>") Right (AN.unbackedValues rows physical plan)
+              if cost > readMaxUnbackedValues limits - total
+                then Left (ColumnDecodeFailed "<unbacked>" "synthesized FILE values exceed the unbacked-value budget")
+                else Right (total + cost)
+          )
+          0
+          selected
+      V.zipWithM
+        ( \field projected -> do
+            column <- either (Left . ColumnDecodeFailed (AT.fieldName field)) Right (AN.assembleWithRows rows (widenNestedPrimitive nativeFields) physical projected)
+            if AC.columnLength column /= rows
+              then Left (ColumnDecodeFailed (AT.fieldName field) "decoded row count differs from row-group metadata")
+              else Right column
+        )
+        (AT.arrowFields target)
+        selected
+
+
+collectTimestampFields :: IntMap.IntMap AT.Field -> AN.Plan -> IntMap.IntMap AT.Field
+collectTimestampFields fields plan = case AN.planKind plan of
+  AN.Primitive
+    | Timestamp.isTimestampField (AN.planField plan) -> IntMap.insert (AN.planAnchor plan) (AN.planField plan) fields
+    | otherwise -> fields
+  AN.Struct children -> V.foldl' collectTimestampFields fields children
+  AN.List child -> collectTimestampFields fields child
+  AN.Map key value -> collectTimestampFields (collectTimestampFields fields key) value
+  AN.EmptyFile -> fields
+
+
+-- Only context-dependent narrow decimals need an override. Ordinals keep
+-- equally named leaves under different Variant objects independent.
+collectNarrow :: IntMap.IntMap AT.ArrowType -> AN.Plan -> IntMap.IntMap AT.ArrowType
+collectNarrow current plan = case AN.planKind plan of
+  AN.Primitive -> case AT.fieldType (AN.planField plan) of
+    typ@AT.ADecimal32 {} -> IntMap.insert (AN.planAnchor plan) typ current
+    typ@AT.ADecimal64 {} -> IntMap.insert (AN.planAnchor plan) typ current
+    AT.ALargeUtf8 -> IntMap.insert (AN.planAnchor plan) AT.ALargeUtf8 current
+    AT.ALargeBinary -> IntMap.insert (AN.planAnchor plan) AT.ALargeBinary current
+    _ -> current
+  AN.Struct fields -> V.foldl' collectNarrow current fields
+  AN.List child -> collectNarrow current child
+  AN.Map key value -> collectNarrow (collectNarrow current key) value
+  AN.EmptyFile -> current
+
+
+-- Retaining a Variant annotation also retains its exact semantic storage.
+-- Dropping fallback fields or widening int32 to int64 changes Variant values.
+-- Raw physical projections remain available by removing the extension.
+sameVariantStorage :: AT.Field -> AT.Field -> Bool
+sameVariantStorage source target =
+  sameType && AT.fieldDictionary source == AT.fieldDictionary target && sameChildren && sameExtension
+  where
+    sourceType = AT.fieldType source
+    targetType = AT.fieldType target
+    list typ = typ `elem` [AT.AList, AT.ALargeList]
+    sameType = sourceType == targetType || (list sourceType && list targetType)
+    sourceChildren = AT.fieldChildren source
+    targetChildren = AT.fieldChildren target
+    sameChildren
+      | list sourceType = V.length sourceChildren == 1 && V.length targetChildren == 1 && sameVariantStorage (V.head sourceChildren) (V.head targetChildren)
+      | otherwise =
+          let named = Map.fromList (V.toList (V.map (\field -> (AT.fieldName field, field)) sourceChildren))
+          in V.length sourceChildren == V.length targetChildren && V.all (\field -> maybe False (\native -> sameVariantStorage native field) (Map.lookup (AT.fieldName field) named)) targetChildren
+    extensions = V.filter ((== "ARROW:extension:name") . fst) . AT.fieldMetadata
+    sameExtension = extensions source == extensions target
+
+
+-- Select the logical tree before assembly. List/map wrapper names are
+-- positional; struct members are selected by name. Anchors follow retained
+-- children so an omitted physical leaf is neither read nor decoded.
+projectNestedPlan
+  :: Bool
+  -> V.Vector (Either String AN.LeafColumn)
+  -> Int
+  -> Text
+  -> AT.Field
+  -> AN.Plan
+  -> Either ProjectionError AN.Plan
+projectNestedPlan emptyRowGroup leaves ancestorPresence path requested native = do
+  if VariantSchema.isVariantField requested
+    then do
+      either
+        (Left . ColumnDecodeFailed path)
+        Right
+        (VariantSchema.validateVariantFieldWithLimits (VariantSchema.VariantSchemaLimits 128 maxBound) requested)
+      if VariantSchema.isVariantField source && sameVariantStorage source requested then Right () else incompatible
+    else Right ()
+  timestampCompatible <-
+    if Timestamp.isTimestampField source || Timestamp.isTimestampField requested
+      then either (Left . ColumnDecodeFailed path) Right (Timestamp.fieldsCompatible source requested)
+      else Right (compatiblePrimitive (AT.fieldType source) (AT.fieldType requested))
+  case AT.fieldDictionary requested of
+    Just _ -> incompatible
+    Nothing -> Right ()
+  projected <- case AN.planKind native of
+    AN.Primitive
+      | V.null (AT.fieldChildren requested)
+      , timestampCompatible ->
+          Right native {AN.planField = requested}
+    AN.EmptyFile
+      | AT.fieldType requested == AT.AStruct && V.null (AT.fieldChildren requested) ->
+          Right native {AN.planField = requested}
+    AN.Struct children
+      | AT.fieldType requested == AT.AStruct -> do
+          let named = Map.fromList (V.toList (V.map (\p -> (AT.fieldName (AN.planField p), p)) children))
+          selected <-
+            V.mapM
+              ( \field -> do
+                  let childPath = path <> "." <> AT.fieldName field
+                  child <- maybe (Left (MissingColumn childPath)) Right (Map.lookup (AT.fieldName field) named)
+                  projectNestedPlan emptyRowGroup leaves visible childPath field child
+              )
+              (AT.fieldChildren requested)
+          Right
+            native
+              { AN.planField = requested
+              , AN.planAnchor = maybe (AN.planAnchor native) AN.planAnchor (V.find ((>= 0) . AN.planAnchor) selected)
+              , AN.planKind = AN.Struct selected
+              }
+    AN.List child
+      | AT.fieldType requested `elem` [AT.AList, AT.ALargeList]
+      , [childField] <- V.toList (AT.fieldChildren requested) -> do
+          selected <- projectNestedPlan emptyRowGroup leaves (AN.planSlotDef child) (path <> "." <> AT.fieldName childField) childField child
+          Right native {AN.planField = requested, AN.planAnchor = AN.planAnchor selected, AN.planKind = AN.List selected}
+    AN.Map key value
+      | AT.fieldType requested == AT.AMap False
+      , [entryField] <- V.toList (AT.fieldChildren requested)
+      , AT.fieldType entryField == AT.AStruct
+      , not (AT.fieldNullable entryField)
+      , Nothing <- AT.fieldDictionary entryField
+      , [keyField, valueField] <- V.toList (AT.fieldChildren entryField)
+      , not (AT.fieldNullable keyField) -> do
+          selectedKey <- projectNestedPlan emptyRowGroup leaves (AN.planSlotDef key) (path <> "." <> AT.fieldName keyField) keyField key
+          selectedValue <- projectNestedPlan emptyRowGroup leaves (AN.planSlotDef value) (path <> "." <> AT.fieldName valueField) valueField value
+          let anchor = if AN.planAnchor selectedKey >= 0 then AN.planAnchor selectedKey else AN.planAnchor selectedValue
+          Right native {AN.planField = requested, AN.planAnchor = anchor, AN.planKind = AN.Map selectedKey selectedValue}
+    _ -> incompatible
+  -- Null ancestors have no child value. Narrowing a nullable child is valid
+  -- only when every event at which its ancestors are present contains it.
+  -- Check native levels before changing validity/filling absent child slots.
+  if not emptyRowGroup && AT.fieldNullable source && not (AT.fieldNullable requested)
+    then do
+      if AN.planAnchor projected < 0 then incompatible else Right ()
+      leaf <- maybe (Left (ColumnDecodeFailed path "missing physical leaf")) (either (Left . ColumnDecodeFailed path) Right) (leaves V.!? AN.planAnchor projected)
+      if VP.any (\def -> fromIntegral def >= ancestorPresence && fromIntegral def < AN.planPresence native) (AN.leafDefs leaf)
+        then incompatible
+        else Right projected
+    else Right projected
+  where
+    source = AN.planField native
+    visible = max ancestorPresence (AN.planPresence native)
+    incompatible = Left (IncompatibleType path (AT.fieldType requested))
+    compatiblePrimitive actual target =
+      actual == target
+        || canWidenBinary actual target
+        || (actual == AT.AInt 32 True && target == AT.AInt 64 True)
+        || (actual == AT.AFloatingPoint AT.Single && target == AT.AFloatingPoint AT.DoublePrecision)
+
+
+widenNestedPrimitive :: IntMap.IntMap AT.Field -> AN.Plan -> AC.ColumnArray -> Either String AC.ColumnArray
+widenNestedPrimitive sources plan column
+  | Just source <- IntMap.lookup (AN.planAnchor plan) sources
+  , Timestamp.isTimestampField source || Timestamp.isTimestampField (AN.planField plan) =
+      Timestamp.projectTimestampColumn source (AN.planField plan) column
+widenNestedPrimitive _ plan column = case (AT.fieldType (AN.planField plan), column) of
+  (AT.AInt 64 True, AC.ColInt32 {}) -> coerceColumn (AT.AInt 64 True) column
+  (AT.AFloatingPoint AT.DoublePrecision, AC.ColFloat {}) -> coerceColumn (AT.AFloatingPoint AT.DoublePrecision) column
+  _ -> Right column
+
+
+-- ============================================================
+-- Projection / schema evolution
+-- ============================================================
+
+-- | Why a projection request couldn't be satisfied.
+data ProjectionError
+  = {- | The target schema references a column name that isn't
+    present in the Parquet footer. A real schema-evolution
+    implementation would fill this column with nulls; callers
+    that want that behaviour can catch this constructor and
+    synthesize a null column.
+    -}
+    MissingColumn !Text
+  | {- | The target schema requests a type the physical Parquet
+    column can't be coerced to. The bridge's coercion table is
+    intentionally narrow: numeric widening (Int32 → Int64,
+    Float → Double), identity reads for equal types.
+    -}
+    IncompatibleType !Text !AT.ArrowType
+  | -- | A column's native values could not be decoded.
+    ColumnDecodeFailed !Text !String
+  deriving (Show, Eq)
+
+
+{- | Recover the Arrow-shaped schema implied by a Parquet file's
+leaf columns. Uses the Parquet converted-type / logical-type
+annotations to pick the right Arrow flavour (UTF-8 vs raw
+binary, Date vs Int32, Timestamp vs Int64).
+-}
+parquetFileArrowSchema :: PR.ParquetFile -> AT.Schema
+-- Kept for callers with a known-valid schema. Use the checked variant at
+-- file boundaries so malformed trees are reported through Either.
+parquetFileArrowSchema = either error id . parquetFileArrowSchemaChecked
+
+
+-- | Infer a complete schema, reporting malformed physical trees explicitly.
+parquetFileArrowSchemaChecked :: PR.ParquetFile -> Either String AT.Schema
+parquetFileArrowSchemaChecked pf = do
+  let footer = PR.pfFooter pf
+      fieldWithMetadata element = do
+        field <- schemaElementToArrowField element
+        metadata <- Geo.toArrowMetadata footer element
+        Right (if V.null metadata then field else field {AT.fieldMetadata = metadata})
+  nodes <- AN.plans fieldWithMetadata (P.fmSchema footer)
+  Right
+    AT.Schema
+      { AT.arrowFields = AN.planField <$> nodes
+      , AT.arrowEndianness = AT.Little
+      , AT.arrowMetadata = V.empty
+      , AT.arrowFeatures = V.empty
+      }
+
+
+{- | Map a Parquet 'P.SchemaElement' back to an Arrow leaf
+'AT.Field' using its converted-type / logical-type hints.
+Mirrors the inverse of 'arrowFieldToSchemaElement'.
+-}
+schemaElementToArrowField :: P.SchemaElement -> Either String AT.Field
+schemaElementToArrowField se = do
+  -- FLBA(12) timestamps are valid Parquet, but Arrow's timestamp storage is
+  -- signed 64-bit. Never silently erase their logical type into raw bytes.
+  encoding <- Timestamp.schemaEncoding se
+  case (P.seLogicalType se, P.seConvertedType se) of
+    (Just (P.LTTimestamp _ _), _) | encoding == Nothing -> requirePhysical P.PTInt64
+    (Just (P.LTTime _ P.LtMillis), _) -> requirePhysical P.PTInt32
+    (Just (P.LTTime _ _), _) -> requirePhysical P.PTInt64
+    (_, Just P.CTTimestampMillis) -> requirePhysical P.PTInt64
+    (_, Just P.CTTimestampMicros) -> requirePhysical P.PTInt64
+    (_, Just P.CTTimeMillis) -> requirePhysical P.PTInt32
+    (_, Just P.CTTimeMicros) -> requirePhysical P.PTInt64
+    _ -> Right ()
+  let !name = P.seName se
+      !nullable = case P.seRepetition se of
+        Just P.Optional -> True
+        _ -> False
+      !ty = arrowTypeFromSchemaElement se
+      metadata =
+        if ty == AT.AUtf8 && (P.seLogicalType se == Just P.LTJson || P.seConvertedType se == Just P.CTJson)
+          then V.fromList [("ARROW:extension:name", "arrow.json"), ("ARROW:extension:metadata", "{}")]
+          else V.empty
+  Right $ case encoding of
+    Just kind -> Timestamp.timestampField name nullable kind
+    Nothing -> AT.Field name nullable ty V.empty Nothing metadata
+  where
+    requirePhysical expected
+      | P.seType se == Just expected = Right ()
+      | otherwise = Left ("Parquet.Arrow: unsupported physical storage for TIME/TIMESTAMP in " ++ show (P.seName se))
+
+
+arrowTypeFromSchemaElement :: P.SchemaElement -> AT.ArrowType
+arrowTypeFromSchemaElement se
+  | P.seLogicalType se == Just P.LTUnsupported =
+      arrowTypeFromSchemaElement (se {P.seLogicalType = Nothing, P.seConvertedType = Nothing})
+  | P.seLogicalType se == Just P.LTNull = AT.ANull
+  | Just (P.LTDecimal precision scale) <- P.seLogicalType se
+  , P.seType se `elem` [Just P.PTInt32, Just P.PTInt64, Just P.PTByteArray, Just P.PTFixedLenByteArray] =
+      if precision <= 38
+        then AT.ADecimal (fromIntegral precision) (fromIntegral scale)
+        else AT.ADecimal256 (fromIntegral precision) (fromIntegral scale)
+  | otherwise = case P.seType se of
+      Just P.PTInt96 -> AT.AFixedSizeBinary 12
+      Just P.PTFixedLenByteArray -> case P.seLogicalType se of
+        Just P.LTFloat16 -> AT.AFloatingPoint AT.Half
+        _ -> AT.AFixedSizeBinary (maybe 0 fromIntegral (P.seTypeLength se))
+      Just P.PTBoolean -> AT.ABool
+      Just P.PTInt32 -> case (P.seLogicalType se, P.seConvertedType se) of
+        (Just P.LTDate, _) -> AT.ADate AT.DateDay
+        (Just (P.LTTime _ unit), _)
+          | Just u <- arrowTimeUnit unit -> AT.ATime u 32
+        (Just (P.LTInteger w isSigned), _)
+          | w <= 32 -> AT.AInt (fromIntegral w) isSigned
+        (_, Just P.CTDate) -> AT.ADate AT.DateDay
+        (_, Just P.CTTimeMillis) -> AT.ATime AT.Millisecond 32
+        (_, Just P.CTInt8) -> AT.AInt 8 True
+        (_, Just P.CTInt16) -> AT.AInt 16 True
+        (_, Just P.CTUInt8) -> AT.AInt 8 False
+        (_, Just P.CTUInt16) -> AT.AInt 16 False
+        (_, Just P.CTUInt32) -> AT.AInt 32 False
+        _ -> AT.AInt 32 True
+      Just P.PTInt64 -> case (P.seLogicalType se, P.seConvertedType se) of
+        (Just (P.LTTime _ unit), _)
+          | Just u <- arrowTimeUnit unit -> AT.ATime u 64
+        (Just (P.LTTimestamp adj unit), _)
+          | Just u <- arrowTimeUnit unit ->
+              AT.ATimestamp
+                u
+                (if adj then Just (T.pack "UTC") else Nothing)
+        (Just (P.LTInteger 64 isSigned), _) ->
+          AT.AInt 64 isSigned
+        (_, Just P.CTTimeMicros) -> AT.ATime AT.Microsecond 64
+        (_, Just P.CTTimestampMillis) -> AT.ATimestamp AT.Millisecond (Just "UTC")
+        (_, Just P.CTTimestampMicros) -> AT.ATimestamp AT.Microsecond (Just "UTC")
+        (_, Just P.CTUInt64) -> AT.AInt 64 False
+        _ -> AT.AInt 64 True
+      Just P.PTFloat -> AT.AFloatingPoint AT.Single
+      Just P.PTDouble -> AT.AFloatingPoint AT.DoublePrecision
+      Just P.PTByteArray -> case (P.seLogicalType se, P.seConvertedType se) of
+        (Just P.LTString, _) -> AT.AUtf8
+        (Just P.LTEnum, _) -> AT.AUtf8
+        -- Geometry / Geography / Variant + Json / Bson are all
+        -- bytes on the wire; expose as ABinary so callers see the
+        -- raw WKB / JSON / variant bytes. The LogicalType
+        -- annotation survives round-trip for downstream tools.
+        (Just P.LTGeometry {}, _) -> AT.ABinary
+        (Just P.LTGeography {}, _) -> AT.ABinary
+        (Just (P.LTVariant _), _) -> AT.ABinary
+        (Just P.LTJson, _) -> AT.AUtf8
+        (Just P.LTBson, _) -> AT.ABinary
+        (_, Just P.CTUtf8) -> AT.AUtf8
+        (_, Just P.CTEnum) -> AT.AUtf8
+        (_, Just P.CTJson) -> AT.AUtf8
+        (_, Just P.CTBson) -> AT.ABinary
+        _ -> AT.ABinary
+      _ -> AT.ABinary -- FIXED_LEN_BYTE_ARRAY / Int96 fallback
+
+
+arrowTimeUnit :: P.LtTimeUnit -> Maybe AT.TimeUnit
+arrowTimeUnit P.LtMillis = Just AT.Millisecond
+arrowTimeUnit P.LtMicros = Just AT.Microsecond
+arrowTimeUnit P.LtNanos = Just AT.Nanosecond
+
+
+{- | Core per-column reader used by 'parquetRowGroupToArrow'.
+Looks up the column by name, reads it at the file's native
+Arrow type, then coerces to the target type via 'coerceColumn'
+if needed.
+-}
+readOneProjected
+  :: PR.ParquetFile
+  -> Int
+  -> V.Vector P.SchemaElement
+  -> Map.Map Text Int
+  -> AT.Field
+  -> Either ProjectionError AC.ColumnArray
+readOneProjected pf rgIdx fileLeaves nameToIdx fld =
+  case Map.lookup (AT.fieldName fld) nameToIdx of
+    Nothing -> Left (MissingColumn (AT.fieldName fld))
+    Just fileIdx -> do
+      -- Decode at the file's physical/logical type before coercion. Trying
+      -- the target decoder first can silently reinterpret int bytes as
+      -- floats or booleans instead of reporting an incompatible projection.
+      fileFld <-
+        either
+          (Left . ColumnDecodeFailed (AT.fieldName fld))
+          Right
+          (schemaElementToArrowField (V.unsafeIndex fileLeaves fileIdx))
+      let incompatible = IncompatibleType (AT.fieldName fld) (AT.fieldType fld)
+      let decodingField = if canWidenBinary (AT.fieldType fileFld) (AT.fieldType fld) then fileFld {AT.fieldType = AT.fieldType fld} else fileFld
+      native <- case readParquetColumn pf rgIdx fileIdx decodingField of
+        Left err -> Left (ColumnDecodeFailed (AT.fieldName fld) err)
+        Right col -> Right col
+      if not (AT.fieldNullable fld) && AC.nullCount native > 0
+        then Left incompatible
+        else
+          if Timestamp.isTimestampField fileFld || Timestamp.isTimestampField fld
+            then either (Left . ColumnDecodeFailed (AT.fieldName fld)) Right (Timestamp.projectTimestampColumn fileFld fld native)
+            else
+              if AT.fieldType fld == AT.fieldType decodingField
+                then Right native
+                else coerceColumn (AT.fieldType fld) native `orLeft` incompatible
+  where
+    orLeft (Right x) _ = Right x
+    orLeft (Left _) e = Left e
+
+
+-- Widening offset storage preserves logical values and aliases payload bytes.
+canWidenBinary :: AT.ArrowType -> AT.ArrowType -> Bool
+canWidenBinary AT.AUtf8 AT.ALargeUtf8 = True
+canWidenBinary AT.ABinary AT.ALargeBinary = True
+canWidenBinary _ _ = False
+
+
+{- | Best-effort column coercion for the projection path. The
+coercion table is deliberately narrow: numeric and offset widening
+(Int32 → Int64, Float → Double, Utf8/Binary → LargeUtf8/LargeBinary),
+and identity reads. Returns
+'Left' for unsupported coercions; callers route that to
+'IncompatibleType'.
+-}
+coerceColumn :: AT.ArrowType -> AC.ColumnArray -> Either String AC.ColumnArray
+coerceColumn target col = case (target, col) of
+  (AT.ALargeUtf8, AC.ColUtf8 validity offsets bytes) -> AC.mkLargeUtf8 validity (VS.map fromIntegral offsets) bytes
+  (AT.ALargeBinary, AC.ColBinary validity offsets bytes) -> AC.mkLargeBinary validity (VS.map fromIntegral offsets) bytes
+  (AT.ALargeUtf8, AC.ColLargeUtf8 {}) -> Right col
+  (AT.ALargeBinary, AC.ColLargeBinary {}) -> Right col
+  (AT.AInt 64 True, AC.ColInt32 mv xs) ->
+    AC.mkPrim AC.PInt64 mv (VS.map (fromIntegral :: Int32 -> Int64) xs)
+  (AT.AFloatingPoint AT.DoublePrecision, AC.ColFloat mv xs) ->
+    AC.mkPrim AC.PDouble mv (VS.map (realToFrac :: Float -> Double) xs)
+  _ -> Left ("coerceColumn: " ++ show target ++ " <- " ++ AC.columnTag col)
+
+
+{- | Read one column chunk and project it into a 'ColumnArray'.
+Dispatches on the Arrow target type + nullability; falls back
+to a clean 'Left' for shapes the bridge doesn't yet cover.
+-}
+readParquetColumn
+  :: PR.ParquetFile
+  -> Int
+  -- ^ row-group index
+  -> Int
+  -- ^ column index within the row group
+  -> AT.Field
+  -> Either String AC.ColumnArray
+readParquetColumn pf rgIdx colIdx requested = do
+  chunk <- PR.columnChunkSlice pf rgIdx colIdx
+  let schema = P.fmSchema (PR.pfFooter pf)
+      leaves = V.filter (maybe False (const True) . P.seType) schema
+  leaf <- maybe (Left "Parquet.Arrow: missing leaf schema") Right (leaves V.!? colIdx)
+  metadata <-
+    maybe
+      (Left "Parquet.Arrow: missing column metadata")
+      Right
+      (P.ccMetadata (P.rgColumns (P.fmRowGroups (PR.pfFooter pf) V.! rgIdx) V.! colIdx))
+  if P.seType leaf /= Just (P.cmType metadata)
+    then Left "Parquet.Arrow: column metadata and schema physical types differ"
+    else Right ()
+  native <- schemaElementToArrowField leaf
+  let codec = P.cmCodec metadata
+  timestampCompatible <-
+    if Timestamp.isTimestampField native || Timestamp.isTimestampField requested
+      then Timestamp.fieldsCompatible native requested
+      else Right True
+  if (AT.fieldType requested /= AT.fieldType native && not (canWidenBinary (AT.fieldType native) (AT.fieldType requested))) || not timestampCompatible
+    then Left "Parquet.Arrow: requested field differs from file type; use schema projection for coercion"
+    else Right ()
+  let decodingField = if canWidenBinary (AT.fieldType native) (AT.fieldType requested) then native {AT.fieldType = AT.fieldType requested} else native
+  (maxRep, maxDef) <- Levels.maxLevelsForColumnPath schema (P.cmPathInSchema metadata)
+  if maxRep /= 0
+    then Left "Parquet.Arrow: a repeated physical leaf needs parquetRowGroupToArrow to reconstruct its containers"
+    else Right ()
+  let rows = P.rgNumRows (P.fmRowGroups (PR.pfFooter pf) V.! rgIdx)
+  if rows < 0 || (fromIntegral rows :: Word64) > fromIntegral (maxBound :: Int) || P.cmNumValues metadata /= rows
+    then Left "Parquet.Arrow: non-repeated column events differ from row count"
+    else Right ()
+  column <-
+    if maxDef > 1 || (maxDef > 0 && P.seRepetition leaf /= Just P.Optional)
+      then do
+        values <- readLeveledLeaf (if isLargeBinary (AT.fieldType decodingField) then IntMap.singleton colIdx (AT.fieldType decodingField) else IntMap.empty) pf rgIdx colIdx
+        AN.assemble
+          (V.singleton (Right values))
+          (AN.Plan (decodingField {AT.fieldNullable = True}) 0 0 0 maxDef AN.Primitive)
+      else readFlat leaf metadata codec chunk decodingField
+  if fromIntegral (AC.columnLength column) /= rows
+    then Left "Parquet.Arrow: decoded row count differs from column metadata"
+    else
+      if not (AT.fieldNullable requested) && AC.nullCount column > 0
+        then Left "Parquet.Arrow: non-nullable target cannot contain nulls"
+        else Right column
+  where
+    readFlat leaf metadata codec chunk native = case (P.seType leaf, AT.fieldType native) of
+      (_, AT.ANull) -> Right (AC.ColNull (fromIntegral (P.rgNumRows (P.fmRowGroups (PR.pfFooter pf) V.! rgIdx))))
+      (Just P.PTInt96, _) -> annotated leaf metadata codec chunk
+      (Just P.PTFixedLenByteArray, _) -> annotated leaf metadata codec chunk
+      (_, AT.ADecimal _ _) -> annotated leaf metadata codec chunk
+      (_, AT.ADecimal256 _ _) -> annotated leaf metadata codec chunk
+      _
+        | AT.fieldNullable native -> liftColumn (ChunkSource codec chunk) native
+        | otherwise -> readPlainColumn codec chunk native
+    annotated leaf metadata codec chunk = do
+      (maxRep, maxDef) <-
+        Levels.maxLevelsForColumnPath
+          (P.fmSchema (PR.pfFooter pf))
+          (P.cmPathInSchema metadata)
+      if maxRep /= 0
+        then Left "Parquet.Arrow: repeated annotated values need a nested Arrow field"
+        else readAnnotatedColumn leaf codec chunk maxDef
+
+-- Physical page decoding remains shared with the flat reader. Only defined
+-- values are lifted; the schema plan scatters nulls and builds containers.
+
+
+readLeveledLeaf :: IntMap.IntMap AT.ArrowType -> PR.ParquetFile -> Int -> Int -> Either String AN.LeafColumn
+readLeveledLeaf overrides pf groupIndex columnIndex = do
+  let footer = PR.pfFooter pf
+      leaves = V.filter (maybe False (const True) . P.seType) (P.fmSchema footer)
+  leaf <- maybe (Left "Parquet.Arrow: missing physical schema leaf") Right (leaves V.!? columnIndex)
+  group <- maybe (Left "Parquet.Arrow: row group out of range") Right (P.fmRowGroups footer V.!? groupIndex)
+  chunkMetadata <-
+    maybe
+      (Left "Parquet.Arrow: missing column metadata")
+      Right
+      (P.rgColumns group V.!? columnIndex >>= P.ccMetadata)
+  if P.seType leaf /= Just (P.cmType chunkMetadata)
+    then Left "Parquet.Arrow: schema and column physical types disagree"
+    else Right ()
+  (maxRep, maxDef) <- Levels.maxLevelsForColumnPath (P.fmSchema footer) (P.cmPathInSchema chunkMetadata)
+  bytes <- PR.columnChunkSlice pf groupIndex columnIndex
+  let codec = P.cmCodec chunkMetadata
+      nativeType = IntMap.findWithDefault (arrowTypeFromSchemaElement leaf) columnIndex overrides
+      completeWith :: (a -> Either String AC.ColumnArray) -> Either String (PR.ColumnLevels a) -> Either String AN.LeafColumn
+      completeWith lift decoded = do
+        levels <- decoded
+        let reps = PR.clRepetition levels
+            defs = PR.clDefinition levels
+            rows = VP.foldl' (\n rep -> if rep == 0 then n + 1 else n) (0 :: Int64) reps
+        if fromIntegral (VP.length defs) /= P.cmNumValues chunkMetadata || rows /= P.rgNumRows group
+          then Left "Parquet.Arrow: physical event/row count differs from column metadata"
+          else do
+            values <- lift (PR.clValues levels)
+            Right (AN.LeafColumn reps defs values)
+      complete wrap = completeWith (liftDefined leaf . wrap)
+  case P.cmType chunkMetadata of
+    physical
+      | nativeScalarPhysical nativeType == Just physical ->
+          completeWith (scalarBuffersColumn nativeType) (PR.readScalarBuffersLevels physical codec maxRep maxDef bytes)
+    P.PTInt32 -> complete PW.ColInt32 (PR.readInt32Levels codec maxRep maxDef bytes)
+    P.PTInt64 -> complete PW.ColInt64 (PR.readInt64Levels codec maxRep maxDef bytes)
+    P.PTFloat -> complete PW.ColFloat (PR.readFloatLevels codec maxRep maxDef bytes)
+    P.PTDouble -> complete PW.ColDouble (PR.readDoubleLevels codec maxRep maxDef bytes)
+    P.PTBoolean -> completeWith boolBuffersColumn (PR.readBoolBuffersLevels codec maxRep maxDef bytes)
+    P.PTByteArray
+      | isLargeBinary nativeType ->
+          completeWith (largeBinaryBuffersColumn nativeType) (PR.readLargeBinaryBuffersLevels codec maxRep maxDef bytes)
+      | isNativeBinary (arrowTypeFromSchemaElement leaf) ->
+          completeWith (binaryBuffersColumn (arrowTypeFromSchemaElement leaf)) (PR.readBinaryBuffersLevels codec maxRep maxDef bytes)
+      | otherwise -> complete PW.ColByteArray (PR.readByteArrayLevels codec maxRep maxDef bytes)
+    P.PTInt96 -> complete PW.ColByteArray (PR.readFixedLevels 12 codec maxRep maxDef bytes)
+    P.PTFixedLenByteArray -> case P.seTypeLength leaf of
+      Just width -> complete PW.ColByteArray (PR.readFixedLevels (fromIntegral width) codec maxRep maxDef bytes)
+      Nothing -> Left "Parquet.Arrow: fixed binary leaf is missing its width"
+
+
+liftDefined :: P.SchemaElement -> PW.ColumnData -> Either String AC.ColumnArray
+liftDefined leaf values = case (arrowTypeFromSchemaElement leaf, values) of
+  (AT.ANull, _) -> Right (AC.ColNull (PW.columnDataLength values))
+  (AT.AInt 8 True, PW.ColInt32 xs) -> buildDenseChecked AC.PInt8 (VP.length xs) (VP.unsafeIndex xs) (\input value -> fromIntegral value == input) fromIntegral
+  (AT.AInt 16 True, PW.ColInt32 xs) -> buildDenseChecked AC.PInt16 (VP.length xs) (VP.unsafeIndex xs) (\input value -> fromIntegral value == input) fromIntegral
+  (AT.AInt 32 True, PW.ColInt32 xs) -> Right (AC.primColumn AC.PInt32 (primToStorable xs))
+  (AT.AInt 64 True, PW.ColInt64 xs) -> Right (AC.primColumn AC.PInt64 (primToStorable xs))
+  (AT.AInt 8 False, PW.ColInt32 xs) -> buildDenseChecked AC.PUInt8 (VP.length xs) (VP.unsafeIndex xs) (\input value -> fromIntegral value == input) fromIntegral
+  (AT.AInt 16 False, PW.ColInt32 xs) -> buildDenseChecked AC.PUInt16 (VP.length xs) (VP.unsafeIndex xs) (\input value -> fromIntegral value == input) fromIntegral
+  (AT.AInt 32 False, PW.ColInt32 xs) -> Right (AC.primColumn AC.PUInt32 (VS.generate (VP.length xs) (fromIntegral . VP.unsafeIndex xs)))
+  (AT.AInt 64 False, PW.ColInt64 xs) -> Right (AC.primColumn AC.PUInt64 (VS.generate (VP.length xs) (fromIntegral . VP.unsafeIndex xs)))
+  (AT.AFloatingPoint AT.Single, PW.ColFloat xs) -> Right (AC.primColumn AC.PFloat (primToStorable xs))
+  (AT.AFloatingPoint AT.DoublePrecision, PW.ColDouble xs) -> Right (AC.primColumn AC.PDouble (primToStorable xs))
+  (AT.ADate AT.DateDay, PW.ColInt32 xs) -> Right (AC.primColumn AC.PDate32 (primToStorable xs))
+  (AT.ATime _ 32, PW.ColInt32 xs) -> Right (AC.primColumn AC.PTime32 (primToStorable xs))
+  (AT.ATime _ 64, PW.ColInt64 xs) -> Right (AC.primColumn AC.PTime64 (primToStorable xs))
+  (AT.ATimestamp _ _, PW.ColInt64 xs) -> Right (AC.primColumn AC.PTimestamp (primToStorable xs))
+  (AT.ABool, PW.ColBool xs) -> Right (AC.fromBools xs)
+  (AT.AUtf8, PW.ColByteArray xs) -> utf8FromBinary (AC.fromByteStrings xs)
+  (AT.ABinary, PW.ColByteArray xs) -> Right (AC.fromByteStrings xs)
+  (AT.AFixedSizeBinary width, PW.ColByteArray xs) -> do
+    column <- fixedSizeBinary width xs
+    encoding <- Timestamp.schemaEncoding leaf
+    maybe (Right column) (\kind -> Timestamp.validateTimestampColumn kind column) encoding
+  (AT.AFloatingPoint AT.Half, PW.ColByteArray xs) ->
+    buildDenseChecked
+      AC.PFloat16
+      (V.length xs)
+      (V.unsafeIndex xs)
+      (\bytes _ -> BS.length bytes == 2)
+      (\bytes -> AC.Float16 (fromIntegral (BSU.unsafeIndex bytes 0) .|. (fromIntegral (BSU.unsafeIndex bytes 1) `shiftL` 8)))
+  (AT.ADecimal precision scale, _)
+    | precision >= 1 && precision <= 38 ->
+        let bound = 10 ^ precision - 1 :: Integer
+            low = AC.decimal128FromInteger (negate bound)
+            high = AC.decimal128FromInteger bound
+        in decimal
+             (AC.PDecimal128 precision scale)
+             16
+             decimal128Bytes
+             (\value -> compare128 value low /= LT && compare128 value high /= GT)
+             (\n -> AC.Decimal128 (fromIntegral n) (if n < 0 then maxBound else 0))
+  (AT.ADecimal256 precision scale, _)
+    | precision >= 1 && precision <= 76 ->
+        let bound = 10 ^ precision - 1 :: Integer
+            low = AC.decimal256FromInteger (negate bound)
+            high = AC.decimal256FromInteger bound
+        in decimal
+             (AC.PDecimal256 precision scale)
+             32
+             decimal256Bytes
+             (\value -> compare256 value low /= LT && compare256 value high /= GT)
+             (\n -> let sign = if n < 0 then maxBound else 0 in AC.Decimal256 (fromIntegral n) sign sign sign)
+  _ -> Left "Parquet.Arrow: unsupported physical/logical leaf combination"
+  where
+    decimal :: Storable d => AC.PrimType d -> Int -> (ByteString -> d) -> (d -> Bool) -> (Int64 -> d) -> Either String AC.ColumnArray
+    decimal primitive width decode valid fromInt = case values of
+      PW.ColInt32 xs ->
+        buildDenseChecked
+          primitive
+          (VP.length xs)
+          (VP.unsafeIndex xs)
+          (\_ -> valid)
+          (fromInt . fromIntegral)
+      PW.ColInt64 xs -> buildDenseChecked primitive (VP.length xs) (VP.unsafeIndex xs) (\_ -> valid) fromInt
+      PW.ColByteArray xs ->
+        buildDenseChecked
+          primitive
+          (V.length xs)
+          (V.unsafeIndex xs)
+          (\bytes value -> not (BS.null bytes) && fitsSignedBytes width bytes && valid value)
+          decode
+      _ -> Left "Parquet.Arrow: DECIMAL has an invalid physical type"
+
+
+-- Required single-page PLAIN scalars can already have Arrow's layout.
+-- Numeric buffers are aliased (copied once if misaligned), booleans stay
+-- bit-packed, and binary values go directly to Arrow offsets/data. Other
+-- encodings retain the generic dictionary/delta/multi-page reader.
+readPlainColumn :: P.Compression -> ByteString -> AT.Field -> Either String AC.ColumnArray
+readPlainColumn codec chunk fld | BS.null chunk = liftColumn (ChunkSource codec chunk) fld
+readPlainColumn codec chunk fld = do
+  (header, afterHeader) <- Page.readPageHeaderCheckedAt chunk 0
+  let onePage =
+        maybe
+          False
+          (\size -> size >= 0 && fromIntegral size == BS.length chunk - afterHeader)
+          (Page.phCompressedPageSize header)
+      fallback = liftColumn (ChunkSource codec chunk) fld
+      binary n raw = do
+        buffers <- PR.decodePlainBinaryBuffers n raw
+        let construct = if AT.fieldType fld == AT.AUtf8 then AC.mkUtf8 else AC.mkBinary
+        construct Nothing (PR.binaryOffsets buffers) (PR.binaryData buffers)
+      fixed :: AC.PrimType a -> Int -> Int -> ByteString -> Either String AC.ColumnArray
+      fixed tag width n raw
+        | targetByteOrder /= LittleEndian = fallback
+        | n < 0 || n > BS.length raw `quot` width || n * width /= BS.length raw =
+            Left "Parquet.Arrow: PLAIN primitive count/size mismatch"
+        | otherwise = AC.withPrim tag (Right (AC.primColumn tag (Buffer.bytesToStorable raw)))
+      build n raw = case AT.fieldType fld of
+        AT.AUtf8 -> binary n raw
+        AT.ABinary -> binary n raw
+        AT.AInt 32 True -> fixed AC.PInt32 4 n raw
+        AT.AInt 64 True -> fixed AC.PInt64 8 n raw
+        AT.AInt 32 False -> fixed AC.PUInt32 4 n raw
+        AT.AInt 64 False -> fixed AC.PUInt64 8 n raw
+        AT.AFloatingPoint AT.Single -> fixed AC.PFloat 4 n raw
+        AT.AFloatingPoint AT.DoublePrecision -> fixed AC.PDouble 8 n raw
+        AT.ADate AT.DateDay -> fixed AC.PDate32 4 n raw
+        AT.ATime _ 32 -> fixed AC.PTime32 4 n raw
+        AT.ATime _ 64 -> fixed AC.PTime64 8 n raw
+        AT.ATimestamp _ _ -> fixed AC.PTimestamp 8 n raw
+        AT.ABool
+          | n >= 0
+          , (n + 7) `quot` 8 == BS.length raw ->
+              AC.mkBool Nothing =<< AC.mkBitmap raw 0 n
+          | otherwise -> Left "Parquet.Arrow: PLAIN BOOLEAN count/size mismatch"
+        _ -> fallback
+  case Page.phType header of
+    Page.PtDataPage page
+      | onePage
+      , Page.dphEncoding page == 0 -> do
+          (_, _, raw, _) <- PR.decompressDataPageBody codec chunk 0
+          build (fromIntegral (Page.dphNumValues page)) raw
+    Page.PtDataPageV2 page
+      | onePage
+      , Page.dph2Encoding page == 0
+      , Page.dph2NumNulls page == 0
+      , Page.dph2RepLevelsLen page == 0
+      , Page.dph2DefLevelsLen page == 0 -> do
+          (_, _, _, _, raw, _) <- PR.decompressDataPageV2Body codec 0 0 chunk 0
+          build (fromIntegral (Page.dph2NumValues page)) raw
+    _ -> fallback
+
+
+boolBuffersColumn :: PR.BoolBuffers -> Either String AC.ColumnArray
+boolBuffersColumn values = AC.mkBool Nothing =<< AC.mkBitmap (PR.boolData values) 0 (PR.boolCount values)
+
+
+-- Both indexed and sequential reads use the same checked buffer decoder.
+binaryBuffersColumn :: AT.ArrowType -> PR.BinaryBuffers -> Either String AC.ColumnArray
+binaryBuffersColumn typ buffers = case typ of
+  AT.AUtf8 -> AC.mkUtf8 Nothing (PR.binaryOffsets buffers) (PR.binaryData buffers)
+  AT.ABinary -> AC.mkBinary Nothing (PR.binaryOffsets buffers) (PR.binaryData buffers)
+  _ -> Left "Parquet.Arrow: binary buffers need a native binary or UTF-8 field"
+
+
+largeBinaryBuffersColumn :: AT.ArrowType -> PR.LargeBinaryBuffers -> Either String AC.ColumnArray
+largeBinaryBuffersColumn typ buffers = case typ of
+  AT.ALargeUtf8 -> AC.mkLargeUtf8 Nothing (PR.binaryOffsets buffers) (PR.binaryData buffers)
+  AT.ALargeBinary -> AC.mkLargeBinary Nothing (PR.binaryOffsets buffers) (PR.binaryData buffers)
+  _ -> Left "Parquet.Arrow: large binary buffers need a LargeBinary or LargeUtf8 field"
+
+
+isLargeBinary :: AT.ArrowType -> Bool
+isLargeBinary AT.ALargeUtf8 = True
+isLargeBinary AT.ALargeBinary = True
+isLargeBinary _ = False
+
+
+isNativeBinary :: AT.ArrowType -> Bool
+isNativeBinary AT.AUtf8 = True
+isNativeBinary AT.ABinary = True
+isNativeBinary _ = False
+
+
+nativeScalarPhysical :: AT.ArrowType -> Maybe P.ParquetType
+nativeScalarPhysical typ = case typ of
+  AT.ADecimal32 _ _ -> Just P.PTInt32
+  AT.ADecimal64 _ _ -> Just P.PTInt64
+  AT.AInt 32 _ -> Just P.PTInt32
+  AT.AInt 64 _ -> Just P.PTInt64
+  AT.AFloatingPoint AT.Single -> Just P.PTFloat
+  AT.AFloatingPoint AT.DoublePrecision -> Just P.PTDouble
+  AT.ADate AT.DateDay -> Just P.PTInt32
+  AT.ADate AT.DateMillisecond -> Just P.PTInt64
+  AT.ATime _ 32 -> Just P.PTInt32
+  AT.ATime _ 64 -> Just P.PTInt64
+  AT.ATimestamp _ _ -> Just P.PTInt64
+  AT.ADuration _ -> Just P.PTInt64
+  _ -> Nothing
+
+
+scalarBuffersColumn :: AT.ArrowType -> PR.ScalarBuffers -> Either String AC.ColumnArray
+scalarBuffersColumn typ buffers = case typ of
+  AT.ADecimal32 precision scale
+    | precision >= 1 && precision <= 9 ->
+        let bound = 10 ^ precision - 1 :: Int32
+            values = Buffer.bytesToStorable (PR.scalarData buffers)
+        in if VS.all (\value -> value >= negate bound && value <= bound) values
+             then Right (AC.primColumn (AC.PDecimal32 precision scale) values)
+             else Left "Parquet.Arrow: typed Decimal32 exceeds declared precision"
+  AT.ADecimal64 precision scale
+    | precision >= 10 && precision <= 18 ->
+        let bound = 10 ^ precision - 1 :: Int64
+            values = Buffer.bytesToStorable (PR.scalarData buffers)
+        in if VS.all (\value -> value >= negate bound && value <= bound) values
+             then Right (AC.primColumn (AC.PDecimal64 precision scale) values)
+             else Left "Parquet.Arrow: typed Decimal64 exceeds declared precision"
+  AT.AInt 32 True -> fixed AC.PInt32
+  AT.AInt 64 True -> fixed AC.PInt64
+  AT.AInt 32 False -> fixed AC.PUInt32
+  AT.AInt 64 False -> fixed AC.PUInt64
+  AT.AFloatingPoint AT.Single -> fixed AC.PFloat
+  AT.AFloatingPoint AT.DoublePrecision -> fixed AC.PDouble
+  AT.ADate AT.DateDay -> fixed AC.PDate32
+  AT.ADate AT.DateMillisecond -> fixed AC.PDate64
+  AT.ATime _ 32 -> fixed AC.PTime32
+  AT.ATime _ 64 -> fixed AC.PTime64
+  AT.ATimestamp _ _ -> fixed AC.PTimestamp
+  AT.ADuration _ -> fixed AC.PDuration
+  _ -> Left "Parquet.Arrow: scalar buffers need a matching native primitive field"
+  where
+    fixed :: AC.PrimType a -> Either String AC.ColumnArray
+    fixed tag = AC.withPrim tag (Right (AC.primColumn tag (Buffer.bytesToStorable (PR.scalarData buffers))))
+
+
+{- | A whole column chunk, decoded through generic per-page dispatchers
+which handle every
+encoding the spec defines for the physical type (PLAIN,
+dictionary, DELTA_*, BYTE_STREAM_SPLIT) and both DATA_PAGE and
+DATA_PAGE_V2.
+-}
+data Source
+  = ChunkSource P.Compression ByteString
+
+
+{- | Decode a flat column from a 'Source' at the Arrow target
+type. Required fields read the dense value stream; nullable
+fields read the definition-level form. The optional readers
+take (max_repetition_level, max_definition_level); for a flat
+optional primitive these are (0, 1).
+
+Native scalars retain validated source pages until the final buffer is
+built; definition levels scatter nullable values through the shared
+assembler. Narrow casts use the primitive-vector readers. Byte arrays
+are copied once into the offsets/data buffers.
+-}
+liftColumn :: Source -> AT.Field -> Either String AC.ColumnArray
+liftColumn (ChunkSource codec chunk) fld
+  | Just physical <- nativeScalarPhysical (AT.fieldType fld) =
+      if AT.fieldNullable fld
+        then do
+          levels <- PR.readScalarBuffersLevels physical codec 0 1 chunk
+          values <- scalarBuffersColumn (AT.fieldType fld) (PR.clValues levels)
+          let leaf = AN.LeafColumn (PR.clRepetition levels) (PR.clDefinition levels) values
+          AN.assemble (V.singleton (Right leaf)) (AN.Plan fld 0 0 0 1 AN.Primitive)
+        else scalarBuffersColumn (AT.fieldType fld) =<< PR.readScalarBuffersColumnChunk physical codec chunk
+liftColumn src fld = case AT.fieldType fld of
+  AT.AInt 8 True -> narrow32 AC.PInt8 (\input value -> fromIntegral value == input) fromIntegral
+  AT.AInt 16 True -> narrow32 AC.PInt16 (\input value -> fromIntegral value == input) fromIntegral
+  AT.AInt 32 True -> int32 AC.PInt32
+  AT.AInt 64 True -> int64 AC.PInt64
+  AT.AInt 8 False -> narrow32 AC.PUInt8 (\input value -> fromIntegral value == input) fromIntegral
+  AT.AInt 16 False -> narrow32 AC.PUInt16 (\input value -> fromIntegral value == input) fromIntegral
+  AT.AInt 32 False -> cast32 AC.PUInt32 fromIntegral
+  AT.AInt 64 False -> cast64 AC.PUInt64 fromIntegral
+  AT.AFloatingPoint AT.Single
+    | nullable -> AC.fromMaybes AC.PFloat <$> optFloat src
+    | otherwise -> AC.primColumn AC.PFloat . primToStorable <$> reqFloat src
+  AT.AFloatingPoint AT.DoublePrecision
+    | nullable -> AC.fromMaybes AC.PDouble <$> optDouble src
+    | otherwise -> AC.primColumn AC.PDouble . primToStorable <$> reqDouble src
+  AT.ABool -> case src of
+    ChunkSource codec chunk ->
+      if nullable
+        then do
+          levels <- PR.readBoolBuffersLevels codec 0 1 chunk
+          values <- boolBuffersColumn (PR.clValues levels)
+          let leaf = AN.LeafColumn (PR.clRepetition levels) (PR.clDefinition levels) values
+          AN.assemble (V.singleton (Right leaf)) (AN.Plan fld 0 0 0 1 AN.Primitive)
+        else boolBuffersColumn =<< PR.readBoolBuffersColumnChunk codec chunk
+  AT.AUtf8 -> binary
+  AT.ABinary -> binary
+  AT.ALargeUtf8 -> largeBinary
+  AT.ALargeBinary -> largeBinary
+  -- Temporal: read the underlying int stream and tag it with the
+  -- Arrow column flavour.
+  AT.ADate AT.DateDay -> int32 AC.PDate32
+  AT.ADate AT.DateMillisecond -> int64 AC.PDate64
+  AT.ATime _ 32 -> int32 AC.PTime32
+  AT.ATime _ 64 -> int64 AC.PTime64
+  AT.ATimestamp _ _ -> int64 AC.PTimestamp
+  AT.ADuration _ -> int64 AC.PDuration
+  -- INT96 (legacy 12-byte timestamp) and FIXED_LEN_BYTE_ARRAY
+  -- (UUIDs / float16 / decimal128 in fixed form). Both are
+  -- exposed via 'ColFixedSizeBinary'; the bridge handles the
+  -- required, whole-chunk PLAIN case.
+  AT.AFixedSizeBinary w
+    | not nullable
+    , ChunkSource codec chunk <- src ->
+        fixedSizeBinary w
+          =<< PR.readGenericFixedLenByteArrayColumnChunk w codec chunk
+  other ->
+    Left $
+      "Parquet.Arrow: column type "
+        <> show other
+        <> " (nullable="
+        <> show nullable
+        <> ") not yet supported by the read bridge; use the "
+        <> "specialised readers in Parquet.Read"
+  where
+    !nullable = AT.fieldNullable fld
+    largeBinary = case src of
+      ChunkSource codec chunk
+        | nullable -> do
+            levels <- PR.readLargeBinaryBuffersLevels codec 0 1 chunk
+            values <- largeBinaryBuffersColumn (AT.fieldType fld) (PR.clValues levels)
+            let physical = AN.LeafColumn (PR.clRepetition levels) (PR.clDefinition levels) values
+            AN.assemble (V.singleton (Right physical)) (AN.Plan fld 0 0 0 1 AN.Primitive)
+        | otherwise -> largeBinaryBuffersColumn (AT.fieldType fld) =<< PR.readLargeBinaryBuffersColumnChunk codec chunk
+    binary = case src of
+      ChunkSource codec chunk
+        | nullable -> do
+            levels <- PR.readBinaryBuffersLevels codec 0 1 chunk
+            values <- binaryBuffersColumn (AT.fieldType fld) (PR.clValues levels)
+            let physical = AN.LeafColumn (PR.clRepetition levels) (PR.clDefinition levels) values
+            AN.assemble (V.singleton (Right physical)) (AN.Plan fld 0 0 0 1 AN.Primitive)
+        | otherwise -> binaryBuffersColumn (AT.fieldType fld) =<< PR.readBinaryBuffersColumnChunk codec chunk
+    int32 :: AC.PrimType Int32 -> Either String AC.ColumnArray
+    int32 t
+      | nullable = AC.fromMaybes t <$> optInt32 src
+      | otherwise = AC.primColumn t . primToStorable <$> reqInt32 src
+    int64 :: AC.PrimType Int64 -> Either String AC.ColumnArray
+    int64 t
+      | nullable = AC.fromMaybes t <$> optInt64 src
+      | otherwise = AC.primColumn t . primToStorable <$> reqInt64 src
+    -- Decode only defined values, range-check while narrowing, and scatter
+    -- nulls through the same assembler as nested leaves. No Maybe per row.
+    narrow32 :: AC.PrimType a -> (Int32 -> a -> Bool) -> (Int32 -> a) -> Either String AC.ColumnArray
+    narrow32 tag valid convert = AC.withPrim tag $ case src of
+      ChunkSource codec bytes -> do
+        let maxDef = if nullable then 1 else 0
+        levels <- PR.readInt32Levels codec 0 maxDef bytes
+        let values = PR.clValues levels
+        dense <- buildDenseChecked tag (VP.length values) (VP.unsafeIndex values) valid convert
+        let leaf = AN.LeafColumn (PR.clRepetition levels) (PR.clDefinition levels) dense
+        AN.assemble (V.singleton (Right leaf)) (AN.Plan fld 0 0 0 maxDef AN.Primitive)
+    {-# INLINE narrow32 #-}
+    cast32 :: AC.PrimType a -> (Int32 -> a) -> Either String AC.ColumnArray
+    cast32 t f =
+      AC.withPrim t $
+        if nullable
+          then AC.fromMaybes t . V.map (fmap f) <$> optInt32 src
+          else do
+            xs <- reqInt32 src
+            Right (AC.primColumn t (VS.generate (VP.length xs) (f . VP.unsafeIndex xs)))
+    cast64 :: AC.PrimType a -> (Int64 -> a) -> Either String AC.ColumnArray
+    cast64 t f =
+      AC.withPrim t $
+        if nullable
+          then AC.fromMaybes t . V.map (fmap f) <$> optInt64 src
+          else do
+            xs <- reqInt64 src
+            Right (AC.primColumn t (VS.generate (VP.length xs) (f . VP.unsafeIndex xs)))
+
+
+reqInt32 :: Source -> Either String (VP.Vector Int32)
+reqInt32 (ChunkSource c bs) = PR.readGenericInt32ColumnChunk c bs
+
+
+reqInt64 :: Source -> Either String (VP.Vector Int64)
+reqInt64 (ChunkSource c bs) = PR.readGenericInt64ColumnChunk c bs
+
+
+reqFloat :: Source -> Either String (VP.Vector Float)
+reqFloat (ChunkSource c bs) = PR.readGenericFloatColumnChunk c bs
+
+
+reqDouble :: Source -> Either String (VP.Vector Double)
+reqDouble (ChunkSource c bs) = PR.readGenericDoubleColumnChunk c bs
+
+
+optInt32 :: Source -> Either String (V.Vector (Maybe Int32))
+optInt32 (ChunkSource c bs) = PR.readGenericInt32OptionalColumnChunk c 0 1 bs
+
+
+optInt64 :: Source -> Either String (V.Vector (Maybe Int64))
+optInt64 (ChunkSource c bs) = PR.readGenericInt64OptionalColumnChunk c 0 1 bs
+
+
+optFloat :: Source -> Either String (V.Vector (Maybe Float))
+optFloat (ChunkSource c bs) = PR.readGenericFloatOptionalColumnChunk c 0 1 bs
+
+
+optDouble :: Source -> Either String (V.Vector (Maybe Double))
+optDouble (ChunkSource c bs) = PR.readGenericDoubleOptionalColumnChunk c 0 1 bs
+
+
+{- | Copy a decoder's primitive vector into a pinned Arrow value
+buffer with one @memcpy@.
+-}
+primToStorable :: forall a. Storable a => VP.Vector a -> VS.Vector a
+primToStorable (VP.Vector off n ba) = unsafeDupablePerformIO $ do
+  mv <- VSM.unsafeNew n
+  let !sz = sizeOf (undefined :: a)
+  VSM.unsafeWith mv $ \p -> copyByteArrayToAddr (castPtr p) ba (off * sz) (n * sz)
+  VS.unsafeFreeze mv
+
+
+{- | Retag a binary column built from Parquet BYTE_ARRAY values as
+utf8. The C kernel validates the data in one pass; a column with
+invalid UTF-8 is rejected rather than silently replacing bytes with
+U+FFFD and changing the stored data.
+-}
+utf8FromBinary :: AC.ColumnArray -> Either String AC.ColumnArray
+utf8FromBinary col = case col of
+  AC.ColBinary mv offs dat -> AC.mkUtf8 mv offs dat
+  _ -> Left ("Parquet.Arrow: expected a binary column, got " <> AC.columnTag col)
+
+
+-- Decode schema-annotated primitives through the same dictionary / page
+-- machinery as ordinary columns. Definition levels come from the full path.
+readAnnotatedColumn
+  :: P.SchemaElement -> P.Compression -> ByteString -> Int -> Either String AC.ColumnArray
+readAnnotatedColumn leaf codec chunk maxDef = case arrowTypeFromSchemaElement leaf of
+  AT.ADecimal precision scale
+    | precision >= 1 && precision <= 38 ->
+        let bound = 10 ^ precision - 1 :: Integer
+            low = AC.decimal128FromInteger (negate bound)
+            high = AC.decimal128FromInteger bound
+            valid value = compare128 value low /= LT && compare128 value high /= GT
+        in decimalAs
+             (AC.PDecimal128 precision scale)
+             16
+             decimal128Bytes
+             valid
+             (\n -> AC.Decimal128 (fromIntegral n) (if n < 0 then maxBound else 0))
+             (AC.Decimal128 0 0)
+  AT.ADecimal256 precision scale
+    | precision >= 1 && precision <= 76 ->
+        let bound = 10 ^ precision - 1 :: Integer
+            low = AC.decimal256FromInteger (negate bound)
+            high = AC.decimal256FromInteger bound
+            valid value = compare256 value low /= LT && compare256 value high /= GT
+        in decimalAs
+             (AC.PDecimal256 precision scale)
+             32
+             decimal256Bytes
+             valid
+             (\n -> let sign = if n < 0 then maxBound else 0 in AC.Decimal256 (fromIntegral n) sign sign sign)
+             (AC.Decimal256 0 0 0 0)
+  AT.AFixedSizeBinary width -> do
+    column <- if nullable
+      then fixedOptional width >>= AC.fromMaybeFixedSizeBinary width
+      else fixedRequired width >>= fixedSizeBinary width
+    encoding <- Timestamp.schemaEncoding leaf
+    maybe (Right column) (\kind -> Timestamp.validateTimestampColumn kind column) encoding
+  AT.AFloatingPoint AT.Half ->
+    if nullable
+      then do
+        values <- fixedOptional 2
+        buildOptionalChecked AC.PFloat16 values (\bytes _ -> BS.length bytes == 2) half (AC.Float16 0)
+      else do
+        values <- fixedRequired 2
+        buildDenseChecked
+          AC.PFloat16
+          (V.length values)
+          (V.unsafeIndex values)
+          (\bytes _ -> BS.length bytes == 2)
+          half
+  _ -> Left "Parquet.Arrow: annotated primitive is not representable by this Arrow type"
+  where
+    nullable = maxDef > 0
+    fixedRequired width = PR.readGenericFixedLenByteArrayColumnChunk width codec chunk
+    fixedOptional width = PR.readGenericFixedLenByteArrayOptionalColumnChunk width codec 0 maxDef chunk
+    half bytes =
+      AC.Float16
+        ( fromIntegral (BSU.unsafeIndex bytes 0)
+            .|. (fromIntegral (BSU.unsafeIndex bytes 1) `shiftL` 8)
+        )
+    decimalAs
+      :: Storable d
+      => AC.PrimType d
+      -> Int
+      -> (ByteString -> d)
+      -> (d -> Bool)
+      -> (Int64 -> d)
+      -> d
+      -> Either String AC.ColumnArray
+    decimalAs primitive width decode valid fromInt zero = case P.seType leaf of
+      Just P.PTInt32 ->
+        if nullable
+          then do
+            values <- PR.readGenericInt32OptionalColumnChunk codec 0 maxDef chunk
+            buildOptionalChecked primitive values (\_ -> valid) (fromInt . fromIntegral) zero
+          else do
+            values <- PR.readGenericInt32ColumnChunk codec chunk
+            buildDenseChecked
+              primitive
+              (VP.length values)
+              (VP.unsafeIndex values)
+              (\_ -> valid)
+              (fromInt . fromIntegral)
+      Just P.PTInt64 ->
+        if nullable
+          then do
+            values <- PR.readGenericInt64OptionalColumnChunk codec 0 maxDef chunk
+            buildOptionalChecked primitive values (\_ -> valid) fromInt zero
+          else do
+            values <- PR.readGenericInt64ColumnChunk codec chunk
+            buildDenseChecked primitive (VP.length values) (VP.unsafeIndex values) (\_ -> valid) fromInt
+      Just P.PTByteArray ->
+        if nullable
+          then do
+            values <- PR.readGenericByteArrayOptionalColumnChunk codec 0 maxDef chunk
+            buildOptionalChecked primitive values (validBytes width valid) decode zero
+          else do
+            values <- PR.readGenericByteArrayColumnChunk codec chunk
+            buildDenseChecked primitive (V.length values) (V.unsafeIndex values) (validBytes width valid) decode
+      Just P.PTFixedLenByteArray -> case P.seTypeLength leaf of
+        Just physicalWidth ->
+          if nullable
+            then do
+              values <- fixedOptional (fromIntegral physicalWidth)
+              buildOptionalChecked primitive values (validBytes width valid) decode zero
+            else do
+              values <- fixedRequired (fromIntegral physicalWidth)
+              buildDenseChecked primitive (V.length values) (V.unsafeIndex values) (validBytes width valid) decode
+        Nothing -> Left "Parquet.Arrow: missing decimal fixed byte width"
+      _ -> Left "Parquet.Arrow: DECIMAL physical type is unsupported"
+    validBytes width valid bytes value =
+      not (BS.null bytes)
+        && fitsSignedBytes width bytes
+        && valid value
+
+
+-- Page-level Either only: the per-value loop uses a Boolean branch and
+-- writes directly to a storable vector. No per-row Either/Maybe is created.
+buildDenseChecked
+  :: Storable b
+  => AC.PrimType b
+  -> Int
+  -> (Int -> a)
+  -> (a -> b -> Bool)
+  -> (a -> b)
+  -> Either String AC.ColumnArray
+buildDenseChecked primitive count get valid convert = runST $ do
+  output <- VSM.new count
+  let loop !i
+        | i == count = pure True
+        | otherwise =
+            let input = get i
+                value = convert input
+            in if valid input value
+                 then VSM.unsafeWrite output i value >> loop (i + 1)
+                 else pure False
+  good <- loop 0
+  if good
+    then Right . AC.primColumn primitive <$> VS.unsafeFreeze output
+    else pure (Left "Parquet.Arrow: annotated value exceeds its physical/logical range")
+{-# INLINE buildDenseChecked #-}
+
+
+buildOptionalChecked
+  :: Storable b
+  => AC.PrimType b
+  -> V.Vector (Maybe a)
+  -> (a -> b -> Bool)
+  -> (a -> b)
+  -> b
+  -> Either String AC.ColumnArray
+buildOptionalChecked primitive values valid convert zero = do
+  vector <- runST $ do
+    output <- VSM.new count
+    let loop !i
+          | i == count = pure True
+          | otherwise = case V.unsafeIndex values i of
+              Nothing -> VSM.unsafeWrite output i zero >> loop (i + 1)
+              Just input ->
+                let value = convert input
+                in if valid input value
+                     then VSM.unsafeWrite output i value >> loop (i + 1)
+                     else pure False
+    good <- loop 0
+    if good
+      then Right <$> VS.unsafeFreeze output
+      else pure (Left "Parquet.Arrow: annotated value exceeds its physical/logical range")
+  AC.mkPrim primitive (AC.validityGenerate count present) vector
+  where
+    count = V.length values
+    present i = case V.unsafeIndex values i of Just _ -> True; Nothing -> False
+{-# INLINE buildOptionalChecked #-}
+
+
+-- Read a sign-extended limb from the end of a big-endian two's-complement
+-- byte string. Decimal precision is checked against precomputed word bounds;
+-- Integer is used once per column, never inside the per-value loop.
+decimalLimb :: ByteString -> Int -> Word64
+decimalLimb bytes limb = go 0 0
+  where
+    count = BS.length bytes
+    extension = if count > 0 && BSU.unsafeIndex bytes 0 .&. 0x80 /= 0 then 0xff else 0
+    start = count - (limb + 1) * 8
+    go !j !acc
+      | j == 8 = acc
+      | otherwise =
+          let index = start + j
+              byte = if index < 0 then extension else BSU.unsafeIndex bytes index
+          in go (j + 1) ((acc `shiftL` 8) .|. fromIntegral byte)
+{-# INLINE decimalLimb #-}
+
+
+decimal128Bytes :: ByteString -> AC.Decimal128
+decimal128Bytes bytes = AC.Decimal128 (decimalLimb bytes 0) (decimalLimb bytes 1)
+{-# INLINE decimal128Bytes #-}
+
+
+decimal256Bytes :: ByteString -> AC.Decimal256
+decimal256Bytes bytes =
+  AC.Decimal256
+    (decimalLimb bytes 0)
+    (decimalLimb bytes 1)
+    (decimalLimb bytes 2)
+    (decimalLimb bytes 3)
+{-# INLINE decimal256Bytes #-}
+
+
+fitsSignedBytes :: Int -> ByteString -> Bool
+fitsSignedBytes width bytes
+  | extra <= 0 = True
+  | otherwise = go 0
+  where
+    extra = BS.length bytes - width
+    sign = if BSU.unsafeIndex bytes extra .&. 0x80 /= 0 then 0xff else 0
+    go !i
+      | i == extra = True
+      | BSU.unsafeIndex bytes i == sign = go (i + 1)
+      | otherwise = False
+{-# INLINE fitsSignedBytes #-}
+
+
+compare128 :: AC.Decimal128 -> AC.Decimal128 -> Ordering
+compare128 (AC.Decimal128 lo hi) (AC.Decimal128 lo' hi') =
+  case compare (fromIntegral hi :: Int64) (fromIntegral hi') of
+    EQ -> compare lo lo'
+    order -> order
+{-# INLINE compare128 #-}
+
+
+compare256 :: AC.Decimal256 -> AC.Decimal256 -> Ordering
+compare256 (AC.Decimal256 a b c d) (AC.Decimal256 a' b' c' d') =
+  case compare (fromIntegral d :: Int64) (fromIntegral d') of
+    EQ -> case compare c c' of
+      EQ -> case compare b b' of EQ -> compare a a'; order -> order
+      order -> order
+    order -> order
+{-# INLINE compare256 #-}
+
+
+-- | One fixed-size-binary column from equal-width values (one copy).
+fixedSizeBinary :: Int -> V.Vector ByteString -> Either String AC.ColumnArray
+fixedSizeBinary w vals
+  | BS.length dat /= w * rows =
+      Left ("Parquet.Arrow: fixed-size binary values are not all " <> show w <> " bytes")
+  | otherwise = AC.mkFixedSizeBinary w rows Nothing dat
+  where
+    !rows = V.length vals
+    !dat = BS.concat (V.toList vals)
+
+
+{- | Look up the column's 'Compression' codec from the footer.
+| Compute @max_repetition_level@ for a column chunk by
+walking its 'cmPathInSchema' back through the file's schema
+and counting 'Repeated' elements. Returns 'Nothing' if the
+chunk's metadata is absent or the path can't be resolved
+(in which case the caller should treat it as conservatively
+repetition-bearing).
+
+Spec: parquet-format/Nested-Layout.md, "Computing levels".
+max_repetition_level = number of @REPEATED@ elements on the
+path from the root to (and including) the leaf.
+-}
+
+-- ============================================================
+-- Arrow → Parquet.Nested (nested types)
+-- ============================================================
+
+{- | Map an Arrow 'AT.Field' onto a 'PN.NestedSchema' tree
+suitable for 'Parquet.HighLevel.encodeParquetNested'. Handles
+flat primitives (wraps them in 'PN.NSRequired' / 'PN.NSOptional'
+based on 'fieldNullable'), struct, list and map types. Integer and
+temporal annotations match the flat bridge. Pass this same field to
+'columnArrayToNestedRows' so schema and payload normalization agree.
+-}
+arrowFieldToNestedSchema
+  :: AT.Field -> Either String PN.NestedSchema
+arrowFieldToNestedSchema f
+  | Just _ <- AT.fieldDictionary f = Left "Parquet.Arrow: nested dictionary fields are not supported"
+  | VariantSchema.isVariantField f = do
+      storage <- VariantSchema.compileVariantStorageSchema f
+      pure ((if AT.fieldNullable f then PN.NSOptional else PN.NSRequired) (PN.NSVariantTyped storage))
+  | otherwise = do
+      core <- case AT.fieldType f of
+        _ | FileArrow.isFileField f -> PN.NSFile <$> FileArrow.fileSchemaFromField f
+        AT.AStruct ->
+          PN.NSStruct
+            <$> V.mapM
+              (\child -> (,) (AT.fieldName child) <$> arrowFieldToNestedSchema child)
+              (AT.fieldChildren f)
+        AT.AList -> listSchema
+        AT.ALargeList -> listSchema
+        AT.AMap _ -> case V.toList (AT.fieldChildren f) of
+          [entries]
+            | AT.fieldType entries == AT.AStruct
+            , not (AT.fieldNullable entries)
+            , [key, value] <- V.toList (AT.fieldChildren entries)
+            , not (AT.fieldNullable key) ->
+                PN.NSMap <$> arrowFieldToNestedSchema key <*> arrowFieldToNestedSchema value
+          _ -> Left "Parquet.Arrow: a map needs a required entries struct and required key"
+        _ -> PN.NSPrimitive <$> primitiveNestedType f
+      Right (if AT.fieldNullable f then PN.NSOptional core else PN.NSRequired core)
+  where
+    listSchema = case V.toList (AT.fieldChildren f) of
+      [child] -> PN.NSList <$> arrowFieldToNestedSchema child
+      _ -> Left "Parquet.Arrow: a list must have exactly one child field"
+
+
+-- Reuse flat lowering's type/unit decisions, including its explicit
+-- rejection of durations and invalid time-unit/width combinations.
+primitiveNestedType :: AT.Field -> Either String PN.LeafType
+primitiveNestedType field
+  | Just (DecimalParameters precision scale) <- decimalParameters (AT.fieldType field) = do
+      AT.validateDecimalType (AT.fieldType field)
+      if scale < 0 || scale > precision
+        then Left "Parquet.Arrow: Parquet DECIMAL scale must be between zero and precision"
+        else Right (PN.LtDecimal (fromIntegral precision) (fromIntegral scale))
+  | Timestamp.isTimestampField field = do
+      encoding <- Timestamp.timestampEncoding field
+      case encoding of
+        Just (Timestamp.SignedTimestamp96 adjusted unit) -> Right (PN.LtTimestamp96 adjusted unit)
+        Just Timestamp.JulianInt96 -> Right PN.LtInt96
+        Nothing -> Left "Parquet.Arrow: missing timestamp encoding"
+  | AT.AFixedSizeBinary width <- AT.fieldType field =
+      if width <= 0 || toInteger width > toInteger (maxBound :: Int32)
+        then Left "Parquet.Arrow: fixed-byte width must fit a positive INT32"
+        else
+          if V.elem ("ARROW:extension:name", "arrow.uuid") (AT.fieldMetadata field)
+            then
+              let names = V.map snd (V.filter ((== "ARROW:extension:name") . fst) (AT.fieldMetadata field))
+                  parameters = V.map snd (V.filter ((== "ARROW:extension:metadata") . fst) (AT.fieldMetadata field))
+              in if width == 16 && names == V.singleton "arrow.uuid" && V.length parameters <= 1 && V.all T.null parameters
+                   then Right PN.LtUuid
+                   else Left "Parquet.Arrow: UUID requires16bytes and unique parameterless extension metadata"
+            else Right (PN.LtFixedBinary (fromIntegral width))
+  | AT.AUtf8View <- AT.fieldType field = Right PN.LtString
+  | AT.ABinaryView <- AT.fieldType field = Right PN.LtBinary
+  | otherwise = primitiveNestedTypeBasic field
+
+
+data DecimalParameters = DecimalParameters
+  { parameterPrecision :: {-# UNPACK #-} !Int
+  , parameterScale :: {-# UNPACK #-} !Int
+  }
+
+
+decimalParameters :: AT.ArrowType -> Maybe DecimalParameters
+decimalParameters typ = case typ of
+  AT.ADecimal32 precision scale -> Just (DecimalParameters precision scale)
+  AT.ADecimal64 precision scale -> Just (DecimalParameters precision scale)
+  AT.ADecimal precision scale -> Just (DecimalParameters precision scale)
+  AT.ADecimal256 precision scale -> Just (DecimalParameters precision scale)
+  _ -> Nothing
+
+
+primitiveNestedTypeBasic :: AT.Field -> Either String PN.LeafType
+primitiveNestedTypeBasic field = do
+  physical <- arrowFieldToSchemaElement field
+  case (P.seType physical, P.seLogicalType physical) of
+    (_, Just (P.LTInteger width signed)) -> Right (PN.LtInteger width signed)
+    (_, Just P.LTFloat16) -> Right PN.LtFloat16
+    (_, Just P.LTDate) -> Right PN.LtDate
+    (_, Just (P.LTTime adjusted unit)) -> Right (PN.LtTime adjusted unit)
+    (_, Just (P.LTTimestamp adjusted unit)) -> Right (PN.LtTimestamp adjusted unit)
+    (_, Just P.LTString) -> Right PN.LtString
+    (_, Just P.LTJson) -> Right PN.LtJson
+    (Just P.PTInt32, Nothing) -> Right PN.LtInt32
+    (Just P.PTInt64, Nothing) -> Right PN.LtInt64
+    (Just P.PTFloat, Nothing) -> Right PN.LtFloat
+    (Just P.PTDouble, Nothing) -> Right PN.LtDouble
+    (Just P.PTBoolean, Nothing) -> Right PN.LtBool
+    (Just P.PTByteArray, Nothing) -> Right PN.LtBinary
+    _ -> Left "Parquet.Arrow: unsupported nested primitive annotation"
+
+
+{- | Lower an Arrow column using its field's types and temporal units.
+Only values reachable through present parents are examined. Required
+children may carry null/poison storage beneath a null parent; such slots
+have no Parquet value. Units are normalized in the same way as flat
+lowering (DATE64 to days, seconds to milliseconds), without truncation.
+-}
+columnArrayToNestedRows
+  :: AT.Field -> AC.ColumnArray -> Either String (V.Vector PN.NestedRow)
+columnArrayToNestedRows field input = do
+  _ <- arrowFieldToNestedSchema field
+  column <- VariantArray.alignVariantColumns field input
+  -- Validate shapes once; enforce nullability only for visible rows.
+  validateColumns (V.singleton (relaxNullability field)) (V.singleton column)
+  plan <- nestedRowPlan field column
+  case AC.columnLength column of
+    I# count -> case Generate.generate# count (nestedRowAt# plan) of
+      (# message | #) -> Left message
+      (# | rows #) -> Right rows
+  where
+    relaxNullability f =
+      let children = V.map relaxNullability (AT.fieldChildren f)
+          kept = if AT.fieldType f == AT.ARunEndEncoded && not (V.null children) then children V.// [(0, (V.head children) {AT.fieldNullable = False})] else children
+      in f {AT.fieldNullable = True, AT.fieldChildren = kept}
+
+
+newtype NestedRowPlan = NestedRowPlan
+  { nestedRowAt# :: Int# -> (# String | PN.NestedRow #)
+  }
+
+
+
+
+
+nestedRowPlan :: AT.Field -> AC.ColumnArray -> Either String NestedRowPlan
+nestedRowPlan field column
+  | VariantSchema.isVariantField field = do
+      _ <- VariantSchema.compileVariantStorageSchema field
+      -- Keep source nullability so a visible required child is checked.
+      -- Only metadata's storage encoding changes for the native row view.
+      let children = V.map (\child -> if AT.fieldName child == "metadata" then child {AT.fieldType = AT.ABinary, AT.fieldDictionary = Nothing, AT.fieldChildren = V.empty} else child) (AT.fieldChildren field)
+          raw = field {AT.fieldMetadata = V.filter (\(key, _) -> key /= "ARROW:extension:name" && key /= "ARROW:extension:metadata") (AT.fieldMetadata field), AT.fieldChildren = children}
+      nestedRowPlan raw column
+nestedRowPlan field column = do
+  present <- case column of
+    AC.ColStruct {} | FileArrow.isFileField field -> do
+      schema <- FileArrow.fileSchemaFromField field
+      reader <- File.compileFileReader schema column
+      pure $ \index -> case File.fileReferenceAt# reader index of
+        (# message | | #) -> (# message | #)
+        (# | reference | #) -> (# | PN.NRFile reference #)
+        (# | | () #) -> (# | PN.NRNull #)
+    AC.ColInt8 _ xs -> pure (primitive (PN.LvInt32 . fromIntegral) xs)
+    AC.ColInt16 _ xs -> pure (primitive (PN.LvInt32 . fromIntegral) xs)
+    AC.ColInt32 _ xs -> pure (primitive PN.LvInt32 xs)
+    AC.ColInt64 _ xs -> pure (primitive PN.LvInt64 xs)
+    AC.ColUInt8 _ xs -> pure (primitive (PN.LvInt32 . fromIntegral) xs)
+    AC.ColUInt16 _ xs -> pure (primitive (PN.LvInt32 . fromIntegral) xs)
+    AC.ColUInt32 _ xs -> pure (primitive (PN.LvInt32 . fromIntegral) xs)
+    AC.ColUInt64 _ xs -> pure (primitive (PN.LvInt64 . fromIntegral) xs)
+    AC.ColDate32 _ xs -> pure (primitive PN.LvInt32 xs)
+    AC.ColDate64 _ xs -> pure (primitive PN.LvInt64 xs)
+    AC.ColTime32 _ xs -> pure (primitive PN.LvInt32 xs)
+    AC.ColTime64 _ xs -> pure (primitive PN.LvInt64 xs)
+    AC.ColTimestamp _ xs -> pure (primitive PN.LvInt64 xs)
+    AC.ColFloat16 _ xs -> pure (primitive (\(AC.Float16 bits) -> PN.LvFloat16 bits) xs)
+    AC.ColFloat _ xs -> pure (primitive PN.LvFloat xs)
+    AC.ColDouble _ xs -> pure (primitive PN.LvDouble xs)
+    AC.ColDecimal32 precision _ _ xs -> pure (decimal32Rows precision xs)
+    AC.ColDecimal64 precision _ _ xs -> pure (decimal64Rows precision xs)
+    AC.ColDecimal128 precision _ _ xs -> pure (decimal128Rows precision xs)
+    AC.ColDecimal256 precision _ _ xs -> pure (decimal256Rows precision xs)
+    AC.ColFixedSizeBinary {} -> pure (\index -> fromMaybeValue# PN.LvFixedBinary (AC.anyBytesAt column (I# index)))
+    AC.ColUtf8View {} -> pure (\index -> fromMaybeValue# PN.LvString (AC.anyTextAt column (I# index)))
+    AC.ColBinaryView {} -> pure (\index -> fromMaybeValue# PN.LvBinary (AC.anyBytesAt column (I# index)))
+    AC.ColDictionary {} | AT.fieldType field == AT.ABinary -> metadataPlan
+    AC.ColRunEndEncoded {} | AT.fieldType field == AT.ABinary -> metadataPlan
+    AC.ColStruct _ _ children -> do
+      plans <- V.zipWithM (\f (_, c) -> nestedRowPlan f c) (AT.fieldChildren field) children
+      pure $ \index -> case V.length plans of
+        I# count -> case Generate.generate# count (\child -> nestedRowAt# (V.unsafeIndex plans (I# child)) index) of
+          (# message | #) -> (# message | #)
+          (# | rows #) -> (# | PN.NRStruct rows #)
+    AC.ColList _ offsets child -> listPlan offsets child
+    AC.ColLargeList _ offsets child -> listPlan offsets child
+    AC.ColListView _ offsets sizes child -> do
+      plan <- nestedRowPlan (V.head (AT.fieldChildren field)) child
+      let !childRows = AC.columnLength child
+      pure $ \index ->
+        let !start = fromIntegral (VS.unsafeIndex offsets (I# index))
+            !count = fromIntegral (VS.unsafeIndex sizes (I# index))
+        in if start < 0 || count < 0 || start > childRows || count > childRows - start
+             then (# "Parquet.Arrow: nested list-view range is outside its column" | #)
+             else case start of
+               I# start# -> case count of
+                 I# count# -> case Generate.generate# count# (\offset -> nestedRowAt# plan (start# +# offset)) of
+                   (# message | #) -> (# message | #)
+                   (# | rows #) -> (# | PN.NRList rows #)
+    AC.ColMap _ offsets keys values -> do
+      let entries = V.unsafeHead (AT.fieldChildren field)
+          keyField = V.unsafeIndex (AT.fieldChildren entries) 0
+          valueField = V.unsafeIndex (AT.fieldChildren entries) 1
+          !childRows = AC.columnLength keys
+          !sorted = case AT.fieldType field of AT.AMap True -> True; _ -> False
+      keyPlan <- nestedRowPlan keyField keys
+      valuePlan <- nestedRowPlan valueField values
+      let row index = case checkedNestedRange# offsets childRows index of
+            (# message | #) -> (# message | #)
+            (# | (# start, count #) #) ->
+              case Generate.generate#
+                count
+                ( \offset ->
+                    case nestedRowAt# keyPlan (start +# offset) of
+                      (# message | #) -> (# message | #)
+                      (# | !key #) -> case nestedRowAt# valuePlan (start +# offset) of
+                        (# message | #) -> (# message | #)
+                        (# | !value #) -> (# | (key, value) #)
+                ) of
+                (# message | #) -> (# message | #)
+                (# | pairs #) -> (# | PN.NRMapEntries pairs #)
+      pure $ \index ->
+        if sorted
+          then case AC.validateMapKeysSorted (AC.sliceColumnArray (I# index) 1 column) of
+            Left message -> (# message | #)
+            Right () -> row index
+          else row index
+    _
+      | Just values <- AC.asBool column -> pure (\index -> fromMaybeValue# PN.LvBool (AC.boolArrayAt values (I# index)))
+      | Just values <- AC.asUtf8 column -> pure (\index -> fromMaybeValue# PN.LvString (AC.unsafeTextAt values (I# index)))
+      | Just values <- AC.asLargeUtf8 column -> pure (\index -> fromMaybeValue# PN.LvString (AC.unsafeTextAt values (I# index)))
+      | Just values <- AC.asBinary column -> pure (\index -> fromMaybeValue# PN.LvBinary (AC.unsafeBytesAt values (I# index)))
+      | Just values <- AC.asLargeBinary column -> pure (\index -> fromMaybeValue# PN.LvBinary (AC.unsafeBytesAt values (I# index)))
+      | otherwise -> Left ("Parquet.Arrow: unsupported nested column " ++ AC.columnTag column)
+  Right $ NestedRowPlan $ \index ->
+    if AC.isValidAt (AC.validity column) (I# index)
+      then present index
+      else
+        if AT.fieldNullable field
+          then (# | PN.NRNull #)
+          else (# "Parquet.Arrow: null at required nested field " ++ show (AT.fieldName field) | #)
+  where
+    metadataPlan = do
+      reader <- VariantArray.compileBytes column
+      pure $ \index -> case VariantArray.bytesAt# reader index of
+        (# | () #) -> (# "Parquet.Arrow: present Variant root has null metadata" | #)
+        (# bytes | #) -> (# | PN.NRLeaf (PN.LvBinary bytes) #)
+    primitive :: Storable a => (a -> PN.LeafValue) -> VS.Vector a -> Int# -> (# String | PN.NestedRow #)
+    primitive wrap values index = case normalizeNestedValue# field (wrap (VS.unsafeIndex values (I# index))) of
+      (# message | #) -> (# message | #)
+      (# | value #) -> let !row = PN.NRLeaf value in (# | row #)
+    {-# INLINE primitive #-}
+    listPlan :: (Storable o, Integral o) => VS.Vector o -> AC.ColumnArray -> Either String (Int# -> (# String | PN.NestedRow #))
+    listPlan offsets child = do
+      plan <- nestedRowPlan (V.unsafeHead (AT.fieldChildren field)) child
+      let !childRows = AC.columnLength child
+      pure $ \index -> case checkedNestedRange# offsets childRows index of
+        (# message | #) -> (# message | #)
+        (# | (# start, count #) #) -> case Generate.generate# count (\offset -> nestedRowAt# plan (start +# offset)) of
+          (# message | #) -> (# message | #)
+          (# | rows #) -> (# | PN.NRList rows #)
+    {-# INLINE listPlan #-}
+
+
+-- Precompute precision bounds once per column and retain concrete workers.
+-- Decimal narrowing is checked before conversion, including at negative
+-- extremes; null or poisoned child slots are never visited by the parent plan.
+decimal32Rows :: Int -> VS.Vector Int32 -> Int# -> (# String | PN.NestedRow #)
+decimal32Rows precision values =
+  let !bound = fromInteger (10 ^ precision) :: Int32
+  in \index ->
+       let !value = VS.unsafeIndex values (I# index)
+       in if value > negate bound && value < bound
+            then (# | PN.NRLeaf (PN.LvInt32 value) #)
+            else (# "Parquet.Arrow: decimal exceeds its declared precision" | #)
+
+
+decimal64Rows :: Int -> VS.Vector Int64 -> Int# -> (# String | PN.NestedRow #)
+decimal64Rows precision values =
+  let !bound = fromInteger (10 ^ precision) :: Int64
+  in \index ->
+       let !value = VS.unsafeIndex values (I# index)
+       in if value > negate bound && value < bound
+            then (# | PN.NRLeaf (if precision <= 9 then PN.LvInt32 (fromIntegral value) else PN.LvInt64 value) #)
+            else (# "Parquet.Arrow: decimal exceeds its declared precision" | #)
+
+
+decimal128Rows :: Int -> VS.Vector AC.Decimal128 -> Int# -> (# String | PN.NestedRow #)
+decimal128Rows precision values =
+  let !bound = 10 ^ precision
+      !low = AC.decimal128FromInteger (negate bound)
+      !high = AC.decimal128FromInteger bound
+  in \index ->
+       let !value@(AC.Decimal128 limb _) = VS.unsafeIndex values (I# index)
+       in if compare128 value low == GT && compare128 value high == LT
+            then (# | PN.NRLeaf (if precision <= 9 then PN.LvInt32 (fromIntegral limb) else if precision <= 18 then PN.LvInt64 (fromIntegral limb) else PN.LvFixedBinary (decimal128BigEndian value)) #)
+            else (# "Parquet.Arrow: decimal exceeds its declared precision" | #)
+
+
+decimal256Rows :: Int -> VS.Vector AC.Decimal256 -> Int# -> (# String | PN.NestedRow #)
+decimal256Rows precision values =
+  let !bound = 10 ^ precision
+      !low = AC.decimal256FromInteger (negate bound)
+      !high = AC.decimal256FromInteger bound
+  in \index ->
+       let !value@(AC.Decimal256 limb limb1 _ _) = VS.unsafeIndex values (I# index)
+       in if compare256 value low == GT && compare256 value high == LT
+            then (# | PN.NRLeaf (if precision <= 9 then PN.LvInt32 (fromIntegral limb) else if precision <= 18 then PN.LvInt64 (fromIntegral limb) else if precision <= 38 then PN.LvFixedBinary (decimal128BigEndian (AC.Decimal128 limb limb1)) else PN.LvFixedBinary (decimal256BigEndian value)) #)
+            else (# "Parquet.Arrow: decimal exceeds its declared precision" | #)
+
+
+decimal128BigEndian :: AC.Decimal128 -> ByteString
+decimal128BigEndian (AC.Decimal128 low high) = BSI.unsafeCreate 16 $ \ptr -> do
+  pokeByteOff ptr 0 (byteSwap64 high)
+  pokeByteOff ptr 8 (byteSwap64 low)
+
+
+decimal256BigEndian :: AC.Decimal256 -> ByteString
+decimal256BigEndian (AC.Decimal256 limb0 limb1 limb2 limb3) = BSI.unsafeCreate 32 $ \ptr -> do
+  pokeByteOff ptr 0 (byteSwap64 limb3)
+  pokeByteOff ptr 8 (byteSwap64 limb2)
+  pokeByteOff ptr 16 (byteSwap64 limb1)
+  pokeByteOff ptr 24 (byteSwap64 limb0)
+
+
+fromMaybeValue# :: (a -> PN.LeafValue) -> Maybe a -> (# String | PN.NestedRow #)
+fromMaybeValue# wrap value = case value of
+  Nothing -> (# "Parquet.Arrow: missing nested value in a present slot" | #)
+  Just present -> let !row = PN.NRLeaf (wrap present) in (# | row #)
+{-# INLINE fromMaybeValue# #-}
+
+
+checkedNestedRange# :: (Storable o, Integral o) => VS.Vector o -> Int -> Int# -> (# String | (# Int#, Int# #) #)
+checkedNestedRange# offsets childRows index =
+  let !first = VS.unsafeIndex offsets (I# index)
+      !lastOffset = VS.unsafeIndex offsets (I# (index +# 1#))
+      !start = fromIntegral first :: Int
+      !end = fromIntegral lastOffset :: Int
+  in if fromIntegral start /= first || fromIntegral end /= lastOffset || start < 0 || end < start || end > childRows
+       then (# "Parquet.Arrow: nested child range is outside its column" | #)
+       else case start of I# start# -> case end - start of I# count# -> (# | (# start#, count# #) #)
+{-# INLINE checkedNestedRange# #-}
+
+
+normalizeNestedValue# :: AT.Field -> PN.LeafValue -> (# String | PN.LeafValue #)
+normalizeNestedValue# field value = case (AT.fieldType field, value) of
+  (AT.ADate AT.DateMillisecond, PN.LvInt64 milliseconds) ->
+    let (days, rest) = milliseconds `quotRem` 86400000
+    in if rest == 0 && days >= fromIntegral (minBound :: Int32) && days <= fromIntegral (maxBound :: Int32)
+         then (# | PN.LvInt32 (fromIntegral days) #)
+         else (# message | #)
+  (AT.ATime AT.Second 32, PN.LvInt32 seconds)
+    | seconds >= 0 && seconds < 86400 -> (# | PN.LvInt32 (seconds * 1000) #)
+    | otherwise -> (# message | #)
+  (AT.ATime AT.Millisecond 32, PN.LvInt32 milliseconds)
+    | milliseconds >= 0 && milliseconds < 86400000 -> (# | value #)
+    | otherwise -> (# message | #)
+  (AT.ATime AT.Microsecond 64, PN.LvInt64 microseconds)
+    | microseconds >= 0 && microseconds < 86400000000 -> (# | value #)
+    | otherwise -> (# message | #)
+  (AT.ATime AT.Nanosecond 64, PN.LvInt64 nanoseconds)
+    | nanoseconds >= 0 && nanoseconds < 86400000000000 -> (# | value #)
+    | otherwise -> (# message | #)
+  (AT.ATimestamp AT.Second _, PN.LvInt64 seconds)
+    | seconds >= (minBound :: Int64) `quot` 1000 && seconds <= (maxBound :: Int64) `quot` 1000 ->
+        (# | PN.LvInt64 (seconds * 1000) #)
+    | otherwise -> (# message | #)
+  _ -> (# | value #)
+  where
+    message = "Parquet.Arrow: nested temporal value loses precision or exceeds its range"
+{-# INLINE normalizeNestedValue# #-}
+
+
+-- ============================================================
+-- Streaming reader
+-- ============================================================
+
+{- | Number of row groups in the file. Useful as a loop bound for
+'parquetRowGroupToArrow' / 'streamRowGroups'.
+-}
+numRowGroups :: PR.ParquetFile -> Int
+numRowGroups pf =
+  V.length (P.fmRowGroups (PR.pfFooter pf))
+
+
+{- | Lazily project every row group of a Parquet file into Arrow
+columns, mirroring pyarrow's @ParquetFile.iter_batches()@. The
+resulting list defers the per-row-group decode until the
+consumer pulls the corresponding @Either@; failed row groups
+surface their parse error in the @Left@ slot without aborting
+the rest of the stream.
+
+@
+pf <- 'Parquet.HighLevel.decodeParquet' bytes
+forM_ ('streamRowGroups' arrowSchema pf) $ \\rg -> case rg of
+  Right cols -> consume cols
+  Left  err  -> log err
+@
+-}
+streamRowGroups
+  :: AT.Schema
+  -> PR.ParquetFile
+  -> [Either String (V.Vector AC.ColumnArray)]
+streamRowGroups sch pf =
+  [ case parquetRowGroupToArrow sch pf i of
+      Right cols -> Right cols
+      Left err -> Left (show err)
+  | i <- [0 .. numRowGroups pf - 1]
+  ]
+
+
+{- | Iterator-shaped variant of 'streamRowGroups'. Each
+'IS.iterStep' decodes one row group on demand. Use
+'Columnar.Stream.iterTake' / 'Columnar.Stream.iterFold' /
+friends to drive it without materialising every row group up
+front.
+
+Behaves like 'streamRowGroups' for the per-row-group decode
+(same target Arrow schema controls projection / coercion);
+the difference is that decoding errors halt the iterator at
+the failing step instead of being threaded through a list.
+-}
+streamRowGroupsIter
+  :: AT.Schema
+  -> PR.ParquetFile
+  -> IS.Iter (V.Vector AC.ColumnArray)
+streamRowGroupsIter sch pf =
+  IS.iterFromIndexed (numRowGroups pf) $ \i ->
+    case parquetRowGroupToArrow sch pf i of
+      Right cols -> Right cols
+      Left err -> Left (show err)
+
+
+{- | Like 'streamRowGroupsIter' but projects each row group to a
+subset of named columns (and an optional reordering). The
+caller supplies the target Arrow schema /before/ projection;
+this helper extracts the named subset and runs the
+per-row-group decode against the narrower schema, so only the
+requested columns are read off disk.
+
+Names not present in the source schema cause every iterator
+step to fail with the same error (matching the
+'Arrow.Stream.streamReaderProjectedIter' shape).
+-}
+streamRowGroupsProjectedIter
+  :: AT.Schema
+  -> [Text]
+  -> PR.ParquetFile
+  -> IS.Iter (V.Vector AC.ColumnArray)
+streamRowGroupsProjectedIter sch names pf =
+  case projectFields names sch of
+    Left e -> IS.iterUnfold () (\_ -> Left e)
+    Right narrowSch -> streamRowGroupsIter narrowSch pf
+
+
+{- | Decode a single row group with column projection. Equivalent
+to @'parquetRowGroupToArrow' (projectSchema names target) pf
+rgIdx@ but checks the projection up front so the error path is
+single-shot rather than per-column.
+-}
+parquetRowGroupToArrowProjected
+  :: AT.Schema
+  -> [Text]
+  -> PR.ParquetFile
+  -> Int
+  -> Either ProjectionError (V.Vector AC.ColumnArray)
+parquetRowGroupToArrowProjected target names pf rgIdx = do
+  narrow <- case projectFields names target of
+    Right s -> Right s
+    Left _ -> Left (MissingColumn (T.pack "<projection>"))
+  parquetRowGroupToArrow narrow pf rgIdx
+
+
+{- | Iterator over row groups that drops any row group whose
+statistics prove the predicate matches no rows.
+
+Skipping is /sound/: only row groups whose
+'Parquet.Predicate.evalRowGroup' returns 'Pred.PSkip' are
+elided. Row groups whose statistics are missing or
+inconclusive are decoded normally and yielded as iterator
+elements.
+
+Returns the iterator paired with the planning summary
+@(totalRowGroups, skippedRowGroups)@ so callers can log how
+effective the predicate was without holding onto the file.
+-}
+streamRowGroupsFilteredIter
+  :: AT.Schema
+  -> Pred.Predicate
+  -> PR.ParquetFile
+  -> (Int, Int, IS.Iter (V.Vector AC.ColumnArray))
+streamRowGroupsFilteredIter sch predicate pf =
+  let !rgs = P.fmRowGroups (PR.pfFooter pf)
+      !nRg = V.length rgs
+      keep i =
+        Pred.evalRowGroup (PR.pfFooter pf) predicate (V.unsafeIndex rgs i)
+          == Pred.PMaybeKeep
+      !kept = V.filter keep (V.enumFromN 0 nRg)
+      !nKept = V.length kept
+      !nSkip = nRg - nKept
+      step k =
+        let !i = V.unsafeIndex kept k
+        in case parquetRowGroupToArrow sch pf i of
+             Right cols -> Right cols
+             Left err -> Left (show err)
+  in (nRg, nSkip, IS.iterFromIndexed nKept step)
+
+
+{- | Combination of 'streamRowGroupsProjectedIter' and
+'streamRowGroupsFilteredIter': only decodes the named
+columns of row groups whose statistics survive the
+predicate.
+-}
+streamRowGroupsProjectedFilteredIter
+  :: AT.Schema
+  -> [Text]
+  -> Pred.Predicate
+  -> PR.ParquetFile
+  -> Either String (Int, Int, IS.Iter (V.Vector AC.ColumnArray))
+streamRowGroupsProjectedFilteredIter sch names predicate pf = do
+  narrowSch <- projectFields names sch
+  let (nRg, nSkip, it) =
+        streamRowGroupsFilteredIter narrowSch predicate pf
+  Right (nRg, nSkip, it)
+
+
+{- | Read one column with page-level predicate pushdown.
+
+Looks up the column chunk's 'OffsetIndex' + 'ColumnIndex',
+evaluates the predicate against the 'ColumnIndex' to produce
+a per-page keep mask, then decodes only retained pages using the shared
+level-preserving readers. Whole retained pages are returned; apply an
+additional row filter if exact predicate matches are required.
+
+Native logical types and schema definition levels are used before checking
+the target's nullability or applying supported numeric widening. Nullable
+ancestors, dictionary encoding and fixed/decimal values use the same path.
+
+Returns 'Right (Nothing, ...)' when the column doesn't carry
+a 'ColumnIndex' / 'OffsetIndex' pair (page-level pruning isn't
+possible without the page-index region — fall back to
+'readParquetColumn'). Returns 'Right (Just (kept, total), col)'
+when pruning ran, with @kept@ pages decoded out of @total@.
+
+/Repeated columns are rejected/: a column whose path crosses
+a 'Repeated' schema element (lists, maps, or any field with
+@max_repetition_level > 0@) carries per-page repetition
+streams that change the row count of every kept page. The
+simple keep-mask shape this function exposes can't model
+that, so it returns 'Left' with a typed error rather than
+silently producing the wrong row count. Callers reading
+nested columns should fall through to 'readParquetColumn'
+(no pushdown) or to 'Parquet.Nested' for the Dremel-shredded
+read path.
+-}
+readParquetColumnWithPagePruning
+  :: PR.ParquetFile
+  -> Int
+  -- ^ row-group index
+  -> Int
+  -- ^ column index within the row group
+  -> AT.Field
+  -- ^ Arrow target field
+  -> Pred.PColPredicate
+  -- ^ predicate to push down to the page index
+  -> Either String (Maybe (Int, Int), AC.ColumnArray)
+readParquetColumnWithPagePruning pf rgIdx colIdx requested predicate = do
+  let metadata = PR.pfFooter pf
+      schema = P.fmSchema metadata
+      leaves = V.filter (maybe False (const True) . P.seType) schema
+  group <- maybe (Left "Parquet.Arrow: row group out of range") Right (P.fmRowGroups metadata V.!? rgIdx)
+  column <- maybe (Left "Parquet.Arrow: column out of range") Right (P.rgColumns group V.!? colIdx)
+  cm <- maybe (Left "Parquet.Arrow: missing column metadata") Right (P.ccMetadata column)
+  leaf <- maybe (Left "Parquet.Arrow: missing physical leaf") Right (leaves V.!? colIdx)
+  if P.seType leaf /= Just (P.cmType cm)
+    then Left "Parquet.Arrow: schema and column physical types disagree"
+    else Right ()
+  native <- schemaElementToArrowField leaf
+  (maxRep, maxDef) <- Levels.maxLevelsForColumnPath schema (P.cmPathInSchema cm)
+  if maxRep /= 0
+    then Left "Parquet.Arrow: repeated fields need row-group container reconstruction; page pruning is not supported"
+    else Right ()
+  if P.rgNumRows group < 0 || P.cmNumValues cm /= P.rgNumRows group
+    then Left "Parquet.Arrow: non-repeated column events differ from row count"
+    else Right ()
+  -- Validate the requested type even if every data page will be skipped.
+  compatible <-
+    if Timestamp.isTimestampField native || Timestamp.isTimestampField requested
+      then Timestamp.fieldsCompatible native requested
+      else Right (AT.fieldType requested == AT.fieldType native || canWiden (AT.fieldType native) (AT.fieldType requested))
+  if not compatible
+    then Left "Parquet.Arrow: incompatible page-pruning target type"
+    else Right ()
+  let decodingField = if canWidenBinary (AT.fieldType native) (AT.fieldType requested) then native {AT.fieldType = AT.fieldType requested} else native
+  indexes <- loadIndices pf rgIdx colIdx
+  case indexes of
+    Nothing -> do
+      decoded <- readParquetColumn pf rgIdx colIdx (decodingField {AT.fieldNullable = True})
+      result <- project native decoded
+      Right (Nothing, result)
+    Just index -> do
+      context <- maybe (Left "Parquet.Arrow: missing statistics context") Right (Pred.statisticsContext metadata colIdx)
+      let keep = (== Pred.PMaybeKeep) <$> Pred.evalPagesByColumnIndex context (pruningBounds index) predicate
+          selection =
+            PR.PageSelection
+              (P.oiPageLocations (pruningOffsets index))
+              keep
+              (P.cmDictionaryPageOffset cm)
+              (Just (P.rgNumRows group))
+          total = V.length keep
+          retained = V.foldl' (\n yes -> n + if yes then 1 else 0) 0 keep
+          codec = P.cmCodec cm
+          completeWith lift dense decoded =
+            if maxDef == 0
+              then dense >>= lift
+              else do
+                levels <- decoded
+                values <- lift (PR.clValues levels)
+                let physical = AN.LeafColumn (PR.clRepetition levels) (PR.clDefinition levels) values
+                AN.assemble
+                  (V.singleton (Right physical))
+                  (AN.Plan (decodingField {AT.fieldNullable = True}) 0 0 0 maxDef AN.Primitive)
+          complete wrap = completeWith (liftDefined leaf . wrap)
+      prepared <- PR.prepareColumnSelection pf rgIdx colIdx selection
+      let file = PR.preparedSelectionBytes prepared
+          selected = PR.preparedSelection prepared
+      decoded <- case P.cmType cm of
+        physical
+          | nativeScalarPhysical (AT.fieldType native) == Just physical ->
+              completeWith
+                (scalarBuffersColumn (AT.fieldType native))
+                (PR.readScalarBuffersSelectedValues physical codec file selected)
+                (PR.readScalarBuffersSelectedLevels physical codec maxRep maxDef file selected)
+        P.PTInt32 -> complete PW.ColInt32 (PR.readInt32SelectedValues codec file selected) (PR.readInt32SelectedLevels codec maxRep maxDef file selected)
+        P.PTInt64 -> complete PW.ColInt64 (PR.readInt64SelectedValues codec file selected) (PR.readInt64SelectedLevels codec maxRep maxDef file selected)
+        P.PTFloat -> complete PW.ColFloat (PR.readFloatSelectedValues codec file selected) (PR.readFloatSelectedLevels codec maxRep maxDef file selected)
+        P.PTDouble -> complete PW.ColDouble (PR.readDoubleSelectedValues codec file selected) (PR.readDoubleSelectedLevels codec maxRep maxDef file selected)
+        P.PTBoolean -> completeWith boolBuffersColumn (PR.readBoolBuffersSelectedValues codec file selected) (PR.readBoolBuffersSelectedLevels codec maxRep maxDef file selected)
+        P.PTByteArray
+          | isLargeBinary (AT.fieldType decodingField) ->
+              completeWith
+                (largeBinaryBuffersColumn (AT.fieldType decodingField))
+                (PR.readLargeBinaryBuffersSelectedValues codec file selected)
+                (PR.readLargeBinaryBuffersSelectedLevels codec maxRep maxDef file selected)
+          | isNativeBinary (AT.fieldType native) ->
+              completeWith
+                (binaryBuffersColumn (AT.fieldType native))
+                (PR.readBinaryBuffersSelectedValues codec file selected)
+                (PR.readBinaryBuffersSelectedLevels codec maxRep maxDef file selected)
+          | otherwise -> complete PW.ColByteArray (PR.readByteArraySelectedValues codec file selected) (PR.readByteArraySelectedLevels codec maxRep maxDef file selected)
+        P.PTInt96 -> complete PW.ColByteArray (PR.readFixedSelectedValues 12 codec file selected) (PR.readFixedSelectedLevels 12 codec maxRep maxDef file selected)
+        P.PTFixedLenByteArray -> case P.seTypeLength leaf of
+          Just width -> complete PW.ColByteArray (PR.readFixedSelectedValues (fromIntegral width) codec file selected) (PR.readFixedSelectedLevels (fromIntegral width) codec maxRep maxDef file selected)
+          Nothing -> Left "Parquet.Arrow: fixed binary leaf is missing its width"
+      result <- project native decoded
+      Right (Just (retained, total), result)
+  where
+    canWiden (AT.AInt 32 True) (AT.AInt 64 True) = True
+    canWiden (AT.AFloatingPoint AT.Single) (AT.AFloatingPoint AT.DoublePrecision) = True
+    canWiden actual target = canWidenBinary actual target
+    project native values = do
+      if not (AT.fieldNullable requested) && AC.nullCount values /= 0
+        then Left "Parquet.Arrow: non-nullable page-pruning target cannot contain nulls"
+        else Right ()
+      if Timestamp.isTimestampField native || Timestamp.isTimestampField requested
+        then Timestamp.projectTimestampColumn native requested values
+        else
+          if AT.fieldType requested == AT.fieldType native
+            then Right values
+            else coerceColumn (AT.fieldType requested) values
+
+
+data PruningIndex = PruningIndex
+  { pruningOffsets :: !P.OffsetIndex
+  , pruningBounds :: !P.ColumnIndex
+  }
+
+
+loadIndices :: PR.ParquetFile -> Int -> Int -> Either String (Maybe PruningIndex)
+loadIndices pf rgIdx colIdx = do
+  bounds <- PI.readColumnIndex pf rgIdx colIdx
+  case bounds of
+    Nothing -> Right Nothing
+    Just ci -> do
+      offsets <- PI.readOffsetIndex pf rgIdx colIdx
+      case offsets of
+        Just oi
+          | V.length (P.oiPageLocations oi) /= V.length (P.ciNullPages ci) ->
+              Left "Parquet.Arrow: column/offset index page counts disagree"
+          | otherwise -> Right (Just (PruningIndex oi ci))
+        Nothing -> Right Nothing
+
+
+-- | Build a sub-schema by name. Preserves the order of @names@.
+projectFields :: [Text] -> AT.Schema -> Either String AT.Schema
+projectFields names sch =
+  let !fields = AT.arrowFields sch
+      !byName =
+        Map.fromList
+          [(AT.fieldName f, f) | f <- V.toList fields]
+      pickOne nm = case Map.lookup nm byName of
+        Just f -> Right f
+        Nothing ->
+          Left $
+            "Parquet.Arrow: projected column "
+              ++ show nm
+              ++ " not present in target schema"
+  in do
+       fs <- traverse pickOne names
+       Right sch {AT.arrowFields = V.fromList fs}
diff --git a/src/Parquet/Arrow/File.hs b/src/Parquet/Arrow/File.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Arrow/File.hs
@@ -0,0 +1,84 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+{- | Compatibility with arrow-rs's experimental FILE extension. The extension
+name is not yet a standardized canonical Arrow extension.
+-}
+module Parquet.Arrow.File (
+  isFileField,
+  fileSchemaFromField,
+  fileMetadata,
+  fieldIdMetadata,
+) where
+
+import Arrow.Types qualified as A
+import Control.Monad (unless)
+import Data.Int (Int32)
+import Data.Text (Text)
+import Data.Text qualified as T
+import Data.Text.Lazy qualified as TL
+import Data.Text.Lazy.Builder qualified as TB
+import Data.Text.Lazy.Builder.Int qualified as TBI
+import Data.Text.Read qualified as TR
+import Data.Vector qualified as V
+import Parquet.File qualified as F
+
+
+isFileField :: A.Field -> Bool
+isFileField field = V.elem ("ARROW:extension:name", "arrow.parquet.file") (A.fieldMetadata field)
+
+
+fileMetadata :: V.Vector (Text, Text)
+fileMetadata = V.fromList [("ARROW:extension:name", "arrow.parquet.file"), ("ARROW:extension:metadata", "")]
+
+
+fieldIdMetadata :: Maybe Int32 -> V.Vector (Text, Text)
+fieldIdMetadata = maybe V.empty (V.singleton . ("PARQUET:field_id",) . TL.toStrict . TB.toLazyText . TBI.decimal)
+
+
+fileSchemaFromField :: A.Field -> Either String F.FileSchema
+fileSchemaFromField field = do
+  let names = values "ARROW:extension:name" field
+      parameters = values "ARROW:extension:metadata" field
+  unless
+    (names == V.singleton "arrow.parquet.file" && V.length parameters <= 1 && V.all T.null parameters)
+    (Left "Parquet.Arrow: FILE extension expects a unique name and absent/empty metadata")
+  unless
+    (A.fieldType field == A.AStruct && A.fieldDictionary field == Nothing)
+    (Left "Parquet.Arrow: FILE extension requires struct storage")
+  ident <- fieldId field
+  children <- V.mapM child (A.fieldChildren field)
+  F.withFileSchemaFieldId ident <$> F.mkFileSchema children
+  where
+    child value = do
+      kind <- case A.fieldName value of
+        "uri" -> Right F.FileUri
+        "offset" -> Right F.FileOffset
+        "size" -> Right F.FileSize
+        "content_type" -> Right F.FileContentType
+        "checksum" -> Right F.FileChecksumField
+        "inline" -> Right F.FileInline
+        _ -> Left "Parquet.Arrow: unrecognized FILE field name"
+      let ty = A.fieldType value
+          matches = case kind of
+            F.FileOffset -> ty == A.AInt 64 True
+            F.FileSize -> ty == A.AInt 64 True
+            F.FileInline -> ty `elem` [A.ABinary, A.ALargeBinary, A.ABinaryView]
+            _ -> ty `elem` [A.AUtf8, A.ALargeUtf8, A.AUtf8View]
+      unless
+        (matches && A.fieldNullable value && V.null (A.fieldChildren value) && A.fieldDictionary value == Nothing)
+        (Left "Parquet.Arrow: FILE children must be nullable primitives with their specified types")
+      F.FileFieldSpec kind <$> fieldId value
+
+
+values :: Text -> A.Field -> V.Vector Text
+values key = V.map snd . V.filter ((== key) . fst) . A.fieldMetadata
+
+
+fieldId :: A.Field -> Either String (Maybe Int32)
+fieldId field = case V.toList (values "PARQUET:field_id" field) of
+  [] -> Right Nothing
+  [encoded] -> case TR.signed TR.decimal encoded :: Either String (Integer, Text) of
+    Right (number, remainder)
+      | T.null remainder && number >= fromIntegral (minBound :: Int32) && number <= fromIntegral (maxBound :: Int32) -> Right (Just (fromInteger number))
+    _ -> Left "Parquet.Arrow: FILE field ID must fit a signed 32-bit integer"
+  _ -> Left "Parquet.Arrow: duplicate FILE field ID metadata"
diff --git a/src/Parquet/Arrow/Geospatial.hs b/src/Parquet/Arrow/Geospatial.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Arrow/Geospatial.hs
@@ -0,0 +1,145 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+-- | Translate geospatial semantics without changing the WKB storage bytes.
+module Parquet.Arrow.Geospatial (toArrowMetadata, fromArrowField) where
+
+import Arrow.Types qualified as A
+import Data.Aeson ((.=))
+import Data.Aeson qualified as J
+import Data.Aeson.Key (Key)
+import Data.Aeson.KeyMap qualified as KM
+import Data.ByteString.Lazy qualified as BL
+import Data.Text (Text)
+import Data.Text qualified as T
+import Data.Text.Encoding qualified as TE
+import Data.Vector qualified as V
+import Parquet.Types qualified as P
+
+
+data CRSMetadata = CRSMetadata
+  { crsValue :: !J.Value
+  , crsHint :: !(Maybe Text)
+  }
+
+
+encodeJSON :: J.Value -> Text
+encodeJSON = TE.decodeUtf8 . BL.toStrict . J.encode
+
+
+objectJSON :: Text -> Either String J.Object
+objectJSON value = case J.eitherDecodeStrict' (TE.encodeUtf8 value) of
+  Right (J.Object object) -> Right object
+  _ -> Left "Parquet.Arrow: CRS definition must be a JSON object"
+
+
+resolveCRS :: P.FileMetadata -> Maybe Text -> Either String CRSMetadata
+resolveCRS _ Nothing = Right (CRSMetadata (J.String "OGC:CRS84") (Just "authority_code"))
+resolveCRS footer (Just raw)
+  | Just name <- T.stripPrefix "projjson:" raw = do
+      if T.null name then Left "Parquet.Arrow: empty PROJJSON metadata reference" else Right ()
+      let entries = V.filter ((== TE.encodeUtf8 name) . P.kvKey) (maybe V.empty id (P.fmKeyValueMetadata footer))
+      value <- case V.toList entries of
+        [P.KeyValue _ (Just bytes)] -> either (const (Left "Parquet.Arrow: PROJJSON metadata is not UTF-8")) Right (TE.decodeUtf8' bytes)
+        _ -> Left "Parquet.Arrow: missing, absent-valued or ambiguous PROJJSON metadata reference"
+      object <- objectJSON value
+      Right (CRSMetadata (J.Object object) (Just "projjson"))
+  | Just identifier <- T.stripPrefix "srid:" raw =
+      if T.null identifier then Left "Parquet.Arrow: empty SRID" else Right (CRSMetadata (J.String identifier) (Just "srid"))
+  | T.null raw = Left "Parquet.Arrow: empty CRS does not identify a coordinate reference system"
+  | otherwise = case J.eitherDecodeStrict' (TE.encodeUtf8 raw) of
+      Right (J.Object object) -> Right (CRSMetadata (J.Object object) (Just "projjson"))
+      _ -> Right (CRSMetadata (J.String raw) Nothing)
+
+
+edgeName :: P.EdgeInterpolationAlgorithm -> Maybe Text
+edgeName P.Spherical = Just "spherical"
+edgeName P.Vincenty = Just "vincenty"
+edgeName P.Thomas = Just "thomas"
+edgeName P.Andoyer = Just "andoyer"
+edgeName P.Karney = Just "karney"
+edgeName P.UnrecognizedInterpolation {} = Nothing
+
+
+parseEdge :: Text -> Either String P.EdgeInterpolationAlgorithm
+parseEdge "spherical" = Right P.Spherical
+parseEdge "vincenty" = Right P.Vincenty
+parseEdge "thomas" = Right P.Thomas
+parseEdge "andoyer" = Right P.Andoyer
+parseEdge "karney" = Right P.Karney
+parseEdge _ = Left "Parquet.Arrow: unsupported GeoArrow edge interpolation"
+
+
+toArrowMetadata :: P.FileMetadata -> P.SchemaElement -> Either String (V.Vector (Text, Text))
+toArrowMetadata footer element
+  | P.seType element /= Just P.PTByteArray = Right V.empty
+  | otherwise = case P.seLogicalType element of
+      Just (P.LTGeometry parameters) -> build (P.geometryCrs parameters) Nothing
+      Just (P.LTGeography parameters) -> case edgeName (maybe P.Spherical id (P.geographyAlgorithm parameters)) of
+        -- A future algorithm cannot be labelled as planar or spherical WKB.
+        Nothing -> Right V.empty
+        Just edges -> build (P.geographyCrs parameters) (Just edges)
+      _ -> Right V.empty
+  where
+    build :: Maybe Text -> Maybe Text -> Either String (V.Vector (Text, Text))
+    build raw edges = do
+      crs <- resolveCRS footer raw
+      let fields =
+            ["crs" .= crsValue crs]
+              ++ maybe [] (\hint -> ["crs_type" .= hint]) (crsHint crs)
+              ++ maybe [] (\value -> ["edges" .= value]) edges
+      Right (V.fromList [("ARROW:extension:name", "geoarrow.wkb"), ("ARROW:extension:metadata", encodeJSON (J.Object (KM.fromList fields)))])
+
+
+reservedField :: Text -> A.Field -> Either String (Maybe Text)
+reservedField name field = case V.toList (V.filter ((== name) . fst) (A.fieldMetadata field)) of
+  [] -> Right Nothing
+  [(_, value)] -> Right (Just value)
+  _ -> Left "Parquet.Arrow: duplicate Arrow extension metadata key"
+
+
+optionalText :: Key -> J.Object -> Either String (Maybe Text)
+optionalText name object = case KM.lookup name object of
+  Nothing -> Right Nothing
+  Just (J.String value) -> Right (Just value)
+  _ -> Left "Parquet.Arrow: GeoArrow metadata field must be a string"
+
+
+fromArrowField :: A.Field -> Either String (Maybe P.LogicalType)
+fromArrowField field
+  | not (V.any (\(key, value) -> key == "ARROW:extension:name" && "geoarrow." `T.isPrefixOf` value) (A.fieldMetadata field)) = Right Nothing
+  | otherwise = do
+      extension <- reservedField "ARROW:extension:name" field
+      case extension of
+        Just "geoarrow.wkb" -> convert
+        Just name | "geoarrow." `T.isPrefixOf` name -> Left "Parquet.Arrow: only WKB GeoArrow storage can be written as Parquet geospatial data"
+        _ -> Right Nothing
+  where
+    convert = do
+      if A.fieldType field `elem` [A.ABinary, A.ALargeBinary]
+        then Right ()
+        else Left "Parquet.Arrow: GeoArrow WKB requires binary storage"
+      encoded <- reservedField "ARROW:extension:metadata" field
+      object <- case encoded of
+        Nothing -> Right KM.empty
+        Just value -> case J.eitherDecodeStrict' (TE.encodeUtf8 value) of
+          Right (J.Object fields) -> Right fields
+          _ -> Left "Parquet.Arrow: GeoArrow metadata must be a JSON object"
+      hint <- optionalText "crs_type" object
+      crs <- case KM.lookup "crs" object of
+        Just (J.Object fields) | hint `elem` [Nothing, Just "projjson"] -> Right (encodeJSON (J.Object fields))
+        Just (J.String value) | not (T.null value) -> case hint of
+          Just "srid" -> Right ("srid:" <> value)
+          Nothing -> literal value
+          Just "authority_code" -> literal value
+          Just "wkt2:2019" -> literal value
+          _ -> Left "Parquet.Arrow: unsupported GeoArrow CRS representation"
+        _ -> Left "Parquet.Arrow: unknown GeoArrow CRS cannot be replaced by Parquet's OGC:CRS84 default"
+      edges <- optionalText "edges" object
+      case edges of
+        Nothing -> Right (Just (P.LTGeometry (P.GeometryParameters (Just crs))))
+        Just value -> do
+          algorithm <- parseEdge value
+          Right (Just (P.LTGeography (P.GeographyParameters (Just crs) (Just algorithm))))
+    literal value
+      | "projjson:" `T.isPrefixOf` value = Left "Parquet.Arrow: GeoArrow CRS cannot reference missing file metadata"
+      | otherwise = Right value
diff --git a/src/Parquet/Arrow/Nested.hs b/src/Parquet/Arrow/Nested.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Arrow/Nested.hs
@@ -0,0 +1,823 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE GADTs #-}
+
+{- | Internal schema planning and columnar Dremel assembly. Physical leaf
+ordinals remain distinct even when several structs use the same names.
+-}
+module Parquet.Arrow.Nested (
+  Plan (..),
+  PlanKind (..),
+  LeafColumn (..),
+  plans,
+  assemble,
+  assembleWith,
+  assembleWithRows,
+  unbackedValues,
+) where
+
+import Arrow.Column qualified as C
+import Arrow.Column.Buffer qualified as Buffer
+import Arrow.Types qualified as A
+import Control.Monad.ST (runST)
+import Data.Bits (shiftL, (.|.))
+import Data.ByteString (ByteString)
+import Data.Int (Int16, Int32, Int64, Int8)
+import Data.Map.Strict qualified as Names
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as P
+import Data.Vector.Storable qualified as S
+import Data.Vector.Storable.Mutable qualified as M
+import Data.Word (Word16, Word32, Word64, Word8)
+import Foreign.Storable (Storable)
+import Parquet.Arrow.File qualified as FileArrow
+import Parquet.File qualified as File
+import Parquet.Types qualified as T
+import Parquet.Variant.Schema qualified as VariantSchema
+
+
+data Physical = Physical
+  { physicalElement :: !T.SchemaElement
+  , physicalChildren :: !(V.Vector Physical)
+  , physicalLeaf :: {-# UNPACK #-} !Int
+  , physicalDef :: {-# UNPACK #-} !Int
+  , physicalRep :: {-# UNPACK #-} !Int
+  }
+
+
+data Parsed = Parsed
+  { parsedNodes :: ![Physical]
+  , parsedNext :: {-# UNPACK #-} !Int
+  , parsedLeaf :: {-# UNPACK #-} !Int
+  }
+
+
+data Plan = Plan
+  { planField :: !A.Field
+  , planAnchor :: {-# UNPACK #-} !Int
+  , planSlotDef :: {-# UNPACK #-} !Int
+  , planSlotRep :: {-# UNPACK #-} !Int
+  , planPresence :: {-# UNPACK #-} !Int
+  , planKind :: !PlanKind
+  }
+
+
+data PlanKind = Primitive | Struct !(V.Vector Plan) | List !Plan | Map !Plan !Plan | EmptyFile
+
+
+data LeafColumn = LeafColumn
+  { leafReps :: !(P.Vector Int32)
+  , leafDefs :: !(P.Vector Int32)
+  , leafValues :: !C.ColumnArray
+  }
+
+
+plans :: (T.SchemaElement -> Either String A.Field) -> V.Vector T.SchemaElement -> Either String (V.Vector Plan)
+plans leafField schema
+  | V.null schema = Left "Parquet.Arrow: schema is missing its root"
+  | T.seType root /= Nothing = Left "Parquet.Arrow: schema root must be a group"
+  | T.seNumChildren root == Nothing = Left "Parquet.Arrow: schema root is missing num_children"
+  | otherwise = do
+      children <- parseChildren 0 0 0 1 0 (maybe 0 fromIntegral (T.seNumChildren root))
+      if parsedNext children /= V.length schema
+        then Left "Parquet.Arrow: schema has trailing nodes"
+        else
+          if not (unique (V.fromList (parsedNodes children)))
+            then Left "Parquet.Arrow: duplicate sibling field names"
+            else V.mapM (node 0 0) (V.fromList (parsedNodes children))
+  where
+    root = V.head schema
+    parseChildren :: Int -> Int -> Int -> Int -> Int -> Int -> Either String Parsed
+    parseChildren depth def rep index ordinal count
+      | count < 0 || count > V.length schema - index = Left "Parquet.Arrow: invalid schema child count"
+      | count == 0 = Right (Parsed [] index ordinal)
+      | depth > 128 = Left "Parquet.Arrow: schema nesting exceeds 128 levels"
+      | otherwise = do
+          element <- maybe (Left "Parquet.Arrow: truncated schema") Right (schema V.!? index)
+          case T.seRepetition element of
+            Nothing -> Left "Parquet.Arrow: non-root schema node is missing repetition_type"
+            Just _ -> Right ()
+          case (T.seType element, T.seNumChildren element) of
+            (Just _, Just _) -> Left "Parquet.Arrow: primitive schema node has num_children"
+            (Nothing, Nothing) -> Left "Parquet.Arrow: group schema node is missing num_children"
+            _ -> Right ()
+          let ownDef = def + if T.seRepetition element `elem` [Just T.Optional, Just T.Repeated] then 1 else 0
+              ownRep = rep + if T.seRepetition element == Just T.Repeated then 1 else 0
+              isLeaf = T.seType element /= Nothing
+              nChildren = maybe 0 fromIntegral (T.seNumChildren element)
+          nested <- parseChildren (depth + 1) ownDef ownRep (index + 1) ordinal nChildren
+          let nextLeaf = if isLeaf then ordinal + 1 else parsedLeaf nested
+              physical = Physical element (V.fromList (parsedNodes nested)) ordinal ownDef ownRep
+          siblings <- parseChildren depth def rep (parsedNext nested) nextLeaf (count - 1)
+          Right siblings {parsedNodes = physical : parsedNodes siblings}
+    node slotDef slotRep physical
+      | T.seRepetition (physicalElement physical) == Just T.Repeated = do
+          child <- content (physicalDef physical) (physicalRep physical) physical
+          let field =
+                (planField child)
+                  { A.fieldNullable = False
+                  , A.fieldType = A.AList
+                  , A.fieldChildren = V.singleton ((planField child) {A.fieldNullable = False})
+                  , A.fieldMetadata = FileArrow.fieldIdMetadata (T.seFieldId (physicalElement physical))
+                  }
+          Right
+            ( Plan
+                field
+                (planAnchor child)
+                slotDef
+                slotRep
+                (physicalDef physical - 1)
+                (List child)
+            )
+      | otherwise = content slotDef slotRep physical
+    content slotDef slotRep physical
+      | not (unique children) = Left "Parquet.Arrow: duplicate sibling field names"
+      | T.seLogicalType element == Just (T.LTVariant 1) && T.seType element /= Nothing = Left "Parquet.Arrow: VARIANT(1) requires group storage"
+      | T.seType element /= Nothing = do
+          fld <- leafField element
+          Right (base fld Primitive)
+      | T.seLogicalType element == Just (T.LTVariant 1) = do
+          require (T.seConvertedType element == Nothing) "Variant root has a conflicting converted annotation"
+          result <- variantNode True slotDef slotRep physical
+          let annotated = (planField result) {A.fieldMetadata = VariantSchema.variantExtensionMetadata V.++ FileArrow.fieldIdMetadata (T.seFieldId element)}
+          VariantSchema.validateVariantFieldWithLimits (VariantSchema.VariantSchemaLimits 128 (V.length schema)) annotated
+          Right result {planField = annotated}
+      | isList element = case V.toList children of
+          [repeated] | T.seRepetition (physicalElement repeated) == Just T.Repeated -> do
+            child <- listElement element repeated
+            Right (base (field A.AList (V.singleton (planField child))) (List child))
+          _ -> Left "Parquet.Arrow: LIST must contain one repeated field"
+      | isMap element = case V.toList children of
+          [entries] | T.seRepetition (physicalElement entries) == Just T.Repeated ->
+            case V.toList (physicalChildren entries) of
+              [key] -> do
+                child <- node (physicalDef entries) (physicalRep entries) key
+                Right (base (field A.AList (V.singleton (planField child))) (List child))
+              [key, value] -> do
+                keyPlan <- node (physicalDef entries) (physicalRep entries) key
+                let kp = case planKind keyPlan of
+                      EmptyFile
+                        | T.seRepetition (physicalElement key) == Just T.Required ->
+                            keyPlan {planField = (planField keyPlan) {A.fieldNullable = False}}
+                      _ -> keyPlan
+                vp <- node (physicalDef entries) (physicalRep entries) value
+                if A.fieldNullable (planField kp)
+                  then Left "Parquet.Arrow: MAP keys cannot be optional"
+                  else do
+                    let entryField =
+                          -- The repeated Parquet group is a storage
+                          -- wrapper; Arrow's logical map child is entries.
+                          A.Field
+                            "entries"
+                            False
+                            A.AStruct
+                            (V.fromList [planField kp, planField vp])
+                            Nothing
+                            V.empty
+                    Right (base (field (A.AMap False) (V.singleton entryField)) (Map kp vp))
+              _ -> Left "Parquet.Arrow: MAP must contain key and optional value fields"
+          _ -> Left "Parquet.Arrow: MAP must contain one repeated group"
+      | V.null children && T.seLogicalType element == Just T.LTFile = do
+          _ <- File.parseFileSchema element V.empty
+          let empty =
+                (field A.AStruct V.empty)
+                  { A.fieldNullable = True
+                  , A.fieldMetadata = FileArrow.fileMetadata V.++ FileArrow.fieldIdMetadata (T.seFieldId element)
+                  }
+          Right ((base empty EmptyFile) {planAnchor = -1})
+      | V.null children = Left "Parquet.Arrow: an empty group has no physical leaf"
+      | otherwise = do
+          case T.seLogicalType element of
+            Just T.LTFile -> () <$ File.parseFileSchema element (physicalElement <$> children)
+            _ -> Right ()
+          fields <- V.mapM (node slotDef slotRep) children
+          let withId physicalChild childPlan =
+                let childField = planField childPlan
+                in childPlan {planField = childField {A.fieldMetadata = A.fieldMetadata childField V.++ FileArrow.fieldIdMetadata (T.seFieldId (physicalElement physicalChild))}}
+              preserved = if T.seLogicalType element == Just T.LTFile then V.zipWith withId children fields else fields
+              structField = field A.AStruct (planField <$> preserved)
+              annotated =
+                if T.seLogicalType element == Just T.LTFile
+                  then structField {A.fieldMetadata = FileArrow.fileMetadata V.++ FileArrow.fieldIdMetadata (T.seFieldId element)}
+                  else structField
+          Right (base annotated (Struct preserved))
+      where
+        element = physicalElement physical
+        children = physicalChildren physical
+        field ty kids =
+          A.Field
+            (T.seName element)
+            (T.seRepetition element == Just T.Optional)
+            ty
+            kids
+            Nothing
+            V.empty
+        base fld kind = Plan fld (if hasLeaf physical then physicalLeaf physical else -1) slotDef slotRep (physicalDef physical) kind
+    -- Known Variant layouts use their own exact schema rules. In particular,
+    -- the generic LIST legacy-name heuristics must not change element shape.
+    variantNode root slotDef slotRep physical = do
+      let element = physicalElement physical
+          children = physicalChildren physical
+          names = T.seName . physicalElement <$> children
+          allowed = if root then ["metadata", "value", "typed_value"] else ["value", "typed_value"]
+          typed = V.elem "typed_value" names
+      require (T.seType element == Nothing && unique children) "Variant node must be a group with unique fields"
+      require (root || (plain element && T.seRepetition element == Just T.Required)) "Variant wrapper must be a required unannotated group"
+      require (V.length names <= length allowed && V.all (`elem` allowed) names) "unexpected Variant node field"
+      require ((not root || V.elem "metadata" names) && (typed || V.elem "value" names)) "Variant node is missing metadata or value storage"
+      fields <-
+        V.mapM
+          ( \child -> case T.seName (physicalElement child) of
+              "metadata" -> variantBinary T.Required slotDef slotRep child
+              "value" -> variantBinary (if root && not typed then T.Required else T.Optional) slotDef slotRep child
+              "typed_value" -> variantTyped slotDef slotRep child
+              _ -> Left "Parquet.Arrow: unexpected Variant field"
+          )
+          children
+      Right (variantBase slotDef slotRep physical A.AStruct fields (Struct fields))
+    variantBinary repetition slotDef slotRep physical = do
+      let element = physicalElement physical
+      require (T.seType element == Just T.PTByteArray && plain element && T.seRepetition element == Just repetition) "Variant binary storage has an invalid type, annotation or repetition"
+      result <- node slotDef slotRep physical
+      let field = planField result
+      Right result {planField = field {A.fieldMetadata = A.fieldMetadata field V.++ FileArrow.fieldIdMetadata (T.seFieldId element)}}
+    variantTyped slotDef slotRep physical = do
+      let element = physicalElement physical
+          children = physicalChildren physical
+      require (T.seRepetition element == Just T.Optional) "Variant typed_value must be optional"
+      if T.seType element /= Nothing
+        then do
+          typ <- variantPrimitive element
+          result <- node slotDef slotRep physical
+          let field = planField result
+              metadata = if T.seLogicalType element == Just T.LTUUID then V.fromList [("ARROW:extension:name", "arrow.uuid"), ("ARROW:extension:metadata", "")] else V.empty
+          Right result {planField = field {A.fieldType = typ, A.fieldMetadata = metadata V.++ FileArrow.fieldIdMetadata (T.seFieldId element)}}
+        else
+          if isList element
+            then case V.toList children of
+              [repeated]
+                | let wrapper = physicalElement repeated
+                , T.seType wrapper == Nothing && plain wrapper && T.seRepetition wrapper == Just T.Repeated
+                , [item] <- V.toList (physicalChildren repeated) -> do
+                    require (logical element == Just T.LTList) "Variant list has a conflicting annotation"
+                    child <- variantNode False (physicalDef repeated) (physicalRep repeated) item
+                    Right (variantBase slotDef slotRep physical A.AList (V.singleton child) (List child))
+              _ -> Left "Parquet.Arrow: Variant arrays require an exact three-level LIST with a required element group"
+            else do
+              require (plain element && unique children) "Variant object must be an unannotated group with unique fields"
+              fields <- V.mapM (variantNode False slotDef slotRep) children
+              Right (variantBase slotDef slotRep physical A.AStruct fields (Struct fields))
+    variantBase slotDef slotRep physical typ fields kind =
+      let element = physicalElement physical
+          field = (A.defaultField (T.seName element) (T.seRepetition element == Just T.Optional) typ (planField <$> fields)) {A.fieldMetadata = FileArrow.fieldIdMetadata (T.seFieldId element)}
+      in Plan field (if hasLeaf physical then physicalLeaf physical else -1) slotDef slotRep (physicalDef physical) kind
+    plain element = T.seLogicalType element == Nothing && T.seConvertedType element == Nothing
+    require good message = if good then Right () else Left ("Parquet.Arrow: " ++ message)
+    logical element = case T.seLogicalType element of
+      Just annotation -> Just annotation
+      Nothing -> case T.seConvertedType element of
+        Nothing -> Nothing
+        Just T.CTUtf8 -> Just T.LTString
+        Just T.CTList -> Just T.LTList
+        Just T.CTDate -> Just T.LTDate
+        Just T.CTInt8 -> Just (T.LTInteger 8 True)
+        Just T.CTInt16 -> Just (T.LTInteger 16 True)
+        Just T.CTInt32 -> Just (T.LTInteger 32 True)
+        Just T.CTInt64 -> Just (T.LTInteger 64 True)
+        Just T.CTTimestampMicros -> Just (T.LTTimestamp True T.LtMicros)
+        _ -> Just T.LTUnsupported
+    variantPrimitive element = case (T.seType element, logical element) of
+      (Just T.PTBoolean, Nothing) -> Right A.ABool
+      (Just T.PTInt32, Just (T.LTInteger width True)) | width `elem` [8, 16, 32] -> Right (A.AInt (fromIntegral width) True)
+      (Just T.PTInt32, Nothing) -> Right (A.AInt 32 True)
+      (Just T.PTInt64, Nothing) -> Right (A.AInt 64 True)
+      (Just T.PTInt64, Just (T.LTInteger 64 True)) -> Right (A.AInt 64 True)
+      (Just T.PTFloat, Nothing) -> Right (A.AFloatingPoint A.Single)
+      (Just T.PTDouble, Nothing) -> Right (A.AFloatingPoint A.DoublePrecision)
+      (Just physical, Just (T.LTDecimal precision scale))
+        | precision >= 1 && precision <= 38 && scale >= 0 && scale <= precision && T.hasCompatiblePhysicalType element ->
+            let p = fromIntegral precision; s = fromIntegral scale
+            in case physical of
+                 T.PTInt32 | precision <= 9 -> Right (A.ADecimal32 p s)
+                 T.PTInt64 | precision >= 10 && precision <= 18 -> Right (A.ADecimal64 p s)
+                 _ | physical `elem` [T.PTByteArray, T.PTFixedLenByteArray] && precision >= 19 -> Right (A.ADecimal p s)
+                 _ -> invalid
+      (Just T.PTInt32, Just T.LTDate) -> Right (A.ADate A.DateDay)
+      (Just T.PTInt64, Just (T.LTTime False T.LtMicros)) -> Right (A.ATime A.Microsecond 64)
+      (Just T.PTInt64, Just (T.LTTimestamp utc unit))
+        | unit `elem` [T.LtMicros, T.LtNanos] ->
+            Right (A.ATimestamp (if unit == T.LtMicros then A.Microsecond else A.Nanosecond) (if utc then Just "UTC" else Nothing))
+      (Just T.PTByteArray, Nothing) -> Right A.ABinary
+      (Just T.PTByteArray, Just T.LTString) -> Right A.AUtf8
+      (Just T.PTFixedLenByteArray, Just T.LTUUID) | T.seTypeLength element == Just 16 -> Right (A.AFixedSizeBinary 16)
+      _ -> invalid
+      where
+        invalid = Left "Parquet.Arrow: primitive has no exact native Variant mapping"
+    hasLeaf physical = T.seType (physicalElement physical) /= Nothing || V.any hasLeaf (physicalChildren physical)
+    listElement parent repeated =
+      let kids = physicalChildren repeated
+          name = T.seName (physicalElement repeated)
+          legacyElement =
+            T.seType (physicalElement repeated) /= Nothing
+              || V.length kids /= 1
+              || name == "array"
+              || name == T.seName parent <> "_tuple"
+              || isList (physicalElement repeated)
+              || isMap (physicalElement repeated)
+      in if legacyElement
+           then content (physicalDef repeated) (physicalRep repeated) repeated
+           else node (physicalDef repeated) (physicalRep repeated) (V.head kids)
+    isList e = T.seLogicalType e == Just T.LTList || T.seConvertedType e == Just T.CTList
+    isMap e = T.seLogicalType e == Just T.LTMap || T.seConvertedType e == Just T.CTMap
+    unique nodes =
+      Names.size
+        ( Names.fromList
+            ( V.toList
+                (V.map (\n -> (T.seName (physicalElement n), ())) nodes)
+            )
+        )
+        == V.length nodes
+
+
+{- | Assemble one logical root column from lazily shared physical leaves.
+Every child is built column-wise; no row-major object tree is allocated.
+-}
+assemble :: V.Vector (Either String LeafColumn) -> Plan -> Either String C.ColumnArray
+assemble = assembleWith (\_ -> Right)
+
+
+{- | Transform a primitive after reconstruction. Container plans can be
+narrowed/reordered before assembly, keeping unused physical leaves lazy.
+-}
+assembleWith
+  :: (Plan -> C.ColumnArray -> Either String C.ColumnArray)
+  -> V.Vector (Either String LeafColumn)
+  -> Plan
+  -> Either String C.ColumnArray
+assembleWith = assembleIn Nothing
+
+
+{- | Supply the row count for zero-leaf FILEs. Nested containers pass their
+own slot count down; no neighboring column is mistaken for a FILE leaf.
+-}
+assembleWithRows :: Int -> (Plan -> C.ColumnArray -> Either String C.ColumnArray) -> V.Vector (Either String LeafColumn) -> Plan -> Either String C.ColumnArray
+assembleWithRows rows = assembleIn (Just rows)
+
+
+assembleIn :: Maybe Int -> (Plan -> C.ColumnArray -> Either String C.ColumnArray) -> V.Vector (Either String LeafColumn) -> Plan -> Either String C.ColumnArray
+assembleIn count transform leaves plan = case planKind plan of
+  EmptyFile -> case count of
+    Just rows -> C.mkStruct rows (C.validityGenerate rows (const False)) V.empty
+    Nothing -> Left "Parquet.Arrow: zero-leaf FILE needs its containing row count"
+  Struct children | planAnchor plan < 0 -> case count of
+    Just 0 -> C.emptyColumnFor (planField plan)
+    Just rows | not (A.fieldNullable (planField plan)) -> do
+      columns <- V.mapM (assembleIn (Just rows) transform leaves) children
+      C.mkStruct rows Nothing (V.zip (A.fieldName . planField <$> children) columns)
+    _ -> missing
+  _ | planAnchor plan < 0 -> case count of
+    Just 0 -> C.emptyColumnFor (planField plan)
+    _ -> missing
+  _ -> assembleAnchored transform leaves plan
+  where
+    missing = Left "Parquet.Arrow: container has no physical leaf to recover its shape"
+
+
+assembleAnchored :: (Plan -> C.ColumnArray -> Either String C.ColumnArray) -> V.Vector (Either String LeafColumn) -> Plan -> Either String C.ColumnArray
+assembleAnchored transformPrimitive leaves plan = do
+  anchor <- maybe (Left "Parquet.Arrow: missing physical leaf") id (leaves V.!? planAnchor plan)
+  let slots = slotIndices plan anchor
+      n = P.length slots
+      present i = fromIntegral (leafDefs anchor P.! (slots P.! i)) >= planPresence plan
+      validity = if A.fieldNullable (planField plan) then C.validityGenerate n present else Nothing
+      flat =
+        planSlotDef plan == 0
+          && planSlotRep plan == 0
+          && P.length (leafReps anchor) == P.length (leafDefs anchor)
+          && P.all (== 0) (leafReps anchor)
+  result <- case planKind plan of
+    Primitive
+      | C.ColPrim primitive Nothing values <- leafValues anchor
+      , flat ->
+          flatPrimitive plan (leafDefs anchor) primitive values
+    Primitive
+      | C.ColBool Nothing values <- leafValues anchor
+      , flat ->
+          flatBool plan (leafDefs anchor) values
+    Primitive
+      | C.ColUtf8 Nothing offsets bytes <- leafValues anchor
+      , flat ->
+          flatVariable plan (leafDefs anchor) C.mkUtf8 offsets bytes
+    Primitive
+      | C.ColBinary Nothing offsets bytes <- leafValues anchor
+      , flat ->
+          flatVariable plan (leafDefs anchor) C.mkBinary offsets bytes
+    Primitive
+      | C.ColLargeUtf8 Nothing offsets bytes <- leafValues anchor
+      , flat ->
+          flatVariable plan (leafDefs anchor) C.mkLargeUtf8 offsets bytes
+    Primitive
+      | C.ColLargeBinary Nothing offsets bytes <- leafValues anchor
+      , flat ->
+          flatVariable plan (leafDefs anchor) C.mkLargeBinary offsets bytes
+    Primitive -> do
+      let dense = leafValues anchor
+          ranks = P.scanl' (\rank index -> if fromIntegral (leafDefs anchor P.! index) == planPresence plan then rank + 1 else rank) 0 slots
+          good i = fromIntegral (leafDefs anchor P.! (slots P.! i)) == planPresence plan
+      if P.last ranks /= C.columnLength dense
+        then Left "Parquet.Arrow: defined values and levels disagree"
+        else case dense of
+          C.ColUtf8 Nothing offsets bytes -> variableFromRanks C.mkUtf8 validity ranks offsets bytes
+          C.ColBinary Nothing offsets bytes -> variableFromRanks C.mkBinary validity ranks offsets bytes
+          C.ColLargeUtf8 Nothing offsets bytes -> variableFromRanks C.mkLargeUtf8 validity ranks offsets bytes
+          C.ColLargeBinary Nothing offsets bytes -> variableFromRanks C.mkLargeBinary validity ranks offsets bytes
+          _ -> do
+            scattered <-
+              if C.columnLength dense == 0
+                then Right (C.fillerColumn n dense)
+                else
+                  if C.columnLength dense == n
+                    then Right dense
+                    else C.takeColumnArray (S.generate n (\i -> if good i then ranks P.! i else 0)) dense
+            C.maskValidity validity scattered
+    Struct children -> do
+      V.mapM_ (\child -> if planAnchor child < 0 then Right () else sameShape leaves plan (planAnchor child)) children
+      columns <- V.mapM (assembleIn (Just n) transformPrimitive leaves) children
+      if V.any ((/= n) . C.columnLength) columns
+        then Left "Parquet.Arrow: struct children have inconsistent row counts"
+        else C.mkStruct n validity (V.zip (A.fieldName . planField <$> children) columns)
+    List child ->
+      if A.fieldType (planField plan) == A.ALargeList
+        then do
+          offsets <- listOffsets child anchor slots :: Either String (S.Vector Int64)
+          values <- assembleIn (Just (fromIntegral (S.last offsets))) transformPrimitive leaves child
+          if fromIntegral (S.last offsets) /= C.columnLength values
+            then Left "Parquet.Arrow: list offsets and child count disagree"
+            else C.mkLargeList validity offsets values
+        else do
+          offsets <- listOffsets child anchor slots :: Either String (S.Vector Int32)
+          values <- assembleIn (Just (fromIntegral (S.last offsets))) transformPrimitive leaves child
+          if fromIntegral (S.last offsets) /= C.columnLength values
+            then Left "Parquet.Arrow: list offsets and child count disagree"
+            else C.mkList validity offsets values
+    Map key value -> do
+      if planAnchor value < 0
+        then Right ()
+        else do
+          sameShape leaves plan (planAnchor value)
+          if planAnchor key < 0 then Right () else sameShape leaves (key {planPresence = planSlotDef key}) (planAnchor value)
+      offsets <- listOffsets key anchor slots
+      let entries = Just (fromIntegral (S.last offsets))
+      keys <- assembleIn entries transformPrimitive leaves key
+      values <- assembleIn entries transformPrimitive leaves value
+      if C.columnLength keys /= C.columnLength values || fromIntegral (S.last offsets) /= C.columnLength keys
+        then Left "Parquet.Arrow: map entries have inconsistent row counts"
+        else C.mkMap validity offsets keys values
+    EmptyFile -> Left "Parquet.Arrow: zero-leaf FILE cannot have a physical anchor"
+  case planKind plan of
+    Primitive -> transformPrimitive plan result
+    _ -> Right result
+
+
+{- | Count synthesized FILE values before allocating their null bitmaps. A
+count-only level scan avoids constructing a second vector of slot indices.
+-}
+unbackedValues :: Int -> V.Vector (Either String LeafColumn) -> Plan -> Either String Int64
+unbackedValues rows leaves plan
+  | not (needsValues plan) = Right 0
+  | otherwise = count (Just rows) plan
+  where
+    needsValues current = case planKind current of
+      EmptyFile -> True
+      Struct children -> V.any needsValues children
+      List child -> needsValues child
+      Map key value -> needsValues key || needsValues value
+      Primitive -> False
+    leaf current = maybe (Left "Parquet.Arrow: missing physical anchor") id (leaves V.!? planAnchor current)
+    slots current column =
+      P.ifoldl'
+        ( \total index definition ->
+            if fromIntegral (leafReps column P.! index) <= planSlotRep current && fromIntegral definition >= planSlotDef current
+              then total + 1
+              else total
+        )
+        0
+        (leafDefs column)
+    slotCount context current
+      | planAnchor current >= 0 = slots current <$> leaf current
+      | otherwise = maybe (Left "Parquet.Arrow: missing containing row count") Right context
+    add left right = if left > maxBound - right then maxBound else left + right
+    childrenTotal context = V.foldM (\total child -> add total <$> count context child) 0
+    count context current
+      | not (needsValues current) = Right 0
+      | otherwise = case planKind current of
+          EmptyFile -> fromIntegral <$> slotCount context current
+          Struct children -> do
+            size <- slotCount context current
+            childrenTotal (Just size) children
+          List child
+            | planAnchor current < 0 -> case context of
+                Just 0 -> Right 0
+                _ -> missing
+            | otherwise -> do
+                column <- leaf current
+                count (Just (slots child column)) child
+          Map key value
+            | planAnchor current < 0 -> case context of
+                Just 0 -> Right 0
+                _ -> missing
+            | otherwise -> do
+                column <- leaf current
+                let entries = Just (slots key column)
+                keyCount <- count entries key
+                valueCount <- count entries value
+                Right (add keyCount valueCount)
+          Primitive -> Right 0
+    missing = Left "Parquet.Arrow: container has no physical leaf to recover its shape"
+
+
+-- Defined byte/text values are already in output order. Inserting empty null
+-- slots requires new offsets, not a gather that copies the first string into
+-- every null row (which can overflow Arrow's offsets for a small valid file).
+flatVariable
+  :: Storable o
+  => Plan
+  -> P.Vector Int32
+  -> (Maybe C.Validity -> S.Vector o -> ByteString -> Either String C.ColumnArray)
+  -> S.Vector o
+  -> ByteString
+  -> Either String C.ColumnArray
+flatVariable plan defs mk offsets bytes
+  | S.length offsets /= defined + 1 = Left "Parquet.Arrow: defined values and offsets disagree"
+  | defined == n = mk validity offsets bytes
+  | otherwise = mk validity expanded bytes
+  where
+    n = P.length defs
+    presence = fromIntegral (planPresence plan)
+    defined = P.foldl' (\count def -> count + if def == presence then 1 else 0) 0 defs
+    validity = if A.fieldNullable (planField plan) then C.validityGenerate n (\i -> P.unsafeIndex defs i >= presence) else Nothing
+    expanded = runST $ do
+      output <- M.unsafeNew (n + 1)
+      let loop !i !rank = do
+            M.unsafeWrite output i (S.unsafeIndex offsets rank)
+            if i == n
+              then S.unsafeFreeze output
+              else loop (i + 1) (rank + if P.unsafeIndex defs i == presence then 1 else 0)
+      loop 0 0
+{-# INLINE flatVariable #-}
+
+
+variableFromRanks
+  :: Storable o
+  => (Maybe C.Validity -> S.Vector o -> ByteString -> Either String C.ColumnArray)
+  -> Maybe C.Validity
+  -> P.Vector Int
+  -> S.Vector o
+  -> ByteString
+  -> Either String C.ColumnArray
+variableFromRanks mk validity ranks offsets bytes =
+  mk validity (S.generate (P.length ranks) (\i -> S.unsafeIndex offsets (P.unsafeIndex ranks i))) bytes
+{-# INLINE variableFromRanks #-}
+
+
+-- Flat BOOLEAN needs only value/validity bitmaps. Walk definitions with
+-- a scalar source rank instead of allocating row-sized slots/ranks/indices.
+flatBool :: Plan -> P.Vector Int32 -> C.Bitmap -> Either String C.ColumnArray
+flatBool plan defs source
+  | defined /= C.bitmapLength source = Left "Parquet.Arrow: defined values and levels disagree"
+  | defined == n = C.mkBool Nothing source
+  | otherwise =
+      let buffers = scatterBoolBits presence defs source
+          validity = if A.fieldNullable (planField plan) then Just (Buffer.Validity (scatteredBoolValidity buffers) (n - defined)) else Nothing
+      in C.mkBool validity (scatteredBoolValues buffers)
+  where
+    n = P.length defs
+    presence = fromIntegral (planPresence plan)
+    defined = P.foldl' (\count def -> count + if def == presence then 1 else 0) 0 defs
+
+
+data ScatteredBool = ScatteredBool
+  { scatteredBoolValues :: !C.Bitmap
+  , scatteredBoolValidity :: !C.Bitmap
+  }
+
+
+scatterBoolBits :: Int32 -> P.Vector Int32 -> C.Bitmap -> ScatteredBool
+scatterBoolBits presence defs source = runST $ do
+  let n = P.length defs
+      (!whole, !tailBits) = n `quotRem` 8
+      size = whole + if tailBits == 0 then 0 else 1
+  values <- M.unsafeNew size
+  validity <- M.unsafeNew size
+  let finish = do
+        vb <- S.unsafeFreeze values
+        nb <- S.unsafeFreeze validity
+        pure (ScatteredBool (Buffer.Bitmap (Buffer.storableToBytes vb) 0 n) (Buffer.Bitmap (Buffer.storableToBytes nb) 0 n))
+      emit !row !rank !vb !nb !bit continue
+        | P.unsafeIndex defs row == presence =
+            let !nextValues = if Buffer.unsafeBitAt source rank then vb .|. bit else vb
+            in continue (rank + 1) nextValues (nb .|. bit)
+        | otherwise = continue rank vb nb
+      {-# INLINE emit #-}
+      tailRows !row !rank !lane !vb !nb
+        | row == n = M.unsafeWrite values (row `quot` 8) vb *> M.unsafeWrite validity (row `quot` 8) nb *> finish
+        | otherwise = emit row rank vb nb (1 `shiftL` lane) $ \nextRank nextValues nextValidity -> tailRows (row + 1) nextRank (lane + 1) nextValues nextValidity
+      loop !row !rank
+        | row == n = finish
+        | n - row < 8 = tailRows row rank 0 0 0
+        | otherwise =
+            emit row rank (0 :: Word8) (0 :: Word8) 1 $ \r1 v1 n1 ->
+              emit (row + 1) r1 v1 n1 2 $ \r2 v2 n2 ->
+                emit (row + 2) r2 v2 n2 4 $ \r3 v3 n3 ->
+                  emit (row + 3) r3 v3 n3 8 $ \r4 v4 n4 ->
+                    emit (row + 4) r4 v4 n4 16 $ \r5 v5 n5 ->
+                      emit (row + 5) r5 v5 n5 32 $ \r6 v6 n6 ->
+                        emit (row + 6) r6 v6 n6 64 $ \r7 v7 n7 ->
+                          emit (row + 7) r7 v7 n7 128 $ \r8 v8 n8 -> do
+                            M.unsafeWrite values (row `quot` 8) v8
+                            M.unsafeWrite validity (row `quot` 8) n8
+                            loop (row + 8) r8
+  loop 0 0
+{-# INLINE scatterBoolBits #-}
+
+
+-- A non-repeated primitive has one definition event per output row. Scatter
+-- directly, rather than building slots, prefix ranks and gather indices.
+-- Concrete tags at each call site let specialization remove Storable dispatch
+-- from the row loop, including for the composite decimal/interval values.
+flatPrimitive :: Plan -> P.Vector Int32 -> C.PrimType a -> S.Vector a -> Either String C.ColumnArray
+flatPrimitive plan defs primitive values = case primitive of
+  C.PInt8 -> flatPrimitiveValues plan defs C.PInt8 values
+  C.PInt16 -> flatPrimitiveValues plan defs C.PInt16 values
+  C.PInt32 -> flatPrimitiveValues plan defs C.PInt32 values
+  C.PInt64 -> flatPrimitiveValues plan defs C.PInt64 values
+  C.PUInt8 -> flatPrimitiveValues plan defs C.PUInt8 values
+  C.PUInt16 -> flatPrimitiveValues plan defs C.PUInt16 values
+  C.PUInt32 -> flatPrimitiveValues plan defs C.PUInt32 values
+  C.PUInt64 -> flatPrimitiveValues plan defs C.PUInt64 values
+  C.PFloat16 -> flatPrimitiveValues plan defs C.PFloat16 values
+  C.PFloat -> flatPrimitiveValues plan defs C.PFloat values
+  C.PDouble -> flatPrimitiveValues plan defs C.PDouble values
+  C.PDate32 -> flatPrimitiveValues plan defs C.PDate32 values
+  C.PDate64 -> flatPrimitiveValues plan defs C.PDate64 values
+  C.PTime32 -> flatPrimitiveValues plan defs C.PTime32 values
+  C.PTime64 -> flatPrimitiveValues plan defs C.PTime64 values
+  C.PTimestamp -> flatPrimitiveValues plan defs C.PTimestamp values
+  C.PDuration -> flatPrimitiveValues plan defs C.PDuration values
+  C.PIntervalYearMonth -> flatPrimitiveValues plan defs C.PIntervalYearMonth values
+  C.PIntervalDayTime -> flatPrimitiveValues plan defs C.PIntervalDayTime values
+  C.PIntervalMonthDayNano -> flatPrimitiveValues plan defs C.PIntervalMonthDayNano values
+  C.PDecimal32 precision scale -> flatPrimitiveValues plan defs (C.PDecimal32 precision scale) values
+  C.PDecimal64 precision scale -> flatPrimitiveValues plan defs (C.PDecimal64 precision scale) values
+  C.PDecimal128 precision scale -> flatPrimitiveValues plan defs (C.PDecimal128 precision scale) values
+  C.PDecimal256 precision scale -> flatPrimitiveValues plan defs (C.PDecimal256 precision scale) values
+
+
+flatPrimitiveValues :: Storable a => Plan -> P.Vector Int32 -> C.PrimType a -> S.Vector a -> Either String C.ColumnArray
+flatPrimitiveValues plan defs primitive values
+  | defined /= S.length values = Left "Parquet.Arrow: defined values and levels disagree"
+  | defined == n = C.mkPrim primitive Nothing values
+  | defined == 0 = C.maskValidity validity (C.fillerColumn n (C.primColumn primitive values))
+  | A.fieldNullable (planField plan) =
+      let buffers = scatterWithValidity presence defs values defined
+      in C.mkPrim primitive (Just (scatteredValidity buffers)) (scatteredValues buffers)
+  | otherwise = C.mkPrim primitive validity scattered
+  where
+    n = P.length defs
+    presence = fromIntegral (planPresence plan)
+    defined = P.foldl' (\count def -> count + if def == presence then 1 else 0) 0 defs
+    validity = if A.fieldNullable (planField plan) then C.validityGenerate n (\i -> P.unsafeIndex defs i >= presence) else Nothing
+    scattered = runST $ do
+      output <- M.unsafeNew n
+      let loop !i !rank
+            | i == n = S.unsafeFreeze output
+            | P.unsafeIndex defs i == presence = do
+                M.unsafeWrite output i (S.unsafeIndex values rank)
+                loop (i + 1) (rank + 1)
+            | otherwise = do
+                M.unsafeWrite output i (S.unsafeIndex values 0)
+                loop (i + 1) rank
+      loop 0 0
+{-# INLINEABLE flatPrimitiveValues #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Int8 -> S.Vector Int8 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Int16 -> S.Vector Int16 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Int32 -> S.Vector Int32 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Int64 -> S.Vector Int64 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Word8 -> S.Vector Word8 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Word16 -> S.Vector Word16 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Word32 -> S.Vector Word32 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Word64 -> S.Vector Word64 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType C.Float16 -> S.Vector C.Float16 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Float -> S.Vector Float -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType Double -> S.Vector Double -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType C.IntervalDayTime -> S.Vector C.IntervalDayTime -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType C.IntervalMonthDayNano -> S.Vector C.IntervalMonthDayNano -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType C.Decimal128 -> S.Vector C.Decimal128 -> Either String C.ColumnArray #-}
+{-# SPECIALIZE flatPrimitiveValues :: Plan -> P.Vector Int32 -> C.PrimType C.Decimal256 -> S.Vector C.Decimal256 -> Either String C.ColumnArray #-}
+
+
+data ScatteredPrimitive a = ScatteredPrimitive
+  { scatteredValues :: !(S.Vector a)
+  , scatteredValidity :: !C.Validity
+  }
+
+
+-- The caller preflights the present count before allocating or reading a
+-- value. Build its bitmap while scattering, rather than scanning definitions
+-- again. Null slots keep the same first-value filler as the generic path.
+scatterWithValidity :: Storable a => Int32 -> P.Vector Int32 -> S.Vector a -> Int -> ScatteredPrimitive a
+scatterWithValidity presence defs values defined = runST $ do
+  let n = P.length defs
+      bytes = n `quot` 8 + if n `rem` 8 == 0 then 0 else 1
+      filler = S.unsafeIndex values 0
+  output <- M.unsafeNew n
+  bitmap <- M.unsafeNew bytes
+  let finish = do
+        frozen <- S.unsafeFreeze output
+        bits <- S.unsafeFreeze bitmap
+        pure (ScatteredPrimitive frozen (Buffer.Validity (Buffer.Bitmap (Buffer.storableToBytes bits) 0 n) (n - defined)))
+      emit !i !rank !mask !bit continue
+        | P.unsafeIndex defs i == presence = do
+            M.unsafeWrite output i (S.unsafeIndex values rank)
+            continue (rank + 1) (mask .|. bit)
+        | otherwise = do
+            M.unsafeWrite output i filler
+            continue rank mask
+      {-# INLINE emit #-}
+      tailRows !i !rank !lane !mask
+        | i == n = M.unsafeWrite bitmap (i `quot` 8) mask *> finish
+        | otherwise = emit i rank mask (1 `shiftL` lane) $ \nextRank nextMask ->
+            tailRows (i + 1) nextRank (lane + 1) nextMask
+      bytesLoop !i !rank
+        | i == n = finish
+        | n - i < 8 = tailRows i rank 0 0
+        | otherwise =
+            -- Constant bit positions eliminate per-row shifts and the
+            -- byte-boundary branch. Known continuations inline as joins.
+            emit i rank (0 :: Word8) 1 $ \r1 m1 ->
+              emit (i + 1) r1 m1 2 $ \r2 m2 ->
+                emit (i + 2) r2 m2 4 $ \r3 m3 ->
+                  emit (i + 3) r3 m3 8 $ \r4 m4 ->
+                    emit (i + 4) r4 m4 16 $ \r5 m5 ->
+                      emit (i + 5) r5 m5 32 $ \r6 m6 ->
+                        emit (i + 6) r6 m6 64 $ \r7 m7 ->
+                          emit (i + 7) r7 m7 128 $ \r8 m8 -> do
+                            M.unsafeWrite bitmap (i `quot` 8) m8
+                            bytesLoop (i + 8) r8
+  bytesLoop 0 0
+{-# INLINE scatterWithValidity #-}
+
+
+slotIndices :: Plan -> LeafColumn -> P.Vector Int
+slotIndices plan leaf =
+  P.filter
+    ( \i ->
+        fromIntegral (leafReps leaf P.! i) <= planSlotRep plan
+          && fromIntegral (leafDefs leaf P.! i) >= planSlotDef plan
+    )
+    (P.enumFromN 0 (P.length (leafDefs leaf)))
+
+
+listOffsets :: forall o. (Storable o, Integral o, Bounded o) => Plan -> LeafColumn -> P.Vector Int -> Either String (S.Vector o)
+listOffsets child leaf slots = runST $ do
+  offsets <- M.new (P.length slots + 1)
+  let loop !i !row !count !previousDef
+        | i == P.length (leafDefs leaf) = do
+            M.unsafeWrite offsets (P.length slots) (fromIntegral count)
+            if toInteger count > toInteger (maxBound :: o)
+              then pure (Left "Parquet.Arrow: list exceeds requested Arrow offset width")
+              else Right <$> S.unsafeFreeze offsets
+        | otherwise = do
+            let !rep = fromIntegral (leafReps leaf P.! i)
+                !def = fromIntegral (leafDefs leaf P.! i)
+                !continued = rep >= planSlotRep child
+                !entryDef = planSlotDef child
+            if (i == 0 && rep /= 0) || (continued && (previousDef < entryDef || def < entryDef))
+              then pure (Left "Parquet.Arrow: repeated value continues an absent container")
+              else do
+                next <-
+                  if row < P.length slots && slots P.! row == i
+                    then M.unsafeWrite offsets row (fromIntegral count) >> pure (row + 1)
+                    else pure row
+                let entry = rep <= planSlotRep child && def >= entryDef
+                loop (i + 1) next (if entry then count + 1 else count) def
+  loop 0 0 (0 :: Int) (0 :: Int)
+{-# INLINEABLE listOffsets #-}
+{-# SPECIALIZE listOffsets :: Plan -> LeafColumn -> P.Vector Int -> Either String (S.Vector Int32) #-}
+{-# SPECIALIZE listOffsets :: Plan -> LeafColumn -> P.Vector Int -> Either String (S.Vector Int64) #-}
+
+
+-- Siblings share their ancestors' presence and repetition boundaries.
+-- Equal total lengths alone would miss children assigned to different rows.
+sameShape :: V.Vector (Either String LeafColumn) -> Plan -> Int -> Either String ()
+sameShape leaves parent otherIndex = do
+  first <- maybe (Left "Parquet.Arrow: missing anchor leaf") id (leaves V.!? planAnchor parent)
+  other <- maybe (Left "Parquet.Arrow: missing sibling leaf") id (leaves V.!? otherIndex)
+  let a = slotIndices parent first
+      b = slotIndices parent other
+      matches i =
+        leafReps first P.! (a P.! i) == leafReps other P.! (b P.! i)
+          && min (fromIntegral (leafDefs first P.! (a P.! i))) (planPresence parent)
+            == min (fromIntegral (leafDefs other P.! (b P.! i))) (planPresence parent)
+  if P.length a == P.length b && P.all matches (P.enumFromN 0 (P.length a))
+    then Right ()
+    else Left "Parquet.Arrow: siblings disagree on ancestor levels"
diff --git a/src/Parquet/BloomFilter.hs b/src/Parquet/BloomFilter.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/BloomFilter.hs
@@ -0,0 +1,619 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE PatternSynonyms #-}
+{-# LANGUAGE RankNTypes #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+
+{- | Apache Parquet split-block bloom filter (SBBF), parquet-format 2.10+.
+
+See <https://parquet.apache.org/docs/file-format/bloomfilter/> for the
+spec. SBBF stores a bit array as a sequence of 256-bit blocks, each of
+which contains 8 32-bit words. Hashing uses XXH64 with seed 0 over the
+value's PLAIN encoding ("Wireform.Hash"'s seed-zero @xxh64@).
+
+The on-disk layout is:
+
+@
+BloomFilterHeader (Thrift Compact)
+  1: required i32 numBytes
+  2: required BloomFilterAlgorithm  algorithm  (always BLOCK)
+  3: required BloomFilterHash       hash       (always XXHASH)
+  4: required BloomFilterCompression compression (always UNCOMPRESSED)
+bitset bytes (numBytes wide)
+@
+
+This module gives:
+
+* 'newSbbf' / 'sbbfInsertHash' / 'sbbfCheckHash' for the in-memory filter
+* 'sbbfInsert' / 'sbbfCheck' for direct value insertion (XXH64 internal)
+* 'encodeBloomFilter' / 'decodeBloomFilter' for the spec's wire format
+* 'optimalNumBytes' for sizing helpers
+
+Hot paths use 'Data.Vector.Unboxed.Mutable.Vector Word64' for the
+bitset, four 64-bit reads/writes per block, and avoid all 'Maybe'
+allocation in the inner kernel.
+-}
+module Parquet.BloomFilter (
+  -- * Filter
+  Sbbf,
+  newSbbf,
+  newSbbfChecked,
+  newSbbfBytes,
+  newSbbfBytesChecked,
+  newSbbfFromBytes,
+  newSbbfFromBytesChecked,
+  SbbfBuilder,
+  buildSbbf,
+  buildSbbfChecked,
+  sbbfBuilderInsert,
+  sbbfBuilderInsertHash,
+  sbbfNumBytes,
+  sbbfInsert,
+  sbbfCheck,
+  sbbfInsertHash,
+  sbbfCheckHash,
+
+  -- * Wire format
+  BloomFilterHeader (..),
+  encodeBloomFilter,
+  decodeBloomFilter,
+  readBloomFilter,
+
+  -- * Sizing
+  optimalNumBytes,
+) where
+
+import Control.Monad.ST (ST, runST)
+import Control.Monad.ST.Unsafe (unsafeIOToST)
+import Data.Bits (shiftR, unsafeShiftL, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Int (Int16, Int32)
+import Data.Primitive.ByteArray (copyByteArrayToAddr)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Unboxed qualified as VU
+import Data.Vector.Unboxed.Base qualified as VUB
+import Data.Vector.Unboxed.Mutable qualified as MVU
+import Data.Word (Word32, Word64, Word8)
+import Foreign.Marshal.Utils (copyBytes)
+import Foreign.Ptr (Ptr, castPtr, plusPtr)
+import Foreign.Storable (pokeByteOff)
+import GHC.ByteOrder (ByteOrder (..), targetByteOrder)
+import GHC.Float (expm1Double, log1pDouble)
+import Parquet.Encryption qualified as Encryption
+import Parquet.Read qualified as Read
+import Parquet.Thrift.Schema
+import Parquet.Types qualified as P
+import Thrift.Decode (decodeCompactFrom)
+import Thrift.Encode (encodeCompact)
+import Thrift.Value qualified as TV
+import Wireform.Encode.Direct qualified as Direct
+import Wireform.Hash qualified as Hash
+
+
+-- | XXH64 with the Parquet bloom-filter default seed (@0@).
+xxh64 :: ByteString -> Word64
+xxh64 = Hash.xxh64 0
+{-# INLINE xxh64 #-}
+
+
+-- The spec's eight salt constants. Keeping them as cases lets each unrolled
+-- lane use an immediate constant rather than loading a shared vector.
+{-# INLINE saltForLane #-}
+saltForLane :: Int -> Word32
+saltForLane lane = case lane of
+  0 -> 0x47b6137b
+  1 -> 0x44974d91
+  2 -> 0x8824ad5b
+  3 -> 0xa2b7289d
+  4 -> 0x705495c7
+  5 -> 0x2df1424b
+  6 -> 0x9efc4947
+  _ -> 0x5c6bfb31
+
+
+-- | Block size in bytes (256 bits = eight 32-bit words = four 64-bit words).
+blockBytes :: Int
+blockBytes = 32
+
+
+{- | A split-block bloom filter, stored as @numBytes / 8@ packed
+64-bit words. Bit ordering inside each block follows the Parquet spec
+(block is eight 32-bit words, word @i@ stored at byte offset @4*i@,
+little-endian).
+-}
+data Sbbf = Sbbf
+  { sbbfBytes :: {-# UNPACK #-} !Int
+  -- ^ 'numBytes' in the header
+  , sbbfBlocks :: {-# UNPACK #-} !Int
+  -- ^ derived: 'sbbfBytes' / 32
+  , sbbfData :: {-# UNPACK #-} !(VU.Vector Word64)
+  }
+  deriving stock (Show, Eq)
+
+
+{- | Create a new SBBF with @numBytes@ bytes (rounded up to a multiple of 32).
+All bits start at zero. Use 'optimalNumBytes' to pick a sensible size.
+-}
+newSbbf :: Int -> Sbbf
+newSbbf numBytes = either error id (newSbbfChecked numBytes)
+
+
+{- | Checked, zeroed filter allocation. Sizes below one block select 32 bytes;
+oversized requests are rejected before rounding or allocating.
+-}
+newSbbfChecked :: Int -> Either String Sbbf
+newSbbfChecked numBytes = do
+  nb <- normalisedBitsetSize numBytes
+  newSbbfBytesChecked nb VU.empty
+
+
+{- | Build an exact-size filter from decoded 64-bit words. Empty words
+request a zeroed filter; other vectors must match the declared bitset.
+-}
+newSbbfBytes :: Int -> VU.Vector Word64 -> Sbbf
+newSbbfBytes nb bitsetWords = either error id (newSbbfBytesChecked nb bitsetWords)
+
+
+newSbbfBytesChecked :: Int -> VU.Vector Word64 -> Either String Sbbf
+newSbbfBytesChecked nb bitsetWords
+  | nb < blockBytes || nb `rem` blockBytes /= 0 || nb > largestBitset = Left "Parquet.BloomFilter: bitset size must be a positive multiple of 32 within the signed 32-bit wire limit"
+  | not (VU.null bitsetWords) && VU.length bitsetWords /= nb `quot` 8 = Left "Parquet.BloomFilter: decoded word count does not match bitset size"
+  | otherwise = Right (Sbbf nb (nb `quot` blockBytes) (if VU.null bitsetWords then VU.replicate (nb `quot` 8) 0 else bitsetWords))
+
+
+{- | Build from a serialized bitset, without its header. Invalid sizes are
+rejected rather than truncating bytes or creating a zero-block filter.
+-}
+newSbbfFromBytes :: ByteString -> Sbbf
+newSbbfFromBytes bytes = either error id (newSbbfFromBytesChecked bytes)
+
+
+newSbbfFromBytesChecked :: ByteString -> Either String Sbbf
+newSbbfFromBytesChecked bytes
+  | nb < blockBytes || nb `rem` blockBytes /= 0 || nb > largestBitset = Left "Parquet.BloomFilter: raw bitset size must be a positive multiple of 32 within the signed 32-bit wire limit"
+  | otherwise = newSbbfBytesChecked nb (parseBitset bytes)
+  where
+    nb = BS.length bytes
+
+
+largestBitset :: Int
+largestBitset = fromIntegral (maxBound :: Int32) - (blockBytes - 1)
+
+
+{-# INLINE normalisedBitsetSize #-}
+normalisedBitsetSize :: Int -> Either String Int
+normalisedBitsetSize bytes
+  | bytes > largestBitset = Left "Parquet.BloomFilter: requested bitset exceeds the signed 32-bit wire limit"
+  | otherwise = Right (roundUpBlock (max blockBytes bytes))
+
+
+-- | Private mutable state confined by the rank-two 'buildSbbf' callback.
+data SbbfBuilder s = SbbfBuilder
+  { builderBlocks :: {-# UNPACK #-} !Int
+  , builderData :: !(MVU.MVector s Word64)
+  }
+
+
+{- | Build a whole filter with one bitset allocation. The callback cannot
+retain mutable state after the filter is frozen. Prefer this over repeated
+'sbbfInsert' calls when constructing a column's complete filter.
+-}
+{-# INLINE buildSbbf #-}
+buildSbbf :: Int -> (forall s. SbbfBuilder s -> ST s ()) -> Sbbf
+buildSbbf bytes action = either error id (buildSbbfChecked bytes action)
+
+
+{-# INLINE buildSbbfChecked #-}
+buildSbbfChecked :: Int -> (forall s. SbbfBuilder s -> ST s ()) -> Either String Sbbf
+buildSbbfChecked bytes action = do
+  nb <- normalisedBitsetSize bytes
+  Right $ runST $ do
+    bitsetWords <- MVU.replicate (nb `quot` 8) 0
+    let blocks = nb `quot` blockBytes
+    action (SbbfBuilder blocks bitsetWords)
+    frozen <- VU.unsafeFreeze bitsetWords
+    pure (Sbbf nb blocks frozen)
+
+
+{-# INLINE sbbfBuilderInsert #-}
+sbbfBuilderInsert :: SbbfBuilder s -> ByteString -> ST s ()
+sbbfBuilderInsert builder bytes = do
+  -- XXH64 is read-only and keeps this immutable ByteString alive until the
+  -- FFI finishes. Threading that IO result through ST avoids a separate
+  -- unsafePerformIO thunk/noDuplicate boundary for every inserted value.
+  hash <- unsafeIOToST (Hash.xxh64IO 0 bytes)
+  sbbfBuilderInsertHash builder hash
+
+
+{-# INLINE sbbfBuilderInsertHash #-}
+sbbfBuilderInsertHash :: SbbfBuilder s -> Word64 -> ST s ()
+sbbfBuilderInsertHash builder !hash =
+  updateMutableBlock (builderData builder) (blockIndex hash (builderBlocks builder)) (fromIntegral hash)
+
+
+roundUpBlock :: Int -> Int
+roundUpBlock n =
+  let r = n `rem` blockBytes
+  in if r == 0 then n else n + (blockBytes - r)
+
+
+-- | Number of bytes in the bitset (matches 'numBytes' in the header).
+sbbfNumBytes :: Sbbf -> Int
+sbbfNumBytes = sbbfBytes
+
+
+{- | Insert a value (encoded as raw bytes — usually the column's PLAIN
+physical layout) into the filter.
+-}
+{-# INLINE sbbfInsert #-}
+sbbfInsert :: ByteString -> Sbbf -> Sbbf
+sbbfInsert bs = sbbfInsertHash (xxh64 bs)
+
+
+{- | Test whether a value /might/ be in the filter. False positives
+are possible; false negatives are not.
+-}
+{-# INLINE sbbfCheck #-}
+sbbfCheck :: ByteString -> Sbbf -> Bool
+sbbfCheck bs = sbbfCheckHash (xxh64 bs)
+
+
+-- | Insert by raw 64-bit hash (callers supply XXH64 themselves).
+sbbfInsertHash :: Word64 -> Sbbf -> Sbbf
+sbbfInsertHash !h sbbf =
+  let !blocks = sbbfBlocks sbbf
+      !blockIdx = blockIndex h blocks
+      !x = fromIntegral h :: Word32
+      !ws = sbbfData sbbf
+      !ws' = updateBlock ws blockIdx x
+  in sbbf {sbbfData = ws'}
+
+
+-- | Check by raw 64-bit hash.
+sbbfCheckHash :: Word64 -> Sbbf -> Bool
+sbbfCheckHash !h sbbf =
+  let !blocks = sbbfBlocks sbbf
+      !blockIdx = blockIndex h blocks
+      !x = fromIntegral h :: Word32
+  in checkBlock (sbbfData sbbf) blockIdx x
+
+
+{-# INLINE blockIndex #-}
+blockIndex :: Word64 -> Int -> Int
+blockIndex h blocks =
+  let !top = h `shiftR` 32
+  in fromIntegral ((top * fromIntegral blocks) `shiftR` 32) :: Int
+
+
+{- | Apply the @mask(x)@ to a single 32-bit lane @i@. Each word ends up
+with exactly one bit set: bit @((x * salt[i]) >> 27)@.
+-}
+{-# INLINE maskBitForLane #-}
+maskBitForLane :: Word32 -> Int -> Word32
+maskBitForLane x i =
+  let !s = saltForLane i
+      !y = x * s
+      !idx = fromIntegral (y `shiftR` 27) :: Int
+  in 1 `unsafeShiftL` idx
+
+
+-- One immutable insertion must preserve the original filter. Bulk callers
+-- share the same lane kernel, but mutate one private bitset for all values.
+updateBlock :: VU.Vector Word64 -> Int -> Word32 -> VU.Vector Word64
+updateBlock bitsetWords block value = runST $ do
+  mutable <- VU.thaw bitsetWords
+  updateMutableBlock mutable block value
+  VU.unsafeFreeze mutable
+
+
+{-# INLINE updateMutableBlock #-}
+updateMutableBlock :: forall s. MVU.MVector s Word64 -> Int -> Word32 -> ST s ()
+updateMutableBlock bitsetWords !block !value = do
+  let base = block * 4
+  applyLanePair (base + 0) 0 1
+  applyLanePair (base + 1) 2 3
+  applyLanePair (base + 2) 4 5
+  applyLanePair (base + 3) 6 7
+  where
+    {-# INLINE applyLanePair #-}
+    applyLanePair :: Int -> Int -> Int -> ST s ()
+    applyLanePair index low high = do
+      current <- MVU.unsafeRead bitsetWords index
+      let maskLow = fromIntegral (maskBitForLane value low) :: Word64
+          maskHigh = fromIntegral (maskBitForLane value high) :: Word64
+      MVU.unsafeWrite bitsetWords index (current .|. maskLow .|. (maskHigh `unsafeShiftL` 32))
+
+
+checkBlock :: VU.Vector Word64 -> Int -> Word32 -> Bool
+checkBlock ws !blockIdx !x =
+  let !base = blockIdx * 4
+      laneOk lo hi =
+        let !cur = VU.unsafeIndex ws (base + (lo `quot` 2))
+            !mLo = fromIntegral (maskBitForLane x lo) :: Word64
+            !mHi = fromIntegral (maskBitForLane x hi) :: Word64
+            !packed = mLo .|. (mHi `unsafeShiftL` 32)
+        in (cur .&. packed) == packed
+  in laneOk 0 1
+       && laneOk 2 3
+       && laneOk 4 5
+       && laneOk 6 7
+
+
+-- ============================================================
+-- Wire format
+-- ============================================================
+
+{- | Decoded @BloomFilterHeader@ struct. Algorithm and hash are
+enums-of-one in the current spec; we preserve them so that future
+variants don't silently round-trip into BLOCK/XXHASH.
+-}
+data BloomFilterHeader = BloomFilterHeader
+  { bfhNumBytes :: {-# UNPACK #-} !Int32
+  , bfhAlgorithm :: !BloomFilterAlgorithm
+  , bfhHash :: !BloomFilterHash
+  , bfhCompression :: !BloomFilterCompression
+  }
+  deriving stock (Show, Eq)
+
+
+data BloomFilterAlgorithm = AlgBlock
+  deriving stock (Show, Eq)
+
+
+data BloomFilterHash = HashXxh64
+  deriving stock (Show, Eq)
+
+
+data BloomFilterCompression = CompUncompressed
+  deriving stock (Show, Eq)
+
+
+{- | Build the on-disk byte string: Thrift-Compact 'BloomFilterHeader'
+followed by the bitset.
+-}
+encodeBloomFilter :: Sbbf -> ByteString
+encodeBloomFilter sbbf =
+  let !hdr =
+        BloomFilterHeader
+          { bfhNumBytes = fromIntegral (sbbfBytes sbbf)
+          , bfhAlgorithm = AlgBlock
+          , bfhHash = HashXxh64
+          , bfhCompression = CompUncompressed
+          }
+      !hdrBs = encodeCompact (bloomFilterHeaderToThrift hdr)
+      !headerBytes = BS.length hdrBs
+      !total = headerBytes + sbbfBytes sbbf
+  in Direct.directEncode total $ \target _ -> do
+       BSU.unsafeUseAsCString hdrBs $ \header -> copyBytes target (castPtr header) headerBytes
+       copyBitset (target `plusPtr` headerBytes) (sbbfData sbbf) (sbbfBytes sbbf)
+       pure total
+
+
+{- | Read an on-disk bloom filter (header + bitset). Validates that
+@numBytes@ matches what the bitset contains.
+-}
+decodeBloomFilter :: ByteString -> Either String (BloomFilterHeader, Sbbf)
+decodeBloomFilter bs = do
+  -- The Compact decoder reports the consumed header length, including
+  -- unknown optional fields, without repeatedly parsing growing prefixes.
+  (hdr, rest) <- splitHeader bs
+  let !nb = fromIntegral (bfhNumBytes hdr) :: Int
+  if nb < blockBytes || nb `rem` blockBytes /= 0
+    then Left "Parquet.BloomFilter: bitset size must be a positive multiple of 32 bytes"
+    else
+      if BS.length rest < nb
+        then
+          Left $
+            "Parquet.BloomFilter: bitset truncated (need "
+              ++ show nb
+              ++ " bytes, have "
+              ++ show (BS.length rest)
+              ++ ")"
+        else do
+          let !bitsetBs = BS.take nb rest
+              !words_ = parseBitset bitsetBs
+              !sbbf = newSbbfBytes nb words_
+          Right (hdr, sbbf)
+
+
+{- | Try to parse the Thrift Compact 'BloomFilterHeader' off the front
+of @bs@ and return @(header, bytesAfterHeader)@.
+-}
+splitHeader :: ByteString -> Either String (BloomFilterHeader, ByteString)
+splitHeader bs = do
+  (value, end) <- decodeCompactFrom bs 0
+  header <- thriftToBloomFilterHeader value
+  Right (header, BS.drop end bs)
+
+
+{- | Read a column's bloom filter, authenticating its separately encrypted
+header and bitset where required. Old files may omit the length field.
+-}
+readBloomFilter :: Read.ParquetFile -> Int -> Int -> Either String (Maybe Sbbf)
+readBloomFilter file groupIndex columnIndex = do
+  group <- maybe (Left "Parquet.BloomFilter: row group out of range") Right (P.fmRowGroups (Read.pfFooter file) V.!? groupIndex)
+  column <- maybe (Left "Parquet.BloomFilter: column out of range") Right (P.rgColumns group V.!? columnIndex)
+  case P.ccFilePath column of
+    Just path | path /= mempty -> Left "Parquet.BloomFilter: external column files are not supported"
+    _ -> Right ()
+  metadata <- maybe (Left "Parquet.BloomFilter: missing column metadata/key") Right (P.ccMetadata column)
+  case P.cmBloomFilterOffset metadata of
+    Nothing -> Right Nothing
+    Just offset -> do
+      let bytes = Read.pfBytes file
+          size = maybe (fromIntegral (BS.length bytes) - offset) fromIntegral (P.cmBloomFilterLength metadata)
+      if offset < 0 || offset > fromIntegral (BS.length bytes) || size < 0 || size > fromIntegral (BS.length bytes) - offset
+        then Left "Parquet.BloomFilter: bloom filter slice out of bounds"
+        else Right ()
+      let raw = BS.take (fromIntegral size) (BS.drop (fromIntegral offset) bytes)
+      plaintext <-
+        if Read.isColumnEncrypted file groupIndex columnIndex
+          then do
+            (_, afterHeader) <- Encryption.readFramedModule raw 0
+            headerBytes <- Read.decryptFileColumnModule file groupIndex columnIndex Encryption.ModuleBloomFilterHeader (BS.take afterHeader raw)
+            (_, afterBitset) <- Encryption.readFramedModule raw afterHeader
+            bitset <- Read.decryptFileColumnModule file groupIndex columnIndex Encryption.ModuleBloomFilterBitset (BS.take (afterBitset - afterHeader) (BS.drop afterHeader raw))
+            case P.cmBloomFilterLength metadata of
+              Just _ | afterBitset /= BS.length raw -> Left "Parquet.BloomFilter: encrypted bloom size differs from metadata"
+              _ -> Right ()
+            (value, headerEnd) <- decodeCompactFrom headerBytes 0
+            header <- thriftToBloomFilterHeader value
+            if not (BS.all (== 0) (BS.drop headerEnd headerBytes)) || BS.length bitset /= fromIntegral (bfhNumBytes header)
+              then Left "Parquet.BloomFilter: encrypted header/bitset sizes disagree"
+              else Right (BS.take headerEnd headerBytes <> bitset)
+          else Right raw
+      Just . snd <$> decodeBloomFilter plaintext
+
+
+bloomFilterHeaderToThrift :: BloomFilterHeader -> TV.Value
+bloomFilterHeaderToThrift hdr =
+  TV.Struct $
+    V.fromList
+      [ BloomFilterHeader_NumBytes (bfhNumBytes hdr)
+      , BloomFilterHeader_Algorithm (unionVariant1) -- BLOCK
+      , BloomFilterHeader_Hash (unionVariant1) -- XXHASH
+      , BloomFilterHeader_Compression (unionVariant1) -- UNCOMPRESSED
+      ]
+  where
+    -- Parquet's three bloom-filter enums are each encoded as a Thrift
+    -- union; we only support the first variant of each (BLOCK /
+    -- XXHASH / UNCOMPRESSED), so the nested struct always has field 1
+    -- set to an empty struct.
+    unionVariant1 :: V.Vector (Int16, TV.Value)
+    unionVariant1 = V.singleton (1, TV.Struct V.empty)
+
+
+thriftToBloomFilterHeader :: TV.Value -> Either String BloomFilterHeader
+thriftToBloomFilterHeader (TV.Struct fields) = do
+  let fm = V.toList fields
+  nb <- case findField
+    fm
+    ( \case
+        BloomFilterHeader_NumBytes v -> Just v
+        _ -> Nothing
+    ) of
+    Just v -> Right v
+    Nothing -> Left "Parquet.BloomFilter: missing numBytes"
+  alg <-
+    requireUnionVariant1
+      fm
+      "algorithm"
+      (\case BloomFilterHeader_Algorithm fs -> Just fs; _ -> Nothing)
+      AlgBlock
+      "BloomFilterAlgorithm"
+  hsh <-
+    requireUnionVariant1
+      fm
+      "hash"
+      (\case BloomFilterHeader_Hash fs -> Just fs; _ -> Nothing)
+      HashXxh64
+      "BloomFilterHash"
+  cmp <-
+    requireUnionVariant1
+      fm
+      "compression"
+      (\case BloomFilterHeader_Compression fs -> Just fs; _ -> Nothing)
+      CompUncompressed
+      "BloomFilterCompression"
+  Right
+    BloomFilterHeader
+      { bfhNumBytes = nb
+      , bfhAlgorithm = alg
+      , bfhHash = hsh
+      , bfhCompression = cmp
+      }
+thriftToBloomFilterHeader _ =
+  Left "Parquet.BloomFilter: expected struct for BloomFilterHeader"
+
+
+{- | Match a nested union struct that carries exactly one field with id
+@1@, return the corresponding Haskell enum value, and produce a
+uniform error for missing or unsupported variants.
+-}
+requireUnionVariant1
+  :: [(Int16, TV.Value)]
+  -> String
+  -> ((Int16, TV.Value) -> Maybe (V.Vector (Int16, TV.Value)))
+  -> a
+  -> String
+  -> Either String a
+requireUnionVariant1 fm missingLabel probe variant unionName =
+  case findField fm probe of
+    Just branches -> case V.toList branches of
+      [(1, _)] -> Right variant
+      _ ->
+        Left $
+          "Parquet.BloomFilter: unsupported "
+            ++ unionName
+            ++ " union variant"
+    Nothing -> Left $ "Parquet.BloomFilter: missing " ++ missingLabel
+
+
+-- Sbbf constructors guarantee a complete, exact-size Word64 vector. Copy
+-- only its logical slice; on big-endian hosts write individual bytes instead.
+-- The primitive copy keeps the ByteArray alive across any GC and does not
+-- require pinned source storage or an aligned destination.
+copyBitset :: Ptr Word8 -> VU.Vector Word64 -> Int -> IO ()
+copyBitset target words_@(VUB.V_Word64 (VP.Vector offset _ array)) bytes
+  | targetByteOrder == LittleEndian = copyByteArrayToAddr target array (offset * 8) bytes
+  | otherwise = go 0
+  where
+    go !index
+      | index >= bytes `quot` 8 = pure ()
+      | otherwise = do
+          let word = VU.unsafeIndex words_ index
+              putByte lane
+                | lane == 8 = pure ()
+                | otherwise = do
+                    pokeByteOff target (index * 8 + lane) (fromIntegral (word `shiftR` (lane * 8)) :: Word8)
+                    putByte (lane + 1)
+          putByte 0
+          go (index + 1)
+
+
+parseBitset :: ByteString -> VU.Vector Word64
+parseBitset bs =
+  let !n = BS.length bs `quot` 8
+  in VU.generate n $ \i ->
+       readLE64 bs (i * 8)
+
+
+{-# INLINE readLE64 #-}
+readLE64 :: ByteString -> Int -> Word64
+readLE64 bs !off =
+  let rd i = fromIntegral (BSU.unsafeIndex bs (off + i)) :: Word64
+  in rd 0
+       .|. (rd 1 `unsafeShiftL` 8)
+       .|. (rd 2 `unsafeShiftL` 16)
+       .|. (rd 3 `unsafeShiftL` 24)
+       .|. (rd 4 `unsafeShiftL` 32)
+       .|. (rd 5 `unsafeShiftL` 40)
+       .|. (rd 6 `unsafeShiftL` 48)
+       .|. (rd 7 `unsafeShiftL` 56)
+
+
+-- ============================================================
+-- Sizing
+-- ============================================================
+
+{- | Estimate bitset bytes using the eight-hash SBBF model, rounded up to a
+32-byte block. Invalid false-positive probabilities select one block. Sizes
+saturate at the largest bitset representable by Parquet's signed 32-bit header;
+that cap can prevent meeting a very demanding probability. Stable 'log1pDouble'
+and 'expm1Double' arithmetic handles probabilities near both 0 and 1.
+-}
+optimalNumBytes :: Int -> Double -> Int
+optimalNumBytes n fpp
+  | n <= 0 || isNaN fpp || fpp <= 0 || fpp >= 1 = blockBytes
+  | requested >= fromIntegral largestBitset = largestBitset
+  | otherwise = roundUpBlock (max blockBytes (ceiling requested))
+  where
+    logRoot = log fpp / 8
+    -- log(1-exp(x)) needs separate stable forms on either side of log(1/2).
+    -- In particular, exp(x) can round to 1 for a valid probability below1.
+    logGap
+      | logRoot > negate (log 2) = log (negate (expm1Double logRoot))
+      | otherwise = log1pDouble (negate (exp logRoot))
+    requested = negate (fromIntegral n) / logGap
diff --git a/src/Parquet/Brotli.hs b/src/Parquet/Brotli.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Brotli.hs
@@ -0,0 +1,143 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE EmptyDataDecls #-}
+{-# LANGUAGE ForeignFunctionInterface #-}
+
+{- | Native Brotli calls. Parquet supplies the decoded page size, so the normal
+reader allocates only that destination plus one overflow-detection byte.
+A complete stream and complete consumption of its input are both required.
+-}
+module Parquet.Brotli (compress, decompress, decompressSized) where
+
+import Control.Exception (bracket)
+import Control.Monad (when)
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Internal qualified as BSI
+import Data.ByteString.Unsafe qualified as U
+import Data.Int (Int32)
+import Data.Word (Word8)
+import Foreign.C.Types (CInt (..), CSize (..))
+import Foreign.ForeignPtr (withForeignPtr)
+import Foreign.Marshal.Alloc (alloca)
+import Foreign.Ptr (FunPtr, Ptr, castPtr, nullFunPtr, nullPtr)
+import Foreign.Storable (peek, poke)
+import System.IO.Unsafe (unsafeDupablePerformIO)
+
+
+data Decoder
+
+
+type Alloc = Ptr () -> CSize -> IO (Ptr ())
+
+
+type Free = Ptr () -> Ptr () -> IO ()
+
+
+foreign import ccall unsafe "BrotliDecoderCreateInstance"
+  createDecoder :: FunPtr Alloc -> FunPtr Free -> Ptr () -> IO (Ptr Decoder)
+
+
+foreign import ccall unsafe "BrotliDecoderDestroyInstance"
+  destroyDecoder :: Ptr Decoder -> IO ()
+
+
+foreign import ccall safe "BrotliDecoderDecompressStream"
+  decodeStream :: Ptr Decoder -> Ptr CSize -> Ptr (Ptr Word8) -> Ptr CSize -> Ptr (Ptr Word8) -> Ptr CSize -> IO CInt
+
+
+foreign import ccall unsafe "BrotliEncoderMaxCompressedSize"
+  maximumCompressedSize :: CSize -> IO CSize
+
+
+foreign import ccall safe "BrotliEncoderCompress"
+  encode :: CInt -> CInt -> CInt -> CSize -> Ptr Word8 -> Ptr CSize -> Ptr Word8 -> IO CInt
+
+
+-- The decoder state is destroyed before any continuation runs, including a
+-- retry with a larger destination. All FFI byte counts use size_t/CSize.
+decodeAtCapacity :: Int -> ByteString -> (ByteString -> IO a) -> IO a -> (String -> IO a) -> IO a
+decodeAtCapacity capacity input complete full failed = do
+  output <- BSI.mallocByteString capacity
+  withForeignPtr output $ \destination -> U.unsafeUseAsCStringLen input $ \(source, count) ->
+    alloca $ \availableInput -> alloca $ \nextInput -> alloca $ \availableOutput -> alloca $ \nextOutput -> do
+      poke availableInput (fromIntegral count)
+      poke nextInput (castPtr source)
+      poke availableOutput (fromIntegral capacity)
+      poke nextOutput destination
+      status <-
+        bracket
+          (createDecoder nullFunPtr nullFunPtr nullPtr)
+          (\decoder -> when (decoder /= nullPtr) (destroyDecoder decoder))
+          (\decoder -> if decoder == nullPtr then pure 0 else decodeStream decoder availableInput nextInput availableOutput nextOutput nullPtr)
+      leftInput <- peek availableInput
+      leftOutput <- peek availableOutput
+      let written = capacity - fromIntegral leftOutput
+      case status of
+        1
+          | leftInput /= 0 -> failed "trailing compressed input"
+          | leftOutput > fromIntegral capacity -> failed "invalid decoder output count"
+          | otherwise -> complete (BSI.fromForeignPtr output 0 written)
+        2 -> failed "truncated input"
+        3 -> full
+        _ -> failed "invalid stream or decoder allocation failure"
+
+
+{- | Exact page-sized decoding. One extra byte distinguishes a completed empty
+tail from a stream that actually expands past its advertised destination.
+-}
+decompressSized :: Int -> ByteString -> Either String ByteString
+decompressSized expected input
+  | expected < 0 || expected >= maxBound || expected > fromIntegral (maxBound :: Int32) = Left "Parquet.Read: invalid Brotli uncompressed size"
+  | otherwise =
+      unsafeDupablePerformIO $
+        decodeAtCapacity
+          (expected + 1)
+          input
+          (\bytes -> pure $ if BS.length bytes == expected then Right bytes else Left "Parquet.Read: Brotli decompressed size differs from page header")
+          (pure (Left "Parquet.Read: Brotli output exceeds page header size"))
+          (pure . Left . ("Parquet.Read: Brotli decompress failed: " ++))
+
+
+{- | Compatibility API for callers without a page header. Grow geometrically
+up to Parquet's signed INT32 page-size ceiling. File readers use the exact
+bounded path above instead of discovering the output size this way.
+-}
+decompress :: ByteString -> Either String ByteString
+decompress input = unsafeDupablePerformIO (go 32768)
+  where
+    limit = fromIntegral (maxBound :: Int32)
+    go !capacity =
+      decodeAtCapacity
+        capacity
+        input
+        (pure . Right)
+        ( if capacity == limit
+            then pure (Left "Parquet.Read: Brotli output exceeds INT32 page-size limit")
+            else go (if capacity > limit `quot` 2 then limit else capacity * 2)
+        )
+        (pure . Left . ("Parquet.Read: Brotli decompress failed: " ++))
+
+
+{- | Native default quality11, window22, generic mode. The destination is sized
+using the encoder's own bound; counts are checked before converting to Int.
+-}
+compress :: ByteString -> Either String ByteString
+compress input = unsafeDupablePerformIO $ do
+  bound <- maximumCompressedSize (fromIntegral (BS.length input))
+  if bound == 0 || bound > fromIntegral (maxBound :: Int)
+    then pure (Left "Parquet.Compress: Brotli output bound exceeds indexing range")
+    else do
+      output <- BSI.mallocByteString (fromIntegral bound)
+      withForeignPtr output $ \destination -> U.unsafeUseAsCStringLen input $ \(source, count) -> alloca $ \size -> do
+        poke size bound
+        status <- encode 11 22 0 (fromIntegral count) (castPtr source) size destination
+        actual <- peek size
+        pure $
+          if status == 1 && actual <= bound
+            then
+              let bytes = BSI.fromForeignPtr output 0 (fromIntegral actual)
+                  -- Keep incompressible data without an extra copy, but do not
+                  -- retain an input-sized destination for a tiny encoded page.
+                  trimmed = if actual < bound `quot` 2 then BS.copy bytes else bytes
+              in Right $! trimmed
+            else Left "Parquet.Compress: Brotli compression failed"
diff --git a/src/Parquet/ByteStreamSplit.hs b/src/Parquet/ByteStreamSplit.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/ByteStreamSplit.hs
@@ -0,0 +1,121 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | Encoder side of @BYTE_STREAM_SPLIT@ (Parquet encoding 9).
+
+Transposes the little-endian byte representation of fixed-width
+numeric values: instead of writing @[byte0, byte1, byte2, byte3]@ of
+value 0, then the same of value 1, etc., the encoder writes
+@[byte0(v0), byte0(v1), ...]@, then @[byte1(v0), byte1(v1), ...]@,
+and so on. For columns of mostly-similar floats this clusters the
+redundant high bytes together so downstream compressors (zstd /
+snappy / gzip) recover most of the savings.
+
+Reader counterparts: 'Parquet.Read.decodeByteStreamSplitFloat',
+'Parquet.Read.decodeByteStreamSplitDouble'.
+-}
+module Parquet.ByteStreamSplit (
+  encodeByteStreamSplitFloat,
+  encodeByteStreamSplitDouble,
+) where
+
+import Columnar.SIMD qualified as SIMD
+import Data.Bits (shiftR, (.&.))
+import Data.ByteString (ByteString)
+import Data.ByteString.Internal qualified as BSI
+import Data.ByteString.Unsafe qualified as BSUnsafe
+import Data.Primitive.ByteArray (ByteArray, copyByteArrayToAddr)
+import Data.Vector.Primitive qualified as VP
+import Data.Word (Word32, Word64, Word8)
+import Foreign.ForeignPtr (withForeignPtr)
+import Foreign.Ptr (Ptr, castPtr)
+import Foreign.Storable (pokeByteOff)
+import GHC.ByteOrder (ByteOrder (LittleEndian), targetByteOrder)
+import GHC.Float (castDoubleToWord64, castFloatToWord32)
+import System.IO.Unsafe (unsafeDupablePerformIO)
+
+
+-- | @BYTE_STREAM_SPLIT@ for @FLOAT@: 4 streams of @n@ bytes (4n bytes total).
+encodeByteStreamSplitFloat :: VP.Vector Float -> ByteString
+encodeByteStreamSplitFloat vs
+  | n > maxBound `quot` 4 = error "Parquet.ByteStreamSplit: FLOAT output size overflow"
+  | n >= 16 && targetByteOrder == LittleEndian =
+      encodeSplit 4 SIMD.splitByteStreams4Array SIMD.splitByteStreams4 vs
+  | otherwise = unsafeDupablePerformIO $ do
+      fp <- BSI.mallocByteString (4 * n)
+      withForeignPtr fp $ \ptr -> writeFloats ptr vs n 0
+      pure (BSI.fromForeignPtr fp 0 (4 * n))
+  where
+    n = VP.length vs
+
+
+writeFloats :: Ptr Word8 -> VP.Vector Float -> Int -> Int -> IO ()
+writeFloats !ptr !vs !n !i
+  | i >= n = pure ()
+  | otherwise = do
+      let !w = castFloatToWord32 (VP.unsafeIndex vs i)
+      pokeByteOff ptr i (byteOf32 0 w)
+      pokeByteOff ptr (n + i) (byteOf32 1 w)
+      pokeByteOff ptr (2 * n + i) (byteOf32 2 w)
+      pokeByteOff ptr (3 * n + i) (byteOf32 3 w)
+      writeFloats ptr vs n (i + 1)
+
+
+byteOf32 :: Int -> Word32 -> Word8
+byteOf32 k w = fromIntegral ((w `shiftR` (k * 8)) .&. 0xFF)
+{-# INLINE byteOf32 #-}
+
+
+-- | @BYTE_STREAM_SPLIT@ for @DOUBLE@: 8 streams of @n@ bytes (8n bytes total).
+encodeByteStreamSplitDouble :: VP.Vector Double -> ByteString
+encodeByteStreamSplitDouble vs
+  | n > maxBound `quot` 8 = error "Parquet.ByteStreamSplit: DOUBLE output size overflow"
+  | n >= 16 && targetByteOrder == LittleEndian =
+      encodeSplit 8 SIMD.splitByteStreams8Array SIMD.splitByteStreams8 vs
+  | otherwise = unsafeDupablePerformIO $ do
+      fp <- BSI.mallocByteString (8 * n)
+      withForeignPtr fp $ \ptr -> writeDoubles ptr vs n 0
+      pure (BSI.fromForeignPtr fp 0 (8 * n))
+  where
+    n = VP.length vs
+
+
+-- Small immutable arrays may move between calls, but cannot move during a
+-- bounded unsafe FFI call. Larger inputs are copied once into pinned
+-- storage so the safe call can allow GC while C reads them.
+encodeSplit
+  :: Int
+  -> (ByteArray -> Int -> Ptr Word8 -> Int -> IO ())
+  -> (Ptr Word8 -> Ptr Word8 -> Int -> IO ())
+  -> VP.Vector a
+  -> ByteString
+encodeSplit width splitArray split (VP.Vector offset n bytes) =
+  unsafeDupablePerformIO $
+    if n <= SIMD.unsafeCallBytes `quot` width
+      then BSI.create total $ \dst -> splitArray bytes (offset * width) dst n
+      else do
+        input <- BSI.create total $ \src -> copyByteArrayToAddr src bytes (offset * width) total
+        BSI.create total $ \dst -> BSUnsafe.unsafeUseAsCString input $ \src -> split (castPtr src) dst n
+  where
+    total = width * n
+{-# INLINE encodeSplit #-}
+
+
+writeDoubles :: Ptr Word8 -> VP.Vector Double -> Int -> Int -> IO ()
+writeDoubles !ptr !vs !n !i
+  | i >= n = pure ()
+  | otherwise = do
+      let !w = castDoubleToWord64 (VP.unsafeIndex vs i)
+      pokeByteOff ptr i (byteOf64 0 w)
+      pokeByteOff ptr (n + i) (byteOf64 1 w)
+      pokeByteOff ptr (2 * n + i) (byteOf64 2 w)
+      pokeByteOff ptr (3 * n + i) (byteOf64 3 w)
+      pokeByteOff ptr (4 * n + i) (byteOf64 4 w)
+      pokeByteOff ptr (5 * n + i) (byteOf64 5 w)
+      pokeByteOff ptr (6 * n + i) (byteOf64 6 w)
+      pokeByteOff ptr (7 * n + i) (byteOf64 7 w)
+      writeDoubles ptr vs n (i + 1)
+
+
+byteOf64 :: Int -> Word64 -> Word8
+byteOf64 k w = fromIntegral ((w `shiftR` (k * 8)) .&. 0xFF)
+{-# INLINE byteOf64 #-}
diff --git a/src/Parquet/Compress.hs b/src/Parquet/Compress.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Compress.hs
@@ -0,0 +1,137 @@
+{-# LANGUAGE CPP #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+{- | Page-data compression for the Parquet writer.
+
+The reader's 'Parquet.Read.decompressChunk' supports @Uncompressed@,
+@GZip@, @Snappy@ (with @-fsnappy@), @ZSTD@ (with @-fzstd@), and
+@LZ4_RAW@ (with @-flz4@), raw @LZO@ and optional @Brotli@
+(with @-fbrotli@). This module exposes the symmetric writer
+side: 'compressPageBytes' takes a 'Compression' codec and a page body
+and returns the compressed bytes.
+
+The codec set behind cabal flags is identical to the reader's; if the
+user requests a codec that wasn't enabled at build time, the writer
+returns @Left@ rather than silently emitting uncompressed data.
+-}
+module Parquet.Compress (
+  compressPageBytes,
+  validateCompression,
+) where
+
+import Codec.Compression.GZip qualified as GZip
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Lazy qualified as BL
+import Columnar.LZO qualified as LZO
+import Data.Bifunctor (first)
+
+
+#ifdef HAVE_SNAPPY
+import qualified Codec.Compression.Snappy as Snappy
+#endif
+
+#ifdef HAVE_ZSTD
+import qualified Codec.Compression.Zstd as Zstd
+#endif
+
+#ifdef HAVE_LZ4
+import qualified Columnar.LZ4 as LZ4
+#endif
+
+#ifdef HAVE_BROTLI
+import qualified Parquet.Brotli as Brotli
+#endif
+
+import Parquet.Types (Compression (..))
+
+
+-- | Check availability without running the codec or allocating a page.
+validateCompression :: Compression -> Either String ()
+validateCompression codec = case codec of
+  Uncompressed -> Right ()
+  GZip -> Right ()
+  LZO -> Right ()
+#ifdef HAVE_SNAPPY
+  Snappy -> Right ()
+#endif
+#ifdef HAVE_ZSTD
+  ZSTD -> Right ()
+#endif
+#ifdef HAVE_LZ4
+  LZ4Raw -> Right ()
+#endif
+#ifdef HAVE_BROTLI
+  Brotli -> Right ()
+#endif
+  _ -> Left ("Parquet.Compress: codec unavailable for writing: " ++ show codec)
+
+
+{- | Compress a page-body byte string with the given codec.
+
+@Uncompressed@ is always available; @GZip@ uses the built-in @zlib@
+dependency; @Snappy@\/@ZSTD@\/@LZ4@ require the matching @-f@ flag at
+build time. Returns @Left@ for codecs we cannot encode (e.g. the
+deprecated Hadoop-flavoured @LZ4@).
+-}
+compressPageBytes :: Compression -> ByteString -> Either String ByteString
+compressPageBytes Uncompressed bs = Right bs
+compressPageBytes GZip bs =
+  Right (BL.toStrict (GZip.compress (BL.fromStrict bs)))
+
+#ifdef HAVE_SNAPPY
+compressPageBytes Snappy bs = Right (Snappy.compress bs)
+#else
+compressPageBytes Snappy _ =
+  Left "Parquet.Compress: Snappy requires building wireform with -fsnappy"
+#endif
+
+#ifdef HAVE_ZSTD
+compressPageBytes ZSTD bs =
+  Right (Zstd.compress 3 bs)  -- level 3 is the parquet-mr default.
+#else
+compressPageBytes ZSTD _ =
+  Left "Parquet.Compress: ZSTD requires building wireform with -fzstd"
+#endif
+
+#ifdef HAVE_LZ4
+-- LZ4_RAW (Parquet codec id 7): the raw LZ4 block format with
+-- no framing. 'Columnar.LZ4.compress' is a direct FFI call to
+-- liblz4's @LZ4_compress_default@ — output is byte-identical
+-- to what arrow-cpp / parquet-mr / pyarrow emit, so any
+-- modern Parquet reader accepts it.
+-- A page above liblz4's raw-block limit cannot be compressed at all:
+-- 'LZ4.compress' would return an empty payload, which would be written
+-- as a valid but empty page. Reject it instead (Parquet pages are
+-- bounded by the page size, far below the limit).
+-- The raw block format represents empty input with a final zero token.
+-- Columnar.LZ4 uses an empty ByteString as its failure/empty sentinel, so
+-- handle this legal page explicitly before asking for a non-empty bound.
+compressPageBytes LZ4Raw bs
+  | BS.null bs = Right (BS.singleton 0)
+  | LZ4.compressBound (BS.length bs) < 0 =
+      Left "Parquet.Compress: LZ4_RAW input exceeds LZ4_MAX_INPUT_SIZE"
+  | otherwise = Right (LZ4.compress bs)
+#else
+compressPageBytes LZ4Raw _ =
+  Left "Parquet.Compress: LZ4_RAW requires building wireform with -flz4"
+#endif
+
+
+compressPageBytes LZ4 _ =
+  Left $
+    "Parquet.Compress: deprecated Hadoop LZ4 (codec 5) is not supported; "
+      ++ "use LZ4_RAW (codec 7) with -flz4"
+
+#ifdef HAVE_BROTLI
+compressPageBytes Brotli bs =
+  Brotli.compress bs
+#else
+compressPageBytes Brotli _ =
+  Left "Parquet.Compress: Brotli requires building wireform with -fbrotli"
+#endif
+
+
+-- Parquet uses the raw LZO1X stream, without Hadoop/lzop framing.
+compressPageBytes LZO bytes =
+  first (("Parquet.Compress: " ++) . LZO.prettyLZOError) (LZO.compress bytes)
diff --git a/src/Parquet/Decimal.hs b/src/Parquet/Decimal.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Decimal.hs
@@ -0,0 +1,110 @@
+{-# LANGUAGE BangPatterns #-}
+
+-- | Signed big-endian two's-complement operations for decimal storage.
+module Parquet.Decimal (
+  compareDecimalBytes,
+  decodeDecimalInteger,
+  encodeDecimalInteger,
+  decimalPrecisionFits,
+) where
+
+import Data.Bits (shiftR, testBit, (.&.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Int (Int32)
+
+
+{- | Compare represented integers, including different widths and redundant
+sign extension. Offsets stay unboxed after inlining; no slices or Integer
+values are allocated by the comparison loop.
+-}
+compareDecimalBytes :: ByteString -> ByteString -> Ordering
+compareDecimalBytes a b
+  | BS.null a || BS.null b = compare (BS.length a) (BS.length b)
+  | negativeA /= negativeB = if negativeA then LT else GT
+  | widthA /= widthB = if negativeA then compare widthB widthA else compare widthA widthB
+  | otherwise = bytes 0
+  where
+    negativeA = testBit (BSU.unsafeIndex a 0) 7
+    negativeB = testBit (BSU.unsafeIndex b 0) 7
+    startA = significantStart a
+    startB = significantStart b
+    widthA = BS.length a - startA
+    widthB = BS.length b - startB
+    bytes !i
+      | i == widthA = EQ
+      | otherwise = case compare (BSU.unsafeIndex a (startA + i)) (BSU.unsafeIndex b (startB + i)) of
+          EQ -> bytes (i + 1)
+          result -> result
+{-# INLINE compareDecimalBytes #-}
+
+
+significantStart :: ByteString -> Int
+significantStart bytes = go 0
+  where
+    go !i
+      | i >= BS.length bytes - 1 = i
+      | otherwise =
+          let byte = BSU.unsafeIndex bytes i
+              nextNegative = testBit (BSU.unsafeIndex bytes (i + 1)) 7
+          in if (byte == 0 && not nextNegative) || (byte == 255 && nextNegative)
+               then go (i + 1)
+               else i
+{-# INLINE significantStart #-}
+
+
+-- | Metadata-only conversion; the per-value writer uses compareDecimalBytes.
+decodeDecimalInteger :: ByteString -> Maybe Integer
+decodeDecimalInteger bytes
+  | BS.null bytes = Nothing
+  | otherwise =
+      Just
+        ( BS.foldl'
+            (\n byte -> n * 256 + fromIntegral byte)
+            (if testBit (BSU.unsafeIndex bytes 0) 7 then -1 else 0)
+            bytes
+        )
+
+
+encodeDecimalInteger :: Integer -> ByteString
+encodeDecimalInteger = BS.reverse . BS.unfoldr step . Just
+  where
+    step Nothing = Nothing
+    step (Just n) =
+      let byte = fromIntegral (n .&. 255)
+          rest = n `shiftR` 8
+          done = (rest == 0 && not (testBit byte 7)) || (rest == -1 && testBit byte 7)
+      in Just (byte, if done then Nothing else Just rest)
+
+
+{- | Whether a positive DECIMAL precision fits signed, fixed-width storage.
+All positive Int32 widths/precisions are handled without floating point or
+large powers derived from the metadata. BYTE_ARRAY has no such bound.
+
+The capacity is floor((8*width-1)*log10(2)). The rational below is a lower
+bound on log10(2), less than 10^-50 below its upper bound. Its floor is exact
+for every bit count <=17179869175: the whole log interval is strictly between
+adjacent Farey fractions 5107137094/16965542197 and 579001193/1923400330.
+Their determinant is 1 and denominator sum 18888942527 exceeds that bit limit;
+no rational k/n in this interval can have an admitted denominator n.
+
+scripts/verify_parquet_decimal_capacity.py proves both the logarithm bounds
+with exact rational series and the Farey certificate against these constants.
+This is metadata validation, outside the per-value comparison path.
+-}
+decimalPrecisionFits :: Int32 -> Int32 -> Bool
+decimalPrecisionFits precision width
+  | precision <= 0 || width <= 0 = False
+  | otherwise =
+      let bits = 8 * toInteger width - 1
+          capacity = (bits * log10TwoLowerNumerator) `quot` log10TwoDenominator
+      in toInteger precision <= capacity
+
+
+log10TwoLowerNumerator :: Integer
+log10TwoLowerNumerator = 30102999566398119521373889472449302676818988146210
+
+
+log10TwoDenominator :: Integer
+log10TwoDenominator = 100000000000000000000000000000000000000000000000000
diff --git a/src/Parquet/Decryption.hs b/src/Parquet/Decryption.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Decryption.hs
@@ -0,0 +1,308 @@
+{-# LANGUAGE PatternSynonyms #-}
+
+{- | Key routing and authenticated metadata for Parquet Modular Encryption.
+Key metadata is opaque; applications can resolve it through their own KMS
+and supply the resulting keys. This module performs no network access.
+-}
+module Parquet.Decryption (
+  DecryptionConfig (..),
+  defaultDecryptionConfig,
+  DecryptedMetadata (..),
+  DecryptionState,
+  ColumnCrypto,
+  ColumnKeyMetadata (..),
+  columnKeyMetadata,
+  decryptFileMetadata,
+  columnCrypto,
+  cryptoColumnMetadata,
+  decryptColumnModule,
+  decryptColumnPageBody,
+  decryptColumnPageHeader,
+) where
+
+import Control.Monad (unless)
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int16)
+import Data.Map.Strict (Map)
+import Data.Map.Strict qualified as Map
+import Data.Text (Text)
+import Data.Text.Encoding qualified as TE
+import Data.Vector qualified as V
+import Parquet.Encryption qualified as E
+import Parquet.Footer qualified as F
+import Parquet.Levels qualified as Levels
+import Parquet.Thrift.Schema
+import Parquet.Types
+import Thrift.Decode (decodeCompactFrom)
+import Thrift.Value qualified as TV
+
+
+data DecryptionConfig = DecryptionConfig
+  { dcFooterKey :: !(Maybe ByteString)
+  -- ^ Explicit footer encryption/signing key, overriding key metadata.
+  , dcColumnKeys :: !(Map (V.Vector Text) ByteString)
+  -- ^ Explicit keys by complete schema path, overriding key metadata.
+  , dcKeyMetadataKeys :: !(Map ByteString ByteString)
+  -- ^ Keys resolved by the application from opaque key metadata.
+  , dcAadPrefix :: !(Maybe ByteString)
+  -- ^ Expected stored prefix, or the prefix omitted by the writer.
+  , dcExpectedFileId :: !(Maybe ByteString)
+  -- ^ Optional identity check for callers using the original explicit-AAD API.
+  }
+  deriving stock (Eq)
+
+
+instance Show DecryptionConfig where
+  show config =
+    "DecryptionConfig {footerKey = "
+      ++ maybe "absent" (const "<redacted>") (dcFooterKey config)
+      ++ ", columnKeys = "
+      ++ show (Map.size (dcColumnKeys config))
+      ++ ", metadataKeys = "
+      ++ show (Map.size (dcKeyMetadataKeys config))
+      ++ "}"
+
+
+defaultDecryptionConfig :: DecryptionConfig
+defaultDecryptionConfig = DecryptionConfig Nothing Map.empty Map.empty Nothing Nothing
+
+
+data ColumnOrdinal = ColumnOrdinal
+  { ordinalGroup :: {-# UNPACK #-} !Int
+  , ordinalColumn :: {-# UNPACK #-} !Int
+  }
+  deriving stock (Eq, Ord)
+
+
+newtype DecryptionState = DecryptionState (Map ColumnOrdinal ColumnCrypto)
+  deriving stock (Eq)
+
+
+instance Show DecryptionState where
+  show (DecryptionState columns) = "DecryptionState {encryptedColumns = " ++ show (Map.size columns) ++ "}"
+
+
+data ColumnCrypto = ColumnCrypto
+  { cryptoKey :: !(Either String ByteString)
+  , cryptoAlgorithm :: !E.EncryptionAlgorithm
+  , cryptoFileId :: !ByteString
+  , cryptoPrefix :: !ByteString
+  , cryptoRowGroup :: {-# UNPACK #-} !Int16
+  , cryptoOrdinal :: {-# UNPACK #-} !Int16
+  , cryptoColumnMetadata :: !(Either String ColumnMetadata)
+  , cryptoKeyPath :: !(Maybe (V.Vector Text))
+  , cryptoKeyMetadata :: !(Maybe ByteString)
+  }
+  deriving stock (Eq)
+
+
+{- | Authenticated routing information, without the resolved encryption key.
+Inspect these entries after opening a file with its footer key, resolve
+their opaque metadata through an application KMS, then supply the keys in
+a configuration for the file. Entries are per row group/physical column.
+-}
+data ColumnKeyMetadata = ColumnKeyMetadata
+  { ckmRowGroup :: {-# UNPACK #-} !Int
+  , ckmColumn :: {-# UNPACK #-} !Int
+  , ckmPath :: !(V.Vector Text)
+  , ckmKeyMetadata :: !(Maybe ByteString)
+  }
+  deriving stock (Show, Eq)
+
+
+columnKeyMetadata :: DecryptionState -> V.Vector ColumnKeyMetadata
+columnKeyMetadata (DecryptionState columns) = V.fromList (Map.foldrWithKey collect [] columns)
+  where
+    collect ordinal context entries = case cryptoKeyPath context of
+      Nothing -> entries
+      Just path -> ColumnKeyMetadata (ordinalGroup ordinal) (ordinalColumn ordinal) path (cryptoKeyMetadata context) : entries
+
+
+data DecryptedMetadata = DecryptedMetadata
+  { decryptedMetadata :: !FileMetadata
+  , decryptionState :: !DecryptionState
+  }
+  deriving stock (Show, Eq)
+
+
+columnCrypto :: DecryptionState -> Int -> Int -> Maybe ColumnCrypto
+columnCrypto (DecryptionState columns) group column = Map.lookup (ColumnOrdinal group column) columns
+
+
+{- | Authenticate the footer and resolve available column metadata. An absent
+or incorrect key for an unrequested column does not prevent projection of
+other columns. Its metadata remains absent, so statistics cannot prune on
+unreadable data; requesting that column reports its key/authentication error.
+-}
+decryptFileMetadata :: DecryptionConfig -> ByteString -> Either String DecryptedMetadata
+decryptFileMetadata config bytes = do
+  routing <- E.readFooterCryptoMetadata bytes
+  key <- case routing of
+    Nothing -> Right BS.empty
+    Just info -> resolveKey (dcFooterKey config) (E.fcmKeyMetadata info)
+  authenticated <- E.authenticateFooter key (dcAadPrefix config) (dcExpectedFileId config) bytes
+  metadata <- F.thriftToFileMetadata (E.afValue authenticated)
+  case E.afCryptoMetadata authenticated of
+    Nothing -> Right (DecryptedMetadata metadata (DecryptionState Map.empty))
+    Just info -> do
+      fields <- struct (E.afValue authenticated)
+      rawGroups <- required (FileMetadata_RowGroups V.empty) fields >>= list
+      unless (V.length rawGroups == V.length (fmRowGroups metadata)) (Left "Parquet.Decryption: row-group count mismatch")
+      let prefix = maybe (maybe BS.empty id (E.fcmStoredAadPrefix info)) id (dcAadPrefix config)
+      groups <- V.imapM (prepareGroup metadata info prefix key) rawGroups
+      let updated = V.map groupMetadata groups
+          contexts = V.foldl' (\allContexts group -> Map.union allContexts (groupContexts group)) Map.empty groups
+          sanitized = case fmColumnOrders metadata of
+            Nothing -> updated
+            Just orders -> V.map (F.sanitizeColumnOrders (fmSchema metadata) orders) updated
+      Right (DecryptedMetadata metadata {fmRowGroups = sanitized} (DecryptionState contexts))
+  where
+    resolveKey explicit opaque = case explicit of
+      Just key -> Right key
+      Nothing -> maybe (Left "Parquet.Decryption: no key for encrypted metadata") Right (opaque >>= (`Map.lookup` dcKeyMetadataKeys config))
+    prepareGroup metadataForGroup info prefix footerKey groupIndex raw = do
+      fields <- struct raw
+      rawColumns <- required (RowGroup_Columns V.empty) fields >>= list
+      let group = fmRowGroups metadataForGroup V.! groupIndex
+      unless (V.length rawColumns == V.length (rgColumns group)) (Left "Parquet.Decryption: column count mismatch")
+      ordinal <-
+        optional (RowGroup_Ordinal 0) fields >>= \case
+          Nothing -> Right groupIndex
+          Just (TV.I16 value) -> Right (fromIntegral value)
+          _ -> Left "Parquet.Decryption: invalid row-group ordinal"
+      columns <- V.imapM (prepareColumn metadataForGroup info prefix footerKey groupIndex ordinal) rawColumns
+      Right (PreparedGroup group {rgColumns = V.map preparedColumn columns} (V.foldl' (\m col -> maybe m (\context -> Map.insert (preparedOrdinal col) context m) (preparedCrypto col)) Map.empty columns))
+    prepareColumn metadata info prefix footerKey groupIndex groupOrdinal columnIndex raw = do
+      fields <- struct raw
+      description <- optional (ColumnChunk_CryptoMetadata V.empty) fields
+      -- The ordinary footer parser conservatively removes index locations
+      -- when column metadata is unavailable. Start with the original chunk,
+      -- decrypt its metadata, then apply that ordering policy to the result.
+      column <- F.thriftToColumnChunk raw
+      let ordinal = ColumnOrdinal groupIndex columnIndex
+      case description of
+        Nothing -> do
+          encrypted <- optional (ColumnChunk_EncryptedColumnMetadata BS.empty) fields
+          unless (encrypted == Nothing) (Left "Parquet.Decryption: encrypted metadata lacks crypto description")
+          Right (PreparedColumn column ordinal Nothing)
+        Just descriptionValue -> do
+          variants <- struct descriptionValue
+          unless (V.length variants == 1) (Left "Parquet.Decryption: column crypto union needs one variant")
+          colOrdinal <- checkedOrdinal columnIndex
+          rowOrdinal <- checkedOrdinal groupOrdinal
+          keyChoice <- case V.head variants of
+            ColumnCryptoMetaData_EncryptionWithFooterKey _ -> Right (KeyChoice (Right footerKey) Nothing Nothing)
+            ColumnCryptoMetaData_EncryptionWithColumnKey entries -> do
+              keyFields <- struct (TV.Struct entries)
+              path <- required (EncryptionWithColumnKey_PathInSchema V.empty) keyFields >>= list >>= V.mapM text
+              unless (not (V.null path)) (Left "Parquet.Decryption: empty encrypted column path")
+              _ <- Levels.maxLevelsForColumnPath (fmSchema metadata) path
+              opaque <- optional (EncryptionWithColumnKey_KeyMetadata BS.empty) keyFields >>= traverse binary
+              Right (KeyChoice (resolveKey (Map.lookup path (dcColumnKeys config)) opaque) (Just path) opaque)
+            _ -> Left "Parquet.Decryption: unsupported column crypto variant"
+          encryptedMetadata <- optional (ColumnChunk_EncryptedColumnMetadata BS.empty) fields >>= traverse binary
+          let baseContext = ColumnCrypto (chosenKey keyChoice) (E.fcmAlgorithm info) (E.fcmFileId info) prefix rowOrdinal colOrdinal (Left "Parquet.Decryption: column metadata has not been resolved") (chosenPath keyChoice) (chosenMetadata keyChoice)
+              context = baseContext {cryptoColumnMetadata = resolved}
+              resolved = do
+                _ <- chosenKey keyChoice
+                decoded <- case encryptedMetadata of
+                  Nothing
+                    | chosenPath keyChoice /= Nothing || BS.take 4 bytes == F.parquetMagic -> Left "Parquet.Decryption: missing encrypted column metadata"
+                    | otherwise -> maybe (Left "Parquet.Decryption: missing column metadata") Right (ccMetadata column)
+                  Just ciphertext -> do
+                    plaintext <- decryptColumnModule baseContext E.ModuleColumnMetaData ciphertext
+                    (value, end) <- decodeCompactFrom plaintext 0
+                    unless (BS.all (== 0) (BS.drop end plaintext)) (Left "Parquet.Decryption: trailing encrypted column metadata")
+                    F.thriftToColumnMetadata value
+                case chosenPath keyChoice of
+                  Nothing -> Right ()
+                  Just path -> unless (path == cmPathInSchema decoded) (Left "Parquet.Decryption: encrypted column path mismatch")
+                Right decoded
+          Right (PreparedColumn column {ccMetadata = either (const Nothing) Just resolved} ordinal (Just context))
+
+
+data KeyChoice = KeyChoice
+  { chosenKey :: !(Either String ByteString)
+  , chosenPath :: !(Maybe (V.Vector Text))
+  , chosenMetadata :: !(Maybe ByteString)
+  }
+
+
+data PreparedGroup = PreparedGroup
+  { groupMetadata :: !RowGroup
+  , groupContexts :: !(Map ColumnOrdinal ColumnCrypto)
+  }
+
+
+data PreparedColumn = PreparedColumn
+  { preparedColumn :: !ColumnChunk
+  , preparedOrdinal :: !ColumnOrdinal
+  , preparedCrypto :: !(Maybe ColumnCrypto)
+  }
+
+
+checkedOrdinal :: Int -> Either String Int16
+checkedOrdinal value
+  | value < 0 || value > 32767 = Left "Parquet.Decryption: encryption ordinal exceeds signed 16-bit range"
+  | otherwise = Right (fromIntegral value)
+
+
+decryptColumnModule :: ColumnCrypto -> E.ModuleType -> ByteString -> Either String ByteString
+decryptColumnModule context kind bytes = do
+  key <- cryptoKey context
+  (ciphertext, end) <- E.readFramedModule bytes 0
+  unless (end == BS.length bytes) (Left "Parquet.Decryption: trailing encrypted module bytes")
+  E.decryptGcmModule key (columnAad context kind 0) ciphertext
+
+
+decryptColumnPageBody :: ColumnCrypto -> E.ModuleType -> Int -> ByteString -> Either String ByteString
+decryptColumnPageBody context kind page bytes = do
+  ordinal <- checkedOrdinal page
+  key <- cryptoKey context
+  case cryptoAlgorithm context of
+    E.AesGcmV1 -> E.decryptGcmModule key (columnAad context kind ordinal) bytes
+    E.AesGcmCtrV1 -> E.decryptCtrModule key bytes
+
+
+decryptColumnPageHeader :: ColumnCrypto -> E.ModuleType -> Int -> ByteString -> Either String ByteString
+decryptColumnPageHeader context kind page bytes = do
+  ordinal <- checkedOrdinal page
+  key <- cryptoKey context
+  E.decryptGcmModule key (columnAad context kind ordinal) bytes
+
+
+columnAad :: ColumnCrypto -> E.ModuleType -> Int16 -> ByteString
+columnAad context kind page = E.buildAad (cryptoPrefix context) (E.buildAadSuffix (cryptoFileId context) kind (cryptoRowGroup context) (cryptoOrdinal context) page)
+
+
+struct :: TV.Value -> Either String (V.Vector (Int16, TV.Value))
+struct (TV.Struct fields) = do
+  unless (Map.size (V.foldl' (\seen (tag, _) -> Map.insert tag () seen) Map.empty fields) == V.length fields) (Left "Parquet.Decryption: duplicate metadata field")
+  Right fields
+struct _ = Left "Parquet.Decryption: expected metadata struct"
+
+
+list :: TV.Value -> Either String (V.Vector TV.Value)
+list (TV.List _ values) = Right values
+list _ = Left "Parquet.Decryption: expected metadata list"
+
+
+optional :: (Int16, TV.Value) -> V.Vector (Int16, TV.Value) -> Either String (Maybe TV.Value)
+optional (tag, _) = Right . fmap snd . V.find ((== tag) . fst)
+
+
+required :: (Int16, TV.Value) -> V.Vector (Int16, TV.Value) -> Either String TV.Value
+required tag fields = optional tag fields >>= maybe (Left "Parquet.Decryption: missing metadata field") Right
+
+
+binary :: TV.Value -> Either String ByteString
+binary (TV.Binary bytes) = Right bytes
+binary (TV.String value) = Right (TE.encodeUtf8 value)
+binary _ = Left "Parquet.Decryption: expected binary metadata"
+
+
+text :: TV.Value -> Either String Text
+text (TV.String value) = Right value
+text (TV.Binary bytes) = either (const (Left "Parquet.Decryption: invalid UTF-8 column path")) Right (TE.decodeUtf8' bytes)
+text _ = Left "Parquet.Decryption: expected text column path"
diff --git a/src/Parquet/Delta.hs b/src/Parquet/Delta.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Delta.hs
@@ -0,0 +1,270 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | DELTA_BINARY_PACKED, DELTA_LENGTH_BYTE_ARRAY, and DELTA_BYTE_ARRAY
+encodings for Parquet columns.
+
+See Apache Parquet spec Encodings.md.
+-}
+module Parquet.Delta (
+  decodeDeltaBinaryPackedInt32,
+  decodeDeltaBinaryPackedInt64,
+  decodeDeltaLengthByteArray,
+  decodeDeltaByteArray,
+) where
+
+import Control.Monad.ST (ST, runST)
+import Data.Bits (shiftL, shiftR, xor, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int32, Int64)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Primitive.Mutable qualified as MVP
+import Data.Word (Word64)
+
+
+decodeDeltaBinaryPackedInt32 :: Int -> ByteString -> Either String (VP.Vector Int32)
+decodeDeltaBinaryPackedInt32 n bs = do
+  (v64, _) <- decodeDeltaBinaryPackedRaw n bs
+  Right (VP.map fromIntegral v64)
+{-# INLINE decodeDeltaBinaryPackedInt32 #-}
+
+
+decodeDeltaBinaryPackedInt64 :: Int -> ByteString -> Either String (VP.Vector Int64)
+decodeDeltaBinaryPackedInt64 n bs = fst <$> decodeDeltaBinaryPackedRaw n bs
+{-# INLINE decodeDeltaBinaryPackedInt64 #-}
+
+
+decodeDeltaBinaryPackedRaw :: Int -> ByteString -> Either String (VP.Vector Int64, Int)
+decodeDeltaBinaryPackedRaw expected _
+  | expected < 0 =
+      Left "Parquet.Delta: negative expected value count"
+decodeDeltaBinaryPackedRaw expected bs = do
+  (blockSize64, off1) <- readULEB128 bs 0
+  (numMiniblocks64, off2) <- readULEB128 bs off1
+  (totalValues64, off3) <- readULEB128 bs off2
+  (firstValue, off4) <- readZigzagLEB128 bs off3
+  let !blockSize = fromIntegral blockSize64 :: Int
+      !numMiniblocks = fromIntegral numMiniblocks64 :: Int
+      !totalValues = fromIntegral totalValues64 :: Int
+  if totalValues64 > fromIntegral (maxBound :: Int32)
+    then Left "Parquet.Delta: value count exceeds Parquet's signed 32-bit page limit"
+    else Right ()
+  if totalValues /= expected
+    then Left "Parquet.Delta: value count differs from page header"
+    else Right ()
+  if blockSize64 > fromIntegral (maxBound :: Int32)
+    || numMiniblocks64 > fromIntegral (maxBound :: Int32)
+    || numMiniblocks <= 0
+    || blockSize <= 0
+    || blockSize `rem` 128 /= 0
+    || blockSize `rem` numMiniblocks /= 0
+    || (blockSize `quot` numMiniblocks) `rem` 32 /= 0
+    then Left "Parquet.Delta: invalid block_size or num_miniblocks"
+    else Right ()
+  if totalValues == 0
+    then Right (VP.empty, off4)
+    else do
+      let !miniblockSize = blockSize `quot` numMiniblocks
+          !numDeltas = totalValues - 1
+          !blocks = if numDeltas == 0 then 0 else (numDeltas - 1) `quot` blockSize + 1
+      -- Every block needs at least a min-delta byte and all bit-width
+      -- bytes, even when every delta is constant. Check this before
+      -- allocating a vector based on an untrusted header count.
+      if blocks > (BS.length bs - off4) `quot` (numMiniblocks + 1)
+        then Left "Parquet.Delta: truncated block headers"
+        else Right ()
+      (deltas, finalOff) <- decodeAllBlocks bs off4 numDeltas numMiniblocks miniblockSize
+      Right (prefixSumVector totalValues firstValue deltas, finalOff)
+
+
+readULEB128 :: ByteString -> Int -> Either String (Word64, Int)
+readULEB128 bs = go 0 0
+  where
+    go !acc !shift !off
+      | off >= BS.length bs = Left "Parquet.Delta: truncated ULEB128"
+      | shift > 63 = Left "Parquet.Delta: ULEB128 overflow"
+      | shift == 63 && BS.index bs off > 1 = Left "Parquet.Delta: ULEB128 overflow"
+      | otherwise =
+          let !b = BS.index bs off
+              !val = acc .|. (fromIntegral (b .&. 0x7F) `shiftL` shift)
+          in if b .&. 0x80 == 0
+               then Right (val, off + 1)
+               else go val (shift + 7) (off + 1)
+
+
+readZigzagLEB128 :: ByteString -> Int -> Either String (Int64, Int)
+readZigzagLEB128 bs off = do
+  (raw, next) <- readULEB128 bs off
+  -- Shift the unsigned payload before converting: an arithmetic right shift
+  -- of a signed payload corrupts values whose zigzag form has bit 63 set.
+  let !decoded = fromIntegral (raw `shiftR` 1) `xor` negate (fromIntegral (raw .&. 1))
+  Right (decoded, next)
+
+
+prefixSumVector :: Int -> Int64 -> VP.Vector Int64 -> VP.Vector Int64
+prefixSumVector n firstVal deltas = runST $ do
+  mv <- MVP.new n
+  MVP.write mv 0 firstVal
+  let go !i !prev
+        | i >= n = pure ()
+        | otherwise = do
+            let !d =
+                  if i - 1 < VP.length deltas
+                    then VP.unsafeIndex deltas (i - 1)
+                    else 0
+                !cur = prev + d
+            MVP.write mv i cur
+            go (i + 1) cur
+  go 1 firstVal
+  VP.unsafeFreeze mv
+
+
+decodeAllBlocks
+  :: ByteString
+  -> Int
+  -> Int
+  -> Int
+  -> Int
+  -> Either String (VP.Vector Int64, Int)
+decodeAllBlocks bs off0 numDeltas nMini miniblockSize = runST $ do
+  mv <- MVP.new (max numDeltas 0) :: ST s (MVP.MVector s Int64)
+  result <- goBlock off0 0 mv
+  case result of
+    Left e -> pure (Left e)
+    Right finalOff -> do
+      v <- VP.unsafeFreeze mv
+      pure (Right (v, finalOff))
+  where
+    goBlock :: Int -> Int -> MVP.MVector s Int64 -> ST s (Either String Int)
+    goBlock !off !written mv
+      | written >= numDeltas = pure (Right off)
+      | otherwise =
+          case readZigzagLEB128 bs off of
+            Left e -> pure (Left e)
+            Right (minDelta, off1) ->
+              if off1 + nMini > BS.length bs
+                then pure (Left "Parquet.Delta: truncated bit widths")
+                else do
+                  let !off2 = off1 + nMini
+                  er <- goMini off2 0 written minDelta off1 mv
+                  case er of
+                    Left e -> pure (Left e)
+                    Right (off3, written3) -> goBlock off3 written3 mv
+
+    goMini :: Int -> Int -> Int -> Int64 -> Int -> MVP.MVector s Int64 -> ST s (Either String (Int, Int))
+    goMini !off !miniIdx !written !minDelta !bwOff mv
+      | miniIdx >= nMini = pure (Right (off, written))
+      | written >= numDeltas = pure (Right (off, written))
+      | otherwise = do
+          let !bw = fromIntegral (BS.index bs (bwOff + miniIdx)) :: Int
+              !nInMini = min miniblockSize (numDeltas - written)
+              !totalBitsInMini = miniblockSize * bw
+              !totalBytesInMini = (totalBitsInMini + 7) `quot` 8
+          if bw > 64
+            then pure (Left "Parquet.Delta: bit width exceeds 64")
+            else
+              if bw == 0
+                then do
+                  let fill !i
+                        | i >= nInMini = pure ()
+                        | otherwise = do
+                            MVP.write mv (written + i) minDelta
+                            fill (i + 1)
+                  fill 0
+                  goMini off (miniIdx + 1) (written + nInMini) minDelta bwOff mv
+                else
+                  if off + totalBytesInMini > BS.length bs
+                    then pure (Left "Parquet.Delta: truncated miniblock data")
+                    else do
+                      let unpack !i
+                            | i >= nInMini = pure ()
+                            | otherwise = do
+                                let !bitStart = i * bw
+                                    !raw = readBitsLE bs off bitStart bw
+                                    !delta = fromIntegral raw + minDelta
+                                MVP.write mv (written + i) delta
+                                unpack (i + 1)
+                      unpack 0
+                      goMini (off + totalBytesInMini) (miniIdx + 1) (written + nInMini) minDelta bwOff mv
+
+
+{-# INLINE readBitsLE #-}
+readBitsLE :: ByteString -> Int -> Int -> Int -> Word64
+readBitsLE bs baseOff bitOff bw
+  | bw == 0 = 0
+  | otherwise =
+      let !startByte = baseOff + (bitOff `quot` 8)
+          !startBit = bitOff `rem` 8
+          !endBit = startBit + bw
+          !bytesNeeded = (endBit + 7) `quot` 8
+          !mask = if bw >= 64 then maxBound else (1 `shiftL` bw) - 1
+          accum :: Word64 -> Int -> Word64
+          accum !acc !i
+            | i >= bytesNeeded = acc
+            | startByte + i >= BS.length bs = acc
+            | otherwise =
+                let !b = fromIntegral (BS.index bs (startByte + i)) :: Word64
+                    !part = if i == 0 then b `shiftR` startBit else b `shiftL` (8 * i - startBit)
+                in accum (acc .|. part) (i + 1)
+      in accum 0 0 .&. mask
+
+
+-- | DELTA_LENGTH_BYTE_ARRAY: delta-packed lengths followed by concatenated payloads.
+decodeDeltaLengthByteArray :: Int -> ByteString -> Either String (V.Vector ByteString)
+decodeDeltaLengthByteArray n bs = do
+  (lengths64, dataOffset) <- decodeDeltaBinaryPackedRaw n bs
+  let !payload = BS.drop dataOffset bs
+  splitByLengths lengths64 payload
+{-# INLINE decodeDeltaLengthByteArray #-}
+
+
+splitByLengths :: VP.Vector Int64 -> ByteString -> Either String (V.Vector ByteString)
+splitByLengths lens payload = case go [] 0 0 of
+  Left e -> Left e
+  Right xs -> Right $! V.fromList (reverse xs)
+  where
+    !n = VP.length lens
+    go !acc !i !off
+      | i >= n = Right acc
+      | otherwise =
+          let !len = fromIntegral (VP.unsafeIndex lens i) :: Int
+          in if len < 0 || len > BS.length payload - off
+               then Left "Parquet.Delta: DELTA_LENGTH_BYTE_ARRAY payload truncated"
+               else
+                 let !val = BS.take len (BS.drop off payload)
+                 in go (val : acc) (i + 1) (off + len)
+
+
+{- | DELTA_BYTE_ARRAY: delta-packed prefix lengths + DELTA_LENGTH_BYTE_ARRAY suffixes.
+Front-compressed / incremental string encoding.
+-}
+decodeDeltaByteArray :: Int -> ByteString -> Either String (V.Vector ByteString)
+decodeDeltaByteArray n bs = do
+  (prefixLens64, suffixOffset) <- decodeDeltaBinaryPackedRaw n bs
+  let !suffixBs = BS.drop suffixOffset bs
+  suffixes <- decodeDeltaLengthByteArray (VP.length prefixLens64) suffixBs
+  reconstructPrefixCompressed prefixLens64 suffixes
+{-# INLINE decodeDeltaByteArray #-}
+
+
+reconstructPrefixCompressed :: VP.Vector Int64 -> V.Vector ByteString -> Either String (V.Vector ByteString)
+reconstructPrefixCompressed prefixLens suffixes
+  | VP.length prefixLens /= V.length suffixes =
+      Left "Parquet.Delta: prefix/suffix count mismatch"
+  | otherwise = case go [] 0 BS.empty of
+      Left e -> Left e
+      Right xs -> Right $! V.fromList (reverse xs)
+  where
+    !n = VP.length prefixLens
+    go !acc !i !prev
+      | i >= n = Right acc
+      | otherwise =
+          let !pLen = fromIntegral (VP.unsafeIndex prefixLens i) :: Int
+              !suffix = V.unsafeIndex suffixes i
+          in if pLen < 0 || pLen > BS.length prev
+               then Left "Parquet.Delta: prefix length exceeds previous value length"
+               else
+                 let !prefix = BS.take pLen prev
+                     !val = BS.append prefix suffix
+                 in go (val : acc) (i + 1) val
diff --git a/src/Parquet/DeltaEncode.hs b/src/Parquet/DeltaEncode.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/DeltaEncode.hs
@@ -0,0 +1,310 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | Encoder side of @DELTA_BINARY_PACKED@.
+
+The reader's "Parquet.Delta" handles decode; this module produces
+bytes the reader accepts:
+
+@
+ULEB128 block_size
+ULEB128 num_miniblocks_in_block
+ULEB128 total_value_count
+ZigzagLEB128 first_value
+
+per block (until total_value_count consumed):
+  ZigzagLEB128 min_delta
+  uint8 bit_width[num_miniblocks_in_block]
+  per miniblock:
+    ceil(miniblock_size * bit_width / 8) bytes of LSB-packed (delta - min_delta)
+@
+
+We default @block_size = 128@ and @num_miniblocks = 4@ (so each
+miniblock holds 32 values), matching parquet-mr's writer config.
+-}
+module Parquet.DeltaEncode (
+  encodeDeltaBinaryPackedInt32,
+  encodeDeltaBinaryPackedInt64,
+  encodeDeltaBinaryPackedRaw,
+  encodeDeltaLengthByteArray,
+  encodeDeltaByteArray,
+) where
+
+import Data.Bits (countLeadingZeros, shiftL, shiftR, unsafeShiftL, unsafeShiftR, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder.Prim qualified as Prim
+import Data.ByteString.Builder.Prim.Internal qualified as PrimInternal
+import Data.ByteString.Lazy qualified as BL
+import Data.Int (Int32, Int64)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Word (Word32, Word64)
+import Foreign.Ptr (plusPtr)
+import Wireform.Builder qualified as B
+
+
+defaultBlockSize, defaultNumMiniblocks :: Int
+defaultBlockSize = 128
+defaultNumMiniblocks = 4
+
+
+{- | DELTA_BINARY_PACKED for INT32. Differences wrap at the physical
+32-bit width before promotion; widening the inputs first can produce
+33-bit miniblocks and min deltas that an INT32 reader cannot consume.
+-}
+encodeDeltaBinaryPackedInt32 :: VP.Vector Int32 -> ByteString
+encodeDeltaBinaryPackedInt32 vs
+  | VP.null vs = encodeDeltaStream 0 0 (const 0)
+  | otherwise =
+      encodeDeltaStream
+        (VP.length vs)
+        (fromIntegral (VP.unsafeIndex vs 0))
+        (\i -> fromIntegral (VP.unsafeIndex vs (i + 1) - VP.unsafeIndex vs i))
+
+
+-- | DELTA_BINARY_PACKED for INT64.
+encodeDeltaBinaryPackedInt64 :: VP.Vector Int64 -> ByteString
+encodeDeltaBinaryPackedInt64 = encodeDeltaBinaryPackedRaw
+
+
+-- | Lower-level raw encoder.
+encodeDeltaBinaryPackedRaw :: VP.Vector Int64 -> ByteString
+encodeDeltaBinaryPackedRaw vs
+  | VP.null vs = encodeDeltaStream 0 0 (const 0)
+  | otherwise = encodeDeltaStream (VP.length vs) (VP.unsafeIndex vs 0) (\i -> VP.unsafeIndex vs (i + 1) - VP.unsafeIndex vs i)
+
+
+-- Keep the physical-width subtraction in the typed caller. Inlining this
+-- pipeline removes the accessor closure from the block's scanning/packing
+-- loops and avoids materialising an input-sized vector of Int64 deltas.
+encodeDeltaStream :: Int -> Int64 -> (Int -> Int64) -> ByteString
+encodeDeltaStream n firstVal deltaAt =
+  let !header =
+        encodeULeb (fromIntegral defaultBlockSize)
+          <> encodeULeb (fromIntegral defaultNumMiniblocks)
+          <> encodeULeb (fromIntegral n)
+      !blocks = encodeBlocks (max 0 (n - 1)) deltaAt
+  in BL.toStrict (B.toLazyByteString (header <> encodeZigzagLeb firstVal <> blocks))
+{-# INLINE encodeDeltaStream #-}
+
+
+encodeBlocks :: Int -> (Int -> Int64) -> B.Builder
+encodeBlocks n deltaAt = go 0
+  where
+    go !off
+      | off >= n = mempty
+      | otherwise =
+          encodeOneBlock off (min defaultBlockSize (n - off)) deltaAt
+            <> go (off + defaultBlockSize)
+{-# INLINE encodeBlocks #-}
+
+
+encodeOneBlock :: Int -> Int -> (Int -> Int64) -> B.Builder
+encodeOneBlock off count deltaAt =
+  let !miniblockSize = defaultBlockSize `quot` defaultNumMiniblocks
+      minimumFrom !i !smallest
+        | i == count = smallest
+        | otherwise = minimumFrom (i + 1) (min smallest (deltaAt (off + i)))
+      !minDelta = minimumFrom 1 (deltaAt off)
+      payload !start !width =
+        encodeMiniblockPayload
+          minDelta
+          miniblockSize
+          width
+          (max 0 (min miniblockSize (count - start)))
+          (\i -> deltaAt (off + start + i))
+      widthAt !start =
+        let !end = min count (start + miniblockSize)
+            maximumFrom !i !largest
+              | i >= end = bitWidthW64 largest
+              | otherwise = maximumFrom (i + 1) (max largest (fromIntegral (deltaAt (off + i) - minDelta)))
+        in maximumFrom start 0
+      !width0 = widthAt 0
+      !width1 = widthAt miniblockSize
+      !width2 = widthAt (2 * miniblockSize)
+      !width3 = widthAt (3 * miniblockSize)
+  in encodeZigzagLeb minDelta
+       <> B.word8 (fromIntegral width0)
+       <> B.word8 (fromIntegral width1)
+       <> B.word8 (fromIntegral width2)
+       <> B.word8 (fromIntegral width3)
+       <> payload 0 width0
+       <> payload miniblockSize width1
+       <> payload (2 * miniblockSize) width2
+       <> payload (3 * miniblockSize) width3
+{-# INLINE encodeOneBlock #-}
+
+
+bitWidthW64 :: Word64 -> Int
+bitWidthW64 value = 64 - countLeadingZeros value
+
+
+-- Serialise the miniblock's packed bits. Always emits
+-- @ceil(miniblockSize * bw / 8)@ bytes (i.e. uses the *spec* miniblock
+-- size, not the actual chunk length). Trailing values past the end of
+-- the actual miniblock length are zero-padded.
+encodeMiniblockPayload :: Int64 -> Int -> Int -> Int -> (Int -> Int64) -> B.Builder
+encodeMiniblockPayload _minDelta _miniblockSize 0 _ _ = mempty
+encodeMiniblockPayload minDelta miniblockSize bw n deltaAt =
+  let !totalBits = miniblockSize * bw
+      !totalBytes = (totalBits + 7) `shiftR` 3
+  in B.primFixed (PrimInternal.fixedPrim totalBytes fill) ()
+  where
+    valueAt :: Int -> Word64
+    valueAt i = if i < n then fromIntegral (deltaAt i - minDelta) else 0
+    {-# INLINE valueAt #-}
+    -- FixedPrim reserves the whole miniblock once. Its standard LE stores
+    -- support unaligned builder cursors and write exactly four/eight bytes.
+    fill () output
+      | bw == 64 = words64 0
+      | bw == 32 = words32 0
+      | otherwise = packed 0 0 0 0
+      where
+        words64 !i
+          | i == miniblockSize = pure ()
+          | otherwise = PrimInternal.runF Prim.word64LE (valueAt i) (output `plusPtr` (i * 8)) *> words64 (i + 1)
+        words32 !i
+          | i == miniblockSize = pure ()
+          | otherwise = PrimInternal.runF Prim.word32LE (fromIntegral (valueAt i)) (output `plusPtr` (i * 4)) *> words32 (i + 1)
+        packed !i !offset !used !acc
+          | i == miniblockSize = tailBytes offset used acc
+          | otherwise =
+              let !value = valueAt i
+                  !merged = acc .|. (value `unsafeShiftL` used)
+                  !bits = used + bw
+              in if bits < 64
+                   then packed (i + 1) offset bits merged
+                   else do
+                     PrimInternal.runF Prim.word64LE merged (output `plusPtr` offset)
+                     -- used stays in [0,63]. A positive carry implies
+                     -- used > 0, so the remaining shift is also in [1,63].
+                     let !carry = if bits == 64 then 0 else value `unsafeShiftR` (64 - used)
+                     packed (i + 1) (offset + 8) (bits - 64) carry
+        tailBytes !offset !used !acc
+          | used == 0 = pure ()
+          | used == 32 = PrimInternal.runF Prim.word32LE (fromIntegral acc) (output `plusPtr` offset)
+          | otherwise = bytes 0
+          where
+            bytes !i
+              | i == (used + 7) `quot` 8 = pure ()
+              | otherwise = PrimInternal.runF Prim.word8 (fromIntegral (acc `unsafeShiftR` (i * 8))) (output `plusPtr` (offset + i)) *> bytes (i + 1)
+{-# INLINE encodeMiniblockPayload #-}
+
+
+-- ============================================================
+-- ULEB128 / zigzag
+-- ============================================================
+
+encodeULeb :: Word64 -> B.Builder
+encodeULeb = go
+  where
+    go !n
+      | n < 0x80 = B.word8 (fromIntegral n)
+      | otherwise =
+          B.word8 (fromIntegral (n .&. 0x7F) .|. 0x80)
+            <> go (n `shiftR` 7)
+
+
+encodeZigzagLeb :: Int64 -> B.Builder
+encodeZigzagLeb v =
+  let !u =
+        if v >= 0
+          then fromIntegral (v `shiftL` 1) :: Word64
+          else fromIntegral (negate v `shiftL` 1 - 1)
+  in encodeULeb u
+
+
+-- ============================================================
+-- DELTA_LENGTH_BYTE_ARRAY
+-- ============================================================
+
+{- | Encode a vector of byte arrays as @DELTA_LENGTH_BYTE_ARRAY@ (Parquet
+encoding 6).
+
+Layout:
+
+@
+  <DELTA_BINARY_PACKED of all lengths (Int32)>
+  <concatenated value bytes>
+@
+
+The total length / value count of the lengths block matches the input
+vector's length, and value bytes are written in input order with no
+separators or length prefixes (the lengths block is the index).
+-}
+encodeDeltaLengthByteArray :: V.Vector ByteString -> ByteString
+encodeDeltaLengthByteArray vs =
+  let !lens = VP.fromList [fromIntegral (BS.length b) :: Int32 | b <- V.toList vs]
+      !lengthsEncoded = encodeDeltaBinaryPackedInt32 lens
+      !concatenated =
+        BL.toStrict
+          ( B.toLazyByteString
+              (V.foldl' (\acc b -> acc <> B.byteString b) mempty vs)
+          )
+  in lengthsEncoded <> concatenated
+
+
+-- ============================================================
+-- DELTA_BYTE_ARRAY (incremental encoding)
+-- ============================================================
+
+{- | Encode a vector of byte arrays as @DELTA_BYTE_ARRAY@ (Parquet
+encoding 7), aka /incremental encoding/.
+
+Layout:
+
+@
+  <DELTA_BINARY_PACKED of prefix lengths (Int32)>
+  <DELTA_BINARY_PACKED of suffix lengths (Int32)>
+  <concatenated suffix bytes>
+@
+
+The /prefix length/ is the number of leading bytes shared with the
+previous element (always 0 for the first element); the /suffix/ is
+the trailing bytes that differ. Reassembly is
+@value[i] = value[i-1][:prefix[i]] <> suffix[i]@.
+
+This is the encoding parquet-mr uses for sorted string columns.
+-}
+encodeDeltaByteArray :: V.Vector ByteString -> ByteString
+encodeDeltaByteArray vs =
+  let (prefixLens, suffixes) = computePrefixesSuffixes vs
+      !prefixVec = VP.fromList prefixLens
+      !suffixLensVec = VP.fromList [fromIntegral (BS.length s) :: Int32 | s <- suffixes]
+      !prefixesEncoded = encodeDeltaBinaryPackedInt32 prefixVec
+      !suffixLensEncoded = encodeDeltaBinaryPackedInt32 suffixLensVec
+      !suffixBytes =
+        BL.toStrict
+          ( B.toLazyByteString
+              (foldMap B.byteString suffixes)
+          )
+  in prefixesEncoded <> suffixLensEncoded <> suffixBytes
+
+
+-- | Walk the input vector once computing each (prefixLen, suffix) pair.
+computePrefixesSuffixes :: V.Vector ByteString -> ([Int32], [ByteString])
+computePrefixesSuffixes vs = go 0 BS.empty [] []
+  where
+    n = V.length vs
+    go !i !prev accLens accSufs
+      | i >= n = (reverse accLens, reverse accSufs)
+      | otherwise =
+          let !cur = V.unsafeIndex vs i
+              !pfx = commonPrefixLen prev cur
+              !suf = BS.drop pfx cur
+          in go (i + 1) cur (fromIntegral pfx : accLens) (suf : accSufs)
+
+
+commonPrefixLen :: ByteString -> ByteString -> Int
+commonPrefixLen a b =
+  let !maxN = min (BS.length a) (BS.length b)
+      go !i
+        | i >= maxN = i
+        | BS.index a i /= BS.index b i = i
+        | otherwise = go (i + 1)
+  in go 0
+
+
+-- Suppress unused-import warning if 'Word32' isn't referenced directly.
+_unusedW32 :: Word32 -> Word32
+_unusedW32 = id
diff --git a/src/Parquet/Derive.hs b/src/Parquet/Derive.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Derive.hs
@@ -0,0 +1,543 @@
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE TemplateHaskell #-}
+
+{- | Annotation-driven Template Haskell deriver for Apache Parquet.
+
+Parquet is a file-format with column-chunk layout, page splitting,
+compression, and footer metadata. Fully automating a row codec
+would require inventing layout decisions the user typically wants
+to control. This deriver therefore ships /schema-only/ TH plus a
+per-row leaf projection:
+
+* 'parquetSchemaFor' splices a flat
+  @V.Vector "Parquet.Types".SchemaElement@ — the same shape
+  "Parquet.Footer" expects in @fmSchema@. Index 0 is a synthetic
+  root struct (@seName = "schema"@); indices @1..N@ are the leaves
+  in record-declaration order. Field names honour 'rename' \/
+  'renameStyle' modifiers.
+* 'ToParquetRow' \/ 'FromParquetRow' convert a record to a
+  per-row @V.Vector (Maybe PN.LeafValue)@ with one slot per
+  non-skipped field. 'Maybe' fields lower to a 'Nothing' slot.
+* 'deriveParquet' emits both class instances at once.
+
+== Limitations
+
+* Records only. Newtypes \/ sums \/ enums fail at splice time.
+* Only the recognised flat scalar leaves (@Int32 \/ Int64 \/ Int
+  \/ Word32 \/ Word64 \/ Float \/ Double \/ Bool \/ Text \/
+  String \/ ByteString@) are supported, plus newtypes thereof
+  when annotated with 'coerced'.
+-}
+module Parquet.Derive (
+  parquetSchemaFor,
+  ToParquetRow (..),
+  FromParquetRow (..),
+  deriveParquet,
+  deriveToParquetRow,
+  deriveFromParquetRow,
+) where
+
+import Data.ByteString (ByteString)
+import Data.Coerce (coerce)
+import Data.Int (Int32, Int64)
+import Data.Text qualified as T
+import Data.Vector qualified as V
+import Data.Word (Word32, Word64)
+import Language.Haskell.TH
+import Parquet.Nested qualified as PN
+import Parquet.Types qualified as PT
+import Wireform.Derive.Backend (backendParquet)
+import Wireform.Derive.ModifierInfo
+import Wireform.Derive.TypeInfo
+
+
+-- ---------------------------------------------------------------------------
+-- Row classes
+-- ---------------------------------------------------------------------------
+
+{- | Convert a record to a row of optional Parquet leaf values, in
+the same left-to-right order 'parquetSchemaFor' produces leaves.
+Required fields always carry @Just@; @Maybe@ fields use @Nothing@
+to mark a missing value.
+-}
+class ToParquetRow a where
+  toParquetRow :: a -> V.Vector (Maybe PN.LeafValue)
+
+
+{- | Decode a record from a row of optional leaf values. Returns
+'Left' if the leaf count mismatches the schema, a leaf's runtime
+type is wrong, or a 'Nothing' appears in a required column.
+-}
+class FromParquetRow a where
+  fromParquetRow :: V.Vector (Maybe PN.LeafValue) -> Either String a
+
+
+-- ---------------------------------------------------------------------------
+-- Public splice entry points
+-- ---------------------------------------------------------------------------
+
+{- | Splice a @V.Vector "Parquet.Types".SchemaElement@ for the given
+record type. The first element is a synthetic root struct named
+@"schema"@ with @seNumChildren = Just N@; subsequent elements are
+the field leaves, with names, physical types, converted types and
+repetition derived from the record fields and any 'rename' \/
+'coerced' modifiers attached to them.
+-}
+parquetSchemaFor :: Name -> Q Exp
+parquetSchemaFor nm = do
+  ti <- reifyTypeInfo nm
+  case typeInfoShape ti of
+    TypeShapeRecord c -> recordSchemaE c
+    _ ->
+      fail $
+        "Parquet.Derive.parquetSchemaFor: "
+          ++ nameBase nm
+          ++ " must be a single-constructor record"
+
+
+-- | Derive both 'ToParquetRow' and 'FromParquetRow' for a record.
+deriveParquet :: Name -> Q [Dec]
+deriveParquet nm = (++) <$> deriveToParquetRow nm <*> deriveFromParquetRow nm
+
+
+deriveToParquetRow :: Name -> Q [Dec]
+deriveToParquetRow nm = do
+  ti <- reifyTypeInfo nm
+  c <- recordCon nm ti
+  body <- toRowBody c
+  let typ = applyTypeArgs (ConT (typeInfoName ti)) (typeInfoVarTypes ti)
+  pure
+    [ InstanceD
+        Nothing
+        []
+        (AppT (ConT ''ToParquetRow) typ)
+        [FunD 'toParquetRow [Clause [] (NormalB body) []]]
+    ]
+
+
+deriveFromParquetRow :: Name -> Q [Dec]
+deriveFromParquetRow nm = do
+  ti <- reifyTypeInfo nm
+  c <- recordCon nm ti
+  body <- fromRowBody c
+  let typ = applyTypeArgs (ConT (typeInfoName ti)) (typeInfoVarTypes ti)
+  pure
+    [ InstanceD
+        Nothing
+        []
+        (AppT (ConT ''FromParquetRow) typ)
+        [FunD 'fromParquetRow [Clause [] (NormalB body) []]]
+    ]
+
+
+-- ---------------------------------------------------------------------------
+-- Schema construction
+-- ---------------------------------------------------------------------------
+
+recordSchemaE :: ConInfo -> Q Exp
+recordSchemaE c = do
+  let n = length (conInfoFields c)
+      nLit = litE (integerL (fromIntegral n))
+  rootE <-
+    [|
+      PT.SchemaElement
+        { PT.seTypeLength = Nothing
+        , PT.seName = T.pack "schema"
+        , PT.seRepetition = Nothing
+        , PT.seType = Nothing
+        , PT.seNumChildren = Just $nLit
+        , PT.seConvertedType = Nothing
+        , PT.seLogicalType = Nothing
+        , PT.seFieldId = Nothing
+        }
+      |]
+  leafExps <- mapM fieldSchemaE (conInfoFields c)
+  [|V.fromList ($(pure rootE) : $(pure (ListE leafExps)))|]
+
+
+fieldSchemaE :: FieldInfo -> Q Exp
+fieldSchemaE (FieldInfo mSel ty) = do
+  selName <- requireSelector mSel
+  mi <- reifyModifierInfoFor backendParquet selName
+  let selBase = T.pack (nameBase selName)
+  keyExp <- renderWireKey mi selBase
+  let (isOptional, innerTy) = unwrapMaybe ty
+      effectiveTy = case miCoerce mi of
+        Just tgtName -> ConT tgtName
+        Nothing -> innerTy
+  (ptExp, ctExp) <- physicalAndConvertedE selName effectiveTy
+  let repExp =
+        if isOptional
+          then [|Just PT.Optional|]
+          else [|Just PT.Required|]
+  [|
+    PT.SchemaElement
+      { PT.seTypeLength = Nothing
+      , PT.seName = $(pure keyExp)
+      , PT.seRepetition = $repExp
+      , PT.seType = Just $(pure ptExp)
+      , PT.seNumChildren = Nothing
+      , PT.seConvertedType = $(pure ctExp)
+      , PT.seLogicalType = Nothing
+      , PT.seFieldId = Nothing
+      }
+    |]
+
+
+-- | Map a Haskell scalar type to (parquet physical type, converted type).
+physicalAndConvertedE :: Name -> Type -> Q (Exp, Exp)
+physicalAndConvertedE selName ty = case typeBaseName ty of
+  Just "Int32" -> pair [|PT.PTInt32|] [|Nothing|]
+  Just "Int64" -> pair [|PT.PTInt64|] [|Nothing|]
+  Just "Int" -> pair [|PT.PTInt64|] [|Nothing|]
+  Just "Word32" -> pair [|PT.PTInt32|] [|Just PT.CTUInt32|]
+  Just "Word64" -> pair [|PT.PTInt64|] [|Just PT.CTUInt64|]
+  Just "Float" -> pair [|PT.PTFloat|] [|Nothing|]
+  Just "Double" -> pair [|PT.PTDouble|] [|Nothing|]
+  Just "Bool" -> pair [|PT.PTBoolean|] [|Nothing|]
+  Just "Text" -> pair [|PT.PTByteArray|] [|Just PT.CTUtf8|]
+  Just "String" -> pair [|PT.PTByteArray|] [|Just PT.CTUtf8|]
+  Just "ByteString" -> pair [|PT.PTByteArray|] [|Nothing|]
+  _ ->
+    fail $
+      "Parquet.Derive: unsupported field type for "
+        ++ nameBase selName
+        ++ ": "
+        ++ pprint ty
+  where
+    pair p c = (,) <$> p <*> c
+
+
+-- ---------------------------------------------------------------------------
+-- toParquetRow body
+-- ---------------------------------------------------------------------------
+
+toRowBody :: ConInfo -> Q Exp
+toRowBody c = do
+  x <- newName "x"
+  leafExps <- mapM (fieldToLeafE x) (conInfoFields c)
+  lamE [varP x] [|V.fromList $(pure (ListE leafExps))|]
+
+
+fieldToLeafE :: Name -> FieldInfo -> Q Exp
+fieldToLeafE x (FieldInfo mSel ty) = do
+  selName <- requireSelector mSel
+  mi <- reifyModifierInfoFor backendParquet selName
+  let getter = AppE (VarE selName) (VarE x)
+      (isOptional, innerTy) = unwrapMaybe ty
+      effectiveTy = case miCoerce mi of
+        Just tgtName -> ConT tgtName
+        Nothing -> innerTy
+      coercedToInner expr =
+        case miCoerce mi of
+          Just _ -> [|coerce $expr|]
+          Nothing -> expr
+  if isOptional
+    then do
+      v <- newName "y"
+      inner <- coercedToInner (varE v)
+      leaf <- toLeafE selName effectiveTy inner
+      [|
+        case $(pure getter) of
+          Nothing -> Nothing
+          Just $(varP v) -> Just $(pure leaf)
+        |]
+    else do
+      inner <- coercedToInner (pure getter)
+      leaf <- toLeafE selName effectiveTy inner
+      [|Just $(pure leaf)|]
+
+
+{- | Wrap a Haskell value of the given inner type into the matching
+'PN.LeafValue' constructor. Caller must pass the unwrapped value
+(i.e. after any 'coerce').
+-}
+toLeafE :: Name -> Type -> Exp -> Q Exp
+toLeafE selName ty getter = case typeBaseName ty of
+  Just "Int32" -> [|PN.LvInt32 $(pure getter)|]
+  Just "Int64" -> [|PN.LvInt64 $(pure getter)|]
+  Just "Int" -> [|PN.LvInt64 (fromIntegral ($(pure getter) :: Int))|]
+  Just "Word32" -> [|PN.LvInt32 (fromIntegral ($(pure getter) :: Word32))|]
+  Just "Word64" -> [|PN.LvInt64 (fromIntegral ($(pure getter) :: Word64))|]
+  Just "Float" -> [|PN.LvFloat $(pure getter)|]
+  Just "Double" -> [|PN.LvDouble $(pure getter)|]
+  Just "Bool" -> [|PN.LvBool $(pure getter)|]
+  Just "Text" -> [|PN.LvString $(pure getter)|]
+  Just "String" -> [|PN.LvString (T.pack $(pure getter))|]
+  Just "ByteString" -> [|PN.LvBinary $(pure getter)|]
+  _ ->
+    fail $
+      "Parquet.Derive: unsupported row field type for "
+        ++ nameBase selName
+        ++ ": "
+        ++ pprint ty
+
+
+-- ---------------------------------------------------------------------------
+-- fromParquetRow body
+-- ---------------------------------------------------------------------------
+
+fromRowBody :: ConInfo -> Q Exp
+fromRowBody c = do
+  v <- newName "v"
+  let conName = conInfoName c
+      fields = conInfoFields c
+      n = length fields
+      nLit = litE (integerL (fromIntegral n))
+      indexedFs = zip [0 ..] fields
+  parserExps <- mapM (fieldFromLeafE v) indexedFs
+  chainE <- case parserExps of
+    [] -> [|Right $(conE conName)|]
+    (p0 : ps) -> do
+      hd <- [|$(conE conName) <$> $(pure p0)|]
+      foldM (\acc e -> [|$(pure acc) <*> $(pure e)|]) hd ps
+  body <-
+    [|
+      if V.length $(varE v) /= $nLit
+        then
+          Left
+            ( "Parquet.Derive: expected "
+                ++ show ($nLit :: Int)
+                ++ " leaves, got "
+                ++ show (V.length $(varE v))
+            )
+        else $(pure chainE)
+      |]
+  lamE [varP v] (pure body)
+
+
+fieldFromLeafE :: Name -> (Int, FieldInfo) -> Q Exp
+fieldFromLeafE v (idx, FieldInfo mSel ty) = do
+  selName <- requireSelector mSel
+  mi <- reifyModifierInfoFor backendParquet selName
+  let nameStr = nameBase selName
+      idxLit = litE (integerL (fromIntegral idx))
+      leafE = [|V.unsafeIndex $(varE v) $idxLit|]
+      (isOptional, innerTy) = unwrapMaybe ty
+      effectiveTy = case miCoerce mi of
+        Just tgtName -> ConT tgtName
+        Nothing -> innerTy
+      mapBackE expr =
+        case miCoerce mi of
+          Just _ -> [|fmap coerce $expr|]
+          Nothing -> expr
+  if isOptional
+    then do
+      x <- newName "x"
+      decoded <- fromLeafE nameStr effectiveTy (varE x)
+      mapped <- mapBackE [|$(pure decoded)|]
+      [|
+        case $leafE of
+          Nothing -> Right Nothing
+          Just $(varP x) ->
+            case $(pure mapped) of
+              Right val -> Right (Just val)
+              Left err -> Left err
+        |]
+    else do
+      x <- newName "x"
+      decoded <- fromLeafE nameStr effectiveTy (varE x)
+      mapped <- mapBackE [|$(pure decoded)|]
+      [|
+        case $leafE of
+          Nothing ->
+            Left
+              ( "Parquet.Derive: "
+                  ++ nameStr
+                  ++ ": null in required column"
+              )
+          Just $(varP x) -> $(pure mapped)
+        |]
+
+
+{- | Decode a single 'PN.LeafValue' (already unwrapped from 'Just')
+into the given inner Haskell type. Returns @Either String t@.
+-}
+fromLeafE :: String -> Type -> Q Exp -> Q Exp
+fromLeafE nameStr ty leafE = case typeBaseName ty of
+  Just "Int32" ->
+    [|
+      case $leafE of
+        PN.LvInt32 z -> Right z
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvInt32, got "
+                ++ show other
+            )
+      |]
+  Just "Int64" ->
+    [|
+      case $leafE of
+        PN.LvInt64 z -> Right z
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvInt64, got "
+                ++ show other
+            )
+      |]
+  Just "Int" ->
+    [|
+      case $leafE of
+        PN.LvInt64 z -> Right (fromIntegral z :: Int)
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvInt64, got "
+                ++ show other
+            )
+      |]
+  Just "Word32" ->
+    [|
+      case $leafE of
+        PN.LvInt32 z -> Right (fromIntegral z :: Word32)
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvInt32, got "
+                ++ show other
+            )
+      |]
+  Just "Word64" ->
+    [|
+      case $leafE of
+        PN.LvInt64 z -> Right (fromIntegral z :: Word64)
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvInt64, got "
+                ++ show other
+            )
+      |]
+  Just "Float" ->
+    [|
+      case $leafE of
+        PN.LvFloat z -> Right z
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvFloat, got "
+                ++ show other
+            )
+      |]
+  Just "Double" ->
+    [|
+      case $leafE of
+        PN.LvDouble z -> Right z
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvDouble, got "
+                ++ show other
+            )
+      |]
+  Just "Bool" ->
+    [|
+      case $leafE of
+        PN.LvBool z -> Right z
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvBool, got "
+                ++ show other
+            )
+      |]
+  Just "Text" ->
+    [|
+      case $leafE of
+        PN.LvString z -> Right z
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvString, got "
+                ++ show other
+            )
+      |]
+  Just "String" ->
+    [|
+      case $leafE of
+        PN.LvString z -> Right (T.unpack z)
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvString, got "
+                ++ show other
+            )
+      |]
+  Just "ByteString" ->
+    [|
+      case $leafE of
+        PN.LvBinary z -> Right z
+        other ->
+          Left
+            ( "Parquet.Derive: "
+                ++ nameStr
+                ++ ": expected LvBinary, got "
+                ++ show other
+            )
+      |]
+  _ ->
+    fail $
+      "Parquet.Derive: unsupported row field type for "
+        ++ nameStr
+        ++ ": "
+        ++ pprint ty
+
+
+_unused :: (Int32, Int64, Word32, Word64, ByteString)
+_unused = (0, 0, 0, 0, mempty)
+
+
+-- ---------------------------------------------------------------------------
+-- Helpers
+-- ---------------------------------------------------------------------------
+
+unwrapMaybe :: Type -> (Bool, Type)
+unwrapMaybe (AppT (ConT n) t) | n == ''Maybe = (True, t)
+unwrapMaybe t = (False, t)
+
+
+typeBaseName :: Type -> Maybe String
+typeBaseName = \case
+  ConT n -> Just (nameBase n)
+  AppT t _ -> typeBaseName t
+  _ -> Nothing
+
+
+recordCon :: Name -> TypeInfo -> Q ConInfo
+recordCon nm ti = case typeInfoShape ti of
+  TypeShapeRecord c -> pure c
+  _ ->
+    fail $
+      "Parquet.Derive: "
+        ++ nameBase nm
+        ++ " must be a single-constructor record"
+
+
+requireSelector :: Maybe Name -> Q Name
+requireSelector (Just n) = pure n
+requireSelector Nothing =
+  fail "Parquet.Derive: cannot derive Parquet for non-record positional field"
+
+
+applyTypeArgs :: Type -> [Type] -> Type
+applyTypeArgs = foldl AppT
+
+
+foldM :: (a -> b -> Q a) -> a -> [b] -> Q a
+foldM _ acc [] = pure acc
+foldM f acc (x : xs) = do
+  acc' <- f acc x
+  foldM f acc' xs
diff --git a/src/Parquet/Encryption.hs b/src/Parquet/Encryption.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Encryption.hs
@@ -0,0 +1,700 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE PatternSynonyms #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+{- | Apache Parquet modular encryption (parquet-format/Encryption.md).
+
+Implements the spec's two encryption algorithms:
+
+- 'AesGcmV1' (full AES-GCM): every encrypted module - footer, column
+  metadata, column index, offset index, bloom filter, and each page -
+  is encrypted as @nonce(12) || ciphertext || tag(16)@. The data and the
+  AAD are both authenticated, so any tampering with the layout aborts
+  the read.
+
+- 'AesGcmCtrV1' (mixed mode): metadata modules (footer, column metadata,
+  page headers, indexes, bloom filter) use AES-GCM as above; data
+  pages and dictionary pages use AES-CTR for speed (no authentication on
+  the data bytes themselves, only on the encrypted page header).
+
+The 'AAD' (Additional Authenticated Data) for each module is the
+concatenation of:
+
+@
+AAD = aad_prefix || aad_suffix
+aad_suffix = aad_file_id(variable) || module_type(1)
+             || row_group_ordinal(2) || column_ordinal(2)
+             || page_ordinal(2)
+@
+
+not all modules use every suffix component; this module exposes
+'buildAadSuffix' / 'buildAad' helpers that match the spec's wire layout.
+
+The actual key material is supplied by the caller through
+'EncryptionKeys'; this module does not assume a particular KMS. The
+opaque @key_metadata@ bytes that should be stored on the encrypted
+column chunks (and on the Iceberg @data_file.key_metadata@ field) round-
+trip unchanged through 'EncryptionConfig'.
+-}
+module Parquet.Encryption (
+  -- * Algorithms
+  EncryptionAlgorithm (..),
+  ModuleType (..),
+  moduleTypeId,
+
+  -- * AAD construction
+  buildAadSuffix,
+  buildAad,
+
+  -- * Encrypt / decrypt
+  encryptModule,
+  decryptModule,
+  encryptModuleCtr,
+  decryptModuleCtr,
+
+  -- * Explicit nonces (must be freshly generated for every module)
+  encryptGcmModuleWithNonce,
+  encryptCtrModuleWithNonce,
+  decryptGcmModule,
+  decryptCtrModule,
+
+  -- * Wire framing (4-byte length prefix per the spec, section 5.1)
+  encryptGcmModuleFramed,
+  encryptCtrModuleFramed,
+  encryptGcmModuleFramedWithNonce,
+  encryptCtrModuleFramedWithNonce,
+  readFramedModule,
+
+  -- * File footer authentication
+  FooterCryptoMetadata (..),
+  AuthenticatedFooter (..),
+  readFooterCryptoMetadata,
+  authenticateFooter,
+
+  -- * Key configuration
+  EncryptionKeys (..),
+  EncryptionConfig (..),
+  unencrypted,
+) where
+
+import Crypto.Cipher.AES qualified as Crypto
+import Crypto.Cipher.Types (AEADMode (..), BlockCipher, IV)
+import Crypto.Cipher.Types qualified as Cipher
+import Crypto.Error (CryptoFailable (..))
+import Crypto.Random.Types qualified as RNG
+import Data.ByteArray qualified as BA
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int16)
+import Data.Map.Strict (Map)
+import Data.Map.Strict qualified as Map
+import Data.Maybe (fromMaybe)
+import Data.Text (Text)
+import Data.Text.Encoding qualified as TE
+import Data.Vector qualified as V
+import Data.Word (Word32)
+import Parquet.Footer qualified as Footer
+import Parquet.Thrift.Schema
+import Thrift.Decode (decodeCompactFrom)
+import Thrift.Value qualified as TV
+import Wireform.Builder qualified as B
+
+
+{- | Unauthenticated routing information read from the file. The key metadata
+is opaque: callers may resolve it with their own KMS before authenticating.
+Neither this structure nor its AAD fields establish the file's identity
+until 'authenticateFooter' has succeeded.
+-}
+data FooterCryptoMetadata = FooterCryptoMetadata
+  { fcmAlgorithm :: !EncryptionAlgorithm
+  , fcmFileId :: !ByteString
+  , fcmStoredAadPrefix :: !(Maybe ByteString)
+  , fcmSupplyAadPrefix :: !Bool
+  , fcmKeyMetadata :: !(Maybe ByteString)
+  }
+  deriving stock (Show, Eq)
+
+
+{- | The authenticated Thrift footer, retaining its crypto fields for column
+decryption. Ordinary, unsigned files have no crypto metadata.
+-}
+data AuthenticatedFooter = AuthenticatedFooter
+  { afValue :: !TV.Value
+  , afCryptoMetadata :: !(Maybe FooterCryptoMetadata)
+  }
+  deriving stock (Show, Eq)
+
+
+{- | Inspect the untrusted key metadata and AAD description. This does not
+decrypt the footer or verify its signature. A returned file identifier is
+supplied to the cipher, never used as evidence that the file is authentic.
+-}
+readFooterCryptoMetadata :: ByteString -> Either String (Maybe FooterCryptoMetadata)
+readFooterCryptoMetadata bytes = do
+  trailer <- checkedCryptoTrailer bytes
+  if Footer.ftMagic trailer == Footer.parquetEncryptedMagic
+    then do
+      (value, _) <- decodeCompactFrom (Footer.ftBytes trailer) 0
+      Just <$> encryptedFooterMetadata value
+    else do
+      (value, _) <- decodeCompactFrom (Footer.ftBytes trailer) 0
+      plaintextFooterMetadata value
+
+
+{- | Authenticate an encrypted footer or a signed plaintext footer. The
+optional expected prefix is compared with a stored prefix, or supplied
+when the writer omitted it. The optional expected file identifier supports
+callers migrating from the original explicit-AAD reader; normally the
+identifier comes from the file's crypto metadata.
+
+Plaintext footer signatures authenticate the original serialized bytes,
+not a re-encoding of the parsed Thrift value. No column pages are decrypted
+by this function. Unsigned ordinary files remain accepted.
+-}
+authenticateFooter
+  :: ByteString
+  -> Maybe ByteString
+  -> Maybe ByteString
+  -> ByteString
+  -> Either String AuthenticatedFooter
+authenticateFooter key expectedPrefix expectedFileId bytes = do
+  trailer <- checkedCryptoTrailer bytes
+  let footerBytes = Footer.ftBytes trailer
+  if Footer.ftMagic trailer == Footer.parquetEncryptedMagic
+    then do
+      (cryptoValue, encryptedStart) <- decodeCompactFrom footerBytes 0
+      metadata <- encryptedFooterMetadata cryptoValue
+      aad <- footerAad metadata expectedPrefix expectedFileId
+      (ciphertext, afterModule) <- readFramedModule footerBytes encryptedStart
+      requireCrypto (afterModule == BS.length footerBytes) "trailing bytes after encrypted footer"
+      plaintext <- decryptGcmModule key aad ciphertext
+      (value, end) <- decodeCompactFrom plaintext 0
+      -- parquet-mr encrypts a capacity-sized serialization buffer in several
+      -- official fixtures. Its unused tail consists of authenticated zeros.
+      -- Check the complete GCM module first, then permit only that padding.
+      requireCrypto (BS.all (== 0) (BS.drop end plaintext)) "nonzero trailing bytes in decrypted footer"
+      pure (AuthenticatedFooter value (Just metadata))
+    else do
+      (value, end) <- decodeCompactFrom footerBytes 0
+      metadata <- plaintextFooterMetadata value
+      case metadata of
+        Nothing -> do
+          requireCrypto (end == BS.length footerBytes) "trailing bytes after unsigned footer"
+          pure (AuthenticatedFooter value Nothing)
+        Just crypto -> do
+          aad <- footerAad crypto expectedPrefix expectedFileId
+          let signature = BS.drop end footerBytes
+          requireCrypto (BS.length signature == 28) "plaintext footer signature must contain 28 bytes"
+          let nonce = BS.take 12 signature
+          encrypted <- encryptGcmModuleWithNonce key nonce aad (BS.take end footerBytes)
+          requireCrypto (BA.constEq (BS.drop 12 signature) (BS.takeEnd 16 encrypted)) "plaintext footer signature mismatch"
+          pure (AuthenticatedFooter value metadata)
+
+
+checkedCryptoTrailer :: ByteString -> Either String Footer.FooterTrailer
+checkedCryptoTrailer bytes = do
+  trailer <- Footer.readFooterTrailer bytes
+  requireCrypto (BS.take 4 bytes == Footer.ftMagic trailer) "leading and trailing magic differ"
+  requireCrypto (BS.length (Footer.ftBytes trailer) <= BS.length bytes - 12) "footer overlaps leading magic"
+  pure trailer
+
+
+encryptedFooterMetadata :: TV.Value -> Either String FooterCryptoMetadata
+encryptedFooterMetadata value = do
+  fields <- cryptoStruct value
+  algorithm <- requiredCryptoField (FileCryptoMetaData_EncryptionAlgorithm V.empty) fields
+  keyMetadata <- optionalCryptoField (FileCryptoMetaData_KeyMetadata BS.empty) fields >>= traverse cryptoBytes
+  parseFooterAlgorithm keyMetadata algorithm
+
+
+plaintextFooterMetadata :: TV.Value -> Either String (Maybe FooterCryptoMetadata)
+plaintextFooterMetadata value = do
+  fields <- cryptoStruct value
+  algorithm <- optionalCryptoField (FileMetadata_EncryptionAlgorithm V.empty) fields
+  keyMetadata <- optionalCryptoField (FileMetadata_FooterSigningKeyMetadata BS.empty) fields >>= traverse cryptoBytes
+  case algorithm of
+    Nothing -> do
+      requireCrypto (keyMetadata == Nothing) "footer signing key metadata lacks an encryption algorithm"
+      pure Nothing
+    Just description -> Just <$> parseFooterAlgorithm keyMetadata description
+
+
+parseFooterAlgorithm :: Maybe ByteString -> TV.Value -> Either String FooterCryptoMetadata
+parseFooterAlgorithm keyMetadata value = do
+  union <- cryptoStruct value
+  requireCrypto (V.length union == 1) "encryption algorithm must have exactly one variant"
+  (algorithm, description) <- case V.head union of
+    EncryptionAlgorithm_AesGcmV1 fields -> Right (AesGcmV1, TV.Struct fields)
+    EncryptionAlgorithm_AesGcmCtrV1 fields -> Right (AesGcmCtrV1, TV.Struct fields)
+    _ -> Left "Parquet.Encryption: unsupported encryption algorithm"
+  fields <- cryptoStruct description
+  prefix <- optionalCryptoField (AesGcmV1_AadPrefix BS.empty) fields >>= traverse cryptoBytes
+  fileId <- requiredCryptoField (AesGcmV1_AadFileUnique BS.empty) fields >>= cryptoBytes
+  requireCrypto (not (BS.null fileId)) "missing unique file identifier"
+  supplied <-
+    optionalCryptoField (AesGcmV1_SupplyAadPrefix False) fields >>= \case
+      Nothing -> Right False
+      Just (TV.Bool flag) -> Right flag
+      _ -> Left "Parquet.Encryption: supply_aad_prefix must be boolean"
+  requireCrypto (not supplied || prefix == Nothing) "AAD prefix is both stored and required from caller"
+  pure (FooterCryptoMetadata algorithm fileId prefix supplied keyMetadata)
+
+
+footerAad :: FooterCryptoMetadata -> Maybe ByteString -> Maybe ByteString -> Either String ByteString
+footerAad metadata expectedPrefix expectedFileId = do
+  case expectedFileId of
+    Nothing -> pure ()
+    Just expected -> requireCrypto (expected == fcmFileId metadata) "file identifier differs from expected value"
+  prefix <- case fcmStoredAadPrefix metadata of
+    Just stored -> do
+      case expectedPrefix of
+        Nothing -> pure ()
+        Just expected -> requireCrypto (expected == stored) "AAD prefix differs from expected value"
+      pure stored
+    Nothing -> do
+      requireCrypto (not (fcmSupplyAadPrefix metadata) || expectedPrefix /= Nothing) "file requires an AAD prefix from caller"
+      let supplied = fromMaybe BS.empty expectedPrefix
+      requireCrypto (fcmSupplyAadPrefix metadata || BS.null supplied) "file has no AAD prefix"
+      pure supplied
+  pure (buildAad prefix (buildAadSuffix (fcmFileId metadata) ModuleFooter 0 0 0))
+
+
+cryptoStruct :: TV.Value -> Either String (V.Vector (Int16, TV.Value))
+cryptoStruct (TV.Struct fields) = do
+  let unique = V.foldl' (\known (tag, _) -> Map.insert tag () known) Map.empty fields
+  requireCrypto (Map.size unique == V.length fields) "duplicate crypto metadata field"
+  pure fields
+cryptoStruct _ = Left "Parquet.Encryption: expected crypto metadata struct"
+
+
+optionalCryptoField :: (Int16, TV.Value) -> V.Vector (Int16, TV.Value) -> Either String (Maybe TV.Value)
+optionalCryptoField (wanted, _) = pure . fmap snd . V.find ((== wanted) . fst)
+
+
+requiredCryptoField :: (Int16, TV.Value) -> V.Vector (Int16, TV.Value) -> Either String TV.Value
+requiredCryptoField tag fields = optionalCryptoField tag fields >>= maybe (Left "Parquet.Encryption: missing crypto metadata field") Right
+
+
+cryptoBytes :: TV.Value -> Either String ByteString
+cryptoBytes (TV.Binary bytes) = Right bytes
+cryptoBytes (TV.String text) = Right (TE.encodeUtf8 text)
+cryptoBytes _ = Left "Parquet.Encryption: expected binary crypto metadata"
+
+
+requireCrypto :: Bool -> String -> Either String ()
+requireCrypto True _ = Right ()
+requireCrypto False message = Left ("Parquet.Encryption: " ++ message)
+
+
+-- ============================================================
+-- Spec types
+-- ============================================================
+
+data EncryptionAlgorithm = AesGcmV1 | AesGcmCtrV1
+  deriving (Show, Eq)
+
+
+data ModuleType
+  = ModuleFooter
+  | ModuleColumnMetaData
+  | ModuleDataPage
+  | ModuleDictionaryPage
+  | ModuleDataPageHeader
+  | ModuleDictionaryPageHeader
+  | ModuleColumnIndex
+  | ModuleOffsetIndex
+  | ModuleBloomFilterHeader
+  | ModuleBloomFilterBitset
+  deriving (Show, Eq)
+
+
+-- | The byte constant the spec assigns to each module type.
+moduleTypeId :: ModuleType -> Int
+moduleTypeId = \case
+  ModuleFooter -> 0
+  ModuleColumnMetaData -> 1
+  ModuleDataPage -> 2
+  ModuleDictionaryPage -> 3
+  ModuleDataPageHeader -> 4
+  ModuleDictionaryPageHeader -> 5
+  ModuleColumnIndex -> 6
+  ModuleOffsetIndex -> 7
+  ModuleBloomFilterHeader -> 8
+  ModuleBloomFilterBitset -> 9
+
+
+-- ============================================================
+-- AAD framing
+-- ============================================================
+
+buildAadSuffix
+  :: ByteString
+  -- ^ aad_file_unique, preserved verbatim (the format leaves its length to the writer).
+  -> ModuleType
+  -> Int16
+  -- ^ row group ordinal.
+  -> Int16
+  -- ^ column ordinal.
+  -> Int16
+  -- ^ page ordinal.
+  -> ByteString
+buildAadSuffix fileId mt rg col pg
+  | BS.length fileId < 0 || BS.length fileId > maxBound - extra = error "Parquet.Encryption: AAD suffix exceeds addressable size"
+  | otherwise =
+      B.toStrictByteStringExact (BS.length fileId + extra) $
+        B.byteString fileId
+          <> B.word8 (fromIntegral (moduleTypeId mt))
+          <> (if mt == ModuleFooter then mempty else B.int16LE rg <> B.int16LE col)
+          <> ( case mt of
+                 ModuleDataPage -> B.int16LE pg
+                 ModuleDataPageHeader -> B.int16LE pg
+                 _ -> mempty
+             )
+  where
+    extra = case mt of
+      ModuleFooter -> 1
+      ModuleDataPage -> 7
+      ModuleDataPageHeader -> 7
+      _ -> 5
+
+
+buildAad
+  :: ByteString
+  -- ^ aad_prefix (caller-defined; can be empty).
+  -> ByteString
+  -- ^ aad_suffix produced by 'buildAadSuffix'.
+  -> ByteString
+buildAad = (<>)
+
+
+-- ============================================================
+-- AES-GCM
+-- ============================================================
+
+-- | Encrypt a module with AES-GCM. Output: @nonce(12) || ciphertext || tag(16)@.
+encryptModule
+  :: RNG.MonadRandom m
+  => ByteString
+  -- ^ AES key (16, 24, or 32 bytes).
+  -> ByteString
+  -- ^ AAD.
+  -> ByteString
+  -- ^ Plaintext.
+  -> m (Either String ByteString)
+encryptModule key aad plaintext = do
+  nonce <- RNG.getRandomBytes 12 :: RNG.MonadRandom m => m BS.ByteString
+  pure (encryptGcmWithNonce key nonce aad plaintext)
+
+
+decryptModule
+  :: ByteString
+  -- ^ key
+  -> ByteString
+  -- ^ aad
+  -> ByteString
+  -- ^ wire bytes (nonce || ciphertext || tag)
+  -> Either String ByteString
+decryptModule key aad bs = case BS.length bs of
+  n
+    | n < 28 -> Left "Parquet.Encryption: ciphertext too short"
+    | otherwise ->
+        let (nonce, rest) = BS.splitAt 12 bs
+            (ct, tagBs) = BS.splitAt (BS.length rest - 16) rest
+        in withAes
+             key
+             (\(c :: Crypto.AES128) -> gcmDecrypt c nonce aad ct tagBs)
+             (\(c :: Crypto.AES192) -> gcmDecrypt c nonce aad ct tagBs)
+             (\(c :: Crypto.AES256) -> gcmDecrypt c nonce aad ct tagBs)
+
+
+encryptGcmWithNonce :: ByteString -> ByteString -> ByteString -> ByteString -> Either String ByteString
+encryptGcmWithNonce key nonce aad plaintext =
+  withAes
+    key
+    (\(c :: Crypto.AES128) -> gcmEncrypt c nonce aad plaintext)
+    (\(c :: Crypto.AES192) -> gcmEncrypt c nonce aad plaintext)
+    (\(c :: Crypto.AES256) -> gcmEncrypt c nonce aad plaintext)
+
+
+gcmEncrypt :: forall c. BlockCipher c => c -> ByteString -> ByteString -> ByteString -> Either String ByteString
+gcmEncrypt cipher nonce aad plaintext = do
+  -- AES-GCM uses a 12-byte nonce; aeadInit accepts any ByteArrayAccess
+  -- so we pass the nonce bytes directly. The IV-length restriction in
+  -- @makeIV@ doesn't apply to AEAD initialisation.
+  aead0 <- adapt (Cipher.aeadInit AEAD_GCM cipher nonce)
+  let aead1 = Cipher.aeadAppendHeader aead0 aad
+      (ciphertext, aead2) = Cipher.aeadEncrypt aead1 plaintext
+      tag = Cipher.aeadFinalize aead2 16
+  Right $ BS.concat [nonce, ciphertext, BA.convert tag]
+
+
+gcmDecrypt :: forall c. BlockCipher c => c -> ByteString -> ByteString -> ByteString -> ByteString -> Either String ByteString
+gcmDecrypt cipher nonce aad ct tagBs = do
+  aead0 <- adapt (Cipher.aeadInit AEAD_GCM cipher nonce)
+  let aead1 = Cipher.aeadAppendHeader aead0 aad
+      (plaintext, aead2) = Cipher.aeadDecrypt aead1 ct
+      expected = Cipher.aeadFinalize aead2 16
+  if BA.constEq expected tagBs
+    then Right plaintext
+    else Left "Parquet.Encryption: GCM tag mismatch"
+
+
+-- ============================================================
+-- AES-CTR (mixed-mode payload encryption)
+-- ============================================================
+
+{- | Encrypt a module with AES-CTR (no authentication). Wire format:
+@nonce(12) || ciphertext@. Used for data\/dictionary pages in
+'AesGcmCtrV1'.
+-}
+encryptModuleCtr
+  :: RNG.MonadRandom m
+  => ByteString
+  -- ^ key
+  -> ByteString
+  -- ^ plaintext
+  -> m (Either String ByteString)
+encryptModuleCtr key plaintext = do
+  nonce <- RNG.getRandomBytes 12 :: RNG.MonadRandom m => m BS.ByteString
+  pure (ctrEncryptWithNonce key nonce plaintext)
+
+
+decryptModuleCtr :: ByteString -> ByteString -> Either String ByteString
+decryptModuleCtr key bs
+  | BS.length bs < 12 = Left "Parquet.Encryption: CTR ciphertext too short"
+  | otherwise =
+      let (nonce, ct) = BS.splitAt 12 bs
+      in withAes
+           key
+           (\(c :: Crypto.AES128) -> ctrCombine c nonce ct)
+           (\(c :: Crypto.AES192) -> ctrCombine c nonce ct)
+           (\(c :: Crypto.AES256) -> ctrCombine c nonce ct)
+
+
+ctrEncryptWithNonce :: ByteString -> ByteString -> ByteString -> Either String ByteString
+ctrEncryptWithNonce key nonce plaintext =
+  fmap
+    (BS.append nonce)
+    ( withAes
+        key
+        (\(c :: Crypto.AES128) -> ctrCombine c nonce plaintext)
+        (\(c :: Crypto.AES192) -> ctrCombine c nonce plaintext)
+        (\(c :: Crypto.AES256) -> ctrCombine c nonce plaintext)
+    )
+
+
+ctrCombine :: forall c. BlockCipher c => c -> ByteString -> ByteString -> Either String ByteString
+ctrCombine cipher nonce buf = do
+  -- Per Parquet spec: the 16-byte AES-CTR IV is the 12-byte module nonce
+  -- followed by the big-endian initial counter 1 (Encryption.md §4.2.2).
+  iv <- mkIVFor cipher (BS.append nonce (BS.pack [0, 0, 0, 1]))
+  Right (Cipher.ctrCombine cipher iv buf)
+
+
+-- ============================================================
+-- Key configuration
+-- ============================================================
+
+data EncryptionKeys = EncryptionKeys
+  { ekFooterKey :: !ByteString
+  , ekColumnKeys :: !(Map Text ByteString)
+  }
+  deriving (Show, Eq)
+
+
+data EncryptionConfig = EncryptionConfig
+  { encAlgorithm :: !EncryptionAlgorithm
+  , encKeys :: !EncryptionKeys
+  , encAadFileId :: !ByteString
+  , encAadPrefix :: !ByteString
+  , encKeyMetadata :: !ByteString
+  }
+  deriving (Show, Eq)
+
+
+unencrypted :: EncryptionConfig
+unencrypted =
+  EncryptionConfig
+    { encAlgorithm = AesGcmV1
+    , encKeys = EncryptionKeys BS.empty Map.empty
+    , encAadFileId = BS.empty
+    , encAadPrefix = BS.empty
+    , encKeyMetadata = BS.empty
+    }
+
+
+-- ============================================================
+-- Explicit nonce primitives
+-- ============================================================
+
+{- | Encrypt one GCM module. The caller must supply a fresh, random
+12-byte nonce for every invocation with a given key. Prefer
+'encryptModule', which obtains that nonce from 'RNG.MonadRandom'.
+-}
+encryptGcmModuleWithNonce
+  :: ByteString -> ByteString -> ByteString -> ByteString -> Either String ByteString
+encryptGcmModuleWithNonce key nonce aad plaintext
+  | BS.length nonce /= 12 = Left "Parquet.Encryption: nonce must contain 12 bytes"
+  | otherwise = encryptGcmWithNonce key nonce aad plaintext
+
+
+{- | Explicit-nonce CTR counterpart of 'encryptModuleCtr'. The nonce
+must be fresh, random, and exactly 12 bytes. CTR does not authenticate.
+-}
+encryptCtrModuleWithNonce
+  :: ByteString -> ByteString -> ByteString -> Either String ByteString
+encryptCtrModuleWithNonce key nonce plaintext
+  | BS.length nonce /= 12 = Left "Parquet.Encryption: nonce must contain 12 bytes"
+  | otherwise = ctrEncryptWithNonce key nonce plaintext
+
+
+{- | Decrypt an @nonce || ciphertext || tag@ blob. Same as
+'decryptModule' but exported under a name that pairs nicely with
+'encryptGcmModuleWithNonce'.
+-}
+decryptGcmModule :: ByteString -> ByteString -> ByteString -> Either String ByteString
+decryptGcmModule = decryptModule
+
+
+-- | Decrypt an @nonce || ciphertext@ blob.
+decryptCtrModule :: ByteString -> ByteString -> Either String ByteString
+decryptCtrModule = decryptModuleCtr
+
+
+-- ============================================================
+-- Spec-compliant wire framing (length-prefixed)
+-- ============================================================
+--
+-- Per parquet-format Encryption.md §5.1, every encrypted module on
+-- the wire has a 4-byte little-endian length prefix giving the
+-- length of the @nonce || ct || (tag)@ blob. The previous helpers
+-- emit the raw blob; the *Framed wrappers add the length prefix so
+-- the writer stays byte-compatible with parquet-mr / arrow-rs.
+
+-- | Encrypt a module using a fresh random nonce and the section 5.1 framing.
+encryptGcmModuleFramed
+  :: RNG.MonadRandom m
+  => ByteString -> ByteString -> ByteString -> m (Either String ByteString)
+encryptGcmModuleFramed key aad plain = case checkFramedPlainSize 28 plain of
+  Left err -> pure (Left err)
+  Right () -> fmap frameModule <$> encryptModule key aad plain
+
+
+-- | CTR counterpart of 'encryptGcmModuleFramed'.
+encryptCtrModuleFramed
+  :: RNG.MonadRandom m
+  => ByteString -> ByteString -> m (Either String ByteString)
+encryptCtrModuleFramed key plain = case checkFramedPlainSize 12 plain of
+  Left err -> pure (Left err)
+  Right () -> fmap frameModule <$> encryptModuleCtr key plain
+
+
+-- | Frame a GCM module encrypted with an explicitly supplied fresh nonce.
+encryptGcmModuleFramedWithNonce
+  :: ByteString -> ByteString -> ByteString -> ByteString -> Either String ByteString
+encryptGcmModuleFramedWithNonce key nonce aad plain = do
+  checkFramedPlainSize 28 plain
+  frameModule <$> encryptGcmModuleWithNonce key nonce aad plain
+
+
+-- | Frame a CTR module encrypted with an explicitly supplied fresh nonce.
+encryptCtrModuleFramedWithNonce
+  :: ByteString -> ByteString -> ByteString -> Either String ByteString
+encryptCtrModuleFramedWithNonce key nonce plain = do
+  checkFramedPlainSize 12 plain
+  frameModule <$> encryptCtrModuleWithNonce key nonce plain
+
+
+{- | Read one length-prefixed encrypted module from @bs@ starting at
+@off@. Returns the raw module bytes (nonce || ct || (tag)) plus
+the byte offset just past the module. Caller decrypts via
+'decryptGcmModule' / 'decryptCtrModule'.
+-}
+readFramedModule :: ByteString -> Int -> Either String (ByteString, Int)
+readFramedModule bs off
+  | off < 0 || off > BS.length bs - 4 =
+      Left "Parquet.Encryption: short buffer reading framed module length"
+  | otherwise =
+      let !len = readLE32 bs off
+      in if len > BS.length bs - off - 4
+           then Left "Parquet.Encryption: framed module runs past end of buffer"
+           else Right (BS.take len (BS.drop (off + 4) bs), off + 4 + len)
+
+
+-- | Prepend a 4-byte little-endian length to the module bytes.
+frameModule :: ByteString -> ByteString
+frameModule bs
+  | toInteger len > min (toInteger (maxBound :: Word32)) (toInteger (maxBound :: Int) - 4) || len < 0 = error "Parquet.Encryption: encrypted module exceeds framing limit"
+  | otherwise =
+      B.toStrictByteStringExact (len + 4) $
+        B.word32LE (fromIntegral len)
+          <> B.byteString bs
+  where
+    !len = BS.length bs
+
+
+-- Reject before random generation, cipher allocation or a payload read.
+-- The prefix counts nonce/ciphertext/tag; the complete buffer also needs
+-- four bytes for that prefix and must fit the host address space.
+checkFramedPlainSize :: Int -> ByteString -> Either String ()
+checkFramedPlainSize overhead plain =
+  let size = toInteger (BS.length plain)
+      limit = min (toInteger (maxBound :: Word32) - toInteger overhead) (toInteger (maxBound :: Int) - toInteger overhead - 4)
+  in if size < 0 || size > limit
+       then Left "Parquet.Encryption: encrypted module exceeds framing limit"
+       else Right ()
+
+
+-- | Read a 32-bit little-endian length from @bs@ at @off@.
+readLE32 :: ByteString -> Int -> Int
+readLE32 bs off =
+  let !b0 = fromIntegral (BS.index bs off) :: Int
+      !b1 = fromIntegral (BS.index bs (off + 1)) :: Int
+      !b2 = fromIntegral (BS.index bs (off + 2)) :: Int
+      !b3 = fromIntegral (BS.index bs (off + 3)) :: Int
+  in b0 + b1 * 256 + b2 * 65536 + b3 * 16777216
+
+
+-- ============================================================
+-- Internals
+-- ============================================================
+
+{- | Dispatch on key length to one of the three concrete AES variants.
+The three branches exist because @crypton@ uses different types for
+AES-128 / 192 / 256 to encode key sizes statically; the call-site
+continues with whichever branch was selected.
+-}
+withAes
+  :: ByteString
+  -> (Crypto.AES128 -> Either String r)
+  -> (Crypto.AES192 -> Either String r)
+  -> (Crypto.AES256 -> Either String r)
+  -> Either String r
+withAes key k128 k192 k256 = case BS.length key of
+  16 -> case Cipher.cipherInit key :: CryptoFailable Crypto.AES128 of
+    CryptoPassed c -> k128 c
+    CryptoFailed e -> Left ("Parquet.Encryption: AES128 init: " ++ show e)
+  24 -> case Cipher.cipherInit key :: CryptoFailable Crypto.AES192 of
+    CryptoPassed c -> k192 c
+    CryptoFailed e -> Left ("Parquet.Encryption: AES192 init: " ++ show e)
+  32 -> case Cipher.cipherInit key :: CryptoFailable Crypto.AES256 of
+    CryptoPassed c -> k256 c
+    CryptoFailed e -> Left ("Parquet.Encryption: AES256 init: " ++ show e)
+  n -> Left ("Parquet.Encryption: unsupported key length " ++ show n)
+
+
+{- | Construct an IV whose phantom cipher type matches the supplied cipher.
+Forces the @IV@'s polymorphic block size to the concrete one that
+'aeadInit' / 'ctrCombine' expect later.
+-}
+mkIVFor :: forall c. BlockCipher c => c -> ByteString -> Either String (IV c)
+mkIVFor _ bs = case Cipher.makeIV bs of
+  Just v -> Right v
+  Nothing -> Left "Parquet.Encryption: invalid IV length"
+
+
+adapt :: CryptoFailable a -> Either String a
+adapt (CryptoPassed a) = Right a
+adapt (CryptoFailed e) = Left ("Parquet.Encryption: " ++ show e)
diff --git a/src/Parquet/File.hs b/src/Parquet/File.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/File.hs
@@ -0,0 +1,439 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | The Parquet @FILE@ logical type. References retain the original strings
+and distinguish absent values from empty inline bytes. Resolution here is a
+pure description of the bytes to retrieve: it does not fetch URIs, interpret
+relative paths, or verify checksums. Applications select their own transport,
+URI policy and integrity checks. A URI always names an external object, even
+when it names the Parquet file being read.
+-}
+module Parquet.File (
+  FileField (..),
+  FileFieldSpec (..),
+  FileSchema,
+  mkFileSchema,
+  fileSchemaFields,
+  fileSchemaFieldId,
+  withFileSchemaFieldId,
+  fileFieldName,
+  fileSchemaElements,
+  parseFileSchema,
+  FileReference (..),
+  emptyFileReference,
+  validateFileReference,
+  validateFileReferenceForSchema,
+  FileLocation,
+  fileLocationUri,
+  fileLocationOffset,
+  fileLocationSize,
+  fileLocationEnd,
+  FileSource (..),
+  FileResolution (..),
+  FileChecksum (..),
+  FileDigestAlgorithm (..),
+  parseFileChecksum,
+  resolveFileReference,
+  FileReader,
+  compileFileReader,
+  fileReferenceAt,
+  fileReferenceAt#,
+) where
+
+import Arrow.Column qualified as A
+import Control.Monad (unless, when)
+import Data.Bits (bit, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int32, Int64)
+import Data.Maybe (isJust)
+import Data.Text (Text)
+import Data.Text qualified as T
+import Data.Vector qualified as V
+import Data.Word (Word64, Word8)
+import GHC.Exts (Int (I#), Int#)
+import Parquet.Types
+
+
+data FileField = FileUri | FileOffset | FileSize | FileContentType | FileChecksumField | FileInline
+  deriving (Eq, Ord, Show, Enum, Bounded)
+
+
+data FileFieldSpec = FileFieldSpec
+  { fileField :: !FileField
+  , fileFieldId :: !(Maybe Int32)
+  }
+  deriving (Eq, Show)
+
+
+{- | Validated, ordered fields. The cached mask avoids scanning the schema
+for every row. An empty schema has no physical leaves and no valid non-null
+references; null values are recovered from their containing row counts.
+-}
+data FileSchema = FileSchema !(V.Vector FileFieldSpec) {-# UNPACK #-} !Word8 !(Maybe Int32)
+  deriving (Eq, Show)
+
+
+mkFileSchema :: V.Vector FileFieldSpec -> Either String FileSchema
+mkFileSchema fields = (\mask -> FileSchema fields mask Nothing) <$> V.foldM add 0 fields
+  where
+    add !mask field =
+      let !flag = fieldBit (fileField field)
+      in if mask .&. flag /= 0
+           then Left "Parquet.File: duplicate FILE field"
+           else Right (mask .|. flag)
+
+
+fileSchemaFields :: FileSchema -> V.Vector FileFieldSpec
+fileSchemaFields (FileSchema fields _ _) = fields
+
+
+fileSchemaFieldId :: FileSchema -> Maybe Int32
+fileSchemaFieldId (FileSchema _ _ ident) = ident
+
+
+-- | Set the ID of the FILE group itself, independently of its child IDs.
+withFileSchemaFieldId :: Maybe Int32 -> FileSchema -> FileSchema
+withFileSchemaFieldId ident (FileSchema fields mask _) = FileSchema fields mask ident
+
+
+fieldBit :: FileField -> Word8
+fieldBit = bit . fromEnum
+{-# INLINE fieldBit #-}
+
+
+fileFieldName :: FileField -> Text
+fileFieldName = \case
+  FileUri -> "uri"
+  FileOffset -> "offset"
+  FileSize -> "size"
+  FileContentType -> "content_type"
+  FileChecksumField -> "checksum"
+  FileInline -> "inline"
+
+
+{- | Direct children, in schema order; the annotated group itself is emitted
+by the enclosing writer. Every child is OPTIONAL, including locator fields.
+-}
+fileSchemaElements :: FileSchema -> V.Vector SchemaElement
+fileSchemaElements = V.map element . fileSchemaFields
+  where
+    element spec =
+      let field = fileField spec
+          string = field == FileUri || field == FileContentType || field == FileChecksumField
+          physical = if field == FileOffset || field == FileSize then PTInt64 else PTByteArray
+      in SchemaElement
+           { seName = fileFieldName field
+           , seRepetition = Just Optional
+           , seType = Just physical
+           , seNumChildren = Nothing
+           , seConvertedType = if string then Just CTUtf8 else Nothing
+           , seLogicalType = if string then Just LTString else Nothing
+           , seFieldId = fileFieldId spec
+           , seTypeLength = Nothing
+           }
+
+
+{- | Validate a FILE group and its direct children. Names are case sensitive;
+order and field IDs are preserved. Additional application metadata belongs
+beside the FILE group, rather than inside it.
+-}
+parseFileSchema :: SchemaElement -> V.Vector SchemaElement -> Either String FileSchema
+parseFileSchema group children = do
+  unless
+    ( seLogicalType group == Just LTFile
+        && seType group == Nothing
+        && seNumChildren group == Just (fromIntegral (V.length children))
+        && seConvertedType group == Nothing
+        && seTypeLength group == Nothing
+    )
+    (Left "Parquet.File: expected a FILE-annotated group")
+  fields <- V.mapM child children
+  withFileSchemaFieldId (seFieldId group) <$> mkFileSchema fields
+  where
+    child element = do
+      kind <- case seName element of
+        "uri" -> Right FileUri
+        "offset" -> Right FileOffset
+        "size" -> Right FileSize
+        "content_type" -> Right FileContentType
+        "checksum" -> Right FileChecksumField
+        "inline" -> Right FileInline
+        _ -> Left "Parquet.File: unknown FILE field (names are case sensitive)"
+      let primitive = seNumChildren element == Nothing && seTypeLength element == Nothing
+          plain = seLogicalType element == Nothing && seConvertedType element == Nothing
+          string = case seLogicalType element of
+            Just LTString -> seConvertedType element `elem` [Nothing, Just CTUtf8]
+            Nothing -> seConvertedType element == Just CTUtf8
+            _ -> False
+          signed = case seLogicalType element of
+            Just (LTInteger 64 True) -> seConvertedType element `elem` [Nothing, Just CTInt64]
+            Nothing -> seConvertedType element `elem` [Nothing, Just CTInt64]
+            _ -> False
+          typeMatches = case kind of
+            FileOffset -> seType element == Just PTInt64 && signed
+            FileSize -> seType element == Just PTInt64 && signed
+            FileInline -> seType element == Just PTByteArray && plain
+            _ -> seType element == Just PTByteArray && string
+      unless
+        (primitive && seRepetition element == Just Optional && typeMatches)
+        (Left "Parquet.File: FILE children must be OPTIONAL primitives with the specified types")
+      Right (FileFieldSpec kind (seFieldId element))
+
+
+data FileReference = FileReference
+  { fileUri :: !(Maybe Text)
+  , fileOffset :: !(Maybe Int64)
+  , fileSize :: !(Maybe Int64)
+  , fileContentType :: !(Maybe Text)
+  , fileChecksum :: !(Maybe Text)
+  , fileInline :: !(Maybe ByteString)
+  }
+  deriving (Eq, Show)
+
+
+emptyFileReference :: FileReference
+emptyFileReference = FileReference Nothing Nothing Nothing Nothing Nothing Nothing
+
+
+{- | A validated external range. Offset and size are stored unsigned so even
+@maxBound :: Int64@ plus @maxBound :: Int64@ has an exact exclusive end.
+-}
+data FileLocation = FileLocation
+  { fileLocationUri :: !Text
+  , fileLocationOffset :: {-# UNPACK #-} !Word64
+  , fileLocationSize :: !(Maybe Word64)
+  }
+  deriving (Eq, Show)
+
+
+fileLocationEnd :: FileLocation -> Maybe Word64
+fileLocationEnd location = (fileLocationOffset location +) <$> fileLocationSize location
+
+
+data FileSource = InlineBytes !ByteString | ExternalBytes !FileLocation
+  deriving (Eq, Show)
+
+
+data FileDigestAlgorithm = FileMD5 | FileCRC32 | FileCRC32C | FileSHA256
+  deriving (Eq, Show)
+
+
+{- | Parsed integrity metadata, not proof of verification. ETAG applies to the
+whole external object; digests apply to the resolved range/inline bytes.
+-}
+data FileChecksum = FileETag !Text | FileDigest !FileDigestAlgorithm !Text
+  deriving (Eq, Show)
+
+
+data FileResolution = FileResolution
+  { filePreferredSource :: !FileSource
+  , fileExternalLocation :: !(Maybe FileLocation)
+  , fileMediaType :: !Text
+  , fileIntegrityToken :: !(Maybe FileChecksum)
+  }
+  deriving (Eq, Show)
+
+
+nonempty :: Maybe Text -> Maybe Text
+nonempty (Just value) | not (T.null value) = Just value
+nonempty _ = Nothing
+{-# INLINE nonempty #-}
+
+
+{- | Unknown algorithms are ignored, as required by the FILE specification.
+Known digest algorithms require their exact lowercase hexadecimal encoding.
+-}
+parseFileChecksum :: Maybe Text -> Either String (Maybe FileChecksum)
+parseFileChecksum value = case nonempty value of
+  Nothing -> Right Nothing
+  Just token ->
+    let (algorithm, colonDigest) = T.breakOn ":" token
+        digest = T.drop 1 colonDigest
+        hex count kind
+          | T.length digest == count && T.all lowerHex digest = Right (Just (FileDigest kind digest))
+          | otherwise = Left "Parquet.File: malformed known checksum digest"
+    in if T.null colonDigest || T.null algorithm
+         then Left "Parquet.File: checksum must have algorithm:digest form"
+         else case algorithm of
+           "ETAG" -> Right (Just (FileETag digest))
+           "MD5" -> hex 32 FileMD5
+           "CRC32" -> hex 8 FileCRC32
+           "CRC32C" -> hex 8 FileCRC32C
+           "SHA-256" -> hex 64 FileSHA256
+           _ -> Right Nothing
+  where
+    lowerHex c = (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f')
+
+
+{- | Validate source/locator relationships. In particular, a present zero offset
+still requires both URI and size. Empty inline bytes are a valid source.
+-}
+validateFileReference :: FileReference -> Either String ()
+validateFileReference reference = do
+  validateFileSources reference
+  _ <- parseFileChecksum (fileChecksum reference)
+  Right ()
+{-# INLINE validateFileReference #-}
+
+
+validateFileSources :: FileReference -> Either String ()
+validateFileSources reference = do
+  let uri = isJust (nonempty (fileUri reference))
+      offset = fileOffset reference
+      size = fileSize reference
+  when
+    (maybe False (< 0) offset || maybe False (< 0) size)
+    (Left "Parquet.File: negative offset or size")
+  when
+    (isJust offset && (not uri || not (isJust size)))
+    (Left "Parquet.File: offset requires URI and size")
+  when
+    (isJust size && not uri)
+    (Left "Parquet.File: size requires URI")
+  unless
+    (uri || isJust (fileInline reference))
+    (Left "Parquet.File: reference has neither inline bytes nor URI")
+  Right ()
+{-# INLINE validateFileSources #-}
+
+
+{- | Reject values that would lose a present field when written using a subset
+schema. This tests raw presence, so @Just ""@ is preserved rather than dropped.
+-}
+validateFileReferenceForSchema :: FileSchema -> FileReference -> Either String ()
+validateFileReferenceForSchema (FileSchema _ mask _) reference = do
+  let present field value = if isJust value then fieldBit field else 0
+      used =
+        present FileUri (fileUri reference)
+          .|. present FileOffset (fileOffset reference)
+          .|. present FileSize (fileSize reference)
+          .|. present FileContentType (fileContentType reference)
+          .|. present FileChecksumField (fileChecksum reference)
+          .|. present FileInline (fileInline reference)
+  unless (used .&. mask == used) (Left "Parquet.File: value contains a field omitted by its schema")
+  validateFileReference reference
+  -- Readers may choose either source without comparing them. A producer can
+  -- nevertheless reject this locally provable disagreement without fetching.
+  case (fileInline reference, fileSize reference) of
+    (Just bytes, Just size) ->
+      unless
+        (fromIntegral (BS.length bytes) == size)
+        (Left "Parquet.File: inline byte length disagrees with locator size")
+    _ -> Right ()
+{-# INLINE validateFileReferenceForSchema #-}
+
+
+{- | Choose inline bytes when available, while retaining a valid external
+alternative. Locator offset/size never slice the inline bytes.
+-}
+resolveFileReference :: FileReference -> Either String FileResolution
+resolveFileReference reference = do
+  validateFileSources reference
+  integrity <- parseFileChecksum (fileChecksum reference)
+  let location = (\uri -> FileLocation uri (maybe 0 fromIntegral (fileOffset reference)) (fromIntegral <$> fileSize reference)) <$> nonempty (fileUri reference)
+  source <- case fileInline reference of
+    Just bytes -> Right (InlineBytes bytes)
+    Nothing -> maybe (Left "Parquet.File: missing source") (Right . ExternalBytes) location
+  Right (FileResolution source location (maybe "application/octet-stream" id (nonempty (fileContentType reference))) integrity)
+
+
+data TextColumn = TextColumn32 !(A.Utf8Array Int32) | TextColumn64 !(A.Utf8Array Int64) | TextColumnView !A.ColumnArray
+
+
+data BinaryColumn = BinaryColumn32 !(A.BytesArray Int32) | BinaryColumn64 !(A.BytesArray Int64) | BinaryColumnView !A.ColumnArray
+
+
+-- | Cached, named column views. Compile once per row group, not once per row.
+data FileReader = FileReader
+  { readerLength :: {-# UNPACK #-} !Int
+  , readerValidity :: !(Maybe A.Validity)
+  , readerUri :: !(Maybe TextColumn)
+  , readerOffset :: !(Maybe (A.PrimArray Int64))
+  , readerSize :: !(Maybe (A.PrimArray Int64))
+  , readerContentType :: !(Maybe TextColumn)
+  , readerChecksum :: !(Maybe TextColumn)
+  , readerInline :: !(Maybe BinaryColumn)
+  }
+
+
+compileFileReader :: FileSchema -> A.ColumnArray -> Either String FileReader
+compileFileReader schema column = case column of
+  A.ColStruct n valid children -> do
+    let specs = fileSchemaFields schema
+        find field = snd <$> V.find ((== fileFieldName field) . fst) children
+        expected name = V.any ((== name) . fileFieldName . fileField) specs
+    unless
+      ( V.length specs == V.length children
+          && V.all (expected . fst) children
+          && V.all (\spec -> V.length (V.filter ((== fileFieldName (fileField spec)) . fst) children) == 1) specs
+      )
+      (Left "Parquet.File: column fields do not match FILE schema")
+    unless
+      (V.all ((>= n) . A.columnLength . snd) children)
+      (Left "Parquet.File: child column shorter than FILE group")
+    uri <- traverse textColumn (find FileUri)
+    offset <- traverse intColumn (find FileOffset)
+    size <- traverse intColumn (find FileSize)
+    content <- traverse textColumn (find FileContentType)
+    checksum <- traverse textColumn (find FileChecksumField)
+    inline <- traverse binaryColumn (find FileInline)
+    Right (FileReader n valid uri offset size content checksum inline)
+  _ -> Left "Parquet.File: expected a struct column"
+  where
+    textColumn value = case value of
+      A.ColUtf8View {} -> Right (TextColumnView value)
+      _ -> case A.asUtf8 value of
+        Just array -> Right (TextColumn32 array)
+        Nothing -> maybe (Left "Parquet.File: expected STRING column") (Right . TextColumn64) (A.asLargeUtf8 value)
+    intColumn value = case value of
+      A.ColInt64 valid values -> Right (A.PrimArray valid values)
+      _ -> Left "Parquet.File: expected INT64 column"
+    binaryColumn value = case value of
+      A.ColBinary {} -> maybe (Left "Parquet.File: invalid BYTE_ARRAY column") (Right . BinaryColumn32) (A.asBinary value)
+      A.ColLargeBinary {} -> maybe (Left "Parquet.File: invalid BYTE_ARRAY column") (Right . BinaryColumn64) (A.asLargeBinary value)
+      A.ColBinaryView {} -> Right (BinaryColumnView value)
+      _ -> Left "Parquet.File: expected BYTE_ARRAY column"
+
+
+{- | Read a raw reference; invalid resolution metadata remains inspectable.
+Call 'resolveFileReference' to validate it, or map its error to null as the
+FILE specification permits. The containing struct's validity takes priority
+over arbitrary values in its children beneath a null row.
+-}
+fileReferenceAt :: FileReader -> Int -> Either String (Maybe FileReference)
+fileReferenceAt reader (I# index) = case fileReferenceAt# reader index of
+  (# message | | #) -> Left message
+  (# | reference | #) -> Right (Just reference)
+  (# | | () #) -> Right Nothing
+
+
+{- | The row-loop worker: error, present reference, or null. Avoids intermediate
+boxed Either/Maybe results when composing with a nested encoder.
+-}
+fileReferenceAt# :: FileReader -> Int# -> (# String | FileReference | () #)
+fileReferenceAt# reader index#
+  | index < 0 || index >= readerLength reader = (# "Parquet.File: row index out of range" | | #)
+  | not (A.isValidAt (readerValidity reader) index) = (# | | () #)
+  | otherwise =
+      let !reference =
+            FileReference
+              (readerUri reader >>= textAt)
+              (readerOffset reader >>= (`A.primAt` index))
+              (readerSize reader >>= (`A.primAt` index))
+              (readerContentType reader >>= textAt)
+              (readerChecksum reader >>= textAt)
+              (readerInline reader >>= bytesAt)
+      in (# | reference | #)
+  where
+    index = I# index#
+    textAt (TextColumn32 array) = A.textAt array index
+    textAt (TextColumn64 array) = A.textAt array index
+    textAt (TextColumnView column) = A.anyTextAt column index
+    bytesAt (BinaryColumn32 array) = A.bytesAt array index
+    bytesAt (BinaryColumn64 array) = A.bytesAt array index
+    bytesAt (BinaryColumnView column) = A.anyBytesAt column index
diff --git a/src/Parquet/Footer.hs b/src/Parquet/Footer.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Footer.hs
@@ -0,0 +1,1021 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE PatternSynonyms #-}
+
+{- | Read/write Apache Parquet file footer.
+
+Parquet file layout ends with:
+  [Thrift Compact Protocol encoded FileMetadata] [4-byte LE metadata length] [PAR1 magic]
+
+We use the existing Thrift Compact Protocol encoder/decoder to serialize
+the FileMetadata as a Thrift struct. Struct-field placement is mediated
+by the bidirectional pattern synonyms in "Parquet.Thrift.Schema" so
+that field numbers live in one spec-tracking module; writers and
+readers reference the fields by name.
+-}
+module Parquet.Footer (
+  readFooter,
+  readFooterRaw,
+  writeFooter,
+  writeFooterEither,
+  writeRawFooter,
+  writeRawFooterEither,
+  fileMetadataToThrift,
+  thriftToFileMetadata,
+  thriftToColumnMetadata,
+  thriftToColumnChunk,
+  sanitizeColumnOrders,
+  parquetMagic,
+  parquetEncryptedMagic,
+
+  -- * Trailer parsing
+  FooterTrailer (..),
+  readFooterTrailer,
+) where
+
+import Data.Bits (shiftL, (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Int (Int16, Int32)
+import Data.Text qualified as T
+import Data.Text.Encoding qualified
+import Data.Vector qualified as V
+import Data.Word (Word32)
+import Parquet.Thrift.Schema
+import Parquet.Types
+import Thrift.Decode (decodeCompact)
+import Thrift.Encode (encodeCompactBounded)
+import Thrift.Value qualified as TV
+import Wireform.Builder qualified as B
+import Parquet.Decimal (decimalPrecisionFits)
+
+
+parquetMagic :: ByteString
+parquetMagic = BS.pack [0x50, 0x41, 0x52, 0x31]
+
+
+{- | The trailing magic for an encrypted-footer Parquet file: @PARE@.
+Replaces 'parquetMagic' in the encrypted-footer mode so a reader
+can distinguish a file whose footer is itself an AES-GCM module
+from a plaintext-footer file whose columns happen to be encrypted.
+-}
+parquetEncryptedMagic :: ByteString
+parquetEncryptedMagic = BS.pack [0x50, 0x41, 0x52, 0x45]
+
+
+writeFooter :: FileMetadata -> ByteString
+writeFooter = either error id . writeFooterEither
+
+
+-- | Serialize metadata and check its footer length/trailer bounds.
+writeFooterEither :: FileMetadata -> Either String ByteString
+writeFooterEither fm = do
+  let !thriftVal = fileMetadataToThrift fm
+      !limit = fromInteger (min (toInteger (maxBound :: Word32)) (toInteger (maxBound :: Int) - 8))
+  encoded <- encodeCompactBounded limit thriftVal
+  writeRawFooterEither parquetMagic encoded
+
+
+{- | Build a footer trailer from already-encoded thrift bytes plus a
+magic number. Encrypted-footer mode passes 'parquetEncryptedMagic'
+and the GCM-encrypted thrift bytes; plaintext-footer mode passes
+'parquetMagic' and the raw thrift.
+-}
+writeRawFooter :: ByteString -> ByteString -> ByteString
+writeRawFooter magic = either error id . writeRawFooterEither magic
+
+
+{- | Check the four-byte footer length before narrowing it or copying the
+already encoded metadata. The magic must occupy four bytes; its contents
+remain caller-selected (normally PAR1 or PARE). Logical metadata validation
+belongs to the higher-level writer, not this raw framing helper.
+-}
+writeRawFooterEither :: ByteString -> ByteString -> Either String ByteString
+writeRawFooterEither magic encoded
+  | BS.length magic /= 4 = Left "Parquet.Footer: trailer magic must contain four bytes"
+  | metaLen < 0 || toInteger metaLen > toInteger (maxBound :: Word32) = Left "Parquet.Footer: metadata length exceeds unsigned 32-bit footer limit"
+  | metaLen > maxBound - 8 = Left "Parquet.Footer: footer trailer exceeds addressable byte size"
+  | otherwise =
+      Right $
+        B.toStrictByteStringWith (metaLen + 8) $
+          B.byteString encoded
+            <> B.word32LE (fromIntegral metaLen)
+            <> B.byteString magic
+  where
+    !metaLen = BS.length encoded
+
+
+{- | The bytes the footer trailer points at, plus which magic ended
+the file. For a plaintext-footer file (@PAR1@) the bytes are the
+compact-encoded 'FileMetadata' thrift; for an encrypted-footer
+file (@PARE@) they are the AES-GCM module the caller must
+decrypt before parsing the same thrift.
+-}
+data FooterTrailer = FooterTrailer
+  { ftMagic :: !ByteString
+  -- ^ Either 'parquetMagic' or 'parquetEncryptedMagic'.
+  , ftBytes :: !ByteString
+  {- ^ Footer bytes (raw thrift for plaintext, GCM module for
+    encrypted).
+  -}
+  }
+  deriving (Show, Eq)
+
+
+{- | Parse the trailing 8 bytes (length + magic) and slice out the
+footer module bytes. Doesn't decode them - that's the caller's
+decision based on which magic appeared.
+-}
+readFooterTrailer :: ByteString -> Either String FooterTrailer
+readFooterTrailer bs
+  | BS.length bs < 8 = Left "Parquet.Footer: input too short"
+  | otherwise =
+      let !totalLen = BS.length bs
+          !magic = BSU.unsafeTake 4 (BSU.unsafeDrop (totalLen - 4) bs)
+      in if magic /= parquetMagic && magic /= parquetEncryptedMagic
+           then Left "Parquet.Footer: invalid magic (expected PAR1 or PARE)"
+           else
+             let !metaLenOff = totalLen - 8
+                 !metaLen = fromIntegral (readLE32 bs metaLenOff) :: Int
+             in if metaLen < 0 || metaLen > totalLen - 8
+                  then Left "Parquet.Footer: invalid metadata length"
+                  else
+                    let !metaStart = totalLen - 8 - metaLen
+                        !metaBytes =
+                          BSU.unsafeTake
+                            metaLen
+                            (BSU.unsafeDrop metaStart bs)
+                    in Right (FooterTrailer magic metaBytes)
+
+
+{- | Parse the plaintext-thrift bytes of a footer (i.e. what
+'readFooterTrailer' returns for a @PAR1@ file or what the caller
+got after decrypting a @PARE@ footer module).
+-}
+readFooterRaw :: ByteString -> Either String FileMetadata
+readFooterRaw thriftBytes = do
+  thriftVal <- decodeCompact thriftBytes
+  thriftToFileMetadata thriftVal
+
+
+readFooter :: ByteString -> Either String FileMetadata
+readFooter bs = do
+  trailer <- readFooterTrailer bs
+  if ftMagic trailer == parquetEncryptedMagic
+    then Left "Parquet.Footer: file has encrypted footer (PARE); use loadParquetFileEncrypted"
+    else readFooterRaw (ftBytes trailer)
+
+
+readLE32 :: ByteString -> Int -> Word32
+readLE32 bs off =
+  let !b0 = fromIntegral (BSU.unsafeIndex bs off) :: Word32
+      !b1 = fromIntegral (BSU.unsafeIndex bs (off + 1)) :: Word32
+      !b2 = fromIntegral (BSU.unsafeIndex bs (off + 2)) :: Word32
+      !b3 = fromIntegral (BSU.unsafeIndex bs (off + 3)) :: Word32
+  in b0 .|. (b1 `shiftL` 8) .|. (b2 `shiftL` 16) .|. (b3 `shiftL` 24)
+
+
+fileMetadataToThrift :: FileMetadata -> TV.Value
+fileMetadataToThrift fm =
+  TV.Struct $
+    V.fromList $
+      [ FileMetadata_Version (fmVersion fm)
+      , FileMetadata_Schema (V.map schemaElementToThrift (fmSchema fm))
+      , FileMetadata_NumRows (fmNumRows fm)
+      , FileMetadata_RowGroups (V.map rowGroupToThrift (fmRowGroups fm))
+      ]
+        ++ optField (fmKeyValueMetadata fm) (FileMetadata_KeyValueMetadata . V.map keyValueToThrift)
+        ++ optField (fmCreatedBy fm) FileMetadata_CreatedBy
+        ++ optField
+          (fmColumnOrders fm)
+          (FileMetadata_ColumnOrders . V.map columnOrderToThrift)
+
+
+keyValueToThrift :: KeyValue -> TV.Value
+keyValueToThrift entry =
+  TV.Struct $
+    V.singleton (KeyValue_Key (TV.Binary (kvKey entry)))
+      V.++ maybe V.empty (V.singleton . KeyValue_Value . TV.Binary) (kvValue entry)
+
+
+columnOrderToThrift :: ColumnOrder -> TV.Value
+columnOrderToThrift TypeDefinedOrder = columnOrderTypeDefined
+columnOrderToThrift IEEE754TotalOrder = columnOrderIeee754Total
+columnOrderToThrift Int96TimestampOrder = columnOrderInt96Timestamp
+columnOrderToThrift UnsupportedColumnOrder = error "Parquet.Footer: cannot write an unsupported column order"
+
+
+schemaElementToThrift :: SchemaElement -> TV.Value
+schemaElementToThrift se =
+  TV.Struct $
+    V.fromList $
+      concat
+        [ optField (seType se) (SchemaElement_Type . parquetTypeToInt)
+        , optField (seTypeLength se) SchemaElement_TypeLength
+        , optField (seRepetition se) (SchemaElement_RepetitionType . fromIntegral . fromEnum)
+        , [SchemaElement_Name (seName se)]
+        , optField (seNumChildren se) SchemaElement_NumChildren
+        , optField
+            ( case (seConvertedType se, seLogicalType se) of
+                (Nothing, Just (LTDecimal _ _)) -> Just CTDecimal
+                (converted, _) -> converted
+            )
+            (SchemaElement_ConvertedType . fromIntegral . fromEnum)
+        , optField (seFieldId se) SchemaElement_FieldId
+        , optField
+            (seLogicalType se)
+            (SchemaElement_LogicalType . V.fromList . logicalTypeFields)
+        , case seLogicalType se of
+            Just (LTDecimal precision scale) ->
+              [SchemaElement_Scale scale, SchemaElement_Precision precision]
+            _ -> []
+        ]
+
+
+{- | Encode a 'LogicalType' as the inner struct of the
+@parquet.thrift@ @LogicalType@ union — exactly one
+variant-tagged field.
+-}
+logicalTypeFields :: LogicalType -> [(Int16, TV.Value)]
+logicalTypeFields = \case
+  LTString -> [(1, emptyStruct)]
+  LTMap -> [(2, emptyStruct)]
+  LTList -> [(3, emptyStruct)]
+  LTEnum -> [(4, emptyStruct)]
+  LTDecimal p s ->
+    [
+      ( 5
+      , TV.Struct $
+          V.fromList
+            [ (1, TV.I32 s) -- scale
+            , (2, TV.I32 p) -- precision
+            ]
+      )
+    ]
+  LTDate -> [(6, emptyStruct)]
+  LTTime adj unit ->
+    [
+      ( 7
+      , TV.Struct $
+          V.fromList
+            [ (1, TV.Bool adj)
+            , (2, encodeTimeUnitStruct unit)
+            ]
+      )
+    ]
+  LTTimestamp adj unit ->
+    [
+      ( 8
+      , TV.Struct $
+          V.fromList
+            [ (1, TV.Bool adj)
+            , (2, encodeTimeUnitStruct unit)
+            ]
+      )
+    ]
+  LTInteger w isSigned ->
+    [
+      ( 10
+      , TV.Struct $
+          V.fromList
+            [ (1, TV.Byte (fromIntegral w))
+            , (2, TV.Bool isSigned)
+            ]
+      )
+    ]
+  LTNull -> [(11, emptyStruct)]
+  LTJson -> [(12, emptyStruct)]
+  LTBson -> [(13, emptyStruct)]
+  LTUUID -> [(14, emptyStruct)]
+  LTFloat16 -> [(15, emptyStruct)]
+  LTVariant ver ->
+    [
+      ( 16
+      , TV.Struct $
+          V.fromList
+            [ (1, TV.Byte (fromIntegral ver))
+            ]
+      )
+    ]
+  LTGeometry parameters ->
+    [(17, TV.Struct (V.fromList (maybe [] (\crs -> [(1, TV.String crs)]) (geometryCrs parameters))))]
+  LTGeography parameters ->
+    [
+      ( 18
+      , TV.Struct
+          ( V.fromList
+              ( maybe [] (\crs -> [(1, TV.String crs)]) (geographyCrs parameters)
+                  ++ maybe [] (\algorithm -> [(2, TV.I32 (interpolationAlgorithmToInt algorithm))]) (geographyAlgorithm parameters)
+              )
+          )
+      )
+    ]
+  LTFile -> [(19, emptyStruct)]
+  LTUnsupported -> error "Parquet.Footer: cannot write an unsupported logical annotation"
+
+
+emptyStruct :: TV.Value
+emptyStruct = TV.Struct V.empty
+
+
+encodeTimeUnitStruct :: LtTimeUnit -> TV.Value
+encodeTimeUnitStruct unit =
+  TV.Struct $
+    V.fromList
+      [
+        ( case unit of
+            LtMillis -> 1
+            LtMicros -> 2
+            LtNanos -> 3
+        , emptyStruct
+        )
+      ]
+
+
+decodeLogicalType :: V.Vector (Int16, TV.Value) -> Maybe LogicalType
+decodeLogicalType fs = Just (maybe LTUnsupported id (decodeKnownLogicalType fs))
+
+
+decodeKnownLogicalType :: V.Vector (Int16, TV.Value) -> Maybe LogicalType
+decodeKnownLogicalType fs = case V.toList fs of
+  [entry] -> case entry of
+    (1, TV.Struct _) -> Just LTString
+    (2, TV.Struct _) -> Just LTMap
+    (3, TV.Struct _) -> Just LTList
+    (4, TV.Struct _) -> Just LTEnum
+    (5, TV.Struct sb) -> decodeDecimal sb
+    (6, TV.Struct _) -> Just LTDate
+    (7, TV.Struct sb) -> decodeTimeOrTimestamp LTTime sb
+    (8, TV.Struct sb) -> decodeTimeOrTimestamp LTTimestamp sb
+    (10, TV.Struct sb) -> decodeIntType sb
+    (11, TV.Struct _) -> Just LTNull
+    (12, TV.Struct _) -> Just LTJson
+    (13, TV.Struct _) -> Just LTBson
+    (14, TV.Struct _) -> Just LTUUID
+    (15, TV.Struct _) -> Just LTFloat16
+    (16, TV.Struct sb) -> decodeVariant sb
+    (17, TV.Struct sb) -> LTGeometry . GeometryParameters <$> optionalLogicalField 1 asLogicalText sb
+    (18, TV.Struct sb) ->
+      LTGeography
+        <$> ( GeographyParameters
+                <$> optionalLogicalField 1 asLogicalText sb
+                <*> optionalLogicalField 2 (fmap intToInterpolationAlgorithm . asI32) sb
+            )
+    (19, TV.Struct _) -> Just LTFile
+    _ -> Nothing
+  _ -> Nothing
+  where
+    decodeDecimal :: V.Vector (Int16, TV.Value) -> Maybe LogicalType
+    decodeDecimal sb =
+      let mScale = lookup 1 (V.toList sb) >>= asI32
+          mPrec = lookup 2 (V.toList sb) >>= asI32
+      in case (mScale, mPrec) of
+           (Just s, Just p) -> Just (LTDecimal p s)
+           _ -> Nothing
+    decodeTimeOrTimestamp
+      :: (Bool -> LtTimeUnit -> LogicalType)
+      -> V.Vector (Int16, TV.Value)
+      -> Maybe LogicalType
+    decodeTimeOrTimestamp ctor sb =
+      let mAdj = lookup 1 (V.toList sb) >>= asBool
+          mUnit = lookup 2 (V.toList sb) >>= asTimeUnit
+      in ctor <$> mAdj <*> mUnit
+    decodeIntType :: V.Vector (Int16, TV.Value) -> Maybe LogicalType
+    decodeIntType sb =
+      let mWidth = lookup 1 (V.toList sb) >>= asByte
+          mSigned = lookup 2 (V.toList sb) >>= asBool
+      in LTInteger <$> (fromIntegral <$> mWidth) <*> mSigned
+    decodeVariant :: V.Vector (Int16, TV.Value) -> Maybe LogicalType
+    decodeVariant sb =
+      let mVer = lookup 1 (V.toList sb) >>= asByte
+      in LTVariant . fromIntegral <$> mVer
+
+
+-- Unknown fields permit extension; malformed/duplicate known parameters must
+-- fall back to physical storage rather than silently becoming default values.
+optionalLogicalField :: Int16 -> (TV.Value -> Maybe a) -> V.Vector (Int16, TV.Value) -> Maybe (Maybe a)
+optionalLogicalField field parse fields = case V.toList (V.filter ((== field) . fst) fields) of
+  [] -> Just Nothing
+  [(_, value)] -> Just <$> parse value
+  _ -> Nothing
+
+
+asLogicalText :: TV.Value -> Maybe T.Text
+asLogicalText (TV.String value) = Just value
+asLogicalText (TV.Binary value) = either (const Nothing) Just (Data.Text.Encoding.decodeUtf8' value)
+asLogicalText _ = Nothing
+
+
+asI32 :: TV.Value -> Maybe Int32
+asI32 (TV.I32 v) = Just v
+asI32 _ = Nothing
+
+
+asBool :: TV.Value -> Maybe Bool
+asBool (TV.Bool v) = Just v
+asBool _ = Nothing
+
+
+asByte :: TV.Value -> Maybe Int
+asByte (TV.Byte v) = Just (fromIntegral v)
+asByte (TV.I32 v) = Just (fromIntegral v)
+asByte _ = Nothing
+
+
+asTimeUnit :: TV.Value -> Maybe LtTimeUnit
+asTimeUnit (TV.Struct sb) = case V.toList sb of
+  [(1, TV.Struct _)] -> Just LtMillis
+  [(2, TV.Struct _)] -> Just LtMicros
+  [(3, TV.Struct _)] -> Just LtNanos
+  _ -> Nothing
+asTimeUnit _ = Nothing
+
+
+rowGroupToThrift :: RowGroup -> TV.Value
+rowGroupToThrift rg =
+  TV.Struct $
+    V.fromList $
+      [ RowGroup_Columns (V.map columnChunkToThrift (rgColumns rg))
+      , RowGroup_TotalByteSize (rgTotalByteSize rg)
+      , RowGroup_NumRows (rgNumRows rg)
+      ]
+        ++ optField
+          (rgSortingColumns rg)
+          (RowGroup_SortingColumns . V.map sortingColumnToThrift)
+
+
+sortingColumnToThrift :: SortingColumn -> TV.Value
+sortingColumnToThrift sc =
+  TV.Struct $
+    V.fromList
+      [ SortingColumn_ColumnIdx (scColumnIdx sc)
+      , SortingColumn_Descending (scDescending sc)
+      , SortingColumn_NullsFirst (scNullsFirst sc)
+      ]
+
+
+columnChunkToThrift :: ColumnChunk -> TV.Value
+columnChunkToThrift cc =
+  TV.Struct $
+    V.fromList $
+      concat
+        [ optField (ccFilePath cc) ColumnChunk_FilePath
+        , [ColumnChunk_FileOffset (ccFileOffset cc)]
+        , optField
+            (ccMetadata cc)
+            (\cm -> ColumnChunk_MetaData (V.fromList (columnMetadataFields cm)))
+        , -- Offset/column-index placement is spec'd on ColumnChunk itself;
+          -- older wireform writers omitted these fields entirely, which
+          -- decoders treat as @Nothing@.
+          optField (ccOffsetIndexOffset cc) ColumnChunk_OffsetIndexOffset
+        , optField (ccOffsetIndexLength cc) ColumnChunk_OffsetIndexLength
+        , optField (ccColumnIndexOffset cc) ColumnChunk_ColumnIndexOffset
+        , optField (ccColumnIndexLength cc) ColumnChunk_ColumnIndexLength
+        ]
+
+
+columnMetadataFields :: ColumnMetadata -> [(Int16, TV.Value)]
+columnMetadataFields cm =
+  concat
+    [
+      [ ColumnMetaData_Type (parquetTypeToInt (cmType cm))
+      , ColumnMetaData_Encodings
+          (V.map (TV.I32 . encodingToInt) (cmEncodings cm))
+      , ColumnMetaData_PathInSchema (V.map TV.String (cmPathInSchema cm))
+      , ColumnMetaData_Codec (compressionToInt (cmCodec cm))
+      , ColumnMetaData_NumValues (cmNumValues cm)
+      , ColumnMetaData_TotalUncompressedSize (cmTotalUncompressedSize cm)
+      , ColumnMetaData_TotalCompressedSize (cmTotalCompressedSize cm)
+      , ColumnMetaData_DataPageOffset (cmDataPageOffset cm)
+      ]
+    , optField (cmDictionaryPageOffset cm) ColumnMetaData_DictionaryPageOffset
+    , optField
+        (cmStatistics cm)
+        (\s -> ColumnMetaData_Statistics (V.fromList (statisticsFields s)))
+    , optField (cmBloomFilterOffset cm) ColumnMetaData_BloomFilterOffset
+    , optField (cmBloomFilterLength cm) ColumnMetaData_BloomFilterLength
+    ]
+
+
+statisticsFields :: Statistics -> [(Int16, TV.Value)]
+statisticsFields st =
+  concat
+    [ optField (statMax st) Statistics_Max
+    , optField (statMin st) Statistics_Min
+    , optField (statNullCount st) Statistics_NullCount
+    , optField (statDistinctCount st) Statistics_DistinctCount
+    , optField (statMaxValue st) Statistics_MaxValue
+    , optField (statMinValue st) Statistics_MinValue
+    , optField (statMaxValueExact st) Statistics_MaxValueExact
+    , optField (statMinValueExact st) Statistics_MinValueExact
+    , optField (statNanCount st) Statistics_NanCount
+    ]
+
+
+encodingToInt :: Encoding -> Int32
+encodingToInt = \case
+  Plain -> 0
+  PlainDictionary -> 2
+  RLE -> 3
+  BitPacked -> 4
+  DeltaBinaryPacked -> 5
+  DeltaLengthByteArray -> 6
+  DeltaByteArray -> 7
+  RLEDictionary -> 8
+  ByteStreamSplit -> 9
+  Alp -> 10
+
+
+intToEncoding :: Int32 -> Maybe Encoding
+intToEncoding = \case
+  0 -> Just Plain
+  2 -> Just PlainDictionary
+  3 -> Just RLE
+  4 -> Just BitPacked
+  5 -> Just DeltaBinaryPacked
+  6 -> Just DeltaLengthByteArray
+  7 -> Just DeltaByteArray
+  8 -> Just RLEDictionary
+  9 -> Just ByteStreamSplit
+  10 -> Just Alp
+  _ -> Nothing
+
+
+compressionToInt :: Compression -> Int32
+compressionToInt = \case
+  Uncompressed -> 0
+  Snappy -> 1
+  GZip -> 2
+  LZO -> 3
+  Brotli -> 4
+  LZ4 -> 5
+  ZSTD -> 6
+  LZ4Raw -> 7
+
+
+intToCompression :: Int32 -> Maybe Compression
+intToCompression = \case
+  0 -> Just Uncompressed
+  1 -> Just Snappy
+  2 -> Just GZip
+  3 -> Just LZO
+  4 -> Just Brotli
+  5 -> Just LZ4
+  6 -> Just ZSTD
+  7 -> Just LZ4Raw
+  _ -> Nothing
+
+
+-- Decoding from Thrift value back to our types
+
+thriftToFileMetadata :: TV.Value -> Either String FileMetadata
+thriftToFileMetadata (TV.Struct fields) = do
+  let fm = V.toList fields
+  version <- require fm "version" $ \case
+    FileMetadata_Version v -> Just v
+    _ -> Nothing
+  schema <- requireListStruct fm "schema" thriftToSchemaElement $ \case
+    FileMetadata_Schema xs -> Just xs
+    _ -> Nothing
+  numRows <- require fm "num_rows" $ \case
+    FileMetadata_NumRows v -> Just v
+    _ -> Nothing
+  rowGroups <- requireListStruct fm "row_groups" thriftToRowGroup $ \case
+    FileMetadata_RowGroups xs -> Just xs
+    _ -> Nothing
+  if numRows < 0
+    then Left "Parquet.Footer: negative file row count"
+    else Right ()
+  -- Historical files can have a stale file total while their row groups and
+  -- data remain readable (parquet-testing/repeated_no_annotation.parquet).
+  -- Preserve it for checked aggregate validation instead of losing the data.
+  if V.any ((< 0) . rgNumRows) rowGroups
+    then Left "Parquet.Footer: negative row-group count"
+    else Right ()
+  keyValues <- case V.toList (V.filter ((== 5) . fst) fields) of
+    [] -> Right Nothing
+    [FileMetadata_KeyValueMetadata entries] -> Just <$> V.mapM thriftToKeyValue entries
+    _ -> Left "Parquet.Footer: invalid or duplicate key_value_metadata"
+  let createdBy = findField fm $ \case
+        FileMetadata_CreatedBy t -> Just t
+        _ -> Nothing
+  let columnOrders = findField fm $ \case
+        FileMetadata_ColumnOrders xs ->
+          Just (V.map thriftToColumnOrder xs)
+        _ -> Nothing
+  case columnOrders of
+    Just orders
+      | V.length orders /= V.length (V.filter (maybe False (const True) . seType) schema) ->
+          Left "Parquet.Footer: column-order count differs from leaf-column count"
+    _ -> Right ()
+  Right
+    FileMetadata
+      { fmVersion = version
+      , fmSchema = schema
+      , fmNumRows = numRows
+      , fmRowGroups = maybe rowGroups (\orders -> V.map (sanitizeColumnOrders schema orders) rowGroups) columnOrders
+      , fmCreatedBy = createdBy
+      , fmColumnOrders = columnOrders
+      , fmKeyValueMetadata = keyValues
+      }
+thriftToFileMetadata _ = Left "Parquet.Footer: expected struct"
+
+
+thriftToKeyValue :: TV.Value -> Either String KeyValue
+thriftToKeyValue (TV.Struct fields) = do
+  key <- metadataField "key" (\case KeyValue_Key value -> Just value; _ -> Nothing)
+  value <- metadataField "value" (\case KeyValue_Value value -> Just value; _ -> Nothing)
+  requiredKey <- maybe (Left "Parquet.Footer: metadata entry has no key") Right key
+  Right (KeyValue requiredKey value)
+  where
+    metadataField name select = case V.toList (V.mapMaybe select fields) of
+      [] -> Right Nothing
+      [TV.Binary bytes] -> Right (Just bytes)
+      [TV.String text] -> Right (Just (Data.Text.Encoding.encodeUtf8 text))
+      _ -> Left ("Parquet.Footer: invalid or duplicate metadata " ++ name)
+thriftToKeyValue _ = Left "Parquet.Footer: expected struct for metadata entry"
+
+
+thriftToColumnOrder :: TV.Value -> ColumnOrder
+thriftToColumnOrder (TV.Struct fields) =
+  case V.toList fields of
+    [(1, TV.Struct _)] -> TypeDefinedOrder
+    [(2, TV.Struct _)] -> IEEE754TotalOrder
+    [(3, TV.Struct _)] -> Int96TimestampOrder
+    _ -> UnsupportedColumnOrder
+thriftToColumnOrder _ = UnsupportedColumnOrder
+
+
+-- Preserve the position of unknown union variants. Dropping one would
+-- shift the ordering of all later columns and could cause false pruning.
+-- Bounds with an unsupported order are unavailable; null counts remain valid.
+sanitizeColumnOrders :: V.Vector SchemaElement -> V.Vector ColumnOrder -> RowGroup -> RowGroup
+sanitizeColumnOrders schema orders rg = rg {rgColumns = V.imap sanitize (rgColumns rg)}
+  where
+    leaves = V.filter (maybe False (const True) . seType) schema
+    sanitize i cc
+      | maybe False (supported i . cmType) (ccMetadata cc) = cc
+      | otherwise =
+          cc
+            { ccMetadata = sanitizeMetadata i <$> ccMetadata cc
+            , ccColumnIndexOffset = Nothing
+            , ccColumnIndexLength = Nothing
+            }
+    sanitizeMetadata i md
+      | supported i (cmType md) = md
+      | otherwise = md {cmStatistics = fmap clearBounds (cmStatistics md)}
+    supported i ty =
+      maybe False hasDefinedStatisticsOrder (leaves V.!? i) && case orders V.!? i of
+        Just TypeDefinedOrder -> ty /= PTInt96
+        Just IEEE754TotalOrder ->
+          ty == PTFloat
+            || ty == PTDouble
+            || (ty == PTFixedLenByteArray && (leaves V.!? i >>= seLogicalType) == Just LTFloat16)
+        Just Int96TimestampOrder -> ty == PTInt96
+        _ -> False
+    clearBounds stats =
+      stats
+        { statMin = Nothing
+        , statMax = Nothing
+        , statMinValue = Nothing
+        , statMaxValue = Nothing
+        , statMinValueExact = Nothing
+        , statMaxValueExact = Nothing
+        }
+
+
+thriftToSchemaElement :: TV.Value -> Either String SchemaElement
+thriftToSchemaElement (TV.Struct fields) = do
+  let fm = V.toList fields
+  name <- require fm "schema name" $ \case
+    SchemaElement_Name t -> Just t
+    _ -> Nothing
+  typ <- traverse decodeType $ findField fm $ \case
+    SchemaElement_Type t -> Just t
+    _ -> Nothing
+  rep <- traverse decodeRepetition $ findField fm $ \case
+    SchemaElement_RepetitionType r -> Just r
+    _ -> Nothing
+  let numCh = findField fm $ \case
+        SchemaElement_NumChildren n -> Just n
+        _ -> Nothing
+      conv = findField fm $ \case
+        SchemaElement_ConvertedType c
+          | c >= 0, c <= 21 -> Just (toEnum (fromIntegral c))
+        _ -> Nothing
+      fid = findField fm $ \case
+        SchemaElement_FieldId v -> Just v
+        _ -> Nothing
+      typeLength = findField fm $ \case
+        SchemaElement_TypeLength n -> Just n
+        _ -> Nothing
+      modernLogical = findField fm $ \case
+        SchemaElement_LogicalType inner -> decodeLogicalType inner
+        _ -> Nothing
+      legacyPrecision = findField fm $ \case
+        SchemaElement_Precision n -> Just n
+        _ -> Nothing
+      legacyScale = findField fm $ \case
+        SchemaElement_Scale n -> Just n
+        _ -> Nothing
+  logical <- case (modernLogical, conv, legacyPrecision) of
+    (Just annotation, _, _) -> Right (Just annotation)
+    (Nothing, Just CTDecimal, Just precision) ->
+      Right (Just (LTDecimal precision (maybe 0 id legacyScale)))
+    (Nothing, Just CTDecimal, Nothing) -> Left "Parquet.Footer: legacy DECIMAL is missing precision"
+    _ -> Right Nothing
+  case numCh of
+    Just n | n < 0 -> Left "Parquet.Footer: negative schema child count"
+    _ -> Right ()
+  case (typ, typeLength) of
+    (Just PTFixedLenByteArray, Just n) | n > 0 -> Right ()
+    (Just PTFixedLenByteArray, _) -> Left "Parquet.Footer: fixed byte array needs a positive type_length"
+    (_, Just n) | n < 0 -> Left "Parquet.Footer: negative type_length"
+    _ -> Right ()
+  case logical of
+    Just (LTDecimal precision scale)
+      | precision <= 0 || scale < 0 || scale > precision ->
+          Left "Parquet.Footer: invalid DECIMAL precision or scale"
+      | typ == Just PTInt32 && precision > 9 -> Left "Parquet.Footer: INT32 DECIMAL precision exceeds 9"
+      | typ == Just PTInt64 && precision > 18 -> Left "Parquet.Footer: INT64 DECIMAL precision exceeds 18"
+      | Just width <- typeLength
+      , typ == Just PTFixedLenByteArray
+      , not (decimalPrecisionFits precision width) ->
+          Left "Parquet.Footer: DECIMAL precision exceeds fixed byte width"
+    _ -> Right ()
+  Right
+    SchemaElement
+      { seTypeLength = typeLength
+      , seName = name
+      , seRepetition = rep
+      , seType = typ
+      , seNumChildren = numCh
+      , seConvertedType = if logical == Just LTUnsupported then Nothing else conv
+      , seLogicalType = logical
+      , seFieldId = fid
+      }
+  where
+    decodeType tag = case intToParquetType tag of
+      Just ty -> Right ty
+      Nothing -> Left ("Parquet.Footer: unknown physical type " ++ show tag)
+    decodeRepetition = \case
+      0 -> Right Required
+      1 -> Right Optional
+      2 -> Right Repeated
+      tag -> Left ("Parquet.Footer: unknown repetition type " ++ show tag)
+thriftToSchemaElement _ = Left "Parquet.Footer: expected struct for SchemaElement"
+
+
+thriftToRowGroup :: TV.Value -> Either String RowGroup
+thriftToRowGroup (TV.Struct fields) = do
+  let fm = V.toList fields
+  cols <- requireListStruct fm "columns" thriftToColumnChunk $ \case
+    RowGroup_Columns xs -> Just xs
+    _ -> Nothing
+  totalBytes <- require fm "total_byte_size" $ \case
+    RowGroup_TotalByteSize v -> Just v
+    _ -> Nothing
+  numRows <- require fm "num_rows" $ \case
+    RowGroup_NumRows v -> Just v
+    _ -> Nothing
+  let sortingColumns = findField fm $ \case
+        RowGroup_SortingColumns xs ->
+          Just (V.mapMaybe thriftToSortingColumn xs)
+        _ -> Nothing
+  Right
+    RowGroup
+      { rgColumns = cols
+      , rgTotalByteSize = totalBytes
+      , rgNumRows = numRows
+      , rgSortingColumns = sortingColumns
+      }
+thriftToRowGroup _ = Left "Parquet.Footer: expected struct for RowGroup"
+
+
+thriftToSortingColumn :: TV.Value -> Maybe SortingColumn
+thriftToSortingColumn (TV.Struct fields) = do
+  let look p = V.find p fields
+  TV.I32 i <- snd <$> look (\(fid, _) -> fid == 1)
+  TV.Bool d <- snd <$> look (\(fid, _) -> fid == 2)
+  TV.Bool n <- snd <$> look (\(fid, _) -> fid == 3)
+  Just SortingColumn {scColumnIdx = i, scDescending = d, scNullsFirst = n}
+thriftToSortingColumn _ = Nothing
+
+
+thriftToColumnChunk :: TV.Value -> Either String ColumnChunk
+thriftToColumnChunk (TV.Struct fields) = do
+  let fm = V.toList fields
+      fp = findField fm $ \case
+        ColumnChunk_FilePath t -> Just t
+        _ -> Nothing
+  fileOff <- require fm "file_offset" $ \case
+    ColumnChunk_FileOffset v -> Just v
+    _ -> Nothing
+  meta <- case findField
+    fm
+    ( \case
+        ColumnChunk_MetaData fs -> Just fs
+        _ -> Nothing
+    ) of
+    Just fs -> Just <$> thriftToColumnMetadata (TV.Struct fs)
+    Nothing -> Right Nothing
+  let oio = findField fm $ \case
+        ColumnChunk_OffsetIndexOffset v -> Just v
+        _ -> Nothing
+      oil = findField fm $ \case
+        ColumnChunk_OffsetIndexLength v -> Just v
+        _ -> Nothing
+      cio = findField fm $ \case
+        ColumnChunk_ColumnIndexOffset v -> Just v
+        _ -> Nothing
+      cil = findField fm $ \case
+        ColumnChunk_ColumnIndexLength v -> Just v
+        _ -> Nothing
+  Right
+    ColumnChunk
+      { ccFilePath = fp
+      , ccFileOffset = fileOff
+      , ccMetadata = meta
+      , ccOffsetIndexOffset = oio
+      , ccOffsetIndexLength = oil
+      , ccColumnIndexOffset = cio
+      , ccColumnIndexLength = cil
+      }
+thriftToColumnChunk _ = Left "Parquet.Footer: expected struct for ColumnChunk"
+
+
+thriftToColumnMetadata :: TV.Value -> Either String ColumnMetadata
+thriftToColumnMetadata (TV.Struct fields) = do
+  let fm = V.toList fields
+  typeVal <- require fm "type" $ \case
+    ColumnMetaData_Type v -> Just v
+    _ -> Nothing
+  pt <- maybe (Left "Parquet.Footer: invalid parquet type") Right (intToParquetType typeVal)
+  encodings <- case findField
+    fm
+    ( \case
+        ColumnMetaData_Encodings xs -> Just xs
+        _ -> Nothing
+    ) of
+    Just es -> V.mapM expectEncoding es
+    Nothing -> Left "Parquet.Footer: missing encodings"
+  paths <- case findField
+    fm
+    ( \case
+        ColumnMetaData_PathInSchema xs -> Just xs
+        _ -> Nothing
+    ) of
+    Just ps -> V.mapM expectPathStr ps
+    Nothing -> Left "Parquet.Footer: missing path_in_schema"
+  codecVal <- require fm "codec" $ \case
+    ColumnMetaData_Codec v -> Just v
+    _ -> Nothing
+  codec <- maybe (Left "Parquet.Footer: invalid compression") Right (intToCompression codecVal)
+  numVals <- require fm "num_values" $ \case
+    ColumnMetaData_NumValues v -> Just v
+    _ -> Nothing
+  uncompSz <- require fm "total_uncompressed_size" $ \case
+    ColumnMetaData_TotalUncompressedSize v -> Just v
+    _ -> Nothing
+  compSz <- require fm "total_compressed_size" $ \case
+    ColumnMetaData_TotalCompressedSize v -> Just v
+    _ -> Nothing
+  dataOff <- require fm "data_page_offset" $ \case
+    ColumnMetaData_DataPageOffset v -> Just v
+    _ -> Nothing
+  -- index_page_offset / dictionary_page_offset / encoding_stats /
+  -- key_value_metadata are all spec-defined but unused by this reader.
+  stats <- traverse (thriftToStatistics . TV.Struct) $ findField fm $ \case
+    ColumnMetaData_Statistics fs -> Just fs
+    _ -> Nothing
+  if numVals < 0 || uncompSz < 0 || compSz < 0 || dataOff < 0
+    then Left "Parquet.Footer: negative column count, size, or page offset"
+    else Right ()
+  case stats of
+    Just st
+      | maybe False (> numVals) (statNullCount st)
+          || maybe False (> numVals - maybe 0 id (statNullCount st)) (statNanCount st) ->
+          Left "Parquet.Footer: statistics counts exceed column value count"
+    _ -> Right ()
+  let bfo = findField fm $ \case
+        ColumnMetaData_BloomFilterOffset v -> Just v
+        _ -> Nothing
+      bfl = findField fm $ \case
+        ColumnMetaData_BloomFilterLength v -> Just v
+        _ -> Nothing
+      dpo = findField fm $ \case
+        ColumnMetaData_DictionaryPageOffset v -> Just v
+        _ -> Nothing
+  Right
+    ColumnMetadata
+      { cmType = pt
+      , cmEncodings = encodings
+      , cmPathInSchema = paths
+      , cmCodec = codec
+      , cmNumValues = numVals
+      , cmTotalUncompressedSize = uncompSz
+      , cmTotalCompressedSize = compSz
+      , cmDataPageOffset = dataOff
+      , cmDictionaryPageOffset = dpo
+      , cmStatistics = stats
+      , cmBloomFilterOffset = bfo
+      , cmBloomFilterLength = bfl
+      }
+thriftToColumnMetadata _ = Left "Parquet.Footer: expected struct for ColumnMetadata"
+
+
+expectEncoding :: TV.Value -> Either String Encoding
+expectEncoding (TV.I32 e) =
+  maybe (Left "Parquet.Footer: invalid encoding") Right (intToEncoding e)
+expectEncoding _ = Left "Parquet.Footer: expected i32 in encodings"
+
+
+expectPathStr :: TV.Value -> Either String T.Text
+expectPathStr (TV.String t) = Right t
+expectPathStr _ = Left "Parquet.Footer: expected string in path"
+
+
+thriftToStatistics :: TV.Value -> Either String Statistics
+thriftToStatistics (TV.Struct fields) = do
+  minExact <- exactFlag 8
+  maxExact <- exactFlag 7
+  let fm = V.toList fields
+      -- Thrift Compact stores both binary and UTF-8 strings under
+      -- TT_STRING; the decoder surfaces TV.String when the bytes happen
+      -- to parse as UTF-8. Statistics values are arbitrary bytes
+      -- (PLAIN-encoded primitives) so accept either shape.
+      minProbe = \case
+        Statistics_Min b -> Just b
+        (2, TV.String t) -> Just (Data.Text.Encoding.encodeUtf8 t)
+        _ -> Nothing
+      maxProbe = \case
+        Statistics_Max b -> Just b
+        (1, TV.String t) -> Just (Data.Text.Encoding.encodeUtf8 t)
+        _ -> Nothing
+      minValueProbe = \case
+        Statistics_MinValue b -> Just b
+        (6, TV.String t) -> Just (Data.Text.Encoding.encodeUtf8 t)
+        _ -> Nothing
+      maxValueProbe = \case
+        Statistics_MaxValue b -> Just b
+        (5, TV.String t) -> Just (Data.Text.Encoding.encodeUtf8 t)
+        _ -> Nothing
+  let statistics =
+        Statistics
+          { statMax = findField fm maxProbe
+          , statMin = findField fm minProbe
+          , statNullCount = findField fm $ \case
+              Statistics_NullCount v -> Just v
+              _ -> Nothing
+          , statDistinctCount = findField fm $ \case
+              Statistics_DistinctCount v -> Just v
+              _ -> Nothing
+          , statMaxValue = findField fm maxValueProbe
+          , statMinValue = findField fm minValueProbe
+          , statNanCount = findField fm $ \case
+              Statistics_NanCount v -> Just v
+              _ -> Nothing
+          , statMinValueExact = minExact
+          , statMaxValueExact = maxExact
+          }
+  if any
+    (maybe False (< 0))
+    [statNullCount statistics, statDistinctCount statistics, statNanCount statistics]
+    then Left "Parquet.Footer: negative statistics count"
+    else Right statistics
+  where
+    exactFlag tag = case V.toList (V.filter ((== tag) . fst) fields) of
+      [] -> Right Nothing
+      [(_, TV.Bool value)] -> Right (Just value)
+      _ -> Left "Parquet.Footer: invalid or duplicate statistics exactness flag"
+thriftToStatistics _ = Left "Parquet.Footer: expected struct for Statistics"
+
+
+-- Helpers
+
+{- | Look up a scalar field with a caller-supplied probe and fail with
+a uniform error message if the field is absent or the probe rejects
+its shape.
+-}
+require
+  :: [(Int16, TV.Value)]
+  -> String
+  -> ((Int16, TV.Value) -> Maybe a)
+  -> Either String a
+require fm name probe = case findField fm probe of
+  Just v -> Right v
+  Nothing -> Left $ "Parquet.Footer: missing or invalid field " ++ name
+
+
+{- | Variant of 'require' that expects a struct-list field; each element
+is decoded with the supplied function.
+-}
+requireListStruct
+  :: [(Int16, TV.Value)]
+  -> String
+  -> (TV.Value -> Either String a)
+  -> ((Int16, TV.Value) -> Maybe (V.Vector TV.Value))
+  -> Either String (V.Vector a)
+requireListStruct fm name decode probe = case findField fm probe of
+  Just xs -> V.mapM decode xs
+  Nothing -> Left $ "Parquet.Footer: missing or invalid field " ++ name
diff --git a/src/Parquet/GZip.hs b/src/Parquet/GZip.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/GZip.hs
@@ -0,0 +1,51 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | Strict, optionally page-bounded GZip decoding through zlib's incremental
+API. Output is checked before requesting the next chunk; concatenated GZip
+members, CRCs, end-of-input and trailing bytes all remain validated.
+-}
+module Parquet.GZip (decompress, decompressSized) where
+
+import Codec.Compression.Zlib.Internal qualified as Z
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int32)
+import System.IO.Unsafe (unsafeDupablePerformIO)
+
+
+decompress :: ByteString -> Either String ByteString
+decompress = decode Nothing
+
+
+decompressSized :: Int -> ByteString -> Either String ByteString
+decompressSized expected
+  | expected < 0 || expected >= maxBound || expected > fromIntegral (maxBound :: Int32) = const (Left "Parquet.Read: invalid GZip uncompressed size")
+  | otherwise = decode (Just expected)
+
+
+decode :: Maybe Int -> ByteString -> Either String ByteString
+decode expected input = unsafeDupablePerformIO (walk False False 0 [] initial)
+  where
+    limit = maybe (fromIntegral (maxBound :: Int32)) id expected
+    parameters =
+      Z.defaultDecompressParams
+        { Z.decompressBufferSize = maybe 32768 (\n -> n + 1) expected
+        , Z.decompressAllMembers = True
+        }
+    initial = Z.decompressIO Z.gzipFormat parameters
+    walk !fed !eof !written !chunks stream = case stream of
+      Z.DecompressInputRequired supply
+        | not fed -> supply input >>= walk True (BS.null input) written chunks
+        | not eof -> supply BS.empty >>= walk True True written chunks
+        | otherwise -> pure (Left "Parquet.Read: GZip truncated input")
+      Z.DecompressOutputAvailable chunk next
+        | BS.length chunk > limit - written -> pure (Left "Parquet.Read: GZip output exceeds page size")
+        | otherwise -> next >>= walk fed eof (written + BS.length chunk) (chunk : chunks)
+      Z.DecompressStreamEnd unused
+        | not (BS.null unused) -> pure (Left "Parquet.Read: GZip trailing compressed input")
+        | maybe False (/= written) expected -> pure (Left "Parquet.Read: GZip decompressed size differs from page header")
+        | otherwise -> pure (Right (finish chunks))
+      Z.DecompressStreamError problem -> pure (Left ("Parquet.Read: GZip decompress failed: " ++ show problem))
+    finish [] = BS.empty
+    finish [chunk] = chunk
+    finish chunks = BS.concat (reverse chunks)
diff --git a/src/Parquet/HighLevel.hs b/src/Parquet/HighLevel.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/HighLevel.hs
@@ -0,0 +1,615 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | High-level Parquet API.
+
+95% of callers should reach for this module. It hides the
+@ColumnAux@ parallel-array machinery, the encrypted-footer
+variant, and the per-row-group compression knobs of
+"Parquet.Write" behind a single record-of-options:
+
+@
+-- Encode
+let bytes = 'encodeParquet' 'defaultWriteOptions'
+                           schema rowGroups
+
+-- Read
+case 'decodeParquet' bytes of
+  Right (schema', rowGroups') -> ...
+  Left  err                   -> ...
+@
+
+@rowGroups@ is a @[V.Vector ColumnData]@ — one entry per row
+group, each entry one 'ColumnData' per /leaf/ schema column in
+the same order @schema@ enumerates them.
+
+The 'WriteOptions' record consolidates every Parquet writer
+knob in one place: compression, page version, bloom filters,
+page-index emission, per-column encryption, and footer
+encryption (PARE mode). Defaults are the modern-Parquet
+recommended settings (Snappy, V2 pages, no encryption).
+
+For lower-level control (per-column compression overrides,
+bespoke 'ColumnAux' values, custom row-group dictionaries) drop
+down to "Parquet.Write".
+-}
+module Parquet.HighLevel (
+  -- * Encoding
+  encodeParquet,
+  encodeParquetIO,
+  encodeParquetMixed,
+  encodeParquetMixedIO,
+  encodeParquetNested,
+  encodeParquetNestedWith,
+  encodeParquetNestedIO,
+  FooterMode (..),
+  WriteOptions (..),
+  defaultWriteOptions,
+  ParquetColumn (..),
+  OptionalColumn (..),
+
+  -- * Decoding
+  decodeParquet,
+  ReadOptions (..),
+  defaultReadOptions,
+  FooterDecryption (..),
+  DecryptionConfig (..),
+  defaultDecryptionConfig,
+  ColumnKeyMetadata (..),
+  encryptedColumnKeyMetadata,
+  ParquetFile (..),
+
+  -- * Re-exports for convenience
+  ColumnData (..),
+  ColumnEncryption (..),
+  FooterEncryption (..),
+  Compression (..),
+  PageVersion (..),
+  SchemaElement (..),
+  NestedSchema (..),
+  NestedRow (..),
+  LeafType (..),
+  LeafValue (..),
+) where
+
+import Crypto.Random.Types qualified as RNG
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Lazy qualified as BL
+import Data.Int (Int32, Int64)
+import Data.Text (Text)
+import Data.Text.Encoding qualified as TE
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import GHC.Float (castDoubleToWord64, castFloatToWord32)
+import Parquet.Arrow qualified as Arrow
+import Parquet.BloomFilter qualified as Bloom
+import Parquet.Compress (validateCompression)
+import Parquet.Footer qualified as Footer
+import Parquet.Decryption (ColumnKeyMetadata (..), DecryptionConfig (..), defaultDecryptionConfig)
+import Parquet.Nested (
+  LeafType (..),
+  LeafValue (..),
+  NestedRow (..),
+  NestedSchema (..),
+  buildNestedFile,
+  buildNestedFileWithAux,
+  buildNestedFileWithBloomFilters,
+  buildNestedFileWithBloomFiltersUsing,
+  nestedSchemaToFlatSchema,
+ )
+import Parquet.Read (
+  FooterDecryption (..),
+  ParquetFile (..),
+  encryptedColumnKeyMetadata,
+  loadParquetFile,
+  loadParquetFileEncrypted,
+  loadParquetFileWithDecryption,
+ )
+import Parquet.Types (
+  Compression (..),
+  FileMetadata,
+  SchemaElement (..),
+ )
+import Parquet.Write.Encrypted (FooterMode (..))
+import Parquet.Write.Encrypted qualified as Encrypted
+import Parquet.Write (
+  ColumnAux (..),
+  ColumnData (..),
+  ColumnEncryption (..),
+  FooterEncryption (..),
+  OptionalColumn (..),
+  PageVersion (..),
+  ParquetColumn (..),
+  buildParquetFileMixedWithAux,
+  buildParquetFileMixedWithAuxUsing,
+  buildParquetFileWithIndex,
+  buildParquetFileWithIndexEncryptedFooter,
+  buildParquetFileWithIndexIO,
+  emptyColumnAux,
+  optionalColumnPresentValues,
+ )
+import Wireform.Builder qualified as B
+
+
+-- ============================================================
+-- Options
+-- ============================================================
+
+{- | Parquet writer configuration. Construct one with
+'defaultWriteOptions' and override the fields you care about:
+
+@
+let opts = 'defaultWriteOptions'
+            { writeCompression = 'ZSTD'
+            , writeBloomFilters = ["sku"]
+            }
+    bytes = 'encodeParquet' opts schema rowGroups
+@
+-}
+data WriteOptions = WriteOptions
+  { writeCompression :: !Compression
+  {- ^ Compression codec applied to every column's data pages.
+  Default: 'Snappy'. Use 'Uncompressed' to skip.
+  -}
+  , writePageVersion :: !PageVersion
+  {- ^ Data page version. 'PageV2' is recommended for modern
+  writers; 'PageV1' interoperates with older Parquet readers.
+  Default: 'PageV2'.
+  -}
+  , writeBloomFilters :: ![Text]
+  {- ^ Column paths (top-level field names) that should carry a
+  split-block bloom filter. Empty list → no bloom filters.
+  Filter parameters use parquet-cpp's defaults
+  (~3% FPP at 1024 distinct values per row group).
+  -}
+  , writePageIndex :: !Bool
+  {- ^ Emit per-column 'OffsetIndex' / 'ColumnIndex' regions in
+  the trailing page-index area. Default: 'True' — page
+  indexes substantially improve scan performance for filter
+  pushdown and most ecosystem readers (pyarrow, parquet-mr,
+  DuckDB, Trino) take advantage of them when present.
+  -}
+  , writeColumnEncryption :: !(V.Vector (Maybe ColumnEncryption))
+  {- ^ Per-leaf-column encryption configuration. The vector
+  length must match the number of leaf columns; 'Nothing'
+  entries leave the column in plaintext. Default:
+  'V.empty' (no per-column encryption — interpreted as
+  "all columns plaintext").
+  -}
+  , writeFooterMode :: !FooterMode
+  -- ^ Encrypted footer (default), or an authenticated plaintext footer.
+  , writeFooterEncryption :: !(Maybe FooterEncryption)
+  {- ^ Footer encryption/signing key and file AAD context. 'writeFooterMode'
+  selects an encrypted footer (PARE) or a signed plaintext footer (PAR1).
+  'Nothing' means an ordinary unencrypted file and requires plaintext columns.
+  -}
+  }
+  deriving (Show, Eq)
+
+
+{- | Sensible modern-Parquet defaults: Snappy compression, V2
+pages, page indexes on, no encryption, no bloom filters.
+-}
+defaultWriteOptions :: WriteOptions
+defaultWriteOptions =
+  WriteOptions
+    { writeCompression = Snappy
+    , writePageVersion = PageV2
+    , writeBloomFilters = []
+    , writePageIndex = True
+    , writeColumnEncryption = V.empty
+    , writeFooterMode = EncryptedFooter
+    , writeFooterEncryption = Nothing
+    }
+
+
+-- ============================================================
+-- Encoding
+-- ============================================================
+
+{- | Serialise a Parquet file from a schema + row groups, applying
+the supplied options.
+
+The schema is a flat 'V.Vector' of 'SchemaElement' (one entry
+per node in the parquet schema tree, including the synthetic
+root). Row groups are a list of column-major collections — one
+'V.Vector' 'ColumnData' per row group, each containing exactly
+one entry per leaf column in declaration order.
+-}
+encodeParquet
+  :: WriteOptions
+  -> V.Vector SchemaElement
+  -> [V.Vector ColumnData]
+  -> ByteString
+encodeParquet opts _ _
+  | encryptionRequested opts =
+      error "Parquet.HighLevel: encryption requires encodeParquetIO"
+encodeParquet opts schema rgs =
+  let !rowGroups = V.fromList rgs
+      !auxes = V.map (mkAuxes opts schema) rowGroups
+  in case validateCompression (writeCompression opts) >> Right (writeFooterEncryption opts) of
+       Left err -> error err
+       Right Nothing -> buildParquetFileWithIndex schema rowGroups auxes
+       Right (Just _) -> error "Parquet.HighLevel: encryption requires encodeParquetIO"
+
+
+{- | Encoding with random encryption nonces. Invalid encryption keys return
+'Left', with no plaintext file produced. Unencrypted callers can continue
+to use 'encodeParquet'.
+-}
+encodeParquetIO
+  :: RNG.MonadRandom m
+  => WriteOptions
+  -> V.Vector SchemaElement
+  -> [V.Vector ColumnData]
+  -> m (Either String ByteString)
+encodeParquetIO opts schema rgs =
+  case validateCompression (writeCompression opts) >> validateWriteEncryption opts schema of
+    Left err -> pure (Left err)
+    Right () ->
+      let groups = V.fromList rgs
+      in case writeFooterEncryption opts of
+        Nothing -> buildParquetFileWithIndexIO schema groups (V.map (mkAuxes opts schema) groups)
+        Just footer
+          | writeFooterMode opts == EncryptedFooter
+          , V.all (maybe True ((== feKey footer) . ceKey)) (writeColumnEncryption opts) ->
+              buildParquetFileWithIndexEncryptedFooter footer schema groups (V.map (mkAuxes opts schema) groups)
+        Just _ -> do
+          let plainOptions = withoutEncryption opts
+              auxes = V.map (mkAuxes plainOptions schema) groups
+          plaintext <- buildParquetFileWithIndexIO schema groups auxes
+          finishEncrypted opts plaintext
+
+
+withoutEncryption :: WriteOptions -> WriteOptions
+withoutEncryption opts = opts {writeColumnEncryption = V.empty, writeFooterEncryption = Nothing, writeFooterMode = EncryptedFooter}
+
+
+finishEncrypted :: RNG.MonadRandom m => WriteOptions -> Either String ByteString -> m (Either String ByteString)
+finishEncrypted _ (Left err) = pure (Left err)
+finishEncrypted opts (Right plaintext) = case writeFooterEncryption opts of
+  Nothing -> pure (Right plaintext)
+  Just footer -> Encrypted.encryptWrittenFile (writeFooterMode opts) footer (writeColumnEncryption opts) plaintext
+
+
+finishWriterOutput :: RNG.MonadRandom m => FooterEncryption -> WriteOptions -> Either String Encrypted.WriterOutput -> m (Either String ByteString)
+finishWriterOutput _ _ (Left err) = pure (Left err)
+finishWriterOutput footer opts (Right output) =
+  Encrypted.encryptWriterOutput (writeFooterMode opts) footer (writeColumnEncryption opts) output
+
+
+{- | Build the leaf-name -> column-index lookup for a flat
+schema. The synthetic root is at index 0; leaves start at 1
+in the schema vector but are addressed 0-indexed in the
+per-row-group columns. Used by the bloom-filter populator to
+map the @writeBloomFilters@ name list to column positions.
+-}
+leafColumnIndex :: V.Vector SchemaElement -> Text -> Maybe Int
+leafColumnIndex schema name =
+  let leaves = V.filter (maybe False (const True) . seType) schema
+  in V.findIndex ((== name) . seName) leaves
+
+
+{- | Serialise a Parquet file from a schema + row groups where
+each column may be either required ('PCRequired') or nullable
+('PCOptional'). Honors compression, page version, bloom filters and page
+indexes. Unsupported codecs and invalid layouts raise a descriptive error;
+they never silently fall back to another codec. Use 'encodeParquetMixedIO'
+for encryption with fresh random nonces.
+-}
+encodeParquetMixed
+  :: WriteOptions
+  -> V.Vector SchemaElement
+  -> [V.Vector ParquetColumn]
+  -> ByteString
+encodeParquetMixed opts _ _
+  | encryptionRequested opts =
+      error "Parquet.HighLevel: encryption is not supported by the mixed writer"
+encodeParquetMixed opts schema rgs =
+  either error id $
+    validateCompression (writeCompression opts) >>
+      buildParquetFileMixedWithAuxUsing plainMixedOutput schema (V.fromList rgs) (V.map (mkAuxes opts schema))
+
+
+plainMixedOutput :: FileMetadata -> [ByteString] -> ByteString
+plainMixedOutput metadata parts = BS.concat (Footer.parquetMagic : parts ++ [Footer.writeFooter metadata])
+
+
+-- | Nullable/required columns with fresh random encryption nonces.
+encodeParquetMixedIO
+  :: RNG.MonadRandom m
+  => WriteOptions
+  -> V.Vector SchemaElement
+  -> [V.Vector ParquetColumn]
+  -> m (Either String ByteString)
+encodeParquetMixedIO opts schema rgs =
+  case validateCompression (writeCompression opts) >> validateWriteEncryption opts schema of
+    Left err -> pure (Left err)
+    Right () ->
+      let plainOptions = withoutEncryption opts
+          groups = V.fromList rgs
+          makeAuxes = V.map (mkAuxes plainOptions schema)
+      in case writeFooterEncryption opts of
+           Nothing -> pure (buildParquetFileMixedWithAuxUsing plainMixedOutput schema groups makeAuxes)
+           Just footer ->
+             finishWriterOutput footer opts $
+               buildParquetFileMixedWithAuxUsing (\metadata parts -> Encrypted.WriterOutput metadata (BS.concat (Footer.parquetMagic : parts))) schema groups makeAuxes
+
+
+encryptionRequested :: WriteOptions -> Bool
+encryptionRequested opts =
+  writeFooterMode opts == SignedPlaintextFooter
+    || maybe False (const True) (writeFooterEncryption opts)
+    || V.any (maybe False (const True)) (writeColumnEncryption opts)
+
+
+{- | Compute a 'ColumnAux' vector per row group from the
+write-time options.
+
+Compression + page version are applied uniformly to every
+column. Bloom filters are built per-column for the leaves
+whose names appear in 'writeBloomFilters' — the writer hashes
+each value's PLAIN payload into a fresh 'Sbbf' sized for the
+column's row count so a downstream reader can probe membership
+via 'Parquet.Predicate.evalBloomChunk' without false
+negatives.
+-}
+mkAuxes
+  :: WriteOptions
+  -> V.Vector SchemaElement
+  -> V.Vector ColumnData
+  -> V.Vector ColumnAux
+mkAuxes opts schema cols =
+  let !bloomNames = writeBloomFilters opts
+      bloomIdxs =
+        foldr (\name indices -> maybe indices (: indices) (leafColumnIndex schema name)) [] bloomNames
+      bloomSet = bloomIdxs
+  in V.imap (\i col -> mkOne i col bloomSet) cols
+  where
+    mkOne :: Int -> ColumnData -> [Int] -> ColumnAux
+    mkOne i col blooms =
+      emptyColumnAux
+        { caCodec = writeCompression opts
+        , caEncryption = maybe Nothing id (writeColumnEncryption opts V.!? i)
+        , caGeneratePageIndex = writePageIndex opts
+        , caPageVersion = writePageVersion opts
+        , caBloomFilter =
+            if i `elem` blooms
+              then Just $! buildBloomFilterFor col
+              else Nothing
+        }
+
+
+-- Check the requested configuration even for an empty dataset. Building aux
+-- metadata from zero row groups cannot detect a truncated key vector or a
+-- missing encrypted footer on its own.
+validateWriteEncryption :: WriteOptions -> V.Vector SchemaElement -> Either String ()
+validateWriteEncryption opts schema
+  | not (V.null columns) && V.length columns /= V.length leaves = Left "Parquet.HighLevel: column encryption vector must match the leaf-column count"
+  | writeFooterMode opts == SignedPlaintextFooter && writeFooterEncryption opts == Nothing = Left "Parquet.HighLevel: signed plaintext footer requires a signing key"
+  | otherwise = do
+      case writeFooterEncryption opts of
+        Nothing -> Right ()
+        Just footer
+          | BS.length (feKey footer) `notElem` [16,24,32] -> Left "Parquet.HighLevel: AES key must contain 16, 24, or 32 bytes"
+          | BS.null (feFileId footer) -> Left "Parquet.HighLevel: footer requires a fresh random file identifier"
+          | otherwise -> Right ()
+      V.imapM_ check columns
+  where
+    columns = writeColumnEncryption opts
+    leaves = V.filter (maybe False (const True) . seType) schema
+    algorithm =
+      V.foldl'
+        ( \found entry -> case found of
+            Just _ -> found
+            Nothing -> ceAlgorithm <$> entry
+        )
+        Nothing
+        columns
+    check _ Nothing = Right ()
+    check index (Just column)
+      | index > 32767 = Left "Parquet.HighLevel: encrypted column ordinal exceeds signed 16-bit range"
+      | BS.length (ceKey column) `notElem` [16, 24, 32] = Left "Parquet.HighLevel: AES key must contain 16, 24, or 32 bytes"
+      | otherwise = case writeFooterEncryption opts of
+          Nothing -> Left "Parquet.HighLevel: encrypted columns require an encrypted footer"
+          Just footer
+            | ceFileId column /= feFileId footer || ceAadPrefix column /= feAadPrefix footer -> Left "Parquet.HighLevel: column and footer AAD contexts must match"
+            | Just (ceAlgorithm column) /= algorithm -> Left "Parquet.HighLevel: encrypted columns must share one file-level algorithm"
+            | otherwise -> Right ()
+
+
+{- | Build a split-block bloom filter populated from a column's
+values. Sizes the filter via 'Bloom.optimalNumBytes' for the
+column's row count at a 1% false-positive rate (parquet-cpp's
+default), then inserts each value's PLAIN-encoded payload —
+matching what 'Parquet.Predicate.encodePlain' probes with on
+the read side.
+-}
+buildBloomFilterFor :: ColumnData -> Bloom.Sbbf
+buildBloomFilterFor col =
+  let !ndv = max 1 (columnDistinctEstimate col)
+      !nBytes = Bloom.optimalNumBytes ndv 0.01
+      !empty0 = Bloom.newSbbf nBytes
+  in case col of
+       ColInt32 v ->
+         VP.foldl' (\acc x -> Bloom.sbbfInsert (i32LE x) acc) empty0 v
+       ColInt64 v ->
+         VP.foldl' (\acc x -> Bloom.sbbfInsert (i64LE x) acc) empty0 v
+       ColFloat v ->
+         VP.foldl' (\acc x -> Bloom.sbbfInsert (f32LE x) acc) empty0 v
+       ColDouble v ->
+         VP.foldl' (\acc x -> Bloom.sbbfInsert (f64LE x) acc) empty0 v
+       ColBool v ->
+         V.foldl' (\acc x -> Bloom.sbbfInsert (boolPayload x) acc) empty0 v
+       ColByteArray v ->
+         V.foldl' (\acc x -> Bloom.sbbfInsert x acc) empty0 v
+
+
+{- | Cheap distinct-value upper bound: row count. Real
+distinct-counting would need a second pass; sizing for the
+worst case (all-distinct) keeps the filter slightly oversize
+but never underfilled.
+-}
+columnDistinctEstimate :: ColumnData -> Int
+columnDistinctEstimate = \case
+  ColInt32 v -> VP.length v
+  ColInt64 v -> VP.length v
+  ColFloat v -> VP.length v
+  ColDouble v -> VP.length v
+  ColBool v -> V.length v
+  ColByteArray v -> V.length v
+
+
+{- | PLAIN encodings used for bloom-filter inserts. These must
+match 'Parquet.Predicate.encodePlain' byte-for-byte so a
+@PEq@ predicate hashes to the same key.
+-}
+i32LE :: Int32 -> ByteString
+i32LE = BL.toStrict . B.toLazyByteString . B.int32LE
+
+
+i64LE :: Int64 -> ByteString
+i64LE = BL.toStrict . B.toLazyByteString . B.int64LE
+
+
+f32LE :: Float -> ByteString
+f32LE f = BL.toStrict (B.toLazyByteString (B.word32LE (castFloatToWord32 f)))
+
+
+f64LE :: Double -> ByteString
+f64LE d = BL.toStrict (B.toLazyByteString (B.word64LE (castDoubleToWord64 d)))
+
+
+boolPayload :: Bool -> ByteString
+boolPayload True = TE.encodeUtf8 "\x01"
+boolPayload False = TE.encodeUtf8 "\x00"
+
+
+-- | Nested records with random module nonces, per-leaf keys and either
+-- encrypted or signed plaintext footer. Pure nested writing remains available
+-- through 'encodeParquetNestedWith' when encryption is not requested.
+encodeParquetNestedIO
+  :: RNG.MonadRandom m
+  => WriteOptions
+  -> V.Vector (Text, NestedSchema)
+  -> V.Vector (V.Vector NestedRow)
+  -> m (Either String ByteString)
+encodeParquetNestedIO opts columns rows =
+  case validateCompression (writeCompression opts) >> validateWriteEncryption opts schema of
+    Left err -> pure (Left err)
+    Right () -> case writeFooterEncryption opts of
+      Nothing -> pure (encodeParquetNestedWith (withoutEncryption opts) columns rows)
+      Just footer ->
+        let leaves = V.foldl' (\count field -> count + maybe 0 (const 1) (seType field)) 0 schema
+            aux = emptyColumnAux {caCodec = writeCompression opts, caPageVersion = writePageVersion opts, caGeneratePageIndex = writePageIndex opts}
+        in finishWriterOutput footer opts $
+             buildNestedFileWithBloomFiltersUsing Encrypted.nestedWriterOutput (writeBloomFilters opts) (V.replicate leaves aux) columns rows
+  where
+    schema = nestedSchemaToFlatSchema columns
+
+
+-- ============================================================
+-- Decoding
+-- ============================================================
+
+{- | Serialise a Parquet file carrying /nested/ (struct / list /
+map / variant) columns. Delegates to 'Parquet.Nested.buildNestedFile'
+after the Dremel shredder in "Parquet.Nested".
+
+@columns@ is a vector of @(column-name, schema)@ pairs;
+@rowsPerColumn@ is a parallel vector where the i-th entry is
+the row-major list of 'NestedRow' values for column @i@. Every
+column must carry the same number of rows.
+
+This entry point retains the original uncompressed @DATA_PAGE_V2@
+layout. Use 'encodeParquetNestedWith' to select compression, page version
+and indexes with 'WriteOptions', or 'encodeParquetNestedIO' for encryption.
+-}
+encodeParquetNested
+  :: V.Vector (Text, NestedSchema)
+  -> V.Vector (V.Vector NestedRow)
+  -> Either String ByteString
+encodeParquetNested = buildNestedFile
+
+
+{- | Nested writing with compression, page version and generated indexes.
+The existing 'encodeParquetNested' retains its uncompressed V2 defaults.
+Names in 'writeBloomFilters' select top-level fields and populate every
+physical leaf below them. Unknown names return 'Left'. Encryption uses
+'encodeParquetNestedIO'. Pre-built per-leaf filters and explicit indexes are available
+through 'buildNestedFileWithAux'.
+-}
+encodeParquetNestedWith
+  :: WriteOptions
+  -> V.Vector (Text, NestedSchema)
+  -> V.Vector (V.Vector NestedRow)
+  -> Either String ByteString
+encodeParquetNestedWith opts columns rows
+  | encryptionRequested opts = Left "Parquet.HighLevel: nested encryption requires an IO writer"
+  | otherwise =
+      let schema = nestedSchemaToFlatSchema columns
+          leaves = V.length (V.filter (maybe False (const True) . seType) schema)
+          aux = emptyColumnAux {caCodec = writeCompression opts, caPageVersion = writePageVersion opts, caGeneratePageIndex = writePageIndex opts}
+      in buildNestedFileWithBloomFilters (writeBloomFilters opts) (V.replicate leaves aux) columns rows
+
+
+-- ============================================================
+-- Decoding
+-- ============================================================
+
+{- | Parquet reader configuration. Construct one with
+'defaultReadOptions' and override the fields you care about.
+
+@
+let opts = 'defaultReadOptions'
+            { readFooterDecryption = Just ('FooterDecryption' key fileId prefix) }
+'decodeParquet' opts bytes
+@
+-}
+data ReadOptions = ReadOptions
+  { readFooterDecryption :: !(Maybe FooterDecryption)
+  {- ^ When 'Just', authenticate an encrypted footer (PARE) or a signed
+  plaintext footer (PAR1) with the supplied key, file identifier and AAD
+  prefix. Ordinary unsigned files are also accepted. When 'Nothing'
+  (the default), a plaintext footer is parsed without signature verification.
+  -}
+  , readDecryptionConfig :: !(Maybe DecryptionConfig)
+  -- ^ Full file/column key routing. Do not also set 'readFooterDecryption'.
+  }
+  deriving (Show, Eq)
+
+
+-- | Plaintext-footer defaults (matches the common case).
+defaultReadOptions :: ReadOptions
+defaultReadOptions =
+  ReadOptions
+    { readFooterDecryption = Nothing
+    , readDecryptionConfig = Nothing
+    }
+
+
+{- | Parse a Parquet file's footer. By default expects a
+plaintext PAR1 footer without signature verification; pass
+'readFooterDecryption' in 'ReadOptions' to decrypt a PARE footer or
+authenticate a signed plaintext footer and read footer-key columns. Use
+'readDecryptionConfig' for column-specific keys and opaque key-metadata routing.
+
+@
+-- plaintext
+'decodeParquet' 'defaultReadOptions' bytes
+
+-- encrypted footer
+'decodeParquet'
+  'defaultReadOptions' { 'readFooterDecryption' = Just fd }
+  bytes
+@
+-}
+decodeParquet :: ReadOptions -> ByteString -> Either String ParquetFile
+decodeParquet opts bytes = do
+  file <- case (readDecryptionConfig opts, readFooterDecryption opts) of
+    (Nothing, Nothing) -> loadParquetFile bytes
+    (Nothing, Just fd) -> loadParquetFileEncrypted fd bytes
+    (Just config, Nothing) -> loadParquetFileWithDecryption config bytes
+    (Just _, Just _) -> Left "Parquet.HighLevel: set only one decryption configuration"
+  _ <- Arrow.parquetFileArrowSchemaChecked file
+  Right file
diff --git a/src/Parquet/Levels.hs b/src/Parquet/Levels.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Levels.hs
@@ -0,0 +1,903 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | Parquet definition / repetition levels for data page v1.
+
+Data page v1 layout (uncompressed body): repetition levels (if @max repetition > 0@),
+then definition levels (if @max definition > 0@), then encoded values (@PLAIN@, etc.).
+Each level column is length-prefixed hybrid RLE (see @Parquet.RLE@).
+
+Use 'maxLevelsForColumnPath' with footer schema + 'ColumnMetadata' path to obtain
+@maxRep@ / @maxDef@ for a leaf column.
+-}
+module Parquet.Levels (
+  levelBitWidth,
+  maxLevelsForColumnPath,
+  parseDataPageV1Levels,
+  parseDataPageV1LevelsWithEncoding,
+  materializePlainInt32Optional,
+  materializePlainInt64Optional,
+  materializePlainFloatOptional,
+  materializePlainDoubleOptional,
+  materializePlainBoolOptional,
+  materializePlainByteArrayOptional,
+  materializeRepeatedInt32,
+  materializeRepeatedInt64,
+  materializeRepeatedFloat,
+  materializeRepeatedDouble,
+  materializeRepeatedByteArray,
+  materializeRepeatedByNested,
+  NestedValue (..),
+) where
+
+import Data.Bits (countLeadingZeros, finiteBitSize, shiftL, shiftR, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int32, Int64)
+import Data.Text (Text)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Word (Word32, Word64)
+import GHC.Float (castWord32ToFloat, castWord64ToDouble)
+import Parquet.RLE (decodeHybridRleUnsigned32)
+import Parquet.Types (Repetition (..), SchemaElement (..))
+
+
+{- | Bits required to store any level in @[0 .. maxLevel]@. Returns @0@ when
+@maxLevel == 0@ (no level data on disk for that column).
+-}
+levelBitWidth :: Int -> Int
+levelBitWidth maxLevel
+  | maxLevel <= 0 = 0
+  | otherwise = finiteBitSize maxLevel - countLeadingZeros maxLevel
+
+
+readLE32 :: ByteString -> Int -> Word32
+readLE32 bs o =
+  let b0 = fromIntegral (BS.index bs o) :: Word32
+      b1 = fromIntegral (BS.index bs (o + 1)) :: Word32
+      b2 = fromIntegral (BS.index bs (o + 2)) :: Word32
+      b3 = fromIntegral (BS.index bs (o + 3)) :: Word32
+  in b0 .|. (b1 `shiftL` 8) .|. (b2 `shiftL` 16) .|. (b3 `shiftL` 24)
+
+
+readLE64 :: ByteString -> Int -> Word64
+readLE64 bs o =
+  let w0 = fromIntegral (readLE32 bs o) :: Word64
+      w1 = fromIntegral (readLE32 bs (o + 4)) :: Word64
+  in w0 .|. (w1 `shiftL` 32)
+
+
+{-# INLINE readBitLsb #-}
+readBitLsb :: ByteString -> Int -> Bool
+readBitLsb bs bitIdx =
+  let bi = bitIdx `quot` 8
+      ii = bitIdx `rem` 8
+      b = BS.index bs bi
+  in (b `shiftR` ii) .&. 1 /= 0
+
+
+{- | Decode one length-prefixed hybrid level stream starting at @off@.
+Returns decoded levels and the offset immediately after this stream.
+-}
+decodeLengthPrefixedHybrid
+  :: Int
+  -> Int
+  -> ByteString
+  -> Int
+  -> Either String (VP.Vector Int32, Int)
+decodeLengthPrefixedHybrid bw n bs off
+  | bw == 0 =
+      if n < 0
+        then Left "Parquet.Levels: negative value count for level stream"
+        else Right (VP.replicate n 0, off)
+  | off + 4 > BS.length bs =
+      Left "Parquet.Levels: truncated level length prefix"
+  | otherwise =
+      let !len = fromIntegral (readLE32 bs off) :: Int
+          !rest = BS.drop (off + 4) bs
+      in if len < 0 || len > BS.length rest
+           then Left "Parquet.Levels: invalid level slice length"
+           else case decodeHybridRleUnsigned32 bw n (BS.take len rest) of
+             Left e -> Left e
+             Right v -> Right (v, off + 4 + len)
+
+
+{- | Split an uncompressed data page v1 body into repetition levels, definition
+levels, and the remaining payload (e.g. @PLAIN@ values).
+
+When @maxRep@ or @maxDef@ is @0@, the corresponding vector is all zeros and no
+bytes are consumed for that stream (Parquet omits zero-bit-width level data).
+-}
+parseDataPageV1Levels
+  :: Int
+  -> Int
+  -> Int
+  -> ByteString
+  -> Either String (VP.Vector Int32, VP.Vector Int32, ByteString)
+parseDataPageV1Levels maxRep maxDef numValues raw = do
+  let !bwRep = levelBitWidth maxRep
+      !bwDef = levelBitWidth maxDef
+  (rep, off1) <- decodeLengthPrefixedHybrid bwRep numValues raw 0
+  (def, off2) <- decodeLengthPrefixedHybrid bwDef numValues raw off1
+  let !rest = BS.drop off2 raw
+  pure (rep, def, rest)
+
+
+{- | Legacy BIT_PACKED levels use MSB-first bits with neither a length
+prefix nor hybrid run headers. Modern RLE levels retain their prefix.
+-}
+parseDataPageV1LevelsWithEncoding
+  :: Int32
+  -> Int32
+  -> Int
+  -> Int
+  -> Int
+  -> ByteString
+  -> Either String (VP.Vector Int32, VP.Vector Int32, ByteString)
+parseDataPageV1LevelsWithEncoding _ _ maxRep maxDef numValues _
+  | maxRep < 0
+      || maxDef < 0
+      || maxRep > maxDef
+      || numValues < 0
+      || toInteger numValues > toInteger (maxBound :: Int32)
+      || toInteger maxDef > toInteger (maxBound :: Int32) =
+      Left "Parquet.Levels: invalid level limits or value count"
+parseDataPageV1LevelsWithEncoding repEncoding defEncoding maxRep maxDef numValues raw = do
+  (rep, next) <- levels repEncoding maxRep 0
+  (def, end) <- levels defEncoding maxDef next
+  Right (rep, def, BS.drop end raw)
+  where
+    levels encoding maximum off
+      | maximum == 0 = Right (VP.replicate numValues 0, off)
+      | encoding == 3 = decodeLengthPrefixedHybrid (levelBitWidth maximum) numValues raw off
+      | encoding == 4 =
+          let width = levelBitWidth maximum
+              bytes = (toInteger numValues * toInteger width + 7) `quot` 8
+          in if bytes > toInteger (BS.length raw - off)
+               then Left "Parquet.Levels: truncated BIT_PACKED levels"
+               else
+                 Right
+                   ( VP.generate
+                       numValues
+                       ( \i ->
+                           let (group, lane) = i `quotRem` 8
+                           in readValue width (off + group * width) (lane * width)
+                       )
+                   , off + fromInteger bytes
+                   )
+      | otherwise = Left "Parquet.Levels: unsupported level encoding"
+    readValue width off start = go 0 0
+      where
+        go !bit !acc
+          | bit == width = acc
+          | otherwise =
+              let position = start + bit
+                  byte = BS.index raw (off + position `quot` 8)
+                  value = fromIntegral ((byte `shiftR` (7 - position `rem` 8)) .&. 1)
+              in go (bit + 1) ((acc `shiftL` 1) .|. value)
+
+
+{- | Map @PLAIN@ packed @INT32@ values using Parquet definition levels: rows with
+@def == maxDef@ consume the next four bytes; nulls use @def \< maxDef@.
+-}
+materializePlainInt32Optional
+  :: VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (Maybe Int32))
+materializePlainInt32Optional defs maxDef plain
+  | maxDef < 0 = Left "Parquet.Levels: negative max definition level"
+  | otherwise =
+      let n = VP.length defs
+          needPresent =
+            VP.foldl'
+              ( \a v ->
+                  if v == fromIntegral maxDef then a + 1 else a
+              )
+              0
+              defs
+          needBytes = needPresent * 4
+          go !acc !i !off
+            | i >= n =
+                if off == needBytes
+                  then Right acc
+                  else
+                    Left $
+                      "Parquet.Levels: unconsumed PLAIN bytes: "
+                        ++ show (needBytes - off)
+            | otherwise =
+                let !d = VP.unsafeIndex defs i
+                    !maxD = fromIntegral maxDef :: Int32
+                in if d > maxD || d < 0
+                     then
+                       Left $
+                         "Parquet.Levels: definition level out of range: "
+                           ++ show d
+                     else
+                       if d == maxD
+                         then
+                           let !v = fromIntegral (readLE32 plain off) :: Int32
+                           in go (Just v : acc) (i + 1) (off + 4)
+                         else go (Nothing : acc) (i + 1) off
+      in if BS.length plain < needBytes
+           then
+             Left $
+               "Parquet.Levels: PLAIN INT32 buffer too small for "
+                 ++ show needPresent
+                 ++ " defined values"
+           else case go [] 0 0 of
+             Left e -> Left e
+             Right xs -> Right $! V.fromList (reverse xs)
+
+
+-- | @PLAIN@ @INT64@ (8-byte LE per defined value).
+materializePlainInt64Optional
+  :: VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (Maybe Int64))
+materializePlainInt64Optional defs maxDef plain
+  | maxDef < 0 = Left "Parquet.Levels: negative max definition level"
+  | otherwise =
+      let n = VP.length defs
+          needPresent =
+            VP.foldl'
+              ( \a v ->
+                  if v == fromIntegral maxDef then a + 1 else a
+              )
+              0
+              defs
+          needBytes = needPresent * 8
+          go !acc !i !off
+            | i >= n =
+                if off == needBytes
+                  then Right acc
+                  else
+                    Left $
+                      "Parquet.Levels: unconsumed PLAIN bytes: "
+                        ++ show (needBytes - off)
+            | otherwise =
+                let !d = VP.unsafeIndex defs i
+                    !maxD = fromIntegral maxDef :: Int32
+                in if d > maxD || d < 0
+                     then
+                       Left $
+                         "Parquet.Levels: definition level out of range: "
+                           ++ show d
+                     else
+                       if d == maxD
+                         then
+                           let !v = fromIntegral (readLE64 plain off) :: Int64
+                           in go (Just v : acc) (i + 1) (off + 8)
+                         else go (Nothing : acc) (i + 1) off
+      in if BS.length plain < needBytes
+           then
+             Left $
+               "Parquet.Levels: PLAIN INT64 buffer too small for "
+                 ++ show needPresent
+                 ++ " defined values"
+           else case go [] 0 0 of
+             Left e -> Left e
+             Right xs -> Right $! V.fromList (reverse xs)
+
+
+-- | @PLAIN@ @FLOAT@ (4-byte IEEE LE per defined value).
+materializePlainFloatOptional
+  :: VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (Maybe Float))
+materializePlainFloatOptional defs maxDef plain
+  | maxDef < 0 = Left "Parquet.Levels: negative max definition level"
+  | otherwise =
+      let n = VP.length defs
+          needPresent =
+            VP.foldl'
+              ( \a v ->
+                  if v == fromIntegral maxDef then a + 1 else a
+              )
+              0
+              defs
+          needBytes = needPresent * 4
+          go !acc !i !off
+            | i >= n =
+                if off == needBytes
+                  then Right acc
+                  else
+                    Left $
+                      "Parquet.Levels: unconsumed PLAIN bytes: "
+                        ++ show (needBytes - off)
+            | otherwise =
+                let !d = VP.unsafeIndex defs i
+                    !maxD = fromIntegral maxDef :: Int32
+                in if d > maxD || d < 0
+                     then
+                       Left $
+                         "Parquet.Levels: definition level out of range: "
+                           ++ show d
+                     else
+                       if d == maxD
+                         then
+                           let !w = readLE32 plain off
+                               !v = castWord32ToFloat w
+                           in go (Just v : acc) (i + 1) (off + 4)
+                         else go (Nothing : acc) (i + 1) off
+      in if BS.length plain < needBytes
+           then
+             Left $
+               "Parquet.Levels: PLAIN FLOAT buffer too small for "
+                 ++ show needPresent
+                 ++ " defined values"
+           else case go [] 0 0 of
+             Left e -> Left e
+             Right xs -> Right $! V.fromList (reverse xs)
+
+
+-- | @PLAIN@ @DOUBLE@ (8-byte IEEE LE per defined value).
+materializePlainDoubleOptional
+  :: VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (Maybe Double))
+materializePlainDoubleOptional defs maxDef plain
+  | maxDef < 0 = Left "Parquet.Levels: negative max definition level"
+  | otherwise =
+      let n = VP.length defs
+          needPresent =
+            VP.foldl'
+              ( \a v ->
+                  if v == fromIntegral maxDef then a + 1 else a
+              )
+              0
+              defs
+          needBytes = needPresent * 8
+          go !acc !i !off
+            | i >= n =
+                if off == needBytes
+                  then Right acc
+                  else
+                    Left $
+                      "Parquet.Levels: unconsumed PLAIN bytes: "
+                        ++ show (needBytes - off)
+            | otherwise =
+                let !d = VP.unsafeIndex defs i
+                    !maxD = fromIntegral maxDef :: Int32
+                in if d > maxD || d < 0
+                     then
+                       Left $
+                         "Parquet.Levels: definition level out of range: "
+                           ++ show d
+                     else
+                       if d == maxD
+                         then
+                           let !w = readLE64 plain off
+                               !v = castWord64ToDouble w
+                           in go (Just v : acc) (i + 1) (off + 8)
+                         else go (Nothing : acc) (i + 1) off
+      in if BS.length plain < needBytes
+           then
+             Left $
+               "Parquet.Levels: PLAIN DOUBLE buffer too small for "
+                 ++ show needPresent
+                 ++ " defined values"
+           else case go [] 0 0 of
+             Left e -> Left e
+             Right xs -> Right $! V.fromList (reverse xs)
+
+
+{- | @PLAIN@ @BOOLEAN@ — packed bits in definition order; only defined values
+occupy bits (LSB of first byte is first defined value).
+-}
+materializePlainBoolOptional
+  :: VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (Maybe Bool))
+materializePlainBoolOptional defs maxDef plain
+  | maxDef < 0 = Left "Parquet.Levels: negative max definition level"
+  | otherwise =
+      let n = VP.length defs
+          needBits =
+            VP.foldl'
+              ( \a v ->
+                  if v == fromIntegral maxDef then a + 1 else a
+              )
+              0
+              defs
+          needBytes = (needBits + 7) `quot` 8
+          go !acc !i !bitPos
+            | i >= n =
+                if bitPos == needBits
+                  then Right acc
+                  else
+                    Left $
+                      "Parquet.Levels: BOOLEAN bit stream incomplete: "
+                        ++ show (needBits - bitPos)
+            | otherwise =
+                let !d = VP.unsafeIndex defs i
+                    !maxD = fromIntegral maxDef :: Int32
+                in if d > maxD || d < 0
+                     then
+                       Left $
+                         "Parquet.Levels: definition level out of range: "
+                           ++ show d
+                     else
+                       if d == maxD
+                         then
+                           let !b = readBitLsb plain bitPos
+                           in go (Just b : acc) (i + 1) (bitPos + 1)
+                         else go (Nothing : acc) (i + 1) bitPos
+      in if BS.length plain < needBytes
+           then
+             Left $
+               "Parquet.Levels: PLAIN BOOLEAN buffer too small for "
+                 ++ show needBits
+                 ++ " defined bits"
+           else case go [] 0 0 of
+             Left e -> Left e
+             Right xs -> Right $! V.fromList (reverse xs)
+
+
+-- | @PLAIN@ @BYTE_ARRAY@ — per defined value: 4-byte LE length + payload.
+materializePlainByteArrayOptional
+  :: VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (Maybe ByteString))
+materializePlainByteArrayOptional defs maxDef plain
+  | maxDef < 0 = Left "Parquet.Levels: negative max definition level"
+  | otherwise =
+      let n = VP.length defs
+          go !acc !i !off
+            | i >= n =
+                if off == BS.length plain
+                  then Right acc
+                  else
+                    Left $
+                      "Parquet.Levels: trailing PLAIN BYTE_ARRAY bytes: "
+                        ++ show (BS.length plain - off)
+            | otherwise =
+                let !d = VP.unsafeIndex defs i
+                    !maxD = fromIntegral maxDef :: Int32
+                in if d > maxD || d < 0
+                     then
+                       Left $
+                         "Parquet.Levels: definition level out of range: "
+                           ++ show d
+                     else
+                       if d == maxD
+                         then
+                           if off + 4 > BS.length plain
+                             then Left "Parquet.Levels: PLAIN BYTE_ARRAY truncated length"
+                             else
+                               let !len = fromIntegral (readLE32 plain off) :: Int
+                                   !off2 = off + 4
+                               in if len < 0 || off2 + len > BS.length plain
+                                    then
+                                      Left "Parquet.Levels: PLAIN BYTE_ARRAY payload out of bounds"
+                                    else
+                                      let !payload = BS.take len (BS.drop off2 plain)
+                                      in go (Just payload : acc) (i + 1) (off2 + len)
+                         else go (Nothing : acc) (i + 1) off
+      in case go [] 0 0 of
+           Left e -> Left e
+           Right xs -> Right $! V.fromList (reverse xs)
+
+
+{- | Maximum repetition and definition levels for a leaf column identified by
+@path@ (same as 'Parquet.Types.ColumnMetadata' @path_in_schema@), from a
+preorder Parquet schema. On success: @(max repetition level, max definition level)@.
+-}
+maxLevelsForColumnPath
+  :: V.Vector SchemaElement
+  -> V.Vector Text
+  -> Either String (Int, Int)
+maxLevelsForColumnPath sch path
+  | V.null sch = Left "Parquet.Levels: empty schema"
+  | V.null path = Left "Parquet.Levels: empty path"
+  | seType (V.head sch) /= Nothing = Left "Parquet.Levels: schema root must be a group"
+  | otherwise = descend 0 (V.toList path) (0, 0)
+  where
+    descend :: Int -> [Text] -> (Int, Int) -> Either String (Int, Int)
+    descend parent remaining acc = case remaining of
+      [] -> Left "Parquet.Levels: empty path segment"
+      p : ps -> do
+        child <- findChild sch parent p
+        let element = V.unsafeIndex sch child
+        repetition <- maybe (Left "Parquet.Levels: non-root schema node is missing repetition_type") Right (seRepetition element)
+        let next = stepLevels repetition acc
+        case (seType element, seNumChildren element) of
+          (Just _, Nothing)
+            | null ps -> Right next
+            | otherwise -> Left "Parquet.Levels: path continues past primitive column"
+          (Just _, Just _) -> Left "Parquet.Levels: primitive schema node has num_children"
+          (Nothing, Nothing) -> Left "Parquet.Levels: group without num_children"
+          (Nothing, Just count)
+            | count < 0 -> Left "Parquet.Levels: negative schema child count"
+            | null ps -> Left "Parquet.Levels: path ends at group, not leaf"
+            | otherwise -> descend child ps next
+
+    stepLevels :: Repetition -> (Int, Int) -> (Int, Int)
+    stepLevels Required (!maxRep, !maxDef) = (maxRep, maxDef)
+    stepLevels Optional (!maxRep, !maxDef) = (maxRep, maxDef + 1)
+    stepLevels Repeated (!maxRep, !maxDef) = (maxRep + 1, maxDef + 1)
+
+
+-- Scan a skipped subtree iteratively. Pending nodes can never exceed the
+-- remaining schema entries, so malformed counts fail without recursion or
+-- imposing an arbitrary depth limit on this low-level path-lookup API.
+subtreeSize :: V.Vector SchemaElement -> Int -> Either String Int
+subtreeSize sch start = go start 1
+  where
+    go !index !pending
+      | pending == 0 = Right (index - start)
+      | index < 0 || index >= V.length sch = Left "Parquet.Levels: schema index out of range"
+      | otherwise = do
+          let element = V.unsafeIndex sch index
+          case seRepetition element of
+            Nothing -> Left "Parquet.Levels: non-root schema node is missing repetition_type"
+            Just _ -> Right ()
+          case (seType element, seNumChildren element) of
+            (Just _, Nothing) -> go (index + 1) (pending - 1)
+            (Just _, Just _) -> Left "Parquet.Levels: primitive schema node has num_children"
+            (Nothing, Nothing) -> Left "Parquet.Levels: group without num_children"
+            (Nothing, Just count)
+              | count < 0 || fromIntegral count > V.length sch - index - pending -> Left "Parquet.Levels: invalid schema child count"
+              | otherwise -> go (index + 1) (pending - 1 + fromIntegral count)
+
+
+-- Index of a direct child. Root repetition is deliberately ignored: common
+-- writers set it to REQUIRED even though the schema root has no parent.
+findChild :: V.Vector SchemaElement -> Int -> Text -> Either String Int
+findChild sch parent name = do
+  count <- case seNumChildren (V.unsafeIndex sch parent) of
+    Nothing -> Left "Parquet.Levels: parent is not a group"
+    Just n
+      | n < 0 || fromIntegral n > V.length sch - parent - 1 -> Left "Parquet.Levels: invalid schema child count"
+      | otherwise -> Right (fromIntegral n :: Int)
+  let go !index !remaining
+        | remaining == 0 = Left "Parquet.Levels: column path not found in schema"
+        | index >= V.length sch = Left "Parquet.Levels: schema truncated while searching children"
+        | seName (V.unsafeIndex sch index) == name = Right index
+        | otherwise = do
+            size <- subtreeSize sch index
+            go (index + size) (remaining - 1)
+  go (parent + 1) count
+
+
+{- | Materialize a repeated @INT32@ column using repetition and definition levels.
+
+@rep=0@ starts a new top-level row. Within a row, @rep>0@ continues the same
+list. @def \< maxDef@ means the list element is null.
+-}
+materializeRepeatedInt32
+  :: VP.Vector Int32
+  -> VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe Int32)))
+materializeRepeatedInt32 reps defs maxDef plain
+  | VP.length reps /= VP.length defs =
+      Left "Parquet.Levels: rep/def level count mismatch"
+  | otherwise = case goRepI32 [] [] 0 0 of
+      Left e -> Left e
+      Right (rows, _) ->
+        Right $! V.fromList (reverse (map (V.fromList . reverse) rows))
+  where
+    !n = VP.length reps
+    !maxD = fromIntegral maxDef :: Int32
+
+    goRepI32
+      :: [[Maybe Int32]]
+      -> [Maybe Int32]
+      -> Int
+      -> Int
+      -> Either String ([[Maybe Int32]], Int)
+    goRepI32 !rows !curRow !i !off
+      | i >= n =
+          let !finalRows = if null curRow then rows else curRow : rows
+          in Right (finalRows, off)
+      | otherwise =
+          let !r = VP.unsafeIndex reps i
+              !d = VP.unsafeIndex defs i
+              !rows' =
+                if r == 0
+                  then if null curRow then rows else curRow : rows
+                  else rows
+              !row' = if r == 0 then [] else curRow
+          in if d == maxD
+               then
+                 if off + 4 > BS.length plain
+                   then Left "Parquet.Levels: PLAIN INT32 buffer too small for repeated column"
+                   else
+                     let !v = fromIntegral (readLE32 plain off) :: Int32
+                     in goRepI32 rows' (Just v : row') (i + 1) (off + 4)
+               else goRepI32 rows' (Nothing : row') (i + 1) off
+
+
+-- | Materialize a repeated @BYTE_ARRAY@ column using repetition and definition levels.
+materializeRepeatedByteArray
+  :: VP.Vector Int32
+  -> VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe ByteString)))
+materializeRepeatedByteArray reps defs maxDef plain
+  | VP.length reps /= VP.length defs =
+      Left "Parquet.Levels: rep/def level count mismatch"
+  | otherwise = case goRepBA [] [] 0 0 of
+      Left e -> Left e
+      Right (rows, _) ->
+        Right $! V.fromList (reverse (map (V.fromList . reverse) rows))
+  where
+    !n = VP.length reps
+    !maxD = fromIntegral maxDef :: Int32
+
+    goRepBA
+      :: [[Maybe ByteString]]
+      -> [Maybe ByteString]
+      -> Int
+      -> Int
+      -> Either String ([[Maybe ByteString]], Int)
+    goRepBA !rows !curRow !i !off
+      | i >= n =
+          let !finalRows = if null curRow then rows else curRow : rows
+          in Right (finalRows, off)
+      | otherwise =
+          let !r = VP.unsafeIndex reps i
+              !d = VP.unsafeIndex defs i
+              !rows' =
+                if r == 0
+                  then if null curRow then rows else curRow : rows
+                  else rows
+              !row' = if r == 0 then [] else curRow
+          in if d == maxD
+               then
+                 if off + 4 > BS.length plain
+                   then Left "Parquet.Levels: BYTE_ARRAY truncated length for repeated column"
+                   else
+                     let !len = fromIntegral (readLE32 plain off) :: Int
+                         !off2 = off + 4
+                     in if len < 0 || off2 + len > BS.length plain
+                          then Left "Parquet.Levels: BYTE_ARRAY payload out of bounds for repeated column"
+                          else
+                            let !val = BS.take len (BS.drop off2 plain)
+                            in goRepBA rows' (Just val : row') (i + 1) (off2 + len)
+               else goRepBA rows' (Nothing : row') (i + 1) off
+
+
+-- | Materialize a repeated @INT64@ column using repetition and definition levels.
+materializeRepeatedInt64
+  :: VP.Vector Int32
+  -> VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe Int64)))
+materializeRepeatedInt64 =
+  materializeFixedWidth 8 decodeI64
+  where
+    decodeI64 !bs !off = fromIntegral (readLE64 bs off) :: Int64
+
+
+-- | Materialize a repeated @FLOAT@ column using repetition and definition levels.
+materializeRepeatedFloat
+  :: VP.Vector Int32
+  -> VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe Float)))
+materializeRepeatedFloat =
+  materializeFixedWidth 4 (\bs off -> castWord32ToFloat (readLE32 bs off))
+
+
+-- | Materialize a repeated @DOUBLE@ column using repetition and definition levels.
+materializeRepeatedDouble
+  :: VP.Vector Int32
+  -> VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe Double)))
+materializeRepeatedDouble =
+  materializeFixedWidth 8 (\bs off -> castWord64ToDouble (readLE64 bs off))
+
+
+{- | Fixed-width primitive repeated materialiser. Walks rep/def
+levels row-grouped and lifts the fixed-size on-disk slice at
+@off@ via @decode bs off@ when @d == maxDef@.
+-}
+materializeFixedWidth
+  :: Int
+  -> (ByteString -> Int -> a)
+  -> VP.Vector Int32
+  -> VP.Vector Int32
+  -> Int
+  -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe a)))
+materializeFixedWidth !w decode reps defs maxDef plain
+  | VP.length reps /= VP.length defs =
+      Left "Parquet.Levels: rep/def level count mismatch"
+  | otherwise = case go [] [] 0 0 of
+      Left e -> Left e
+      Right (rows, _) ->
+        Right $! V.fromList (reverse (map (V.fromList . reverse) rows))
+  where
+    !n = VP.length reps
+    !maxD = fromIntegral maxDef :: Int32
+
+    go !rows !curRow !i !off
+      | i >= n =
+          let !finalRows = if null curRow then rows else curRow : rows
+          in Right (finalRows, off)
+      | otherwise =
+          let !r = VP.unsafeIndex reps i
+              !d = VP.unsafeIndex defs i
+              !rows' =
+                if r == 0
+                  then if null curRow then rows else curRow : rows
+                  else rows
+              !row' = if r == 0 then [] else curRow
+          in if d == maxD
+               then
+                 if off + w > BS.length plain
+                   then Left "Parquet.Levels: PLAIN buffer too small for repeated column"
+                   else
+                     let !v = decode plain off
+                     in go rows' (Just v : row') (i + 1) (off + w)
+               else go rows' (Nothing : row') (i + 1) off
+
+
+{- | Decode a column with arbitrary repetition depth (i.e. nested
+@LIST<LIST<…<T>>>@) using the standard Dremel reconstruction
+algorithm. Returns one 'NestedValue' tree per top-level row.
+
+The parameter @maxRep@ is the maximum repetition level (number of
+nested @LIST@ wrappers). A @rep == 0@ marker starts a new
+top-level row; @rep == k@ starts a new sibling at depth @k@.
+
+@
+  maxRep = 2
+  reps  = 0 2 1 2 0 1
+  defs  = 2 2 2 2 2 2   (all present, maxDef == 2)
+  →
+  row 0 = [ [v0, v1], [v2, v3] ]
+  row 1 = [ [v4],     [v5]      ]   -- second top-level row
+@
+
+The caller supplies a per-leaf decoder that lifts one on-disk
+value to a @Maybe a@ and returns the advanced offset. A
+non-maximal definition level produces a 'NVLeaf' @Nothing@ at
+the appropriate depth (Dremel's null-with-shape semantics).
+-}
+materializeRepeatedByNested
+  :: VP.Vector Int32
+  -> VP.Vector Int32
+  -> Int
+  -- ^ maxDef
+  -> Int
+  -- ^ maxRep
+  -> ByteString
+  -> (ByteString -> Int -> Either String (a, Int))
+  -- ^ per-leaf decoder
+  -> Either String (V.Vector (NestedValue a))
+materializeRepeatedByNested reps defs maxDef maxRep plain leafDecode
+  | VP.length reps /= VP.length defs =
+      Left "Parquet.Levels: rep/def level count mismatch"
+  | maxRep < 0 =
+      Left "Parquet.Levels: negative maxRep"
+  | VP.null reps = Right V.empty
+  | otherwise = go 0 0 []
+  where
+    !n = VP.length reps
+    !maxD = fromIntegral maxDef :: Int32
+
+    -- Decode the leaf at cursor @i@ given the on-disk @off@. When
+    -- @def < maxDef@ the row position contains a NULL (no value
+    -- bytes consumed); the returned 'NestedValue' is then 'NVLeaf
+    -- Nothing' at the depth implied by 'def'.
+    decodeLeaf !off !i = do
+      let !d = VP.unsafeIndex defs i
+      if d == maxD
+        then do
+          (v, off') <- leafDecode plain off
+          Right (NVLeaf (Just v), off')
+        else Right (NVLeaf Nothing, off)
+
+    -- Top-level driver. Accumulates rows into 'rev' (in reverse).
+    -- @off@ is the current decoder position into @plain@; @i@ is
+    -- the current rep/def cursor.
+    go !off !i rev
+      | i >= n = Right (V.fromList (reverse rev))
+      | otherwise = do
+          (row, off', i') <- consumeRow off i
+          go off' i' (row : rev)
+
+    -- Read one top-level row, returning a 'NestedValue' tree.
+    consumeRow !off !i = do
+      -- A row always starts at rep == 0; skip the check for the
+      -- first item so callers can pass the initial cursor cleanly.
+      let !d = VP.unsafeIndex defs i
+      (leaf, off1) <- decodeLeaf off i
+      buildRow off1 (i + 1) (singletonAtDepth maxRep leaf (fromIntegral d))
+
+    -- @i@ is the cursor for the NEXT triple; @acc@ is the row
+    -- built so far (a NestedValue tree that grows to the right).
+    -- Continue while @rep > 0@ — that means "still in this row".
+    buildRow !off !i acc
+      | i >= n = Right (acc, off, i)
+      | VP.unsafeIndex reps i == 0 = Right (acc, off, i)
+      | otherwise = do
+          let !d = VP.unsafeIndex defs i
+              !r = fromIntegral (VP.unsafeIndex reps i) :: Int
+          (leaf, off1) <- decodeLeaf off i
+          let !acc' = appendAtDepth maxRep r (fromIntegral d) leaf acc
+          buildRow off1 (i + 1) acc'
+
+
+{- | Build the initial single-leaf row value: wrap @leaf@ in
+@maxRep@ list layers so the leaf lands at the innermost
+position.
+
+Nuance: a row with @def \< maxDef@ in a nested column actually
+represents an /empty list/ or /null at some intermediate level/
+— Dremel's def-level encoding distinguishes those cases — but
+the standard Parquet/Dremel reconstruction requires you to look
+at @def@ relative to the schema's nullable layers. For now we
+always emit a fully-nested singleton; callers that need the
+empty-list case should consult the def stream directly.
+-}
+singletonAtDepth :: Int -> NestedValue a -> Int -> NestedValue a
+singletonAtDepth !depth !leaf !_def = wrapLists depth leaf
+
+
+{- | Append a new leaf to an existing nested value tree at the
+specified rep depth. The leaf is wrapped so its physical depth
+under the row root is @maxRep@ (i.e. it lands as an innermost-
+list element). The /append point/ is at depth @rep@ of the
+existing tree:
+
+  * @rep == maxRep@: descend to the innermost list and append
+    the bare leaf as a new sibling.
+  * @rep == maxRep-1@: descend one level less and append a /new
+    innermost list containing the leaf/.
+  * In general: descend @rep - 1@ list layers (rightmost child
+    each time), then append a new node of depth @maxRep - rep@
+    to that list.
+-}
+appendAtDepth :: Int -> Int -> Int -> NestedValue a -> NestedValue a -> NestedValue a
+appendAtDepth !maxRep !rep !_def !leaf !tree =
+  goDescend (rep - 1) tree
+  where
+    -- The new sibling we'll attach: leaf wrapped in @(maxRep - rep)@
+    -- list layers so its leaf depth becomes @maxRep@.
+    !newSibling = wrapLists (maxRep - rep) leaf
+
+    -- Descend @k@ list layers from the current node (rightmost
+    -- child each time), then append @newSibling@ to that list.
+    goDescend !k node = case node of
+      NVList xs
+        | k <= 0 -> NVList (xs ++ [newSibling])
+        | otherwise -> case reverse xs of
+            (lastChild : revInit) ->
+              NVList (reverse revInit ++ [goDescend (k - 1) lastChild])
+            [] -> NVList [newSibling]
+      NVLeaf _ ->
+        -- Shouldn't happen if maxRep > 0 and the row was started
+        -- correctly, but be defensive.
+        NVList [node, newSibling]
+
+
+-- | Wrap a value in @k@ singleton lists.
+wrapLists :: Int -> NestedValue a -> NestedValue a
+wrapLists !k v
+  | k <= 0 = v
+  | otherwise = NVList [wrapLists (k - 1) v]
+
+
+{- | A nested value: either a leaf (possibly null) or a list of
+children. The caller's row is one 'NestedValue' per top-level
+column entry.
+-}
+data NestedValue a
+  = NVLeaf !(Maybe a)
+  | NVList ![NestedValue a]
+  deriving stock (Show, Eq)
diff --git a/src/Parquet/LevelsEncode.hs b/src/Parquet/LevelsEncode.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/LevelsEncode.hs
@@ -0,0 +1,414 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Encoder side of Parquet's hybrid RLE / bit-packed streams.
+
+Repeated spans use RLE; other inputs use bit-packed groups of eight,
+with zero padding only in the final group. Runs are split at the format's
+signed 32-bit value-count limit.
+
+A 'HybridPlan' validates values and measures the encoded bytes without
+allocating a payload. Page writers can reject a size limit before encoding.
+-}
+module Parquet.LevelsEncode (
+  encodeLengthPrefixedHybrid,
+  encodeRLEHybrid,
+  bitWidthFor,
+  HybridPlan,
+  planRLEHybrid,
+  planRepeatedRLEHybrid,
+  hybridEncodedSize,
+  encodeHybridPlan,
+) where
+
+import Data.Bits (shiftL, shiftR, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int32)
+import Data.Primitive.ByteArray (copyByteArrayToAddr)
+import Data.Vector.Primitive qualified as VP
+import Data.Word (Word32, Word64, Word8, byteSwap32, byteSwap64)
+import Foreign.Ptr (Ptr, plusPtr)
+import GHC.ByteOrder (ByteOrder (..), targetByteOrder)
+import GHC.Exts (Int (I#), Int#, RealWorld, State#)
+import GHC.IO (IO (..))
+import Wireform.Encode.Direct qualified as Direct
+
+
+-- | Bits required for values in [0, n]. Negative maxima are invalid.
+bitWidthFor :: Int -> Int
+bitWidthFor n
+  | n < 0 = error "Parquet.LevelsEncode: negative maximum value"
+  | otherwise = go 0 n
+  where
+    go !width 0 = width
+    go !width remaining = go (width + 1) (shiftR remaining 1)
+
+
+data HybridBody
+  = EmptyHybrid
+  | RepeatedHybrid {-# UNPACK #-} !Int {-# UNPACK #-} !Word32
+  | PackedHybrid !(VP.Vector Int32)
+  | MixedHybrid !(VP.Vector Int32) {-# UNPACK #-} !Int
+
+
+{- | A validated, exactly sized encoding. Constructors remain private so
+encoding cannot bypass the range and address-space checks.
+-}
+data HybridPlan = HybridPlan
+  { hybridWidth :: {-# UNPACK #-} !Int
+  , hybridEncodedSize :: {-# UNPACK #-} !Int
+  , hybridBody :: !HybridBody
+  }
+
+
+maxRepeatedValues :: Int
+maxRepeatedValues = 0x7fffffff
+
+
+-- A packed header counts groups; the limit applies to values, not groups.
+maxPackedGroups :: Int
+maxPackedGroups = 0x0fffffff
+
+
+widthMask :: Int -> Either String Word32
+widthMask width
+  | width < 0 || width > 32 = Left "Parquet.LevelsEncode: bit width out of range"
+  | otherwise = Right (fromIntegral (shiftL (1 :: Word64) width - 1))
+
+
+{- | Validate a stream and its inclusive maximum value, then measure it.
+Int32 input elements carry unsigned wire bits: negative elements are valid
+at width 32 when the configured maximum allows them. A dictionary writer
+supplies its largest valid index as the maximum instead.
+-}
+planRLEHybrid :: Int -> Word32 -> VP.Vector Int32 -> Either String HybridPlan
+planRLEHybrid width maximumValue values = do
+  mask <- widthMask width
+  if maximumValue > mask
+    then Left "Parquet.LevelsEncode: maximum exceeds bit width"
+    else
+      if VP.null values
+        then Right (HybridPlan width 0 EmptyHybrid)
+        else
+          let !first = VP.unsafeHead values
+              !firstWord = fromIntegral first :: Word32
+              outOfRange row = Left ("Parquet.LevelsEncode: value at row " ++ show row ++ " exceeds maximum")
+              validate !firstDifferent !row
+                | row == VP.length values = measureMixedHybrid width values firstDifferent
+                | otherwise =
+                    let !value = fromIntegral (VP.unsafeIndex values row) :: Word32
+                    in if value > maximumValue
+                         then outOfRange row
+                         else validate firstDifferent (row + 1)
+              -- An equal value inherits the first value's range check.
+              -- Once a difference is found, only range checks remain;
+              -- at full width all Word32 bit patterns are already valid.
+              seekDifference !row
+                | row == VP.length values = repeatedPlan width (VP.length values) firstWord
+                | VP.unsafeIndex values row == first = seekDifference (row + 1)
+                | maximumValue == maxBound = measureMixedHybrid width values row
+                | maximumValue == mask && valuesFitMask mask (VP.unsafeDrop row values) = measureMixedHybrid width values row
+                | otherwise = validate row row
+          in if firstWord > maximumValue
+               then outOfRange 0
+               else seekDifference 1
+
+
+-- A bit-width mask is contiguous, so OR-ing the values preserves every
+-- out-of-range bit. Align the logical slice before reinterpreting pairs;
+-- drain an odd leading/trailing Int32 separately, without reading padding.
+-- Endianness changes lane order, but not the OR of the two 32-bit halves.
+valuesFitMask :: Word32 -> VP.Vector Int32 -> Bool
+valuesFitMask maximumValue values@(VP.Vector offset count bytes)
+  | count == 0 = True
+  | otherwise =
+      let !start = offset .&. 1
+          !remaining = count - start
+          !pairs = VP.Vector ((offset + start) `quot` 2) (remaining `quot` 2) bytes :: VP.Vector Word64
+          !combined = VP.foldl' (.|.) 0 pairs
+          !lanes = fromIntegral combined .|. fromIntegral (shiftR combined 32) :: Word32
+          !leading = if start == 0 then lanes else lanes .|. fromIntegral (VP.unsafeHead values)
+          !allBits = if remaining .&. 1 == 0 then leading else leading .|. fromIntegral (VP.unsafeLast values)
+      in allBits <= maximumValue
+{-# INLINE valuesFitMask #-}
+
+
+-- At width one, a run of eight takes twice the payload of a packed group.
+-- Wait for sixteen equal values; wider values break even by eight.
+minimumRepeatedValues :: Int -> Int
+minimumRepeatedValues width = if width == 1 then 16 else 8
+{-# INLINE minimumRepeatedValues #-}
+
+
+-- Start candidates only at a packed-group boundary. An emitted repeated
+-- run may end at any row: the next packed segment starts a fresh group.
+-- This keeps padding out of the middle of the logical value stream.
+findRepeatedEnd# :: VP.Vector Int32 -> Int -> Int -> Int#
+findRepeatedEnd# values start width =
+  let !first = VP.unsafeIndex values start
+      !minimumCount = minimumRepeatedValues width
+      go !row
+        | row == VP.length values || VP.unsafeIndex values row /= first =
+            let !count = row - start
+                -- A short constant tail can avoid a whole padded group.
+                -- At one bit, its two-byte RLE needs at least nine values.
+                !compactTail = row == VP.length values && (width /= 1 || count >= 9)
+            in if count >= minimumCount || compactTail then case row of I# end# -> end# else 0#
+        | otherwise = go (row + 1)
+  in -- A different value at the minimum run's last position rules the run
+     -- out immediately. Matching endpoints still need the full interior
+     -- check; a short final tail keeps its separate compact-tail rule.
+     if VP.length values - start >= minimumCount
+       && VP.unsafeIndex values (start + minimumCount - 1) /= first
+       then 0#
+       else go (start + 1)
+{-# INLINE findRepeatedEnd# #-}
+
+
+-- Size arithmetic stays in unboxed machine integers on the hot path.
+-- Both additions are checked before multiplication or narrowing; no
+-- segment list, run object or Integer is allocated for each group.
+withPackedSize :: Int -> Int -> Int -> (String -> r) -> (Int -> r) -> r
+withPackedSize width count total failed next
+  | count == 0 = next total
+  | otherwise =
+      let (whole, tailValues) = quotRem count 8
+          !groups = whole + if tailValues == 0 then 0 else 1
+          (full, rest) = quotRem groups maxPackedGroups
+          !headers = full * 5 + if rest == 0 then 0 else varintSize (shiftL (fromIntegral rest) 1 .|. 1)
+          !remaining = maxBound - total - headers
+      in if remaining < 0 || (width /= 0 && groups > remaining `quot` width)
+           then failed "Parquet.LevelsEncode: encoded stream exceeds addressable size"
+           else next (total + headers + groups * width)
+{-# INLINE withPackedSize #-}
+
+
+withRepeatedSize :: Int -> Int -> Int -> (String -> r) -> (Int -> r) -> r
+withRepeatedSize width count total failed next =
+  let !bytes = (width + 7) `quot` 8
+      !size =
+        if count == 0
+          then 0
+          else
+            if count <= maxRepeatedValues
+              then varintSize (shiftL (fromIntegral count) 1) + bytes
+              else
+                let (full, rest) = quotRem count maxRepeatedValues
+                    !tailSize = if rest == 0 then 0 else varintSize (shiftL (fromIntegral rest) 1) + bytes
+                in full * (5 + bytes) + tailSize
+  in if total > maxBound - size
+       then failed "Parquet.LevelsEncode: encoded stream exceeds addressable size"
+       else next (total + size)
+{-# INLINE withRepeatedSize #-}
+
+
+measureMixedHybrid :: Int -> VP.Vector Int32 -> Int -> Either String HybridPlan
+measureMixedHybrid width values firstDifferent
+  | firstRepeated == 0 = go 0 0 0 False
+  | otherwise = withRepeatedSize width firstRepeated 0 Left $ \size -> go firstRepeated firstRepeated size True
+  where
+    -- The constant-prefix check already found this maximal run. Retain
+    -- it in the plan so neither sizing nor encoding reads it a second time.
+    firstRepeated = if firstDifferent >= minimumRepeatedValues width then firstDifferent else 0
+    go !row !packedStart !total !hasRepeated
+      | row == VP.length values =
+          withPackedSize width (row - packedStart) total Left $ \size ->
+            Right (HybridPlan width size (if hasRepeated then MixedHybrid values firstRepeated else PackedHybrid values))
+      | otherwise =
+          case findRepeatedEnd# values row width of
+            0# -> go (row + min 8 (VP.length values - row)) packedStart total hasRepeated
+            end# ->
+              let !end = I# end#
+              in withPackedSize width (row - packedStart) total Left $ \beforeRun ->
+                   withRepeatedSize width (end - row) beforeRun Left $ \afterRun ->
+                     go end end afterRun True
+
+
+{- | Plan a repeated value without materializing a vector. Large counts
+are represented by several legal runs, rather than one oversized header.
+-}
+planRepeatedRLEHybrid :: Int -> Int -> Word32 -> Either String HybridPlan
+planRepeatedRLEHybrid width count value = do
+  mask <- widthMask width
+  if count < 0
+    then Left "Parquet.LevelsEncode: negative value count"
+    else
+      if count == 0
+        then Right (HybridPlan width 0 EmptyHybrid)
+        else
+          if value > mask
+            then Left "Parquet.LevelsEncode: repeated value exceeds bit width"
+            else repeatedPlan width count value
+
+
+repeatedPlan :: Int -> Int -> Word32 -> Either String HybridPlan
+repeatedPlan width count value =
+  let (full, rest) = quotRem count maxRepeatedValues
+      bytes = (width + 7) `quot` 8
+      tailSize = if rest == 0 then 0 else varintSize (shiftL (fromIntegral rest) 1) + bytes
+      size = toInteger full * toInteger (5 + bytes) + toInteger tailSize
+  in sizedPlan width (RepeatedHybrid count value) size
+
+
+sizedPlan :: Int -> HybridBody -> Integer -> Either String HybridPlan
+sizedPlan width body size
+  | size > toInteger (maxBound :: Int) = Left "Parquet.LevelsEncode: encoded stream exceeds addressable size"
+  | otherwise = Right (HybridPlan width (fromInteger size) body)
+
+
+varintSize :: Word64 -> Int
+varintSize = go 1
+  where
+    go !bytes value
+      | value < 128 = bytes
+      | otherwise = go (bytes + 1) (shiftR value 7)
+
+
+-- | Encode a previously validated plan, with one exact-size allocation.
+encodeHybridPlan :: HybridPlan -> ByteString
+encodeHybridPlan plan
+  | hybridEncodedSize plan == 0 = BS.empty
+  | otherwise = Direct.directEncode (hybridEncodedSize plan) (\ptr offset -> encodeHybridInto ptr offset plan)
+
+
+{- | Encode a raw hybrid stream. Invalid widths and unrepresentable values
+fail before payload allocation. Use 'planRLEHybrid' for a checked result
+or for a smaller semantic maximum than the bit width permits.
+-}
+encodeRLEHybrid :: Int -> VP.Vector Int32 -> ByteString
+encodeRLEHybrid width values = either error encodeHybridPlan $ do
+  maximumValue <- widthMask width
+  planRLEHybrid width maximumValue values
+
+
+{- | Encode a V1 repetition/definition-level stream with its unsigned
+four-byte length prefix. Dictionary index streams have no such prefix.
+Width zero omits the level stream; values must still be representable.
+-}
+encodeLengthPrefixedHybrid :: Int -> VP.Vector Int32 -> ByteString
+encodeLengthPrefixedHybrid width values = either error encode $ do
+  maximumValue <- widthMask width
+  planRLEHybrid width maximumValue values
+  where
+    encode plan
+      | width == 0 = BS.empty
+      | toInteger (hybridEncodedSize plan) > toInteger (maxBound :: Word32) = error "Parquet.LevelsEncode: length prefix exceeds unsigned 32-bit size"
+      | hybridEncodedSize plan > maxBound - 4 = error "Parquet.LevelsEncode: prefixed stream exceeds addressable size"
+      | otherwise = Direct.directEncode (hybridEncodedSize plan + 4) $ \ptr offset -> do
+          let size = fromIntegral (hybridEncodedSize plan)
+          payload <- Direct.dWord32LE ptr offset (case targetByteOrder of LittleEndian -> size; BigEndian -> byteSwap32 size)
+          encodeHybridInto ptr payload plan
+
+
+-- Only the outer Direct writer returns a boxed offset. All run workers
+-- return the state and offset unboxed, including across width dispatch.
+encodeHybridInto :: Ptr Word8 -> Int -> HybridPlan -> IO Int
+encodeHybridInto ptr start (HybridPlan width _ body) = IO $ \state ->
+  let write s = case body of
+        EmptyHybrid -> case start of I# start# -> (# s, start# #)
+        RepeatedHybrid count value -> encodeRepeatedRuns# ptr start width count value s
+        PackedHybrid values -> encodePackedRuns# ptr start width values 0 (VP.length values) s
+        MixedHybrid values firstRepeated -> encodeMixedRuns# ptr start width values firstRepeated s
+  in case write state of (# next, end# #) -> (# next, I# end# #)
+{-# INLINE encodeHybridInto #-}
+
+
+runWrite# :: IO Int -> State# RealWorld -> (# State# RealWorld, Int# #)
+runWrite# (IO write) state = case write state of (# next, I# offset# #) -> (# next, offset# #)
+{-# INLINE runWrite# #-}
+
+
+encodeRepeatedRuns# :: Ptr Word8 -> Int -> Int -> Int -> Word32 -> State# RealWorld -> (# State# RealWorld, Int# #)
+encodeRepeatedRuns# ptr start width count !value state =
+  let !valueBytes = (width + 7) `quot` 8
+      writeValue !offset s = case valueBytes of
+        0 -> case offset of I# offset# -> (# s, offset# #)
+        1 -> runWrite# (Direct.dWord8 ptr offset (fromIntegral value)) s
+        2 -> case runWrite# (Direct.dWord8 ptr offset (fromIntegral value)) s of
+          (# second, next# #) -> runWrite# (Direct.dWord8 ptr (I# next#) (fromIntegral (shiftR value 8))) second
+        3 -> case runWrite# (Direct.dWord8 ptr offset (fromIntegral value)) s of
+          (# second, next# #) -> case runWrite# (Direct.dWord8 ptr (I# next#) (fromIntegral (shiftR value 8))) second of
+            (# third, last# #) -> runWrite# (Direct.dWord8 ptr (I# last#) (fromIntegral (shiftR value 16))) third
+        _ -> runWrite# (Direct.dWord32LE ptr offset (case targetByteOrder of LittleEndian -> value; BigEndian -> byteSwap32 value)) s
+      writeRun !countHere !offset s =
+        case runWrite# (Direct.dVarint ptr offset (shiftL (fromIntegral countHere) 1)) s of
+          (# afterHeader, payload# #) -> writeValue (I# payload#) afterHeader
+      runs !remaining !offset s
+        | remaining == 0 = case offset of I# offset# -> (# s, offset# #)
+        | remaining <= maxRepeatedValues = writeRun remaining offset s
+        | otherwise = case writeRun maxRepeatedValues offset s of
+            (# next, offset# #) -> runs (remaining - maxRepeatedValues) (I# offset#) next
+  in runs count start state
+{-# INLINE encodeRepeatedRuns# #-}
+
+
+encodePackedRuns# :: Ptr Word8 -> Int -> Int -> VP.Vector Int32 -> Int -> Int -> State# RealWorld -> (# State# RealWorld, Int# #)
+encodePackedRuns# ptr start width values startRow count state =
+  let runs !row !remaining !offset s
+        | remaining == 0 = case offset of I# offset# -> (# s, offset# #)
+        | otherwise =
+            let (whole, tailValues) = quotRem remaining 8
+                !groups = min maxPackedGroups (whole + if tailValues == 0 then 0 else 1)
+                !countHere = min remaining (groups * 8)
+            in case runWrite# (Direct.dVarint ptr offset (shiftL (fromIntegral groups) 1 .|. 1)) s of
+                 (# afterHeader, payload# #) ->
+                   case packValues# ptr width values row countHere (I# payload#) (groups * width) afterHeader of
+                     (# next, end# #) -> runs (row + countHere) (remaining - countHere) (I# end#) next
+  in runs startRow count start state
+{-# INLINE encodePackedRuns# #-}
+
+
+encodeMixedRuns# :: Ptr Word8 -> Int -> Int -> VP.Vector Int32 -> Int -> State# RealWorld -> (# State# RealWorld, Int# #)
+encodeMixedRuns# ptr start width values firstRepeated state
+  | firstRepeated == 0 = go 0 0 start state
+  | otherwise =
+      case encodeRepeatedRuns# ptr start width firstRepeated (fromIntegral (VP.unsafeHead values)) state of
+        (# next, end# #) -> go firstRepeated firstRepeated (I# end#) next
+  where
+    go !row !packedStart !offset s
+      | row == VP.length values = encodePackedRuns# ptr offset width values packedStart (row - packedStart) s
+      | otherwise = case findRepeatedEnd# values row width of
+          0# -> go (row + min 8 (VP.length values - row)) packedStart offset s
+          end# ->
+            let !end = I# end#
+            in case encodePackedRuns# ptr offset width values packedStart (row - packedStart) s of
+                 (# afterPacked, payload# #) ->
+                   case encodeRepeatedRuns# ptr (I# payload#) width (end - row) (fromIntegral (VP.unsafeIndex values row)) afterPacked of
+                     (# afterRepeated, next# #) -> go end end (I# next#) afterRepeated
+{-# INLINE encodeMixedRuns# #-}
+
+
+-- Emit complete machine words, retaining any high bits of a straddling
+-- value in the next accumulator. Only the last partial word uses byte
+-- writes. Every input load and output store stays within its logical slice.
+packValues# :: Ptr Word8 -> Int -> VP.Vector Int32 -> Int -> Int -> Int -> Int -> State# RealWorld -> (# State# RealWorld, Int# #)
+packValues# ptr width values startRow count startOffset byteCount state =
+  let !end = startOffset + byteCount
+      zeroPad !offset s
+        | offset == end = case offset of I# offset# -> (# s, offset# #)
+        | otherwise = case runWrite# (Direct.dWord8 ptr offset 0) s of
+            (# next, offset# #) -> zeroPad (I# offset#) next
+      tailBytes !offset !bits !acc s
+        | bits <= 0 = zeroPad offset s
+        | otherwise = case runWrite# (Direct.dWord8 ptr offset (fromIntegral acc)) s of
+            (# next, offset# #) -> tailBytes (I# offset#) (bits - 8) (shiftR acc 8) next
+      consume !row !offset !bits !acc s
+        | row == count = tailBytes offset bits acc s
+        | otherwise =
+            let !word = fromIntegral (fromIntegral (VP.unsafeIndex values (startRow + row)) :: Word32) :: Word64
+                !combined = acc .|. shiftL word bits
+                !nextBits = bits + width
+            in if nextBits < 64
+                 then consume (row + 1) offset nextBits combined s
+                 else case runWrite# (Direct.dWord64LE ptr offset (case targetByteOrder of LittleEndian -> combined; BigEndian -> byteSwap64 combined)) s of
+                   (# next, offset# #) -> consume (row + 1) (I# offset#) (nextBits - 64) (shiftR word (64 - bits)) next
+  in if width == 32 && targetByteOrder == LittleEndian
+       then case values of
+         VP.Vector sliceOffset _ bytes ->
+           case copyByteArrayToAddr (ptr `plusPtr` startOffset) bytes ((sliceOffset + startRow) * 4) (count * 4) of
+             IO copy -> case copy state of
+               (# next, _ #) -> zeroPad (startOffset + count * 4) next
+       else consume 0 startOffset 0 (0 :: Word64) state
+{-# INLINE packValues# #-}
diff --git a/src/Parquet/Nested.hs b/src/Parquet/Nested.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Nested.hs
@@ -0,0 +1,1820 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Writer-side support for arbitrary nested Parquet column trees:
+structs, lists (3-level encoding), maps, and any composition of
+those with primitive leaves. The writer walks a row-major tree and
+emits Dremel-style @(repetition, definition, value)@ events per
+leaf, ready to drop into a DATA_PAGE_V2.
+
+The Iceberg spec uses the standard parquet-format encoding for
+each compound type:
+
+* @list<T>@ → @optional group <name> (LIST) { repeated group list
+  { optional <T> element; } }@.
+* @map<K, V>@ → @optional group <name> (MAP) { repeated group
+  key_value { required <K> key; optional <V> value; } }@.
+* @struct<...>@ → an unannotated group whose children are fields.
+
+We model the row-major input as 'NestedRow' (a self-similar tree
+of @Maybe@ / list / struct / map / leaf), build the schema with
+'NestedSchema' / 'mkSchema', and run 'shred' to flatten one row at
+a time. The result is one 'NestedLeaf' per primitive leaf in the
+schema in left-to-right order, exactly matching what
+DATA_PAGE_V2 expects.
+
+The sibling 'encodeOptionalListOptionalI32' / friends shipped in
+the previous PR are now thin wrappers that build a 'NestedSchema',
+a 'NestedRow' vector, and call 'shred'.
+-}
+module Parquet.Nested (
+  -- * Schema
+  NestedSchema (..),
+  LeafType (..),
+  LeafDescriptor (..),
+
+  -- * Row-major data
+  NestedRow (..),
+  LeafValue (..),
+
+  -- * Shredding
+  NestedLeaf (..),
+  shred,
+
+  -- * Schema flattening
+  flattenSchema,
+  nestedSchemaToFlatSchema,
+
+  -- * Whole-file builder
+  buildNestedFile,
+  buildNestedFileWithAux,
+  buildNestedFileWithBloomFilters,
+  buildNestedFileWithBloomFiltersUsing,
+
+  -- * Convenience for the optional-list-of-optional-primitive case
+
+  --   (the previous PR's Iceberg-default-value shape)
+  encodeOptionalListOptionalI32,
+  encodeOptionalListOptionalI64,
+  encodeOptionalListOptionalDouble,
+  optionalListSchemaSegments,
+  buildOptionalListFile,
+  buildOptionalListFileEither,
+) where
+
+import Data.Bits (setBit, shiftL, shiftR, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Lazy qualified as BL
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Int (Int32, Int64)
+import Data.Text (Text)
+import Data.Text.Encoding qualified as TE
+import Data.Text.Foreign qualified as TF
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Word (Word16, Word32, Word64, Word8)
+import GHC.Exts (Int (I#), Int#, Word64#, (+#), (<#), (==#), (>#))
+import GHC.Float (castDoubleToWord64, castFloatToWord32)
+import GHC.Word (Word64 (W64#))
+import Parquet.Compress qualified as Compress
+import Parquet.Nested.Fast qualified as Fast
+import Parquet.File qualified as F
+import Parquet.Footer qualified as PF
+import Parquet.LevelsEncode qualified as LE
+import Parquet.Page qualified as PP
+import Parquet.Types (
+  ColumnChunk (..),
+  ColumnMetadata (..),
+  Compression (..),
+  ConvertedType (..),
+  Encoding (..),
+  FileMetadata (..),
+  LogicalType (..),
+  LtTimeUnit (..),
+  ParquetType (..),
+  Repetition (..),
+  RowGroup (..),
+  SchemaElement (..),
+  Statistics (..),
+  ColumnOrder (..),
+  hasCompatiblePhysicalType,
+ )
+import Parquet.Variant qualified as Variant
+import Parquet.Write qualified as PW
+import Parquet.Nested.Bloom qualified as NestedBloom
+import Parquet.Nested.Statistics qualified as NestedStats
+import Parquet.Nested.Types
+import Parquet.Variant.Nested qualified as VariantNested
+import Wireform.Builder qualified as B
+
+
+-- ============================================================
+-- Schema description
+-- ============================================================
+
+leafParquetType :: LeafType -> ParquetType
+leafParquetType = \case
+  LtInt32 -> PTInt32
+  LtInt64 -> PTInt64
+  LtFloat16 -> PTFixedLenByteArray
+  LtFloat -> PTFloat
+  LtDouble -> PTDouble
+  LtBool -> PTBoolean
+  LtString -> PTByteArray
+  LtJson -> PTByteArray
+  LtBinary -> PTByteArray
+  LtInteger 64 _ -> PTInt64
+  LtInteger _ _ -> PTInt32
+  LtDate -> PTInt32
+  LtTime _ LtMillis -> PTInt32
+  LtTime _ _ -> PTInt64
+  LtTimestamp {} -> PTInt64
+  LtTimestamp96 {} -> PTFixedLenByteArray
+  LtInt96 -> PTInt96
+  LtDecimal precision _
+    | precision <= 9 -> PTInt32
+    | precision <= 18 -> PTInt64
+    | otherwise -> PTFixedLenByteArray
+  LtFixedBinary {} -> PTFixedLenByteArray
+  LtUuid -> PTFixedLenByteArray
+
+
+leafConvertedType :: LeafType -> Maybe ConvertedType
+leafConvertedType = \case
+  LtString -> Just CTUtf8
+  LtJson -> Just CTJson
+  LtDecimal {} -> Just CTDecimal
+  LtInteger 8 True -> Just CTInt8
+  LtInteger 16 True -> Just CTInt16
+  LtInteger 32 True -> Just CTInt32
+  LtInteger 64 True -> Just CTInt64
+  LtInteger 8 False -> Just CTUInt8
+  LtInteger 16 False -> Just CTUInt16
+  LtInteger 32 False -> Just CTUInt32
+  LtInteger 64 False -> Just CTUInt64
+  LtDate -> Just CTDate
+  LtTime _ LtMillis -> Just CTTimeMillis
+  LtTime _ LtMicros -> Just CTTimeMicros
+  LtTimestamp _ LtMillis -> Just CTTimestampMillis
+  LtTimestamp _ LtMicros -> Just CTTimestampMicros
+  _ -> Nothing
+
+
+leafLogicalType :: LeafType -> Maybe LogicalType
+leafLogicalType = \case
+  LtFloat16 -> Just LTFloat16
+  LtString -> Just LTString
+  LtJson -> Just LTJson
+  LtInteger width signed -> Just (LTInteger width signed)
+  LtDate -> Just LTDate
+  LtTime adjusted unit -> Just (LTTime adjusted unit)
+  LtTimestamp adjusted unit -> Just (LTTimestamp adjusted unit)
+  LtTimestamp96 adjusted unit -> Just (LTTimestamp adjusted unit)
+  LtDecimal precision scale -> Just (LTDecimal precision scale)
+  LtUuid -> Just LTUUID
+  _ -> Nothing
+
+
+leafSchemaElement :: Text -> Maybe Repetition -> LeafType -> SchemaElement
+leafSchemaElement name repetition typ =
+  SchemaElement
+    { seTypeLength = case typ of
+        LtFloat16 -> Just 2
+        LtFixedBinary width -> Just width
+        LtTimestamp96 {} -> Just 12
+        LtUuid -> Just 16
+        LtDecimal precision _ | precision > 18 -> Just (if precision <= 38 then 16 else 32)
+        _ -> Nothing
+    , seName = name
+    , seRepetition = repetition
+    , seType = Just (leafParquetType typ)
+    , seNumChildren = Nothing
+    , seConvertedType = leafConvertedType typ
+    , seLogicalType = leafLogicalType typ
+    , seFieldId = Nothing
+    }
+
+
+-- ============================================================
+-- Shredded leaf
+-- ============================================================
+
+-- | One primitive leaf after Dremel shredding.
+data NestedLeaf = NestedLeaf
+  { nlPath :: !(V.Vector Text)
+  , nlMaxDef :: !Int
+  , nlMaxRep :: !Int
+  , nlDefLevels :: !(VP.Vector Int32)
+  , nlRepLevels :: !(VP.Vector Int32)
+  , nlValueBytes :: !ByteString
+  , nlValueCount :: !Int
+  }
+  deriving (Show, Eq)
+
+
+-- ============================================================
+-- Schema flattening + max levels
+-- ============================================================
+
+{- | Walk a 'NestedSchema' producing one entry per primitive leaf, in
+the same order Parquet's flat schema expects. Each entry carries
+the leaf's path, its physical type, and the Dremel max definition
+and repetition levels at the leaf.
+-}
+flattenSchema :: Text -> NestedSchema -> V.Vector (LeafDescriptor)
+flattenSchema rootName ns = V.fromList (go (V.singleton rootName) 0 0 ns)
+  where
+    -- Walk one node, accumulating 'curDef' / 'curRep' as we descend.
+    go path !d !r = \case
+      NSPrimitive lt ->
+        [LeafDescriptor path lt d r]
+      NSOptional inner ->
+        go path (d + 1) r inner
+      NSRequired inner ->
+        go path d r inner
+      NSList inner ->
+        let path' = V.snoc (V.snoc path "list") "element"
+        in -- 'list' is a repeated group, so descending into it
+           -- bumps both d and r.
+           go path' (d + 1) (r + 1) inner
+      NSMap k v ->
+        let !pkv = V.snoc path "key_value"
+        in go (V.snoc pkv "key") (d + 1) (r + 1) k
+             ++ go (V.snoc pkv "value") (d + 1) (r + 1) v
+      NSStruct children ->
+        concatMap
+          (\(name, child) -> go (V.snoc path name) d r child)
+          (V.toList children)
+      NSFile fields ->
+        V.foldr
+          (\spec rest -> LeafDescriptor (V.snoc path (F.fileFieldName (F.fileField spec))) (fileLeafType (F.fileField spec)) (d + 1) r : rest)
+          []
+          (F.fileSchemaFields fields)
+      NSVariant ->
+        -- Variant is a 2-leaf binary group. Both leaves are
+        -- @required binary@ so descending into them doesn't bump d
+        -- or r; the group's own repetition is set by an enclosing
+        -- NSOptional / NSRequired (typical Iceberg usage:
+        -- @optional NSVariant@).
+        [ LeafDescriptor (V.snoc path "metadata") LtBinary d r
+        , LeafDescriptor (V.snoc path "value") LtBinary d r
+        ]
+      NSVariantWithLimits _ -> go path d r NSVariant
+      NSVariantTyped storage -> go path d r (storageLayout storage)
+
+
+{- | Per-leaf metadata used both by the shredder and by
+'buildOptionalListFile' to populate the column chunks.
+-}
+data LeafDescriptor = LeafDescriptor
+  { ldPath :: !(V.Vector Text)
+  , ldType :: !LeafType
+  , ldMaxDef :: !Int
+  , ldMaxRep :: !Int
+  }
+  deriving (Show, Eq)
+
+
+
+
+-- ============================================================
+-- Shredding
+-- ============================================================
+
+{- | Shred a vector of row-major records into one 'NestedLeaf' per
+primitive leaf in @schema@. Length of 'nlDefLevels' / 'nlRepLevels'
+on each leaf is the same, equal to the total number of value
+positions (one per "leaf slot" expanded across all rows).
+
+Each row is one 'NestedRow' that must structurally match @schema@:
+
+* 'NRLeaf' under 'NSPrimitive'.
+* 'NRList' under 'NSList'.
+* 'NRStruct' under 'NSStruct' with children in the same order.
+* 'NRMapEntries' under 'NSMap'.
+* 'NRNull' under any 'NSOptional' wrapper.
+
+A type-mismatch yields 'Left'.
+-}
+shred
+  :: NestedSchema
+  -> V.Vector NestedRow
+  -> Either String (V.Vector NestedLeaf)
+shred schema rows = do
+  planned <- planShred schema rows
+  validateVariantRows schema rows
+  pure (V.map materializeShreddedLeaf planned)
+
+
+-- All leaf sizes and level streams are planned before any value builder is
+-- run. Keeping the plan private also lets the whole-file writer reuse it.
+data ShreddedLeafPlan = ShreddedLeafPlan
+  { slpDescriptor :: !LeafDescriptor
+  , slpDefinitions :: !(VP.Vector Int32)
+  , slpRepetitions :: !(VP.Vector Int32)
+  , slpValues :: !ShreddedValues
+  , slpPage :: !NestedPagePlan
+  }
+
+
+-- Materialize a leaf only when an operation needs its PLAIN bytes. A bloom
+-- filter and V2 compression share that buffer; ordinary uncompressed writes
+-- retain the direct builder path.
+data ShreddedValues
+  = PlannedValues !B.Builder
+  | MaterializedValues !ByteString
+  | DeferredValues {-# UNPACK #-} !Int ~ByteString
+
+
+shreddedValueBuilder :: ShreddedValues -> B.Builder
+shreddedValueBuilder (PlannedValues builder) = builder
+shreddedValueBuilder (MaterializedValues bytes) = B.byteString bytes
+shreddedValueBuilder (DeferredValues _ bytes) = B.byteString bytes
+
+
+shreddedValueBytes :: ShreddedValues -> ByteString
+shreddedValueBytes (PlannedValues builder) = BL.toStrict (B.toLazyByteString builder)
+shreddedValueBytes (MaterializedValues bytes) = bytes
+shreddedValueBytes (DeferredValues _ bytes) = bytes
+
+
+planShred :: NestedSchema -> V.Vector NestedRow -> Either String (V.Vector ShreddedLeafPlan)
+planShred schema rows = do
+  _ <- nestedPageCount "row count" (V.length rows)
+  validateNestedSchema schema
+  if V.null rows then Right () else validateObservableShape schema
+  let !leaves = flattenSchema "" schema
+      !nLeaves = V.length leaves
+      seeds = V.replicate nLeaves emptyAcc
+  V.mapM_
+    ( \leaf ->
+        if hasCompatiblePhysicalType (leafSchemaElement "" Nothing (ldType leaf))
+          then Right ()
+          else Left "Parquet.Nested: invalid logical leaf type"
+    )
+    leaves
+  case Fast.shredFast schema rows of
+    Just result -> result >>= V.imapM (\index leaf -> finalizeFast (V.unsafeIndex leaves index) leaf)
+    Nothing -> do
+      finalAcc <- V.foldM' (\acc row -> shredRow schema acc row 0 0) seeds rows
+      V.imapM (\i ld -> finalize ld (V.unsafeIndex finalAcc i)) leaves
+  where
+    finalizeFast ld leaf = do
+      let definitions = Fast.fastDefinitions leaf
+          repetitions = Fast.fastRepetitions leaf
+          payload = Fast.fastPayload leaf
+          input = NestedPageInput (V.length rows) (ldMaxDef ld) (ldMaxRep ld) definitions repetitions (ShreddedCounts (Fast.fastValueCount leaf)) (Fast.fastPayloadSize leaf)
+      page <- planNestedPageInput input
+      Right (ShreddedLeafPlan ld definitions repetitions (DeferredValues (Fast.fastPayloadSize leaf) payload) page)
+    finalize ld acc = do
+      let definitions = VP.fromList (reverse (accDefs acc))
+          repetitions = VP.fromList (reverse (accReps acc))
+          input = NestedPageInput (V.length rows) (ldMaxDef ld) (ldMaxRep ld) definitions repetitions (CheckLevelCounts Nothing) (accPayloadSize acc)
+      page <- planNestedPageInput input
+      Right (ShreddedLeafPlan ld definitions repetitions (PlannedValues (finishValues acc)) page)
+
+
+materializeShreddedLeaf :: ShreddedLeafPlan -> NestedLeaf
+materializeShreddedLeaf prepared =
+  let descriptor = slpDescriptor prepared
+  in NestedLeaf
+       { nlPath = ldPath descriptor
+       , nlMaxDef = ldMaxDef descriptor
+       , nlMaxRep = ldMaxRep descriptor
+       , nlDefLevels = slpDefinitions prepared
+       , nlRepLevels = slpRepetitions prepared
+       , nlValueBytes = shreddedValueBytes (slpValues prepared)
+       , nlValueCount = nppValueCount (slpPage prepared)
+       }
+
+
+-- Repetition wrappers describe one physical node, not additional nodes.
+-- The schema emitter can store only one repetition value there; accepting
+-- adjacent wrappers would let the shredder count levels absent from the file.
+validateNestedSchema :: NestedSchema -> Either String ()
+validateNestedSchema = go
+  where
+    go node = case node of
+      NSPrimitive (LtDecimal precision scale)
+        | precision < 1 || precision > 76 || scale < 0 || scale > precision -> Left "Parquet.Nested: DECIMAL requires precision1..76 and scale0..precision"
+      NSPrimitive (LtFixedBinary width)
+        | width <= 0 -> Left "Parquet.Nested: fixed-byte width must be positive"
+      NSOptional child -> unwrapped child
+      NSRequired child -> unwrapped child
+      NSList child -> go child
+      NSMap key value -> do
+        case key of
+          NSOptional _ -> Left "Parquet.Nested: MAP keys must be required"
+          _ -> Right ()
+        go key
+        go value
+      NSStruct fields
+        | V.null fields -> Left "Parquet.Nested: empty structs have no physical leaf"
+        | otherwise -> V.mapM_ (go . snd) fields
+      NSVariantWithLimits limits
+        | Variant.variantMaxDepth limits < 0 || Variant.variantMaxValues limits <= 0 || Variant.variantMaxDictionaryEntries limits < 0 ->
+            Left "Parquet.Nested: invalid Variant resource limits"
+      _ -> Right ()
+    unwrapped child = case child of
+      NSOptional _ -> adjacent
+      NSRequired _ -> adjacent
+      _ -> go child
+    adjacent = Left "Parquet.Nested: adjacent Optional / Required wrappers describe the same physical node"
+
+
+-- A zero-field FILE can only contain null references. It needs no levels of
+-- its own, but other optional/repeated containers still need a physical leaf
+-- to encode their presence and multiplicity. Reject unobservable shapes
+-- instead of emitting a file that silently loses those distinctions.
+validateObservableShape :: NestedSchema -> Either String ()
+validateObservableShape schema = case schema of
+  NSOptional child
+    | leafCount child == 0 -> case child of
+        NSFile _ -> Right ()
+        _ -> missing
+    | otherwise -> validateObservableShape child
+  NSRequired child -> validateObservableShape child
+  NSList child
+    | leafCount child == 0 -> missing
+    | otherwise -> validateObservableShape child
+  NSMap key value
+    | leafCount key + leafCount value == 0 -> missing
+    | otherwise -> validateObservableShape key >> validateObservableShape value
+  NSStruct fields -> V.mapM_ (validateObservableShape . snd) fields
+  NSVariantTyped storage -> validateObservableShape (storageLayout storage)
+  _ -> Right ()
+  where
+    missing = Left "Parquet.Nested: optional/repeated container has no physical leaf to encode its shape"
+
+
+{- | Per-leaf accumulator. We push events as we walk each row
+recursively; finalising reverses the def / rep lists into the
+'VP.Vector's the writer expects.
+-}
+data LeafAcc
+  = LeafAcc
+      { accDefs :: ![Int32]
+      -- ^ reversed
+      , accReps :: ![Int32]
+      -- ^ reversed
+      , accValuesB :: !B.Builder
+      , -- Low 32 bits: event count. High 32 bits: planned value bytes.
+        -- Both are bounded by signed i32, so they fit without adding a field
+        -- to every per-event accumulator. Non-null count comes from levels.
+        accPageCounts :: {-# UNPACK #-} !Word64
+      }
+  | BooleanLeafAcc
+      -- Only boolean leaves carry a partial byte plus its bit position.
+      -- Nulls advance the event count but leave this state untouched.
+      { accDefs :: ![Int32]
+      , accReps :: ![Int32]
+      , accValuesB :: !B.Builder
+      , accPageCounts :: {-# UNPACK #-} !Word64
+      , accBooleanState :: {-# UNPACK #-} !Word16
+      }
+
+
+emptyAcc :: LeafAcc
+emptyAcc = LeafAcc [] [] mempty 0
+
+
+finishValues :: LeafAcc -> B.Builder
+finishValues acc = case acc of
+  BooleanLeafAcc {accBooleanState = state} | state `shiftR` 8 /= 0 -> accValuesB acc <> B.word8 (fromIntegral state)
+  _ -> accValuesB acc
+
+
+accPayloadSize :: LeafAcc -> Int
+accPayloadSize acc = fromIntegral (accPageCounts acc `shiftR` 32)
+{-# INLINE accPayloadSize #-}
+
+
+booleanState :: LeafAcc -> Word16
+booleanState acc = case acc of
+  BooleanLeafAcc {accBooleanState = state} -> state
+  _ -> 0
+{-# INLINE booleanState #-}
+
+
+{- | Shred one row recursively. The arguments are the schema we're
+still descending through, the per-leaf accumulators (one slot per
+leaf in the *original* schema, indexed left-to-right), the row
+itself, and the current (def, rep) levels.
+
+Critical invariant: the order in which leaves get appended must
+match the schema's flatten order, which 'descendThrough' preserves
+by walking the same way 'flattenSchema' does.
+-}
+shredRow
+  :: NestedSchema
+  -> V.Vector LeafAcc
+  -> NestedRow
+  -> Int
+  -- ^ current def
+  -> Int
+  -- ^ current rep
+  -> Either String (V.Vector LeafAcc)
+shredRow schema accs row d r = do
+  (newAccs, _) <- descendThrough schema 0 accs row d r 0
+  Right newAccs
+
+
+{- | Descend one schema node into one row value.
+
+Arguments:
+
+  * @schema@: the (sub)schema to descend.
+  * @cursor@: the leaf-index to write the next event to.
+  * @accs@: per-leaf event accumulators.
+  * @row@: the row value being shredded against @schema@.
+  * @d@: current definition level.
+  * @r@: rep level to emit for the very next leaf event the recursion
+         produces (i.e. the rep level for the FIRST element of any
+         repeated group inside @schema@). Subsequent elements of any
+         repeated group within @schema@ use the absolute rep depth.
+  * @absRep@: total number of repeated groups crossed so far, which
+         determines the rep level for "subsequent siblings" inside
+         a repeated group boundary.
+-}
+descendThrough
+  :: NestedSchema
+  -> Int
+  -- ^ leafCursor
+  -> V.Vector LeafAcc
+  -> NestedRow
+  -> Int
+  -- ^ current def
+  -> Int
+  -- ^ rep level for the next leaf event
+  -> Int
+  -- ^ absolute rep depth
+  -> Either String (V.Vector LeafAcc, Int)
+descendThrough schema !cursor !accs row !d !r !absRep = case (schema, row) of
+  -- An NSOptional node either consumes NRNull (which emits a null
+  -- event at the *parent's* def for every leaf in the subtree -
+  -- this Optional layer wasn't crossed) or unwraps the inner row,
+  -- bumping def by 1 to reflect that the layer was crossed.
+  (NSOptional inner, NRNull) ->
+    case emitNullsAcrossSubtree inner cursor accs d r of
+      (# message | #) -> Left message
+      (# | next #) -> Right (next, cursor + leafCount inner)
+  (NSOptional inner, other) ->
+    descendThrough inner cursor accs other (d + 1) r absRep
+  (NSRequired inner, other) ->
+    descendThrough inner cursor accs other d r absRep
+  -- NRNull at a required-or-list node is an error; the schema doesn't
+  -- allow nulls there.
+  (NSPrimitive _, NRNull) ->
+    Left "Parquet.Nested: NRNull at required NSPrimitive"
+  (NSList _, NRNull) ->
+    Left "Parquet.Nested: NRNull at required NSList (wrap with NSOptional)"
+  (NSMap _ _, NRNull) ->
+    Left "Parquet.Nested: NRNull at required NSMap (wrap with NSOptional)"
+  (NSStruct _, NRNull) ->
+    Left "Parquet.Nested: NRNull at required NSStruct (wrap with NSOptional)"
+  (NSPrimitive typ, NRLeaf v)
+    | not (leafValueMatches typ v) -> Left "Parquet.Nested: leaf value violates its physical or logical type"
+    | otherwise ->
+        case pushLeafChecked# (V.unsafeIndex accs cursor) d r v of
+          (# message | #) -> Left message
+          (# | next #) -> Right (V.unsafeUpd accs [(cursor, next)], cursor + 1)
+  (NSPrimitive _, _) ->
+    Left "Parquet.Nested: row shape doesn't match NSPrimitive"
+  -- NRList under NSList: empty -> emit one "empty list defined"
+  -- event per leaf in the subtree (def stays at d, the LIST itself
+  -- is defined; the contents aren't). Non-empty -> recurse, with
+  -- the FIRST element using the parent's r and subsequent ones
+  -- bumping r by 1 (we've crossed a repeated group).
+  (NSList inner, NRList children)
+    | 1# <- nestedCountExceeded# (V.length children) -> Left "Parquet.Nested: list length exceeds signed 32-bit page limit"
+    | V.null children ->
+        case emitNullsAcrossSubtree inner cursor accs d r of
+          (# message | #) -> Left message
+          (# | next #) -> Right (next, cursor + leafCount inner)
+    | otherwise ->
+        -- We're crossing this list's repeated group. The first
+        -- element keeps the caller's rep level (we haven't
+        -- "started a new sibling at this depth" - we're just
+        -- descending into the first one). Subsequent elements use
+        -- the absolute rep depth for /this/ list = absRep + 1.
+        let !thisAbsRep = absRep + 1
+            nKids = V.length children
+            stepKid (accs', _cur) i =
+              let !kid = V.unsafeIndex children i
+                  !rEvent = if i == 0 then r else thisAbsRep
+              in descendThrough inner cursor accs' kid (d + 1) rEvent thisAbsRep
+        in case foldM stepKid (accs, cursor) [0 .. nKids - 1] of
+             Right (accs', _) -> Right (accs', cursor + leafCount inner)
+             Left e -> Left e
+  (NSList _, _) -> Left "Parquet.Nested: row shape doesn't match NSList"
+  (NSMap k v, NRMapEntries pairs)
+    | 1# <- nestedCountExceeded# (V.length pairs) -> Left "Parquet.Nested: map length exceeds signed 32-bit page limit"
+    | V.null pairs ->
+        case emitNullsAcrossSubtree
+          (NSStruct (V.fromList [("key", k), ("value", v)]))
+          cursor
+          accs
+          d
+          r of
+          (# message | #) -> Left message
+          (# | next #) -> Right (next, cursor + leafCount k + leafCount v)
+    | otherwise ->
+        let !thisAbsRep = absRep + 1
+            nPairs = V.length pairs
+            stepPair (accs', _cur) i =
+              let (kRow, vRow) = V.unsafeIndex pairs i
+                  !rEvent = if i == 0 then r else thisAbsRep
+              in do
+                   (a1, c1) <- descendThrough k cursor accs' kRow (d + 1) rEvent thisAbsRep
+                   (a2, c2) <- descendThrough v c1 a1 vRow (d + 1) rEvent thisAbsRep
+                   Right (a2, c2)
+        in case foldM stepPair (accs, cursor) [0 .. nPairs - 1] of
+             Right (accs', _) -> Right (accs', cursor + leafCount k + leafCount v)
+             Left e -> Left e
+  (NSMap _ _, _) -> Left "Parquet.Nested: row shape doesn't match NSMap"
+  (NSVariantTyped storage, input) -> descendThrough (storageLayout storage) cursor accs (VariantNested.normalizeStorageRow storage input) d r absRep
+  (NSFile fields, NRFile reference) -> do
+    F.validateFileReferenceForSchema fields reference
+    next <- V.ifoldM (pushFileField reference) accs (F.fileSchemaFields fields)
+    Right (next, cursor + V.length (F.fileSchemaFields fields))
+    where
+      pushFileField reference' accumulators index spec =
+        let !position = cursor + index
+            !accumulator = V.unsafeIndex accumulators position
+            value = case F.fileField spec of
+              F.FileUri -> LvString <$> F.fileUri reference'
+              F.FileOffset -> LvInt64 <$> F.fileOffset reference'
+              F.FileSize -> LvInt64 <$> F.fileSize reference'
+              F.FileContentType -> LvString <$> F.fileContentType reference'
+              F.FileChecksumField -> LvString <$> F.fileChecksum reference'
+              F.FileInline -> LvBinary <$> F.fileInline reference'
+        in case value of
+             Nothing -> case emitNullsAcrossSubtree (NSPrimitive (fileLeafType (F.fileField spec))) position accumulators d r of
+               (# message | #) -> Left message
+               (# | result #) -> Right result
+             Just present -> case pushLeafChecked# accumulator (d + 1) r present of
+               (# message | #) -> Left message
+               (# | result #) -> Right (V.unsafeUpd accumulators [(position, result)])
+  (NSFile _, _) -> Left "Parquet.Nested: row shape doesn't match NSFile (expected NRFile)"
+  (variant, NRVariantBytes metaBs valBs) | Just _ <- variantLimits variant -> do
+    -- Push two binary leaves: the metadata and value byte-strings.
+    -- Both are 'required binary' so they emit at the current
+    -- definition level. Calling code typically wraps NSVariant in
+    -- NSOptional, in which case the row is either NRNull (handled
+    -- above) or NRVariantBytes for a present Variant.
+    -- Payload interpretation runs after every leaf's byte/count preflight,
+    -- so rejected pages do not repeatedly decode large valid dictionaries.
+    case pushLeafChecked# (V.unsafeIndex accs cursor) d r (LvBinary metaBs) of
+      (# message | #) -> Left message
+      (# | metadata #) ->
+        case pushLeafChecked# (V.unsafeIndex accs (cursor + 1)) d r (LvBinary valBs) of
+          (# message | #) -> Left message
+          (# | value #) -> Right (V.unsafeUpd accs [(cursor, metadata), (cursor + 1, value)], cursor + 2)
+  (NSVariant, _) ->
+    Left "Parquet.Nested: row shape doesn't match NSVariant (expected NRVariantBytes or NRNull)"
+  (NSVariantWithLimits _, _) ->
+    Left "Parquet.Nested: row shape doesn't match NSVariantWithLimits (expected NRVariantBytes or NRNull)"
+  (NSStruct fields, NRStruct values)
+    | V.length fields /= V.length values ->
+        Left "Parquet.Nested: NSStruct / NRStruct field count mismatch"
+    | otherwise ->
+        let nFs = V.length fields
+            stepField (accs', cur) i =
+              let (_, child) = V.unsafeIndex fields i
+                  val = V.unsafeIndex values i
+              in descendThrough child cur accs' val d r absRep
+        in case foldM stepField (accs, cursor) [0 .. nFs - 1] of
+             Right (accs', cur') -> Right (accs', cur')
+             Left e -> Left e
+  (NSStruct _, _) -> Left "Parquet.Nested: row shape doesn't match NSStruct"
+
+
+variantLimits :: NestedSchema -> Maybe Variant.VariantLimits
+variantLimits NSVariant = Just Variant.defaultVariantLimits
+variantLimits (NSVariantWithLimits limits) = Just limits
+variantLimits _ = Nothing
+{-# INLINE variantLimits #-}
+
+
+-- Compile only the Variant-bearing portions of a schema. No extra per-row
+-- traversal is needed for ordinary columns; nested checks visit selected
+-- children without creating intermediate row vectors.
+data VariantCheck
+  = CheckVariant !Variant.VariantLimits
+  | CheckTypedVariant !VariantStorageSchema
+  | CheckVariantStruct !(V.Vector VariantCheckChild)
+  | CheckVariantList !VariantCheck
+  | CheckVariantMap !(Maybe VariantCheck) !(Maybe VariantCheck)
+
+
+data VariantCheckChild = VariantCheckChild
+  { variantChildIndex :: {-# UNPACK #-} !Int
+  , variantChildCheck :: !VariantCheck
+  }
+
+
+variantCheck :: NestedSchema -> Maybe VariantCheck
+variantCheck schema = case schema of
+  NSVariant -> Just (CheckVariant Variant.defaultVariantLimits)
+  NSVariantWithLimits limits -> Just (CheckVariant limits)
+  NSVariantTyped storage -> Just (CheckTypedVariant storage)
+  NSOptional child -> variantCheck child
+  NSRequired child -> variantCheck child
+  NSList child -> CheckVariantList <$> variantCheck child
+  NSMap key value -> case (variantCheck key, variantCheck value) of
+    (Nothing, Nothing) -> Nothing
+    (keyCheck, valueCheck) -> Just (CheckVariantMap keyCheck valueCheck)
+  NSStruct fields ->
+    let checks = V.imapMaybe (\index (_, child) -> VariantCheckChild index <$> variantCheck child) fields
+    in if V.null checks then Nothing else Just (CheckVariantStruct checks)
+  _ -> Nothing
+
+
+validateVariantRows :: NestedSchema -> V.Vector NestedRow -> Either String ()
+validateVariantRows schema rows = case variantCheck schema of
+  Nothing -> Right ()
+  Just plan -> V.mapM_ (validateVariantRow plan) rows
+
+
+validateVariantRow :: VariantCheck -> NestedRow -> Either String ()
+validateVariantRow _ NRNull = Right ()
+validateVariantRow plan row = case (plan, row) of
+  (CheckTypedVariant storage, value) -> VariantNested.validateStorageRow storage value
+  (CheckVariant limits, NRVariantBytes metadata value) ->
+    () <$ Variant.decodeVariantWithLimits limits metadata value
+  (CheckVariantStruct children, NRStruct values) ->
+    V.mapM_ (\child -> validateVariantRow (variantChildCheck child) (V.unsafeIndex values (variantChildIndex child))) children
+  (CheckVariantList child, NRList values) -> V.mapM_ (validateVariantRow child) values
+  (CheckVariantMap keyPlan valuePlan, NRMapEntries pairs) ->
+    V.mapM_
+      ( \(key, value) -> do
+          maybe (Right ()) (`validateVariantRow` key) keyPlan
+          maybe (Right ()) (`validateVariantRow` value) valuePlan
+      )
+      pairs
+  _ -> Left "Parquet.Nested: Variant validation plan disagrees with preflight row shape"
+
+
+-- | Number of primitive leaves under a schema node.
+leafCount :: NestedSchema -> Int
+leafCount = \case
+  NSPrimitive _ -> 1
+  NSOptional s -> leafCount s
+  NSRequired s -> leafCount s
+  NSList s -> leafCount s
+  NSMap k v -> leafCount k + leafCount v
+  NSStruct fields -> sum (map (leafCount . snd) (V.toList fields))
+  NSFile fields -> V.length (F.fileSchemaFields fields)
+  NSVariant -> 2
+  NSVariantWithLimits _ -> 2
+  NSVariantTyped storage -> leafCount (storageLayout storage)
+
+
+fileLeafType :: F.FileField -> LeafType
+fileLeafType = \case
+  F.FileOffset -> LtInt64
+  F.FileSize -> LtInt64
+  F.FileInline -> LtBinary
+  _ -> LtString
+{-# INLINE fileLeafType #-}
+
+
+{- | Push one (def, rep) event for /every/ leaf in a subtree, with
+no value. Used for null-list and null-optional events.
+-}
+emitNullsAcrossSubtree
+  :: NestedSchema
+  -> Int
+  -- ^ leafCursor
+  -> V.Vector LeafAcc
+  -> Int
+  -> Int
+  -- ^ def, rep
+  -> (# String | V.Vector LeafAcc #)
+emitNullsAcrossSubtree sch !cur !accs !d !r =
+  let !nLeaves = leafCount sch
+      indices = [cur .. cur + nLeaves - 1]
+      updates =
+        map
+          ( \i ->
+              let acc = V.unsafeIndex accs i
+                  !acc' = pushNull acc d r
+              in (i, acc')
+          )
+          indices
+  in case cur of
+       I# start -> case cur + nLeaves of
+         I# end -> case nullRangeFits# start end accs of
+           0# -> (# "Parquet.Nested: event count exceeds signed 32-bit page limit" | #)
+           _ -> let !next = V.unsafeUpd accs updates in (# | next #)
+
+
+nestedCountExceeded# :: Int -> Int#
+nestedCountExceeded# (I# count) = case count <# 0# of
+  1# -> 1#
+  _ -> count ># 2147483647#
+{-# INLINE nestedCountExceeded# #-}
+
+
+nullRangeFits# :: Int# -> Int# -> V.Vector LeafAcc -> Int#
+nullRangeFits# index end accs = case index ==# end of
+  1# -> 1#
+  _ -> case fromIntegral (accPageCounts (V.unsafeIndex accs (I# index)) .&. 0xffffffff) :: Int of
+    I# count -> case count <# 2147483647# of
+      1# -> nullRangeFits# (index +# 1#) end accs
+      _ -> 0#
+
+
+advancePageCounts# :: LeafAcc -> Int# -> (# String | Word64# #)
+advancePageCounts# acc bytes# =
+  let !events = fromIntegral (accPageCounts acc .&. 0xffffffff) :: Int
+      !bytes = accPayloadSize acc
+      !added = I# bytes#
+  in if events == 2147483647
+       then (# "Parquet.Nested: event count exceeds signed 32-bit page limit" | #)
+       else
+         if added < 0 || added > 2147483647 - bytes
+           then (# "Parquet.Nested: value payload size exceeds signed 32-bit page limit" | #)
+           else case (fromIntegral (bytes + added) `shiftL` 32) .|. fromIntegral (events + 1) :: Word64 of
+             W64# counts -> (# | counts #)
+{-# INLINE advancePageCounts# #-}
+
+
+leafValueSize :: LeafAcc -> LeafValue -> Int
+leafValueSize acc value = case value of
+  LvInt32 {} -> 4
+  LvInt64 {} -> 8
+  LvFloat16 {} -> 2
+  LvFloat {} -> 4
+  LvDouble {} -> 8
+  LvBool {} -> if booleanState acc `shiftR` 8 == 0 then 1 else 0
+  LvString text -> prefixedSize (TF.lengthWord8 text)
+  LvBinary bytes -> prefixedSize (BS.length bytes)
+  LvFixedBinary bytes -> if BS.length bytes > 2147483647 then -1 else BS.length bytes
+  where
+    prefixedSize size
+      | size < 0 || size > 2147483643 = -1
+      | otherwise = size + 4
+{-# INLINE leafValueSize #-}
+
+
+pushLeafChecked# :: LeafAcc -> Int -> Int -> LeafValue -> (# String | LeafAcc #)
+pushLeafChecked# acc d r value = case leafValueSize acc value of
+  I# bytes -> case advancePageCounts# acc bytes of
+    (# message | #) -> (# message | #)
+    (# | counts #) -> let !next = pushLeaf acc counts d r value in (# | next #)
+{-# INLINE pushLeafChecked# #-}
+
+
+pushLeaf :: LeafAcc -> Word64# -> Int -> Int -> LeafValue -> LeafAcc
+pushLeaf acc counts d r v =
+  let !defs = fromIntegral d : accDefs acc
+      !reps = fromIntegral r : accReps acc
+  in case v of
+       LvBool bit ->
+         let !state = booleanState acc
+             !position = fromIntegral (state `shiftR` 8)
+             !pending = fromIntegral state :: Word8
+             !byte = if bit then setBit pending position else pending
+         in if position == 7
+              then BooleanLeafAcc defs reps (accValuesB acc <> B.word8 byte) (W64# counts) 0
+              else BooleanLeafAcc defs reps (accValuesB acc) (W64# counts) (fromIntegral byte .|. (fromIntegral (position + 1) `shiftL` 8))
+       _ -> LeafAcc defs reps (accValuesB acc <> encodeLeafValue v) (W64# counts)
+
+
+pushNull :: LeafAcc -> Int -> Int -> LeafAcc
+pushNull acc d r =
+  acc
+    { accDefs = fromIntegral d : accDefs acc
+    , accReps = fromIntegral r : accReps acc
+    , accPageCounts = accPageCounts acc + 1
+    }
+{-# INLINE pushNull #-}
+
+
+encodeLeafValue :: LeafValue -> B.Builder
+encodeLeafValue = \case
+  LvInt32 v -> B.int32LE v
+  LvInt64 v -> B.int64LE v
+  LvFloat16 v -> B.word16LE v
+  LvFloat v -> B.word32LE (castFloatToWord32 v)
+  LvDouble v -> B.word64LE (castDoubleToWord64 v)
+  LvBool b -> B.word8 (if b then 1 else 0)
+  -- Defer UTF-8 buffer creation until all page plans have passed. Size
+  -- accounting uses text-2.x's O(1) UTF-8 byte length above.
+  LvString t -> B.Builder $ \sink state ->
+    let !bs = TE.encodeUtf8 t
+    in B.unBuilder (B.word32LE (fromIntegral (BS.length bs)) <> B.byteString bs) sink state
+  LvBinary bs ->
+    B.word32LE (fromIntegral (BS.length bs)) <> B.byteString bs
+  LvFixedBinary bs -> B.byteString bs
+
+
+-- A Data.Foldable.foldM-equivalent specialised to lists; we don't
+-- want to drag the Foldable typeclass machinery into the inner
+-- shredder loop.
+foldM :: (s -> a -> Either String s) -> s -> [a] -> Either String s
+foldM _ !s [] = Right s
+foldM f !s (x : xs) = case f s x of
+  Right s' -> foldM f s' xs
+  Left e -> Left e
+
+
+-- ============================================================
+-- Specialised entry points (kept from the previous PR)
+-- ============================================================
+
+{- | @optional list&lt;optional INT32&gt;@ shred wrapper (the Iceberg
+V3 default-value-array shape). Internally builds a 'NestedSchema'
+and a 'V.Vector NestedRow' and calls 'shred'.
+-}
+encodeOptionalListOptionalI32
+  :: Text
+  -> V.Vector (Maybe (V.Vector (Maybe Int32)))
+  -> NestedLeaf
+encodeOptionalListOptionalI32 outerName =
+  optListOptPrim outerName LtInt32 (LvInt32 . id)
+
+
+encodeOptionalListOptionalI64
+  :: Text
+  -> V.Vector (Maybe (V.Vector (Maybe Int64)))
+  -> NestedLeaf
+encodeOptionalListOptionalI64 outerName =
+  optListOptPrim outerName LtInt64 LvInt64
+
+
+encodeOptionalListOptionalDouble
+  :: Text
+  -> V.Vector (Maybe (V.Vector (Maybe Double)))
+  -> NestedLeaf
+encodeOptionalListOptionalDouble outerName =
+  optListOptPrim outerName LtDouble LvDouble
+
+
+optListOptPrim
+  :: Text
+  -> LeafType
+  -> (a -> LeafValue)
+  -> V.Vector (Maybe (V.Vector (Maybe a)))
+  -> NestedLeaf
+optListOptPrim outerName lt mkLeaf rows =
+  let !schema = NSOptional (NSList (NSOptional (NSPrimitive lt)))
+      mkRow Nothing = NRNull
+      mkRow (Just inner) =
+        NRList
+          ( V.map
+              ( \case
+                  Nothing -> NRNull
+                  Just v -> NRLeaf (mkLeaf v)
+              )
+              inner
+          )
+      !nrows = V.map mkRow rows
+  in case shred schema nrows of
+       Right ls
+         | V.length ls == 1 ->
+             let leaf = V.unsafeIndex ls 0
+             in leaf {nlPath = V.fromList [outerName, "list", "element"]}
+       Right _ -> error "Parquet.Nested: shred produced wrong leaf count"
+       Left e -> error ("Parquet.Nested: shred failed: " ++ e)
+
+
+-- ============================================================
+-- Schema helpers (kept from the previous PR)
+-- ============================================================
+
+optionalListSchemaSegments
+  :: Text
+  -> ParquetType
+  -> Maybe Int32
+  -> Maybe Int32
+  -> [SchemaElement]
+optionalListSchemaSegments outerName leafType outerFid leafFid =
+  [ SchemaElement
+      { seTypeLength = Nothing
+      , seName = outerName
+      , seRepetition = Just Optional
+      , seType = Nothing
+      , seNumChildren = Just 1
+      , seConvertedType = Just CTList
+      , seLogicalType = Just LTList
+      , seFieldId = outerFid
+      }
+  , SchemaElement
+      { seTypeLength = Nothing
+      , seName = "list"
+      , seRepetition = Just Repeated
+      , seType = Nothing
+      , seNumChildren = Just 1
+      , seConvertedType = Nothing
+      , seLogicalType = Nothing
+      , seFieldId = Nothing
+      }
+  , SchemaElement
+      { seTypeLength = Nothing
+      , seName = "element"
+      , seRepetition = Just Optional
+      , seType = Just leafType
+      , seNumChildren = Nothing
+      , seConvertedType = Nothing
+      , seLogicalType = Nothing
+      , seFieldId = leafFid
+      }
+  ]
+
+
+buildOptionalListFile
+  :: ParquetType
+  -> NestedLeaf
+  -> Int
+  -> ByteString
+buildOptionalListFile leafType leaf numRows =
+  either error id (buildOptionalListFileEither leafType leaf numRows)
+
+
+{- | Checked optional-list convenience writer. The leaf must describe the
+standard optional list of optional primitives, with path @name/list/element@.
+Counts, level ranges, row boundaries and the complete page size are checked
+before encoding level streams or copying the supplied PLAIN value bytes.
+'buildOptionalListFile' is the exception-raising convenience wrapper.
+-}
+buildOptionalListFileEither :: ParquetType -> NestedLeaf -> Int -> Either String ByteString
+buildOptionalListFileEither leafType leaf numRows = do
+  if nlMaxDef leaf /= 3 || nlMaxRep leaf /= 1
+    then Left "Parquet.Nested: optional-list leaf needs maximum definition/repetition levels 3/1"
+    else Right ()
+  let path = nlPath leaf
+  if V.length path /= 3 || path V.! 1 /= "list" || path V.! 2 /= "element"
+    then Left "Parquet.Nested: optional-list leaf needs path name/list/element"
+    else Right ()
+  plan <- planNestedLeafPage numRows leaf
+  validateOptionalListBoundaries leaf
+  validateOptionalListPlainSize leafType leaf
+  pageSize <- checkedNestedFileSize (plannedNestedPageSize plan)
+  let
+    !numEvents = VP.length (nlDefLevels leaf)
+    !schema =
+      V.fromList
+        ( SchemaElement
+            { seTypeLength = Nothing
+            , seName = "schema"
+            , seRepetition = Nothing
+            , seType = Nothing
+            , seNumChildren = Just 1
+            , seConvertedType = Nothing
+            , seLogicalType = Nothing
+            , seFieldId = Nothing
+            }
+            : optionalListSchemaSegments
+              (V.unsafeIndex (nlPath leaf) 0)
+              leafType
+              Nothing
+              Nothing
+        )
+
+    !colChunk =
+      ColumnChunk
+        { ccFilePath = Nothing
+        , ccFileOffset = 0
+        , ccMetadata =
+            Just
+              ColumnMetadata
+                { cmType = leafType
+                , cmEncodings = V.fromList [Plain, RLE]
+                , cmPathInSchema = nlPath leaf
+                , cmCodec = Uncompressed
+                , cmNumValues = fromIntegral numEvents
+                , cmTotalUncompressedSize = fromIntegral pageSize
+                , cmTotalCompressedSize = fromIntegral pageSize
+                , cmDataPageOffset = 4
+                , cmDictionaryPageOffset = Nothing
+                , cmStatistics =
+                    Just
+                      Statistics
+                        { statMinValueExact = Nothing
+                        , statMaxValueExact = Nothing
+                        , statNanCount = Nothing
+                        , statMin = Nothing
+                        , statMax = Nothing
+                        , statNullCount = Just (fromIntegral (numEvents - nlValueCount leaf))
+                        , statDistinctCount = Nothing
+                        , statMinValue = Nothing
+                        , statMaxValue = Nothing
+                        }
+                , cmBloomFilterOffset = Nothing
+                , cmBloomFilterLength = Nothing
+                }
+        , ccOffsetIndexOffset = Nothing
+        , ccOffsetIndexLength = Nothing
+        , ccColumnIndexOffset = Nothing
+        , ccColumnIndexLength = Nothing
+        }
+    !rg =
+      RowGroup
+        { rgColumns = V.singleton colChunk
+        , rgTotalByteSize = fromIntegral pageSize
+        , rgNumRows = fromIntegral numRows
+        , rgSortingColumns = Nothing
+        }
+    !fm =
+      FileMetadata
+        { fmVersion = 2
+        , fmSchema = schema
+        , fmNumRows = fromIntegral numRows
+        , fmRowGroups = V.singleton rg
+        , fmCreatedBy = Just "wireform"
+        , fmKeyValueMetadata = Nothing
+        , fmColumnOrders = Nothing
+        }
+  assembleNestedOutput fm (toInteger pageSize) (plannedNestedPageBuilder plan (B.byteString (nlValueBytes leaf)))
+
+
+-- ============================================================
+-- Schema serialisation
+-- ============================================================
+
+{- | Walk a top-level @(name, NestedSchema)@ vector and produce the
+flat 'V.Vector SchemaElement' Parquet's footer expects. The first
+element is always the row-group root; the rest are the schema
+nodes in pre-order DFS, with @num_children@ populated on every
+internal node.
+-}
+nestedSchemaToFlatSchema
+  :: V.Vector (Text, NestedSchema)
+  -> V.Vector SchemaElement
+nestedSchemaToFlatSchema columns =
+  let !root =
+        SchemaElement
+          { seTypeLength = Nothing
+          , seName = "schema"
+          , seRepetition = Nothing
+          , seType = Nothing
+          , seNumChildren = Just (fromIntegral (V.length columns))
+          , seConvertedType = Nothing
+          , seLogicalType = Nothing
+          , seFieldId = Nothing
+          }
+      !cols =
+        concatMap
+          (\(name, sch) -> emitColumn name sch)
+          (V.toList columns)
+  in V.fromList (root : cols)
+
+
+{- | Emit a column's flat schema entries in pre-order DFS. The
+top-level element gets a name and (for compound types) the
+LogicalType / ConvertedType annotation.
+-}
+emitColumn :: Text -> NestedSchema -> [SchemaElement]
+emitColumn outerName outerSchema = goTop outerName outerSchema
+  where
+    -- Top-level: peel the outer Optional / Required wrappers,
+    -- recording the repetition. The actual /child/ that gets the
+    -- name and annotations is what's underneath.
+    goTop name (NSOptional inner) = goNamed name (Just Optional) inner
+    goTop name (NSRequired inner) = goNamed name (Just Required) inner
+    goTop name other = goNamed name (Just Required) other
+
+    -- A "named" node: pick its annotation + group-or-leaf shape.
+    goNamed name rep node = case node of
+      NSPrimitive lt -> [leafSchemaElement name rep lt]
+      NSOptional inner -> goNamed name (Just Optional) inner
+      NSRequired inner -> goNamed name (Just Required) inner
+      NSList inner ->
+        let !groupHead =
+              SchemaElement
+                { seTypeLength = Nothing
+                , seName = name
+                , seRepetition = rep
+                , seType = Nothing
+                , seNumChildren = Just 1
+                , seConvertedType = Just CTList
+                , seLogicalType = Just LTList
+                , seFieldId = Nothing
+                }
+            !listGroup =
+              SchemaElement
+                { seTypeLength = Nothing
+                , seName = "list"
+                , seRepetition = Just Repeated
+                , seType = Nothing
+                , seNumChildren = Just 1
+                , seConvertedType = Nothing
+                , seLogicalType = Nothing
+                , seFieldId = Nothing
+                }
+        in groupHead : listGroup : goNamed "element" (Just Required) inner
+      NSMap k v ->
+        let !groupHead =
+              SchemaElement
+                { seTypeLength = Nothing
+                , seName = name
+                , seRepetition = rep
+                , seType = Nothing
+                , seNumChildren = Just 1
+                , seConvertedType = Just CTMap
+                , seLogicalType = Just LTMap
+                , seFieldId = Nothing
+                }
+            !kvGroup =
+              SchemaElement
+                { seTypeLength = Nothing
+                , seName = "key_value"
+                , seRepetition = Just Repeated
+                , seType = Nothing
+                , seNumChildren = Just 2
+                , seConvertedType = Nothing
+                , seLogicalType = Nothing
+                , seFieldId = Nothing
+                }
+        in groupHead
+             : kvGroup
+             : goNamed "key" (Just Required) k
+             ++ goNamed "value" (Just Required) v
+      NSStruct fields ->
+        let !groupHead =
+              SchemaElement
+                { seTypeLength = Nothing
+                , seName = name
+                , seRepetition = rep
+                , seType = Nothing
+                , seNumChildren = Just (fromIntegral (V.length fields))
+                , seConvertedType = Nothing
+                , seLogicalType = Nothing
+                , seFieldId = Nothing
+                }
+        in groupHead
+             : concatMap
+               (\(fname, fch) -> goNamed fname (Just Required) fch)
+               (V.toList fields)
+      NSFile fields ->
+        let children = F.fileSchemaElements fields
+            groupHead =
+              SchemaElement
+                { seTypeLength = Nothing
+                , seName = name
+                , seRepetition = rep
+                , seType = Nothing
+                , seNumChildren = Just (fromIntegral (V.length children))
+                , seConvertedType = Nothing
+                , seLogicalType = Just LTFile
+                , seFieldId = F.fileSchemaFieldId fields
+                }
+        in groupHead : V.toList children
+      NSVariant ->
+        -- The Iceberg V3 / Spark Variant unshredded shape is:
+        --   <rep> group <name> (VARIANT(1)) {
+        --     required binary metadata;
+        --     required binary value;
+        --   }
+        let !groupHead =
+              SchemaElement
+                { seTypeLength = Nothing
+                , seName = name
+                , seRepetition = rep
+                , seType = Nothing
+                , seNumChildren = Just 2
+                , seConvertedType = Nothing
+                , seLogicalType = Just (LTVariant 1)
+                , seFieldId = Nothing
+                }
+            !metadataLeaf =
+              SchemaElement
+                { seTypeLength = Nothing
+                , seName = "metadata"
+                , seRepetition = Just Required
+                , seType = Just PTByteArray
+                , seNumChildren = Nothing
+                , seConvertedType = Nothing
+                , seLogicalType = Nothing
+                , seFieldId = Nothing
+                }
+            !valueLeaf =
+              SchemaElement
+                { seTypeLength = Nothing
+                , seName = "value"
+                , seRepetition = Just Required
+                , seType = Just PTByteArray
+                , seNumChildren = Nothing
+                , seConvertedType = Nothing
+                , seLogicalType = Nothing
+                , seFieldId = Nothing
+                }
+        in [groupHead, metadataLeaf, valueLeaf]
+      NSVariantWithLimits _ -> goNamed name rep NSVariant
+      NSVariantTyped storage -> case goNamed name rep (storageLayout storage) of
+        group : children ->
+          V.toList (V.imap (\index node -> node {seFieldId = maybe Nothing id (storageFieldIds storage V.!? index)}) (V.fromList (group {seLogicalType = Just (LTVariant 1)} : children)))
+        [] -> []
+
+
+-- ============================================================
+-- Whole-file builder for arbitrary nested schemas
+-- ============================================================
+
+{- | Build a complete Parquet file from a vector of top-level
+@(name, NestedSchema)@ columns plus a vector of row-major
+'NestedRow' values, one per column. Row count = length of the
+inner vector for any column (they must all match).
+
+The file layout is one DATA_PAGE_V2 per primitive leaf, no
+compression, no bloom filter / page index. Suitable for the
+pyarrow round-trip test that ground-truths the shred against
+arrow-cpp's reader.
+-}
+buildNestedFile
+  :: V.Vector (Text, NestedSchema)
+  -> V.Vector (V.Vector NestedRow)
+  -- ^ outer index = column, inner = row
+  -> Either String ByteString
+buildNestedFile = buildNestedFileWithAux V.empty
+
+
+{- | Nested writer with one auxiliary record per physical leaf, in schema
+order. An empty vector selects the legacy uncompressed V2 layout. Supports
+compression, V1/V2 pages, bloom filters and indexes. Automatic column indexes
+are emitted when bounds or all-null statistics are available. Encryption is
+rejected explicitly; callers must use an IO writer for random nonces.
+-}
+buildNestedFileWithAux
+  :: V.Vector PW.ColumnAux
+  -> V.Vector (Text, NestedSchema)
+  -> V.Vector (V.Vector NestedRow)
+  -> Either String ByteString
+buildNestedFileWithAux = buildNestedFileWithBloomFilters []
+
+
+{- | Like 'buildNestedFileWithAux', generating a bloom filter for every
+physical leaf beneath each requested top-level field name. Unknown names
+are rejected. Explicit per-leaf filters take precedence over generation.
+-}
+buildNestedFileWithBloomFilters
+  :: [Text]
+  -> V.Vector PW.ColumnAux
+  -> V.Vector (Text, NestedSchema)
+  -> V.Vector (V.Vector NestedRow)
+  -> Either String ByteString
+buildNestedFileWithBloomFilters = buildNestedFileWithBloomFiltersUsing assembleNestedOutputChecked
+
+
+-- | Pass validated page builders and metadata to a custom file assembler.
+-- The validation action must run before the builder is materialized.
+buildNestedFileWithBloomFiltersUsing
+  :: (FileMetadata -> Integer -> Either String () -> B.Builder -> Either String a)
+  -> [Text]
+  -> V.Vector PW.ColumnAux
+  -> V.Vector (Text, NestedSchema)
+  -> V.Vector (V.Vector NestedRow)
+  -> Either String a
+buildNestedFileWithBloomFiltersUsing finish bloomNames suppliedAux columns rowsPerColumn
+  | V.length columns /= V.length rowsPerColumn =
+      Left "Parquet.Nested.buildNestedFile: column count mismatch"
+  | V.null columns = Left "Parquet.Nested.buildNestedFile: at least one column required"
+  | otherwise = do
+      mapM_ (\name -> if V.any ((== name) . fst) columns then Right () else Left "Parquet.Nested: requested bloom field does not exist") bloomNames
+      V.mapM_ validateNestedAux suppliedAux
+      let !numRows = V.length (V.unsafeIndex rowsPerColumn 0)
+      _ <- nestedPageCount "row count" numRows
+      -- Sanity: every column must have the same row count.
+      let !rowCounts = V.map V.length rowsPerColumn
+      if V.any (/= numRows) rowCounts
+        then Left "Parquet.Nested.buildNestedFile: row counts differ between columns"
+        else do
+          shreds <-
+            V.imapM
+              ( \i (_name, sch) ->
+                  let !rows = V.unsafeIndex rowsPerColumn i
+                  in planShred sch rows
+              )
+              columns
+          -- A null-only empty FILE contributes no physical leaf.
+          let !flatSchema = nestedSchemaToFlatSchema columns
+              -- Patch each leaf's path so that its first element is
+              -- the column name; the shredder uses "" by default.
+              !columnNames = V.toList (V.map fst columns)
+              !leavesByCol = V.toList shreds
+              !pathedPlans =
+                concat
+                  ( zipWith
+                      ( \name leaves ->
+                          map
+                            (\prepared -> let descriptor = slpDescriptor prepared in prepared {slpDescriptor = descriptor {ldPath = V.cons name (V.tail (ldPath descriptor))}})
+                            (V.toList leaves)
+                      )
+                      columnNames
+                      leavesByCol
+                  )
+          let leafCount = length pathedPlans
+              baseAuxes = if V.null suppliedAux then V.replicate leafCount PW.emptyColumnAux {PW.caPageVersion = PW.PageV2} else suppliedAux
+          if V.length baseAuxes /= leafCount
+            then Left "Parquet.Nested: auxiliary column count mismatch"
+            else Right ()
+          let leafFields = V.filter (maybe False (const True) . seType) flatSchema
+              generateStats = not (V.null suppliedAux)
+          if V.length leafFields /= leafCount
+            then Left "Parquet.Nested: schema and shredded leaf counts disagree"
+            else Right ()
+          generated <- V.imapM (\index prepared -> prepareAuxiliary generateStats (leafFields V.! index) bloomNames (baseAuxes V.! index) prepared) (V.fromList pathedPlans)
+          let auxes = V.map preparedAux generated
+          encoded <- V.mapM (\entry -> let prepared = preparedLeaf entry in EncodedNestedLeaf prepared (preparedStatistics entry) <$> encodeNestedPlan numRows (preparedAux entry) prepared) generated
+          let encodedPlans = V.toList encoded
+          rowGroupSize <- checkedNestedFileSize (V.foldl' (\total leaf -> total + toInteger (nepSize (enlPage leaf))) 0 encoded)
+          let !startOfData = 4 :: Int
+          -- Build per-column metadata, threading the file-relative
+          -- offset.
+          let buildCol :: Int -> [EncodedNestedLeaf] -> [ColumnChunk]
+              buildCol _ [] = []
+              buildCol off (encodedLeaf : rest) =
+                let prepared = enlPlan encodedLeaf
+                    encodedPage = enlPage encodedLeaf
+                    page = slpPage prepared
+                    descriptor = slpDescriptor prepared
+                    sz = nepSize encodedPage
+                    ldType' = leafParquetType (ldType descriptor)
+                    cm =
+                      ColumnMetadata
+                        { cmType = ldType'
+                        , cmEncodings =
+                            if ldMaxDef descriptor > 0 || ldMaxRep descriptor > 0
+                              then V.fromList [Plain, RLE]
+                              else V.singleton Plain
+                        , cmPathInSchema = ldPath descriptor
+                        , cmCodec = nepCodec encodedPage
+                        , cmNumValues =
+                            fromIntegral
+                              (VP.length (slpDefinitions prepared))
+                        , cmTotalUncompressedSize = fromIntegral (nepUncompressedSize encodedPage)
+                        , cmTotalCompressedSize = fromIntegral sz
+                        , cmDataPageOffset = fromIntegral off
+                        , cmDictionaryPageOffset = Nothing
+                        , cmStatistics = Just (enlStatistics encodedLeaf)
+                        , cmBloomFilterOffset = Nothing
+                        , cmBloomFilterLength = Nothing
+                        }
+                    cc =
+                      ColumnChunk
+                        { ccFilePath = Nothing
+                        , ccFileOffset = 0
+                        , ccMetadata = Just cm
+                        , ccOffsetIndexOffset = Nothing
+                        , ccOffsetIndexLength = Nothing
+                        , ccColumnIndexOffset = Nothing
+                        , ccColumnIndexLength = Nothing
+                        }
+                in cc : buildCol (off + sz) rest
+              !columnChunks =
+                buildCol
+                  startOfData
+                  encodedPlans
+              !rg =
+                RowGroup
+                  { rgColumns = V.fromList columnChunks
+                  , rgTotalByteSize = V.foldl' (\total leaf -> total + fromIntegral (nepUncompressedSize (enlPage leaf))) 0 encoded
+                  , rgNumRows = fromIntegral numRows
+                  , rgSortingColumns = Nothing
+                  }
+              !fm =
+                FileMetadata
+                  { fmVersion = 2
+                  , fmSchema = flatSchema
+                  , fmNumRows = fromIntegral numRows
+                  , fmRowGroups = V.singleton rg
+                  , fmCreatedBy = Just "wireform"
+                  , fmKeyValueMetadata = Nothing
+                  , fmColumnOrders = if generateStats || V.any (\aux -> PW.caGeneratePageIndex aux || maybe False (const True) (PW.caColumnIndex aux)) auxes then Just (V.map NestedStats.statisticsOrderFor leafFields) else Nothing
+                  }
+          layout <- PW.layoutColumnAuxiliaries (V.singleton rg) (V.singleton auxes) (4 + rowGroupSize)
+          finish
+            fm {fmRowGroups = PW.auxRowGroups layout}
+            (toInteger (PW.auxEndOffset layout) - 4)
+            (V.imapM_ (\i (_, schema) -> validateVariantRows schema (V.unsafeIndex rowsPerColumn i)) columns)
+            (foldMap (nepBuilder . enlPage) encodedPlans <> foldMap B.byteString (PW.auxParts layout))
+
+
+-- Keep the page plan and its per-leaf options together while generated
+-- filters replace only missing explicit filters.
+data PreparedNestedLeaf = PreparedNestedLeaf
+  { preparedLeaf :: !ShreddedLeafPlan
+  , preparedAux :: !PW.ColumnAux
+  , preparedStatistics :: !Statistics
+  }
+
+
+prepareAuxiliary :: Bool -> SchemaElement -> [Text] -> PW.ColumnAux -> ShreddedLeafPlan -> Either String PreparedNestedLeaf
+prepareAuxiliary generateStats field names aux prepared = do
+  let descriptor = slpDescriptor prepared
+      count = nppValueCount (slpPage prepared)
+      nulls = VP.length (slpDefinitions prepared) - count
+      nullStatistics = Statistics Nothing Nothing (Just (fromIntegral nulls)) Nothing Nothing Nothing Nothing Nothing Nothing
+      requestBloom = case PW.caBloomFilter aux of
+        Just _ -> False
+        Nothing -> V.head (ldPath descriptor) `elem` names
+  if not generateStats && not requestBloom
+    then pure (PreparedNestedLeaf prepared aux nullStatistics)
+    else do
+      let bytes = shreddedValueBytes (slpValues prepared)
+          cached = prepared {slpValues = MaterializedValues bytes}
+      bloom <- if requestBloom then Just <$> NestedBloom.buildBloomFilter field count bytes else pure (PW.caBloomFilter aux)
+      stats <- if generateStats then NestedStats.columnStatistics (NestedStats.statisticsOrderFor field) field nulls count bytes else pure nullStatistics
+      pure (PreparedNestedLeaf cached aux {PW.caBloomFilter = bloom} stats)
+
+
+data EncodedNestedPage = EncodedNestedPage
+  { nepBuilder :: !B.Builder
+  , nepSize :: {-# UNPACK #-} !Int
+  , nepUncompressedSize :: {-# UNPACK #-} !Int
+  , nepCodec :: !Compression
+  }
+
+
+data EncodedNestedLeaf = EncodedNestedLeaf
+  { enlPlan :: !ShreddedLeafPlan
+  , enlStatistics :: !Statistics
+  , enlPage :: !EncodedNestedPage
+  }
+
+
+validateNestedAux :: PW.ColumnAux -> Either String ()
+validateNestedAux aux = do
+  PW.validateAuxIndexes aux
+  Compress.validateCompression (PW.caCodec aux)
+  case PW.caEncryption aux of
+    Just _ -> Left "Parquet.Nested: encryption requires a nested IO writer"
+    Nothing -> Right ()
+
+
+encodeNestedPlan :: Int -> PW.ColumnAux -> ShreddedLeafPlan -> Either String EncodedNestedPage
+encodeNestedPlan _ aux prepared
+  | PW.caPageVersion aux == PW.PageV2 && PW.caCodec aux == Uncompressed =
+      let plan = slpPage prepared
+          size = fromInteger (plannedNestedPageSize plan)
+      in Right (EncodedNestedPage (plannedNestedPageBuilder plan (shreddedValueBuilder (slpValues prepared))) size size Uncompressed)
+encodeNestedPlan numRows aux prepared = do
+  let plan = slpPage prepared
+      descriptor = slpDescriptor prepared
+      codec = PW.caCodec aux
+      version = PW.caPageVersion aux
+      levelBytes = nestedLevelSize (nppRepetition plan) + nestedLevelSize (nppDefinition plan)
+      prefixes = case version of
+        PW.PageV1 -> (if ldMaxRep descriptor > 0 then 4 else 0) + (if ldMaxDef descriptor > 0 then 4 else 0)
+        PW.PageV2 -> 0
+      plainSize = fromIntegral (nppPayloadSize plan) + prefixes
+      values = shreddedValueBuilder (slpValues prepared)
+      repetition = maybe BS.empty LE.encodeHybridPlan (nppRepetition plan)
+      definition = maybe BS.empty LE.encodeHybridPlan (nppDefinition plan)
+      levels = levelPart version (nppRepetition plan) repetition <> levelPart version (nppDefinition plan) definition
+      plainBody = levels <> values
+  uncompressed <- nestedPageCount "uncompressed page size" plainSize
+  -- The uncompressed path retains the builder directly, avoiding an
+  -- intermediate values buffer and an extra copy for existing callers.
+  payload <- case codec of
+    Uncompressed -> Right (NestedPayload plainBody plainSize)
+    _ -> case version of
+      PW.PageV1 -> do
+        compressed <- Compress.compressPageBytes codec (BL.toStrict (B.toLazyByteString plainBody))
+        Right (NestedPayload (B.byteString compressed) (BS.length compressed))
+      PW.PageV2 -> do
+        compressed <- Compress.compressPageBytes codec (shreddedValueBytes (slpValues prepared))
+        Right (NestedPayload (levels <> B.byteString compressed) (levelBytes + BS.length compressed))
+  compressed <- nestedPageCount "compressed page size" (npSize payload)
+  let events = fromIntegral (VP.length (slpDefinitions prepared))
+      rows = fromIntegral numRows
+      kind = case version of
+        PW.PageV1 -> PP.PtDataPage (PP.DataPageHeader events 0)
+        PW.PageV2 -> PP.PtDataPageV2 (PP.DataPageHeaderV2 events (events - fromIntegral (nppValueCount plan)) rows 0 (fromIntegral (BS.length definition)) (fromIntegral (BS.length repetition)) (codec /= Uncompressed))
+      header = PW.encodePageHeader (PP.PageHeader kind (Just uncompressed) (Just compressed))
+      headerSize = BS.length header
+  Right (EncodedNestedPage (B.byteString header <> npBuilder payload) (headerSize + npSize payload) (headerSize + plainSize) codec)
+  where
+    levelPart PW.PageV1 (Just _) bytes = B.word32LE (fromIntegral (BS.length bytes)) <> B.byteString bytes
+    levelPart _ _ bytes = B.byteString bytes
+
+
+data NestedPayload = NestedPayload
+  { npBuilder :: !B.Builder
+  , npSize :: {-# UNPACK #-} !Int
+  }
+
+
+-- Page-header counts and byte sizes are signed i32 in parquet.thrift.
+-- Keep validation/planning separate from encoding so a rejected page never
+-- allocates level payloads or copies an oversized supplied value payload.
+data NestedPagePlan = NestedPagePlan
+  { nppHeaderBytes :: !ByteString
+  , nppDefinition :: !(Maybe LE.HybridPlan)
+  , nppRepetition :: !(Maybe LE.HybridPlan)
+  , nppPayloadSize :: {-# UNPACK #-} !Int32
+  , nppValueCount :: {-# UNPACK #-} !Int
+  }
+
+
+-- Page metadata can be measured from levels and planned value length,
+-- without constructing the potentially large encoded value buffer.
+-- Caller-supplied levels need a full count/boundary check. The internal
+-- shredder has already validated rows and counted each leaf; retain those
+-- counts instead of rescanning levels it just constructed.
+data NestedCountSource = CheckLevelCounts !(Maybe Int) | ShreddedCounts {-# UNPACK #-} !Int
+
+
+data NestedPageInput = NestedPageInput
+  { npiRows :: {-# UNPACK #-} !Int
+  , npiMaxDef :: {-# UNPACK #-} !Int
+  , npiMaxRep :: {-# UNPACK #-} !Int
+  , npiDefinitions :: !(VP.Vector Int32)
+  , npiRepetitions :: !(VP.Vector Int32)
+  , npiCounts :: !NestedCountSource
+  , npiValueBytes :: {-# UNPACK #-} !Int
+  }
+
+
+nestedPageCount :: String -> Int -> Either String Int32
+nestedPageCount label count
+  | count < 0 || toInteger count > toInteger (maxBound :: Int32) =
+      Left ("Parquet.Nested: " ++ label ++ " exceeds signed 32-bit page limit")
+  | otherwise = Right (fromIntegral count)
+
+
+planNestedLeafPage :: Int -> NestedLeaf -> Either String NestedPagePlan
+planNestedLeafPage numRows leaf =
+  planNestedPageInput
+    ( NestedPageInput
+        numRows
+        (nlMaxDef leaf)
+        (nlMaxRep leaf)
+        (nlDefLevels leaf)
+        (nlRepLevels leaf)
+        (CheckLevelCounts (Just (nlValueCount leaf)))
+        (BS.length (nlValueBytes leaf))
+    )
+
+
+planNestedPageInput :: NestedPageInput -> Either String NestedPagePlan
+planNestedPageInput input = do
+  let !numRows = npiRows input
+  rows <- nestedPageCount "row count" numRows
+  let defs = npiDefinitions input
+      reps = npiRepetitions input
+      !numEvents = VP.length defs
+      expectedValues = case npiCounts input of CheckLevelCounts expected -> expected; ShreddedCounts count -> Just count
+      !valueBytes = npiValueBytes input
+  events <- nestedPageCount "event count" numEvents
+  case expectedValues of
+    Just count -> do
+      _ <- nestedPageCount "value count" count
+      if count > numEvents then Left "Parquet.Nested: inconsistent leaf event/value/row counts or level maxima" else Right ()
+    Nothing -> Right ()
+  _ <- nestedPageCount "value payload size" valueBytes
+  _ <- nestedPageCount "maximum definition level" (npiMaxDef input)
+  _ <- nestedPageCount "maximum repetition level" (npiMaxRep input)
+  if VP.length reps /= numEvents || numRows > numEvents || npiMaxRep input > npiMaxDef input
+    then Left "Parquet.Nested: inconsistent leaf event/value/row counts or level maxima"
+    else Right ()
+  -- This loop returns one public error/result for the entire page. Strict
+  -- counters become Int# workers; there is no per-event Either or tuple.
+  let validate !index !observedRows !observedValues
+        | index == numEvents =
+            if observedRows == numRows && maybe True (== observedValues) expectedValues
+              then Right observedValues
+              else Left "Parquet.Nested: levels disagree with row or non-null value count"
+        | otherwise =
+            let !rep = VP.unsafeIndex reps index
+                !def = VP.unsafeIndex defs index
+            in if index == 0 && rep /= 0
+                 then Left "Parquet.Nested: a V2 page must begin at a row boundary"
+                 else validate (index + 1) (observedRows + if rep == 0 then 1 else 0) (observedValues + if fromIntegral def == npiMaxDef input then 1 else 0)
+  numValues <- case npiCounts input of
+    CheckLevelCounts _ -> validate 0 0 0
+    ShreddedCounts count -> Right count
+  definition <- levelPlan (npiMaxDef input) defs
+  repetition <- levelPlan (npiMaxRep input) reps
+  let !total = toInteger valueBytes + toInteger (nestedLevelSize definition) + toInteger (nestedLevelSize repetition)
+  if total > toInteger (maxBound :: Int32)
+    then Left "Parquet.Nested: complete page payload exceeds signed 32-bit limit"
+    else
+      let !payloadSize = fromInteger total
+          !header =
+            PP.PageHeader
+              { PP.phType =
+                  PP.PtDataPageV2
+                    PP.DataPageHeaderV2
+                      { PP.dph2NumValues = events
+                      , PP.dph2NumNulls = fromIntegral (numEvents - numValues)
+                      , PP.dph2NumRows = rows
+                      , PP.dph2Encoding = 0
+                      , PP.dph2DefLevelsLen = fromIntegral (nestedLevelSize definition)
+                      , PP.dph2RepLevelsLen = fromIntegral (nestedLevelSize repetition)
+                      , PP.dph2IsCompressed = False
+                      }
+              , PP.phUncompressedPageSize = Just payloadSize
+              , PP.phCompressedPageSize = Just payloadSize
+              }
+      in Right (NestedPagePlan (PW.encodePageHeader header) definition repetition payloadSize numValues)
+  where
+    levelPlan 0 _ | ShreddedCounts _ <- npiCounts input = Right Nothing
+    levelPlan maximumLevel levels = do
+      plan <- LE.planRLEHybrid (LE.bitWidthFor maximumLevel) (fromIntegral maximumLevel) levels
+      Right (if maximumLevel == 0 then Nothing else Just plan)
+
+
+nestedLevelSize :: Maybe LE.HybridPlan -> Int
+nestedLevelSize = maybe 0 LE.hybridEncodedSize
+
+
+-- A continuation belongs to the same repeated element group. Both its
+-- predecessor and current event must have crossed that group's definition
+-- threshold (2 for optional-list<optional primitive>). A null or empty list
+-- therefore cannot be followed by another event in the same row.
+validateOptionalListBoundaries :: NestedLeaf -> Either String ()
+validateOptionalListBoundaries leaf = go 0 0
+  where
+    defs = nlDefLevels leaf
+    reps = nlRepLevels leaf
+    go !index !previousDef
+      | index == VP.length defs = Right ()
+      | otherwise =
+          let !def = VP.unsafeIndex defs index
+              !rep = VP.unsafeIndex reps index
+          in if rep /= 0 && (previousDef < 2 || def < 2)
+               then Left "Parquet.Nested: repeated value continues a null or empty list"
+               else go (index + 1) def
+
+
+-- The convenience schema has no fixed-byte width parameter. Other fixed
+-- physical types have an exact PLAIN size; BYTE_ARRAY carries its own lengths.
+validateOptionalListPlainSize :: ParquetType -> NestedLeaf -> Either String ()
+validateOptionalListPlainSize physical leaf = case physical of
+  PTBoolean -> checkSize ((toInteger (nlValueCount leaf) + 7) `quot` 8)
+  PTInt32 -> fixed 4
+  PTInt64 -> fixed 8
+  PTInt96 -> fixed 12
+  PTFloat -> fixed 4
+  PTDouble -> fixed 8
+  PTByteArray -> validateNestedPlainByteArrays (nlValueCount leaf) (nlValueBytes leaf)
+  PTFixedLenByteArray -> Left "Parquet.Nested: optional-list schema cannot specify a fixed-byte width"
+  where
+    fixed width = checkSize (width * toInteger (nlValueCount leaf))
+    checkSize expected
+      | expected == toInteger (BS.length (nlValueBytes leaf)) = Right ()
+      | otherwise = Left "Parquet.Nested: PLAIN payload size differs from physical value count"
+
+
+validateNestedPlainByteArrays :: Int -> ByteString -> Either String ()
+validateNestedPlainByteArrays count bytes = go 0 0
+  where
+    !size = BS.length bytes
+    go !index !offset
+      | index == count =
+          if offset == size then Right () else Left "Parquet.Nested: trailing PLAIN BYTE_ARRAY bytes"
+      | size - offset < 4 = Left "Parquet.Nested: truncated PLAIN BYTE_ARRAY length"
+      | otherwise =
+          let !lengthWord =
+                fromIntegral (BSU.unsafeIndex bytes offset)
+                  + (fromIntegral (BSU.unsafeIndex bytes (offset + 1)) `shiftL` 8)
+                  + (fromIntegral (BSU.unsafeIndex bytes (offset + 2)) `shiftL` 16)
+                  + (fromIntegral (BSU.unsafeIndex bytes (offset + 3)) `shiftL` 24)
+                  :: Word32
+          in if lengthWord > fromIntegral (size - offset - 4)
+               then Left "Parquet.Nested: truncated PLAIN BYTE_ARRAY value"
+               else go (index + 1) (offset + 4 + fromIntegral lengthWord)
+
+
+checkedNestedFileSize :: Integer -> Either String Int
+checkedNestedFileSize size
+  | size < 0 || size > toInteger (maxBound :: Int) - 4 = Left "Parquet.Nested: row-group bytes exceed addressable file offsets"
+  | otherwise = Right (fromInteger size)
+
+
+plannedNestedPageBuilder :: NestedPagePlan -> B.Builder -> B.Builder
+plannedNestedPageBuilder plan values =
+  let !defStream = maybe BS.empty LE.encodeHybridPlan (nppDefinition plan)
+      !repStream = maybe BS.empty LE.encodeHybridPlan (nppRepetition plan)
+  in B.byteString (nppHeaderBytes plan) <> B.byteString repStream <> B.byteString defStream <> values
+
+
+assembleNestedOutput :: FileMetadata -> Integer -> B.Builder -> Either String ByteString
+assembleNestedOutput metadata dataSize = assembleNestedOutputChecked metadata dataSize (Right ())
+
+
+assembleNestedOutputChecked :: FileMetadata -> Integer -> Either String () -> B.Builder -> Either String ByteString
+assembleNestedOutputChecked metadata dataSize validatePayloads body = do
+  footer <- PF.writeFooterEither metadata
+  let !total = dataSize + 4 + toInteger (BS.length footer)
+  if dataSize < 0 || total > toInteger (maxBound :: Int)
+    then Left "Parquet.Nested: complete file exceeds addressable byte size"
+    else do
+      validatePayloads
+      Right (B.toStrictByteStringWith (fromInteger total) (B.byteString PF.parquetMagic <> body <> B.byteString footer))
+
+
+plannedNestedPageSize :: NestedPagePlan -> Integer
+plannedNestedPageSize plan = toInteger (nppPayloadSize plan) + toInteger (BS.length (nppHeaderBytes plan))
+
+
+-- silence unused 'leafConvertedType' / 'leafLogicalType' / 'leafParquetType' warnings
+_unusedHelpers :: (LeafType -> ParquetType, LeafType -> Maybe ConvertedType, LeafType -> Maybe LogicalType)
+_unusedHelpers = (leafParquetType, leafConvertedType, leafLogicalType)
diff --git a/src/Parquet/Nested/Bloom.hs b/src/Parquet/Nested/Bloom.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Nested/Bloom.hs
@@ -0,0 +1,69 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE RankNTypes #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+
+-- | Bloom construction from the present values of a shredded PLAIN leaf.
+module Parquet.Nested.Bloom (buildBloomFilter) where
+
+import Control.Monad.ST (ST)
+import Data.Bits (shiftR, (.&.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Unsafe qualified as BSU
+import Parquet.BloomFilter qualified as Bloom
+import Parquet.Nested.Plain (PlainLayout (..), lengthAt, plainLayout, validPlainValues)
+import Parquet.Types (SchemaElement)
+
+
+-- Validate once before the ST insertion loop. BYTE_ARRAY lengths belong to
+-- PLAIN framing and must not be included in the value's hash. BOOLEAN values
+-- are hashed individually as 0/1 bytes, rather than as packed page bits.
+buildBloomFilter :: SchemaElement -> Int -> ByteString -> Either String Bloom.Sbbf
+buildBloomFilter field count bytes = do
+  layout <- plainLayout field
+  if not (validPlainValues layout count bytes)
+    then Left "Parquet.Nested: bloom values disagree with the physical PLAIN layout"
+    else pure $ case layout of
+      BooleanValues -> build (insertBooleans count bytes)
+      VariableValues -> build (insertByteArrays count bytes)
+      FixedValues width -> build (insertFixed count width bytes)
+  where
+    build :: (forall s. Bloom.SbbfBuilder s -> ST s ()) -> Bloom.Sbbf
+    build action = Bloom.buildSbbf (Bloom.optimalNumBytes (max 1 count) 0.01) action
+
+
+insertFixed :: forall s. Int -> Int -> ByteString -> Bloom.SbbfBuilder s -> ST s ()
+insertFixed count width bytes builder = go 0 0
+  where
+    go :: Int -> Int -> ST s ()
+    go !index !offset
+      | index == count = pure ()
+      | otherwise = do
+          Bloom.sbbfBuilderInsert builder (BS.take width (BS.drop offset bytes))
+          go (index + 1) (offset + width)
+
+
+insertByteArrays :: forall s. Int -> ByteString -> Bloom.SbbfBuilder s -> ST s ()
+insertByteArrays count bytes builder = go 0 0
+  where
+    go :: Int -> Int -> ST s ()
+    go !index !offset
+      | index == count = pure ()
+      | otherwise = do
+          let !length_ = lengthAt bytes offset
+          Bloom.sbbfBuilderInsert builder (BS.take length_ (BS.drop (offset + 4) bytes))
+          go (index + 1) (offset + 4 + length_)
+
+
+insertBooleans :: forall s. Int -> ByteString -> Bloom.SbbfBuilder s -> ST s ()
+insertBooleans count bytes builder = go 0
+  where
+    go :: Int -> ST s ()
+    go !index
+      | index == count = pure ()
+      | otherwise = do
+          let !value = BSU.unsafeIndex bytes (index `quot` 8) `shiftR` (index `rem` 8) .&. 1
+          Bloom.sbbfBuilderInsert builder (if value == 0 then falseByte else trueByte)
+          go (index + 1)
+    falseByte = BS.singleton 0
+    trueByte = BS.singleton 1
diff --git a/src/Parquet/Nested/Fast.hs b/src/Parquet/Nested/Fast.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Nested/Fast.hs
@@ -0,0 +1,836 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeFamilies #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Two-pass shredding into exact-size level and PLAIN buffers. The first
+pass validates all rows and sizes before any payload buffer is allocated.
+FILE and Variant keep their specialized validation/normalization path.
+-}
+module Parquet.Nested.Fast (FastLeaf (..), shredFast) where
+
+import Control.Monad.Primitive (PrimMonad (..), touch)
+import Control.Monad.ST (runST)
+import Control.Monad.ST.Unsafe (unsafeIOToST)
+import Data.Bits (setBit, shiftR)
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Internal qualified as BSI
+import Data.ByteString.Short.Internal qualified as SBS
+import Data.Int (Int32)
+import Data.Primitive.ByteArray
+import Data.Primitive.PrimArray
+import Data.Text.Foreign qualified as TF
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Primitive.Mutable qualified as MVP
+import Data.Word (Word16, Word32, Word64, Word8, byteSwap16, byteSwap32, byteSwap64)
+import Foreign.ForeignPtr (withForeignPtr)
+import Foreign.Marshal.Utils (copyBytes)
+import Foreign.Ptr (plusPtr)
+import GHC.ByteOrder (ByteOrder (..), targetByteOrder)
+import GHC.Exts (Int (I#), Int#, State#, isTrue#, (+#), (==#))
+import GHC.Float (castDoubleToWord64, castFloatToWord32)
+import GHC.ST (ST (..))
+import Parquet.Nested.Types
+import Parquet.Types (LtTimeUnit (..))
+
+
+-- Only the outer boundary boxes a validation result. Successful events carry
+-- an unboxed sum through the primitive state thread.
+newtype Check s a = Check (State# s -> (# State# s, (# a | String #) #))
+
+
+instance Functor (Check s) where
+  fmap f (Check action) = Check $ \state -> case action state of
+    (# next, (# value | #) #) -> (# next, (# f value | #) #)
+    (# next, (# | message #) #) -> (# next, (# | message #) #)
+  {-# INLINE fmap #-}
+
+
+instance Applicative (Check s) where
+  pure value = Check $ \state -> (# state, (# value | #) #)
+  function <*> argument = function >>= \f -> fmap f argument
+  {-# INLINE pure #-}
+  {-# INLINE (<*>) #-}
+
+
+instance Monad (Check s) where
+  Check action >>= continuation = Check $ \state -> case action state of
+    (# next, (# value | #) #) -> case continuation value of Check after -> after next
+    (# next, (# | message #) #) -> (# next, (# | message #) #)
+  {-# INLINE (>>=) #-}
+
+
+instance PrimMonad (Check s) where
+  type PrimState (Check s) = s
+  primitive action = Check $ \state -> case action state of
+    (# next, value #) -> (# next, (# value | #) #)
+  {-# INLINE primitive #-}
+
+
+runCheck :: Check s a -> ST s (Either String a)
+runCheck (Check action) = ST $ \state -> case action state of
+  (# next, (# value | #) #) -> (# next, Right value #)
+  (# next, (# | message #) #) -> (# next, Left message #)
+{-# INLINE runCheck #-}
+
+
+failCheck :: String -> Check s a
+failCheck message = Check $ \state -> (# state, (# | message #) #)
+{-# INLINE failCheck #-}
+
+
+data FastLeaf = FastLeaf
+  { fastDefinitions :: !(VP.Vector Int32)
+  , fastRepetitions :: !(VP.Vector Int32)
+  , fastValueCount :: {-# UNPACK #-} !Int
+  , fastPayloadSize :: {-# UNPACK #-} !Int
+  , fastPayload :: ~ByteString
+  }
+
+
+data ValueKind = KInt32 | KInt64 | KFloat16 | KFloat | KDouble | KBool | KText | KBinary | KFixed {-# UNPACK #-} !Int
+
+
+data Program
+  = Scalar {-# UNPACK #-} !Int !LeafType !ValueKind
+  | Optional {-# UNPACK #-} !Int {-# UNPACK #-} !Int !Program
+  | List {-# UNPACK #-} !Int {-# UNPACK #-} !Int {-# UNPACK #-} !Int !Program
+  | Mapping {-# UNPACK #-} !Int {-# UNPACK #-} !Int {-# UNPACK #-} !Int !Program !Program
+  | Struct !(V.Vector Program)
+
+
+data Compiled = Compiled !Program {-# UNPACK #-} !Int
+
+
+data CompiledFields = CompiledFields ![Program] {-# UNPACK #-} !Int
+
+
+data LeafBuffer s = LeafBuffer
+  { bufferDefinitions :: !(MVP.MVector s Int32)
+  , bufferRepetitions :: !(MVP.MVector s Int32)
+  , bufferValueCount :: {-# UNPACK #-} !Int
+  , bufferPayloadSize :: {-# UNPACK #-} !Int
+  , bufferPayload :: !(Maybe (MutableByteArray s))
+  }
+
+
+compile :: Int -> Int -> NestedSchema -> Maybe Compiled
+compile cursor depth schema = case schema of
+  NSPrimitive ty -> Just (Compiled (Scalar cursor ty (kind ty)) (cursor + 1))
+  NSRequired child -> compile cursor depth child
+  NSOptional child -> do
+    Compiled node end <- compile cursor depth child
+    pure (Compiled (Optional cursor end node) end)
+  NSList child -> do
+    Compiled node end <- compile cursor (depth + 1) child
+    pure (Compiled (List cursor end (depth + 1) node) end)
+  NSMap key value -> do
+    Compiled kn middle <- compile cursor (depth + 1) key
+    Compiled vn end <- compile middle (depth + 1) value
+    pure (Compiled (Mapping cursor end (depth + 1) kn vn) end)
+  NSStruct fields -> do
+    CompiledFields nodes end <-
+      V.foldM
+        ( \(CompiledFields nodes next) (_, child) -> do
+            Compiled node after <- compile next depth child
+            pure (CompiledFields (node : nodes) after)
+        )
+        (CompiledFields [] cursor)
+        fields
+    pure (Compiled (Struct (V.fromList (reverse nodes))) end)
+  _ -> Nothing
+  where
+    kind ty = case ty of
+      LtInt32 -> KInt32
+      LtInt64 -> KInt64
+      LtFloat16 -> KFloat16
+      LtFloat -> KFloat
+      LtDouble -> KDouble
+      LtBool -> KBool
+      LtString -> KText
+      LtJson -> KText
+      LtBinary -> KBinary
+      LtInteger 64 _ -> KInt64
+      LtInteger _ _ -> KInt32
+      LtDate -> KInt32
+      LtTime _ LtMillis -> KInt32
+      LtTime _ _ -> KInt64
+      LtTimestamp {} -> KInt64
+      LtTimestamp96 {} -> KFixed 12
+      LtInt96 -> KFixed 12
+      LtDecimal precision _ | precision <= 9 -> KInt32
+      LtDecimal precision _ | precision <= 18 -> KInt64
+      LtDecimal precision _ -> KFixed (if precision <= 38 then 16 else 32)
+      LtFixedBinary width -> KFixed (fromIntegral width)
+      LtUuid -> KFixed 16
+
+
+shredFast
+  :: NestedSchema
+  -> V.Vector NestedRow
+  -> Maybe (Either String (V.Vector FastLeaf))
+shredFast schema rows = do
+  Compiled program leaves <- compile 0 0 schema
+  pure $
+    if leaves > maxBound `quot` 3
+      then Left "Parquet.Nested: leaf-state size exceeds addressable limit"
+      else case simpleList program of
+        Just simple -> shredSimpleList simple program rows
+        Nothing -> runST $ do
+          counters <- newPrimArray (leaves * 3)
+          setPrimArray counters 0 (leaves * 3) 0
+          problem <- runCheck (countRows counters program rows)
+          case problem of
+            Left message -> pure (Left message)
+            Right () | Scalar {} <- program -> do
+              -- A required primitive has one event per row and no levels on
+              -- disk. Share one zero vector for the public shred result and
+              -- write values directly when its independently lazy payload is used.
+              events <- readPrimArray counters 0
+              present <- readPrimArray counters 1
+              bytes <- readPrimArray counters 2
+              let levels = VP.replicate events 0
+                  payload = materializePayload program rows 0 bytes
+              pure (Right (V.singleton (FastLeaf levels levels present bytes payload)))
+            Right () -> do
+              cacheValues <- smallPayloads counters leaves 0 0
+              buffers <- V.generateM leaves $ \index -> do
+                events <- readPrimArray counters (index * 3)
+                present <- readPrimArray counters (index * 3 + 1)
+                bytes <- readPrimArray counters (index * 3 + 2)
+                definitions <- MVP.unsafeNew events
+                repetitions <- MVP.unsafeNew events
+                payload <- if cacheValues then Just <$> newPinnedByteArray bytes else pure Nothing
+                pure (LeafBuffer definitions repetitions present bytes payload)
+              setPrimArray counters 0 (leaves * 3) 0
+              fillRows counters buffers program rows
+              Right <$> V.imapM (freeze program) buffers
+  where
+    freeze :: Program -> Int -> LeafBuffer s -> ST s FastLeaf
+    freeze program index buffer = do
+      definitions <- VP.unsafeFreeze (bufferDefinitions buffer)
+      repetitions <- VP.unsafeFreeze (bufferRepetitions buffer)
+      let size = bufferPayloadSize buffer
+      bytes <- case bufferPayload buffer of
+        Nothing -> pure (materializePayload program rows index size)
+        Just payload -> do
+          frozen <- unsafeFreezeByteArray payload
+          pure (ownedPayload frozen)
+      pure (FastLeaf definitions repetitions (bufferValueCount buffer) size bytes)
+
+
+-- The standard three-level list has a single physical leaf. Carry its
+-- counters through both row and element loops instead of loading/storing
+-- the general leaf-state array at every list boundary.
+data SimpleList = SimpleList !Bool !Bool !LeafType !ValueKind
+
+
+data SimpleCounts = SimpleCounts
+  { simpleEvents :: {-# UNPACK #-} !Int
+  , simplePresent :: {-# UNPACK #-} !Int
+  , simpleBytes :: {-# UNPACK #-} !Int
+  }
+
+
+simpleList :: Program -> Maybe SimpleList
+simpleList program = case program of
+  Optional _ _ child -> list True child
+  _ -> list False program
+  where
+    list rootOptional (List _ _ 1 child) = case child of
+      Scalar _ ty kind -> Just (SimpleList rootOptional False ty kind)
+      Optional _ _ (Scalar _ ty kind) -> Just (SimpleList rootOptional True ty kind)
+      _ -> Nothing
+    list _ _ = Nothing
+
+
+shredSimpleList :: SimpleList -> Program -> V.Vector NestedRow -> Either String (V.Vector FastLeaf)
+shredSimpleList schema program rows = do
+  counts <- countSimpleList schema rows
+  runST $ do
+    definitions <- MVP.unsafeNew (simpleEvents counts)
+    repetitions <- MVP.unsafeNew (simpleEvents counts)
+    storage <- if simpleBytes counts <= 1048576 then Just <$> newPinnedByteArray (simpleBytes counts) else pure Nothing
+    filled <- fillSimpleList schema counts rows definitions repetitions storage
+    if not filled
+      then pure (Left "Parquet.Nested.Fast: list fill disagrees with preflight counts")
+      else do
+        defs <- VP.unsafeFreeze definitions
+        reps <- VP.unsafeFreeze repetitions
+        bytes <- case storage of
+          Nothing -> pure (materializePayload program rows 0 (simpleBytes counts))
+          Just payload -> ownedPayload <$> unsafeFreezeByteArray payload
+        pure (Right (V.singleton (FastLeaf defs reps (simplePresent counts) (simpleBytes counts) bytes)))
+
+
+countSimpleList :: SimpleList -> V.Vector NestedRow -> Either String SimpleCounts
+countSimpleList schema@(SimpleList rootOptional elementOptional ty kind) rows = case fixedWidth kind of
+  Just width -> countFixedList schema width rows
+  Nothing -> row 0# 0# 0# 0#
+  where
+    !(I# rowCount#) = V.length rows
+    !(I# limit#) = limit
+    countError = Left "Parquet.Nested: value count exceeds signed 32-bit page limit"
+    shapeError = Left "Parquet.Nested: row shape does not match schema"
+    row i# events# present# bytes#
+      | isTrue# (i# ==# rowCount#) = Right (SimpleCounts (I# events#) (I# present#) (I# bytes#))
+      | otherwise = case V.unsafeIndex rows (I# i#) of
+          NRNull
+            | rootOptional ->
+                if isTrue# (events# ==# limit#) then countError else row (i# +# 1#) (events# +# 1#) present# bytes#
+          NRList values
+            | V.null values ->
+                if isTrue# (events# ==# limit#) then countError else row (i# +# 1#) (events# +# 1#) present# bytes#
+            | V.length values > limit -> Left "Parquet.Nested: list length exceeds signed 32-bit page limit"
+            | otherwise -> element i# values 0# events# present# bytes#
+          _ -> shapeError
+    element i# values j# events# present# bytes#
+      | I# j# == V.length values = row (i# +# 1#) events# present# bytes#
+      | otherwise = case V.unsafeIndex values (I# j#) of
+          NRNull
+            | not elementOptional -> Left "Parquet.Nested: NRNull at required NSPrimitive"
+            | isTrue# (events# ==# limit#) -> countError
+            | otherwise -> element i# values (j# +# 1#) (events# +# 1#) present# bytes#
+          NRLeaf value
+            | not (leafValueMatches ty value) -> Left "Parquet.Nested: leaf value violates its physical or logical type"
+            | isTrue# (events# ==# limit#) -> countError
+            | otherwise ->
+                let !size = plainValueSize kind value (I# present#)
+                in if size < 0 || size > limit || I# bytes# > limit - size
+                     then Left "Parquet.Nested: value bytes exceed signed 32-bit page limit"
+                     else case size of
+                       I# size# -> element i# values (j# +# 1#) (events# +# 1#) (present# +# 1#) (bytes# +# size#)
+          _ -> shapeError
+
+
+-- Fixed-width leaves only need a present count during validation. Account
+-- for a list's events once at its boundary and check the final multiplication
+-- before allocating. Zero denotes the packed Boolean representation.
+fixedWidth :: ValueKind -> Maybe Int
+fixedWidth kind = case kind of
+  KBool -> Just 0
+  KInt32 -> Just 4
+  KInt64 -> Just 8
+  KFloat16 -> Just 2
+  KFloat -> Just 4
+  KDouble -> Just 8
+  KFixed width | width > 0 -> Just width
+  _ -> Nothing
+
+
+countFixedList :: SimpleList -> Int -> V.Vector NestedRow -> Either String SimpleCounts
+countFixedList (SimpleList rootOptional elementOptional ty _) width rows = row 0# 0# 0#
+  where
+    !(I# rowCount#) = V.length rows
+    !(I# limit#) = limit
+    countError = Left "Parquet.Nested: value count exceeds signed 32-bit page limit"
+    shapeError = Left "Parquet.Nested: row shape does not match schema"
+    row i# events# present#
+      | isTrue# (i# ==# rowCount#) =
+          let present = I# present#
+          in if width /= 0 && present > limit `quot` width
+               then Left "Parquet.Nested: value bytes exceed signed 32-bit page limit"
+               else
+                 let bytes = if width == 0 then present `quot` 8 + if present `rem` 8 == 0 then 0 else 1 else present * width
+                 in Right (SimpleCounts (I# events#) present bytes)
+      | otherwise = case V.unsafeIndex rows (I# i#) of
+          NRNull
+            | rootOptional ->
+                if isTrue# (events# ==# limit#) then countError else row (i# +# 1#) (events# +# 1#) present#
+          NRList values
+            | V.null values ->
+                if isTrue# (events# ==# limit#) then countError else row (i# +# 1#) (events# +# 1#) present#
+            | V.length values > limit - I# events# -> countError
+            | otherwise -> case V.length values of
+                I# size# -> element i# values 0# (events# +# size#) present#
+          _ -> shapeError
+    element i# values j# events# present#
+      | I# j# == V.length values = row (i# +# 1#) events# present#
+      | otherwise = case V.unsafeIndex values (I# j#) of
+          NRNull
+            | elementOptional -> element i# values (j# +# 1#) events# present#
+            | otherwise -> Left "Parquet.Nested: NRNull at required NSPrimitive"
+          NRLeaf value
+            | leafValueMatches ty value -> element i# values (j# +# 1#) events# (present# +# 1#)
+            | otherwise -> Left "Parquet.Nested: leaf value violates its physical or logical type"
+          _ -> shapeError
+
+
+fillSimpleList :: forall s. SimpleList -> SimpleCounts -> V.Vector NestedRow -> MVP.MVector s Int32 -> MVP.MVector s Int32 -> Maybe (MutableByteArray s) -> ST s Bool
+fillSimpleList (SimpleList rootOptional elementOptional _ kind) counts rows definitions repetitions storage = row 0# 0# 0# 0#
+  where
+    !(I# rowCount#) = V.length rows
+    !emptyDefinition = if rootOptional then 1 else 0 :: Int
+    !elementDefinition = emptyDefinition + 1
+    !valueDefinition = elementDefinition + if elementOptional then 1 else 0
+    putLevel :: Int# -> Int -> Int -> ST s ()
+    putLevel event# definition repetition = do
+      MVP.unsafeWrite definitions (I# event#) (fromIntegral definition)
+      MVP.unsafeWrite repetitions (I# event#) (fromIntegral repetition)
+    {-# INLINE putLevel #-}
+    row i# event# present# cursor#
+      | isTrue# (i# ==# rowCount#) =
+          pure
+            ( I# event# == simpleEvents counts
+                && I# present# == simplePresent counts
+                && case storage of Nothing -> True; Just _ -> I# cursor# == simpleBytes counts
+            )
+      | otherwise = case V.unsafeIndex rows (I# i#) of
+          NRNull -> do
+            putLevel event# 0 0
+            row (i# +# 1#) (event# +# 1#) present# cursor#
+          NRList values
+            | V.null values -> do
+                putLevel event# emptyDefinition 0
+                row (i# +# 1#) (event# +# 1#) present# cursor#
+            | otherwise -> element i# values 0# event# present# cursor#
+          _ -> error "Parquet.Nested.Fast: preflighted list changed shape"
+    element i# values j# event# present# cursor#
+      | I# j# == V.length values = row (i# +# 1#) event# present# cursor#
+      | otherwise = do
+          let !repetition = if isTrue# (j# ==# 0#) then 0 else 1
+          case V.unsafeIndex values (I# j#) of
+            NRNull -> do
+              putLevel event# elementDefinition repetition
+              element i# values (j# +# 1#) (event# +# 1#) present# cursor#
+            NRLeaf value -> do
+              putLevel event# valueDefinition repetition
+              case storage of
+                Nothing -> element i# values (j# +# 1#) (event# +# 1#) (present# +# 1#) cursor#
+                Just payload -> do
+                  size <- writeValueAt payload kind value (I# present#) (I# cursor#)
+                  case size of
+                    I# size# -> element i# values (j# +# 1#) (event# +# 1#) (present# +# 1#) (cursor# +# size#)
+            _ -> error "Parquet.Nested.Fast: preflighted element changed shape"
+
+
+plainValueSize :: ValueKind -> LeafValue -> Int -> Int
+plainValueSize kind value present = case kind of
+  KBool -> if present `rem` 8 == 0 then 1 else 0
+  KInt32 -> 4
+  KInt64 -> 8
+  KFloat16 -> 2
+  KFloat -> 4
+  KDouble -> 8
+  KFixed width -> width
+  KText -> case value of LvString text -> TF.lengthWord8 text + 4; _ -> error "validated text"
+  KBinary -> case value of LvBinary binary -> BS.length binary + 4; _ -> error "validated binary"
+{-# INLINE plainValueSize #-}
+
+
+-- Cache values during level filling only when the entire column needs at
+-- most one MiB. Large accepted plans retain independently lazy payloads,
+-- including the near-limit preflight cases that must not allocate output.
+smallPayloads :: MutablePrimArray s Int -> Int -> Int -> Int -> ST s Bool
+smallPayloads counters leaves !index !total
+  | index == leaves = pure True
+  | otherwise = do
+      size <- readPrimArray counters (index * 3 + 2)
+      if size > 1048576 - total then pure False else smallPayloads counters leaves (index + 1) (total + size)
+
+
+-- bytestring retains the frozen pinned array as its ForeignPtr owner.
+-- fromShort has a safe copying fallback for an unpinned input too.
+ownedPayload :: ByteArray -> ByteString
+ownedPayload (ByteArray bytes#) = SBS.fromShort (SBS.SBS bytes#)
+
+
+-- Payloads stay independently lazy for callers inspecting a successful plan.
+-- Each leaf keeps only its own path through the immutable input tree.
+data PayloadProgram
+  = PayloadScalar !ValueKind
+  | PayloadOptional !PayloadProgram
+  | PayloadList !PayloadProgram
+  | PayloadMapKey !PayloadProgram
+  | PayloadMapValue !PayloadProgram
+  | PayloadStruct {-# UNPACK #-} !Int !PayloadProgram
+
+
+payloadProgram :: Int -> Program -> Maybe PayloadProgram
+payloadProgram target program = case program of
+  Scalar index _ kind
+    | target == index -> Just (PayloadScalar kind)
+    | otherwise -> Nothing
+  Optional _ _ child -> PayloadOptional <$> payloadProgram target child
+  List _ _ _ child -> PayloadList <$> payloadProgram target child
+  Mapping _ _ _ key value -> case payloadProgram target key of
+    Just child -> Just (PayloadMapKey child)
+    Nothing -> PayloadMapValue <$> payloadProgram target value
+  Struct children -> go children 0
+  where
+    go children !i
+      | i == V.length children = Nothing
+      | otherwise = case payloadProgram target (V.unsafeIndex children i) of
+          Nothing -> go children (i + 1)
+          Just child -> Just (PayloadStruct i child)
+
+
+materializePayload :: Program -> V.Vector NestedRow -> Int -> Int -> ByteString
+materializePayload program rows index size
+  | size == 0 = BS.empty
+  | otherwise = case payloadProgram index program of
+      Nothing -> error "Parquet.Nested.Fast: missing preflighted leaf"
+      Just selected -> runST $ do
+        payload <- newPinnedByteArray size
+        counters <- newPrimArray 3
+        setPrimArray counters 0 3 0
+        fillPayloadRows counters payload selected rows
+        frozen <- unsafeFreezeByteArray payload
+        pure (ownedPayload frozen)
+
+
+fillPayload :: MutablePrimArray s Int -> MutableByteArray s -> PayloadProgram -> NestedRow -> ST s ()
+fillPayload !counters !payload program row = case (program, row) of
+  (PayloadScalar kind, NRLeaf value) -> writeValue counters payload 0 kind value
+  (PayloadOptional _, NRNull) -> pure ()
+  (PayloadOptional child, value) -> fillPayload counters payload child value
+  (PayloadList child, NRList values) -> fillPayloadRows counters payload child values
+  (PayloadMapKey child, NRMapEntries pairs) -> goPair True child pairs 0
+  (PayloadMapValue child, NRMapEntries pairs) -> goPair False child pairs 0
+  (PayloadStruct field child, NRStruct values) -> fillPayload counters payload child (V.unsafeIndex values field)
+  _ -> error "Parquet.Nested.Fast: preflighted payload changed shape"
+  where
+    goPair key child pairs !i
+      | i == V.length pairs = pure ()
+      | otherwise = case V.unsafeIndex pairs i of
+          (keyRow, valueRow) -> fillPayload counters payload child (if key then keyRow else valueRow) >> goPair key child pairs (i + 1)
+
+
+eachRow :: V.Vector NestedRow -> (NestedRow -> Check s ()) -> Check s ()
+eachRow rows action = go 0
+  where
+    go !i
+      | i == V.length rows = pure ()
+      | otherwise = action (V.unsafeIndex rows i) >> go (i + 1)
+{-# INLINE eachRow #-}
+
+
+-- Select the scalar loop once per sequence rather than interpret the same
+-- schema nodes for every primitive in a list or top-level column.
+countRows :: MutablePrimArray s Int -> Program -> V.Vector NestedRow -> Check s ()
+countRows counters program rows = case program of
+  Scalar index ty kind -> scalar False index ty kind
+  Optional _ _ (Scalar index ty kind) -> scalar True index ty kind
+  _ -> eachRow rows (count counters program)
+  where
+    scalar nullable index ty kind = case kind of
+      KText -> variable nullable index ty kind
+      KBinary -> variable nullable index ty kind
+      KBool -> countFixedRows counters index ty nullable 0 rows
+      KFloat16 -> countFixedRows counters index ty nullable 2 rows
+      KInt64 -> countFixedRows counters index ty nullable 8 rows
+      KDouble -> countFixedRows counters index ty nullable 8 rows
+      KFixed width -> countFixedRows counters index ty nullable width rows
+      _ -> countFixedRows counters index ty nullable 4 rows
+    variable nullable index ty kind = eachRow rows $ \row -> case row of
+      NRNull -> if nullable then addNull counters index else failCheck "Parquet.Nested: NRNull at required NSPrimitive"
+      NRLeaf value
+        | leafValueMatches ty value -> addPresent counters index kind value
+        | otherwise -> failCheck "Parquet.Nested: leaf value violates its physical or logical type"
+      _ -> failCheck "Parquet.Nested: row shape does not match schema"
+
+
+-- Fixed-width sequences need only a local present count while validating.
+-- Update the shared leaf counters once per sequence, with multiplication
+-- checked before forming the byte size. Width zero denotes packed booleans.
+countFixedRows :: MutablePrimArray s Int -> Int -> LeafType -> Bool -> Int -> V.Vector NestedRow -> Check s ()
+countFixedRows counters leaf ty nullable width rows = do
+  let slot = leaf * 3
+      length_ = V.length rows
+  events <- readPrimArray counters slot
+  present <- readPrimArray counters (slot + 1)
+  if length_ > limit - events
+    then failCheck "Parquet.Nested: value count exceeds signed 32-bit page limit"
+    else
+      let go !i !found
+            | i == length_ =
+                let total = present + found
+                in if width /= 0 && total > limit `quot` width
+                     then failCheck "Parquet.Nested: value bytes exceed signed 32-bit page limit"
+                     else do
+                       let bytes = if width == 0 then total `quot` 8 + if total `rem` 8 == 0 then 0 else 1 else total * width
+                       writePrimArray counters slot (events + length_)
+                       writePrimArray counters (slot + 1) total
+                       writePrimArray counters (slot + 2) bytes
+            | otherwise = case V.unsafeIndex rows i of
+                NRNull -> if nullable then go (i + 1) found else failCheck "Parquet.Nested: NRNull at required NSPrimitive"
+                NRLeaf value
+                  | leafValueMatches ty value -> go (i + 1) (found + 1)
+                  | otherwise -> failCheck "Parquet.Nested: leaf value violates its physical or logical type"
+                _ -> failCheck "Parquet.Nested: row shape does not match schema"
+      in go 0 0
+
+
+fillPayloadRows :: MutablePrimArray s Int -> MutableByteArray s -> PayloadProgram -> V.Vector NestedRow -> ST s ()
+fillPayloadRows !counters !payload program rows = case program of
+  PayloadScalar kind -> scalar False kind
+  PayloadOptional (PayloadScalar kind) -> scalar True kind
+  _ -> generic 0
+  where
+    scalar nullable kind = do
+      firstPresent <- readPrimArray counters 1
+      firstCursor <- readPrimArray counters 2
+      let go !i !present !cursor
+            | i == V.length rows = do
+                writePrimArray counters 1 present
+                writePrimArray counters 2 cursor
+            | otherwise = case V.unsafeIndex rows i of
+                NRNull | nullable -> go (i + 1) present cursor
+                NRLeaf value -> do
+                  size <- writeValueAt payload kind value present cursor
+                  go (i + 1) (present + 1) (cursor + size)
+                _ -> error "Parquet.Nested.Fast: preflighted scalar changed shape"
+      go 0 firstPresent firstCursor
+    generic !i
+      | i == V.length rows = pure ()
+      | otherwise = fillPayload counters payload program (V.unsafeIndex rows i) >> generic (i + 1)
+
+
+count :: MutablePrimArray s Int -> Program -> NestedRow -> Check s ()
+count counters program row = case (program, row) of
+  (Scalar index ty kind, NRLeaf value)
+    | leafValueMatches ty value -> addPresent counters index kind value
+    | otherwise -> failCheck "Parquet.Nested: leaf value violates its physical or logical type"
+  (Scalar {}, NRNull) -> failCheck "Parquet.Nested: NRNull at required NSPrimitive"
+  (Optional begin end _, NRNull) -> countNulls counters begin end
+  (Optional _ _ child, value) -> count counters child value
+  (List begin end _ _, NRList values) | V.null values -> countNulls counters begin end
+  (List _ _ _ child, NRList values)
+    | V.length values > limit -> failCheck "Parquet.Nested: list length exceeds signed 32-bit page limit"
+    | otherwise -> countRows counters child values
+  (Mapping begin end _ _ _, NRMapEntries values) | V.null values -> countNulls counters begin end
+  (Mapping _ _ _ key value, NRMapEntries pairs)
+    | V.length pairs > limit -> failCheck "Parquet.Nested: map length exceeds signed 32-bit page limit"
+    | otherwise -> goPair key value pairs 0
+  (Struct children, NRStruct values)
+    | V.length children /= V.length values -> failCheck "Parquet.Nested: NSStruct / NRStruct field count mismatch"
+    | otherwise -> goField children values 0
+  _ -> failCheck "Parquet.Nested: row shape does not match schema"
+  where
+    goPair key value pairs !i
+      | i == V.length pairs = pure ()
+      | otherwise = case V.unsafeIndex pairs i of
+          (keyRow, valueRow) -> count counters key keyRow >> count counters value valueRow >> goPair key value pairs (i + 1)
+    goField children values !i
+      | i == V.length children = pure ()
+      | otherwise = count counters (V.unsafeIndex children i) (V.unsafeIndex values i) >> goField children values (i + 1)
+
+
+limit :: Int
+limit = 2147483647
+
+
+countNulls :: MutablePrimArray s Int -> Int -> Int -> Check s ()
+countNulls counters begin end = go begin
+  where
+    go !i
+      | i == end = pure ()
+      | otherwise = addNull counters i >> go (i + 1)
+
+
+addNull :: MutablePrimArray s Int -> Int -> Check s ()
+addNull counters leaf = do
+  let slot = leaf * 3
+  events <- readPrimArray counters slot
+  if events == limit
+    then failCheck "Parquet.Nested: value count exceeds signed 32-bit page limit"
+    else writePrimArray counters slot (events + 1)
+{-# INLINE addNull #-}
+
+
+addPresent :: MutablePrimArray s Int -> Int -> ValueKind -> LeafValue -> Check s ()
+addPresent counters leaf kind value = do
+  let slot = leaf * 3
+  events <- readPrimArray counters slot
+  if events == limit
+    then failCheck "Parquet.Nested: value count exceeds signed 32-bit page limit"
+    else do
+      count <- readPrimArray counters (slot + 1)
+      bytes <- readPrimArray counters (slot + 2)
+      let size = plainValueSize kind value count
+      if size < 0 || size > limit || bytes > limit - size
+        then failCheck "Parquet.Nested: value bytes exceed signed 32-bit page limit"
+        else do
+          writePrimArray counters slot (events + 1)
+          writePrimArray counters (slot + 1) (count + 1)
+          writePrimArray counters (slot + 2) (bytes + size)
+{-# INLINE addPresent #-}
+
+
+fillRows :: MutablePrimArray s Int -> V.Vector (LeafBuffer s) -> Program -> V.Vector NestedRow -> ST s ()
+fillRows counters buffers program rows = fillSequence counters buffers program rows 0 0 0
+
+
+fillSequence :: MutablePrimArray s Int -> V.Vector (LeafBuffer s) -> Program -> V.Vector NestedRow -> Int -> Int -> Int -> ST s ()
+fillSequence counters buffers program rows !definition !firstRep !laterRep = case program of
+  Scalar leaf _ kind -> scalar False leaf kind
+  Optional _ _ (Scalar leaf _ kind) -> scalar True leaf kind
+  _ -> generic 0
+  where
+    scalar nullable leaf kind = do
+      let slot = leaf * 3
+          buffer = V.unsafeIndex buffers leaf
+      start <- readPrimArray counters slot
+      let go !i
+            | i == V.length rows = writePrimArray counters slot (start + i)
+            | otherwise = do
+                let def = if nullable then case V.unsafeIndex rows i of NRNull -> definition; _ -> definition + 1 else definition
+                    rep = if i == 0 then firstRep else laterRep
+                MVP.unsafeWrite (bufferDefinitions buffer) (start + i) (fromIntegral def)
+                MVP.unsafeWrite (bufferRepetitions buffer) (start + i) (fromIntegral rep)
+                go (i + 1)
+          cached payload !i !present !cursor
+            | i == V.length rows = do
+                writePrimArray counters slot (start + i)
+                writePrimArray counters (slot + 1) present
+                writePrimArray counters (slot + 2) cursor
+            | otherwise = do
+                let row = V.unsafeIndex rows i
+                    def = if nullable then case row of NRNull -> definition; _ -> definition + 1 else definition
+                    rep = if i == 0 then firstRep else laterRep
+                MVP.unsafeWrite (bufferDefinitions buffer) (start + i) (fromIntegral def)
+                MVP.unsafeWrite (bufferRepetitions buffer) (start + i) (fromIntegral rep)
+                case row of
+                  NRLeaf value -> do
+                    size <- writeValueAt payload kind value present cursor
+                    cached payload (i + 1) (present + 1) (cursor + size)
+                  _ -> cached payload (i + 1) present cursor
+      case bufferPayload buffer of
+        Nothing -> go 0
+        Just payload -> do
+          present <- readPrimArray counters (slot + 1)
+          cursor <- readPrimArray counters (slot + 2)
+          cached payload 0 present cursor
+    generic !i
+      | i == V.length rows = pure ()
+      | otherwise = fill counters buffers program (V.unsafeIndex rows i) definition (if i == 0 then firstRep else laterRep) >> generic (i + 1)
+
+
+fill :: MutablePrimArray s Int -> V.Vector (LeafBuffer s) -> Program -> NestedRow -> Int -> Int -> ST s ()
+fill counters buffers program row !definition !repetition = case (program, row) of
+  (Scalar index _ kind, NRLeaf value) -> do
+    emitLevel counters buffers index definition repetition
+    case bufferPayload (V.unsafeIndex buffers index) of
+      Nothing -> pure ()
+      Just payload -> writeValue counters payload index kind value
+  (Optional begin end _, NRNull) -> fillNulls counters buffers begin end definition repetition
+  (Optional _ _ child, value) -> fill counters buffers child value (definition + 1) repetition
+  (List begin end _ _, NRList values) | V.null values -> fillNulls counters buffers begin end definition repetition
+  (List _ _ depth child, NRList values) -> fillSequence counters buffers child values (definition + 1) repetition depth
+  (Mapping begin end _ _ _, NRMapEntries values) | V.null values -> fillNulls counters buffers begin end definition repetition
+  (Mapping _ _ depth key value, NRMapEntries pairs) -> goPair depth key value pairs 0
+  (Struct children, NRStruct values) -> goField children values 0
+  _ -> error "Parquet.Nested.Fast: validated row changed shape"
+  where
+    goPair depth key value pairs !i
+      | i == V.length pairs = pure ()
+      | otherwise = case V.unsafeIndex pairs i of
+          (keyRow, valueRow) -> do
+            let rep = if i == 0 then repetition else depth
+            fill counters buffers key keyRow (definition + 1) rep
+            fill counters buffers value valueRow (definition + 1) rep
+            goPair depth key value pairs (i + 1)
+    goField children values !i
+      | i == V.length children = pure ()
+      | otherwise = fill counters buffers (V.unsafeIndex children i) (V.unsafeIndex values i) definition repetition >> goField children values (i + 1)
+
+
+emitLevel :: MutablePrimArray s Int -> V.Vector (LeafBuffer s) -> Int -> Int -> Int -> ST s ()
+emitLevel counters buffers leaf definition repetition = do
+  let slot = leaf * 3; buffer = V.unsafeIndex buffers leaf
+  event <- readPrimArray counters slot
+  MVP.unsafeWrite (bufferDefinitions buffer) event (fromIntegral definition)
+  MVP.unsafeWrite (bufferRepetitions buffer) event (fromIntegral repetition)
+  writePrimArray counters slot (event + 1)
+{-# INLINE emitLevel #-}
+
+
+fillNulls :: MutablePrimArray s Int -> V.Vector (LeafBuffer s) -> Int -> Int -> Int -> Int -> ST s ()
+fillNulls counters buffers begin end definition repetition = go begin
+  where
+    go !i
+      | i == end = pure ()
+      | otherwise = emitLevel counters buffers i definition repetition >> go (i + 1)
+
+
+writeValue :: MutablePrimArray s Int -> MutableByteArray s -> Int -> ValueKind -> LeafValue -> ST s ()
+writeValue counters payload leaf kind value = do
+  let slot = leaf * 3
+  present <- readPrimArray counters (slot + 1)
+  cursor <- readPrimArray counters (slot + 2)
+  size <- writeValueAt payload kind value present cursor
+  writePrimArray counters (slot + 1) (present + 1)
+  writePrimArray counters (slot + 2) (cursor + size)
+{-# INLINE writeValue #-}
+
+
+writeValueAt :: MutableByteArray s -> ValueKind -> LeafValue -> Int -> Int -> ST s Int
+writeValueAt payload kind value present cursor =
+  case (kind, value) of
+    (KInt32, LvInt32 x) -> writeByteArray payload present (le32 (fromIntegral x)) >> pure 4
+    (KInt64, LvInt64 x) -> writeByteArray payload present (le64 (fromIntegral x)) >> pure 8
+    (KFloat16, LvFloat16 x) -> writeByteArray payload present (le16 x) >> pure 2
+    (KFloat, LvFloat x) -> writeByteArray payload present (le32 (castFloatToWord32 x)) >> pure 4
+    (KDouble, LvDouble x) -> writeByteArray payload present (le64 (castDoubleToWord64 x)) >> pure 8
+    (KBool, LvBool x) -> do
+      let (byte, bit) = present `quotRem` 8
+      old <- if bit == 0 then pure 0 else readByteArray payload byte
+      writeByteArray payload byte (if x then setBit old bit else old :: Word8)
+      pure (if bit == 0 then 1 else 0)
+    (KText, LvString text) -> do
+      let size = TF.lengthWord8 text
+      prefix payload cursor size
+      if size == 0 then pure () else unsafeIOToST (TF.unsafeCopyToPtr text (mutableByteArrayContents payload `plusPtr` (cursor + 4)))
+      touch payload
+      pure (size + 4)
+    (KBinary, LvBinary bytes) -> do
+      let size = BS.length bytes
+      prefix payload cursor size
+      copy payload (cursor + 4) bytes
+      pure (size + 4)
+    (KFixed width, LvFixedBinary bytes) -> copy payload cursor bytes >> pure width
+    _ -> error "Parquet.Nested.Fast: validated scalar changed type"
+{-# INLINE writeValueAt #-}
+
+
+prefix :: MutableByteArray s -> Int -> Int -> ST s ()
+prefix payload cursor size = do
+  writeByteArray payload cursor (fromIntegral size :: Word8)
+  writeByteArray payload (cursor + 1) (fromIntegral (size `shiftR` 8) :: Word8)
+  writeByteArray payload (cursor + 2) (fromIntegral (size `shiftR` 16) :: Word8)
+  writeByteArray payload (cursor + 3) (fromIntegral (size `shiftR` 24) :: Word8)
+{-# INLINE prefix #-}
+
+
+copy :: MutableByteArray s -> Int -> ByteString -> ST s ()
+copy payload cursor bytes = do
+  let (fp, offset, size) = BSI.toForeignPtr bytes
+  if size == 0 then pure () else unsafeIOToST $ withForeignPtr fp $ \ptr -> copyBytes (mutableByteArrayContents payload `plusPtr` cursor) (ptr `plusPtr` offset) size
+  touch payload
+{-# INLINE copy #-}
+
+
+le16 :: Word16 -> Word16
+le16 x = case targetByteOrder of LittleEndian -> x; BigEndian -> byteSwap16 x
+
+
+le32 :: Word32 -> Word32
+le32 x = case targetByteOrder of LittleEndian -> x; BigEndian -> byteSwap32 x
+
+
+le64 :: Word64 -> Word64
+le64 x = case targetByteOrder of LittleEndian -> x; BigEndian -> byteSwap64 x
+
+
+{-# INLINE le16 #-}
+
+
+{-# INLINE le32 #-}
+
+
+{-# INLINE le64 #-}
diff --git a/src/Parquet/Nested/Generate.hs b/src/Parquet/Nested/Generate.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Nested/Generate.hs
@@ -0,0 +1,38 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Internal strict vector construction without per-element Either, list
+spines or deferred indexing closures.
+-}
+module Parquet.Nested.Generate (generate#) where
+
+import Data.Vector qualified as V
+import Data.Vector.Mutable qualified as VM
+import GHC.Exts (Int (I#), Int#, runRW#, (+#), (==#))
+import GHC.ST (ST (..))
+
+
+-- Materialize only visited rows, with no boxed index or per-row Either.
+-- Force each result before storing it, avoiding deferred indexing closures
+-- that retain a whole input column after conversion.
+generate# :: Int# -> (Int# -> (# String | a #)) -> (# String | V.Vector a #)
+generate# count produce = runRW# $ \state ->
+  case VM.unsafeNew (I# count) of
+    ST allocate ->
+      case allocate state of
+        (# state1, output #) ->
+          let go index state2 =
+                case index ==# count of
+                  1# -> case V.unsafeFreeze output of
+                    ST freeze -> case freeze state2 of
+                      (# _, result #) -> (# | result #)
+                  _ -> case produce index of
+                    (# message | #) -> (# message | #)
+                    (# | value #) -> case value of
+                      !strictValue -> case VM.unsafeWrite output (I# index) strictValue of
+                        ST write -> case write state2 of
+                          (# state3, () #) -> go (index +# 1#) state3
+          in go 0# state1
+{-# INLINE generate# #-}
diff --git a/src/Parquet/Nested/Plain.hs b/src/Parquet/Nested/Plain.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Nested/Plain.hs
@@ -0,0 +1,105 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+-- | Checked PLAIN layout shared by nested auxiliary-data generators.
+module Parquet.Nested.Plain (
+  PlainLayout (..),
+  plainLayout,
+  validPlainValues,
+  lengthAt,
+  word16At,
+  word32At,
+  word64At,
+) where
+
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Internal qualified as BSI
+import Data.Word (Word16, Word32, Word64, byteSwap16, byteSwap32, byteSwap64)
+import Foreign.ForeignPtr (touchForeignPtr)
+import Foreign.ForeignPtr.Unsafe (unsafeForeignPtrToPtr)
+import Foreign.Ptr (plusPtr)
+import GHC.ByteOrder (ByteOrder (..), targetByteOrder)
+import GHC.Exts (readWord8OffAddrAsWord16#, readWord8OffAddrAsWord32#, readWord8OffAddrAsWord64#)
+import GHC.IO (IO (..))
+import GHC.Ptr (Ptr (..))
+import GHC.Word (Word16 (W16#), Word32 (W32#), Word64 (W64#))
+import Parquet.Types (ParquetType (..), SchemaElement (..))
+
+
+data PlainLayout = BooleanValues | VariableValues | FixedValues {-# UNPACK #-} !Int
+
+
+plainLayout :: SchemaElement -> Either String PlainLayout
+plainLayout field = case seType field of
+  Just PTBoolean -> Right BooleanValues
+  Just PTByteArray -> Right VariableValues
+  Just PTInt32 -> Right (FixedValues 4)
+  Just PTInt64 -> Right (FixedValues 8)
+  Just PTInt96 -> Right (FixedValues 12)
+  Just PTFloat -> Right (FixedValues 4)
+  Just PTDouble -> Right (FixedValues 8)
+  Just PTFixedLenByteArray -> case seTypeLength field of
+    Just width | width > 0 -> Right (FixedValues (fromIntegral width))
+    _ -> invalid
+  _ -> invalid
+  where
+    invalid = Left "Parquet.Nested: missing or invalid physical PLAIN layout"
+
+
+validPlainValues :: PlainLayout -> Int -> ByteString -> Bool
+validPlainValues layout count bytes
+  | count < 0 = False
+  | otherwise = case layout of
+      BooleanValues -> BS.length bytes == count `quot` 8 + if count `rem` 8 == 0 then 0 else 1
+      FixedValues width -> toInteger count * toInteger width == toInteger (BS.length bytes)
+      VariableValues -> go 0 0
+  where
+    !size = BS.length bytes
+    go !index !offset
+      | index == count = offset == size
+      | size - offset < 4 = False
+      | otherwise =
+          let !length_ = lengthAt bytes offset
+          in length_ >= 0 && length_ <= 2147483647 && length_ <= size - offset - 4 && go (index + 1) (offset + 4 + length_)
+
+
+-- Only call these readers within a checked logical slice. They read exactly
+-- the named bytes, require no alignment, and are portable across host order.
+word16At :: ByteString -> Int -> Word16
+word16At bytes offset = BSI.accursedUnutterablePerformIO $ do
+  let (fp, start, _) = BSI.toForeignPtr bytes
+  value <- case unsafeForeignPtrToPtr fp `plusPtr` (start + offset) of
+    Ptr address -> IO $ \s -> case readWord8OffAddrAsWord16# address 0# s of
+      (# next, word #) -> (# next, W16# word #)
+  touchForeignPtr fp
+  pure (case targetByteOrder of LittleEndian -> value; BigEndian -> byteSwap16 value)
+{-# INLINE word16At #-}
+
+
+word32At :: ByteString -> Int -> Word32
+word32At bytes offset = BSI.accursedUnutterablePerformIO $ do
+  let (fp, start, _) = BSI.toForeignPtr bytes
+  value <- case unsafeForeignPtrToPtr fp `plusPtr` (start + offset) of
+    Ptr address -> IO $ \s -> case readWord8OffAddrAsWord32# address 0# s of
+      (# next, word #) -> (# next, W32# word #)
+  touchForeignPtr fp
+  pure (case targetByteOrder of LittleEndian -> value; BigEndian -> byteSwap32 value)
+{-# INLINE word32At #-}
+
+
+word64At :: ByteString -> Int -> Word64
+word64At bytes offset = BSI.accursedUnutterablePerformIO $ do
+  let (fp, start, _) = BSI.toForeignPtr bytes
+  value <- case unsafeForeignPtrToPtr fp `plusPtr` (start + offset) of
+    Ptr address -> IO $ \s -> case readWord8OffAddrAsWord64# address 0# s of
+      (# next, word #) -> (# next, W64# word #)
+  touchForeignPtr fp
+  pure (case targetByteOrder of LittleEndian -> value; BigEndian -> byteSwap64 value)
+{-# INLINE word64At #-}
+
+
+lengthAt :: ByteString -> Int -> Int
+lengthAt bytes offset = fromIntegral (word32At bytes offset)
+{-# INLINE lengthAt #-}
diff --git a/src/Parquet/Nested/Statistics.hs b/src/Parquet/Nested/Statistics.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Nested/Statistics.hs
@@ -0,0 +1,302 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+
+{- | Statistics over checked PLAIN spans. Bounds retain offsets rather than
+allocating decoded values or ByteString slices inside the scan.
+-}
+module Parquet.Nested.Statistics (
+  statisticsOrderFor,
+  columnStatistics,
+) where
+
+import Data.Bits (complement, shiftL, shiftR, xor, (.&.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as Builder
+import Data.ByteString.Lazy qualified as BL
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Int (Int64)
+import Data.Word (Word64, Word8)
+import GHC.Exts (Int (I#), Int#, isTrue#, (+#), (==#))
+import Parquet.Nested.Plain
+import Parquet.Types
+
+
+-- Prefer the explicit orderings recommended by the current format. Legacy
+-- entry points without auxiliary options keep their original metadata.
+statisticsOrderFor :: SchemaElement -> ColumnOrder
+statisticsOrderFor field
+  | not (hasDefinedStatisticsOrder field) = TypeDefinedOrder
+  | floatingField field = IEEE754TotalOrder
+  | seType field == Just PTInt96 = Int96TimestampOrder
+  | otherwise = TypeDefinedOrder
+
+
+data SortKind
+  = NoOrder
+  | BooleanOrder
+  | UnsignedOrder
+  | SignedOrder
+  | FloatingOrder
+  | BinaryOrder
+  | DecimalOrder
+  | Timestamp96Order
+  | LegacyTimestampOrder
+  deriving stock (Eq)
+
+
+floatingField :: SchemaElement -> Bool
+floatingField field = seType field `elem` [Just PTFloat, Just PTDouble] || seLogicalType field == Just LTFloat16
+
+
+sortKind :: ColumnOrder -> SchemaElement -> SortKind
+sortKind order field
+  | not (hasDefinedStatisticsOrder field) = NoOrder
+  | order == UnsupportedColumnOrder = NoOrder
+  | floatingField field =
+      if order `elem` [TypeDefinedOrder, IEEE754TotalOrder] then FloatingOrder else NoOrder
+  | seType field == Just PTInt96 =
+      if order == Int96TimestampOrder then LegacyTimestampOrder else NoOrder
+  | order /= TypeDefinedOrder = NoOrder
+  | otherwise = case seType field of
+      Just PTBoolean -> BooleanOrder
+      Just PTInt32 -> integerOrder
+      Just PTInt64 -> integerOrder
+      Just PTFixedLenByteArray
+        | Just LTTimestamp {} <- seLogicalType field -> Timestamp96Order
+      Just PTFixedLenByteArray -> byteOrder
+      Just PTByteArray -> byteOrder
+      _ -> NoOrder
+  where
+    integerOrder = case seLogicalType field of
+      Just (LTInteger _ False) -> UnsignedOrder
+      _ | seConvertedType field `elem` map Just [CTUInt8, CTUInt16, CTUInt32, CTUInt64] -> UnsignedOrder
+      _ -> SignedOrder
+    byteOrder = case seLogicalType field of
+      Just LTDecimal {} -> DecimalOrder
+      _ | seConvertedType field == Just CTDecimal -> DecimalOrder
+      _ -> BinaryOrder
+
+
+columnStatistics :: ColumnOrder -> SchemaElement -> Int -> Int -> ByteString -> Either String Statistics
+columnStatistics order field nulls count bytes = do
+  layout <- plainLayout field
+  if nulls < 0 || not (validPlainValues layout count bytes)
+    then Left "Parquet.Nested: statistics values disagree with the physical PLAIN layout"
+    else
+      if kind == DecimalOrder && emptyDecimal layout 0 0
+        then Left "Parquet.Nested: empty DECIMAL value in statistics input"
+        else
+          if kind == NoOrder
+            then Right empty
+            else Right $
+              case kind of
+                UnsignedOrder -> integer
+                SignedOrder -> integer
+                FloatingOrder -> numeric 0 0 0 (-1) 0 (-1) 0
+                _ -> scan layout 0# 0# (-1#) 0# (-1#) 0# 0#
+  where
+    emptyDecimal VariableValues !index !offset
+      | index == count = False
+      | otherwise = let size = lengthAt bytes offset in size == 0 || emptyDecimal VariableValues (index + 1) (offset + 4 + size)
+    emptyDecimal _ _ _ = False
+    !kind = sortKind order field
+    !width = case seType field of
+      Just PTInt32 -> 4
+      Just PTInt64 -> 8
+      Just PTFloat -> 4
+      Just PTDouble -> 8
+      _ -> maybe 0 fromIntegral (seTypeLength field)
+    !sign = if width `elem` [2, 4, 8] then (1 :: Word64) `shiftL` (width * 8 - 1) else 0
+    !mask = if width == 8 then maxBound else sign + (sign - 1)
+    !infinity = case width of 2 -> 0x7c00; 4 -> 0x7f800000; _ -> 0x7ff0000000000000
+    empty = Statistics Nothing Nothing (Just (fromIntegral nulls)) Nothing Nothing Nothing Nothing Nothing Nothing
+    !(I# count#) = count
+    !(I# width#) = width
+    !(I# byteSize#) = BS.length bytes
+    integer
+      | count == 0 = finish (-1) (-1) 0
+      | otherwise = let key = raw 0 `xor` integerSign in scanInteger width# key 0# key 0#
+    !integerSign = if kind == SignedOrder then sign else 0
+    -- Integer ordering needs no NaN state or per-value ordering dispatch.
+    -- The checked fixed-width layout bounds every exact-width read.
+    scanInteger :: Int# -> Word64 -> Int# -> Word64 -> Int# -> Statistics
+    scanInteger cursor# !lowKey low# !highKey high#
+      | isTrue# (cursor# ==# byteSize#) = finish (I# low#) (I# high#) 0
+      | otherwise =
+          let !key = raw (I# cursor#) `xor` integerSign
+              !replaceLow = key < lowKey
+              !replaceHigh = key > highKey
+          in scanInteger
+               (cursor# +# width#)
+               (if replaceLow then key else lowKey)
+               (if replaceLow then cursor# else low#)
+               (if replaceHigh then key else highKey)
+               (if replaceHigh then cursor# else high#)
+    -- Cache comparison keys rather than rereading both extrema for every
+    -- value. Width and ordering are constant for the whole physical column.
+    numeric :: Int -> Int -> Word64 -> Int -> Word64 -> Int -> Int -> Statistics
+    numeric !index !cursor !lowKey !low !highKey !high !nans
+      | index == count = finish low high nans
+      | otherwise =
+          let !bits = raw cursor
+              !nan = kind == FloatingOrder && bits .&. (sign - 1) > infinity
+              !key = case kind of
+                SignedOrder -> bits `xor` sign
+                FloatingOrder -> floatKey bits
+                _ -> bits
+              !firstNumeric = not nan && index == nans
+              !include = not nan || index == nans
+              !replaceLow = firstNumeric || (include && (low < 0 || key < lowKey))
+              !replaceHigh = firstNumeric || (include && (high < 0 || key > highKey))
+          in numeric
+               (index + 1)
+               (cursor + width)
+               (if replaceLow then key else lowKey)
+               (if replaceLow then cursor else low)
+               (if replaceHigh then key else highKey)
+               (if replaceHigh then cursor else high)
+               (nans + if nan then 1 else 0)
+    finish low high nans =
+      let nanCount = if kind == FloatingOrder then Just (fromIntegral nans :: Int64) else Nothing
+          noBounds = low < 0 || (kind == FloatingOrder && order == TypeDefinedOrder && nans == count)
+      in if noBounds
+           then empty {statNanCount = nanCount}
+           else
+             empty
+               { statMinValue = Just (bound True low width)
+               , statMaxValue = Just (bound False high width)
+               , statMinValueExact = Just True
+               , statMaxValueExact = Just True
+               , statNanCount = nanCount
+               }
+    scan :: PlainLayout -> Int# -> Int# -> Int# -> Int# -> Int# -> Int# -> Int# -> Statistics
+    scan layout index# cursor# low# lowLength# high# highLength# nans#
+      | isTrue# (index# ==# count#) =
+          let nanCount = if kind == FloatingOrder then Just (fromIntegral nans :: Int64) else Nothing
+              noBounds = low < 0 || (kind == FloatingOrder && order == TypeDefinedOrder && nans == count)
+          in if noBounds
+               then empty {statNanCount = nanCount}
+               else
+                 empty
+                   { statMinValue = Just (bound True low lowLength)
+                   , statMaxValue = Just (bound False high highLength)
+                   , statMinValueExact = Just True
+                   , statMaxValueExact = Just True
+                   , statNanCount = nanCount
+                   }
+      | otherwise =
+          let !offset = case layout of VariableValues -> cursor + 4; BooleanValues -> index; _ -> cursor
+              !size = case layout of VariableValues -> lengthAt bytes cursor; BooleanValues -> 1; FixedValues n -> n
+              !nan = kind == FloatingOrder && raw offset .&. (sign - 1) > infinity
+              !firstNumeric = not nan && index == nans
+              !include = not nan || index == nans
+              !replaceLow = firstNumeric || (include && (low < 0 || compareAt offset size low lowLength == LT))
+              !replaceHigh = firstNumeric || (include && (high < 0 || compareAt offset size high highLength == GT))
+          in case offset of
+               I# offset# -> case size of
+                 I# size# ->
+                   scan
+                     layout
+                     (index# +# 1#)
+                     (offset# +# size#)
+                     (if replaceLow then offset# else low#)
+                     (if replaceLow then size# else lowLength#)
+                     (if replaceHigh then offset# else high#)
+                     (if replaceHigh then size# else highLength#)
+                     (nans# +# if nan then 1# else 0#)
+      where
+        index = I# index#
+        cursor = I# cursor#
+        low = I# low#
+        lowLength = I# lowLength#
+        high = I# high#
+        highLength = I# highLength#
+        nans = I# nans#
+    {-# INLINE raw #-}
+    raw offset = case width of
+      2 -> fromIntegral (word16At bytes offset)
+      4 -> fromIntegral (word32At bytes offset)
+      _ -> word64At bytes offset
+    {-# INLINE compareAt #-}
+    compareAt left leftSize right rightSize = case kind of
+      BooleanOrder -> compare (booleanAt bytes left) (booleanAt bytes right)
+      UnsignedOrder -> compare (raw left) (raw right)
+      SignedOrder -> compare (raw left `xor` sign) (raw right `xor` sign)
+      FloatingOrder -> compare (floatKey (raw left)) (floatKey (raw right))
+      DecimalOrder -> compareDecimal bytes left leftSize right rightSize
+      Timestamp96Order -> compareLittleSigned96 bytes left right
+      LegacyTimestampOrder ->
+        case compare (word32At bytes (left + 8) `xor` 0x80000000) (word32At bytes (right + 8) `xor` 0x80000000) of
+          EQ -> compare (word64At bytes left `xor` 0x8000000000000000) (word64At bytes right `xor` 0x8000000000000000)
+          result -> result
+      _ -> compareSpan bytes left leftSize right rightSize
+    floatKey bits = if bits .&. sign /= 0 then complement bits .&. mask else bits `xor` sign
+    bound lower offset size
+      | kind == BooleanOrder = BS.singleton (booleanAt bytes offset)
+      | kind == FloatingOrder && order == TypeDefinedOrder && raw offset .&. (sign - 1) == 0 =
+          let zero = if lower then sign else 0
+          in BL.toStrict $ Builder.toLazyByteString $ case width of
+               2 -> Builder.word16LE (fromIntegral zero)
+               4 -> Builder.word32LE (fromIntegral zero)
+               _ -> Builder.word64LE zero
+      | otherwise = BS.take size (BS.drop offset bytes)
+
+
+booleanAt :: ByteString -> Int -> Word8
+booleanAt bytes index = (BSU.unsafeIndex bytes (index `quot` 8) `shiftR` (index `rem` 8)) .&. 1
+{-# INLINE booleanAt #-}
+
+
+compareSpan :: ByteString -> Int -> Int -> Int -> Int -> Ordering
+compareSpan bytes left leftSize right rightSize = go 0
+  where
+    !common = min leftSize rightSize
+    go !index
+      | index == common = compare leftSize rightSize
+      | otherwise = case compare (BSU.unsafeIndex bytes (left + index)) (BSU.unsafeIndex bytes (right + index)) of
+          EQ -> go (index + 1)
+          result -> result
+{-# INLINE compareSpan #-}
+
+
+compareLittleSigned96 :: ByteString -> Int -> Int -> Ordering
+compareLittleSigned96 bytes left right =
+  case compare (BSU.unsafeIndex bytes (left + 11) `xor` 128) (BSU.unsafeIndex bytes (right + 11) `xor` 128) of
+    EQ -> go 10
+    result -> result
+  where
+    go !index
+      | index < 0 = EQ
+      | otherwise = case compare (BSU.unsafeIndex bytes (left + index)) (BSU.unsafeIndex bytes (right + index)) of
+          EQ -> go (index - 1)
+          result -> result
+{-# INLINE compareLittleSigned96 #-}
+
+
+compareDecimal :: ByteString -> Int -> Int -> Int -> Int -> Ordering
+compareDecimal bytes left leftSize right rightSize
+  | leftSize == 0 || rightSize == 0 = compare leftSize rightSize
+  | leftNegative /= rightNegative = if leftNegative then LT else GT
+  | leftSize == rightSize = compareSpan bytes left leftSize right rightSize
+  | otherwise =
+      let !leftStart = significant left (left + leftSize) leftNegative
+          !rightStart = significant right (right + rightSize) rightNegative
+          !leftLength = left + leftSize - leftStart
+          !rightLength = right + rightSize - rightStart
+      in case compare leftLength rightLength of
+           EQ -> compareSpan bytes leftStart leftLength rightStart rightLength
+           result -> if leftNegative then invert result else result
+  where
+    leftNegative = BSU.unsafeIndex bytes left .&. 128 /= 0
+    rightNegative = BSU.unsafeIndex bytes right .&. 128 /= 0
+    significant !start !end negative
+      | start + 1 == end = start
+      | BSU.unsafeIndex bytes start == (if negative then 255 else 0)
+      , (BSU.unsafeIndex bytes (start + 1) .&. 128 /= 0) == negative =
+          significant (start + 1) end negative
+      | otherwise = start
+    invert LT = GT
+    invert GT = LT
+    invert EQ = EQ
+{-# INLINE compareDecimal #-}
diff --git a/src/Parquet/Nested/Types.hs b/src/Parquet/Nested/Types.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Nested/Types.hs
@@ -0,0 +1,225 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | Shared writer data types. Kept internal so Variant schema validation
+and nested writing can depend on each other without a module cycle.
+-}
+module Parquet.Nested.Types where
+
+import Arrow.Types qualified as A
+import Data.Bits (shiftL, shiftR)
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int32, Int64)
+import Data.Set qualified as Set
+import Data.Text (Text)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Word (Word16)
+import Parquet.File qualified as F
+import Parquet.Types (LtTimeUnit (..))
+import Parquet.Variant qualified as Variant
+
+
+{- | Description of one column tree, mirroring the user's logical
+type. 'NSOptional' / 'NSRequired' wrap a child to set the leaf or
+group's repetition (Optional / Required); 'NSList' / 'NSMap' /
+'NSStruct' name the compound types; 'NSVariant' emits the
+Iceberg V3 / Spark Variant 2-leaf binary group
+(@{required metadata: BINARY, required value: BINARY}@) annotated
+with the @VARIANT(1)@ logical type.
+
+Each named node accepts at most one Optional / Required wrapper. Map
+keys must be required, and structs must contain at least one field.
+The public writer validates these constraints before rows. 'NSVariantTyped'
+uses an opaque canonical schema from Parquet.Variant.Schema, preserving typed
+storage and original shared metadata/fallback bytes.
+-}
+data NestedSchema
+  = NSPrimitive !LeafType
+  | NSOptional !NestedSchema
+  | NSRequired !NestedSchema
+  | NSList !NestedSchema
+  | NSMap !NestedSchema !NestedSchema -- key, value
+  | NSStruct !(V.Vector (Text, NestedSchema))
+  | NSFile !F.FileSchema
+  | NSVariant
+  | NSVariantWithLimits !Variant.VariantLimits
+  | NSVariantTyped !VariantStorageSchema
+  deriving (Show, Eq)
+
+
+-- | Leaf primitive type and its Parquet physical encoding.
+data LeafType
+  = LtInt32
+  | LtInt64
+  | LtFloat16
+  | LtFloat
+  | LtDouble
+  | LtBool
+  | LtString
+  | LtJson
+  | LtBinary
+  | LtInteger !Int32 !Bool
+  | LtDate
+  | LtTime !Bool !LtTimeUnit
+  | LtTimestamp !Bool !LtTimeUnit
+  | -- | Signed96 little-endian Unix-epoch counts in fixed12 bytes.
+    LtTimestamp96 !Bool !LtTimeUnit
+  | -- | Legacy signed Julian day plus nanoseconds-within-day, in12bytes.
+    LtInt96
+  | {- | Precision1..76 and scale0..precision; narrowest standard numeric
+    carrier, then fixed16/32bytes. Wide values use signed big-endian bytes.
+    -}
+    LtDecimal !Int32 !Int32
+  | LtFixedBinary !Int32
+  | LtUuid
+  deriving (Show, Eq)
+
+
+-- | One value at a schema node, with fields in schema order.
+data NestedRow
+  = -- | a primitive value (matched against an NSPrimitive node)
+    NRLeaf !LeafValue
+  | -- | a Nothing at an NSOptional wrapper
+    NRNull
+  | -- | a list (possibly empty)
+    NRList !(V.Vector NestedRow)
+  | -- | struct fields, indexed in NSStruct order
+    NRStruct !(V.Vector NestedRow)
+  | -- | a map, as a vector of (key, value) pairs
+    NRMapEntries !(V.Vector (NestedRow, NestedRow))
+  | -- | A FILE reference. Use "Parquet.File" for schemas and resolution.
+    NRFile !F.FileReference
+  | {- | Pre-encoded Variant @(metadataBytes, valueBytes)@, matching
+    the two binary leaves an 'NSVariant' schema emits. Use
+    'encodeVariant' from "Parquet.Variant" to obtain the bytes.
+    -}
+    NRVariantBytes !ByteString !ByteString
+  deriving (Show, Eq)
+
+
+-- | Concrete value in a primitive leaf.
+data LeafValue
+  = LvInt32 !Int32
+  | LvInt64 !Int64
+  | -- | IEEE binary16 bits, retaining signed zeros and NaN payloads.
+    LvFloat16 !Word16
+  | LvFloat !Float
+  | LvDouble !Double
+  | LvBool !Bool
+  | LvString !Text
+  | LvBinary !ByteString
+  | -- | Unprefixed fixed-size bytes (including UUID and wide DECIMAL).
+    LvFixedBinary !ByteString
+  deriving (Show, Eq)
+
+
+-- The constructor is package-private. Only the canonical schema compiler
+-- builds these plans; public callers receive an opaque validated value.
+data VariantStorageSchema = VariantStorageSchema
+  { storageLimits :: !Variant.VariantLimits
+  , storageField :: !A.Field
+  , storageLayout :: !NestedSchema
+  , storageMetadataIndex :: {-# UNPACK #-} !Int
+  , storageFieldIds :: !(V.Vector (Maybe Int32))
+  , storageNode :: !VariantStorageNode
+  }
+  deriving (Show, Eq)
+
+
+data VariantStorageNode = VariantStorageNode
+  { storageFieldCount :: {-# UNPACK #-} !Int
+  , storageValueIndex :: {-# UNPACK #-} !Int
+  , storageTypedIndex :: {-# UNPACK #-} !Int
+  , storageValueRequired :: !Bool
+  , storageTypedRequired :: !Bool
+  , storageTyped :: !(Maybe VariantStorageTyped)
+  , storageNormalizationBelow :: !Bool
+  }
+  deriving (Show, Eq)
+
+
+data VariantStorageTyped
+  = StoragePrimitive
+  | StorageObject !(V.Vector VariantStorageChild) !(Set.Set Text)
+  | StorageArray !VariantStorageNode
+  deriving (Show, Eq)
+
+
+data VariantStorageChild = VariantStorageChild
+  { storageChildName :: !Text
+  , storageChildIndex :: {-# UNPACK #-} !Int
+  , storageChildNode :: !VariantStorageNode
+  }
+  deriving (Show, Eq)
+
+
+-- Shared by both shredders so the hot path can inline validation.
+leafValueMatches :: LeafType -> LeafValue -> Bool
+leafValueMatches typ value = case (typ, value) of
+  (LtInteger 64 _, LvInt64 {}) -> True
+  (LtInteger width signed, LvInt32 x)
+    | width == 32 -> True
+    | width == 8 || width == 16 ->
+        if signed
+          then let bound = (1 :: Int32) `shiftL` (fromIntegral width - 1) in x >= negate bound && x < bound
+          else x >= 0 && x < (1 :: Int32) `shiftL` fromIntegral width
+  (LtDate, LvInt32 {}) -> True
+  (LtTime _ LtMillis, LvInt32 x) -> x >= 0 && x < 86400000
+  (LtTime _ LtMicros, LvInt64 x) -> x >= 0 && x < 86400000000
+  (LtTime _ LtNanos, LvInt64 x) -> x >= 0 && x < 86400000000000
+  (LtTimestamp {}, LvInt64 {}) -> True
+  (LtTimestamp96 {}, LvFixedBinary bytes) -> BS.length bytes == 12
+  (LtInt96, LvFixedBinary bytes) -> BS.length bytes == 12
+  (LtInt32, LvInt32 {}) -> True
+  (LtInt64, LvInt64 {}) -> True
+  (LtFloat16, LvFloat16 {}) -> True
+  (LtFloat, LvFloat {}) -> True
+  (LtDouble, LvDouble {}) -> True
+  (LtBool, LvBool {}) -> True
+  (LtString, LvString {}) -> True
+  (LtJson, LvString {}) -> True
+  (LtBinary, LvBinary {}) -> True
+  (LtFixedBinary width, LvFixedBinary bytes) -> BS.length bytes == fromIntegral width
+  (LtUuid, LvFixedBinary bytes) -> BS.length bytes == 16
+  (LtDecimal precision _, LvInt32 raw) | precision <= 9 -> decimalFitsSmall precision (fromIntegral raw)
+  (LtDecimal precision _, LvInt64 raw) | precision > 9 && precision <= 18 -> decimalFitsSmall precision raw
+  (LtDecimal precision _, LvFixedBinary bytes)
+    | precision > 18 && precision <= 76 ->
+        BS.length bytes == (if precision <= 38 then 16 else 32) && decimalFitsBytes precision bytes
+  _ -> False
+{-# INLINE leafValueMatches #-}
+
+
+-- Bounds are shared across all rows. Do not exponentiate, construct an
+-- Integer, or decode wide bytes to Integer in the value-validation loop.
+decimalFitsSmall :: Int32 -> Int64 -> Bool
+decimalFitsSmall precision raw
+  | precision < 1 || precision > 18 = False
+  | otherwise = let !bound = VP.unsafeIndex decimalSmallBounds (fromIntegral precision) in raw > negate bound && raw < bound
+{-# INLINE decimalFitsSmall #-}
+
+
+decimalSmallBounds :: VP.Vector Int64
+decimalSmallBounds = VP.generate 19 (\precision -> 10 ^ precision)
+{-# NOINLINE decimalSmallBounds #-}
+
+
+data DecimalByteBounds = DecimalByteBounds !ByteString !ByteString
+
+
+decimalByteBounds :: V.Vector DecimalByteBounds
+decimalByteBounds = V.generate 77 $ \precision ->
+  let width = if precision <= 38 then 16 else 32
+      bound = 10 ^ precision :: Integer
+      bytes value = BS.pack (map (\index -> fromInteger (value `shiftR` (8 * (width - 1 - index)))) [0 .. width - 1])
+  in DecimalByteBounds (bytes (negate bound)) (bytes bound)
+{-# NOINLINE decimalByteBounds #-}
+
+
+decimalFitsBytes :: Int32 -> ByteString -> Bool
+decimalFitsBytes precision bytes
+  | precision < 19 || precision > 76 || BS.null bytes = False
+  | otherwise = case V.unsafeIndex decimalByteBounds (fromIntegral precision) of
+      DecimalByteBounds low high -> if BS.head bytes >= 128 then bytes > low else bytes < high
+{-# INLINE decimalFitsBytes #-}
diff --git a/src/Parquet/NullPagesBitmap.hs b/src/Parquet/NullPagesBitmap.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/NullPagesBitmap.hs
@@ -0,0 +1,93 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | SIMD-accelerated helpers for Parquet @ColumnIndex.null_pages@.
+
+@ColumnIndex@ stores a @Vector Bool@ where index @i@ is @True@ when the
+corresponding page is entirely null. Scan planners want fast answers
+to two questions:
+
+1. /How many/ pages can be skipped because they are all-null?
+2. /Which/ pages overlap with a given delete-position range or
+   deletion vector? The complement (\"which pages have at least one
+   non-null row\") is the working set.
+
+The @null_pages@ vector is dense (one bit per page; tables typically
+have hundreds to thousands of pages per row group), so packing it as
+a 1-bit-per-page bitmap and using "Wireform.Hash"'s Roaring
+32-bit kernels (or "Columnar.SIMD"'s @popcount@ for non-zero counts)
+gives a much tighter scan than the boxed boolean vector.
+-}
+module Parquet.NullPagesBitmap (
+  packNullPages,
+  unpackNullPages,
+  nullPageCount,
+  nonNullPages,
+) where
+
+import Columnar.SIMD (bitmapPopCount)
+import Data.Bits (shiftL, shiftR, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Vector qualified as V
+import Data.Word (Word8)
+
+
+{- | Pack a @null_pages@ vector into an LSB-first bitmap, one bit per
+page (1 = null page, 0 = page has at least one non-null row).
+-}
+packNullPages :: V.Vector Bool -> ByteString
+packNullPages vs =
+  let !n = V.length vs
+      !numBytes = (n + 7) `shiftR` 3
+  in BS.pack [byteAt i | i <- [0 .. numBytes - 1]]
+  where
+    !n = V.length vs
+    byteAt :: Int -> Word8
+    byteAt byteIdx =
+      let go !bit !acc
+            | bit >= 8 = acc
+            | byteIdx * 8 + bit >= n = acc
+            | otherwise =
+                let !v = V.unsafeIndex vs (byteIdx * 8 + bit)
+                    !flag =
+                      if v
+                        then acc .|. (1 `shiftL` bit)
+                        else acc
+                in go (bit + 1) flag
+      in fromIntegral (go 0 (0 :: Int))
+
+
+-- | Inverse of 'packNullPages'.
+unpackNullPages :: Int -> ByteString -> V.Vector Bool
+unpackNullPages n bs = V.generate n $ \i ->
+  let !byteIdx = i `shiftR` 3
+      !bit = i .&. 7
+      !b = if byteIdx < BS.length bs then BS.index bs byteIdx else 0
+  in (b `shiftR` bit) .&. 1 == 1
+
+
+{- | Number of null pages in the bitmap. Backed by the SIMD
+'bitmapPopCount' kernel from "Columnar.SIMD".
+-}
+nullPageCount :: ByteString -> Int
+nullPageCount = bitmapPopCount
+{-# INLINE nullPageCount #-}
+
+
+{- | Indices of pages that are /not/ all-null - i.e. the pages a scan
+needs to read. Walks 8 bits at a time and uses GHC's @countLeadingZeros@
+intrinsic for cheap bit-scan, the same pattern the Roaring BITSET
+decoder uses.
+-}
+nonNullPages :: Int -> ByteString -> V.Vector Int
+nonNullPages totalPages bs = V.fromList (go 0)
+  where
+    go !i
+      | i >= totalPages = []
+      | otherwise =
+          let !byteIdx = i `shiftR` 3
+              !bit = i .&. 7
+              !b = if byteIdx < BS.length bs then BS.index bs byteIdx else 0
+          in if (b `shiftR` bit) .&. 1 == 1
+               then go (i + 1)
+               else i : go (i + 1)
diff --git a/src/Parquet/Page.hs b/src/Parquet/Page.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Page.hs
@@ -0,0 +1,376 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE ForeignFunctionInterface #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE PatternSynonyms #-}
+
+{- | Parquet page headers (Thrift compact protocol).
+
+See @parquet.thrift@ (@PageHeader@, @DataPageHeader@, @DictionaryPageHeader@,
+@DataPageHeaderV2@). Thrift field placement is mediated by the
+pattern synonyms in "Parquet.Thrift.Schema".
+-}
+module Parquet.Page (
+  PageHeader (..),
+  PageType (..),
+  DataPageHeader (..),
+  DictionaryPageHeader (..),
+  DataPageHeaderV2 (..),
+  readPageHeaderAt,
+  readPageHeaderCheckedAt,
+  PageDetails (..),
+  readPageDetailsAt,
+  readPageDetailsCheckedAt,
+  pageTypeTag,
+  pageTypeIsDataPageV1,
+  pageTypeIsDataPageV2,
+  pageTypeIsDictionary,
+  verifyPageChecksum,
+) where
+
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Int (Int16, Int32, Int64)
+import Data.Vector qualified as V
+import Data.Word (Word32, Word8)
+import Foreign.C.Types (CUInt (..), CULong (..))
+import Foreign.Ptr (Ptr, castPtr)
+import Parquet.Thrift.Schema
+import System.IO.Unsafe (unsafeDupablePerformIO)
+import Thrift.Decode (decodeCompactFrom)
+import Thrift.Value qualified as TV
+
+
+{- | Discriminated union over Parquet page types. Mirrors the
+@PageType@ enum in @parquet.thrift@ (DATA_PAGE=0, INDEX_PAGE=1,
+DICTIONARY_PAGE=2, DATA_PAGE_V2=3) but each constructor carries the
+nested struct that the spec couples with that variant — there is no
+meaningful "DATA_PAGE without DataPageHeader" value on the wire, so
+we don't represent one.
+-}
+data PageType
+  = PtDataPage !DataPageHeader
+  | PtIndexPage
+  | PtDictionaryPage !DictionaryPageHeader
+  | PtDataPageV2 !DataPageHeaderV2
+  deriving stock (Show, Eq)
+
+
+-- | The on-the-wire @PageType@ tag (Thrift @PageHeader.type@, field 1).
+pageTypeTag :: PageType -> Int32
+pageTypeTag = \case
+  PtDataPage {} -> 0
+  PtIndexPage -> 1
+  PtDictionaryPage {} -> 2
+  PtDataPageV2 {} -> 3
+
+
+pageTypeIsDataPageV1 :: PageType -> Bool
+pageTypeIsDataPageV1 PtDataPage {} = True
+pageTypeIsDataPageV1 _ = False
+
+
+pageTypeIsDataPageV2 :: PageType -> Bool
+pageTypeIsDataPageV2 PtDataPageV2 {} = True
+pageTypeIsDataPageV2 _ = False
+
+
+pageTypeIsDictionary :: PageType -> Bool
+pageTypeIsDictionary PtDictionaryPage {} = True
+pageTypeIsDictionary _ = False
+
+
+data PageHeader = PageHeader
+  { phType :: !PageType
+  , phUncompressedPageSize :: !(Maybe Int32)
+  , phCompressedPageSize :: !(Maybe Int32)
+  }
+  deriving stock (Show, Eq)
+
+
+-- | Nested @DataPageHeader@ (field 5 of @PageHeader@).
+data DataPageHeader = DataPageHeader
+  { dphNumValues :: !Int32
+  , dphEncoding :: !Int32
+  }
+  deriving stock (Show, Eq)
+
+
+-- | Nested @DictionaryPageHeader@ (field 7 of @PageHeader@).
+data DictionaryPageHeader = DictionaryPageHeader
+  { dictNumValues :: !Int32
+  , dictEncoding :: !Int32
+  }
+  deriving stock (Show, Eq)
+
+
+{- | Nested @DataPageHeaderV2@ (field 8 of @PageHeader@).
+Parquet Thrift field IDs 1–7 of the @DataPageHeaderV2@ struct.
+-}
+data DataPageHeaderV2 = DataPageHeaderV2
+  { dph2NumValues :: !Int32
+  , dph2NumNulls :: !Int32
+  , dph2NumRows :: !Int32
+  , dph2Encoding :: !Int32
+  , dph2DefLevelsLen :: !Int32
+  , dph2RepLevelsLen :: !Int32
+  , dph2IsCompressed :: !Bool
+  }
+  deriving stock (Show, Eq)
+
+
+readPageHeaderAt :: ByteString -> Int -> Either String (PageHeader, Int)
+readPageHeaderAt bs off = do
+  details <- readPageDetailsAt bs off
+  Right (pdHeader details, pdBodyOffset details)
+
+
+data PageDetails = PageDetails
+  { pdHeader :: !PageHeader
+  , pdBodyOffset :: {-# UNPACK #-} !Int
+  , pdDefinitionEncoding :: {-# UNPACK #-} !Int32
+  , pdRepetitionEncoding :: {-# UNPACK #-} !Int32
+  , pdChecksum :: !(Maybe Word32)
+  }
+
+
+readPageDetailsAt :: ByteString -> Int -> Either String PageDetails
+readPageDetailsAt bs off
+  | off < 0 || off >= BS.length bs = Left "Parquet.Page: header offset out of bounds"
+  | otherwise = do
+      (v, endOff) <- decodeCompactFrom bs off
+      ph <- pageHeaderFromThrift v
+      validatePageHeader ph
+      checksum <- case v of
+        TV.Struct fs ->
+          V.foldM
+            ( \seen field -> case field of
+                PageHeader_Crc n -> case seen of
+                  Nothing -> Right (Just (fromIntegral n))
+                  Just _ -> Left "Parquet.Page: duplicate CRC field"
+                (4, _) -> Left "Parquet.Page: CRC must be an i32"
+                _ -> Right seen
+            )
+            Nothing
+            fs
+        _ -> Right Nothing
+      let fields = case v of TV.Struct fs -> V.toList fs; _ -> []
+          inner = maybe [] V.toList $ findField fields $ \case
+            PageHeader_DataPageHeader fs -> Just fs
+            _ -> Nothing
+          definition = maybe 3 id $ findField inner $ \case
+            DataPageHeader_DefinitionLevelEncoding n -> Just n
+            _ -> Nothing
+          repetition = maybe 3 id $ findField inner $ \case
+            DataPageHeader_RepetitionLevelEncoding n -> Just n
+            _ -> Nothing
+      pure (PageDetails ph endOff definition repetition checksum)
+
+
+{- | Read a complete page header and check the serialized (compressed) body.
+Header-only callers, including encryption framing, use 'readPageHeaderAt'.
+Every data reader uses this checked variant before decoding or decompressing.
+-}
+readPageHeaderCheckedAt :: ByteString -> Int -> Either String (PageHeader, Int)
+readPageHeaderCheckedAt bs off = do
+  details <- readPageDetailsCheckedAt bs off
+  Right (pdHeader details, pdBodyOffset details)
+
+
+readPageDetailsCheckedAt :: ByteString -> Int -> Either String PageDetails
+readPageDetailsCheckedAt bs off = do
+  details <- readPageDetailsAt bs off
+  let body = pdBodyOffset details
+  case phCompressedPageSize (pdHeader details) of
+    Just size
+      | fromIntegral size <= BS.length bs - body -> case pdChecksum details of
+          Nothing -> Right details
+          Just expected
+            | pageCrc32 (BS.take (fromIntegral size) (BS.drop body bs)) == expected -> Right details
+            | otherwise -> Left "Parquet.Page: CRC32 checksum mismatch"
+    _ -> Left "Parquet.Page: truncated page body"
+
+
+-- zlib's uInt length is safe here: the validated page size is a nonnegative
+-- signed 32-bit integer, bounded below uInt's maximum on supported platforms.
+-- The foreign call is deterministic and only reads the immutable bytes.
+-- Only validated Parquet page bodies reach this worker, so their signed
+-- 32-bit size fits zlib's unsigned-int byte count without narrowing overflow.
+pageCrc32 :: ByteString -> Word32
+pageCrc32 bytes = unsafeDupablePerformIO $
+  BSU.unsafeUseAsCStringLen bytes $ \(ptr, len) ->
+    fromIntegral <$> c_crc32 0 (castPtr ptr) (fromIntegral len)
+{-# NOINLINE pageCrc32 #-}
+
+
+-- | Check the CRC of an on-disk page body, including encryption framing.
+-- Enforce Parquet's signed 32-bit page-size bound before calling zlib.
+verifyPageChecksum :: Word32 -> ByteString -> Either String ()
+verifyPageChecksum expected bytes
+  | BS.length bytes > fromIntegral (maxBound :: Int32) = Left "Parquet.Page: page body exceeds signed 32-bit size"
+  | pageCrc32 bytes == expected = Right ()
+  | otherwise = Left "Parquet.Page: CRC32 checksum mismatch"
+
+
+foreign import ccall unsafe "crc32"
+  c_crc32 :: CULong -> Ptr Word8 -> CUInt -> IO CULong
+
+
+validatePageHeader :: PageHeader -> Either String ()
+validatePageHeader header = do
+  uncompressed <- size "uncompressed_page_size" (phUncompressedPageSize header)
+  compressed <- size "compressed_page_size" (phCompressedPageSize header)
+  case phType header of
+    PtDataPage page
+      | dphNumValues page < 0 -> Left "Parquet.Page: negative data-page value count"
+    PtDictionaryPage page
+      | dictNumValues page < 0 -> Left "Parquet.Page: negative dictionary value count"
+    PtDataPageV2 page
+      | dph2NumValues page < 0
+          || dph2NumNulls page < 0
+          || dph2NumRows page < 0
+          || dph2DefLevelsLen page < 0
+          || dph2RepLevelsLen page < 0 ->
+          Left "Parquet.Page: negative V2 count or level length"
+      | dph2NumNulls page > dph2NumValues page || dph2NumRows page > dph2NumValues page ->
+          Left "Parquet.Page: inconsistent V2 row/null/value counts"
+      | let levels = fromIntegral (dph2DefLevelsLen page) + fromIntegral (dph2RepLevelsLen page) :: Int64
+      , levels > fromIntegral uncompressed || levels > fromIntegral compressed ->
+          Left "Parquet.Page: V2 level lengths exceed page sizes"
+    _ -> Right ()
+  where
+    size name = \case
+      Just n | n >= 0 -> Right n
+      _ -> Left ("Parquet.Page: missing or negative " ++ name)
+
+
+pageHeaderFromThrift :: TV.Value -> Either String PageHeader
+pageHeaderFromThrift (TV.Struct fields) = do
+  let fm = V.toList fields
+  ty <- requireI32 fm "PageHeader.type" $ \case
+    PageHeader_Type v -> Just v
+    _ -> Nothing
+  let unc = findField fm $ \case
+        PageHeader_UncompressedSize v -> Just v
+        _ -> Nothing
+      comp = findField fm $ \case
+        PageHeader_CompressedSize v -> Just v
+        _ -> Nothing
+  pageType <- case ty of
+    0 -> case findField
+      fm
+      ( \case
+          PageHeader_DataPageHeader fs -> Just fs
+          _ -> Nothing
+      ) of
+      Just fs -> PtDataPage <$> dataPageHeaderFromThrift (TV.Struct fs)
+      Nothing ->
+        Left
+          "Parquet.Page: DATA_PAGE without DataPageHeader (field 5)"
+    1 -> Right PtIndexPage
+    2 -> case findField
+      fm
+      ( \case
+          PageHeader_DictionaryPageHeader fs -> Just fs
+          _ -> Nothing
+      ) of
+      Just fs -> PtDictionaryPage <$> dictionaryPageHeaderFromThrift (TV.Struct fs)
+      Nothing ->
+        Left
+          "Parquet.Page: DICTIONARY_PAGE without DictionaryPageHeader (field 7)"
+    3 -> case findField
+      fm
+      ( \case
+          PageHeader_DataPageHeaderV2 fs -> Just fs
+          _ -> Nothing
+      ) of
+      Just fs -> PtDataPageV2 <$> dataPageHeaderV2FromThrift (TV.Struct fs)
+      Nothing ->
+        Left
+          "Parquet.Page: DATA_PAGE_V2 without DataPageHeaderV2 (field 8)"
+    _ -> Left ("Parquet.Page: unknown PageType tag " ++ show ty)
+  pure
+    PageHeader
+      { phType = pageType
+      , phUncompressedPageSize = unc
+      , phCompressedPageSize = comp
+      }
+pageHeaderFromThrift _ = Left "Parquet.Page: expected PageHeader struct"
+
+
+dataPageHeaderFromThrift :: TV.Value -> Either String DataPageHeader
+dataPageHeaderFromThrift (TV.Struct fields) = do
+  let fm = V.toList fields
+  n <- requireI32 fm "DataPageHeader.num_values" $ \case
+    DataPageHeader_NumValues v -> Just v
+    _ -> Nothing
+  -- encoding defaults to 0 (PLAIN) when absent, per historic writers.
+  let enc = maybe 0 id $ findField fm $ \case
+        DataPageHeader_Encoding v -> Just v
+        _ -> Nothing
+  pure DataPageHeader {dphNumValues = n, dphEncoding = enc}
+dataPageHeaderFromThrift _ = Left "Parquet.Page: expected DataPageHeader struct"
+
+
+dictionaryPageHeaderFromThrift :: TV.Value -> Either String DictionaryPageHeader
+dictionaryPageHeaderFromThrift (TV.Struct fields) = do
+  let fm = V.toList fields
+  n <- requireI32 fm "DictionaryPageHeader.num_values" $ \case
+    DictionaryPageHeader_NumValues v -> Just v
+    _ -> Nothing
+  let enc = maybe 0 id $ findField fm $ \case
+        DictionaryPageHeader_Encoding v -> Just v
+        _ -> Nothing
+  pure DictionaryPageHeader {dictNumValues = n, dictEncoding = enc}
+dictionaryPageHeaderFromThrift _ = Left "Parquet.Page: expected DictionaryPageHeader struct"
+
+
+dataPageHeaderV2FromThrift :: TV.Value -> Either String DataPageHeaderV2
+dataPageHeaderV2FromThrift (TV.Struct fields) = do
+  let fm = V.toList fields
+  nv <- requireI32 fm "DataPageHeaderV2.num_values" $ \case
+    DataPageHeaderV2_NumValues v -> Just v
+    _ -> Nothing
+  nn <- requireI32 fm "DataPageHeaderV2.num_nulls" $ \case
+    DataPageHeaderV2_NumNulls v -> Just v
+    _ -> Nothing
+  nr <- requireI32 fm "DataPageHeaderV2.num_rows" $ \case
+    DataPageHeaderV2_NumRows v -> Just v
+    _ -> Nothing
+  enc <- requireI32 fm "DataPageHeaderV2.encoding" $ \case
+    DataPageHeaderV2_Encoding v -> Just v
+    _ -> Nothing
+  dl <- requireI32 fm "DataPageHeaderV2.definition_levels_byte_length" $ \case
+    DataPageHeaderV2_DefinitionLevelsByteLength v -> Just v
+    _ -> Nothing
+  rl <- requireI32 fm "DataPageHeaderV2.repetition_levels_byte_length" $ \case
+    DataPageHeaderV2_RepetitionLevelsByteLength v -> Just v
+    _ -> Nothing
+  -- is_compressed is optional; spec default is true.
+  let isComp = maybe True id $ findField fm $ \case
+        DataPageHeaderV2_IsCompressed b -> Just b
+        _ -> Nothing
+  pure
+    DataPageHeaderV2
+      { dph2NumValues = nv
+      , dph2NumNulls = nn
+      , dph2NumRows = nr
+      , dph2Encoding = enc
+      , dph2DefLevelsLen = dl
+      , dph2RepLevelsLen = rl
+      , dph2IsCompressed = isComp
+      }
+dataPageHeaderV2FromThrift _ = Left "Parquet.Page: expected DataPageHeaderV2 struct"
+
+
+{- | Specialised @require@ for @Int32@ fields, producing a
+@Parquet.Page@-flavoured error message.
+-}
+requireI32
+  :: [(Int16, TV.Value)]
+  -> String
+  -> ((Int16, TV.Value) -> Maybe Int32)
+  -> Either String Int32
+requireI32 fm name probe = case findField fm probe of
+  Just v -> Right v
+  Nothing -> Left $ "Parquet.Page: missing or invalid field " ++ name
diff --git a/src/Parquet/PageIndex.hs b/src/Parquet/PageIndex.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/PageIndex.hs
@@ -0,0 +1,456 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE PatternSynonyms #-}
+
+{- | Apache Parquet page index: 'OffsetIndex' + 'ColumnIndex' (Thrift).
+
+The page index tier (added in parquet-format 2.5) lets readers skip
+entire pages without scanning column chunks. It is stored separately
+from the row-group metadata, near the file footer:
+
+* 'OffsetIndex' — per-page @(offset, compressed_page_size, first_row_index)@
+  plus optional @unencoded_byte_array_data_bytes@ (size_statistics).
+* 'ColumnIndex' — per-page @null_pages@, @min_values@, @max_values@,
+  plus a 'BoundaryOrder' and optional null/level histograms.
+
+'ColumnChunk' carries 'ccOffsetIndexOffset' / @offset_index_length@ and
+'ccColumnIndexOffset' / @column_index_length@; this module reads/writes
+the structures themselves with the Thrift Compact Protocol used by
+"Parquet.Footer".
+-}
+module Parquet.PageIndex (
+  -- * OffsetIndex
+  encodeOffsetIndex,
+  decodeOffsetIndex,
+  readOffsetIndex,
+
+  -- * ColumnIndex
+  encodeColumnIndex,
+  decodeColumnIndex,
+  readColumnIndex,
+
+  -- * Slicing
+  columnChunkOffsetIndexSlice,
+  columnChunkColumnIndexSlice,
+) where
+
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int16, Int32, Int64)
+import Data.Text.Encoding qualified
+import Data.Vector qualified as V
+import Parquet.Encryption qualified as Encryption
+import Parquet.Read (ParquetFile (..), decryptFileColumnModule, rawColumnChunkSlice)
+import Parquet.Thrift.Schema
+import Parquet.Types (
+  ColumnChunk (..),
+  ColumnIndex (..),
+  ColumnMetadata (..),
+  FileMetadata (..),
+  OffsetIndex (..),
+  PageLocation (..),
+  RowGroup (..),
+  boundaryOrderToInt,
+  intToBoundaryOrder,
+ )
+import Thrift.Decode (decodeCompactBinaryStrings)
+import Thrift.Encode (encodeCompact)
+import Thrift.Value qualified as TV
+
+
+-- ============================================================
+-- OffsetIndex
+-- ============================================================
+
+-- | Serialize an 'OffsetIndex' in Thrift Compact Protocol.
+encodeOffsetIndex :: OffsetIndex -> ByteString
+encodeOffsetIndex = encodeCompact . offsetIndexToThrift
+
+
+-- | Parse an 'OffsetIndex' from a Thrift Compact byte slice.
+decodeOffsetIndex :: ByteString -> Either String OffsetIndex
+decodeOffsetIndex bs = decodeCompactBinaryStrings bs >>= thriftToOffsetIndex
+
+
+{- | Look up the 'OffsetIndex' for the column chunk at @(rowGroupIdx, columnIdx)@
+if 'ccOffsetIndexOffset' / 'ccOffsetIndexLength' are populated and within
+file bounds.
+-}
+readOffsetIndex
+  :: ParquetFile
+  -> Int
+  -> Int
+  -> Either String (Maybe OffsetIndex)
+readOffsetIndex pf rg col = do
+  msl <- columnChunkOffsetIndexSlice pf rg col
+  case msl of
+    Nothing -> Right Nothing
+    Just bs -> do
+      index <- decodeOffsetIndex bs
+      validateColumnOffsets pf rg col index
+      Right (Just index)
+
+
+{- | Slice a 'ParquetFile' to the bytes covering a column chunk's serialized
+'OffsetIndex'. Returns 'Nothing' when the column chunk did not record one.
+-}
+columnChunkOffsetIndexSlice
+  :: ParquetFile
+  -> Int
+  -> Int
+  -> Either String (Maybe ByteString)
+columnChunkOffsetIndexSlice pf rgIdx colIdx = do
+  cc <- selectColumnChunk pf rgIdx colIdx
+  case (ccOffsetIndexOffset cc, ccOffsetIndexLength cc) of
+    (Just off, Just len) -> do
+      bytes <- sliceFile pf off len "offset index"
+      Just <$> decryptFileColumnModule pf rgIdx colIdx Encryption.ModuleOffsetIndex bytes
+    _ -> Right Nothing
+
+
+-- ============================================================
+-- ColumnIndex
+-- ============================================================
+
+-- | Serialize a 'ColumnIndex' in Thrift Compact Protocol.
+encodeColumnIndex :: ColumnIndex -> ByteString
+encodeColumnIndex = encodeCompact . columnIndexToThrift
+
+
+-- | Parse a 'ColumnIndex' without interpreting opaque min/max bytes as text.
+decodeColumnIndex :: ByteString -> Either String ColumnIndex
+decodeColumnIndex bs = decodeCompactBinaryStrings bs >>= thriftToColumnIndex
+
+
+{- | Look up the 'ColumnIndex' for the column chunk at @(rowGroupIdx,
+columnIdx)@.
+-}
+readColumnIndex
+  :: ParquetFile
+  -> Int
+  -> Int
+  -> Either String (Maybe ColumnIndex)
+readColumnIndex pf rg col = do
+  msl <- columnChunkColumnIndexSlice pf rg col
+  case msl of
+    Nothing -> Right Nothing
+    Just bs -> Just <$> decodeColumnIndex bs
+
+
+{- | Slice a 'ParquetFile' to the bytes covering a column chunk's serialized
+'ColumnIndex'. Returns 'Nothing' when the column chunk did not record one.
+-}
+columnChunkColumnIndexSlice
+  :: ParquetFile
+  -> Int
+  -> Int
+  -> Either String (Maybe ByteString)
+columnChunkColumnIndexSlice pf rgIdx colIdx = do
+  cc <- selectColumnChunk pf rgIdx colIdx
+  case (ccColumnIndexOffset cc, ccColumnIndexLength cc) of
+    (Just off, Just len) -> do
+      bytes <- sliceFile pf off len "column index"
+      Just <$> decryptFileColumnModule pf rgIdx colIdx Encryption.ModuleColumnIndex bytes
+    _ -> Right Nothing
+
+
+-- ============================================================
+-- Internal: Thrift conversions
+-- ============================================================
+
+offsetIndexToThrift :: OffsetIndex -> TV.Value
+offsetIndexToThrift oi =
+  TV.Struct $
+    V.fromList $
+      concat
+        [ [OffsetIndex_PageLocations (V.map pageLocationToThrift (oiPageLocations oi))]
+        , optField
+            (oiUnencodedByteArrayDataBytes oi)
+            (OffsetIndex_UnencodedByteArrayDataBytes . V.map TV.I64)
+        ]
+
+
+pageLocationToThrift :: PageLocation -> TV.Value
+pageLocationToThrift pl =
+  TV.Struct $
+    V.fromList
+      [ PageLocation_Offset (plOffset pl)
+      , PageLocation_CompressedPageSize (plCompressedPageSize pl)
+      , PageLocation_FirstRowIndex (plFirstRowIndex pl)
+      ]
+
+
+thriftToOffsetIndex :: TV.Value -> Either String OffsetIndex
+thriftToOffsetIndex (TV.Struct fields) = do
+  let fm = V.toList fields
+  pages <- case findField
+    fm
+    ( \case
+        OffsetIndex_PageLocations xs -> Just xs
+        _ -> Nothing
+    ) of
+    Just vs -> V.mapM thriftToPageLocation vs
+    Nothing -> Left "Parquet.PageIndex: missing page_locations"
+  unencV <- case findField
+    fm
+    ( \case
+        OffsetIndex_UnencodedByteArrayDataBytes xs -> Just xs
+        _ -> Nothing
+    ) of
+    Just vs -> Just <$> V.mapM expectI64 vs
+    Nothing -> Right Nothing
+  Right
+    OffsetIndex
+      { oiPageLocations = pages
+      , oiUnencodedByteArrayDataBytes = unencV
+      }
+thriftToOffsetIndex _ = Left "Parquet.PageIndex: expected struct for OffsetIndex"
+
+
+thriftToPageLocation :: TV.Value -> Either String PageLocation
+thriftToPageLocation (TV.Struct fields) = do
+  let fm = V.toList fields
+  off <- requireField fm "page_location.offset" $ \case
+    PageLocation_Offset v -> Just v
+    _ -> Nothing
+  csz <- requireField fm "page_location.compressed_page_size" $ \case
+    PageLocation_CompressedPageSize v -> Just v
+    _ -> Nothing
+  fri <- requireField fm "page_location.first_row_index" $ \case
+    PageLocation_FirstRowIndex v -> Just v
+    _ -> Nothing
+  Right
+    PageLocation
+      { plOffset = off
+      , plCompressedPageSize = csz
+      , plFirstRowIndex = fri
+      }
+thriftToPageLocation _ =
+  Left "Parquet.PageIndex: expected struct for PageLocation"
+
+
+columnIndexToThrift :: ColumnIndex -> TV.Value
+columnIndexToThrift ci =
+  TV.Struct $
+    V.fromList $
+      concat
+        [
+          [ ColumnIndex_NullPages (V.map TV.Bool (ciNullPages ci))
+          , ColumnIndex_MinValues (V.map TV.Binary (ciMinValues ci))
+          , ColumnIndex_MaxValues (V.map TV.Binary (ciMaxValues ci))
+          , ColumnIndex_BoundaryOrder (boundaryOrderToInt (ciBoundaryOrder ci))
+          ]
+        , optField
+            (ciNullCounts ci)
+            (ColumnIndex_NullCounts . V.map TV.I64)
+        , optField
+            (ciNanCounts ci)
+            (ColumnIndex_NanCounts . V.map TV.I64)
+        , optField
+            (ciRepetitionLevelHistograms ci)
+            (ColumnIndex_RepetitionLevelHistograms . V.map TV.I64)
+        , optField
+            (ciDefinitionLevelHistograms ci)
+            (ColumnIndex_DefinitionLevelHistograms . V.map TV.I64)
+        ]
+
+
+thriftToColumnIndex :: TV.Value -> Either String ColumnIndex
+thriftToColumnIndex (TV.Struct fields) = do
+  let fm = V.toList fields
+  nullPages <- case findField
+    fm
+    ( \case
+        ColumnIndex_NullPages xs -> Just xs
+        _ -> Nothing
+    ) of
+    Just vs -> V.mapM expectBool vs
+    Nothing -> Left "Parquet.PageIndex: missing null_pages"
+  mins <- case findField
+    fm
+    ( \case
+        ColumnIndex_MinValues xs -> Just xs
+        _ -> Nothing
+    ) of
+    Just vs -> V.mapM expectBinary vs
+    Nothing -> Left "Parquet.PageIndex: missing min_values"
+  maxs <- case findField
+    fm
+    ( \case
+        ColumnIndex_MaxValues xs -> Just xs
+        _ -> Nothing
+    ) of
+    Just vs -> V.mapM expectBinary vs
+    Nothing -> Left "Parquet.PageIndex: missing max_values"
+  boInt <- requireField fm "boundary_order" $ \case
+    ColumnIndex_BoundaryOrder v -> Just v
+    _ -> Nothing
+  bo <-
+    maybe
+      (Left $ "Parquet.PageIndex: invalid boundary_order " ++ show boInt)
+      Right
+      (intToBoundaryOrder boInt)
+  ncv <- optListI64 fm $ \case
+    ColumnIndex_NullCounts xs -> Just xs
+    _ -> Nothing
+  nanv <- optListI64 fm $ \case
+    ColumnIndex_NanCounts xs -> Just xs
+    _ -> Nothing
+  repv <- optListI64 fm $ \case
+    ColumnIndex_RepetitionLevelHistograms xs -> Just xs
+    _ -> Nothing
+  defv <- optListI64 fm $ \case
+    ColumnIndex_DefinitionLevelHistograms xs -> Just xs
+    _ -> Nothing
+  let count = V.length nullPages
+  if V.length mins /= count
+    || V.length maxs /= count
+    || maybe False ((/= count) . V.length) ncv
+    || maybe False ((/= count) . V.length) nanv
+    then Left "Parquet.PageIndex: per-page vector lengths differ"
+    else Right ()
+  if any (maybe False (V.any (< 0))) [ncv, nanv, repv, defv]
+    then Left "Parquet.PageIndex: negative count or level frequency"
+    else Right ()
+  Right
+    ColumnIndex
+      { ciNullPages = nullPages
+      , ciMinValues = mins
+      , ciMaxValues = maxs
+      , ciBoundaryOrder = bo
+      , ciNullCounts = ncv
+      , ciNanCounts = nanv
+      , ciRepetitionLevelHistograms = repv
+      , ciDefinitionLevelHistograms = defv
+      }
+thriftToColumnIndex _ =
+  Left "Parquet.PageIndex: expected struct for ColumnIndex"
+
+
+optListI64
+  :: [(Int16, TV.Value)]
+  -> ((Int16, TV.Value) -> Maybe (V.Vector TV.Value))
+  -> Either String (Maybe (V.Vector Int64))
+optListI64 fm probe = case findField fm probe of
+  Just vs -> Just <$> V.mapM expectI64 vs
+  Nothing -> Right Nothing
+
+
+-- ============================================================
+-- Helpers
+-- ============================================================
+
+selectColumnChunk
+  :: ParquetFile -> Int -> Int -> Either String ColumnChunk
+selectColumnChunk pf rgIdx colIdx = do
+  let rgs = fmRowGroups (pfFooter pf)
+  if rgIdx < 0 || rgIdx >= V.length rgs
+    then Left "Parquet.PageIndex: row group index out of range"
+    else do
+      let cs = rgColumns (V.unsafeIndex rgs rgIdx)
+      if colIdx < 0 || colIdx >= V.length cs
+        then Left "Parquet.PageIndex: column index out of range"
+        else do
+          let chunk = V.unsafeIndex cs colIdx
+          case ccFilePath chunk of
+            Just path | path /= mempty -> Left "Parquet.PageIndex: external column-chunk files are not supported"
+            _ -> Right chunk
+
+
+-- Check the complete index, including entries the predicate will skip.
+-- Data-page bytes are deliberately left untouched until a page is retained.
+validateColumnOffsets :: ParquetFile -> Int -> Int -> OffsetIndex -> Either String ()
+validateColumnOffsets pf groupIndex columnIndex index = do
+  chunk <- selectColumnChunk pf groupIndex columnIndex
+  metadata <- maybe (Left "Parquet.PageIndex: missing column metadata") Right (ccMetadata chunk)
+  bytes <- rawColumnChunkSlice pf groupIndex columnIndex
+  let group = fmRowGroups (pfFooter pf) V.! groupIndex
+      rows = rgNumRows group
+      locations = oiPageLocations index
+      start = maybe (cmDataPageOffset metadata) (min (cmDataPageOffset metadata)) (cmDictionaryPageOffset metadata)
+      size = if cmNumValues metadata == 0 then cmTotalCompressedSize metadata else fromIntegral (BS.length bytes)
+      fileSize = fromIntegral (BS.length (pfBytes pf)) :: Int64
+  if rows < 0 || start < 0 || start > fileSize || size < 0 || size > fileSize - start
+    then Left "Parquet.PageIndex: invalid column bounds"
+    else Right ()
+  if V.null locations && rows /= 0
+    then Left "Parquet.PageIndex: nonempty group has no indexed pages"
+    else Right ()
+  V.imapM_
+    ( \i location -> do
+        let offset = plOffset location
+            pageSize = fromIntegral (plCompressedPageSize location) :: Int64
+            row = plFirstRowIndex location
+        if offset < start
+          || offset > start + size
+          || pageSize <= 0
+          || pageSize > start + size - offset
+          || row < 0
+          || row >= rows && not (rows == 0 && i == 0)
+          || i == 0 && (row /= 0 || offset /= cmDataPageOffset metadata)
+          then Left "Parquet.PageIndex: page location lies outside its column/row range"
+          else Right ()
+        if i == 0
+          then Right ()
+          else do
+            let previous = locations V.! (i - 1)
+            if plOffset previous + fromIntegral (plCompressedPageSize previous) > offset
+              || plFirstRowIndex previous >= row
+              then Left "Parquet.PageIndex: unordered or overlapping page locations"
+              else Right ()
+    )
+    locations
+  case oiUnencodedByteArrayDataBytes index of
+    Just sizes
+      | V.length sizes /= V.length locations || V.any (< 0) sizes ->
+          Left "Parquet.PageIndex: invalid per-page unencoded byte counts"
+    _ -> Right ()
+
+
+sliceFile
+  :: ParquetFile
+  -> Int64
+  -> Int32
+  -> String
+  -> Either String ByteString
+sliceFile pf off len what =
+  let !o = fromIntegral off :: Int
+      !l = fromIntegral len :: Int
+      !bs = pfBytes pf
+  in if o < 0 || l < 0 || o + l > BS.length bs
+       then Left $ "Parquet.PageIndex: " ++ what ++ " slice out of bounds"
+       else Right $! BS.take l (BS.drop o bs)
+
+
+requireField
+  :: [(Int16, TV.Value)]
+  -> String
+  -> ((Int16, TV.Value) -> Maybe a)
+  -> Either String a
+requireField fm name probe = case findField fm probe of
+  Just v -> Right v
+  Nothing -> Left $ "Parquet.PageIndex: missing or invalid field " ++ name
+
+
+expectI64 :: TV.Value -> Either String Int64
+expectI64 (TV.I64 v) = Right v
+expectI64 v =
+  Left $
+    "Parquet.PageIndex: expected i64 but got " ++ show v
+
+
+expectBool :: TV.Value -> Either String Bool
+expectBool (TV.Bool b) = Right b
+expectBool v =
+  Left $
+    "Parquet.PageIndex: expected bool but got " ++ show v
+
+
+-- Thrift Compact transports binary and UTF-8 strings under the same
+-- @TT_STRING@ wire type, so the decoder may surface either shape.
+expectBinary :: TV.Value -> Either String ByteString
+expectBinary (TV.Binary b) = Right b
+expectBinary (TV.String t) =
+  Right $! Data.Text.Encoding.encodeUtf8 t
+expectBinary v =
+  Left $
+    "Parquet.PageIndex: expected binary but got " ++ show v
diff --git a/src/Parquet/Predicate.hs b/src/Parquet/Predicate.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Predicate.hs
@@ -0,0 +1,520 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE LambdaCase #-}
+
+{- | Predicate pushdown helpers for Parquet readers.
+
+The Parquet spec already gives the reader several places to
+avoid touching column data:
+
+  * Row-group 'Statistics' carry @min_value@ / @max_value@ /
+    @null_count@ for every column chunk.
+  * Page-level 'ColumnIndex' carries the same triple per page,
+    plus a 'BoundaryOrder' hint and an optional null-pages
+    bitmap.
+  * Per-column 'BloomFilter' (Sbbf) lets the reader prove a
+    value is /not/ present in the column chunk.
+
+This module bundles the three signals behind a single
+'Predicate' ADT so callers can express filters once and ask
+the planner whether a row group / page can be skipped without
+decoding it.
+
+The vocabulary is deliberately narrow — equality, range, and
+membership over the same scalar value space (@PValue@) the
+writer's statistics use. Compound boolean structure
+(@'PAnd'@, @'POr'@, @'PNot'@) composes up from there.
+
+@
+import qualified Parquet.Predicate as Pred
+
+let !p = 'PAnd' ('PCol' "ts" ('PGtEq' ('PVInt64' 1700000000)))
+               ('PCol' "ts" ('PLt'   ('PVInt64' 1700100000)))
+skipRowGroup :: 'P.RowGroup' -> Bool
+skipRowGroup rg = 'evalRowGroup' fileMetadata p rg == 'PSkip'
+@
+
+The evaluator never produces a /false negative/ skip
+(returning 'PSkip' when in fact some rows match) — if there's
+any uncertainty (missing statistics, types we don't compare)
+the answer is 'PMaybeKeep' and the caller falls back to
+decoding the column chunk normally.
+-}
+module Parquet.Predicate (
+  -- * Predicate vocabulary
+
+  --
+
+  {- | Re-exported from "Columnar.Predicate" so the same
+  @PValue@ / @PColPredicate@ / @Predicate@ surface drives
+  skip decisions in both Parquet and ORC.
+  -}
+  Predicate (..),
+  PColPredicate (..),
+  PValue (..),
+
+  -- * Evaluation results
+  Decision (..),
+  combineDecisions,
+  StatisticsContext (..),
+  statisticsContext,
+
+  -- * Statistics-based skipping
+  evalRowGroup,
+  evalColumnChunk,
+
+  -- * Page-index-based skipping
+  evalPagesByColumnIndex,
+
+  -- * Bloom-filter membership
+  evalBloomChunk,
+
+  -- * Conversions
+  decodePValueLE,
+  decodePValueForSchema,
+  minimumStatistic,
+  maximumStatistic,
+) where
+
+import Arrow.Column qualified as AC
+import Columnar.Predicate (
+  Decision (..),
+  PColPredicate (..),
+  PValue (..),
+  Predicate (..),
+  combineDecisions,
+  evalRange,
+ )
+import Data.Bits (shiftL, (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int32, Int64)
+import Data.Ratio (denominator, numerator)
+import Data.Text (Text)
+import Data.Text qualified as T
+import Data.Text.Encoding qualified as TE
+import Data.Vector qualified as V
+import Data.Word (Word32, Word64)
+import GHC.Float (castDoubleToWord64, castFloatToWord32, castWord32ToFloat, castWord64ToDouble)
+import Parquet.BloomFilter qualified as Bloom
+import Parquet.Decimal (decodeDecimalInteger)
+import Parquet.Types qualified as P
+
+
+-- ============================================================
+-- Statistics-based skipping
+-- ============================================================
+
+{- | Logical type plus the file's declared ordering. Missing orders cannot
+give meaning to modern bounds; well-defined legacy numeric bounds remain
+usable independently of this optional declaration.
+-}
+data StatisticsContext = StatisticsContext
+  { statisticsField :: !P.SchemaElement
+  , statisticsOrder :: !(Maybe P.ColumnOrder)
+  }
+  deriving (Show, Eq)
+
+
+statisticsContext :: P.FileMetadata -> Int -> Maybe StatisticsContext
+statisticsContext metadata index = do
+  field <- V.filter (maybe False (const True) . P.seType) (P.fmSchema metadata) V.!? index
+  Just (StatisticsContext field (P.fmColumnOrders metadata >>= (V.!? index)))
+
+
+modernOrderSupported :: StatisticsContext -> Bool
+modernOrderSupported context =
+  P.hasDefinedStatisticsOrder field && case statisticsOrder context of
+    Just P.TypeDefinedOrder -> P.seType field /= Just P.PTInt96
+    Just P.IEEE754TotalOrder ->
+      P.seType field `elem` [Just P.PTFloat, Just P.PTDouble]
+        || P.seLogicalType field == Just P.LTFloat16
+    Just P.Int96TimestampOrder -> P.seType field == Just P.PTInt96
+    _ -> False
+  where
+    field = statisticsField context
+
+
+{- | Decide whether an entire row group can be skipped.
+
+Walks the predicate tree, looking up each leaf's column by
+column path in the file schema. The schema retains logical annotations
+so decimal and unsigned bounds use their numeric ordering. Missing columns / missing stats degrade
+gracefully to 'PMaybeKeep'.
+-}
+evalRowGroup
+  :: P.FileMetadata
+  -- ^ File schema including logical annotations; nested columns use dotted paths.
+  -> Predicate
+  -> P.RowGroup
+  -> Decision
+evalRowGroup metadata p rg = evalPredicate lookupStats p
+  where
+    leaves = V.filter (maybe False (const True) . P.seType) (P.fmSchema metadata)
+    lookupStats name = do
+      let matches =
+            V.findIndices
+              ( \column -> case P.ccMetadata column of
+                  Just columnMetadata ->
+                    P.cmPathInSchema columnMetadata == V.singleton name
+                      || name == T.intercalate "." (V.toList (P.cmPathInSchema columnMetadata))
+                  _ -> False
+              )
+              (P.rgColumns rg)
+      index <-
+        if V.length leaves == V.length (P.rgColumns rg) && V.length matches == 1
+          then Just (V.head matches)
+          else Nothing
+      context <- statisticsContext metadata index
+      let field = statisticsField context
+      column <- P.rgColumns rg V.!? index
+      columnMetadata <- P.ccMetadata column
+      statistics <- P.cmStatistics columnMetadata
+      if P.seType field == Just (P.cmType columnMetadata)
+        then Just (context, statistics)
+        else Nothing
+
+
+{- | Decide whether one column chunk can be skipped, given the
+predicate fragment that applies to its column. Useful when
+the caller has already projected the predicate per column.
+-}
+evalColumnChunk
+  :: StatisticsContext
+  -> P.ColumnChunk
+  -> PColPredicate
+  -> Decision
+evalColumnChunk context cc cp = case P.ccMetadata cc of
+  Nothing -> PMaybeKeep
+  Just md -> case P.cmStatistics md of
+    Nothing -> PMaybeKeep
+    Just stats | P.seType (statisticsField context) == Just (P.cmType md) -> evalLeaf context stats cp
+    _ -> PMaybeKeep
+
+
+evalPredicate
+  :: (Text -> Maybe (StatisticsContext, P.Statistics))
+  -> Predicate
+  -> Decision
+evalPredicate _ PTrue = PMaybeKeep
+evalPredicate _ PFalse = PSkip
+evalPredicate look (PCol name cp) = case look name of
+  Nothing -> PMaybeKeep
+  Just (ty, stats) -> evalLeaf ty stats cp
+evalPredicate look (PAnd a b) =
+  combineDecisions (evalPredicate look a) (evalPredicate look b)
+evalPredicate look (POr a b) =
+  -- For OR we can only skip if /both/ disjuncts skip. The
+  -- conservative answer otherwise is 'PMaybeKeep'.
+  case (evalPredicate look a, evalPredicate look b) of
+    (PSkip, PSkip) -> PSkip
+    _ -> PMaybeKeep
+evalPredicate look (PNot inner) = case evalPredicate look inner of
+  -- Negation can't be pushed in general (a 'PSkip' on the
+  -- inner predicate doesn't imply skipping for the negation).
+  -- The conservative answer is always 'PMaybeKeep'.
+  _ -> case inner of
+    PFalse -> PMaybeKeep
+    _ -> PMaybeKeep
+
+
+-- ============================================================
+-- Leaf predicates
+-- ============================================================
+
+{- | Evaluate one column-leaf predicate against the column
+chunk's 'Statistics'. The 'ParquetType' tells us how to
+decode the bytes inside @statMinValue@ / @statMaxValue@.
+-}
+evalLeaf :: StatisticsContext -> P.Statistics -> PColPredicate -> Decision
+evalLeaf _ stats PIsNull
+  -- IS NULL is skippable iff null_count is known to be zero.
+  | P.statNullCount stats == Just 0 = PSkip
+  | otherwise = PMaybeKeep
+evalLeaf _ stats PIsNotNull
+  -- IS NOT NULL is skippable iff every row is null. Without a
+  -- per-chunk row count we can't be sure; fall back to maybe.
+  | otherwise = case P.statNullCount stats of
+      Just _ -> PMaybeKeep -- conservative
+      Nothing -> PMaybeKeep
+evalLeaf field stats cp =
+  case (minimumStatistic field stats, maximumStatistic field stats) of
+    (Just mn, Just mx) -> evalRange mn mx cp
+    _ -> PMaybeKeep
+
+
+minimumStatistic :: StatisticsContext -> P.Statistics -> Maybe PValue
+minimumStatistic field stats = statisticValue field (P.statMinValue stats) (P.statMin stats)
+
+
+maximumStatistic :: StatisticsContext -> P.Statistics -> Maybe PValue
+maximumStatistic field stats = statisticValue field (P.statMaxValue stats) (P.statMax stats)
+
+
+statisticValue :: StatisticsContext -> Maybe ByteString -> Maybe ByteString -> Maybe PValue
+statisticValue context current legacy =
+  ( case current of
+      Just value | modernOrderSupported context -> Just value
+      _ | legacyOrderMatches -> legacy
+      _ -> Nothing
+  )
+    >>= decodePValueForSchema field
+  where
+    field = statisticsField context
+    legacyOrderMatches =
+      P.seType field `elem` (Just <$> [P.PTBoolean, P.PTInt32, P.PTInt64, P.PTFloat, P.PTDouble]) && case P.seLogicalType field of
+        Just (P.LTInteger _ False) -> False
+        Just P.LTDecimal {} -> P.seType field `elem` [Just P.PTInt32, Just P.PTInt64]
+        _ -> P.seConvertedType field `notElem` (Just <$> [P.CTUInt8, P.CTUInt16, P.CTUInt32, P.CTUInt64, P.CTDecimal])
+
+
+-- ============================================================
+-- Min / max decoding
+-- ============================================================
+
+{- | Decode a min/max byte payload according to its
+'P.ParquetType'. Mirrors what the writer's
+@statisticsFor*@ helpers in "Parquet.Write" produced.
+-}
+decodePValueLE :: P.ParquetType -> ByteString -> Maybe PValue
+decodePValueLE ty bs = case ty of
+  P.PTBoolean ->
+    case BS.uncons bs of
+      Just (b, rest) | BS.null rest && b <= 1 -> Just (PVBool (b /= 0))
+      Just _ -> Nothing
+      Nothing -> Nothing
+  P.PTInt32
+    | BS.length bs == 4 ->
+        Just (PVInt32 (fromIntegral (readLE32 bs 0)))
+  P.PTInt64
+    | BS.length bs == 8 ->
+        Just (PVInt64 (fromIntegral (readLE64 bs 0)))
+  P.PTFloat
+    | BS.length bs == 4 ->
+        let value = castWord32ToFloat (readLE32 bs 0)
+        in if isNaN value then Nothing else Just (PVFloat value)
+  P.PTDouble
+    | BS.length bs == 8 ->
+        let value = castWord64ToDouble (readLE64 bs 0)
+        in if isNaN value then Nothing else Just (PVDouble value)
+  P.PTByteArray ->
+    -- Stats store the bytes without the PLAIN length prefix
+    -- (per spec). Treat them as opaque binary; consumers can
+    -- coerce to text if they know the column is UTF-8.
+    Just (PVBinary bs)
+  P.PTFixedLenByteArray ->
+    Just (PVBinary bs)
+  _ -> Nothing
+
+
+{- | Decode statistics using the logical annotation as well as its carrier.
+Exact decimal scalars cover the Arrow decimal256 precision range (76 digits).
+-}
+decodePValueForSchema :: P.SchemaElement -> ByteString -> Maybe PValue
+decodePValueForSchema field bytes
+  | not (P.hasDefinedStatisticsOrder field) = Nothing
+  | otherwise = case P.seLogicalType field of
+      Just P.LTFloat16
+        | BS.length bytes == 2 ->
+            let bits = fromIntegral (BS.index bytes 0) .|. (fromIntegral (BS.index bytes 1) `shiftL` 8)
+                value = AC.float16ToDouble (AC.Float16 bits)
+            in if isNaN value then Nothing else Just (PVDouble value)
+      Just P.LTFloat16 -> Nothing
+      Just P.LTTimestamp {} | P.seType field /= Just P.PTInt64 -> Nothing
+      Just (P.LTDecimal precision scale)
+        | precision > 0 && precision <= 76 && scale >= 0 && scale <= precision -> do
+            value <- case P.seType field of
+              Just P.PTInt32 | BS.length bytes == 4 -> Just (fromIntegral (fromIntegral (readLE32 bytes 0) :: Int32))
+              Just P.PTInt64 | BS.length bytes == 8 -> Just (fromIntegral (fromIntegral (readLE64 bytes 0) :: Int64))
+              Just P.PTByteArray -> decodeDecimalInteger bytes
+              Just P.PTFixedLenByteArray -> decodeDecimalInteger bytes
+              _ -> Nothing
+            Just (PVDecimal (fromInteger value / fromInteger (10 ^ scale)))
+        | otherwise -> Nothing
+      _
+        | unsigned -> case P.seType field of
+            Just P.PTInt32 | BS.length bytes == 4 -> Just (PVUnsigned (fromIntegral (readLE32 bytes 0)))
+            Just P.PTInt64 | BS.length bytes == 8 -> Just (PVUnsigned (readLE64 bytes 0))
+            _ -> Nothing
+        | text -> either (const Nothing) (Just . PVText) (TE.decodeUtf8' bytes)
+        | otherwise -> P.seType field >>= (`decodePValueLE` bytes)
+  where
+    unsigned = case P.seLogicalType field of
+      Just (P.LTInteger _ signed) -> not signed
+      _ -> P.seConvertedType field `elem` (Just <$> [P.CTUInt8, P.CTUInt16, P.CTUInt32, P.CTUInt64])
+    text =
+      P.seType field == Just P.PTByteArray
+        && ( P.seLogicalType field `elem` [Just P.LTString, Just P.LTEnum, Just P.LTJson]
+               || P.seConvertedType field `elem` [Just P.CTUtf8, Just P.CTEnum, Just P.CTJson]
+           )
+
+
+readLE32 :: ByteString -> Int -> Word32
+readLE32 bs o =
+  let b0 = fromIntegral (BS.index bs o) :: Word32
+      b1 = fromIntegral (BS.index bs (o + 1)) :: Word32
+      b2 = fromIntegral (BS.index bs (o + 2)) :: Word32
+      b3 = fromIntegral (BS.index bs (o + 3)) :: Word32
+  in b0 .|. (b1 `shiftL` 8) .|. (b2 `shiftL` 16) .|. (b3 `shiftL` 24)
+
+
+readLE64 :: ByteString -> Int -> Word64
+readLE64 bs o =
+  let lo = fromIntegral (readLE32 bs o) :: Word64
+      hi = fromIntegral (readLE32 bs (o + 4)) :: Word64
+  in lo .|. (hi `shiftL` 32)
+
+
+-- ============================================================
+-- Page-index-based skipping
+-- ============================================================
+
+{- | Per-page skip decisions for one column chunk, derived from
+the chunk's 'P.ColumnIndex'. The result vector is parallel
+to @ciNullPages@ / @ciMinValues@ / @ciMaxValues@: an entry
+of 'PSkip' means the corresponding 'P.PageLocation' (in the
+chunk's matching 'P.OffsetIndex') can be skipped without
+decoding.
+
+Pages whose @null_pages@ slot is 'True' (the page contains
+only nulls) are skipped for /any/ value-style predicate
+('PEq', 'PLt', …); 'PIsNull' keeps them.
+-}
+evalPagesByColumnIndex
+  :: StatisticsContext
+  -> P.ColumnIndex
+  -> PColPredicate
+  -> V.Vector Decision
+evalPagesByColumnIndex context ci cp =
+  let !nulls = P.ciNullPages ci
+      !mins = P.ciMinValues ci
+      !maxs = P.ciMaxValues ci
+      !n = V.length nulls
+  in if V.length mins /= n || V.length maxs /= n
+       then V.replicate n PMaybeKeep
+       else V.generate n $ \i ->
+         let !isNull = V.unsafeIndex nulls i
+         in if isNull
+              then case cp of
+                PIsNull -> PMaybeKeep
+                PIsNotNull -> PSkip
+                _ -> PSkip
+              else case ( decodeBound (V.unsafeIndex mins i)
+                        , decodeBound (V.unsafeIndex maxs i)
+                        ) of
+                (Just mn, Just mx) -> evalRange mn mx cp
+                _ -> PMaybeKeep
+  where
+    decodeBound bytes
+      | modernOrderSupported context = decodePValueForSchema (statisticsField context) bytes
+      | otherwise = Nothing
+
+
+-- ============================================================
+-- Bloom-filter membership
+-- ============================================================
+
+{- | Probe a column chunk's bloom filter for membership of the
+value(s) referenced by the predicate. Returns 'PSkip' when
+the bloom proves the column /cannot/ contain any matching
+value; 'PMaybeKeep' otherwise.
+
+Only @PEq@ and @PIn@ are bloom-checkable; other predicates
+always degrade to 'PMaybeKeep' here (range / nullity have
+to use min/max stats instead).
+-}
+evalBloomChunk
+  :: P.SchemaElement
+  -> Bloom.Sbbf
+  -> PColPredicate
+  -> Decision
+evalBloomChunk field sbbf = \case
+  PEq v -> case bloomCheckVal field sbbf v of
+    True -> PMaybeKeep
+    False -> PSkip
+  PIn vs ->
+    -- Skip iff every candidate is rejected by the filter.
+    if all (not . bloomCheckVal field sbbf) vs
+      then PSkip
+      else PMaybeKeep
+  _ -> PMaybeKeep
+
+
+{- | Bloom-filter check for one PValue. Encodes the value into
+its PLAIN-form byte payload (matching what the writer
+inserts) and probes the filter.
+-}
+bloomCheckVal :: P.SchemaElement -> Bloom.Sbbf -> PValue -> Bool
+bloomCheckVal field sbbf value = case value of
+  PVFloat f | f == 0 -> check (PVFloat 0.0) || check (PVFloat (-0.0))
+  PVDouble d | d == 0 -> check (PVDouble 0.0) || check (PVDouble (-0.0))
+  _ -> check value
+  where
+    -- Unknown representations cannot prove absence. Variable-width decimal
+    -- bytes may have redundant sign extension, so one hash is insufficient.
+    check v = maybe True (\bytes -> Bloom.sbbfCheck bytes sbbf) (encodePlain field v)
+
+
+encodePlain :: P.SchemaElement -> PValue -> Maybe ByteString
+encodePlain field value
+  | not (P.hasCompatiblePhysicalType field) = Nothing
+  | Just P.LTDecimal {} <- P.seLogicalType field
+  , notDecimal value =
+      Nothing
+  | otherwise = case (P.seType field, value) of
+      (Just P.PTInt32, PVInt32 n) -> Just (word32LE (fromIntegral n))
+      (Just P.PTInt64, PVInt64 n) -> Just (word64LE (fromIntegral n))
+      (Just P.PTInt32, PVUnsigned n) | unsigned && n <= fromIntegral (maxBound :: Word32) -> Just (word32LE (fromIntegral n))
+      (Just P.PTInt64, PVUnsigned n) | unsigned -> Just (word64LE n)
+      (Just P.PTFloat, PVFloat f) -> Just (word32LE (castFloatToWord32 f))
+      (Just P.PTDouble, PVDouble d) -> Just (word64LE (castDoubleToWord64 d))
+      (Just P.PTBoolean, PVBool b) -> Just (BS.singleton (if b then 1 else 0))
+      (Just P.PTByteArray, PVText t) -> Just (TE.encodeUtf8 t)
+      (Just P.PTByteArray, PVBinary bytes) -> Just bytes
+      (Just P.PTFixedLenByteArray, PVBinary bytes) -> Just bytes
+      (_, PVDecimal decimal) -> case P.seLogicalType field of
+        Just (P.LTDecimal _ scale)
+          | scale >= 0 && scale <= 76 ->
+              let scaled = decimal * fromInteger (10 ^ scale)
+                  integer = numerator scaled
+              in if denominator scaled /= 1
+                   then Nothing
+                   else case P.seType field of
+                     Just P.PTInt32
+                       | integer >= fromIntegral (minBound :: Int32) && integer <= fromIntegral (maxBound :: Int32) ->
+                           Just (word32LE (fromIntegral integer))
+                     Just P.PTInt64
+                       | integer >= fromIntegral (minBound :: Int64) && integer <= fromIntegral (maxBound :: Int64) ->
+                           Just (word64LE (fromIntegral integer))
+                     _ -> Nothing
+        _ -> Nothing
+      _ -> Nothing
+  where
+    notDecimal PVDecimal {} = False
+    notDecimal _ = True
+    unsigned = case P.seLogicalType field of
+      Just (P.LTInteger _ signed) -> not signed
+      _ -> P.seConvertedType field `elem` (Just <$> [P.CTUInt8, P.CTUInt16, P.CTUInt32, P.CTUInt64])
+
+
+word32LE :: Word32 -> ByteString
+word32LE w =
+  BS.pack
+    [ fromIntegral w
+    , fromIntegral (w `quot` 0x100)
+    , fromIntegral (w `quot` 0x10000)
+    , fromIntegral (w `quot` 0x1000000)
+    ]
+
+
+word64LE :: Word64 -> ByteString
+word64LE w =
+  BS.pack
+    [ fromIntegral w
+    , fromIntegral (w `quot` 0x100)
+    , fromIntegral (w `quot` 0x10000)
+    , fromIntegral (w `quot` 0x1000000)
+    , fromIntegral (w `quot` 0x100000000)
+    , fromIntegral (w `quot` 0x10000000000)
+    , fromIntegral (w `quot` 0x1000000000000)
+    , fromIntegral (w `quot` 0x100000000000000)
+    ]
diff --git a/src/Parquet/RLE.hs b/src/Parquet/RLE.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/RLE.hs
@@ -0,0 +1,352 @@
+{-# LANGUAGE BangPatterns #-}
+
+{- | Parquet hybrid RLE / bit-packed decoding. Dictionary indices carry
+their bit width in one byte; V1 level streams carry a four-byte length.
+-}
+module Parquet.RLE (
+  decodeDictionaryIndices,
+  validateDictionaryExpansion,
+  validateDictionaryExpansionFor,
+  decodeHybridRleUnsigned32,
+  decodeHybridRleLengthPrefixed,
+  decodeHybridRleBoolean,
+) where
+
+import Columnar.SIMD (copyBits)
+import Control.Monad.ST (runST)
+import Data.Bits (shiftL, shiftR, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Internal qualified as BSI
+import Data.ByteString.Unsafe qualified as BSU
+import Data.Int (Int32, Int64)
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Primitive.Mutable qualified as MVP
+import Data.Vector.Storable qualified as VS
+import Data.Word (Word32, Word64, Word8)
+import Foreign.Marshal.Utils (fillBytes)
+import Foreign.Ptr (castPtr, plusPtr)
+import Foreign.Storable (Storable, peekByteOff, pokeByteOff)
+import System.IO.Unsafe (unsafePerformIO)
+
+
+decodeDictionaryIndices :: Int -> ByteString -> Either String (VP.Vector Int32)
+decodeDictionaryIndices count bytes
+  | count < 0 = Left "Parquet.RLE: negative value count"
+  | count == 0 = Right VP.empty
+  | BS.null bytes = Left "Parquet.RLE: empty dictionary index buffer"
+  | otherwise = decodeHybridRleUnsigned32 (fromIntegral (BS.head bytes)) count (BS.tail bytes)
+
+
+{- | Check a dictionary index prefix against a byte budget without allocating
+an index or output vector. Dictionary offsets must be nonnegative and
+monotonic; a nonzero base is allowed. Only the requested prefix is inspected,
+as with 'decodeDictionaryIndices'. Zero-width indices implicitly reference
+entry zero. Repeated runs are checked in constant time, even for huge counts.
+-}
+validateDictionaryExpansion :: Int -> VS.Vector Int32 -> Int -> ByteString -> Either String ()
+validateDictionaryExpansion = validateDictionaryExpansionFor
+
+
+validateDictionaryExpansionFor :: (Integral o, Storable o) => Int -> VS.Vector o -> Int -> ByteString -> Either String ()
+validateDictionaryExpansionFor limit offsets count encoded
+  | limit < 0 = Left "Parquet.RLE: negative dictionary byte budget"
+  | count < 0 = Left "Parquet.RLE: negative value count"
+  | count == 0 = Right ()
+  | VS.length offsets < 2 = Left "Parquet.RLE: dictionary index out of range"
+  | VS.unsafeHead offsets < 0 = Left "Parquet.RLE: negative dictionary offset"
+  | BS.null encoded = Left "Parquet.RLE: empty dictionary index buffer"
+  | width > 32 = Left "Parquet.RLE: bit width out of range"
+  | otherwise = do
+      checkOffsets 1 (VS.unsafeHead offsets)
+      if width == 0
+        then withSize 0 (0 :: Word64) count (\_ -> Right ())
+        else loop 0 count 0
+  where
+    width = fromIntegral (BSU.unsafeHead encoded)
+    bytes = BSU.unsafeTail encoded
+    dictionaryCount = VS.length offsets - 1
+    mask = ((1 :: Word64) `shiftL` width) - 1
+    checkOffsets !i !previous
+      | i == VS.length offsets = Right ()
+      | next < previous = Left "Parquet.RLE: dictionary offsets are not monotonic"
+      | otherwise = checkOffsets (i + 1) next
+      where
+        next = VS.unsafeIndex offsets i
+    withSize !total !key !emit continue
+      | key >= fromIntegral dictionaryCount = Left "Parquet.RLE: dictionary index out of range"
+      | size /= 0 && emit > (limit - total) `quot` size = Left "Parquet.RLE: dictionary expansion exceeds byte budget"
+      | otherwise = continue (total + emit * size)
+      where
+        index = fromIntegral key
+        size = fromIntegral (VS.unsafeIndex offsets (index + 1) - VS.unsafeIndex offsets index) :: Int
+    {-# INLINE withSize #-}
+    loop !offset !remaining !total
+      | remaining == 0 = Right ()
+      | otherwise = withHybridRun width bytes offset remaining Left packed repeated
+      where
+        packed start next emit = values 0 start 0 total
+          where
+            values !i !byteOffset !bitOffset !used
+              | i == emit = loop next (remaining - emit) used
+              | otherwise =
+                  let key = readBits bytes byteOffset bitOffset width .&. mask
+                      totalBits = bitOffset + width
+                  in withSize used key 1 $ \nextUsed ->
+                       values (i + 1) (byteOffset + totalBits `quot` 8) (totalBits `rem` 8) nextUsed
+        repeated start next emit =
+          let key = readBits bytes start 0 width .&. mask
+          in withSize total key emit (loop next (remaining - emit))
+{-# SPECIALIZE validateDictionaryExpansionFor :: Int -> VS.Vector Int32 -> Int -> ByteString -> Either String () #-}
+{-# SPECIALIZE validateDictionaryExpansionFor :: Int -> VS.Vector Int64 -> Int -> ByteString -> Either String () #-}
+
+
+decodeHybridRleLengthPrefixed :: Int -> Int -> ByteString -> Either String (VP.Vector Int32)
+decodeHybridRleLengthPrefixed width count bytes
+  | BS.length bytes < 4 = Left "Parquet.RLE: length-prefixed buffer shorter than 4 bytes"
+  | otherwise =
+      let size = fromIntegral (readLE32 bytes 0)
+      in if size > BS.length bytes - 4
+           then Left "Parquet.RLE: invalid length-prefixed hybrid size"
+           else decodeHybridRleUnsigned32 width count (BS.take size (BS.drop 4 bytes))
+
+
+{- | Decode exactly count values into one vector. Run state and byte/bit
+cursors are threaded directly; there are no per-value STRefs, temporary
+group vectors, or repeated vector concatenations.
+-}
+decodeHybridRleUnsigned32 :: Int -> Int -> ByteString -> Either String (VP.Vector Int32)
+decodeHybridRleUnsigned32 width count bytes
+  | count < 0 = Left "Parquet.RLE: negative value count"
+  | width < 0 || width > 32 = Left "Parquet.RLE: bit width out of range"
+  | count == 0 = Right VP.empty
+  | count > maxBound `quot` 4 = Left "Parquet.RLE: decoded vector exceeds addressable size"
+  | width == 0 = Right (VP.replicate count 0)
+  | BS.null bytes = Left "Parquet.RLE: empty hybrid stream"
+  | otherwise = withHybridRun width bytes 0 count Left (prepare True) (prepare False)
+  where
+    -- Check run structure before allocating from an untrusted value count.
+    -- Retain the first parsed run: single-run pages need no second header pass.
+    prepare packed offset next emit = do
+      validate next (count - emit)
+      decode packed offset next emit
+    decode firstPacked firstOffset firstNext firstCount = runST $ do
+      output <- MVP.unsafeNew count
+      let header !offset !written
+            | written == count = pure (Right ())
+            | otherwise =
+                withHybridRun
+                  width
+                  bytes
+                  offset
+                  (count - written)
+                  (pure . Left)
+                  (packed written)
+                  (repeated written)
+          packed !written !offset !next !emit =
+            let values !i !byteOffset !bitOffset
+                  | i == emit = header next (written + emit)
+                  | otherwise = do
+                      let value = readBits bytes byteOffset bitOffset width .&. mask
+                          totalBits = bitOffset + width
+                          advance = totalBits `quot` 8
+                          nextBit = totalBits `rem` 8
+                      MVP.unsafeWrite output (written + i) (fromIntegral value)
+                      values (i + 1) (byteOffset + advance) nextBit
+                -- Common level/dictionary widths divide a byte. Decode
+                -- that byte once and write all of its complete fields;
+                -- a partial last byte still uses the checked scalar tail.
+                bits1 !i !off
+                  | emit - i < 8 = values i off 0
+                  | otherwise = do
+                      let byte = BSU.unsafeIndex bytes off
+                          base = written + i
+                      MVP.unsafeWrite output base (fromIntegral (byte .&. 1))
+                      MVP.unsafeWrite output (base + 1) (fromIntegral ((byte `shiftR` 1) .&. 1))
+                      MVP.unsafeWrite output (base + 2) (fromIntegral ((byte `shiftR` 2) .&. 1))
+                      MVP.unsafeWrite output (base + 3) (fromIntegral ((byte `shiftR` 3) .&. 1))
+                      MVP.unsafeWrite output (base + 4) (fromIntegral ((byte `shiftR` 4) .&. 1))
+                      MVP.unsafeWrite output (base + 5) (fromIntegral ((byte `shiftR` 5) .&. 1))
+                      MVP.unsafeWrite output (base + 6) (fromIntegral ((byte `shiftR` 6) .&. 1))
+                      MVP.unsafeWrite output (base + 7) (fromIntegral (byte `shiftR` 7))
+                      bits1 (i + 8) (off + 1)
+                bits2 !i !off
+                  | emit - i < 4 = values i off 0
+                  | otherwise = do
+                      let byte = BSU.unsafeIndex bytes off
+                          base = written + i
+                      MVP.unsafeWrite output base (fromIntegral (byte .&. 3))
+                      MVP.unsafeWrite output (base + 1) (fromIntegral ((byte `shiftR` 2) .&. 3))
+                      MVP.unsafeWrite output (base + 2) (fromIntegral ((byte `shiftR` 4) .&. 3))
+                      MVP.unsafeWrite output (base + 3) (fromIntegral (byte `shiftR` 6))
+                      bits2 (i + 4) (off + 1)
+                bits4 !i !off
+                  | emit - i < 2 = values i off 0
+                  | otherwise = do
+                      let byte = BSU.unsafeIndex bytes off
+                          base = written + i
+                      MVP.unsafeWrite output base (fromIntegral (byte .&. 15))
+                      MVP.unsafeWrite output (base + 1) (fromIntegral (byte `shiftR` 4))
+                      bits4 (i + 2) (off + 1)
+                bits8 !i !off
+                  | i == emit = header next (written + emit)
+                  | otherwise = do
+                      MVP.unsafeWrite output (written + i) (fromIntegral (BSU.unsafeIndex bytes off))
+                      bits8 (i + 1) (off + 1)
+            in case width of
+                 1 -> bits1 0 offset
+                 2 -> bits2 0 offset
+                 4 -> bits4 0 offset
+                 8 -> bits8 0 offset
+                 _ -> values 0 offset 0
+          repeated !written !offset !next !emit =
+            let value = fromIntegral (readBits bytes offset 0 width .&. mask) :: Int32
+            in do
+                 MVP.set (MVP.unsafeSlice written emit output) value
+                 header next (written + emit)
+      result <-
+        if firstPacked
+          then packed 0 firstOffset firstNext firstCount
+          else repeated 0 firstOffset firstNext firstCount
+      case result of
+        Left err -> pure (Left err)
+        Right () -> Right <$> VP.unsafeFreeze output
+    mask = ((1 :: Word64) `shiftL` width) - 1
+    validate !offset !remaining
+      | remaining == 0 = Right ()
+      | otherwise = withHybridRun width bytes offset remaining Left advance advance
+      where
+        advance _ next emit = validate next (remaining - emit)
+
+
+-- Both preflight and decoding use the same structural checks. Continuations
+-- receive the payload offset, next header offset and clipped output count.
+-- Inlining keeps the header cursor/count unboxed without allocating run nodes.
+withHybridRun
+  :: Int
+  -> ByteString
+  -> Int
+  -> Int
+  -> (String -> r)
+  -> (Int -> Int -> Int -> r)
+  -> (Int -> Int -> Int -> r)
+  -> r
+withHybridRun width bytes start remaining invalid packed repeated = varint start 0 0
+  where
+    size = BS.length bytes
+    paddedBytes = (width + 7) `quot` 8
+    varint !offset !acc !shift
+      | offset == size = invalid "Parquet.RLE: truncated hybrid stream"
+      | otherwise =
+          let byte = BSU.unsafeIndex bytes offset
+              value = acc .|. (fromIntegral (byte .&. 0x7f) `shiftL` shift) :: Word64
+          in if shift == 63 && byte > 1
+               then invalid "Parquet.RLE: run header overflows 64 bits"
+               else
+                 if byte .&. 0x80 /= 0
+                   then varint (offset + 1) value (shift + 7)
+                   else run (offset + 1) value
+    run !offset !value
+      | value .&. 1 /= 0 =
+          -- The specification caps values per run at 2^31 - 1;
+          -- a packed header counts groups of eight, not values.
+          let groups = value `shiftR` 1
+          in if groups == 0
+               then invalid "Parquet.RLE: zero-length bit-packed run"
+               else
+                 if groups > 0x0fffffff
+                   then invalid "Parquet.RLE: bit-packed run exceeds signed 32-bit length"
+                   else
+                     if groups > fromIntegral ((size - offset) `quot` width)
+                       then invalid "Parquet.RLE: truncated bit-packed run"
+                       else
+                         let next = offset + fromIntegral groups * width
+                             emit =
+                               if groups > fromIntegral (remaining `quot` 8)
+                                 then remaining
+                                 else fromIntegral groups * 8
+                         in packed offset next emit
+      | otherwise =
+          let count = value `shiftR` 1
+          in if count == 0
+               then invalid "Parquet.RLE: invalid RLE run length"
+               else
+                 if count > 0x7fffffff
+                   then invalid "Parquet.RLE: RLE run exceeds signed 32-bit length"
+                   else
+                     if paddedBytes > size - offset
+                       then invalid "Parquet.RLE: truncated padded value"
+                       else
+                         repeated
+                           offset
+                           (offset + paddedBytes)
+                           (if count > fromIntegral remaining then remaining else fromIntegral count)
+{-# INLINE withHybridRun #-}
+
+
+-- A 32-bit value may touch five bytes when its starting bit is unaligned.
+-- The complete packed run has already been bounds-checked by the caller.
+readBits :: ByteString -> Int -> Int -> Int -> Word64
+readBits bytes offset bit width = go 0 0 `shiftR` bit
+  where
+    needed = (bit + width + 7) `quot` 8
+    go !i !acc
+      | i == needed = acc
+      | otherwise =
+          go
+            (i + 1)
+            (acc .|. (fromIntegral (BSU.unsafeIndex bytes (offset + i)) `shiftL` (i * 8)))
+{-# INLINE readBits #-}
+
+
+readLE32 :: ByteString -> Int -> Word32
+readLE32 bytes offset = fromIntegral (readBits bytes offset 0 32)
+{-# INLINE readLE32 #-}
+
+
+-- BOOLEAN RLE retains the hybrid stream's LSB-first layout. Validate every
+-- requested run before allocation, then copy packed spans or set repeated
+-- one bits directly; neither a Word32 nor a boxed Bool is built per value.
+decodeHybridRleBoolean :: Int -> ByteString -> Either String ByteString
+decodeHybridRleBoolean count framed
+  | count < 0 = Left "Parquet.RLE: negative value count"
+  | BS.length framed < 4 = Left "Parquet.RLE: length-prefixed buffer shorter than 4 bytes"
+  | encodedSize > BS.length framed - 4 = Left "Parquet.RLE: invalid length-prefixed hybrid size"
+  | count == 0 = Right BS.empty
+  | otherwise = withHybridRun 1 bytes 0 count Left (prepare True) (prepare False)
+  where
+    encodedSize = fromIntegral (readLE32 framed 0)
+    bytes = BS.take encodedSize (BS.drop 4 framed)
+    outputSize = let (!whole, !tailBits) = count `quotRem` 8 in whole + if tailBits == 0 then 0 else 1
+    prepare packed offset next emit = do
+      validate next (count - emit)
+      Right $! unsafePerformIO $ BSI.create outputSize $ \target -> do
+        fillBytes target 0 outputSize
+        let header !written !position
+              | written == count = pure ()
+              | otherwise = withHybridRun 1 bytes position (count - written) (error . ("validated BOOLEAN run changed: " ++)) (copyPacked written) (copyRepeated written)
+            copyPacked !written !start !after !size = do
+              BSU.unsafeUseAsCString bytes $ \source -> copyBits target written (castPtr source `plusPtr` start) 0 size
+              header (written + size) after
+            copyRepeated !written !start !after !size = do
+              if BSU.unsafeIndex bytes start .&. 1 == 0 then pure () else setOnes target written size
+              header (written + size) after
+        if packed then copyPacked 0 offset next emit else copyRepeated 0 offset next emit
+    validate !offset !remaining
+      | remaining == 0 = Right ()
+      | otherwise = withHybridRun 1 bytes offset remaining Left (\_ next emit -> validate next (remaining - emit)) (\_ next emit -> validate next (remaining - emit))
+    setOnes target !start !size = do
+      let (!firstByte, !firstBit) = start `quotRem` 8
+          firstCount = min size (8 - firstBit)
+          mask n = fromIntegral (((1 :: Word32) `shiftL` n) - 1) :: Word8
+          remaining = size - firstCount
+          (!whole, !tailCount) = remaining `quotRem` 8
+      old <- peekByteOff target firstByte :: IO Word8
+      pokeByteOff target firstByte (old .|. (mask firstCount `shiftL` firstBit))
+      if whole == 0 then pure () else fillBytes (target `plusPtr` (firstByte + 1)) 255 whole
+      if tailCount == 0
+        then pure ()
+        else do
+          lastByte <- peekByteOff target (firstByte + 1 + whole) :: IO Word8
+          pokeByteOff target (firstByte + 1 + whole) (lastByte .|. mask tailCount)
+{-# NOINLINE decodeHybridRleBoolean #-}
diff --git a/src/Parquet/Read.hs b/src/Parquet/Read.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Read.hs
@@ -0,0 +1,3377 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+{-# LANGUAGE CPP #-}
+{-# LANGUAGE ForeignFunctionInterface #-}
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE PatternSynonyms #-}
+-- | Read Parquet column data into primitive vectors.
+--
+-- Supports @DATA_PAGE@ sequences with @PLAIN@ physical encoding for common
+-- types, optional @DICTIONARY_PAGE@ + @PLAIN_DICTIONARY@ (hybrid RLE @INT32@
+-- indices per Parquet spec),
+-- and @Uncompressed@ / @GZip@ / (with @-fsnappy@) @Snappy@ / (with @-fzstd@) @ZSTD@ compression.
+--
+-- * @readPlain*@*ColumnChunk@ for primitives without nested nullability assumes the
+--   column is @REQUIRED@ (no level data on disk).
+-- * @readPlain*Optional*@ helpers decode data page v1 with definition\/repetition
+--   levels ('Parquet.Levels'); use 'Parquet.Levels.maxLevelsForColumnPath' with
+--   footer schema + column path. Available for @INT32@, @INT64@, @FLOAT@,
+--   @DOUBLE@, @BOOL@, and @BYTE_ARRAY@.
+--
+-- For metadata and footer I/O use "Parquet.Footer".
+module Parquet.Read
+  ( ParquetFile (..)
+  , loadParquetFile
+  , loadParquetFileEncrypted
+  , loadParquetFileWithDecryption
+  , loadParquetFilePath
+  , openParquetReader
+  , FooterDecryption (..)
+  , columnChunkSlice
+  , rawColumnChunkSlice
+  , decryptFileColumnModule
+  , isColumnEncrypted
+  , encryptedColumnKeyMetadata
+  , PreparedSelection (..)
+  , prepareColumnSelection
+  , readPlainInt32FirstPage
+  , readPlainInt32ColumnChunk
+  , readPlainInt64ColumnChunk
+  , readPlainFloatColumnChunk
+  , readPlainDoubleColumnChunk
+  , readPlainBoolColumnChunk
+  , readPlainByteArrayColumnChunk
+  , readPlainInt96ColumnChunk
+  , readPlainFixedLenByteArrayColumnChunk
+  , readPlainDictionaryInt32ColumnChunk
+  , readDictionaryOptionalColumnChunk
+  , readDictionaryInt32OptionalColumnChunk
+  , decompressDataPageBody
+  , decompressDataPageV2Body
+  , decompressChunk
+  , decodePlainInt32
+  , decodePlainInt64
+  , decodePlainFloat
+  , decodePlainDouble
+  , decodePlainBool
+  , decodePlainByteArray
+  , BinaryBuffers
+  , LargeBinaryBuffers
+  , decodePlainLargeBinaryBuffers
+  , readLargeBinaryBuffersColumnChunk
+  , readLargeBinaryBuffersLevels
+  , readLargeBinaryBuffersSelectedValues
+  , readLargeBinaryBuffersSelectedLevels
+  , binaryOffsets
+  , binaryData
+  , decodePlainBinaryBuffers
+  , readBinaryBuffersColumnChunk
+  , readBinaryBuffersLevels
+  , readBinaryBuffersSelectedValues
+  , readBinaryBuffersSelectedLevels
+  , BoolBuffers
+  , boolCount
+  , boolData
+  , readBoolBuffersColumnChunk
+  , readBoolBuffersLevels
+  , readBoolBuffersSelectedValues
+  , readBoolBuffersSelectedLevels
+  , ScalarBuffers
+  , scalarData
+  , readScalarBuffersColumnChunk
+  , readScalarBuffersLevels
+  , readScalarBuffersSelectedValues
+  , readScalarBuffersSelectedLevels
+  , decodePlainInt96
+  , decodePlainFixedLenByteArray
+  , decodeByteStreamSplitFloat
+  , decodeByteStreamSplitDouble
+  , decodeAlpFloat
+  , decodeAlpDouble
+  , decodeDictionaryIndices
+  , validateDictionaryExpansion
+  , decodeHybridRleLengthPrefixed
+  , decodeHybridRleUnsigned32
+  , readPlainInt32OptionalFirstPage
+  , readPlainInt32OptionalColumnChunk
+  , readPlainInt64OptionalFirstPage
+  , readPlainInt64OptionalColumnChunk
+  , readPlainFloatOptionalFirstPage
+  , readPlainFloatOptionalColumnChunk
+  , readPlainDoubleOptionalFirstPage
+  , readPlainDoubleOptionalColumnChunk
+  , readPlainBoolOptionalFirstPage
+  , readPlainBoolOptionalColumnChunk
+  , readPlainByteArrayOptionalFirstPage
+  , readPlainByteArrayOptionalColumnChunk
+  , decodeDeltaBinaryPackedInt32
+  , decodeDeltaBinaryPackedInt64
+  , encRleDictionary
+    -- * Generic per-page dispatch
+    --
+    -- | The 'readGeneric*ColumnChunk' family handles every encoding the
+    -- spec defines for the matching physical type, dispatching on
+    -- 'phType' (DATA_PAGE / DATA_PAGE_V2 / DICTIONARY_PAGE) and the
+    -- per-page encoding tag. Use these in preference to the
+    -- @readPlain*@ helpers when reading files produced by other
+    -- writers — wireform's own writer emits PLAIN, but pyarrow /
+    -- parquet-cpp / arrow-rs routinely produce dictionary-encoded
+    -- BYTE_ARRAY columns + DELTA_BINARY_PACKED INT32/INT64 +
+    -- BYTE_STREAM_SPLIT FLOAT/DOUBLE + DATA_PAGE_V2 pages, all of
+    -- which the @readPlain*@ helpers reject.
+  , readGenericInt32ColumnChunk
+  , readGenericInt64ColumnChunk
+  , readGenericFloatColumnChunk
+  , readGenericDoubleColumnChunk
+  , readGenericBoolColumnChunk
+  , readGenericByteArrayColumnChunk
+  , readGenericFixedLenByteArrayColumnChunk
+    -- ** Optional / nullable variants
+  , readGenericInt32OptionalColumnChunk
+  , readGenericInt64OptionalColumnChunk
+  , readGenericFloatOptionalColumnChunk
+  , readGenericDoubleOptionalColumnChunk
+  , readGenericBoolOptionalColumnChunk
+  , readGenericByteArrayOptionalColumnChunk
+  , readGenericFixedLenByteArrayOptionalColumnChunk
+    -- * Repeated readers (rep > 0 columns: lists, maps)
+  , ColumnLevels (..)
+  , readInt32Levels
+  , readInt64Levels
+  , readFloatLevels
+  , readDoubleLevels
+  , readBoolLevels
+  , readByteArrayLevels
+  , readFixedLevels
+  , PageSelection (..)
+  , readInt32SelectedLevels
+  , readInt64SelectedLevels
+  , readFloatSelectedLevels
+  , readDoubleSelectedLevels
+  , readBoolSelectedLevels
+  , readByteArraySelectedLevels
+  , readFixedSelectedLevels
+  , readInt32SelectedValues
+  , readInt64SelectedValues
+  , readFloatSelectedValues
+  , readDoubleSelectedValues
+  , readBoolSelectedValues
+  , readByteArraySelectedValues
+  , readFixedSelectedValues
+  , readGenericByteArrayRepeatedColumnChunk
+  , readGenericByteArrayRepeatedColumnChunkWith
+  , readGenericInt32RepeatedColumnChunk
+  , readGenericInt64RepeatedColumnChunk
+  , readGenericRepeatedColumnChunkWith
+    -- * Page-index-driven page skipping
+  , readGenericInt32SelectedPages
+  , readGenericInt64SelectedPages
+  , readGenericFloatSelectedPages
+  , readGenericDoubleSelectedPages
+  , readGenericBoolSelectedPages
+  , readGenericByteArraySelectedPages
+    -- ** Optional / nullable variants
+  , readGenericInt32OptionalSelectedPages
+  , readGenericInt64OptionalSelectedPages
+  , readGenericFloatOptionalSelectedPages
+  , readGenericDoubleOptionalSelectedPages
+  , readGenericBoolOptionalSelectedPages
+  , readGenericByteArrayOptionalSelectedPages
+  ) where
+
+#include "MachDeps.h"
+
+import Control.Exception (SomeException, evaluate, try)
+import Control.Monad.ST (runST)
+import Data.Bits (shiftL, shiftR, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import qualified Data.ByteString as BS
+import qualified Data.ByteString.Internal as BSI
+import qualified Data.ByteString.Unsafe as BSUnsafe
+import qualified Data.ByteString.Lazy as BL
+import Data.Int (Int32, Int64)
+import Data.Primitive.ByteArray (MutableByteArray, copyByteArrayToAddr, mutableByteArrayContents, newPinnedByteArray)
+import Data.Primitive.Types (Prim)
+
+#if !defined(WORDS_BIGENDIAN)
+import Data.Primitive.ByteArray (copyPtrToMutableByteArray)
+#endif
+import Foreign.ForeignPtr (withForeignPtr)
+import Foreign.Marshal.Utils (copyBytes, fillBytes)
+import Foreign.Ptr (Ptr, castPtr, plusPtr, ptrToWordPtr)
+import Foreign.Storable (Storable, sizeOf, peekByteOff, pokeByteOff)
+import qualified Data.Vector as V
+import qualified Data.Vector.Mutable as VM
+import qualified Data.Vector.Primitive as VP
+import qualified Data.Vector.Primitive.Mutable as MVP
+import qualified Data.Vector.Storable as VS
+import qualified Data.Vector.Storable.Mutable as VSM
+import Data.Word (Word8, Word32, Word64)
+import GHC.ByteOrder (ByteOrder (LittleEndian), targetByteOrder)
+import GHC.Float (castWord32ToFloat, castWord64ToDouble)
+import GHC.ForeignPtr (mallocPlainForeignPtrAlignedBytes)
+import GHC.Exts (RealWorld)
+import Wireform.Encode.Direct qualified as Direct
+import System.IO.Unsafe (unsafePerformIO)
+
+import Columnar.LZO qualified as LZO
+import Columnar.SIMD (copyBits, unpackBitsLsbUnsafe)
+import qualified Columnar.SIMD as SIMD
+
+import Parquet.Alp (decodeAlpFloat, decodeAlpDouble)
+import Parquet.Delta
+  ( decodeDeltaBinaryPackedInt32
+  , decodeDeltaBinaryPackedInt64
+  , decodeDeltaByteArray
+  , decodeDeltaLengthByteArray
+  )
+import Parquet.RLE (decodeDictionaryIndices, decodeHybridRleBoolean, decodeHybridRleLengthPrefixed, decodeHybridRleUnsigned32, validateDictionaryExpansion, validateDictionaryExpansionFor)
+
+import qualified Parquet.GZip as GZip
+#ifdef HAVE_ZSTD
+import qualified Codec.Compression.Zstd.Base as ZstdBase
+import qualified Codec.Compression.Zstd.Lazy as ZstdLazy
+#endif
+#ifdef HAVE_SNAPPY
+import qualified Codec.Compression.Snappy as Snappy
+#endif
+#ifdef HAVE_LZ4
+import qualified Columnar.LZ4 as LZ4
+#endif
+#ifdef HAVE_BROTLI
+import qualified Parquet.Brotli as Brotli
+#endif
+
+import qualified Columnar.IO as IO
+import qualified Columnar.Stream as IS
+import qualified Parquet.Encryption as Enc
+import qualified Parquet.Decryption as Decryption
+import qualified Parquet.Page as Page
+import Parquet.Thrift.Schema (pattern PageHeader_CompressedSize, pattern PageHeader_Crc)
+import qualified Thrift.Decode as TC
+import Thrift.Encode (encodeCompact)
+import qualified Thrift.Value as TV
+import Parquet.Footer (readFooter)
+import qualified Parquet.Footer as F
+import Parquet.Levels
+  ( levelBitWidth
+  , materializePlainBoolOptional
+  , materializePlainByteArrayOptional
+  , materializePlainDoubleOptional
+  , materializePlainFloatOptional
+  , materializePlainInt32Optional
+  , materializePlainInt64Optional
+  , parseDataPageV1Levels
+  , parseDataPageV1LevelsWithEncoding
+  )
+import Parquet.Page
+  ( DataPageHeader (..)
+  , DataPageHeaderV2 (..)
+  , DictionaryPageHeader (..)
+  , PageHeader (..)
+  , PageType (..)
+  , readPageHeaderCheckedAt
+  , PageDetails (..)
+  , readPageDetailsCheckedAt
+  , readPageDetailsAt
+  )
+#ifdef HAVE_SNAPPY
+import Foreign.C.Types (CInt (..))
+import Foreign.Marshal.Alloc (alloca)
+import Foreign.Storable (peek)
+#endif
+#if defined(HAVE_SNAPPY) || defined(HAVE_ZSTD)
+import Foreign.C.Types (CSize (..))
+#endif
+#ifdef HAVE_ZSTD
+import Foreign.C.Types (CULLong (..))
+#endif
+import Parquet.Types
+  ( ColumnChunk (..)
+  , ColumnMetadata (..)
+  , Compression (..)
+  , FileMetadata (..)
+  , PageLocation (..)
+  , ParquetType (..)
+  , RowGroup (..)
+  )
+
+-- | A Parquet file loaded in memory with parsed footer metadata.
+data ParquetFile = ParquetFile
+  { pfBytes  :: !ByteString
+  , pfFooter :: !FileMetadata
+  }
+  | DecryptedParquetFile
+  { pfBytes :: !ByteString
+  , pfFooter :: !FileMetadata
+  , pfDecryptionState :: !Decryption.DecryptionState
+  }
+  deriving stock (Show, Eq)
+
+-- | Parse the footer from the tail of a complete @PAR1@ file.
+-- Refuses encrypted-footer files with a clear error pointing to
+-- 'loadParquetFileEncrypted'.
+loadParquetFile :: ByteString -> Either String ParquetFile
+loadParquetFile bs = do
+  fm <- readFooter bs
+  Right ParquetFile {pfBytes = bs, pfFooter = fm}
+
+-- | Read a Parquet file from disk and parse its footer.
+--
+-- Uses 'Columnar.IO.loadFile' under the hood, which mmaps
+-- files above 'Columnar.IO.defaultLoadStrategy''s threshold
+-- (64 KiB) and reads smaller files eagerly. The 'ParquetFile'
+-- references the loaded bytes directly, so opening a 50 GB
+-- file costs roughly a syscall + page-fault-on-access cost
+-- rather than copying the whole file into the GC heap.
+--
+-- For an explicit choice, use 'Columnar.IO.loadFileMmap' /
+-- 'Columnar.IO.loadFileEager' and pass the bytes to
+-- 'loadParquetFile' directly.
+loadParquetFilePath :: FilePath -> IO (Either String ParquetFile)
+loadParquetFilePath path = do
+  bs <- IO.loadFile path
+  pure (loadParquetFile bs)
+
+-- | Open a Parquet file as an 'IS.IterIO' over its row groups.
+-- Each step yields one row-group index on demand; callers
+-- join with 'Parquet.Arrow.parquetRowGroupToArrow' (or any
+-- per-format reader) to materialise columns lazily.
+--
+-- Pairs with 'loadParquetFilePath''s mmap-aware loader: the
+-- file's bytes are mmapped (on files above the default
+-- threshold), so per-row-group slices are pointer arithmetic
+-- and only the touched pages are paged in by the kernel. A
+-- 50 GB file with one queried row group reads only the
+-- footer + the slice at that row group's offset.
+openParquetReader
+  :: FilePath
+  -> IO (Either String (ParquetFile, IS.IterIO Int))
+    -- ^ Returns the parsed footer + an iterator that yields
+    -- one row-group index at a time. Callers join the index
+    -- with the file's per-format readers (e.g.
+    -- 'Parquet.Arrow.parquetRowGroupToArrow') to materialise
+    -- columns lazily.
+openParquetReader path = do
+  loaded <- loadParquetFilePath path
+  case loaded of
+    Left e -> pure (Left e)
+    Right pf ->
+      let !nRg = V.length (fmRowGroups (pfFooter pf))
+          step ref
+            | ref >= nRg = pure (Right Nothing)
+            | otherwise  = pure (Right (Just ref))
+          mkIter k = IS.IterIO $ do
+            r <- step k
+            pure $ case r of
+              Left e -> Left e
+              Right Nothing -> Right IS.IterIODone
+              Right (Just i) -> Right (IS.IterIOYield i (mkIter (k + 1)))
+      in pure (Right (pf, mkIter 0))
+
+-- | Footer-decryption configuration. Mirrors
+-- 'Parquet.Write.FooterEncryption' but on the read side: the AAD
+-- prefix and file id must match what the writer used or GCM auth
+-- will reject the trailing module.
+data FooterDecryption = FooterDecryption
+  { fdKey       :: !ByteString
+  , fdFileId    :: !ByteString
+  , fdAadPrefix :: !ByteString
+  } deriving (Show, Eq)
+
+-- | Authenticate a @PARE@ encrypted footer or a @PAR1@ signed plaintext
+-- footer. The supplied file identifier and AAD prefix must agree with the
+-- file's crypto metadata. Ordinary unsigned @PAR1@ files remain accepted.
+-- The supplied key also decrypts columns encrypted with the footer key. For
+-- column-specific keys use 'loadParquetFileWithDecryption'. Use
+-- 'Enc.readFooterCryptoMetadata' to inspect opaque key metadata
+-- before resolving a key with an application's own KMS.
+loadParquetFileEncrypted :: FooterDecryption -> ByteString -> Either String ParquetFile
+loadParquetFileEncrypted fd bs = do
+  loadParquetFileWithDecryption Decryption.defaultDecryptionConfig
+    { Decryption.dcFooterKey = Just (fdKey fd)
+    , Decryption.dcAadPrefix = Just (fdAadPrefix fd)
+    , Decryption.dcExpectedFileId = Just (fdFileId fd)
+    } bs
+
+
+-- | Authenticate metadata and retain the context for decrypting requested
+-- columns. Column keys can be supplied explicitly by schema path or resolved
+-- by the application from opaque key metadata. Unrequested page bytes remain
+-- untouched, including when the file is memory mapped.
+loadParquetFileWithDecryption :: Decryption.DecryptionConfig -> ByteString -> Either String ParquetFile
+loadParquetFileWithDecryption config bytes = do
+  loaded <- Decryption.decryptFileMetadata config bytes
+  Right DecryptedParquetFile
+    { pfBytes = bytes
+    , pfFooter = Decryption.decryptedMetadata loaded
+    , pfDecryptionState = Decryption.decryptionState loaded
+    }
+
+
+fileColumnCrypto :: ParquetFile -> Int -> Int -> Maybe Decryption.ColumnCrypto
+fileColumnCrypto ParquetFile{} _ _ = Nothing
+fileColumnCrypto DecryptedParquetFile{pfDecryptionState = state} group column = Decryption.columnCrypto state group column
+
+
+isColumnEncrypted :: ParquetFile -> Int -> Int -> Bool
+isColumnEncrypted file group column = maybe False (const True) (fileColumnCrypto file group column)
+
+
+-- | Column-specific key routes from an authenticated footer. This allows an
+-- application to discover unresolved key IDs without parsing raw Thrift.
+encryptedColumnKeyMetadata :: ParquetFile -> V.Vector Decryption.ColumnKeyMetadata
+encryptedColumnKeyMetadata ParquetFile{} = V.empty
+encryptedColumnKeyMetadata DecryptedParquetFile{pfDecryptionState = state} = Decryption.columnKeyMetadata state
+
+
+-- | Authenticate an encrypted column auxiliary module, leaving plaintext
+-- columns unchanged. Index/bloom readers use the same column key and AAD.
+decryptFileColumnModule :: ParquetFile -> Int -> Int -> Enc.ModuleType -> ByteString -> Either String ByteString
+decryptFileColumnModule file group column kind bytes = case fileColumnCrypto file group column of
+  Nothing -> Right bytes
+  Just context -> Decryption.decryptColumnModule context kind bytes
+
+-- | Raw bytes for one column chunk.
+--
+-- A column chunk's wire layout is
+-- @[dictionary page (optional)][data page 1]...[data page N]@.
+-- When the column uses dictionary encoding 'cmDictionaryPageOffset'
+-- points at the dictionary page, which sits immediately before
+-- 'cmDataPageOffset'; the chunk's slice must start at the
+-- dictionary page so the page-walking decoder sees the dictionary
+-- before any RLE_DICTIONARY data page references it.
+--
+-- Per the Parquet spec the rule is: start at @min(dictionary_page_offset,
+-- data_page_offset)@ when both are present, else start at
+-- @data_page_offset@. 'cmTotalCompressedSize' covers both.
+columnChunkSlice :: ParquetFile -> Int -> Int -> Either String ByteString
+columnChunkSlice pf group column = do
+  bytes <- rawColumnChunkSlice pf group column
+  case fileColumnCrypto pf group column of
+    Nothing -> Right bytes
+    Just context -> do
+      metadata <- Decryption.cryptoColumnMetadata context
+      let dictionary = maybe False (> 0) (cmDictionaryPageOffset metadata)
+      decryptChunk context metadata dictionary bytes
+
+
+-- | Original on-disk bytes, before any page decryption. This is also the
+-- bounds-checking seam for offset indexes; validating an index must not read
+-- or decrypt the pages that a predicate will skip.
+rawColumnChunkSlice :: ParquetFile -> Int -> Int -> Either String ByteString
+rawColumnChunkSlice pf rgIdx colIdx = do
+  case fileColumnCrypto pf rgIdx colIdx of
+    Nothing -> Right ()
+    Just context -> Decryption.cryptoColumnMetadata context >> Right ()
+  let fm = pfFooter pf
+      rgs = fmRowGroups fm
+  whenOutOfRange rgIdx (V.length rgs) "row group"
+  let rg = V.unsafeIndex rgs rgIdx
+      cols = rgColumns rg
+  whenOutOfRange colIdx (V.length cols) "column"
+  let chunk = V.unsafeIndex cols colIdx
+  case ccFilePath chunk of
+    Just path | path /= mempty -> Left "Parquet.Read: external column-chunk files are not supported"
+    _ -> Right ()
+  meta <- case ccMetadata chunk of
+    Nothing -> Left "Parquet.Read: column chunk missing ColumnMetaData"
+    Just m -> Right m
+  let !dataOff = fromIntegral (cmDataPageOffset meta) :: Int
+      !startOff = case cmDictionaryPageOffset meta of
+        Just dpo
+          | dpo > 0 && fromIntegral dpo < dataOff ->
+              fromIntegral dpo :: Int
+        _ -> dataOff
+      !sz  = fromIntegral (cmTotalCompressedSize meta) :: Int
+      !bs0 = pfBytes pf
+  if cmNumValues meta == 0
+    then Right BS.empty
+    else if startOff < 0 || sz < 0 || startOff > BS.length bs0 || sz > BS.length bs0 - startOff
+    then Left "Parquet.Read: column chunk slice out of bounds"
+    else do
+      correctedSize <- case fileColumnCrypto pf rgIdx colIdx of
+        Just _ -> Right sz
+        Nothing -> legacyDictionaryChunkSize pf meta startOff sz
+      Right $! BS.take correctedSize (BS.drop startOff bs0)
+
+
+data DecryptedPage = DecryptedPage
+  { decryptedPageBytes :: !ByteString
+  , decryptedPageEnd :: {-# UNPACK #-} !Int
+  , decryptedPageValues :: {-# UNPACK #-} !Int64
+  , decryptedPageUsesDictionary :: !Bool
+  }
+
+
+decryptChunk :: Decryption.ColumnCrypto -> ColumnMetadata -> Bool -> ByteString -> Either String ByteString
+decryptChunk context metadata dictionary bytes = walk 0 0 dictionary 0 []
+  where
+    walk !offset !page !isDictionary !values !pages
+      | offset == BS.length bytes =
+          if values == cmNumValues metadata
+            then Right (BS.concat (reverse pages))
+            else Left "Parquet.Read: encrypted chunk value count differs from metadata"
+      | otherwise = do
+          decoded <- decryptPage context isDictionary page bytes offset
+          let count = decryptedPageValues decoded
+          if count < 0 || count > cmNumValues metadata - values
+            then Left "Parquet.Read: encrypted chunk exceeds declared value count"
+            else walk (decryptedPageEnd decoded) (if isDictionary then page else page + 1) False (values + count) (decryptedPageBytes decoded : pages)
+
+
+decryptPage :: Decryption.ColumnCrypto -> Bool -> Int -> ByteString -> Int -> Either String DecryptedPage
+decryptPage context dictionary page bytes offset = do
+  (encryptedHeader, afterHeader) <- Enc.readFramedModule bytes offset
+  let headerKind = if dictionary then Enc.ModuleDictionaryPageHeader else Enc.ModuleDataPageHeader
+      bodyKind = if dictionary then Enc.ModuleDictionaryPage else Enc.ModuleDataPage
+  headerBytes <- Decryption.decryptColumnPageHeader context headerKind page encryptedHeader
+  details <- Page.readPageDetailsAt headerBytes 0
+  (headerValue, headerEnd) <- TC.decodeCompactFrom headerBytes 0
+  if not (BS.all (== 0) (BS.drop headerEnd headerBytes))
+    then Left "Parquet.Read: nonzero trailing encrypted page header bytes"
+    else Right ()
+  count <- case Page.phType (Page.pdHeader details) of
+    PtDictionaryPage{} | dictionary -> Right 0
+    PtDataPage dataHeader | not dictionary -> Right (fromIntegral (dphNumValues dataHeader))
+    PtDataPageV2 dataHeader | not dictionary -> Right (fromIntegral (dph2NumValues dataHeader))
+    _ -> Left "Parquet.Read: encrypted page type disagrees with dictionary/data position"
+  (encryptedBody, afterBody) <- Enc.readFramedModule bytes afterHeader
+  let wireBody = BS.take (afterBody - afterHeader) (BS.drop afterHeader bytes)
+  case phCompressedPageSize (Page.pdHeader details) of
+    Just size | fromIntegral size == BS.length wireBody -> Right ()
+    _ -> Left "Parquet.Read: encrypted body size differs from authenticated header"
+  case Page.pdChecksum details of
+    Just expected -> Page.verifyPageChecksum expected wireBody
+    Nothing -> Right ()
+  body <- Decryption.decryptColumnPageBody context bodyKind page encryptedBody
+  if BS.length body > fromIntegral (maxBound :: Int32)
+    then Left "Parquet.Read: decrypted page exceeds signed 32-bit size"
+    else Right ()
+  fields <- case headerValue of
+    TV.Struct fields -> Right fields
+    _ -> Left "Parquet.Read: expected decrypted page header struct"
+  -- CRC covers the on-disk encrypted body, which was checked above. Remove
+  -- it from the temporary plaintext view; ordinary decoders still validate
+  -- every other header, level, compression and value invariant.
+  let normalized = TV.Struct (V.map (\field -> case field of
+        PageHeader_CompressedSize _ -> PageHeader_CompressedSize (fromIntegral (BS.length body))
+        _ -> field) (V.filter (\field -> fst field /= fst (PageHeader_Crc 0)) fields))
+      usesDictionary = case phType (Page.pdHeader details) of
+        PtDataPage header -> dphEncoding header `elem` [2, 8]
+        PtDataPageV2 header -> dph2Encoding header `elem` [2, 8]
+        _ -> False
+  Right (DecryptedPage (encodeCompact normalized <> body) afterBody count usesDictionary)
+
+
+data PreparedSelection = PreparedSelection
+  { preparedSelectionBytes :: !ByteString
+  , preparedSelection :: !PageSelection
+  }
+
+
+-- | Produce a temporary plaintext view containing only retained encrypted
+-- pages and their dictionary when needed. Skipped locations get one-byte
+-- placeholders, preserving all original row boundaries without reading those
+-- page bytes. Plaintext columns keep their original file and index unchanged.
+prepareColumnSelection :: ParquetFile -> Int -> Int -> PageSelection -> Either String PreparedSelection
+prepareColumnSelection file group column selection = case fileColumnCrypto file group column of
+  Nothing -> Right (PreparedSelection (pfBytes file) selection)
+  Just context -> do
+    let bytes = pfBytes file
+        locations = selectionLocations selection
+    validateSelection bytes selection
+    raw <- rawColumnChunkSlice file group column
+    metadata <- Decryption.cryptoColumnMetadata context
+    let start = maybe (cmDataPageOffset metadata) (min (cmDataPageOffset metadata)) (cmDictionaryPageOffset metadata)
+        end = start + fromIntegral (BS.length raw)
+    V.mapM_ (\location ->
+      if plOffset location < start || plOffset location > end || fromIntegral (plCompressedPageSize location) > end - plOffset location
+        then Left "Parquet.Read: encrypted page selection is outside its column"
+        else Right ()) locations
+    pages <- V.imapM (\ordinal location ->
+      if not (selectionKeep selection V.! ordinal)
+        then Right (DecryptedPage (BS.singleton 0) 0 0 False)
+        else do
+          decoded <- decryptPage context False ordinal bytes (fromIntegral (plOffset location))
+          if fromIntegral (decryptedPageEnd decoded) /= plOffset location + fromIntegral (plCompressedPageSize location)
+            then Left "Parquet.Read: encrypted page size differs from offset index"
+            else Right decoded) locations
+    dictionary <- if V.any decryptedPageUsesDictionary pages
+      then do
+        offset <- maybe (Left "Parquet.Read: encrypted dictionary page offset is missing") Right (cmDictionaryPageOffset metadata)
+        if V.null locations || offset < start || offset >= plOffset (V.head locations)
+          then Left "Parquet.Read: encrypted dictionary lies outside the column"
+          else Right ()
+        decoded <- decryptPage context True 0 bytes (fromIntegral offset)
+        if fromIntegral (decryptedPageEnd decoded) > plOffset (V.head locations)
+          then Left "Parquet.Read: encrypted dictionary overlaps data pages"
+          else Right (decryptedPageBytes decoded)
+      else Right BS.empty
+    let sizes = VP.generate (V.length pages) (BS.length . decryptedPageBytes . (pages V.!))
+        offsets = VP.scanl' (+) (BS.length dictionary) sizes
+    if VP.any (< 0) offsets || VP.last offsets < BS.length dictionary
+      then Left "Parquet.Read: selected plaintext pages exceed addressable size"
+      else Right ()
+    normalizedLocations <- V.imapM (\index location ->
+      let size = sizes VP.! index
+      in if toInteger size > toInteger (maxBound :: Int32)
+           then Left "Parquet.Read: plaintext indexed page exceeds signed 32-bit size"
+           else Right location {plOffset = fromIntegral (offsets VP.! index), plCompressedPageSize = fromIntegral size}) locations
+    let normalized = selection
+          { selectionLocations = normalizedLocations
+          , selectionDictionaryOffset = if BS.null dictionary then Nothing else Just 0
+          }
+        plaintext = BS.concat (dictionary : V.toList (V.map decryptedPageBytes pages))
+    Right (PreparedSelection plaintext normalized)
+
+-- Early parquet-mr files sometimes point data_page_offset at an unadvertised
+-- dictionary and omit its header from total_compressed_size. Repair only that
+-- exact legacy shape, by exactly one dictionary-header length. A complete
+-- page walk must consume the corrected slice and the declared value count;
+-- it may never enter another column, an auxiliary index, or the footer.
+legacyDictionaryChunkSize :: ParquetFile -> ColumnMetadata -> Int -> Int -> Either String Int
+legacyDictionaryChunkSize pf meta start size
+  | fmCreatedBy footer /= Just "parquet-mr"
+      || not (V.null (cmEncodings meta))
+      || cmDictionaryPageOffset meta /= Nothing = Right size
+  | otherwise = do
+      details <- readPageDetailsAt original 0
+      case phType (pdHeader details) of
+        PtDictionaryPage {} -> case walk original of
+          Right () -> Right size
+          Left _ -> do
+            trailer <- F.readFooterTrailer bytes
+            let footerStart = BS.length bytes - 8 - BS.length (F.ftBytes trailer)
+                boundary = V.foldl' rowBoundary (fromIntegral footerStart) (fmRowGroups footer)
+                headerSize = pdBodyOffset details
+            if fromIntegral headerSize > (boundary :: Int64) - fromIntegral start - fromIntegral size
+              then Left "Parquet.Read: legacy dictionary size repair crosses a column/index/footer boundary"
+              else do
+                let corrected = size + headerSize
+                walk (BS.take corrected (BS.drop start bytes))
+                Right corrected
+        _ -> Right size
+  where
+    bytes = pfBytes pf
+    footer = pfFooter pf
+    original = BS.take size (BS.drop start bytes)
+    nearer boundary off
+      | off > fromIntegral start = min boundary off
+      | otherwise = boundary
+    optionalBoundary boundary = maybe boundary (nearer boundary)
+    rowBoundary boundary row = V.foldl' columnBoundary boundary (rgColumns row)
+    columnBoundary boundary column =
+      let indexed = optionalBoundary
+            (optionalBoundary boundary (ccOffsetIndexOffset column))
+            (ccColumnIndexOffset column)
+      in case ccMetadata column of
+        Nothing -> indexed
+        Just m -> optionalBoundary
+          (optionalBoundary (nearer indexed (cmDataPageOffset m)) (cmDictionaryPageOffset m))
+          (cmBloomFilterOffset m)
+    walk chunk = go 0 0 True
+      where
+        go !off !values !first
+          | off == BS.length chunk =
+              if not first && values == cmNumValues meta
+                then Right ()
+                else Left "Parquet.Read: legacy dictionary chunk value count mismatch"
+          | otherwise = do
+              details <- readPageDetailsCheckedAt chunk off
+              let header = pdHeader details
+              count <- case phType header of
+                PtDictionaryPage {} | first -> Right 0
+                PtDataPage p | not first -> Right (fromIntegral (dphNumValues p))
+                PtDataPageV2 p | not first -> Right (fromIntegral (dph2NumValues p))
+                _ -> Left "Parquet.Read: invalid page sequence in legacy dictionary chunk"
+              if count > cmNumValues meta - values
+                then Left "Parquet.Read: legacy dictionary chunk exceeds its declared value count"
+                else case phCompressedPageSize header of
+                  Just bodySize -> go (pdBodyOffset details + fromIntegral bodySize) (values + count) False
+                  Nothing -> Left "Parquet.Read: missing legacy page size"
+
+whenOutOfRange :: Int -> Int -> String -> Either String ()
+whenOutOfRange i n msg
+  | i >= 0 && i < n = Right ()
+  | otherwise = Left $ "Parquet.Read: " ++ msg ++ " index out of range"
+
+-- | Thrift @Encoding@ for @PLAIN@.
+encPlain :: Int32
+encPlain = 0
+
+-- | Thrift @Encoding@ for @PLAIN_DICTIONARY@.
+encPlainDictionary :: Int32
+encPlainDictionary = 2
+
+-- | Thrift @Encoding@ for @RLE_DICTIONARY@ (modern name for PLAIN_DICTIONARY).
+encRleDictionary :: Int32
+encRleDictionary = 8
+
+-- | Thrift @Encoding@ for @RLE@ (encoding 3). In Parquet V1
+-- this only appears as a column-chunk-level encoding for
+-- repetition / definition levels (not data); in V2 BOOLEAN
+-- columns are encoded as RLE/bit-packed directly.
+encRle :: Int32
+encRle = 3
+
+isDictionaryEncoding :: Int32 -> Bool
+isDictionaryEncoding e = e == encPlainDictionary || e == encRleDictionary
+
+{-# INLINE decompressDataPageBody #-}
+decompressDataPageBody ::
+  Compression ->
+  ByteString ->
+  Int ->
+  Either String (PageHeader, DataPageHeader, ByteString, Int)
+decompressDataPageBody codec chunk off = do
+  (hdr, afterHdr) <- readPageHeaderCheckedAt chunk off
+  dph <- case phType hdr of
+    PtDataPage d -> Right d
+    _            -> Left "Parquet.Read: expected DATA_PAGE"
+  do
+      compSz <- case phCompressedPageSize hdr of
+        Nothing -> Left "Parquet.Read: missing compressed_page_size"
+        Just s -> Right (fromIntegral s :: Int)
+      let !bodyStart = afterHdr
+      if bodyStart + compSz > BS.length chunk
+        then Left "Parquet.Read: truncated page body"
+        else do
+          let !compBody = BS.take compSz (BS.drop bodyStart chunk)
+          !raw <- decompressPageData codec (phUncompressedPageSize hdr) compBody
+          let !nextOff = bodyStart + compSz
+          Right (hdr, dph, raw, nextOff)
+
+-- | Read every @DATA_PAGE@ with @PLAIN@ @INT32@ in order until the chunk ends.
+readPlainInt32ColumnChunk :: Compression -> ByteString -> Either String (VP.Vector Int32)
+readPlainInt32ColumnChunk codec chunk = go 0 []
+  where
+    go !off !acc
+      | off >= BS.length chunk = Right (concatPages VP.concat acc)
+      | otherwise = do
+          (_hdr, dph, raw, nextOff) <- decompressDataPageBody codec chunk off
+          if dphEncoding dph /= encPlain
+            then Left "Parquet.Read: encoding is not PLAIN (0)"
+            else do
+              let !n = fromIntegral (dphNumValues dph) :: Int
+              pageVec <- decodePlainInt32 n raw
+              go nextOff (pageVec : acc)
+
+-- | Read the first data page of a chunk as @PLAIN@ @INT32@ values.
+readPlainInt32FirstPage :: Compression -> ByteString -> Either String (VP.Vector Int32)
+readPlainInt32FirstPage codec chunk = do
+  (_hdr, dph, raw, _) <- decompressDataPageBody codec chunk 0
+  if dphEncoding dph /= encPlain
+    then Left "Parquet.Read: encoding is not PLAIN (0)"
+    else do
+      let !n = fromIntegral (dphNumValues dph) :: Int
+      decodePlainInt32 n raw
+
+readPlainOptionalFirstPageWith ::
+  Compression ->
+  Int ->
+  Int ->
+  ByteString ->
+  (VP.Vector Int32 -> Int -> ByteString -> Either String (V.Vector (Maybe a))) ->
+  Either String (V.Vector (Maybe a))
+readPlainOptionalFirstPageWith codec maxRep maxDef chunk mat = do
+  (_hdr, dph, raw, _) <- decompressDataPageBody codec chunk 0
+  if dphEncoding dph /= encPlain
+    then Left "Parquet.Read: encoding is not PLAIN (0)"
+    else do
+      let !n = fromIntegral (dphNumValues dph) :: Int
+      (_rep, def, rest) <- parseDataPageV1Levels maxRep maxDef n raw
+      mat def maxDef rest
+
+readPlainOptionalColumnChunkWith ::
+  Compression ->
+  Int ->
+  Int ->
+  ByteString ->
+  (VP.Vector Int32 -> Int -> ByteString -> Either String (V.Vector (Maybe a))) ->
+  Either String (V.Vector (Maybe a))
+readPlainOptionalColumnChunkWith codec maxRep maxDef chunk mat = go 0 []
+  where
+    go !off !acc
+      | off >= BS.length chunk = Right (concatPages V.concat acc)
+      | otherwise = do
+          (_hdr, dph, raw, nextOff) <- decompressDataPageBody codec chunk off
+          if dphEncoding dph /= encPlain
+            then Left "Parquet.Read: encoding is not PLAIN (0)"
+            else do
+              let !n = fromIntegral (dphNumValues dph) :: Int
+              (_rep, def, rest) <- parseDataPageV1Levels maxRep maxDef n raw
+              page <- mat def maxDef rest
+              go nextOff (page : acc)
+
+-- | First @DATA_PAGE@ as @PLAIN@ @INT32@ with levels.
+readPlainInt32OptionalFirstPage ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Int32))
+readPlainInt32OptionalFirstPage codec mr md ch =
+  readPlainOptionalFirstPageWith codec mr md ch materializePlainInt32Optional
+
+-- | All @DATA_PAGE@s as optional @PLAIN@ @INT32@.
+readPlainInt32OptionalColumnChunk ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Int32))
+readPlainInt32OptionalColumnChunk codec mr md ch =
+  readPlainOptionalColumnChunkWith codec mr md ch materializePlainInt32Optional
+
+readPlainInt64OptionalFirstPage ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Int64))
+readPlainInt64OptionalFirstPage codec mr md ch =
+  readPlainOptionalFirstPageWith codec mr md ch materializePlainInt64Optional
+
+readPlainInt64OptionalColumnChunk ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Int64))
+readPlainInt64OptionalColumnChunk codec mr md ch =
+  readPlainOptionalColumnChunkWith codec mr md ch materializePlainInt64Optional
+
+readPlainFloatOptionalFirstPage ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Float))
+readPlainFloatOptionalFirstPage codec mr md ch =
+  readPlainOptionalFirstPageWith codec mr md ch materializePlainFloatOptional
+
+readPlainFloatOptionalColumnChunk ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Float))
+readPlainFloatOptionalColumnChunk codec mr md ch =
+  readPlainOptionalColumnChunkWith codec mr md ch materializePlainFloatOptional
+
+readPlainDoubleOptionalFirstPage ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Double))
+readPlainDoubleOptionalFirstPage codec mr md ch =
+  readPlainOptionalFirstPageWith codec mr md ch materializePlainDoubleOptional
+
+readPlainDoubleOptionalColumnChunk ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Double))
+readPlainDoubleOptionalColumnChunk codec mr md ch =
+  readPlainOptionalColumnChunkWith codec mr md ch materializePlainDoubleOptional
+
+readPlainBoolOptionalFirstPage ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Bool))
+readPlainBoolOptionalFirstPage codec mr md ch =
+  readPlainOptionalFirstPageWith codec mr md ch materializePlainBoolOptional
+
+readPlainBoolOptionalColumnChunk ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Bool))
+readPlainBoolOptionalColumnChunk codec mr md ch =
+  readPlainOptionalColumnChunkWith codec mr md ch materializePlainBoolOptional
+
+readPlainByteArrayOptionalFirstPage ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe ByteString))
+readPlainByteArrayOptionalFirstPage codec mr md ch =
+  readPlainOptionalFirstPageWith codec mr md ch materializePlainByteArrayOptional
+
+readPlainByteArrayOptionalColumnChunk ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe ByteString))
+readPlainByteArrayOptionalColumnChunk codec mr md ch =
+  readPlainOptionalColumnChunkWith codec mr md ch materializePlainByteArrayOptional
+
+-- | @PLAIN@ @INT64@ (little-endian), all @DATA_PAGE@s concatenated.
+readPlainInt64ColumnChunk :: Compression -> ByteString -> Either String (VP.Vector Int64)
+readPlainInt64ColumnChunk codec chunk = go 0 []
+  where
+    go !off !acc
+      | off >= BS.length chunk = Right (concatPages VP.concat acc)
+      | otherwise = do
+          (_hdr, dph, raw, nextOff) <- decompressDataPageBody codec chunk off
+          if dphEncoding dph /= encPlain
+            then Left "Parquet.Read: encoding is not PLAIN (0)"
+            else do
+              let !n = fromIntegral (dphNumValues dph) :: Int
+              pageVec <- decodePlainInt64 n raw
+              go nextOff (pageVec : acc)
+
+-- | @PLAIN@ @FLOAT@ (IEEE little-endian).
+readPlainFloatColumnChunk :: Compression -> ByteString -> Either String (VP.Vector Float)
+readPlainFloatColumnChunk codec chunk = go 0 []
+  where
+    go !off !acc
+      | off >= BS.length chunk = Right (concatPages VP.concat acc)
+      | otherwise = do
+          (_hdr, dph, raw, nextOff) <- decompressDataPageBody codec chunk off
+          if dphEncoding dph /= encPlain
+            then Left "Parquet.Read: encoding is not PLAIN (0)"
+            else do
+              let !n = fromIntegral (dphNumValues dph) :: Int
+              pageVec <- decodePlainFloat n raw
+              go nextOff (pageVec : acc)
+
+-- | @PLAIN@ @DOUBLE@ (IEEE little-endian).
+readPlainDoubleColumnChunk :: Compression -> ByteString -> Either String (VP.Vector Double)
+readPlainDoubleColumnChunk codec chunk = go 0 []
+  where
+    go !off !acc
+      | off >= BS.length chunk = Right (concatPages VP.concat acc)
+      | otherwise = do
+          (_hdr, dph, raw, nextOff) <- decompressDataPageBody codec chunk off
+          if dphEncoding dph /= encPlain
+            then Left "Parquet.Read: encoding is not PLAIN (0)"
+            else do
+              let !n = fromIntegral (dphNumValues dph) :: Int
+              pageVec <- decodePlainDouble n raw
+              go nextOff (pageVec : acc)
+
+-- | @PLAIN@ @BOOLEAN@ (packed bits, LSB of first byte is first value).
+readPlainBoolColumnChunk :: Compression -> ByteString -> Either String (V.Vector Bool)
+readPlainBoolColumnChunk codec chunk = go 0 []
+  where
+    go !off !acc
+      | off >= BS.length chunk = Right (concatPages V.concat acc)
+      | otherwise = do
+          (_hdr, dph, raw, nextOff) <- decompressDataPageBody codec chunk off
+          if dphEncoding dph /= encPlain
+            then Left "Parquet.Read: encoding is not PLAIN (0)"
+            else do
+              let !n = fromIntegral (dphNumValues dph) :: Int
+              pageVec <- decodePlainBool n raw
+              go nextOff (pageVec : acc)
+
+-- | @PLAIN@ @BYTE_ARRAY@ (length-prefixed 4-byte LE + bytes per value).
+readPlainByteArrayColumnChunk :: Compression -> ByteString -> Either String (V.Vector ByteString)
+readPlainByteArrayColumnChunk codec chunk = go 0 []
+  where
+    go !off !acc
+      | off >= BS.length chunk = Right (concatPages V.concat acc)
+      | otherwise = do
+          (_hdr, dph, raw, nextOff) <- decompressDataPageBody codec chunk off
+          if dphEncoding dph /= encPlain
+            then Left "Parquet.Read: encoding is not PLAIN (0)"
+            else do
+              let !n = fromIntegral (dphNumValues dph) :: Int
+              pageVec <- decodePlainByteArray n raw
+              go nextOff (pageVec : acc)
+
+-- | Dictionary page (@PLAIN@ @INT32@ values) followed by @DATA_PAGE@s with
+-- @PLAIN_DICTIONARY@ (indices as @PLAIN@ @INT32@). Plain @DATA_PAGE@s without
+-- a dictionary are also accepted.
+readPlainDictionaryInt32ColumnChunk :: Compression -> ByteString -> Either String (VP.Vector Int32)
+readPlainDictionaryInt32ColumnChunk codec chunk = go 0 Nothing []
+  where
+    go !off !mDict !acc
+      | off >= BS.length chunk =
+          if all VP.null acc
+            then Left "Parquet.Read: empty dictionary column chunk"
+            else Right (concatPages VP.concat acc)
+      | otherwise = do
+          (hdr, afterHdr) <- readPageHeaderCheckedAt chunk off
+          compSz <- case phCompressedPageSize hdr of
+            Nothing -> Left "Parquet.Read: missing compressed_page_size"
+            Just s -> Right (fromIntegral s :: Int)
+          let !bodyStart = afterHdr
+          if bodyStart + compSz > BS.length chunk
+            then Left "Parquet.Read: truncated page body"
+            else do
+              let !compBody = BS.take compSz (BS.drop bodyStart chunk)
+              checkDictionaryPagePosition off hdr
+              !raw <- decompressPageData codec (phUncompressedPageSize hdr) compBody
+              let !nextOff = bodyStart + compSz
+              case phType hdr of
+                PtDictionaryPage dk
+                  | not (dictEncoding dk == encPlain || dictEncoding dk == encPlainDictionary) ->
+                      Left "Parquet.Read: dictionary page encoding is neither PLAIN (0) nor PLAIN_DICTIONARY (2)"
+                  | otherwise -> do
+                      let !nDict = fromIntegral (dictNumValues dk) :: Int
+                      dict <- decodePlainInt32 nDict raw
+                      go nextOff (Just dict) acc
+                PtDataPage dph -> case dphEncoding dph of
+                  e
+                    | e == encPlain -> do
+                        let !n = fromIntegral (dphNumValues dph) :: Int
+                        pageVec <- decodePlainInt32 n raw
+                        go nextOff mDict (pageVec : acc)
+                    | isDictionaryEncoding e -> do
+                        dict0 <- case mDict of
+                          Nothing ->
+                            Left "Parquet.Read: PLAIN_DICTIONARY data page before dictionary page"
+                          Just d -> Right d
+                        let !n = fromIntegral (dphNumValues dph) :: Int
+                        ix <- decodeDictionaryIndices n raw
+                        let !nD = VP.length dict0
+                            ok =
+                              VP.foldl'
+                                ( \a k ->
+                                    a
+                                      && ( let !j = fromIntegral k :: Int
+                                           in j >= 0 && j < nD
+                                         )
+                                )
+                                True
+                                ix
+                        if not ok
+                          then Left "Parquet.Read: dictionary index out of range"
+                          else do
+                            let pageVec = VP.map (\k -> dict0 VP.! fromIntegral k) ix
+                            go nextOff mDict (pageVec : acc)
+                  e ->
+                    Left $
+                      "Parquet.Read: unsupported data page encoding "
+                        ++ show e
+                        ++ " (expected PLAIN, PLAIN_DICTIONARY, or RLE_DICTIONARY)"
+                _ -> Left "Parquet.Read: expected DICTIONARY_PAGE or DATA_PAGE"
+
+decompressChunk :: Compression -> ByteString -> Either String ByteString
+decompressChunk Uncompressed bs = Right bs
+decompressChunk GZip bs = tryGZip bs
+decompressChunk Snappy bs = trySnappy bs
+#ifdef HAVE_ZSTD
+decompressChunk ZSTD bs = tryZstd bs
+#endif
+decompressChunk LZ4 _ =
+  Left "Parquet.Read: legacy LZ4 requires uncompressed size; use decompressDataPageBody"
+decompressChunk LZ4Raw _ =
+  Left "Parquet.Read: LZ4_RAW requires uncompressed size; use decompressPage internally"
+#ifdef HAVE_BROTLI
+decompressChunk Brotli bs = tryBrotli bs
+#else
+decompressChunk Brotli _ =
+  Left "Parquet.Read: Brotli requires building wireform with -fbrotli"
+#endif
+decompressChunk LZO bytes =
+  either (Left . (("Parquet.Read: " ++) . LZO.prettyLZOError)) Right
+    (LZO.decompress (fromIntegral (maxBound :: Int32)) bytes)
+decompressChunk c _ =
+  Left $
+    "Parquet.Read: compression "
+      ++ show c
+      ++ " not supported (use Uncompressed, GZip, Snappy with -fsnappy"
+#ifdef HAVE_ZSTD
+      ++ ", Zstandard with -fzstd"
+#endif
+#ifdef HAVE_LZ4
+      ++ ", LZ4_RAW with -flz4"
+#endif
+#ifdef HAVE_BROTLI
+      ++ ", Brotli with -fbrotli"
+#endif
+      ++ ")"
+
+decompressPageData :: Compression -> Maybe Int32 -> ByteString -> Either String ByteString
+decompressPageData GZip (Just expected) bytes = GZip.decompressSized (fromIntegral expected) bytes
+#ifdef HAVE_SNAPPY
+decompressPageData Snappy (Just expected) bytes = trySnappySized (fromIntegral expected) bytes
+#endif
+decompressPageData LZO (Just expected) bytes = do
+  raw <- either (Left . (("Parquet.Read: " ++) . LZO.prettyLZOError)) Right
+    (LZO.decompress (fromIntegral expected) bytes)
+  if BS.length raw == fromIntegral expected
+    then Right raw
+    else Left "Parquet.Read: LZO decompressed size differs from page header"
+#ifdef HAVE_BROTLI
+decompressPageData Brotli (Just expected) bytes = Brotli.decompressSized (fromIntegral expected) bytes
+#endif
+#ifdef HAVE_ZSTD
+decompressPageData ZSTD (Just uncompSz) bs = tryZstdSized (fromIntegral uncompSz) bs
+#endif
+#ifdef HAVE_LZ4
+decompressPageData LZ4 (Just uncompSz) bs = tryLegacyLZ4 (fromIntegral uncompSz) bs
+decompressPageData LZ4Raw (Just uncompSz) bs = tryLZ4Raw (fromIntegral uncompSz) bs
+decompressPageData LZ4Raw Nothing _ =
+  Left "Parquet.Read: LZ4_RAW decompression requires uncompressed_page_size in header"
+#endif
+decompressPageData codec (Just expected) bytes = do
+  raw <- decompressChunk codec bytes
+  if BS.length raw == fromIntegral expected then Right raw else Left "Parquet.Read: decompressed size differs from page header"
+decompressPageData codec Nothing bytes = decompressChunk codec bytes
+
+-- V2's uncompressed_page_size includes the uncompressed level streams,
+-- while the codec sees only the values. All-null pages can have no values
+-- at all (not a valid Snappy stream), or a compressed empty ZSTD stream.
+decompressV2Values
+  :: Compression -> PageHeader -> DataPageHeaderV2 -> ByteString
+  -> Either String ByteString
+decompressV2Values codec hdr dph2 bytes = do
+  size <- case phUncompressedPageSize hdr of
+    Nothing -> Left "Parquet.Read: V2 page missing uncompressed_page_size"
+    Just n -> Right (fromIntegral n - fromIntegral (dph2RepLevelsLen dph2) - fromIntegral (dph2DefLevelsLen dph2) :: Int)
+  if size < 0
+    then Left "Parquet.Read: V2 levels exceed uncompressed page size"
+    else if size == 0 && dph2NumValues dph2 == dph2NumNulls dph2 && BS.null bytes
+      then Right BS.empty
+      else do
+        values <- if dph2IsCompressed dph2
+          then decompressPageData codec (Just (fromIntegral size)) bytes
+          else Right bytes
+        if BS.length values == size
+          then Right values
+          else Left "Parquet.Read: V2 decompressed values size mismatch"
+{-# INLINE decompressV2Values #-}
+
+tryGZip :: ByteString -> Either String ByteString
+tryGZip = GZip.decompress
+
+trySnappy :: ByteString -> Either String ByteString
+#ifdef HAVE_SNAPPY
+trySnappy = trySnappyBounded Nothing
+#else
+trySnappy _ = Left "Parquet.Read: Snappy requires building wireform with -fsnappy"
+#endif
+
+#ifdef HAVE_SNAPPY
+foreign import ccall unsafe "snappy_uncompressed_length"
+  snappyDecodedLength :: Ptr Word8 -> CSize -> Ptr CSize -> IO CInt
+
+trySnappySized :: Int -> ByteString -> Either String ByteString
+trySnappySized expected = trySnappyBounded (Just expected)
+
+trySnappyBounded :: Maybe Int -> ByteString -> Either String ByteString
+trySnappyBounded expected bytes = unsafePerformIO $ BSUnsafe.unsafeUseAsCStringLen bytes $ \(source, count) -> alloca $ \size -> do
+  status <- snappyDecodedLength (castPtr source) (fromIntegral count) size
+  if status /= 0 then pure (Left "Parquet.Read: invalid Snappy length header") else do
+    actual <- peek size
+    if actual > fromIntegral (maxBound :: Int32) || maybe False (\n -> n < 0 || actual /= fromIntegral n) expected
+      then pure (Left "Parquet.Read: Snappy decoded size differs from page header or exceeds INT32 limit")
+      else do
+        result <- try @SomeException (evaluate (Snappy.decompress bytes))
+        pure $ case result of
+          Left err -> Left ("Parquet.Read: snappy decompress failed: " ++ show err)
+          Right raw
+            | fromIntegral (BS.length raw) == actual -> Right raw
+            | otherwise -> Left "Parquet.Read: Snappy decoded size mismatch"
+#endif
+
+#ifdef HAVE_ZSTD
+foreign import ccall unsafe "ZSTD_getFrameContentSize"
+  zstdFrameContentSize :: Ptr Word8 -> CSize -> IO CULLong
+
+tryZstd :: ByteString -> Either String ByteString
+tryZstd bytes = unsafePerformIO $ BSUnsafe.unsafeUseAsCStringLen bytes $ \(source, count) -> do
+  size <- zstdFrameContentSize (castPtr source) (fromIntegral count)
+  if size == maxBound - 1
+    then pure (Left "Parquet.Read: invalid ZSTD frame header")
+    else if size == maxBound
+      then do
+        result <- try @SomeException $ evaluate $ BL.toStrict $
+          BL.take (fromIntegral (maxBound :: Int32) + 1) (ZstdLazy.decompress (BL.fromStrict bytes))
+        pure $ case result of
+          Left err -> Left ("Parquet.Read: zstd decompress failed: " ++ show err)
+          Right raw
+            | BS.length raw > fromIntegral (maxBound :: Int32) -> Left "Parquet.Read: ZSTD output exceeds INT32 page-size limit"
+            | otherwise -> tryZstdSized (BS.length raw) bytes
+      else if size > fromIntegral (maxBound :: Int32)
+        then pure (Left "Parquet.Read: ZSTD output exceeds INT32 page-size limit")
+        else pure (tryZstdSized (fromIntegral size) bytes)
+
+-- A ZSTD frame may omit its content size, and a valid empty frame has
+-- size zero. The high-level zstd API reports both as Skip. Parquet already
+-- provides the exact size, so decode directly into that bounded buffer.
+tryZstdSized :: Int -> ByteString -> Either String ByteString
+tryZstdSized expected bytes
+  | expected < 0 = Left "Parquet.Read: negative ZSTD uncompressed size"
+  | otherwise = unsafePerformIO $ do
+      output <- BSI.mallocByteString expected
+      result <- withForeignPtr output $ \dst ->
+        BSUnsafe.unsafeUseAsCStringLen bytes $ \(src, size) ->
+          ZstdBase.decompress dst expected src size
+      pure $ case result of
+        Left err -> Left ("Parquet.Read: zstd decompress failed: " ++ err)
+        Right size
+          | size == expected -> Right (BSI.fromForeignPtr output 0 size)
+          | otherwise -> Left "Parquet.Read: ZSTD decompressed size differs from page header"
+#endif
+
+#ifdef HAVE_LZ4
+-- Codec 5 was emitted both with Hadoop's big-endian block/chunk lengths
+-- and (by older parquet-cpp writers) as a raw block. Bound every advertised
+-- size against the page size before asking liblz4 for an output buffer.
+tryLegacyLZ4 :: Int -> ByteString -> Either String ByteString
+tryLegacyLZ4 expected bytes = case blocks 0 0 [] of
+  Right parts -> Right (BS.concat (reverse parts))
+  Left _ -> tryLZ4Raw expected bytes
+  where
+    size = BS.length bytes
+    be32 off = fromIntegral
+      ((fromIntegral (BSUnsafe.unsafeIndex bytes off) `shiftL` 24
+        .|. fromIntegral (BSUnsafe.unsafeIndex bytes (off + 1)) `shiftL` 16
+        .|. fromIntegral (BSUnsafe.unsafeIndex bytes (off + 2)) `shiftL` 8
+        .|. fromIntegral (BSUnsafe.unsafeIndex bytes (off + 3))) :: Word32)
+    blocks !off !written !parts
+      | off == size && written == expected = Right parts
+      | size - off < 4 = Left "Parquet.Read: truncated Hadoop LZ4 block header"
+      | otherwise =
+          let blockSize = be32 off
+          in if blockSize <= 0 || blockSize > expected - written
+               then Left "Parquet.Read: invalid Hadoop LZ4 block size"
+               else chunks (off + 4) written blockSize parts
+    chunks !off !written !remaining !parts
+      | remaining == 0 = blocks off written parts
+      | size - off < 4 = Left "Parquet.Read: truncated Hadoop LZ4 chunk header"
+      | otherwise = do
+          let compressedSize = be32 off
+          if compressedSize <= 0 || compressedSize > size - off - 4
+            then Left "Parquet.Read: invalid Hadoop LZ4 chunk size"
+            else do
+              decoded <- LZ4.decompress remaining (BS.take compressedSize (BS.drop (off + 4) bytes))
+              let actual = BS.length decoded
+              if actual <= 0 || actual > remaining
+                then Left "Parquet.Read: invalid Hadoop LZ4 decoded chunk size"
+                else chunks (off + 4 + compressedSize) (written + actual)
+                       (remaining - actual) (decoded : parts)
+
+-- | Decompress an LZ4_RAW block — the codec Parquet's spec
+-- numbers as 7. The block is in raw LZ4 block format with no
+-- header at all; 'Columnar.LZ4.decompress' wraps a direct FFI
+-- call to @LZ4_decompress_safe@ from @liblz4@.
+tryLZ4Raw :: Int -> ByteString -> Either String ByteString
+tryLZ4Raw uncompSize bs = case LZ4.decompress uncompSize bs of
+  Right out
+    | BS.length out == uncompSize -> Right out
+    | otherwise -> Left $
+        "Parquet.Read: LZ4_RAW size mismatch (page header said "
+          ++ show uncompSize ++ ", got " ++ show (BS.length out)
+          ++ "; the file is malformed or the page header is wrong)"
+  Left e -> Left ("Parquet.Read: " ++ e)
+#endif
+
+#ifdef HAVE_BROTLI
+tryBrotli :: ByteString -> Either String ByteString
+tryBrotli = Brotli.decompress
+#endif
+
+decodePlainInt32 :: Int -> ByteString -> Either String (VP.Vector Int32)
+decodePlainInt32 n bs
+  | n < 0 || n > BS.length bs `quot` 4 = Left "Parquet.Read: PLAIN INT32 buffer too small"
+#if !defined(WORDS_BIGENDIAN)
+  | otherwise = Right $! copyPlainNative n bs
+#else
+  | otherwise =
+      Right $
+        runST $ do
+          mv <- MVP.new n
+          let go2 !i
+                | i >= n = VP.unsafeFreeze mv
+                | otherwise = do
+                    let !o = i * 4
+                        !v = readLE32 bs o
+                    MVP.write mv i (fromIntegral v :: Int32)
+                    go2 (i + 1)
+          go2 0
+#endif
+
+decodePlainInt64 :: Int -> ByteString -> Either String (VP.Vector Int64)
+decodePlainInt64 n bs
+  | n < 0 || n > BS.length bs `quot` 8 = Left "Parquet.Read: PLAIN INT64 buffer too small"
+#if !defined(WORDS_BIGENDIAN)
+  | otherwise = Right $! copyPlainNative n bs
+#else
+  | otherwise =
+      Right $
+        runST $ do
+          mv <- MVP.new n
+          let go2 !i
+                | i >= n = VP.unsafeFreeze mv
+                | otherwise = do
+                    let !o = i * 8
+                        !v = readLE64 bs o
+                    MVP.write mv i (fromIntegral v :: Int64)
+                    go2 (i + 1)
+          go2 0
+#endif
+
+decodePlainFloat :: Int -> ByteString -> Either String (VP.Vector Float)
+decodePlainFloat n bs
+  | n < 0 || n > BS.length bs `quot` 4 = Left "Parquet.Read: PLAIN FLOAT buffer too small"
+#if !defined(WORDS_BIGENDIAN)
+  | otherwise = Right $! copyPlainNative n bs
+#else
+  | otherwise =
+      Right $
+        runST $ do
+          mv <- MVP.new n
+          let go2 !i
+                | i >= n = VP.unsafeFreeze mv
+                | otherwise = do
+                    let !o = i * 4
+                        !w = readLE32 bs o
+                    MVP.write mv i (castWord32ToFloat w)
+                    go2 (i + 1)
+          go2 0
+#endif
+
+decodePlainDouble :: Int -> ByteString -> Either String (VP.Vector Double)
+decodePlainDouble n bs
+  | n < 0 || n > BS.length bs `quot` 8 = Left "Parquet.Read: PLAIN DOUBLE buffer too small"
+#if !defined(WORDS_BIGENDIAN)
+  | otherwise = Right $! copyPlainNative n bs
+#else
+  | otherwise =
+      Right $
+        runST $ do
+          mv <- MVP.new n
+          let go2 !i
+                | i >= n = VP.unsafeFreeze mv
+                | otherwise = do
+                    let !o = i * 8
+                        !w = readLE64 bs o
+                    MVP.write mv i (castWord64ToDouble w)
+                    go2 (i + 1)
+          go2 0
+#endif
+
+#if !defined(WORDS_BIGENDIAN)
+-- PLAIN primitives already have native layout on little-endian hosts.
+-- Copy only the validated prefix, accepting unaligned input without typed
+-- pointer loads. The fresh primitive vector owns the immutable result.
+copyPlainNative :: forall a. Prim a => Int -> ByteString -> VP.Vector a
+copyPlainNative n bs
+  | n == 0 = VP.empty
+  | otherwise = unsafePerformIO $ do
+      mv@(MVP.MVector off _ array) <- MVP.unsafeNew n
+      BSUnsafe.unsafeUseAsCString bs $ \ptr ->
+        copyPtrToMutableByteArray array off (castPtr ptr :: Ptr a) n
+      VP.unsafeFreeze mv
+{-# NOINLINE copyPlainNative #-}
+#endif
+
+decodePlainBool :: Int -> ByteString -> Either String (V.Vector Bool)
+decodePlainBool n bs
+  -- n comes from the page header (dphNumValues, an Int32), so it can be
+  -- negative in a malformed file; unpackBitsLsbUnsafe allocates n slots.
+  | n < 0 = Left "Parquet.Read: PLAIN BOOLEAN negative value count"
+  | wholeBytes > BS.length bs || (wholeBytes == BS.length bs && tailBits /= 0) = Left "Parquet.Read: PLAIN BOOLEAN buffer too small"
+  | otherwise = Right $! unpackBitsLsbUnsafe n bs
+  where
+    (wholeBytes, tailBits) = n `quotRem` 8
+
+decodePlainByteArray :: Int -> ByteString -> Either String (V.Vector ByteString)
+decodePlainByteArray n bs0
+  | n < 0 = Left "Parquet.Read: PLAIN BYTE_ARRAY negative value count"
+  | n > BS.length bs0 `quot` 4 = Left "Parquet.Read: PLAIN BYTE_ARRAY truncated lengths"
+  | otherwise = runST $ do
+      out <- VM.unsafeNew n
+      let go !i !off
+            | i == n = Right <$> V.unsafeFreeze out
+            | BS.length bs0 - off < 4 = pure (Left "Parquet.Read: PLAIN BYTE_ARRAY truncated length")
+            | otherwise = do
+                let !len = fromIntegral (readLE32 bs0 off) :: Int
+                    !payloadOff = off + 4
+                if len > BS.length bs0 - payloadOff
+                  then pure (Left "Parquet.Read: PLAIN BYTE_ARRAY payload out of bounds")
+                  else do
+                    let !payload = BS.take len (BS.drop payloadOff bs0)
+                    VM.unsafeWrite out i payload
+                    go (i + 1) (payloadOff + len)
+      go 0 0
+
+{- | Dense BYTE_ARRAY values in Arrow's offsets/data layout. Construction is
+checked, offsets start at zero, and the data fits signed 32-bit offsets.
+The constructor stays private so dictionary gather can trust these bounds.
+-}
+type BinaryBuffers = BinaryBuffersOf Int32
+
+
+-- | Dense BYTE_ARRAY buffers with signed64-bit Arrow offsets.
+type LargeBinaryBuffers = BinaryBuffersOf Int64
+
+
+data BinaryBuffersOf o = BinaryBuffers
+  { binaryOffsets :: !(VS.Vector o)
+  , binaryData :: !ByteString
+  }
+
+
+-- Internal page layouts retain validated source bytes until the entire
+-- column's size is known. Only the final materialization copies payloads;
+-- collecting many pages must not copy their data twice.
+data BinaryPiece o = BinaryPiece
+  { pieceOffsets :: !(VS.Vector o)
+  , pieceSource :: !(BinarySource o)
+  }
+
+
+data BinarySource o
+  = BinaryContiguous !ByteString
+  | BinaryPrepared !(PreparedDictionary o)
+  | BinaryPlain !ByteString
+  | BinaryDictionary !(BinaryBuffersOf o) !(VP.Vector Int32)
+  | BinaryBoxed !(V.Vector ByteString)
+  | BinaryJoined ![BinaryPiece o]
+
+
+data PreparedDictionary o = PreparedDictionary
+  { preparedBuffers :: !(BinaryBuffersOf o)
+  , preparedMaxBytes :: {-# UNPACK #-} !Int
+  }
+
+
+emptyBinaryPiece :: forall o. (Num o, Storable o) => BinaryPiece o
+emptyBinaryPiece = BinaryPiece (VS.singleton 0) (BinaryContiguous BS.empty)
+
+
+pieceBytes :: forall o. (Integral o, Storable o) => BinaryPiece o -> Int
+pieceBytes = fromIntegral . VS.unsafeLast . pieceOffsets
+{-# INLINE pieceBytes #-}
+
+
+{- | Decode a complete PLAIN BYTE_ARRAY values section, without allocating
+a ByteString slice for every row. Validate all lengths before copying.
+-}
+decodePlainBinaryBuffers :: Int -> ByteString -> Either String BinaryBuffers
+decodePlainBinaryBuffers n raw = materializeBinaryPiece <$> decodePlainBinaryPiece n raw
+
+
+decodePlainBinaryPiece :: forall o. (Integral o, Bounded o, Storable o) => Int -> ByteString -> Either String (BinaryPiece o)
+decodePlainBinaryPiece n raw
+  | n < 0 || n > BS.length raw `quot` 4 = Left "Parquet.Read: invalid PLAIN BYTE_ARRAY count"
+  | n > binaryCountLimit @o = Left "Parquet.Read: BYTE_ARRAY offsets exceed address space"
+  | dataSize > binaryOffsetLimit @o = Left ("Parquet.Read: BYTE_ARRAY data exceeds " ++ binaryOffsetName @o)
+  | n == 0 = if BS.null raw then Right emptyBinaryPiece else Left "Parquet.Read: PLAIN BYTE_ARRAY count/size mismatch"
+  | otherwise = unsafePerformIO $ do
+      offsets <- VSM.unsafeNew (n + 1)
+      result <- BSUnsafe.unsafeUseAsCStringLen raw $ \(src, _) -> do
+        let go !i !sourceOffset !dataOffset
+              | i == n =
+                  if sourceOffset == BS.length raw && dataOffset == dataSize
+                    then VSM.unsafeWrite offsets n (fromIntegral dataOffset) *> pure (Right ())
+                    else pure (Left "Parquet.Read: PLAIN BYTE_ARRAY count/size mismatch")
+              | BS.length raw - sourceOffset < 4 = pure (Left "Parquet.Read: truncated PLAIN BYTE_ARRAY length")
+              | otherwise = do
+                  encodedSize <- binaryLengthAt (castPtr src) sourceOffset
+                  let !size = fromIntegral encodedSize :: Int
+                      !payload = sourceOffset + 4
+                  if size < 0 || size > BS.length raw - payload || size > dataSize - dataOffset
+                    then pure (Left "Parquet.Read: PLAIN BYTE_ARRAY payload out of bounds")
+                    else do
+                      VSM.unsafeWrite offsets i (fromIntegral dataOffset)
+                      go (i + 1) (payload + size) (dataOffset + size)
+        go 0 0 0
+      case result of
+        Left err -> pure (Left err)
+        Right () -> do
+          frozen <- VS.unsafeFreeze offsets
+          pure (Right (BinaryPiece frozen (BinaryPlain raw)))
+  where
+    !dataSize = BS.length raw - n * 4
+{-# INLINEABLE decodePlainBinaryPiece #-}
+
+
+-- The enclosing useAsCStringLen keeps the source alive. The caller checked
+-- all four bytes; individual byte loads also work on unaligned input slices.
+binaryLengthAt :: Ptr Word8 -> Int -> IO Word32
+binaryLengthAt bytes offset = do
+  a <- peekByteOff bytes offset :: IO Word8
+  b <- peekByteOff bytes (offset + 1) :: IO Word8
+  c <- peekByteOff bytes (offset + 2) :: IO Word8
+  d <- peekByteOff bytes (offset + 3) :: IO Word8
+  pure $!
+    fromIntegral a
+      .|. (fromIntegral b `shiftL` 8)
+      .|. (fromIntegral c `shiftL` 16)
+      .|. (fromIntegral d `shiftL` 24)
+{-# INLINE binaryLengthAt #-}
+
+
+-- Dictionaries are packed once when loaded, then shared by all data pages.
+-- Validate indices and expansion sizes while filling only offsets. No output
+-- payload is allocated until all selected pages passed their preflight.
+gatherBinaryPiece :: forall o. (Integral o, Bounded o, Storable o) => BinaryPiece o -> VP.Vector Int32 -> Either String (BinaryPiece o)
+gatherBinaryPiece dictionary indices
+  | VP.length indices > binaryCountLimit @o = Left "Parquet.Read: BYTE_ARRAY offsets exceed address space"
+  | otherwise = unsafePerformIO $ do
+      let !buffers = materializeBinaryPiece dictionary
+          !sourceOffsets = binaryOffsets buffers
+          !dictionaryCount = VS.length sourceOffsets - 1
+          !count = VP.length indices
+      offsets <- VSM.unsafeNew (count + 1)
+      let measure !i !total
+            | i == count = VSM.unsafeWrite offsets count (fromIntegral total) *> pure (Right ())
+            | key < 0 || key >= dictionaryCount = pure (Left "Parquet.Read: dictionary index out of range")
+            | size > binaryOffsetLimit @o - total = pure (Left ("Parquet.Read: dictionary output exceeds " ++ binaryOffsetName @o))
+            | otherwise = do
+                VSM.unsafeWrite offsets i (fromIntegral total)
+                measure (i + 1) (total + size)
+            where
+              key = fromIntegral (VP.unsafeIndex indices i) :: Int
+              size = fromIntegral (VS.unsafeIndex sourceOffsets (key + 1) - VS.unsafeIndex sourceOffsets key) :: Int
+      result <- measure 0 0
+      case result of
+        Left err -> pure (Left err)
+        Right () -> do
+          frozen <- VS.unsafeFreeze offsets
+          pure (Right (BinaryPiece frozen (BinaryDictionary buffers indices)))
+{-# INLINEABLE gatherBinaryPiece #-}
+
+
+data BinarySize = BinarySize
+  { binaryRows :: {-# UNPACK #-} !Int
+  , binaryBytes :: {-# UNPACK #-} !Int
+  }
+
+
+concatBinaryPieces :: forall o. (Integral o, Bounded o, Storable o) => [BinaryPiece o] -> Either String (BinaryPiece o)
+concatBinaryPieces [] = Right emptyBinaryPiece
+concatBinaryPieces pieces = do
+  size <- measure 0 0 pieces
+  let !totalRows = binaryRows size
+      !totalBytes = binaryBytes size
+  Right $!
+    unsafePerformIO
+      ( do
+          offsets <- VSM.unsafeNew (totalRows + 1)
+          let fill !_ !_ [] = VSM.unsafeWrite offsets totalRows (fromIntegral totalBytes)
+              fill !row !position (piece : rest) = do
+                let !source = pieceOffsets piece
+                    !n = VS.length source - 1
+                    copyOffsets !i
+                      | i == n = pure ()
+                      | otherwise = do
+                          VSM.unsafeWrite offsets (row + i) (fromIntegral position + VS.unsafeIndex source i)
+                          copyOffsets (i + 1)
+                copyOffsets 0
+                fill (row + n) (position + pieceBytes piece) rest
+          fill 0 0 pieces
+          frozen <- VS.unsafeFreeze offsets
+          pure (BinaryPiece frozen (BinaryJoined pieces))
+      )
+  where
+    measure !rows !bytes [] = Right (BinarySize rows bytes)
+    measure !rows !bytes (piece : rest)
+      | n > binaryCountLimit @o - rows = Left "Parquet.Read: BYTE_ARRAY offsets exceed address space"
+      | size > binaryOffsetLimit @o - bytes = Left ("Parquet.Read: BYTE_ARRAY data exceeds " ++ binaryOffsetName @o)
+      | otherwise = measure (rows + n) (bytes + size) rest
+      where
+        !n = VS.length (pieceOffsets piece) - 1
+        !size = pieceBytes piece
+{-# INLINEABLE concatBinaryPieces #-}
+
+
+-- DELTA encodings currently expose slices. Retain those slices until the
+-- final copy, just as PLAIN and dictionary pages retain their source buffers.
+packBinaryPiece :: forall o. (Integral o, Bounded o, Storable o) => V.Vector ByteString -> Either String (BinaryPiece o)
+packBinaryPiece values
+  | V.length values > binaryCountLimit @o = Left "Parquet.Read: BYTE_ARRAY offsets exceed address space"
+  | otherwise = unsafePerformIO $ do
+      let !count = V.length values
+      offsets <- VSM.unsafeNew (count + 1)
+      let measure !i !total
+            | i == count = VSM.unsafeWrite offsets count (fromIntegral total) *> pure (Right ())
+            | size > binaryOffsetLimit @o - total = pure (Left ("Parquet.Read: BYTE_ARRAY data exceeds " ++ binaryOffsetName @o))
+            | otherwise = do
+                VSM.unsafeWrite offsets i (fromIntegral total)
+                measure (i + 1) (total + size)
+            where
+              size = BS.length (V.unsafeIndex values i)
+      result <- measure 0 0
+      case result of
+        Left err -> pure (Left err)
+        Right () -> do
+          frozen <- VS.unsafeFreeze offsets
+          pure (Right (BinaryPiece frozen (BinaryBoxed values)))
+{-# INLINEABLE packBinaryPiece #-}
+
+
+materializeBinaryPiece :: forall o. (Integral o, Bounded o, Storable o) => BinaryPiece o -> BinaryBuffersOf o
+materializeBinaryPiece (BinaryPiece _ (BinaryPrepared dictionary)) = preparedBuffers dictionary
+materializeBinaryPiece (BinaryPiece offsets (BinaryContiguous bytes)) = BinaryBuffers offsets bytes
+materializeBinaryPiece piece = unsafePerformIO $ do
+  let !size = pieceBytes piece
+  output <- BSI.mallocByteString size
+  withForeignPtr output (copyBinaryPiece piece)
+  pure (BinaryBuffers (pieceOffsets piece) (BSI.fromForeignPtr output 0 size))
+{-# INLINEABLE materializeBinaryPiece #-}
+
+
+-- Every source span, index, offset and aggregate size was validated before
+-- this loop. No per-value ByteString wrappers or intermediate payload copies.
+copyBinaryPiece :: forall o. (Integral o, Bounded o, Storable o) => BinaryPiece o -> Ptr Word8 -> IO ()
+copyBinaryPiece piece dst
+  | pieceBytes piece == 0 = pure ()
+  | otherwise = case pieceSource piece of
+      BinaryPrepared dictionary ->
+        BSUnsafe.unsafeUseAsCStringLen (binaryData (preparedBuffers dictionary)) $ \(src, n) -> copyBytes dst (castPtr src) n
+      BinaryContiguous bytes ->
+        BSUnsafe.unsafeUseAsCStringLen bytes $ \(src, n) -> copyBytes dst (castPtr src) n
+      BinaryPlain raw ->
+        BSUnsafe.unsafeUseAsCStringLen raw $ \(src, _) -> do
+          let !offsets = pieceOffsets piece
+              !count = VS.length offsets - 1
+              fill !i !start
+                | i == count = pure ()
+                | otherwise = do
+                    let !end = fromIntegral (VS.unsafeIndex offsets (i + 1))
+                        !payload = start + (i + 1) * 4
+                    copyBytes (dst `plusPtr` start) (castPtr src `plusPtr` payload) (end - start)
+                    fill (i + 1) end
+          fill 0 0
+      BinaryDictionary (BinaryBuffers offsets bytes) indices ->
+        BSUnsafe.unsafeUseAsCStringLen bytes $ \(src, _) -> do
+          let !count = VP.length indices
+              fill !i !position
+                | i == count = pure ()
+                | otherwise = do
+                    let !key = fromIntegral (VP.unsafeIndex indices i)
+                        !start = fromIntegral (VS.unsafeIndex offsets key)
+                        !size = fromIntegral (VS.unsafeIndex offsets (key + 1)) - start
+                    copyBytes (dst `plusPtr` position) (castPtr src `plusPtr` start) size
+                    fill (i + 1) (position + size)
+          fill 0 0
+      BinaryBoxed values -> do
+        let !count = V.length values
+            fill !i !position
+              | i == count = pure ()
+              | otherwise = do
+                  let !bytes = V.unsafeIndex values i
+                  BSUnsafe.unsafeUseAsCStringLen bytes $ \(src, n) -> copyBytes (dst `plusPtr` position) (castPtr src) n
+                  fill (i + 1) (position + BS.length bytes)
+        fill 0 0
+      BinaryJoined pieces ->
+        let fill !_ [] = pure ()
+            fill !position (part : rest) = do
+              copyBinaryPiece part (dst `plusPtr` position)
+              fill (position + pieceBytes part) rest
+        in fill 0 pieces
+{-# INLINEABLE copyBinaryPiece #-}
+
+
+prepareBinaryDictionary :: forall o. (Integral o, Bounded o, Storable o) => BinaryPiece o -> Either String (BinaryPiece o)
+prepareBinaryDictionary piece =
+  let !buffers = materializeBinaryPiece piece
+      !offsets = binaryOffsets buffers
+      maximumSize !i !previous !maximumBytes
+        | i == VS.length offsets = maximumBytes
+        | otherwise =
+            let !next = fromIntegral (VS.unsafeIndex offsets i)
+            in maximumSize (i + 1) next (max maximumBytes (next - previous))
+      !largest = maximumSize 1 0 0
+  in Right (BinaryPiece offsets (BinaryPrepared (PreparedDictionary buffers largest)))
+
+
+decodeBinaryDictionary :: forall o. (Integral o, Bounded o, Storable o) => Int -> ByteString -> BinaryPiece o -> Either String (BinaryPiece o)
+decodeBinaryDictionary count bytes dictionary
+  | count < 0 = Left "Parquet.Read: negative dictionary value count"
+  | count == 0 = Right emptyBinaryPiece
+  | count > binaryCountLimit @o = Left "Parquet.Read: BYTE_ARRAY offsets exceed address space"
+  | VS.length (pieceOffsets dictionary) < 2 = Left "Parquet.Read: dictionary index out of range"
+  | otherwise = do
+      -- Most pages provably fit from count * maximum entry length. Only
+      -- potentially oversized pages need a streaming exact preflight,
+      -- before either decoded indices or expanded offsets are allocated.
+      let maximumBytes = case pieceSource dictionary of
+            BinaryPrepared prepared -> preparedMaxBytes prepared
+            _ -> pieceBytes dictionary
+      if maximumBytes /= 0 && count > binaryOffsetLimit @o `quot` maximumBytes
+        then validateDictionaryExpansionFor (binaryOffsetLimit @o) (pieceOffsets dictionary) count bytes
+        else Right ()
+      indices <- decodeDictionaryIndices count bytes
+      gatherBinaryPiece dictionary indices
+
+
+binaryOffsetLimit :: forall o. (Integral o, Bounded o) => Int
+binaryOffsetLimit = fromInteger (min (toInteger (maxBound :: o)) (toInteger (maxBound :: Int)))
+{-# INLINE binaryOffsetLimit #-}
+
+
+binaryCountLimit :: forall o. (Num o, Storable o) => Int
+binaryCountLimit = maxBound `quot` sizeOf (0 :: o) - 1
+{-# INLINE binaryCountLimit #-}
+
+
+binaryOffsetName :: forall o. (Num o, Storable o) => String
+binaryOffsetName = if sizeOf (0 :: o) == 4 then "32-bit offsets; request LargeUtf8/LargeBinary for larger columns" else "64-bit offsets"
+{-# INLINE binaryOffsetName #-}
+
+
+{-# SPECIALIZE emptyBinaryPiece :: BinaryPiece Int32 #-}
+{-# SPECIALIZE emptyBinaryPiece :: BinaryPiece Int64 #-}
+
+
+{-# SPECIALIZE pieceBytes :: BinaryPiece Int32 -> Int #-}
+{-# SPECIALIZE pieceBytes :: BinaryPiece Int64 -> Int #-}
+
+
+{-# SPECIALIZE decodePlainBinaryPiece :: Int -> ByteString -> Either String (BinaryPiece Int32) #-}
+{-# SPECIALIZE decodePlainBinaryPiece :: Int -> ByteString -> Either String (BinaryPiece Int64) #-}
+
+
+{-# SPECIALIZE gatherBinaryPiece :: BinaryPiece Int32 -> VP.Vector Int32 -> Either String (BinaryPiece Int32) #-}
+{-# SPECIALIZE gatherBinaryPiece :: BinaryPiece Int64 -> VP.Vector Int32 -> Either String (BinaryPiece Int64) #-}
+
+
+{-# SPECIALIZE concatBinaryPieces :: [BinaryPiece Int32] -> Either String (BinaryPiece Int32) #-}
+{-# SPECIALIZE concatBinaryPieces :: [BinaryPiece Int64] -> Either String (BinaryPiece Int64) #-}
+
+
+{-# SPECIALIZE packBinaryPiece :: V.Vector ByteString -> Either String (BinaryPiece Int32) #-}
+{-# SPECIALIZE packBinaryPiece :: V.Vector ByteString -> Either String (BinaryPiece Int64) #-}
+
+
+{-# SPECIALIZE materializeBinaryPiece :: BinaryPiece Int32 -> BinaryBuffersOf Int32 #-}
+{-# SPECIALIZE materializeBinaryPiece :: BinaryPiece Int64 -> BinaryBuffersOf Int64 #-}
+
+
+{-# SPECIALIZE copyBinaryPiece :: BinaryPiece Int32 -> Ptr Word8 -> IO () #-}
+{-# SPECIALIZE copyBinaryPiece :: BinaryPiece Int64 -> Ptr Word8 -> IO () #-}
+
+
+{-# SPECIALIZE prepareBinaryDictionary :: BinaryPiece Int32 -> Either String (BinaryPiece Int32) #-}
+{-# SPECIALIZE prepareBinaryDictionary :: BinaryPiece Int64 -> Either String (BinaryPiece Int64) #-}
+
+
+{-# SPECIALIZE decodeBinaryDictionary :: Int -> ByteString -> BinaryPiece Int32 -> Either String (BinaryPiece Int32) #-}
+{-# SPECIALIZE decodeBinaryDictionary :: Int -> ByteString -> BinaryPiece Int64 -> Either String (BinaryPiece Int64) #-}
+
+
+-- | Read a column chunk with optional @DICTIONARY_PAGE@ + @PLAIN_DICTIONARY@
+-- data pages, supporting definition\/repetition levels.
+--
+-- @decodeDictValues@: decodes PLAIN dictionary page body into a container.
+-- @lookupDict@: retrieves a value by dictionary index (returns 'Nothing' if
+-- the index is out of range).
+{-# INLINE readDictionaryOptionalColumnChunk #-}
+readDictionaryOptionalColumnChunk ::
+  (Int -> ByteString -> Either String dict) ->
+  (dict -> Int32 -> Maybe a) ->
+  Compression -> Int -> Int -> ByteString ->
+  Either String (V.Vector (Maybe a))
+readDictionaryOptionalColumnChunk decodeDictValues lookupDict codec maxRep maxDef chunk =
+  go 0 Nothing []
+  where
+    go !off !mDict !acc
+      | off >= BS.length chunk = Right (concatPages V.concat acc)
+      | otherwise = do
+          (hdr, afterHdr) <- readPageHeaderCheckedAt chunk off
+          compSz <- case phCompressedPageSize hdr of
+            Nothing -> Left "Parquet.Read: missing compressed_page_size"
+            Just s -> Right (fromIntegral s :: Int)
+          let !bodyStart = afterHdr
+          if bodyStart + compSz > BS.length chunk
+            then Left "Parquet.Read: truncated page body"
+            else do
+              let !compBody = BS.take compSz (BS.drop bodyStart chunk)
+              checkDictionaryPagePosition off hdr
+              !raw <- decompressPageData codec (phUncompressedPageSize hdr) compBody
+              let !nextOff = bodyStart + compSz
+              case phType hdr of
+                PtDictionaryPage dk
+                  | not (dictEncoding dk == encPlain || dictEncoding dk == encPlainDictionary) ->
+                      Left "Parquet.Read: dictionary page encoding is neither PLAIN (0) nor PLAIN_DICTIONARY (2)"
+                  | otherwise -> do
+                      let !nDict = fromIntegral (dictNumValues dk) :: Int
+                      dict <- decodeDictValues nDict raw
+                      go nextOff (Just dict) acc
+                PtDataPage dph
+                  | not (isDictionaryEncoding (dphEncoding dph)) ->
+                      Left "Parquet.Read: expected PLAIN_DICTIONARY or RLE_DICTIONARY encoding for dictionary optional column"
+                  | otherwise -> do
+                      dict0 <- case mDict of
+                        Nothing ->
+                          Left "Parquet.Read: PLAIN_DICTIONARY data page before dictionary page"
+                        Just d -> Right d
+                      let !n = fromIntegral (dphNumValues dph) :: Int
+                      (_rep, def, rest) <- parseDataPageV1Levels maxRep maxDef n raw
+                      let !maxD = fromIntegral maxDef :: Int32
+                          !nDefined = VP.foldl' (\a d -> if d == maxD then a + 1 else a) 0 def
+                      ix <- decodeDictionaryIndices nDefined rest
+                      page <- materializeDictOptional def maxDef ix dict0 lookupDict
+                      go nextOff mDict (page : acc)
+                _ -> Left "Parquet.Read: expected DICTIONARY_PAGE or DATA_PAGE"
+
+materializeDictOptional ::
+  VP.Vector Int32 ->
+  Int ->
+  VP.Vector Int32 ->
+  dict ->
+  (dict -> Int32 -> Maybe a) ->
+  Either String (V.Vector (Maybe a))
+materializeDictOptional defs maxDef indices dict lookupDict =
+  let !n = VP.length defs
+      !maxD = fromIntegral maxDef :: Int32
+      go !acc !i !ixPos
+        | i >= n =
+            if ixPos == VP.length indices
+              then Right acc
+              else Left "Parquet.Read: unconsumed dictionary indices"
+        | otherwise =
+            let !d = VP.unsafeIndex defs i
+            in if d == maxD
+              then
+                if ixPos >= VP.length indices
+                  then Left "Parquet.Read: ran out of dictionary indices"
+                  else
+                    let !idx = VP.unsafeIndex indices ixPos
+                    in case lookupDict dict idx of
+                      Nothing -> Left "Parquet.Read: dictionary index out of range"
+                      Just v -> go (Just v : acc) (i + 1) (ixPos + 1)
+              else go (Nothing : acc) (i + 1) ixPos
+  in case go [] 0 0 of
+    Left e -> Left e
+    Right xs -> Right $! V.fromList (reverse xs)
+
+-- | Specialized dictionary optional reader for @INT32@ columns.
+readDictionaryInt32OptionalColumnChunk ::
+  Compression -> Int -> Int -> ByteString -> Either String (V.Vector (Maybe Int32))
+readDictionaryInt32OptionalColumnChunk =
+  readDictionaryOptionalColumnChunk decodePlainInt32 vpLookupInt32
+  where
+    vpLookupInt32 :: VP.Vector Int32 -> Int32 -> Maybe Int32
+    vpLookupInt32 v idx =
+      let !i = fromIntegral idx :: Int
+      in if i >= 0 && i < VP.length v
+        then Just (VP.unsafeIndex v i)
+        else Nothing
+
+-- | Decompress a @DATA_PAGE_V2@ body. In v2 the repetition\/definition levels
+-- are stored uncompressed before the (optionally compressed) values section.
+{-# INLINE decompressDataPageV2Body #-}
+decompressDataPageV2Body ::
+  Compression ->
+  Int ->
+  Int ->
+  ByteString ->
+  Int ->
+  Either String (PageHeader, DataPageHeaderV2, VP.Vector Int32, VP.Vector Int32, ByteString, Int)
+decompressDataPageV2Body codec maxRep maxDef chunk off = do
+  (hdr, afterHdr) <- readPageHeaderCheckedAt chunk off
+  dph2 <- case phType hdr of
+    PtDataPageV2 d -> Right d
+    _              -> Left "Parquet.Read: expected DATA_PAGE_V2"
+  do
+      compSz <- case phCompressedPageSize hdr of
+        Nothing -> Left "Parquet.Read: missing compressed_page_size"
+        Just s -> Right (fromIntegral s :: Int)
+      let !bodyStart = afterHdr
+      if bodyStart + compSz > BS.length chunk
+        then Left "Parquet.Read: truncated page v2 body"
+        else do
+          let !body = BS.take compSz (BS.drop bodyStart chunk)
+              !repLen = fromIntegral (dph2RepLevelsLen dph2) :: Int
+              !defLen = fromIntegral (dph2DefLevelsLen dph2) :: Int
+              !levelsLen = repLen + defLen
+          if levelsLen > BS.length body
+            then Left "Parquet.Read: v2 levels exceed body size"
+            else do
+              let !numValues = fromIntegral (dph2NumValues dph2) :: Int
+                  !repBs = BS.take repLen body
+                  !defBs = BS.take defLen (BS.drop repLen body)
+                  !valuesSection = BS.drop levelsLen body
+                  !bwRep = levelBitWidth maxRep
+                  !bwDef = levelBitWidth maxDef
+              repLevels <- if repLen == 0
+                then Right (VP.replicate numValues 0)
+                else decodeHybridRleUnsigned32 bwRep numValues repBs
+              defLevels <- if defLen == 0
+                then Right (VP.replicate numValues 0)
+                else decodeHybridRleUnsigned32 bwDef numValues defBs
+              !values <- decompressV2Values codec hdr dph2 valuesSection
+              let !nextOff = bodyStart + compSz
+              Right (hdr, dph2, repLevels, defLevels, values, nextOff)
+
+readLE32 :: ByteString -> Int -> Word32
+readLE32 bs o =
+  let b0 = fromIntegral (BS.index bs o) :: Word32
+      b1 = fromIntegral (BS.index bs (o + 1)) :: Word32
+      b2 = fromIntegral (BS.index bs (o + 2)) :: Word32
+      b3 = fromIntegral (BS.index bs (o + 3)) :: Word32
+  in b0 .|. (b1 `shiftL` 8) .|. (b2 `shiftL` 16) .|. (b3 `shiftL` 24)
+
+#if defined(WORDS_BIGENDIAN)
+readLE64 :: ByteString -> Int -> Word64
+readLE64 bs o =
+  let w0 = fromIntegral (readLE32 bs o) :: Word64
+      w1 = fromIntegral (readLE32 bs (o + 4)) :: Word64
+  in w0 .|. (w1 `shiftL` 32)
+#endif
+
+-- | @PLAIN@ @INT96@ — each value is 12 raw bytes, returned as 'ByteString'.
+{-# INLINE decodePlainInt96 #-}
+decodePlainInt96 :: Int -> ByteString -> Either String (V.Vector ByteString)
+decodePlainInt96 n bs
+  | n < 0 || n > BS.length bs `quot` 12 = Left "Parquet.Read: PLAIN INT96 buffer too small"
+  | otherwise = Right $! V.generate n $ \i ->
+      BS.take 12 (BS.drop (i * 12) bs)
+
+-- | @PLAIN@ @FIXED_LEN_BYTE_ARRAY@ — each value is @typeLen@ raw bytes.
+{-# INLINE decodePlainFixedLenByteArray #-}
+decodePlainFixedLenByteArray :: Int -> Int -> ByteString -> Either String (V.Vector ByteString)
+decodePlainFixedLenByteArray typeLen n bs
+  | typeLen <= 0 = Left "Parquet.Read: FIXED_LEN_BYTE_ARRAY type_length must be positive"
+  | n < 0 || n > BS.length bs `quot` typeLen = Left "Parquet.Read: PLAIN FIXED_LEN_BYTE_ARRAY buffer too small"
+  | otherwise = Right $! V.generate n $ \i ->
+      BS.take typeLen (BS.drop (i * typeLen) bs)
+
+-- | All @DATA_PAGE@s as @PLAIN@ @INT96@.
+readPlainInt96ColumnChunk :: Compression -> ByteString -> Either String (V.Vector ByteString)
+readPlainInt96ColumnChunk codec chunk = go 0 []
+  where
+    go !off !acc
+      | off >= BS.length chunk = Right (concatPages V.concat acc)
+      | otherwise = do
+          (_hdr, dph, raw, nextOff) <- decompressDataPageBody codec chunk off
+          if dphEncoding dph /= encPlain
+            then Left "Parquet.Read: encoding is not PLAIN (0)"
+            else do
+              let !n = fromIntegral (dphNumValues dph) :: Int
+              pageVec <- decodePlainInt96 n raw
+              go nextOff (pageVec : acc)
+
+-- | All @DATA_PAGE@s as @PLAIN@ @FIXED_LEN_BYTE_ARRAY@ with given type length.
+readPlainFixedLenByteArrayColumnChunk :: Int -> Compression -> ByteString -> Either String (V.Vector ByteString)
+readPlainFixedLenByteArrayColumnChunk typeLen codec chunk = go 0 []
+  where
+    go !off !acc
+      | off >= BS.length chunk = Right (concatPages V.concat acc)
+      | otherwise = do
+          (_hdr, dph, raw, nextOff) <- decompressDataPageBody codec chunk off
+          if dphEncoding dph /= encPlain
+            then Left "Parquet.Read: encoding is not PLAIN (0)"
+            else do
+              let !n = fromIntegral (dphNumValues dph) :: Int
+              pageVec <- decodePlainFixedLenByteArray typeLen n raw
+              go nextOff (pageVec : acc)
+
+-- | @BYTE_STREAM_SPLIT@ for @FLOAT@: bytes are transposed into 4 runs of N bytes.
+{-# INLINE decodeByteStreamSplitFloat #-}
+decodeByteStreamSplitFloat :: Int -> ByteString -> Either String (VP.Vector Float)
+decodeByteStreamSplitFloat n bs
+  | n < 0 || n > BS.length bs `quot` 4 = Left "Parquet.Read: BYTE_STREAM_SPLIT FLOAT buffer too small"
+  | n >= 16 && targetByteOrder == LittleEndian =
+      Right $ decodeByteStreamSplitNative 4 SIMD.joinByteStreams4Array SIMD.joinByteStreams4 n bs
+  | otherwise =
+      Right $
+        runST $ do
+          mv <- MVP.new n
+          let go2 !i
+                | i >= n = VP.unsafeFreeze mv
+                | otherwise = do
+                    let !b0 = fromIntegral (BS.index bs i) :: Word32
+                        !b1 = fromIntegral (BS.index bs (n + i)) :: Word32
+                        !b2 = fromIntegral (BS.index bs (2 * n + i)) :: Word32
+                        !b3 = fromIntegral (BS.index bs (3 * n + i)) :: Word32
+                        !w = b0 .|. (b1 `shiftL` 8) .|. (b2 `shiftL` 16) .|. (b3 `shiftL` 24)
+                    MVP.write mv i (castWord32ToFloat w)
+                    go2 (i + 1)
+          go2 0
+
+-- | @BYTE_STREAM_SPLIT@ for @DOUBLE@: bytes are transposed into 8 runs of N bytes.
+{-# INLINE decodeByteStreamSplitDouble #-}
+decodeByteStreamSplitDouble :: Int -> ByteString -> Either String (VP.Vector Double)
+decodeByteStreamSplitDouble n bs
+  | n < 0 || n > BS.length bs `quot` 8 = Left "Parquet.Read: BYTE_STREAM_SPLIT DOUBLE buffer too small"
+  | n >= 16 && targetByteOrder == LittleEndian =
+      Right $ decodeByteStreamSplitNative 8 SIMD.joinByteStreams8Array SIMD.joinByteStreams8 n bs
+  | otherwise =
+      Right $
+        runST $ do
+          mv <- MVP.new n
+          let go2 !i
+                | i >= n = VP.unsafeFreeze mv
+                | otherwise = do
+                    let !b0 = fromIntegral (BS.index bs i) :: Word64
+                        !b1 = fromIntegral (BS.index bs (n + i)) :: Word64
+                        !b2 = fromIntegral (BS.index bs (2 * n + i)) :: Word64
+                        !b3 = fromIntegral (BS.index bs (3 * n + i)) :: Word64
+                        !b4 = fromIntegral (BS.index bs (4 * n + i)) :: Word64
+                        !b5 = fromIntegral (BS.index bs (5 * n + i)) :: Word64
+                        !b6 = fromIntegral (BS.index bs (6 * n + i)) :: Word64
+                        !b7 = fromIntegral (BS.index bs (7 * n + i)) :: Word64
+                        !w = b0 .|. (b1 `shiftL` 8) .|. (b2 `shiftL` 16) .|. (b3 `shiftL` 24)
+                              .|. (b4 `shiftL` 32) .|. (b5 `shiftL` 40) .|. (b6 `shiftL` 48) .|. (b7 `shiftL` 56)
+                    MVP.write mv i (castWord64ToDouble w)
+                    go2 (i + 1)
+          go2 0
+
+
+-- The caller proves width*n fits inside the input. A bounded unsafe call
+-- can fill an ordinary mutable array without allowing GC to move it.
+-- Larger outputs are explicitly pinned for the safe call; freezing after
+-- the call keeps their owner alive throughout C's writes.
+decodeByteStreamSplitNative
+  :: Prim a
+  => Int
+  -> (Ptr Word8 -> MutableByteArray RealWorld -> Int -> IO ())
+  -> (Ptr Word8 -> Ptr Word8 -> Int -> IO ())
+  -> Int
+  -> ByteString
+  -> VP.Vector a
+decodeByteStreamSplitNative width joinArray join n bs = unsafePerformIO $
+  if n <= SIMD.unsafeCallBytes `quot` width
+    then do
+      mv@(MVP.MVector _ _ bytes) <- MVP.unsafeNew n
+      BSUnsafe.unsafeUseAsCString bs $ \src -> joinArray (castPtr src) bytes n
+      VP.unsafeFreeze mv
+    else do
+      bytes <- newPinnedByteArray (width * n)
+      BSUnsafe.unsafeUseAsCString bs $ \src -> join (castPtr src) (mutableByteArrayContents bytes) n
+      VP.unsafeFreeze (MVP.MVector 0 n bytes)
+{-# INLINE decodeByteStreamSplitNative #-}
+
+-- ============================================================
+-- Generic per-page chunk dispatch
+-- ============================================================
+
+-- | Encoding tags used by the generic dispatch.
+encDeltaBinaryPacked, encDeltaLengthByteArray, encDeltaByteArray, encByteStreamSplit, encAlp :: Int32
+encDeltaBinaryPacked     = 5
+encDeltaLengthByteArray  = 6
+encDeltaByteArray        = 7
+encByteStreamSplit       = 9
+encAlp                   = 10
+
+-- | Dispatcher type: per-page decoder produces a chunk of values
+-- of the type the caller asked for.
+data PerPage a = PerPage
+  { ppDecodePlain :: !(Int -> ByteString -> Either String a)
+    -- ^ Decode a PLAIN-encoded page body into a chunk of length n.
+  , ppPrepareDictionary :: !(a -> Either String a)
+    -- ^ Materialize a reusable dictionary once, before caching it.
+  , ppDecodeDictionary :: !(Int -> ByteString -> a -> Either String a)
+    -- ^ Decode dictionary indices and look up their values. Keeping raw
+    -- indices here allows output-size preflight before index allocation.
+  , ppExtended :: !(Int32 -> Int -> ByteString -> Either String a)
+    -- ^ Encoding-specific decoders (delta / byte-stream-split).
+    -- @ppExtended encoding numValues body@ — return Left if the
+    -- encoding is genuinely unsupported for this physical type.
+  , ppConcat :: !([a] -> Either String a)
+  , ppEmpty :: !a
+  }
+
+-- | Walk every page in a column chunk; for each DATA_PAGE /
+-- DATA_PAGE_V2, dispatch on its encoding via the supplied
+-- 'PerPage' record. DICTIONARY_PAGE pages are decoded once with
+-- 'ppDecodePlain' and held for reuse by RLE_DICTIONARY pages.
+-- Accumulate page-sized pieces and copy once. In particular, avoid copying
+-- a growing column on every page; the singleton path retains its buffer.
+concatPages :: ([a] -> a) -> [a] -> a
+concatPages _ [page] = page
+concatPages combine pages = combine (reverse pages)
+{-# INLINE concatPages #-}
+
+concatValuePages :: PerPage a -> [a] -> Either String a
+concatValuePages _ [page] = Right page
+concatValuePages pp pages = ppConcat pp (reverse pages)
+{-# INLINE concatValuePages #-}
+
+-- A chunk may contain one dictionary, before all data pages. Check before
+-- decompressing a dictionary body, including in the legacy chunk readers.
+checkDictionaryPagePosition :: Int -> PageHeader -> Either String ()
+checkDictionaryPagePosition offset header = case phType header of
+  PtDictionaryPage _ | offset /= 0 -> Left "Parquet.Read: dictionary must be the first and only dictionary page in a column"
+  _ -> Right ()
+{-# INLINE checkDictionaryPagePosition #-}
+
+genericReadColumnChunk
+  :: PerPage a
+  -> Compression
+  -> ByteString
+  -> Either String a
+genericReadColumnChunk pp codec chunk0 = go 0 Nothing []
+  where
+    go !off !mDict !acc
+      | off >= BS.length chunk0 = concatValuePages pp acc
+      | otherwise = do
+          (hdr, afterHdr) <- readPageHeaderCheckedAt chunk0 off
+          checkDictionaryPagePosition off hdr
+          compSz <- case phCompressedPageSize hdr of
+            Nothing -> Left "Parquet.Read: missing compressed_page_size"
+            Just s -> Right (fromIntegral s :: Int)
+          let !bodyStart = afterHdr
+          if bodyStart + compSz > BS.length chunk0
+            then Left "Parquet.Read: truncated page body"
+            else do
+              let !compBody = BS.take compSz (BS.drop bodyStart chunk0)
+                  !nextOff = bodyStart + compSz
+              case phType hdr of
+                PtDictionaryPage dk
+                  | not (dictEncoding dk == encPlain || dictEncoding dk == encPlainDictionary) ->
+                      Left "Parquet.Read: dictionary page encoding is neither PLAIN (0) nor PLAIN_DICTIONARY (2)"
+                  | otherwise -> do
+                      raw <- decompressPageData codec
+                               (phUncompressedPageSize hdr) compBody
+                      let !nDict = fromIntegral (dictNumValues dk) :: Int
+                      dict <- ppDecodePlain pp nDict raw >>= ppPrepareDictionary pp
+                      go nextOff (Just dict) acc
+                PtDataPage dph -> do
+                  raw <- decompressPageData codec
+                           (phUncompressedPageSize hdr) compBody
+                  let !n = fromIntegral (dphNumValues dph) :: Int
+                  pageVec <- decodeDataPage pp mDict (dphEncoding dph) n raw
+                  go nextOff mDict (pageVec : acc)
+                PtDataPageV2 dph2 -> do
+                  -- V2 page body is: rep_levels ++ def_levels ++ values.
+                  -- For required (max_def=0) flat columns the level
+                  -- streams are zero bytes. Skip them and decode the
+                  -- values section under the page's encoding.
+                  let !repLen = fromIntegral (dph2RepLevelsLen dph2) :: Int
+                      !defLen = fromIntegral (dph2DefLevelsLen dph2) :: Int
+                      !levelsLen = repLen + defLen
+                      !body = compBody
+                  if levelsLen > BS.length body
+                    then Left "Parquet.Read: V2 levels exceed body size"
+                    else do
+                      let !valuesSection = BS.drop levelsLen body
+                      values <- decompressV2Values codec hdr dph2 valuesSection
+                      let !n = fromIntegral (dph2NumValues dph2) :: Int
+                      pageVec <-
+                        decodeDataPage pp mDict (dph2Encoding dph2) n values
+                      go nextOff mDict (pageVec : acc)
+                _ -> Left "Parquet.Read: expected DATA_PAGE / DATA_PAGE_V2 / DICTIONARY_PAGE"
+
+    decodeDataPage pp' mDict !enc !n !raw
+      | enc == encPlain = ppDecodePlain pp' n raw
+      | isDictionaryEncoding enc = case mDict of
+          Nothing ->
+            Left "Parquet.Read: RLE_DICTIONARY page before dictionary page"
+          Just dict -> ppDecodeDictionary pp' n raw dict
+      | otherwise = ppExtended pp' enc n raw
+
+-- ============================================================
+-- Per-physical-type dispatchers
+-- ============================================================
+
+dispatchInt32 :: PerPage (VP.Vector Int32)
+dispatchInt32 = PerPage
+  { ppDecodePlain  = decodePlainInt32
+  , ppPrepareDictionary = Right
+  , ppDecodeDictionary = \n raw dict -> decodeDictionaryIndices n raw >>= dictLookupVP dict
+  , ppExtended = \enc n raw ->
+      if enc == encDeltaBinaryPacked
+        then decodeDeltaBinaryPackedInt32 n raw
+        else if enc == encByteStreamSplit
+          then decodeByteStreamSplitRaw 4 n raw >>= decodePlainInt32 n
+        else Left $ unsupportedEncoding "INT32" enc
+  , ppConcat = Right . VP.concat
+  , ppEmpty = VP.empty
+  }
+
+dispatchInt64 :: PerPage (VP.Vector Int64)
+dispatchInt64 = PerPage
+  { ppDecodePlain  = decodePlainInt64
+  , ppPrepareDictionary = Right
+  , ppDecodeDictionary = \n raw dict -> decodeDictionaryIndices n raw >>= dictLookupVP dict
+  , ppExtended = \enc n raw ->
+      if enc == encDeltaBinaryPacked
+        then decodeDeltaBinaryPackedInt64 n raw
+        else if enc == encByteStreamSplit
+          then decodeByteStreamSplitRaw 8 n raw >>= decodePlainInt64 n
+        else Left $ unsupportedEncoding "INT64" enc
+  , ppConcat = Right . VP.concat
+  , ppEmpty = VP.empty
+  }
+
+dispatchFloat :: PerPage (VP.Vector Float)
+dispatchFloat = PerPage
+  { ppDecodePlain = decodePlainFloat
+  , ppPrepareDictionary = Right
+  , ppDecodeDictionary = \n raw dict -> decodeDictionaryIndices n raw >>= dictLookupVP dict
+  , ppExtended = \enc n raw ->
+      if enc == encByteStreamSplit
+        then decodeByteStreamSplitFloat n raw
+        else if enc == encAlp
+          then decodeAlpFloat n raw
+        else Left $ unsupportedEncoding "FLOAT" enc
+  , ppConcat = Right . VP.concat
+  , ppEmpty = VP.empty
+  }
+
+dispatchDouble :: PerPage (VP.Vector Double)
+dispatchDouble = PerPage
+  { ppDecodePlain = decodePlainDouble
+  , ppPrepareDictionary = Right
+  , ppDecodeDictionary = \n raw dict -> decodeDictionaryIndices n raw >>= dictLookupVP dict
+  , ppExtended = \enc n raw ->
+      if enc == encByteStreamSplit
+        then decodeByteStreamSplitDouble n raw
+        else if enc == encAlp
+          then decodeAlpDouble n raw
+        else Left $ unsupportedEncoding "DOUBLE" enc
+  , ppConcat = Right . VP.concat
+  , ppEmpty = VP.empty
+  }
+
+dispatchBool :: PerPage (V.Vector Bool)
+dispatchBool = PerPage
+  { ppDecodePlain = decodePlainBool
+  , ppPrepareDictionary = Right
+  , ppDecodeDictionary = \n raw dict -> decodeDictionaryIndices n raw >>= dictLookupV dict
+  , ppExtended = \enc n raw ->
+      if enc == encRle
+        -- BOOLEAN with RLE encoding: the values section is a
+        -- length-prefixed hybrid RLE block (4-byte LE length
+        -- prefix, then bit-packed/RLE 1-bit values). Common
+        -- shape for both DATA_PAGE_V2 BOOLEAN columns and any
+        -- writer that picks RLE explicitly for BOOLEAN.
+        then do
+          bits <- decodeHybridRleBoolean n raw
+          Right $! unpackBitsLsbUnsafe n bits
+        else Left $ unsupportedEncoding "BOOLEAN" enc
+  , ppConcat = Right . V.concat
+  , ppEmpty = V.empty
+  }
+
+
+-- | Checked, LSB-first BOOLEAN values. The constructor stays private;
+-- unused high bits are not values, and counts need not be byte-aligned.
+data BoolBuffers = BoolBuffers
+  { boolCount :: {-# UNPACK #-} !Int
+  , boolData :: !ByteString
+  }
+
+
+data BoolPiece = BoolPiece {-# UNPACK #-} !Int !BoolSource
+
+
+data BoolSource = BoolPlain !ByteString | BoolJoined ![BoolPiece]
+
+
+boolPieceCount :: BoolPiece -> Int
+boolPieceCount (BoolPiece count _) = count
+
+
+boolByteCount :: Int -> Int
+boolByteCount n = let (!whole, !tailBits) = n `quotRem` 8 in whole + if tailBits == 0 then 0 else 1
+{-# INLINE boolByteCount #-}
+
+
+decodePlainBoolPiece :: Int -> ByteString -> Either String BoolPiece
+decodePlainBoolPiece count raw
+  | count < 0 = Left "Parquet.Read: PLAIN BOOLEAN negative value count"
+  | boolByteCount count > BS.length raw = Left "Parquet.Read: PLAIN BOOLEAN buffer too small"
+  | otherwise = Right (BoolPiece count (BoolPlain (BS.take (boolByteCount count) raw)))
+
+
+concatBoolPieces :: [BoolPiece] -> Either String BoolPiece
+concatBoolPieces pieces = do
+  count <- total 0 pieces
+  Right (BoolPiece count (BoolJoined pieces))
+  where
+    total !count [] = Right count
+    total !count (piece : rest)
+      | boolPieceCount piece > maxBound - count = Left "Parquet.Read: BOOLEAN column exceeds address space"
+      | otherwise = total (count + boolPieceCount piece) rest
+
+
+materializeBool :: BoolPiece -> BoolBuffers
+materializeBool (BoolPiece count source) = BoolBuffers count $ case source of
+  BoolPlain bytes -> bytes
+  BoolJoined pieces -> unsafePerformIO $ BSI.create (boolByteCount count) $ \target -> do
+    fillBytes target 0 (boolByteCount count)
+    let fill !offset (BoolPiece n current) = case current of
+          BoolPlain bytes -> BSUnsafe.unsafeUseAsCString bytes $ \ptr -> copyBits target offset (castPtr ptr) 0 n
+          BoolJoined parts -> each offset parts
+        each !_ [] = pure ()
+        each !offset (piece : rest) = fill offset piece >> each (offset + boolPieceCount piece) rest
+    each 0 pieces
+{-# NOINLINE materializeBool #-}
+
+
+decodeBoolDictionary :: Int -> ByteString -> BoolPiece -> Either String BoolPiece
+decodeBoolDictionary count raw dictionary = do
+  indices <- decodeDictionaryIndices count raw
+  if VP.any (\key -> key < 0 || fromIntegral key >= boolPieceCount dictionary) indices
+    then Left "Parquet.Read: BOOLEAN dictionary index out of range"
+    else
+      let values = boolData (materializeBool dictionary)
+          packed = packBoolIndices values indices
+      in Right (BoolPiece count (BoolPlain packed))
+
+
+packBoolIndices :: ByteString -> VP.Vector Int32 -> ByteString
+packBoolIndices values indices = unsafePerformIO $ BSI.create (boolByteCount count) $ \target -> do
+  let byte !row !lane !acc
+        | row == count || lane == 8 = acc
+        | otherwise =
+            let key = fromIntegral (VP.unsafeIndex indices row)
+                (!byteIndex, !bitIndex) = key `quotRem` 8
+                bit = (BSUnsafe.unsafeIndex values byteIndex `shiftR` bitIndex) .&. 1
+            in byte (row + 1) (lane + 1) (acc .|. (bit `shiftL` lane))
+      loop !row
+        | row == count = pure ()
+        | otherwise = do
+            let !value = byte row 0 (0 :: Word8)
+            pokeByteOff target (row `quot` 8) value
+            loop (row + min 8 (count - row))
+  loop 0
+  where
+    count = VP.length indices
+{-# NOINLINE packBoolIndices #-}
+
+
+dispatchBoolPieces :: PerPage BoolPiece
+dispatchBoolPieces = PerPage
+  { ppDecodePlain = decodePlainBoolPiece
+  , ppPrepareDictionary = Right
+  , ppDecodeDictionary = decodeBoolDictionary
+  , ppExtended = \encoding count raw ->
+      if encoding == encRle
+        then BoolPiece count . BoolPlain <$> decodeHybridRleBoolean count raw
+        else Left (unsupportedEncoding "BOOLEAN" encoding)
+  , ppConcat = concatBoolPieces
+  , ppEmpty = BoolPiece 0 (BoolPlain BS.empty)
+  }
+
+
+-- | Keep PLAIN and RLE BOOLEAN pages packed, joining arbitrary bit tails.
+readBoolBuffersColumnChunk :: Compression -> ByteString -> Either String BoolBuffers
+readBoolBuffersColumnChunk codec chunk = materializeBool <$> genericReadColumnChunk dispatchBoolPieces codec chunk
+
+
+readBoolBuffersLevels :: Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels BoolBuffers)
+readBoolBuffersLevels codec maxRep maxDef chunk = materializeBoolLevels <$> readLevelsColumnChunk dispatchBoolPieces codec maxRep maxDef chunk
+
+
+readBoolBuffersSelectedValues :: Compression -> ByteString -> PageSelection -> Either String BoolBuffers
+readBoolBuffersSelectedValues codec file selection = materializeBool <$> readSelectedValues dispatchBoolPieces codec file selection
+
+
+readBoolBuffersSelectedLevels :: Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels BoolBuffers)
+readBoolBuffersSelectedLevels codec maxRep maxDef file selection = materializeBoolLevels <$> readSelectedLevels dispatchBoolPieces codec maxRep maxDef file selection
+
+
+materializeBoolLevels :: ColumnLevels BoolPiece -> ColumnLevels BoolBuffers
+materializeBoolLevels levels = ColumnLevels (clRepetition levels) (clDefinition levels) (materializeBool (clValues levels))
+
+{- | Checked dense scalars in native byte order. The private constructor
+guarantees whole 4- or 8-byte values; Arrow aligns the final buffer if needed.
+-}
+newtype ScalarBuffers = ScalarBuffers {scalarData :: ByteString}
+
+
+data ScalarPiece = ScalarPiece
+  { scalarCount :: {-# UNPACK #-} !Int
+  , scalarSource :: !ScalarSource
+  }
+
+
+data ScalarSource
+  = ScalarPlain !ByteString
+  | ScalarDictionary !ByteString !(VP.Vector Int32)
+  | ScalarJoined ![ScalarPiece]
+
+
+-- Keep source pages until the entire output size is checked. PLAIN pages
+-- need no intermediate value vector; dictionary gathers write the final
+-- column directly rather than materializing a vector for each data page.
+scalarDispatcher :: ParquetType -> Either String (PerPage ScalarPiece)
+scalarDispatcher physical = case physical of
+  PTInt32 -> Right (dispatchScalar 4 dispatchInt32)
+  PTInt64 -> Right (dispatchScalar 8 dispatchInt64)
+  PTFloat -> Right (dispatchScalar 4 dispatchFloat)
+  PTDouble -> Right (dispatchScalar 8 dispatchDouble)
+  _ -> Left "Parquet.Read: scalar buffers require INT32, INT64, FLOAT or DOUBLE"
+
+
+dispatchScalar :: Int -> PerPage (VP.Vector a) -> PerPage ScalarPiece
+dispatchScalar width legacy =
+  PerPage
+    { ppDecodePlain = \n raw ->
+        if n < 0 || n > BS.length raw `quot` width
+          then Left "Parquet.Read: invalid PLAIN scalar count"
+          else
+            if targetByteOrder == LittleEndian
+              then Right (ScalarPiece n (ScalarPlain (BS.take (n * width) raw)))
+              else scalarFromVector width <$> ppDecodePlain legacy n raw
+    , ppPrepareDictionary = Right . prepareScalarDictionary width
+    , ppDecodeDictionary = \n raw dict -> do
+        if n < 0 || n > maxBound `quot` width
+          then Left "Parquet.Read: scalar dictionary exceeds address space"
+          else Right ()
+        indices <- decodeDictionaryIndices n raw
+        if VP.any (\key -> key < 0 || fromIntegral key >= scalarCount dict) indices
+          then Left "Parquet.Read: scalar dictionary index out of bounds"
+          else Right (ScalarPiece n (ScalarDictionary (scalarData (materializeScalar width dict)) indices))
+    , ppExtended = \encoding n raw -> scalarFromVector width <$> ppExtended legacy encoding n raw
+    , ppConcat = concatScalars width
+    , ppEmpty = ScalarPiece 0 (ScalarPlain BS.empty)
+    }
+
+
+scalarFromVector :: Int -> VP.Vector a -> ScalarPiece
+scalarFromVector width (VP.Vector offset count bytes) =
+  ScalarPiece
+    count
+    ( ScalarPlain
+        ( unsafePerformIO $ do
+            result <- mallocPlainForeignPtrAlignedBytes (count * width) width
+            withForeignPtr result $ \target -> copyByteArrayToAddr target bytes (offset * width) (count * width)
+            pure (BSI.PS result 0 (count * width))
+        )
+    )
+{-# NOINLINE scalarFromVector #-}
+
+
+-- A dictionary is reused by many pages. Align it once, if necessary, so
+-- every gather can load one native word safely, without memcpy per value.
+prepareScalarDictionary :: Int -> ScalarPiece -> ScalarPiece
+prepareScalarDictionary width piece =
+  ScalarPiece (scalarCount piece) (ScalarPlain aligned)
+  where
+    bytes = scalarData (materializeScalar width piece)
+    aligned = unsafePerformIO $ BSUnsafe.unsafeUseAsCString bytes $ \source ->
+      if ptrToWordPtr source .&. fromIntegral (width - 1) == 0
+        then pure bytes
+        else do
+          result <- mallocPlainForeignPtrAlignedBytes (BS.length bytes) width
+          withForeignPtr result $ \target -> copyBytes target (castPtr source) (BS.length bytes)
+          pure (BSI.PS result 0 (BS.length bytes))
+{-# NOINLINE prepareScalarDictionary #-}
+
+
+concatScalars :: Int -> [ScalarPiece] -> Either String ScalarPiece
+concatScalars width pieces = do
+  count <- go 0 pieces
+  Right (ScalarPiece count (ScalarJoined pieces))
+  where
+    go !count [] = Right count
+    go !count (piece : rest)
+      | scalarCount piece > maxBound `quot` width - count = Left "Parquet.Read: scalar column exceeds address space"
+      | otherwise = go (count + scalarCount piece) rest
+
+
+materializeScalar :: Int -> ScalarPiece -> ScalarBuffers
+materializeScalar width piece = ScalarBuffers $ case scalarSource piece of
+  ScalarPlain bytes -> bytes
+  _ -> unsafePerformIO $ do
+    result <- mallocPlainForeignPtrAlignedBytes (scalarCount piece * width) width
+    withForeignPtr result $ \target -> fill target 0 piece
+    pure (BSI.PS result 0 (scalarCount piece * width))
+  where
+    fill target !offset current = case scalarSource current of
+      ScalarPlain bytes -> BSUnsafe.unsafeUseAsCString bytes $ \source ->
+        copyBytes (target `plusPtr` offset) (castPtr source) (BS.length bytes)
+      ScalarDictionary bytes indices -> BSUnsafe.unsafeUseAsCString bytes $ \source -> do
+        -- Both the prepared dictionary and final buffer are width-aligned.
+        let gather4 !i
+              | i == VP.length indices = pure ()
+              | otherwise = do
+                  let !key = fromIntegral (VP.unsafeIndex indices i)
+                  value <- peekByteOff source (key * 4) :: IO Word32
+                  pokeByteOff target (offset + i * 4) value
+                  gather4 (i + 1)
+            gather8 !i
+              | i == VP.length indices = pure ()
+              | otherwise = do
+                  let !key = fromIntegral (VP.unsafeIndex indices i)
+                  value <- peekByteOff source (key * 8) :: IO Word64
+                  pokeByteOff target (offset + i * 8) value
+                  gather8 (i + 1)
+        if width == 4 then gather4 0 else gather8 0
+      ScalarJoined pieces -> do
+        let next !_ [] = pure ()
+            next !position (part : rest) = do
+              fill target position part
+              next (position + scalarCount part * width) rest
+        next offset pieces
+{-# NOINLINE materializeScalar #-}
+
+
+scalarWidth :: ParquetType -> Int
+scalarWidth PTInt32 = 4
+scalarWidth PTFloat = 4
+scalarWidth _ = 8
+
+
+-- | Read supported physical scalars without intermediate per-page vectors.
+readScalarBuffersColumnChunk :: ParquetType -> Compression -> ByteString -> Either String ScalarBuffers
+readScalarBuffersColumnChunk physical codec chunk = do
+  dispatcher <- scalarDispatcher physical
+  materializeScalar (scalarWidth physical) <$> genericReadColumnChunk dispatcher codec chunk
+
+
+readScalarBuffersLevels :: ParquetType -> Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels ScalarBuffers)
+readScalarBuffersLevels physical codec maxRep maxDef chunk = do
+  dispatcher <- scalarDispatcher physical
+  materializeScalarLevels (scalarWidth physical) <$> readLevelsColumnChunk dispatcher codec maxRep maxDef chunk
+
+
+readScalarBuffersSelectedValues :: ParquetType -> Compression -> ByteString -> PageSelection -> Either String ScalarBuffers
+readScalarBuffersSelectedValues physical codec file selection = do
+  dispatcher <- scalarDispatcher physical
+  materializeScalar (scalarWidth physical) <$> readSelectedValues dispatcher codec file selection
+
+
+readScalarBuffersSelectedLevels :: ParquetType -> Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels ScalarBuffers)
+readScalarBuffersSelectedLevels physical codec maxRep maxDef file selection = do
+  dispatcher <- scalarDispatcher physical
+  materializeScalarLevels (scalarWidth physical) <$> readSelectedLevels dispatcher codec maxRep maxDef file selection
+
+
+materializeScalarLevels :: Int -> ColumnLevels ScalarPiece -> ColumnLevels ScalarBuffers
+materializeScalarLevels width levels = ColumnLevels (clRepetition levels) (clDefinition levels) (materializeScalar width (clValues levels))
+
+dispatchByteArray :: PerPage (V.Vector ByteString)
+dispatchByteArray = PerPage
+  { ppDecodePlain = decodePlainByteArray
+  , ppPrepareDictionary = Right
+  , ppDecodeDictionary = \n raw dict -> decodeDictionaryIndices n raw >>= dictLookupV dict
+  , ppExtended = \enc n raw ->
+      if enc == encDeltaLengthByteArray
+        then decodeDeltaLengthByteArray n raw
+        else if enc == encDeltaByteArray
+          then decodeDeltaByteArray n raw
+          else Left $ unsupportedEncoding "BYTE_ARRAY" enc
+  , ppConcat = Right . V.concat
+  , ppEmpty = V.empty
+  }
+
+dispatchBinaryPiecesFor :: forall o. (Integral o, Bounded o, Storable o) => PerPage (BinaryPiece o)
+dispatchBinaryPiecesFor =
+  PerPage
+    { ppDecodePlain = decodePlainBinaryPiece
+    , ppPrepareDictionary = prepareBinaryDictionary
+    , ppDecodeDictionary = decodeBinaryDictionary
+    , ppExtended = \enc n raw ->
+        if enc == encDeltaLengthByteArray
+          then decodeDeltaLengthByteArray n raw >>= packBinaryPiece
+          else
+            if enc == encDeltaByteArray
+              then decodeDeltaByteArray n raw >>= packBinaryPiece
+              else Left $ unsupportedEncoding "BYTE_ARRAY" enc
+    , ppConcat = concatBinaryPieces
+    , ppEmpty = emptyBinaryPiece
+    }
+
+
+{- | BYTE_ARRAY pages decoded directly to contiguous offsets/data buffers.
+Dictionaries and both delta encodings are supported, as for the vector API.
+-}
+readBinaryBuffersColumnChunk :: Compression -> ByteString -> Either String BinaryBuffers
+readBinaryBuffersColumnChunk codec chunk = materializeBinaryPiece <$> genericReadColumnChunk dispatchBinaryPieces codec chunk
+
+
+readBinaryBuffersLevels :: Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels BinaryBuffers)
+readBinaryBuffersLevels codec maxRep maxDef chunk = materializeBinaryLevels <$> readLevelsColumnChunk dispatchBinaryPieces codec maxRep maxDef chunk
+
+
+readBinaryBuffersSelectedValues :: Compression -> ByteString -> PageSelection -> Either String BinaryBuffers
+readBinaryBuffersSelectedValues codec file selection = materializeBinaryPiece <$> readSelectedValues dispatchBinaryPieces codec file selection
+
+
+readBinaryBuffersSelectedLevels :: Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels BinaryBuffers)
+readBinaryBuffersSelectedLevels codec maxRep maxDef file selection = materializeBinaryLevels <$> readSelectedLevels dispatchBinaryPieces codec maxRep maxDef file selection
+
+
+materializeBinaryLevels :: forall o. (Integral o, Bounded o, Storable o) => ColumnLevels (BinaryPiece o) -> ColumnLevels (BinaryBuffersOf o)
+materializeBinaryLevels levels = ColumnLevels (clRepetition levels) (clDefinition levels) (materializeBinaryPiece (clValues levels))
+
+
+dispatchBinaryPieces :: PerPage (BinaryPiece Int32)
+dispatchBinaryPieces = dispatchBinaryPiecesFor @Int32
+
+
+largeBinaryPieces :: PerPage (BinaryPiece Int64)
+largeBinaryPieces = dispatchBinaryPiecesFor @Int64
+
+
+-- | Decode PLAIN values into64-bit offsets without narrowing their sum.
+decodePlainLargeBinaryBuffers :: Int -> ByteString -> Either String LargeBinaryBuffers
+decodePlainLargeBinaryBuffers n raw = materializeBinaryPiece <$> decodePlainBinaryPiece @Int64 n raw
+
+
+readLargeBinaryBuffersColumnChunk :: Compression -> ByteString -> Either String LargeBinaryBuffers
+readLargeBinaryBuffersColumnChunk codec chunk = materializeBinaryPiece <$> genericReadColumnChunk largeBinaryPieces codec chunk
+
+
+readLargeBinaryBuffersLevels :: Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels LargeBinaryBuffers)
+readLargeBinaryBuffersLevels codec maxRep maxDef chunk = materializeBinaryLevels <$> readLevelsColumnChunk largeBinaryPieces codec maxRep maxDef chunk
+
+
+readLargeBinaryBuffersSelectedValues :: Compression -> ByteString -> PageSelection -> Either String LargeBinaryBuffers
+readLargeBinaryBuffersSelectedValues codec file selection = materializeBinaryPiece <$> readSelectedValues largeBinaryPieces codec file selection
+
+
+readLargeBinaryBuffersSelectedLevels :: Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels LargeBinaryBuffers)
+readLargeBinaryBuffersSelectedLevels codec maxRep maxDef file selection = materializeBinaryLevels <$> readSelectedLevels largeBinaryPieces codec maxRep maxDef file selection
+
+
+{-# SPECIALIZE dispatchBinaryPiecesFor :: PerPage (BinaryPiece Int32) #-}
+{-# SPECIALIZE dispatchBinaryPiecesFor :: PerPage (BinaryPiece Int64) #-}
+
+
+{-# SPECIALIZE materializeBinaryLevels :: ColumnLevels (BinaryPiece Int32) -> ColumnLevels BinaryBuffers #-}
+{-# SPECIALIZE materializeBinaryLevels :: ColumnLevels (BinaryPiece Int64) -> ColumnLevels LargeBinaryBuffers #-}
+
+
+-- Fixed byte arrays share the dictionary/delta page machinery, but PLAIN
+-- values have no individual length prefix. Width always comes from schema.
+dispatchFixedBytes :: Int -> PerPage (V.Vector ByteString)
+dispatchFixedBytes width = PerPage
+  { ppDecodePlain = decodePlainFixedLenByteArray width
+  , ppPrepareDictionary = Right
+  , ppDecodeDictionary = \n raw dict -> decodeDictionaryIndices n raw >>= dictLookupV dict
+  , ppExtended = \encoding count bytes ->
+      if encoding == encDeltaByteArray
+        then do
+          values <- decodeDeltaByteArray count bytes
+          if V.all ((== width) . BS.length) values
+            then Right values
+            else Left "Parquet.Read: delta fixed byte array has an invalid width"
+        else if encoding == encByteStreamSplit
+          then decodeByteStreamSplitRaw width count bytes >>= decodePlainFixedLenByteArray width count
+          else Left (unsupportedEncoding "FIXED_LEN_BYTE_ARRAY" encoding)
+  , ppConcat = Right . V.concat
+  , ppEmpty = V.empty
+  }
+
+
+-- Undo byte-stream splitting in one buffer, with no division or allocation
+-- inside the per-byte loop. Bounds are established before any unsafe reads.
+decodeByteStreamSplitRaw :: Int -> Int -> ByteString -> Either String ByteString
+decodeByteStreamSplitRaw width count bytes
+  | width <= 0 || count < 0 || count > BS.length bytes `quot` width =
+      Left "Parquet.Read: invalid BYTE_STREAM_SPLIT size"
+  | otherwise = Right $ Direct.directEncode (width * count) $ \ptr ->
+      let row !i !offset
+            | i == count = pure offset
+            | otherwise = lane i 0 offset
+          lane !i !j !offset
+            | j == width = row (i + 1) offset
+            | otherwise = do
+                next <- Direct.dWord8 ptr offset (BSUnsafe.unsafeIndex bytes (j * count + i))
+                lane i (j + 1) next
+      in row 0
+
+
+readGenericFixedLenByteArrayColumnChunk
+  :: Int -> Compression -> ByteString -> Either String (V.Vector ByteString)
+readGenericFixedLenByteArrayColumnChunk width = genericReadColumnChunk (dispatchFixedBytes width)
+
+
+readGenericFixedLenByteArrayOptionalColumnChunk
+  :: Int -> Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (Maybe ByteString))
+readGenericFixedLenByteArrayOptionalColumnChunk width =
+  readGenericOptionalColumnChunk (dispatchFixedBytes width) id
+
+
+dictLookupVP
+  :: VP.Prim a
+  => VP.Vector a -> VP.Vector Int32 -> Either String (VP.Vector a)
+dictLookupVP dict indices =
+  let !nD = VP.length dict
+      !ok = VP.foldl' (\a k -> a && let !j = fromIntegral k :: Int
+                                    in j >= 0 && j < nD) True indices
+  in if not ok
+       then Left "Parquet.Read: dictionary index out of range"
+       else Right $! VP.map (\k -> dict VP.! fromIntegral k) indices
+
+dictLookupV
+  :: V.Vector a -> VP.Vector Int32 -> Either String (V.Vector a)
+dictLookupV dict indices =
+  let !nD = V.length dict
+      !ok = VP.foldl' (\a k -> a && let !j = fromIntegral k :: Int
+                                    in j >= 0 && j < nD) True indices
+  in if not ok
+       then Left "Parquet.Read: dictionary index out of range"
+       -- A boxed generate stores a deferred lookup per row. Resolve each
+       -- index before writing so repeated strings share the dictionary's
+       -- ByteString directly instead of allocating a closure per value.
+       else Right $! runST (do
+         let !n = VP.length indices
+         out <- VM.unsafeNew n
+         let fill !i
+               | i == n = V.unsafeFreeze out
+               | otherwise = do
+                   let !value = V.unsafeIndex dict (fromIntegral (VP.unsafeIndex indices i))
+                   VM.unsafeWrite out i value
+                   fill (i + 1)
+         fill 0)
+
+unsupportedEncoding :: String -> Int32 -> String
+unsupportedEncoding ty enc =
+  "Parquet.Read: " ++ ty ++ " column has unsupported encoding "
+    ++ show enc
+    ++ " (PLAIN=0, PLAIN_DICTIONARY=2, RLE_DICTIONARY=8, "
+    ++ "DELTA_BINARY_PACKED=5, DELTA_LENGTH_BYTE_ARRAY=6, "
+    ++ "DELTA_BYTE_ARRAY=7, BYTE_STREAM_SPLIT=9)"
+
+-- ============================================================
+-- Public generic readers (required)
+-- ============================================================
+
+readGenericInt32ColumnChunk :: Compression -> ByteString -> Either String (VP.Vector Int32)
+readGenericInt32ColumnChunk = genericReadColumnChunk dispatchInt32
+
+readGenericInt64ColumnChunk :: Compression -> ByteString -> Either String (VP.Vector Int64)
+readGenericInt64ColumnChunk = genericReadColumnChunk dispatchInt64
+
+readGenericFloatColumnChunk :: Compression -> ByteString -> Either String (VP.Vector Float)
+readGenericFloatColumnChunk = genericReadColumnChunk dispatchFloat
+
+readGenericDoubleColumnChunk :: Compression -> ByteString -> Either String (VP.Vector Double)
+readGenericDoubleColumnChunk = genericReadColumnChunk dispatchDouble
+
+readGenericBoolColumnChunk :: Compression -> ByteString -> Either String (V.Vector Bool)
+readGenericBoolColumnChunk = genericReadColumnChunk dispatchBool
+
+readGenericByteArrayColumnChunk :: Compression -> ByteString -> Either String (V.Vector ByteString)
+readGenericByteArrayColumnChunk = genericReadColumnChunk dispatchByteArray
+
+-- ============================================================
+-- Public generic readers (optional / nullable)
+-- ============================================================
+--
+-- For nullable columns the page body carries definition-level
+-- streams in addition to the values; the bridge currently keeps
+-- the existing 'readPlain*OptionalColumnChunk' paths for the V1
+-- + PLAIN case (which the wireform writer always produces) and
+-- falls back to the generic dispatcher for any non-PLAIN
+-- encoding the optional reader sees.
+--
+-- The generic optional path defers to the existing
+-- materializePlain* combinators after the level streams are
+-- parsed, so it inherits the same nullable-column shape.
+
+readGenericInt32OptionalColumnChunk
+  :: Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (Maybe Int32))
+readGenericInt32OptionalColumnChunk =
+  readGenericOptionalColumnChunk dispatchInt32 vpToBoxed
+
+readGenericInt64OptionalColumnChunk
+  :: Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (Maybe Int64))
+readGenericInt64OptionalColumnChunk =
+  readGenericOptionalColumnChunk dispatchInt64 vpToBoxed
+
+readGenericFloatOptionalColumnChunk
+  :: Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (Maybe Float))
+readGenericFloatOptionalColumnChunk =
+  readGenericOptionalColumnChunk dispatchFloat vpToBoxed
+
+readGenericDoubleOptionalColumnChunk
+  :: Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (Maybe Double))
+readGenericDoubleOptionalColumnChunk =
+  readGenericOptionalColumnChunk dispatchDouble vpToBoxed
+
+readGenericBoolOptionalColumnChunk
+  :: Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (Maybe Bool))
+readGenericBoolOptionalColumnChunk =
+  readGenericOptionalColumnChunk dispatchBool id
+
+readGenericByteArrayOptionalColumnChunk
+  :: Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (Maybe ByteString))
+readGenericByteArrayOptionalColumnChunk =
+  readGenericOptionalColumnChunk dispatchByteArray id
+
+-- ============================================================
+-- Public generic readers (repeated)
+-- ============================================================
+--
+-- For columns where the schema path passes through a repeated
+-- group (a Parquet list or map). 'readGenericXxxRepeatedColumnChunk'
+-- returns one outer element per top-level row, each holding the
+-- inner sequence of @Maybe a@s (one per @max_repetition_level@
+-- boundary in the rep stream).
+--
+-- The values payload is decoded in any encoding the underlying
+-- 'PerPage' supports (PLAIN, RLE_DICTIONARY, …); the rep + def
+-- streams come from the standard data-page level layout.
+
+readGenericByteArrayRepeatedColumnChunk
+  :: Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe ByteString)))
+readGenericByteArrayRepeatedColumnChunk codec maxRep maxDef =
+  -- Default: assume the list element is required, so any
+  -- def < maxDef on a rep=0 boundary collapses to "empty/absent
+  -- list". Callers that need to surface element-level nulls
+  -- inside a non-empty list (a Parquet 'optional' element)
+  -- should pass an explicit 'parentEmptyDef' via
+  -- 'readGenericByteArrayRepeatedColumnChunkWith'.
+  readGenericRepeatedColumnChunkWith dispatchByteArray id
+    codec maxRep maxDef (maxDef - 1)
+
+-- | Like 'readGenericByteArrayRepeatedColumnChunk' but the
+-- caller picks @parent_empty_def@ explicitly — typically
+-- @maxDef - 2@ for an optional-element list / map-of-optional-
+-- value.
+readGenericByteArrayRepeatedColumnChunkWith
+  :: Compression -> Int -> Int -> Int -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe ByteString)))
+readGenericByteArrayRepeatedColumnChunkWith =
+  readGenericRepeatedColumnChunkWith dispatchByteArray id
+
+readGenericInt32RepeatedColumnChunk
+  :: Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe Int32)))
+readGenericInt32RepeatedColumnChunk codec maxRep maxDef =
+  readGenericRepeatedColumnChunkWith dispatchInt32 vpToBoxed
+    codec maxRep maxDef (maxDef - 1)
+
+readGenericInt64RepeatedColumnChunk
+  :: Compression -> Int -> Int -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe Int64)))
+readGenericInt64RepeatedColumnChunk codec maxRep maxDef =
+  readGenericRepeatedColumnChunkWith dispatchInt64 vpToBoxed
+    codec maxRep maxDef (maxDef - 1)
+
+-- | Walk every page in a column chunk that has @max_rep > 0@,
+-- accumulate (rep level, def level, defined value) triples, and
+-- group consecutive entries by the rep-level boundaries
+-- (@rep == 0@ marks the start of a new top-level row).
+--
+-- Per-element interpretation:
+--
+--   * @def == maxDef@                         → @Just <value>@
+--   * @parentEmptyDef < def < maxDef@         → @Nothing@ (a
+--     null element inside a present list / map; only possible
+--     when the list element itself is Parquet-optional, hence
+--     the explicit @parentEmptyDef@ split here)
+--   * @def <= parentEmptyDef@                 → no entry (the
+--     parent list / map group is empty or absent on this row)
+--
+-- The @rep == 0@ boundary marks the start of a new row;
+-- empty-list rows still produce an empty inner @V.Vector@ so
+-- the output's outer length always equals the number of
+-- top-level rows in the column.
+--
+-- For required-element lists pass @parentEmptyDef = maxDef - 1@
+-- (which is what the public 'readGeneric*RepeatedColumnChunk'
+-- helpers do).
+-- | Physical levels and only the defined values, in file order. Retaining
+-- the levels lets a nested reader distinguish absent lists, empty lists and
+-- null elements, including where a row continues onto another page.
+data ColumnLevels a = ColumnLevels
+  { clRepetition :: !(VP.Vector Int32)
+  , clDefinition :: !(VP.Vector Int32)
+  , clValues :: !a
+  }
+
+readInt32Levels :: Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels (VP.Vector Int32))
+readInt32Levels = readLevelsColumnChunk dispatchInt32
+readInt64Levels :: Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels (VP.Vector Int64))
+readInt64Levels = readLevelsColumnChunk dispatchInt64
+readFloatLevels :: Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels (VP.Vector Float))
+readFloatLevels = readLevelsColumnChunk dispatchFloat
+readDoubleLevels :: Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels (VP.Vector Double))
+readDoubleLevels = readLevelsColumnChunk dispatchDouble
+readBoolLevels :: Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels (V.Vector Bool))
+readBoolLevels = readLevelsColumnChunk dispatchBool
+readByteArrayLevels :: Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels (V.Vector ByteString))
+readByteArrayLevels = readLevelsColumnChunk dispatchByteArray
+readFixedLevels :: Int -> Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels (V.Vector ByteString))
+readFixedLevels width = readLevelsColumnChunk (dispatchFixedBytes width)
+
+-- | Data-page locations and their keep mask. Supplying the dictionary offset
+-- avoids a footer lookup; the row count enables last-page row validation.
+-- Skipped pages are not read or checksummed, as required for selective IO.
+data PageSelection = PageSelection
+  { selectionLocations :: !(V.Vector PageLocation)
+  , selectionKeep :: !(V.Vector Bool)
+  , selectionDictionaryOffset :: !(Maybe Int64)
+  , selectionRowCount :: !(Maybe Int64)
+  }
+
+readInt32SelectedLevels :: Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels (VP.Vector Int32))
+readInt32SelectedLevels = readSelectedLevels dispatchInt32
+readInt64SelectedLevels :: Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels (VP.Vector Int64))
+readInt64SelectedLevels = readSelectedLevels dispatchInt64
+readFloatSelectedLevels :: Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels (VP.Vector Float))
+readFloatSelectedLevels = readSelectedLevels dispatchFloat
+readDoubleSelectedLevels :: Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels (VP.Vector Double))
+readDoubleSelectedLevels = readSelectedLevels dispatchDouble
+readBoolSelectedLevels :: Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels (V.Vector Bool))
+readBoolSelectedLevels = readSelectedLevels dispatchBool
+readByteArraySelectedLevels :: Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels (V.Vector ByteString))
+readByteArraySelectedLevels = readSelectedLevels dispatchByteArray
+readFixedSelectedLevels :: Int -> Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels (V.Vector ByteString))
+readFixedSelectedLevels width = readSelectedLevels (dispatchFixedBytes width)
+
+-- | Dense required columns need no materialized zero-level vectors.
+readInt32SelectedValues :: Compression -> ByteString -> PageSelection -> Either String (VP.Vector Int32)
+readInt32SelectedValues = readSelectedValues dispatchInt32
+readInt64SelectedValues :: Compression -> ByteString -> PageSelection -> Either String (VP.Vector Int64)
+readInt64SelectedValues = readSelectedValues dispatchInt64
+readFloatSelectedValues :: Compression -> ByteString -> PageSelection -> Either String (VP.Vector Float)
+readFloatSelectedValues = readSelectedValues dispatchFloat
+readDoubleSelectedValues :: Compression -> ByteString -> PageSelection -> Either String (VP.Vector Double)
+readDoubleSelectedValues = readSelectedValues dispatchDouble
+readBoolSelectedValues :: Compression -> ByteString -> PageSelection -> Either String (V.Vector Bool)
+readBoolSelectedValues = readSelectedValues dispatchBool
+readByteArraySelectedValues :: Compression -> ByteString -> PageSelection -> Either String (V.Vector ByteString)
+readByteArraySelectedValues = readSelectedValues dispatchByteArray
+readFixedSelectedValues :: Int -> Compression -> ByteString -> PageSelection -> Either String (V.Vector ByteString)
+readFixedSelectedValues width = readSelectedValues (dispatchFixedBytes width)
+
+-- A page-sized intermediate, shared by sequential and indexed decoding.
+-- Defined counts and level validation are computed in one unboxed loop.
+data LevelPage = LevelPage
+  { lpReps :: !(VP.Vector Int32)
+  , lpDefs :: !(VP.Vector Int32)
+  , lpEncoding :: {-# UNPACK #-} !Int32
+  , lpDefined :: {-# UNPACK #-} !Int
+  , lpRows :: {-# UNPACK #-} !Int
+  , lpValues :: !ByteString
+  }
+
+data LevelCounts = LevelCounts
+  { levelRows :: {-# UNPACK #-} !Int
+  , levelDefined :: {-# UNPACK #-} !Int
+  }
+
+validateLevelLimits :: Int -> Int -> Either String ()
+validateLevelLimits maxRep maxDef
+  | maxRep < 0 || maxDef < maxRep || maxDef > fromIntegral (maxBound :: Int32) =
+      Left "Parquet.Read: invalid maximum repetition/definition levels"
+  | otherwise = Right ()
+
+countLevelEvents :: Int -> Int -> VP.Vector Int32 -> VP.Vector Int32 -> Either String LevelCounts
+countLevelEvents maxRep maxDef reps defs
+  | VP.length reps /= VP.length defs = Left "Parquet.Read: mismatched level counts"
+  | otherwise = go 0 0 0
+  where
+    go !i !rows !defined
+      | i == VP.length defs = Right (LevelCounts rows defined)
+      | otherwise =
+          let !rep = VP.unsafeIndex reps i
+              !def = VP.unsafeIndex defs i
+          in if rep < 0 || rep > fromIntegral maxRep || def < 0 || def > fromIntegral maxDef
+               then Left "Parquet.Read: invalid repetition/definition levels"
+               else go (i + 1) (rows + if rep == 0 then 1 else 0)
+                     (defined + if def == fromIntegral maxDef then 1 else 0)
+{-# INLINE countLevelEvents #-}
+
+readLevelDataPage :: Compression -> Int -> Int -> PageDetails -> ByteString -> Either String LevelPage
+readLevelDataPage codec maxRep maxDef details compBody = case phType hdr of
+  PtDataPage page -> do
+    raw <- decompressPageData codec (phUncompressedPageSize hdr) compBody
+    (reps, defs, values) <- parseDataPageV1LevelsWithEncoding
+      (pdRepetitionEncoding details) (pdDefinitionEncoding details)
+      maxRep maxDef (fromIntegral (dphNumValues page)) raw
+    counts <- countLevelEvents maxRep maxDef reps defs
+    Right (LevelPage reps defs (dphEncoding page) (levelDefined counts) (levelRows counts) values)
+  PtDataPageV2 page -> do
+    let repLength = fromIntegral (dph2RepLevelsLen page)
+        defLength = fromIntegral (dph2DefLevelsLen page)
+        count = fromIntegral (dph2NumValues page)
+        levelsLength = repLength + defLength
+    -- Some producers retain an explicit zero-width RLE stream. Its values
+    -- are still all zero; the declared lengths locate the value payload.
+    if levelsLength > BS.length compBody
+      then Left "Parquet.Read: V2 level lengths exceed body"
+      else Right ()
+    reps <- decodeHybridRleUnsigned32 (levelBitWidth maxRep) count (BS.take repLength compBody)
+    defs <- decodeHybridRleUnsigned32 (levelBitWidth maxDef) count (BS.take defLength (BS.drop repLength compBody))
+    counts <- countLevelEvents maxRep maxDef reps defs
+    if (not (VP.null reps) && VP.head reps /= 0)
+        || levelRows counts /= fromIntegral (dph2NumRows page)
+        || count - levelDefined counts /= fromIntegral (dph2NumNulls page)
+      then Left "Parquet.Read: V2 row/null counts disagree with levels"
+      else Right ()
+    values <- decompressV2Values codec hdr page (BS.drop levelsLength compBody)
+    Right (LevelPage reps defs (dph2Encoding page) (levelDefined counts) (levelRows counts) values)
+  _ -> Left "Parquet.Read: expected a data page"
+  where
+    hdr = pdHeader details
+
+-- Required data has implicit zero levels. Keep their counts without
+-- allocating/filling repetition and definition vectors for every page.
+readRequiredDataPage :: Compression -> PageDetails -> ByteString -> Either String LevelPage
+readRequiredDataPage codec details body = case phType header of
+  PtDataPage page -> do
+    values <- decompressPageData codec (phUncompressedPageSize header) body
+    let count = fromIntegral (dphNumValues page)
+    Right (LevelPage VP.empty VP.empty (dphEncoding page) count count values)
+  PtDataPageV2 page -> do
+    let levelsLength = fromIntegral (dph2RepLevelsLen page) + fromIntegral (dph2DefLevelsLen page)
+        count = fromIntegral (dph2NumValues page)
+    if levelsLength > BS.length body || dph2NumRows page /= dph2NumValues page || dph2NumNulls page /= 0
+      then Left "Parquet.Read: required V2 row/null/level counts disagree"
+      else Right ()
+    values <- decompressV2Values codec header page (BS.drop levelsLength body)
+    Right (LevelPage VP.empty VP.empty (dph2Encoding page) count count values)
+  _ -> Left "Parquet.Read: expected a required data page"
+  where
+    header = pdHeader details
+
+readDictionaryValues :: PerPage vec -> Compression -> PageHeader -> ByteString -> Either String vec
+readDictionaryValues pp codec header body = case phType header of
+  PtDictionaryPage page
+    | dictEncoding page == encPlain || dictEncoding page == encPlainDictionary -> do
+        raw <- decompressPageData codec (phUncompressedPageSize header) body
+        ppDecodePlain pp (fromIntegral (dictNumValues page)) raw >>= ppPrepareDictionary pp
+    | otherwise -> Left "Parquet.Read: dictionary encoding must be PLAIN"
+  _ -> Left "Parquet.Read: dictionary offset does not point to a dictionary page"
+
+readLevelsColumnChunk :: forall vec. PerPage vec -> Compression -> Int -> Int -> ByteString -> Either String (ColumnLevels vec)
+readLevelsColumnChunk pp codec maxRep maxDef chunk0 = do
+  validateLevelLimits maxRep maxDef
+  levels <- collectPages 0 Nothing [] [] []
+  if not (VP.null (clRepetition levels)) && VP.head (clRepetition levels) /= 0
+    then Left "Parquet.Read: first repetition level must be zero"
+    else Right levels
+  where
+    collectPages !off !mDict !accReps !accDefs !accVals
+      | off == BS.length chunk0 = ColumnLevels (concatPages VP.concat accReps) (concatPages VP.concat accDefs) <$> concatValuePages pp accVals
+      | otherwise = do
+          details <- readPageDetailsCheckedAt chunk0 off
+          let hdr = pdHeader details
+              bodyStart = pdBodyOffset details
+          compSz <- maybe (Left "Parquet.Read: missing compressed_page_size") (Right . fromIntegral) (phCompressedPageSize hdr)
+          let compBody = BS.take compSz (BS.drop bodyStart chunk0)
+              nextOff = bodyStart + compSz
+          case phType hdr of
+            PtDictionaryPage _ -> do
+              if off /= 0
+                then Left "Parquet.Read: dictionary must be the first page in a column"
+                else Right ()
+              case mDict of
+                Just _ -> Left "Parquet.Read: multiple dictionary pages in one column"
+                Nothing -> Right ()
+              dict <- readDictionaryValues pp codec hdr compBody
+              collectPages nextOff (Just dict) accReps accDefs accVals
+            _ -> do
+              page <- readLevelDataPage codec maxRep maxDef details compBody
+              defined <- decodeDefinedCount pp mDict (lpEncoding page) (lpDefined page) (lpValues page)
+              collectPages nextOff mDict (lpReps page : accReps) (lpDefs page : accDefs) (defined : accVals)
+
+
+readGenericRepeatedColumnChunkWith
+  :: forall vec a.
+     PerPage vec
+  -> (vec -> V.Vector a)
+  -> Compression
+  -> Int  -- ^ max_repetition_level
+  -> Int  -- ^ max_definition_level
+  -> Int  -- ^ parent_empty_def (any def at-or-below this means
+          --   the list / map is empty or absent on that row)
+  -> ByteString
+  -> Either String (V.Vector (V.Vector (Maybe a)))
+readGenericRepeatedColumnChunkWith pp toBoxed codec maxRep maxDef parentEmptyDef chunk0 = do
+  levels <- readLevelsColumnChunk pp codec maxRep maxDef chunk0
+  Right (groupByRows (clRepetition levels) (clDefinition levels) (toBoxed (clValues levels)))
+  where
+    !maxD = fromIntegral maxDef :: Int32
+
+    -- | Group the (rep, def, defined-values) triple into per-row
+    -- inner vectors. Every @rep == 0@ boundary starts a new
+    -- top-level row; the row built so far gets pushed even if
+    -- it's empty.
+    --
+    -- Note we always push exactly one outer row per @rep == 0@
+    -- boundary, including empty-row cases, so the resulting
+    -- vector has the same length as the number of top-level
+    -- rows in the column.
+    groupByRows
+      :: VP.Vector Int32
+      -> VP.Vector Int32
+      -> V.Vector a
+      -> V.Vector (V.Vector (Maybe a))
+    groupByRows reps defs defined
+      | VP.length reps == 0 = V.empty
+      | otherwise =
+          let !n = VP.length reps
+              go !rows !curRow !inRow !i !defIx
+                | i >= n =
+                    let !rows' = if inRow then curRow : rows else rows
+                     in V.fromList (reverse (map finalise rows'))
+                | otherwise =
+                    let !r = VP.unsafeIndex reps i
+                        !d = VP.unsafeIndex defs i
+                        -- On a 'rep == 0' boundary we flush the
+                        -- previous row (if any) and start a new
+                        -- one. The very first entry has no row
+                        -- to flush, hence the 'inRow' guard.
+                        (!rows', !row0) =
+                          if r == 0
+                            then (if inRow then curRow : rows else rows, [])
+                            else (rows, curRow)
+                     in if d == maxD
+                          then go rows'
+                                  (Just (V.unsafeIndex defined defIx) : row0)
+                                  True (i + 1) (defIx + 1)
+                          else if d <= parentEmptyDef'
+                            then go rows' row0 True (i + 1) defIx
+                            else go rows' (Nothing : row0) True (i + 1) defIx
+           in go [] [] False 0 0
+
+    finalise xs = V.fromList (reverse xs)
+
+    -- | Floor for "list / map is empty or absent on this row".
+    -- Caller-supplied (see the 'parentEmptyDef' parameter on
+    -- the public entry).
+    parentEmptyDef' :: Int32
+    parentEmptyDef' = fromIntegral parentEmptyDef
+
+decodeDefinedCount :: PerPage vec -> Maybe vec -> Int32 -> Int -> ByteString -> Either String vec
+decodeDefinedCount pp mDict !enc !count !bytes
+  | count == 0 = Right (ppEmpty pp)
+  | enc == encPlain = ppDecodePlain pp count bytes
+  | isDictionaryEncoding enc = case mDict of
+      Nothing -> Left "Parquet.Read: RLE_DICTIONARY page before dictionary page"
+      Just dict -> ppDecodeDictionary pp count bytes dict
+  | otherwise = ppExtended pp enc count bytes
+
+-- | Walk every page in a column chunk and interleave a
+-- definition-level stream per page so the result is
+-- @V.Vector (Maybe a)@. Handles V1 and V2 pages and any of the
+-- encodings that the underlying 'PerPage' supports for the
+-- /defined/ values (PLAIN, dictionary, delta, byte-stream-split).
+readGenericOptionalColumnChunk
+  :: forall vec a.
+     PerPage vec
+  -> (vec -> V.Vector a)
+  -> Compression
+  -> Int  -- ^ max_repetition_level (typically 0 for flat)
+  -> Int  -- ^ max_definition_level (typically 1 for flat optional)
+  -> ByteString
+  -> Either String (V.Vector (Maybe a))
+readGenericOptionalColumnChunk pp toBoxed codec maxRep maxDef chunk = do
+  levels <- readLevelsColumnChunk pp codec maxRep maxDef chunk
+  Right (interleaveDefined (clDefinition levels) (fromIntegral maxDef) (toBoxed (clValues levels)))
+
+-- | Convert a 'VP.Vector' to a 'V.Vector' via 'VP.convert'.
+vpToBoxed :: VP.Prim a => VP.Vector a -> V.Vector a
+vpToBoxed = VP.convert
+
+interleaveDefined :: VP.Vector Int32 -> Int32 -> V.Vector a -> V.Vector (Maybe a)
+interleaveDefined def maxD defined = runST $ do
+  let !n = VP.length def
+  v <- VM.unsafeNew n
+  let go !i !j
+        | i >= n = pure ()
+        | VP.unsafeIndex def i == maxD = do
+            VM.unsafeWrite v i (Just (V.unsafeIndex defined j))
+            go (i + 1) (j + 1)
+        | otherwise = do
+            VM.unsafeWrite v i Nothing
+            go (i + 1) j
+  go 0 0
+  V.unsafeFreeze v
+
+-- ============================================================
+-- Page-index-driven page skipping
+-- ============================================================
+--
+-- The 'PageLocation' offsets in an 'Parquet.Types.OffsetIndex'
+-- are absolute file offsets (per the spec), so the page-level
+-- skipping API takes the full file 'ByteString' rather than a
+-- column-chunk slice.
+--
+-- The 'V.Vector Bool' alongside @pageLocations@ is the
+-- per-page \"keep this page\" mask: 'True' = decode it, 'False'
+-- = skip. Producers typically build this by running
+-- 'Parquet.Predicate.evalPagesByColumnIndex' against the chunk's
+-- 'ColumnIndex' and mapping 'PMaybeKeep' -> True / 'PSkip' ->
+-- False.
+--
+-- All variants assume each page contributes a contiguous chunk
+-- of values to the surviving result vector — i.e. they're
+-- correct for required (max-def-level=0) columns. For nullable
+-- columns the per-page def-level streams need to be parsed to
+-- know how many values a page actually contributes; that's a
+-- separate optional-page-skipping API.
+
+readGenericInt32SelectedPages
+  :: Compression -> ByteString -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (VP.Vector Int32)
+readGenericInt32SelectedPages = readSelectedPages dispatchInt32
+
+readGenericInt64SelectedPages
+  :: Compression -> ByteString -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (VP.Vector Int64)
+readGenericInt64SelectedPages = readSelectedPages dispatchInt64
+
+readGenericFloatSelectedPages
+  :: Compression -> ByteString -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (VP.Vector Float)
+readGenericFloatSelectedPages = readSelectedPages dispatchFloat
+
+readGenericDoubleSelectedPages
+  :: Compression -> ByteString -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (VP.Vector Double)
+readGenericDoubleSelectedPages = readSelectedPages dispatchDouble
+
+readGenericBoolSelectedPages
+  :: Compression -> ByteString -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (V.Vector Bool)
+readGenericBoolSelectedPages = readSelectedPages dispatchBool
+
+readGenericByteArraySelectedPages
+  :: Compression -> ByteString -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (V.Vector ByteString)
+readGenericByteArraySelectedPages = readSelectedPages dispatchByteArray
+
+-- | Compatibility surface for dense columns. Dictionary offsets are resolved
+-- from a full PAR1 file only if a kept page actually needs its dictionary.
+-- Metadata-aware callers should use the selected-level readers directly.
+readSelectedPages
+  :: PerPage a -> Compression -> ByteString -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String a
+readSelectedPages pp codec file locations keep =
+  readSelectedValues pp codec file (PageSelection locations keep Nothing Nothing)
+
+readSelectedValues :: PerPage vec -> Compression -> ByteString -> PageSelection -> Either String vec
+readSelectedValues pp codec file selection = clValues <$> readSelectedCore False pp codec 0 0 file selection
+
+-- Validate locations without touching page bytes. A retained page is sliced
+-- to its declared size before parsing, so its header/body cannot escape into
+-- a neighbour, index or footer even if its internal size is corrupt.
+validateSelection :: ByteString -> PageSelection -> Either String ()
+validateSelection file selection
+  | V.length locations /= V.length keep = Left "Parquet.Read: keep-mask/page-location count mismatch"
+  | maybe False (< 0) (selectionRowCount selection) = Left "Parquet.Read: negative row count"
+  | V.null locations && maybe False (/= 0) (selectionRowCount selection) = Left "Parquet.Read: missing data pages"
+  | otherwise = go 0 0 (-1)
+  where
+    locations = selectionLocations selection
+    keep = selectionKeep selection
+    fileSize = fromIntegral (BS.length file) :: Int64
+    go !i !previousEnd !previousRow
+      | i == V.length locations = Right ()
+      | otherwise =
+          let page = V.unsafeIndex locations i
+              offset = plOffset page
+              size = fromIntegral (plCompressedPageSize page) :: Int64
+              row = plFirstRowIndex page
+          in if offset < 0 || size <= 0 || offset > fileSize || size > fileSize - offset
+                || (i > 0 && offset < previousEnd) || row < 0 || row <= previousRow
+                || maybe False (\total -> row >= total && not (total == 0 && i == 0)) (selectionRowCount selection)
+                || (i == 0 && selectionRowCount selection /= Nothing && row /= 0)
+               then Left "Parquet.Read: invalid/overlapping page location or row boundary"
+               else go (i + 1) (offset + size) row
+
+readSelectedLevels :: PerPage vec -> Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels vec)
+readSelectedLevels = readSelectedCore True
+
+readSelectedCore :: Bool -> PerPage vec -> Compression -> Int -> Int -> ByteString -> PageSelection -> Either String (ColumnLevels vec)
+readSelectedCore retainLevels pp codec maxRep maxDef file selection = do
+  validateLevelLimits maxRep maxDef
+  validateSelection file selection
+  walk 0 Nothing [] [] []
+  where
+    locations = selectionLocations selection
+    keep = selectionKeep selection
+    walk !i !dictionary !reps !defs !values
+      | i == V.length locations = ColumnLevels (concatPages VP.concat reps) (concatPages VP.concat defs) <$> concatValuePages pp values
+      | not (V.unsafeIndex keep i) = walk (i + 1) dictionary reps defs values
+      | otherwise = do
+          let location = V.unsafeIndex locations i
+              bytes = BS.take (fromIntegral (plCompressedPageSize location)) (BS.drop (fromIntegral (plOffset location)) file)
+          details <- readPageDetailsCheckedAt bytes 0
+          let header = pdHeader details
+          size <- maybe (Left "Parquet.Read: missing page size") (Right . fromIntegral) (phCompressedPageSize header)
+          if pdBodyOffset details + size /= BS.length bytes
+            then Left "Parquet.Read: page size differs from offset index"
+            else Right ()
+          page <- if retainLevels
+            then readLevelDataPage codec maxRep maxDef details (BS.drop (pdBodyOffset details) bytes)
+            else readRequiredDataPage codec details (BS.drop (pdBodyOffset details) bytes)
+          if not (VP.null (lpReps page)) && VP.head (lpReps page) /= 0
+            then Left "Parquet.Read: indexed page starts within a row"
+            else Right ()
+          let nextRow = if i + 1 < V.length locations
+                then Just (plFirstRowIndex (V.unsafeIndex locations (i + 1)))
+                else selectionRowCount selection
+          case nextRow of
+            Just end | end - plFirstRowIndex location /= fromIntegral (lpRows page) ->
+              Left "Parquet.Read: decoded page rows differ from offset index"
+            _ -> Right ()
+          dict <- if lpDefined page > 0 && isDictionaryEncoding (lpEncoding page)
+            then case dictionary of
+              Just _ -> Right dictionary
+              Nothing -> Just <$> loadDictionary
+            else Right dictionary
+          defined <- decodeDefinedCount pp dict (lpEncoding page) (lpDefined page) (lpValues page)
+          walk (i + 1) dict (if retainLevels then lpReps page : reps else reps)
+            (if retainLevels then lpDefs page : defs else defs) (defined : values)
+    loadDictionary = do
+      offset <- case selectionDictionaryOffset selection of
+        Just offset -> Right offset
+        Nothing -> dictionaryOffsetFromFooter codec file locations
+      let firstData = plOffset (V.head locations)
+      if offset < 0 || offset >= firstData
+        then Left "Parquet.Read: dictionary offset is not before data pages"
+        else Right ()
+      let bytes = BS.take (fromIntegral (firstData - offset)) (BS.drop (fromIntegral offset) file)
+      details <- readPageDetailsCheckedAt bytes 0
+      let size = maybe 0 fromIntegral (phCompressedPageSize (pdHeader details))
+      readDictionaryValues pp codec (pdHeader details) (BS.take size (BS.drop (pdBodyOffset details) bytes))
+
+-- This path is lazy: PLAIN/DELTA pages and synthetic page buffers do not pay
+-- for parsing a footer. A unique matching column is required before using its
+-- dictionary; guessing by scanning unrelated bytes could return wrong values.
+dictionaryOffsetFromFooter :: Compression -> ByteString -> V.Vector PageLocation -> Either String Int64
+dictionaryOffsetFromFooter codec file locations
+  | BS.take 4 file /= BS.pack [80,65,82,49] = Left "Parquet.Read: selected dictionary page needs its metadata offset"
+  | otherwise = do
+      metadata <- readFooter file
+      let firstData = plOffset (V.head locations)
+          candidates = V.concatMap
+            (V.mapMaybe (\column -> do
+              md <- ccMetadata column
+              offset <- cmDictionaryPageOffset md
+              if cmDataPageOffset md == firstData && cmCodec md == codec
+                then Just offset else Nothing) . rgColumns)
+            (fmRowGroups metadata)
+      if V.length candidates == 1
+        then Right (V.head candidates)
+        else Left "Parquet.Read: cannot uniquely resolve selected dictionary"
+
+-- ============================================================
+-- Optional page-index-driven page skipping
+-- ============================================================
+--
+-- The required-page-skip path above assumes every surviving
+-- page contributes a contiguous chunk of values. Nullable
+-- columns carry per-page def-level streams; a /skipped/ page
+-- still elides its rows from the output, so we have to:
+--
+-- Retain levels and defined values only for kept pages, then interleave
+-- once. Skipped pages contribute no output rows. Use row-index ranges
+-- from OffsetIndex when aligning selections across columns.
+
+readGenericInt32OptionalSelectedPages
+  :: Compression -> Int -> Int -> ByteString
+  -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (V.Vector (Maybe Int32))
+readGenericInt32OptionalSelectedPages =
+  readGenericOptionalSelectedPages dispatchInt32 vpToBoxed
+
+readGenericInt64OptionalSelectedPages
+  :: Compression -> Int -> Int -> ByteString
+  -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (V.Vector (Maybe Int64))
+readGenericInt64OptionalSelectedPages =
+  readGenericOptionalSelectedPages dispatchInt64 vpToBoxed
+
+readGenericFloatOptionalSelectedPages
+  :: Compression -> Int -> Int -> ByteString
+  -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (V.Vector (Maybe Float))
+readGenericFloatOptionalSelectedPages =
+  readGenericOptionalSelectedPages dispatchFloat vpToBoxed
+
+readGenericDoubleOptionalSelectedPages
+  :: Compression -> Int -> Int -> ByteString
+  -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (V.Vector (Maybe Double))
+readGenericDoubleOptionalSelectedPages =
+  readGenericOptionalSelectedPages dispatchDouble vpToBoxed
+
+readGenericBoolOptionalSelectedPages
+  :: Compression -> Int -> Int -> ByteString
+  -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (V.Vector (Maybe Bool))
+readGenericBoolOptionalSelectedPages =
+  readGenericOptionalSelectedPages dispatchBool id
+
+readGenericByteArrayOptionalSelectedPages
+  :: Compression -> Int -> Int -> ByteString
+  -> V.Vector PageLocation -> V.Vector Bool
+  -> Either String (V.Vector (Maybe ByteString))
+readGenericByteArrayOptionalSelectedPages =
+  readGenericOptionalSelectedPages dispatchByteArray id
+
+-- | Walk pages by 'PageLocation', honour the keep mask, and
+-- materialise an interleaved @V.Vector (Maybe a)@. Skipped
+-- pages don't contribute rows to the output; if the caller
+-- wants positional alignment with the unfiltered column they
+-- need to also collect the per-page row counts (the
+-- 'PageLocation.plFirstRowIndex' deltas give that).
+readGenericOptionalSelectedPages
+  :: PerPage vec
+  -> (vec -> V.Vector a)
+  -> Compression
+  -> Int  -- ^ max_repetition_level
+  -> Int  -- ^ max_definition_level
+  -> ByteString
+  -> V.Vector PageLocation
+  -> V.Vector Bool
+  -> Either String (V.Vector (Maybe a))
+readGenericOptionalSelectedPages pp toBoxed codec maxRep maxDef file locations keep = do
+  levels <- readSelectedLevels pp codec maxRep maxDef file (PageSelection locations keep Nothing Nothing)
+  Right (interleaveDefined (clDefinition levels) (fromIntegral maxDef) (toBoxed (clValues levels)))
diff --git a/src/Parquet/Thrift/Schema.hs b/src/Parquet/Thrift/Schema.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Thrift/Schema.hs
@@ -0,0 +1,922 @@
+{-# LANGUAGE PatternSynonyms #-}
+
+{- | Named Thrift-field pattern synonyms for every @parquet.thrift@
+struct this codebase encodes or decodes.
+
+Each pattern synonym has the form
+
+@
+pattern \<StructName\>_\<FieldName\> :: \<HaskellType\> -> (Int16, TV.Value)
+pattern \<StructName\>_\<FieldName\> v = (\<field-id-from-parquet.thrift\>, TV.\<WireTag\> v)
+@
+
+and is bidirectional, so both writers and readers name the field slot
+directly rather than by a bare integer. The motivation is concrete: a
+recent bug had the writer emit @Iceberg field_id@ into Thrift field 8
+of @SchemaElement@, which @parquet.thrift@ actually reserves for
+@precision@. Because both sides used @(8, TV.I32 _)@ the wireform
+self-round-trip hid it; pyarrow and parquet-mr silently dropped the
+id. With pattern synonyms named after the @.thrift@ file, any such
+mismatch becomes a visible name collision.
+
+/Scope./ The synonyms cover exactly the fields we construct or match
+against in "Parquet.Footer", "Parquet.Page", "Parquet.PageIndex",
+"Parquet.Write" and "Parquet.BloomFilter". Fields we never touch
+(e.g. @ColumnMetaData.key_value_metadata@ or
+@ColumnMetaData.encoding_stats@) are intentionally absent; adding one
+is a one-line exercise.
+
+/Spec refs./ Field numbers below are quoted from
+@apache/parquet-format@ at
+@src/main/thrift/parquet.thrift@. Encryption structs are from the
+same file's @FileCryptoMetaData@ / @EncryptionAlgorithm@ /
+@AesGcmV1@ blocks (Parquet Modular Encryption, section 5.2).
+
+Conventions:
+
+* Scalar-valued fields carry their Thrift wire type directly
+  (@I32@ / @I64@ / @String@ / @Binary@ / @Bool@).
+* Enum-valued fields are exposed as @Int32@ — the caller converts
+  through the domain-specific @\<foo\>ToInt@ / @intTo\<Foo\>@ helpers
+  from "Parquet.Types". Keeping the synonyms at wire level makes the
+  spec-to-code mapping 1:1 and avoids hiding Maybe-failures inside a
+  pattern.
+* Nested struct fields carry a @Vector (Int16, TV.Value)@ so the
+  match succeeds only for a struct, and the inner pattern synonyms
+  of that nested type are directly usable inside.
+-}
+module Parquet.Thrift.Schema (
+  -- * Composition helpers
+  optField,
+  findField,
+
+  -- * FileMetadata
+  pattern FileMetadata_Version,
+  pattern FileMetadata_Schema,
+  pattern FileMetadata_NumRows,
+  pattern FileMetadata_RowGroups,
+  pattern FileMetadata_KeyValueMetadata,
+  pattern KeyValue_Key,
+  pattern KeyValue_Value,
+  pattern FileMetadata_CreatedBy,
+  pattern FileMetadata_ColumnOrders,
+  pattern FileMetadata_EncryptionAlgorithm,
+  pattern FileMetadata_FooterSigningKeyMetadata,
+
+  -- * SchemaElement
+
+  --
+
+  {- | @parquet.thrift@:
+
+  @
+  1: optional Type                    type
+  2: optional i32                     type_length
+  3: optional FieldRepetitionType     repetition_type
+  4: required string                  name
+  5: optional i32                     num_children
+  6: optional ConvertedType           converted_type
+  7: optional i32                     scale
+  8: optional i32                     precision
+  9: optional i32                     field_id
+  10: optional LogicalType            logicalType
+  @
+  -}
+  pattern SchemaElement_Type,
+  pattern SchemaElement_TypeLength,
+  pattern SchemaElement_RepetitionType,
+  pattern SchemaElement_Name,
+  pattern SchemaElement_NumChildren,
+  pattern SchemaElement_ConvertedType,
+  pattern SchemaElement_Scale,
+  pattern SchemaElement_Precision,
+  pattern SchemaElement_FieldId,
+  pattern SchemaElement_LogicalType,
+
+  -- * RowGroup
+  pattern RowGroup_Columns,
+  pattern RowGroup_Ordinal,
+  pattern RowGroup_TotalByteSize,
+  pattern RowGroup_NumRows,
+  pattern RowGroup_SortingColumns,
+
+  -- ** SortingColumn struct fields
+  pattern SortingColumn_ColumnIdx,
+  pattern SortingColumn_Descending,
+  pattern SortingColumn_NullsFirst,
+
+  -- ** ColumnOrder union variants
+  columnOrderTypeDefined,
+  columnOrderIeee754Total,
+  columnOrderInt96Timestamp,
+
+  -- * ColumnChunk
+  pattern ColumnChunk_FilePath,
+  pattern ColumnChunk_FileOffset,
+  pattern ColumnChunk_MetaData,
+  pattern ColumnChunk_OffsetIndexOffset,
+  pattern ColumnChunk_OffsetIndexLength,
+  pattern ColumnChunk_ColumnIndexOffset,
+  pattern ColumnChunk_ColumnIndexLength,
+  pattern ColumnChunk_CryptoMetadata,
+  pattern ColumnCryptoMetaData_EncryptionWithFooterKey,
+  pattern ColumnCryptoMetaData_EncryptionWithColumnKey,
+  pattern EncryptionWithColumnKey_PathInSchema,
+  pattern EncryptionWithColumnKey_KeyMetadata,
+  pattern ColumnChunk_EncryptedColumnMetadata,
+
+  -- * ColumnMetaData
+  pattern ColumnMetaData_Type,
+  pattern ColumnMetaData_Encodings,
+  pattern ColumnMetaData_PathInSchema,
+  pattern ColumnMetaData_Codec,
+  pattern ColumnMetaData_NumValues,
+  pattern ColumnMetaData_TotalUncompressedSize,
+  pattern ColumnMetaData_TotalCompressedSize,
+  pattern ColumnMetaData_DataPageOffset,
+  pattern ColumnMetaData_DictionaryPageOffset,
+  pattern ColumnMetaData_Statistics,
+  pattern ColumnMetaData_BloomFilterOffset,
+  pattern ColumnMetaData_BloomFilterLength,
+
+  -- * Statistics
+
+  --
+
+  {- | Parquet stores min/max as @TT_STRING@, which the Thrift compact
+  decoder surfaces as either 'TV.Binary' or 'TV.String'. Only the
+  'TV.Binary' constructor is used on the write side; reader callers
+  should fall back to 'TV.String' via a dedicated helper.
+  -}
+  pattern Statistics_Max,
+  pattern Statistics_Min,
+  pattern Statistics_NullCount,
+  pattern Statistics_DistinctCount,
+  pattern Statistics_MaxValue,
+  pattern Statistics_MinValue,
+  pattern Statistics_NanCount,
+  pattern Statistics_MinValueExact,
+  pattern Statistics_MaxValueExact,
+
+  -- * PageHeader
+
+  --
+
+  {- | @parquet.thrift@:
+
+  @
+  1: required PageType               type
+  2: required i32                    uncompressed_page_size
+  3: required i32                    compressed_page_size
+  4: optional i32                    crc (skipped)
+  5: optional DataPageHeader         data_page_header
+  6: optional IndexPageHeader        index_page_header (skipped)
+  7: optional DictionaryPageHeader   dictionary_page_header
+  8: optional DataPageHeaderV2       data_page_header_v2
+  @
+  -}
+  pattern PageHeader_Type,
+  pattern PageHeader_UncompressedSize,
+  pattern PageHeader_CompressedSize,
+  pattern PageHeader_Crc,
+  pattern PageHeader_DataPageHeader,
+  pattern PageHeader_DictionaryPageHeader,
+  pattern PageHeader_DataPageHeaderV2,
+
+  -- * DataPageHeader
+  pattern DataPageHeader_NumValues,
+  pattern DataPageHeader_Encoding,
+  pattern DataPageHeader_DefinitionLevelEncoding,
+  pattern DataPageHeader_RepetitionLevelEncoding,
+
+  -- * DictionaryPageHeader
+  pattern DictionaryPageHeader_NumValues,
+  pattern DictionaryPageHeader_Encoding,
+
+  -- * DataPageHeaderV2
+  pattern DataPageHeaderV2_NumValues,
+  pattern DataPageHeaderV2_NumNulls,
+  pattern DataPageHeaderV2_NumRows,
+  pattern DataPageHeaderV2_Encoding,
+  pattern DataPageHeaderV2_DefinitionLevelsByteLength,
+  pattern DataPageHeaderV2_RepetitionLevelsByteLength,
+  pattern DataPageHeaderV2_IsCompressed,
+
+  -- * OffsetIndex
+  pattern OffsetIndex_PageLocations,
+  pattern OffsetIndex_UnencodedByteArrayDataBytes,
+
+  -- * PageLocation
+  pattern PageLocation_Offset,
+  pattern PageLocation_CompressedPageSize,
+  pattern PageLocation_FirstRowIndex,
+
+  -- * ColumnIndex
+  pattern ColumnIndex_NullPages,
+  pattern ColumnIndex_MinValues,
+  pattern ColumnIndex_MaxValues,
+  pattern ColumnIndex_BoundaryOrder,
+  pattern ColumnIndex_NullCounts,
+  pattern ColumnIndex_NanCounts,
+  pattern ColumnIndex_RepetitionLevelHistograms,
+  pattern ColumnIndex_DefinitionLevelHistograms,
+
+  -- * BloomFilterHeader
+  pattern BloomFilterHeader_NumBytes,
+  pattern BloomFilterHeader_Algorithm,
+  pattern BloomFilterHeader_Hash,
+  pattern BloomFilterHeader_Compression,
+
+  -- * FileCryptoMetaData (Modular Encryption)
+  pattern FileCryptoMetaData_EncryptionAlgorithm,
+  pattern FileCryptoMetaData_KeyMetadata,
+
+  -- * EncryptionAlgorithm
+
+  --
+
+  -- | Only the @AES_GCM_V1@ branch is used by the footer writer.
+  pattern EncryptionAlgorithm_AesGcmV1,
+  pattern EncryptionAlgorithm_AesGcmCtrV1,
+
+  -- * AesGcmV1
+  pattern AesGcmV1_AadPrefix,
+  pattern AesGcmV1_AadFileUnique,
+  pattern AesGcmV1_SupplyAadPrefix,
+) where
+
+import Data.ByteString (ByteString)
+import Data.Int (Int16, Int32, Int64)
+import Data.Maybe (listToMaybe, mapMaybe)
+import Data.Text (Text)
+import Data.Vector (Vector)
+import Data.Vector qualified as V
+import Thrift.Value qualified as TV
+import Thrift.Wire (ThriftType (..))
+
+
+-- ============================================================
+-- Composition helpers
+-- ============================================================
+
+{- | @optField (Just x) P@ emits @[P x]@; @optField Nothing _@ emits
+@[]@. Intended to be used on a list of pattern-synonym constructors
+so that a writer body looks like the corresponding @.thrift@ struct:
+
+> TV.Struct $ V.fromList $ concat
+>   [ optField (seType se) (SchemaElement_Type . parquetTypeToInt)
+>   , [SchemaElement_Name (seName se)]
+>   , optField (seFieldId se) SchemaElement_FieldId
+>   ]
+-}
+optField :: Maybe a -> (a -> (Int16, TV.Value)) -> [(Int16, TV.Value)]
+optField Nothing _ = []
+optField (Just x) f = [f x]
+
+
+{- | Find the first field entry for which @probe@ returns @Just@.
+Typical call site:
+
+> findField fm $ \case
+>   SchemaElement_FieldId v -> Just v
+>   _                       -> Nothing
+
+Thrift compact sorts struct fields by id on the wire so the first
+match is always the intended one.
+-}
+findField
+  :: [(Int16, TV.Value)]
+  -> ((Int16, TV.Value) -> Maybe a)
+  -> Maybe a
+findField fs probe = listToMaybe (mapMaybe probe fs)
+
+
+-- ============================================================
+-- FileMetadata
+-- ============================================================
+
+pattern FileMetadata_Version :: Int32 -> (Int16, TV.Value)
+pattern FileMetadata_Version v = (1, TV.I32 v)
+
+
+pattern FileMetadata_Schema :: Vector TV.Value -> (Int16, TV.Value)
+pattern FileMetadata_Schema elems <- (2, TV.List _ elems)
+  where
+    FileMetadata_Schema elems = (2, TV.List TT_STRUCT elems)
+
+
+-- FileMetaData.key_value_metadata is field 5. KeyValue uses the Thrift
+-- string wire type; Value exposes both decoded Text and opaque bytes.
+pattern FileMetadata_KeyValueMetadata :: Vector TV.Value -> (Int16, TV.Value)
+pattern FileMetadata_KeyValueMetadata xs <- (5, TV.List _ xs)
+  where
+    FileMetadata_KeyValueMetadata xs = (5, TV.List TT_STRUCT xs)
+
+
+pattern KeyValue_Key :: TV.Value -> (Int16, TV.Value)
+pattern KeyValue_Key value = (1, value)
+
+
+pattern KeyValue_Value :: TV.Value -> (Int16, TV.Value)
+pattern KeyValue_Value value = (2, value)
+
+
+pattern FileMetadata_NumRows :: Int64 -> (Int16, TV.Value)
+pattern FileMetadata_NumRows v = (3, TV.I64 v)
+
+
+pattern FileMetadata_RowGroups :: Vector TV.Value -> (Int16, TV.Value)
+pattern FileMetadata_RowGroups elems <- (4, TV.List _ elems)
+  where
+    FileMetadata_RowGroups elems = (4, TV.List TT_STRUCT elems)
+
+
+{- | @FileMetaData.created_by@ is field id 6 in the official
+parquet.thrift; field id 5 is reserved for
+@key_value_metadata@. Strict readers (pyarrow, the dataframe
+library, parquet-mr's footer parser) raise on the wrong slot.
+-}
+pattern FileMetadata_CreatedBy :: Text -> (Int16, TV.Value)
+pattern FileMetadata_CreatedBy t = (6, TV.String t)
+
+
+{- | @FileMetaData.column_orders@ is field id 7 in
+parquet.thrift. The list is parallel to the leaf-column
+order in 'fmSchema' and tells readers how to compare
+BYTE_ARRAY statistics (every modern writer emits this; the
+column index without it is unreliable for pushdown on
+string columns).
+-}
+pattern FileMetadata_ColumnOrders :: Vector TV.Value -> (Int16, TV.Value)
+pattern FileMetadata_ColumnOrders xs <- (7, TV.List _ xs)
+  where
+    FileMetadata_ColumnOrders xs = (7, TV.List TT_STRUCT xs)
+
+
+pattern FileMetadata_EncryptionAlgorithm :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern FileMetadata_EncryptionAlgorithm fs = (8, TV.Struct fs)
+
+
+pattern FileMetadata_FooterSigningKeyMetadata :: ByteString -> (Int16, TV.Value)
+pattern FileMetadata_FooterSigningKeyMetadata v = (9, TV.Binary v)
+
+
+-- ============================================================
+-- SchemaElement
+-- ============================================================
+
+pattern SchemaElement_Type :: Int32 -> (Int16, TV.Value)
+pattern SchemaElement_Type v = (1, TV.I32 v)
+
+
+pattern SchemaElement_TypeLength :: Int32 -> (Int16, TV.Value)
+pattern SchemaElement_TypeLength v = (2, TV.I32 v)
+
+
+pattern SchemaElement_RepetitionType :: Int32 -> (Int16, TV.Value)
+pattern SchemaElement_RepetitionType v = (3, TV.I32 v)
+
+
+pattern SchemaElement_Name :: Text -> (Int16, TV.Value)
+pattern SchemaElement_Name t = (4, TV.String t)
+
+
+pattern SchemaElement_NumChildren :: Int32 -> (Int16, TV.Value)
+pattern SchemaElement_NumChildren v = (5, TV.I32 v)
+
+
+pattern SchemaElement_ConvertedType :: Int32 -> (Int16, TV.Value)
+pattern SchemaElement_ConvertedType v = (6, TV.I32 v)
+
+
+pattern SchemaElement_Scale :: Int32 -> (Int16, TV.Value)
+pattern SchemaElement_Scale v = (7, TV.I32 v)
+
+
+pattern SchemaElement_Precision :: Int32 -> (Int16, TV.Value)
+pattern SchemaElement_Precision v = (8, TV.I32 v)
+
+
+pattern SchemaElement_FieldId :: Int32 -> (Int16, TV.Value)
+pattern SchemaElement_FieldId v = (9, TV.I32 v)
+
+
+{- | LogicalType is encoded as field 10, holding a struct that
+represents the @LogicalType@ union from @parquet.thrift@.
+The struct carries exactly one field whose id picks the
+variant (StringType=1, MapType=2, …).
+-}
+pattern SchemaElement_LogicalType
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern SchemaElement_LogicalType fs = (10, TV.Struct fs)
+
+
+-- ============================================================
+-- RowGroup
+-- ============================================================
+
+pattern RowGroup_Columns :: Vector TV.Value -> (Int16, TV.Value)
+pattern RowGroup_Columns elems <- (1, TV.List _ elems)
+  where
+    RowGroup_Columns elems = (1, TV.List TT_STRUCT elems)
+
+
+pattern RowGroup_Ordinal :: Int16 -> (Int16, TV.Value)
+pattern RowGroup_Ordinal v = (7, TV.I16 v)
+
+
+pattern RowGroup_TotalByteSize :: Int64 -> (Int16, TV.Value)
+pattern RowGroup_TotalByteSize v = (2, TV.I64 v)
+
+
+pattern RowGroup_NumRows :: Int64 -> (Int16, TV.Value)
+pattern RowGroup_NumRows v = (3, TV.I64 v)
+
+
+{- | @RowGroup.sorting_columns@ is field id 4 — list of
+'SortingColumn' (struct {column_idx, descending, nulls_first}).
+Lets a reader skip ORDER BY when scanning a sorted file.
+-}
+pattern RowGroup_SortingColumns :: Vector TV.Value -> (Int16, TV.Value)
+pattern RowGroup_SortingColumns xs <- (4, TV.List _ xs)
+  where
+    RowGroup_SortingColumns xs = (4, TV.List TT_STRUCT xs)
+
+
+-- ============================================================
+-- SortingColumn
+-- ============================================================
+
+pattern SortingColumn_ColumnIdx :: Int32 -> (Int16, TV.Value)
+pattern SortingColumn_ColumnIdx v = (1, TV.I32 v)
+
+
+pattern SortingColumn_Descending :: Bool -> (Int16, TV.Value)
+pattern SortingColumn_Descending b = (2, TV.Bool b)
+
+
+pattern SortingColumn_NullsFirst :: Bool -> (Int16, TV.Value)
+pattern SortingColumn_NullsFirst b = (3, TV.Bool b)
+
+
+-- ============================================================
+-- ColumnOrder
+-- ============================================================
+-- All three ColumnOrder union variants carry an empty struct.
+columnOrderTypeDefined :: TV.Value
+columnOrderTypeDefined = TV.Struct (V.singleton (1, TV.Struct V.empty))
+
+
+columnOrderIeee754Total :: TV.Value
+columnOrderIeee754Total = TV.Struct (V.singleton (2, TV.Struct V.empty))
+
+
+columnOrderInt96Timestamp :: TV.Value
+columnOrderInt96Timestamp = TV.Struct (V.singleton (3, TV.Struct V.empty))
+
+
+-- ============================================================
+-- ColumnChunk
+-- ============================================================
+
+pattern ColumnChunk_FilePath :: Text -> (Int16, TV.Value)
+pattern ColumnChunk_FilePath t = (1, TV.String t)
+
+
+pattern ColumnChunk_FileOffset :: Int64 -> (Int16, TV.Value)
+pattern ColumnChunk_FileOffset v = (2, TV.I64 v)
+
+
+pattern ColumnChunk_MetaData :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern ColumnChunk_MetaData fs = (3, TV.Struct fs)
+
+
+pattern ColumnChunk_OffsetIndexOffset :: Int64 -> (Int16, TV.Value)
+pattern ColumnChunk_OffsetIndexOffset v = (4, TV.I64 v)
+
+
+pattern ColumnChunk_OffsetIndexLength :: Int32 -> (Int16, TV.Value)
+pattern ColumnChunk_OffsetIndexLength v = (5, TV.I32 v)
+
+
+pattern ColumnChunk_ColumnIndexOffset :: Int64 -> (Int16, TV.Value)
+pattern ColumnChunk_ColumnIndexOffset v = (6, TV.I64 v)
+
+
+pattern ColumnChunk_ColumnIndexLength :: Int32 -> (Int16, TV.Value)
+pattern ColumnChunk_ColumnIndexLength v = (7, TV.I32 v)
+
+
+pattern ColumnChunk_CryptoMetadata :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern ColumnChunk_CryptoMetadata fs = (8, TV.Struct fs)
+
+
+pattern ColumnCryptoMetaData_EncryptionWithFooterKey :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern ColumnCryptoMetaData_EncryptionWithFooterKey fs = (1, TV.Struct fs)
+
+
+pattern ColumnCryptoMetaData_EncryptionWithColumnKey :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern ColumnCryptoMetaData_EncryptionWithColumnKey fs = (2, TV.Struct fs)
+
+
+pattern EncryptionWithColumnKey_PathInSchema :: Vector TV.Value -> (Int16, TV.Value)
+pattern EncryptionWithColumnKey_PathInSchema values <- (1, TV.List _ values)
+  where
+    EncryptionWithColumnKey_PathInSchema values = (1, TV.List TT_STRING values)
+
+
+pattern EncryptionWithColumnKey_KeyMetadata :: ByteString -> (Int16, TV.Value)
+pattern EncryptionWithColumnKey_KeyMetadata value = (2, TV.Binary value)
+
+
+pattern ColumnChunk_EncryptedColumnMetadata :: ByteString -> (Int16, TV.Value)
+pattern ColumnChunk_EncryptedColumnMetadata value = (9, TV.Binary value)
+
+
+-- ============================================================
+-- ColumnMetaData
+-- ============================================================
+
+pattern ColumnMetaData_Type :: Int32 -> (Int16, TV.Value)
+pattern ColumnMetaData_Type v = (1, TV.I32 v)
+
+
+pattern ColumnMetaData_Encodings :: Vector TV.Value -> (Int16, TV.Value)
+pattern ColumnMetaData_Encodings elems <- (2, TV.List _ elems)
+  where
+    ColumnMetaData_Encodings elems = (2, TV.List TT_I32 elems)
+
+
+pattern ColumnMetaData_PathInSchema :: Vector TV.Value -> (Int16, TV.Value)
+pattern ColumnMetaData_PathInSchema elems <- (3, TV.List _ elems)
+  where
+    ColumnMetaData_PathInSchema elems = (3, TV.List TT_STRING elems)
+
+
+pattern ColumnMetaData_Codec :: Int32 -> (Int16, TV.Value)
+pattern ColumnMetaData_Codec v = (4, TV.I32 v)
+
+
+pattern ColumnMetaData_NumValues :: Int64 -> (Int16, TV.Value)
+pattern ColumnMetaData_NumValues v = (5, TV.I64 v)
+
+
+pattern ColumnMetaData_TotalUncompressedSize :: Int64 -> (Int16, TV.Value)
+pattern ColumnMetaData_TotalUncompressedSize v = (6, TV.I64 v)
+
+
+pattern ColumnMetaData_TotalCompressedSize :: Int64 -> (Int16, TV.Value)
+pattern ColumnMetaData_TotalCompressedSize v = (7, TV.I64 v)
+
+
+pattern ColumnMetaData_DataPageOffset :: Int64 -> (Int16, TV.Value)
+pattern ColumnMetaData_DataPageOffset v = (9, TV.I64 v)
+
+
+{- | parquet.thrift @ColumnMetaData.index_page_offset@ (field
+10). Optional; we don't currently consume it but keeping
+the slot reserved means we never collide with it on
+subsequent additions.
+-}
+pattern ColumnMetaData_IndexPageOffset :: Int64 -> (Int16, TV.Value)
+pattern ColumnMetaData_IndexPageOffset v = (10, TV.I64 v)
+
+
+{- | parquet.thrift @ColumnMetaData.dictionary_page_offset@
+(field 11). Byte offset of the dictionary page; lives
+/before/ 'ColumnMetaData_DataPageOffset' when present.
+Modern writers (pyarrow / duckdb / polars / parquet-mr)
+always populate this for dictionary-encoded columns; readers
+that ignore it can't access the dictionary, so RLE_DICTIONARY
+pages fail to decode.
+-}
+pattern ColumnMetaData_DictionaryPageOffset :: Int64 -> (Int16, TV.Value)
+pattern ColumnMetaData_DictionaryPageOffset v = (11, TV.I64 v)
+
+
+pattern ColumnMetaData_Statistics
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern ColumnMetaData_Statistics fs = (12, TV.Struct fs)
+
+
+pattern ColumnMetaData_BloomFilterOffset :: Int64 -> (Int16, TV.Value)
+pattern ColumnMetaData_BloomFilterOffset v = (14, TV.I64 v)
+
+
+pattern ColumnMetaData_BloomFilterLength :: Int32 -> (Int16, TV.Value)
+pattern ColumnMetaData_BloomFilterLength v = (15, TV.I32 v)
+
+
+-- ============================================================
+-- Statistics
+-- ============================================================
+
+pattern Statistics_Max :: ByteString -> (Int16, TV.Value)
+pattern Statistics_Max v = (1, TV.Binary v)
+
+
+pattern Statistics_Min :: ByteString -> (Int16, TV.Value)
+pattern Statistics_Min v = (2, TV.Binary v)
+
+
+pattern Statistics_NanCount :: Int64 -> (Int16, TV.Value)
+pattern Statistics_NanCount v = (9, TV.I64 v)
+
+
+pattern Statistics_NullCount :: Int64 -> (Int16, TV.Value)
+pattern Statistics_NullCount v = (3, TV.I64 v)
+
+
+pattern Statistics_DistinctCount :: Int64 -> (Int16, TV.Value)
+pattern Statistics_DistinctCount v = (4, TV.I64 v)
+
+
+pattern Statistics_MaxValue :: ByteString -> (Int16, TV.Value)
+pattern Statistics_MaxValue v = (5, TV.Binary v)
+
+
+pattern Statistics_MinValue :: ByteString -> (Int16, TV.Value)
+pattern Statistics_MinValue v = (6, TV.Binary v)
+
+
+pattern Statistics_MaxValueExact :: Bool -> (Int16, TV.Value)
+pattern Statistics_MaxValueExact v = (7, TV.Bool v)
+
+
+pattern Statistics_MinValueExact :: Bool -> (Int16, TV.Value)
+pattern Statistics_MinValueExact v = (8, TV.Bool v)
+
+
+-- ============================================================
+-- PageHeader
+-- ============================================================
+
+pattern PageHeader_Type :: Int32 -> (Int16, TV.Value)
+pattern PageHeader_Type v = (1, TV.I32 v)
+
+
+pattern PageHeader_UncompressedSize :: Int32 -> (Int16, TV.Value)
+pattern PageHeader_UncompressedSize v = (2, TV.I32 v)
+
+
+pattern PageHeader_CompressedSize :: Int32 -> (Int16, TV.Value)
+pattern PageHeader_CompressedSize v = (3, TV.I32 v)
+
+
+pattern PageHeader_Crc :: Int32 -> (Int16, TV.Value)
+pattern PageHeader_Crc v = (4, TV.I32 v)
+
+
+pattern PageHeader_DataPageHeader
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern PageHeader_DataPageHeader fs = (5, TV.Struct fs)
+
+
+pattern PageHeader_DictionaryPageHeader
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern PageHeader_DictionaryPageHeader fs = (7, TV.Struct fs)
+
+
+pattern PageHeader_DataPageHeaderV2
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern PageHeader_DataPageHeaderV2 fs = (8, TV.Struct fs)
+
+
+-- ============================================================
+-- DataPageHeader
+-- ============================================================
+
+pattern DataPageHeader_NumValues :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeader_NumValues v = (1, TV.I32 v)
+
+
+pattern DataPageHeader_Encoding :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeader_Encoding v = (2, TV.I32 v)
+
+
+{- | Field 3 (@definition_level_encoding@) and field 4
+(@repetition_level_encoding@) are both marked /required/ in
+parquet.thrift's @DataPageHeader@. For max-def-level-0 columns
+the encoded level data is zero bytes regardless, but strict
+readers (pyarrow, parquet-mr, the dataframe library) still
+require the fields to be present in the page header.
+-}
+pattern DataPageHeader_DefinitionLevelEncoding :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeader_DefinitionLevelEncoding v = (3, TV.I32 v)
+
+
+pattern DataPageHeader_RepetitionLevelEncoding :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeader_RepetitionLevelEncoding v = (4, TV.I32 v)
+
+
+-- ============================================================
+-- DictionaryPageHeader
+-- ============================================================
+
+pattern DictionaryPageHeader_NumValues :: Int32 -> (Int16, TV.Value)
+pattern DictionaryPageHeader_NumValues v = (1, TV.I32 v)
+
+
+pattern DictionaryPageHeader_Encoding :: Int32 -> (Int16, TV.Value)
+pattern DictionaryPageHeader_Encoding v = (2, TV.I32 v)
+
+
+-- ============================================================
+-- DataPageHeaderV2
+-- ============================================================
+
+pattern DataPageHeaderV2_NumValues :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeaderV2_NumValues v = (1, TV.I32 v)
+
+
+pattern DataPageHeaderV2_NumNulls :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeaderV2_NumNulls v = (2, TV.I32 v)
+
+
+pattern DataPageHeaderV2_NumRows :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeaderV2_NumRows v = (3, TV.I32 v)
+
+
+pattern DataPageHeaderV2_Encoding :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeaderV2_Encoding v = (4, TV.I32 v)
+
+
+pattern DataPageHeaderV2_DefinitionLevelsByteLength
+  :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeaderV2_DefinitionLevelsByteLength v = (5, TV.I32 v)
+
+
+pattern DataPageHeaderV2_RepetitionLevelsByteLength
+  :: Int32 -> (Int16, TV.Value)
+pattern DataPageHeaderV2_RepetitionLevelsByteLength v = (6, TV.I32 v)
+
+
+pattern DataPageHeaderV2_IsCompressed :: Bool -> (Int16, TV.Value)
+pattern DataPageHeaderV2_IsCompressed v = (7, TV.Bool v)
+
+
+-- ============================================================
+-- OffsetIndex
+-- ============================================================
+
+pattern OffsetIndex_PageLocations :: Vector TV.Value -> (Int16, TV.Value)
+pattern OffsetIndex_PageLocations elems <- (1, TV.List _ elems)
+  where
+    OffsetIndex_PageLocations elems = (1, TV.List TT_STRUCT elems)
+
+
+pattern OffsetIndex_UnencodedByteArrayDataBytes
+  :: Vector TV.Value -> (Int16, TV.Value)
+pattern OffsetIndex_UnencodedByteArrayDataBytes elems <- (2, TV.List _ elems)
+  where
+    OffsetIndex_UnencodedByteArrayDataBytes elems =
+      (2, TV.List TT_I64 elems)
+
+
+-- ============================================================
+-- PageLocation
+-- ============================================================
+
+pattern PageLocation_Offset :: Int64 -> (Int16, TV.Value)
+pattern PageLocation_Offset v = (1, TV.I64 v)
+
+
+pattern PageLocation_CompressedPageSize :: Int32 -> (Int16, TV.Value)
+pattern PageLocation_CompressedPageSize v = (2, TV.I32 v)
+
+
+pattern PageLocation_FirstRowIndex :: Int64 -> (Int16, TV.Value)
+pattern PageLocation_FirstRowIndex v = (3, TV.I64 v)
+
+
+-- ============================================================
+-- ColumnIndex
+-- ============================================================
+
+pattern ColumnIndex_NullPages :: Vector TV.Value -> (Int16, TV.Value)
+pattern ColumnIndex_NullPages elems <- (1, TV.List _ elems)
+  where
+    ColumnIndex_NullPages elems = (1, TV.List TT_BOOL elems)
+
+
+pattern ColumnIndex_MinValues :: Vector TV.Value -> (Int16, TV.Value)
+pattern ColumnIndex_MinValues elems <- (2, TV.List _ elems)
+  where
+    ColumnIndex_MinValues elems = (2, TV.List TT_STRING elems)
+
+
+pattern ColumnIndex_MaxValues :: Vector TV.Value -> (Int16, TV.Value)
+pattern ColumnIndex_MaxValues elems <- (3, TV.List _ elems)
+  where
+    ColumnIndex_MaxValues elems = (3, TV.List TT_STRING elems)
+
+
+pattern ColumnIndex_BoundaryOrder :: Int32 -> (Int16, TV.Value)
+pattern ColumnIndex_BoundaryOrder v = (4, TV.I32 v)
+
+
+pattern ColumnIndex_NullCounts :: Vector TV.Value -> (Int16, TV.Value)
+pattern ColumnIndex_NullCounts elems <- (5, TV.List _ elems)
+  where
+    ColumnIndex_NullCounts elems = (5, TV.List TT_I64 elems)
+
+
+pattern ColumnIndex_NanCounts :: Vector TV.Value -> (Int16, TV.Value)
+pattern ColumnIndex_NanCounts elems <- (8, TV.List _ elems)
+  where
+    ColumnIndex_NanCounts elems = (8, TV.List TT_I64 elems)
+
+
+pattern ColumnIndex_RepetitionLevelHistograms
+  :: Vector TV.Value -> (Int16, TV.Value)
+pattern ColumnIndex_RepetitionLevelHistograms elems <- (6, TV.List _ elems)
+  where
+    ColumnIndex_RepetitionLevelHistograms elems =
+      (6, TV.List TT_I64 elems)
+
+
+pattern ColumnIndex_DefinitionLevelHistograms
+  :: Vector TV.Value -> (Int16, TV.Value)
+pattern ColumnIndex_DefinitionLevelHistograms elems <- (7, TV.List _ elems)
+  where
+    ColumnIndex_DefinitionLevelHistograms elems =
+      (7, TV.List TT_I64 elems)
+
+
+-- ============================================================
+-- BloomFilterHeader
+-- ============================================================
+--
+-- Parquet's BloomFilterHeader carries three nested "enum-tag structs",
+-- each being a union where one empty struct variant is emitted:
+--
+
+-- * @algorithm@: only @BLOCK@ (variant 1) is defined.
+
+
+-- * @hash@:      only @XXHASH@ (variant 1) is defined.
+
+
+-- * @compression@: only @UNCOMPRESSED@ (variant 1) is defined.
+
+
+pattern BloomFilterHeader_NumBytes :: Int32 -> (Int16, TV.Value)
+pattern BloomFilterHeader_NumBytes v = (1, TV.I32 v)
+
+
+pattern BloomFilterHeader_Algorithm
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern BloomFilterHeader_Algorithm fs = (2, TV.Struct fs)
+
+
+pattern BloomFilterHeader_Hash
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern BloomFilterHeader_Hash fs = (3, TV.Struct fs)
+
+
+pattern BloomFilterHeader_Compression
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern BloomFilterHeader_Compression fs = (4, TV.Struct fs)
+
+
+-- ============================================================
+-- FileCryptoMetaData
+-- ============================================================
+
+pattern FileCryptoMetaData_EncryptionAlgorithm
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern FileCryptoMetaData_EncryptionAlgorithm fs = (1, TV.Struct fs)
+
+
+pattern FileCryptoMetaData_KeyMetadata :: ByteString -> (Int16, TV.Value)
+pattern FileCryptoMetaData_KeyMetadata v = (2, TV.Binary v)
+
+
+-- ============================================================
+-- EncryptionAlgorithm
+-- ============================================================
+
+pattern EncryptionAlgorithm_AesGcmV1
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern EncryptionAlgorithm_AesGcmV1 fs = (1, TV.Struct fs)
+
+
+pattern EncryptionAlgorithm_AesGcmCtrV1
+  :: Vector (Int16, TV.Value) -> (Int16, TV.Value)
+pattern EncryptionAlgorithm_AesGcmCtrV1 fs = (2, TV.Struct fs)
+
+
+-- ============================================================
+-- AesGcmV1
+-- ============================================================
+
+pattern AesGcmV1_AadPrefix :: ByteString -> (Int16, TV.Value)
+pattern AesGcmV1_AadPrefix v = (1, TV.Binary v)
+
+
+pattern AesGcmV1_AadFileUnique :: ByteString -> (Int16, TV.Value)
+pattern AesGcmV1_AadFileUnique v = (2, TV.Binary v)
+
+
+pattern AesGcmV1_SupplyAadPrefix :: Bool -> (Int16, TV.Value)
+pattern AesGcmV1_SupplyAadPrefix v = (3, TV.Bool v)
diff --git a/src/Parquet/Timestamp.hs b/src/Parquet/Timestamp.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Timestamp.hs
@@ -0,0 +1,22 @@
+{- | Lossless modern signed96 TIMESTAMP and legacy Julian-day INT96 values.
+
+The Arrow bridge infers distinct wireform extension fields backed by exact
+12-byte storage. Use 'projectTimestampColumn' or the bridge's schema projection
+for checked conversion to an ordinary Arrow timestamp. These extensions are
+wireform-specific, not canonical Apache Arrow extension types.
+-}
+module Parquet.Timestamp (
+  Timestamp96 (..),
+  TimestampEncoding (..),
+  timestamp96FromInteger,
+  timestamp96ToInteger,
+  encodeTimestamp96,
+  decodeTimestamp96,
+  decodeJulianInt96,
+  timestampField,
+  timestampEncoding,
+  projectTimestampColumn,
+) where
+
+import Parquet.Timestamp.Internal
+
diff --git a/src/Parquet/Timestamp/Internal.hs b/src/Parquet/Timestamp/Internal.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Timestamp/Internal.hs
@@ -0,0 +1,255 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE UnboxedSums #-}
+
+{- | Lossless timestamp storage and checked projections. The extension names
+below belong to wireform; they are not canonical Apache Arrow extensions.
+-}
+module Parquet.Timestamp.Internal where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Control.Monad (unless)
+import Control.Monad.ST (runST)
+import Data.Bits (shiftL, shiftR, (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as B
+import Data.ByteString.Lazy qualified as BL
+import Data.ByteString.Unsafe qualified as U
+import Data.Int (Int32, Int64)
+import Data.Text (Text)
+import Data.Vector qualified as V
+import Data.Vector.Storable qualified as S
+import Data.Vector.Storable.Mutable qualified as M
+import Data.Word (Word64)
+import Parquet.Types qualified as P
+
+
+{- | A signed two's-complement 96-bit integer, with a signed high word and
+unsigned low word. Every constructor value is valid. Units belong to the
+column's 'TimestampEncoding', not to this integer.
+-}
+data Timestamp96 = Timestamp96
+  { timestamp96High :: {-# UNPACK #-} !Int32
+  , timestamp96Low :: {-# UNPACK #-} !Word64
+  }
+  deriving (Show, Eq, Ord)
+
+
+{- | Distinct 12-byte timestamp formats. 'SignedTimestamp96' counts the named
+units since the Unix epoch. 'JulianInt96' stores a signed Julian day and
+signed nanoseconds, as used by legacy Parquet writers. Non-normalized
+nanoseconds are preserved; scalar/projection helpers normalize arithmetically.
+-}
+data TimestampEncoding = SignedTimestamp96 !Bool !P.LtTimeUnit | JulianInt96
+  deriving (Show, Eq)
+
+
+-- | Construct a timestamp count without truncation.
+timestamp96FromInteger :: Integer -> Either String Timestamp96
+timestamp96FromInteger value
+  | value < negate (2 ^ (95 :: Int)) || value >= 2 ^ (95 :: Int) = Left "Parquet.Timestamp: count exceeds signed96"
+  | otherwise = Right (Timestamp96 (fromInteger (value `shiftR` 64)) (fromInteger value))
+
+
+{- | Recover the full signed count. This scalar convenience function uses
+arbitrary-precision arithmetic; column projection uses concrete word loops.
+-}
+timestamp96ToInteger :: Timestamp96 -> Integer
+timestamp96ToInteger (Timestamp96 high low) = (toInteger high `shiftL` 64) + toInteger low
+
+
+-- | The modern TIMESTAMP fixed12 representation: signed little-endian counts.
+encodeTimestamp96 :: Timestamp96 -> ByteString
+encodeTimestamp96 (Timestamp96 high low) = BL.toStrict (B.toLazyByteString (B.word64LE low <> B.int32LE high))
+
+
+-- | Decode exactly 12 bytes; every signed96 bit pattern is a valid count.
+decodeTimestamp96 :: ByteString -> Either String Timestamp96
+decodeTimestamp96 bytes
+  | BS.length bytes /= 12 = Left "Parquet.Timestamp: expected12bytes"
+  | otherwise = Right (Timestamp96 (fromIntegral (wordAt bytes 8 4)) (wordAt bytes 0 8))
+
+
+{- | Decode legacy INT96 into a full signed96 count of nanoseconds since the
+Unix epoch. Signed/non-normalized nanoseconds are included without wrapping.
+-}
+decodeJulianInt96 :: ByteString -> Either String Timestamp96
+decodeJulianInt96 bytes
+  | BS.length bytes /= 12 = Left "Parquet.Timestamp: expected12bytes"
+  | otherwise = timestamp96FromInteger (toInteger days * 86400000000000 + toInteger nanos)
+  where
+    nanos = fromIntegral (wordAt bytes 0 8) :: Int64
+    days = fromIntegral (fromIntegral (wordAt bytes 8 4) :: Int32) - 2440588 :: Int64
+
+
+{- | Make a lossless Arrow field backed by FixedSizeBinary(12). Modern storage
+uses extension @wireform.parquet.timestamp96@ with metadata
+@millis:utc@, @millis:local@, @micros:utc@, @micros:local@,
+@nanos:utc@ or @nanos:local@. Legacy storage uses
+@wireform.parquet.int96@ with empty metadata. The 12 payload bytes retain
+the original Parquet representation, independently of Arrow endianness.
+-}
+timestampField :: Text -> Bool -> TimestampEncoding -> A.Field
+timestampField name nullable encoding =
+  (A.defaultField name nullable (A.AFixedSizeBinary 12) V.empty)
+    { A.fieldMetadata = V.fromList [("ARROW:extension:name", extensionName encoding), ("ARROW:extension:metadata", parameters encoding)]
+    }
+
+
+extensionName :: TimestampEncoding -> Text
+extensionName SignedTimestamp96 {} = "wireform.parquet.timestamp96"
+extensionName JulianInt96 = "wireform.parquet.int96"
+
+
+parameters :: TimestampEncoding -> Text
+parameters JulianInt96 = ""
+parameters (SignedTimestamp96 adjusted unit) = unitName unit <> if adjusted then ":utc" else ":local"
+
+
+unitName :: P.LtTimeUnit -> Text
+unitName P.LtMillis = "millis"
+unitName P.LtMicros = "micros"
+unitName P.LtNanos = "nanos"
+
+
+isTimestampField :: A.Field -> Bool
+isTimestampField = V.any (\entry -> entry == ("ARROW:extension:name", "wireform.parquet.timestamp96") || entry == ("ARROW:extension:name", "wireform.parquet.int96")) . A.fieldMetadata
+
+
+{- | Inspect and validate a wireform timestamp extension. Other fields return
+Nothing; duplicate names, malformed parameters and incompatible storage fail.
+-}
+timestampEncoding :: A.Field -> Either String (Maybe TimestampEncoding)
+timestampEncoding field
+  | not (isTimestampField field) = Right Nothing
+  | otherwise = do
+      encoding <- case (V.toList (values "ARROW:extension:name"), V.toList (values "ARROW:extension:metadata")) of
+        (["wireform.parquet.int96"], []) -> Right JulianInt96
+        (["wireform.parquet.int96"], [""]) -> Right JulianInt96
+        (["wireform.parquet.timestamp96"], [text]) -> case text of
+          "millis:utc" -> Right (SignedTimestamp96 True P.LtMillis)
+          "millis:local" -> Right (SignedTimestamp96 False P.LtMillis)
+          "micros:utc" -> Right (SignedTimestamp96 True P.LtMicros)
+          "micros:local" -> Right (SignedTimestamp96 False P.LtMicros)
+          "nanos:utc" -> Right (SignedTimestamp96 True P.LtNanos)
+          "nanos:local" -> Right (SignedTimestamp96 False P.LtNanos)
+          _ -> invalid
+        _ -> invalid
+      unless (A.fieldType field == A.AFixedSizeBinary 12 && A.fieldDictionary field == Nothing && V.null (A.fieldChildren field)) invalid
+      Right (Just encoding)
+  where
+    values key = V.map snd (V.filter ((== key) . fst) (A.fieldMetadata field))
+    invalid = Left "Parquet.Timestamp: invalid timestamp extension/storage"
+
+
+schemaEncoding :: P.SchemaElement -> Either String (Maybe TimestampEncoding)
+schemaEncoding field = case (P.seType field, P.seLogicalType field) of
+  (Just P.PTFixedLenByteArray, Just (P.LTTimestamp adjusted unit))
+    | P.seTypeLength field == Just 12 -> Right (Just (SignedTimestamp96 adjusted unit))
+    | otherwise -> Left "Parquet.Timestamp: TIMESTAMP fixed storage must have length12"
+  (_, Just P.LTTimestamp {}) | P.seType field /= Just P.PTInt64 -> Left "Parquet.Timestamp: unsupported TIMESTAMP storage"
+  (Just P.PTInt96, _) -> Right (Just JulianInt96)
+  _ -> Right Nothing
+
+
+{- | Decide a typed projection before reading values. Removing the extension
+explicitly permits raw FixedSizeBinary(12) access. Retaining it requires
+exactly the same encoding and parameters. Signed96 narrows only to the same
+unit and UTC/local semantics; INT96 supports exact second/ms/us/ns conversion.
+-}
+fieldsCompatible :: A.Field -> A.Field -> Either String Bool
+fieldsCompatible source target = do
+  actual <- timestampEncoding source
+  wanted <- timestampEncoding target
+  Right $ case (actual, wanted, A.fieldType target) of
+    (Just encoding, Just same, _) -> encoding == same
+    (Just _, Nothing, A.AFixedSizeBinary 12) -> not (V.any ((== "ARROW:extension:name") . fst) (A.fieldMetadata target))
+    (Just (SignedTimestamp96 adjusted unit), Nothing, A.ATimestamp targetUnit zone) -> noExtension target && arrowUnit unit == targetUnit && adjusted == maybe False (const True) zone
+    (Just JulianInt96, Nothing, A.ATimestamp _ Nothing) -> noExtension target
+    _ -> False
+
+
+noExtension :: A.Field -> Bool
+noExtension = not . V.any ((== "ARROW:extension:name") . fst) . A.fieldMetadata
+
+
+arrowUnit :: P.LtTimeUnit -> A.TimeUnit
+arrowUnit P.LtMillis = A.Millisecond
+arrowUnit P.LtMicros = A.Microsecond
+arrowUnit P.LtNanos = A.Nanosecond
+
+
+{- | Convert an extension column to a checked Arrow timestamp, or retain its
+exact storage. Null payloads are never inspected. Overflow and sub-unit
+precision loss fail, including below nested nullable ancestors after assembly.
+-}
+projectTimestampColumn :: A.Field -> A.Field -> C.ColumnArray -> Either String C.ColumnArray
+projectTimestampColumn source target column = do
+  compatible <- fieldsCompatible source target
+  unless compatible (Left "Parquet.Timestamp: incompatible timestamp projection")
+  encoding <- timestampEncoding source >>= maybe (Left "Parquet.Timestamp: source is not a timestamp extension") Right
+  unless (A.fieldNullable target || C.nullCount column == 0) (Left "Parquet.Timestamp: non-nullable target contains nulls")
+  case (A.fieldType target, column) of
+    (A.AFixedSizeBinary 12, C.ColFixedSizeBinary 12 _ _ _) -> validateTimestampColumn encoding column
+    (A.ATimestamp unit _, C.ColFixedSizeBinary 12 count validity bytes) -> do
+      let project = case encoding of
+            SignedTimestamp96 {} -> signed64At# bytes
+            JulianInt96 -> julian64At# unit bytes
+      values <- runST $ do
+        output <- M.unsafeNew count
+        let loop !index
+              | index == count = Right <$> S.unsafeFreeze output
+              | not (C.isValidAt validity index) = M.unsafeWrite output index 0 >> loop (index + 1)
+              | otherwise = case project (index * 12) of
+                  (# message | #) -> pure (Left message)
+                  (# | value #) -> M.unsafeWrite output index value >> loop (index + 1)
+        loop 0
+      C.mkPrim C.PTimestamp validity values
+    _ -> Left "Parquet.Timestamp: expected FixedSizeBinary(12) column"
+
+
+validateTimestampColumn :: TimestampEncoding -> C.ColumnArray -> Either String C.ColumnArray
+validateTimestampColumn _ column = case column of
+  C.ColFixedSizeBinary 12 _ _ _ -> Right column
+  _ -> Left "Parquet.Timestamp: expected FixedSizeBinary(12) column"
+
+
+wordAt :: ByteString -> Int -> Int -> Word64
+wordAt bytes offset width = loop 0 0
+  where
+    loop !index !value
+      | index == width = value
+      | otherwise = loop (index + 1) (value .|. (fromIntegral (U.unsafeIndex bytes (offset + index)) `shiftL` (index * 8)))
+{-# INLINE wordAt #-}
+
+
+signed64At# :: ByteString -> Int -> (# String | Int64 #)
+signed64At# bytes offset =
+  let low = fromIntegral (wordAt bytes offset 8) :: Int64
+      high = fromIntegral (wordAt bytes (offset + 8) 4) :: Int32
+  in if high == (if low < 0 then -1 else 0)
+       then (# | low #)
+       else (# "Parquet.Timestamp: timestamp exceeds Arrow Int64 range" | #)
+{-# INLINE signed64At# #-}
+
+
+julian64At# :: A.TimeUnit -> ByteString -> Int -> (# String | Int64 #)
+julian64At# unit bytes offset =
+  let factor = case unit of A.Second -> 1000000000; A.Millisecond -> 1000000; A.Microsecond -> 1000; A.Nanosecond -> 1
+      unitsPerDay = 86400000000000 `quot` factor
+      nanos = fromIntegral (wordAt bytes offset 8) :: Int64
+      (carry, normalized) = nanos `divMod` 86400000000000
+      day = fromIntegral (fromIntegral (wordAt bytes (offset + 8) 4) :: Int32) - 2440588 + carry :: Int64
+      (fraction, rest) = normalized `quotRem` factor
+      (lowDay, lowFraction) = (minBound :: Int64) `divMod` unitsPerDay
+      (highDay, highFraction) = (maxBound :: Int64) `divMod` unitsPerDay
+  in if rest /= 0
+       then (# "Parquet.Timestamp: timestamp projection loses sub-unit precision" | #)
+       else
+         if day < lowDay || day > highDay || (day == lowDay && fraction < lowFraction) || (day == highDay && fraction > highFraction)
+           then (# "Parquet.Timestamp: timestamp exceeds Arrow Int64 range" | #)
+           else (# | day * unitsPerDay + fraction #)
+{-# INLINE julian64At# #-}
diff --git a/src/Parquet/Types.hs b/src/Parquet/Types.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Types.hs
@@ -0,0 +1,583 @@
+{- | Apache Parquet file metadata types.
+
+Parquet is a columnar storage format. The metadata (file footer, schema,
+row groups, column chunks) is Thrift Compact Protocol encoded. These types
+mirror the Parquet spec's Thrift definitions.
+-}
+module Parquet.Types (
+  FileMetadata (..),
+  KeyValue (..),
+  SchemaElement (..),
+  hasDefinedStatisticsOrder,
+  hasCompatiblePhysicalType,
+  RowGroup (..),
+  SortingColumn (..),
+  ColumnOrder (..),
+  ColumnChunk (..),
+  ColumnMetadata (..),
+  ParquetType (..),
+  Repetition (..),
+  Encoding (..),
+  Compression (..),
+  ConvertedType (..),
+  LogicalType (..),
+  LtTimeUnit (..),
+  GeometryParameters (..),
+  GeographyParameters (..),
+  EdgeInterpolationAlgorithm (..),
+  defaultGeometryParameters,
+  defaultGeographyParameters,
+  interpolationAlgorithmToInt,
+  intToInterpolationAlgorithm,
+  Statistics (..),
+  PageLocation (..),
+  OffsetIndex (..),
+  ColumnIndex (..),
+  BoundaryOrder (..),
+  parquetTypeToInt,
+  intToParquetType,
+  boundaryOrderToInt,
+  intToBoundaryOrder,
+) where
+
+import Control.DeepSeq (NFData)
+import Data.ByteString (ByteString)
+import Data.Int (Int32, Int64)
+import Data.Text (Text)
+import Data.Vector (Vector)
+import GHC.Generics (Generic)
+import Parquet.Decimal (decimalPrecisionFits)
+
+
+data ParquetType
+  = PTBoolean
+  | PTInt32
+  | PTInt64
+  | PTInt96
+  | PTFloat
+  | PTDouble
+  | PTByteArray
+  | PTFixedLenByteArray
+  deriving stock (Show, Eq, Enum, Bounded, Generic)
+  deriving anyclass (NFData)
+
+
+parquetTypeToInt :: ParquetType -> Int32
+parquetTypeToInt = \case
+  PTBoolean -> 0
+  PTInt32 -> 1
+  PTInt64 -> 2
+  PTInt96 -> 3
+  PTFloat -> 4
+  PTDouble -> 5
+  PTByteArray -> 6
+  PTFixedLenByteArray -> 7
+
+
+intToParquetType :: Int32 -> Maybe ParquetType
+intToParquetType = \case
+  0 -> Just PTBoolean
+  1 -> Just PTInt32
+  2 -> Just PTInt64
+  3 -> Just PTInt96
+  4 -> Just PTFloat
+  5 -> Just PTDouble
+  6 -> Just PTByteArray
+  7 -> Just PTFixedLenByteArray
+  _ -> Nothing
+
+
+data Repetition = Required | Optional | Repeated
+  deriving stock (Show, Eq, Enum, Bounded, Generic)
+  deriving anyclass (NFData)
+
+
+data Encoding
+  = Plain
+  | PlainDictionary
+  | RLE
+  | BitPacked
+  | DeltaBinaryPacked
+  | DeltaLengthByteArray
+  | DeltaByteArray
+  | RLEDictionary
+  | ByteStreamSplit
+  | Alp
+  deriving stock (Show, Eq, Enum, Bounded, Generic)
+  deriving anyclass (NFData)
+
+
+data Compression
+  = Uncompressed
+  | Snappy
+  | GZip
+  | LZO
+  | Brotli
+  | LZ4
+  | ZSTD
+  | LZ4Raw
+  deriving stock (Show, Eq, Enum, Bounded, Generic)
+  deriving anyclass (NFData)
+
+
+data ConvertedType
+  = CTUtf8
+  | CTMap
+  | CTMapKeyValue
+  | CTList
+  | CTEnum
+  | CTDecimal
+  | CTDate
+  | CTTimeMillis
+  | CTTimeMicros
+  | CTTimestampMillis
+  | CTTimestampMicros
+  | CTUInt8
+  | CTUInt16
+  | CTUInt32
+  | CTUInt64
+  | CTInt8
+  | CTInt16
+  | CTInt32
+  | CTInt64
+  | CTJson
+  | CTBson
+  | CTInterval
+  deriving stock (Show, Eq, Enum, Bounded, Generic)
+  deriving anyclass (NFData)
+
+
+-- | LogicalType time/timestamp unit (parquet.thrift @TimeUnit@).
+data LtTimeUnit = LtMillis | LtMicros | LtNanos
+  deriving stock (Show, Eq, Enum, Bounded, Generic)
+  deriving anyclass (NFData)
+
+
+-- | Preserve absence separately from an explicit CRS. Absent means OGC:CRS84.
+data GeometryParameters = GeometryParameters
+  { geometryCrs :: !(Maybe Text)
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+-- | Absent CRS means OGC:CRS84; absent interpolation means spherical edges.
+data GeographyParameters = GeographyParameters
+  { geographyCrs :: !(Maybe Text)
+  , geographyAlgorithm :: !(Maybe EdgeInterpolationAlgorithm)
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data EdgeInterpolationAlgorithm
+  = Spherical
+  | Vincenty
+  | Thomas
+  | Andoyer
+  | Karney
+  | UnrecognizedInterpolation {-# UNPACK #-} !Int32
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+defaultGeometryParameters :: GeometryParameters
+defaultGeometryParameters = GeometryParameters Nothing
+
+
+defaultGeographyParameters :: GeographyParameters
+defaultGeographyParameters = GeographyParameters Nothing Nothing
+
+
+interpolationAlgorithmToInt :: EdgeInterpolationAlgorithm -> Int32
+interpolationAlgorithmToInt Spherical = 0
+interpolationAlgorithmToInt Vincenty = 1
+interpolationAlgorithmToInt Thomas = 2
+interpolationAlgorithmToInt Andoyer = 3
+interpolationAlgorithmToInt Karney = 4
+interpolationAlgorithmToInt (UnrecognizedInterpolation code) = code
+
+
+intToInterpolationAlgorithm :: Int32 -> EdgeInterpolationAlgorithm
+intToInterpolationAlgorithm 0 = Spherical
+intToInterpolationAlgorithm 1 = Vincenty
+intToInterpolationAlgorithm 2 = Thomas
+intToInterpolationAlgorithm 3 = Andoyer
+intToInterpolationAlgorithm 4 = Karney
+intToInterpolationAlgorithm code = UnrecognizedInterpolation code
+
+
+{- | Modern Parquet logical-type annotation. Mirrors the
+@LogicalType@ union in @parquet.thrift@. Each constructor
+corresponds to a single field of the union.
+
+This ADT is the modern annotation slot ('seLogicalType');
+'ConvertedType' is the legacy slot kept around for older
+readers. Writers should populate /both/ slots when possible.
+-}
+data LogicalType
+  = LTString
+  | LTMap
+  | LTList
+  | LTEnum
+  | -- | @(precision, scale)@.
+    LTDecimal !Int32 !Int32
+  | LTDate
+  | LTTime
+      !Bool
+      -- ^ @isAdjustedToUTC@
+      !LtTimeUnit
+      -- ^ unit (millis / micros / nanos)
+  | LTTimestamp
+      !Bool
+      -- ^ @isAdjustedToUTC@
+      !LtTimeUnit
+      -- ^ unit
+  | LTInteger
+      !Int32
+      -- ^ bit width (8, 16, 32, 64)
+      !Bool
+      -- ^ is signed
+  | LTNull
+  | LTJson
+  | LTBson
+  | LTUUID
+  | {- | Parquet IEEE 754 half-precision; physical type is
+    @FIXED_LEN_BYTE_ARRAY(2)@.
+    -}
+    LTFloat16
+  | {- | Parquet geospatial geometry (parquet-format 2.11+);
+    physical type is @BYTE_ARRAY@ holding WKB.
+    -}
+    LTGeometry !GeometryParameters
+  | {- | Parquet geospatial geography (parquet-format 2.11+);
+    physical type is @BYTE_ARRAY@ holding WKB.
+    -}
+    LTGeography !GeographyParameters
+  | -- | A group of optional inline/external byte-reference fields (format 2.14).
+    LTFile
+  | {- | Parquet 'Variant' (semi-structured) annotation. The
+    payload column is itself a struct of (metadata, value)
+    BYTE_ARRAY columns; the carried Int32 is the
+    @specification_version@ field.
+    -}
+    LTVariant !Int32
+  | {- | An unrecognized or malformed modern annotation. Readers may expose
+    the physical storage, but cannot infer a logical ordering from it.
+    -}
+    LTUnsupported
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data SchemaElement = SchemaElement
+  { seName :: !Text
+  , seRepetition :: !(Maybe Repetition)
+  , seType :: !(Maybe ParquetType)
+  , seNumChildren :: !(Maybe Int32)
+  , seConvertedType :: !(Maybe ConvertedType)
+  , seLogicalType :: !(Maybe LogicalType)
+  , seFieldId :: !(Maybe Int32)
+  {- ^ Iceberg's identifier for this leaf column. Required for any
+  Parquet file that participates in an Iceberg table — readers
+  match @field_id@, not @name@. Encoded into Thrift field 9 of
+  @parquet.thrift::SchemaElement@ (field 8 is @precision@, field 7
+  is @scale@).
+  -}
+  , seTypeLength :: !(Maybe Int32)
+  -- ^ Physical byte width for FIXED_LEN_BYTE_ARRAY (Thrift field 2).
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+{- | These annotations explicitly forbid min/max statistics. Raw storage
+order is not a substitute for an undefined logical order.
+-}
+hasDefinedStatisticsOrder :: SchemaElement -> Bool
+hasDefinedStatisticsOrder field =
+  hasCompatiblePhysicalType field && case seLogicalType field of
+    Just LTGeometry {} -> False
+    Just LTGeography {} -> False
+    Just LTFile -> False
+    Just LTNull -> False
+    Just LTVariant {} -> False
+    _ -> seConvertedType field /= Just CTInterval
+
+
+{- | Recognized annotations must use the carriers specified by Parquet.
+Unknown/unsupported combinations cannot supply usable ordered bounds.
+-}
+hasCompatiblePhysicalType :: SchemaElement -> Bool
+hasCompatiblePhysicalType field = case seLogicalType field of
+  Just LTUnsupported -> False
+  Just LTString -> bytes
+  Just LTEnum -> bytes
+  Just LTJson -> bytes
+  Just LTBson -> bytes
+  Just LTGeometry {} -> bytes
+  Just LTGeography {} -> bytes
+  Just LTDate -> physical PTInt32
+  Just (LTTime _ LtMillis) -> physical PTInt32
+  Just (LTTime _ _) -> physical PTInt64
+  Just LTTimestamp {} -> physical PTInt64 || fixed 12
+  Just (LTInteger width _) -> (width `elem` [8, 16, 32] && physical PTInt32) || (width == 64 && physical PTInt64)
+  Just (LTDecimal precision scale) ->
+    precision > 0 && scale >= 0 && scale <= precision && case seType field of
+      Just PTInt32 -> precision <= 9
+      Just PTInt64 -> precision <= 18
+      Just PTByteArray -> True
+      Just PTFixedLenByteArray -> maybe False (decimalPrecisionFits precision) (seTypeLength field)
+      _ -> False
+  Just LTFloat16 -> fixed 2
+  Just LTUUID -> fixed 16
+  Just LTList -> group
+  Just LTMap -> group
+  Just LTVariant {} -> group
+  Just LTFile -> group
+  Just LTNull -> True
+  Nothing -> case seConvertedType field of
+    Just CTUtf8 -> bytes
+    Just CTEnum -> bytes
+    Just CTJson -> bytes
+    Just CTBson -> bytes
+    Just CTDate -> physical PTInt32
+    Just CTTimeMillis -> physical PTInt32
+    Just CTTimeMicros -> physical PTInt64
+    Just CTTimestampMillis -> physical PTInt64
+    Just CTTimestampMicros -> physical PTInt64
+    Just CTUInt8 -> physical PTInt32
+    Just CTUInt16 -> physical PTInt32
+    Just CTUInt32 -> physical PTInt32
+    Just CTUInt64 -> physical PTInt64
+    Just CTInt8 -> physical PTInt32
+    Just CTInt16 -> physical PTInt32
+    Just CTInt32 -> physical PTInt32
+    Just CTInt64 -> physical PTInt64
+    Just CTInterval -> fixed 12
+    Just CTMap -> group
+    Just CTMapKeyValue -> group
+    Just CTList -> group
+    Just CTDecimal -> seType field `elem` (Just <$> [PTInt32, PTInt64, PTByteArray, PTFixedLenByteArray])
+    Nothing -> True
+  where
+    physical ty = seType field == Just ty
+    bytes = physical PTByteArray
+    fixed size = physical PTFixedLenByteArray && seTypeLength field == Just size
+    group = seType field == Nothing
+
+
+data ColumnMetadata = ColumnMetadata
+  { cmType :: !ParquetType
+  , cmEncodings :: !(Vector Encoding)
+  , cmPathInSchema :: !(Vector Text)
+  , cmCodec :: !Compression
+  , cmNumValues :: !Int64
+  , cmTotalUncompressedSize :: !Int64
+  , cmTotalCompressedSize :: !Int64
+  , cmDataPageOffset :: !Int64
+  , cmDictionaryPageOffset :: !(Maybe Int64)
+  {- ^ Byte offset of the (optional) dictionary page (parquet.thrift
+  field 11). When present this is /before/ 'cmDataPageOffset' and
+  callers reading raw column-chunk bytes must start their slice
+  here, not at 'cmDataPageOffset'. Modern writers (pyarrow, polars,
+  duckdb) always populate this when the column uses dictionary
+  encoding.
+  -}
+  , cmStatistics :: !(Maybe Statistics)
+  , cmBloomFilterOffset :: !(Maybe Int64)
+  {- ^ Byte offset from beginning of file to the bloom filter for this
+  column chunk, if a bloom filter is written. Field 14.
+  -}
+  , cmBloomFilterLength :: !(Maybe Int32)
+  {- ^ Length of the bloom filter (header + bitset) in bytes. Field 15
+  (added in parquet-format 2.10).
+  -}
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data ColumnChunk = ColumnChunk
+  { ccFilePath :: !(Maybe Text)
+  , ccFileOffset :: !Int64
+  , ccMetadata :: !(Maybe ColumnMetadata)
+  , ccOffsetIndexOffset :: !(Maybe Int64)
+  {- ^ Byte offset of this column chunk's 'OffsetIndex' (Thrift Compact),
+  relative to the start of the file. Page-index spec, field 4.
+  -}
+  , ccOffsetIndexLength :: !(Maybe Int32)
+  -- ^ Length in bytes of the serialized 'OffsetIndex'. Field 5.
+  , ccColumnIndexOffset :: !(Maybe Int64)
+  {- ^ Byte offset of this column chunk's 'ColumnIndex' (Thrift Compact),
+  relative to the start of the file. Field 6.
+  -}
+  , ccColumnIndexLength :: !(Maybe Int32)
+  -- ^ Length in bytes of the serialized 'ColumnIndex'. Field 7.
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+{- | One entry of @RowGroup.sorting_columns@. Tells readers
+(DuckDB, Trino, parquet-mr) which leaf columns the row
+group is sorted on so they can skip ORDER BY scans.
+-}
+data SortingColumn = SortingColumn
+  { scColumnIdx :: !Int32
+  {- ^ Leaf-column index in the row group (0-based, parallel
+  to @rgColumns@).
+  -}
+  , scDescending :: !Bool
+  -- ^ Sort direction. @False@ = ascending.
+  , scNullsFirst :: !Bool
+  -- ^ Whether nulls sort before non-nulls.
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data RowGroup = RowGroup
+  { rgColumns :: !(Vector ColumnChunk)
+  , rgTotalByteSize :: !Int64
+  , rgNumRows :: !Int64
+  , rgSortingColumns :: !(Maybe (Vector SortingColumn))
+  {- ^ Per-row-group sort metadata. 'Nothing' for unsorted
+  row groups (the common case); populated by writers that
+  want to advertise an ordering. Readers use this to skip
+  an ORDER BY when scanning a sorted file.
+  -}
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+{- | Per-leaf-column ordering rule. parquet-format defines this
+as a union describing natural, IEEE 754 total, or legacy INT96
+timestamp ordering. Without it, statistics
+on BYTE_ARRAY columns can be reported but readers may refuse
+to use them for pushdown.
+-}
+data ColumnOrder
+  = TypeDefinedOrder
+  | IEEE754TotalOrder
+  | Int96TimestampOrder
+  | UnsupportedColumnOrder
+  deriving stock (Show, Eq, Enum, Bounded, Generic)
+  deriving anyclass (NFData)
+
+
+{- | Opaque application metadata. Order, duplicate keys, absent values and
+empty values are retained. Decode values as UTF-8 only when interpreting
+a particular metadata convention (such as a PROJJSON CRS definition).
+-}
+data KeyValue = KeyValue
+  { kvKey :: !ByteString
+  , kvValue :: !(Maybe ByteString)
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data FileMetadata = FileMetadata
+  { fmVersion :: !Int32
+  , fmSchema :: !(Vector SchemaElement)
+  , fmNumRows :: !Int64
+  , fmRowGroups :: !(Vector RowGroup)
+  , fmCreatedBy :: !(Maybe Text)
+  , fmColumnOrders :: !(Maybe (Vector ColumnOrder))
+  {- ^ Per-leaf-column ordering rules (parquet-format field 7).
+  Length must match the leaf-column count when populated.
+  'Nothing' means readers fall back to legacy ordering;
+  modern writers always emit this.
+  -}
+  , fmKeyValueMetadata :: !(Maybe (Vector KeyValue))
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data Statistics = Statistics
+  { statMin :: !(Maybe ByteString)
+  , statMax :: !(Maybe ByteString)
+  , statNullCount :: !(Maybe Int64)
+  , statDistinctCount :: !(Maybe Int64)
+  , statMinValue :: !(Maybe ByteString)
+  , statMaxValue :: !(Maybe ByteString)
+  , statNanCount :: !(Maybe Int64)
+  -- ^ Missing means NaNs may be present, never an implicit zero.
+  , statMinValueExact :: !(Maybe Bool)
+  -- ^ Only @Just True@ proves the modern lower bound is an actual value.
+  , statMaxValueExact :: !(Maybe Bool)
+  -- ^ Only @Just True@ proves the modern upper bound is an actual value.
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data PageLocation = PageLocation
+  { plOffset :: !Int64
+  , plCompressedPageSize :: !Int32
+  , plFirstRowIndex :: !Int64
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+data OffsetIndex = OffsetIndex
+  { oiPageLocations :: !(Vector PageLocation)
+  , oiUnencodedByteArrayDataBytes :: !(Maybe (Vector Int64))
+  {- ^ Per-page unencoded byte counts for BYTE_ARRAY columns (parquet-format
+  2.11+). Same length as 'oiPageLocations' when present; @Nothing@ for
+  non-BYTE_ARRAY columns or older writers.
+  -}
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
+
+
+{- | Page-level boundary ordering for a column index's @min_values@ and
+@max_values@. See @parquet.thrift@ enum @BoundaryOrder@.
+-}
+data BoundaryOrder
+  = OrderUnordered
+  | OrderAscending
+  | OrderDescending
+  deriving stock (Show, Eq, Enum, Bounded, Generic)
+  deriving anyclass (NFData)
+
+
+boundaryOrderToInt :: BoundaryOrder -> Int32
+boundaryOrderToInt = \case
+  OrderUnordered -> 0
+  OrderAscending -> 1
+  OrderDescending -> 2
+
+
+intToBoundaryOrder :: Int32 -> Maybe BoundaryOrder
+intToBoundaryOrder = \case
+  0 -> Just OrderUnordered
+  1 -> Just OrderAscending
+  2 -> Just OrderDescending
+  _ -> Nothing
+
+
+data ColumnIndex = ColumnIndex
+  { ciNullPages :: !(Vector Bool)
+  , ciMinValues :: !(Vector ByteString)
+  , ciMaxValues :: !(Vector ByteString)
+  , ciBoundaryOrder :: !BoundaryOrder
+  , ciNullCounts :: !(Maybe (Vector Int64))
+  , ciNanCounts :: !(Maybe (Vector Int64))
+  -- ^ Per-page NaN counts. Missing counts do not imply zero.
+  , ciRepetitionLevelHistograms :: !(Maybe (Vector Int64))
+  {- ^ Per-page repetition level histograms (flattened: @max_rep + 1@ values
+  per page). Optional, parquet-format 2.11+.
+  -}
+  , ciDefinitionLevelHistograms :: !(Maybe (Vector Int64))
+  {- ^ Per-page definition level histograms (flattened: @max_def + 1@ values
+  per page). Optional, parquet-format 2.11+.
+  -}
+  }
+  deriving stock (Show, Eq, Generic)
+  deriving anyclass (NFData)
diff --git a/src/Parquet/Variant.hs b/src/Parquet/Variant.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Variant.hs
@@ -0,0 +1,699 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | The Parquet Variant v1 binary value format. This module owns the
+metadata/value codec; Parquet column shredding is a separate layer.
+-}
+module Parquet.Variant (
+  Variant (..),
+  EncodedVariant (..),
+  VariantMetadata,
+  metadataBytes,
+  metadataKeys,
+  metadataContains,
+  VariantLimits (..),
+  defaultVariantLimits,
+  encodeVariant,
+  encodeVariantWithLimits,
+  decodeVariant,
+  decodeVariantWithLimits,
+  compileVariantMetadata,
+  compileVariantMetadataWithLimits,
+  buildVariantMetadata,
+  buildVariantMetadataWithLimits,
+  buildVariantMetadataFor,
+  buildVariantMetadataForWithLimits,
+  validateVariantWithMetadata,
+  validateVariantWithMetadataWithLimits,
+  encodeVariantValue,
+  encodeVariantValueWithLimits,
+  decodeVariantValue,
+  decodeVariantValueWithLimits,
+  decodeVariantFragment#,
+) where
+
+import Control.Monad (unless, when)
+import Data.Bits (shiftL, shiftR, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as B
+import Data.ByteString.Lazy qualified as BL
+import Data.Int (Int16, Int32, Int64, Int8)
+import Data.IntMap.Strict qualified as IM
+import Data.Map.Strict (Map)
+import Data.Map.Strict qualified as M
+import Data.Set qualified as S
+import Data.Text (Text)
+import Data.Text.Encoding qualified as TE
+import Data.Vector (Vector)
+import Data.Vector qualified as V
+import Data.Vector.Mutable qualified as MV
+import Data.Word (Word32, Word64, Word8)
+import GHC.Exts (Int (I#), Int#, isTrue#, runRW#, (+#), (==#))
+import GHC.Float (castDoubleToWord64, castFloatToWord32, castWord32ToFloat, castWord64ToDouble)
+import GHC.ST (ST (ST))
+
+
+data Variant
+  = VNull
+  | VBool !Bool
+  | VInt8 !Int8
+  | VInt16 !Int16
+  | VInt32 !Int32
+  | VInt64 !Int64
+  | VDouble !Double
+  | VDecimal4 !Word8 !Int32
+  | VDecimal8 !Word8 !Int64
+  | VDecimal16 !Word8 !Integer
+  | VDate !Int32
+  | VTimestamp !Int64
+  | VTimestampNtz !Int64
+  | VFloat !Float
+  | VBinary !ByteString
+  | VString !Text
+  | VTime !Int64
+  | VTimestampNanos !Int64
+  | VTimestampNtzNanos !Int64
+  | VUuid !ByteString
+  | VObject !(Map Text Variant)
+  | VArray !(Vector Variant)
+  deriving (Show, Eq)
+
+
+data EncodedVariant = EncodedVariant
+  { variantMetadata :: !ByteString
+  , variantValue :: !ByteString
+  }
+  deriving (Show, Eq)
+
+
+{- | Validated shared dictionary. All fallback values inside a shredded
+Variant must use the same dictionary, including names only present in
+typed fields. Keep the original bytes when reading an existing dictionary.
+-}
+data VariantMetadata = VariantMetadata
+  { metadataBytes :: !ByteString
+  , metadataKeys :: !(Vector Text)
+  , metadataIndices :: !(Map Text Int)
+  }
+  deriving (Show, Eq)
+
+
+{- | Bounds on decoded/encoded trees, independently of the byte-buffer size.
+Counts include the root. Callers can raise these for large valid values.
+-}
+data VariantLimits = VariantLimits
+  { variantMaxDepth :: {-# UNPACK #-} !Int
+  , variantMaxValues :: {-# UNPACK #-} !Int
+  , variantMaxDictionaryEntries :: {-# UNPACK #-} !Int
+  }
+  deriving (Show, Eq)
+
+
+defaultVariantLimits :: VariantLimits
+defaultVariantLimits = VariantLimits 500 1048576 1048576
+
+
+bad :: String -> Either String a
+bad = Left . ("Parquet.Variant: " ++)
+
+
+check :: Bool -> String -> Either String ()
+check condition message = unless condition (bad message)
+
+
+checkLimits :: VariantLimits -> Either String ()
+checkLimits limits =
+  check
+    (variantMaxDepth limits >= 0 && variantMaxValues limits > 0 && variantMaxDictionaryEntries limits >= 0)
+    "invalid resource limits"
+
+
+type Decoded# = (# String | (# Variant, Int#, Int# #) #)
+
+
+decodeVariant :: ByteString -> ByteString -> Either String Variant
+decodeVariant = decodeVariantWithLimits defaultVariantLimits
+
+
+decodeVariantWithLimits :: VariantLimits -> ByteString -> ByteString -> Either String Variant
+decodeVariantWithLimits limits metadata bytes = do
+  dictionary <- compileVariantMetadataWithLimits limits metadata
+  decodeVariantValueWithLimits limits dictionary bytes
+
+
+compileVariantMetadata :: ByteString -> Either String VariantMetadata
+compileVariantMetadata = compileVariantMetadataWithLimits defaultVariantLimits
+
+
+compileVariantMetadataWithLimits :: VariantLimits -> ByteString -> Either String VariantMetadata
+compileVariantMetadataWithLimits limits bytes = do
+  checkLimits limits
+  names <- decodeDictionary limits bytes
+  pure (VariantMetadata bytes names (M.fromList (V.toList (V.imap (\i name -> (name, i)) names))))
+
+
+{- | Construct one sorted, unique dictionary for a complete shredded value.
+The supplied names must include every object key, whether typed or binary.
+-}
+buildVariantMetadata :: Vector Text -> Either String VariantMetadata
+buildVariantMetadata = buildVariantMetadataWithLimits defaultVariantLimits
+
+
+buildVariantMetadataWithLimits :: VariantLimits -> Vector Text -> Either String VariantMetadata
+buildVariantMetadataWithLimits limits keys = do
+  checkLimits limits
+  let names = V.fromList (S.toAscList (V.foldl' (flip S.insert) S.empty keys))
+  check (V.length names <= variantMaxDictionaryEntries limits) "dictionary entry limit exceeded"
+  bytes <- encodeDictionary names
+  pure (VariantMetadata bytes names (M.fromDistinctAscList (zip (V.toList names) [0 ..])))
+
+
+decodeVariantValue :: VariantMetadata -> ByteString -> Either String Variant
+decodeVariantValue = decodeVariantValueWithLimits defaultVariantLimits
+
+
+decodeVariantValueWithLimits :: VariantLimits -> VariantMetadata -> ByteString -> Either String Variant
+decodeVariantValueWithLimits limits metadata bytes = case variantMaxValues limits of
+  I# remaining -> case decodeVariantFragment# limits metadata 0# remaining bytes of
+    (# message | #) -> Left message
+    (# | (# value, _ #) #) -> Right value
+
+
+-- | Dictionary membership without rebuilding a set for every typed object.
+metadataContains :: Text -> VariantMetadata -> Bool
+metadataContains name = M.member name . metadataIndices
+{-# INLINE metadataContains #-}
+
+
+{- | Decode one fallback fragment at its actual depth and with the remaining
+value budget of a complete shredded tree. Returns the unspent budget so
+sibling fragments cannot each reset the resource limits. The shared metadata
+is compiled once for the row. A fragment must consume its whole byte region.
+-}
+decodeVariantFragment# :: VariantLimits -> VariantMetadata -> Int# -> Int# -> ByteString -> (# String | (# Variant, Int# #) #)
+decodeVariantFragment# limits metadata depth remaining bytes
+  | variantMaxDepth limits < 0 || variantMaxValues limits <= 0 || variantMaxDictionaryEntries limits < 0 = (# "Parquet.Variant: invalid resource limits" | #)
+  | I# depth < 0 || I# remaining < 0 || I# remaining > variantMaxValues limits = (# "Parquet.Variant: invalid fragment budget" | #)
+  | V.length (metadataKeys metadata) > variantMaxDictionaryEntries limits = (# "Parquet.Variant: dictionary entry limit exceeded" | #)
+  | otherwise = case (variantMaxDepth limits, BS.length bytes) of
+      (I# maximumDepth, I# end) -> case decodeAt# maximumDepth (metadataKeys metadata) bytes depth remaining 0# end of
+        (# message | #) -> (# message | #)
+        (# | (# value, consumed, left #) #)
+          | isTrue# (consumed ==# end) -> (# | (# value, left #) #)
+          | otherwise -> (# "Parquet.Variant: trailing value bytes" | #)
+
+
+encodeVariantValue :: VariantMetadata -> Variant -> Either String ByteString
+encodeVariantValue = encodeVariantValueWithLimits defaultVariantLimits
+
+
+encodeVariantValueWithLimits :: VariantLimits -> VariantMetadata -> Variant -> Either String ByteString
+encodeVariantValueWithLimits limits metadata value = do
+  checkLimits limits
+  check (V.length (metadataKeys metadata) <= variantMaxDictionaryEntries limits) "dictionary entry limit exceeded"
+  _ <- validateTree limits 0 (variantMaxValues limits) value
+  encodeValue (metadataIndices metadata) value
+
+
+decodeDictionary :: VariantLimits -> ByteString -> Either String (Vector Text)
+decodeDictionary limits bs = do
+  check (not (BS.null bs)) "empty metadata"
+  let header = BS.head bs
+      width = fromIntegral (header `shiftR` 6) + 1
+  check (header .&. 15 == 1) "unsupported metadata version"
+  count <- readCount width bs 1 (BS.length bs)
+  check (count <= variantMaxDictionaryEntries limits) "dictionary entry limit exceeded"
+  let offsets = 1 + width
+      available = BS.length bs - offsets
+  check (count < available `quot` width) "truncated metadata offset table"
+  let start = offsets + (count + 1) * width
+      total = BS.length bs - start
+      offset :: Int -> Int
+      offset i = fromIntegral (readLE width bs (offsets + i * width))
+  check (offset 0 == 0 && offset count == total) "metadata first/last offsets do not cover the dictionary"
+  entries <- V.generateM count $ \i -> do
+    let lo = offset i
+        hi = offset (i + 1)
+    check (lo >= 0 && lo <= hi && hi <= total) "invalid metadata offsets"
+    utf8 (BS.take (hi - lo) (BS.drop (start + lo) bs))
+  when (header .&. 16 /= 0) $
+    check (V.and (V.zipWith (<) entries (V.drop 1 entries))) "sorted dictionary is not sorted and unique"
+  pure entries
+
+
+readLE :: Int -> ByteString -> Int -> Word64
+readLE width bs start = go 0 0
+  where
+    go !i !acc
+      | i == width = acc
+      | otherwise = go (i + 1) (acc .|. (fromIntegral (BS.index bs (start + i)) `shiftL` (i * 8)))
+{-# INLINE readLE #-}
+
+
+readCount :: Int -> ByteString -> Int -> Int -> Either String Int
+readCount width bs off end = do
+  check (off >= 0 && off <= end && width <= end - off) "truncated count"
+  let value = readLE width bs off
+  check (value <= fromIntegral (maxBound :: Int)) "count exceeds machine indexing range"
+  pure (fromIntegral value)
+
+
+utf8 :: ByteString -> Either String Text
+utf8 = either (const (bad "invalid UTF-8")) Right . TE.decodeUtf8'
+
+
+-- Only the requested Variant value is materialized. Cursor/budget/error
+-- control flow stays unboxed across recursive calls.
+good# :: Variant -> Int -> Int -> Decoded#
+good# !value (I# end) (I# remaining) = (# | (# value, end, remaining #) #)
+{-# INLINE good# #-}
+
+
+failure# :: String -> Decoded#
+failure# message = (# "Parquet.Variant: " ++ message | #)
+{-# INLINE failure# #-}
+
+
+readCount# :: Int -> ByteString -> Int -> Int -> (# String | Int# #)
+readCount# width bs off end
+  | off < 0 || off > end || width > end - off = (# "Parquet.Variant: truncated count" | #)
+  | otherwise =
+      let value = readLE width bs off
+      in if value > fromIntegral (maxBound :: Int)
+           then (# "Parquet.Variant: count exceeds machine indexing range" | #)
+           else case fromIntegral value of I# count -> (# | count #)
+{-# INLINE readCount# #-}
+
+
+decodeAt# :: Int# -> Vector Text -> ByteString -> Int# -> Int# -> Int# -> Int# -> Decoded#
+decodeAt# maximumDepth dictionary bs depth# remaining# off# end#
+  | depth > I# maximumDepth = failure# "nesting depth limit exceeded"
+  | remaining <= 0 = failure# "value count limit exceeded"
+  | off < 0 || off >= end || end > BS.length bs = failure# "missing value"
+  | otherwise =
+      let tag = fromIntegral (BS.index bs off) :: Int
+          header = tag `shiftR` 2
+          start = off + 1
+          result value consumed = good# value consumed (remaining - 1)
+          fixed width make
+            | width > end - start = failure# "truncated primitive"
+            | otherwise = result (make (readLE width bs start)) (start + width)
+          string size begin
+            | size > end - begin = failure# "truncated string"
+            | otherwise = case TE.decodeUtf8' (BS.take size (BS.drop begin bs)) of
+                Left _ -> failure# "invalid UTF-8"
+                Right text -> result (VString text) (begin + size)
+          blob make = case readCount# 4 bs start end of
+            (# message | #) -> (# message | #)
+            (# | size# #) ->
+              let size = I# size#
+                  begin = start + 4
+              in if size > end - begin
+                   then failure# "truncated binary/string"
+                   else result (make (BS.take size (BS.drop begin bs))) (begin + size)
+      in case tag .&. 3 of
+           1 -> string header start
+           2 -> decodeObject# maximumDepth dictionary bs (depth# +# 1#) (remaining# +# (-1#)) header start end
+           3 -> decodeArray# maximumDepth dictionary bs (depth# +# 1#) (remaining# +# (-1#)) header start end
+           _ -> case header of
+             0 -> result VNull start
+             1 -> result (VBool True) start
+             2 -> result (VBool False) start
+             3 -> fixed 1 (VInt8 . fromIntegral)
+             4 -> fixed 2 (VInt16 . fromIntegral)
+             5 -> fixed 4 (VInt32 . fromIntegral)
+             6 -> fixed 8 (VInt64 . fromIntegral)
+             7 -> fixed 8 (VDouble . castWord64ToDouble)
+             8
+               | end - start < 5 -> failure# "truncated decimal"
+               | otherwise ->
+                   let scale = BS.index bs start
+                       value = fromIntegral (readLE 4 bs (start + 1)) :: Int32
+                   in if scale > 38
+                        then failure# "decimal scale exceeds 38"
+                        else
+                          if value < (-999999999) || value > 999999999
+                            then failure# "decimal precision exceeds its physical width"
+                            else result (VDecimal4 scale value) (start + 5)
+             9
+               | end - start < 9 -> failure# "truncated decimal"
+               | otherwise ->
+                   let scale = BS.index bs start
+                       value = fromIntegral (readLE 8 bs (start + 1)) :: Int64
+                   in if scale > 38
+                        then failure# "decimal scale exceeds 38"
+                        else
+                          if value < (-999999999999999999) || value > 999999999999999999
+                            then failure# "decimal precision exceeds its physical width"
+                            else result (VDecimal8 scale value) (start + 9)
+             10
+               | end - start < 17 -> failure# "truncated decimal"
+               | otherwise ->
+                   let scale = BS.index bs start
+                       value = signedLE 16 bs (start + 1)
+                   in case checkDecimal 16 scale value of
+                        Left message -> (# message | #)
+                        Right () -> result (VDecimal16 scale value) (start + 17)
+             11 -> fixed 4 (VDate . fromIntegral)
+             12 -> fixed 8 (VTimestamp . fromIntegral)
+             13 -> fixed 8 (VTimestampNtz . fromIntegral)
+             14 -> fixed 4 (VFloat . castWord32ToFloat . fromIntegral)
+             15 -> blob VBinary
+             16 -> case readCount# 4 bs start end of
+               (# message | #) -> (# message | #)
+               (# | size# #) -> string (I# size#) (start + 4)
+             17
+               | end - start < 8 -> failure# "truncated primitive"
+               | otherwise ->
+                   let value = fromIntegral (readLE 8 bs start) :: Int64
+                   in if value < 0 || value >= 86400000000
+                        then failure# "time is outside a day"
+                        else result (VTime value) (start + 8)
+             18 -> fixed 8 (VTimestampNanos . fromIntegral)
+             19 -> fixed 8 (VTimestampNtzNanos . fromIntegral)
+             20
+               | end - start < 16 -> failure# "truncated primitive"
+               | otherwise -> result (VUuid (BS.take 16 (BS.drop start bs))) (start + 16)
+             _ -> failure# "unknown primitive type"
+  where
+    depth = I# depth#
+    remaining = I# remaining#
+    off = I# off#
+    end = I# end#
+
+
+signedLE :: Int -> ByteString -> Int -> Integer
+signedLE width bs off =
+  let raw = go 0 0
+  in if BS.index bs (off + width - 1) .&. 128 == 0 then raw else raw - (1 `shiftL` (8 * width))
+  where
+    go !i !acc
+      | i == width = acc
+      | otherwise = go (i + 1) (acc .|. (fromIntegral (BS.index bs (off + i)) `shiftL` (8 * i)))
+
+
+checkDecimal :: Int -> Word8 -> Integer -> Either String ()
+checkDecimal width scale value = do
+  check (scale <= 38) "decimal scale exceeds 38"
+  let precision :: Int
+      precision = case width of
+        4 -> 9
+        8 -> 18
+        _ -> 38
+  check (abs value < 10 ^ precision) "decimal precision exceeds its physical width"
+
+
+checkTime :: Int64 -> Either String ()
+checkTime micros = check (micros >= 0 && micros < 86400000000) "time is outside a day"
+
+
+-- Object offsets follow key order, not physical value order. The offset
+-- index is required only to establish a precise enclosing bound per child.
+-- It also catches duplicate/overlapping child offsets without quadratic scans.
+decodeObject# :: Int# -> Vector Text -> ByteString -> Int# -> Int# -> Int -> Int -> Int -> Decoded#
+decodeObject# maximumDepth dictionary bs depth# remaining# header off end =
+  case readCount# cw bs off end of
+    (# message | #) -> (# message | #)
+    (# | count# #) ->
+      let count = I# count#
+          idsStart = off + cw
+      in if count > I# remaining#
+           then failure# "value count limit exceeded"
+           else
+             if ow > end - idsStart || count > (end - idsStart - ow) `quot` (iw + ow)
+               then failure# "truncated object table"
+               else
+                 let offsetsStart = idsStart + count * iw
+                     start = offsetsStart + (count + 1) * ow
+                     offset i = fromIntegral (readLE ow bs (offsetsStart + i * ow)) :: Int
+                     total = offset count
+                     -- Validate names in key order, build the physical-order
+                     -- index in the same pass. No intermediate names vector.
+                     slotsLoop !i !previousId !slots
+                       | i == count = (# | slots #)
+                       | otherwise =
+                           let keyId = readLE iw bs (idsStart + i * iw)
+                               lo = offset i
+                           in if keyId >= fromIntegral (V.length dictionary)
+                                then (# "Parquet.Variant: object field ID outside dictionary" | #)
+                                else
+                                  if lo < 0 || lo >= total
+                                    then (# "Parquet.Variant: invalid object offsets" | #)
+                                    else
+                                      let name = V.unsafeIndex dictionary (fromIntegral keyId)
+                                      in if i > 0 && V.unsafeIndex dictionary previousId >= name
+                                           then (# "Parquet.Variant: object keys are not sorted and unique" | #)
+                                           else slotsLoop (i + 1) (fromIntegral keyId) (IM.insert lo name slots)
+                 in if total < 0 || total > end - start
+                      then failure# "object exceeds enclosing value"
+                      else case slotsLoop 0 0 IM.empty of
+                        (# message | #) -> (# message | #)
+                        (# | slots #)
+                          | IM.size slots /= count -> failure# "object values share an offset"
+                          | if count == 0 then total /= 0 else fst (IM.findMin slots) /= 0 -> failure# "object values do not start at zero"
+                          | otherwise -> objectLoop start total (IM.toAscList slots) M.empty remaining#
+  where
+    ow = (header .&. 3) + 1
+    iw = ((header `shiftR` 2) .&. 3) + 1
+    cw = if header .&. 16 == 0 then 1 else 4
+    objectLoop start total slots !values budget# = case slots of
+      [] -> case start + total of I# consumed -> (# | (# VObject values, consumed, budget# #) #)
+      (lo, name) : rest ->
+        let hi = case rest of [] -> total; (next, _) : _ -> next
+        in if lo >= hi || hi > total
+             then failure# "invalid object offsets"
+             else case (start + lo, start + hi) of
+               (I# begin, I# finish) -> case decodeAt# maximumDepth dictionary bs depth# budget# begin finish of
+                 (# message | #) -> (# message | #)
+                 (# | (# value, consumed, remaining #) #)
+                   | not (isTrue# (consumed ==# finish)) -> failure# "object child does not fill its byte range"
+                   | otherwise -> objectLoop start total rest (M.insert name value values) remaining
+
+
+decodeArray# :: Int# -> Vector Text -> ByteString -> Int# -> Int# -> Int -> Int -> Int -> Decoded#
+decodeArray# maximumDepth dictionary bs depth# remaining# header off end =
+  case readCount# cw bs off end of
+    (# message | #) -> (# message | #)
+    (# | count# #) ->
+      let count = I# count#
+          offsetsStart = off + cw
+      in if count > I# remaining#
+           then failure# "value count limit exceeded"
+           else
+             if count >= (end - offsetsStart) `quot` ow
+               then failure# "truncated array table"
+               else
+                 let start = offsetsStart + (count + 1) * ow
+                     offset i = fromIntegral (readLE ow bs (offsetsStart + i * ow)) :: Int
+                     total = offset count
+                 in if offset 0 /= 0 || total < 0 || total > end - start
+                      then failure# "invalid array first/last offsets"
+                      else runRW# $ \state -> case MV.unsafeNew count of
+                        ST allocate -> case allocate state of
+                          (# state1, output #) ->
+                            let loop i# budget# state2
+                                  | isTrue# (i# ==# count#) = case V.unsafeFreeze output of
+                                      ST freeze -> case freeze state2 of
+                                        (# _, values #) -> case start + total of
+                                          I# consumed -> (# | (# VArray values, consumed, budget# #) #)
+                                  | otherwise =
+                                      let lo = offset (I# i#)
+                                          hi = offset (I# (i# +# 1#))
+                                      in if lo < 0 || lo >= hi || hi > total
+                                           then failure# "invalid array offsets"
+                                           else case (start + lo, start + hi) of
+                                             (I# begin, I# finish) -> case decodeAt# maximumDepth dictionary bs depth# budget# begin finish of
+                                               (# message | #) -> (# message | #)
+                                               (# | (# value, consumed, remaining #) #)
+                                                 | not (isTrue# (consumed ==# finish)) -> failure# "array child does not fill its byte range"
+                                                 | otherwise -> case value of
+                                                     !strictValue -> case MV.unsafeWrite output (I# i#) strictValue of
+                                                       ST write -> case write state2 of
+                                                         (# state3, () #) -> loop (i# +# 1#) remaining state3
+                            in loop 0# remaining# state1
+  where
+    ow = (header .&. 3) + 1
+    cw = if header .&. 4 == 0 then 1 else 4
+
+
+encodeVariant :: Variant -> Either String EncodedVariant
+encodeVariant = encodeVariantWithLimits defaultVariantLimits
+
+
+encodeVariantWithLimits :: VariantLimits -> Variant -> Either String EncodedVariant
+encodeVariantWithLimits limits value =
+  withVariantMetadataFor limits value $ \metadata _ indices -> do
+    bytes <- encodeValue indices value
+    pure (EncodedVariant metadata bytes)
+
+
+-- | Collect all actual object names, including names selected for typed
+-- columns, after validating the complete tree's depth/value/type limits.
+buildVariantMetadataFor :: Variant -> Either String VariantMetadata
+buildVariantMetadataFor = buildVariantMetadataForWithLimits defaultVariantLimits
+
+
+buildVariantMetadataForWithLimits :: VariantLimits -> Variant -> Either String VariantMetadata
+buildVariantMetadataForWithLimits limits value =
+  withVariantMetadataFor limits value $ \bytes dictionary indices ->
+    pure (VariantMetadata bytes dictionary indices)
+{-# INLINE buildVariantMetadataForWithLimits #-}
+
+
+-- Keep the components separate until the caller chooses its output. This
+-- avoids constructing a temporary compiled-metadata record in the binary
+-- encoder, including with GHC 9.14's simplifier.
+withVariantMetadataFor :: VariantLimits -> Variant -> (ByteString -> Vector Text -> M.Map Text Int -> Either String a) -> Either String a
+withVariantMetadataFor limits value use = do
+  checkLimits limits
+  _ <- validateTree limits 0 (variantMaxValues limits) value
+  let dictionary = V.fromList (S.toAscList (collectNames value S.empty))
+  check (V.length dictionary <= variantMaxDictionaryEntries limits) "dictionary entry limit exceeded"
+  bytes <- encodeDictionary dictionary
+  use bytes dictionary (M.fromDistinctAscList (zip (V.toList dictionary) [0 ..]))
+{-# INLINE withVariantMetadataFor #-}
+
+
+-- | Validate a whole value against an original compiled dictionary without
+-- producing a second encoded copy. Every actual key must be present even
+-- when the value will be fully shredded into typed columns.
+validateVariantWithMetadata :: VariantMetadata -> Variant -> Either String ()
+validateVariantWithMetadata = validateVariantWithMetadataWithLimits defaultVariantLimits
+
+
+validateVariantWithMetadataWithLimits :: VariantLimits -> VariantMetadata -> Variant -> Either String ()
+validateVariantWithMetadataWithLimits limits metadata value = do
+  checkLimits limits
+  check (V.length (metadataKeys metadata) <= variantMaxDictionaryEntries limits) "dictionary entry limit exceeded"
+  _ <- validateTree limits 0 (variantMaxValues limits) value
+  check (namesPresent value) "object key absent from shared dictionary"
+  where
+    namesPresent current = case current of
+      VObject fields -> M.foldrWithKey (\name child rest -> metadataContains name metadata && namesPresent child && rest) True fields
+      VArray values -> V.all namesPresent values
+      _ -> True
+
+
+
+validateTree :: VariantLimits -> Int -> Int -> Variant -> Either String Int
+validateTree limits depth remaining value = do
+  check (depth <= variantMaxDepth limits) "nesting depth limit exceeded"
+  check (remaining > 0) "value count limit exceeded"
+  let left = remaining - 1
+      child = validateTree limits (depth + 1)
+  case value of
+    VArray xs -> V.foldM' child left xs
+    VObject fields -> M.foldl' (\acc v -> acc >>= \budget -> child budget v) (pure left) fields
+    VDecimal4 scale raw -> checkDecimal 4 scale (toInteger raw) >> pure left
+    VDecimal8 scale raw -> checkDecimal 8 scale (toInteger raw) >> pure left
+    VDecimal16 scale raw -> checkDecimal 16 scale raw >> pure left
+    VTime micros -> checkTime micros >> pure left
+    VUuid bytes -> check (BS.length bytes == 16) "UUID must contain exactly 16 bytes" >> pure left
+    _ -> pure left
+
+
+collectNames :: Variant -> S.Set Text -> S.Set Text
+collectNames value acc = case value of
+  VArray xs -> V.foldl' (flip collectNames) acc xs
+  VObject fields -> M.foldlWithKey' (\names name v -> collectNames v (S.insert name names)) acc fields
+  _ -> acc
+
+
+encodeDictionary :: Vector Text -> Either String ByteString
+encodeDictionary dictionary = do
+  let strings = V.map TE.encodeUtf8 dictionary
+      offsets = V.scanl' (\n s -> n + toInteger (BS.length s)) 0 strings
+      total = V.last offsets
+      count = V.length strings
+  bound32 (max total (toInteger count))
+  let width = pickWidth (fromInteger (max total (toInteger count)))
+  pure (build (B.word8 (17 .|. fromIntegral ((width - 1) `shiftL` 6)) <> unsigned width count <> foldMap (unsigned width . fromInteger) offsets <> foldMap B.byteString strings))
+
+
+encodeValue :: Map Text Int -> Variant -> Either String ByteString
+encodeValue dictionary = fmap build . go
+  where
+    prim tag bytes = pure (B.word8 (tag `shiftL` 2) <> bytes)
+    go = \case
+      VNull -> prim 0 mempty
+      VBool True -> prim 1 mempty
+      VBool False -> prim 2 mempty
+      VInt8 n -> prim 3 (B.int8 n)
+      VInt16 n -> prim 4 (B.int16LE n)
+      VInt32 n -> prim 5 (B.int32LE n)
+      VInt64 n -> prim 6 (B.int64LE n)
+      VDouble n -> prim 7 (B.word64LE (castDoubleToWord64 n))
+      VDecimal4 scale n -> prim 8 (B.word8 scale <> B.int32LE n)
+      VDecimal8 scale n -> prim 9 (B.word8 scale <> B.int64LE n)
+      VDecimal16 scale n -> prim 10 (B.word8 scale <> int128 n)
+      VDate n -> prim 11 (B.int32LE n)
+      VTimestamp n -> prim 12 (B.int64LE n)
+      VTimestampNtz n -> prim 13 (B.int64LE n)
+      VFloat n -> prim 14 (B.word32LE (castFloatToWord32 n))
+      VBinary bytes -> long 15 bytes
+      VString text ->
+        let bytes = TE.encodeUtf8 text
+            size = BS.length bytes
+        in if size < 64 then pure (B.word8 (fromIntegral (size `shiftL` 2) .|. 1) <> B.byteString bytes) else long 16 bytes
+      VTime n -> prim 17 (B.int64LE n)
+      VTimestampNanos n -> prim 18 (B.int64LE n)
+      VTimestampNtzNanos n -> prim 19 (B.int64LE n)
+      VUuid bytes -> prim 20 (B.byteString bytes)
+      VArray xs -> do
+        children <- V.mapM (encodeValue dictionary) xs
+        compound 3 V.empty children
+      VObject fields -> do
+        let names = V.fromList (M.keys fields)
+        ids <- V.mapM (\name -> maybe (bad "object key absent from shared dictionary") pure (M.lookup name dictionary)) names
+        children <- V.mapM (encodeValue dictionary) (V.fromList (M.elems fields))
+        compound 2 ids children
+    long tag bytes = do
+      bound32 (toInteger (BS.length bytes))
+      prim tag (B.word32LE (fromIntegral (BS.length bytes)) <> B.byteString bytes)
+    compound basic ids children = do
+      let count = V.length children
+          offsets = V.scanl' (\n b -> n + toInteger (BS.length b)) 0 children
+          total = V.last offsets
+          maxId = V.foldl' max 0 ids
+      bound32 (max (toInteger count) total)
+      let ow = pickWidth (fromInteger total)
+          iw = pickWidth maxId
+          large = count > 255
+          header = if basic == 2 then (if large then 16 else 0) .|. ((iw - 1) `shiftL` 2) .|. (ow - 1) else (if large then 4 else 0) .|. (ow - 1)
+      pure (B.word8 (fromIntegral ((header `shiftL` 2) .|. basic)) <> unsigned (if large then 4 else 1) count <> foldMap (unsigned iw) ids <> foldMap (unsigned ow . fromInteger) offsets <> foldMap B.byteString children)
+
+
+bound32 :: Integer -> Either String ()
+bound32 n = check (n <= toInteger (maxBound :: Word32)) "encoded count/offset exceeds unsigned 32-bit width"
+
+
+pickWidth :: Int -> Int
+pickWidth n
+  | n < 256 = 1
+  | n < 65536 = 2
+  | n < 16777216 = 3
+  | otherwise = 4
+
+
+unsigned :: Int -> Int -> B.Builder
+unsigned width value = go 0
+  where
+    go !i
+      | i == width = mempty
+      | otherwise = B.word8 (fromIntegral (value `shiftR` (i * 8))) <> go (i + 1)
+
+
+int128 :: Integer -> B.Builder
+int128 value = go 0
+  where
+    go !i
+      | i == 16 = mempty
+      | otherwise = B.word8 (fromIntegral (value `shiftR` (i * 8))) <> go (i + 1)
+
+
+build :: B.Builder -> ByteString
+build = BL.toStrict . B.toLazyByteString
diff --git a/src/Parquet/Variant/Array.hs b/src/Parquet/Variant/Array.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Variant/Array.hs
@@ -0,0 +1,152 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+-- | Internal shared binary accessors for Variant reading and writing.
+module Parquet.Variant.Array (BytesReader (..), compileBytes, alignVariantColumns) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Data.ByteString (ByteString)
+import Data.Map.Strict qualified as M
+import Data.Vector qualified as V
+import Data.Vector.Storable qualified as S
+import Foreign.Storable (Storable)
+import GHC.Exts (Int (I#), Int#)
+import Parquet.Variant.Schema qualified as Schema
+
+
+newtype BytesReader = BytesReader {bytesAt# :: Int# -> (# ByteString | () #)}
+
+
+newtype IndexReader = IndexReader {indexAt# :: Int# -> (# Int# | () #)}
+
+
+-- Only metadata may be dictionary or run-end encoded. Resolve one logical
+-- index at a time; no expanded metadata column is allocated.
+compileBytes :: C.ColumnArray -> Either String BytesReader
+compileBytes column = case column of
+  C.ColDictionary _ keys values -> do
+    entries <- compileBytes values
+    indices <- compileIndices keys
+    pure $ BytesReader $ \index -> case indexAt# indices index of
+      (# | () #) -> (# | () #)
+      (# key | #) -> bytesAt# entries key
+  C.ColRunEndEncoded offset _ ends values -> do
+    entries <- compileBytes values
+    case ends of
+      C.ColInt16 _ xs -> pure (runs entries offset xs)
+      C.ColInt32 _ xs -> pure (runs entries offset xs)
+      C.ColInt64 _ xs -> pure (runs entries offset xs)
+      _ -> Left "Parquet.Variant.Arrow: invalid metadata run ends"
+  C.ColBinary validity offsets bytes -> pure (variableBytes validity offsets bytes)
+  C.ColLargeBinary validity offsets bytes -> pure (variableBytes validity offsets bytes)
+  C.ColBinaryView {} -> pure $ BytesReader $ \index -> case C.anyBytesAt column (I# index) of
+    Nothing -> (# | () #)
+    Just bytes -> (# bytes | #)
+  _ -> Left "Parquet.Variant.Arrow: expected binary storage"
+  where
+    runs :: (Storable a, Integral a) => BytesReader -> Int -> S.Vector a -> BytesReader
+    runs entries offset ends = BytesReader $ \index ->
+      let position = offset + I# index
+          search !low !high
+            | low == high = low
+            | fromIntegral (S.unsafeIndex ends middle) <= position = search (middle + 1) high
+            | otherwise = search low middle
+            where
+              middle = low + (high - low) `quot` 2
+      in case search 0 (S.length ends) of I# run -> bytesAt# entries run
+
+
+-- The public dictionary accessor returns a boxed index and must dispatch
+-- on its integer type for each row. Bind the concrete key vector once.
+compileIndices :: C.ColumnArray -> Either String IndexReader
+compileIndices column = case column of
+  C.ColInt8 v xs -> pure (indexKeys v xs)
+  C.ColInt16 v xs -> pure (indexKeys v xs)
+  C.ColInt32 v xs -> pure (indexKeys v xs)
+  C.ColInt64 v xs -> pure (indexKeys v xs)
+  C.ColUInt8 v xs -> pure (indexKeys v xs)
+  C.ColUInt16 v xs -> pure (indexKeys v xs)
+  C.ColUInt32 v xs -> pure (indexKeys v xs)
+  C.ColUInt64 v xs -> pure (indexKeys v xs)
+  _ -> Left "Parquet.Variant.Arrow: dictionary keys must be integers"
+
+
+indexKeys :: (Storable a, Integral a) => Maybe C.Validity -> S.Vector a -> IndexReader
+indexKeys validity values = IndexReader $ \index ->
+  if C.isValidAt validity (I# index)
+    then case fromIntegral (S.unsafeIndex values (I# index)) of I# key -> (# key | #)
+    else (# | () #)
+{-# INLINE indexKeys #-}
+
+
+variableBytes :: (Storable a, Integral a) => Maybe C.Validity -> S.Vector a -> ByteString -> BytesReader
+variableBytes validity offsets bytes =
+  let array = C.BytesArray validity offsets bytes
+  in BytesReader $ \index -> case C.unsafeBytesAt array (I# index) of
+       Nothing -> (# | () #)
+       Just value -> (# value | #)
+{-# INLINE variableBytes #-}
+
+
+-- Names carry Variant semantics even when the in-memory column order differs
+-- from its field. Bind once before structural validation or positional row
+-- lowering. Normal IPC columns take the linear already-ordered fast path;
+-- a permuted wide object builds one name map. No value buffer is copied.
+alignVariantColumns :: A.Field -> C.ColumnArray -> Either String C.ColumnArray
+alignVariantColumns = go False
+  where
+    -- The common ordered case aliases the complete original column and
+    -- never revalidates offsets or creates replacement container vectors.
+    needed parent field column =
+      let active = parent || Schema.isVariantField field
+          fields = A.fieldChildren field
+          one value = case V.toList fields of [item] -> needed active item value; _ -> False
+      in case column of
+           C.ColStruct _ _ columns
+             | V.length columns == V.length fields ->
+                 (active && V.or (V.zipWith (\item (name, _) -> A.fieldName item /= name) fields columns))
+                   || V.or (V.zipWith (\item (_, value) -> needed active item value) fields columns)
+           C.ColList _ _ values -> one values
+           C.ColLargeList _ _ values -> one values
+           C.ColListView _ _ _ values -> one values
+           C.ColMap _ _ keys values -> case V.toList fields of
+             [entries] -> case V.toList (A.fieldChildren entries) of
+               [key, value] -> needed active key keys || needed active value values
+               _ -> False
+             _ -> False
+           _ -> False
+    go parent field column | not (needed parent field column) = Right column
+    go parent field column =
+      let active = parent || Schema.isVariantField field
+          fields = A.fieldChildren field
+          child value = case V.toList fields of
+            [item] -> go active item value
+            _ -> Left "Parquet.Variant: list storage requires one child field"
+      in case column of
+           C.ColStruct count validity columns -> do
+             if V.length columns /= V.length fields then Left "Parquet.Variant: struct child count mismatch" else Right ()
+             ordered <-
+               if not active || V.and (V.zipWith (\item (name, _) -> A.fieldName item == name) fields columns)
+                 then Right columns
+                 else do
+                   let named = M.fromList (V.toList columns)
+                   if M.size named /= V.length columns then Left "Parquet.Variant: duplicate named storage child" else Right ()
+                   V.mapM (\item -> maybe (Left "Parquet.Variant: missing named storage child") (\value -> Right (A.fieldName item, value)) (M.lookup (A.fieldName item) named)) fields
+             aligned <- V.zipWithM (\item (name, value) -> (,) name <$> go active item value) fields ordered
+             C.mkStruct count validity aligned
+           C.ColList validity offsets values -> child values >>= C.mkList validity offsets
+           C.ColLargeList validity offsets values -> child values >>= C.mkLargeList validity offsets
+           C.ColListView validity offsets sizes values -> child values >>= C.mkListView validity offsets sizes
+           C.ColMap validity offsets keys values -> case V.toList fields of
+             [entries] -> case V.toList (A.fieldChildren entries) of
+               [key, value] -> do
+                 alignedKeys <- go active key keys
+                 alignedValues <- go active value values
+                 C.mkMap validity offsets alignedKeys alignedValues
+               _ -> Left "Parquet.Variant: map entries require key and value fields"
+             _ -> Left "Parquet.Variant: map storage requires entries"
+           _ -> Right column
diff --git a/src/Parquet/Variant/Arrow.hs b/src/Parquet/Variant/Arrow.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Variant/Arrow.hs
@@ -0,0 +1,363 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Semantic reconstruction of canonical @arrow.parquet.variant@ arrays.
+
+Compile field names, storage profiles and primitive conversions once. Each
+present row uses one original metadata dictionary and one depth/value budget
+across its typed nodes and binary fallback fragments. Null storage slots,
+present Variant nulls and missing object fields remain distinct.
+
+See https://arrow.apache.org/docs/format/CanonicalExtensions.html#parquet-variant
+and https://parquet.apache.org/docs/file-format/types/variantshredding/.
+-}
+module Parquet.Variant.Arrow (
+  VariantArrowReader,
+  compileVariantArrowReader,
+  compileVariantArrowReaderWithLimits,
+  variantArrowLength,
+  variantArrowAt,
+  variantArrowAt#,
+) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Arrow.Write.Columns (validateColumns)
+import Control.Monad (unless)
+import Data.Int (Int32, Int64)
+import Data.Map.Strict qualified as M
+import Data.Text (Text)
+import Data.Vector qualified as V
+import Data.Vector.Mutable qualified as MV
+import Data.Vector.Storable qualified as S
+import Foreign.Storable (Storable)
+import GHC.Exts (Int (I#), Int#, isTrue#, runRW#, (+#), (==#))
+import GHC.ST (ST (..))
+import Parquet.Variant qualified as B
+import Parquet.Variant.Array (BytesReader (..), alignVariantColumns, compileBytes)
+import Parquet.Variant.Schema qualified as Schema
+
+
+data VariantArrowReader = VariantArrowReader
+  { variantArrowLength :: {-# UNPACK #-} !Int
+  , readerValidity :: !(Maybe C.Validity)
+  , readerMetadata :: !BytesReader
+  , readerNode :: !NodePlan
+  , readerLimits :: !B.VariantLimits
+  }
+
+
+newtype PrimitiveReader = PrimitiveReader {primitiveAt# :: Int# -> (# String | B.Variant #)}
+
+
+newtype RangeReader = RangeReader {rangeAt# :: Int# -> (# Int#, Int# #)}
+
+
+data NodePlan = NodePlan !(Maybe C.Validity) !BytesReader !(Maybe TypedPlan)
+
+
+data TypedPlan
+  = PrimitivePlan !(Maybe C.Validity) !PrimitiveReader
+  | ObjectPlan !(Maybe C.Validity) !(V.Vector ObjectField)
+  | ArrayPlan !(Maybe C.Validity) !RangeReader !NodePlan
+
+
+data ObjectField = ObjectField
+  { objectName :: !Text
+  , objectPlan :: !NodePlan
+  }
+
+
+type NodeResult# = (# String | (# B.Variant, Int# #) | Int# #)
+
+
+type PresentResult# = (# String | (# B.Variant, Int# #) #)
+
+
+compileVariantArrowReader :: A.Field -> C.ColumnArray -> Either String VariantArrowReader
+compileVariantArrowReader = compileVariantArrowReaderWithLimits B.defaultVariantLimits Schema.defaultVariantSchemaLimits
+
+
+{- | Independent limits bound schema compilation and each reconstructed tree.
+Arrow buffer shapes are checked once. Required-child validity is checked only
+where its containing Variant/object/array is present; null ancestors mask
+arbitrary children, including malformed Variant payload bytes.
+-}
+compileVariantArrowReaderWithLimits :: B.VariantLimits -> Schema.VariantSchemaLimits -> A.Field -> C.ColumnArray -> Either String VariantArrowReader
+compileVariantArrowReaderWithLimits limits schemaLimits field input = do
+  unless (B.variantMaxDepth limits >= 0 && B.variantMaxValues limits > 0 && B.variantMaxDictionaryEntries limits >= 0) (Left "Parquet.Variant.Arrow: invalid resource limits")
+  Schema.validateVariantFieldWithLimits schemaLimits field
+  column <- alignVariantColumns field input
+  validateColumns (V.singleton field {A.fieldChildren = V.map relax (A.fieldChildren field)}) (V.singleton column)
+  metadata <- namedColumn "metadata" column >>= compileBytes
+  plan <- compileNode field column
+  pure (VariantArrowReader (C.columnLength column) (C.validity column) metadata plan limits)
+  where
+    relax current = current {A.fieldNullable = True, A.fieldChildren = V.map relax (A.fieldChildren current)}
+
+
+namedColumn :: Text -> C.ColumnArray -> Either String C.ColumnArray
+namedColumn name (C.ColStruct _ _ children) = maybe (Left "Parquet.Variant.Arrow: missing named child") (Right . snd) (V.find ((== name) . fst) children)
+namedColumn _ _ = Left "Parquet.Variant.Arrow: expected struct storage"
+
+
+compileNode :: A.Field -> C.ColumnArray -> Either String NodePlan
+compileNode field column = do
+  let children = A.fieldChildren field
+  fallback <- case V.find ((== "value") . A.fieldName) children of
+    Nothing -> pure (BytesReader (\_ -> (# | () #)))
+    Just _ -> namedColumn "value" column >>= compileBytes
+  typed <- case V.find ((== "typed_value") . A.fieldName) children of
+    Nothing -> pure Nothing
+    Just child -> Just <$> (namedColumn "typed_value" column >>= compileTyped child)
+  -- Preserve required-child checks at visible rows without scanning payloads
+  -- beneath null parents. Usually no required child has a validity bitmap;
+  -- only the exceptional case needs one combined mask at compile time.
+  required <-
+    V.mapM
+      ( \child ->
+          if not (A.fieldNullable child) && A.fieldName child /= "metadata"
+            then C.validity <$> namedColumn (A.fieldName child) column
+            else pure Nothing
+      )
+      children
+  let requiredMasks = V.mapMaybe id required
+      visible =
+        if V.null requiredMasks
+          then C.validity column
+          else
+            C.validityGenerate
+              (C.columnLength column)
+              ( \index ->
+                  C.isValidAt (C.validity column) index && V.all (\mask -> C.bitAt (C.validityBits mask) index) requiredMasks
+              )
+  pure (NodePlan visible fallback typed)
+
+
+compileTyped :: A.Field -> C.ColumnArray -> Either String TypedPlan
+compileTyped field column = case (A.fieldType field, column) of
+  (A.AStruct, C.ColStruct _ validity columns) -> do
+    -- Name alignment has already bound every object once, before shape
+    -- validation. Positional compilation now needs no second name map.
+    children <- V.zipWithM (\child (_, value) -> ObjectField (A.fieldName child) <$> compileNode child value) (A.fieldChildren field) columns
+    pure (ObjectPlan validity children)
+  (_, C.ColList validity offsets child) -> list validity (offsetsRange offsets) child
+  (_, C.ColLargeList validity offsets child) -> list validity (offsetsRange offsets) child
+  (_, C.ColListView validity offsets sizes child) -> list validity (viewRange offsets sizes) child
+  _ -> PrimitivePlan (C.validity column) <$> compilePrimitive field column
+  where
+    list validity ranges child = do
+      plan <- compileNode (V.head (A.fieldChildren field)) child
+      pure (ArrayPlan validity ranges plan)
+
+
+offsetsRange :: (Storable a, Integral a) => S.Vector a -> RangeReader
+offsetsRange offsets = RangeReader $ \index ->
+  case fromIntegral (S.unsafeIndex offsets (I# index)) of
+    I# start -> case fromIntegral (S.unsafeIndex offsets (I# (index +# 1#))) - I# start of
+      I# count -> (# start, count #)
+{-# INLINE offsetsRange #-}
+
+
+viewRange :: (Storable a, Integral a) => S.Vector a -> S.Vector a -> RangeReader
+viewRange offsets sizes = RangeReader $ \index ->
+  case fromIntegral (S.unsafeIndex offsets (I# index)) of
+    I# start -> case fromIntegral (S.unsafeIndex sizes (I# index)) of
+      I# count -> (# start, count #)
+{-# INLINE viewRange #-}
+
+
+compilePrimitive :: A.Field -> C.ColumnArray -> Either String PrimitiveReader
+compilePrimitive field column = case column of
+  C.ColInt8 _ xs -> pure (primitive B.VInt8 xs)
+  C.ColInt16 _ xs -> pure (primitive B.VInt16 xs)
+  C.ColInt32 _ xs -> pure (primitive B.VInt32 xs)
+  C.ColInt64 _ xs -> pure (primitive B.VInt64 xs)
+  C.ColFloat _ xs -> pure (primitive B.VFloat xs)
+  C.ColDouble _ xs -> pure (primitive B.VDouble xs)
+  C.ColDate32 _ xs -> pure (primitive B.VDate xs)
+  C.ColTime64 _ xs -> pure $ PrimitiveReader $ \index ->
+    let value = S.unsafeIndex xs (I# index)
+    in if value >= 0 && value < 86400000000 then (# | B.VTime value #) else (# "Parquet.Variant.Arrow: time outside one day" | #)
+  C.ColTimestamp _ xs -> pure (primitive timestamp xs)
+  C.ColDecimal32 precision scale _ xs ->
+    let !bound = fromInteger (10 ^ precision) :: Int32
+    in pure $ PrimitiveReader $ \index ->
+         let !value = S.unsafeIndex xs (I# index)
+         in if value > negate bound && value < bound then (# | B.VDecimal4 (fromIntegral scale) value #) else badDecimal#
+  C.ColDecimal64 precision scale _ xs ->
+    let !bound = fromInteger (10 ^ precision) :: Int64
+    in pure $ PrimitiveReader $ \index ->
+         let !value = S.unsafeIndex xs (I# index)
+         in if value > negate bound && value < bound then (# | B.VDecimal8 (fromIntegral scale) value #) else badDecimal#
+  C.ColDecimal128 precision scale _ xs ->
+    let !bound = 10 ^ precision
+    in pure $ PrimitiveReader $ \index ->
+         let !value = C.decimal128ToInteger (S.unsafeIndex xs (I# index))
+         in if value > negate bound && value < bound then (# | B.VDecimal16 (fromIntegral scale) value #) else badDecimal#
+  _
+    | A.fieldType field == A.ABool
+    , Just values <- C.asBool column ->
+        pure $ PrimitiveReader $ \index -> case C.boolArrayAt values (I# index) of
+          Just value -> (# | B.VBool value #)
+          Nothing -> missingPrimitive#
+    | A.fieldType field `elem` [A.AUtf8, A.ALargeUtf8, A.AUtf8View] ->
+        pure $ PrimitiveReader $ \index -> case C.anyTextAt column (I# index) of
+          Just value -> (# | B.VString value #)
+          Nothing -> missingPrimitive#
+    | otherwise ->
+        pure $ PrimitiveReader $ \index -> case C.anyBytesAt column (I# index) of
+          Just value -> (# | if A.fieldType field == A.AFixedSizeBinary 16 then B.VUuid value else B.VBinary value #)
+          Nothing -> missingPrimitive#
+  where
+    timestamp = case A.fieldType field of
+      A.ATimestamp A.Microsecond (Just "UTC") -> B.VTimestamp
+      A.ATimestamp A.Nanosecond (Just "UTC") -> B.VTimestampNanos
+      A.ATimestamp A.Microsecond Nothing -> B.VTimestampNtz
+      _ -> B.VTimestampNtzNanos
+    primitive :: Storable a => (a -> B.Variant) -> S.Vector a -> PrimitiveReader
+    primitive make values = PrimitiveReader $ \index -> let !value = make (S.unsafeIndex values (I# index)) in (# | value #)
+    {-# INLINE primitive #-}
+    badDecimal# :: (# String | B.Variant #)
+    badDecimal# = (# "Parquet.Variant.Arrow: decimal exceeds declared precision" | #)
+    missingPrimitive# :: (# String | B.Variant #)
+    missingPrimitive# = (# "Parquet.Variant.Arrow: missing typed primitive" | #)
+
+
+variantArrowAt :: VariantArrowReader -> Int -> Either String (Maybe B.Variant)
+variantArrowAt reader (I# index) = case variantArrowAt# reader index of
+  (# message | | #) -> Left message
+  (# | value | #) -> Right (Just value)
+  (# | | () #) -> Right Nothing
+
+
+variantArrowAt# :: VariantArrowReader -> Int# -> (# String | B.Variant | () #)
+variantArrowAt# reader index
+  | I# index < 0 || I# index >= variantArrowLength reader = (# "Parquet.Variant.Arrow: row index out of range" | | #)
+  | not (C.isValidAt (readerValidity reader) (I# index)) = (# | | () #)
+  | otherwise = case bytesAt# (readerMetadata reader) index of
+      (# | () #) -> (# "Parquet.Variant.Arrow: present root has null metadata" | | #)
+      (# bytes | #) -> case B.compileVariantMetadataWithLimits (readerLimits reader) bytes of
+        Left message -> (# message | | #)
+        Right dictionary -> case B.variantMaxValues (readerLimits reader) of
+          I# budget -> case required# (readerLimits reader) dictionary (readerNode reader) 0# budget index of
+            (# message | #) -> (# message | | #)
+            (# | (# value, _ #) #) -> (# | value | #)
+{-# INLINE variantArrowAt# #-}
+
+
+charge# :: B.VariantLimits -> Int# -> Int# -> (# String | Int# #)
+charge# limits depth budget
+  | I# depth > B.variantMaxDepth limits = (# "Parquet.Variant.Arrow: nesting depth limit exceeded" | #)
+  | I# budget <= 0 = (# "Parquet.Variant.Arrow: value count limit exceeded" | #)
+  | otherwise = (# | budget +# (-1#) #)
+{-# INLINE charge# #-}
+
+
+required# :: B.VariantLimits -> B.VariantMetadata -> NodePlan -> Int# -> Int# -> Int# -> PresentResult#
+required# limits dictionary plan depth budget index = case readNode# limits dictionary plan depth budget index of
+  (# message | | #) -> (# message | #)
+  (# | (# value, left #) | #) -> (# | (# value, left #) #)
+  (# | | left #) -> case charge# limits depth left of
+    (# message | #) -> (# message | #)
+    (# | remaining #) -> (# | (# B.VNull, remaining #) #)
+{-# INLINE required# #-}
+
+
+readNode# :: B.VariantLimits -> B.VariantMetadata -> NodePlan -> Int# -> Int# -> Int# -> NodeResult#
+readNode# limits dictionary (NodePlan validity fallback typed) depth budget index
+  | not (C.isValidAt validity (I# index)) = (# "Parquet.Variant.Arrow: null shredded wrapper or required child" | | #)
+  | otherwise = case typed of
+      Just plan | typedPresent plan -> case plan of
+        PrimitivePlan _ primitive -> case bytesAt# fallback index of
+          (# _ | #) -> conflict#
+          (# | () #) -> case charge# limits depth budget of
+            (# message | #) -> (# message | | #)
+            (# | left #) -> case primitiveAt# primitive index of
+              (# message | #) -> (# message | | #)
+              (# | !value #) -> (# | (# value, left #) | #)
+        ArrayPlan _ ranges child -> case bytesAt# fallback index of
+          (# _ | #) -> conflict#
+          (# | () #) -> case charge# limits depth budget of
+            (# message | #) -> (# message | | #)
+            (# | left #) -> case rangeAt# ranges index of
+              (# start, count #) -> case readArray# limits dictionary child (depth +# 1#) left start count of
+                (# message | #) -> (# message | | #)
+                (# | (# value, remaining #) #) -> (# | (# value, remaining #) | #)
+        ObjectPlan _ fields -> case bytesAt# fallback index of
+          (# | () #) -> case charge# limits depth budget of
+            (# message | #) -> (# message | | #)
+            (# | left #) -> object fields M.empty left
+          (# bytes | #) -> case B.decodeVariantFragment# limits dictionary depth budget bytes of
+            (# message | #) -> (# message | | #)
+            (# | (# B.VObject rest, left #) #)
+              | V.any (\field -> M.member (objectName field) rest) fields -> (# "Parquet.Variant.Arrow: object field appears in typed and fallback storage" | | #)
+              | otherwise -> object fields rest left
+            _ -> (# "Parquet.Variant.Arrow: partial fallback must be an object" | | #)
+      _ -> case bytesAt# fallback index of
+        (# | () #) -> (# | | budget #)
+        (# bytes | #) -> case B.decodeVariantFragment# limits dictionary depth budget bytes of
+          (# message | #) -> (# message | | #)
+          (# | (# value, left #) #) -> case (typed, value) of
+            (Just ObjectPlan {}, B.VObject {}) -> (# "Parquet.Variant.Arrow: object is missing its typed storage" | | #)
+            (Just ArrayPlan {}, B.VArray {}) -> (# "Parquet.Variant.Arrow: array is missing its typed storage" | | #)
+            _ -> (# | (# value, left #) | #)
+  where
+    typedPresent plan = C.isValidAt (case plan of PrimitivePlan v _ -> v; ObjectPlan v _ -> v; ArrayPlan v _ _ -> v) (I# index)
+    object :: V.Vector ObjectField -> M.Map Text B.Variant -> Int# -> NodeResult#
+    object fields rest left = case readObject# limits dictionary fields (depth +# 1#) left index 0# rest of
+      (# message | #) -> (# message | | #)
+      (# | (# value, remaining #) #) -> (# | (# value, remaining #) | #)
+    conflict# :: NodeResult#
+    conflict# = (# "Parquet.Variant.Arrow: value and typed_value conflict" | | #)
+
+
+-- A dictionary omission can be detected from storage presence alone. Do
+-- not construct a large typed subtree only to reject its field name later.
+nodePresent# :: NodePlan -> Int# -> (# String | Bool #)
+nodePresent# (NodePlan validity fallback typed) index
+  | not (C.isValidAt validity (I# index)) = (# "Parquet.Variant.Arrow: null shredded wrapper or required child" | #)
+  | otherwise = case typed of
+      Just plan | C.isValidAt (case plan of PrimitivePlan v _ -> v; ObjectPlan v _ -> v; ArrayPlan v _ _ -> v) (I# index) -> (# | True #)
+      _ -> case bytesAt# fallback index of
+        (# _ | #) -> (# | True #)
+        (# | () #) -> (# | False #)
+{-# INLINE nodePresent# #-}
+
+
+readObject# :: B.VariantLimits -> B.VariantMetadata -> V.Vector ObjectField -> Int# -> Int# -> Int# -> Int# -> M.Map Text B.Variant -> PresentResult#
+readObject# limits dictionary fields depth budget index fieldIndex values
+  | isTrue# (fieldIndex ==# count) = (# | (# B.VObject values, budget #) #)
+  | otherwise = case V.unsafeIndex fields (I# fieldIndex) of
+      field
+        | not (B.metadataContains (objectName field) dictionary) -> case nodePresent# (objectPlan field) index of
+            (# message | #) -> (# message | #)
+            (# | True #) -> (# "Parquet.Variant.Arrow: typed object field missing from shared dictionary" | #)
+            (# | False #) -> readObject# limits dictionary fields depth budget index (fieldIndex +# 1#) values
+        | otherwise -> case readNode# limits dictionary (objectPlan field) depth budget index of
+            (# message | | #) -> (# message | #)
+            (# | | left #) -> readObject# limits dictionary fields depth left index (fieldIndex +# 1#) values
+            (# | (# value, left #) | #) -> readObject# limits dictionary fields depth left index (fieldIndex +# 1#) (M.insert (objectName field) value values)
+  where
+    !(I# count) = V.length fields
+
+
+readArray# :: B.VariantLimits -> B.VariantMetadata -> NodePlan -> Int# -> Int# -> Int# -> Int# -> PresentResult#
+readArray# limits dictionary plan depth budget start count
+  | I# count > I# budget = (# "Parquet.Variant.Arrow: value count limit exceeded" | #)
+  | I# count > 0 && I# depth > B.variantMaxDepth limits = (# "Parquet.Variant.Arrow: nesting depth limit exceeded" | #)
+  | otherwise = runRW# $ \state -> case MV.unsafeNew (I# count) of
+      ST allocate -> case allocate state of
+        (# state1, output #) ->
+          let loop offset left state2
+                | isTrue# (offset ==# count) = case V.unsafeFreeze output of
+                    ST freeze -> case freeze state2 of (# _, array #) -> (# | (# B.VArray array, left #) #)
+                | otherwise = case required# limits dictionary plan depth left (start +# offset) of
+                    (# message | #) -> (# message | #)
+                    (# | (# !value, remaining #) #) -> case MV.unsafeWrite output (I# offset) value of
+                      ST write -> case write state2 of (# state3, () #) -> loop (offset +# 1#) remaining state3
+          in loop 0# budget state1
diff --git a/src/Parquet/Variant/Nested.hs b/src/Parquet/Variant/Nested.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Variant/Nested.hs
@@ -0,0 +1,204 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Internal semantic validation after every native leaf's structural and
+byte-count preflight. Typed primitives were already range-checked there;
+this pass checks shared dictionaries, conflicts and one global tree budget.
+-}
+module Parquet.Variant.Nested (normalizeStorageRow, validateStorageRow) where
+
+import Data.ByteString qualified as BS
+import Data.Map.Strict qualified as M
+import Data.Set qualified as Set
+import Data.Vector qualified as V
+import GHC.Exts (Int (I#), Int#, isTrue#, (+#), (==#))
+import Parquet.Nested.Types
+import Parquet.Variant qualified as B
+
+
+-- Native array elements must actually contain a Variant value. The Arrow
+-- convention permits both slots to be missing and reads that as Variant null;
+-- supply binary 00 in the native fallback without losing any array elements.
+-- The same normalization applies to a missing required root value. Metadata
+-- and all supplied fragments are retained exactly, never re-encoded.
+normalizeStorageRow :: VariantStorageSchema -> NestedRow -> NestedRow
+normalizeStorageRow schema = node True (storageNode schema)
+  where
+    node required plan row = case row of
+      NRStruct fields
+        | V.length fields == storageFieldCount plan ->
+            let fallback = slot (storageValueIndex plan) fields
+                typed = slot (storageTypedIndex plan) fields
+                value = if required && missing fallback && missing typed then NRLeaf (LvBinary (BS.singleton 0)) else fallback
+                typedValue = maybe typed (`typedRow` typed) (storageTyped plan)
+                output = V.imap (\index original -> if index == storageValueIndex plan then value else if index == storageTypedIndex plan then typedValue else original) fields
+            in if not (needs required plan row) then row else NRStruct (if storageValueIndex plan < 0 then V.snoc output value else output)
+      _ -> row
+    needs required plan row = case row of
+      NRStruct fields
+        | V.length fields == storageFieldCount plan ->
+            storageValueIndex plan < 0
+              || (required && missing (slot (storageValueIndex plan) fields) && missing (slot (storageTypedIndex plan) fields))
+              || (storageNormalizationBelow plan && maybe False (\kind -> typedNeeds kind (slot (storageTypedIndex plan) fields)) (storageTyped plan))
+      _ -> False
+    typedNeeds kind row = case (kind, row) of
+      (StorageObject children _, NRStruct fields) | V.length fields == V.length children -> V.any (\child -> needs False (storageChildNode child) (V.unsafeIndex fields (storageChildIndex child))) children
+      (StorageArray child, NRList values) -> V.any (needs True child) values
+      _ -> False
+    typedRow kind row = case (kind, row) of
+      (StorageObject children _, NRStruct fields)
+        | V.length fields == V.length children ->
+            NRStruct (V.zipWith (\child value -> node False (storageChildNode child) value) children fields)
+      (StorageArray child, NRList values) -> NRList (V.map (node True child) values)
+      _ -> row
+
+
+slot :: Int -> V.Vector NestedRow -> NestedRow
+slot index fields = maybe NRNull id (fields V.!? index)
+{-# INLINE slot #-}
+
+
+missing :: NestedRow -> Bool
+missing NRNull = True
+missing _ = False
+{-# INLINE missing #-}
+
+
+type Checked# = (# String | Int# #)
+
+
+type NodeChecked# = (# String | Int# | () #)
+
+
+validateStorageRow :: VariantStorageSchema -> NestedRow -> Either String ()
+validateStorageRow _ NRNull = Right ()
+validateStorageRow schema row = case row of
+  NRStruct fields | V.length fields == storageFieldCount (storageNode schema) -> case slot (storageMetadataIndex schema) fields of
+    NRLeaf (LvBinary metadata) -> case B.compileVariantMetadataWithLimits limits metadata of
+      Left message -> Left message
+      Right dictionary -> case B.variantMaxValues limits of
+        I# budget -> case required# limits dictionary (storageNode schema) 0# budget row of
+          (# message | #) -> Left message
+          (# | _ #) -> Right ()
+    _ -> Left "Parquet.Variant.Nested: present root requires binary metadata"
+  _ -> Left "Parquet.Variant.Nested: root storage shape mismatch"
+  where
+    limits = storageLimits schema
+
+
+charge# :: B.VariantLimits -> Int# -> Int# -> Checked#
+charge# limits depth budget
+  | I# depth > B.variantMaxDepth limits = (# "Parquet.Variant.Nested: nesting depth limit exceeded" | #)
+  | I# budget <= 0 = (# "Parquet.Variant.Nested: value count limit exceeded" | #)
+  | otherwise = (# | budget +# (-1#) #)
+{-# INLINE charge# #-}
+
+
+required# :: B.VariantLimits -> B.VariantMetadata -> VariantStorageNode -> Int# -> Int# -> NestedRow -> Checked#
+required# limits dictionary plan depth budget row = case checkNode# limits dictionary plan depth budget row of
+  (# message | | #) -> (# message | #)
+  (# | left | #) -> (# | left #)
+  (# | | () #) -> charge# limits depth budget
+{-# INLINE required# #-}
+
+
+presence :: VariantStorageNode -> NestedRow -> Either String Bool
+presence plan (NRStruct fields)
+  | V.length fields /= storageFieldCount plan = Left "Parquet.Variant.Nested: wrapper field count mismatch"
+  | storageValueRequired plan && missing value = Left "Parquet.Variant.Nested: null at required value field"
+  | storageTypedRequired plan && missing typed = Left "Parquet.Variant.Nested: null at required typed field"
+  | otherwise = Right (not (missing value && missing typed))
+  where
+    value = slot (storageValueIndex plan) fields
+    typed = slot (storageTypedIndex plan) fields
+presence _ _ = Left "Parquet.Variant.Nested: shredded wrapper must be a required struct"
+{-# INLINE presence #-}
+
+
+checkNode# :: B.VariantLimits -> B.VariantMetadata -> VariantStorageNode -> Int# -> Int# -> NestedRow -> NodeChecked#
+checkNode# limits dictionary plan depth budget row = case presence plan row of
+  Left message -> (# message | | #)
+  Right False -> (# | | () #)
+  Right True
+    | NRStruct fields <- row ->
+        let fallback = slot (storageValueIndex plan) fields
+            typed = slot (storageTypedIndex plan) fields
+        in case (storageTyped plan, typed) of
+             (Just (StorageObject children names), NRStruct values) ->
+               case fallback of
+                 NRNull -> case charge# limits depth budget of
+                   (# message | #) -> (# message | | #)
+                   (# | left #) -> object children values left
+                 NRLeaf (LvBinary bytes) -> case B.decodeVariantFragment# limits dictionary depth budget bytes of
+                   (# message | #) -> (# message | | #)
+                   (# | (# B.VObject rest, left #) #)
+                     | M.foldrWithKey (\name _ found -> Set.member name names || found) False rest -> (# "Parquet.Variant.Nested: object field appears in typed and fallback storage" | | #)
+                     | otherwise -> object children values left
+                   _ -> (# "Parquet.Variant.Nested: partial fallback must be an object" | | #)
+                 _ -> badShapeResult# ()
+             (Just (StorageArray child), NRList values) -> case fallback of
+               NRNull -> case charge# limits depth budget of
+                 (# message | #) -> (# message | | #)
+                 (# | left #) -> case array# limits dictionary child (depth +# 1#) left values 0# of
+                   (# message | #) -> (# message | | #)
+                   (# | remaining #) -> (# | remaining | #)
+               _ -> conflictResult# ()
+             (Just StoragePrimitive, NRLeaf _) -> case fallback of
+               NRNull -> case charge# limits depth budget of
+                 (# message | #) -> (# message | | #)
+                 (# | left #) -> (# | left | #)
+               _ -> conflictResult# ()
+             (_, NRNull) -> case fallback of
+               NRLeaf (LvBinary bytes) -> case B.decodeVariantFragment# limits dictionary depth budget bytes of
+                 (# message | #) -> (# message | | #)
+                 (# | (# value, remaining #) #) -> case (storageTyped plan, value) of
+                   (Just StorageObject {}, B.VObject {}) -> (# "Parquet.Variant.Nested: object is missing its typed storage" | | #)
+                   (Just StorageArray {}, B.VArray {}) -> (# "Parquet.Variant.Nested: array is missing its typed storage" | | #)
+                   _ -> (# | remaining | #)
+               _ -> badShapeResult# ()
+             _ -> badShapeResult# ()
+    where
+      object children values left
+        | V.length values /= V.length children = badShapeResult# ()
+        | otherwise = case object# limits dictionary children (depth +# 1#) left values 0# of
+            (# message | #) -> (# message | | #)
+            (# | remaining #) -> (# | remaining | #)
+  _ -> badShapeResult# ()
+
+
+badShapeResult# :: () -> NodeChecked#
+badShapeResult# () = (# "Parquet.Variant.Nested: typed storage shape mismatch" | | #)
+
+
+conflictResult# :: () -> NodeChecked#
+conflictResult# () = (# "Parquet.Variant.Nested: value and typed_value conflict" | | #)
+
+
+object# :: B.VariantLimits -> B.VariantMetadata -> V.Vector VariantStorageChild -> Int# -> Int# -> V.Vector NestedRow -> Int# -> Checked#
+object# limits dictionary children depth budget values index
+  | isTrue# (index ==# count) = (# | budget #)
+  | otherwise =
+      let child = V.unsafeIndex children (I# index)
+          row = V.unsafeIndex values (storageChildIndex child)
+      in case presence (storageChildNode child) row of
+           Left message -> (# message | #)
+           Right False -> object# limits dictionary children depth budget values (index +# 1#)
+           Right True | not (B.metadataContains (storageChildName child) dictionary) -> (# "Parquet.Variant.Nested: typed field name is missing from the shared dictionary" | #)
+           _ -> case checkNode# limits dictionary (storageChildNode child) depth budget row of
+             (# message | | #) -> (# message | #)
+             (# | left | #) -> object# limits dictionary children depth left values (index +# 1#)
+             (# | | () #) -> object# limits dictionary children depth budget values (index +# 1#)
+  where
+    I# count = V.length children
+
+
+array# :: B.VariantLimits -> B.VariantMetadata -> VariantStorageNode -> Int# -> Int# -> V.Vector NestedRow -> Int# -> Checked#
+array# limits dictionary child depth budget values index
+  | isTrue# (index ==# count) = (# | budget #)
+  | otherwise = case required# limits dictionary child depth budget (V.unsafeIndex values (I# index)) of
+      (# message | #) -> (# message | #)
+      (# | left #) -> array# limits dictionary child depth left values (index +# 1#)
+  where
+    I# count = V.length values
diff --git a/src/Parquet/Variant/Parquet.hs b/src/Parquet/Variant/Parquet.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Variant/Parquet.hs
@@ -0,0 +1,142 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Parquet Variant v1 columns. A null column slot is distinct
+from the present Variant null value. Binary payloads are decoded only by
+these explicit semantic operations; ordinary Parquet binary reads preserve
+bytes, including payloads that are not valid Variants.
+-}
+module Parquet.Variant.Parquet (
+  VariantReader,
+  compileVariantReader,
+  compileVariantReaderWithLimits,
+  variantAt,
+  variantAt#,
+  variantToNestedRow,
+  variantToNestedRowWithLimits,
+  buildVariantParquetFile,
+  buildVariantParquetFileWithLimits,
+  readVariantColumn,
+  readVariantColumnWithLimits,
+) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Control.Monad (unless)
+import Data.ByteString (ByteString)
+import Data.Text (Text)
+import Data.Vector qualified as V
+import GHC.Exts (Int (I#), Int#)
+import Parquet.Arrow qualified as Arrow
+import Parquet.Nested qualified as N
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+import Parquet.Variant qualified as Variant
+import Parquet.Variant.Arrow qualified as VariantArrow
+import Parquet.Variant.Schema qualified as VariantSchema
+
+
+data VariantReader = VariantReader
+  { readerLength :: {-# UNPACK #-} !Int
+  , readerValidity :: !(Maybe C.Validity)
+  , readerMetadata :: !C.ColumnArray
+  , readerValue :: !C.ColumnArray
+  , readerLimits :: !Variant.VariantLimits
+  }
+
+
+compileVariantReader :: C.ColumnArray -> Either String VariantReader
+compileVariantReader = compileVariantReaderWithLimits Variant.defaultVariantLimits
+
+
+{- | Compile named binary child views once. Accepts ordinary/large/view
+binary arrays. Required children are checked only when the parent is
+present, so null parents mask arbitrary child storage.
+-}
+compileVariantReaderWithLimits :: Variant.VariantLimits -> C.ColumnArray -> Either String VariantReader
+compileVariantReaderWithLimits limits column = case column of
+  C.ColStruct count validity children -> do
+    unless
+      (count >= 0 && V.length children == 2 && V.length (V.filter ((== "metadata") . fst) children) == 1 && V.length (V.filter ((== "value") . fst) children) == 1)
+      (Left "Parquet.Variant: unshredded column requires unique metadata and value fields")
+    metadata <- named "metadata" children
+    value <- named "value" children
+    unless
+      (binary metadata && binary value && C.columnLength metadata >= count && C.columnLength value >= count)
+      (Left "Parquet.Variant: metadata/value must be binary arrays covering the group")
+    unless
+      (Variant.variantMaxDepth limits >= 0 && Variant.variantMaxValues limits > 0 && Variant.variantMaxDictionaryEntries limits >= 0)
+      (Left "Parquet.Variant: invalid resource limits")
+    pure (VariantReader count validity metadata value limits)
+  _ -> Left "Parquet.Variant: expected a struct column"
+  where
+    named name children = maybe (Left "Parquet.Variant: missing binary field") (Right . snd) (V.find ((== name) . fst) children)
+    binary value = case value of
+      C.ColBinary {} -> True
+      C.ColLargeBinary {} -> True
+      C.ColBinaryView {} -> True
+      _ -> False
+
+
+variantAt :: VariantReader -> Int -> Either String (Maybe Variant.Variant)
+variantAt reader (I# index) = case variantAt# reader index of
+  (# message | | #) -> Left message
+  (# | value | #) -> Right (Just value)
+  (# | | () #) -> Right Nothing
+
+
+variantAt# :: VariantReader -> Int# -> (# String | Variant.Variant | () #)
+variantAt# reader index#
+  | index < 0 || index >= readerLength reader = (# "Parquet.Variant: row index out of range" | | #)
+  | not (C.isValidAt (readerValidity reader) index) = (# | | () #)
+  | otherwise = case C.anyBytesAt (readerMetadata reader) index of
+      Nothing -> (# "Parquet.Variant: present group has null metadata" | | #)
+      Just metadata -> case C.anyBytesAt (readerValue reader) index of
+        Nothing -> (# "Parquet.Variant: present unshredded group has null value" | | #)
+        Just value -> case Variant.decodeVariantWithLimits (readerLimits reader) metadata value of
+          Left message -> (# message | | #)
+          Right decoded -> (# | decoded | #)
+  where
+    index = I# index#
+{-# INLINE variantAt# #-}
+
+
+variantToNestedRow :: Maybe Variant.Variant -> Either String N.NestedRow
+variantToNestedRow = variantToNestedRowWithLimits Variant.defaultVariantLimits
+
+
+variantToNestedRowWithLimits :: Variant.VariantLimits -> Maybe Variant.Variant -> Either String N.NestedRow
+variantToNestedRowWithLimits _ Nothing = Right N.NRNull
+variantToNestedRowWithLimits limits (Just value) = do
+  encoded <- Variant.encodeVariantWithLimits limits value
+  pure (N.NRVariantBytes (Variant.variantMetadata encoded) (Variant.variantValue encoded))
+
+
+buildVariantParquetFile :: Text -> V.Vector (Maybe Variant.Variant) -> Either String ByteString
+buildVariantParquetFile = buildVariantParquetFileWithLimits Variant.defaultVariantLimits
+
+
+buildVariantParquetFileWithLimits :: Variant.VariantLimits -> Text -> V.Vector (Maybe Variant.Variant) -> Either String ByteString
+buildVariantParquetFileWithLimits limits name values = do
+  rows <- V.mapM (variantToNestedRowWithLimits limits) values
+  N.buildNestedFile (V.singleton (name, N.NSOptional (N.NSVariantWithLimits limits))) (V.singleton rows)
+
+
+readVariantColumn :: Read.ParquetFile -> Int -> Text -> Either String (V.Vector (Maybe Variant.Variant))
+readVariantColumn = readVariantColumnWithLimits Variant.defaultVariantLimits
+
+
+{- | Read one top-level VARIANT(1) column, reconstructing typed primitives,
+objects and arrays with the original shared metadata dictionary.
+-}
+readVariantColumnWithLimits :: Variant.VariantLimits -> Read.ParquetFile -> Int -> Text -> Either String (V.Vector (Maybe Variant.Variant))
+readVariantColumnWithLimits limits file group name = do
+  schema <- Arrow.parquetFileArrowSchemaChecked file
+  field <- maybe (Left "Parquet.Variant: column not found") Right (V.find ((== name) . A.fieldName) (A.arrowFields schema))
+  unless (VariantSchema.isVariantField field) (Left "Parquet.Variant: expected VARIANT(1) schema")
+  columns <- either (Left . show) Right (Arrow.parquetRowGroupToArrow schema {A.arrowFields = V.singleton field} file group)
+  let schemaLimits = VariantSchema.VariantSchemaLimits 128 (V.length (P.fmSchema (Read.pfFooter file)))
+  reader <- VariantArrow.compileVariantArrowReaderWithLimits limits schemaLimits field (V.head columns)
+  V.generateM (VariantArrow.variantArrowLength reader) (VariantArrow.variantArrowAt reader)
diff --git a/src/Parquet/Variant/Schema.hs b/src/Parquet/Variant/Schema.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Variant/Schema.hs
@@ -0,0 +1,315 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+{- | Canonical @arrow.parquet.variant@ storage schemas. The binary Variant
+codec accepts a wider scale range than a typed decimal column: typed storage
+must use the narrowest precision band and @0 <= scale <= precision@.
+
+See https://arrow.apache.org/docs/format/CanonicalExtensions.html#parquet-variant.
+This module checks storage shape and type mappings; value reconstruction is
+owned by the Variant semantic reader, not by this schema validator.
+-}
+module Parquet.Variant.Schema (
+  VariantSchemaLimits (..),
+  VariantStorageSchema,
+  compileVariantStorageSchema,
+  compileVariantStorageSchemaWithLimits,
+  defaultVariantSchemaLimits,
+  variantExtensionMetadata,
+  isVariantField,
+  variantField,
+  validateVariantField,
+  validateVariantFieldWithLimits,
+  variantTypedLeaf,
+) where
+
+import Arrow.Types qualified as A
+import Control.Monad (unless)
+import Data.Int (Int32)
+import Data.Set qualified as Set
+import Data.Text (Text)
+import Data.Text qualified as T
+import Data.Text.Read qualified as TR
+import Data.Vector qualified as V
+import Parquet.Nested.Types (VariantStorageSchema)
+import Parquet.Nested.Types qualified as N
+import Parquet.Types qualified as P
+import Parquet.Variant qualified as B
+
+
+data VariantSchemaLimits = VariantSchemaLimits
+  { variantSchemaMaxDepth :: {-# UNPACK #-} !Int
+  , variantSchemaMaxFields :: {-# UNPACK #-} !Int
+  }
+  deriving (Show, Eq)
+
+
+defaultVariantSchemaLimits :: VariantSchemaLimits
+defaultVariantSchemaLimits = VariantSchemaLimits 64 1048576
+
+
+variantExtensionMetadata :: V.Vector (Text, Text)
+variantExtensionMetadata = V.fromList [("ARROW:extension:name", "arrow.parquet.variant"), ("ARROW:extension:metadata", "")]
+
+
+isVariantField :: A.Field -> Bool
+isVariantField = V.elem ("ARROW:extension:name", "arrow.parquet.variant") . A.fieldMetadata
+
+
+{- | Standard metadata/value storage, optionally with a typed column. Its
+supplied name/nullability are replaced with the canonical optional field.
+-}
+variantField :: Text -> Bool -> Maybe A.Field -> Either String A.Field
+variantField name nullable typed = do
+  let fields = V.fromList ([A.defaultLeafField "metadata" False A.ABinary, A.defaultLeafField "value" True A.ABinary] ++ maybe [] (\field -> [field {A.fieldName = "typed_value", A.fieldNullable = True}]) typed)
+      result = (A.defaultField name nullable A.AStruct fields) {A.fieldMetadata = variantExtensionMetadata}
+  validateVariantField result
+  pure result
+
+
+values :: Text -> A.Field -> V.Vector Text
+values key = V.map snd . V.filter ((== key) . fst) . A.fieldMetadata
+
+
+bad :: String -> Either String a
+bad = Left . ("Parquet.Variant.Schema: " ++)
+
+
+need :: Bool -> String -> Either String ()
+need condition message = unless condition (bad message)
+
+
+emptyExtension :: Text -> A.Field -> Either String ()
+emptyExtension name field = do
+  need (values "ARROW:extension:name" field == V.singleton name) "extension name must be unique and exact"
+  let parameters = values "ARROW:extension:metadata" field
+  need (V.length parameters <= 1 && V.all T.null parameters) "extension parameters must be absent or empty"
+
+
+plain :: A.Field -> Bool
+plain field = A.fieldDictionary field == Nothing && V.null (A.fieldChildren field)
+
+
+binary :: A.ArrowType -> Bool
+binary typ = typ `elem` [A.ABinary, A.ALargeBinary, A.ABinaryView]
+
+
+validateVariantField :: A.Field -> Either String ()
+validateVariantField = validateVariantFieldWithLimits defaultVariantSchemaLimits
+
+
+validateVariantFieldWithLimits :: VariantSchemaLimits -> A.Field -> Either String ()
+validateVariantFieldWithLimits limits field = do
+  need (variantSchemaMaxDepth limits >= 0 && variantSchemaMaxFields limits > 0) "invalid schema resource limits"
+  emptyExtension "arrow.parquet.variant" field
+  _ <- node 0 True (variantSchemaMaxFields limits) field
+  pure ()
+  where
+    charge depth remaining = do
+      need (depth <= variantSchemaMaxDepth limits) "schema depth limit exceeded"
+      need (remaining > 0) "schema field limit exceeded"
+      pure (remaining - 1)
+    node depth root remaining current = do
+      budget <- charge depth remaining
+      need (A.fieldType current == A.AStruct && A.fieldDictionary current == Nothing) "Variant node must use struct storage"
+      let fields = A.fieldChildren current
+          names = A.fieldName <$> fields
+          allowed = if root then ["metadata", "value", "typed_value"] else ["value", "typed_value"]
+      need (V.length fields <= length allowed && Set.size (Set.fromList (V.toList names)) == V.length fields && V.all (`elem` allowed) names) "node fields must be unique canonical names"
+      need (V.elem "value" names || V.elem "typed_value" names) "node requires value or typed_value"
+      need (not root || V.elem "metadata" names) "Variant root requires metadata"
+      V.foldM'
+        ( \left child -> case A.fieldName child of
+            "metadata" -> metadata (depth + 1) left child
+            "value" -> do
+              next <- charge (depth + 1) left
+              need (plain child && binary (A.fieldType child)) "value must use binary storage"
+              pure next
+            "typed_value" -> typed (depth + 1) left child
+            _ -> bad "unexpected node field"
+        )
+        budget
+        fields
+    metadata depth remaining current = do
+      budget <- charge depth remaining
+      need (not (A.fieldNullable current)) "metadata must be non-nullable"
+      case A.fieldType current of
+        A.ARunEndEncoded -> do
+          need (A.fieldDictionary current == Nothing) "metadata cannot combine dictionary and run-end encoding"
+          case V.toList (A.fieldChildren current) of
+            [ends, entries] -> do
+              b1 <- charge (depth + 1) budget
+              b2 <- charge (depth + 1) b1
+              need (plain ends && not (A.fieldNullable ends) && A.fieldType ends `elem` [A.AInt 16 True, A.AInt 32 True, A.AInt 64 True]) "metadata run ends require non-null signed16/32/64 storage"
+              need (plain entries && binary (A.fieldType entries)) "metadata run values must be binary"
+              pure b2
+            _ -> bad "metadata run-end encoding requires two children"
+        typ -> do
+          need (binary typ && V.null (A.fieldChildren current)) "metadata must use binary storage"
+          case A.fieldDictionary current of
+            Nothing -> pure budget
+            Just dictionary -> do
+              case A.deIndexType dictionary of
+                A.AInt width _ -> need (width `elem` [8, 16, 32, 64]) "metadata dictionary index width must be8/16/32/64"
+                _ -> bad "metadata dictionary indices must be integers"
+              pure budget
+    typed depth remaining current = case A.fieldType current of
+      A.AStruct -> do
+        need (V.null (values "ARROW:extension:name" current)) "typed object must not carry another extension"
+        budget <- charge depth remaining
+        need (A.fieldDictionary current == Nothing) "typed objects cannot be dictionary encoded"
+        let fields = A.fieldChildren current
+        need (V.length fields <= budget) "schema field limit exceeded"
+        need (Set.size (Set.fromList (V.toList (A.fieldName <$> fields))) == V.length fields) "object field names must be unique"
+        V.foldM'
+          ( \left child -> do
+              need (not (A.fieldNullable child)) "shredded object field wrappers must be non-nullable"
+              node (depth + 1) False left child
+          )
+          budget
+          fields
+      typ | typ `elem` [A.AList, A.ALargeList, A.AListView] -> do
+        need (V.null (values "ARROW:extension:name" current)) "typed list must not carry another extension"
+        budget <- charge depth remaining
+        need (A.fieldDictionary current == Nothing) "typed lists cannot be dictionary encoded"
+        case V.toList (A.fieldChildren current) of
+          [child] -> do
+            need (not (A.fieldNullable child)) "shredded list elements must be non-nullable"
+            node (depth + 1) False budget child
+          _ -> bad "typed list requires one struct element field"
+      _ -> do
+        budget <- charge depth remaining
+        _ <- variantTypedLeaf current
+        pure budget
+
+
+{- | Exact Arrow-to-Parquet primitive mapping for typed Variant storage.
+Generic Arrow decimals with negative scales, wider carriers or different
+units remain valid Arrow types, but cannot be used as typed Variants.
+-}
+variantTypedLeaf :: A.Field -> Either String N.LeafType
+variantTypedLeaf field = do
+  need (plain field) "typed primitives cannot have children or dictionary encoding"
+  let extension = values "ARROW:extension:name" field
+  if extension == V.singleton "arrow.uuid"
+    then do
+      emptyExtension "arrow.uuid" field
+      need (A.fieldType field == A.AFixedSizeBinary 16) "UUID storage must be fixed binary16"
+      pure N.LtUuid
+    else do
+      need (V.null extension) "unrecognized typed primitive extension"
+      case A.fieldType field of
+        A.ABool -> pure N.LtBool
+        A.AInt 8 True -> pure (N.LtInteger 8 True)
+        A.AInt 16 True -> pure (N.LtInteger 16 True)
+        A.AInt 32 True -> pure N.LtInt32
+        A.AInt 64 True -> pure N.LtInt64
+        A.AFloatingPoint A.Single -> pure N.LtFloat
+        A.AFloatingPoint A.DoublePrecision -> pure N.LtDouble
+        A.ADecimal32 precision scale -> decimal 1 9 precision scale
+        A.ADecimal64 precision scale -> decimal 10 18 precision scale
+        A.ADecimal precision scale -> decimal 19 38 precision scale
+        A.ADate A.DateDay -> pure N.LtDate
+        A.ATime A.Microsecond 64 -> pure (N.LtTime False P.LtMicros)
+        A.ATimestamp A.Microsecond Nothing -> pure (N.LtTimestamp False P.LtMicros)
+        A.ATimestamp A.Nanosecond Nothing -> pure (N.LtTimestamp False P.LtNanos)
+        A.ATimestamp A.Microsecond (Just "UTC") -> pure (N.LtTimestamp True P.LtMicros)
+        A.ATimestamp A.Nanosecond (Just "UTC") -> pure (N.LtTimestamp True P.LtNanos)
+        typ | typ `elem` [A.ABinary, A.ALargeBinary, A.ABinaryView] -> pure N.LtBinary
+        typ | typ `elem` [A.AUtf8, A.ALargeUtf8, A.AUtf8View] -> pure N.LtString
+        _ -> bad "Arrow type has no canonical typed Variant mapping"
+  where
+    decimal low high precision scale = do
+      need (precision >= low && precision <= high && scale >= 0 && scale <= precision) "typed decimal requires its exact precision band and scale0..precision"
+      pure (N.LtDecimal (fromIntegral precision) (fromIntegral scale))
+
+
+{- | Compile canonical Arrow Variant storage to a native typed schema.
+Primitive tags/scales are never inferred from row values. Metadata storage
+encodings normalize to binary while the original payload dictionary stays
+byte-for-byte intact. Use 'N.NSVariantTyped' with this opaque schema.
+-}
+compileVariantStorageSchema :: A.Field -> Either String VariantStorageSchema
+compileVariantStorageSchema = compileVariantStorageSchemaWithLimits B.defaultVariantLimits defaultVariantSchemaLimits
+
+
+compileVariantStorageSchemaWithLimits :: B.VariantLimits -> VariantSchemaLimits -> A.Field -> Either String VariantStorageSchema
+compileVariantStorageSchemaWithLimits limits schemaLimits field = do
+  validateVariantFieldWithLimits schemaLimits field
+  need (B.variantMaxDepth limits >= 0 && B.variantMaxValues limits > 0 && B.variantMaxDictionaryEntries limits >= 0) "invalid Variant resource limits"
+  layout <- nodeLayout True field
+  plan <- nodePlan field
+  identifiers <- nodeIds field
+  let metadataIndex = maybe (-1) id (V.findIndex ((== "metadata") . A.fieldName) (A.fieldChildren field))
+  pure (N.VariantStorageSchema limits field layout metadataIndex identifiers plan)
+  where
+    optional nullable value = if nullable then N.NSOptional value else N.NSRequired value
+    nodeLayout root current = do
+      let fields = A.fieldChildren current
+          shredded = V.any ((== "typed_value") . A.fieldName) fields
+      children <-
+        V.mapM
+          ( \child -> do
+              layout <- case A.fieldName child of
+                "metadata" -> pure (N.NSRequired (N.NSPrimitive N.LtBinary))
+                "value" -> pure (optional (not root || shredded) (N.NSPrimitive N.LtBinary))
+                "typed_value" -> N.NSOptional <$> typedLayout child
+                _ -> bad "unexpected storage field"
+              pure (A.fieldName child, layout)
+          )
+          fields
+      let complete = if V.any ((== "value") . A.fieldName) fields then children else V.snoc children ("value", N.NSOptional (N.NSPrimitive N.LtBinary))
+      pure (N.NSStruct complete)
+    typedLayout current = case A.fieldType current of
+      A.AStruct ->
+        N.NSStruct
+          <$> V.mapM
+            ( \child -> do
+                layout <- nodeLayout False child
+                pure (A.fieldName child, N.NSRequired layout)
+            )
+            (A.fieldChildren current)
+      typ | typ `elem` [A.AList, A.ALargeList, A.AListView] -> do
+        layout <- nodeLayout False (V.head (A.fieldChildren current))
+        pure (N.NSList (N.NSRequired layout))
+      _ -> N.NSPrimitive <$> variantTypedLeaf current
+    nodePlan current = do
+      let fields = A.fieldChildren current
+          index name = maybe (-1) id (V.findIndex ((== name) . A.fieldName) fields)
+          required position = maybe False (not . A.fieldNullable) (fields V.!? position)
+          value = index "value"
+          typed = index "typed_value"
+      plan <- case fields V.!? typed of
+        Nothing -> pure Nothing
+        Just child -> Just <$> typedPlan child
+      pure (N.VariantStorageNode (V.length fields) value typed (required value) (required typed) plan (maybe False below plan))
+    typedPlan current = case A.fieldType current of
+      A.AStruct -> do
+        children <- V.imapM (\index child -> N.VariantStorageChild (A.fieldName child) index <$> nodePlan child) (A.fieldChildren current)
+        pure (N.StorageObject children (Set.fromList (V.toList (N.storageChildName <$> children))))
+      typ | typ `elem` [A.AList, A.ALargeList, A.AListView] -> N.StorageArray <$> nodePlan (V.head (A.fieldChildren current))
+      _ -> pure N.StoragePrimitive
+
+    fieldId current = case V.toList (values "PARQUET:field_id" current) of
+      [] -> pure Nothing
+      [text] -> case TR.signed TR.decimal text :: Either String (Integer, Text) of
+        Right (number, rest) | T.null rest && number >= toInteger (minBound :: Int32) && number <= toInteger (maxBound :: Int32) -> pure (Just (fromInteger number))
+        _ -> bad "field ID must fit a signed INT32"
+      _ -> bad "field ID must be unique"
+    nodeIds current = do
+      ident <- fieldId current
+      children <- V.mapM (\child -> if A.fieldName child == "typed_value" then typedIds child else V.singleton <$> fieldId child) (A.fieldChildren current)
+      let body = V.concat (V.toList children)
+          complete = if V.any ((== "value") . A.fieldName) (A.fieldChildren current) then body else V.snoc body Nothing
+      pure (V.cons ident complete)
+    typedIds current = do
+      ident <- fieldId current
+      case A.fieldType current of
+        A.AStruct -> V.cons ident . V.concat . V.toList <$> V.mapM nodeIds (A.fieldChildren current)
+        typ | typ `elem` [A.AList, A.ALargeList, A.AListView] -> V.cons ident . V.cons Nothing <$> nodeIds (V.head (A.fieldChildren current))
+        _ -> pure (V.singleton ident)
+
+    needs required plan = N.storageValueIndex plan < 0 || N.storageNormalizationBelow plan || (required && not (N.storageValueRequired plan) && not (N.storageTypedRequired plan))
+    below current = case current of
+      N.StoragePrimitive -> False
+      N.StorageObject children _ -> V.any (needs False . N.storageChildNode) children
+      N.StorageArray child -> needs True child
diff --git a/src/Parquet/Variant/Shred.hs b/src/Parquet/Variant/Shred.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Variant/Shred.hs
@@ -0,0 +1,247 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE UnboxedSums #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Shred semantic Variant values to a declared canonical typed shape.
+Exact Variant constructors and decimal scales select typed storage; a
+mismatch stays in binary fallback with its original tag and coefficient.
+-}
+module Parquet.Variant.Shred (
+  VariantShredder,
+  compileVariantShredder,
+  compileVariantShredderWithLimits,
+  variantShredSchema,
+  shredVariant,
+  shredVariantWithMetadata,
+) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Data.ByteString qualified as BS
+import Data.ByteString.Internal qualified as BSI
+import Data.Int (Int32, Int64)
+import Data.Map.Internal qualified as MI
+import Data.Map.Strict qualified as M
+import Data.Set qualified as Set
+import Data.Text (Text)
+import Data.Vector qualified as V
+import Data.Word (byteSwap64)
+import Foreign.Storable (pokeByteOff)
+import GHC.ByteOrder (ByteOrder (..), targetByteOrder)
+import GHC.Exts (Int (I#))
+import Parquet.Nested.Generate qualified as Generate
+import Parquet.Nested.Types
+import Parquet.Variant qualified as B
+import Parquet.Variant.Schema qualified as Schema
+
+
+data VariantShredder = VariantShredder !VariantStorageSchema !NodePlan
+
+
+data NodePlan = NodePlan
+  { nodeFields :: {-# UNPACK #-} !Int
+  , nodeMetadata :: {-# UNPACK #-} !Int
+  , nodeValue :: {-# UNPACK #-} !Int
+  , nodeTyped :: {-# UNPACK #-} !Int
+  , nodePlan :: !(Maybe TypedPlan)
+  }
+
+
+data TypedPlan
+  = PrimitivePlan !(B.Variant -> (# LeafValue | () #))
+  | ObjectPlan !(V.Vector ChildPlan) !(Set.Set Text)
+  | ArrayPlan !NodePlan
+
+
+data ChildPlan = ChildPlan !Text !NodePlan
+
+
+compileVariantShredder :: A.Field -> Either String VariantShredder
+compileVariantShredder = compileVariantShredderWithLimits B.defaultVariantLimits Schema.defaultVariantSchemaLimits
+
+
+compileVariantShredderWithLimits :: B.VariantLimits -> Schema.VariantSchemaLimits -> A.Field -> Either String VariantShredder
+compileVariantShredderWithLimits limits schemaLimits field = do
+  Schema.validateVariantFieldWithLimits schemaLimits field
+  let complete = completeNode field
+  storage <- Schema.compileVariantStorageSchemaWithLimits limits schemaLimits complete
+  plan <- compileNode complete
+  pure (VariantShredder storage plan)
+  where
+    completeNode current =
+      let fields = A.fieldChildren current
+          normalized =
+            V.map
+              ( \child -> case A.fieldName child of
+                  "metadata" -> child {A.fieldType = A.ABinary, A.fieldDictionary = Nothing, A.fieldChildren = V.empty}
+                  "value" -> child {A.fieldType = A.ABinary, A.fieldNullable = True}
+                  "typed_value" -> completeTyped child
+                  _ -> child
+              )
+              fields
+          full = if V.any ((== "value") . A.fieldName) fields then normalized else V.snoc normalized (A.defaultLeafField "value" True A.ABinary)
+      in current {A.fieldChildren = full}
+    completeTyped current =
+      current
+        { A.fieldNullable = True
+        , A.fieldChildren = case A.fieldType current of
+            A.AStruct -> completeNode <$> A.fieldChildren current
+            typ | typ `elem` [A.AList, A.ALargeList, A.AListView] -> completeNode <$> A.fieldChildren current
+            _ -> A.fieldChildren current
+        }
+
+
+variantShredSchema :: VariantShredder -> NestedSchema
+variantShredSchema (VariantShredder storage _) =
+  (if A.fieldNullable (storageField storage) then NSOptional else NSRequired) (NSVariantTyped storage)
+
+
+shredVariant :: VariantShredder -> Maybe B.Variant -> Either String NestedRow
+shredVariant _ Nothing = Right NRNull
+shredVariant shredder@(VariantShredder storage _) (Just value) = do
+  metadata <- B.buildVariantMetadataForWithLimits (storageLimits storage) value
+  shredVariantWithMetadata shredder metadata (Just value)
+
+
+{- | Use one original dictionary for every fallback fragment and all fully
+shredded names. The complete semantic tree is checked against one budget
+before choosing any typed or binary branch. No scale conversion is done.
+-}
+shredVariantWithMetadata :: VariantShredder -> B.VariantMetadata -> Maybe B.Variant -> Either String NestedRow
+shredVariantWithMetadata _ _ Nothing = Right NRNull
+shredVariantWithMetadata (VariantShredder storage plan) metadata (Just value) = do
+  B.validateVariantWithMetadataWithLimits (storageLimits storage) metadata value
+  case nodeRow# (storageLimits storage) metadata plan (# value | #) of
+    (# message | #) -> Left message
+    (# | row #) -> Right row
+
+
+compileNode :: A.Field -> Either String NodePlan
+compileNode field = do
+  let fields = A.fieldChildren field
+      index name = maybe (-1) id (V.findIndex ((== name) . A.fieldName) fields)
+      typed = index "typed_value"
+  plan <- case fields V.!? typed of
+    Nothing -> pure Nothing
+    Just child -> Just <$> compileTyped child
+  pure (NodePlan (V.length fields) (index "metadata") (index "value") typed plan)
+
+
+compileTyped :: A.Field -> Either String TypedPlan
+compileTyped field = case A.fieldType field of
+  A.AStruct -> do
+    children <- V.mapM (\child -> ChildPlan (A.fieldName child) <$> compileNode child) (A.fieldChildren field)
+    pure (ObjectPlan children (Set.fromList (V.toList (A.fieldName <$> A.fieldChildren field))))
+  typ | typ `elem` [A.AList, A.ALargeList, A.AListView] -> ArrayPlan <$> compileNode (V.head (A.fieldChildren field))
+  _ -> PrimitivePlan <$> primitivePlan field
+
+
+type RowResult# = (# String | NestedRow #)
+
+
+nodeRow# :: B.VariantLimits -> B.VariantMetadata -> NodePlan -> (# B.Variant | () #) -> RowResult#
+nodeRow# limits metadata plan value = case value of
+  (# | () #) -> finish NRNull NRNull
+  (# present | #) -> case (nodePlan plan, present) of
+    (Just (PrimitivePlan select), _) -> case select present of
+      (# leaf | #) -> finish NRNull (NRLeaf leaf)
+      (# | () #) -> fallback present
+    (Just (ArrayPlan element), B.VArray values) -> case V.length values of
+      I# count -> case Generate.generate# count (\index -> nodeRow# limits metadata element (# V.unsafeIndex values (I# index) | #)) of
+        (# message | #) -> (# message | #)
+        (# | rows #) -> finish NRNull (NRList rows)
+    (Just (ObjectPlan children names), B.VObject fields) -> case V.length children of
+      I# count -> case Generate.generate#
+        count
+        ( \index -> case V.unsafeIndex children (I# index) of
+            ChildPlan name child -> nodeRow# limits metadata child (lookupValue# name fields)
+        ) of
+        (# message | #) -> (# message | #)
+        (# | rows #) ->
+          let remainder = M.withoutKeys fields names
+          in if M.null remainder
+               then finish NRNull (NRStruct rows)
+               else case B.encodeVariantValueWithLimits limits metadata (B.VObject remainder) of
+                 Left message -> (# message | #)
+                 Right bytes -> finish (NRLeaf (LvBinary bytes)) (NRStruct rows)
+    _ -> fallback present
+  where
+    finish binary typed = case nodeFields plan of
+      I# count -> case Generate.generate#
+        count
+        ( \index ->
+            (#
+              | if I# index == nodeMetadata plan
+                then NRLeaf (LvBinary (B.metadataBytes metadata))
+                else
+                  if I# index == nodeValue plan
+                    then binary
+                    else
+                      if I# index == nodeTyped plan
+                        then typed
+                        else NRNull
+            #)
+        ) of
+        (# message | #) -> (# message | #)
+        (# | rows #) -> (# | NRStruct rows #)
+    {-# INLINE finish #-}
+    fallback present = case B.encodeVariantValueWithLimits limits metadata present of
+      Left message -> (# message | #)
+      Right bytes -> finish (NRLeaf (LvBinary bytes)) NRNull
+    {-# INLINE fallback #-}
+
+
+-- Data.Map.lookup's boxed Maybe would allocate per shredded field. Keep the
+-- same ordered-tree search while returning an unboxed finite result.
+lookupValue# :: Text -> M.Map Text B.Variant -> (# B.Variant | () #)
+lookupValue# key current = case current of
+  MI.Tip -> (# | () #)
+  MI.Bin _ name value left right -> case compare key name of
+    LT -> lookupValue# key left
+    GT -> lookupValue# key right
+    EQ -> (# value | #)
+
+
+primitivePlan :: A.Field -> Either String (B.Variant -> (# LeafValue | () #))
+primitivePlan field = do
+  _ <- Schema.variantTypedLeaf field
+  pure $ case A.fieldType field of
+    A.ABool -> \value -> case value of B.VBool x -> (# LvBool x | #); _ -> no# ()
+    A.AInt 8 True -> \value -> case value of B.VInt8 x -> (# LvInt32 (fromIntegral x) | #); _ -> no# ()
+    A.AInt 16 True -> \value -> case value of B.VInt16 x -> (# LvInt32 (fromIntegral x) | #); _ -> no# ()
+    A.AInt 32 True -> \value -> case value of B.VInt32 x -> (# LvInt32 x | #); _ -> no# ()
+    A.AInt 64 True -> \value -> case value of B.VInt64 x -> (# LvInt64 x | #); _ -> no# ()
+    A.AFloatingPoint A.Single -> \value -> case value of B.VFloat x -> (# LvFloat x | #); _ -> no# ()
+    A.AFloatingPoint A.DoublePrecision -> \value -> case value of B.VDouble x -> (# LvDouble x | #); _ -> no# ()
+    A.ADecimal32 precision scale ->
+      let !bound = fromInteger (10 ^ precision - 1) :: Int32
+      in \value -> case value of B.VDecimal4 s x | fromIntegral s == scale && x >= negate bound && x <= bound -> (# LvInt32 x | #); _ -> no# ()
+    A.ADecimal64 precision scale ->
+      let !bound = fromInteger (10 ^ precision - 1) :: Int64
+      in \value -> case value of B.VDecimal8 s x | fromIntegral s == scale && x >= negate bound && x <= bound -> (# LvInt64 x | #); _ -> no# ()
+    A.ADecimal precision scale ->
+      let !bound = 10 ^ precision - 1
+      in \value -> case value of B.VDecimal16 s x | fromIntegral s == scale && x >= negate bound && x <= bound -> (# LvFixedBinary (decimalBytes (C.decimal128FromInteger x)) | #); _ -> no# ()
+    A.ADate A.DateDay -> \value -> case value of B.VDate x -> (# LvInt32 x | #); _ -> no# ()
+    A.ATime A.Microsecond 64 -> \value -> case value of B.VTime x -> (# LvInt64 x | #); _ -> no# ()
+    A.ATimestamp A.Microsecond Nothing -> \value -> case value of B.VTimestampNtz x -> (# LvInt64 x | #); _ -> no# ()
+    A.ATimestamp A.Microsecond (Just "UTC") -> \value -> case value of B.VTimestamp x -> (# LvInt64 x | #); _ -> no# ()
+    A.ATimestamp A.Nanosecond Nothing -> \value -> case value of B.VTimestampNtzNanos x -> (# LvInt64 x | #); _ -> no# ()
+    A.ATimestamp A.Nanosecond (Just "UTC") -> \value -> case value of B.VTimestampNanos x -> (# LvInt64 x | #); _ -> no# ()
+    A.AFixedSizeBinary 16 -> \value -> case value of B.VUuid x -> (# LvFixedBinary x | #); _ -> no# ()
+    typ | typ `elem` [A.ABinary, A.ALargeBinary, A.ABinaryView] -> \value -> case value of B.VBinary x -> (# LvBinary x | #); _ -> no# ()
+    typ | typ `elem` [A.AUtf8, A.ALargeUtf8, A.AUtf8View] -> \value -> case value of B.VString x -> (# LvString x | #); _ -> no# ()
+    _ -> \_ -> no# ()
+
+
+no# :: () -> (# LeafValue | () #)
+no# () = (# | () #)
+{-# INLINE no# #-}
+
+
+decimalBytes :: C.Decimal128 -> BS.ByteString
+decimalBytes (C.Decimal128 lo hi) = BSI.unsafeCreate 16 $ \pointer -> do
+  let big word = case targetByteOrder of LittleEndian -> byteSwap64 word; BigEndian -> word
+  pokeByteOff pointer 0 (big hi)
+  pokeByteOff pointer 8 (big lo)
diff --git a/src/Parquet/Write.hs b/src/Parquet/Write.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Write.hs
@@ -0,0 +1,3573 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE PatternSynonyms #-}
+{-# LANGUAGE RankNTypes #-}
+{-# LANGUAGE UnboxedTuples #-}
+
+{- | Write Parquet files.
+
+Provides page-level encoding, column chunk assembly, and whole-file builders.
+The user-facing entry point is 'buildParquetFile' (or
+'buildParquetFileWithIndex' when emitting bloom filter / page index
+regions). Both accept heterogeneous primitive columns via 'ColumnData'.
+
+@
+import qualified Data.Vector.Primitive as VP
+import qualified Data.Vector as V
+import Parquet.Write
+import Parquet.Types
+
+let schema = V.fromList
+      [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+      , SchemaElement "x" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+      ]
+    vals = VP.fromList [1, 2, 3 :: Int32]
+    bs = buildParquetFile schema (V.singleton (V.singleton (ColInt32 vals)))
+@
+-}
+module Parquet.Write (
+  -- * Whole-file builders (preferred entry points)
+  buildParquetFile,
+  buildParquetFileWithIndex,
+  buildParquetFileWithIndexIO,
+
+  -- * Per-column auxiliary metadata for the indexed writer
+  ColumnAux (..),
+  buildParquetFileMixedWithAux,
+  buildParquetFileMixedWithAuxUsing,
+  emptyColumnAux,
+
+  -- * Per-column encryption (modular AES-GCM / AES-GCM-CTR)
+  ColumnEncryption (..),
+  columnEncryptionFor,
+  encryptPageBytes,
+  encryptPageBytesV2,
+  encryptAuxModule,
+
+  -- * Encrypted-footer mode
+  FooterEncryption (..),
+  newFooterEncryption,
+  buildParquetFileWithIndexEncryptedFooter,
+
+  -- * Column data
+  ColumnData (..),
+  columnDataLength,
+  columnDataParquetType,
+  columnDataStatistics,
+  encodeColumnDataPage,
+  encodeColumnDataPageParts,
+
+  -- * Nullable columns (definition levels)
+  OptionalColumn (..),
+  optionalColumnLength,
+  optionalColumnNullCount,
+  optionalColumnPresentValues,
+  encodeOptionalColumnPage,
+
+  -- * Dictionary encoding
+  Dictionary (..),
+  buildDictionary,
+  encodeDictPage,
+  encodeDictDataPage,
+
+  -- * Data page version (V1 vs V2)
+  PageVersion (..),
+  encodeColumnDataPageV2,
+  encodeColumnDataPageV2Parts,
+  encodeOptionalColumnPageV2,
+  encodeOptionalColumnPageV2Parts,
+
+  -- * Page / footer building blocks (used by composite writers)
+  writeParquetFile,
+  encodePageHeader,
+  assembleColumnChunk,
+  ColumnAuxLayout (..),
+  layoutColumnAuxiliaries,
+  validateAuxIndexes,
+
+  -- * Mixed required + optional columns (nullable-aware)
+  ParquetColumn (..),
+  parquetColumnLength,
+  parquetColumnParquetType,
+  buildParquetFileMixed,
+  buildParquetFileMixedWith,
+
+  -- * Size statistics
+  columnDataUnencodedByteArrayBytes,
+  buildOffsetIndexWithSizeStats,
+) where
+
+import Control.Monad.ST (runST)
+import Control.Monad.ST.Unsafe (unsafeIOToST)
+import Crypto.Random.Types qualified as RNG
+import Data.Bits (finiteBitSize, rotateL, setBit, shiftL, shiftR, xor, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Internal qualified as BSI
+import Data.ByteString.Lazy qualified as BL
+import Data.Int (Int16, Int32, Int64)
+import Data.Map.Strict qualified as Map
+import Data.Maybe (fromMaybe)
+import Data.Primitive.ByteArray (copyByteArrayToAddr)
+import Data.Primitive.Types (Prim)
+import Data.Text (Text)
+import Data.Vector qualified as V
+import Data.Vector.Mutable qualified as MV
+import Data.Vector.Primitive qualified as VP
+import Data.Vector.Primitive.Mutable qualified as MVP
+import Data.Word (Word16, Word32, Word64, Word8, byteSwap16, byteSwap32, byteSwap64)
+import Foreign.ForeignPtr (touchForeignPtr)
+import Foreign.ForeignPtr.Unsafe (unsafeForeignPtrToPtr)
+import Foreign.Ptr (plusPtr, ptrToWordPtr, wordPtrToPtr)
+import GHC.ByteOrder (ByteOrder (..), targetByteOrder)
+import GHC.Exts (Int (I#), Int#, inline, keepAlive#, readWord8OffAddr#, readWord8OffAddrAsWord16#, readWord8OffAddrAsWord32#, readWord8OffAddrAsWord64#, timesWord2#, word64ToWord#, wordToWord64#, xor#, (<=#), (==#), (>#), (>=#))
+import GHC.Float (castDoubleToWord64, castFloatToWord32)
+import GHC.IO (IO (..))
+import GHC.Ptr (Ptr (..))
+import GHC.ST (ST (..))
+import GHC.Word (Word16 (W16#), Word32 (W32#), Word64 (W64#), Word8 (W8#))
+import Parquet.BloomFilter (Sbbf, encodeBloomFilter, sbbfNumBytes)
+import Parquet.BloomFilter qualified as BF
+import Parquet.Compress (compressPageBytes)
+import Parquet.Compress qualified as Compress
+import Parquet.Decimal (compareDecimalBytes, encodeDecimalInteger)
+import Parquet.Encryption qualified as Enc
+import Parquet.Footer (
+  fileMetadataToThrift,
+  parquetEncryptedMagic,
+  parquetMagic,
+  writeFooter,
+  writeRawFooterEither,
+ )
+import Parquet.LevelsEncode qualified as LE
+import Parquet.Page (
+  DataPageHeader (..),
+  DataPageHeaderV2 (..),
+  DictionaryPageHeader (..),
+  PageHeader (..),
+  PageType (..),
+  pageTypeTag,
+  readPageHeaderAt,
+ )
+import Parquet.PageIndex (
+  encodeColumnIndex,
+  encodeOffsetIndex,
+ )
+import Parquet.Thrift.Schema
+import Parquet.Types (
+  BoundaryOrder (..),
+  ColumnChunk (..),
+  ColumnIndex (..),
+  ColumnMetadata (..),
+  ColumnOrder (..),
+  Compression (..),
+  ConvertedType (..),
+  Encoding (..),
+  FileMetadata (..),
+  LogicalType (..),
+  OffsetIndex (..),
+  PageLocation (..),
+  ParquetType (..),
+  Repetition (..),
+  RowGroup (..),
+  SchemaElement (..),
+  Statistics (..),
+  hasCompatiblePhysicalType,
+  hasDefinedStatisticsOrder,
+ )
+import Thrift.Decode qualified as Thrift
+import Thrift.Encode (compactEncodedSizeBounded, encodeCompact, encodeCompactBounded)
+import Thrift.Value qualified as TV
+import Wireform.Builder qualified as B
+import Wireform.Encode.Direct qualified as Direct
+import Wireform.Hash qualified as Hash
+
+
+{- | Assemble a complete Parquet file from pre-computed metadata and encoded
+column chunk data. Each inner vector is one row group's column chunks
+(already-encoded pages).
+-}
+writeParquetFile :: FileMetadata -> V.Vector (V.Vector ByteString) -> ByteString
+writeParquetFile fm rowGroupData =
+  BL.toStrict $
+    B.toLazyByteString $
+      B.byteString parquetMagic
+        <> V.foldl' (\b rg -> V.foldl' (\b2 col -> b2 <> B.byteString col) b rg) mempty rowGroupData
+        <> B.byteString (writeFooter fm)
+
+
+writeFloatLE :: Float -> B.Builder
+writeFloatLE = B.word32LE . castFloatToWord32
+
+
+writeDoubleLE :: Double -> B.Builder
+writeDoubleLE = B.word64LE . castDoubleToWord64
+
+
+mkPlainDataPageHeader :: Int32 -> Int32 -> PageHeader
+mkPlainDataPageHeader numValues bodySize =
+  PageHeader
+    { phType =
+        PtDataPage
+          DataPageHeader
+            { dphNumValues = numValues
+            , dphEncoding = 0
+            }
+    , phUncompressedPageSize = Just bodySize
+    , phCompressedPageSize = Just bodySize
+    }
+
+
+-- | Thrift compact-encode a 'PageHeader'.
+encodePageHeader :: PageHeader -> ByteString
+encodePageHeader hdr = encodeCompact (pageHeaderToThrift hdr)
+
+
+pageHeaderToThrift :: PageHeader -> TV.Value
+pageHeaderToThrift hdr =
+  TV.Struct $
+    V.fromList $
+      concat
+        [ [PageHeader_Type (pageTypeTag (phType hdr))]
+        , optField (phUncompressedPageSize hdr) PageHeader_UncompressedSize
+        , optField (phCompressedPageSize hdr) PageHeader_CompressedSize
+        , case phType hdr of
+            PtDataPage dph ->
+              [ PageHeader_DataPageHeader
+                  (dataPageHeaderFields dph)
+              ]
+            PtDictionaryPage dk ->
+              [ PageHeader_DictionaryPageHeader
+                  (dictPageHeaderFields dk)
+              ]
+            PtDataPageV2 v2 ->
+              [ PageHeader_DataPageHeaderV2
+                  (dataPageHeaderV2Fields v2)
+              ]
+            PtIndexPage -> []
+        ]
+
+
+dataPageHeaderFields :: DataPageHeader -> V.Vector (Int16, TV.Value)
+dataPageHeaderFields dph =
+  V.fromList
+    [ DataPageHeader_NumValues (dphNumValues dph)
+    , DataPageHeader_Encoding (dphEncoding dph)
+    , -- Both fields are /required/ in parquet.thrift's DataPageHeader.
+      -- For required (max-def-level=0) columns the encoded level data
+      -- is zero bytes, but the encoding still has to be declared or
+      -- strict readers reject the page header. RLE (3) is what
+      -- parquet-mr / arrow-cpp stamp here, so we mirror that.
+      DataPageHeader_DefinitionLevelEncoding 3
+    , DataPageHeader_RepetitionLevelEncoding 3
+    ]
+
+
+dictPageHeaderFields :: DictionaryPageHeader -> V.Vector (Int16, TV.Value)
+dictPageHeaderFields dk =
+  V.fromList
+    [ DictionaryPageHeader_NumValues (dictNumValues dk)
+    , DictionaryPageHeader_Encoding (dictEncoding dk)
+    ]
+
+
+dataPageHeaderV2Fields :: DataPageHeaderV2 -> V.Vector (Int16, TV.Value)
+dataPageHeaderV2Fields v2 =
+  V.fromList
+    [ DataPageHeaderV2_NumValues (dph2NumValues v2)
+    , DataPageHeaderV2_NumNulls (dph2NumNulls v2)
+    , DataPageHeaderV2_NumRows (dph2NumRows v2)
+    , DataPageHeaderV2_Encoding (dph2Encoding v2)
+    , DataPageHeaderV2_DefinitionLevelsByteLength (dph2DefLevelsLen v2)
+    , DataPageHeaderV2_RepetitionLevelsByteLength (dph2RepLevelsLen v2)
+    , DataPageHeaderV2_IsCompressed (dph2IsCompressed v2)
+    ]
+
+
+{- | Concatenate pre-encoded pages into a single column chunk. Currently only
+@Uncompressed@ is supported for writing; pages must already be encoded with
+their headers.
+-}
+assembleColumnChunk :: Compression -> [ByteString] -> ByteString
+assembleColumnChunk _codec pages = mconcat pages
+
+
+-- ============================================================
+-- DATA_PAGE_V2
+-- ============================================================
+
+{- | Encode an 'OptionalColumn' as a single @DATA_PAGE_V2@.
+
+Layout (per the Parquet spec):
+
+@
+<repetition_levels>   -- length given by header.repetition_levels_byte_length
+                      -- always uncompressed; we emit zero bytes for
+                      -- non-repeated columns.
+<definition_levels>   -- length given by header.definition_levels_byte_length
+                      -- always uncompressed; max def-level is 1 for
+                      -- optional columns.
+<values>              -- compressed iff codec /= Uncompressed; PLAIN encoded.
+@
+
+The level segments are RLE-hybrid encoded *without* the 4-byte length
+prefix that V1 uses. The header records both segment lengths and an
+@is_compressed@ flag.
+-}
+encodeOptionalColumnPageV2 :: Compression -> OptionalColumn -> Either String ByteString
+encodeOptionalColumnPageV2 codec oc = do
+  parts <- encodeOptionalColumnPageV2Parts codec oc
+  Right (concatV2Parts parts)
+
+
+{- | Like 'encodeOptionalColumnPageV2' but returns the four byte
+segments separately so callers (in particular the encrypted writer
+path) can apply per-module ciphers. The tuple is
+@(pageHeader, repLevels, defLevels, values)@.
+-}
+encodeOptionalColumnPageV2Parts
+  :: Compression
+  -> OptionalColumn
+  -> Either String (ByteString, ByteString, ByteString, ByteString)
+encodeOptionalColumnPageV2Parts codec oc = do
+  page <- encodeOptionalV2Prepared codec oc (optionalColumnPresentValues oc)
+  Right (eov2Header page, eov2Repetitions page, eov2Definitions page, eov2Values page)
+
+
+data EncodedOptionalV2 = EncodedOptionalV2
+  { eov2Header :: !ByteString
+  , eov2Repetitions :: !ByteString
+  , eov2Definitions :: !ByteString
+  , eov2Values :: !ByteString
+  , eov2UncompressedSize :: {-# UNPACK #-} !Int
+  }
+
+
+encodeOptionalV2Prepared :: Compression -> OptionalColumn -> ColumnData -> Either String EncodedOptionalV2
+encodeOptionalV2Prepared codec oc present = do
+  nVals <- pageInt32 "value count" (optionalColumnLength oc)
+  valuePlan <- planPlainPayload present
+  defPlan <- LE.planRLEHybrid 1 1 (optionalDefinitionLevels oc)
+  uncompPageSize <- pageSizeWithOverhead (LE.hybridEncodedSize defPlan) (plainPayloadSize valuePlan)
+  let !defStream = LE.encodeHybridPlan defPlan
+      !defLen = LE.hybridEncodedSize defPlan
+      !repStream = BS.empty
+      !repLen = 0 :: Int
+      !valuesRaw = encodePlannedPlainPayload valuePlan present
+  (valuesBs, codecActual) <- case Compress.compressPageBytes codec valuesRaw of
+    Right cb -> Right (cb, codec)
+    Left e -> Left e
+  compPageSize <- pageSizeWithOverhead defLen (BS.length valuesBs)
+  let !nNulls = optionalColumnLength oc - columnDataLength present
+      !nRows = nVals -- non-repeated => num_rows == num_values
+      !hdrBytes =
+        encodePageHeader
+          PageHeader
+            { phType =
+                PtDataPageV2
+                  DataPageHeaderV2
+                    { dph2NumValues = nVals
+                    , dph2NumNulls = fromIntegral nNulls
+                    , dph2NumRows = nRows
+                    , dph2Encoding = 0 -- PLAIN
+                    , dph2DefLevelsLen = fromIntegral defLen
+                    , dph2RepLevelsLen = fromIntegral repLen
+                    , dph2IsCompressed = codecActual /= Uncompressed
+                    }
+            , phUncompressedPageSize = Just uncompPageSize
+            , phCompressedPageSize = Just compPageSize
+            }
+  Right (EncodedOptionalV2 hdrBytes repStream defStream valuesBs (fromIntegral uncompPageSize))
+
+
+-- | Concatenate a @V2 parts tuple@ in spec order.
+concatV2Parts :: (ByteString, ByteString, ByteString, ByteString) -> ByteString
+concatV2Parts (h, r, d, v) = BS.concat [h, r, d, v]
+
+
+{- | Encode a required (non-null) 'ColumnData' as a single
+@DATA_PAGE_V2@. No def/rep level streams are emitted; only the values
+segment, compressed if the caller requested it.
+-}
+encodeColumnDataPageV2 :: Compression -> ColumnData -> Either String ByteString
+encodeColumnDataPageV2 codec cd = do
+  page <- encodeRequiredV2 codec cd
+  Right (erv2Header page <> erv2Values page)
+
+
+{- | Like 'encodeColumnDataPageV2' but returns the four parts
+separately. For required columns the rep / def segments are empty
+so this is just @(pageHeader, "", "", values)@.
+-}
+encodeColumnDataPageV2Parts
+  :: Compression
+  -> ColumnData
+  -> Either String (ByteString, ByteString, ByteString, ByteString)
+encodeColumnDataPageV2Parts codec cd = do
+  page <- encodeRequiredV2 codec cd
+  Right (erv2Header page, BS.empty, BS.empty, erv2Values page)
+
+
+data EncodedRequiredV2 = EncodedRequiredV2
+  { erv2Header :: !ByteString
+  , erv2Values :: !ByteString
+  , erv2UncompressedSize :: {-# UNPACK #-} !Int
+  }
+
+
+encodeRequiredV2 :: Compression -> ColumnData -> Either String EncodedRequiredV2
+encodeRequiredV2 codec cd = do
+  plan <- planPlainPayload cd
+  let !valuesRaw = encodePlannedPlainPayload plan cd
+      !uncompValuesLen = plainPayloadSize plan
+  valuesBs <- Compress.compressPageBytes codec valuesRaw
+  compPageSize <- pageInt32 "compressed page size" (BS.length valuesBs)
+  let !nVals = plainValueCount plan
+      !hdrBytes =
+        encodePageHeader
+          PageHeader
+            { phType =
+                PtDataPageV2
+                  DataPageHeaderV2
+                    { dph2NumValues = nVals
+                    , dph2NumNulls = 0
+                    , dph2NumRows = nVals
+                    , dph2Encoding = 0
+                    , dph2DefLevelsLen = 0
+                    , dph2RepLevelsLen = 0
+                    , dph2IsCompressed = codec /= Uncompressed
+                    }
+            , phUncompressedPageSize = Just (fromIntegral uncompValuesLen)
+            , phCompressedPageSize = Just compPageSize
+            }
+  Right (EncodedRequiredV2 hdrBytes valuesBs uncompValuesLen)
+
+
+-- ============================================================
+-- Page / column statistics
+-- ============================================================
+
+{- | Compute Parquet 'Statistics' for an @INT32@ column.
+
+Encodes @min_value@ / @max_value@ as little-endian @INT32@ per the
+spec (PLAIN encoding for variable-length types is the same except
+for byte arrays).  Both legacy @min@/@max@ and the modern
+@min_value@/@max_value@ slots are populated.
+-}
+statisticsForInt32 :: VP.Vector Int32 -> Statistics
+statisticsForInt32 vs
+  | VP.null vs = emptyStats
+  | otherwise = go 1 first first
+  where
+    !count = VP.length vs
+    first = VP.unsafeIndex vs 0
+    go !row !mn !mx
+      | row == count = integralStatistics (i32LE mn) (i32LE mx)
+      | otherwise =
+          let !value = VP.unsafeIndex vs row
+          in go (row + 1) (min mn value) (max mx value)
+
+
+-- | Compute Parquet 'Statistics' for an @INT64@ column (LE i64 min/max).
+statisticsForInt64 :: VP.Vector Int64 -> Statistics
+statisticsForInt64 vs
+  | VP.null vs = emptyStats
+  | otherwise = go 1 first first
+  where
+    !count = VP.length vs
+    first = VP.unsafeIndex vs 0
+    go !row !mn !mx
+      | row == count = integralStatistics (i64LE mn) (i64LE mx)
+      | otherwise =
+          let !value = VP.unsafeIndex vs row
+          in go (row + 1) (min mn value) (max mx value)
+
+
+integralStatistics :: ByteString -> ByteString -> Statistics
+integralStatistics encMin encMax =
+  Statistics
+    { statMinValueExact = Just True
+    , statMaxValueExact = Just True
+    , statNanCount = Nothing
+    , statMin = Just encMin
+    , statMax = Just encMax
+    , statNullCount = Just 0
+    , statDistinctCount = Nothing
+    , statMinValue = Just encMin
+    , statMaxValue = Just encMax
+    }
+
+
+{- | Compute Parquet 'Statistics' for a @BYTE_ARRAY@ column. Values are
+compared lexicographically (unsigned byte-by-byte).  The min/max
+bytes are stored without their PLAIN length prefix per the spec.
+-}
+statisticsForByteArray :: V.Vector ByteString -> Statistics
+statisticsForByteArray vs
+  | V.null vs = emptyStats
+  | BS.length first > 8 = general 1 first first
+  | otherwise = runST $ withByteDictionarySource vs $ do
+      key <- unsafeIOToST (shortStatisticsKeyIO first)
+      short 1 0 0 key key (BS.length first) (BS.length first)
+  where
+    !count = V.length vs
+    first = V.unsafeIndex vs 0
+    general !row !mn !mx
+      | row == count = byteStatistics mn mx
+      | otherwise =
+          let !value = V.unsafeIndex vs row
+          in if value < mn
+               then general (row + 1) value mx
+               else general (row + 1) mn (if value > mx then value else mx)
+    short !row !minRow !maxRow !minKey !maxKey !minLength !maxLength
+      | row == count = do
+          let !mn = V.unsafeIndex vs minRow
+              !mx = V.unsafeIndex vs maxRow
+          pure $! byteStatistics mn mx
+      | otherwise = do
+          let !value = V.unsafeIndex vs row
+              !size = BS.length value
+          if size > 8
+            then pure $! general row (V.unsafeIndex vs minRow) (V.unsafeIndex vs maxRow)
+            else do
+              key <- unsafeIOToST (shortStatisticsKeyIO value)
+              if key < minKey || (key == minKey && size < minLength)
+                then short (row + 1) row maxRow key maxKey size maxLength
+                else
+                  if key > maxKey || (key == maxKey && size > maxLength)
+                    then short (row + 1) minRow row minKey key minLength size
+                    else short (row + 1) minRow maxRow minKey maxKey minLength maxLength
+
+
+-- The caller proves length <=8 and keeps the entire source column alive.
+-- Big-endian, zero-padded keys have unsigned byte order; equal keys need
+-- the lengths as well to distinguish a prefix from trailing NUL bytes.
+shortStatisticsKeyIO :: ByteString -> IO Word64
+shortStatisticsKeyIO bytes = do
+  let (fp, offset, size) = BSI.toForeignPtr bytes
+      ptr = unsafeForeignPtrToPtr fp `plusPtr` offset
+  key <- dictionaryReadShort ptr size
+  pure (byteSwap64 key)
+{-# INLINE shortStatisticsKeyIO #-}
+
+
+byteStatistics :: ByteString -> ByteString -> Statistics
+byteStatistics !mn !mx =
+  Statistics
+    { statMinValueExact = Just True
+    , statMaxValueExact = Just True
+    , statNanCount = Nothing
+    , statMin = Nothing
+    , statMax = Nothing
+    , statNullCount = Just 0
+    , statDistinctCount = Nothing
+    , statMinValue = Just mn
+    , statMaxValue = Just mx
+    }
+
+
+emptyStats :: Statistics
+emptyStats = Statistics Nothing Nothing (Just 0) Nothing Nothing Nothing Nothing Nothing Nothing
+
+
+-- Demand scalar bounds in all four numeric encoders. Otherwise GHC can
+-- carry a boxed maximum through the statistics loop and allocate on updates.
+i32LE :: Int32 -> ByteString
+i32LE !v = BL.toStrict (B.toLazyByteString (B.int32LE v))
+
+
+i64LE :: Int64 -> ByteString
+i64LE !v = BL.toStrict (B.toLazyByteString (B.int64LE v))
+
+
+{- | Float statistics use TYPE_ORDER: omit NaNs from bounds, count them,
+and canonicalize zero bounds to -0/+0. This also handles all-NaN pages.
+-}
+statisticsForFloat :: VP.Vector Float -> Statistics
+statisticsForFloat = floatingStatistics fLE
+
+
+statisticsForDouble :: VP.Vector Double -> Statistics
+statisticsForDouble = floatingStatistics dLE
+
+
+floatingStatistics :: (VP.Prim a, RealFloat a) => (a -> ByteString) -> VP.Vector a -> Statistics
+floatingStatistics encode values = seek 0 0
+  where
+    !count = VP.length values
+    -- IEEE self-inequality tests NaN without a per-value C call. The
+    -- specialized Core keeps the bounds, counter and offset unboxed.
+    seek !i !nans
+      | i == count = emptyStats {statNanCount = Just nans}
+      | otherwise =
+          let !value = VP.unsafeIndex values i
+          in if value /= value
+               then seek (i + 1) (nans + 1)
+               else bounds (i + 1) nans value value
+    bounds !i !nans !lo !hi
+      | i == count =
+          let !encodedMin = encode (if lo == 0 then negate 0 else lo)
+              !encodedMax = encode (if hi == 0 then 0 else hi)
+          in Statistics
+               (Just encodedMin)
+               (Just encodedMax)
+               (Just 0)
+               Nothing
+               (Just encodedMin)
+               (Just encodedMax)
+               (Just nans)
+               (Just True)
+               (Just True)
+      | otherwise =
+          let !value = VP.unsafeIndex values i
+          in if value /= value
+               then bounds (i + 1) (nans + 1) lo hi
+               else bounds (i + 1) nans (min lo value) (max hi value)
+{-# INLINE floatingStatistics #-}
+
+
+{- | Compute Parquet 'Statistics' for a @BOOLEAN@ column. Min is the
+first @False@ that appears (otherwise @True@); max is the first @True@.
+Encoded as a single byte (0 or 1) per the PLAIN spec.
+-}
+statisticsForBool :: V.Vector Bool -> Statistics
+statisticsForBool vs
+  | V.null vs = emptyStats
+  | otherwise =
+      let hasFalse = V.any not vs
+          hasTrue = V.any id vs
+          encMin = if hasFalse then BS.singleton 0 else BS.singleton 1
+          encMax = if hasTrue then BS.singleton 1 else BS.singleton 0
+      in Statistics
+           (Just encMin)
+           (Just encMax)
+           (Just 0)
+           Nothing
+           (Just encMin)
+           (Just encMax)
+           Nothing
+           (Just True)
+           (Just True)
+
+
+fLE :: Float -> ByteString
+fLE !v = BL.toStrict (B.toLazyByteString (B.word32LE (castFloatToWord32 v)))
+
+
+dLE :: Double -> ByteString
+dLE !v = BL.toStrict (B.toLazyByteString (B.word64LE (castDoubleToWord64 v)))
+
+
+-- ============================================================
+-- Heterogeneous column data
+-- ============================================================
+
+{- | A single column's worth of values, tagged with its physical type.
+Used by 'buildParquetFileTyped' / 'buildParquetFileTypedWithIndex' so
+writers can emit any primitive type from one entry point.
+-}
+data ColumnData
+  = ColInt32 !(VP.Vector Int32)
+  | ColInt64 !(VP.Vector Int64)
+  | ColFloat !(VP.Vector Float)
+  | ColDouble !(VP.Vector Double)
+  | ColBool !(V.Vector Bool)
+  | ColByteArray !(V.Vector ByteString)
+  deriving (Show, Eq)
+
+
+-- | Number of values in the column.
+columnDataLength :: ColumnData -> Int
+columnDataLength = \case
+  ColInt32 v -> VP.length v
+  ColInt64 v -> VP.length v
+  ColFloat v -> VP.length v
+  ColDouble v -> VP.length v
+  ColBool v -> V.length v
+  ColByteArray v -> V.length v
+
+
+-- | The Parquet physical type the column data should be written as.
+columnDataParquetType :: ColumnData -> ParquetType
+columnDataParquetType = \case
+  ColInt32 {} -> PTInt32
+  ColInt64 {} -> PTInt64
+  ColFloat {} -> PTFloat
+  ColDouble {} -> PTDouble
+  ColBool {} -> PTBoolean
+  ColByteArray {} -> PTByteArray
+
+
+-- | Encode the column as a single uncompressed @PLAIN@ @DATA_PAGE@.
+encodeColumnDataPage :: ColumnData -> ByteString
+encodeColumnDataPage cd =
+  let (h, b) = encodeColumnDataPageParts cd in BS.append h b
+
+
+{- | Encode a column data page as @(headerBytes, bodyBytes)@. Same
+contents as 'encodeColumnDataPage' but split so callers (in
+particular 'encryptPageBytes') can encrypt the two parts under
+different module-type AADs.
+-}
+encodeColumnDataPageParts :: ColumnData -> (ByteString, ByteString)
+encodeColumnDataPageParts = either error id . encodeColumnDataPagePartsChecked
+
+
+encodeColumnDataPagePartsChecked :: ColumnData -> Either String (ByteString, ByteString)
+encodeColumnDataPagePartsChecked cd = do
+  plan <- planPlainPayload cd
+  let !body = encodePlannedPlainPayload plan cd
+      !hdr = encodePageHeader (mkPlainDataPageHeader (plainValueCount plan) (fromIntegral (plainPayloadSize plan)))
+  Right (hdr, body)
+
+
+-- | Compute Parquet 'Statistics' for the column.
+columnDataStatistics :: ColumnData -> Statistics
+columnDataStatistics = \case
+  ColInt32 v -> statisticsForInt32 v
+  ColInt64 v -> statisticsForInt64 v
+  ColFloat v -> statisticsForFloat v
+  ColDouble v -> statisticsForDouble v
+  ColBool v -> statisticsForBool v
+  ColByteArray v -> statisticsForByteArray v
+
+
+-- Unsigned logical integers share signed physical storage. Comparing that
+-- storage as Int32/Int64 gives false bounds at the signed boundary, allowing
+-- an external engine to incorrectly skip matching row groups.
+columnStatisticsForSchema :: SchemaElement -> ColumnData -> Statistics
+columnStatisticsForSchema leaf col
+  | not (hasDefinedStatisticsOrder leaf) = emptyStats
+  | isDecimal
+  , ColByteArray values <- col =
+      if V.null values
+        then emptyStats
+        else
+          let low = V.foldl1' (\a b -> if compareDecimalBytes a b == GT then b else a) values
+              high = V.foldl1' (\a b -> if compareDecimalBytes a b == LT then b else a) values
+          in Statistics Nothing Nothing (Just 0) Nothing (Just low) (Just high) Nothing (Just True) (Just True)
+  | isUnsigned = case col of
+      ColInt32 xs
+        | not (VP.null xs) ->
+            unsignedStats (i32LE (VP.foldl1' min32 xs)) (i32LE (VP.foldl1' max32 xs))
+      ColInt64 xs
+        | not (VP.null xs) ->
+            unsignedStats (i64LE (VP.foldl1' min64 xs)) (i64LE (VP.foldl1' max64 xs))
+      _ -> columnDataStatistics col
+  | otherwise = columnDataStatistics col
+  where
+    isDecimal = case seLogicalType leaf of
+      Just LTDecimal {} -> True
+      _ -> seConvertedType leaf == Just CTDecimal
+    isUnsigned = case seLogicalType leaf of
+      Just (LTInteger _ signed) -> not signed
+      _ -> maybe False (`elem` [CTUInt8, CTUInt16, CTUInt32, CTUInt64]) (seConvertedType leaf)
+    min32 a b = if (fromIntegral a :: Word32) <= fromIntegral b then a else b
+    max32 a b = if (fromIntegral a :: Word32) >= fromIntegral b then a else b
+    min64 a b = if (fromIntegral a :: Word64) <= fromIntegral b then a else b
+    max64 a b = if (fromIntegral a :: Word64) >= fromIntegral b then a else b
+    -- The deprecated bounds use signed ordering and must stay absent.
+    unsignedStats lo hi = Statistics Nothing Nothing (Just 0) Nothing (Just lo) (Just hi) Nothing (Just True) (Just True)
+
+
+validateLogicalColumn :: SchemaElement -> ColumnData -> Either String ()
+validateLogicalColumn leaf column
+  | not (hasCompatiblePhysicalType leaf) = Left "Parquet.Write: logical annotation has incompatible physical storage"
+  | otherwise = case seLogicalType leaf of
+      Just LTNull
+        | columnDataLength column == 0 -> Right ()
+        | otherwise -> Left "Parquet.Write: NULL logical type requires every value to be null"
+      Just (LTDecimal precision scale)
+        | precision < 1 || scale < 0 || scale > precision -> Left "Parquet.Write: invalid DECIMAL precision/scale"
+        | otherwise -> case column of
+            ColInt32 values
+              | precision <= 9 ->
+                  let !bound = fromInteger (10 ^ precision - 1) :: Int64
+                  in require
+                       ( VP.all
+                           ( \value ->
+                               let n = fromIntegral value :: Int64
+                               in n >= negate bound && n <= bound
+                           )
+                           values
+                       )
+            ColInt64 values
+              | precision <= 18 ->
+                  let !bound = fromInteger (10 ^ precision - 1) :: Int64
+                  in require (VP.all (\value -> value >= negate bound && value <= bound) values)
+            ColByteArray values ->
+              let width = V.foldl' (\n value -> max n (BS.length value)) 0 values
+                  -- At most 3 decimal digits per stored byte; avoid constructing
+                  -- an enormous power for a permissive precision on tiny values.
+                  boundNeeded = toInteger precision < 3 * toInteger width
+                  high = encodeDecimalInteger (10 ^ precision - 1)
+                  low = encodeDecimalInteger (negate (10 ^ precision - 1))
+                  valid value =
+                    not (BS.null value)
+                      && ( not boundNeeded
+                             || (compareDecimalBytes low value /= GT && compareDecimalBytes value high /= GT)
+                         )
+              in require (V.all valid values)
+            _ -> Left "Parquet.Write: invalid physical storage or precision for DECIMAL"
+      _
+        | seConvertedType leaf == Just CTDecimal -> Left "Parquet.Write: DECIMAL requires precision/scale in LogicalType"
+        | otherwise -> Right ()
+  where
+    require True = Right ()
+    require False = Left "Parquet.Write: DECIMAL value exceeds precision or has empty storage"
+
+
+-- ============================================================
+-- Nullable columns: definition levels + PLAIN values
+-- ============================================================
+
+{- | A column with optional values. Internally we store the present-flag
+vector alongside the present-only values; readers reconstruct the
+@Maybe@ shape via 'Parquet.Levels.materializePlainInt32Optional' and
+friends.
+-}
+data OptionalColumn
+  = OptInt32 !(V.Vector (Maybe Int32))
+  | OptInt64 !(V.Vector (Maybe Int64))
+  | OptFloat !(V.Vector (Maybe Float))
+  | OptDouble !(V.Vector (Maybe Double))
+  | OptBool !(V.Vector (Maybe Bool))
+  | OptByteArray !(V.Vector (Maybe ByteString))
+  deriving (Show, Eq)
+
+
+optionalColumnLength :: OptionalColumn -> Int
+optionalColumnLength = \case
+  OptInt32 v -> V.length v
+  OptInt64 v -> V.length v
+  OptFloat v -> V.length v
+  OptDouble v -> V.length v
+  OptBool v -> V.length v
+  OptByteArray v -> V.length v
+
+
+optionalColumnNullCount :: OptionalColumn -> Int
+optionalColumnNullCount = \case
+  OptInt32 v -> count v
+  OptInt64 v -> count v
+  OptFloat v -> count v
+  OptDouble v -> count v
+  OptBool v -> count v
+  OptByteArray v -> count v
+  where
+    count = V.foldl' (\n -> maybe (n + 1) (const n)) 0
+
+
+-- | Strip nulls and return only the present values as a 'ColumnData'.
+optionalColumnPresentValues :: OptionalColumn -> ColumnData
+optionalColumnPresentValues = \case
+  OptInt32 v -> ColInt32 (V.convert (V.mapMaybe id v))
+  OptInt64 v -> ColInt64 (V.convert (V.mapMaybe id v))
+  OptFloat v -> ColFloat (V.convert (V.mapMaybe id v))
+  OptDouble v -> ColDouble (V.convert (V.mapMaybe id v))
+  OptBool v -> ColBool (V.mapMaybe id v)
+  OptByteArray v -> ColByteArray (V.mapMaybe id v)
+
+
+optionalDefinitionLevels :: OptionalColumn -> VP.Vector Int32
+optionalDefinitionLevels = \case
+  OptInt32 v -> levels v
+  OptInt64 v -> levels v
+  OptFloat v -> levels v
+  OptDouble v -> levels v
+  OptBool v -> levels v
+  OptByteArray v -> levels v
+  where
+    levels values =
+      VP.generate
+        (V.length values)
+        (\i -> maybe 0 (const 1) (V.unsafeIndex values i))
+
+
+{- | Encode an 'OptionalColumn' as a single uncompressed @PLAIN@
+@DATA_PAGE@ V1 carrying the definition-level stream + present-only
+PLAIN values.
+-}
+encodeOptionalColumnPage :: OptionalColumn -> ByteString
+encodeOptionalColumnPage = either error id . encodeOptionalColumnPageChecked
+
+
+encodeOptionalColumnPageChecked :: OptionalColumn -> Either String ByteString
+encodeOptionalColumnPageChecked oc = encodeOptionalPagePrepared oc (optionalColumnPresentValues oc)
+
+
+encodeOptionalPagePrepared :: OptionalColumn -> ColumnData -> Either String ByteString
+encodeOptionalPagePrepared oc present = do
+  n <- pageInt32 "value count" (optionalColumnLength oc)
+  valuePlan <- planPlainPayload present
+  defPlan <- LE.planRLEHybrid 1 1 (optionalDefinitionLevels oc)
+  -- Include the V1 level-length prefix before allocating either segment.
+  bodySize <- pageSizeWithOverhead (LE.hybridEncodedSize defPlan + 4) (plainPayloadSize valuePlan)
+  let !defs = LE.encodeHybridPlan defPlan
+      !prefix = Direct.directEncode 4 (\ptr offset -> let size = fromIntegral (LE.hybridEncodedSize defPlan) in Direct.dWord32LE ptr offset (case targetByteOrder of LittleEndian -> size; BigEndian -> byteSwap32 size))
+      !valuesBs = encodePlannedPlainPayload valuePlan present
+      !hdr = mkPlainDataPageHeader n bodySize
+  Right (BS.concat [encodePageHeader hdr, prefix, defs, valuesBs])
+
+
+{- | Encode just the PLAIN-values portion (no page header). Used inside
+'encodeOptionalColumnPage' so we can prepend the definition-level
+stream and write a single page header.
+-}
+encodeColumnDataPagePayload :: ColumnData -> ByteString
+encodeColumnDataPagePayload cd = either error (\plan -> encodePlannedPlainPayload plan cd) (planPlainPayload cd)
+
+
+-- Counts and page sizes are signed i32 fields in parquet.thrift. Validate
+-- their complete PLAIN payload before allocating or narrowing anything.
+data PlainPayloadPlan = PlainPayloadPlan
+  { plainValueCount :: {-# UNPACK #-} !Int32
+  , plainPayloadSize :: {-# UNPACK #-} !Int
+  }
+
+
+pageInt32 :: String -> Int -> Either String Int32
+pageInt32 label value
+  | value < 0 || toInteger value > toInteger (maxBound :: Int32) =
+      Left ("Parquet.Write: " ++ label ++ " exceeds signed 32-bit limit")
+  | otherwise = Right (fromIntegral value)
+
+
+pageSizeWithOverhead :: Int -> Int -> Either String Int32
+pageSizeWithOverhead overhead payload
+  | overhead < 0 || payload < 0 || toInteger overhead + toInteger payload > toInteger (maxBound :: Int32) =
+      Left "Parquet.Write: page payload exceeds signed 32-bit limit"
+  | otherwise = Right (fromIntegral (overhead + payload))
+
+
+planPlainPayload :: ColumnData -> Either String PlainPayloadPlan
+planPlainPayload cd = do
+  count <- pageInt32 "value count" (columnDataLength cd)
+  size <- case cd of
+    ColInt32 v -> fixed 4 (VP.length v)
+    ColInt64 v -> fixed 8 (VP.length v)
+    ColFloat v -> fixed 4 (VP.length v)
+    ColDouble v -> fixed 8 (VP.length v)
+    ColBool v ->
+      let (bytes, tailBits) = quotRem (V.length v) 8
+      in Right (bytes + if tailBits == 0 then 0 else 1)
+    ColByteArray v
+      | V.length v > limit `quot` 4 -> tooLarge
+      | otherwise ->
+          let go !row !total
+                | row == V.length v = Right total
+                | total > limit - 4 = tooLarge
+                | otherwise =
+                    let !size = BS.length (V.unsafeIndex v row)
+                    in if size > limit - total - 4
+                         then tooLarge
+                         else go (row + 1) (total + 4 + size)
+          in go 0 0
+  Right (PlainPayloadPlan count size)
+  where
+    limit = fromIntegral (maxBound :: Int32)
+    tooLarge = Left "Parquet.Write: PLAIN page payload exceeds signed 32-bit limit"
+    fixed width count
+      | count > limit `quot` width = tooLarge
+      | otherwise = Right (count * width)
+
+
+encodePlannedPlainPayload :: PlainPayloadPlan -> ColumnData -> ByteString
+encodePlannedPlainPayload plan = \case
+  ColInt32 v ->
+    fixedPayload
+      (plainPayloadSize plan)
+      4
+      ( \xs ->
+          BL.toStrict $
+            B.toLazyByteString $
+              VP.foldl' (\b x -> b <> B.int32LE x) mempty xs
+      )
+      v
+  ColInt64 v ->
+    fixedPayload
+      (plainPayloadSize plan)
+      8
+      ( \xs ->
+          BL.toStrict $
+            B.toLazyByteString $
+              VP.foldl' (\b x -> b <> B.int64LE x) mempty xs
+      )
+      v
+  ColFloat v ->
+    fixedPayload
+      (plainPayloadSize plan)
+      4
+      ( \xs ->
+          BL.toStrict $
+            B.toLazyByteString $
+              VP.foldl' (\b x -> b <> writeFloatLE x) mempty xs
+      )
+      v
+  ColDouble v ->
+    fixedPayload
+      (plainPayloadSize plan)
+      8
+      ( \xs ->
+          BL.toStrict $
+            B.toLazyByteString $
+              VP.foldl' (\b x -> b <> writeDoubleLE x) mempty xs
+      )
+      v
+  ColBool v ->
+    let !n = V.length v
+        !numBytes = plainPayloadSize plan
+    in Direct.directEncode numBytes $ \ptr ->
+         let go !byteIdx !offset
+               | byteIdx == numBytes = pure offset
+               | otherwise = do
+                   let goBit !bit !acc
+                         | bit == 8 || byteIdx * 8 + bit == n = acc
+                         | otherwise =
+                             goBit
+                               (bit + 1)
+                               (if V.unsafeIndex v (byteIdx * 8 + bit) then setBit acc bit else acc)
+                   next <- Direct.dWord8 ptr offset (goBit 0 0)
+                   go (byteIdx + 1) next
+         in go 0
+  ColByteArray v | targetByteOrder == LittleEndian ->
+    Direct.directEncode (plainPayloadSize plan) $ \ptr ->
+      let go !i !offset
+            | i == V.length v = pure offset
+            | otherwise = do
+                let !bytes = V.unsafeIndex v i
+                payload <- Direct.dWord32LE ptr offset (fromIntegral (BS.length bytes))
+                next <- Direct.dBytes ptr payload bytes
+                go (i + 1) next
+      in go 0
+  ColByteArray v ->
+    BL.toStrict $
+      B.toLazyByteString $
+        V.foldl'
+          ( \b x ->
+              b
+                <> B.word32LE (fromIntegral (BS.length x))
+                <> B.byteString x
+          )
+          mempty
+          v
+
+
+-- On little-endian hosts the primitive vector is already PLAIN-encoded.
+-- Copy its logical slice once; retain the portable builder on big-endian
+-- hosts rather than writing native-endian bytes into a little-endian file.
+fixedPayload :: Int -> Int -> (VP.Vector a -> ByteString) -> VP.Vector a -> ByteString
+fixedPayload size width fallback values@(VP.Vector offset _ bytes)
+  | targetByteOrder /= LittleEndian = fallback values
+  | otherwise = Direct.directEncode size $ \ptr _ -> do
+      copyByteArrayToAddr ptr bytes (offset * width) size
+      pure size
+{-# INLINE fixedPayload #-}
+
+
+-- ============================================================
+-- Dictionary encoding (PLAIN_DICTIONARY / RLE_DICTIONARY)
+-- ============================================================
+
+{- | A computed dictionary for a single column chunk. 'dictUniques' holds
+the column values in dictionary order; 'dictIndices' maps each row's
+value to its dictionary index (0-based).
+-}
+data Dictionary = Dictionary
+  { dictUniques :: !ColumnData
+  , dictIndices :: !(VP.Vector Int32)
+  }
+  deriving (Show, Eq)
+
+
+{- | Compute a dictionary for a 'ColumnData' by deduplicating the input.
+Order of unique values follows their first appearance.
+-}
+buildDictionary :: ColumnData -> Dictionary
+buildDictionary = \case
+  ColInt32 values -> buildScalarDictionary ColInt32 fromIntegral values
+  ColInt64 values -> buildScalarDictionary ColInt64 fromIntegral values
+  -- Preserve IEEE wire bits, including signed zeros and NaN payloads.
+  ColFloat values -> buildScalarDictionary (ColFloat . VP.unsafeCast) fromIntegral (VP.unsafeCast values :: VP.Vector Word32)
+  ColDouble values -> buildScalarDictionary (ColDouble . VP.unsafeCast) id (VP.unsafeCast values :: VP.Vector Word64)
+  ColBool values ->
+    buildDictionaryFromIndices
+      True
+      (V.length values)
+      (\i -> pure (if V.unsafeIndex values i then 1 else 0))
+      (\i j -> V.unsafeIndex values i == V.unsafeIndex values j)
+      (ColBool . gatherDictionaryValues values)
+  ColByteArray values -> buildByteDictionary values
+
+
+-- Exact scalar keys double as the returned dictionary. Freezing the native
+-- values avoids a representative-row array and a second gather/copy.
+buildScalarDictionary :: (Prim a, Eq a) => (VP.Vector a -> ColumnData) -> (a -> Word64) -> VP.Vector a -> Dictionary
+buildScalarDictionary makeColumn toHash values
+  | count == 0 = Dictionary (makeColumn VP.empty) VP.empty
+  | count > maxBound `quot` 4 = error "Parquet.Write: dictionary indices exceed addressable size"
+  | otherwise = runST $ do
+      indices <- MVP.unsafeNew count
+      keys <- MVP.unsafeNew (min count 32)
+      table <- MVP.replicate 64 (-1 :: Int32)
+      let go !row !distinct !uniqueKeys !slots
+            | row == count = do
+                uniques <- VP.unsafeFreeze (MVP.unsafeSlice 0 distinct uniqueKeys)
+                rowIndices <- VP.unsafeFreeze indices
+                pure (Dictionary (makeColumn uniques) rowIndices)
+            | otherwise =
+                let !value = VP.unsafeIndex values row
+                in probe value (fromIntegral (dictionaryHashWord64 (toHash value)) .&. mask)
+            where
+              !mask = MVP.length slots - 1
+              probe !value !bucket = do
+                entry <- MVP.unsafeRead slots bucket
+                if entry < 0
+                  then case dictionaryCapacityReached distinct (MVP.length uniqueKeys) of
+                    1# -> grow
+                    _ -> do
+                      case dictionaryEntriesExceeded distinct of
+                        1# -> error "Parquet.Write: too many dictionary entries"
+                        _ -> pure ()
+                      let !entryId = fromIntegral distinct
+                      MVP.unsafeWrite uniqueKeys distinct value
+                      MVP.unsafeWrite slots bucket entryId
+                      MVP.unsafeWrite indices row entryId
+                      go (row + 1) (distinct + 1) uniqueKeys slots
+                  else do
+                    cached <- MVP.unsafeRead uniqueKeys (fromIntegral entry)
+                    if cached == value
+                      then do
+                        MVP.unsafeWrite indices row entry
+                        go (row + 1) distinct uniqueKeys slots
+                      else probe value ((bucket + 1) .&. mask)
+              grow
+                | 1# <- dictionaryTableSizeExceeded (MVP.length slots) = error "Parquet.Write: dictionary exceeds addressable size"
+                | otherwise = do
+                    let !capacity = MVP.length uniqueKeys
+                        !extra = min capacity (count - capacity)
+                    expandedKeys <- MVP.unsafeGrow uniqueKeys extra
+                    expandedTable <- MVP.replicate (MVP.length slots * 2) (-1 :: Int32)
+                    let !newMask = MVP.length expandedTable - 1
+                        rehash !entry
+                          | entry == distinct = go row distinct expandedKeys expandedTable
+                          | otherwise = do
+                              key <- MVP.unsafeRead expandedKeys entry
+                              let insert !bucket = do
+                                    old <- MVP.unsafeRead expandedTable bucket
+                                    if old < 0
+                                      then MVP.unsafeWrite expandedTable bucket (fromIntegral entry) >> rehash (entry + 1)
+                                      else insert ((bucket + 1) .&. newMask)
+                              insert (fromIntegral (dictionaryHashWord64 (toHash key)) .&. newMask)
+                    rehash 0
+      go 0 0 keys table
+  where
+    !count = VP.length values
+{-# INLINE buildScalarDictionary #-}
+
+
+data ByteKeyShape = GeneralByteKeys | TaggedByteKeys | EightByteKeys | MixedShortByteKeys
+
+
+-- A small-key column can use exact primitive keys. The scan examines only
+-- lengths and exits at the first larger value, so normal binary columns
+-- incur constant dispatch cost. Tags make all zero-padded <=7-byte values
+-- injective; an all-eight-byte column needs no length tag or equality read.
+classifyByteKeys :: V.Vector ByteString -> ByteKeyShape
+classifyByteKeys values = go 0 8 0
+  where
+    go !i !minimumSize !maximumSize
+      | i == V.length values =
+          if maximumSize < 8 then TaggedByteKeys else if minimumSize == 8 then EightByteKeys else MixedShortByteKeys
+      | otherwise =
+          let !size = BS.length (V.unsafeIndex values i)
+          in if size > 8 then GeneralByteKeys else go (i + 1) (min minimumSize size) (max maximumSize size)
+{-# INLINE classifyByteKeys #-}
+
+
+buildByteDictionary :: V.Vector ByteString -> Dictionary
+buildByteDictionary values
+  | V.length values > maxBound `quot` 4 = error "Parquet.Write: dictionary indices exceed addressable size"
+  | otherwise = case classifyByteKeys values of
+      TaggedByteKeys -> buildSmallByteDictionary True True values
+      EightByteKeys -> buildSmallByteDictionary True False values
+      MixedShortByteKeys -> buildSmallByteDictionary False False values
+      GeneralByteKeys ->
+        if preferPointerByteDictionary values
+          then internByteDictionary values
+          else case internLargeByteDictionary values of
+            DictionaryBuild rows indices -> Dictionary (ColByteArray (gatherDictionaryValues values rows)) indices
+
+
+-- This is a bounded performance hint, never a size invariant: either
+-- scanner handles every byte-string length, including later wider values.
+-- Avoid an extra full-column pass just to choose the scratch layout.
+preferPointerByteDictionary :: V.Vector ByteString -> Bool
+preferPointerByteDictionary values = go 0
+  where
+    !limit = min 32 (V.length values)
+    go !row
+      | row == limit = True
+      | BS.length (V.unsafeIndex values row) > 128 = False
+      | otherwise = go (row + 1)
+{-# INLINE preferPointerByteDictionary #-}
+
+
+buildSmallByteDictionary :: Bool -> Bool -> V.Vector ByteString -> Dictionary
+buildSmallByteDictionary exactKeys tagged values =
+  buildDictionaryFromIndices
+    exactKeys
+    (V.length values)
+    (\i -> unsafeIOToST (dictionarySmallKeyIO tagged (V.unsafeIndex values i)))
+    (\i j -> BS.length (V.unsafeIndex values i) == BS.length (V.unsafeIndex values j))
+    (ColByteArray . gatherDictionaryValues values)
+{-# INLINE buildSmallByteDictionary #-}
+
+
+-- Called only after the length scan proved that every input is <=8 bytes.
+dictionarySmallKeyIO :: Bool -> ByteString -> IO Word64
+dictionarySmallKeyIO tagged bytes
+  | BS.null bytes = pure 0
+  | otherwise = do
+      let (fp, offset, size) = BSI.toForeignPtr bytes
+          ptr = unsafeForeignPtrToPtr fp `plusPtr` offset
+      key <- dictionaryReadShort ptr size
+      touchForeignPtr fp
+      pure (if tagged then key .|. (fromIntegral size `shiftL` 56) else key)
+{-# INLINE dictionarySmallKeyIO #-}
+
+
+-- Force each selected reference before storing it. A lazy boxed generate
+-- would retain indexing closures over the entire input, including rows
+-- that the dictionary no longer needs, and defer construction work.
+gatherDictionaryValues :: V.Vector a -> VP.Vector Int -> V.Vector a
+gatherDictionaryValues values rows = V.create $ do
+  output <- MV.unsafeNew (VP.length rows)
+  let go !i
+        | i == VP.length rows = pure output
+        | otherwise = do
+            let !value = V.unsafeIndex values (VP.unsafeIndex rows i)
+            MV.unsafeWrite output i value
+            go (i + 1)
+  go 0
+{-# INLINE gatherDictionaryValues #-}
+
+
+-- The table stores dense dictionary ids, whose representative source rows
+-- live in a growable primitive vector. This avoids boxing/hash-map nodes
+-- on every row and never duplicates byte-array payloads. The scratch buffers grow
+-- only when the number of distinct values grows; the table stays <= 50%
+-- full, including during rehashing. Inlining specialises the key,
+-- equality and collision callbacks.
+data DictionaryBuild = DictionaryBuild
+  { dictionarySourceRows :: !(VP.Vector Int)
+  , dictionaryRowIndices :: !(VP.Vector Int32)
+  }
+
+
+-- Scalar keys contain every input bit, so they need no second equality
+-- check. Variable-length byte keys additionally check length/content.
+buildDictionaryFromIndices :: Bool -> Int -> (forall s. Int -> ST s Word64) -> (Int -> Int -> Bool) -> (VP.Vector Int -> ColumnData) -> Dictionary
+buildDictionaryFromIndices exactKeys count keyAt same makeColumn =
+  case internDictionary exactKeys count keyAt same of
+    DictionaryBuild rows indices -> Dictionary (makeColumn rows) indices
+{-# INLINE buildDictionaryFromIndices #-}
+
+
+internDictionary :: Bool -> Int -> (forall s. Int -> ST s Word64) -> (Int -> Int -> Bool) -> DictionaryBuild
+internDictionary _ 0 _ _ = DictionaryBuild VP.empty VP.empty
+internDictionary exactKeys count keyAt same
+  | count > maxBound `quot` 4 = error "Parquet.Write: dictionary indices exceed addressable size"
+  | otherwise = runST $ do
+      indices <- MVP.unsafeNew count
+      sourceRows <- MVP.unsafeNew (min count 32)
+      cachedKeys <- MVP.unsafeNew (min count 32)
+      slots <- MVP.replicate 64 (-1 :: Int32)
+      scanDictionary exactKeys count keyAt same continueDictionaryCollision indices 0 0 sourceRows cachedKeys slots
+{-# INLINE internDictionary #-}
+
+
+-- Ambiguous sampled keys transfer the existing buffers to a refined scan,
+-- then to full keys if necessary. Full-key/scalar scans inline an identity handler,
+-- so their row loops carry no adaptive-mode argument or branch.
+-- Arguments are the current row, representative row, unique count,
+-- source-row array, cached keys, slots, and ordinary probe continuation.
+type DictionaryCollision s = Int -> Int -> Int -> MVP.MVector s Int -> MVP.MVector s Word64 -> MVP.MVector s Int32 -> ST s DictionaryBuild -> ST s DictionaryBuild
+
+
+continueDictionaryCollision :: DictionaryCollision s
+continueDictionaryCollision _ _ _ _ _ _ continue = continue
+{-# INLINE continueDictionaryCollision #-}
+
+
+-- Large payloads retain the compact source-row representation; its lower
+-- allocation and lookup cost wins when byte comparison dominates.
+type LargeDictionaryScan s = Int -> Int -> MVP.MVector s Int -> MVP.MVector s Word64 -> MVP.MVector s Int32 -> ST s DictionaryBuild
+
+
+sameLargeByteRows :: V.Vector ByteString -> Int -> Int -> Bool
+sameLargeByteRows values i j =
+  let !a = V.unsafeIndex values i
+      !b = V.unsafeIndex values j
+  in case dictionaryShortSize (BS.length a) of
+       1# -> BS.length a == BS.length b
+       _ -> a == b
+{-# INLINE sameLargeByteRows #-}
+
+
+internLargeByteDictionary :: V.Vector ByteString -> DictionaryBuild
+internLargeByteDictionary values = runST $ do
+  let count = V.length values
+      sampledKey i = unsafeIOToST (dictionaryByteKeyIO False (V.unsafeIndex values i))
+  indices <- MVP.unsafeNew count
+  sourceRows <- MVP.unsafeNew (min count 32)
+  cachedKeys <- MVP.unsafeNew (min count 32)
+  slots <- MVP.replicate 64 (-1 :: Int32)
+  scanDictionary False count sampledKey (sameLargeByteRows values) (promoteRefinedLargeDictionary values indices) indices 0 0 sourceRows cachedKeys slots
+{-# INLINE internLargeByteDictionary #-}
+
+
+scanFullLargeByteDictionary :: V.Vector ByteString -> MVP.MVector s Int32 -> LargeDictionaryScan s
+scanFullLargeByteDictionary values indices =
+  scanDictionary
+    False
+    (V.length values)
+    (\i -> unsafeIOToST (dictionaryByteKeyIO True (V.unsafeIndex values i)))
+    (sameLargeByteRows values)
+    continueDictionaryCollision
+    indices
+{-# NOINLINE scanFullLargeByteDictionary #-}
+
+
+scanRefinedLargeByteDictionary :: Int -> V.Vector ByteString -> MVP.MVector s Int32 -> LargeDictionaryScan s
+scanRefinedLargeByteDictionary !pivot values indices =
+  scanDictionary
+    False
+    (V.length values)
+    (\i -> unsafeIOToST (dictionaryRefinedKeyIO pivot (V.unsafeIndex values i)))
+    (sameLargeByteRows values)
+    (promoteFullLargeDictionary values indices)
+    indices
+{-# NOINLINE scanRefinedLargeByteDictionary #-}
+
+
+promoteRefinedLargeDictionary :: V.Vector ByteString -> MVP.MVector s Int32 -> DictionaryCollision s
+promoteRefinedLargeDictionary values indices row representative distinct rows keys table _ = do
+  pivot <- unsafeIOToST (dictionaryDifferenceOffsetIO (V.unsafeIndex values row) (V.unsafeIndex values representative))
+  if pivot < 0
+    then do
+      rekeyLargeDictionary distinct rows keys table (\i -> unsafeIOToST (dictionaryByteKeyIO True (V.unsafeIndex values i)))
+      scanFullLargeByteDictionary values indices row distinct rows keys table
+    else do
+      rekeyLargeDictionary distinct rows keys table (\i -> unsafeIOToST (dictionaryRefinedKeyIO pivot (V.unsafeIndex values i)))
+      scanRefinedLargeByteDictionary pivot values indices row distinct rows keys table
+{-# NOINLINE promoteRefinedLargeDictionary #-}
+
+
+promoteFullLargeDictionary :: V.Vector ByteString -> MVP.MVector s Int32 -> DictionaryCollision s
+promoteFullLargeDictionary values indices row _ distinct rows keys table _ = do
+  rekeyLargeDictionary distinct rows keys table (\i -> unsafeIOToST (dictionaryByteKeyIO True (V.unsafeIndex values i)))
+  scanFullLargeByteDictionary values indices row distinct rows keys table
+{-# NOINLINE promoteFullLargeDictionary #-}
+
+
+rekeyLargeDictionary :: Int -> MVP.MVector s Int -> MVP.MVector s Word64 -> MVP.MVector s Int32 -> (Int -> ST s Word64) -> ST s ()
+rekeyLargeDictionary distinct rows keys table keyAt = do
+  MVP.set table (-1)
+  let !mask = MVP.length table - 1
+      rekey !entry
+        | entry == distinct = pure ()
+        | otherwise = do
+            representative <- MVP.unsafeRead rows entry
+            key <- inline keyAt representative
+            MVP.unsafeWrite keys entry key
+            let insert !bucket = do
+                  old <- MVP.unsafeRead table bucket
+                  if old < 0
+                    then MVP.unsafeWrite table bucket (fromIntegral entry) >> rekey (entry + 1)
+                    else insert ((bucket + 1) .&. mask)
+            insert (fromIntegral (dictionaryHashWord64 key) .&. mask)
+  rekey 0
+{-# INLINE rekeyLargeDictionary #-}
+
+
+-- Each unique byte string owns the cached address in its metadata record.
+-- Metadata stores (key, length, address) in three adjacent Word64 cells;
+-- the boxed owner array stays live through every lookup and becomes the
+-- result dictionary. No source-row lookup or payload copy is needed.
+type ByteDictionaryKey s = ByteString -> Ptr Word8 -> Int -> ST s Word64
+
+
+type ByteDictionaryCollision s = Int -> Int -> Int -> MV.MVector s ByteString -> MVP.MVector s Word64 -> MVP.MVector s Int32 -> ST s Dictionary -> ST s Dictionary
+
+
+type ByteDictionaryScan s = Int -> Int -> MV.MVector s ByteString -> MVP.MVector s Word64 -> MVP.MVector s Int32 -> ST s Dictionary
+
+
+continueByteDictionaryCollision :: ByteDictionaryCollision s
+continueByteDictionaryCollision _ _ _ _ _ _ continue = continue
+{-# INLINE continueByteDictionaryCollision #-}
+
+
+-- Retain the entire owner graph once, around construction. Every cached
+-- address comes from an input value, including during growth/refinement.
+-- keepAlive# also covers exceptional exits; unlike a final touch, it
+-- cannot disappear when the optimiser proves that a branch throws.
+-- The returned dictionary owns its selected references after the scope.
+-- See https://www.haskell.org/ghc/blog/20210607-the-keepAlive-story.html.
+withByteDictionarySource :: V.Vector ByteString -> ST s a -> ST s a
+withByteDictionarySource values (ST action) = ST (\state -> keepAlive# values state action)
+{-# INLINE withByteDictionarySource #-}
+
+
+internByteDictionary :: V.Vector ByteString -> Dictionary
+internByteDictionary values = runST $ withByteDictionarySource values $ do
+  let !count = V.length values
+      !capacity = min count 32
+      keyAt value ptr size = unsafeIOToST (dictionaryByteKeyAtIO False value ptr size)
+  indices <- MVP.unsafeNew count
+  entries <- MV.unsafeNew capacity
+  metadata <- MVP.unsafeNew (capacity * 3)
+  slots <- MVP.replicate 64 (-1 :: Int32)
+  scanByteDictionary count keyAt (promoteRefinedDictionary values indices) values indices 0 0 entries metadata slots
+{-# INLINE internByteDictionary #-}
+
+
+scanFullByteDictionary :: V.Vector ByteString -> MVP.MVector s Int32 -> ByteDictionaryScan s
+scanFullByteDictionary values indices =
+  scanByteDictionary
+    (V.length values)
+    (\value ptr size -> unsafeIOToST (dictionaryByteKeyAtIO True value ptr size))
+    continueByteDictionaryCollision
+    values
+    indices
+{-# NOINLINE scanFullByteDictionary #-}
+
+
+scanRefinedByteDictionary :: Int -> V.Vector ByteString -> MVP.MVector s Int32 -> ByteDictionaryScan s
+scanRefinedByteDictionary !pivot values indices =
+  scanByteDictionary
+    (V.length values)
+    (\_ ptr size -> unsafeIOToST (dictionaryRefinedKeyAtIO pivot ptr size))
+    (promoteFullDictionary values indices)
+    values
+    indices
+{-# NOINLINE scanRefinedByteDictionary #-}
+
+
+promoteRefinedDictionary :: V.Vector ByteString -> MVP.MVector s Int32 -> ByteDictionaryCollision s
+promoteRefinedDictionary values indices row representative distinct entries metadata table _ = do
+  previous <- MV.unsafeRead entries representative
+  pivot <- unsafeIOToST (dictionaryDifferenceOffsetIO (V.unsafeIndex values row) previous)
+  if pivot < 0
+    then do
+      rekeyByteDictionary distinct entries metadata table (\value ptr size -> unsafeIOToST (dictionaryByteKeyAtIO True value ptr size))
+      scanFullByteDictionary values indices row distinct entries metadata table
+    else do
+      rekeyByteDictionary distinct entries metadata table (\_ ptr size -> unsafeIOToST (dictionaryRefinedKeyAtIO pivot ptr size))
+      scanRefinedByteDictionary pivot values indices row distinct entries metadata table
+{-# NOINLINE promoteRefinedDictionary #-}
+
+
+promoteFullDictionary :: V.Vector ByteString -> MVP.MVector s Int32 -> ByteDictionaryCollision s
+promoteFullDictionary values indices row _ distinct entries metadata table _ = do
+  rekeyByteDictionary distinct entries metadata table (\value ptr size -> unsafeIOToST (dictionaryByteKeyAtIO True value ptr size))
+  scanFullByteDictionary values indices row distinct entries metadata table
+{-# NOINLINE promoteFullDictionary #-}
+
+
+rekeyByteDictionary :: Int -> MV.MVector s ByteString -> MVP.MVector s Word64 -> MVP.MVector s Int32 -> ByteDictionaryKey s -> ST s ()
+rekeyByteDictionary distinct entries metadata table keyAt = do
+  MVP.set table (-1)
+  let !mask = MVP.length table - 1
+      rekey !entry
+        | entry == distinct = pure ()
+        | otherwise = do
+            value <- MV.unsafeRead entries entry
+            let (fp, _, _) = BSI.toForeignPtr value
+                !base = entry * 3
+            size <- MVP.unsafeRead metadata (base + 1)
+            address <- MVP.unsafeRead metadata (base + 2)
+            key <- inline keyAt value (wordPtrToPtr (fromIntegral address)) (fromIntegral size)
+            unsafeIOToST (touchForeignPtr fp)
+            MVP.unsafeWrite metadata base key
+            let insert !bucket = do
+                  old <- MVP.unsafeRead table bucket
+                  if old < 0
+                    then MVP.unsafeWrite table bucket (fromIntegral entry) >> rekey (entry + 1)
+                    else insert ((bucket + 1) .&. mask)
+            insert (fromIntegral (dictionaryHashWord64 key) .&. mask)
+  rekey 0
+{-# INLINE rekeyByteDictionary #-}
+
+
+scanByteDictionary
+  :: Int
+  -> ByteDictionaryKey s
+  -> ByteDictionaryCollision s
+  -> V.Vector ByteString
+  -> MVP.MVector s Int32
+  -> ByteDictionaryScan s
+scanByteDictionary count keyAt onCollision values indices startRow startDistinct startEntries startMetadata startTable =
+  let go !row !distinct !entries !metadata !table
+        | row == count = do
+            uniqueValues <- V.unsafeFreeze (MV.unsafeSlice 0 distinct entries)
+            rowIndices <- VP.unsafeFreeze indices
+            pure (Dictionary (ColByteArray uniqueValues) rowIndices)
+        | otherwise = do
+            let !value = V.unsafeIndex values row
+                (fp, offset, size) = BSI.toForeignPtr value
+                !ptr = unsafeForeignPtrToPtr fp `plusPtr` offset
+                !mask = MVP.length table - 1
+                emit !entry = do
+                  MVP.unsafeWrite indices row entry
+                  go (row + 1) distinct entries metadata table
+                collide !entry !key !bucket =
+                  onCollision row entry distinct entries metadata table (probe key ((bucket + 1) .&. mask))
+                probe !key !bucket = do
+                  entryId <- MVP.unsafeRead table bucket
+                  if entryId < 0
+                    then case dictionaryCapacityReached distinct (MV.length entries) of
+                      1# -> grow row distinct entries metadata table
+                      _ -> do
+                        case dictionaryEntriesExceeded distinct of
+                          1# -> error "Parquet.Write: too many dictionary entries"
+                          _ -> pure ()
+                        let !base = distinct * 3
+                            !newId = fromIntegral distinct
+                        -- Store the owner before its address. Growing copies
+                        -- these references; freezing returns the same owners.
+                        MV.unsafeWrite entries distinct value
+                        MVP.unsafeWrite metadata base key
+                        MVP.unsafeWrite metadata (base + 1) (fromIntegral size)
+                        MVP.unsafeWrite metadata (base + 2) (fromIntegral (ptrToWordPtr ptr))
+                        MVP.unsafeWrite table bucket newId
+                        MVP.unsafeWrite indices row newId
+                        go (row + 1) (distinct + 1) entries metadata table
+                    else do
+                      let !entry = fromIntegral entryId
+                          !base = entry * 3
+                      cachedKey <- MVP.unsafeRead metadata base
+                      if cachedKey /= key
+                        then probe key ((bucket + 1) .&. mask)
+                        else do
+                          cachedSize <- MVP.unsafeRead metadata (base + 1)
+                          if cachedSize /= fromIntegral size
+                            then collide entry key bucket
+                            else case dictionaryShortSize size of
+                              1# -> emit entryId
+                              _ -> do
+                                address <- MVP.unsafeRead metadata (base + 2)
+                                let !previous = wordPtrToPtr (fromIntegral address) :: Ptr Word8
+                                equal <-
+                                  if ptr == previous
+                                    then pure True
+                                    else
+                                      if size == 64
+                                        then unsafeIOToST (dictionaryEqual64IO ptr previous)
+                                        else (== 0) <$> unsafeIOToST (BSI.memcmp ptr previous size)
+                                if equal then emit entryId else collide entry key bucket
+            key <- inline keyAt value ptr size
+            probe key (fromIntegral (dictionaryHashWord64 key) .&. mask)
+      grow !row !distinct !entries !metadata !table
+        | 1# <- dictionaryTableSizeExceeded (MVP.length table) = error "Parquet.Write: dictionary exceeds addressable size"
+        | otherwise = do
+            let !capacity = MV.length entries
+                !extra = min capacity (count - capacity)
+                !nextCapacity = capacity + extra
+            if nextCapacity > maxBound `quot` 24
+              then error "Parquet.Write: dictionary exceeds addressable size"
+              else pure ()
+            expandedEntries <- MV.unsafeGrow entries extra
+            expandedMetadata <- MVP.unsafeGrow metadata (extra * 3)
+            expandedTable <- MVP.replicate (MVP.length table * 2) (-1 :: Int32)
+            let !mask = MVP.length expandedTable - 1
+                rehash !entry
+                  | entry == distinct = go row distinct expandedEntries expandedMetadata expandedTable
+                  | otherwise = do
+                      key <- MVP.unsafeRead expandedMetadata (entry * 3)
+                      let insert !bucket = do
+                            old <- MVP.unsafeRead expandedTable bucket
+                            if old < 0
+                              then MVP.unsafeWrite expandedTable bucket (fromIntegral entry) >> rehash (entry + 1)
+                              else insert ((bucket + 1) .&. mask)
+                      insert (fromIntegral (dictionaryHashWord64 key) .&. mask)
+            rehash 0
+  in go startRow startDistinct startEntries startMetadata startTable
+{-# INLINE scanByteDictionary #-}
+
+
+scanDictionary
+  :: Bool
+  -> Int
+  -> (Int -> ST s Word64)
+  -> (Int -> Int -> Bool)
+  -> DictionaryCollision s
+  -> MVP.MVector s Int32
+  -> Int
+  -> Int
+  -> MVP.MVector s Int
+  -> MVP.MVector s Word64
+  -> MVP.MVector s Int32
+  -> ST s DictionaryBuild
+scanDictionary exactKeys count keyAt same onCollision indices startRow startDistinct startRows startKeys startTable =
+  let go !row !distinct !rows !keys !table
+        | row == count = do
+            uniqueRows <- VP.unsafeFreeze (MVP.unsafeSlice 0 distinct rows)
+            rowIndices <- VP.unsafeFreeze indices
+            pure (DictionaryBuild uniqueRows rowIndices)
+        | otherwise = do
+            -- Inlining keeps keys unboxed across both scan instantiations.
+            key <- inline keyAt row
+            probe key (fromIntegral (dictionaryHashWord64 key) .&. mask)
+        where
+          !mask = MVP.length table - 1
+          emit !entry = do
+            MVP.unsafeWrite indices row entry
+            go (row + 1) distinct rows keys table
+          probe !key !bucket = do
+            entry <- MVP.unsafeRead table bucket
+            if entry < 0
+              then case dictionaryCapacityReached distinct (MVP.length rows) of
+                1# -> grow
+                _ -> do
+                  case dictionaryEntriesExceeded distinct of
+                    1# -> error "Parquet.Write: too many dictionary entries"
+                    _ -> pure ()
+                  let !entryId = fromIntegral distinct
+                  MVP.unsafeWrite rows distinct row
+                  MVP.unsafeWrite keys distinct key
+                  MVP.unsafeWrite table bucket entryId
+                  MVP.unsafeWrite indices row entryId
+                  go (row + 1) (distinct + 1) rows keys table
+              else do
+                cached <- MVP.unsafeRead keys (fromIntegral entry)
+                if cached /= key
+                  then probe key ((bucket + 1) .&. mask)
+                  else
+                    if exactKeys
+                      then emit entry
+                      else do
+                        representative <- MVP.unsafeRead rows (fromIntegral entry)
+                        if inline same row representative
+                          then emit entry
+                          else onCollision row representative distinct rows keys table (probe key ((bucket + 1) .&. mask))
+          grow
+            | MVP.length table > maxBound `quot` 8 = error "Parquet.Write: dictionary exceeds addressable size"
+            | otherwise = do
+                let extra = min (MVP.length rows) (count - MVP.length rows)
+                expandedRows <- MVP.unsafeGrow rows extra
+                expandedKeys <- MVP.unsafeGrow keys extra
+                expandedTable <- MVP.replicate (MVP.length table * 2) (-1 :: Int32)
+                let !newMask = MVP.length expandedTable - 1
+                    rehash !entry
+                      | entry == distinct = go row distinct expandedRows expandedKeys expandedTable
+                      | otherwise = do
+                          key <- MVP.unsafeRead keys entry
+                          let insert !bucket = do
+                                old <- MVP.unsafeRead expandedTable bucket
+                                if old < 0
+                                  then MVP.unsafeWrite expandedTable bucket (fromIntegral entry) >> rehash (entry + 1)
+                                  else insert ((bucket + 1) .&. newMask)
+                          insert (fromIntegral (dictionaryHashWord64 key) .&. newMask)
+                rehash 0
+  in go startRow startDistinct startRows startKeys startTable
+{-# INLINE scanDictionary #-}
+
+
+-- These predicates are shared by probe branches. Lifted Bools otherwise
+-- float into one heap thunk per input row when a cold transition escapes.
+dictionaryCapacityReached :: Int -> Int -> Int#
+dictionaryCapacityReached (I# used) (I# capacity) = used ==# capacity
+{-# INLINE dictionaryCapacityReached #-}
+
+
+dictionaryEntriesExceeded :: Int -> Int#
+dictionaryEntriesExceeded (I# count) = count >=# 2147483647#
+{-# INLINE dictionaryEntriesExceeded #-}
+
+
+dictionaryTableSizeExceeded :: Int -> Int#
+dictionaryTableSizeExceeded (I# size) = case maxBound `quot` 8 of
+  I# limit -> size ># limit
+{-# INLINE dictionaryTableSizeExceeded #-}
+
+
+-- Shared by key calculation and equality. A lifted predicate otherwise
+-- becomes a fresh thunk per input row when a cold collision call escapes.
+dictionaryShortSize :: Int -> Int#
+dictionaryShortSize (I# size) = size <=# 8#
+{-# INLINE dictionaryShortSize #-}
+
+
+-- Private table-address mix; never a persisted Parquet/Iceberg hash.
+-- On 64-bit hosts, fold both halves of a seeded 64x64 product. GHC lowers
+-- this to native low/high multiplies and an XOR without boxed intermediates.
+-- Word# cannot carry a Word64 on 32-bit hosts, so retain the old mixer there.
+dictionaryHashWord64 :: Word64 -> Word64
+dictionaryHashWord64 value
+  | finiteBitSize (0 :: Word) == 64 =
+      case value `xor` 0xa0761d6478bd642f of
+        W64# x -> case (0xe7037ed1a0b428db :: Word64) of
+          W64# y -> case timesWord2# (word64ToWord# x) (word64ToWord# y) of
+            (# high, low #) -> W64# (wordToWord64# (xor# high low))
+  | otherwise =
+      let !a = (value `xor` (value `shiftR` 33)) * 0xff51afd7ed558ccd
+          !b = (a `xor` (a `shiftR` 33)) * 0xc4ceb9fe1a85ec53
+      in b `xor` (b `shiftR` 33)
+{-# INLINE dictionaryHashWord64 #-}
+
+
+-- Short byte strings use exact little-endian word keys, followed by a
+-- length comparison. Longer values first use a bounded end fingerprint;
+-- an ambiguous fingerprint refines it with a differing word, then falls
+-- back to full-content keys on a second ambiguity. Every mode still
+-- requires full byte equality for longer values.
+-- Cached keys therefore never stand in for equality of larger payloads.
+-- Every load below is unaligned and fits inside the logical byte string;
+-- in particular, a short tail is never read as a complete eight-byte word.
+dictionaryByteKeyAtIO :: Bool -> ByteString -> Ptr Word8 -> Int -> IO Word64
+dictionaryByteKeyAtIO fullHash bytes ptr size = case dictionaryShortSize size of
+  1# -> dictionaryReadShort ptr size
+  _ -> if not fullHash then dictionaryEndKey ptr size else if size > 128 then Hash.xxh64IO 0 bytes else dictionaryMediumKey ptr size
+{-# INLINE dictionaryByteKeyAtIO #-}
+
+
+dictionaryByteKeyIO :: Bool -> ByteString -> IO Word64
+dictionaryByteKeyIO fullHash bytes = do
+  let (fp, offset, size) = BSI.toForeignPtr bytes
+      ptr = unsafeForeignPtrToPtr fp `plusPtr` offset
+  key <- dictionaryByteKeyAtIO fullHash bytes ptr size
+  touchForeignPtr fp
+  pure key
+{-# INLINE dictionaryByteKeyIO #-}
+
+
+-- Longer values have at least nine bytes. Both unaligned word loads fit
+-- inside the logical slice, including when they overlap. Length separates
+-- equal ends at different sizes; full equality verifies every cached hit.
+dictionaryEndKey :: Ptr Word8 -> Int -> IO Word64
+dictionaryEndKey ptr size = do
+  first <- dictionaryRead64 ptr
+  lastWord <- dictionaryRead64 (ptr `plusPtr` (size - 8))
+  pure (first `xor` rotateL lastWord 27 `xor` (fromIntegral size * 0x9e3779b97f4a7c15))
+{-# INLINE dictionaryEndKey #-}
+
+
+-- Refinement is chosen once, on the first ambiguous fingerprint. An
+-- equal-length pair supplies a differing bounded word; other shapes fall
+-- back to full keys immediately. Neither payload is read past its slice.
+dictionaryDifferenceOffsetIO :: ByteString -> ByteString -> IO Int
+dictionaryDifferenceOffsetIO a b
+  | size <= 8 || size /= BS.length b = pure (-1)
+  | otherwise = do
+      let (fpA, offsetA, _) = BSI.toForeignPtr a
+          (fpB, offsetB, _) = BSI.toForeignPtr b
+          ptrA = unsafeForeignPtrToPtr fpA `plusPtr` offsetA
+          ptrB = unsafeForeignPtrToPtr fpB `plusPtr` offsetB
+          go !offset
+            | offset == size = pure (-1)
+            | otherwise = do
+                let !at = min offset (size - 8)
+                x <- dictionaryRead64 (ptrA `plusPtr` at)
+                y <- dictionaryRead64 (ptrB `plusPtr` at)
+                if x /= y then pure at else if size - offset <= 8 then pure (-1) else go (offset + 8)
+      result <- go 0
+      touchForeignPtr fpA
+      touchForeignPtr fpB
+      pure result
+  where
+    size = BS.length a
+{-# INLINE dictionaryDifferenceOffsetIO #-}
+
+
+-- Include the chosen word in addition to both ends. Multiplication by an
+-- odd constant and rotation are injective, so the triggering equal-end
+-- pair is separated. A second ambiguity promotes to full-content keys.
+dictionaryRefinedKeyAtIO :: Int -> Ptr Word8 -> Int -> IO Word64
+dictionaryRefinedKeyAtIO pivot ptr size = case dictionaryShortSize size of
+  1# -> dictionaryReadShort ptr size
+  _ -> do
+    ends <- dictionaryEndKey ptr size
+    middle <- dictionaryRead64 (ptr `plusPtr` min pivot (size - 8))
+    pure (ends `xor` rotateL (middle * 0xd6e8feb86659fd93) 17)
+{-# INLINE dictionaryRefinedKeyAtIO #-}
+
+
+dictionaryRefinedKeyIO :: Int -> ByteString -> IO Word64
+dictionaryRefinedKeyIO pivot bytes = do
+  let (fp, offset, size) = BSI.toForeignPtr bytes
+      ptr = unsafeForeignPtrToPtr fp `plusPtr` offset
+  key <- dictionaryRefinedKeyAtIO pivot ptr size
+  touchForeignPtr fp
+  pure key
+{-# INLINE dictionaryRefinedKeyIO #-}
+
+
+-- For small dictionary values a native four-lane word mix avoids a
+-- foreign-call boundary per row. These are internal lookup keys, never
+-- Parquet's persisted hashes. Full byte equality still verifies matches.
+dictionaryMediumKey :: Ptr Word8 -> Int -> IO Word64
+dictionaryMediumKey ptr size = blocks 0 0x9e3779b97f4a7c15 0x243f6a8885a308d3 0x13198a2e03707344 0xa4093822299f31d0
+  where
+    step !acc !word = (acc `xor` word) * 0x9e3779b185ebca87
+    {-# INLINE step #-}
+    blocks !offset !a !b !c !d
+      | size - offset < 32 =
+          finish offset (fromIntegral size `xor` rotateL a 5 `xor` rotateL b 17 `xor` rotateL c 37 `xor` rotateL d 53)
+      | otherwise = do
+          w0 <- dictionaryRead64 (ptr `plusPtr` offset)
+          w1 <- dictionaryRead64 (ptr `plusPtr` (offset + 8))
+          w2 <- dictionaryRead64 (ptr `plusPtr` (offset + 16))
+          w3 <- dictionaryRead64 (ptr `plusPtr` (offset + 24))
+          blocks (offset + 32) (step a w0) (step b w1) (step c w2) (step d w3)
+    finish !offset !acc
+      | size - offset < 8 = do
+          tailWord <- dictionaryReadShort (ptr `plusPtr` offset) (size - offset)
+          pure (acc `xor` tailWord)
+      | otherwise = do
+          word <- dictionaryRead64 (ptr `plusPtr` offset)
+          finish (offset + 8) (rotateL (step acc word) 27)
+{-# INLINE dictionaryMediumKey #-}
+
+
+-- Called only after both logical lengths have been checked to be 64.
+-- Reduce all word differences once; no variable loop or foreign call.
+dictionaryEqual64IO :: Ptr Word8 -> Ptr Word8 -> IO Bool
+dictionaryEqual64IO a b = do
+  a0 <- dictionaryRead64 a
+  b0 <- dictionaryRead64 b
+  let !d0 = a0 `xor` b0
+  a1 <- dictionaryRead64 (a `plusPtr` 8)
+  b1 <- dictionaryRead64 (b `plusPtr` 8)
+  let !d1 = d0 .|. (a1 `xor` b1)
+  a2 <- dictionaryRead64 (a `plusPtr` 16)
+  b2 <- dictionaryRead64 (b `plusPtr` 16)
+  let !d2 = d1 .|. (a2 `xor` b2)
+  a3 <- dictionaryRead64 (a `plusPtr` 24)
+  b3 <- dictionaryRead64 (b `plusPtr` 24)
+  let !d3 = d2 .|. (a3 `xor` b3)
+  a4 <- dictionaryRead64 (a `plusPtr` 32)
+  b4 <- dictionaryRead64 (b `plusPtr` 32)
+  let !d4 = d3 .|. (a4 `xor` b4)
+  a5 <- dictionaryRead64 (a `plusPtr` 40)
+  b5 <- dictionaryRead64 (b `plusPtr` 40)
+  let !d5 = d4 .|. (a5 `xor` b5)
+  a6 <- dictionaryRead64 (a `plusPtr` 48)
+  b6 <- dictionaryRead64 (b `plusPtr` 48)
+  let !d6 = d5 .|. (a6 `xor` b6)
+  a7 <- dictionaryRead64 (a `plusPtr` 56)
+  b7 <- dictionaryRead64 (b `plusPtr` 56)
+  pure ((d6 .|. (a7 `xor` b7)) == 0)
+{-# INLINE dictionaryEqual64IO #-}
+
+
+-- Exact zero-padded LE keys for a caller-checked tail of zero to eight bytes.
+dictionaryReadShort :: Ptr Word8 -> Int -> IO Word64
+dictionaryReadShort ptr size = case size of
+  0 -> pure 0
+  1 -> fromIntegral <$> dictionaryRead8 ptr
+  2 -> fromIntegral <$> dictionaryRead16 ptr
+  3 -> do
+    a <- dictionaryRead16 ptr
+    b <- dictionaryRead8 (ptr `plusPtr` 2)
+    pure (fromIntegral a .|. (fromIntegral b `shiftL` 16))
+  4 -> fromIntegral <$> dictionaryRead32 ptr
+  5 -> do
+    a <- dictionaryRead32 ptr
+    b <- dictionaryRead8 (ptr `plusPtr` 4)
+    pure (fromIntegral a .|. (fromIntegral b `shiftL` 32))
+  6 -> do
+    a <- dictionaryRead32 ptr
+    b <- dictionaryRead16 (ptr `plusPtr` 4)
+    pure (fromIntegral a .|. (fromIntegral b `shiftL` 32))
+  7 -> do
+    a <- dictionaryRead32 ptr
+    b <- dictionaryRead16 (ptr `plusPtr` 4)
+    c <- dictionaryRead8 (ptr `plusPtr` 6)
+    pure (fromIntegral a .|. (fromIntegral b `shiftL` 32) .|. (fromIntegral c `shiftL` 48))
+  _ -> dictionaryRead64 ptr
+{-# INLINE dictionaryReadShort #-}
+
+
+-- Keep the shared size predicate unboxed. A lifted Bool shared between
+-- hashing and equality otherwise becomes one heap thunk per input row.
+dictionaryRead8 :: Ptr Word8 -> IO Word8
+dictionaryRead8 (Ptr address) = IO $ \s -> case readWord8OffAddr# address 0# s of
+  (# next, value #) -> (# next, W8# value #)
+{-# INLINE dictionaryRead8 #-}
+
+
+dictionaryRead16 :: Ptr Word8 -> IO Word16
+dictionaryRead16 (Ptr address) = do
+  value <- IO $ \s -> case readWord8OffAddrAsWord16# address 0# s of
+    (# next, word #) -> (# next, W16# word #)
+  pure (case targetByteOrder of LittleEndian -> value; BigEndian -> byteSwap16 value)
+{-# INLINE dictionaryRead16 #-}
+
+
+dictionaryRead32 :: Ptr Word8 -> IO Word32
+dictionaryRead32 (Ptr address) = do
+  value <- IO $ \s -> case readWord8OffAddrAsWord32# address 0# s of
+    (# next, word #) -> (# next, W32# word #)
+  pure (case targetByteOrder of LittleEndian -> value; BigEndian -> byteSwap32 value)
+{-# INLINE dictionaryRead32 #-}
+
+
+dictionaryRead64 :: Ptr Word8 -> IO Word64
+dictionaryRead64 (Ptr address) = do
+  value <- IO $ \s -> case readWord8OffAddrAsWord64# address 0# s of
+    (# next, word #) -> (# next, W64# word #)
+  pure (case targetByteOrder of LittleEndian -> value; BigEndian -> byteSwap64 value)
+{-# INLINE dictionaryRead64 #-}
+
+
+-- | Encode a 'Dictionary' as a @DICTIONARY_PAGE@.
+encodeDictPage :: Dictionary -> ByteString
+encodeDictPage d = either error encode (planPlainPayload (dictUniques d))
+  where
+    encode plan =
+      let !payload = encodePlannedPlainPayload plan (dictUniques d)
+          !numEntries = plainValueCount plan
+          !size = fromIntegral (plainPayloadSize plan)
+          !hdr =
+            PageHeader
+              { phType =
+                  PtDictionaryPage
+                    DictionaryPageHeader
+                      { dictNumValues = numEntries
+                      , dictEncoding = 0 -- Dictionary entries use PLAIN.
+                      }
+              , phUncompressedPageSize = Just size
+              , phCompressedPageSize = Just size
+              }
+      in encodePageHeader hdr <> payload
+
+
+{- | Encode the 'DATA_PAGE' that consumes a dictionary (RLE-hybrid index
+stream prefixed by a single byte recording the bit width).
+-}
+encodeDictDataPage :: Dictionary -> ByteString
+encodeDictDataPage d = either error id $ do
+  let !indices = dictIndices d
+      !numIndices = VP.length indices
+      !uniqueCount = columnDataLength (dictUniques d)
+  numValues <- pageInt32 "dictionary index count" numIndices
+  _ <- pageInt32 "dictionary entry count" uniqueCount
+  if uniqueCount == 0 && numIndices /= 0
+    then Left "Parquet.Write: nonempty indices require a nonempty dictionary"
+    else Right ()
+  let !largestIndex = max 0 (uniqueCount - 1)
+      !bw = LE.bitWidthFor largestIndex
+  plan <- LE.planRLEHybrid bw (fromIntegral largestIndex) indices
+  bodySize <- pageSizeWithOverhead 1 (LE.hybridEncodedSize plan)
+  let !indexStream = LE.encodeHybridPlan plan
+      !body = BS.singleton (fromIntegral bw) <> indexStream
+      !hdr =
+        PageHeader
+          { phType =
+              PtDataPage
+                DataPageHeader
+                  { dphNumValues = numValues
+                  , dphEncoding = parquetEncodingRleDictionary
+                  }
+          , phUncompressedPageSize = Just bodySize
+          , phCompressedPageSize = Just bodySize
+          }
+  Right (encodePageHeader hdr <> body)
+
+
+parquetEncodingRleDictionary :: Int32
+parquetEncodingRleDictionary = 8
+
+
+-- ============================================================
+-- Indexed writer: bloom filter + page index footers
+-- ============================================================
+
+{- | Which Parquet data page header to emit for a column chunk.
+
+- 'PageV1': @DATA_PAGE@ (legacy). Definition + repetition levels are
+  length-prefixed RLE-hybrid streams concatenated with the values
+  inside the (optionally compressed) page body.
+- 'PageV2': @DATA_PAGE_V2@. Definition and repetition levels are NOT
+  length-prefixed and are NOT compressed. Only the values segment is
+  compressed, and the level segment lengths are recorded in the page
+  header so readers can skip directly to the data.
+-}
+data PageVersion = PageV1 | PageV2
+  deriving (Show, Eq)
+
+
+{- | Per-column encryption knobs the writer needs at page-emit time.
+
+Lifted out of the global 'Enc.EncryptionConfig' so a single column
+aux record carries everything: the key, the algorithm, the file-id /
+AAD-prefix / key-metadata bytes, and the column ordinal that goes
+into the AAD suffix. All columns in a typical Parquet file share the
+same algorithm and AAD-prefix; the helper 'columnEncryptionFor'
+builds a per-column 'ColumnEncryption' from the file-wide
+'Enc.EncryptionConfig' so callers don't have to repeat the boilerplate.
+-}
+data ColumnEncryption = ColumnEncryption
+  { ceAlgorithm :: !Enc.EncryptionAlgorithm
+  {- ^ 'Enc.AesGcmV1' encrypts every page (header + body) with GCM;
+  'Enc.AesGcmCtrV1' encrypts data\/dictionary page bodies with CTR
+  and everything else (page headers, column metadata, indexes) with
+  GCM. Both algorithms produce the same on-the-wire framing.
+  -}
+  , ceKey :: !BS.ByteString
+  -- ^ AES key (16, 24, or 32 bytes).
+  , ceFileId :: !BS.ByteString
+  -- ^ Fresh random file identifier, shared with the footer's AAD context.
+  , ceAadPrefix :: !BS.ByteString
+  -- ^ Caller-supplied AAD prefix (typically empty).
+  , ceKeyMetadata :: !BS.ByteString
+  {- ^ Reserved for column-specific keys. The whole-file writer currently
+  supports footer-key encryption and uses 'feKeyMetadata' for key recovery.
+  -}
+  , ceColumnOrdinal :: !Int
+  -- ^ Column ordinal within the row group.
+  }
+  deriving (Show, Eq)
+
+
+{- | Auxiliary metadata for one column chunk. Explicit values override
+generated indexes; 'caGeneratePageIndex' requests automatic indexes when
+the corresponding explicit fields are 'Nothing'.
+-}
+data ColumnAux = ColumnAux
+  { caGeneratePageIndex :: !Bool
+  -- ^ Generate indexes from the actual single-page layout and statistics.
+  , caBloomFilter :: !(Maybe Sbbf)
+  {- ^ Pre-built split-block bloom filter for this column chunk. The
+  writer serialises it into the bloom-filter region and records the
+  (offset, length) on the column metadata.
+  -}
+  , caOffsetIndex :: !(Maybe OffsetIndex)
+  {- ^ Per-page @(offset, compressed_size, first_row_index)@ entries.
+  The writer rewrites the @plOffset@ of each 'PageLocation' so that
+  it points at the actual page-bytes location in the assembled file.
+  -}
+  , caColumnIndex :: !(Maybe ColumnIndex)
+  -- ^ Per-page null/min/max statistics. Written verbatim.
+  , caCodec :: !Compression
+  {- ^ Compression codec for the column-chunk page bytes. Default
+  'Uncompressed'; use any codec listed in 'Parquet.Compress.compressPageBytes'.
+  -}
+  , caPageVersion :: !PageVersion
+  -- ^ Page header version to emit. Defaults to 'PageV1'.
+  , caEncryption :: !(Maybe ColumnEncryption)
+  {- ^ When 'Just', the page header + body for this column chunk are
+  encrypted per the spec module-wise framing (nonce || ciphertext
+  || tag for GCM modules; nonce || ciphertext for CTR modules).
+  Defaults to 'Nothing' (plaintext).
+  -}
+  }
+  deriving (Show, Eq)
+
+
+-- These builders emit one data page per column. Explicit auxiliary indexes
+-- must describe that page; their offsets/sizes are fixed during layout.
+validateAuxIndexes :: ColumnAux -> Either String ()
+validateAuxIndexes aux = do
+  case caOffsetIndex aux of
+    Just oi
+      | V.length (oiPageLocations oi) /= 1
+          || maybe False ((/= 1) . V.length) (oiUnencodedByteArrayDataBytes oi) ->
+          Left "Parquet.Write: explicit offset index must describe exactly one page"
+    _ -> Right ()
+  case caColumnIndex aux of
+    Just ci
+      | V.length (ciNullPages ci) /= 1
+          || V.length (ciMinValues ci) /= 1
+          || V.length (ciMaxValues ci) /= 1
+          || maybe False ((/= 1) . V.length) (ciNullCounts ci)
+          || maybe False ((/= 1) . V.length) (ciNanCounts ci) ->
+          Left "Parquet.Write: explicit column index must describe exactly one page"
+    _ -> Right ()
+
+
+emptyColumnAux :: ColumnAux
+emptyColumnAux = ColumnAux False Nothing Nothing Nothing Uncompressed PageV1 Nothing
+
+
+{- | Convenience: build a 'ColumnEncryption' for a leaf column from
+the file-wide 'Enc.EncryptionConfig'. Looks up the column key from
+@encColumnKeys@ by the leaf @SchemaElement@'s @seName@ (if absent
+we fall back to @ekFooterKey@ so a single-key configuration "just
+works"); copies the algorithm / file-id / AAD-prefix / key-metadata
+through verbatim.
+
+Returns 'Nothing' when the configuration is 'Enc.unencrypted'
+(empty footer key /and/ empty column-keys map).
+-}
+columnEncryptionFor
+  :: Enc.EncryptionConfig
+  -> Text
+  -- ^ leaf column name
+  -> Int
+  -- ^ column ordinal
+  -> Maybe ColumnEncryption
+columnEncryptionFor cfg colName colOrd
+  | BS.null (Enc.ekFooterKey keys)
+      && Map.null (Enc.ekColumnKeys keys) =
+      Nothing
+  | otherwise =
+      Just
+        ColumnEncryption
+          { ceAlgorithm = Enc.encAlgorithm cfg
+          , ceKey = lookupKey
+          , ceFileId = Enc.encAadFileId cfg
+          , ceAadPrefix = Enc.encAadPrefix cfg
+          , ceKeyMetadata = Enc.encKeyMetadata cfg
+          , ceColumnOrdinal = colOrd
+          }
+  where
+    keys = Enc.encKeys cfg
+    lookupKey = case Map.lookup colName (Enc.ekColumnKeys keys) of
+      Just k -> k
+      Nothing -> Enc.ekFooterKey keys
+
+
+{- | Encrypt a single page (header || body) according to a
+'ColumnEncryption'. The protocol the writer follows for one page:
+
+1. Build the page header thrift bytes /and/ the (possibly compressed)
+   body bytes as usual.
+2. Compute @AAD = aad_prefix || aad_file_id || module_type || rg ||
+   col || page@ for the page header module.
+3. Encrypt the page header bytes with GCM (always) under that AAD,
+   yielding @nonce || ciphertext || tag@ (28 bytes of overhead).
+4. Compute the same AAD with @module_type = ModuleDataPage@ for the
+   body. Encrypt the body with the algorithm-appropriate cipher
+   ('Enc.AesGcmV1' uses GCM, 'Enc.AesGcmCtrV1' uses CTR).
+5. Concatenate @encryptedHeader || encryptedBody@. The result is
+   what gets written to disk; the only metadata change on the column
+   chunk is that @cmEncoding@ continues to advertise the underlying
+   encoding and the encryption is recorded on the column-chunk's
+   @cmKeyMetadata@.
+-}
+encryptPageBytes
+  :: RNG.MonadRandom m
+  => ColumnEncryption
+  -> Enc.ModuleType
+  -- ^ module type for the page body (DataPage, DictionaryPage)
+  -> Int
+  -- ^ row-group ordinal
+  -> Int
+  -- ^ page ordinal within the column chunk
+  -> ByteString
+  -- ^ unencrypted page header bytes
+  -> ByteString
+  -- ^ unencrypted page body bytes
+  -> m (Either String ByteString)
+encryptPageBytes ce bodyModule rgOrd pageOrd hdrBytes bodyBytes = do
+  nonces <- RNG.getRandomBytes 24
+  pure (encryptPageBytesWithNonces nonces ce bodyModule rgOrd pageOrd hdrBytes bodyBytes)
+
+
+encryptPageBytesWithNonces
+  :: ByteString
+  -> ColumnEncryption
+  -> Enc.ModuleType
+  -> Int
+  -> Int
+  -> ByteString
+  -> ByteString
+  -> Either String ByteString
+encryptPageBytesWithNonces nonces ce bodyModule rgOrd pageOrd hdrBytes bodyBytes = do
+  encryptedSize <-
+    pageSizeWithOverhead
+      (case ceAlgorithm ce of Enc.AesGcmV1 -> 32; Enc.AesGcmCtrV1 -> 16)
+      (BS.length bodyBytes)
+  let !aadHdrModule = case bodyModule of
+        Enc.ModuleDataPage -> Enc.ModuleDataPageHeader
+        Enc.ModuleDictionaryPage -> Enc.ModuleDictionaryPageHeader
+        other -> other
+      !suffixHdr =
+        Enc.buildAadSuffix
+          (ceFileId ce)
+          aadHdrModule
+          (fromIntegral rgOrd)
+          (fromIntegral (ceColumnOrdinal ce))
+          (fromIntegral pageOrd)
+      !suffixBody =
+        Enc.buildAadSuffix
+          (ceFileId ce)
+          bodyModule
+          (fromIntegral rgOrd)
+          (fromIntegral (ceColumnOrdinal ce))
+          (fromIntegral pageOrd)
+      !aadHdr = Enc.buildAad (ceAadPrefix ce) suffixHdr
+      !aadBody = Enc.buildAad (ceAadPrefix ce) suffixBody
+  encBody <- case ceAlgorithm ce of
+    Enc.AesGcmV1 -> Enc.encryptGcmModuleFramedWithNonce (ceKey ce) (BS.take 12 (BS.drop 12 nonces)) aadBody bodyBytes
+    Enc.AesGcmCtrV1 -> Enc.encryptCtrModuleFramedWithNonce (ceKey ce) (BS.take 12 (BS.drop 12 nonces)) bodyBytes
+  (header, _) <- readPageHeaderAt hdrBytes 0
+  let encryptedHeader =
+        encodePageHeader
+          header
+            { phCompressedPageSize = Just encryptedSize
+            }
+  encHdr <- Enc.encryptGcmModuleFramedWithNonce (ceKey ce) (BS.take 12 nonces) aadHdr encryptedHeader
+  Right (BS.append encHdr encBody)
+
+
+{- | Encrypt a DATA_PAGE_V2 page, given the four parts produced by
+'encodeColumnDataPageV2Parts' / 'encodeOptionalColumnPageV2Parts'.
+
+The level segments remain uncompressed, but are encrypted along with
+all values as a single page body. The authenticated page header is a
+separate encrypted module, exactly as for V1.
+-}
+encryptPageBytesV2
+  :: RNG.MonadRandom m
+  => ColumnEncryption
+  -> Int
+  -> Int
+  -> ByteString
+  -> ByteString
+  -> ByteString
+  -> ByteString
+  -> m (Either String ByteString)
+encryptPageBytesV2 ce rgOrd pageOrd hdrBytes repBytes defBytes valBytes =
+  encryptPageBytes
+    ce
+    Enc.ModuleDataPage
+    rgOrd
+    pageOrd
+    hdrBytes
+    (BS.concat [repBytes, defBytes, valBytes])
+
+
+{- | Encrypt a single auxiliary module (bloom filter, offset index,
+column index) with the column's GCM key under the module's AAD,
+when 'caEncryption' is set. Returns the original payload unchanged
+otherwise. CTR isn't used for these modules even on
+'AesGcmCtrV1' columns: the spec mandates GCM for everything except
+data\/dictionary page bodies, so the algorithm flag is irrelevant
+here.
+-}
+encryptAuxModule
+  :: RNG.MonadRandom m
+  => Maybe ColumnEncryption
+  -> Enc.ModuleType
+  -> Int
+  -> ByteString
+  -> m (Either String ByteString)
+encryptAuxModule Nothing _ _ payload = pure (Right payload)
+encryptAuxModule (Just ce) mt rgOrd payload = do
+  nonce <- RNG.getRandomBytes 12
+  pure (encryptAuxModuleWithNonce nonce ce mt rgOrd payload)
+
+
+encryptAuxModuleWithNonce
+  :: ByteString
+  -> ColumnEncryption
+  -> Enc.ModuleType
+  -> Int
+  -> ByteString
+  -> Either String ByteString
+encryptAuxModuleWithNonce nonce ce mt rgOrd payload =
+  let suffix =
+        Enc.buildAadSuffix
+          (ceFileId ce)
+          mt
+          (fromIntegral rgOrd)
+          (fromIntegral (ceColumnOrdinal ce))
+          0
+  in Enc.encryptGcmModuleFramedWithNonce
+       (ceKey ce)
+       nonce
+       (Enc.buildAad (ceAadPrefix ce) suffix)
+       payload
+
+
+-- One random nonce per module, indexed by physical row group and column.
+-- The writer currently emits one data page per column chunk. These slots
+-- must be extended if it starts emitting dictionary or multiple data pages.
+newtype EncryptionNonces = EncryptionNonces (V.Vector (V.Vector ByteString))
+
+
+moduleNonce :: Maybe EncryptionNonces -> Int -> Int -> Enc.ModuleType -> ByteString
+moduleNonce Nothing _ _ _ = error "Parquet.Write: encryption requires the IO writer"
+moduleNonce (Just (EncryptionNonces groups)) rg col mt =
+  let slot = case mt of
+        Enc.ModuleDataPageHeader -> 0
+        Enc.ModuleDataPage -> 1
+        Enc.ModuleBloomFilterHeader -> 2
+        Enc.ModuleBloomFilterBitset -> 3
+        Enc.ModuleOffsetIndex -> 4
+        Enc.ModuleColumnIndex -> 5
+        _ -> error "Parquet.Write: unsupported encryption nonce slot"
+  in BS.take 12 (BS.drop (slot * 12) (groups V.! rg V.! col))
+
+
+-- Layout functions use the physical column index, never a caller's
+-- possibly stale ceColumnOrdinal, for both the nonce and the AAD.
+encryptLayoutModule
+  :: Maybe EncryptionNonces
+  -> Int
+  -> Int
+  -> Maybe ColumnEncryption
+  -> Enc.ModuleType
+  -> ByteString
+  -> ByteString
+encryptLayoutModule _ _ _ Nothing _ payload = payload
+encryptLayoutModule nonces rg col (Just ce) mt payload =
+  either
+    (error . ("Parquet.Write: encryption failed: " ++))
+    id
+    ( encryptAuxModuleWithNonce
+        (moduleNonce nonces rg col mt)
+        ce {ceColumnOrdinal = col}
+        mt
+        rg
+        payload
+    )
+
+
+layoutBlooms
+  :: Maybe EncryptionNonces
+  -> V.Vector RowGroup
+  -> V.Vector (V.Vector ColumnAux)
+  -> Int
+  -- ^ starting offset
+  -> (V.Vector RowGroup, [ByteString], Int)
+layoutBlooms nonces rgs auxes start = go 0 start [] V.empty
+  where
+    go !i !off !payloads !acc
+      | i >= V.length rgs = (acc, reverse payloads, off)
+      | otherwise =
+          let !rg = V.unsafeIndex rgs i
+              !cols = rgColumns rg
+              !aux = if i < V.length auxes then V.unsafeIndex auxes i else V.empty
+              (!cols', !off', !payloads') =
+                V.ifoldl' (rewriteCol i aux) (V.empty, off, payloads) cols
+              !rg' = rg {rgColumns = cols'}
+          in go (i + 1) off' payloads' (V.snoc acc rg')
+
+    rewriteCol
+      :: Int -- row-group ordinal
+      -> V.Vector ColumnAux
+      -> (V.Vector ColumnChunk, Int, [ByteString])
+      -> Int
+      -> ColumnChunk
+      -> (V.Vector ColumnChunk, Int, [ByteString])
+    rewriteCol rgOrd aux (!ccs, !off, !payloads) cIdx cc =
+      let mAux = if cIdx < V.length aux then Just (V.unsafeIndex aux cIdx) else Nothing
+      in case mAux >>= caBloomFilter of
+           Nothing -> (V.snoc ccs cc, off, payloads)
+           Just bf ->
+             let !raw = encodeBloomFilter bf
+                 -- Bloom headers and bitsets are separate GCM modules,
+                 -- with distinct AAD module types and independent nonces.
+                 !bs = case mAux >>= caEncryption of
+                   Nothing -> raw
+                   Just ce -> case Thrift.decodeCompactFrom raw 0 of
+                     Left err -> error ("Parquet.Write: invalid encoded bloom header: " ++ err)
+                     Right (_, headerEnd) ->
+                       encryptLayoutModule
+                         nonces
+                         rgOrd
+                         cIdx
+                         (Just ce)
+                         Enc.ModuleBloomFilterHeader
+                         (BS.take headerEnd raw)
+                         <> encryptLayoutModule
+                           nonces
+                           rgOrd
+                           cIdx
+                           (Just ce)
+                           Enc.ModuleBloomFilterBitset
+                           (BS.drop headerEnd raw)
+                 !bsLen = BS.length bs
+                 !cm0 = fromMaybe defaultMetadata (ccMetadata cc)
+                 !cm' =
+                   cm0
+                     { cmBloomFilterOffset = Just (fromIntegral off)
+                     -- The length field is optional and signed32, while a
+                     -- legal bitset plus its header/framing can exceed it.
+                     , cmBloomFilterLength = if bsLen <= fromIntegral (maxBound :: Int32) then Just (fromIntegral bsLen) else Nothing
+                     }
+                 !cc' = cc {ccMetadata = Just cm'}
+             in (V.snoc ccs cc', off + bsLen, bs : payloads)
+
+    defaultMetadata =
+      ColumnMetadata
+        { cmType = PTInt32
+        , cmEncodings = V.empty
+        , cmPathInSchema = V.empty
+        , cmCodec = Uncompressed
+        , cmNumValues = 0
+        , cmTotalUncompressedSize = 0
+        , cmTotalCompressedSize = 0
+        , cmDataPageOffset = 0
+        , cmDictionaryPageOffset = Nothing
+        , cmStatistics = Nothing
+        , cmBloomFilterOffset = Nothing
+        , cmBloomFilterLength = Nothing
+        }
+
+
+layoutOffsetIndex
+  :: Maybe EncryptionNonces
+  -> V.Vector RowGroup
+  -> V.Vector (V.Vector ColumnAux)
+  -> Int
+  -> (V.Vector RowGroup, [ByteString], Int)
+layoutOffsetIndex nonces rgs auxes start = go 0 start [] V.empty
+  where
+    go !i !off !payloads !acc
+      | i >= V.length rgs = (acc, reverse payloads, off)
+      | otherwise =
+          let !rg = V.unsafeIndex rgs i
+              !cols = rgColumns rg
+              !aux = if i < V.length auxes then V.unsafeIndex auxes i else V.empty
+              (!cols', !off', !payloads') =
+                V.ifoldl' (rewriteCol i aux) (V.empty, off, payloads) cols
+              !rg' = rg {rgColumns = cols'}
+          in go (i + 1) off' payloads' (V.snoc acc rg')
+
+    rewriteCol
+      :: Int
+      -> V.Vector ColumnAux
+      -> (V.Vector ColumnChunk, Int, [ByteString])
+      -> Int
+      -> ColumnChunk
+      -> (V.Vector ColumnChunk, Int, [ByteString])
+    rewriteCol rgOrd aux (!ccs, !off, !payloads) cIdx cc =
+      let mAux = if cIdx < V.length aux then Just (V.unsafeIndex aux cIdx) else Nothing
+          requested = case mAux >>= caOffsetIndex of
+            Just oi -> Just oi
+            Nothing | maybe False (\aux -> caGeneratePageIndex aux || maybe False (const True) (caColumnIndex aux)) mAux -> Just (OffsetIndex V.empty Nothing)
+            _ -> Nothing
+      in case requested of
+           Nothing -> (V.snoc ccs cc, off, payloads)
+           Just oi ->
+             let !locations = case ccMetadata cc of
+                   Just metadata
+                     | cmTotalCompressedSize metadata <= fromIntegral (maxBound :: Int32) ->
+                         V.singleton
+                           ( PageLocation
+                               (cmDataPageOffset metadata)
+                               (fromIntegral (cmTotalCompressedSize metadata))
+                               0
+                           )
+                   _ -> error "Parquet.Write: indexed page size exceeds signed 32-bit range"
+                 !raw = encodeOffsetIndex oi {oiPageLocations = locations}
+                 !bs =
+                   encryptLayoutModule
+                     nonces
+                     rgOrd
+                     cIdx
+                     (mAux >>= caEncryption)
+                     Enc.ModuleOffsetIndex
+                     raw
+                 !bsLen = BS.length bs
+                 !cc' =
+                   cc
+                     { ccOffsetIndexOffset = Just (fromIntegral off)
+                     , ccOffsetIndexLength = Just (fromIntegral bsLen)
+                     }
+             in (V.snoc ccs cc', off + bsLen, bs : payloads)
+
+
+layoutColumnIndex
+  :: Maybe EncryptionNonces
+  -> V.Vector RowGroup
+  -> V.Vector (V.Vector ColumnAux)
+  -> Int
+  -> (V.Vector RowGroup, [ByteString], Int)
+layoutColumnIndex nonces rgs auxes start = go 0 start [] V.empty
+  where
+    go !i !off !payloads !acc
+      | i >= V.length rgs = (acc, reverse payloads, off)
+      | otherwise =
+          let !rg = V.unsafeIndex rgs i
+              !cols = rgColumns rg
+              !aux = if i < V.length auxes then V.unsafeIndex auxes i else V.empty
+              (!cols', !off', !payloads') =
+                V.ifoldl' (rewriteCol i aux) (V.empty, off, payloads) cols
+              !rg' = rg {rgColumns = cols'}
+          in go (i + 1) off' payloads' (V.snoc acc rg')
+
+    rewriteCol
+      :: Int
+      -> V.Vector ColumnAux
+      -> (V.Vector ColumnChunk, Int, [ByteString])
+      -> Int
+      -> ColumnChunk
+      -> (V.Vector ColumnChunk, Int, [ByteString])
+    rewriteCol rgOrd aux (!ccs, !off, !payloads) cIdx cc =
+      let mAux = if cIdx < V.length aux then Just (V.unsafeIndex aux cIdx) else Nothing
+          requested = case mAux >>= caColumnIndex of
+            Just ci -> Just ci
+            Nothing | maybe False caGeneratePageIndex mAux -> singlePageColumnIndex cc
+            _ -> Nothing
+      in case requested of
+           Nothing -> (V.snoc ccs cc, off, payloads)
+           Just ci ->
+             let !raw = encodeColumnIndex ci
+                 !bs =
+                   encryptLayoutModule
+                     nonces
+                     rgOrd
+                     cIdx
+                     (mAux >>= caEncryption)
+                     Enc.ModuleColumnIndex
+                     raw
+                 !bsLen = BS.length bs
+                 !cc' =
+                   cc
+                     { ccColumnIndexOffset = Just (fromIntegral off)
+                     , ccColumnIndexLength = Just (fromIntegral bsLen)
+                     }
+             in (V.snoc ccs cc', off + bsLen, bs : payloads)
+
+
+-- | The auxiliary regions and rewritten metadata for composite writers.
+data ColumnAuxLayout = ColumnAuxLayout
+  { auxRowGroups :: !(V.Vector RowGroup)
+  , auxParts :: ![ByteString]
+  , auxEndOffset :: {-# UNPACK #-} !Int
+  }
+
+
+{- | Append bloom filters and page indexes for already encoded, single-page
+column chunks. Column metadata must describe the final page bytes, with
+file-relative offsets. This pure entry point rejects encryption; encrypted
+writers must allocate independent nonces for each module.
+-}
+layoutColumnAuxiliaries
+  :: V.Vector RowGroup
+  -> V.Vector (V.Vector ColumnAux)
+  -> Int
+  -> Either String ColumnAuxLayout
+layoutColumnAuxiliaries groups auxes start = do
+  if start < 4 || V.length groups /= V.length auxes
+    then Left "Parquet.Write: invalid auxiliary layout shape or start offset"
+    else Right ()
+  V.imapM_
+    ( \index group -> do
+        let columns = rgColumns group
+            options = auxes V.! index
+        if V.length columns /= V.length options
+          then Left "Parquet.Write: auxiliary column count mismatch"
+          else Right ()
+        V.imapM_
+          ( \column aux -> do
+              validateAuxIndexes aux
+              case caEncryption aux of
+                Just _ -> Left "Parquet.Write: pure auxiliary layout does not support encryption"
+                Nothing -> Right ()
+              case ccMetadata (columns V.! column) of
+                Nothing -> Left "Parquet.Write: auxiliary column metadata missing"
+                Just metadata
+                  | cmDataPageOffset metadata < 4 || cmTotalCompressedSize metadata < 0 ->
+                      Left "Parquet.Write: invalid auxiliary column bounds"
+                  | (caGeneratePageIndex aux || maybe False (const True) (caOffsetIndex aux) || maybe False (const True) (caColumnIndex aux))
+                      && cmTotalCompressedSize metadata > fromIntegral (maxBound :: Int32) ->
+                      Left "Parquet.Write: indexed page size exceeds signed 32-bit range"
+                  | otherwise -> Right ()
+          )
+          options
+    )
+    groups
+  let active aux = caGeneratePageIndex aux || maybe False (const True) (caBloomFilter aux) || maybe False (const True) (caOffsetIndex aux) || maybe False (const True) (caColumnIndex aux)
+  if not (V.any (V.any active) auxes)
+    then Right (ColumnAuxLayout groups [] start)
+    else layout
+  where
+    layout =
+      let (bloomGroups, blooms, bloomEnd) = layoutBlooms Nothing groups auxes start
+          (offsetGroups, offsets, offsetEnd) = layoutOffsetIndex Nothing bloomGroups auxes bloomEnd
+          (indexedGroups, indexes, end) = layoutColumnIndex Nothing offsetGroups auxes offsetEnd
+          parts = blooms ++ offsets ++ indexes
+          total = toInteger start + sum (map (toInteger . BS.length) parts)
+      in if total > toInteger (maxBound :: Int) || any ((> toInteger (maxBound :: Int32)) . toInteger . BS.length) parts
+           then Left "Parquet.Write: auxiliary regions exceed addressable file or signed 32-bit module lengths"
+           else Right (ColumnAuxLayout indexedGroups parts end)
+
+
+singlePageColumnIndex :: ColumnChunk -> Maybe ColumnIndex
+singlePageColumnIndex chunk = do
+  metadata <- ccMetadata chunk
+  statistics <- cmStatistics metadata
+  let allNull = statNullCount statistics == Just (cmNumValues metadata)
+  low <- if allNull then Just BS.empty else statMinValue statistics
+  high <- if allNull then Just BS.empty else statMaxValue statistics
+  pure
+    ColumnIndex
+      { ciNullPages = V.singleton allNull
+      , ciMinValues = V.singleton low
+      , ciMaxValues = V.singleton high
+      , ciBoundaryOrder = OrderUnordered
+      , ciNullCounts = V.singleton <$> statNullCount statistics
+      , ciNanCounts = V.singleton <$> statNanCount statistics
+      , ciRepetitionLevelHistograms = Nothing
+      , ciDefinitionLevelHistograms = Nothing
+      }
+
+
+-- Suppress unused-import warning when bloom-filter sizing helpers aren't
+-- referenced directly in the writer (they are part of the public API).
+_unusedBF :: Sbbf -> Int
+_unusedBF = BF.sbbfNumBytes
+
+
+-- Keep headers and payloads separate until the final file allocation.
+-- Joining each page first would copy every payload one extra time.
+data EncodedColumn = EncodedColumn
+  { ecParts :: ![ByteString]
+  , ecCompressedSize :: {-# UNPACK #-} !Int
+  , ecUncompressedSize :: {-# UNPACK #-} !Int
+  , ecCodec :: !Compression
+  }
+
+
+encodedColumn :: [ByteString] -> Int -> Compression -> EncodedColumn
+encodedColumn parts uncompressed codec =
+  EncodedColumn parts (sum (map BS.length parts)) uncompressed codec
+
+
+-- ============================================================
+-- Heterogeneous typed builders
+-- ============================================================
+
+{- | Build a complete Parquet file from a schema and one or more row
+groups of typed column data. Each leaf in the schema (i.e. each
+entry whose 'seType' is @Just@) must have a matching 'ColumnData'
+column in every row group, in the same order. Produces @PAR1@
+magic, uncompressed @PLAIN@ pages, footer, and trailing magic.
+
+Use 'buildParquetFileWithIndex' to additionally emit bloom filter,
+offset index, and column index regions.
+-}
+buildParquetFile
+  :: V.Vector SchemaElement
+  -> V.Vector (V.Vector ColumnData)
+  -> ByteString
+buildParquetFile schema rowGroups =
+  buildParquetFileWithIndex
+    schema
+    rowGroups
+    (V.map (V.map (const emptyColumnAux)) rowGroups)
+
+
+{- | Build a Parquet file with optional bloom filter, offset index,
+column index, and per-column compression. The 'ColumnAux' parallel
+array specifies what to emit for each column; 'emptyColumnAux'
+omits all extras.
+
+File layout:
+
+@
+PAR1                         -- 4 bytes
+<row group bytes ...>        -- compressed PLAIN data pages
+<bloom filter bitsets ...>   -- one per column with caBloomFilter = Just
+<offset index thrifts ...>   -- one per column with caOffsetIndex = Just
+<column index thrifts ...>   -- one per column with caColumnIndex = Just
+<footer>                     -- Thrift-encoded FileMetadata
+<footer length: int32 LE>
+PAR1
+@
+-}
+buildParquetFileWithIndex
+  :: V.Vector SchemaElement
+  -> V.Vector (V.Vector ColumnData)
+  -> V.Vector (V.Vector ColumnAux)
+  -> ByteString
+buildParquetFileWithIndex schema rowGroups auxes =
+  case validateRequiredLayout schema rowGroups auxes of
+    Left err -> error err
+    Right () ->
+      if V.any (V.any (maybe False (const True) . caEncryption)) auxes
+        then error "Parquet.Write: encryption requires buildParquetFileWithIndexIO and an encrypted footer"
+        else buildParquetFileWithIndex' Nothing Nothing BS.empty schema rowGroups auxes
+
+
+validateRequiredLayout
+  :: V.Vector SchemaElement
+  -> V.Vector (V.Vector ColumnData)
+  -> V.Vector (V.Vector ColumnAux)
+  -> Either String ()
+validateRequiredLayout schema groups auxes = do
+  V.mapM_ (V.mapM_ (Compress.validateCompression . caCodec)) auxes
+  V.mapM_ (V.mapM_ validateAuxIndexes) auxes
+  if V.null schema || seType (V.head schema) /= Nothing
+    then Left "Parquet.Write: schema must start with a group root"
+    else Right ()
+  let leaves = V.tail schema
+  if seNumChildren (V.head schema) /= Just (fromIntegral (V.length leaves))
+    then Left "Parquet.Write: flat schema root child count does not match its fields"
+    else Right ()
+  V.mapM_
+    ( \leaf ->
+        if seType leaf == Nothing || seNumChildren leaf /= Nothing || seRepetition leaf /= Just Required
+          then Left "Parquet.Write: required writer needs flat required fields; use the mixed or nested writer"
+          else
+            if not (hasCompatiblePhysicalType leaf)
+              then Left "Parquet.Write: logical annotation has incompatible physical storage"
+              else Right ()
+    )
+    leaves
+  if V.length auxes > V.length groups
+    then Left "Parquet.Write: auxiliary metadata has extra row groups"
+    else Right ()
+  V.imapM_
+    ( \rg cols -> do
+        if V.length cols /= V.length leaves
+          then Left "Parquet.Write: column count does not match schema"
+          else Right ()
+        if rg < V.length auxes && V.length (auxes V.! rg) > V.length cols
+          then Left "Parquet.Write: auxiliary metadata has extra columns"
+          else Right ()
+        let count = if V.null cols then 0 else columnDataLength (V.head cols)
+        if count > fromIntegral (maxBound :: Int32)
+          then Left "Parquet.Write: row count exceeds a single page's 32-bit limit"
+          else Right ()
+        V.imapM_
+          ( \col values ->
+              if columnDataLength values /= count
+                then Left "Parquet.Write: columns in a row group have different lengths"
+                else
+                  if seType (leaves V.! col) /= Just (columnDataParquetType values)
+                    then Left "Parquet.Write: column physical type does not match schema"
+                    else validateLogicalColumn (leaves V.! col) values
+          )
+          cols
+    )
+    groups
+
+
+{- | Configuration for encrypted-footer mode (see
+'buildParquetFileWithIndexEncryptedFooter'). Encapsulates the AES
+key plus the AAD context so the writer can produce the
+@ModuleFooter@ ciphertext that the parquet-format spec requires.
+-}
+data FooterEncryption = FooterEncryption
+  { feKey :: !ByteString
+  -- ^ AES key (16, 24, or 32 bytes).
+  , feFileId :: !ByteString
+  -- ^ Fresh random file identifier. Generate a new value for every file.
+  , feAadPrefix :: !ByteString
+  -- ^ Caller AAD prefix (typically empty).
+  , feKeyMetadata :: !ByteString
+  {- ^ Opaque KMS handle to record on the file. Round-trips
+  verbatim through the encrypted-footer trailer; readers feed it
+  back to their KMS to recover the key.
+  -}
+  }
+  deriving (Show, Eq)
+
+
+{- | Create a footer configuration with a fresh random file identifier.
+Call once per output file, including when reusing the same encryption key.
+-}
+newFooterEncryption
+  :: RNG.MonadRandom m
+  => ByteString -> ByteString -> ByteString -> m FooterEncryption
+newFooterEncryption key prefix metadata = do
+  fileId <- RNG.getRandomBytes 8
+  pure (FooterEncryption key fileId prefix metadata)
+
+
+{- | Encode a 'FooterEncryption' as the @FileCryptoMetaData@ thrift
+struct the encrypted-footer mode prepends to the encrypted footer
+(parquet-format Encryption.md §5.2). Only the algorithm + key
+metadata + AAD prefix are emitted; the encryption itself is in the
+module that follows this struct.
+-}
+fileCryptoMetaDataToThrift :: Enc.EncryptionAlgorithm -> FooterEncryption -> TV.Value
+fileCryptoMetaDataToThrift algorithm fe =
+  TV.Struct $
+    V.fromList
+      [ FileCryptoMetaData_EncryptionAlgorithm (encryptionAlgorithmFields algorithm fe)
+      , FileCryptoMetaData_KeyMetadata (feKeyMetadata fe)
+      ]
+
+
+-- The file algorithm selects GCM versus CTR for all encrypted page
+-- bodies; headers, indexes, and the footer always use GCM.
+encryptionAlgorithmFields
+  :: Enc.EncryptionAlgorithm -> FooterEncryption -> V.Vector (Int16, TV.Value)
+encryptionAlgorithmFields algorithm fe =
+  V.singleton $ case algorithm of
+    Enc.AesGcmV1 -> EncryptionAlgorithm_AesGcmV1 (aesGcmV1Fields fe)
+    Enc.AesGcmCtrV1 -> EncryptionAlgorithm_AesGcmCtrV1 (aesGcmV1Fields fe)
+
+
+aesGcmV1Fields :: FooterEncryption -> V.Vector (Int16, TV.Value)
+aesGcmV1Fields fe =
+  V.fromList $
+    concat
+      [ optNonEmpty (feAadPrefix fe) AesGcmV1_AadPrefix
+      , optNonEmpty (feFileId fe) AesGcmV1_AadFileUnique
+      ]
+  where
+    optNonEmpty bs mk
+      | BS.null bs = []
+      | otherwise = [mk bs]
+
+
+{- | Build a Parquet file with an /encrypted footer/. Identical to
+'buildParquetFileWithIndex' for the row-group + bloom / offset /
+column index regions, but the trailing footer is wrapped as a
+single AES-GCM module under @ModuleFooter@ AAD and the file ends
+with the @PARE@ magic instead of @PAR1@.
+
+This is the parquet-format "encrypted-footer" file mode (the
+alternative to the "plaintext-footer" mode where the column
+payloads are encrypted but the footer stays in the clear).
+Iceberg's encryption configuration emits encrypted-footer files
+when @write.encryption.encrypt-footer@ is true.
+-}
+buildParquetFileWithIndexEncryptedFooter
+  :: RNG.MonadRandom m
+  => FooterEncryption
+  -> V.Vector SchemaElement
+  -> V.Vector (V.Vector ColumnData)
+  -> V.Vector (V.Vector ColumnAux)
+  -> m (Either String ByteString)
+buildParquetFileWithIndexEncryptedFooter fe = buildParquetFileRandom (Just fe)
+
+
+{- | Build with fresh random module nonces. Encryption errors return 'Left';
+an invalid key never falls back to plaintext. Pure callers must use
+'buildParquetFileWithIndex' without encryption.
+-}
+buildParquetFileWithIndexIO
+  :: RNG.MonadRandom m
+  => V.Vector SchemaElement
+  -> V.Vector (V.Vector ColumnData)
+  -> V.Vector (V.Vector ColumnAux)
+  -> m (Either String ByteString)
+buildParquetFileWithIndexIO = buildParquetFileRandom Nothing
+
+
+buildParquetFileRandom
+  :: RNG.MonadRandom m
+  => Maybe FooterEncryption
+  -> V.Vector SchemaElement
+  -> V.Vector (V.Vector ColumnData)
+  -> V.Vector (V.Vector ColumnAux)
+  -> m (Either String ByteString)
+buildParquetFileRandom footer schema groups auxes =
+  case validateEncryption of
+    Left err -> pure (Left err)
+    Right () -> do
+      nonces <- V.mapM (V.mapM (const (RNG.getRandomBytes 72))) groups
+      footerNonce <- RNG.getRandomBytes 12
+      pure
+        ( Right
+            ( buildParquetFileWithIndex'
+                footer
+                (Just (EncryptionNonces nonces))
+                footerNonce
+                schema
+                groups
+                auxes
+            )
+        )
+  where
+    validKey key
+      | BS.length key `elem` [16, 24, 32] = Right ()
+      | otherwise = Left "Parquet.Write: AES key must contain 16, 24, or 32 bytes"
+    validateEncryption = do
+      validateRequiredLayout schema groups auxes
+      maybe (Right ()) (validKey . feKey) footer
+      case footer of
+        Just fe | BS.null (feFileId fe) -> Left "Parquet.Write: encrypted footer requires a fresh random file identifier"
+        _ -> Right ()
+      V.imapM_ (\rg cols -> V.imapM_ (checkColumn rg) cols) auxes
+      -- Reject an oversized schema or KMS/AAD metadata before nonces, page
+      -- buffers, UTF8 conversion, or encryption are allocated. Final metadata
+      -- is measured again once row-group offsets and crypto fields are known.
+      case footer of
+        Nothing -> Right ()
+        Just fe -> do
+          let fm = FileMetadata 1 schema 0 V.empty Nothing Nothing Nothing
+          _ <-
+            encryptedFooterSizes
+              (fileCryptoMetaDataToThrift (fileEncryptionAlgorithm auxes) fe)
+              (fileMetadataToThrift fm)
+          Right ()
+    checkColumn rg col aux = case caEncryption aux of
+      Nothing -> Right ()
+      Just ce
+        | rg > 32767 || col > 32767 -> Left "Parquet.Write: encryption ordinal exceeds signed 16-bit range"
+        | otherwise -> do
+            validKey (ceKey ce)
+            case footer of
+              Nothing -> Left "Parquet.Write: encrypted columns require an encrypted footer; plaintext-footer signing is not supported"
+              Just fe
+                | ceKey ce /= feKey fe -> Left "Parquet.Write: separate column keys are not supported"
+                | ceFileId ce /= feFileId fe || ceAadPrefix ce /= feAadPrefix fe ->
+                    Left "Parquet.Write: column and footer AAD contexts must match"
+                | ceAlgorithm ce /= fileEncryptionAlgorithm auxes ->
+                    Left "Parquet.Write: encrypted columns must use one file-level algorithm"
+                | otherwise -> Right ()
+
+
+fileEncryptionAlgorithm :: V.Vector (V.Vector ColumnAux) -> Enc.EncryptionAlgorithm
+fileEncryptionAlgorithm auxes =
+  fromMaybe Enc.AesGcmV1 $
+    V.foldl'
+      ( \found cols -> case found of
+          Just _ -> found
+          Nothing ->
+            V.foldl'
+              ( \acc aux -> case acc of
+                  Just _ -> acc
+                  Nothing -> ceAlgorithm <$> caEncryption aux
+              )
+              Nothing
+              cols
+      )
+      Nothing
+      auxes
+
+
+-- The public metadata model omits crypto fields. Add the standardized
+-- footer-key marker and row-group ordinals at the Thrift serialization
+-- seam, after every index/bloom offset has reached its final value.
+footerMetadataWithCrypto
+  :: V.Vector (V.Vector ColumnAux) -> FileMetadata -> TV.Value
+footerMetadataWithCrypto auxes fm = case fileMetadataToThrift fm of
+  TV.Struct fields -> TV.Struct (V.map rewriteFile fields)
+  value -> value
+  where
+    rewriteFile (FileMetadata_RowGroups groups) =
+      FileMetadata_RowGroups (V.imap rewriteGroup groups)
+    rewriteFile field = field
+    rewriteGroup rg (TV.Struct fields) =
+      TV.Struct $
+        V.snoc (V.map (rewriteGroupField rg) fields) (RowGroup_Ordinal (fromIntegral rg))
+    rewriteGroup _ value = value
+    rewriteGroupField rg (RowGroup_Columns cols) =
+      RowGroup_Columns (V.imap (rewriteColumn rg) cols)
+    rewriteGroupField _ field = field
+    rewriteColumn rg col (TV.Struct fields)
+      | rg < V.length auxes
+      , col < V.length (auxes V.! rg)
+      , Just _ <- caEncryption (auxes V.! rg V.! col) =
+          TV.Struct
+            ( V.snoc
+                fields
+                ( ColumnChunk_CryptoMetadata
+                    (V.singleton (ColumnCryptoMetaData_EncryptionWithFooterKey V.empty))
+                )
+            )
+    rewriteColumn _ _ value = value
+
+
+-- Framed GCM adds a four-byte length, twelve-byte nonce and sixteen-byte
+-- authentication tag. The outer footer length covers this and crypto metadata.
+data EncryptedFooterSizes = EncryptedFooterSizes
+  { efsCryptoBytes :: {-# UNPACK #-} !Int
+  , efsPlainBytes :: {-# UNPACK #-} !Int
+  }
+
+
+encryptedFooterSizes :: TV.Value -> TV.Value -> Either String EncryptedFooterSizes
+encryptedFooterSizes cryptoValue plainValue = do
+  let limit = fromInteger (min (toInteger (maxBound :: Word32)) (toInteger (maxBound :: Int) - 8))
+  cryptoSize <- compactEncodedSizeBounded (limit - 32) cryptoValue
+  plainSize <- compactEncodedSizeBounded (limit - 32 - cryptoSize) plainValue
+  Right (EncryptedFooterSizes cryptoSize plainSize)
+
+
+buildParquetFileWithIndex'
+  :: Maybe FooterEncryption
+  -> Maybe EncryptionNonces
+  -> ByteString
+  -> V.Vector SchemaElement
+  -> V.Vector (V.Vector ColumnData)
+  -> V.Vector (V.Vector ColumnAux)
+  -> ByteString
+buildParquetFileWithIndex' mFootEnc nonces footerNonce schema rowGroups auxes =
+  let
+    -- Per-column page bytes plus uncompressed size, both required to
+    -- populate ColumnMetadata. Unsupported codecs are rejected by validation.
+    !encodedRGs = V.imap encodeRG rowGroups
+    !rowGroupBytes = concatMap (concatMap ecParts . V.toList) (V.toList encodedRGs)
+    !rgBytesLen = sum (map BS.length rowGroupBytes)
+    !startOfData = 4 :: Int
+    !startOfBloom = startOfData + rgBytesLen
+
+    (!rgMetasBase, _) = V.ifoldl' buildRG (V.empty, startOfData) encodedRGs
+
+    (!rgMetasBloom, !bloomBytes, !endOfBloom) =
+      layoutBlooms nonces rgMetasBase auxes startOfBloom
+
+    (!rgMetasOff, !offBytes, !endOfOff) =
+      layoutOffsetIndex
+        nonces
+        rgMetasBloom
+        auxes
+        endOfBloom
+
+    (!rgMetasCol, !colBytes, _endOfCol) =
+      layoutColumnIndex nonces rgMetasOff auxes endOfOff
+
+    !totalRows = V.foldl' (\a rg -> a + rgNumRows rg) 0 rgMetasCol
+    !fm =
+      FileMetadata
+        { fmVersion = 1
+        , fmSchema = schema
+        , fmNumRows = totalRows
+        , fmRowGroups = rgMetasCol
+        , fmCreatedBy = Just "wireform"
+        , fmKeyValueMetadata = Nothing
+        , fmColumnOrders = Just (V.replicate (V.length leaves) TypeDefinedOrder)
+        }
+    -- Encrypted-footer mode (parquet-format Encryption.md §5.4):
+    --
+    --   <FileCryptoMetaData thrift>
+    --   <encrypted footer module: nonce || ct || tag>
+    --   <combined-length: i32 LE>     -- of the two blobs above
+    --   PARE
+    --
+    -- The footer module retains its section 5.1 length framing; the
+    -- trailing combined length also includes FileCryptoMetaData.
+    !footerBytes = case mFootEnc of
+      Nothing -> writeFooter fm
+      Just fe -> either error id $ do
+        let cryptoValue = fileCryptoMetaDataToThrift (fileEncryptionAlgorithm auxes) fe
+            plainValue = footerMetadataWithCrypto auxes fm
+        sizes <- encryptedFooterSizes cryptoValue plainValue
+        -- Both metadata trees fit before either output buffer is allocated.
+        cryptoMeta <- encodeCompactBounded (efsCryptoBytes sizes) cryptoValue
+        plainThrift <- encodeCompactBounded (efsPlainBytes sizes) plainValue
+        let suffix = Enc.buildAadSuffix (feFileId fe) Enc.ModuleFooter 0 0 0
+            aad = Enc.buildAad (feAadPrefix fe) suffix
+        encModule <- Enc.encryptGcmModuleFramedWithNonce (feKey fe) footerNonce aad plainThrift
+        writeRawFooterEither parquetEncryptedMagic (cryptoMeta <> encModule)
+  in
+    BS.concat ((maybe parquetMagic (const parquetEncryptedMagic) mFootEnc) : rowGroupBytes ++ bloomBytes ++ offBytes ++ colBytes ++ [footerBytes])
+  where
+    encryptedHeaderSize ce plainBodySize bytes =
+      BS.length bytes - plainBodySize - case ceAlgorithm ce of
+        Enc.AesGcmV1 -> 32 -- module length + nonce + tag
+        Enc.AesGcmCtrV1 -> 16 -- module length + nonce
+    pageNonces rg col =
+      moduleNonce nonces rg col Enc.ModuleDataPageHeader
+        <> moduleNonce nonces rg col Enc.ModuleDataPage
+    !leaves = V.filter (maybe False (const True) . seType) schema
+
+    -- Encode each column's page, then compress it with the codec the
+    -- caller requested via the matching ColumnAux. Returns the *final*
+    -- bytes that go into the file plus the uncompressed size.
+    encodeRG :: Int -> V.Vector ColumnData -> V.Vector EncodedColumn
+    encodeRG rgIdx colsData =
+      let !aux = if rgIdx < V.length auxes then V.unsafeIndex auxes rgIdx else V.empty
+      in V.imap (encodeOne rgIdx aux) colsData
+
+    encodeOne
+      :: Int -> V.Vector ColumnAux -> Int -> ColumnData -> EncodedColumn
+    encodeOne rgIdx aux cIdx cd =
+      let !mAux =
+            if cIdx < V.length aux
+              then Just (V.unsafeIndex aux cIdx)
+              else Nothing
+          !codecRequested = maybe Uncompressed caCodec mAux
+          !pageVer = maybe PageV1 caPageVersion mAux
+          !mEnc = mAux >>= caEncryption
+      in case pageVer of
+           PageV1 ->
+             let !body = encodeColumnDataPagePayload cd
+                 (compBody, cActual) = case Compress.compressPageBytes codecRequested body of
+                   Right cb -> (cb, codecRequested)
+                   Left err -> error err
+                 -- Re-encode the header now that the body has its
+                 -- compressed size; the header records the on-disk
+                 -- compressed_page_size so the reader can frame pages
+                 -- without scanning forward.
+                 !n = columnDataLength cd
+                 !hdr' =
+                   encodePageHeader
+                     ( PageHeader
+                         { phType =
+                             PtDataPage
+                               DataPageHeader
+                                 { dphNumValues = fromIntegral n
+                                 , dphEncoding = 0
+                                 }
+                         , phUncompressedPageSize = Just (fromIntegral (BS.length body))
+                         , phCompressedPageSize = Just (either error id (pageInt32 "compressed page size" (BS.length compBody)))
+                         }
+                     )
+                 !uncompSz = BS.length hdr' + BS.length body
+             in case mEnc of
+                  Nothing ->
+                    encodedColumn [hdr', compBody] uncompSz cActual
+                  Just ce ->
+                    case encryptPageBytesWithNonces
+                      (pageNonces rgIdx cIdx)
+                      ce {ceColumnOrdinal = cIdx}
+                      Enc.ModuleDataPage
+                      rgIdx
+                      0
+                      hdr'
+                      compBody of
+                      Right encBytes ->
+                        encodedColumn [encBytes] (BS.length body + encryptedHeaderSize ce (BS.length compBody) encBytes) cActual
+                      Left err -> error ("Parquet.Write: page encryption failed: " ++ err)
+           PageV2 ->
+             -- For V2 the codec is applied only to the values segment,
+             -- but we account for the *full* page bytes (header +
+             -- segments) when recording sizes on the column metadata so
+             -- that ccTotalCompressedSize / ccTotalUncompressedSize
+             -- reflect on-disk reality.
+             let finish codecActual page =
+                   let !h = erv2Header page
+                       !v = erv2Values page
+                       !uncompSz = BS.length h + erv2UncompressedSize page
+                   in case mEnc of
+                        Nothing -> encodedColumn [h, v] uncompSz codecActual
+                        Just ce -> case encryptPageBytesWithNonces
+                          (pageNonces rgIdx cIdx)
+                          ce {ceColumnOrdinal = cIdx}
+                          Enc.ModuleDataPage
+                          rgIdx
+                          0
+                          h
+                          v of
+                          Right enc ->
+                            encodedColumn
+                              [enc]
+                              (erv2UncompressedSize page + encryptedHeaderSize ce (BS.length v) enc)
+                              codecActual
+                          Left err -> error ("Parquet.Write: page encryption failed: " ++ err)
+             in case encodeRequiredV2 codecRequested cd of
+                  Right page -> finish codecRequested page
+                  Left err -> error err
+
+    buildRG
+      :: (V.Vector RowGroup, Int)
+      -> Int
+      -> V.Vector EncodedColumn
+      -> (V.Vector RowGroup, Int)
+    buildRG (!rgs, !off) rgIdx encodedCols =
+      let !colsData = V.unsafeIndex rowGroups rgIdx
+          (!cols, !off2) = V.ifoldl' (buildCol colsData) (V.empty, off) encodedCols
+          !nRows =
+            if V.null colsData
+              then 0
+              else fromIntegral (columnDataLength (V.unsafeIndex colsData 0))
+          !rg =
+            RowGroup
+              { rgColumns = cols
+              , rgTotalByteSize = V.foldl' (\total column -> total + fromIntegral (ecUncompressedSize column)) 0 encodedCols
+              , rgNumRows = nRows
+              , rgSortingColumns = Nothing
+              }
+      in (V.snoc rgs rg, off2)
+
+    buildCol
+      :: V.Vector ColumnData
+      -> (V.Vector ColumnChunk, Int)
+      -> Int
+      -> EncodedColumn
+      -> (V.Vector ColumnChunk, Int)
+    buildCol colsData (!cs, !cOff) colIdx encoded =
+      let !cd = V.unsafeIndex colsData colIdx
+          !leaf = V.unsafeIndex leaves colIdx
+          !sz = ecCompressedSize encoded
+          !uncompSize = ecUncompressedSize encoded
+          !codec = ecCodec encoded
+          !cc =
+            ColumnChunk
+              { ccFilePath = Nothing
+              , ccFileOffset = 0
+              , ccMetadata =
+                  Just
+                    ColumnMetadata
+                      { cmType = fromMaybe (columnDataParquetType cd) (seType leaf)
+                      , cmEncodings = V.singleton Plain
+                      , cmPathInSchema = V.singleton (seName leaf)
+                      , cmCodec = codec
+                      , cmNumValues = fromIntegral (columnDataLength cd)
+                      , cmTotalUncompressedSize = fromIntegral uncompSize
+                      , cmTotalCompressedSize = fromIntegral sz
+                      , cmDataPageOffset = fromIntegral cOff
+                      , cmDictionaryPageOffset = Nothing
+                      , cmStatistics = Just (columnStatisticsForSchema leaf cd)
+                      , cmBloomFilterOffset = Nothing
+                      , cmBloomFilterLength = Nothing
+                      }
+              , ccOffsetIndexOffset = Nothing
+              , ccOffsetIndexLength = Nothing
+              , ccColumnIndexOffset = Nothing
+              , ccColumnIndexLength = Nothing
+              }
+      in (V.snoc cs cc, cOff + sz)
+
+
+-- ============================================================
+-- Mixed required + optional columns
+-- ============================================================
+
+{- | Sum of the two column-data shapes the writer can emit:
+plain @ColumnData@ (required leaf columns) and
+@OptionalColumn@ (nullable leaf columns with definition
+levels). The 'buildParquetFileMixed' entrypoint below accepts
+a @V.Vector ParquetColumn@ per row group so callers can mix
+nullable and non-nullable leaves in the same file without
+dropping to the page-level builders.
+-}
+data ParquetColumn
+  = -- | A required (non-null) column.
+    PCRequired !ColumnData
+  | {- | A nullable column. Encoded as @DATA_PAGE_V1@ with a
+    definition-level stream followed by present-only values.
+    -}
+    PCOptional !OptionalColumn
+  deriving (Show, Eq)
+
+
+parquetColumnLength :: ParquetColumn -> Int
+parquetColumnLength = \case
+  PCRequired cd -> columnDataLength cd
+  PCOptional oc -> optionalColumnLength oc
+
+
+parquetColumnParquetType :: ParquetColumn -> ParquetType
+parquetColumnParquetType = \case
+  PCRequired cd -> columnDataParquetType cd
+  PCOptional oc -> case oc of
+    OptInt32 {} -> PTInt32
+    OptInt64 {} -> PTInt64
+    OptFloat {} -> PTFloat
+    OptDouble {} -> PTDouble
+    OptBool {} -> PTBoolean
+    OptByteArray {} -> PTByteArray
+
+
+parquetColumnStatistics :: SchemaElement -> ParquetColumn -> ColumnData -> Statistics
+parquetColumnStatistics leaf source present =
+  let stats = columnStatisticsForSchema leaf present
+  in case source of
+       PCRequired _ -> stats
+       PCOptional column -> stats {statNullCount = Just (fromIntegral (optionalColumnLength column - columnDataLength present))}
+
+
+{- | Page-encode one mixed column. Uncompressed @DATA_PAGE_V1@
+for both variants; the simpler readers in
+"Parquet.Read" expect that shape. Returns
+@(pageBytes, uncompressedSize)@ so the row-group builder can
+stamp the matching @ColumnMetadata@ offsets.
+-}
+encodeMixedPageV1 :: ParquetColumn -> ColumnData -> Either String (ByteString, Int)
+encodeMixedPageV1 source present = case source of
+  PCRequired cd -> do
+    (hdr, body) <- encodeColumnDataPagePartsChecked cd
+    Right (BS.append hdr body, BS.length hdr + BS.length body)
+  PCOptional oc -> do
+    pg <- encodeOptionalPagePrepared oc present
+    Right (pg, BS.length pg)
+
+
+{- | Compression-aware mixed page encoder. Compresses the page
+/body/ (header stays plaintext) and rewrites the page header
+with the new compressed_page_size so the round-trip readers
+in "Parquet.Read" can decompress on the way back.
+-}
+encodeMixedPageV1With
+  :: Compression -> ParquetColumn -> ColumnData -> Either String (ByteString, Int)
+encodeMixedPageV1With Uncompressed col present = encodeMixedPageV1 col present
+encodeMixedPageV1With codec col present = do
+  (uncompPage, _) <- encodeMixedPageV1 col present
+  -- Layout is [PageHeader thrift][body]; re-encode the header
+  -- with a compressed size matching the compressed body, then
+  -- stitch the two together.
+  (hdr, afterHdr) <- readPageHeaderAt uncompPage 0
+  let !body = BS.drop afterHdr uncompPage
+  compBody <- compressPageBytes codec body
+  compressedSize <- pageInt32 "compressed page size" (BS.length compBody)
+  let !newHdr = hdr {phCompressedPageSize = Just compressedSize}
+      !hdrBs = encodePageHeader newHdr
+      !page = hdrBs <> compBody
+  Right (page, BS.length hdrBs + BS.length body)
+
+
+{- | Assemble a Parquet file from a flat schema + row groups
+where each column is either required ('PCRequired') or
+nullable ('PCOptional'). Unlike 'buildParquetFileWithIndex',
+no bloom filters / page indexes / encryption are emitted
+here; this is the fast path used by the Arrow <-> Parquet
+bridge when any leaf column is nullable.
+
+Output format:
+
+@
+PAR1
+\<page bytes per (row-group × column)\>
+\<footer thrift (FileMetadata)\>
+\<footer length : i32 LE\>
+PAR1
+@
+-}
+buildParquetFileMixed
+  :: V.Vector SchemaElement
+  -> V.Vector (V.Vector ParquetColumn)
+  -> ByteString
+buildParquetFileMixed schema groups =
+  either error id (buildParquetFileMixedWith Uncompressed schema groups)
+
+
+-- | Encode flat required/nullable V1 pages with a uniform codec.
+buildParquetFileMixedWith
+  :: Compression
+  -> V.Vector SchemaElement
+  -> V.Vector (V.Vector ParquetColumn)
+  -> Either String ByteString
+buildParquetFileMixedWith codec schema groups = do
+  Compress.validateCompression codec
+  buildParquetFileMixedWithAux
+    schema
+    groups
+    (V.map (V.map (const (emptyColumnAux {caCodec = codec}))) groups)
+
+
+validateMixedLayout
+  :: V.Vector SchemaElement
+  -> V.Vector (V.Vector ParquetColumn)
+  -> V.Vector (V.Vector ColumnAux)
+  -> V.Vector (V.Vector ColumnData)
+  -> Either String ()
+validateMixedLayout schema groups auxes presentRows = do
+  V.mapM_ (V.mapM_ (Compress.validateCompression . caCodec)) auxes
+  V.mapM_ (V.mapM_ validateAuxIndexes) auxes
+  if V.null schema || seType (V.head schema) /= Nothing
+    then Left "Parquet.Write: mixed schema must start with a group root"
+    else Right ()
+  let leaves = V.tail schema
+  if seNumChildren (V.head schema) /= Just (fromIntegral (V.length leaves))
+    || V.any
+      ( \leaf ->
+          seType leaf == Nothing
+            || seNumChildren leaf /= Nothing
+            || seRepetition leaf `notElem` [Just Required, Just Optional]
+            || not (hasCompatiblePhysicalType leaf)
+      )
+      leaves
+    then Left "Parquet.Write: mixed writer needs a flat required/optional schema"
+    else Right ()
+  if V.length groups /= V.length auxes
+    then Left "Parquet.Write: mixed auxiliary row-group count mismatch"
+    else Right ()
+  V.imapM_
+    ( \rg cols -> do
+        if V.length cols /= V.length leaves || V.length (auxes V.! rg) /= V.length cols
+          then Left "Parquet.Write: mixed column/auxiliary count does not match schema"
+          else Right ()
+        let count = if V.null cols then 0 else parquetColumnLength (V.head cols)
+        if count > fromIntegral (maxBound :: Int32)
+          then Left "Parquet.Write: mixed row count exceeds signed 32-bit page limit"
+          else Right ()
+        V.imapM_
+          ( \col values -> do
+              let leaf = leaves V.! col
+                  repetition = case values of PCRequired {} -> Required; PCOptional {} -> Optional
+              if parquetColumnLength values /= count
+                || seType leaf /= Just (parquetColumnParquetType values)
+                || seRepetition leaf /= Just repetition
+                then Left "Parquet.Write: mixed column length/type/nullability does not match schema"
+                else
+                  validateLogicalColumn leaf (presentRows V.! rg V.! col)
+              case caEncryption (auxes V.! rg V.! col) of
+                Just _ -> Left "Parquet.Write: mixed column encryption is not supported"
+                Nothing -> Right ()
+          )
+          cols
+    )
+    groups
+
+
+encodeMixedColumn :: ColumnAux -> ParquetColumn -> ColumnData -> Either String EncodedColumn
+encodeMixedColumn aux values present = case caPageVersion aux of
+  PageV1 -> do
+    (bytes, uncompressed) <- encodeMixedPageV1With (caCodec aux) values present
+    Right (encodedColumn [bytes] uncompressed (caCodec aux))
+  PageV2 -> case values of
+    PCRequired column -> do
+      page <- encodeRequiredV2 (caCodec aux) column
+      Right
+        ( encodedColumn
+            [erv2Header page, erv2Values page]
+            (BS.length (erv2Header page) + erv2UncompressedSize page)
+            (caCodec aux)
+        )
+    PCOptional column -> do
+      page <- encodeOptionalV2Prepared (caCodec aux) column present
+      Right
+        ( encodedColumn
+            [eov2Header page, eov2Repetitions page, eov2Definitions page, eov2Values page]
+            (BS.length (eov2Header page) + eov2UncompressedSize page)
+            (caCodec aux)
+        )
+
+
+{- | Flat required/nullable writer honoring each column's codec, page
+version, bloom filter and indexes. Encryption requires the separate
+encrypted writer and is explicitly rejected here.
+-}
+buildParquetFileMixedWithAux
+  :: V.Vector SchemaElement
+  -> V.Vector (V.Vector ParquetColumn)
+  -> V.Vector (V.Vector ColumnAux)
+  -> Either String ByteString
+buildParquetFileMixedWithAux schema groups auxes =
+  buildParquetFileMixedWithAuxUsing
+    (\fm parts -> BS.concat (parquetMagic : parts ++ [writeFooter fm]))
+    schema groups (const auxes)
+
+
+-- | Assemble a validated mixed writer's pages and metadata directly. This
+-- lets encrypted writers consume the metadata without serializing a footer
+-- only to decode it again.
+buildParquetFileMixedWithAuxUsing
+  :: (FileMetadata -> [ByteString] -> a)
+  -> V.Vector SchemaElement
+  -> V.Vector (V.Vector ParquetColumn)
+  -> (V.Vector (V.Vector ColumnData) -> V.Vector (V.Vector ColumnAux))
+  -> Either String a
+buildParquetFileMixedWithAuxUsing finish schema rowGroups makeAuxes = do
+  let presentRows = V.map (V.map (\case PCRequired values -> values; PCOptional values -> optionalColumnPresentValues values)) rowGroups
+      auxes = makeAuxes presentRows
+  validateMixedLayout schema rowGroups auxes presentRows
+  encodedRGs <-
+    V.imapM
+      ( \rg columns ->
+          V.imapM
+            ( \col values ->
+                encodeMixedColumn (auxes V.! rg V.! col) values (presentRows V.! rg V.! col)
+            )
+            columns
+      )
+      rowGroups
+  let !leaves = V.tail schema
+      !allPageBytes = concatMap (concatMap ecParts . V.toList) (V.toList encodedRGs)
+      !startOfData = 4 :: Int
+      -- One RowGroup metadata per input group.
+      (!rgMetasBase, !endOfData) =
+        V.ifoldl'
+          ( \(!rgs, !off) rgIdx encoded ->
+              let !colsData = V.unsafeIndex rowGroups rgIdx
+                  (!chunks, !off') =
+                    V.ifoldl' (buildChunk colsData (presentRows V.! rgIdx)) (V.empty, off) encoded
+                  !nRows =
+                    if V.null colsData
+                      then 0
+                      else fromIntegral (parquetColumnLength (V.unsafeIndex colsData 0))
+                  !rg =
+                    RowGroup
+                      { rgColumns = chunks
+                      , rgTotalByteSize = V.foldl' (\total column -> total + fromIntegral (ecUncompressedSize column)) 0 encoded
+                      , rgNumRows = nRows
+                      , rgSortingColumns = Nothing
+                      }
+              in (V.snoc rgs rg, off')
+          )
+          (V.empty, startOfData)
+          encodedRGs
+
+      (!rgMetasBloom, !bloomBytes, !endOfBloom) = layoutBlooms Nothing rgMetasBase auxes endOfData
+      (!rgMetasOff, !offsetBytes, !endOfOffset) = layoutOffsetIndex Nothing rgMetasBloom auxes endOfBloom
+      (!rgMetas, !columnBytes, _) = layoutColumnIndex Nothing rgMetasOff auxes endOfOffset
+      !totalRows = V.foldl' (\a rg -> a + rgNumRows rg) 0 rgMetas
+      !fm =
+        FileMetadata
+          { fmVersion = 1
+          , fmSchema = schema
+          , fmNumRows = totalRows
+          , fmRowGroups = rgMetas
+          , fmCreatedBy = Just "wireform"
+          , fmKeyValueMetadata = Nothing
+          , fmColumnOrders = Just (V.replicate (V.length leaves) TypeDefinedOrder)
+          }
+  Right (finish fm (allPageBytes ++ bloomBytes ++ offsetBytes ++ columnBytes))
+  where
+    !leaves' = V.filter (maybe False (const True) . seType) schema
+
+    buildChunk
+      :: V.Vector ParquetColumn
+      -> V.Vector ColumnData
+      -> (V.Vector ColumnChunk, Int)
+      -> Int
+      -> EncodedColumn
+      -> (V.Vector ColumnChunk, Int)
+    buildChunk colsData presentColumns (!cs, !cOff) colIdx encoded =
+      let !cd = V.unsafeIndex colsData colIdx
+          !leaf = V.unsafeIndex leaves' colIdx
+          !sz = ecCompressedSize encoded
+          !uncompSize = ecUncompressedSize encoded
+          !cc =
+            ColumnChunk
+              { ccFilePath = Nothing
+              , ccFileOffset = 0
+              , ccMetadata =
+                  Just
+                    ColumnMetadata
+                      { cmType = fromMaybe (parquetColumnParquetType cd) (seType leaf)
+                      , cmEncodings = case cd of
+                          PCRequired {} -> V.singleton Plain
+                          PCOptional {} -> V.fromList [Plain, RLE]
+                      , cmPathInSchema = V.singleton (seName leaf)
+                      , cmCodec = ecCodec encoded
+                      , cmNumValues = fromIntegral (parquetColumnLength cd)
+                      , cmTotalUncompressedSize = fromIntegral uncompSize
+                      , cmTotalCompressedSize = fromIntegral sz
+                      , cmDataPageOffset = fromIntegral cOff
+                      , cmDictionaryPageOffset = Nothing
+                      , cmStatistics = Just (parquetColumnStatistics leaf cd (presentColumns V.! colIdx))
+                      , cmBloomFilterOffset = Nothing
+                      , cmBloomFilterLength = Nothing
+                      }
+              , ccOffsetIndexOffset = Nothing
+              , ccOffsetIndexLength = Nothing
+              , ccColumnIndexOffset = Nothing
+              , ccColumnIndexLength = Nothing
+              }
+      in (V.snoc cs cc, cOff + sz)
+
+
+-- ============================================================
+-- Size statistics
+-- ============================================================
+
+{- | Per-page unencoded byte counts for a BYTE_ARRAY column.
+Used to populate 'OffsetIndex.oiUnencodedByteArrayDataBytes'
+(parquet-format 2.11). For non-BYTE_ARRAY columns returns
+'Nothing'.
+
+The unit is /unencoded bytes/ — for PLAIN-encoded BYTE_ARRAY
+pages that's the sum of value lengths (not including the
+4-byte length prefixes the wire format adds).
+-}
+columnDataUnencodedByteArrayBytes
+  :: ColumnData
+  -> Maybe Int64
+columnDataUnencodedByteArrayBytes = \case
+  ColByteArray vs ->
+    Just $! V.foldl' (\a bs -> a + fromIntegral (BS.length bs)) 0 vs
+  _ -> Nothing
+
+
+{- | Attach 'oiUnencodedByteArrayDataBytes' to an existing
+'OffsetIndex' using the supplied per-page byte counts. The
+vector length must match the number of page locations or the
+attached field is dropped (silently — readers tolerate the
+missing slot, an inconsistent one would be worse).
+-}
+buildOffsetIndexWithSizeStats
+  :: V.Vector Int64
+  -> OffsetIndex
+  -> OffsetIndex
+buildOffsetIndexWithSizeStats sizes oi
+  | V.length sizes == V.length (oiPageLocations oi) =
+      oi {oiUnencodedByteArrayDataBytes = Just sizes}
+  | otherwise = oi
diff --git a/src/Parquet/Write/Encrypted.hs b/src/Parquet/Write/Encrypted.hs
new file mode 100644
--- /dev/null
+++ b/src/Parquet/Write/Encrypted.hs
@@ -0,0 +1,432 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE PatternSynonyms #-}
+
+{- | Finalize files from our single-data-page writers with modular encryption.
+The private seam keeps nullable/nested encoding and compression independent
+of encryption. It is not an API for rewriting arbitrary external files.
+-}
+module Parquet.Write.Encrypted (
+  FooterMode (..),
+  encryptWrittenFile,
+  WriterOutput (..),
+  nestedWriterOutput,
+  encryptWriterOutput,
+) where
+
+import Control.Monad (unless)
+import Crypto.Cipher.AES.GCM qualified as GCM
+import Crypto.Error (CryptoFailable (..))
+import Crypto.Random.Types qualified as RNG
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int16, Int32, Int64)
+import Data.Map.Strict qualified as Map
+import Data.Maybe (fromMaybe)
+import Data.Vector qualified as V
+import Data.Word (Word32)
+import Parquet.Encryption qualified as E
+import Parquet.Footer qualified as F
+import Parquet.Page qualified as P
+import Parquet.PageIndex qualified as I
+import Parquet.Thrift.Schema
+import Parquet.Types
+import Parquet.Write (ColumnEncryption (..), FooterEncryption (..), encodePageHeader)
+import Thrift.Decode (decodeCompactFrom)
+import Thrift.Encode (compactEncodedSizeBounded, encodeCompactBounded)
+import Thrift.Value qualified as TV
+import Wireform.Builder qualified as B
+
+
+data FooterMode = EncryptedFooter | SignedPlaintextFooter
+  deriving (Show, Eq)
+
+
+-- A package-private writer result: magic and page/auxiliary bytes, without
+-- a serialized footer. The metadata is already available from the writer.
+data WriterOutput = WriterOutput !FileMetadata ~ByteString
+
+
+nestedWriterOutput :: FileMetadata -> Integer -> Either String () -> B.Builder -> Either String WriterOutput
+nestedWriterOutput metadata size validate body = do
+  require (size >= 0 && size + 4 <= toInteger (maxBound :: Int)) "complete writer body exceeds addressable size"
+  validate
+  pure (WriterOutput metadata (B.toStrictByteStringWith (fromInteger size + 4) (B.byteString F.parquetMagic <> body)))
+
+
+data PreparedFile = PreparedFile
+  { preparedMetadata :: !FileMetadata
+  , preparedGroups :: !(V.Vector (V.Vector PreparedColumn))
+  , preparedAlgorithm :: !E.EncryptionAlgorithm
+  , preparedFooterContext :: !GCM.Context
+  }
+
+
+data PreparedColumn = PreparedColumn
+  { originalChunk :: !ColumnChunk
+  , originalMetadata :: !ColumnMetadata
+  , originalHeader :: !P.PageHeader
+  , originalHeaderSize :: {-# UNPACK #-} !Int
+  , originalBody :: !ByteString
+  , originalBloom :: !(Maybe BloomParts)
+  , originalOffsets :: !(Maybe OffsetIndex)
+  , originalIndex :: !(Maybe ByteString)
+  , columnEncryption :: !(Maybe ColumnEncryption)
+  , columnContext :: !(Maybe GCM.Context)
+  }
+
+
+data BloomParts = BloomParts !ByteString !ByteString
+
+
+data FileAssembly = FileAssembly
+  { fileCursor :: {-# UNPACK #-} !Int
+  , fileParts :: ![ByteString]
+  , fileGroups :: ![RowGroup]
+  }
+
+
+data GroupAssembly = GroupAssembly
+  { groupCursor :: {-# UNPACK #-} !Int
+  , groupParts :: ![ByteString]
+  , groupColumns :: ![ColumnChunk]
+  , groupUncompressed :: {-# UNPACK #-} !Int64
+  }
+
+
+data EmittedColumn = EmittedColumn
+  { emittedChunk :: !ColumnChunk
+  , emittedParts :: ![ByteString]
+  , emittedEnd :: {-# UNPACK #-} !Int
+  }
+
+
+{- | All layout and key checks precede random generation. A failed request
+returns no bytes; encryption never falls back to a plaintext output.
+-}
+encryptWrittenFile
+  :: RNG.MonadRandom m
+  => FooterMode
+  -> FooterEncryption
+  -> V.Vector (Maybe ColumnEncryption)
+  -> ByteString
+  -> m (Either String ByteString)
+encryptWrittenFile mode footer columns plaintext =
+  case F.readFooter plaintext of
+    Left err -> pure (Left err)
+    Right metadata -> encryptWriterOutput mode footer columns (WriterOutput metadata plaintext)
+
+
+encryptWriterOutput
+  :: RNG.MonadRandom m
+  => FooterMode
+  -> FooterEncryption
+  -> V.Vector (Maybe ColumnEncryption)
+  -> WriterOutput
+  -> m (Either String ByteString)
+encryptWriterOutput mode footer columns (WriterOutput metadata plaintext) =
+  case prepare footer columns metadata plaintext of
+    Left err -> pure (Left err)
+    Right plan -> do
+      nonces <- V.mapM (V.mapM (\column -> case columnEncryption column of Nothing -> pure BS.empty; Just _ -> RNG.getRandomBytes 96)) (preparedGroups plan)
+      footerNonce <- RNG.getRandomBytes 12
+      pure (assemble mode footer plan nonces footerNonce)
+
+
+prepare :: FooterEncryption -> V.Vector (Maybe ColumnEncryption) -> FileMetadata -> ByteString -> Either String PreparedFile
+prepare footer columns metadata plaintext = do
+  validKey (feKey footer)
+  require (not (BS.null (feFileId footer))) "a fresh random file identifier is required"
+  require (BS.take 4 plaintext == F.parquetMagic) "expected a plaintext writer output"
+  let leaves = V.filter (maybe False (const True) . seType) (fmSchema metadata)
+      algorithm = fromMaybe E.AesGcmV1 (V.foldl' firstAlgorithm Nothing columns)
+  require (V.null columns || V.length columns == V.length leaves) "column encryption vector must match the leaf-column count"
+  V.imapM_ (checkColumn algorithm) columns
+  footerContext <- newGcmContext (feKey footer)
+  contexts <- V.mapM (traverse (\ce -> if ceKey ce == feKey footer then Right footerContext else newGcmContext (ceKey ce))) columns
+  groups <- V.imapM (prepareGroup contexts) (fmRowGroups metadata)
+  -- Eight module slots per chunk and one footer signature. Count actual keys
+  -- before encryption, conservatively including optional/unused slots. Bound
+  -- local invocations without constructing per-page counters in the hot loop.
+  let counts = V.foldl' (V.foldl' countColumn) (Map.singleton (feKey footer) (1 :: Integer)) groups
+  require (all (<= 4294967296) (Map.elems counts)) "AES key invocation limit exceeded"
+  pure (PreparedFile metadata groups algorithm footerContext)
+  where
+    firstAlgorithm found entry = case found of
+      Just _ -> found
+      Nothing -> ceAlgorithm <$> entry
+    countColumn counts column = case columnEncryption column of
+      Nothing -> counts
+      Just ce -> Map.insertWith (+) (ceKey ce) 8 counts
+    checkColumn algorithm col entry = case entry of
+      Nothing -> Right ()
+      Just ce -> do
+        require (col <= 32767) "encrypted column ordinal exceeds signed 16-bit range"
+        validKey (ceKey ce)
+        require (ceFileId ce == feFileId footer && ceAadPrefix ce == feAadPrefix footer) "column and footer AAD contexts must match"
+        require (ceAlgorithm ce == algorithm) "encrypted columns must share one file-level algorithm"
+    prepareGroup contexts rg group = do
+      require (rg <= 32767) "row-group ordinal exceeds signed 16-bit range"
+      V.imapM (prepareColumn contexts rg) (rgColumns group)
+    prepareColumn contexts _ col chunk = do
+      require (ccFilePath chunk == Nothing) "external column files are not writer outputs"
+      cm <- maybe (failure "missing column metadata") Right (ccMetadata chunk)
+      require (cmDictionaryPageOffset cm == Nothing) "expected one non-dictionary data page"
+      raw <- slice plaintext (cmDataPageOffset cm) (cmTotalCompressedSize cm)
+      (header, end) <- P.readPageHeaderAt raw 0
+      size <- maybe (failure "missing compressed page size") (Right . fromIntegral) (P.phCompressedPageSize header)
+      require (size >= 0 && end <= BS.length raw && size == BS.length raw - end) "expected exactly one complete data page"
+      require (P.pageTypeIsDataPageV1 (P.phType header) || P.pageTypeIsDataPageV2 (P.phType header)) "expected a data page"
+      bloom <- traverse (prepareBloom cm) (cmBloomFilterOffset cm)
+      offsets <- auxiliary (ccOffsetIndexOffset chunk) (ccOffsetIndexLength chunk) >>= traverse I.decodeOffsetIndex
+      case offsets of
+        Nothing -> Right ()
+        Just oi -> require (V.length (oiPageLocations oi) == 1) "offset index must describe the single data page"
+      index <- auxiliary (ccColumnIndexOffset chunk) (ccColumnIndexLength chunk)
+      pure (PreparedColumn chunk cm header end (BS.drop end raw) bloom offsets index (fromMaybe Nothing (columns V.!? col)) (fromMaybe Nothing (contexts V.!? col)))
+    auxiliary Nothing Nothing = Right Nothing
+    auxiliary (Just offset) (Just len) = Just <$> slice plaintext offset (fromIntegral len)
+    auxiliary _ _ = failure "incomplete auxiliary location"
+    prepareBloom cm offset = do
+      raw <- slice plaintext offset (maybe (fromIntegral (BS.length plaintext) - offset) fromIntegral (cmBloomFilterLength cm))
+      (value, end) <- decodeCompactFrom raw 0
+      size <- case value of
+        TV.Struct fields -> case V.find ((== fst (BloomFilterHeader_NumBytes 0)) . fst) fields of
+          Just (BloomFilterHeader_NumBytes n) -> Right (fromIntegral n)
+          _ -> failure "missing bloom bitset length"
+        _ -> failure "invalid bloom header"
+      require (size > 0 && size `rem` 32 == 0 && end <= BS.length raw && size <= BS.length raw - end) "invalid bloom bitset bounds"
+      case cmBloomFilterLength cm of
+        Just _ -> require (end + size == BS.length raw) "bloom size differs from metadata"
+        Nothing -> Right ()
+      pure (BloomParts (BS.take end raw) (BS.take size (BS.drop end raw)))
+
+
+assemble :: FooterMode -> FooterEncryption -> PreparedFile -> V.Vector (V.Vector ByteString) -> ByteString -> Either String ByteString
+assemble mode footer plan nonces footerNonce = do
+  output <- V.ifoldM emitGroup (FileAssembly 4 [] []) (preparedGroups plan)
+  let metadata = (preparedMetadata plan) {fmRowGroups = V.fromList (reverse (fileGroups output))}
+  raw <- cryptoMetadata mode footer (preparedGroups plan) nonces metadata
+  let algorithm = algorithmFields (preparedAlgorithm plan) footer
+      aad = E.buildAad (feAadPrefix footer) (E.buildAadSuffix (feFileId footer) E.ModuleFooter 0 0 0)
+      magic = case mode of EncryptedFooter -> F.parquetEncryptedMagic; SignedPlaintextFooter -> F.parquetMagic
+  let footerLimit = fromInteger (min (toInteger (maxBound :: Word32)) (toInteger (maxBound :: Int) - toInteger (fileCursor output) - 8))
+  require (footerLimit >= 32) "output has no room for an authenticated footer"
+  finalFooter <- case mode of
+    EncryptedFooter -> do
+      let cryptoValue = TV.Struct (V.fromList [FileCryptoMetaData_EncryptionAlgorithm algorithm, FileCryptoMetaData_KeyMetadata (feKeyMetadata footer)])
+      cryptoSize <- compactEncodedSizeBounded (footerLimit - 32) cryptoValue
+      -- Validate the remaining combined budget while encoding the plain
+      -- metadata once. Delay even the crypto-header allocation until that
+      -- succeeds, since a legal header alone can exhaust the footer budget.
+      plain <- encodeCompactBounded (footerLimit - 32 - cryptoSize) raw
+      crypto <- encodeCompactBounded cryptoSize cryptoValue
+      cipher <- encryptGcmFramed (preparedFooterContext plan) footerNonce aad plain
+      F.writeRawFooterEither magic (crypto <> cipher)
+    SignedPlaintextFooter -> do
+      fields <- struct raw
+      plain <- encodeCompactBounded (footerLimit - 28) (TV.Struct (fields <> V.fromList [FileMetadata_EncryptionAlgorithm algorithm, FileMetadata_FooterSigningKeyMetadata (feKeyMetadata footer)]))
+      cipher <- encryptGcmTagged (preparedFooterContext plan) footerNonce aad plain
+      F.writeRawFooterEither magic (plain <> footerNonce <> BS.takeEnd 16 cipher)
+  _ <- checkedAdd (fileCursor output) (BS.length finalFooter)
+  pure (BS.concat (magic : reverse (fileParts output) ++ [finalFooter]))
+  where
+    emitGroup acc rg columns = do
+      out <- V.ifoldM (emitColumn rg) (GroupAssembly (fileCursor acc) (fileParts acc) [] 0) columns
+      let original = fmRowGroups (preparedMetadata plan) V.! rg
+          group = original {rgColumns = V.fromList (reverse (groupColumns out)), rgTotalByteSize = groupUncompressed out}
+      pure (FileAssembly (groupCursor out) (groupParts out) (group : fileGroups acc))
+    emitColumn rg acc col column = do
+      out <- emitOne rg col (nonces V.! rg V.! col) (groupCursor acc) column
+      cm <- maybe (failure "lost emitted metadata") Right (ccMetadata (emittedChunk out))
+      let total = toInteger (groupUncompressed acc) + toInteger (cmTotalUncompressedSize cm)
+      require (total <= toInteger (maxBound :: Int64)) "row-group uncompressed size exceeds signed 64-bit limit"
+      pure (GroupAssembly (emittedEnd out) (reverse (emittedParts out) ++ groupParts acc) (emittedChunk out : groupColumns acc) (fromInteger total))
+
+
+emitOne :: Int -> Int -> ByteString -> Int -> PreparedColumn -> Either String EmittedColumn
+emitOne rg col nonces start column = do
+  let ce = columnEncryption column
+      cm = originalMetadata column
+      original = originalChunk column
+      body = originalBody column
+      header = originalHeader column
+      gcm slot kind = encryptCached ce (columnContext column) nonces slot kind rg col
+  let overhead = case ce of
+        Nothing -> 0
+        Just settings -> case ceAlgorithm settings of E.AesGcmV1 -> 32; E.AesGcmCtrV1 -> 16
+  expectedBodySize <- checkedAdd (BS.length body) overhead >>= size32
+  encryptedBody <- case ce of
+    Nothing -> Right body
+    Just settings -> case ceAlgorithm settings of
+      E.AesGcmV1 -> gcm 1 E.ModuleDataPage body
+      E.AesGcmCtrV1 -> E.encryptCtrModuleFramedWithNonce (ceKey settings) (nonceAt nonces 1) body
+  require (BS.length encryptedBody == fromIntegral expectedBodySize) "encrypted body size differs from planned framing"
+  let plainHeader = encodePageHeader header {P.phCompressedPageSize = Just expectedBodySize}
+  encryptedHeader <- gcm 0 E.ModuleDataPageHeader plainHeader
+  pageLength <- checkedAdd (BS.length encryptedHeader) (BS.length encryptedBody)
+  pageSize <- case originalOffsets column of
+    Nothing -> Right 0
+    Just _ -> size32 pageLength
+  afterPage <- checkedAdd start pageLength
+  bloom <- traverse (emitBloom gcm) (originalBloom column)
+  let bloomBytes = fromMaybe BS.empty bloom
+  afterBloom <- checkedAdd afterPage (BS.length bloomBytes)
+  offsets <- traverse (emitOffsets gcm pageSize) (originalOffsets column)
+  let offsetBytes = fromMaybe BS.empty offsets
+  offsetSize <- size32 (BS.length offsetBytes)
+  afterOffsets <- checkedAdd afterBloom (BS.length offsetBytes)
+  index <- traverse (gcm 5 E.ModuleColumnIndex) (originalIndex column)
+  let indexBytes = fromMaybe BS.empty index
+  indexSize <- size32 (BS.length indexBytes)
+  end <- checkedAdd afterOffsets (BS.length indexBytes)
+  let sizeDelta = BS.length encryptedHeader - originalHeaderSize column
+      uncompressed = toInteger (cmTotalUncompressedSize cm) + toInteger sizeDelta
+  require (uncompressed >= 0 && uncompressed <= toInteger (maxBound :: Int64)) "column uncompressed size exceeds signed 64-bit limit"
+  let updated =
+        cm
+          { cmDataPageOffset = fromIntegral start
+          , cmTotalCompressedSize = fromIntegral pageLength
+          , cmTotalUncompressedSize = fromInteger uncompressed
+          , cmBloomFilterOffset = fromIntegral afterPage <$ bloom
+          , -- Optional i32 length may be omitted for a legal large bitset whose
+            -- two encrypted modules no longer fit in the signed length field.
+            cmBloomFilterLength = if BS.length bloomBytes <= fromIntegral (maxBound :: Int32) then fromIntegral (BS.length bloomBytes) <$ bloom else Nothing
+          }
+      chunk =
+        original
+          { ccFileOffset = fromIntegral start
+          , ccMetadata = Just updated
+          , ccOffsetIndexOffset = fromIntegral afterBloom <$ offsets
+          , ccOffsetIndexLength = offsetSize <$ offsets
+          , ccColumnIndexOffset = fromIntegral afterOffsets <$ index
+          , ccColumnIndexLength = indexSize <$ index
+          }
+  pure (EmittedColumn chunk [encryptedHeader, encryptedBody, bloomBytes, offsetBytes, indexBytes] end)
+  where
+    emitBloom gcm (BloomParts header bits) = (<>) <$> gcm 2 E.ModuleBloomFilterHeader header <*> gcm 3 E.ModuleBloomFilterBitset bits
+    emitOffsets gcm size oi =
+      gcm 4 E.ModuleOffsetIndex (I.encodeOffsetIndex oi {oiPageLocations = V.map (\p -> p {plOffset = fromIntegral start, plCompressedPageSize = size}) (oiPageLocations oi)})
+
+
+cryptoMetadata :: FooterMode -> FooterEncryption -> V.Vector (V.Vector PreparedColumn) -> V.Vector (V.Vector ByteString) -> FileMetadata -> Either String TV.Value
+cryptoMetadata mode footer plans nonces metadata = do
+  fields <- struct (F.fileMetadataToThrift metadata)
+  TV.Struct <$> V.mapM rewriteFile fields
+  where
+    rewriteFile (FileMetadata_RowGroups groups) = FileMetadata_RowGroups <$> V.imapM rewriteGroup groups
+    rewriteFile field = Right field
+    rewriteGroup rg value = do
+      fields <- struct value
+      updated <- V.mapM (rewriteGroupField rg) fields
+      pure (TV.Struct (V.snoc updated (RowGroup_Ordinal (fromIntegral rg))))
+    rewriteGroupField rg (RowGroup_Columns columns) = RowGroup_Columns <$> V.imapM (rewriteColumn rg) columns
+    rewriteGroupField _ field = Right field
+    rewriteColumn rg col value = case columnEncryption (plans V.! rg V.! col) of
+      Nothing -> Right value
+      Just ce -> do
+        fields <- struct value
+        cm <- maybe (failure "missing emitted column metadata") Right (ccMetadata (rgColumns (fmRowGroups metadata V.! rg) V.! col))
+        cmFields <- maybe (failure "missing serialized column metadata") (struct . snd) (V.find ((== fst (ColumnChunk_MetaData V.empty)) . fst) fields)
+        let footerKey = ceKey ce == feKey footer
+            crypto =
+              if footerKey
+                then V.singleton (ColumnCryptoMetaData_EncryptionWithFooterKey V.empty)
+                else V.singleton (ColumnCryptoMetaData_EncryptionWithColumnKey (V.fromList [EncryptionWithColumnKey_PathInSchema (V.map TV.String (cmPathInSchema cm)), EncryptionWithColumnKey_KeyMetadata (ceKeyMetadata ce)]))
+            base = V.snoc fields (ColumnChunk_CryptoMetadata crypto)
+        if mode == EncryptedFooter && footerKey
+          then Right (TV.Struct base)
+          else do
+            plain <- encode (TV.Struct cmFields)
+            encrypted <- encryptCached (Just ce) (columnContext (plans V.! rg V.! col)) (nonces V.! rg V.! col) 6 E.ModuleColumnMetaData rg col plain
+            let strip (ColumnChunk_MetaData _) = mode == EncryptedFooter
+                strip _ = False
+                sanitize (ColumnChunk_MetaData entries) = ColumnChunk_MetaData (V.filter ((/= fst (ColumnMetaData_Statistics V.empty)) . fst) entries)
+                sanitize entry = entry
+            pure (TV.Struct (V.snoc (V.map sanitize (V.filter (not . strip) base)) (ColumnChunk_EncryptedColumnMetadata encrypted)))
+
+
+algorithmFields :: E.EncryptionAlgorithm -> FooterEncryption -> V.Vector (Int16, TV.Value)
+algorithmFields algorithm footer = V.singleton (variant fields)
+  where
+    variant = case algorithm of E.AesGcmV1 -> EncryptionAlgorithm_AesGcmV1; E.AesGcmCtrV1 -> EncryptionAlgorithm_AesGcmCtrV1
+    fields = V.fromList ([AesGcmV1_AadFileUnique (feFileId footer)] ++ if BS.null (feAadPrefix footer) then [] else [AesGcmV1_AadPrefix (feAadPrefix footer)])
+
+
+encryptCached :: Maybe ColumnEncryption -> Maybe GCM.Context -> ByteString -> Int -> E.ModuleType -> Int -> Int -> ByteString -> Either String ByteString
+encryptCached Nothing _ _ _ _ _ _ bytes = Right bytes
+encryptCached (Just ce) (Just context) nonces slot kind rg col bytes =
+  encryptGcmFramed
+    context
+    (nonceAt nonces slot)
+    (E.buildAad (ceAadPrefix ce) (E.buildAadSuffix (ceFileId ce) kind (fromIntegral rg) (fromIntegral col) 0))
+    bytes
+encryptCached _ _ _ _ _ _ _ _ = failure "missing prepared GCM context"
+
+
+newGcmContext :: ByteString -> Either String GCM.Context
+newGcmContext key = case GCM.newContext key of
+  CryptoPassed context -> Right context
+  CryptoFailed err -> failure ("GCM key initialization: " ++ show err)
+
+
+-- Keep all C-width/address checks ahead of the one-shot call. The framing
+-- length includes nonce and tag; each module still uses its own fresh nonce.
+encryptGcmTagged :: GCM.Context -> ByteString -> ByteString -> ByteString -> Either String ByteString
+encryptGcmTagged context nonce aad plain = do
+  require (BS.length nonce == 12) "nonce must contain 12 bytes"
+  require (toInteger (BS.length aad) <= toInteger (maxBound :: Word32) && toInteger (BS.length plain) <= toInteger (maxBound :: Word32)) "GCM input exceeds unsigned 32-bit C limit"
+  _ <- checkedAdd (BS.length plain) 16
+  pure (GCM.encrypt context nonce aad plain 16)
+
+
+encryptGcmFramed :: GCM.Context -> ByteString -> ByteString -> ByteString -> Either String ByteString
+encryptGcmFramed context nonce aad plain = do
+  framedSize <- checkedAdd (BS.length plain) 28
+  require (toInteger framedSize <= toInteger (maxBound :: Word32)) "encrypted module exceeds unsigned 32-bit length"
+  total <- checkedAdd framedSize 4
+  cipher <- encryptGcmTagged context nonce aad plain
+  require (BS.length cipher == framedSize - 12) "GCM output differs from planned tag length"
+  pure (B.toStrictByteStringExact total (B.word32LE (fromIntegral framedSize) <> B.byteString nonce <> B.byteString cipher))
+
+
+nonceAt :: ByteString -> Int -> ByteString
+nonceAt bytes slot = BS.take 12 (BS.drop (slot * 12) bytes)
+
+
+validKey :: ByteString -> Either String ()
+validKey key = require (BS.length key `elem` [16, 24, 32]) "AES key must contain 16, 24, or 32 bytes"
+
+
+slice :: ByteString -> Int64 -> Int64 -> Either String ByteString
+slice bytes offset size = do
+  require (offset >= 4 && size >= 0 && offset <= fromIntegral (BS.length bytes) && size <= fromIntegral (BS.length bytes) - offset) "writer module lies outside input"
+  pure (BS.take (fromIntegral size) (BS.drop (fromIntegral offset) bytes))
+
+
+checkedAdd :: Int -> Int -> Either String Int
+checkedAdd a b = do
+  require (a >= 0 && b >= 0 && b <= maxBound - a) "output exceeds addressable byte size"
+  pure (a + b)
+
+
+size32 :: Int -> Either String Int32
+size32 size = do
+  require (size >= 0 && toInteger size <= toInteger (maxBound :: Int32)) "page or index size exceeds signed 32-bit limit"
+  pure (fromIntegral size)
+
+
+encode :: TV.Value -> Either String ByteString
+encode = encodeCompactBounded (fromInteger (min (toInteger (maxBound :: Word32)) (toInteger (maxBound :: Int) - 8)))
+
+
+struct :: TV.Value -> Either String (V.Vector (Int16, TV.Value))
+struct (TV.Struct fields) = Right fields
+struct _ = failure "expected metadata struct"
+
+
+require :: Bool -> String -> Either String ()
+require valid message = unless valid (failure message)
+
+
+failure :: String -> Either String a
+failure message = Left ("Parquet.Write.Encrypted: " ++ message)
diff --git a/test-derive/Main.hs b/test-derive/Main.hs
new file mode 100644
--- /dev/null
+++ b/test-derive/Main.hs
@@ -0,0 +1,13 @@
+module Main (main) where
+
+import Test.Parquet.Derive qualified
+import Test.Syd
+
+
+main :: IO ()
+main =
+  sydTest $
+    describe "wireform-parquet-derive" $
+      sequence_
+        [ Test.Parquet.Derive.tests
+        ]
diff --git a/test-derive/Test/Parquet/Derive.hs b/test-derive/Test/Parquet/Derive.hs
new file mode 100644
--- /dev/null
+++ b/test-derive/Test/Parquet/Derive.hs
@@ -0,0 +1,161 @@
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE TemplateHaskell #-}
+
+module Test.Parquet.Derive (tests) where
+
+import Data.Vector qualified as V
+import Parquet.Derive (
+  fromParquetRow,
+  parquetSchemaFor,
+  toParquetRow,
+ )
+import Parquet.Nested qualified as PN
+import Parquet.Types qualified as P
+import Test.Parquet.Derive.Instances (sumTypeDeriveSucceeded)
+import Test.Parquet.Derive.Types
+import Test.Syd
+
+
+tests :: Spec
+tests =
+  describe "Parquet.Derive" $
+    sequence_
+      [ schemaTests
+      , rowTests
+      , coercedTests
+      , spliceTests
+      ]
+
+
+{- | Spliced once at compile time so the test functions can
+pattern-match without re-running TH per case.
+-}
+saleSchema :: V.Vector P.SchemaElement
+saleSchema = $(parquetSchemaFor ''Sale)
+
+
+orderSchema :: V.Vector P.SchemaElement
+orderSchema = $(parquetSchemaFor ''Order)
+
+
+-- ---------------------------------------------------------------------------
+-- Schema
+-- ---------------------------------------------------------------------------
+
+schemaTests :: Spec
+schemaTests =
+  describe "schema" $
+    sequence_
+      [ it "synthetic root + one leaf per field" $ do
+          V.length saleSchema `shouldBe` 4
+          P.seName (V.unsafeIndex saleSchema 0) `shouldBe` "schema"
+          P.seNumChildren (V.unsafeIndex saleSchema 0) `shouldBe` Just 3
+      , it "rename modifier reflected on schema element name" $ do
+          P.seName (V.unsafeIndex saleSchema 1) `shouldBe` "amount"
+          P.seName (V.unsafeIndex saleSchema 2) `shouldBe` "product"
+      , it "absent rename falls back to backend's snake_case style" $
+          P.seName (V.unsafeIndex saleSchema 3) `shouldBe` "sale_region"
+      , it "amount -> INT64 required" $ do
+          let se = V.unsafeIndex saleSchema 1
+          P.seType se `shouldBe` Just P.PTInt64
+          P.seRepetition se `shouldBe` Just P.Required
+      , it "product -> BYTE_ARRAY/UTF8 required" $ do
+          let se = V.unsafeIndex saleSchema 2
+          P.seType se `shouldBe` Just P.PTByteArray
+          P.seConvertedType se `shouldBe` Just P.CTUtf8
+          P.seRepetition se `shouldBe` Just P.Required
+      , it "Maybe Text region -> BYTE_ARRAY/UTF8 optional" $ do
+          let se = V.unsafeIndex saleSchema 3
+          P.seType se `shouldBe` Just P.PTByteArray
+          P.seConvertedType se `shouldBe` Just P.CTUtf8
+          P.seRepetition se `shouldBe` Just P.Optional
+      ]
+
+
+-- ---------------------------------------------------------------------------
+-- Per-row codec
+-- ---------------------------------------------------------------------------
+
+rowTests :: Spec
+rowTests =
+  describe "row" $
+    sequence_
+      [ it "Just region produces three Just leaves" $ do
+          let s = Sale 100 "widget" (Just "us-east")
+              row = toParquetRow s
+          V.length row `shouldBe` 3
+          V.unsafeIndex row 0 `shouldBe` Just (PN.LvInt64 100)
+          V.unsafeIndex row 1 `shouldBe` Just (PN.LvString "widget")
+          V.unsafeIndex row 2 `shouldBe` Just (PN.LvString "us-east")
+      , it "Nothing region produces a Nothing slot" $ do
+          let s = Sale 7 "gizmo" Nothing
+              row = toParquetRow s
+          V.unsafeIndex row 2 `shouldBe` Nothing
+      , it "round-trip Sale through toParquetRow/fromParquetRow" $ do
+          let s = Sale 0xCAFE "wrench" (Just "eu-west")
+          case fromParquetRow (toParquetRow s) of
+            Right s' -> s' `shouldBe` s
+            Left e -> expectationFailure e
+      , it "round-trip Sale with Nothing region" $ do
+          let s = Sale 1 "spanner" Nothing
+          case fromParquetRow (toParquetRow s) of
+            Right s' -> s' `shouldBe` s
+            Left e -> expectationFailure e
+      , it "fromParquetRow rejects wrong leaf count" $
+          case ( fromParquetRow (V.singleton (Just (PN.LvInt64 1)))
+                   :: Either String Sale
+               ) of
+            Left _ -> pure ()
+            Right s -> expectationFailure ("unexpected success: " ++ show s)
+      , it "fromParquetRow rejects null in required column" $
+          case ( fromParquetRow
+                   ( V.fromList
+                       [ Nothing
+                       , Just (PN.LvString "x")
+                       , Nothing
+                       ]
+                   )
+                   :: Either String Sale
+               ) of
+            Left _ -> pure ()
+            Right s -> expectationFailure ("unexpected success: " ++ show s)
+      ]
+
+
+-- ---------------------------------------------------------------------------
+-- coerced newtype roundtrip
+-- ---------------------------------------------------------------------------
+
+coercedTests :: Spec
+coercedTests =
+  describe "coerced" $
+    sequence_
+      [ it "Order schema picks up Int64 from coerced ''Int64" $ do
+          V.length orderSchema `shouldBe` 2
+          let leaf = V.unsafeIndex orderSchema 1
+          P.seType leaf `shouldBe` Just P.PTInt64
+          P.seRepetition leaf `shouldBe` Just P.Required
+      , it "Order encodes via the underlying Int64 representation" $ do
+          let o = Order (OrderId 42)
+              row = toParquetRow o
+          V.length row `shouldBe` 1
+          V.unsafeIndex row 0 `shouldBe` Just (PN.LvInt64 42)
+      , it "Order round-trips through the coerced leaf" $ do
+          let o = Order (OrderId 0xDEAD)
+          case fromParquetRow (toParquetRow o) of
+            Right o' -> o' `shouldBe` o
+            Left e -> expectationFailure e
+      ]
+
+
+-- ---------------------------------------------------------------------------
+-- Splice-time refusal of sum types
+-- ---------------------------------------------------------------------------
+
+spliceTests :: Spec
+spliceTests =
+  describe "splice-time" $
+    sequence_
+      [ it "deriveParquet refuses sum types" $
+          (not sumTypeDeriveSucceeded) `shouldBe` True
+      ]
diff --git a/test-derive/Test/Parquet/Derive/Instances.hs b/test-derive/Test/Parquet/Derive/Instances.hs
new file mode 100644
--- /dev/null
+++ b/test-derive/Test/Parquet/Derive/Instances.hs
@@ -0,0 +1,29 @@
+{-# LANGUAGE TemplateHaskell #-}
+{-# OPTIONS_GHC -Wno-orphans #-}
+
+{- | Instance derivations + a compile-time probe that checks
+'deriveParquet' refuses sum-type shapes.
+-}
+module Test.Parquet.Derive.Instances (
+  sumTypeDeriveSucceeded,
+) where
+
+import Language.Haskell.TH (recover)
+import Language.Haskell.TH.Syntax (lift)
+import Parquet.Derive (deriveParquet)
+import Test.Parquet.Derive.Types
+
+
+deriveParquet ''Sale
+deriveParquet ''Order
+
+
+sumTypeDeriveSucceeded :: Bool
+sumTypeDeriveSucceeded =
+  $( recover
+       (lift False)
+       ( do
+           _ <- deriveParquet ''Color
+           lift True
+       )
+   )
diff --git a/test-derive/Test/Parquet/Derive/Types.hs b/test-derive/Test/Parquet/Derive/Types.hs
new file mode 100644
--- /dev/null
+++ b/test-derive/Test/Parquet/Derive/Types.hs
@@ -0,0 +1,57 @@
+{-# LANGUAGE GeneralisedNewtypeDeriving #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE TemplateHaskell #-}
+
+-- | Annotated fixture types for the Parquet deriver tests.
+module Test.Parquet.Derive.Types (
+  Sale (..),
+  OrderId (..),
+  Order (..),
+  Color (..),
+) where
+
+import Data.Int (Int64)
+import Data.Text (Text)
+import Wireform.Derive.Modifier (coerced, rename)
+
+
+{- | Three flat fields exercising required, required, and nullable
+leaves. The renames are picked up by the spliced schema.
+-}
+data Sale = Sale
+  { saleAmount :: !Int64
+  , saleProduct :: !Text
+  , saleRegion :: !(Maybe Text)
+  }
+  deriving stock (Eq, Show)
+
+
+{-# ANN saleAmount (rename "amount") #-}
+
+
+{-# ANN saleProduct (rename "product") #-}
+
+
+{- | Newtype around 'Int64' used through 'coerced' so the deriver
+emits the underlying physical type without needing an instance on
+'OrderId' itself.
+-}
+newtype OrderId = OrderId {unOrderId :: Int64}
+  deriving stock (Eq, Show)
+
+
+-- | One-field record exercising the 'coerced' modifier.
+data Order = Order
+  { orderId :: !OrderId
+  }
+  deriving stock (Eq, Show)
+
+
+{-# ANN orderId (coerced ''Int64) #-}
+
+
+{- | Multi-constructor sum used to verify 'deriveParquet' refuses
+non-record shapes at splice time.
+-}
+data Color = Red | Green | Blue
+  deriving stock (Eq, Show)
diff --git a/test/Aggregate.hs b/test/Aggregate.hs
new file mode 100644
--- /dev/null
+++ b/test/Aggregate.hs
@@ -0,0 +1,493 @@
+{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+{- | Tests for 'Parquet.Aggregate' — pure stats arithmetic over
+synthetic 'FileMetadata' (no actual parquet files needed).
+
+The interesting cases are:
+
+  * @count(*)@ across multiple row groups.
+  * @count(col)@ when every row group reports null counts.
+  * @count(col)@ poisoned to 'Nothing' when one row group
+    omits the null count.
+  * @columnMin@ / @columnMax@ folding over per-row-group
+    min / max statistics, including the legacy 'statMin' /
+    'statMax' slots and the modern 'statMinValue' /
+    'statMaxValue' slots.
+  * @columnMin@ / @columnMax@ poisoned to 'Nothing' when one
+    row group omits the stat.
+-}
+module Aggregate (run) where
+
+import Columnar.Predicate qualified as Pred
+import Data.ByteString qualified as BS
+import Data.ByteString.Lazy qualified as BL
+import Data.Int (Int32, Int64)
+import Data.List.NonEmpty qualified as NE
+import Data.Vector qualified as V
+import Data.Word ()
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Aggregate qualified as Agg
+import Parquet.Footer qualified as Footer
+import Parquet.Predicate qualified as PPred
+import Parquet.Types
+import Thrift.Encode qualified as Thrift
+import Wireform.Builder (int32LE, int64LE, toLazyByteString)
+
+
+{- | Public entry: prints OK / FAIL lines like the rest of the
+wireform-parquet test suite.
+-}
+run :: IO ()
+run = do
+  test
+    "fileRowCount over 3 row groups"
+    (Agg.fileRowCount (mkFm rowGroups123) == 600)
+
+  test
+    "columnNonNullCount sums (rg.numRows - null_count)"
+    (Agg.columnNonNullCount (mkFm rowGroups123) 0 == Just (600 - (1 + 2 + 3)))
+  test
+    "columnNonNullCount poisons to Nothing when one rg lacks null_count"
+    (Agg.columnNonNullCount (mkFm rowGroupsMissingNull) 0 == Nothing)
+
+  test
+    "columnMin folds modern statMinValue across rgs"
+    ( Agg.columnMin (mkFm rowGroupsMinMaxModern) 0
+        == Just (Pred.PVInt32 1)
+    )
+  test
+    "columnMax folds modern statMaxValue across rgs"
+    ( Agg.columnMax (mkFm rowGroupsMinMaxModern) 0
+        == Just (Pred.PVInt32 99)
+    )
+
+  test
+    "columnMin falls back to legacy statMin when statMinValue absent"
+    ( Agg.columnMin (mkFm rowGroupsMinMaxLegacy) 0
+        == Just (Pred.PVInt64 (-7))
+    )
+  test
+    "columnMax falls back to legacy statMax when statMaxValue absent"
+    ( Agg.columnMax (mkFm rowGroupsMinMaxLegacy) 0
+        == Just (Pred.PVInt64 12345)
+    )
+
+  test
+    "columnMin poisons to Nothing when one rg has no min"
+    (Agg.columnMin (mkFm rowGroupsMissingMin) 0 == Nothing)
+  test
+    "columnMax poisons to Nothing when one rg has no max"
+    (Agg.columnMax (mkFm rowGroupsMissingMax) 0 == Nothing)
+  exactBoundsRegression test
+  countRegression test
+  countProperty
+  where
+    -- columnSum was removed from Parquet.Aggregate (Parquet's
+    -- Statistics message doesn't carry per-row-group sums; ORC
+    -- does, see ORC.Aggregate.columnSum).
+
+    test :: String -> Bool -> IO ()
+    test name True = putStrLn ("OK: " ++ name)
+    test name False = error ("FAIL: " ++ name)
+
+
+-- ============================================================
+-- Synthetic FileMetadata builders
+-- ============================================================
+
+mkFm :: [RowGroup] -> FileMetadata
+mkFm rgs =
+  FileMetadata
+    { fmVersion = 2
+    , fmSchema =
+        V.cons (SchemaElement "schema" Nothing Nothing (Just (fromIntegral (V.length leaves))) Nothing Nothing Nothing Nothing) leaves
+    , fmNumRows = sum (map rgNumRows rgs)
+    , fmRowGroups = V.fromList rgs
+    , fmCreatedBy = Nothing
+    , fmKeyValueMetadata = Nothing
+    , fmColumnOrders = Just (V.replicate (case rgs of [] -> 0; first : _ -> V.length (rgColumns first)) TypeDefinedOrder)
+    }
+  where
+    leaves = case rgs of
+      [] -> V.empty
+      first : _ ->
+        V.map
+          ( \column ->
+              SchemaElement
+                (maybe "value" (\metadata -> V.last (cmPathInSchema metadata)) (ccMetadata column))
+                (Just Optional)
+                (cmType <$> ccMetadata column)
+                Nothing
+                Nothing
+                Nothing
+                Nothing
+                Nothing
+          )
+          (rgColumns first)
+
+
+mkRg :: Int64 -> [(Maybe Int64, Maybe Statistics)] -> RowGroup
+mkRg n cols =
+  RowGroup
+    { rgColumns = V.fromList (map mkCc cols)
+    , rgTotalByteSize = 0
+    , rgNumRows = n
+    , rgSortingColumns = Nothing
+    }
+
+
+mkCc :: (Maybe Int64, Maybe Statistics) -> ColumnChunk
+mkCc (mNumValues, mStats) =
+  ColumnChunk
+    { ccFilePath = Nothing
+    , ccFileOffset = 0
+    , ccMetadata =
+        Just
+          ColumnMetadata
+            { cmType = PTInt32
+            , cmEncodings = V.empty
+            , cmPathInSchema = V.singleton "x"
+            , cmCodec = Uncompressed
+            , cmNumValues = maybe 0 id mNumValues
+            , cmTotalUncompressedSize = 0
+            , cmTotalCompressedSize = 0
+            , cmDataPageOffset = 0
+            , cmDictionaryPageOffset = Nothing
+            , cmStatistics = mStats
+            , cmBloomFilterOffset = Nothing
+            , cmBloomFilterLength = Nothing
+            }
+    , ccOffsetIndexOffset = Nothing
+    , ccOffsetIndexLength = Nothing
+    , ccColumnIndexOffset = Nothing
+    , ccColumnIndexLength = Nothing
+    }
+
+
+emptyStats :: Statistics
+emptyStats =
+  Statistics
+    { statMinValueExact = Nothing
+    , statMaxValueExact = Nothing
+    , statNanCount = Nothing
+    , statMin = Nothing
+    , statMax = Nothing
+    , statNullCount = Nothing
+    , statDistinctCount = Nothing
+    , statMinValue = Nothing
+    , statMaxValue = Nothing
+    }
+
+
+statsWithNullCount :: Int64 -> Statistics
+statsWithNullCount n = emptyStats {statNullCount = Just n}
+
+
+statsInt32MinMax :: Int32 -> Int32 -> Statistics
+statsInt32MinMax lo hi =
+  emptyStats
+    { statMinValue = Just (le32 lo)
+    , statMaxValue = Just (le32 hi)
+    , statMinValueExact = Just True
+    , statMaxValueExact = Just True
+    }
+
+
+statsInt64LegacyMinMax :: Int64 -> Int64 -> Statistics
+statsInt64LegacyMinMax lo hi =
+  emptyStats
+    { statMin = Just (le64 lo)
+    , statMax = Just (le64 hi)
+    }
+
+
+le32 :: Int32 -> BS.ByteString
+le32 = BL.toStrict . toLazyByteString . int32LE
+
+
+le64 :: Int64 -> BS.ByteString
+le64 = BL.toStrict . toLazyByteString . int64LE
+
+
+-- 3 row groups of 100/200/300 rows, 1/2/3 nulls in column 0.
+rowGroups123 :: [RowGroup]
+rowGroups123 =
+  [ mkRg 100 [(Just 100, Just (statsWithNullCount 1))]
+  , mkRg 200 [(Just 200, Just (statsWithNullCount 2))]
+  , mkRg 300 [(Just 300, Just (statsWithNullCount 3))]
+  ]
+
+
+rowGroupsMissingNull :: [RowGroup]
+rowGroupsMissingNull =
+  [ mkRg 100 [(Just 100, Just emptyStats)]
+  , mkRg 200 [(Just 200, Just (statsWithNullCount 0))]
+  ]
+
+
+rowGroupsMinMaxModern :: [RowGroup]
+rowGroupsMinMaxModern =
+  -- min across [3,1,42] = 1; max across [50,99,80] = 99.
+  -- Column 0 must report ParquetType PTInt32 in every chunk
+  -- (mkCc's default).
+  [ mkRg 100 [(Just 100, Just (overrideType PTInt32 (statsInt32MinMax 3 50)))]
+  , mkRg 100 [(Just 100, Just (overrideType PTInt32 (statsInt32MinMax 1 80)))]
+  , mkRg 100 [(Just 100, Just (overrideType PTInt32 (statsInt32MinMax 42 99)))]
+  ]
+
+
+rowGroupsMinMaxLegacy :: [RowGroup]
+rowGroupsMinMaxLegacy =
+  [ mkRgWithType 100 [(Just 100, Just (statsInt64LegacyMinMax (-7) 12345))]
+  , mkRgWithType 100 [(Just 100, Just (statsInt64LegacyMinMax 0 99))]
+  ]
+
+
+rowGroupsMissingMin :: [RowGroup]
+rowGroupsMissingMin =
+  [ mkRg 100 [(Just 100, Just (overrideType PTInt32 (statsInt32MinMax 3 50)))]
+  , mkRg 100 [(Just 100, Just emptyStats)]
+  ]
+
+
+rowGroupsMissingMax :: [RowGroup]
+rowGroupsMissingMax =
+  [ mkRg 100 [(Just 100, Just (overrideType PTInt32 (statsInt32MinMax 3 50)))]
+  , mkRg 100 [(Just 100, Just emptyStats {statMinValue = Just (le32 0)})]
+  ]
+
+
+-- Force the column type on a synthetic ColumnChunk —
+-- cmType gates which 'PValue' constructor decoders pick.
+overrideType :: ParquetType -> Statistics -> Statistics
+overrideType _ = id -- placeholder; type is set on the ColumnMetadata
+
+
+-- Build a row group whose only column reports PTInt64 (so the
+-- legacy stats decode correctly).
+mkRgWithType :: Int64 -> [(Maybe Int64, Maybe Statistics)] -> RowGroup
+mkRgWithType n cols =
+  RowGroup
+    { rgColumns = V.fromList (map (mkCcWithType PTInt64) cols)
+    , rgTotalByteSize = 0
+    , rgNumRows = n
+    , rgSortingColumns = Nothing
+    }
+
+
+mkCcWithType :: ParquetType -> (Maybe Int64, Maybe Statistics) -> ColumnChunk
+mkCcWithType ty values =
+  let column = mkCc values
+  in column {ccMetadata = (\metadata -> metadata {cmType = ty}) <$> ccMetadata column}
+
+
+-- Compact bounds need not occur in the data, so they cannot answer MIN/MAX.
+exactBoundsRegression :: (String -> Bool -> IO ()) -> IO ()
+exactBoundsRegression test = do
+  let compact =
+        emptyStats
+          { statMinValue = Just "B"
+          , statMaxValue = Just "C"
+          , statNullCount = Just 0
+          , statMinValueExact = Just False
+          , statMaxValueExact = Just False
+          }
+      metadata stats = mkFm [mkRgTyped PTByteArray 2 stats]
+      file = metadata compact
+      root = V.head (fmRowGroups file)
+  test
+    "compact bounds cannot supply exact aggregate values"
+    (Agg.columnMin file 0 == Nothing && Agg.columnMax file 0 == Nothing)
+  test
+    "compact bounds still prove a value cannot occur"
+    (PPred.evalRowGroup file (Pred.PCol "x" (Pred.PEq (Pred.PVBinary "A"))) root == Pred.PSkip)
+  mapM_
+    ( \flag -> do
+        let unknown = metadata (compact {statMinValueExact = flag, statMaxValueExact = flag})
+        test
+          "unknown/false exactness cannot establish actual extrema"
+          (Agg.columnMin unknown 0 == Nothing && Agg.columnMax unknown 0 == Nothing)
+    )
+    [Nothing, Just False]
+  let onlyMin = metadata (compact {statMinValueExact = Just True})
+      onlyMax = metadata (compact {statMaxValueExact = Just True})
+  test
+    "min/max exactness is checked independently"
+    ( Agg.columnMin onlyMin 0 == Just (Pred.PVBinary "B")
+        && Agg.columnMax onlyMin 0 == Nothing
+        && Agg.columnMin onlyMax 0 == Nothing
+        && Agg.columnMax onlyMax 0 == Just (Pred.PVBinary "C")
+    )
+  let legacy =
+        (statsInt64LegacyMinMax 7 9)
+          { statMinValue = Just (le64 0)
+          , statMaxValue = Just (le64 10)
+          , statMinValueExact = Just False
+          , statMaxValueExact = Just False
+          }
+      legacyFile = mkFm [mkRgTyped PTInt64 2 legacy]
+  test
+    "inexact modern bounds may fall back to compatible legacy extrema"
+    (Agg.columnMin legacyFile 0 == Just (Pred.PVInt64 7) && Agg.columnMax legacyFile 0 == Just (Pred.PVInt64 9))
+  mapM_
+    ( \flags -> do
+        let stats = compact {statMinValueExact = fst flags, statMaxValueExact = snd flags}
+            original = metadata stats
+            decoded = Footer.readFooterRaw (Thrift.encodeCompact (Footer.fileMetadataToThrift original))
+        test
+          "exactness flags preserve missing, false and true through raw Thrift"
+          (decoded == Right original)
+    )
+    [(Nothing, Nothing), (Just False, Just True), (Just True, Just False)]
+  let allNull = mkRgTyped PTInt32 3 (emptyStats {statNullCount = Just 3})
+      empty = mkRgTyped PTInt32 0 emptyStats
+      exact = mkRgTyped PTInt32 2 (statsInt32MinMax 7 9)
+  test
+    "all-null and empty groups do not poison known extrema"
+    ( Agg.columnMin (mkFm [allNull, exact, empty]) 0 == Just (Pred.PVInt32 7)
+        && Agg.columnMax (mkFm [empty, exact, allNull]) 0 == Just (Pred.PVInt32 9)
+    )
+  test
+    "entirely null or empty columns have no extrema"
+    (Agg.columnMin (mkFm [allNull, empty]) 0 == Nothing && Agg.columnMax (mkFm [allNull, empty]) 0 == Nothing)
+  let floating =
+        emptyStats
+          { statMinValue = Just (BS.pack [0, 0, 128, 63])
+          , statMaxValue = Just (BS.pack [0, 0, 0, 64])
+          , statMinValueExact = Just True
+          , statMaxValueExact = Just True
+          , statNullCount = Just 0
+          }
+      floatFile nans = mkFm [mkRgTyped PTFloat 2 (floating {statNanCount = nans})]
+  mapM_
+    ( \nans ->
+        test
+          "unknown/present NaNs require an explicit scan policy"
+          (Agg.columnMin (floatFile nans) 0 == Nothing && Agg.columnMax (floatFile nans) 0 == Nothing)
+    )
+    [Nothing, Just 1]
+  test
+    "known NaN-free exact floating statistics answer min/max"
+    ( Agg.columnMin (floatFile (Just 0)) 0 == Just (Pred.PVFloat 1)
+        && Agg.columnMax (floatFile (Just 0)) 0 == Just (Pred.PVFloat 2)
+    )
+
+
+countRegression :: (String -> Bool -> IO ()) -> IO ()
+countRegression test = do
+  let group = mkRgTyped PTInt32 3 (statsWithNullCount 1)
+      file = mkFm [group]
+      mapColumn change = group {rgColumns = fmap (\column -> column {ccMetadata = change <$> ccMetadata column}) (rgColumns group)}
+      withNulls n = mapColumn (\metadata -> metadata {cmStatistics = Just (statsWithNullCount n)})
+  mapM_
+    ( \nulls ->
+        test
+          "invalid null counts cannot produce a non-null row count"
+          (Agg.columnNonNullCount (mkFm [withNulls nulls]) 0 == Nothing)
+    )
+    [-1, 4]
+  test
+    "flat events must include null rows"
+    (Agg.columnNonNullCount (mkFm [mapColumn (\metadata -> metadata {cmNumValues = 2})]) 0 == Nothing)
+  test
+    "missing/negative column ordinals do not invent counts"
+    (Agg.columnNonNullCount file (-1) == Nothing && Agg.columnNonNullCount file 1 == Nothing)
+  let required = file {fmSchema = fmSchema file V.// [(1, (fmSchema file V.! 1) {seRepetition = Just Required})]}
+  test "required paths cannot report null rows" (Agg.columnNonNullCount required 0 == Nothing)
+  let repeated = file {fmSchema = fmSchema file V.// [(1, (fmSchema file V.! 1) {seRepetition = Just Repeated})]}
+  test "repeated events do not establish a non-null row count" (Agg.columnNonNullCount repeated 0 == Nothing)
+  let root = SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+      parent = SchemaElement "record" (Just Optional) Nothing (Just 1) Nothing Nothing Nothing Nothing
+      leaf = SchemaElement "x" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+      nested =
+        file
+          { fmSchema = V.fromList [root, parent, leaf]
+          , fmRowGroups =
+              V.singleton
+                (mapColumn (\metadata -> metadata {cmPathInSchema = V.fromList ["record", "x"]}))
+          }
+  test
+    "nullable ancestors contribute null rows to a required leaf"
+    (Agg.columnNonNullCount nested 0 == Just 2)
+  let repeatedAncestor = nested {fmSchema = fmSchema nested V.// [(1, parent {seRepetition = Just Repeated})]}
+  test
+    "repeated ancestors also prevent leaf non-null row counts"
+    (Agg.columnNonNullCount repeatedAncestor 0 == Nothing)
+  mapM_
+    ( \bad -> do
+        test
+          "invalid file/group row counts fail checked aggregation"
+          (Agg.fileRowCountChecked bad == Nothing && Agg.columnNonNullCount bad 0 == Nothing)
+    )
+    [ file {fmNumRows = -1}
+    , file {fmNumRows = 2}
+    , file {fmNumRows = 4}
+    , file {fmRowGroups = V.singleton (group {rgNumRows = -1})}
+    , file {fmNumRows = maxBound, fmRowGroups = V.fromList [group {rgNumRows = maxBound}, group]}
+    ]
+  test
+    "stale file totals preserve historical group-sum behavior"
+    (Agg.fileRowCount (file {fmNumRows = 0}) == 3)
+  mapM_
+    ( \bad ->
+        test
+          "negative row counts reject at footer boundary"
+          (case Footer.readFooterRaw (Thrift.encodeCompact (Footer.fileMetadataToThrift bad)) of Left _ -> True; Right _ -> False)
+    )
+    [file {fmNumRows = -1}, file {fmRowGroups = V.singleton (group {rgNumRows = -1})}]
+  let stale = file {fmNumRows = 0}
+  test
+    "stale totals remain available for data decoding and checked validation"
+    (Footer.readFooterRaw (Thrift.encodeCompact (Footer.fileMetadataToThrift stale)) == Right stale)
+  let huge = mkRgTyped PTInt32 maxBound (statsWithNullCount 0)
+  test
+    "empty groups need no null statistics to establish count zero"
+    (Agg.columnNonNullCount (mkFm [mkRg 0 [(Just 0, Nothing)]]) 0 == Just 0)
+  test
+    "maximum signed64 row count remains exact"
+    ( Agg.fileRowCountChecked (mkFm [huge]) == Just maxBound
+        && Agg.columnNonNullCount (mkFm [huge]) 0 == Just maxBound
+    )
+
+
+mkRgTyped :: ParquetType -> Int64 -> Statistics -> RowGroup
+mkRgTyped ty rows stats =
+  let group = mkRg rows [(Just rows, Just stats)]
+  in group
+       { rgColumns =
+           V.map
+             (\column -> column {ccMetadata = (\metadata -> metadata {cmType = ty}) <$> ccMetadata column})
+             (rgColumns group)
+       }
+
+
+data CountCase = CountCase
+  { countRows :: {-# UNPACK #-} !Int64
+  , countNulls :: {-# UNPACK #-} !Int64
+  }
+  deriving (Show)
+
+
+-- An Integer oracle catches machine-integer overflow across generated groups.
+countProperty :: IO ()
+countProperty = do
+  passed <- H.check $ H.withTests 100 $ H.property $ do
+    cases <- H.forAll (Gen.nonEmpty (Range.linear 1 20) generate)
+    let groups = (\c -> mkRgTyped PTInt32 (countRows c) (statsWithNullCount (countNulls c))) <$> NE.toList cases
+        rows = sum (toInteger . countRows <$> cases)
+        present = sum ((\c -> toInteger (countRows c) - toInteger (countNulls c)) <$> cases)
+        fits = rows <= toInteger (maxBound :: Int64)
+        metadata = (mkFm groups) {fmNumRows = if fits then fromInteger rows else maxBound}
+    H.cover 5 "bounded total" fits
+    H.cover 5 "overflowing total" (not fits)
+    Agg.fileRowCountChecked metadata H.=== (if fits then Just (fromInteger rows) else Nothing)
+    Agg.columnNonNullCount metadata 0 H.=== (if fits then Just (fromInteger present) else Nothing)
+  if passed then pure () else error "FAIL: aggregate count property"
+  where
+    generate = do
+      rows <- Gen.frequency [(3, Gen.int64 (Range.linear 0 1000000)), (1, Gen.int64 (Range.constant 0 maxBound))]
+      nulls <- Gen.int64 (Range.constant 0 rows)
+      pure (CountCase rows nulls)
diff --git a/test/AlpRegression.hs b/test/AlpRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/AlpRegression.hs
@@ -0,0 +1,242 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module AlpRegression (run) where
+
+import Control.Concurrent (forkIO, newEmptyMVar, putMVar, takeMVar, tryReadMVar, yield)
+import Control.Exception (evaluate, finally)
+import Control.Monad (unless)
+import Data.Bits (setBit, shiftL, testBit, (.&.))
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as B
+import Data.ByteString.Lazy qualified as L
+import Data.Either (isLeft)
+import Data.Int (Int32, Int64)
+import Data.Vector.Primitive qualified as P
+import Data.Word (Word32, Word64, Word8)
+import GHC.Float (castDoubleToWord64, castFloatToWord32)
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Alp qualified as Alp
+import System.Mem (performGC)
+
+
+data ExceptionValue = ExceptionValue
+  { exceptionPosition :: !Int
+  , exceptionBits :: !Word64
+  }
+
+
+data TestVector = TestVector
+  { vectorCount :: !Int
+  , vectorExponent :: !Int
+  , vectorFactor :: !Int
+  , vectorWidth :: !Int
+  , vectorFrame :: !Word64
+  , vectorDeltas :: !(P.Vector Word64)
+  , vectorExceptions :: ![ExceptionValue]
+  }
+
+
+data PageFixture = PageFixture
+  { fixtureBytes :: !BS.ByteString
+  , fixtureVectors :: ![TestVector]
+  , fixtureCount :: !Int
+  }
+
+
+run :: IO ()
+run = do
+  mapM_ (\width -> mapM_ (fixed width) [0 .. width * 8]) [4, 8]
+  mapM_ decimalParameters [4, 8]
+  mapM_ (\width -> mapM_ (sizing width) [3 .. 15]) [4, 8]
+  mapM_ malformed [4, 8]
+  ok <- H.check $ H.withTests 300 $ H.property $ do
+    width <- H.forAll (Gen.element [4, 8])
+    bits <- H.forAll (Gen.int (Range.linear 0 (width * 8)))
+    count <- H.forAll (Gen.int (Range.linear 0 257))
+    logSize <- H.forAll (Gen.int (Range.linear 3 8))
+    decimalExponent <- H.forAll (Gen.int (Range.linear 0 (if width == 4 then 10 else 18)))
+    factor <- H.forAll (Gen.int (Range.linear 0 decimalExponent))
+    seed <- H.forAll (Gen.word64 Range.constantBounded)
+    let page = fixture width logSize count bits decimalExponent factor seed
+    H.assert (matches width page)
+  unless ok (fail "ALP generated page regression")
+  gcPressure
+  putStrLn "ALP: full bit widths, vector sizes, malformed pages, IEEE exceptions and 300 generated pages passed"
+  where
+    fixed width bits = do
+      let page = fixture width 3 19 bits (if width == 4 then 10 else 18) 3 0x9876543210
+      unless (matches width page) (fail ("ALP full-width model mismatch: " <> show (width, bits)))
+      mapM_
+        ( \offset ->
+            unless
+              (matches width (page {fixtureBytes = BS.drop offset (BS.replicate offset 0xff <> fixtureBytes page)}))
+              (fail "ALP misaligned input differs")
+        )
+        [1, 3, 7, 15]
+    decimalParameters width =
+      mapM_
+        ( \e ->
+            mapM_
+              ( \f ->
+                  unless
+                    (matches width (fixture width 3 19 (width * 8) e f 9191))
+                    (fail ("ALP decimal parameter mismatch: " <> show (width, e, f)))
+              )
+              [0 .. e]
+        )
+        [0 .. if width == 4 then 10 else 18]
+    sizing width logSize = do
+      let page = fixture width logSize ((1 `shiftL` logSize) + 1) 7 4 3 31337
+      unless (matches width page) (fail ("ALP vector-size mismatch: " <> show (width, logSize)))
+
+
+-- Multiple 32768-row vectors cross the bounded native-call limits. Keep a
+-- collector active until every fresh result has been checked, exercising
+-- ownership of the movable output between chunks and exception patches.
+gcPressure :: IO ()
+gcPressure = do
+  stop <- newEmptyMVar
+  done <- newEmptyMVar
+  let collect = do
+        finished <- tryReadMVar stop
+        case finished of
+          Just () -> pure ()
+          Nothing -> performGC >> yield >> collect
+  _ <- forkIO (collect `finally` putMVar done ())
+  let check width seed = do
+        let page = fixture width 15 65537 (width * 8) (if width == 4 then 10 else 18) 3 seed
+        correct <- evaluate (matches width page)
+        unless correct (fail "ALP large page changed under concurrent GC")
+  mapM_ (\seed -> check 4 seed >> check 8 seed) [1 .. 8]
+    `finally` (putMVar stop () >> takeMVar done)
+
+
+matches :: Int -> PageFixture -> Bool
+matches width page
+  | width == 4 =
+      fmap (P.map castFloatToWord32) (Alp.decodeAlpFloat (fixtureCount page) (fixtureBytes page))
+        == Right (P.concat (map expectedFloat (fixtureVectors page)))
+  | otherwise =
+      fmap (P.map castDoubleToWord64) (Alp.decodeAlpDouble (fixtureCount page) (fixtureBytes page))
+        == Right (P.concat (map expectedDouble (fixtureVectors page)))
+
+
+expectedFloat :: TestVector -> P.Vector Word32
+expectedFloat v = P.generate (vectorCount v) $ \i ->
+  fromIntegral $
+    expectedBits i (vectorExceptions v) $
+      fromIntegral $
+        castFloatToWord32 $
+          (fromIntegral (fromIntegral (vectorFrame v + vectorDeltas v P.! i) :: Int32) * (positive !! vectorFactor v) :: Float)
+            * (negative !! vectorExponent v)
+
+
+expectedDouble :: TestVector -> P.Vector Word64
+expectedDouble v = P.generate (vectorCount v) $ \i ->
+  expectedBits i (vectorExceptions v) $
+    castDoubleToWord64 $
+      (fromIntegral (fromIntegral (vectorFrame v + vectorDeltas v P.! i) :: Int64) * (positive !! vectorFactor v) :: Double)
+        * (negative !! vectorExponent v)
+
+
+expectedBits :: Int -> [ExceptionValue] -> Word64 -> Word64
+expectedBits i exceptions original = foldl' (\value e -> if exceptionPosition e == i then exceptionBits e else value) original exceptions
+
+
+positive :: Fractional a => [a]
+positive = [1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13, 1e14, 1e15, 1e16, 1e17, 1e18]
+
+
+negative :: Fractional a => [a]
+negative = [1e0, 1e-1, 1e-2, 1e-3, 1e-4, 1e-5, 1e-6, 1e-7, 1e-8, 1e-9, 1e-10, 1e-11, 1e-12, 1e-13, 1e-14, 1e-15, 1e-16, 1e-17, 1e-18]
+
+
+fixture :: Int -> Int -> Int -> Int -> Int -> Int -> Word64 -> PageFixture
+fixture width logSize count bits decimalExponent factor seed = PageFixture bytes vectors count
+  where
+    vectorSize = 1 `shiftL` logSize
+    vectors = makeVectors 0 count
+    makeVectors offset remaining
+      | remaining == 0 = []
+      | otherwise =
+          let n = min vectorSize remaining
+              mask = if bits == 64 then maxBound else (1 `shiftL` bits) - 1
+              deltas = P.generate n (\i -> if i == 0 then 0 else if i == 1 then mask else (seed + fromIntegral (offset + i) * 6364136223846793005) .&. mask)
+              exceptions =
+                if width == 4
+                  then [ExceptionValue (n - 1) 0x7fc0dead, ExceptionValue 0 0x80000000]
+                  else [ExceptionValue (n - 1) 0x7ff800deadbeef00, ExceptionValue 0 0x8000000000000000]
+          in TestVector n decimalExponent factor bits (1 `shiftL` (width * 8 - 1)) deltas exceptions : makeVectors (offset + n) (remaining - n)
+    encoded = map (encodeVector width) vectors
+    offsets = init (scanl (+) (length vectors * 4) (map BS.length encoded))
+    bytes =
+      strict $
+        B.word8 0
+          <> B.word8 0
+          <> B.word8 (fromIntegral logSize)
+          <> B.int32LE (fromIntegral count)
+          <> foldMap (B.word32LE . fromIntegral) offsets
+          <> foldMap B.byteString encoded
+
+
+encodeVector :: Int -> TestVector -> BS.ByteString
+encodeVector width v =
+  strict $
+    B.word8 (fromIntegral (vectorExponent v))
+      <> B.word8 (fromIntegral (vectorFactor v))
+      <> B.word16LE (fromIntegral (length (vectorExceptions v)))
+      <> word width (vectorFrame v)
+      <> B.word8 (fromIntegral (vectorWidth v))
+      <> packed
+      <> foldMap (B.word16LE . fromIntegral . exceptionPosition) (vectorExceptions v)
+      <> foldMap (word width . exceptionBits) (vectorExceptions v)
+  where
+    bitCount = vectorCount v * vectorWidth v
+    packed = foldMap (B.word8 . byte) [0 .. (bitCount + 7) `quot` 8 - 1]
+    byte offset =
+      foldl'
+        ( \acc b ->
+            let global = offset * 8 + b
+            in if global < bitCount && testBit (vectorDeltas v P.! (global `quot` vectorWidth v)) (global `rem` vectorWidth v)
+                 then setBit acc b
+                 else acc
+        )
+        (0 :: Word8)
+        [0 .. 7]
+
+
+word :: Int -> Word64 -> B.Builder
+word 4 = B.word32LE . fromIntegral
+word _ = B.word64LE
+
+
+strict :: B.Builder -> BS.ByteString
+strict = L.toStrict . B.toLazyByteString
+
+
+malformed :: Int -> IO ()
+malformed width = do
+  let page = fixture width 3 3 3 4 3 42
+      bytes = fixtureBytes page
+      decode n raw = if width == 4 then (() <$ Alp.decodeAlpFloat n raw) else (() <$ Alp.decodeAlpDouble n raw)
+      replace offset values = BS.take offset bytes <> values <> BS.drop (offset + BS.length values) bytes
+      mutants =
+        [ replace 0 (BS.singleton 1)
+        , replace 1 (BS.singleton 1)
+        , replace 2 (BS.singleton 2)
+        , replace 2 (BS.singleton 16)
+        , replace 3 (strict (B.int32LE (-1)))
+        , replace 7 (strict (B.word32LE 5))
+        , replace 11 (BS.singleton 255)
+        , replace 12 (BS.singleton 5)
+        , replace (15 + width) (BS.singleton (fromIntegral (width * 8 + 1)))
+        , replace (16 + width) (BS.pack [0, 0x80])
+        , replace (18 + width) (strict (B.word16LE 3))
+        , bytes <> BS.singleton 0
+        ]
+  mapM_ (\raw -> unless (isLeft (decode 3 raw)) (fail "ALP accepted a malformed page")) mutants
+  mapM_ (\n -> unless (isLeft (decode 3 (BS.take n bytes))) (fail "ALP accepted a truncated page")) [0 .. BS.length bytes - 1]
+  mapM_ (\n -> unless (isLeft (decode n bytes)) (fail "ALP accepted a wrong count")) [-1, 0, 2, 4, maxBound]
+  unless (matches width (fixture width 3 0 0 0 0 0)) (fail "ALP empty page")
diff --git a/test/BloomBuilderRegression.hs b/test/BloomBuilderRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/BloomBuilderRegression.hs
@@ -0,0 +1,106 @@
+module BloomBuilderRegression (tests) where
+
+import Control.Exception (evaluate)
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Int (Int32)
+import Data.Vector qualified as V
+import Data.Vector.Unboxed qualified as U
+import GHC.Conc (getAllocationCounter)
+import Hedgehog (Group (..), assert, checkParallel, forAll, property, (===))
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.BloomFilter qualified as B
+import System.Mem (performGC)
+
+
+check :: String -> Bool -> IO ()
+check label success = unless success (fail ("bloom builder: " ++ label))
+
+
+bulk :: Int -> V.Vector BS.ByteString -> B.Sbbf
+bulk size values = B.buildSbbf size (\builder -> V.forM_ values (B.sbbfBuilderInsert builder))
+
+
+incremental :: Int -> V.Vector BS.ByteString -> B.Sbbf
+incremental size = V.foldl' (flip B.sbbfInsert) (B.newSbbf size)
+
+
+encoded :: B.Sbbf -> BS.ByteString
+encoded = B.encodeBloomFilter
+
+
+allocation :: BS.ByteString -> IO Int
+allocation bytes = do
+  performGC
+  before <- getAllocationCounter
+  _ <- evaluate (BS.length bytes)
+  after <- getAllocationCounter
+  pure (fromIntegral (before - after))
+
+
+tests :: IO ()
+tests = do
+  okay <-
+    checkParallel $
+      Group
+        "bulk bloom construction"
+        [
+          ( "same wire bits and membership"
+          , property $ do
+              size <- forAll (Gen.element [32, 64, 96, 256, 4096])
+              values <- V.fromList <$> forAll (Gen.list (Range.linear 0 180) (Gen.bytes (Range.linear 0 80)))
+              let built = bulk size values
+                  original = incremental size values
+              encoded built === encoded original
+              assert (V.all (`B.sbbfCheck` built) values)
+              assert (B.sbbfNumBytes built == size)
+          )
+        ,
+          ( "eight-hash sizing estimate"
+          , property $ do
+              count <- forAll (Gen.int (Range.linear 1 100000))
+              probability <- forAll (Gen.element [0.000001, 0.0001, 0.01, 0.1, 0.5])
+              let bytes = B.optimalNumBytes count probability
+                  estimated = (1 - exp (negate (fromIntegral count / fromIntegral bytes))) ** 8
+              assert (bytes >= 32 && bytes `rem` 32 == 0)
+              assert (estimated <= probability + 1e-12)
+          )
+        ]
+  check "properties" okay
+  forM_ [BS.empty, BS.replicate 1 0, BS.replicate 31 0, BS.replicate 33 0] $ \bytes ->
+    check "malformed raw bitsets are rejected before unsafe lane access" (isLeft (B.newSbbfFromBytesChecked bytes))
+  forM_ [0, 31, 33, maxBound] $ \size ->
+    check "invalid exact-size constructors are rejected" (isLeft (B.newSbbfBytesChecked size U.empty))
+  check "decoded word count must match declared size" (isLeft (B.newSbbfBytesChecked 32 (U.singleton 0)))
+  check "oversized allocation request is rejected before rounding" (isLeft (B.newSbbfChecked maxBound))
+  check "oversized bulk request is rejected before allocation" (isLeft (B.buildSbbfChecked maxBound (\_ -> pure ())))
+  forM_ [-1, 0, 1, 31, 32, 33] $ \size -> do
+    emptyFilter <- either fail pure (B.newSbbfChecked size)
+    let rounded = if size <= 32 then 32 else 64
+    check "normal allocation preserves minimum/rounding rules" (B.sbbfNumBytes emptyFilter == rounded)
+  let rawWords = [0x0123456789abcdef, 0xfedcba9876543210, 0x8000000000000001, 0x0102030405060708]
+      expectedBits = BS.pack [0xef, 0xcd, 0xab, 0x89, 0x67, 0x45, 0x23, 0x01, 0x10, 0x32, 0x54, 0x76, 0x98, 0xba, 0xdc, 0xfe, 0x01, 0, 0, 0, 0, 0, 0, 0x80, 0x08, 0x07, 0x06, 0x05, 0x04, 0x03, 0x02, 0x01]
+  forM_ [0, 1, 3, 8] $ \offset -> do
+    let guarded = U.fromList (replicate offset 0xdeadbeef ++ rawWords ++ replicate 4 0xdeadbeef)
+    filter_ <- either fail pure (B.newSbbfBytesChecked 32 (U.slice offset 4 guarded))
+    let bytes = encoded filter_
+    check "serialization respects word-vector slices and little-endian layout" (BS.drop (BS.length bytes - 32) bytes == expectedBits)
+    (_, decoded) <- either fail pure (B.decodeBloomFilter bytes)
+    check "sliced bitsets round-trip without neighboring guard words" (decoded == filter_)
+  let limit = fromIntegral (maxBound :: Int32) - 31
+  -- Independent100-digit Decimal evaluation gives25762.411444445775...
+  -- bytes before rounding. Computing the eighth root first rounds it to1.
+  let belowOne = encodeFloat (2 ^ (53 :: Int) - 1) (-53) :: Double
+  check "probability immediately below1 keeps its finite sizing estimate" (B.optimalNumBytes 1000000 belowOne == 25792)
+  check "huge NDV sizing saturates without integer overflow" (B.optimalNumBytes maxBound 0.01 == limit)
+  check "tiny probability keeps a finite representable size" (B.optimalNumBytes 1 5e-324 == limit)
+  forM_ [0, 1, -1, 0 / 0, 1 / 0, -1 / 0] $ \probability ->
+    check "invalid probability has a deterministic fallback" (B.optimalNumBytes 100 probability == 32)
+  let values = V.generate 4096 (\index -> BS.pack [fromIntegral index, fromIntegral (index `quot` 256), 0, 0])
+  _ <- evaluate (V.foldl' (\total bytes -> total + BS.length bytes) 0 values)
+  bulkBytes <- allocation (encoded (bulk 32768 values))
+  oldBytes <- allocation (encoded (incremental 32768 values))
+  check "whole-column construction avoids a bitset copy per row" (bulkBytes * 8 < oldBytes)
+  putStrLn ("Bloom allocation regression: bulk=" ++ show bulkBytes ++ ", incremental=" ++ show oldBytes)
diff --git a/test/CodecBoundaryRegression.hs b/test/CodecBoundaryRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/CodecBoundaryRegression.hs
@@ -0,0 +1,95 @@
+{-# LANGUAGE CPP #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+module CodecBoundaryRegression (tests) where
+
+import Control.Exception (evaluate)
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import GHC.Conc (getAllocationCounter)
+import Parquet.Compress qualified as Compress
+import Parquet.Page qualified as Page
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+import Parquet.Write qualified as Write
+import System.Mem (performGC)
+
+
+check :: String -> Bool -> IO ()
+check name ok = unless ok (fail ("Codec/page regression: " ++ name))
+
+
+pageV1 :: Int -> BS.ByteString -> BS.ByteString
+pageV1 expected body = Write.encodePageHeader (Page.PageHeader (Page.PtDataPage (Page.DataPageHeader 1 0)) (Just (fromIntegral expected)) (Just (fromIntegral (BS.length body)))) <> body
+
+
+pageV2 :: Bool -> Int -> BS.ByteString -> BS.ByteString
+pageV2 compressed expected body = Write.encodePageHeader (Page.PageHeader (Page.PtDataPageV2 (Page.DataPageHeaderV2 1 1 1 0 2 0 compressed)) (Just (fromIntegral expected + 2)) (Just (fromIntegral (BS.length body) + 2))) <> BS.pack [2, 0] <> body
+
+
+tests :: IO ()
+tests = do
+  forM_ [False, True] $ \compressed -> forM_ [P.Uncompressed, P.GZip, P.Snappy, P.ZSTD, P.Brotli, P.LZ4Raw, P.LZO] $ \codec -> do
+    check "all-null V2 does not ignore non-empty invalid payload" (isLeft (Read.decompressDataPageV2Body codec 0 1 (pageV2 compressed 0 "invalid codec bytes") 0))
+    check "all-null V2 with absent values remains readable" (case Read.decompressDataPageV2Body codec 0 1 (pageV2 compressed 0 BS.empty) 0 of Right (_, _, _, _, values, _) -> BS.null values; Left _ -> False)
+  let available = [P.Uncompressed, P.GZip, P.Snappy, P.ZSTD, P.LZ4Raw, P.LZO, P.Brotli]
+  forM_ available $ \codec -> case Compress.validateCompression codec of
+    Left _ -> pure ()
+    Right () -> do
+      emptyValues <- either fail pure (Compress.compressPageBytes codec BS.empty)
+      check ("enabled codec empty V1 bytes: " ++ show codec) (case Read.decompressDataPageBody codec (pageV1 0 emptyValues) 0 of Right (_, _, value, _) -> BS.null value; Left _ -> False)
+      check ("enabled codec empty V2 values: " ++ show codec) (case Read.decompressDataPageV2Body codec 0 1 (pageV2 True 0 emptyValues) 0 of Right (_, _, _, _, value, _) -> BS.null value; Left _ -> False)
+      let raw = BS.pack [0 .. 255]
+      encoded <- either fail pure (Compress.compressPageBytes codec raw)
+      check "every enabled codec validates declared V1 output size" (isLeft (Read.decompressDataPageBody codec (pageV1 (BS.length raw + 1) encoded) 0))
+      check "every enabled codec preserves exact V1 bytes" (case Read.decompressDataPageBody codec (pageV1 (BS.length raw) encoded) 0 of Right (_, _, value, _) -> value == raw; Left _ -> False)
+      let large = BS.replicate (16 * 1024 * 1024) 0
+      bomb <- either fail pure (Compress.compressPageBytes codec large)
+      let framed = pageV1 8 bomb
+      _ <- evaluate (BS.length framed)
+      performGC
+      before <- getAllocationCounter
+      rejected <- evaluate (isLeft (Read.decompressDataPageBody codec framed 0))
+      after <- getAllocationCounter
+      check ("enabled codec expansion guard: " ++ show codec ++ " allocated=" ++ show (before - after)) (rejected && before - after < 1024 * 1024)
+  -- Forged frame-size headers must be rejected before requesting gigabytes
+  -- from the allocator. The compressed payload itself need not be valid.
+  forM_ [(P.Snappy, BS.pack [128, 128, 128, 128, 8]), (P.ZSTD, BS.pack [40, 181, 47, 253, 224, 0, 0, 0, 128, 0, 0, 0, 0])] $ \(codec, payload) ->
+    case Compress.validateCompression codec of
+      Left _ -> pure ()
+      Right () -> do
+        before <- getAllocationCounter
+        rejected <- evaluate (isLeft (Read.decompressChunk codec payload))
+        after <- getAllocationCounter
+        check "raw codec size ceiling is checked before allocation" (rejected && before - after < 1024 * 1024)
+  a <- either fail pure (Compress.compressPageBytes P.GZip "first")
+  b <- either fail pure (Compress.compressPageBytes P.GZip "second")
+  check "concatenated GZip members retain exact semantics" (Read.decompressChunk P.GZip (a <> b) == Right "firstsecond")
+  check "GZip trailing compressed bytes rejected" (isLeft (Read.decompressChunk P.GZip (a <> "garbage")))
+#ifdef HAVE_BROTLI
+  forM_ [BS.empty, "x", BS.pack [0..255], BS.replicate 32768 97, BS.replicate 131072 0] $ \input -> do
+    encoded <- either fail pure (Compress.compressPageBytes P.Brotli input)
+    check "unsized complete stream" (Read.decompressChunk P.Brotli encoded == Right input)
+    check "exact bounded page" (case Read.decompressDataPageBody P.Brotli (pageV1 (BS.length input) encoded) 0 of Right (_,_,raw,_) -> raw == input; Left _ -> False)
+    forM_ [0, BS.length input + 1] $ \wrong ->
+      if wrong == BS.length input then pure () else check "declared output size mismatch" (isLeft (Read.decompressDataPageBody P.Brotli (pageV1 wrong encoded) 0))
+    check "trailing compressed bytes" (isLeft (Read.decompressChunk P.Brotli (encoded <> "trailing")))
+    check "bounded trailing compressed bytes" (isLeft (Read.decompressDataPageBody P.Brotli (pageV1 (BS.length input) (encoded <> "trailing")) 0))
+    forM_ [0 .. BS.length encoded - 1] $ \prefix -> do
+      check "truncated compressed stream" (isLeft (Read.decompressChunk P.Brotli (BS.take prefix encoded)))
+      check "bounded truncated compressed stream" (isLeft (Read.decompressDataPageBody P.Brotli (pageV1 (BS.length input) (BS.take prefix encoded)) 0))
+  empty <- either fail pure (Compress.compressPageBytes P.Brotli BS.empty)
+  check "compressed empty all-null V2 stream" (case Read.decompressDataPageV2Body P.Brotli 0 1 (pageV2 True 0 empty) 0 of Right (_,_,_,_,raw,_) -> BS.null raw; Left _ -> False)
+  let large = BS.replicate (16*1024*1024) 0
+  bomb <- either fail pure (Compress.compressPageBytes P.Brotli large)
+  _ <- evaluate (BS.length bomb)
+  performGC
+  start <- getAllocationCounter
+  rejected <- evaluate (isLeft (Read.decompressDataPageBody P.Brotli (pageV1 8 bomb) 0))
+  performGC
+  end <- getAllocationCounter
+  check "advertised size prevents full expansion" (rejected && start - end < 1024*1024)
+#else
+  check "Brotli remains explicitly unavailable without its optional flag" (isLeft (Compress.validateCompression P.Brotli) && isLeft (Compress.compressPageBytes P.Brotli "x") && isLeft (Read.decompressChunk P.Brotli "x"))
+#endif
diff --git a/test/DecimalCapacityRegression.hs b/test/DecimalCapacityRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/DecimalCapacityRegression.hs
@@ -0,0 +1,102 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module DecimalCapacityRegression (tests) where
+
+import Control.Exception (evaluate)
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.Either (isRight)
+import Data.Int (Int32)
+import Data.Vector qualified as V
+import GHC.Conc (getAllocationCounter)
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Footer qualified as F
+import Parquet.Types qualified as P
+import Thrift.Encode qualified as T
+import Thrift.Value qualified as TV
+import Thrift.Wire (ThriftType (..))
+
+
+-- Raw field numbers make these fixtures independent of the footer encoder.
+metadata :: Int32 -> Maybe Int32 -> Bool -> Int32 -> TV.Value
+metadata precision width modern physical =
+  let decimal = TV.Struct (V.fromList [(1, TV.I32 0), (2, TV.I32 precision)])
+      leaf = TV.Struct (V.fromList ([(1, TV.I32 physical), (3, TV.I32 0), (4, TV.String "d"), (6, TV.I32 5), (7, TV.I32 0), (8, TV.I32 precision)] ++ maybe [] (\n -> [(2, TV.I32 n)]) width ++ if modern then [(10, TV.Struct (V.singleton (5, decimal)))] else []))
+      root = TV.Struct (V.fromList [(4, TV.String "schema"), (5, TV.I32 1)])
+  in TV.Struct (V.fromList [(1, TV.I32 1), (2, TV.List TT_STRUCT (V.fromList [root, leaf])), (3, TV.I64 0), (4, TV.List TT_STRUCT V.empty)])
+
+
+accepted :: Int32 -> Int32 -> Bool -> Bool
+accepted precision width modern = isRight (F.readFooterRaw (T.encodeCompact (metadata precision (Just width) modern 7)))
+
+
+compatible :: Int32 -> Int32 -> Bool
+compatible precision width =
+  P.hasCompatiblePhysicalType
+    P.SchemaElement
+      { P.seName = "d"
+      , P.seRepetition = Just P.Required
+      , P.seType = Just P.PTFixedLenByteArray
+      , P.seTypeLength = Just width
+      , P.seNumChildren = Nothing
+      , P.seConvertedType = Just P.CTDecimal
+      , P.seLogicalType = Just (P.LTDecimal precision 0)
+      , P.seFieldId = Nothing
+      }
+
+
+exactCapacity :: Int -> Int
+exactCapacity width = search 0 (8 * width)
+  where
+    limit = (2 :: Integer) ^ (8 * width - 1)
+    search low high
+      | high - low <= 1 = low
+      | (10 :: Integer) ^ middle <= limit = search middle high
+      | otherwise = search low middle
+      where
+        middle = (low + high) `quot` 2
+
+
+check :: String -> Bool -> IO ()
+check name ok = unless ok (fail ("DECIMAL capacity regression: " ++ name))
+
+
+tests :: IO ()
+tests = do
+  forM_ [1 .. 512] $ \width -> do
+    let capacity = fromIntegral (exactCapacity width)
+        physicalWidth = fromIntegral width
+    forM_ [False, True] $ \modern -> do
+      check "exact capacity is accepted" (accepted capacity physicalWidth modern)
+      check "one digit past capacity is rejected" (not (accepted (capacity + 1) physicalWidth modern))
+    check "physical compatibility accepts exact capacity" (compatible capacity physicalWidth)
+    check "physical compatibility rejects excess precision" (not (compatible (capacity + 1) physicalWidth))
+  forM_ [(77, 1), (77, 32), (80, 33), (1000, 33), (maxBound, 32)] $ \(precision, width) -> do
+    check "large declared precision cannot bypass fixed capacity" (not (accepted precision width True) && not (accepted precision width False) && not (compatible precision width))
+  forM_ [(79, 33), (1000, 416), (maxBound, maxBound), (maxBound, 1000000000), (9, 536870913)] $ \(precision, width) -> do
+    check "large valid metadata is accepted without Arrow's76-digit cap" (accepted precision width True && accepted precision width False && compatible precision width)
+  forM_ [(0, 1), (-1, 1), (1, 0), (1, -1)] $ \(precision, width) ->
+    check "nonpositive precision/width is invalid" (not (accepted precision width True) && not (compatible precision width))
+  forM_ [77, 1000, maxBound] $ \precision -> do
+    check "BYTE_ARRAY precision remains unbounded by its storage type" (isRight (F.readFooterRaw (T.encodeCompact (metadata precision Nothing True 6))))
+    check "legacy BYTE_ARRAY precision remains unbounded" (isRight (F.readFooterRaw (T.encodeCompact (metadata precision Nothing False 6))))
+  passed <- H.check $ H.withTests 1000 $ H.property $ do
+    width <- H.forAll (Gen.int (Range.linear 1 4096))
+    precision <- H.forAll (Gen.int (Range.linear 1 10000))
+    let expected = (10 :: Integer) ^ precision <= (2 :: Integer) ^ (8 * width - 1)
+    accepted (fromIntegral precision) (fromIntegral width) True H.=== expected
+    compatible (fromIntegral precision) (fromIntegral width) H.=== expected
+  check "generated widths/precisions agree with independent exact powers" passed
+  -- Only metadata is parsed. Declared byte widths must never drive a value
+  -- allocation or an enormous exponent before normal read limits can apply.
+  let bytes = T.encodeCompact (metadata maxBound (Just maxBound) True 7)
+  _ <- evaluate (BS.length bytes)
+  let warm = T.encodeCompact (metadata 1 (Just maxBound) True 7)
+  _ <- evaluate (V.length (case F.readFooterRaw warm of Right file -> P.fmSchema file; Left message -> error message))
+  before <- getAllocationCounter
+  value <- evaluate (case F.readFooterRaw bytes of Right file -> V.length (P.fmSchema file); Left message -> error message)
+  after <- getAllocationCounter
+  check "huge valid width uses bounded metadata memory" (value == 2 && before - after < 1024 * 1024)
+  putStrLn "DECIMAL full-width capacity, legacy/modern, exact-boundary and metadata-memory regressions passed"
diff --git a/test/EncryptedReadRegression.hs b/test/EncryptedReadRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/EncryptedReadRegression.hs
@@ -0,0 +1,271 @@
+{-# LANGUAGE PatternSynonyms #-}
+
+module EncryptedReadRegression (tests) where
+
+import Arrow.Types qualified as AT
+import Control.Monad (forM_, unless)
+import Data.Bits (complement, shiftR, xor, (.&.))
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Map.Strict qualified as Map
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Data.Word (Word32)
+import GHC.Stack (HasCallStack, callStack, prettyCallStack)
+import Parquet.Arrow qualified as A
+import Parquet.BloomFilter qualified as Bloom
+import Parquet.Decryption qualified as D
+import Parquet.Encryption qualified as E
+import Parquet.Footer qualified as F
+import Parquet.HighLevel qualified as H
+import Parquet.Page qualified as Page
+import Parquet.PageIndex qualified as Index
+import Parquet.Predicate qualified as Predicate
+import Parquet.Read qualified as R
+import Parquet.Thrift.Schema
+import Parquet.Types
+import Parquet.Write qualified as W
+import Thrift.Decode (decodeCompactFrom)
+import Thrift.Encode (encodeCompact)
+import Thrift.Value qualified as TV
+
+
+tests :: IO ()
+tests = do
+  bloomBoundaries
+  checksumRegression E.AesGcmV1 W.PageV1 16
+  checksumRegression E.AesGcmCtrV1 W.PageV2 24
+  forM_ [16, 24, 32] $ \width ->
+    forM_ [E.AesGcmV1, E.AesGcmCtrV1] $ \algorithm ->
+      forM_ [W.PageV1, W.PageV2] $ \version -> do
+        putStrLn ("Encrypted read regression: " ++ show width ++ " / " ++ show algorithm ++ " / " ++ show version)
+        let key = BS.replicate width 0x42
+            prefix = "tester"
+        footer <- W.newFooterEncryption key prefix "kf"
+        let encryption = W.ColumnEncryption algorithm key (W.feFileId footer) prefix "" 0
+            options =
+              H.defaultWriteOptions
+                { H.writeCompression = Uncompressed
+                , H.writeFooterEncryption = Just footer
+                , H.writeColumnEncryption = V.fromList [Just encryption, Nothing]
+                , H.writeBloomFilters = ["x"]
+                , H.writePageVersion = version
+                }
+            rows base = V.fromList [W.ColInt32 (VP.fromList [base + 1, base + 2, base + 3, base + 4]), W.ColByteArray (V.fromList ["a", "b", "c", "d"])]
+            groups = [rows 0, rows 10]
+            config = D.defaultDecryptionConfig {D.dcKeyMetadataKeys = Map.singleton "kf" key}
+        bytes <- H.encodeParquetIO options schema groups >>= right
+        file <- right (H.decodeParquet H.defaultReadOptions {H.readDecryptionConfig = Just config} bytes)
+        check "high-level writer encrypts exactly the requested column" (R.isColumnEncrypted file 0 0 && not (R.isColumnEncrypted file 0 1))
+        forM_ [V.singleton (Just encryption), V.snoc (H.writeColumnEncryption options) Nothing] $ \wrongShape -> do
+          rejected <- H.encodeParquetIO options {H.writeColumnEncryption = wrongShape} schema []
+          check "empty dataset rejects an incomplete/oversized encryption vector" (isLeft rejected)
+        noFooter <- H.encodeParquetIO options {H.writeFooterEncryption = Nothing} schema []
+        check "empty dataset cannot silently ignore a requested encrypted column" (isLeft noFooter)
+        badKey <- H.encodeParquetIO options {H.writeColumnEncryption = V.fromList [Just encryption {W.ceKey = "bad"}, Nothing]} schema []
+        check "empty dataset validates requested column keys" (isLeft badKey)
+        forM_ [0, 1] $ \group -> do
+          chunk <- right (R.columnChunkSlice file group 0)
+          values <- right (R.readInt32Levels Uncompressed 0 0 chunk)
+          check "row-group AAD and page decoding" (R.clValues values == VP.generate 4 (\i -> fromIntegral (group * 10 + i + 1)))
+          offset <- right (Index.readOffsetIndex file group 0)
+          bounds <- right (Index.readColumnIndex file group 0)
+          bloom <- right (Bloom.readBloomFilter file group 0)
+          check "encrypted indexes and bloom filter are read" (maybe False (const True) offset && maybe False (const True) bounds && maybe False (const True) bloom)
+        let metadata = R.pfFooter file
+            column = rgColumns (fmRowGroups metadata V.! 0) V.! 0
+        cm <- maybe (fail "missing metadata") pure (ccMetadata column)
+        let damagedBytes = flipByte (fromIntegral (cmDataPageOffset cm)) bytes
+        damaged <- right (R.loadParquetFileWithDecryption config damagedBytes)
+        target <- right (A.parquetFileArrowSchemaChecked damaged)
+        field <- maybe (fail "missing field") pure (V.find ((== "x") . AT.fieldName) (AT.arrowFields target))
+        check "selected damaged page is rejected" (isLeft (A.readParquetColumnWithPagePruning damaged 0 0 field (Predicate.PGtEq (Predicate.PVInt32 0))))
+        _ <- right (A.readParquetColumnWithPagePruning damaged 0 0 field (Predicate.PGtEq (Predicate.PVInt32 1000)))
+        _ <- rightArrow (A.parquetRowGroupToArrow (publicSchema target) damaged 0)
+        forM_ [(ccColumnIndexOffset column, ccColumnIndexLength column, \f -> Index.readColumnIndex f 0 0 >> Right ()), (ccOffsetIndexOffset column, ccOffsetIndexLength column, \f -> Index.readOffsetIndex f 0 0 >> Right ())] $ \(offset, size, readIndex) ->
+          case (offset, size) of
+            (Just start, Just count) -> do
+              altered <- right (R.loadParquetFileWithDecryption config (flipByte (fromIntegral start + fromIntegral count - 1) bytes))
+              check "altered encrypted index tag is rejected" (isLeft (readIndex altered))
+            _ -> fail "missing encrypted index location"
+        case (cmBloomFilterOffset cm, cmBloomFilterLength cm) of
+          (Just start, Just size) -> do
+            let raw = BS.drop (fromIntegral start) bytes
+            (_, headerEnd) <- either (\message -> fail (message ++ "; bloom offset=" ++ show start ++ ", length=" ++ show size ++ ", prefix=" ++ show (BS.take 16 raw))) pure (E.readFramedModule raw 0)
+            forM_ [fromIntegral start + headerEnd - 1, fromIntegral start + fromIntegral size - 1] $ \offset -> do
+              altered <- right (R.loadParquetFileWithDecryption config (flipByte offset bytes))
+              check "altered bloom header/bitset tag is rejected" (isLeft (Bloom.readBloomFilter altered 0 0))
+          _ -> fail "missing encrypted bloom location"
+        routed <- columnKeyMetadata footer bytes
+        let explicit = D.defaultDecryptionConfig {D.dcFooterKey = Just key, D.dcColumnKeys = Map.singleton (V.singleton "x") key}
+        resolved <- right (R.loadParquetFileWithDecryption explicit routed)
+        restored <- right (Index.readColumnIndex resolved 0 0)
+        check "column index is restored after decrypting column-specific metadata" (maybe False (const True) restored)
+        _ <- right (R.columnChunkSlice resolved 1 0)
+        missing <- right (R.loadParquetFileWithDecryption D.defaultDecryptionConfig {D.dcFooterKey = Just key} routed)
+        let routes = R.encryptedColumnKeyMetadata missing
+        check
+          "unresolved column keys can be discovered from authenticated metadata"
+          (V.length routes == 2 && V.all (\route -> D.ckmPath route == V.singleton "x" && D.ckmKeyMetadata route == Just "kf") routes)
+        check "requested column requires its own resolved key" (isLeft (R.columnChunkSlice missing 0 0))
+        missingSchema <- right (A.parquetFileArrowSchemaChecked missing)
+        _ <- rightArrow (A.parquetRowGroupToArrow (publicSchema missingSchema) missing 0)
+        let wrong = explicit {D.dcColumnKeys = Map.singleton (V.singleton "x") (BS.replicate width 0x43)}
+        wrongFile <- right (R.loadParquetFileWithDecryption wrong routed)
+        check "wrong column key reports an authentication failure" (isLeft (R.columnChunkSlice wrongFile 0 0))
+        _ <- rightArrow (A.parquetRowGroupToArrow (publicSchema missingSchema) wrongFile 0)
+        let ambiguous = H.defaultReadOptions {H.readDecryptionConfig = Just config, H.readFooterDecryption = Just (R.FooterDecryption key (W.feFileId footer) prefix)}
+        check "ambiguous decryption options are rejected" (isLeft (H.decodeParquet ambiguous bytes))
+  putStrLn "Encrypted column/key-routing/index/bloom/selective-read regressions passed (12 key/algorithm/page configurations, two row groups each)."
+
+
+bloomBoundaries :: IO ()
+bloomBoundaries = do
+  let variant = V.singleton (1, TV.Struct V.empty)
+      header size = TV.Struct (V.fromList [BloomFilterHeader_NumBytes size, BloomFilterHeader_Algorithm variant, BloomFilterHeader_Hash variant, BloomFilterHeader_Compression variant])
+  forM_ [-1, 0, 1, 31, 33] $ \size ->
+    check "invalid bloom sizes are rejected before constructing a filter" (isLeft (Bloom.decodeBloomFilter (encodeCompact (header size) <> BS.replicate 64 0)))
+  let extended = case header 32 of
+        TV.Struct fields -> TV.Struct (V.snoc fields (100, TV.Binary (BS.replicate 128 0xaa)))
+        value -> value
+  (_, filter_) <- right (Bloom.decodeBloomFilter (encodeCompact extended <> BS.replicate 32 0xff))
+  check "unknown long bloom header fields preserve the bitset boundary" (Bloom.sbbfNumBytes filter_ == 32 && Bloom.sbbfCheck "value" filter_)
+
+
+checksumRegression :: E.EncryptionAlgorithm -> W.PageVersion -> Int -> IO ()
+checksumRegression algorithm version width = do
+  _ <- right (Page.verifyPageChecksum 0xcbf43926 "123456789")
+  let key = BS.replicate width 0x42
+  footer <- W.newFooterEncryption key "tester" "kf"
+  let inputSchema = V.fromList [(schema V.! 0) {seNumChildren = Just 1}, schema V.! 1]
+      encryption = W.ColumnEncryption algorithm key (W.feFileId footer) "tester" "" 0
+      options = H.defaultWriteOptions {H.writeCompression = Uncompressed, H.writeFooterEncryption = Just footer, H.writeColumnEncryption = V.singleton (Just encryption), H.writePageVersion = version, H.writePageIndex = False}
+      config = D.defaultDecryptionConfig {D.dcFooterKey = Just key}
+      aad kind = E.buildAad "tester" (E.buildAadSuffix (W.feFileId footer) kind 0 0 0)
+  bytes <- H.encodeParquetIO options inputSchema [V.singleton (W.ColInt32 (VP.fromList [1, 2, 3, 4]))] >>= right
+  trailer <- right (F.readFooterTrailer bytes)
+  (_, cryptoEnd) <- right (decodeCompactFrom (F.ftBytes trailer) 0)
+  (header, afterHeader) <- right (E.readFramedModule bytes 4)
+  (_, afterBody) <- right (E.readFramedModule bytes afterHeader)
+  let wireBody = BS.take (afterBody - afterHeader) (BS.drop afterHeader bytes)
+  plainHeader <- right (E.decryptGcmModule key (aad E.ModuleDataPageHeader) header)
+  (headerValue, _) <- right (decodeCompactFrom plainHeader 0)
+  original <- right (E.authenticateFooter key Nothing Nothing bytes)
+  forM_ [False, True] $ \incorrect -> do
+    let checksum = crcReference wireBody `xor` if incorrect then 1 else 0
+    updatedHeader <- case headerValue of
+      TV.Struct fields -> pure (TV.Struct (V.snoc fields (PageHeader_Crc (fromIntegral checksum))))
+      _ -> fail "expected encrypted page header"
+    encryptedHeader <- E.encryptGcmModuleFramed key (aad E.ModuleDataPageHeader) (encodeCompact updatedHeader) >>= right
+    let delta = fromIntegral (BS.length encryptedHeader - (afterHeader - 4))
+        updatedFooter = resizeFooter delta (E.afValue original)
+    encryptedFooter <- E.encryptGcmModuleFramed key (aad E.ModuleFooter) (encodeCompact updatedFooter) >>= right
+    let changed = F.parquetEncryptedMagic <> encryptedHeader <> wireBody <> F.writeRawFooter F.parquetEncryptedMagic (BS.take cryptoEnd (F.ftBytes trailer) <> encryptedFooter)
+    file <- right (R.loadParquetFileWithDecryption config changed)
+    if incorrect
+      then check "authenticated header with incorrect ciphertext CRC is rejected" (isLeft (R.columnChunkSlice file 0 0))
+      else do
+        chunk <- right (R.columnChunkSlice file 0 0)
+        values <- right (R.readInt32Levels Uncompressed 0 0 chunk)
+        check "CRC is checked on ciphertext before plaintext decoding" (R.clValues values == VP.fromList [1, 2, 3, 4])
+  where
+    resizeFooter delta = descend
+      where
+        descend (TV.Struct fields) = TV.Struct (V.map update fields)
+        descend value = value
+        update (FileMetadata_RowGroups values) = FileMetadata_RowGroups (V.map resizeGroup values)
+        update field = field
+        resizeGroup (TV.Struct fields) = TV.Struct (V.map resizeGroupField fields)
+        resizeGroup value = value
+        resizeGroupField (RowGroup_Columns values) = RowGroup_Columns (V.map resizeChunk values)
+        resizeGroupField (RowGroup_TotalByteSize size) = RowGroup_TotalByteSize (size + delta)
+        resizeGroupField field = field
+        resizeChunk (TV.Struct fields) = TV.Struct (V.map resizeChunkField fields)
+        resizeChunk value = value
+        resizeChunkField (ColumnChunk_MetaData fields) = ColumnChunk_MetaData (V.map resizeColumn fields)
+        resizeChunkField field = field
+        resizeColumn (ColumnMetaData_TotalCompressedSize size) = ColumnMetaData_TotalCompressedSize (size + delta)
+        resizeColumn (ColumnMetaData_TotalUncompressedSize size) = ColumnMetaData_TotalUncompressedSize (size + delta)
+        resizeColumn field = field
+
+
+-- Small, independent bitwise reference for regression fixtures, rather than
+-- using the zlib implementation under test to produce expected checksums.
+crcReference :: BS.ByteString -> Word32
+crcReference = complement . BS.foldl' byte 0xffffffff
+  where
+    byte crc value = steps (8 :: Int) (crc `xor` fromIntegral value)
+    steps 0 crc = crc
+    steps n crc = steps (n - 1) ((crc `shiftR` 1) `xor` if crc .&. 1 /= 0 then 0xedb88320 else 0)
+
+
+schema :: V.Vector SchemaElement
+schema =
+  V.fromList
+    [ SchemaElement "schema" Nothing Nothing (Just 2) Nothing Nothing Nothing Nothing
+    , SchemaElement "x" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+    , SchemaElement "public" (Just Required) (Just PTByteArray) Nothing (Just CTUtf8) (Just LTString) Nothing Nothing
+    ]
+
+
+publicSchema :: AT.Schema -> AT.Schema
+publicSchema schema = schema {AT.arrowFields = V.filter ((== "public") . AT.fieldName) (AT.arrowFields schema)}
+
+
+columnKeyMetadata :: W.FooterEncryption -> BS.ByteString -> IO BS.ByteString
+columnKeyMetadata footer bytes = do
+  authenticated <- right (E.authenticateFooter key (Just prefix) Nothing bytes)
+  value <- updateFile (E.afValue authenticated)
+  trailer <- right (F.readFooterTrailer bytes)
+  (_, cryptoEnd) <- right (decodeCompactFrom (F.ftBytes trailer) 0)
+  encrypted <- E.encryptGcmModuleFramed key (aad E.ModuleFooter 0) (encodeCompact value) >>= right
+  let before = BS.take (BS.length bytes - 8 - BS.length (F.ftBytes trailer)) bytes
+  pure (before <> F.writeRawFooter F.parquetEncryptedMagic (BS.take cryptoEnd (F.ftBytes trailer) <> encrypted))
+  where
+    key = W.feKey footer
+    prefix = W.feAadPrefix footer
+    aad :: E.ModuleType -> Int -> BS.ByteString
+    aad kind group = E.buildAad prefix (E.buildAadSuffix (W.feFileId footer) kind (fromIntegral group) 0 0)
+    updateFile (TV.Struct fields) =
+      TV.Struct
+        <$> V.mapM
+          ( \case
+              FileMetadata_RowGroups groups -> FileMetadata_RowGroups <$> V.imapM updateGroup groups
+              field -> pure field
+          )
+          fields
+    updateFile _ = fail "expected file struct"
+    updateGroup group (TV.Struct fields) =
+      TV.Struct
+        <$> V.mapM
+          ( \case
+              RowGroup_Columns columns -> RowGroup_Columns <$> V.imapM (updateColumn group) columns
+              field -> pure field
+          )
+          fields
+    updateGroup _ _ = fail "expected group struct"
+    updateColumn group 0 (TV.Struct fields) = do
+      plain <- maybe (fail "missing column metadata") pure (V.find (\case ColumnChunk_MetaData _ -> True; _ -> False) fields)
+      value <- case plain of ColumnChunk_MetaData values -> pure (TV.Struct values); _ -> fail "missing column struct"
+      ciphertext <- E.encryptGcmModuleFramed key (aad E.ModuleColumnMetaData group) (encodeCompact value) >>= right
+      let removed = [fst (ColumnChunk_MetaData V.empty), fst (ColumnChunk_CryptoMetadata V.empty), fst (ColumnChunk_EncryptedColumnMetadata BS.empty)]
+          retained = V.filter (\field -> fst field `notElem` removed) fields
+          description = V.singleton (ColumnCryptoMetaData_EncryptionWithColumnKey (V.fromList [EncryptionWithColumnKey_PathInSchema (V.singleton (TV.String "x")), EncryptionWithColumnKey_KeyMetadata "kf"]))
+      pure (TV.Struct (retained <> V.fromList [ColumnChunk_CryptoMetadata description, ColumnChunk_EncryptedColumnMetadata ciphertext]))
+    updateColumn _ _ value = pure value
+
+
+flipByte :: Int -> BS.ByteString -> BS.ByteString
+flipByte offset bytes = BS.take offset bytes <> BS.singleton (BS.index bytes offset `xor` 1) <> BS.drop (offset + 1) bytes
+
+
+check :: String -> Bool -> IO ()
+check label success = unless success (fail ("EncryptedReadRegression: " ++ label))
+
+
+right :: HasCallStack => Either String a -> IO a
+right = either (\message -> fail (message ++ "\n" ++ prettyCallStack callStack)) pure
+
+
+rightArrow :: Show e => Either e a -> IO a
+rightArrow = either (fail . show) pure
diff --git a/test/EncryptedWriterRegression.hs b/test/EncryptedWriterRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/EncryptedWriterRegression.hs
@@ -0,0 +1,179 @@
+{-# LANGUAGE PatternSynonyms #-}
+
+module EncryptedWriterRegression (tests) where
+
+import Arrow.Types qualified as AT
+import Control.Monad (forM_, unless)
+import Data.Bits (xor)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Map.Strict qualified as Map
+import Data.Text (Text)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as VP
+import Parquet.Arrow qualified as A
+import Parquet.BloomFilter qualified as B
+import Parquet.Compress qualified as C
+import Parquet.Decryption qualified as D
+import Parquet.Encryption qualified as E
+import Parquet.HighLevel qualified as H
+import Parquet.Nested qualified as N
+import Parquet.PageIndex qualified as I
+import Parquet.Read qualified as R
+import Parquet.Types
+import Parquet.Write qualified as W
+import System.Directory (createDirectoryIfMissing)
+import System.Environment (lookupEnv)
+import System.FilePath ((</>))
+
+
+tests :: IO ()
+tests = do
+  output <- lookupEnv "WIREFORM_PARQUET_PRIMITIVE_OUTPUT"
+  forM_ output $ \root -> createDirectoryIfMissing True (root </> "encryption-writer")
+  forM_ [Uncompressed, GZip, Snappy, ZSTD, LZ4Raw, LZO, Brotli] $ \codec -> case C.validateCompression codec of
+    Left _ -> pure ()
+    Right () -> forM_ [W.PageV1, W.PageV2] $ \version -> do
+      let base = H.defaultWriteOptions {H.writeCompression = codec, H.writePageVersion = version, H.writeBloomFilters = ["secret", "record", "mapping"]}
+      nestedPlain <- right (H.encodeParquetNestedWith base nestedSchema nestedRows)
+      let mixedBase = base {H.writeBloomFilters = ["secret"]}
+          mixedPlain = H.encodeParquetMixed mixedBase mixedSchema mixedRows
+      save output ("plain-nested-" ++ show codec ++ "-" ++ show version) nestedPlain
+      save output ("plain-mixed-" ++ show codec ++ "-" ++ show version) mixedPlain
+      forM_ [16, 24, 32] $ \width -> forM_ [E.AesGcmV1, E.AesGcmCtrV1] $ \algorithm ->
+        forM_ [H.EncryptedFooter, H.SignedPlaintextFooter] $ \mode -> forM_ [False, True] $ \split -> do
+          footer <- W.newFooterEncryption (BS.replicate width 0x42) "writer-regression" "kf"
+          let encryption ordinal =
+                W.ColumnEncryption
+                  algorithm
+                  (BS.replicate width (if split then if even ordinal then 0x43 else 0x44 else 0x42))
+                  (W.feFileId footer)
+                  (W.feAadPrefix footer)
+                  (if even ordinal then "kc1" else "kc2")
+                  ordinal
+              configs count = V.generate count (\col -> if col == 0 then Nothing else Just (encryption col))
+              nestedOptions = base {H.writeFooterMode = mode, H.writeFooterEncryption = Just footer, H.writeColumnEncryption = configs 6}
+              mixedOptions = mixedBase {H.writeFooterMode = mode, H.writeFooterEncryption = Just footer, H.writeColumnEncryption = configs 3}
+              suffix = "-" ++ show width ++ "-" ++ show algorithm ++ "-" ++ show mode ++ "-" ++ (if split then "split" else "footer") ++ "-" ++ show codec ++ "-" ++ show version
+              config = D.defaultDecryptionConfig {D.dcKeyMetadataKeys = Map.fromList [("kf", BS.replicate width 0x42), ("kc1", BS.replicate width 0x43), ("kc2", BS.replicate width 0x44)], D.dcAadPrefix = Just "writer-regression"}
+          nested <- H.encodeParquetNestedIO nestedOptions nestedSchema nestedRows >>= right
+          mixed <- H.encodeParquetMixedIO mixedOptions mixedSchema mixedRows >>= right
+          verify config nestedPlain nested
+          verify config mixedPlain mixed
+          save output ("feature-nested" ++ suffix) nested
+          save output ("feature-mixed" ++ suffix) mixed
+          forM_ [nested, mixed] $ \bytes -> do
+            let damaged = BS.take (BS.length bytes - 9) bytes <> BS.singleton (BS.index bytes (BS.length bytes - 9) `xor` 1) <> BS.drop (BS.length bytes - 8) bytes
+            check "altered footer/signature is rejected" (isLeft (R.loadParquetFileWithDecryption config damaged))
+            file <- right (R.loadParquetFileWithDecryption config bytes)
+            let withoutSecrets = config {D.dcKeyMetadataKeys = Map.singleton "kf" (BS.replicate width 0x42)}
+            projection <- right (R.loadParquetFileWithDecryption withoutSecrets bytes)
+            schema <- right (A.parquetFileArrowSchemaChecked projection)
+            let public = schema {AT.arrowFields = V.filter ((== "public") . AT.fieldName) (AT.arrowFields schema)}
+            _ <- either (fail . show) pure (A.parquetRowGroupToArrow public projection 0)
+            whenSplit split $ do
+              check "missing separate key fails selected secret" (isLeft (R.columnChunkSlice projection 0 1))
+              let wrong = config {D.dcKeyMetadataKeys = Map.insert "kc2" (BS.replicate width 0) (D.dcKeyMetadataKeys config)}
+              bad <- right (R.loadParquetFileWithDecryption wrong bytes)
+              check "wrong separate key fails authentication" (isLeft (R.columnChunkSlice bad 0 1))
+            check "requested encryption is present" (R.isColumnEncrypted file 0 1 && not (R.isColumnEncrypted file 0 0))
+  invalidRequests
+  putStrLn "Encrypted writer feature regressions passed: nested/nullable, separate keys and signed plaintext footers, all enabled codecs and key widths."
+
+
+verify :: D.DecryptionConfig -> BS.ByteString -> BS.ByteString -> IO ()
+verify config plaintext bytes = do
+  expected <- right (R.loadParquetFile plaintext)
+  file <- right (R.loadParquetFileWithDecryption config bytes)
+  expectedSchema <- right (A.parquetFileArrowSchemaChecked expected)
+  actualSchema <- right (A.parquetFileArrowSchemaChecked file)
+  check "schema survives encryption" (actualSchema == expectedSchema)
+  forM_ [0 .. V.length (fmRowGroups (R.pfFooter expected)) - 1] $ \rg -> do
+    decoded <- either (fail . show) pure (A.parquetRowGroupToArrow actualSchema file rg)
+    original <- either (fail . show) pure (A.parquetRowGroupToArrow expectedSchema expected rg)
+    V.imapM_
+      ( \col field -> do
+          actual <- right (A.columnArrayToNestedRows field (decoded V.! col))
+          wanted <- right (A.columnArrayToNestedRows field (original V.! col))
+          check "nullable/nested values match plaintext control" (actual == wanted)
+      )
+      (AT.arrowFields actualSchema)
+    V.imapM_
+      ( \col _ -> do
+          actualOffsets <- right (I.readOffsetIndex file rg col)
+          wantedOffsets <- right (I.readOffsetIndex expected rg col)
+          check "offset index remains present" (fmap (V.length . oiPageLocations) actualOffsets == fmap (V.length . oiPageLocations) wantedOffsets)
+          actualIndex <- right (I.readColumnIndex file rg col)
+          wantedIndex <- right (I.readColumnIndex expected rg col)
+          check "column index retains every bound/count" (actualIndex == wantedIndex)
+          actualBloom <- right (B.readBloomFilter file rg col)
+          wantedBloom <- right (B.readBloomFilter expected rg col)
+          check "bloom bitsets retain every inserted value" (fmap B.encodeBloomFilter actualBloom == fmap B.encodeBloomFilter wantedBloom)
+      )
+      (rgColumns (fmRowGroups (R.pfFooter expected) V.! rg))
+
+
+nestedSchema :: V.Vector (Text, N.NestedSchema)
+nestedSchema =
+  V.fromList
+    [ ("public", N.NSRequired (N.NSPrimitive N.LtInt32))
+    , ("secret", N.NSOptional (N.NSList (N.NSOptional (N.NSPrimitive N.LtInt32))))
+    , ("record", N.NSOptional (N.NSStruct (V.fromList [("a", N.NSOptional (N.NSPrimitive N.LtString)), ("b", N.NSRequired (N.NSPrimitive N.LtInt64))])))
+    , ("mapping", N.NSOptional (N.NSMap (N.NSRequired (N.NSPrimitive N.LtString)) (N.NSOptional (N.NSPrimitive N.LtInt64))))
+    ]
+
+
+nestedRows :: V.Vector (V.Vector N.NestedRow)
+nestedRows =
+  V.fromList
+    [ V.fromList (map (N.NRLeaf . N.LvInt32) [1, 2, 3])
+    , V.fromList [N.NRNull, N.NRList V.empty, N.NRList (V.fromList [N.NRNull, N.NRLeaf (N.LvInt32 (-7)), N.NRLeaf (N.LvInt32 42)])]
+    , V.fromList [N.NRNull, N.NRStruct (V.fromList [N.NRNull, N.NRLeaf (N.LvInt64 11)]), N.NRStruct (V.fromList [N.NRLeaf (N.LvString "hi"), N.NRLeaf (N.LvInt64 12)])]
+    , V.fromList [N.NRNull, N.NRMapEntries V.empty, N.NRMapEntries (V.fromList [(N.NRLeaf (N.LvString "k"), N.NRNull), (N.NRLeaf (N.LvString "z"), N.NRLeaf (N.LvInt64 99))])]
+    ]
+
+
+mixedSchema :: V.Vector SchemaElement
+mixedSchema =
+  V.fromList
+    [ SchemaElement "schema" Nothing Nothing (Just 3) Nothing Nothing Nothing Nothing
+    , SchemaElement "public" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+    , SchemaElement "secret" (Just Optional) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+    , SchemaElement "text" (Just Optional) (Just PTByteArray) Nothing Nothing (Just LTString) Nothing Nothing
+    ]
+
+
+mixedRows :: [V.Vector W.ParquetColumn]
+mixedRows = map group [0, 10]
+  where
+    group base = V.fromList [W.PCRequired (W.ColInt32 (VP.fromList [base + 1, base + 2, base + 3])), W.PCOptional (W.OptInt32 (V.fromList [Nothing, Just (-7), Just 42])), W.PCOptional (W.OptByteArray (V.fromList [Just "", Nothing, Just "private"]))]
+
+
+invalidRequests :: IO ()
+invalidRequests = do
+  let signed = H.defaultWriteOptions {H.writeFooterMode = H.SignedPlaintextFooter, H.writeCompression = Uncompressed}
+  absent <- H.encodeParquetNestedIO signed nestedSchema nestedRows
+  check "signed plaintext mode requires a signing key" (isLeft absent)
+  footer <- W.newFooterEncryption (BS.replicate 16 0x42) "" "kf"
+  let wrong = signed {H.writeFooterEncryption = Just footer {W.feKey = "bad"}}
+  bad <- H.encodeParquetMixedIO wrong mixedSchema []
+  check "empty mixed writer validates footer key" (isLeft bad)
+  invalid <- H.encodeParquetNestedIO signed {H.writeFooterEncryption = Just footer, H.writeColumnEncryption = V.singleton Nothing} nestedSchema nestedRows
+  check "nested writer rejects truncated encryption vectors" (isLeft invalid)
+
+
+save :: Maybe FilePath -> String -> BS.ByteString -> IO ()
+save output name bytes = forM_ output $ \root -> BS.writeFile (root </> "encryption-writer" </> (name ++ ".parquet")) bytes
+
+
+whenSplit :: Bool -> IO () -> IO ()
+whenSplit True action = action
+whenSplit False _ = pure ()
+
+
+check :: String -> Bool -> IO ()
+check message valid = unless valid (fail ("EncryptedWriterRegression: " ++ message))
+
+
+right :: Either String a -> IO a
+right = either fail pure
diff --git a/test/EncryptionFooterRegression.hs b/test/EncryptionFooterRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/EncryptionFooterRegression.hs
@@ -0,0 +1,169 @@
+{-# LANGUAGE PatternSynonyms #-}
+
+module EncryptionFooterRegression (tests) where
+
+import Control.Monad (forM_, unless)
+import Data.Bits (xor)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Int (Int16)
+import Data.Vector qualified as V
+import Parquet.Encryption qualified as E
+import Parquet.Footer qualified as F
+import Parquet.Read qualified as R
+import Parquet.Thrift.Schema
+import Parquet.Types
+import Thrift.Encode (encodeCompact)
+import Thrift.Value qualified as TV
+
+
+tests :: IO ()
+tests = do
+  forM_ [16, 24, 32] $ \width ->
+    forM_ [E.AesGcmV1, E.AesGcmCtrV1] $ \algorithm ->
+      forM_ [False, True] $ \omitted ->
+        forM_ [False, True] $ \signed -> validFooter width algorithm omitted signed
+  malformedMetadata
+  ordinary <- right (R.loadParquetFileEncrypted (R.FooterDecryption "unused" "unused" "unused") ordinaryFile)
+  check "ordinary unsigned files remain accepted" (R.pfFooter ordinary == metadata)
+  check "overlapping header/footer is rejected" (isLeft (E.authenticateFooter key Nothing Nothing (F.writeFooter metadata)))
+  putStrLn "OK: encrypted and signed footer authentication (24 configurations plus metadata and tampering regressions)"
+
+
+metadata :: FileMetadata
+metadata = FileMetadata 1 (V.singleton (SchemaElement "schema" Nothing Nothing (Just 0) Nothing Nothing Nothing Nothing)) 0 V.empty Nothing Nothing Nothing
+
+
+ordinaryFile :: BS.ByteString
+ordinaryFile = F.parquetMagic <> F.writeFooter metadata
+
+
+key, fileId, prefix, keyMetadata, nonce :: BS.ByteString
+key = BS.replicate 16 0x42
+fileId = "non-eight-byte-file-id"
+prefix = "expected-file-version"
+keyMetadata = BS.pack [0xff, 0x80, 0, 0x61]
+nonce = BS.replicate 12 0x11
+
+
+description :: E.EncryptionAlgorithm -> Bool -> V.Vector (DataField)
+description algorithm omitted =
+  V.singleton $
+    variant $
+      V.fromList $
+        [AesGcmV1_AadFileUnique fileId]
+          ++ if omitted then [AesGcmV1_SupplyAadPrefix True] else [AesGcmV1_AadPrefix prefix]
+  where
+    variant = case algorithm of
+      E.AesGcmV1 -> EncryptionAlgorithm_AesGcmV1
+      E.AesGcmCtrV1 -> EncryptionAlgorithm_AesGcmCtrV1
+
+
+type DataField = (Int16, TV.Value)
+
+
+cryptoValue :: V.Vector DataField -> TV.Value
+cryptoValue algorithm = TV.Struct (V.fromList [FileCryptoMetaData_EncryptionAlgorithm algorithm, FileCryptoMetaData_KeyMetadata keyMetadata])
+
+
+aad :: BS.ByteString
+aad = E.buildAad prefix (E.buildAadSuffix fileId E.ModuleFooter 0 0 0)
+
+
+encryptedFile :: BS.ByteString -> TV.Value -> BS.ByteString -> Either String BS.ByteString
+encryptedFile aes crypto plaintext = do
+  ciphertext <- E.encryptGcmModuleFramedWithNonce aes nonce aad plaintext
+  pure (F.parquetEncryptedMagic <> F.writeRawFooter F.parquetEncryptedMagic (encodeCompact crypto <> ciphertext))
+
+
+signedFile :: BS.ByteString -> TV.Value -> Either String BS.ByteString
+signedFile aes footer = do
+  let plaintext = encodeCompact footer
+  ciphertext <- E.encryptGcmModuleWithNonce aes nonce aad plaintext
+  let signature = BS.take 12 ciphertext <> BS.takeEnd 16 ciphertext
+  pure (F.parquetMagic <> F.writeRawFooter F.parquetMagic (plaintext <> signature))
+
+
+validFooter :: Int -> E.EncryptionAlgorithm -> Bool -> Bool -> IO ()
+validFooter width algorithm omitted signed = do
+  let aes = BS.replicate width 0x42
+      fields = case F.fileMetadataToThrift metadata of
+        TV.Struct raw -> raw
+        _ -> error "expected footer struct"
+      -- Reverse the fields so verification must use the original serialized
+      -- footer, rather than canonicalizing its order before calculating a tag.
+      plaintext = TV.Struct (V.reverse (fields <> V.fromList [FileMetadata_EncryptionAlgorithm (description algorithm omitted), FileMetadata_FooterSigningKeyMetadata keyMetadata]))
+      expected = R.FooterDecryption aes fileId prefix
+  bytes <-
+    right $
+      if signed
+        then signedFile aes plaintext
+        else encryptedFile aes (cryptoValue (description algorithm omitted)) (encodeCompact (F.fileMetadataToThrift metadata))
+  info <- right (E.readFooterCryptoMetadata bytes) >>= maybe (fail "missing crypto metadata") pure
+  check "opaque key metadata is preserved" (E.fcmKeyMetadata info == Just keyMetadata)
+  check "crypto identity is preserved" (E.fcmFileId info == fileId && E.fcmAlgorithm info == algorithm && E.fcmSupplyAadPrefix info == omitted)
+  loaded <- right (R.loadParquetFileEncrypted expected bytes)
+  check "authenticated footer recovers metadata" (R.pfFooter loaded == metadata)
+  _ <- right (E.authenticateFooter aes (Just prefix) Nothing bytes)
+  if omitted
+    then check "omitted prefix is required" (isLeft (E.authenticateFooter aes Nothing Nothing bytes))
+    else do
+      _ <- right (E.authenticateFooter aes Nothing Nothing bytes)
+      pure ()
+  check "expected prefix is checked" (isLeft (E.authenticateFooter aes (Just "other") Nothing bytes))
+  check "expected file identifier is checked" (isLeft (R.loadParquetFileEncrypted expected {R.fdFileId = "other"} bytes))
+  check "wrong footer key fails authentication" (isLeft (R.loadParquetFileEncrypted expected {R.fdKey = BS.replicate width 0x43} bytes))
+  forM_ [BS.length bytes - 9, BS.length bytes - 20, BS.length bytes - 36] $ \offset ->
+    check "altered tag/nonce/ciphertext is rejected" (isLeft (R.loadParquetFileEncrypted expected (flipByte offset bytes)))
+  check "leading and trailing magic must match" (isLeft (R.loadParquetFileEncrypted expected (BS.replicate 4 0 <> BS.drop 4 bytes)))
+  if signed
+    then do
+      trailer <- right (F.readFooterTrailer bytes)
+      let raw = F.ftBytes trailer
+          incomplete = F.parquetMagic <> F.writeRawFooter F.parquetMagic (BS.init raw)
+          changed = F.parquetMagic <> F.writeRawFooter F.parquetMagic (flipByte 2 raw)
+      check "truncated signature is rejected" (isLeft (R.loadParquetFileEncrypted expected incomplete))
+      check "altered signed metadata is rejected" (isLeft (R.loadParquetFileEncrypted expected changed))
+    else pure ()
+
+
+malformedMetadata :: IO ()
+malformedMetadata = do
+  let normal = V.fromList [AesGcmV1_AadFileUnique fileId, AesGcmV1_AadPrefix prefix]
+      variant = EncryptionAlgorithm_AesGcmV1
+      invalid =
+        [ V.empty
+        , V.fromList [variant normal, EncryptionAlgorithm_AesGcmCtrV1 normal]
+        , V.singleton (99, TV.Struct normal)
+        , V.singleton (variant (V.singleton (AesGcmV1_AadPrefix prefix)))
+        , V.singleton (variant (V.snoc normal (AesGcmV1_AadFileUnique fileId)))
+        , V.singleton (variant (V.snoc normal (AesGcmV1_SupplyAadPrefix True)))
+        , V.singleton (variant (V.snoc normal (fst (AesGcmV1_SupplyAadPrefix False), TV.I32 1)))
+        , V.singleton (variant (V.fromList [AesGcmV1_AadFileUnique fileId, (fst (AesGcmV1_AadPrefix prefix), TV.I32 0)]))
+        ]
+      plaintext = encodeCompact (F.fileMetadataToThrift metadata)
+      expected = R.FooterDecryption key fileId prefix
+  forM_ invalid $ \algorithm -> do
+    bytes <- right (encryptedFile key (cryptoValue algorithm) plaintext)
+    check "invalid crypto metadata is rejected even with a valid GCM footer" (isLeft (R.loadParquetFileEncrypted expected bytes))
+  let duplicate = TV.Struct (V.fromList [FileCryptoMetaData_EncryptionAlgorithm (description E.AesGcmV1 False), FileCryptoMetaData_KeyMetadata keyMetadata, FileCryptoMetaData_KeyMetadata keyMetadata])
+  duplicateFile <- right (encryptedFile key duplicate plaintext)
+  check "duplicate key routing fields are rejected" (isLeft (R.loadParquetFileEncrypted expected duplicateFile))
+  trailing <- right (encryptedFile key (cryptoValue (description E.AesGcmV1 False)) (plaintext <> "junk"))
+  check "authenticated trailing footer bytes are rejected" (isLeft (R.loadParquetFileEncrypted expected trailing))
+  padded <- right (encryptedFile key (cryptoValue (description E.AesGcmV1 False)) (plaintext <> BS.replicate 1600 0))
+  paddedFile <- right (R.loadParquetFileEncrypted expected padded)
+  check "authenticated parquet-mr zero padding is accepted" (R.pfFooter paddedFile == metadata)
+  check "padding is authenticated before it is ignored" (isLeft (R.loadParquetFileEncrypted expected (flipByte (BS.length padded - 25) padded)))
+
+
+flipByte :: Int -> BS.ByteString -> BS.ByteString
+flipByte index bytes = BS.take index bytes <> BS.singleton (BS.index bytes index `xor` 1) <> BS.drop (index + 1) bytes
+
+
+right :: Either String a -> IO a
+right = either fail pure
+
+
+check :: String -> Bool -> IO ()
+check label valid = unless valid (fail ("EncryptionFooterRegression: " ++ label))
diff --git a/test/FileArrowRegression.hs b/test/FileArrowRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/FileArrowRegression.hs
@@ -0,0 +1,98 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module FileArrowRegression (tests) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft, isRight)
+import Data.Text (Text)
+import Data.Vector qualified as V
+import Parquet.Arrow qualified as Arrow
+import Parquet.File qualified as F
+import Parquet.Nested qualified as N
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+
+
+load :: Either String a -> IO a
+load = either fail pure
+
+
+child :: Text -> A.ArrowType -> Text -> A.Field
+child name ty ident = A.Field name True ty V.empty Nothing (V.singleton ("PARQUET:field_id", ident))
+
+
+fileField :: V.Vector A.Field -> A.Field
+fileField children =
+  A.Field
+    "f"
+    True
+    A.AStruct
+    children
+    Nothing
+    (V.fromList [("ARROW:extension:name", "arrow.parquet.file"), ("ARROW:extension:metadata", ""), ("PARQUET:field_id", "-7")])
+
+
+tests :: IO ()
+tests = do
+  let check name condition = unless condition (fail ("Arrow FILE regression: " ++ name))
+      uri = child "uri" A.AUtf8 "-2147483648"
+      inline = child "inline" A.ABinary "2147483647"
+      field = fileField (V.fromList [uri, inline])
+  check "known extension accepted" (isRight (Arrow.arrowFieldToNestedSchema field))
+  check "absent parameters accepted" (isRight (Arrow.arrowFieldToNestedSchema field {A.fieldMetadata = V.filter ((/= "ARROW:extension:metadata") . fst) (A.fieldMetadata field)}))
+  forM_ ["{}", "v2", " "] $ \parameters ->
+    check "unsupported extension metadata cannot disappear silently" (isLeft (Arrow.arrowFieldToNestedSchema field {A.fieldMetadata = V.map (\(key, value) -> (key, if key == "ARROW:extension:metadata" then parameters else value)) (A.fieldMetadata field)}))
+  forM_ ["ARROW:extension:name", "ARROW:extension:metadata", "PARQUET:field_id"] $ \key -> do
+    let pair = V.find ((== key) . fst) (A.fieldMetadata field)
+    check "duplicate reserved metadata rejected" (isLeft (Arrow.arrowFieldToNestedSchema field {A.fieldMetadata = A.fieldMetadata field V.++ maybe V.empty V.singleton pair}))
+  forM_ [uri {A.fieldNullable = False}, uri {A.fieldName = "URI"}, uri {A.fieldType = A.ABinary}, inline {A.fieldType = A.AUtf8}, child "size" (A.AInt 64 False) "0", child "offset" (A.AInt 32 True) "0"] $ \bad ->
+    check "extension validates names/nullability/types" (isLeft (Arrow.arrowFieldToNestedSchema (fileField (V.singleton bad))))
+  forM_ ["2147483648", "-2147483649", "1junk", "", " 1"] $ \ident ->
+    check "field IDs are bounded strict integers" (isLeft (Arrow.arrowFieldToNestedSchema (fileField (V.singleton (uri {A.fieldMetadata = V.singleton ("PARQUET:field_id", ident)})))))
+  check "duplicate names rejected" (isLeft (Arrow.arrowFieldToNestedSchema (fileField (V.fromList [uri, uri]))))
+  check "FILE extension cannot use primitive storage" (isLeft (Arrow.arrowFieldToNestedSchema field {A.fieldType = A.AUtf8, A.fieldChildren = V.empty}))
+  -- Each representation contains both short/inline and long/out-of-line view
+  -- strings. Parent nulls must mask arbitrary child storage in every case.
+  let texts = V.fromList [Just "../images/a%20b-long-relative.png", Just "masked", Nothing, Just ""]
+      bytes = V.fromList [Nothing, Just "masked", Just "", Just (BS.replicate 80 255)]
+      expected =
+        V.fromList
+          [ Just F.emptyFileReference {F.fileUri = Just "../images/a%20b-long-relative.png"}
+          , Nothing
+          , Just F.emptyFileReference {F.fileInline = Just ""}
+          , Just F.emptyFileReference {F.fileUri = Just "", F.fileInline = Just (BS.replicate 80 255)}
+          ]
+      representations =
+        [ (A.AUtf8, A.ABinary, C.fromMaybeTexts texts, C.fromMaybeByteStrings bytes)
+        , (A.ALargeUtf8, A.ALargeBinary, C.fromMaybeLargeTexts texts, C.fromMaybeLargeByteStrings bytes)
+        , (A.AUtf8View, A.ABinaryView, C.fromMaybeUtf8View texts, C.fromMaybeBinaryView bytes)
+        ]
+  forM_ representations $ \(textType, binaryType, textColumn, binaryColumn) -> do
+    let input = fileField (V.fromList [uri {A.fieldType = textType}, inline {A.fieldType = binaryType}])
+    column <- load (C.mkStruct 4 (C.validityFromBools (V.fromList [True, False, True, True])) (V.fromList [("uri", textColumn), ("inline", binaryColumn)]))
+    nested <- load (Arrow.arrowFieldToNestedSchema input)
+    rows <- load (Arrow.columnArrayToNestedRows input column)
+    check "FILE rows use typed references" (rows == V.map (maybe N.NRNull N.NRFile) expected)
+    encoded <- load (N.buildNestedFile (V.singleton ("f", nested)) (V.singleton rows))
+    file <- load (Read.loadParquetFile encoded)
+    let schema = P.fmSchema (Read.pfFooter file)
+    check "FILE and IDs written to native footer" (P.seLogicalType (schema V.! 1) == Just P.LTFile && V.map P.seFieldId (V.drop 1 schema) == V.fromList [Just (-7), Just minBound, Just maxBound])
+    output <- load (Arrow.parquetFileArrowSchemaChecked file)
+    let outputField = V.head (A.arrowFields output)
+    check "parent metadata has experimental FILE name and empty parameters" (A.fieldMetadata outputField == A.fieldMetadata field)
+    check "child IDs survive schema inference" (V.map A.fieldMetadata (A.fieldChildren outputField) == V.map A.fieldMetadata (A.fieldChildren field))
+    columns <- either (fail . show) pure (Arrow.parquetRowGroupToArrow output file 0)
+    nativeSchema <- load (F.parseFileSchema (schema V.! 1) (V.drop 2 schema))
+    reader <- load (F.compileFileReader nativeSchema (V.head columns))
+    actual <- load (V.generateM 4 (F.fileReferenceAt reader))
+    check "all storage representations retain semantic values" (actual == expected)
+    restored <- load (Arrow.arrowFieldToNestedSchema outputField)
+    check "FILE identity and parent/child IDs survive Arrow roundtrip" (restored == nested)
+  let plain = field {A.fieldMetadata = V.empty}
+  case Arrow.arrowFieldToNestedSchema plain of
+    Right (N.NSOptional N.NSStruct {}) -> pure ()
+    _ -> fail "Arrow FILE regression: plain struct must remain unannotated"
+  putStrLn "Arrow FILE extension, IDs, strict metadata and standard/large/view storage regressions passed."
diff --git a/test/FileRegression.hs b/test/FileRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/FileRegression.hs
@@ -0,0 +1,164 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module FileRegression (tests) where
+
+import Arrow.Column qualified as A
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft, isRight)
+import Data.Maybe (isJust)
+import Data.Text qualified as T
+import Data.Vector qualified as V
+import Data.Vector.Storable qualified as VS
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Arrow qualified as Arrow
+import Parquet.File
+import Parquet.Nested qualified as N
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+
+
+load :: Either String a -> IO a
+load = either fail pure
+
+
+fullSchema :: Either String FileSchema
+fullSchema = mkFileSchema (V.fromList (map (\field -> FileFieldSpec field (Just (fromIntegral (fromEnum field + 10)))) [minBound .. maxBound]))
+
+
+readReferences :: BS.ByteString -> Either String (V.Vector (Maybe FileReference))
+readReferences bytes = do
+  file <- Read.loadParquetFile bytes
+  let elements = P.fmSchema (Read.pfFooter file)
+  schema <- parseFileSchema (elements V.! 1) (V.drop 2 elements)
+  arrow <- Arrow.parquetFileArrowSchemaChecked file
+  columns <- either (Left . show) Right (Arrow.parquetRowGroupToArrow arrow file 0)
+  reader <- compileFileReader schema (V.head columns)
+  V.generateM (A.columnLength (V.head columns)) (fileReferenceAt reader)
+
+
+tests :: IO ()
+tests = do
+  let check name condition = unless condition (fail ("FILE regression: " ++ name))
+      inline = emptyFileReference {fileInline = Just ""}
+      external = emptyFileReference {fileUri = Just "../images/a%20b.png?raw=1#part"}
+      both = external {fileOffset = Just 0, fileSize = Just 0, fileInline = Just "whole inline payload"}
+      maximumRange = external {fileOffset = Just maxBound, fileSize = Just maxBound}
+  schema <- load fullSchema
+  forM_ [inline, external, both, maximumRange, inline {fileUri = Just "", fileContentType = Just "", fileChecksum = Just ""}] $ \reference ->
+    check "valid reference" (isRight (resolveFileReference reference))
+  forM_ [emptyFileReference, external {fileUri = Just ""}, external {fileOffset = Just 0}, external {fileOffset = Just (-1), fileSize = Just 1}, external {fileSize = Just (-1)}, inline {fileOffset = Just 0, fileSize = Just 0}, inline {fileSize = Just 1}] $ \reference ->
+    check "invalid locator is not hidden by inline bytes" (isLeft (resolveFileReference reference))
+  resolution <- load (resolveFileReference both)
+  check "inline is not sliced by offset/size" (filePreferredSource resolution == InlineBytes "whole inline payload")
+  check "external alternative retained" (fmap fileLocationSize (fileExternalLocation resolution) == Just (Just 0))
+  check "default content type" (fileMediaType resolution == "application/octet-stream")
+  maximumResolution <- load (resolveFileReference maximumRange)
+  check "exclusive end does not overflow signed 64 bits" ((fileExternalLocation maximumResolution >>= fileLocationEnd) == Just 18446744073709551614)
+  whole <- load (resolveFileReference external)
+  check "whole-file URI is preserved verbatim" (fmap fileLocationUri (fileExternalLocation whole) == fileUri external)
+  check "whole-file size remains unknown" ((fileExternalLocation whole >>= fileLocationEnd) == Nothing)
+  forM_ [("MD5", 32, FileMD5), ("CRC32", 8, FileCRC32), ("CRC32C", 8, FileCRC32C), ("SHA-256", 64, FileSHA256)] $ \(name, width, kind) -> do
+    let digest = T.replicate width "a"
+    check "recognized digest" (parseFileChecksum (Just (name <> ":" <> digest)) == Right (Just (FileDigest kind digest)))
+    forM_ [T.replicate width "A", T.drop 1 digest, digest <> "0", T.replicate width "g"] $ \bad ->
+      check "malformed known digest" (isLeft (parseFileChecksum (Just (name <> ":" <> bad))))
+  check "opaque eTag includes colons verbatim" (parseFileChecksum (Just "ETAG:\"opaque:token-2\"") == Right (Just (FileETag "\"opaque:token-2\"")))
+  check "unknown algorithm ignored" (parseFileChecksum (Just "future:any opaque data") == Right Nothing)
+  check "missing checksum separator rejected" (isLeft (parseFileChecksum (Just "SHA-256")))
+  inlineSchema <- load (mkFileSchema (V.singleton (FileFieldSpec FileInline Nothing)))
+  check "schema cannot silently drop even empty strings" (isLeft (validateFileReferenceForSchema inlineSchema inline {fileUri = Just ""}))
+  check "duplicate fields rejected" (isLeft (mkFileSchema (V.fromList [FileFieldSpec FileUri Nothing, FileFieldSpec FileUri (Just 1)])))
+  let group = P.SchemaElement "f" (Just P.Optional) Nothing (Just 6) Nothing (Just P.LTFile) Nothing Nothing
+      elements = fileSchemaElements schema
+  check "schema IDs/order retained" (parseFileSchema group elements == Right schema)
+  forM_ [P.Required, P.Repeated] $ \repetition ->
+    check "FILE children must be optional" (isLeft (parseFileSchema group (V.imap (\i f -> if i == 0 then f {P.seRepetition = Just repetition} else f) elements)))
+  forM_ ["URI", "unknown", "contentType"] $ \name ->
+    check "case-sensitive exact names" (isLeft (parseFileSchema group (elements V.// [(0, (elements V.! 0) {P.seName = name})])))
+  forM_ [P.LTString, P.LTTimestamp True P.LtNanos, P.LTInteger 64 False] $ \logical ->
+    check "offset cannot borrow unrelated INT64 semantics" (isLeft (parseFileSchema group (elements V.// [(1, (elements V.! 1) {P.seLogicalType = Just logical})])))
+  check "writer rejects locally provable inline/locator disagreement" (isLeft (validateFileReferenceForSchema schema both))
+  let matching = both {fileSize = Just (fromIntegral (BS.length "whole inline payload"))}
+      rows = V.fromList [Nothing, Just inline, Just external, Just matching, Just maximumRange, Just inline {fileUri = Just "", fileContentType = Just "", fileChecksum = Just ""}]
+      nested = N.NSOptional (N.NSFile schema)
+  bytes <- load (N.buildNestedFile (V.singleton ("f", nested)) (V.singleton (V.map (maybe N.NRNull N.NRFile) rows)))
+  actual <- load (readReferences bytes)
+  check "native file/Arrow/typed reader roundtrip" (actual == rows)
+  forM_ [emptyFileReference, external {fileOffset = Just 0}] $ \invalid ->
+    check "writer rejects invalid reference" (isLeft (N.buildNestedFile (V.singleton ("f", nested)) (V.singleton (V.singleton (N.NRFile invalid)))))
+  check "required FILE cannot be null" (isLeft (N.shred (N.NSFile schema) (V.singleton N.NRNull)))
+  -- All source-presence combinations, with zero specifically distinguished
+  -- from absence, against an independent truth table.
+  forM_ [Nothing, Just "", Just "relative"] $ \uri ->
+    forM_ [Nothing, Just 0, Just 17, Just (-1)] $ \offset ->
+      forM_ [Nothing, Just 0, Just 23, Just (-1)] $ \size ->
+        forM_ [Nothing, Just "", Just "bytes"] $ \payload -> do
+          let reference = FileReference uri offset size Nothing Nothing payload
+              hasUri = maybe False (not . T.null) uri
+              expected =
+                (hasUri || isJust payload)
+                  && maybe True (>= 0) offset
+                  && maybe True (>= 0) size
+                  && (not (isJust offset) || (hasUri && isJust size))
+                  && (not (isJust size) || hasUri)
+          check "144-case independent resolution table" (isRight (validateFileReference reference) == expected)
+  passed <- H.check $ H.withTests 100 $ H.property $ do
+    fields <- H.forAll (Gen.shuffle [minBound .. maxBound])
+    count <- H.forAll (Gen.int (Range.linear 0 6))
+    let selected = take count fields
+    subset <- H.evalEither (mkFileSchema (V.fromList (map (`FileFieldSpec` Nothing) selected)))
+    let children = fileSchemaElements subset
+    reparsed <- H.evalEither (parseFileSchema group {P.seNumChildren = Just (fromIntegral count)} children)
+    reparsed H.=== subset
+  check "field permutations/subsets preserve schema" passed
+  roundtrips <- H.check $ H.withTests 100 $ H.property $ do
+    input <- H.forAll (Gen.list (Range.linear 1 30) (Gen.maybe referenceGen))
+    encoded <- H.evalEither (N.buildNestedFile (V.singleton ("f", nested)) (V.singleton (V.fromList (map (maybe N.NRNull N.NRFile) input))))
+    decoded <- H.evalEither (readReferences encoded)
+    decoded H.=== V.fromList input
+  check "arbitrary binary payloads, signed limits and null rows roundtrip" roundtrips
+  opaque <- load (A.mkBinary Nothing (VS.fromList [0, 0, 1]) "x")
+  -- A null parent wins over the deliberately invalid source stored under it.
+  column <- load (A.mkStruct 2 (A.validityFromBools (V.fromList [False, True])) (V.singleton ("inline", opaque)))
+  reader <- load (compileFileReader inlineSchema column)
+  check "null parent masks child" (fileReferenceAt reader 0 == Right Nothing)
+  check "reader retains non-null bytes" (fileReferenceAt reader 1 == Right (Just inline {fileInline = Just "x"}))
+  check "reader index checked" (isLeft (fileReferenceAt reader (-1)) && isLeft (fileReferenceAt reader 2))
+  largeText <- load (A.mkLargeUtf8 Nothing (VS.fromList [0, 1, 2]) "ab")
+  largeBytes <- load (A.mkLargeBinary Nothing (VS.fromList [0, 0, 2]) (BS.pack [0, 255]))
+  largeSchema <- load (mkFileSchema (V.fromList [FileFieldSpec FileUri Nothing, FileFieldSpec FileInline Nothing]))
+  largeColumn <- load (A.mkStruct 2 Nothing (V.fromList [("inline", largeBytes), ("uri", largeText)]))
+  largeReader <- load (compileFileReader largeSchema largeColumn)
+  check "large columns use named cached views" (fileReferenceAt largeReader 1 == Right (Just emptyFileReference {fileUri = Just "b", fileInline = Just (BS.pack [0, 255])}))
+  duplicateColumn <- load (A.mkStruct 2 Nothing (V.fromList [("inline", opaque), ("inline", opaque)]))
+  check "duplicate column names cannot replace a missing field" (isLeft (compileFileReader largeSchema duplicateColumn))
+  textStorage <- load (A.mkStruct 2 Nothing (V.singleton ("inline", largeText)))
+  check "inline must be binary rather than STRING" (isLeft (compileFileReader inlineSchema textStorage))
+  putStrLn "FILE schemas, resolution table, checksums and native roundtrip regression cases passed."
+
+
+referenceGen :: H.Gen FileReference
+referenceGen = Gen.choice [inlineGen, externalGen]
+  where
+    uriGen = Gen.element ["s3://bucket/a%20b", "../images/a%20b.png?raw=1#part", "file.parquet", "https://example.test/file"]
+    position = Gen.int64 (Range.constant 0 maxBound)
+    externalGen = do
+      uri <- uriGen
+      offset <- Gen.maybe position
+      size <- case offset of
+        Nothing -> Gen.maybe position
+        Just _ -> Just <$> position
+      pure emptyFileReference {fileUri = Just uri, fileOffset = offset, fileSize = size}
+    inlineGen = do
+      bytes <- Gen.bytes (Range.linear 0 100)
+      uri <- Gen.choice [pure Nothing, pure (Just ""), Just <$> uriGen]
+      offset <- if maybe False (not . T.null) uri then Gen.maybe position else pure Nothing
+      size <- case offset of
+        Just _ -> pure (Just (fromIntegral (BS.length bytes)))
+        Nothing -> pure Nothing
+      content <- Gen.element [Nothing, Just "", Just "application/octet-stream"]
+      checksum <- Gen.element [Nothing, Just "", Just "future:opaque:token"]
+      pure (FileReference uri offset size content checksum (Just bytes))
diff --git a/test/FileZeroRegression.hs b/test/FileZeroRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/FileZeroRegression.hs
@@ -0,0 +1,147 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module FileZeroRegression (tests) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Int (Int64)
+import Data.Vector qualified as V
+import Parquet.Arrow qualified as Arrow
+import Parquet.File qualified as F
+import Parquet.Footer qualified as Footer
+import Parquet.Nested qualified as N
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+
+
+load :: Either String a -> IO a
+load = either fail pure
+
+
+encode :: N.NestedSchema -> V.Vector N.NestedRow -> Either String BS.ByteString
+encode schema rows = N.buildNestedFile (V.singleton ("f", schema)) (V.singleton rows)
+
+
+decode :: BS.ByteString -> Either String (V.Vector C.ColumnArray)
+decode bytes = do
+  file <- Read.loadParquetFile bytes
+  schema <- Arrow.parquetFileArrowSchemaChecked file
+  either (Left . show) Right (Arrow.parquetRowGroupToArrow schema file 0)
+
+
+tests :: IO ()
+tests = do
+  let check name value = unless value (fail ("zero-leaf FILE: " ++ name))
+      integer value = N.NRLeaf (N.LvInt32 value)
+  empty <- load (F.mkFileSchema V.empty)
+  let file = N.NSFile (F.withFileSchemaFieldId (Just 27) empty)
+      optional = N.NSOptional file
+  bytes <- load (encode optional (V.replicate 3 N.NRNull))
+  parsed <- load (Read.loadParquetFile bytes)
+  schema <- load (Arrow.parquetFileArrowSchemaChecked parsed)
+  columns <- load (decode bytes)
+  let column = V.head columns
+      field = V.head (A.arrowFields schema)
+  check "column identity/schema/IDs retained without inventing a leaf" (A.fieldName field == "f" && A.fieldType field == A.AStruct && V.null (A.fieldChildren field) && V.elem ("PARQUET:field_id", "27") (A.fieldMetadata field))
+  check "metadata-only rows become null references" (C.columnLength column == 3 && C.nullCount column == 3)
+  check "no dummy columns/pages" (V.null (P.rgColumns (V.head (P.fmRowGroups (Read.pfFooter parsed)))) && P.rgTotalByteSize (V.head (P.fmRowGroups (Read.pfFooter parsed))) == 0)
+  typed <- load (F.compileFileReader empty column)
+  actual <- load (V.generateM 3 (F.fileReferenceAt typed))
+  check "typed reader retains all null rows" (actual == V.replicate 3 Nothing)
+  restored <- load (Arrow.arrowFieldToNestedSchema field)
+  rows <- load (Arrow.columnArrayToNestedRows field column)
+  check "Arrow/native roundtrip keeps FILE ID and null rows" (restored == optional && rows == V.replicate 3 N.NRNull)
+  forM_ [file, optional, N.NSList optional, N.NSOptional (N.NSList optional), N.NSOptional (N.NSStruct (V.singleton ("empty", optional))), N.NSMap file optional] $ \shape -> do
+    zero <- load (encode shape V.empty)
+    result <- load (decode zero)
+    check "zero-row schemas retain a typed empty column" (V.length result == 1 && C.columnLength (V.head result) == 0)
+  zero <- load (encode file V.empty)
+  zeroFile <- load (Read.loadParquetFile zero)
+  let footer = Read.pfFooter zeroFile
+      legacySchema = V.imap (\index node -> if index == 1 then node {P.seRepetition = Just P.Repeated} else node) (P.fmSchema footer)
+      legacy = zeroFile {Read.pfFooter = footer {P.fmSchema = legacySchema}}
+  legacyArrow <- load (Arrow.parquetFileArrowSchemaChecked legacy)
+  let legacyField = V.head (A.arrowFields legacyArrow)
+  check "legacy repeated FILE annotates the element rather than list storage" (A.fieldType legacyField == A.AList && not (V.elem ("ARROW:extension:name", "arrow.parquet.file") (A.fieldMetadata legacyField)) && V.elem ("ARROW:extension:name", "arrow.parquet.file") (A.fieldMetadata (V.head (A.fieldChildren legacyField))))
+  _ <- load (Arrow.arrowFieldToNestedSchema legacyField)
+  check "non-null FILE cannot resolve without a source" (isLeft (encode file (V.singleton (N.NRFile F.emptyFileReference))))
+  check "required FILE cannot be null" (isLeft (encode file (V.singleton N.NRNull)))
+  forM_ [N.NSList optional, N.NSOptional (N.NSList optional)] $ \shape ->
+    check "list boundaries without physical leaves are not silently lost" (isLeft (encode shape (V.singleton (N.NRList V.empty))))
+  check "optional parent presence without physical leaves is not silently lost" (isLeft (encode (N.NSOptional (N.NSStruct (V.singleton ("empty", optional)))) (V.singleton N.NRNull)))
+  -- A required parent has known presence; a sibling leaf also carries an
+  -- optional parent's boundaries, including when only the FILE is projected.
+  let requiredParent = N.NSStruct (V.singleton ("empty", optional))
+      requiredRows = V.replicate 3 (N.NRStruct (V.singleton N.NRNull))
+  requiredBytes <- load (encode requiredParent requiredRows)
+  requiredColumn <- V.head <$> load (decode requiredBytes)
+  case requiredColumn of
+    C.ColStruct 3 Nothing children -> check "required zero-leaf parent has known presence" (C.nullCount (snd (V.head children)) == 3)
+    _ -> fail "zero-leaf FILE: required parent was not retained"
+  forM_ [False, True] $ \reverseFields -> do
+    let fields = if reverseFields then V.fromList [("anchor", N.NSPrimitive N.LtInt32), ("empty", optional)] else V.fromList [("empty", optional), ("anchor", N.NSPrimitive N.LtInt32)]
+        values n = if reverseFields then V.fromList [integer n, N.NRNull] else V.fromList [N.NRNull, integer n]
+        shape = N.NSOptional (N.NSStruct fields)
+    encoded <- load (encode shape (V.fromList [N.NRNull, N.NRStruct (values 10), N.NRStruct (values 20)]))
+    decoded <- load (Read.loadParquetFile encoded)
+    inferred <- load (Arrow.parquetFileArrowSchemaChecked decoded)
+    let parent = V.head (A.arrowFields inferred)
+        projected = parent {A.fieldChildren = V.filter ((== "empty") . A.fieldName) (A.fieldChildren parent)}
+    output <- either (fail . show) pure (Arrow.parquetRowGroupToArrow inferred {A.arrowFields = V.singleton projected} decoded 0)
+    case V.head output of
+      C.ColStruct 3 validity children -> check "projection retains parent boundaries and empty FILE on either side of anchor" (not (C.isValidAt validity 0) && C.isValidAt validity 1 && C.nullCount (snd (V.head children)) == 3)
+      _ -> fail "zero-leaf FILE: projected container shape changed"
+  let element = N.NSStruct (V.fromList [("empty", optional), ("anchor", N.NSPrimitive N.LtInt32)])
+      list = N.NSOptional (N.NSList element)
+      item n = N.NRStruct (V.fromList [N.NRNull, integer n])
+  listBytes <- load (encode list (V.fromList [N.NRNull, N.NRList V.empty, N.NRList (V.fromList [item 10, item 20, item 30, item 40, item 50])]))
+  listColumn <- V.head <$> load (decode listBytes)
+  case listColumn of
+    C.ColList _ _ (C.ColStruct 5 _ children) -> check "nested FILE uses element count rather than top-level count" (C.nullCount (snd (V.head children)) == 5)
+    _ -> fail "zero-leaf FILE: nested list counts changed"
+  listFile <- load (Read.loadParquetFile listBytes)
+  listSchema <- load (Arrow.parquetFileArrowSchemaChecked listFile)
+  check "nested budget counts elements, not top-level rows" (isLeft (Arrow.parquetRowGroupToArrowWithLimits (Arrow.ReadLimits 4) listSchema listFile 0))
+  let mapShape = N.NSOptional (N.NSMap (N.NSPrimitive N.LtInt32) optional)
+  mapBytes <- load (encode mapShape (V.fromList [N.NRNull, N.NRMapEntries V.empty, N.NRMapEntries (V.fromList [(integer 1, N.NRNull), (integer 2, N.NRNull)])]))
+  mapColumn <- V.head <$> load (decode mapBytes)
+  case mapColumn of
+    C.ColMap _ _ keys values -> check "map value uses entry count" (C.columnLength keys == 2 && C.columnLength values == 2 && C.nullCount values == 2)
+    _ -> fail "zero-leaf FILE: map values changed"
+  let emptyKeyMap = N.NSOptional (N.NSMap file (N.NSOptional (N.NSPrimitive N.LtInt32)))
+  keyBytes <- load (encode emptyKeyMap (V.fromList [N.NRNull, N.NRMapEntries V.empty, N.NRMapEntries V.empty]))
+  keyColumn <- V.head <$> load (decode keyBytes)
+  case keyColumn of
+    C.ColMap _ _ keys _ -> check "empty map with zero-leaf key has no null key values" (C.columnLength keys == 0 && C.nullCount keys == 0)
+    _ -> fail "zero-leaf FILE: empty map key changed"
+  let readLimit limit = Arrow.parquetRowGroupToArrowWithLimits (Arrow.ReadLimits limit) schema parsed 0
+  check "caller can select unbacked-value budget" (isLeft (readLimit 2) && either (const False) (const True) (readLimit 3) && isLeft (readLimit (-1)))
+  both <- load (N.buildNestedFile (V.fromList [("left", optional), ("right", optional)]) (V.replicate 2 (V.replicate 3 N.NRNull)))
+  bothFile <- load (Read.loadParquetFile both)
+  bothSchema <- load (Arrow.parquetFileArrowSchemaChecked bothFile)
+  check "budget is aggregate across output FILE columns" (isLeft (Arrow.parquetRowGroupToArrowWithLimits (Arrow.ReadLimits 5) bothSchema bothFile 0))
+  _ <- either (fail . show) pure (Arrow.parquetRowGroupToArrowWithLimits (Arrow.ReadLimits 6) bothSchema bothFile 0)
+  let inflate count =
+        let footer = Read.pfFooter parsed
+            changed = footer {P.fmNumRows = count, P.fmRowGroups = V.map (\group -> group {P.rgNumRows = count}) (P.fmRowGroups footer)}
+        in "PAR1" <> Footer.writeFooter changed
+  forM_ [1048577, maxBound :: Int64] $ \claimed ->
+    check "tiny footers cannot trigger unbounded allocation or Int overflow" (isLeft (decode (inflate claimed)))
+  raisedFile <- load (Read.loadParquetFile (inflate 1048577))
+  raised <- either (fail . show) pure (Arrow.parquetRowGroupToArrowWithLimits (Arrow.ReadLimits 1048577) schema raisedFile 0)
+  check "explicit budget override supports larger valid null columns" (C.columnLength (V.head raised) == 1048577 && C.nullCount (V.head raised) == 1048577)
+  forM_ ["root-0-optional", "root-0-required", "root-3-optional", "root-3-required", "with-anchor"] $ \name -> do
+    fixtureBytes <- BS.readFile ("test/fixtures/file-zero-" <> name <> ".parquet")
+    decoded <- load (Read.loadParquetFile fixtureBytes)
+    inferred <- load (Arrow.parquetFileArrowSchemaChecked decoded)
+    let expectedRows = if name == "root-0-optional" || name == "root-0-required" then 0 else 3
+    check "independent fixture retains the FILE field even without row groups" (A.fieldName (V.head (A.arrowFields inferred)) == "f")
+    if V.null (P.fmRowGroups (Read.pfFooter decoded))
+      then check "absent row groups represent an empty file" (expectedRows == 0 && P.fmNumRows (Read.pfFooter decoded) == 0)
+      else do
+        values <- load (decode fixtureBytes)
+        check "independent Thrift/PyArrow fixture retains zero-leaf FILE column" (C.columnLength (V.head values) == expectedRows && C.nullCount (V.head values) == expectedRows)
+  putStrLn "Zero-leaf FILE identity, representable nulls/containers, projection and aggregate resource budgets passed."
diff --git a/test/GeospatialRegression.hs b/test/GeospatialRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/GeospatialRegression.hs
@@ -0,0 +1,96 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module GeospatialRegression (tests) where
+
+import Arrow.Types qualified as A
+import Control.Monad (forM_, unless)
+import Data.Aeson qualified as J
+import Data.Aeson.KeyMap qualified as KM
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Text (Text)
+import Data.Text.Encoding qualified as TE
+import Data.Vector qualified as V
+import Parquet.Arrow qualified as Arrow
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+
+
+fieldFor :: P.LogicalType -> Maybe (V.Vector P.KeyValue) -> Either String A.Field
+fieldFor logical entries = do
+  let root = P.SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+      leaf = P.SchemaElement "g" (Just P.Optional) (Just P.PTByteArray) Nothing Nothing (Just logical) Nothing Nothing
+      footer = P.FileMetadata 1 (V.fromList [root, leaf]) 0 V.empty Nothing Nothing entries
+  schema <- Arrow.parquetFileArrowSchemaChecked (Read.ParquetFile BS.empty footer)
+  Right (V.head (A.arrowFields schema))
+
+
+parameters :: A.Field -> Either String J.Object
+parameters field = case V.find ((== "ARROW:extension:metadata") . fst) (A.fieldMetadata field) of
+  Nothing -> Left "missing extension parameters"
+  Just (_, encoded) -> case J.eitherDecodeStrict' (TE.encodeUtf8 encoded) of
+    Right (J.Object fields) -> Right fields
+    _ -> Left "extension parameters are not a JSON object"
+
+
+logicalFor :: A.Field -> Either String (Maybe P.LogicalType)
+logicalFor field = do
+  let schema = A.Schema (V.singleton field) A.Little V.empty V.empty
+  (elements, _) <- Arrow.arrowToParquetMixed schema []
+  Right (P.seLogicalType (elements V.! 1))
+
+
+geoField :: Text -> A.Field
+geoField encoded =
+  A.Field
+    "g"
+    True
+    A.ABinary
+    V.empty
+    Nothing
+    (V.fromList [("ARROW:extension:name", "geoarrow.wkb"), ("ARROW:extension:metadata", encoded)])
+
+
+tests :: IO ()
+tests = do
+  let check label condition = unless condition (fail ("geospatial metadata: " ++ label))
+      load result = either fail pure result
+      crs = Just "EPSG:4326"
+  planar <- load (fieldFor (P.LTGeometry P.defaultGeometryParameters) Nothing)
+  object <- load (parameters planar)
+  check
+    "default CRS becomes explicit known CRS in GeoArrow"
+    (KM.lookup "crs" object == Just (J.String "OGC:CRS84"))
+  check "planar edges are omitted" (KM.lookup "edges" object == Nothing)
+  check
+    "canonical WKB extension retains binary storage"
+    (A.fieldType planar == A.ABinary && V.elem ("ARROW:extension:name", "geoarrow.wkb") (A.fieldMetadata planar))
+  forM_ [(P.Spherical, "spherical"), (P.Vincenty, "vincenty"), (P.Thomas, "thomas"), (P.Andoyer, "andoyer"), (P.Karney, "karney")] $ \(algorithm, name) -> do
+    let expected = P.LTGeography (P.GeographyParameters crs (Just algorithm))
+    field <- load (fieldFor expected Nothing)
+    fields <- load (parameters field)
+    check "all five edge algorithms keep their names" (KM.lookup "edges" fields == Just (J.String name))
+    check "known geography metadata survives both directions" (logicalFor field == Right (Just expected))
+  spherical <- load (fieldFor (P.LTGeography P.defaultGeographyParameters) Nothing >>= parameters)
+  check "absent geography algorithm has spherical semantics" (KM.lookup "edges" spherical == Just (J.String "spherical"))
+  let definition = "{\"type\":\"GeographicCRS\",\"name\":\"WGS 84\",\"datum\":{\"type\":\"GeodeticReferenceFrame\",\"name\":\"World Geodetic System 1984\",\"ellipsoid\":{\"name\":\"WGS 84\",\"semi_major_axis\":6378137,\"inverse_flattening\":298.257223563}},\"coordinate_system\":{\"subtype\":\"ellipsoidal\",\"axis\":[{\"name\":\"Longitude\",\"abbreviation\":\"lon\",\"direction\":\"east\",\"unit\":\"degree\"},{\"name\":\"Latitude\",\"abbreviation\":\"lat\",\"direction\":\"north\",\"unit\":\"degree\"}]}}"
+      annotation = P.LTGeometry (P.GeometryParameters (Just "projjson:crs"))
+      entry = P.KeyValue "crs" (Just (TE.encodeUtf8 definition))
+  reference <- load (fieldFor annotation (Just (V.singleton entry)) >>= parameters)
+  inline <- load (fieldFor (P.LTGeometry (P.GeometryParameters (Just definition))) Nothing >>= parameters)
+  check "referenced PROJJSON resolves without an escaped JSON string" (KM.lookup "crs" reference == KM.lookup "crs" inline && case KM.lookup "crs" reference of Just J.Object {} -> True; _ -> False)
+  forM_ [Nothing, Just V.empty, Just (V.singleton (P.KeyValue "crs" Nothing)), Just (V.fromList [entry, entry]), Just (V.singleton (P.KeyValue "crs" (Just "[]"))), Just (V.singleton (P.KeyValue "crs" (Just (BS.singleton 255))))] $ \entries ->
+    check "bad PROJJSON references do not acquire guessed CRS" (isLeft (fieldFor annotation entries))
+  srid <- load (fieldFor (P.LTGeometry (P.GeometryParameters (Just "srid:42"))) Nothing)
+  sridFields <- load (parameters srid)
+  check "SRID representation is disambiguated" (KM.lookup "crs" sridFields == Just (J.String "42") && KM.lookup "crs_type" sridFields == Just (J.String "srid"))
+  check "SRID prefix is restored when writing" (logicalFor srid == Right (Just (P.LTGeometry (P.GeometryParameters (Just "srid:42")))))
+  future <- load (fieldFor (P.LTGeography (P.GeographyParameters Nothing (Just (P.UnrecognizedInterpolation 99)))) Nothing)
+  check "future algorithm stays physical binary without planar metadata" (A.fieldType future == A.ABinary && V.null (A.fieldMetadata future))
+  forM_ ["{}", "{\"crs\":null}", "{\"crs\":\"\"}", "{\"crs\":\"EPSG:4326\",\"edges\":\"rhumb\"}", "{\"crs\":\"EPSG:4326\",\"crs_type\":\"future\"}", "[]", "{\"crs\":\"projjson:external\"}"] $ \encoded ->
+    check "unsupported or unknown metadata fails instead of changing semantics" (isLeft (logicalFor (geoField encoded)))
+  let known = geoField "{\"crs\":\"EPSG:3857\"}"
+  check "large-binary WKB is supported" (logicalFor known {A.fieldType = A.ALargeBinary} == Right (Just (P.LTGeometry (P.GeometryParameters (Just "EPSG:3857")))))
+  check "WKB annotation cannot be put on UTF-8 storage" (isLeft (logicalFor known {A.fieldType = A.AUtf8}))
+  check "duplicate extension keys are not resolved arbitrarily" (isLeft (logicalFor known {A.fieldMetadata = V.snoc (A.fieldMetadata known) ("ARROW:extension:name", "arrow.json")}))
+  putStrLn "GeoArrow metadata regression cases passed."
diff --git a/test/LargeOffsetRegression.hs b/test/LargeOffsetRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/LargeOffsetRegression.hs
@@ -0,0 +1,98 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module LargeOffsetRegression (tests) where
+
+import Arrow.Column qualified as A
+import Arrow.Types qualified as T
+import Control.Exception (evaluate)
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as B
+import Data.ByteString.Lazy qualified as BL
+import Data.Either (isLeft)
+import Data.List (isInfixOf)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as P
+import Data.Vector.Storable qualified as S
+import GHC.Conc (getAllocationCounter)
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Arrow qualified as Arrow
+import Parquet.HighLevel qualified as High
+import Parquet.Page qualified as Page
+import Parquet.Predicate qualified as Pred
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as Types
+import Parquet.Write qualified as Write
+import System.Mem (performGC)
+
+
+check :: String -> Bool -> IO ()
+check name ok = unless ok (fail ("Large-offset regression: " ++ name))
+
+
+plain :: [BS.ByteString] -> BS.ByteString
+plain = BL.toStrict . B.toLazyByteString . foldMap (\bytes -> B.word32LE (fromIntegral (BS.length bytes)) <> B.byteString bytes)
+
+
+page :: Page.PageType -> BS.ByteString -> BS.ByteString
+page typ body = Write.encodePageHeader (Page.PageHeader typ (Just (fromIntegral (BS.length body))) (Just (fromIntegral (BS.length body)))) <> body
+
+
+tests :: IO ()
+tests = do
+  valid <- H.check $ H.withTests 300 $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 64) (BS.pack <$> Gen.list (Range.linear 0 256) (Gen.word8 Range.constantBounded)))
+    let bytes = plain values
+        count = length values
+        expected = BS.concat values
+    small <- H.evalEither (Read.decodePlainBinaryBuffers count bytes)
+    large <- H.evalEither (Read.decodePlainLargeBinaryBuffers count bytes)
+    Read.binaryData small H.=== expected
+    Read.binaryData large H.=== expected
+    Read.binaryOffsets large H.=== S.map fromIntegral (Read.binaryOffsets small)
+  check "32/64-bit PLAIN buffers preserve identical bytes and offsets" valid
+  forM_ [(-1, BS.empty), (maxBound, BS.empty), (1, BS.pack [0, 0, 0]), (1, BS.pack [255, 255, 255, 255]), (1, BS.pack [4, 0, 0, 0, 1]), (0, "trailing")] $ \(count, bytes) ->
+    check "large PLAIN bounds reject malformed inputs" (isLeft (Read.decodePlainLargeBinaryBuffers count bytes))
+  let values = V.fromList ["", "alpha", "\NUL\255"]
+      dictionary = Write.Dictionary (Write.ColByteArray values) (P.fromList [0, 1, 2, 1, 0])
+      mixed = Write.encodeDictPage dictionary <> Write.encodeDictDataPage dictionary <> page (Page.PtDataPage (Page.DataPageHeader 2 0)) (plain ["tail", ""])
+  small <- either fail pure (Read.readBinaryBuffersColumnChunk Types.Uncompressed mixed)
+  large <- either fail pure (Read.readLargeBinaryBuffersColumnChunk Types.Uncompressed mixed)
+  check "mixed dictionary/plain pages retain64-bit offsets" (Read.binaryData large == Read.binaryData small && Read.binaryOffsets large == S.map fromIntegral (Read.binaryOffsets small))
+  -- A small shared dictionary requests exactly2GiB of output. The32-bit
+  -- reader must reject before allocating indices/payload; the64-bit reader
+  -- must get past that prefix and reject the subsequent invalid page without
+  -- materializing the2GiB payload. The full valid file has a separate external
+  -- resource test, keeping the ordinary regression suite lightweight.
+  let expansion = Write.Dictionary (Write.ColByteArray (V.singleton (BS.replicate 32768 97))) (P.replicate 65536 0)
+      oversized = Write.encodeDictPage expansion <> Write.encodeDictDataPage expansion
+      invalidTail = page (Page.PtDataPage (Page.DataPageHeader 1 99)) BS.empty
+      complete = oversized <> invalidTail
+  _ <- evaluate (BS.length complete)
+  _ <- evaluate (BS.length oversized)
+  performGC
+  before <- getAllocationCounter
+  narrowRejected <- evaluate (isLeft (Read.readBinaryBuffersColumnChunk Types.Uncompressed oversized))
+  wideFailure <- evaluate (case Read.readLargeBinaryBuffersColumnChunk Types.Uncompressed complete of Left message -> "99" `isInfixOf` message; Right _ -> False)
+  after <- getAllocationCounter
+  check "large prefix preflight keeps width and bounds without2GiB allocation" (narrowRejected && wideFailure && before - after < 4 * 1024 * 1024)
+  forM_ [False, True] $ \indexed -> do
+    let root = Types.SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        leaf = Types.SchemaElement "v" (Just Types.Required) (Just Types.PTByteArray) Nothing (Just Types.CTUtf8) (Just Types.LTString) Nothing Nothing
+        source = High.encodeParquet High.defaultWriteOptions {High.writeCompression = Types.Uncompressed, High.writePageIndex = indexed} (V.fromList [root, leaf]) [V.singleton (Write.ColByteArray (V.fromList ["alpha", "beta"]))]
+    file <- either fail pure (High.decodeParquet High.defaultReadOptions source)
+    native <- either fail pure (Arrow.parquetFileArrowSchemaChecked file)
+    let target = (V.head (T.arrowFields native)) {T.fieldType = T.ALargeUtf8}
+    direct <- either fail pure (Arrow.readParquetColumn file 0 0 target)
+    check "direct large string read" (largeStrings direct == Just ["alpha", "beta"])
+    projected <- either (fail . show) pure (Arrow.parquetRowGroupToArrow native {T.arrowFields = V.singleton target} file 0)
+    check "flat schema large string projection" (largeStrings (V.head projected) == Just ["alpha", "beta"])
+    (_, kept) <- either fail pure (Arrow.readParquetColumnWithPagePruning file 0 0 target (Pred.PEq (Pred.PVText "alpha")))
+    check "indexed/fallback large string projection" (largeStrings kept == Just ["alpha", "beta"])
+    (_, skipped) <- either fail pure (Arrow.readParquetColumnWithPagePruning file 0 0 target (Pred.PGt (Pred.PVText "zzz")))
+    check "empty indexed selection retains64-bit storage" (largeStrings skipped == Just (if indexed then [] else ["alpha", "beta"]))
+  where
+    largeStrings (A.ColLargeUtf8 _ offsets bytes) = Just (map (\i -> BS.take (fromIntegral (offsets S.! (i + 1) - offsets S.! i)) (BS.drop (fromIntegral (offsets S.! i)) bytes)) [0 .. S.length offsets - 2])
+    largeStrings _ = Nothing
diff --git a/test/Main.hs b/test/Main.hs
new file mode 100644
--- /dev/null
+++ b/test/Main.hs
@@ -0,0 +1,3376 @@
+{-# LANGUAGE CPP #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE OverloadedStrings #-}
+module Main (main) where
+
+import qualified GeospatialRegression
+import qualified FileRegression
+import qualified FileArrowRegression
+import qualified FileZeroRegression
+import qualified SchemaBoundaryRegression
+import qualified CodecBoundaryRegression
+import BloomBuilderRegression qualified
+import NestedStatisticsRegression qualified
+import NestedOptionsRegression qualified
+import EncryptedWriterRegression qualified
+import EncryptedReadRegression qualified
+import EncryptionFooterRegression qualified
+import LargeOffsetRegression qualified
+import qualified TimestampRegression
+import qualified NestedPrimitiveRegression
+import qualified VariantSchemaRegression
+import qualified VariantWriteRegression
+import qualified VariantArrowRegression
+import qualified VariantRegression
+import qualified VariantParquetRegression
+import qualified DecimalCapacityRegression
+import qualified MetadataRegression
+import qualified Aggregate
+import qualified AlpRegression
+import qualified Selection
+import qualified WriterBounds
+import Control.Exception (SomeException, evaluate, try)
+import Control.Monad (unless, when)
+import Data.Bits (xor, setBit, testBit, (.|.))
+import qualified Data.ByteString as BS
+import qualified Data.ByteString.Char8 as BSC
+import qualified Data.Vector as V
+import Numeric (showHex)
+import GHC.Float (castWord32ToFloat, castFloatToWord32, castDoubleToWord64)
+import Data.List (isInfixOf)
+import Data.Either (isLeft)
+import qualified Data.Text as T
+import System.Directory (doesFileExist)
+import System.Exit (ExitCode (..), exitFailure)
+import qualified System.Process as Proc
+
+import qualified Data.Vector.Primitive as VP
+import qualified Data.Vector.Storable as VS
+import Data.Int (Int8, Int16, Int32, Int64)
+import Data.Ratio ((%))
+import Data.List.NonEmpty qualified as NE
+import Data.Word (Word8, Word16, Word32, Word64)
+
+import qualified Crypto.Random as RNG
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+
+import Parquet.BloomFilter
+import Parquet.Aggregate qualified as PAgg
+import Columnar.Predicate qualified as SharedPred
+import Parquet.Compress (compressPageBytes)
+import Parquet.LevelsEncode qualified as LE
+import Data.Bits (shiftL, shiftR, (.&.))
+import Parquet.ByteStreamSplit
+  ( encodeByteStreamSplitDouble
+  , encodeByteStreamSplitFloat
+  )
+import Parquet.Delta
+  ( decodeDeltaBinaryPackedInt64
+  , decodeDeltaByteArray
+  , decodeDeltaLengthByteArray
+  )
+import Parquet.DeltaEncode
+  ( encodeDeltaBinaryPackedInt32
+  , encodeDeltaBinaryPackedInt64
+  , encodeDeltaByteArray
+  , encodeDeltaLengthByteArray
+  )
+import qualified Parquet.Nested as Nested
+import qualified Parquet.NullPagesBitmap as NPB
+import qualified Parquet.Encryption as Enc
+import Parquet.PageIndex
+import qualified Parquet.Footer as Footer
+import Parquet.Thrift.Schema qualified as TS
+import Thrift.Encode qualified as Thrift
+import Thrift.Value qualified as TV
+import Parquet.Footer (FooterTrailer (..), parquetMagic)
+import qualified Parquet.Predicate as Pred
+import qualified Parquet.Read
+import Parquet.Read
+  ( decodeByteStreamSplitDouble
+  , decodeByteStreamSplitFloat
+  , loadParquetFile
+  , pfFooter
+  )
+import Parquet.Types
+import Parquet.Timestamp qualified as Timestamp
+import Parquet.Page
+  ( DataPageHeader (..)
+  , DataPageHeaderV2 (..)
+  , DictionaryPageHeader (..)
+  , PageHeader (..)
+  , PageType (..)
+  , readPageHeaderAt
+  , readPageHeaderCheckedAt
+  )
+import Parquet.Write
+  ( ColumnAux (..)
+  , ColumnEncryption (..)
+  , FooterEncryption (..)
+  , PageVersion (..)
+  , ColumnData (..)
+  , Dictionary (..)
+  , OptionalColumn (..)
+  , ParquetColumn (..)
+  , buildDictionary
+  , buildParquetFile
+  , buildParquetFileWithIndex
+  , buildParquetFileWithIndexIO
+  , buildParquetFileWithIndexEncryptedFooter
+  , columnDataLength
+  , columnDataStatistics
+  , emptyColumnAux
+  , encodeColumnDataPageParts
+  , encodeColumnDataPageV2
+  , encodeDictDataPage
+  , encodeDictPage
+  , encodeOptionalColumnPage
+  , encodeOptionalColumnPageV2Parts
+  , encodePageHeader
+  , encryptAuxModule
+  , encryptPageBytes
+  , encryptPageBytesV2
+  , optionalColumnLength
+  , optionalColumnNullCount
+  )
+import qualified Wireform.Hash as Hash
+
+import qualified Arrow.Column      as AC
+import qualified Arrow.Types       as AT
+import qualified Parquet.Arrow     as PArrow
+import qualified Parquet.HighLevel as PHL
+
+main :: IO ()
+main = do
+  DecimalCapacityRegression.tests
+  VariantWriteRegression.tests
+  VariantArrowRegression.tests
+  MetadataRegression.tests
+  GeospatialRegression.tests
+  FileRegression.tests
+  FileArrowRegression.tests
+  FileZeroRegression.tests
+  SchemaBoundaryRegression.tests
+  CodecBoundaryRegression.tests
+  BloomBuilderRegression.tests
+  NestedStatisticsRegression.tests
+  NestedOptionsRegression.tests
+  EncryptedWriterRegression.tests
+  EncryptedReadRegression.tests
+  EncryptionFooterRegression.tests
+  LargeOffsetRegression.tests
+  TimestampRegression.tests
+  NestedPrimitiveRegression.tests
+  VariantSchemaRegression.tests
+  VariantRegression.tests
+  VariantParquetRegression.tests
+  -- XXH64 reference vectors.
+  expectHash "" "ef46db3751d8e999"
+  expectHash "abc" "44bc2cf5ad770999"
+  expectHash "Nobody inspects the spammish repetition" "fbcea83c8a378bf1"
+  -- 32 bytes of 'a' is exactly one bulk stripe (xxhsum -H1 reference).
+  expectHashBs (BS.replicate 32 0x61) "856e843298f99ad7"
+  -- 64 bytes (two stripes) — exercises the bulk-phase merge.
+  expectHashBs (BS.replicate 64 0x62) "ecbaf4bdf26b6349"
+
+  -- OffsetIndex round-trip.
+  let oi = OffsetIndex
+        { oiPageLocations = V.fromList
+            [ PageLocation 100 200 0
+            , PageLocation 300 250 50
+            ]
+        , oiUnencodedByteArrayDataBytes = Just (V.fromList [42, 99])
+        }
+  expect "OffsetIndex round-trip"
+    (decodeOffsetIndex (encodeOffsetIndex oi) == Right oi)
+
+  -- ColumnIndex round-trip with all optional fields.
+  let ci = ColumnIndex
+        { ciNanCounts = Just (V.fromList [0, 1, 0])
+        , ciNullPages = V.fromList [False, False, True]
+        , ciMinValues = V.fromList [BSC.pack "a", BSC.pack "b", BS.empty]
+        , ciMaxValues = V.fromList [BSC.pack "z", BSC.pack "y", BS.empty]
+        , ciBoundaryOrder = OrderAscending
+        , ciNullCounts = Just (V.fromList [0, 0, 100])
+        , ciRepetitionLevelHistograms = Just (V.fromList [10, 5])
+        , ciDefinitionLevelHistograms = Just (V.fromList [3, 8])
+        }
+  expect "ColumnIndex round-trip"
+    (decodeColumnIndex (encodeColumnIndex ci) == Right ci)
+
+  -- Bloom filter membership.
+  let sbbf0 = newSbbf 1024
+      values = ["alpha", "beta", "gamma", "delta", "epsilon"]
+      sbbf  = foldr (sbbfInsert . BSC.pack) sbbf0 values
+  mapM_ (\v -> expect ("bloom contains " ++ v)
+                 (sbbfCheck (BSC.pack v) sbbf)) values
+
+  -- Golden vector from arrow-rs / parquet-mr: a 32-byte bitset produced
+  -- by parquet-mr for the strings "a0".."a9" must report all of them
+  -- present.  This proves byte-compatibility of our XXH64 + block layout
+  -- with the reference writer.
+  let goldenBits = BS.pack
+        [ 200, 1, 80, 20, 64, 68, 8, 109, 6, 37, 4, 67, 144, 80, 96, 32
+        , 8, 132, 43, 33, 0, 5, 99, 65, 2, 0, 224, 44, 64, 78, 96, 4 ]
+      goldenSbbf = newSbbfFromBytes goldenBits
+  mapM_ (\i -> let v = "a" <> show i in
+                 expect ("golden contains " ++ v)
+                   (sbbfCheck (BSC.pack v) goldenSbbf))
+        [(0 :: Int) .. 9]
+
+  -- Bloom filter false-positive sanity.
+  let sbbfBig0 = newSbbf 2048
+      inserted = map (BSC.pack . ("inserted-" <>) . show) [0 .. 255 :: Int]
+      probes   = map (BSC.pack . ("probe-" <>) . show)   [0 .. 255 :: Int]
+      sbbfBig  = foldr sbbfInsert sbbfBig0 inserted
+      fp = length (filter (`sbbfCheck` sbbfBig) probes)
+  expect ("bloom FP rate (got " ++ show fp ++ ")") (fp <= 16)
+
+  -- Bloom encode/decode round-trip.
+  let bs = encodeBloomFilter sbbf
+  case decodeBloomFilter bs of
+    Left e -> failTest ("decodeBloomFilter: " ++ e)
+    Right (_hdr, sbbf') -> do
+      expect "decoded numBytes" (sbbfNumBytes sbbf' == sbbfNumBytes sbbf)
+      mapM_ (\v -> expect ("decoded contains " ++ v)
+                     (sbbfCheck (BSC.pack v) sbbf')) values
+
+  -- Statistics (via columnDataStatistics, the public column-typed API).
+  let s32 = columnDataStatistics (ColInt32 (VP.fromList [3, -1, 7, 0, 4 :: Int32]))
+  expect "Int32 stats min"
+    (statMinValue s32 == Just (BS.pack [0xFF, 0xFF, 0xFF, 0xFF]))   -- -1 LE
+  expect "Int32 stats max"
+    (statMaxValue s32 == Just (BS.pack [0x07, 0x00, 0x00, 0x00]))
+  expect "Int32 stats nullCount"
+    (statNullCount s32 == Just 0)
+  let s64 = columnDataStatistics (ColInt64 (VP.fromList [10, 5, -3, 100 :: Int64]))
+  expect "Int64 stats min/max present"
+    (statMinValue s64 /= Nothing && statMaxValue s64 /= Nothing)
+  let sBA = columnDataStatistics
+              (ColByteArray (V.fromList [BSC.pack "banana", BSC.pack "apple", BSC.pack "cherry"]))
+  expect "ByteArray stats min == 'apple'"
+    (statMinValue sBA == Just (BSC.pack "apple"))
+  expect "ByteArray stats max == 'cherry'"
+    (statMaxValue sBA == Just (BSC.pack "cherry"))
+  let binaryBounds = columnDataStatistics (ColByteArray (V.fromList [BS.pack [0x80], BS.pack [0x7f]]))
+  expect "unsigned byte bounds never advertise legacy signed ordering"
+    (statMin binaryBounds == Nothing && statMax binaryBounds == Nothing
+      && statMinValue binaryBounds == Just (BS.pack [0x7f])
+      && statMaxValue binaryBounds == Just (BS.pack [0x80])
+      && statMinValueExact binaryBounds == Just True && statMaxValueExact binaryBounds == Just True)
+  let sEmpty = columnDataStatistics (ColInt32 VP.empty)
+  expect "empty Int32 stats has no min/max"
+    (statMinValue sEmpty == Nothing && statMaxValue sEmpty == Nothing)
+
+  -- Writer attaches statistics that round-trip through readFooter.
+  let schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "x" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+        ]
+      vs   = VP.fromList [(3 :: Int32), -1, 7, 0, 4]
+      fbs  = buildParquetFile schema (V.singleton (V.singleton (ColInt32 vs)))
+  case loadParquetFile fbs of
+    Left e -> failTest ("loadParquetFile: " ++ e)
+    Right pf -> do
+      let !rgs = fmRowGroups (pfFooter pf)
+          !cm = ccMetadata
+                  (V.unsafeIndex (rgColumns (V.unsafeIndex rgs 0)) 0)
+      case cm of
+        Nothing -> failTest "expected ColumnMetadata"
+        Just m -> case cmStatistics m of
+          Nothing -> failTest "writer omitted statistics"
+          Just st -> do
+            expect "writer min == -1"
+              (statMinValue st == Just (BS.pack [0xFF, 0xFF, 0xFF, 0xFF]))
+            expect "writer max == 7"
+              (statMaxValue st == Just (BS.pack [0x07, 0x00, 0x00, 0x00]))
+
+  -- buildParquetFileWithIndex: bloom filter + page index + column index
+  -- offsets are populated on the round-tripped column metadata.
+  let schemaIdx = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "y" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+        ]
+      vsIdx = ColInt32 (VP.fromList [(1 :: Int32), 2, 3, 4])
+      bf    = sbbfInsertHash 0xdeadbeef (newSbbf (optimalNumBytes 1024 0.01))
+      oiIdx = OffsetIndex
+                { oiPageLocations = V.singleton (PageLocation 0 16 0)
+                , oiUnencodedByteArrayDataBytes = Nothing
+                }
+      ciIdx = ColumnIndex
+                { ciNanCounts = Nothing
+                , ciNullPages = V.singleton False
+                , ciMinValues = V.singleton (BS.pack [0x01, 0, 0, 0])
+                , ciMaxValues = V.singleton (BS.pack [0x04, 0, 0, 0])
+                , ciBoundaryOrder = OrderAscending
+                , ciNullCounts = Nothing
+                , ciRepetitionLevelHistograms = Nothing
+                , ciDefinitionLevelHistograms = Nothing
+                }
+      aux   = ColumnAux False (Just bf) (Just oiIdx) (Just ciIdx) Uncompressed PageV1 Nothing
+      fIdx  = buildParquetFileWithIndex schemaIdx
+                (V.singleton (V.singleton vsIdx))
+                (V.singleton (V.singleton aux))
+      _ = vsIdx :: ColumnData
+  case loadParquetFile fIdx of
+    Left e -> failTest ("indexed-writer load: " ++ e)
+    Right pf -> do
+      let !rgs2 = fmRowGroups (pfFooter pf)
+          !cc   = V.unsafeIndex (rgColumns (V.unsafeIndex rgs2 0)) 0
+      case ccMetadata cc of
+        Nothing -> failTest "indexed-writer: missing metadata"
+        Just m -> do
+          expect "indexed-writer: bloom filter offset populated"
+            (cmBloomFilterOffset m /= Nothing)
+          expect "indexed-writer: bloom filter length populated"
+            (cmBloomFilterLength m /= Nothing)
+      expect "indexed-writer: offset index offset populated"
+        (ccOffsetIndexOffset cc /= Nothing)
+      expect "indexed-writer: offset index length populated"
+        (ccOffsetIndexLength cc /= Nothing)
+      expect "indexed-writer: column index offset populated"
+        (ccColumnIndexOffset cc /= Nothing)
+      expect "indexed-writer: column index length populated"
+        (ccColumnIndexLength cc /= Nothing)
+      writtenIndex <- either failTest pure (readOffsetIndex pf 0 0)
+      locations <- maybe (failTest "explicit offset index missing") (pure . oiPageLocations) writtenIndex
+      selected <- either failTest pure (Parquet.Read.readGenericInt32SelectedPages
+        Uncompressed fIdx locations (V.singleton True))
+      expect "explicit index offsets and sizes are repaired to select the real page"
+        (selected == VP.fromList [1,2,3,4])
+
+  -- Typed (heterogeneous-primitive) writer: write a row group with one
+  -- column of each primitive type and confirm each round-trips through
+  -- the footer.
+  let schemaTyped = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 6) Nothing Nothing Nothing Nothing
+        , SchemaElement "i32"  (Just Required) (Just PTInt32)     Nothing Nothing Nothing Nothing Nothing
+        , SchemaElement "i64"  (Just Required) (Just PTInt64)     Nothing Nothing Nothing Nothing Nothing
+        , SchemaElement "f32"  (Just Required) (Just PTFloat)     Nothing Nothing Nothing Nothing Nothing
+        , SchemaElement "f64"  (Just Required) (Just PTDouble)    Nothing Nothing Nothing Nothing Nothing
+        , SchemaElement "bool" (Just Required) (Just PTBoolean)   Nothing Nothing Nothing Nothing Nothing
+        , SchemaElement "ba"   (Just Required) (Just PTByteArray) Nothing Nothing Nothing Nothing Nothing
+        ]
+      cols  = V.fromList
+        [ ColInt32     (VP.fromList [(1 :: Int32), 2, 3])
+        , ColInt64     (VP.fromList [(10 :: Int64), 20, 30])
+        , ColFloat     (VP.fromList [1.5 :: Float, 2.5, 3.5])
+        , ColDouble    (VP.fromList [1e9 :: Double, 2e9, 3e9])
+        , ColBool      (V.fromList [True, False, True])
+        , ColByteArray (V.fromList [BSC.pack "alpha", BSC.pack "beta", BSC.pack "gamma"])
+        ]
+      fTyped = buildParquetFile schemaTyped (V.singleton cols)
+  case loadParquetFile fTyped of
+    Left e -> failTest ("typed-writer load: " ++ e)
+    Right pf -> do
+      let !rgs3 = fmRowGroups (pfFooter pf)
+          !rg   = V.unsafeIndex rgs3 0
+      expect "typed-writer: 6 columns recorded"
+        (V.length (rgColumns rg) == 6)
+      expect "typed-writer: numRows == 3"
+        (rgNumRows rg == 3)
+      let typeOf i = case ccMetadata (V.unsafeIndex (rgColumns rg) i) of
+            Just m  -> Just (cmType m)
+            Nothing -> Nothing
+      expect "typed-writer: column 0 is INT32"
+        (typeOf 0 == Just PTInt32)
+      expect "typed-writer: column 1 is INT64"
+        (typeOf 1 == Just PTInt64)
+      expect "typed-writer: column 2 is FLOAT"
+        (typeOf 2 == Just PTFloat)
+      expect "typed-writer: column 3 is DOUBLE"
+        (typeOf 3 == Just PTDouble)
+      expect "typed-writer: column 4 is BOOLEAN"
+        (typeOf 4 == Just PTBoolean)
+      expect "typed-writer: column 5 is BYTE_ARRAY"
+        (typeOf 5 == Just PTByteArray)
+
+  -- Per-column compression: GZip is always available; round-trip a column
+  -- through the writer and confirm the metadata records the codec.
+  let auxesGzip = V.singleton (V.fromList
+        [ ColumnAux False Nothing Nothing Nothing GZip PageV1 Nothing
+        , ColumnAux False Nothing Nothing Nothing GZip PageV1 Nothing
+        , ColumnAux False Nothing Nothing Nothing Uncompressed PageV1 Nothing  -- floats stay raw
+        , ColumnAux False Nothing Nothing Nothing GZip PageV1 Nothing
+        , ColumnAux False Nothing Nothing Nothing Uncompressed PageV1 Nothing
+        , ColumnAux False Nothing Nothing Nothing GZip PageV1 Nothing
+        ])
+      fGz = buildParquetFileWithIndex schemaTyped (V.singleton cols) auxesGzip
+  case loadParquetFile fGz of
+    Left e -> failTest ("gzip-writer load: " ++ e)
+    Right pf -> do
+      let !rgs4 = fmRowGroups (pfFooter pf)
+          !rg4  = V.unsafeIndex rgs4 0
+          codecOf i = case ccMetadata (V.unsafeIndex (rgColumns rg4) i) of
+            Just m  -> Just (cmCodec m)
+            Nothing -> Nothing
+      expect "gzip-writer: column 0 codec = GZip"
+        (codecOf 0 == Just GZip)
+      expect "gzip-writer: column 2 codec = Uncompressed"
+        (codecOf 2 == Just Uncompressed)
+      expect "gzip-writer: column 5 codec = GZip"
+        (codecOf 5 == Just GZip)
+      -- Compressed page bytes should be smaller for the byte-array column
+      -- (5 letters per value, three values; gzip beats raw at that size
+      -- by virtue of the 4-byte length-prefix overhead overlapping with
+      -- the gzip header but for our test we only assert it's <= raw).
+      let compSize i = case ccMetadata (V.unsafeIndex (rgColumns rg4) i) of
+            Just m -> Just (cmTotalCompressedSize m, cmTotalUncompressedSize m)
+            Nothing -> Nothing
+      case compSize 0 of
+        Just (c, u) -> expect "gzip-writer: column 0 has uncompressed > 0 in metadata"
+          (u > 0 && c > 0)
+        Nothing -> failTest "gzip-writer: column 0 missing metadata"
+
+  -- DATA_PAGE_V2 file round-trip (uncompressed) through buildParquetFileWithIndex.
+  -- We confirm the page header type changes accordingly and the values still
+  -- decode through the V1 PLAIN reader (the value bytes are PLAIN; only the
+  -- header / level layout differ).
+  let v2Schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "x" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+        ]
+      v2Vals = ColInt32 (VP.fromList [(11 :: Int32), 22, 33, 44])
+      v2Aux  = ColumnAux False Nothing Nothing Nothing Uncompressed PageV2 Nothing
+      v2File = buildParquetFileWithIndex v2Schema
+                 (V.singleton (V.singleton v2Vals))
+                 (V.singleton (V.singleton v2Aux))
+  case loadParquetFile v2File of
+    Left e -> failTest ("DATA_PAGE_V2 round-trip load: " ++ e)
+    Right pf -> do
+      let !rgsV2 = fmRowGroups (pfFooter pf)
+      expect "DATA_PAGE_V2: numRows == 4"
+        (rgNumRows (V.unsafeIndex rgsV2 0) == 4)
+  -- Direct page-level V2 encoders must produce DATA_PAGE_V2 headers.
+  case encodeColumnDataPageV2 Uncompressed v2Vals of
+    Left e   -> failTest ("encodeColumnDataPageV2: " ++ e)
+    Right pageBs -> case readPageHeaderAt pageBs 0 of
+      Left e -> failTest ("V2 page header parse: " ++ e)
+      Right (hdr, _) -> case phType hdr of
+        PtDataPageV2 v2 -> do
+          expect "V2 header reports 4 values" (dph2NumValues v2 == 4)
+          expect "V2 header reports 0 nulls"  (dph2NumNulls v2 == 0)
+          expect "V2 header reports 4 rows"   (dph2NumRows v2 == 4)
+        _ -> failTest "V2 encoder did not produce PtDataPageV2"
+
+  -- Nested column shred: optional list of optional INT32, the
+  -- 'list<int?>?' shape every Iceberg V3 default-value array uses.
+  -- For [[Just 1, Nothing, Just 3], [], Nothing] the spec says:
+  --   maxDef=3, maxRep=1
+  --   events:  (d=3,r=0,v=1), (d=2,r=1,v=null), (d=3,r=1,v=3),
+  --            (d=1,r=0,v=null) (empty list),
+  --            (d=0,r=0,v=null) (null list)
+  let nestedRows = V.fromList
+        [ Just (V.fromList [Just (1 :: Int32), Nothing, Just 3])
+        , Just V.empty
+        , Nothing
+        ]
+      nLeaf = Nested.encodeOptionalListOptionalI32 "xs" nestedRows
+  expect "nested leaf maxDef == 3" (Nested.nlMaxDef nLeaf == 3)
+  expect "nested leaf maxRep == 1" (Nested.nlMaxRep nLeaf == 1)
+  expect "nested leaf def levels match Dremel"
+    (VP.toList (Nested.nlDefLevels nLeaf) == [3, 2, 3, 1, 0])
+  expect "nested leaf rep levels match Dremel"
+    (VP.toList (Nested.nlRepLevels nLeaf) == [0, 1, 1, 0, 0])
+  expect "nested leaf present-value count == 2"
+    (Nested.nlValueCount nLeaf == 2)
+  expect "nested leaf PLAIN bytes are LE [1, 3]"
+    (Nested.nlValueBytes nLeaf
+       == BS.pack [0x01,0,0,0, 0x03,0,0,0])
+  expect "nested leaf path is xs.list.element"
+    (V.toList (Nested.nlPath nLeaf) == ["xs", "list", "element"])
+
+  -- Modular encryption round-trip: encrypted column-chunk page-bytes
+  -- must round-trip through encryptPageBytes with the matching AAD.
+  --
+  -- We exercise both algorithms (AES-GCM-V1 and AES-GCM-CTR-V1) and
+  -- assert that flipping one bit of the ciphertext breaks GCM auth.
+  let encKey  = BS.replicate 16 0x42
+      ce alg  = ColumnEncryption
+                  { ceAlgorithm     = alg
+                  , ceKey           = encKey
+                  , ceFileId        = BSC.pack "fileid01"
+                  , ceAadPrefix     = BS.empty
+                  , ceKeyMetadata   = BSC.pack "kid:test"
+                  , ceColumnOrdinal = 0
+                  }
+      encVals = ColInt32 (VP.fromList [(7 :: Int32), 8, 9])
+      encSchema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "v" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+        ]
+      encAux alg = ColumnAux False Nothing Nothing Nothing Uncompressed PageV1 (Just (ce alg))
+      encFooter = FooterEncryption encKey "fileid01" BS.empty "kid:test"
+      encFile alg = buildParquetFileWithIndexEncryptedFooter encFooter encSchema
+                      (V.singleton (V.singleton encVals))
+                      (V.singleton (V.singleton (encAux alg)))
+  gcmFile <- encFile Enc.AesGcmV1 >>= either failTest pure
+  ctrFile <- encFile Enc.AesGcmCtrV1 >>= either failTest pure
+  otherGcmFile <- encFile Enc.AesGcmV1 >>= either failTest pure
+  expect "encrypted file uses fresh nonces on repeated writes" (gcmFile /= otherGcmFile)
+  expect "encrypted file (AES-GCM-V1) is non-empty"
+    (BS.length gcmFile > 0)
+  expect "encrypted file (AES-GCM-CTR-V1) is non-empty"
+    (BS.length ctrFile > 0)
+  expect "encrypted file differs from plaintext output"
+    (gcmFile
+       /= buildParquetFileWithIndex encSchema
+            (V.singleton (V.singleton encVals))
+            (V.singleton (V.singleton emptyColumnAux)))
+
+  -- Round-trip the page through encryptPageBytes / decryptGcmModule
+  -- directly so we know our AAD framing matches what the reader needs.
+  -- Per parquet-format Encryption.md §5.1 each module on the wire is
+  -- prefixed with a 4-byte little-endian length, so the framing is
+  -- '<len4 || nonce(12) || ct || tag(16)>' for header followed by
+  -- '<len4 || nonce(12) || ct || tag(16)>' for body.
+  let (rawHdr, rawBody) = encodeColumnDataPageParts encVals
+  encryptPageBytes (ce Enc.AesGcmV1) Enc.ModuleDataPage 0 0 rawHdr rawBody >>= \case
+    Left e -> failTest ("encryptPageBytes: " ++ e)
+    Right encBytes -> do
+      let aadHdr = Enc.buildAad BS.empty
+                     (Enc.buildAadSuffix (BSC.pack "fileid01")
+                        Enc.ModuleDataPageHeader 0 0 0)
+          aadBody = Enc.buildAad BS.empty
+                     (Enc.buildAadSuffix (BSC.pack "fileid01")
+                        Enc.ModuleDataPage 0 0 0)
+      case Enc.readFramedModule encBytes 0 of
+        Left e -> failTest ("read framed page header: " ++ e)
+        Right (encHdr, after1) -> do
+          case Enc.decryptGcmModule encKey aadHdr encHdr of
+            Right plain -> expect "encrypted page header round-trips"
+                                  (readPageHeaderAt plain 0 == fmap (\(h, _) -> (h {phCompressedPageSize = Just (fromIntegral (BS.length rawBody + 32))}, BS.length plain)) (readPageHeaderAt rawHdr 0))
+            Left e -> failTest ("decrypt page header: " ++ e)
+          case Enc.readFramedModule encBytes after1 of
+            Left e -> failTest ("read framed page body: " ++ e)
+            Right (encBody, _) ->
+              case Enc.decryptGcmModule encKey aadBody encBody of
+                Right plain -> expect "encrypted page body round-trips"
+                                      (plain == rawBody)
+                Left e -> failTest ("decrypt page body: " ++ e)
+      -- Tampering with one byte of the body must invalidate the GCM tag.
+      let tampered = BS.snoc (BS.init encBytes) (BS.last encBytes `xor` 1)
+      case Enc.readFramedModule tampered 0 of
+        Left _ -> expect "tampered framing rejected" True
+        Right (encHdr, after1) -> do
+          case Enc.decryptGcmModule encKey aadHdr encHdr of
+            Left _  -> expect "tampered header fails GCM auth" True
+            Right _ ->
+              case Enc.readFramedModule tampered after1 of
+                Left _ -> expect "tampered body framing rejected" True
+                Right (encBody, _) ->
+                  case Enc.decryptGcmModule encKey aadBody encBody of
+                    Right _ -> failTest "tampered ciphertext decrypted (BAD)"
+                    Left _  -> expect "tampered body fails GCM auth" True
+
+  -- V2 keeps levels uncompressed, but encrypts them with the values.
+  case encodeOptionalColumnPageV2Parts Uncompressed (OptInt32 (V.fromList [Just 7, Nothing, Just 9])) of
+    Left e -> failTest e
+    Right (headerV2, repV2, defV2, valuesV2) -> do
+      expect "nullable V2 encryption test has actual definition levels" (not (BS.null defV2))
+      mapM_ (\alg -> do
+        result <- encryptPageBytesV2 (ce alg) 3 2 headerV2 repV2 defV2 valuesV2
+        bytes <- either failTest pure result
+        (encryptedHeader, afterHeader) <- either failTest pure (Enc.readFramedModule bytes 0)
+        let aadHeader = Enc.buildAadSuffix "fileid01" Enc.ModuleDataPageHeader 3 0 2
+            aadBody = Enc.buildAadSuffix "fileid01" Enc.ModuleDataPage 3 0 2
+        decryptedHeader <- either failTest pure (Enc.decryptGcmModule encKey aadHeader encryptedHeader)
+        (parsedHeader, _) <- either failTest pure (readPageHeaderAt decryptedHeader 0)
+        (originalHeader, _) <- either failTest pure (readPageHeaderAt headerV2 0)
+        (encryptedBody, afterBody) <- either failTest pure (Enc.readFramedModule bytes afterHeader)
+        expect "V2 header records encrypted body size"
+          (parsedHeader == originalHeader {phCompressedPageSize = Just (fromIntegral (afterBody - afterHeader))})
+        expect "V2 has exactly two encrypted modules" (afterBody == BS.length bytes)
+        let decoded = case alg of
+              Enc.AesGcmV1 -> Enc.decryptGcmModule encKey aadBody encryptedBody
+              Enc.AesGcmCtrV1 -> Enc.decryptCtrModule encKey encryptedBody
+        expect "V2 body encrypts levels together with all values"
+          (decoded == Right (BS.concat [repV2, defV2, valuesV2])))
+        [Enc.AesGcmV1, Enc.AesGcmCtrV1]
+
+  -- Encrypted aux modules: bloom filter / offset index / column
+  -- index payloads are wrapped as separate GCM modules under their
+  -- spec-assigned ModuleType AAD when caEncryption is set on the
+  -- column. We exercise this by feeding the resulting bytes back
+  -- through Enc.decryptGcmModule under the matching AAD.
+  do
+    let bfx = sbbfInsertHash 0xdeadbeef (newSbbf (optimalNumBytes 1024 0.01))
+        oix = OffsetIndex
+                { oiPageLocations = V.singleton (PageLocation 0 16 0)
+                , oiUnencodedByteArrayDataBytes = Nothing
+                }
+        cix = ColumnIndex
+                { ciNanCounts = Nothing
+                , ciNullPages = V.singleton False
+                , ciMinValues = V.singleton (BS.pack [0x01, 0, 0, 0])
+                , ciMaxValues = V.singleton (BS.pack [0x04, 0, 0, 0])
+                , ciBoundaryOrder = OrderAscending
+                , ciNullCounts = Nothing
+                , ciRepetitionLevelHistograms = Nothing
+                , ciDefinitionLevelHistograms = Nothing
+                }
+        rawBloom = encodeBloomFilter bfx
+        rawOff   = encodeOffsetIndex oix
+        rawCol   = encodeColumnIndex cix
+        encOf mt = encryptAuxModule
+                    (Just (ce Enc.AesGcmV1)) mt 0
+        aadOf mt = Enc.buildAad BS.empty
+                    (Enc.buildAadSuffix (BSC.pack "fileid01") mt 0 0 0)
+    let unframed mt raw = do
+          encoded <- encOf mt raw >>= either failTest pure
+          fst <$> either failTest pure (Enc.readFramedModule encoded 0)
+    bloomModule <- unframed Enc.ModuleBloomFilterBitset rawBloom
+    offsetModule <- unframed Enc.ModuleOffsetIndex rawOff
+    columnModule <- unframed Enc.ModuleColumnIndex rawCol
+    case Enc.decryptGcmModule encKey
+           (aadOf Enc.ModuleBloomFilterBitset)
+           bloomModule of
+      Right p -> expect "encrypted bloom filter module round-trips"
+                        (p == rawBloom)
+      Left e  -> failTest ("decrypt bloom filter module: " ++ e)
+    case Enc.decryptGcmModule encKey
+           (aadOf Enc.ModuleOffsetIndex)
+           offsetModule of
+      Right p -> expect "encrypted offset-index module round-trips"
+                        (p == rawOff)
+      Left e  -> failTest ("decrypt offset-index module: " ++ e)
+    case Enc.decryptGcmModule encKey
+           (aadOf Enc.ModuleColumnIndex)
+           columnModule of
+      Right p -> expect "encrypted column-index module round-trips"
+                        (p == rawCol)
+      Left e  -> failTest ("decrypt column-index module: " ++ e)
+    -- A whole-file build with caEncryption + bloom/offset/column
+    -- index aux must produce a different file from the same build
+    -- without the encryption (i.e. the auxes really got encrypted).
+    let auxEnc = ColumnAux False (Just bfx) (Just oix) (Just cix)
+                           Uncompressed PageV1 (Just (ce Enc.AesGcmV1))
+        auxPlain = ColumnAux False (Just bfx) (Just oix) (Just cix)
+                             Uncompressed PageV1 Nothing
+        encFileEnc = buildParquetFileWithIndexEncryptedFooter encFooter encSchema
+                       (V.singleton (V.singleton encVals))
+                       (V.singleton (V.singleton auxEnc))
+        encFilePlain = buildParquetFileWithIndex encSchema
+                       (V.singleton (V.singleton encVals))
+                       (V.singleton (V.singleton auxPlain))
+    encryptedAuxFile <- encFileEnc >>= either failTest pure
+    expect "aux-encrypted file diverges from plaintext-aux file"
+      (encryptedAuxFile /= encFilePlain)
+
+  -- Encrypted-footer mode: footer is a single GCM module under
+  -- ModuleFooter AAD, file ends with PARE magic instead of PAR1, and
+  -- decrypting recovers the original plaintext FileMetadata thrift.
+  do
+    let footerEnc = FooterEncryption
+                      { feKey         = encKey
+                      , feFileId      = BSC.pack "fileid01"
+                      , feAadPrefix   = BS.empty
+                      , feKeyMetadata = BSC.pack "kid:test"
+                      }
+        makeEncFooterFile = buildParquetFileWithIndexEncryptedFooter footerEnc
+                    encSchema
+                    (V.singleton (V.singleton encVals))
+                    (V.singleton (V.singleton emptyColumnAux))
+        plainFile = buildParquetFileWithIndex encSchema
+                      (V.singleton (V.singleton encVals))
+                      (V.singleton (V.singleton emptyColumnAux))
+    encFooterFile <- makeEncFooterFile >>= either failTest pure
+    expect "encrypted-footer file is non-empty"
+      (BS.length encFooterFile > 0)
+    expect "encrypted-footer file ends with PARE magic"
+      (BS.takeEnd 4 encFooterFile == BSC.pack "PARE")
+    expect "plaintext-footer file ends with PAR1 magic"
+      (BS.takeEnd 4 plainFile == BSC.pack "PAR1")
+    expect "encrypted-footer file diverges from plaintext-footer"
+      (encFooterFile /= plainFile)
+    -- Use the public encrypted-reader API to round-trip via the
+    -- ModuleFooter AAD. Per parquet-format §5.4 the bytes between
+    -- the leading PAR1 magic and the trailing PARE magic are
+    -- '<FileCryptoMetaData thrift> <encrypted footer module>',
+    -- and the writer + reader handle the layout symmetrically.
+    let fdec = Parquet.Read.FooterDecryption
+                 { Parquet.Read.fdKey       = encKey
+                 , Parquet.Read.fdFileId    = BSC.pack "fileid01"
+                 , Parquet.Read.fdAadPrefix = BS.empty
+                 }
+    case Parquet.Read.loadParquetFileEncrypted fdec encFooterFile of
+      Left e -> failTest ("loadParquetFileEncrypted: " ++ e)
+      Right pf' -> do
+        let fmDecrypted = Parquet.Read.pfFooter pf'
+        expect "encrypted-footer round-trips through reader"
+          (V.length (fmSchema fmDecrypted) > 0)
+        expect "encrypted-footer reader recovers row-group count"
+          (V.length (fmRowGroups fmDecrypted) == 1)
+    -- Wrong key must fail GCM auth.
+    let wrongFd = fdec { Parquet.Read.fdKey = BS.replicate 16 0 }
+    case Parquet.Read.loadParquetFileEncrypted wrongFd encFooterFile of
+      Left _  -> expect "wrong key rejected by GCM auth" True
+      Right _ -> failTest "encrypted footer decrypted with wrong key (BAD)"
+
+  -- Whole-file V2 + encryption: ColumnAux carries both PageV2 and
+  -- ColumnEncryption, so buildParquetFileWithIndex must dispatch
+  -- through encryptPageBytesV2 internally.
+  let v2EncAux alg = ColumnAux False Nothing Nothing Nothing Uncompressed PageV2 (Just (ce alg))
+      v2EncFile alg = buildParquetFileWithIndexEncryptedFooter encFooter encSchema
+                        (V.singleton (V.singleton encVals))
+                        (V.singleton (V.singleton (v2EncAux alg)))
+  v2GcmFile <- v2EncFile Enc.AesGcmV1 >>= either failTest pure
+  v2CtrFile <- v2EncFile Enc.AesGcmCtrV1 >>= either failTest pure
+  expect "V2 + AES-GCM-V1 whole-file write is non-empty"
+    (BS.length v2GcmFile > 0)
+  expect "V2 + AES-GCM-CTR-V1 whole-file write is non-empty"
+    (BS.length v2CtrFile > 0)
+  expect "V2 + encryption differs from V2 plaintext file"
+    (v2GcmFile
+       /= buildParquetFileWithIndex encSchema
+            (V.singleton (V.singleton encVals))
+            (V.singleton (V.singleton
+              (ColumnAux False Nothing Nothing Nothing Uncompressed PageV2 Nothing))))
+
+  -- Optional column page: definition levels + present-only PLAIN values.
+  let optCol = OptInt32 (V.fromList [Just 1, Nothing, Just 3, Nothing, Just 5])
+      pageBs = encodeOptionalColumnPage optCol
+  expect "optional-column-page produces a non-empty body"
+    (BS.length pageBs > 4)
+  expect "optionalColumnLength counts all rows"
+    (optionalColumnLength optCol == 5)
+  expect "optionalColumnNullCount counts nulls"
+    (optionalColumnNullCount optCol == 2)
+
+  -- Dictionary encoding: build a dictionary, encode dictionary + data
+  -- pages, and confirm the dictionary captured the unique values.
+  let dictInput = ColByteArray (V.fromList
+        [BSC.pack "alpha", BSC.pack "beta", BSC.pack "alpha"
+        ,BSC.pack "gamma", BSC.pack "beta", BSC.pack "alpha"])
+      dict = buildDictionary dictInput
+      dictPage = encodeDictPage dict
+      dataPage = encodeDictDataPage dict
+  expect "dictionary unique count == 3"
+    (columnDataLength (dictUniques dict) == 3)
+  expect "dictionary index vector has one entry per row"
+    (VP.length (dictIndices dict) == 6)
+  expect "dictionary page header is non-empty"
+    (BS.length dictPage > 4)
+  expect "dictionary data page is non-empty"
+    (BS.length dataPage > 4)
+
+  -- NullPagesBitmap: pack a Vector Bool into an LSB-first bitmap,
+  -- count null pages via SIMD popcount, list non-null page indices.
+  let nullPages = V.fromList [True, False, True, False, False, True, True, False, True]
+      packed = NPB.packNullPages nullPages
+  expect "nullPagesBitmap round-trip"
+    (NPB.unpackNullPages (V.length nullPages) packed == nullPages)
+  expect "nullPagesBitmap popcount"
+    (NPB.nullPageCount packed == 5)
+  expect "nullPagesBitmap nonNullPages == [1,3,4,7]"
+    (V.toList (NPB.nonNullPages (V.length nullPages) packed) == [1, 3, 4, 7])
+
+  -- DELTA_BINARY_PACKED writer round-trips through the reader for a few
+  -- shapes (constant deltas, mixed deltas, negative deltas, single value).
+  let testCases =
+        [ ("ascending integers", VP.fromList [1, 2, 3, 4, 5, 6, 7, 8, 9, 10 :: Int64])
+        , ("constant",           VP.fromList (replicate 12 (42 :: Int64)))
+        , ("descending negatives", VP.fromList [10, 5, 0, -5, -10, -50, -1000 :: Int64])
+        , ("singleton",          VP.fromList [12345 :: Int64])
+        , ("empty",              VP.empty :: VP.Vector Int64)
+        , ("128 mixed",          VP.fromList [let i64 = fromIntegral i :: Int64 in i64 * 7 - i64 `mod` 13 | i <- [(0 :: Int) .. 127]])
+        ]
+  flip mapM_ testCases $ \(name, xs) ->
+    case decodeDeltaBinaryPackedInt64 (VP.length xs) (encodeDeltaBinaryPackedInt64 xs) of
+      Right out ->
+        expect ("DELTA_BINARY_PACKED round-trip: " ++ name)
+          (VP.toList out == VP.toList xs)
+      Left e -> failTest ("DELTA_BINARY_PACKED " ++ name ++ ": " ++ e)
+
+  -- Modular encryption: round-trip plaintext through encrypt/decrypt for
+  -- both AES-GCM and AES-CTR, and verify GCM rejects a tampered tag.
+  let key128 = BS.replicate 16 0x42
+      aad    = Enc.buildAad "" (Enc.buildAadSuffix "fileid01" Enc.ModuleColumnMetaData 0 0 0)
+      plain  = BSC.pack "Hello, Iceberg + Parquet!"
+  drg0 <- RNG.drgNew
+  let (eGcm, _) = RNG.withDRG drg0 (Enc.encryptModule key128 aad plain)
+  case eGcm of
+    Left e -> failTest ("GCM encrypt: " ++ e)
+    Right ct -> do
+      expect "GCM round-trip"
+        (Enc.decryptModule key128 aad ct == Right plain)
+      expect "GCM rejects tampered ciphertext"
+        (case Enc.decryptModule key128 aad (BS.snoc (BS.init ct) (BS.last ct `xor` 1)) of
+            Right _ -> False
+            Left _  -> True)
+  drg1 <- RNG.drgNew
+  let (eCtr, _) = RNG.withDRG drg1 (Enc.encryptModuleCtr key128 plain)
+  case eCtr of
+    Left e -> failTest ("CTR encrypt: " ++ e)
+    Right ct ->
+      expect "CTR round-trip"
+        (Enc.decryptModuleCtr key128 ct == Right plain)
+  -- Independent spec bytes: footer has no ordinals; dictionary/index
+  -- modules omit page ordinal; file identifiers are not padded/truncated.
+  expect "footer AAD preserves file identifier and omits ordinals"
+    (Enc.buildAadSuffix "abcdefghijk" Enc.ModuleFooter 7 8 9 == "abcdefghijk" <> BS.singleton 0)
+  expect "column metadata AAD omits page ordinal"
+    (Enc.buildAadSuffix "id" Enc.ModuleColumnMetaData 0x102 0x304 9 == "id" <> BS.pack [1, 2, 1, 4, 3])
+  expect "data AAD includes little-endian page ordinal"
+    (Enc.buildAadSuffix "id" Enc.ModuleDataPage 0x102 0x304 0x506 == "id" <> BS.pack [2, 2, 1, 4, 3, 6, 5])
+  expect "CTR starts at counter one (independent AES-128 known answer)"
+    (Enc.decryptModuleCtr (BS.replicate 16 0)
+      (BS.replicate 12 0 <> BS.pack [0x58,0xe2,0xfc,0xce,0xfa,0x7e,0x30,0x61,0x36,0x7f,0x1d,0x57,0xa4,0xe7,0x45,0x5a])
+      == Right (BS.replicate 16 0))
+
+  -- BYTE_STREAM_SPLIT round-trips for FLOAT and DOUBLE.
+  let bssFloats  = VP.fromList [1.5, -2.25, 3.14159, 0, 1e9, -1e-9 :: Float]
+      bssDoubles = VP.fromList [1.5, -2.25, 3.14159, 0, 1e9, -1e-9 :: Double]
+      bssFloatBs  = encodeByteStreamSplitFloat bssFloats
+      bssDoubleBs = encodeByteStreamSplitDouble bssDoubles
+  expect "BYTE_STREAM_SPLIT FLOAT byte length == 4 * n"
+    (BS.length bssFloatBs == 4 * VP.length bssFloats)
+  expect "BYTE_STREAM_SPLIT DOUBLE byte length == 8 * n"
+    (BS.length bssDoubleBs == 8 * VP.length bssDoubles)
+  case decodeByteStreamSplitFloat (VP.length bssFloats) bssFloatBs of
+    Right xs -> expect "BYTE_STREAM_SPLIT FLOAT round-trip" (xs == bssFloats)
+    Left  e  -> failTest ("BYTE_STREAM_SPLIT FLOAT decode: " ++ e)
+  case decodeByteStreamSplitDouble (VP.length bssDoubles) bssDoubleBs of
+    Right xs -> expect "BYTE_STREAM_SPLIT DOUBLE round-trip" (xs == bssDoubles)
+    Left  e  -> failTest ("BYTE_STREAM_SPLIT DOUBLE decode: " ++ e)
+
+  -- Compression codec round-trips. Legacy LZ4 remains read-only;
+  -- LZO is always available without an external compression library.
+  case compressPageBytes LZ4 "anything" of
+    Left _  -> expect "LZ4 (codec 5) is refused by the compressor" True
+    Right _ -> failTest "Parquet.Compress: LZ4 compression should fail"
+  let lzoInput = BS.concat (replicate 256 "raw LZO1X page data ")
+  case compressPageBytes LZO lzoInput of
+    Left err -> failTest ("Parquet.Compress: LZO compression failed: " ++ err)
+    Right compressed -> do
+      expect "LZO compresses the repetitive fixture" (BS.length compressed < BS.length lzoInput)
+      expect "LZO raw page round-trip" (Parquet.Read.decompressChunk LZO compressed == Right lzoInput)
+  expect "LZO empty raw page uses the canonical end marker"
+    (compressPageBytes LZO BS.empty == Right (BS.pack [17,0,0]))
+#ifdef HAVE_BROTLI
+  -- A mid-sized input so Brotli has something to chew on; the original
+  -- plaintext must be recovered after a round-trip through the reader.
+  let brotliInput = BS.concat (replicate 256 "the quick brown fox jumps over the lazy dog ")
+  case compressPageBytes Brotli brotliInput of
+    Left e  -> failTest ("Parquet.Compress: Brotli compression failed: " ++ e)
+    Right compressed -> do
+      expect "Brotli shrinks the repetitive fixture"
+        (BS.length compressed < BS.length brotliInput)
+      case Parquet.Read.decompressChunk Brotli compressed of
+        Left e -> failTest ("Parquet.Read: Brotli decompression failed: " ++ e)
+        Right restored ->
+          expect "Brotli round-trip preserves the input"
+            (restored == brotliInput)
+#else
+  -- Without -fbrotli the writer must surface a clear missing-codec error
+  -- rather than silently falling through to uncompressed.
+  case compressPageBytes Brotli "anything" of
+    Left _  -> expect "Brotli reports the -fbrotli requirement" True
+    Right _ -> failTest "Parquet.Compress: Brotli must fail without -fbrotli"
+#endif
+
+  -- DELTA_LENGTH_BYTE_ARRAY round-trip (encoder <-> decoder).
+  let dlbaInputs =
+        [ V.empty
+        , V.singleton (BSC.pack "alpha")
+        , V.fromList (map BSC.pack ["", "a", "ab", "abc", "abcd"])
+        , V.fromList (map BSC.pack
+            ["one", "tw", "three", "", "five-five-five", "6"])
+        ]
+  mapM_
+    (\inp ->
+       let encoded = encodeDeltaLengthByteArray inp
+        in case decodeDeltaLengthByteArray (V.length inp) encoded of
+             Right xs -> expect "DELTA_LENGTH_BYTE_ARRAY round-trip" (xs == inp)
+             Left  e  -> failTest ("DELTA_LENGTH_BYTE_ARRAY decode: " ++ e))
+    dlbaInputs
+
+  -- DELTA_BYTE_ARRAY round-trip with shared prefixes (front compression).
+  let dbaInputs =
+        [ V.empty
+        , V.singleton (BSC.pack "abc")
+        , V.fromList (map BSC.pack ["", "a", "ab", "abc", "abcd", "abcde"])
+        , V.fromList (map BSC.pack
+            [ "iceberg/ns/tableA"
+            , "iceberg/ns/tableB"
+            , "iceberg/ns/tableC"
+            , "iceberg/ns/zzz/last"
+            , "other/ns/tableA"
+            ])
+        ]
+  mapM_
+    (\inp ->
+       let encoded = encodeDeltaByteArray inp
+        in case decodeDeltaByteArray (V.length inp) encoded of
+             Right xs -> expect "DELTA_BYTE_ARRAY round-trip" (xs == inp)
+             Left  e  -> failTest ("DELTA_BYTE_ARRAY decode: " ++ e))
+    dbaInputs
+
+  -- Golden parquet fixtures from pyarrow (only when present).
+  goldenExist <- and <$> mapM doesFileExist
+    [ "test/fixtures/simple_int.parquet"
+    , "test/fixtures/mixed_types.parquet"
+    , "test/fixtures/bloom_and_index.parquet"
+    ]
+  if goldenExist
+    then do
+      goldenSimpleInt
+      goldenMixedTypes
+      goldenBloomIndex
+      putStrLn "OK: pyarrow golden round-trip"
+    else putStrLn "SKIP: pyarrow golden fixtures not present"
+
+  -- Validate the nested optional-list-of-optional-int writer against
+  -- pyarrow if pyarrow is available on PATH; otherwise skip.
+  pyarrowOk <- pyarrowAvailable
+  if pyarrowOk
+    then do
+      validateNestedAgainstPyarrow
+      validateListStructAgainstPyarrow
+      validateListListAgainstPyarrow
+      validateMapAgainstPyarrow
+      -- Variant + Parquet pyarrow round-trip lives in
+      -- wireform-iceberg's test suite (Iceberg.Variant imports
+      -- wireform-iceberg, which already depends on wireform-parquet).
+    else putStrLn "SKIP: pyarrow not available, nested cross-language checks skipped"
+
+  -- Arrow ↔ Parquet bridge round-trip.
+  arrowParquetBridge
+  arrowParquetInputValidation
+  arrowParquetIntegerTypes
+  arrowParquetProjectionTypes
+  arrowParquetTemporalRegression
+  deltaWideIntegerRegression
+  dataPageV2CompressionRegression
+  malformedCountRegression
+  pageChecksumRegression
+  writerOptionsRegression
+  decimalStatisticsRegression
+  legacyDictionarySizeRegression
+  wideTimestampStorageRegression
+  hybridBitWidthRegression
+  legacyLz4Regression
+  floatingStatisticsRegression
+  encryptionFailureRegression
+  plainByteArrayRegression
+  plainPrimitiveRegression
+  plainWriterRegression
+  plainArrowReadRegression
+
+  -- Predicate evaluator unit tests
+  predicateRowGroupSkipping
+  predicatePageSkipping
+  Selection.run
+  AlpRegression.run
+  WriterBounds.run
+  statisticsOrderingRegression
+  predicateBloomSkipping
+
+  -- LogicalType round-trip
+  logicalTypeRoundTrip
+  logicalParameterRegression
+  fixedDecimalMetadataRegression
+  emptyColumnChunkRegression
+
+  -- Generic per-page dispatch (DELTA, BYTE_STREAM_SPLIT, V2)
+  genericPageDispatch
+  manyPageRegression
+  nestedReadRegression
+  legacyLevelsRegression
+  jsonExtensionRegression
+
+  -- Property-style round-trips for every encoding family
+  encodingRoundTripProperties
+
+  -- Parquet.Aggregate: count(*) / count(col) / min / max
+  Aggregate.run
+
+  -- Auto-populated bloom filters via the high-level writer
+  highLevelBloomFilters
+
+  putStrLn "All Parquet page-index / bloom-filter / statistics tests passed."
+
+-- ============================================================
+-- Parquet.Predicate
+-- ============================================================
+
+-- The mixed bridge used zipWithM, silently truncating mismatched batches;
+-- the dense bridge also compacted nulls without writing definition levels.
+arrowParquetInputValidation :: IO ()
+arrowParquetInputValidation = do
+  let field = AT.Field "x" True (AT.AInt 32 True) V.empty Nothing V.empty
+      schema = AT.Schema (V.singleton field) AT.Little V.empty V.empty
+      col = AC.primColumn AC.PInt32 (VS.fromList [1, 2 :: Int32])
+      short = AC.primColumn AC.PInt32 (VS.singleton (1 :: Int32))
+      nullable = AC.fromMaybes AC.PInt32 (V.fromList [Just 1, Nothing])
+      twoFields = schema {AT.arrowFields = V.fromList [field, field {AT.fieldName = "y"}]}
+      checkBad label sch cols = do
+        expect (label ++ " (dense)") (isLeft (PArrow.arrowToParquet sch [cols]))
+        expect (label ++ " (mixed)") (isLeft (PArrow.arrowToParquetMixed sch [cols]))
+  checkBad "bridge rejects missing columns" schema V.empty
+  checkBad "bridge rejects extra columns" schema (V.fromList [col, col])
+  checkBad "bridge rejects unequal row counts" twoFields (V.fromList [col, short])
+  checkBad "bridge rejects mismatched physical types" schema (V.singleton (AC.fromTexts (V.fromList ["a", "b"])))
+  checkBad "bridge rejects nulls under a required field" (schema {AT.arrowFields = V.singleton (field {AT.fieldNullable = False})}) (V.singleton nullable)
+  expect "mixed bridge validates later batches"
+    (isLeft (PArrow.arrowToParquetMixed schema [V.singleton col, V.empty]))
+  expect "dense bridge rejects null compaction" (isLeft (PArrow.arrowToParquet schema [V.singleton nullable]))
+  case PArrow.arrowToParquetMixed schema [V.singleton nullable] of
+    Left e -> failTest ("mixed nullable bridge: " ++ e)
+    Right (ps, groups) -> do
+      let bytes = PHL.encodeParquetMixed PHL.defaultWriteOptions ps groups
+      case PHL.decodeParquet PHL.defaultReadOptions bytes of
+        Left e -> failTest ("mixed nullable footer: " ++ e)
+        Right pf -> expect "mixed bridge preserves null rows"
+          (PArrow.parquetRowGroupToArrow schema pf 0 == Right (V.singleton nullable))
+
+
+arrowParquetTemporalRegression :: IO ()
+arrowParquetTemporalRegression = do
+  let field typ nullable = AT.Field "x" nullable typ V.empty Nothing V.empty
+      schema fld = AT.Schema (V.singleton fld) AT.Little V.empty V.empty
+      check typ input expected = do
+        let fld = field typ False
+        case PArrow.arrowToParquet (schema fld) [V.singleton input] of
+          Left err -> failTest err
+          Right (ps, groups) -> case loadParquetFile (PHL.encodeParquet PHL.defaultWriteOptions ps groups) of
+            Left err -> failTest err
+            Right pf -> expect ("temporal payload and annotation agree: " ++ show typ)
+              (PArrow.parquetRowGroupToArrow (PArrow.parquetFileArrowSchema pf) pf 0
+                == Right (V.singleton expected))
+      rejects typ input = do
+        let dense = PArrow.arrowToParquet (schema (field typ False)) [V.singleton input]
+            mixed = PArrow.arrowToParquetMixed (schema (field typ True)) [V.singleton input]
+        expect ("dense temporal writer rejects invalid values/type: " ++ show typ) (isLeft dense)
+        expect ("nullable temporal writer rejects invalid values/type: " ++ show typ) (isLeft mixed)
+  check (AT.ADate AT.DateMillisecond)
+    (AC.primColumn AC.PDate64 (VS.fromList [-86400000, 0, 86400000]))
+    (AC.primColumn AC.PDate32 (VS.fromList [-1, 0, 1]))
+  check (AT.ATime AT.Second 32)
+    (AC.primColumn AC.PTime32 (VS.fromList [0, 1, 86399]))
+    (AC.primColumn AC.PTime32 (VS.fromList [0, 1000, 86399000]))
+  check (AT.ATimestamp AT.Second Nothing)
+    (AC.primColumn AC.PTimestamp (VS.fromList [-2, 0, 1700000000]))
+    (AC.primColumn AC.PTimestamp (VS.fromList [-2000, 0, 1700000000000]))
+  let nanos = AC.primColumn AC.PTime64 (VS.fromList [0, 1, 86399999999999])
+  check (AT.ATime AT.Nanosecond 64) nanos nanos
+  rejects (AT.ADate AT.DateMillisecond) (AC.primColumn AC.PDate64 (VS.singleton 1))
+  rejects (AT.ADate AT.DateMillisecond) (AC.primColumn AC.PDate64 (VS.singleton maxBound))
+  rejects (AT.ATime AT.Second 32) (AC.primColumn AC.PTime32 (VS.singleton 86400))
+  rejects (AT.ATime AT.Millisecond 32) (AC.primColumn AC.PTime32 (VS.singleton (-1)))
+  rejects (AT.ATimestamp AT.Second Nothing) (AC.primColumn AC.PTimestamp (VS.singleton maxBound))
+  rejects (AT.ATimestamp AT.Second Nothing) (AC.primColumn AC.PTimestamp (VS.singleton minBound))
+  rejects (AT.ADuration AT.Microsecond) (AC.primColumn AC.PDuration (VS.singleton 1))
+  let fld = field (AT.ATimestamp AT.Second Nothing) True
+      values = AC.fromMaybes AC.PTimestamp (V.fromList [Just (-1), Nothing, Just 2])
+  case PArrow.arrowToParquetMixed (schema fld) [V.singleton values] of
+    Left err -> failTest err
+    Right (ps, groups) -> case loadParquetFile (PHL.encodeParquetMixed PHL.defaultWriteOptions ps groups) of
+      Left err -> failTest err
+      Right pf -> expect "nullable timestamp seconds scale while preserving nulls"
+        (PArrow.parquetRowGroupToArrow (PArrow.parquetFileArrowSchema pf) pf 0
+          == Right (V.singleton (AC.fromMaybes AC.PTimestamp (V.fromList [Just (-1000), Nothing, Just 2000]))))
+
+
+plainArrowReadRegression :: IO ()
+plainArrowReadRegression = do
+  let field = AT.Field "x" False AT.AUtf8 V.empty Nothing V.empty
+      schema = AT.Schema (V.fromList
+        [ field
+        , AT.Field "i32" False (AT.AInt 32 True) V.empty Nothing V.empty
+        , AT.Field "i64" False (AT.AInt 64 True) V.empty Nothing V.empty
+        , AT.Field "f64" False (AT.AFloatingPoint AT.DoublePrecision) V.empty Nothing V.empty
+        , AT.Field "bool" False AT.ABool V.empty Nothing V.empty
+        ]) AT.Little V.empty V.empty
+      values = AC.fromTexts (V.fromList ["", "lambda λ", "emoji 😀", "\NUL"])
+      batch = V.fromList
+        [ values
+        , AC.primColumn AC.PInt32 (VS.fromList [-1, 0, maxBound, minBound])
+        , AC.primColumn AC.PInt64 (VS.fromList [minBound, maxBound, 1, 0])
+        , AC.primColumn AC.PDouble (VS.fromList [1.5, -2.5, 0, -0.0])
+        , AC.fromBools (V.fromList [True, False, True, True])
+        ]
+  case PArrow.arrowToParquet schema [batch] of
+    Left e -> failTest e
+    Right (ps, groups) ->
+      mapM_ (\version -> mapM_ (\codec -> do
+        let bytes = PHL.encodeParquet
+              (PHL.defaultWriteOptions {PHL.writeCompression = codec, PHL.writePageVersion = version}) ps groups
+        case loadParquetFile bytes of
+          Left e -> failTest e
+          Right pf -> expect ("direct Arrow string buffers " ++ show version ++ " " ++ show codec)
+            (PArrow.parquetRowGroupToArrow schema pf 0 == Right batch))
+        [Uncompressed, Snappy, ZSTD, LZ4Raw]) [PageV1, PageV2]
+  let bad = BS.pack [0xc3]
+      ps = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "x" (Just Required) (Just PTByteArray) Nothing (Just CTUtf8) (Just LTString) Nothing Nothing
+        ]
+      badRequired = buildParquetFile ps (V.singleton (V.singleton (ColByteArray (V.singleton bad))))
+      checkInvalid label bytes = case loadParquetFile bytes of
+        Left e -> failTest e
+        Right pf -> expect label
+          (isLeft (PArrow.parquetRowGroupToArrow (PArrow.parquetFileArrowSchema pf) pf 0))
+  checkInvalid "direct Arrow string reader rejects invalid UTF-8" badRequired
+  let optional = ps V.// [(1, (ps V.! 1) {seRepetition = Just Optional})]
+      badOptional = PHL.encodeParquetMixed PHL.defaultWriteOptions optional
+        [V.singleton (PHL.PCOptional (OptByteArray (V.fromList [Just bad, Nothing])))]
+  checkInvalid "generic Arrow string reader rejects invalid UTF-8" badOptional
+
+
+plainWriterRegression :: IO ()
+plainWriterRegression = do
+  let payload = snd . encodeColumnDataPageParts
+      ints = VP.slice 1 2 (VP.fromList [999, 1, -1, 999 :: Int32])
+      longs = VP.slice 1 2 (VP.fromList [999, minBound, maxBound, 999 :: Int64])
+      floats = VP.slice 1 2 (VP.fromList [0, 1.5, castWord32ToFloat 0x7fa00001, 0])
+  expect "PLAIN Int32 writes only the logical vector slice"
+    (payload (ColInt32 ints) == BS.pack [1, 0, 0, 0, 255, 255, 255, 255])
+  expect "PLAIN Int64 preserves little-endian extreme values in a slice"
+    (payload (ColInt64 longs) == BS.pack (replicate 7 0 ++ [128] ++ replicate 7 255 ++ [127]))
+  expect "PLAIN Float preserves IEEE payload bits in a slice"
+    (payload (ColFloat floats) == BS.pack [0, 0, 192, 63, 1, 0, 160, 127])
+  mapM_ (\n -> do
+    let values = V.generate n (\i -> i `rem` 3 == 0)
+    expect ("PLAIN Bool tail length " ++ show n)
+      (Parquet.Read.decodePlainBool n (payload (ColBool values)) == Right values)) [0 .. 65]
+  let schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "x" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+        ]
+      bytes = PHL.encodeParquet
+        (PHL.defaultWriteOptions {PHL.writeCompression = Uncompressed, PHL.writePageVersion = PageV2})
+        schema [V.singleton (ColInt32 ints)]
+  case loadParquetFile bytes of
+    Left e -> failTest e
+    Right pf -> do
+      let chunk = rgColumns (fmRowGroups (pfFooter pf) V.! 0) V.! 0
+      expect "V2 uncompressed page records equal compressed/uncompressed sizes"
+        (maybe False (\m -> cmCodec m == Uncompressed
+                        && cmTotalUncompressedSize m == cmTotalCompressedSize m) (ccMetadata chunk))
+      expect "V2 uncompressed page remains readable"
+        (PArrow.parquetRowGroupToArrow (PArrow.parquetFileArrowSchema pf) pf 0
+          == Right (V.singleton (AC.primColumn AC.PInt32 (VS.fromList [1, -1]))))
+
+
+plainByteArrayRegression :: IO ()
+plainByteArrayRegression = do
+  expect "BYTE_ARRAY rejects a negative count"
+    (isLeft (Parquet.Read.decodePlainByteArray (-1) BS.empty))
+  expect "BYTE_ARRAY rejects an impossible count before allocating"
+    (isLeft (Parquet.Read.decodePlainByteArray maxBound (BS.replicate 4 0)))
+  expect "BYTE_ARRAY rejects a truncated length"
+    (isLeft (Parquet.Read.decodePlainByteArray 1 (BS.pack [0, 0, 0])))
+  expect "BYTE_ARRAY rejects a truncated payload"
+    (isLeft (Parquet.Read.decodePlainByteArray 1 (BS.pack [2, 0, 0, 0, 1])))
+  let values = V.generate 4096 (\i -> BS.replicate (i `rem` 17) (fromIntegral i))
+      (_, body) = encodeColumnDataPageParts (ColByteArray values)
+  expect "BYTE_ARRAY preserves all values in a large page"
+    (Parquet.Read.decodePlainByteArray (V.length values) body == Right values)
+  ok <- H.check $ H.property $ do
+    input <- H.forAll (Gen.list (Range.linear 0 200) (Gen.bytes (Range.linear 0 128)))
+    let columns = V.fromList input
+        (_, payload) = encodeColumnDataPageParts (ColByteArray columns)
+    Parquet.Read.decodePlainByteArray (V.length columns) payload H.=== Right columns
+  unless ok exitFailure
+
+
+plainPrimitiveRegression :: IO ()
+plainPrimitiveRegression = do
+  -- Literal little-endian payloads also cover NaN payloads and negative zero;
+  -- compare floating bits rather than IEEE equality.
+  let words32 = VP.fromList [0, 0x80000000, 0x7fc01234, 0x7f800000, 0xffffffff] :: VP.Vector Word32
+      words64 = VP.fromList [0, 0x8000000000000000, 0x7ff8123456789abc, 0x7ff0000000000000, 0xffffffffffffffff] :: VP.Vector Word64
+      bytes32 = BS.pack . concatMap (\n -> (\s -> fromIntegral (n `shiftR` s)) <$> [0,8,16,24]) . VP.toList
+      bytes64 = BS.pack . concatMap (\n -> (\s -> fromIntegral (n `shiftR` s)) <$> [0,8,16,24,32,40,48,56]) . VP.toList
+      check32 input expected = do
+        (VP.map fromIntegral <$> Parquet.Read.decodePlainInt32 (VP.length expected) input) H.=== Right expected
+        (VP.map castFloatToWord32 <$> Parquet.Read.decodePlainFloat (VP.length expected) input) H.=== Right expected
+      check64 input expected = do
+        (VP.map fromIntegral <$> Parquet.Read.decodePlainInt64 (VP.length expected) input) H.=== Right expected
+        (VP.map castDoubleToWord64 <$> Parquet.Read.decodePlainDouble (VP.length expected) input) H.=== Right expected
+  ok <- H.check $ H.property $ do
+    prefix <- H.forAll (Gen.int (Range.linear 1 7))
+    input32 <- VP.fromList <$> H.forAll (Gen.list (Range.linear 0 128) (Gen.word32 Range.constantBounded))
+    input64 <- VP.fromList <$> H.forAll (Gen.list (Range.linear 0 128) (Gen.word64 Range.constantBounded))
+    let unaligned payload = BS.drop prefix (BS.replicate prefix 0x5a <> payload <> BS.replicate 9 0xa5)
+    check32 (unaligned (bytes32 words32)) words32
+    check64 (unaligned (bytes64 words64)) words64
+    check32 (unaligned (bytes32 input32)) input32
+    check64 (unaligned (bytes64 input64)) input64
+  unless ok exitFailure
+
+
+arrowParquetProjectionTypes :: IO ()
+arrowParquetProjectionTypes = do
+  let field = AT.Field "x" True (AT.AInt 32 True) V.empty Nothing V.empty
+      schema = AT.Schema (V.singleton field) AT.Little V.empty V.empty
+      col = AC.primColumn AC.PInt32 (VS.fromList [-1, 2 :: Int32])
+  case PArrow.arrowToParquet schema [V.singleton col] of
+    Left e -> failTest e
+    Right (ps, groups) -> do
+      let bytes = PHL.encodeParquet PHL.defaultWriteOptions ps groups
+      case PHL.decodeParquet PHL.defaultReadOptions bytes of
+        Left e -> failTest e
+        Right pf -> do
+          let native = PArrow.parquetFileArrowSchema pf
+              check ty = expect ("projection rejects reinterpretation as " ++ show ty)
+                (isLeft (PArrow.parquetRowGroupToArrow
+                  (native {AT.arrowFields = V.singleton (field {AT.fieldType = ty})}) pf 0))
+          expect "dense bridge emits required schema without definition levels"
+            (not (AT.fieldNullable (AT.arrowFields native V.! 0)))
+          expect "dense bridge preserves all-present values from nullable schema"
+            (PArrow.parquetRowGroupToArrow native pf 0 == Right (V.singleton col))
+          mapM_ check [AT.ABool, AT.AFloatingPoint AT.Single, AT.AInt 64 False]
+
+
+encryptionFailureRegression :: IO ()
+encryptionFailureRegression = do
+  let key = BS.replicate 16 0x42
+      column = ColInt32 (VP.fromList [1, 2 :: Int32])
+      schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "x" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+        ]
+      groups = V.singleton (V.singleton column)
+      footer = FooterEncryption key "fresh-id" BS.empty BS.empty
+      ce = ColumnEncryption Enc.AesGcmV1 key "fresh-id" BS.empty BS.empty 0
+      aux enc ver = V.singleton (V.singleton (emptyColumnAux {caEncryption = Just enc, caPageVersion = ver}))
+      badColumn = ce {ceKey = "bad"}
+      badFooter = footer {feKey = "bad"}
+  mapM_ (\ver -> do
+    result <- buildParquetFileWithIndexEncryptedFooter footer schema groups (aux badColumn ver)
+    expect "invalid column key rejects rather than producing plaintext" (isLeft result)) [PageV1, PageV2]
+  badFooterResult <- buildParquetFileWithIndexEncryptedFooter badFooter schema groups V.empty
+  expect "invalid footer key rejects rather than producing plaintext" (isLeft badFooterResult)
+  unsignedFooter <- buildParquetFileWithIndexIO schema groups (aux ce PageV1)
+  expect "encrypted columns reject unsupported unsigned plaintext footer" (isLeft unsignedFooter)
+  auxResult <- encryptAuxModule (Just badColumn) Enc.ModuleColumnIndex 0 "secret-index"
+  expect "auxiliary encryption failure returns Left" (isLeft auxResult)
+  pureResult <- try (evaluate (BS.length (buildParquetFileWithIndex schema groups (aux ce PageV1)))) :: IO (Either SomeException Int)
+  expect "pure writer rejects encrypted configuration and directs caller to IO" (isLeft pureResult)
+  let opts = PHL.defaultWriteOptions {PHL.writeColumnEncryption = V.singleton (Just ce)}
+      mixed = V.singleton (PCRequired column)
+  mixedResult <- try (evaluate (BS.length (PHL.encodeParquetMixed opts schema [mixed]))) :: IO (Either SomeException Int)
+  expect "mixed writer never ignores requested encryption" (isLeft mixedResult)
+  emptyResult <- try (evaluate (BS.length (PHL.encodeParquet opts schema []))) :: IO (Either SomeException Int)
+  expect "pure high-level writer rejects encryption even without row groups" (isLeft emptyResult)
+  first <- Enc.encryptGcmModuleFramed key "same-aad" "first" >>= either failTest pure
+  second <- Enc.encryptGcmModuleFramed key "same-aad" "second" >>= either failTest pure
+  expect "repeated AAD does not reuse GCM nonces"
+    (BS.take 12 (BS.drop 4 first) /= BS.take 12 (BS.drop 4 second))
+  expect "explicit nonce API rejects short nonce"
+    (isLeft (Enc.encryptGcmModuleWithNonce key "short" "aad" "secret"))
+  mapM_ (\offset -> expect "encrypted framing rejects invalid offsets"
+    (isLeft (Enc.readFramedModule first offset))) [-1, maxBound]
+  missing <- buildParquetFileWithIndexIO schema (V.singleton V.empty) V.empty
+  expect "checked writer rejects missing columns" (isLeft missing)
+  wrongType <- buildParquetFileWithIndexIO schema
+    (V.singleton (V.singleton (ColInt64 (VP.fromList [1, 2])))) V.empty
+  expect "checked writer rejects physical type mismatch" (isLeft wrongType)
+  let twoFields = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 2) Nothing Nothing Nothing Nothing
+        , schema V.! 1
+        , (schema V.! 1) {seName = "y"}
+        ]
+  differentLengths <- buildParquetFileWithIndexIO twoFields
+    (V.singleton (V.fromList [column, ColInt32 (VP.singleton 1)])) V.empty
+  expect "checked writer rejects unequal column row counts" (isLeft differentLengths)
+  extraAux <- buildParquetFileWithIndexIO schema groups (V.singleton (V.replicate 2 emptyColumnAux))
+  expect "checked writer rejects unmatched auxiliary columns" (isLeft extraAux)
+
+
+floatingStatisticsRegression :: IO ()
+floatingStatisticsRegression = do
+  let nanF = castWord32ToFloat 0x7fc00001
+      nanD = realToFrac nanF :: Double
+      floatStats xs = columnDataStatistics (ColFloat (VP.fromList xs))
+      doubleStats xs = columnDataStatistics (ColDouble (VP.fromList xs))
+      floatNaNs = [[nanF, -2, 3], [-2, nanF, 3], [-2, 3, nanF]]
+      doubleNaNs = [[nanD, -2, 3], [-2, nanD, 3], [-2, 3, nanD]]
+  mapM_ (\xs -> do
+    let stats = floatStats xs
+    expect "FLOAT statistics ignore NaN at every position"
+      (statNanCount stats == Just 1
+        && (statMinValue stats >>= Pred.decodePValueLE PTFloat) == Just (Pred.PVFloat (-2))
+        && (statMaxValue stats >>= Pred.decodePValueLE PTFloat) == Just (Pred.PVFloat 3))) floatNaNs
+  mapM_ (\xs -> do
+    let stats = doubleStats xs
+    expect "DOUBLE statistics ignore NaN at every position"
+      (statNanCount stats == Just 1
+        && (statMinValue stats >>= Pred.decodePValueLE PTDouble) == Just (Pred.PVDouble (-2))
+        && (statMaxValue stats >>= Pred.decodePValueLE PTDouble) == Just (Pred.PVDouble 3))) doubleNaNs
+  mapM_ (\stats -> expect "all-NaN columns omit every min/max bound and retain NaN count"
+    (statMin stats == Nothing && statMax stats == Nothing
+      && statMinValue stats == Nothing && statMaxValue stats == Nothing
+      && statNullCount stats == Just 0 && statNanCount stats == Just 2))
+    [floatStats [nanF, nanF], doubleStats [nanD, nanD]]
+  mapM_ (\stats -> expect "empty floating columns explicitly report zero NaNs"
+    (statNanCount stats == Just 0 && statMinValue stats == Nothing)) [floatStats [], doubleStats []]
+  mapM_ (\xs -> do
+    let stats = floatStats xs
+    expect "FLOAT zero bounds are canonical -0 and +0"
+      (statMinValue stats == Just (BS.pack [0, 0, 0, 0x80])
+        && statMaxValue stats == Just (BS.replicate 4 0))) [[0], [-0.0], [0, -0.0]]
+  mapM_ (\xs -> do
+    let stats = doubleStats xs
+    expect "DOUBLE zero bounds are canonical -0 and +0"
+      (statMinValue stats == Just (BS.pack [0, 0, 0, 0, 0, 0, 0, 0x80])
+        && statMaxValue stats == Just (BS.replicate 8 0))) [[0], [-0.0], [0, -0.0]]
+  let nanBytes = BS.pack [1, 0, 0xc0, 0x7f]
+      badStats = (floatStats [1]) {statMin = Just nanBytes, statMinValue = Just nanBytes}
+  expect "predicate decoder ignores legacy NaN bounds" (Pred.decodePValueLE PTFloat nanBytes == Nothing)
+  let floatNegativeZero = BS.pack [0, 0, 0, 0x80]
+      doubleNegativeZero = BS.pack [0, 0, 0, 0, 0, 0, 0, 0x80]
+      bloom bytes = sbbfInsert bytes (newSbbf 256)
+  expect "FLOAT bloom lookup preserves = +0 matches in a -0-only column"
+    (Pred.evalBloomChunk (physicalField PTFloat) (bloom floatNegativeZero) (Pred.PEq (Pred.PVFloat 0)) == Pred.PMaybeKeep)
+  expect "FLOAT bloom lookup preserves = -0 matches in a +0-only column"
+    (Pred.evalBloomChunk (physicalField PTFloat) (bloom (BS.replicate 4 0)) (Pred.PEq (Pred.PVFloat (-0.0))) == Pred.PMaybeKeep)
+  expect "DOUBLE bloom lookup preserves both zero encodings"
+    (Pred.evalBloomChunk (physicalField PTDouble) (bloom doubleNegativeZero) (Pred.PIn [Pred.PVDouble 0]) == Pred.PMaybeKeep
+      && Pred.evalBloomChunk (physicalField PTDouble) (bloom (BS.replicate 8 0)) (Pred.PEq (Pred.PVDouble (-0.0))) == Pred.PMaybeKeep)
+  let schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 2) Nothing Nothing Nothing Nothing
+        , SchemaElement "f" (Just Required) (Just PTFloat) Nothing Nothing Nothing Nothing Nothing
+        , SchemaElement "g" (Just Required) (Just PTFloat) Nothing Nothing Nothing Nothing Nothing
+        ]
+      columns = V.fromList [ColFloat (VP.fromList [nanF, -2, 3]), ColFloat (VP.fromList [1, 2, 3])]
+      bytes = buildParquetFile schema (V.singleton columns)
+  file <- either failTest pure (loadParquetFile bytes)
+  let metadata = pfFooter file
+      statsAt fm idx = ccMetadata (rgColumns (fmRowGroups fm V.! 0) V.! idx) >>= cmStatistics
+  expect "footer round-trip preserves NaN counts"
+    (fmap statNanCount (statsAt metadata 0) == Just (Just 1)
+      && fmap statNanCount (statsAt metadata 1) == Just (Just 0))
+  expect "writer declares TYPE_ORDER per leaf"
+    (fmColumnOrders metadata == Just (V.replicate 2 TypeDefinedOrder))
+  let original = rgColumns (fmRowGroups metadata V.! 0) V.! 0
+      withBadStats = original {ccMetadata = fmap (\md -> md {cmStatistics = Just badStats}) (ccMetadata original)}
+  expect "legacy NaN minimum cannot cause false range pruning"
+    (Pred.evalColumnChunk (knownContext (physicalField PTFloat)) withBadStats (Pred.PLt (Pred.PVFloat 2)) == Pred.PMaybeKeep)
+  let indexedMetadata = metadata {fmRowGroups = V.map (\rg -> rg
+        {rgColumns = V.imap (\i cc -> cc
+          {ccColumnIndexOffset = Just (100 + fromIntegral i), ccColumnIndexLength = Just 8})
+          (rgColumns rg)}) (fmRowGroups metadata)}
+      rawOrders orders = case Footer.fileMetadataToThrift indexedMetadata of
+        TV.Struct fields -> TV.Struct (V.map (\field -> case field of
+          TS.FileMetadata_ColumnOrders _ -> TS.FileMetadata_ColumnOrders orders
+          other -> other) fields)
+        value -> value
+      unknown = TV.Struct (V.singleton (99, TV.Struct V.empty))
+      known = TV.Struct (V.singleton (1, TV.Struct V.empty))
+  unknownFile <- either failTest pure (Footer.readFooterRaw (Thrift.encodeCompact (rawOrders (V.fromList [unknown, known]))))
+  expect "unknown column ordering preserves vector positions"
+    (fmColumnOrders unknownFile == Just (V.fromList [UnsupportedColumnOrder, TypeDefinedOrder]))
+  expect "unknown ordering invalidates only the affected bounds"
+    ((statsAt unknownFile 0 >>= statMinValue) == Nothing
+      && (statsAt unknownFile 1 >>= statMinValue) == (statsAt metadata 1 >>= statMinValue))
+  let indexedColumns = rgColumns (fmRowGroups unknownFile V.! 0)
+  expect "unknown ordering disables only the affected column index"
+    (ccColumnIndexOffset (indexedColumns V.! 0) == Nothing
+      && ccColumnIndexOffset (indexedColumns V.! 1) == Just 101)
+  expect "column-order count must match leaf count"
+    (isLeft (Footer.readFooterRaw (Thrift.encodeCompact (rawOrders V.empty))))
+  let knownOrders = metadata
+        { fmNumRows = 0
+        , fmRowGroups = V.empty
+        , fmSchema = schema V.// [(2, (schema V.! 2) {seType = Just PTInt96})]
+        , fmColumnOrders = Just (V.fromList [IEEE754TotalOrder, Int96TimestampOrder])
+        }
+  parsedOrders <- either failTest pure
+    (Footer.readFooterRaw (Thrift.encodeCompact (Footer.fileMetadataToThrift knownOrders)))
+  expect "modern floating and INT96 column-order variants round-trip"
+    (fmColumnOrders parsedOrders == fmColumnOrders knownOrders)
+  let rowGroup = fmRowGroups metadata V.! 0
+      negativeStats = original {ccMetadata = fmap
+        (\md -> md {cmStatistics = fmap (\st -> st {statNanCount = Just (-1)}) (cmStatistics md)})
+        (ccMetadata original)}
+      negativeMetadata = metadata {fmRowGroups = V.singleton
+        (rowGroup {rgColumns = rgColumns rowGroup V.// [(0, negativeStats)]})}
+  expect "negative NaN counts are rejected"
+    (isLeft (Footer.readFooterRaw (Thrift.encodeCompact (Footer.fileMetadataToThrift negativeMetadata))))
+  mapM_ (\edit -> do
+    let changed = original {ccMetadata = fmap
+          (\md -> md {cmStatistics = edit <$> cmStatistics md}) (ccMetadata original)}
+        excessive = metadata {fmRowGroups = V.singleton
+          (rowGroup {rgColumns = rgColumns rowGroup V.// [(0, changed)]})}
+    expect "impossible NaN/null counts are rejected"
+      (isLeft (Footer.readFooterRaw (Thrift.encodeCompact (Footer.fileMetadataToThrift excessive)))))
+    [ (\st -> st {statNanCount = Just 4})
+    , (\st -> st {statNullCount = Just 4})
+    , (\st -> st {statNullCount = Just 2, statNanCount = Just 2})
+    ]
+
+
+legacyLz4Regression :: IO ()
+#ifdef HAVE_LZ4
+legacyLz4Regression = do
+  let literal = BS.pack [0x50, 104, 101, 108, 108, 111]
+      lengthBE n = BS.pack [0, 0, 0, n]
+      chunk = lengthBE 6 <> literal
+      framed = lengthBE 5 <> chunk
+      splitBlock = lengthBE 10 <> chunk <> chunk
+      decode n payload = do
+        let header = PageHeader (PtDataPage (DataPageHeader 1 0))
+              (Just n) (Just (fromIntegral (BS.length payload)))
+        (_, _, raw, _) <- Parquet.Read.decompressDataPageBody LZ4
+          (encodePageHeader header <> payload) 0
+        Right raw
+  expect "legacy LZ4 accepts Hadoop framing" (decode 5 framed == Right "hello")
+  expect "legacy LZ4 accepts several chunks per block" (decode 10 splitBlock == Right "hellohello")
+  expect "legacy LZ4 accepts several Hadoop blocks" (decode 10 (framed <> framed) == Right "hellohello")
+  expect "legacy LZ4 accepts old parquet-cpp raw blocks" (decode 5 literal == Right "hello")
+  mapM_ (\payload -> expect "legacy LZ4 rejects malformed framing"
+      (isLeft (decode 5 payload)))
+    [ BS.take 3 framed, BS.init framed, lengthBE 6 <> chunk
+    , lengthBE 5 <> lengthBE 255 <> literal, framed <> BS.singleton 0
+    ]
+#else
+legacyLz4Regression = pure ()
+#endif
+
+
+hybridBitWidthRegression :: IO ()
+hybridBitWidthRegression = do
+  let golden = BS.pack [9, 3, 0, 254, 7, 240, 63, 0, 224, 191, 254]
+  expect "9-bit dictionary indices preserve values across aligned group ends"
+    (Parquet.Read.decodeDictionaryIndices 8 golden == Right (VP.fromList [0,511,1,510,3,256,255,509]))
+  mapM_ (\width -> do
+    let mask = ((1 :: Word64) `shiftL` width) - 1
+        input = VP.generate 259 (\i -> fromIntegral ((fromIntegral i * 104729 + mask) .&. mask))
+        encoded = LE.encodeRLEHybrid width input
+    expect ("hybrid bit packing round-trips full width " ++ show width)
+      (Parquet.Read.decodeHybridRleUnsigned32 width (VP.length input) encoded == Right input)) [1..32]
+  expect "hybrid decoder rejects zero-length packed run"
+    (isLeft (Parquet.Read.decodeHybridRleUnsigned32 9 1 (BS.singleton 1)))
+  expect "hybrid decoder rejects empty input before allocating a huge output"
+    (isLeft (Parquet.Read.decodeHybridRleUnsigned32 1 maxBound BS.empty))
+  expect "dictionary decoder rejects a missing stream before allocating"
+    (isLeft (Parquet.Read.decodeDictionaryIndices maxBound (BS.singleton 1)))
+  expect "zero-width hybrid streams need no input bytes"
+    (Parquet.Read.decodeHybridRleUnsigned32 0 3 BS.empty == Right (VP.replicate 3 0))
+  mapM_ (\width -> do
+    -- Each prefix is valid but cannot cover the advertised count. In
+    -- particular, scanning only the first header would miss the bad suffix.
+    let repeated = BS.singleton 2 <> BS.replicate ((width + 7) `quot` 8) 0
+        packed = BS.singleton 3 <> BS.replicate width 0
+        suffixes = [BS.empty, BS.singleton 0, BS.singleton 1, BS.singleton 128,
+          BS.replicate 10 255, BS.singleton 3, BS.singleton 2]
+    mapM_ (\prefix -> mapM_ (\suffix ->
+      expect "hybrid decoder validates later runs before allocating a huge output"
+        (isLeft (Parquet.Read.decodeHybridRleUnsigned32 width 100000000 (prefix <> suffix))))
+      suffixes) [BS.empty, repeated, packed, repeated <> packed]) [1..32]
+  expect "hybrid output size must not overflow the primitive vector byte count"
+    (isLeft (Parquet.Read.decodeHybridRleUnsigned32 0 maxBound BS.empty))
+  let longRepeated = BS.pack [128,128,8,1] -- 65536 repeated one-bit values.
+  expect "valid long compressed runs remain supported"
+    (Parquet.Read.decodeHybridRleUnsigned32 1 65536 longRepeated == Right (VP.replicate 65536 1))
+  expect "hybrid validation stops at the requested count, before unused suffixes"
+    (Parquet.Read.decodeHybridRleUnsigned32 1 3 (BS.pack [6,1,128]) == Right (VP.replicate 3 1))
+  expect "hybrid decoder rejects overflowing run headers"
+    (isLeft (Parquet.Read.decodeHybridRleUnsigned32 9 1 (BS.replicate 10 0xff)))
+  expect "hybrid decoder checks packed size without multiplication overflow"
+    (isLeft (Parquet.Read.decodeHybridRleUnsigned32 32 1 (BS.pack [0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,1])))
+  ok <- H.check $ H.withTests 300 $ H.property $ do
+    width <- H.forAll (Gen.element [1,2,4,8])
+    groups <- H.forAll (Gen.int (Range.linear 1 96))
+    packed <- H.forAll (Gen.bytes (Range.singleton (groups * width)))
+    count <- H.forAll (Gen.int (Range.linear 0 (groups * 8)))
+    padding <- H.forAll (Gen.bytes (Range.linear 1 16))
+    repeated <- H.forAll (Gen.word8 Range.constantBounded)
+    let run = groups * 2 + 1
+        runHeader = BS.pack $ if run < 128 then [fromIntegral run]
+          else [fromIntegral (run .&. 127) .|. 128, fromIntegral (run `shiftR` 7)]
+        payload = runHeader <> packed
+        sliced = BS.drop (BS.length padding) (padding <> payload)
+        -- Independent bit-position oracle, rather than the format's encoder.
+        at index = foldr (\bit acc ->
+          let absolute = index * width + bit
+              byte = BS.index packed (absolute `quot` 8)
+          in if testBit byte (absolute `rem` 8) then setBit acc bit else acc)
+          (0 :: Int32) [0 .. width - 1]
+        values = VP.generate (groups * 8) at
+        mask = fromIntegral ((1 `shiftL` width) - 1 :: Int) :: Word8
+        first = repeated .&. mask
+        lastValue = first `xor` mask
+        mixed = BS.pack [6, first] <> payload <> BS.pack [4, lastValue]
+        expected = VP.replicate 3 (fromIntegral first) <> values <> VP.replicate 2 (fromIntegral lastValue)
+    Parquet.Read.decodeHybridRleUnsigned32 width count sliced H.=== Right (VP.take count values)
+    Parquet.Read.decodeHybridRleUnsigned32 width (VP.length expected) mixed H.=== Right expected
+    when (count > 0) $ H.assert (isLeft (Parquet.Read.decodeHybridRleUnsigned32 width count (BS.init payload)))
+  unless ok exitFailure
+
+
+decimalStatisticsRegression :: IO ()
+decimalStatisticsRegression = do
+  let pairs = V.fromList
+        [(-129,BS.pack [255,127]),(-128,BS.pack [128]),(-1,BS.pack [255,255]),
+         (0,BS.pack [0]),(1,BS.pack [1]),(127,BS.pack [127]),(128,BS.pack [0,128]),
+         (256,BS.pack [1,0]),(1000,BS.pack [3,232])] :: V.Vector (Integer,BS.ByteString)
+      field = (physicalField PTByteArray) {seName = "x",seLogicalType = Just (LTDecimal 6 2),seConvertedType = Just CTDecimal}
+      schema = V.fromList [SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing,field]
+      bytes = PHL.encodeParquet (PHL.defaultWriteOptions {PHL.writeCompression = Uncompressed}) schema
+        [V.singleton (ColByteArray (snd <$> pairs))]
+  file <- either failTest pure (loadParquetFile bytes)
+  let metadata = pfFooter file
+      group = V.head (fmRowGroups metadata)
+      column = V.head (rgColumns group)
+  stats <- maybe (failTest "missing decimal statistics") pure (ccMetadata column >>= cmStatistics)
+  expect "DECIMAL byte statistics use signed numeric ordering across widths"
+    (statMinValue stats == Just (BS.pack [255,127]) && statMaxValue stats == Just (BS.pack [3,232])
+      && statMin stats == Nothing && statMax stats == Nothing)
+  expect "DECIMAL aggregate min/max use exact numeric values"
+    (PAgg.columnMin metadata 0 == Just (Pred.PVDecimal ((-129) % 100))
+      && PAgg.columnMax metadata 0 == Just (Pred.PVDecimal 10))
+  ci <- either failTest pure (readColumnIndex file 0 0)
+  index <- maybe (failTest "missing decimal page index") pure ci
+  V.mapM_ (\(number,_) -> do
+    let predicate = Pred.PEq (Pred.PVDecimal (number % 100))
+    expect "decimal row-group pruning keeps every present value"
+      (Pred.evalRowGroup metadata (Pred.PCol "x" predicate) group == Pred.PMaybeKeep)
+    expect "decimal column/page pruning keeps every present value"
+      (Pred.evalColumnChunk (knownContext field) column predicate == Pred.PMaybeKeep
+        && Pred.evalPagesByColumnIndex (knownContext field) index predicate == V.singleton Pred.PMaybeKeep)) pairs
+  expect "decimal pruning rejects a value outside its numeric bounds"
+    (Pred.evalRowGroup metadata (Pred.PCol "x" (Pred.PGt (Pred.PVDecimal 20))) group == Pred.PSkip)
+  let unsigned = (physicalField PTInt32) {seLogicalType = Just (LTInteger 32 False)}
+  expect "unsigned statistics retain the unsigned range"
+    (Pred.decodePValueForSchema unsigned (BS.replicate 4 255) == Just (Pred.PVUnsigned 4294967295))
+  expect "cross-type scalar comparisons never invent equality"
+    (not (SharedPred.pvEq (Pred.PVInt32 1) (Pred.PVText "one"))
+      && SharedPred.evalRange (Pred.PVInt32 1) (Pred.PVInt32 2) (Pred.PLt (Pred.PVDouble 100)) == Pred.PMaybeKeep)
+  mapM_ (\(ty,bytes) -> expect "malformed physical bounds are never used for pruning"
+    (Pred.decodePValueForSchema (physicalField ty) bytes == Nothing))
+    [(PTInt32,BS.replicate 5 0),(PTInt64,BS.replicate 9 0),(PTFloat,BS.replicate 5 0),
+     (PTDouble,BS.replicate 9 0),(PTBoolean,BS.pack [2]),(PTBoolean,BS.pack [1,0])]
+  let halfField = (physicalField PTFixedLenByteArray) {seTypeLength = Just 2,seLogicalType = Just LTFloat16}
+  expect "FLOAT16 statistics use numeric floating-point order"
+    (Pred.decodePValueForSchema halfField (BS.pack [0,188]) == Just (Pred.PVDouble (-1))
+      && Pred.decodePValueForSchema halfField (BS.pack [0,60]) == Just (Pred.PVDouble 1)
+      && Pred.decodePValueForSchema halfField (BS.pack [1,124]) == Nothing)
+  expect "unsupported logical/physical combinations cannot supply ordered bounds"
+    (Pred.decodePValueForSchema (unsigned {seType = Just PTInt64}) (BS.replicate 8 0) == Nothing)
+  let enumField = field {seLogicalType = Just LTEnum,seConvertedType = Just CTEnum}
+      enumFile = Parquet.Read.ParquetFile BS.empty (metadata {fmSchema = V.fromList [schema V.! 0,enumField]})
+  expect "ENUM annotations preserve their UTF-8 semantics"
+    (AT.fieldType (V.head (AT.arrowFields (PArrow.parquetFileArrowSchema enumFile))) == AT.AUtf8
+      && Pred.decodePValueForSchema enumField "ready" == Just (Pred.PVText "ready"))
+  let paddedBloom = sbbfInsert (BS.pack [255,255]) (newSbbf 256)
+  expect "decimal bloom probing cannot reject equivalent sign-extended values"
+    (Pred.evalBloomChunk field paddedBloom (Pred.PEq (Pred.PVDecimal ((-1) % 100))) == Pred.PMaybeKeep)
+  expect "bloom probing keeps incompatible scalar representations"
+    (Pred.evalBloomChunk (physicalField PTInt32) (newSbbf 256) (Pred.PEq (Pred.PVInt64 1)) == Pred.PMaybeKeep)
+  mapM_ (\logical -> do
+    let unordered = field {seLogicalType = Just logical,seConvertedType = Nothing}
+    expect "undefined logical ordering cannot be used for pruning"
+      (Pred.decodePValueForSchema unordered (BS.pack [1]) == Nothing)
+    unorderedFile <- either failTest pure (loadParquetFile (PHL.encodeParquet
+      (PHL.defaultWriteOptions {PHL.writeCompression = Uncompressed})
+      (V.fromList [schema V.! 0,unordered]) [V.singleton (ColByteArray (V.fromList [BS.pack [1],BS.pack [2]]))]))
+    let metadataBounds = ccMetadata (V.head (rgColumns (V.head (fmRowGroups (pfFooter unorderedFile))))) >>= cmStatistics
+    expect "writers omit bounds for undefined logical ordering"
+      (maybe False (\s -> statMinValue s == Nothing && statMaxValue s == Nothing) metadataBounds))
+    [LTGeometry defaultGeometryParameters,LTGeography defaultGeographyParameters]
+  mapM_ (\values -> do
+    result <- PHL.encodeParquetIO (PHL.defaultWriteOptions {PHL.writeCompression = Uncompressed})
+      (V.fromList [schema V.! 0,field {seLogicalType = Just (LTDecimal 2 0)}])
+      [V.singleton (ColByteArray (V.singleton values))]
+    expect "writer rejects empty or out-of-precision decimal storage" (isLeft result))
+    [BS.empty,BS.pack [100],BS.pack [156]]
+  let unsignedSchema = V.fromList [schema V.! 0,unsigned {seName = "x"}]
+      unsignedBytes = PHL.encodeParquet (PHL.defaultWriteOptions {PHL.writeCompression = Uncompressed})
+        unsignedSchema [V.singleton (ColInt32 (VP.fromList [0,minBound,-1]))]
+  unsignedFile <- either failTest pure (loadParquetFile unsignedBytes)
+  let unsignedGroup = V.head (fmRowGroups (pfFooter unsignedFile))
+  mapM_ (\value -> expect "unsigned row-group predicates keep values across the signed boundary"
+    (Pred.evalRowGroup (pfFooter unsignedFile) (Pred.PCol "x" (Pred.PEq (Pred.PVUnsigned value))) unsignedGroup == Pred.PMaybeKeep))
+    [0,2147483648,4294967295]
+  expect "unsigned aggregates compare unsigned values"
+    (PAgg.columnMax (pfFooter unsignedFile) 0 == Just (Pred.PVUnsigned 4294967295))
+  passed <- H.check $ H.withTests 100 $ H.property $ do
+    numbers <- H.forAll (Gen.nonEmpty (Range.linear 1 40) (Gen.int64 (Range.linear minBound maxBound)))
+    width <- H.forAll (Gen.int (Range.linear 8 12))
+    let encode number = BS.pack (reverse ((\offset -> fromIntegral ((fromIntegral number :: Integer) `shiftR` (8 * offset))) <$> [0 .. width-1]))
+        exactField = field {seLogicalType = Just (LTDecimal 19 0)}
+        exactSchema = V.fromList [schema V.! 0,exactField]
+        encoded = PHL.encodeParquet (PHL.defaultWriteOptions {PHL.writeCompression = Uncompressed}) exactSchema
+          [V.singleton (ColByteArray (V.fromList (encode <$> NE.toList numbers)))]
+    loaded <- H.evalEither (loadParquetFile encoded)
+    PAgg.columnMin (pfFooter loaded) 0 H.=== Just (Pred.PVDecimal (fromIntegral (minimum numbers)))
+    PAgg.columnMax (pfFooter loaded) 0 H.=== Just (Pred.PVDecimal (fromIntegral (maximum numbers)))
+  unless passed (failTest "signed decimal statistics property")
+
+
+writerOptionsRegression :: IO ()
+writerOptionsRegression = do
+  let required = SchemaElement "r" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+      optional = SchemaElement "o" (Just Optional) (Just PTInt64) Nothing Nothing Nothing Nothing Nothing
+      schema = V.fromList [SchemaElement "schema" Nothing Nothing (Just 2) Nothing Nothing Nothing Nothing, required, optional]
+      rows = V.fromList [PCRequired (ColInt32 (VP.fromList [1,2,3])), PCOptional (OptInt64 (V.fromList [Just 10,Nothing,Just 30]))]
+  optionalExpected <- either failTest pure (AC.mkPrim AC.PInt64
+    (AC.validityFromBools (V.fromList [True,False,True])) (VS.fromList [10,0,30]))
+  mapM_ (\version -> mapM_ (\codec -> mapM_ (\indexed -> do
+    let opts = PHL.defaultWriteOptions {PHL.writePageVersion = version, PHL.writeCompression = codec,
+          PHL.writePageIndex = indexed, PHL.writeBloomFilters = ["o"]}
+        bytes = PHL.encodeParquetMixed opts schema [rows,rows]
+    pf <- either failTest pure (PHL.decodeParquet PHL.defaultReadOptions bytes)
+    mapM_ (\rg -> mapM_ (\col -> do
+      let chunk = rgColumns (fmRowGroups (pfFooter pf) V.! rg) V.! col
+      metadata <- maybe (failTest "missing options regression metadata") pure (ccMetadata chunk)
+      expect "mixed writer honors requested compression" (cmCodec metadata == codec)
+      (header, _) <- either failTest pure (readPageHeaderCheckedAt bytes (fromIntegral (cmDataPageOffset metadata)))
+      expect "mixed writer honors requested page version" (case (version,phType header) of
+        (PageV1,PtDataPage {}) -> True; (PageV2,PtDataPageV2 {}) -> True; _ -> False)
+      expect "mixed writer honors page-index toggle" ((ccOffsetIndexOffset chunk /= Nothing) == indexed
+        && (ccColumnIndexOffset chunk /= Nothing) == indexed)
+      expect "mixed writer attaches bloom only to requested nullable column"
+        ((cmBloomFilterOffset metadata /= Nothing) == (col == 1))
+      when indexed $ do
+        index <- either failTest pure (readOffsetIndex pf rg col)
+        location <- maybe (failTest "missing generated offset index") (pure . V.head . oiPageLocations) index
+        expect "generated index uses absolute page offset and complete on-disk size"
+          (plOffset location == cmDataPageOffset metadata
+            && fromIntegral (plCompressedPageSize location) == cmTotalCompressedSize metadata
+            && plFirstRowIndex location == 0)
+        ci <- either failTest pure (readColumnIndex pf rg col)
+        expect "generated index includes page null counts"
+          ((ci >>= ciNullCounts) == Just (V.singleton (if col == 1 then 1 else 0)))
+        if col == 0 then do
+          selected <- either failTest pure (Parquet.Read.readGenericInt32SelectedPages codec bytes
+            (V.singleton location) (V.singleton True))
+          expect "generated indexes select required values" (selected == VP.fromList [1,2,3])
+        else do
+          selected <- either failTest pure (Parquet.Read.readGenericInt64OptionalSelectedPages codec 0 1 bytes
+            (V.singleton location) (V.singleton True))
+          expect "generated indexes select nullable values" (selected == V.fromList [Just 10,Nothing,Just 30])) [0,1]) [0,1]
+    let native = PArrow.parquetFileArrowSchema pf
+    columns <- either (failTest . show) pure (PArrow.parquetRowGroupToArrow native pf 1)
+    expect "mixed options preserve nullable values"
+      (columns == V.fromList [AC.primColumn AC.PInt32 (VS.fromList [1,2,3]),
+        optionalExpected])) [False,True]) [Uncompressed,GZip,LZO]) [PageV1,PageV2]
+  rejected <- try (evaluate (BS.length (PHL.encodeParquetMixed
+    (PHL.defaultWriteOptions {PHL.writeCompression = LZ4}) schema [rows]))) :: IO (Either SomeException Int)
+  expect "mixed writer rejects unsupported codec instead of silently falling back" (isLeft rejected)
+  let requiredSchema = V.fromList [SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing, required]
+      badOptions = PHL.defaultWriteOptions {PHL.writeCompression = LZ4}
+  mapM_ (\groups -> do
+    failure <- try (evaluate (BS.length (PHL.encodeParquet badOptions requiredSchema groups))) :: IO (Either SomeException Int)
+    expect "required writer rejects unavailable codec including empty files" (isLeft failure)
+    checked <- PHL.encodeParquetIO badOptions requiredSchema groups
+    expect "checked writer reports unavailable codec through Left" (isLeft checked))
+    [[], [V.singleton (ColInt32 (VP.fromList [1,2,3]))]]
+  mismatch <- pure (PHL.encodeParquetMixed (PHL.defaultWriteOptions {PHL.writeCompression = Uncompressed}) schema
+    [V.singleton (PCRequired (ColInt32 (VP.fromList [1,2,3])))])
+  malformed <- try (evaluate (BS.length mismatch)) :: IO (Either SomeException Int)
+  expect "mixed writer rejects incomplete column groups" (isLeft malformed)
+  let zeros = ColInt32 (VP.replicate 257 0)
+      compressed = PHL.encodeParquetMixed (PHL.defaultWriteOptions
+        {PHL.writeCompression = GZip, PHL.writePageVersion = PageV1}) requiredSchema
+        [V.singleton (PCRequired zeros)]
+  pf <- either failTest pure (loadParquetFile compressed)
+  let rg = V.head (fmRowGroups (pfFooter pf))
+  meta <- maybe (failTest "missing compressed size regression metadata") pure
+    (ccMetadata (V.head (rgColumns rg)))
+  (header, bodyOffset) <- either failTest pure
+    (readPageHeaderCheckedAt compressed (fromIntegral (cmDataPageOffset meta)))
+  let uncompressed = fromIntegral (bodyOffset - fromIntegral (cmDataPageOffset meta))
+        + maybe 0 fromIntegral (phUncompressedPageSize header)
+  expect "mixed uncompressed size uses the actual compressed-page header length"
+    (cmTotalUncompressedSize meta == uncompressed)
+  expect "row-group total byte size is uncompressed even for compressed files"
+    (rgTotalByteSize rg == uncompressed && uncompressed > cmTotalCompressedSize meta)
+
+
+wideTimestampStorageRegression :: IO ()
+wideTimestampStorageRegression = do
+  let schema unit =
+        V.fromList
+          [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+          , SchemaElement
+              "timestamp"
+              (Just Required)
+              (Just PTFixedLenByteArray)
+              Nothing
+              Nothing
+              (Just (LTTimestamp True unit))
+              Nothing
+              (Just 12)
+          ]
+      footer unit = FileMetadata 1 (schema unit) 0 V.empty Nothing Nothing Nothing
+      file unit = parquetMagic <> Footer.writeFooter (footer unit)
+  mapM_
+    ( \unit -> do
+        expect
+          "wide timestamps retain their lossless type and parameters"
+          ( case PArrow.parquetFileArrowSchemaChecked (Parquet.Read.ParquetFile (file unit) (footer unit)) of
+              Right result -> V.length (AT.arrowFields result) == 1 && Timestamp.timestampEncoding (V.head (AT.arrowFields result)) == Right (Just (Timestamp.SignedTimestamp96 True unit))
+              Left _ -> False
+          )
+        expect
+          "public decode accepts valid wide timestamp storage"
+          (either (const False) (const True) (PHL.decodeParquet PHL.defaultReadOptions (file unit)))
+    )
+    [LtMillis, LtMicros, LtNanos]
+
+
+legacyDictionarySizeRegression :: IO ()
+legacyDictionarySizeRegression = do
+  let values = V.fromList ["alpha", "beta", "alpha", "gamma", "beta", "alpha"]
+      schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "x" (Just Required) (Just PTByteArray) Nothing Nothing Nothing Nothing Nothing ]
+      dictionary = buildDictionary (ColByteArray values)
+      dictionaryPage = encodeDictPage dictionary
+      pages = dictionaryPage <> encodeDictDataPage dictionary
+  base <- either failTest pure (loadParquetFile (buildParquetFile schema
+    (V.singleton (V.singleton (ColByteArray values)))))
+  (_, dictionaryHeaderSize) <- either failTest pure (readPageHeaderAt dictionaryPage 0)
+  let footer = pfFooter base
+      row = V.head (fmRowGroups footer)
+      column = V.head (rgColumns row)
+  metadata <- maybe (failTest "missing dictionary regression metadata") pure (ccMetadata column)
+  let shortSize = BS.length pages - dictionaryHeaderSize
+      legacyMeta = metadata
+        { cmEncodings = V.empty, cmDataPageOffset = 4, cmDictionaryPageOffset = Nothing
+        , cmTotalCompressedSize = fromIntegral shortSize
+        , cmTotalUncompressedSize = fromIntegral shortSize }
+      legacyColumn = column {ccMetadata = Just legacyMeta}
+      makeFile col =
+        let fm = footer {fmCreatedBy = Just "parquet-mr",
+              fmRowGroups = V.singleton (row {rgColumns = V.singleton col})}
+        in Parquet.Read.ParquetFile (parquetMagic <> pages <> Footer.writeFooter fm) fm
+      legacy = makeFile legacyColumn
+  corrected <- either failTest pure (Parquet.Read.columnChunkSlice legacy 0 0)
+  expect "legacy dictionary size repair includes exactly the missing header" (corrected == pages)
+  decoded <- either failTest pure (Parquet.Read.readGenericByteArrayColumnChunk Uncompressed corrected)
+  expect "legacy dictionary size repair preserves every value" (decoded == values)
+  let blocked = makeFile (legacyColumn {ccColumnIndexOffset = Just (fromIntegral (4 + BS.length pages - 1))})
+  expect "legacy repair never crosses an auxiliary index boundary"
+    (isLeft (Parquet.Read.columnChunkSlice blocked 0 0))
+  let wrongCount = makeFile (legacyColumn {ccMetadata = Just (legacyMeta {cmNumValues = 7})})
+  expect "legacy repair validates the full declared value count"
+    (isLeft (Parquet.Read.columnChunkSlice wrongCount 0 0))
+  let wrongLength = makeFile (legacyColumn {ccMetadata = Just
+        (legacyMeta {cmTotalCompressedSize = fromIntegral (shortSize - 1)})})
+  expect "legacy repair rejects lengths other than one missing header"
+    (isLeft (Parquet.Read.columnChunkSlice wrongLength 0 0))
+
+
+pageChecksumRegression :: IO ()
+pageChecksumRegression = do
+  -- IEEE CRC32's independent check vector; its high bit also exercises the
+  -- signed i32 Thrift representation. Checksums cover the body, never headers.
+  let payload = "123456789"
+      page ty extra crc body = Thrift.encodeCompact (TV.Struct (V.fromList
+        ([ TS.PageHeader_Type ty, TS.PageHeader_UncompressedSize 9
+         , TS.PageHeader_CompressedSize 9, TS.PageHeader_Crc crc ] ++ extra))) <> body
+      v1 = [TS.PageHeader_DataPageHeader (V.fromList
+        [TS.DataPageHeader_NumValues 1, TS.DataPageHeader_Encoding 0])]
+      v2 = [TS.PageHeader_DataPageHeaderV2 (V.fromList
+        [ TS.DataPageHeaderV2_NumValues 1, TS.DataPageHeaderV2_NumNulls 0
+        , TS.DataPageHeaderV2_NumRows 1, TS.DataPageHeaderV2_Encoding 0
+        , TS.DataPageHeaderV2_DefinitionLevelsByteLength 0, TS.DataPageHeaderV2_RepetitionLevelsByteLength 0 ])]
+      dictionary = [TS.PageHeader_DictionaryPageHeader (V.fromList
+        [TS.DictionaryPageHeader_NumValues 1, TS.DictionaryPageHeader_Encoding 0])]
+      checksum = fromIntegral (0xcbf43926 :: Word32)
+  mapM_ (\(ty, extra) -> do
+    expect "checksums accept the IEEE check vector for every page kind"
+      (not (isLeft (readPageHeaderCheckedAt (page ty extra checksum payload) 0)))
+    expect "checksums reject damaged bodies before decompression"
+      (isLeft (readPageHeaderCheckedAt (page ty extra checksum "123456780") 0))
+    expect "checksums reject a changed CRC"
+      (isLeft (readPageHeaderCheckedAt (page ty extra 0 payload) 0))
+    expect "checksums reject truncated bodies"
+      (isLeft (readPageHeaderCheckedAt (page ty extra checksum "12345678") 0)))
+    [(0, v1), (1, []), (2, dictionary), (3, v2)]
+  let bytes = page 0 v1 checksum payload
+      headerOnly = BS.take (BS.length bytes - BS.length payload) bytes
+  expect "header-only parsing remains available for encryption framing"
+    (not (isLeft (readPageHeaderAt headerOnly 0)))
+  expect "data readers verify checksums instead of exposing damaged bytes"
+    (isLeft (Parquet.Read.decompressDataPageBody Uncompressed (page 0 v1 checksum "123456780") 0))
+  expect "CRC validation handles a page at a nonzero file offset"
+    (not (isLeft (readPageHeaderCheckedAt ("prefix" <> bytes <> "suffix") 6)))
+
+
+malformedCountRegression :: IO ()
+malformedCountRegression = do
+  let check label decoded = expect label (isLeft decoded)
+      encodedInts = encodeDeltaBinaryPackedInt64 (VP.fromList [1, 2, 3])
+      encodedBytes = V.fromList ["first", "second", "third"]
+  mapM_ (\count -> do
+    check "DELTA_BINARY_PACKED checks every expected count"
+      (decodeDeltaBinaryPackedInt64 count encodedInts)
+    check "DELTA_LENGTH_BYTE_ARRAY checks every expected count"
+      (decodeDeltaLengthByteArray count (encodeDeltaLengthByteArray encodedBytes))
+    check "DELTA_BYTE_ARRAY checks every expected count"
+      (decodeDeltaByteArray count (encodeDeltaByteArray encodedBytes))) [-1, 0, 2, 4]
+  check "DELTA rejects a huge truncated count before allocating its output"
+    (decodeDeltaBinaryPackedInt64 2147483647 (BS.pack [0x80, 1, 4, 0xff, 0xff, 0xff, 0xff, 7, 0]))
+  mapM_ (\count -> do
+    check "PLAIN Int32 rejects invalid counts" (Parquet.Read.decodePlainInt32 count BS.empty)
+    check "PLAIN Int64 rejects invalid counts" (Parquet.Read.decodePlainInt64 count BS.empty)
+    check "PLAIN Float rejects invalid counts" (Parquet.Read.decodePlainFloat count BS.empty)
+    check "PLAIN Double rejects invalid counts" (Parquet.Read.decodePlainDouble count BS.empty)
+    check "PLAIN Bool rejects invalid counts" (Parquet.Read.decodePlainBool count BS.empty)
+    check "PLAIN Int96 rejects invalid counts" (Parquet.Read.decodePlainInt96 count BS.empty)
+    check "PLAIN fixed bytes rejects invalid counts" (Parquet.Read.decodePlainFixedLenByteArray 16 count BS.empty)
+    check "BYTE_STREAM_SPLIT Float rejects invalid counts" (Parquet.Read.decodeByteStreamSplitFloat count BS.empty)
+    check "BYTE_STREAM_SPLIT Double rejects invalid counts" (Parquet.Read.decodeByteStreamSplitDouble count BS.empty))
+    [-1, maxBound]
+  let base = PageHeader (PtDataPage (DataPageHeader 0 0)) (Just 0) (Just 0)
+      badHeaders =
+        [ base {phUncompressedPageSize = Just (-1)}
+        , base {phCompressedPageSize = Just (-1)}
+        , base {phUncompressedPageSize = Nothing}
+        , base {phCompressedPageSize = Nothing}
+        , base {phType = PtDataPage (DataPageHeader (-1) 0)}
+        , base {phType = PtDictionaryPage (DictionaryPageHeader (-1) 0)}
+        , base {phType = PtDataPageV2 (DataPageHeaderV2 (-1) 0 0 0 0 0 False)}
+        , base {phType = PtDataPageV2 (DataPageHeaderV2 1 2 1 0 0 0 False)}
+        , base {phType = PtDataPageV2 (DataPageHeaderV2 1 0 2 0 0 0 False)}
+        , base {phType = PtDataPageV2 (DataPageHeaderV2 1 0 1 0 (-1) 0 False)}
+        , base {phType = PtDataPageV2 (DataPageHeaderV2 1 0 1 0 0 (-1) False)}
+        , base {phType = PtDataPageV2 (DataPageHeaderV2 1 0 1 0 maxBound maxBound False)}
+        ]
+  mapM_ (check "malformed page counts/sizes reject" . (`readPageHeaderAt` 0) . encodePageHeader) badHeaders
+  check "negative page-header offset rejects" (readPageHeaderAt (encodePageHeader base) (-1))
+  check "page-header offset at EOF rejects" (readPageHeaderAt BS.empty 0)
+  let metadata extra = TV.Struct (V.fromList
+        [ TS.FileMetadata_Version 1
+        , TS.FileMetadata_Schema (V.fromList
+            [ TV.Struct (V.fromList [TS.SchemaElement_Name "schema", TS.SchemaElement_NumChildren 1])
+            , TV.Struct (V.fromList (TS.SchemaElement_Name "x" : extra))
+            ])
+        , TS.FileMetadata_NumRows 0
+        , TS.FileMetadata_RowGroups V.empty
+        ])
+  check "footer rejects invalid repetition enum without toEnum exception"
+    (Footer.readFooterRaw (Thrift.encodeCompact (metadata [TS.SchemaElement_Type 1, TS.SchemaElement_RepetitionType 99])))
+  check "footer rejects unknown physical type"
+    (Footer.readFooterRaw (Thrift.encodeCompact (metadata [TS.SchemaElement_Type 99, TS.SchemaElement_RepetitionType 0])))
+  check "footer rejects negative child count"
+    (Footer.readFooterRaw (Thrift.encodeCompact (metadata [TS.SchemaElement_NumChildren (-1)])))
+
+
+dataPageV2CompressionRegression :: IO ()
+dataPageV2CompressionRegression = do
+  let definitions = BS.pack [2, 0] -- One null, RLE level 0 at bit width 1.
+      header compressedSize = encodePageHeader PageHeader
+        { phType = PtDataPageV2 (DataPageHeaderV2 1 1 1 0 2 0 True)
+        , phUncompressedPageSize = Just 2
+        , phCompressedPageSize = Just compressedSize
+        }
+      emptySnappy = header 2 <> definitions
+  expect "V2 all-null page permits absent Snappy values"
+    (Parquet.Read.readGenericFloatOptionalColumnChunk Snappy 0 1 emptySnappy == Right (V.singleton Nothing))
+  case compressPageBytes ZSTD BS.empty of
+    Left e -> failTest e
+    Right compressed -> do
+      let page = header (fromIntegral (BS.length definitions + BS.length compressed)) <> definitions <> compressed
+      expect "V2 all-null page permits compressed empty ZSTD values"
+        (Parquet.Read.readGenericInt32OptionalColumnChunk ZSTD 0 1 page == Right (V.singleton Nothing))
+      let dictionaryHeader = encodePageHeader PageHeader
+            { phType = PtDictionaryPage (DictionaryPageHeader 0 0)
+            , phUncompressedPageSize = Just 0
+            , phCompressedPageSize = Just (fromIntegral (BS.length compressed))
+            }
+          dictionaryData = encodePageHeader PageHeader
+            { phType = PtDataPageV2 (DataPageHeaderV2 1 1 1 8 2 0 True)
+            , phUncompressedPageSize = Just 2
+            , phCompressedPageSize = Just 2
+            }
+          allNullDictionary = dictionaryHeader <> compressed <> dictionaryData <> definitions
+      expect "ZSTD empty dictionary and absent all-null indices decode"
+        (Parquet.Read.readGenericInt32OptionalColumnChunk ZSTD 0 1 allNullDictionary == Right (V.singleton Nothing))
+      expect "public ZSTD decoder accepts a valid empty frame"
+        (Parquet.Read.decompressChunk ZSTD compressed == Right BS.empty)
+  -- Zstandard frame: no frame-content-size field, 1 KiB window,
+  -- one final raw block containing "abc". It is independent of our writer.
+  let unknownSize = BS.pack [0x28, 0xb5, 0x2f, 0xfd, 0x00, 0x00, 0x19, 0x00, 0x00, 0x61, 0x62, 0x63]
+      rawHeader expected = encodePageHeader PageHeader
+        { phType = PtDataPage (DataPageHeader 1 0)
+        , phUncompressedPageSize = Just expected
+        , phCompressedPageSize = Just (fromIntegral (BS.length unknownSize))
+        }
+  expect "public ZSTD decoder accepts a frame without content size"
+    (Parquet.Read.decompressChunk ZSTD unknownSize == Right "abc")
+  expect "public ZSTD decoder rejects truncated unknown-size frames"
+    (isLeft (Parquet.Read.decompressChunk ZSTD (BS.take 11 unknownSize)))
+  case Parquet.Read.decompressDataPageBody ZSTD (rawHeader 3 <> unknownSize) 0 of
+    Left e -> failTest e
+    Right (_, _, body, _) -> expect "page-sized ZSTD decoding accepts omitted frame size" (body == "abc")
+  expect "page-sized ZSTD decoding rejects size mismatch"
+    (isLeft (Parquet.Read.decompressDataPageBody ZSTD (rawHeader 4 <> unknownSize) 0))
+  case encodeOptionalColumnPageV2Parts LZ4Raw (OptInt32 (V.fromList [Just 1, Nothing, Just 3])) of
+    Left e -> failTest e
+    Right (hdr, reps, defs, values) ->
+      expect "V2 LZ4 uses values size without level bytes"
+        (Parquet.Read.readGenericInt32OptionalColumnChunk LZ4Raw 0 1 (hdr <> reps <> defs <> values)
+          == Right (V.fromList [Just 1, Nothing, Just 3]))
+
+
+deltaWideIntegerRegression :: IO ()
+deltaWideIntegerRegression = do
+  let header = [0x80, 0x01, 0x04, 0x01]
+      minimumValue = BS.pack (header ++ replicate 9 0xff ++ [0x01])
+      maximumValue = BS.pack (header ++ [0xfe] ++ replicate 8 0xff ++ [0x01])
+  expect "delta zigzag preserves minBound Int64"
+    (decodeDeltaBinaryPackedInt64 1 minimumValue == Right (VP.singleton minBound))
+  expect "delta zigzag preserves maxBound Int64"
+    (decodeDeltaBinaryPackedInt64 1 maximumValue == Right (VP.singleton maxBound))
+  expect "delta rejects overflowing 64-bit varint"
+    (isLeft (decodeDeltaBinaryPackedInt64 1 (BS.pack (header ++ replicate 9 0xff ++ [0x02]))))
+  expect "delta rejects mismatched page count"
+    (isLeft (decodeDeltaBinaryPackedInt64 2 maximumValue))
+  expect "delta rejects zero-sized miniblocks"
+    (isLeft (decodeDeltaBinaryPackedInt64 2 (BS.pack [0x80, 0x01, 0x80, 0x02, 2, 0])))
+
+
+arrowParquetIntegerTypes :: IO ()
+arrowParquetIntegerTypes = do
+  check "Int8" (AT.AInt 8 True) (AC.fromMaybes AC.PInt8 (V.fromList [Just (minBound :: Int8), Nothing, Just maxBound]))
+  check "Int16" (AT.AInt 16 True) (AC.fromMaybes AC.PInt16 (V.fromList [Just (minBound :: Int16), Nothing, Just maxBound]))
+  check "UInt8" (AT.AInt 8 False) (AC.fromMaybes AC.PUInt8 (V.fromList [Just (0 :: Word8), Nothing, Just maxBound]))
+  check "UInt16" (AT.AInt 16 False) (AC.fromMaybes AC.PUInt16 (V.fromList [Just (0 :: Word16), Nothing, Just maxBound]))
+  check "UInt32" (AT.AInt 32 False) (AC.fromMaybes AC.PUInt32 (V.fromList [Just (0 :: Word32), Nothing, Just maxBound]))
+  check "UInt64" (AT.AInt 64 False) (AC.fromMaybes AC.PUInt64 (V.fromList [Just (0 :: Word64), Nothing, Just maxBound]))
+  where
+    check label ty col = do
+      let field = AT.Field "x" True ty V.empty Nothing V.empty
+          schema = AT.Schema (V.singleton field) AT.Little V.empty V.empty
+      case PArrow.arrowToParquetMixed schema [V.singleton col] of
+        Left e -> failTest (label ++ " encode bridge: " ++ e)
+        Right (ps, groups) -> do
+          let bytes = PHL.encodeParquetMixed PHL.defaultWriteOptions ps groups
+          case PHL.decodeParquet PHL.defaultReadOptions bytes of
+            Left e -> failTest (label ++ " footer: " ++ e)
+            Right pf -> do
+              let recovered = PArrow.parquetFileArrowSchema pf
+              expect (label ++ " retains logical integer type") (AT.arrowFields recovered == AT.arrowFields schema)
+              expect (label ++ " retains unsigned/narrow values and nulls")
+                (PArrow.parquetRowGroupToArrow recovered pf 0 == Right (V.singleton col))
+              case ty of
+                AT.AInt width False -> do
+                  let storageBytes = if width == 64 then 8 else 4
+                      expectedMax = BS.pack (replicate (width `quot` 8) 0xff ++ replicate (storageBytes - width `quot` 8) 0)
+                      chunk = rgColumns (fmRowGroups (pfFooter pf) V.! 0) V.! 0
+                      statistics = ccMetadata chunk >>= cmStatistics
+                  expect (label ++ " statistics use unsigned ordering")
+                    (maybe False (\s -> statMinValue s == Just (BS.replicate storageBytes 0)
+                                      && statMaxValue s == Just expectedMax
+                                      && statMin s == Nothing && statMax s == Nothing
+                                      && statNullCount s == Just 1) statistics)
+                _ -> pure ()
+
+
+predicateRowGroupSkipping :: IO ()
+predicateRowGroupSkipping = do
+  let schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "n" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+        ]
+      vs    = VP.fromList [(10 :: Int32), 20, 30, 40, 50]
+      fbs   = buildParquetFile schema (V.singleton (V.singleton (ColInt32 vs)))
+  case loadParquetFile fbs of
+    Left e -> failTest ("predicate: loadParquetFile: " ++ e)
+    Right pf -> do
+      let !rg = V.unsafeIndex (fmRowGroups (pfFooter pf)) 0
+          fileMetadata = pfFooter pf
+          mkPred cp = Pred.PCol "n" cp
+      expect "PEq 25 outside [10,50] -> Skip"
+        (Pred.evalRowGroup fileMetadata (mkPred (Pred.PEq (Pred.PVInt32 25)))
+                           rg == Pred.PMaybeKeep)
+      expect "PEq 5 below min -> Skip"
+        (Pred.evalRowGroup fileMetadata (mkPred (Pred.PEq (Pred.PVInt32 5)))
+                           rg == Pred.PSkip)
+      expect "PEq 100 above max -> Skip"
+        (Pred.evalRowGroup fileMetadata (mkPred (Pred.PEq (Pred.PVInt32 100)))
+                           rg == Pred.PSkip)
+      expect "PLt 5 -> Skip"
+        (Pred.evalRowGroup fileMetadata (mkPred (Pred.PLt (Pred.PVInt32 5)))
+                           rg == Pred.PSkip)
+      expect "PGtEq 30 inside range -> MaybeKeep"
+        (Pred.evalRowGroup fileMetadata (mkPred (Pred.PGtEq (Pred.PVInt32 30)))
+                           rg == Pred.PMaybeKeep)
+      -- AND short-circuits on a Skip side
+      let pAnd = Pred.PAnd
+                   (mkPred (Pred.PLt (Pred.PVInt32 5)))
+                   (mkPred (Pred.PGt (Pred.PVInt32 0)))
+      expect "AND with skipping side -> Skip"
+        (Pred.evalRowGroup fileMetadata pAnd rg == Pred.PSkip)
+      -- IsNull on no-null column => Skip
+      expect "PIsNull when null_count=0 -> Skip"
+        (Pred.evalRowGroup fileMetadata (mkPred Pred.PIsNull) rg == Pred.PSkip)
+
+-- File-level order is part of the interpretation of modern statistics.
+statisticsOrderingRegression :: IO ()
+statisticsOrderingRegression = do
+  let field = physicalField PTInt32
+      schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , field
+        ]
+      values = V.singleton (ColInt32 (VP.fromList [-1, 0]))
+  file <- either failTest pure (loadParquetFile (buildParquetFile schema (V.singleton values)))
+  let metadata = pfFooter file
+      group = V.head (fmRowGroups metadata)
+      column = V.head (rgColumns group)
+      stats = columnDataStatistics (ColInt32 (VP.fromList [-1, 0]))
+      modernOnly = stats {statMin = Nothing, statMax = Nothing}
+      noOrder = Pred.StatisticsContext field Nothing
+      cannotMatch = Pred.PEq (Pred.PVInt32 10)
+      replaceStats st = column {ccMetadata = fmap (\md -> md {cmStatistics = Just st}) (ccMetadata column)}
+      modernGroup = group {rgColumns = V.singleton (replaceStats modernOnly)}
+      modernMetadata = metadata {fmColumnOrders = Nothing, fmRowGroups = V.singleton modernGroup}
+  expect "modern-only bounds without column_orders cannot prune"
+    (Pred.evalColumnChunk noOrder (replaceStats modernOnly) cannotMatch == Pred.PMaybeKeep
+      && Pred.evalRowGroup modernMetadata (Pred.PCol (seName field) cannotMatch) modernGroup == Pred.PMaybeKeep
+      && PAgg.columnMin modernMetadata 0 == Nothing && PAgg.columnMax modernMetadata 0 == Nothing)
+  expect "legacy signed numeric bounds remain usable without column_orders"
+    (Pred.evalColumnChunk noOrder column cannotMatch == Pred.PSkip
+      && Pred.minimumStatistic noOrder stats == Just (Pred.PVInt32 (-1)))
+  let binaryField = physicalField PTByteArray
+      legacyBinary = columnDataStatistics (ColByteArray (V.fromList ["a", "z"]))
+  expect "legacy signed byte bounds cannot establish unsigned binary order"
+    (Pred.minimumStatistic (Pred.StatisticsContext binaryField Nothing) legacyBinary == Nothing)
+  let index = ColumnIndex
+        { ciNanCounts = Nothing
+        , ciNullPages = V.fromList [False, True]
+        , ciMinValues = V.fromList [BS.pack [255,255,255,255], BS.empty]
+        , ciMaxValues = V.fromList [BS.replicate 4 0, BS.empty]
+        , ciBoundaryOrder = OrderAscending
+        , ciNullCounts = Just (V.fromList [0, 2])
+        , ciRepetitionLevelHistograms = Nothing
+        , ciDefinitionLevelHistograms = Nothing
+        }
+  expect "page bounds need an order while all-null pages remain skippable"
+    (Pred.evalPagesByColumnIndex noOrder index cannotMatch == V.fromList [Pred.PMaybeKeep, Pred.PSkip])
+  let missingOrderRaw = case Footer.fileMetadataToThrift modernMetadata of
+        TV.Struct fields -> Thrift.encodeCompact (TV.Struct fields)
+        _ -> error "expected footer struct"
+  parsedMissing <- either failTest pure (Footer.readFooterRaw missingOrderRaw)
+  expect "reading a footer without orders preserves raw modern metadata"
+    ((ccMetadata (V.head (rgColumns (V.head (fmRowGroups parsedMissing)))) >>= cmStatistics) == Just modernOnly)
+  let unknownAnnotations =
+        [ V.singleton (127, TV.Struct V.empty)
+        , V.empty
+        , V.fromList [(1, TV.Struct V.empty), (127, TV.Struct V.empty)]
+        , V.singleton (8, TV.Struct (V.fromList
+            [(1, TV.Bool True), (2, TV.Struct (V.singleton (127, TV.Struct V.empty)))]))
+        ]
+      replaceAnnotation annotation = case Footer.fileMetadataToThrift metadata of
+        TV.Struct fields -> TV.Struct (V.map (\entry -> case entry of
+          TS.FileMetadata_Schema elements -> TS.FileMetadata_Schema (V.imap (\i element ->
+            if i == 0 then element else case element of
+              TV.Struct fields' -> TV.Struct (V.filter (\entry' -> case entry' of
+                TS.SchemaElement_LogicalType _ -> False
+                TS.SchemaElement_ConvertedType _ -> False
+                _ -> True) fields' V.++ V.fromList
+                  [TS.SchemaElement_ConvertedType 13, TS.SchemaElement_LogicalType annotation])
+              other -> other) elements)
+          other -> other) fields)
+        other -> other
+  mapM_ (\annotation -> do
+    parsed <- either failTest pure (Footer.readFooterRaw (Thrift.encodeCompact (replaceAnnotation annotation)))
+    let decodedField = fmSchema parsed V.! 1
+        decodedColumn = V.head (rgColumns (V.head (fmRowGroups parsed)))
+        arrowSchema = PArrow.parquetFileArrowSchema (file {pfFooter = parsed})
+    expect "unknown logical annotations cannot inherit obsolete unsigned semantics"
+      (seLogicalType decodedField == Just LTUnsupported && seConvertedType decodedField == Nothing
+        && AT.fieldType (V.head (AT.arrowFields arrowSchema)) == AT.AInt 32 True)
+    expect "unknown annotations never provide ordered bounds"
+      (Pred.decodePValueForSchema decodedField (BS.replicate 4 0) == Nothing
+        && (ccMetadata decodedColumn >>= cmStatistics >>= statMinValue) == Nothing)
+    checked <- buildParquetFileWithIndexIO (fmSchema parsed) (V.singleton values)
+      (V.singleton (V.singleton emptyColumnAux))
+    expect "writer rejects unsupported logical annotations" (isLeft checked)
+    emptyChecked <- buildParquetFileWithIndexIO (fmSchema parsed) V.empty V.empty
+    expect "empty writer also rejects unsupported logical annotations" (isLeft emptyChecked)) unknownAnnotations
+  let externalFile = file {pfFooter = metadata {fmRowGroups = V.singleton
+        (group {rgColumns = V.singleton (column {ccFilePath = Just "part-00001.parquet"})})}}
+  expect "external chunks cannot read unrelated bytes from the metadata file"
+    (isLeft (Parquet.Read.columnChunkSlice externalFile 0 0))
+  expect "external chunks cannot read unrelated page indexes"
+    (isLeft (readOffsetIndex externalFile 0 0) && isLeft (readColumnIndex externalFile 0 0))
+  let emptyPathFile = file {pfFooter = metadata {fmRowGroups = V.singleton
+        (group {rgColumns = V.singleton (column {ccFilePath = Just mempty})})}}
+  expect "empty external path retains local column reading"
+    (Parquet.Read.columnChunkSlice emptyPathFile 0 0 == Parquet.Read.columnChunkSlice file 0 0)
+
+
+predicatePageSkipping :: IO ()
+predicatePageSkipping = do
+  -- Build a synthetic ColumnIndex for an int32 column with two
+  -- pages: page 0 has [1..10], page 1 has [50..60].
+  let mins = V.fromList
+               [ BS.pack [1, 0, 0, 0]
+               , BS.pack [50, 0, 0, 0]
+               ]
+      maxs = V.fromList
+               [ BS.pack [10, 0, 0, 0]
+               , BS.pack [60, 0, 0, 0]
+               ]
+      ci = ColumnIndex
+             { ciNanCounts = Nothing
+             , ciNullPages = V.fromList [False, False]
+             , ciMinValues = mins
+             , ciMaxValues = maxs
+             , ciBoundaryOrder = OrderAscending
+             , ciNullCounts   = Nothing
+             , ciRepetitionLevelHistograms = Nothing
+             , ciDefinitionLevelHistograms = Nothing
+             }
+      decisions = Pred.evalPagesByColumnIndex (knownContext (physicalField PTInt32)) ci
+                    (Pred.PEq (Pred.PVInt32 30))
+  expect "page 0 ([1,10]) skips for =30"
+    (V.unsafeIndex decisions 0 == Pred.PSkip)
+  expect "page 1 ([50,60]) skips for =30"
+    (V.unsafeIndex decisions 1 == Pred.PSkip)
+  let decisions2 = Pred.evalPagesByColumnIndex (knownContext (physicalField PTInt32)) ci
+                     (Pred.PEq (Pred.PVInt32 5))
+  expect "page 0 keeps for =5"
+    (V.unsafeIndex decisions2 0 == Pred.PMaybeKeep)
+  expect "page 1 skips for =5"
+    (V.unsafeIndex decisions2 1 == Pred.PSkip)
+  let malformed = ci {ciMinValues = V.take 1 mins}
+  expect "malformed page bounds never reach unchecked indexing"
+    (Pred.evalPagesByColumnIndex (knownContext (physicalField PTInt32)) malformed (Pred.PEq (Pred.PVInt32 30))
+      == V.replicate 2 Pred.PMaybeKeep)
+  mapM_ (\broken -> expect "malformed column-index vectors reject during decoding"
+    (isLeft (decodeColumnIndex (encodeColumnIndex broken))))
+    [ malformed
+    , ci {ciMaxValues = V.empty}
+    , ci {ciNullCounts = Just (V.singleton 0)}
+    , ci {ciNanCounts = Just (V.singleton 0)}
+    , ci {ciNanCounts = Just (V.fromList [-1, 0])}
+    ]
+
+logicalTypeRoundTrip :: IO ()
+logicalTypeRoundTrip = do
+  -- Build a footer that exercises a handful of LogicalType
+  -- variants (the modern slot, field 10) and assert they
+  -- survive a thrift round-trip through readFooterRaw.
+  let cases =
+        [ ("string-col",  PTByteArray, Just LTString)
+        , ("date-col",    PTInt32,     Just LTDate)
+        , ("time-millis", PTInt32,     Just (LTTime False LtMillis))
+        , ("time-micros", PTInt64,     Just (LTTime True  LtMicros))
+        , ("ts-nanos",    PTInt64,     Just (LTTimestamp True  LtNanos))
+        , ("dec-12-3",    PTFixedLenByteArray, Just (LTDecimal 12 3))
+        , ("uuid-col",    PTFixedLenByteArray, Just LTUUID)
+        , ("uint8-col",   PTInt32,     Just (LTInteger 8 False))
+        , ("float16-col", PTFixedLenByteArray, Just LTFloat16)
+        , ("variant-col", PTByteArray, Just (LTVariant 1))
+        , ("geom-col",    PTByteArray, Just (LTGeometry defaultGeometryParameters))
+        , ("geog-col",    PTByteArray, Just (LTGeography defaultGeographyParameters))
+        ]
+      mkSe (nm, pt, lt) =
+        SchemaElement
+          { seTypeLength = if pt == PTFixedLenByteArray then Just (if lt == Just LTFloat16 then 2 else 16) else Nothing
+            , seName          = nm
+          , seRepetition    = Just Required
+          , seType          = Just pt
+          , seNumChildren   = Nothing
+          , seConvertedType = Nothing
+          , seLogicalType   = lt
+          , seFieldId       = Nothing
+          }
+      schema = V.fromList $
+        SchemaElement "schema" Nothing Nothing
+          (Just (fromIntegral (length cases))) Nothing Nothing Nothing Nothing
+        : map mkSe cases
+      vs = VP.fromList [(0 :: Int32)]
+      cdata = ColInt32 vs
+      -- Reuse the buildParquetFile entry for one stripe; the
+      -- LogicalType slots ride along the schema regardless of
+      -- which physical types the column data actually use.
+      fbs = buildParquetFile
+              (V.fromList
+                 [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+                 , SchemaElement "n" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+                 ])
+              (V.singleton (V.singleton cdata))
+  -- The builder above ignores schema beyond the data layout; we
+  -- exercise the LogicalType round-trip by serialising a
+  -- standalone footer instead.
+  _ <- pure fbs
+  let fmRaw = FileMetadata
+                { fmVersion   = 1
+                , fmSchema    = schema
+                , fmNumRows   = 0
+                , fmRowGroups = V.empty
+                , fmCreatedBy = Just "wireform"
+                , fmKeyValueMetadata = Nothing
+                , fmColumnOrders = Nothing
+                }
+  let bytes = Footer.writeFooter fmRaw
+  -- buildParquetFile pads with magic; readFooter wants the
+  -- same envelope. Just write a self-contained PAR1 footer
+  -- and round-trip via readFooterRaw on the inner thrift bytes.
+  let trailer = either error id (Footer.readFooterTrailer (parquetMagic <> bytes))
+      raw     = ftBytes trailer
+  case Footer.readFooterRaw raw of
+    Left e -> failTest $ "logicalType: readFooterRaw: " ++ e
+    Right fmDecoded -> do
+      let recovered = V.toList (V.drop 1 (fmSchema fmDecoded))
+      flip mapM_ (zip cases recovered) $ \((nm, _, expected), got) -> do
+        expect ("LogicalType " ++ T.unpack nm ++ " round-trip")
+               (seLogicalType got == expected)
+
+-- Explicit Thrift union tags/parameter fields provide an independent wire
+-- oracle. Re-encoding must retain optional-field presence, not just defaults.
+logicalParameterRegression :: IO ()
+logicalParameterRegression = do
+  let geometry = LTGeometry . GeometryParameters
+      geography crs algorithm = LTGeography (GeographyParameters crs algorithm)
+      annotation tag fields = TV.Struct (V.singleton (tag, TV.Struct (V.fromList fields)))
+      cases =
+        [ (annotation 17 [], geometry Nothing)
+        , (annotation 17 [(1, TV.Binary "EPSG:3857")], geometry (Just "EPSG:3857"))
+        , (annotation 17 [(1, TV.Binary BS.empty)], geometry (Just ""))
+        , (annotation 18 [], geography Nothing Nothing)
+        , (annotation 18 [(1, TV.Binary "EPSG:4326")], geography (Just "EPSG:4326") Nothing)
+        ]
+      algorithms =
+        [ (minBound, UnrecognizedInterpolation minBound)
+        , (-1, UnrecognizedInterpolation (-1))
+        , (0, Spherical)
+        , (1, Vincenty)
+        , (2, Thomas)
+        , (3, Andoyer)
+        , (4, Karney)
+        , (127, UnrecognizedInterpolation 127)
+        , (maxBound, UnrecognizedInterpolation maxBound)
+        ]
+      algorithmCase (code, algorithm) =
+        ( annotation 18 [(1, TV.Binary "projjson:custom"), (2, TV.I32 code)]
+        , geography (Just "projjson:custom") (Just algorithm)
+        )
+      checkCase (raw, expected) = do
+        decoded <- decodeFixture False raw
+        expect
+          "geospatial parameters retain optional presence and full-width enums"
+          (seLogicalType (fmSchema decoded V.! 1) == Just expected)
+        expect
+          "geospatial writer emits independent CRS/interpolation wire fields"
+          ((Thrift.encodeCompact <$> findAnnotation decoded) == Just (Thrift.encodeCompact raw))
+        expect
+          "parameterized geospatial annotations retain undefined min/max order"
+          (not (hasDefinedStatisticsOrder (fmSchema decoded V.! 1)))
+  mapM_ checkCase (cases ++ map algorithmCase algorithms)
+  mapM_
+    ( \(code, algorithm) ->
+        checkCase
+          (annotation 18 [(2, TV.I32 code)], geography Nothing (Just algorithm))
+    )
+    algorithms
+  mapM_
+    ( \raw -> do
+        decoded <- decodeFixture False raw
+        expect
+          "malformed geospatial parameters use physical fallback instead of defaults"
+          (seLogicalType (fmSchema decoded V.! 1) == Just LTUnsupported)
+    )
+    [ annotation 17 [(1, TV.I32 1)]
+    , annotation 17 [(1, TV.Binary (BS.singleton 255))]
+    , annotation 17 [(1, TV.Binary "a"), (1, TV.Binary "b")]
+    , annotation 18 [(2, TV.Binary "0")]
+    , annotation 18 [(2, TV.I32 0), (2, TV.I32 1)]
+    ]
+  extended <- decodeFixture False (annotation 18 [(2, TV.I32 4), (99, TV.I32 7)])
+  expect
+    "unknown future geospatial fields do not discard known parameters"
+    (seLogicalType (fmSchema extended V.! 1) == Just (geography Nothing (Just Karney)))
+  file <- decodeFixture True (annotation 19 [])
+  let fileGroup = fmSchema file V.! 1
+  expect
+    "FILE union tag19 retains its group annotation"
+    (seLogicalType fileGroup == Just LTFile && hasCompatiblePhysicalType fileGroup)
+  expect
+    "FILE annotation writer emits the independent tag19 bytes"
+    ((Thrift.encodeCompact <$> findAnnotation file) == Just (Thrift.encodeCompact (annotation 19 [])))
+  expect
+    "FILE cannot annotate scalar storage"
+    (not (hasCompatiblePhysicalType (fileGroup {seType = Just PTByteArray})))
+  where
+    decodeFixture group raw =
+      let root = SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+          field =
+            SchemaElement
+              "x"
+              (Just Optional)
+              (if group then Nothing else Just PTByteArray)
+              (if group then Just 1 else Nothing)
+              Nothing
+              Nothing
+              Nothing
+              Nothing
+          inline = SchemaElement "inline" (Just Optional) (Just PTByteArray) Nothing Nothing Nothing Nothing Nothing
+          schema = V.fromList (if group then [root, field, inline] else [root, field])
+          metadata = FileMetadata 1 schema 0 V.empty Nothing Nothing Nothing
+          update (2, TV.List ty fields) =
+            ( 2
+            , TV.List
+                ty
+                ( V.imap
+                    ( \index value -> case value of
+                        TV.Struct body | index == 1 -> TV.Struct (V.snoc body (10, raw))
+                        _ -> value
+                    )
+                    fields
+                )
+            )
+          update value = value
+          wire = case Footer.fileMetadataToThrift metadata of
+            TV.Struct fields -> TV.Struct (V.map update fields)
+            _ -> error "expected footer struct"
+      in either failTest pure (Footer.readFooterRaw (Thrift.encodeCompact wire))
+    findAnnotation metadata = do
+      TV.Struct fields <- Just (Footer.fileMetadataToThrift metadata)
+      TV.List _ schema <- lookup 2 (V.toList fields)
+      TV.Struct field <- schema V.!? 1
+      lookup 10 (V.toList field)
+emptyColumnChunkRegression :: IO ()
+emptyColumnChunkRegression = do
+  let schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "x" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+        ]
+      bytes = buildParquetFile schema (V.singleton (V.singleton (ColInt32 VP.empty)))
+  case loadParquetFile bytes of
+    Left err -> failTest err
+    Right pf -> do
+      let metadata = pfFooter pf
+          rg = fmRowGroups metadata V.! 0
+          chunk = rgColumns rg V.! 0
+          -- Some zero-row writers advertise offsets at zero and nonzero
+          -- compressed sizes; those bytes are not pages when num_values=0.
+          changed = chunk {ccMetadata = fmap
+            (\md -> md {cmNumValues = 0, cmDataPageOffset = 0, cmTotalCompressedSize = 14})
+            (ccMetadata chunk)}
+          file = pf {Parquet.Read.pfFooter = metadata {fmRowGroups = V.singleton
+            (rg {rgColumns = V.singleton changed})}}
+      expect "zero-value column chunks do not parse file magic as pages"
+        (Parquet.Read.columnChunkSlice file 0 0 == Right BS.empty)
+      expect "zero-value columns retain their empty Arrow shape"
+        (PArrow.parquetRowGroupToArrow (PArrow.parquetFileArrowSchema file) file 0
+          == Right (V.singleton (AC.primColumn AC.PInt32 VS.empty)))
+
+
+fixedDecimalMetadataRegression :: IO ()
+fixedDecimalMetadataRegression = do
+  let schema fields = V.fromList
+        [ TV.Struct (V.fromList [TS.SchemaElement_Name "schema", TS.SchemaElement_NumChildren 1])
+        , TV.Struct (V.fromList (TS.SchemaElement_Name "x" : TS.SchemaElement_RepetitionType 0 : fields))
+        ]
+      footer fields = TV.Struct $ V.fromList
+        [ TS.FileMetadata_Version 1
+        , TS.FileMetadata_Schema (schema fields)
+        , TS.FileMetadata_NumRows 0
+        , TS.FileMetadata_RowGroups V.empty
+        ]
+      decode = Footer.thriftToFileMetadata . footer
+      legacy = [ TS.SchemaElement_Type 7, TS.SchemaElement_TypeLength 7
+               , TS.SchemaElement_ConvertedType 5, TS.SchemaElement_Precision 16
+               , TS.SchemaElement_Scale 4 ]
+  case decode legacy of
+    Left err -> failTest err
+    Right metadata -> do
+      let leaf = fmSchema metadata V.! 1
+      expect "legacy DECIMAL precision and scale are restored"
+        (seLogicalType leaf == Just (LTDecimal 16 4))
+      expect "fixed byte width survives decoding" (seTypeLength leaf == Just 7)
+      case Footer.readFooterRaw (Thrift.encodeCompact (Footer.fileMetadataToThrift metadata)) of
+        Left err -> failTest err
+        Right restored -> expect "fixed DECIMAL width survives a footer round-trip"
+          (fmSchema restored == fmSchema metadata)
+      case Footer.fileMetadataToThrift metadata of
+        TV.Struct fields ->
+          let schemas = V.mapMaybe (\case TS.FileMetadata_Schema xs -> Just xs; _ -> Nothing) fields
+              leaves = V.concatMap (V.drop 1) schemas
+              fieldsOf = V.concatMap (\case TV.Struct xs -> xs; _ -> V.empty) leaves
+          in expect "modern DECIMAL also emits legacy precision and scale"
+            (V.elem (TS.SchemaElement_Precision 16) fieldsOf
+             && V.elem (TS.SchemaElement_Scale 4) fieldsOf)
+        _ -> failTest "footer did not encode as a struct"
+  mapM_ (\fields -> expect "invalid fixed/DECIMAL metadata is rejected" (isLeft (decode fields)))
+    [ [TS.SchemaElement_Type 7]
+    , [TS.SchemaElement_Type 7, TS.SchemaElement_TypeLength 0]
+    , [TS.SchemaElement_Type 7, TS.SchemaElement_TypeLength (-1)]
+    , [TS.SchemaElement_Type 1, TS.SchemaElement_TypeLength (-1)]
+    , [TS.SchemaElement_Type 1, TS.SchemaElement_ConvertedType 5]
+    , [TS.SchemaElement_Type 1, TS.SchemaElement_ConvertedType 5, TS.SchemaElement_Precision 10]
+    , [TS.SchemaElement_Type 2, TS.SchemaElement_ConvertedType 5, TS.SchemaElement_Precision 19]
+    , [TS.SchemaElement_Type 7, TS.SchemaElement_TypeLength 1, TS.SchemaElement_ConvertedType 5, TS.SchemaElement_Precision 3]
+    , [TS.SchemaElement_Type 6, TS.SchemaElement_ConvertedType 5, TS.SchemaElement_Precision 2, TS.SchemaElement_Scale 3]
+    ]
+
+
+-- | Random-input round-trips for every encoder/decoder pair.
+-- Uses a fixed seed so failures reproduce; covers
+-- DELTA_BINARY_PACKED Int32/Int64, DELTA_LENGTH_BYTE_ARRAY,
+-- DELTA_BYTE_ARRAY, BYTE_STREAM_SPLIT Float/Double, and the
+-- predicate evaluator's range arithmetic.
+encodingRoundTripProperties :: IO ()
+encodingRoundTripProperties = do
+  let seed = 0xC0FFEE :: Int
+      cases = 50
+      -- Cheap LCG; we don't need cryptographic quality.
+      lcg s = (s * 1103515245 + 12345) `mod` 0x100000000
+      mkInts32 s n = take n (drop 1 (iterate lcg s))
+        & map (\x -> fromIntegral (x `mod` 0x100000000) :: Int32)
+      mkInts64 s n = take n (drop 1 (iterate lcg s))
+        & map fromIntegral
+      mkFloats s n = map (\x -> fromIntegral x / 1000.0)
+                       (mkInts32 s n)
+      mkDoubles s n = map (\x -> fromIntegral (x :: Int64) / 1000000.0)
+                        (mkInts64 s n)
+      (&) :: a -> (a -> b) -> b
+      a & f = f a
+
+  -- DELTA_BINARY_PACKED Int32
+  do
+    let pass i =
+          let !n = (i `mod` 32) + 1
+              !s = seed + i
+              !vs = VP.fromList (mkInts32 s n)
+          in case decodeDeltaBinaryPackedInt64
+                   (VP.length vs)
+                   (encodeDeltaBinaryPackedInt32 vs) of
+               Right got
+                 | VP.toList (VP.map (fromIntegral :: Int64 -> Int32) got)
+                     == VP.toList vs -> True
+               _ -> False
+    let !okCount = length (filter pass [1 .. cases])
+    expect ("DELTA_BINARY_PACKED Int32 property: "
+              ++ show okCount ++ "/" ++ show cases)
+           (okCount == cases)
+
+  -- DELTA_BINARY_PACKED Int64
+  do
+    let pass i =
+          let !n = (i `mod` 32) + 1
+              !s = seed + i + 1
+              !vs = VP.fromList (mkInts64 s n)
+          in case decodeDeltaBinaryPackedInt64
+                   (VP.length vs)
+                   (encodeDeltaBinaryPackedInt64 vs) of
+               Right got | VP.toList got == VP.toList vs -> True
+               _ -> False
+    let !okCount = length (filter pass [1 .. cases])
+    expect ("DELTA_BINARY_PACKED Int64 property: "
+              ++ show okCount ++ "/" ++ show cases)
+           (okCount == cases)
+
+  -- BYTE_STREAM_SPLIT Float
+  do
+    let pass i =
+          let !n = (i `mod` 16) + 1
+              !s = seed + i + 2
+              !vs = VP.fromList (mkFloats s n)
+          in case decodeByteStreamSplitFloat
+                   (VP.length vs)
+                   (encodeByteStreamSplitFloat vs) of
+               Right got | VP.toList got == VP.toList vs -> True
+               _ -> False
+    let !okCount = length (filter pass [1 .. cases])
+    expect ("BYTE_STREAM_SPLIT Float property: "
+              ++ show okCount ++ "/" ++ show cases)
+           (okCount == cases)
+
+  -- BYTE_STREAM_SPLIT Double
+  do
+    let pass i =
+          let !n = (i `mod` 16) + 1
+              !s = seed + i + 3
+              !vs = VP.fromList (mkDoubles s n)
+          in case decodeByteStreamSplitDouble
+                   (VP.length vs)
+                   (encodeByteStreamSplitDouble vs) of
+               Right got | VP.toList got == VP.toList vs -> True
+               _ -> False
+    let !okCount = length (filter pass [1 .. cases])
+    expect ("BYTE_STREAM_SPLIT Double property: "
+              ++ show okCount ++ "/" ++ show cases)
+           (okCount == cases)
+
+  -- DELTA_LENGTH_BYTE_ARRAY
+  do
+    let pass i =
+          let !n = (i `mod` 8) + 1
+              !vs = V.fromList
+                [ BSC.pack ("v_" ++ show j ++ "_" ++ replicate (j `mod` 5) 'x')
+                | j <- [0 .. n - 1]
+                ]
+          in case decodeDeltaLengthByteArray
+                   (V.length vs)
+                   (encodeDeltaLengthByteArray vs) of
+               Right got | V.toList got == V.toList vs -> True
+               _ -> False
+    let !okCount = length (filter pass [1 .. cases])
+    expect ("DELTA_LENGTH_BYTE_ARRAY property: "
+              ++ show okCount ++ "/" ++ show cases)
+           (okCount == cases)
+
+  -- DELTA_BYTE_ARRAY
+  do
+    let pass i =
+          let !n = (i `mod` 8) + 1
+              -- Build a sequence with non-trivial common
+              -- prefixes so the prefix-compression actually
+              -- exercises the front-coding path.
+              !vs = V.fromList
+                [ BSC.pack ("alphabet" ++ replicate (j `mod` 4) 'z')
+                | j <- [0 .. n - 1]
+                ]
+          in case decodeDeltaByteArray
+                   (V.length vs)
+                   (encodeDeltaByteArray vs) of
+               Right got | V.toList got == V.toList vs -> True
+               _ -> False
+    let !okCount = length (filter pass [1 .. cases])
+    expect ("DELTA_BYTE_ARRAY property: "
+              ++ show okCount ++ "/" ++ show cases)
+           (okCount == cases)
+
+-- | encodeParquet with writeBloomFilters set should emit a
+-- bloom-filter region for the named column and stamp
+-- (offset, length) on its column metadata. The resulting
+-- filter should pass membership tests for every value the
+-- writer saw and reject obviously-absent values (modulo the
+-- nominal false-positive rate).
+highLevelBloomFilters :: IO ()
+highLevelBloomFilters = do
+  let !schema = V.fromList
+        [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+        , SchemaElement "sku" (Just Required) (Just PTByteArray) Nothing
+            (Just CTUtf8) Nothing Nothing Nothing
+        ]
+      !skus = V.fromList
+        [ BSC.pack "AAA001", BSC.pack "AAA002", BSC.pack "BBB100"
+        , BSC.pack "CCC999", BSC.pack "AAA001"
+        ]
+      !batch = V.singleton (ColByteArray skus)
+      !opts  = PHL.defaultWriteOptions
+                 { PHL.writePageVersion  = PageV1
+                 , PHL.writeCompression  = Uncompressed
+                 , PHL.writeBloomFilters = ["sku"]
+                 }
+      !bytes = PHL.encodeParquet opts schema [batch]
+  case loadParquetFile bytes of
+    Left e  -> failTest $ "highLevelBloom loadParquetFile: " ++ e
+    Right pf -> do
+      let !rg = V.unsafeIndex (fmRowGroups (pfFooter pf)) 0
+          !cc = V.unsafeIndex (rgColumns rg) 0
+      case ccMetadata cc of
+        Nothing -> failTest "highLevelBloom: column metadata missing"
+        Just md -> do
+          expect "highLevelBloom: writes bloom-filter offset"
+            (cmBloomFilterOffset md /= Nothing)
+          expect "highLevelBloom: writes bloom-filter length"
+            (cmBloomFilterLength md /= Nothing)
+          case (cmBloomFilterOffset md, cmBloomFilterLength md) of
+            (Just off, Just len) -> do
+              let !o   = fromIntegral off :: Int
+                  !l   = fromIntegral len :: Int
+                  !blob = BS.take l (BS.drop o bytes)
+              case decodeBloomFilter blob of
+                Left e -> failTest $ "highLevelBloom decodeBloomFilter: " ++ e
+                Right (_, sbbf) -> do
+                  expect "highLevelBloom: present sku passes filter"
+                    (sbbfCheck (BSC.pack "AAA001") sbbf)
+                  expect "highLevelBloom: present sku BBB100 passes filter"
+                    (sbbfCheck (BSC.pack "BBB100") sbbf)
+                  -- A sku that wasn't inserted /almost certainly/
+                  -- doesn't pass; with a 1% FPP at ~5 distinct
+                  -- entries the chance of a false positive on
+                  -- this one literal is negligible.
+                  expect "highLevelBloom: absent sku rejected"
+                    (not (sbbfCheck (BSC.pack "ZZZZZ") sbbf))
+            _ -> failTest "highLevelBloom: missing offset/length"
+
+-- | Synthesize column chunks that exercise encoding paths the
+-- wireform writer doesn't naturally produce — DELTA_BINARY_PACKED
+-- INT32, BYTE_STREAM_SPLIT FLOAT, DELTA_BYTE_ARRAY and
+-- DATA_PAGE_V2 — and round-trip them through the generic chunk
+-- readers.
+jsonExtensionRegression :: IO ()
+jsonExtensionRegression = do
+  let field = AT.Field "doc" True AT.AUtf8 V.empty Nothing
+        (V.fromList [("ARROW:extension:name", "arrow.json"), ("ARROW:extension:metadata", "{}")])
+      schema = AT.Schema (V.singleton field) AT.Little V.empty V.empty
+      column = AC.fromMaybeTexts (V.fromList [Just "{\"k\":1}", Nothing, Just "[true,null]"])
+  (physical, groups) <- either failTest pure (PArrow.arrowToParquetMixed schema [V.singleton column])
+  expect "Arrow JSON writes Parquet JSON annotations"
+    (seLogicalType (physical V.! 1) == Just LTJson && seConvertedType (physical V.! 1) == Just CTJson)
+  file <- either failTest pure (loadParquetFile (PHL.encodeParquetMixed PHL.defaultWriteOptions physical groups))
+  expect "Arrow JSON metadata survives a file round-trip"
+    (PArrow.parquetFileArrowSchemaChecked file == Right schema)
+  expect "Arrow JSON storage survives a file round-trip"
+    (PArrow.parquetRowGroupToArrow schema file 0 == Right (V.singleton column))
+  nestedSchema <- either failTest pure (PArrow.arrowFieldToNestedSchema field)
+  rows <- either failTest pure (PArrow.columnArrayToNestedRows field column)
+  nestedBytes <- either failTest pure (Nested.buildNestedFile (V.singleton ("doc", nestedSchema)) (V.singleton rows))
+  nested <- either failTest pure (loadParquetFile nestedBytes)
+  expect "nested writer retains JSON annotations"
+    (PArrow.parquetFileArrowSchemaChecked nested == Right schema)
+
+
+nestedReadRegression :: IO ()
+nestedReadRegression = do
+  expect "nested writer rejects values of the wrong physical type"
+    (isLeft (Nested.buildNestedFile
+      (V.singleton ("x", Nested.NSPrimitive Nested.LtInt32))
+      (V.singleton (V.singleton (Nested.NRLeaf (Nested.LvDouble 1.5))))))
+  let primitive name ty nullable = AT.Field name nullable ty V.empty Nothing V.empty
+      childI = primitive "value" (AT.AInt 32 True) False
+      childD = primitive "value" (AT.AFloatingPoint AT.DoublePrecision) False
+      struct name child = AT.Field name False AT.AStruct (V.singleton child) Nothing V.empty
+      fields = V.fromList [struct "left" childI, struct "right" childD]
+      schema = AT.Schema fields AT.Little V.empty V.empty
+      integers = AC.primColumn AC.PInt32 (VS.fromList [10,20])
+      doubles = AC.primColumn AC.PDouble (VS.fromList [1.5,2.5])
+  left <- either failTest pure (AC.mkStruct 2 Nothing (V.singleton ("value", integers)))
+  right <- either failTest pure (AC.mkStruct 2 Nothing (V.singleton ("value", doubles)))
+  nested <- either failTest pure (V.mapM PArrow.arrowFieldToNestedSchema fields)
+  columns <- either failTest pure (V.zipWithM PArrow.columnArrayToNestedRows fields (V.fromList [left,right]))
+  bytes <- either failTest pure (Nested.buildNestedFile
+    (V.zip (AT.fieldName <$> fields) nested)
+    columns)
+  pf <- either failTest pure (loadParquetFile bytes)
+  inferred <- either failTest pure (PArrow.parquetFileArrowSchemaChecked pf)
+  expect "nested schema preserves parents and duplicate leaf names" (inferred == schema)
+  let malformed = pf {Parquet.Read.pfFooter = (pfFooter pf)
+        {fmSchema = V.empty}}
+      duplicates = pf {Parquet.Read.pfFooter = (pfFooter pf)
+        {fmSchema = V.map (\node -> if seName node == "right" then node {seName = "left"} else node)
+          (fmSchema (pfFooter pf))}}
+  expect "checked schema inference rejects a missing root"
+    (isLeft (PArrow.parquetFileArrowSchemaChecked malformed))
+  expect "high-level decode reports malformed schema trees before returning a file"
+    (case PHL.decodeParquet PHL.defaultReadOptions (parquetMagic <> Footer.writeFooter (pfFooter malformed)) of
+      Left err -> "missing its root" `isInfixOf` err
+      Right _ -> False)
+  expect "checked schema inference rejects duplicate siblings"
+    (isLeft (PArrow.parquetFileArrowSchemaChecked duplicates))
+  let decoded = PArrow.parquetRowGroupToArrow inferred pf 0
+  unless (decoded == Right (V.fromList [left,right]))
+    (failTest ("nested struct leaves keep their own physical column ordinals: " ++ show decoded))
+  let mapSchema = Nested.NSRequired (Nested.NSMap
+        (Nested.NSRequired (Nested.NSPrimitive Nested.LtInt32))
+        (Nested.NSOptional (Nested.NSPrimitive Nested.LtInt32)))
+      pair k v = (Nested.NRLeaf (Nested.LvInt32 k), Nested.NRLeaf (Nested.LvInt32 v))
+      rows = V.singleton (V.fromList
+        [ Nested.NRMapEntries (V.fromList [pair 1 10, pair 2 20])
+        , Nested.NRMapEntries (V.singleton (pair 3 30)) ])
+  mapBytes <- either failTest pure (Nested.buildNestedFile (V.singleton ("m",mapSchema)) rows)
+  mapFile <- either failTest pure (loadParquetFile mapBytes)
+  expect "direct physical-leaf reads reject repeated containers"
+    (isLeft (PArrow.readParquetColumn mapFile 0 0
+      (primitive "key" (AT.AInt 32 True) True)))
+  let nullableStruct = Nested.NSOptional (Nested.NSStruct (V.singleton
+        ("value", Nested.NSRequired (Nested.NSPrimitive Nested.LtInt32))))
+  nullableBytes <- either failTest pure (Nested.buildNestedFile (V.singleton ("parent", nullableStruct))
+    (V.singleton (V.fromList [Nested.NRNull, Nested.NRStruct (V.singleton (Nested.NRLeaf (Nested.LvInt32 42)))])))
+  nullableFile <- either failTest pure (loadParquetFile nullableBytes)
+  nullableValue <- either failTest pure (PArrow.readParquetColumn nullableFile 0 0
+    (primitive "value" (AT.AInt 32 True) True))
+  expect "direct required-leaf reads preserve nullable ancestors"
+    (case AC.asPrim AC.PInt32 nullableValue of
+      Just array -> AC.primAt array 0 == Nothing && AC.primAt array 1 == Just 42
+      Nothing -> False)
+  expect "direct required-leaf reads cannot hide null ancestors from a required target"
+    (isLeft (PArrow.readParquetColumn nullableFile 0 0 (primitive "value" (AT.AInt 32 True) False)))
+  let metadata = (rgColumns (fmRowGroups (pfFooter mapFile) V.! 0) V.! 1)
+  valueMetadata <- maybe (failTest "missing map value metadata") pure (ccMetadata metadata)
+  (header, body) <- either failTest pure (readPageHeaderAt mapBytes (fromIntegral (cmDataPageOffset valueMetadata)))
+  case phType header of
+    PtDataPageV2 page -> do
+      expect "nested V2 page counts rows independently of repeated events"
+        (dph2NumRows page == 2 && dph2NumValues page == 3)
+      let changed = LE.encodeRLEHybrid 1 (VP.fromList [0,0,1])
+          repLength = fromIntegral (dph2RepLevelsLen page)
+      expect "map mismatch regression preserves page lengths" (BS.length changed == repLength)
+      corrupt <- either failTest pure (loadParquetFile (BS.take body mapBytes <> changed <> BS.drop (body + repLength) mapBytes))
+      let result = PArrow.parquetRowGroupToArrow (PArrow.parquetFileArrowSchema corrupt) corrupt 0
+      expect "map siblings with equal totals but different row boundaries are rejected"
+        (case result of Left err -> "siblings disagree" `isInfixOf` show err; Right _ -> False)
+    _ -> failTest "expected a V2 map page"
+
+
+legacyLevelsRegression :: IO ()
+legacyLevelsRegression = do
+  let chunk count levelBytes valueBytes encoding =
+        let body = levelBytes <> valueBytes
+        in Thrift.encodeCompact (TV.Struct (V.fromList
+          [ TS.PageHeader_Type 0
+          , TS.PageHeader_UncompressedSize (fromIntegral (BS.length body))
+          , TS.PageHeader_CompressedSize (fromIntegral (BS.length body))
+          , TS.PageHeader_DataPageHeader (V.fromList
+              [ TS.DataPageHeader_NumValues count, TS.DataPageHeader_Encoding 0
+              , TS.DataPageHeader_DefinitionLevelEncoding encoding
+              , TS.DataPageHeader_RepetitionLevelEncoding 3 ]) ])) <> body
+      int n = BS.pack [n,0,0,0]
+  expect "legacy MSB-first one-bit definition levels"
+    (Parquet.Read.readGenericInt32OptionalColumnChunk Uncompressed 0 1
+      (chunk 5 (BS.singleton 0xb0) (int 10 <> int 20 <> int 30) 4)
+      == Right (V.fromList [Just 10, Nothing, Just 20, Just 30, Nothing]))
+  levels <- either failTest pure (Parquet.Read.readInt32Levels Uncompressed 0 7
+    (chunk 8 (BS.pack [0x05,0x39,0x77]) (int 42) 4))
+  expect "legacy three-bit levels use the Apache MSB-first golden"
+    (Parquet.Read.clDefinition levels == VP.fromList [0..7]
+      && Parquet.Read.clValues levels == VP.singleton 42)
+  grouped <- either failTest pure (Parquet.Read.readInt32Levels Uncompressed 0 7
+    (chunk 17 (BS.pack [0x05,0x39,0x77,0x05,0x39,0x77,0]) (int 42 <> int 43) 4))
+  expect "legacy levels cross complete groups and a partial trailing byte"
+    (Parquet.Read.clDefinition grouped == VP.generate 17 (\i -> fromIntegral (i `rem` 8))
+      && Parquet.Read.clValues grouped == VP.fromList [42,43])
+  expect "truncated legacy levels are rejected"
+    (isLeft (Parquet.Read.readInt32Levels Uncompressed 0 7 (chunk 8 (BS.singleton 0) BS.empty 4)))
+  expect "unknown nonzero-width level encodings are rejected"
+    (isLeft (Parquet.Read.readInt32Levels Uncompressed 0 1 (chunk 1 BS.empty BS.empty 5)))
+  let v2 reps defs values count =
+        let body = reps <> defs <> values
+            page = PageHeader (PtDataPageV2 (DataPageHeaderV2 count 0 count 0
+              (fromIntegral (BS.length defs)) (fromIntegral (BS.length reps)) False))
+              (Just (fromIntegral (BS.length body))) (Just (fromIntegral (BS.length body)))
+        in encodePageHeader page <> body
+  expect "V2 optional pages cannot omit their definition levels"
+    (isLeft (Parquet.Read.readInt32Levels Uncompressed 0 1 (v2 BS.empty BS.empty (int 42) 1)))
+  expect "a repeated column must begin at repetition level zero"
+    (isLeft (Parquet.Read.readInt32Levels Uncompressed 1 1
+      (v2 (LE.encodeRLEHybrid 1 (VP.fromList [1,0,1]))
+          (LE.encodeRLEHybrid 1 (VP.replicate 3 1)) (int 1 <> int 2 <> int 3) 3)))
+
+
+manyPageRegression :: IO ()
+manyPageRegression = do
+  let nPages = 97
+      rowsPerPage = 17
+      required page = VP.generate rowsPerPage (\i -> fromIntegral (page * rowsPerPage + i) :: Int32)
+      optional page = V.generate rowsPerPage (\i ->
+        if i `rem` 3 == 0 then Nothing else Just (fromIntegral (page * rowsPerPage + i) :: Int32))
+      requiredPage version page = case version of
+        PageV1 -> let (header, payload) = encodeColumnDataPageParts (ColInt32 (required page)) in header <> payload
+        PageV2 -> either error id (encodeColumnDataPageV2 Uncompressed (ColInt32 (required page)))
+      optionalPage version page = case version of
+        PageV1 -> encodeOptionalColumnPage (OptInt32 (optional page))
+        PageV2 -> case encodeOptionalColumnPageV2Parts Uncompressed (OptInt32 (optional page)) of
+          Left err -> error err
+          Right (header, reps, defs, values) -> BS.concat [header, reps, defs, values]
+      checkPages version makePage decode select expected = do
+        let pages = V.generate nPages (makePage version)
+            offsets = V.scanl' (+) 0 (BS.length <$> pages)
+            file = BS.concat (V.toList pages)
+            locations = V.imap (\i page -> PageLocation
+              (fromIntegral (offsets V.! i)) (fromIntegral (BS.length page))
+              (fromIntegral (i * rowsPerPage))) pages
+            keep = V.generate nPages (\i -> i `rem` 3 /= 1)
+        expect ("many-page decode preserves order " ++ show version)
+          (decode file == Right (V.concat (V.toList (V.generate nPages expected))))
+        expect ("many-page selection preserves order " ++ show version)
+          (select file locations keep == Right (V.concat (V.toList
+            (V.imapMaybe (\i yes -> if yes then Just (expected i) else Nothing) keep))))
+  mapM_ (\version -> do
+    checkPages version requiredPage
+      (fmap VP.convert . Parquet.Read.readGenericInt32ColumnChunk Uncompressed)
+      (\file locations keep -> VP.convert <$>
+        Parquet.Read.readGenericInt32SelectedPages Uncompressed file locations keep)
+      (VP.convert . required)
+    checkPages version optionalPage
+      (Parquet.Read.readGenericInt32OptionalColumnChunk Uncompressed 0 1)
+      (Parquet.Read.readGenericInt32OptionalSelectedPages Uncompressed 0 1)
+      optional) [PageV1, PageV2]
+
+
+genericPageDispatch :: IO ()
+genericPageDispatch = do
+  -- DELTA_BINARY_PACKED INT32 in a DATA_PAGE V1.
+  do
+    let !values = VP.fromList ([10, 20, 30, 40, 50] :: [Int32])
+        !payload = encodeDeltaBinaryPackedInt32 values
+        !numVals = VP.length values
+        !hdr = PageHeader
+          { phType = PtDataPage
+              (DataPageHeader { dphNumValues = fromIntegral numVals
+                              , dphEncoding  = 5  -- DELTA_BINARY_PACKED
+                              })
+          , phUncompressedPageSize = Just (fromIntegral (BS.length payload))
+          , phCompressedPageSize   = Just (fromIntegral (BS.length payload))
+          }
+        !chunk = encodePageHeader hdr <> payload
+    case Parquet.Read.readGenericInt32ColumnChunk Uncompressed chunk of
+      Right v | VP.toList v == VP.toList values ->
+        putStrLn "OK: generic INT32 dispatch handles DELTA_BINARY_PACKED"
+      Right v -> failTest $ "DELTA_BINARY_PACKED Int32 mismatch: got "
+                            ++ show (VP.toList v)
+      Left e  -> failTest $ "DELTA_BINARY_PACKED Int32: " ++ e
+
+  -- BYTE_STREAM_SPLIT FLOAT in DATA_PAGE V1.
+  do
+    let !values = VP.fromList ([1.0, -2.5, 3.14, 99.9] :: [Float])
+        !payload = encodeByteStreamSplitFloat values
+        !hdr = PageHeader
+          { phType = PtDataPage
+              (DataPageHeader { dphNumValues = fromIntegral (VP.length values)
+                              , dphEncoding  = 9  -- BYTE_STREAM_SPLIT
+                              })
+          , phUncompressedPageSize = Just (fromIntegral (BS.length payload))
+          , phCompressedPageSize   = Just (fromIntegral (BS.length payload))
+          }
+        !chunk = encodePageHeader hdr <> payload
+    case Parquet.Read.readGenericFloatColumnChunk Uncompressed chunk of
+      Right v | VP.toList v == VP.toList values ->
+        putStrLn "OK: generic FLOAT dispatch handles BYTE_STREAM_SPLIT"
+      Right v -> failTest $ "BYTE_STREAM_SPLIT Float mismatch: got "
+                            ++ show (VP.toList v)
+      Left e  -> failTest $ "BYTE_STREAM_SPLIT Float: " ++ e
+
+  -- DELTA_BYTE_ARRAY for BYTE_ARRAY in DATA_PAGE V1.
+  do
+    let !values = V.fromList
+          [ BSC.pack "alpha"
+          , BSC.pack "alphanumeric"
+          , BSC.pack "alphabet"
+          ]
+        !payload = encodeDeltaByteArray values
+        !hdr = PageHeader
+          { phType = PtDataPage
+              (DataPageHeader { dphNumValues = fromIntegral (V.length values)
+                              , dphEncoding  = 7  -- DELTA_BYTE_ARRAY
+                              })
+          , phUncompressedPageSize = Just (fromIntegral (BS.length payload))
+          , phCompressedPageSize   = Just (fromIntegral (BS.length payload))
+          }
+        !chunk = encodePageHeader hdr <> payload
+    case Parquet.Read.readGenericByteArrayColumnChunk Uncompressed chunk of
+      Right v | V.toList v == V.toList values ->
+        putStrLn "OK: generic BYTE_ARRAY dispatch handles DELTA_BYTE_ARRAY"
+      Right v -> failTest $ "DELTA_BYTE_ARRAY mismatch: got "
+                            ++ show (V.toList v)
+      Left e  -> failTest $ "DELTA_BYTE_ARRAY: " ++ e
+
+  -- PLAIN INT64 wrapped in a DATA_PAGE_V2 (no level streams,
+  -- uncompressed). This exercises the V2 page header dispatch.
+  do
+    let !values = VP.fromList ([100, 200, 300] :: [Int64])
+        !payload = mconcat
+          [ BS.pack
+              [ fromIntegral (v `mod` 256)
+              , fromIntegral ((v `div` 256) `mod` 256)
+              , fromIntegral ((v `div` 65536) `mod` 256)
+              , 0, 0, 0, 0, 0
+              ]
+          | v <- VP.toList values
+          ]
+        !hdr = PageHeader
+          { phType = PtDataPageV2
+              DataPageHeaderV2
+                { dph2NumValues    = fromIntegral (VP.length values)
+                , dph2NumNulls     = 0
+                , dph2NumRows      = fromIntegral (VP.length values)
+                , dph2Encoding     = 0  -- PLAIN
+                , dph2DefLevelsLen = 0
+                , dph2RepLevelsLen = 0
+                , dph2IsCompressed = False
+                }
+          , phUncompressedPageSize = Just (fromIntegral (BS.length payload))
+          , phCompressedPageSize   = Just (fromIntegral (BS.length payload))
+          }
+        !chunk = encodePageHeader hdr <> payload
+    case Parquet.Read.readGenericInt64ColumnChunk Uncompressed chunk of
+      Right v | VP.toList v == VP.toList values ->
+        putStrLn "OK: generic INT64 dispatch handles DATA_PAGE_V2"
+      Right v -> failTest $ "DATA_PAGE_V2 Int64 mismatch: got "
+                            ++ show (VP.toList v)
+      Left e  -> failTest $ "DATA_PAGE_V2 Int64: " ++ e
+
+predicateBloomSkipping :: IO ()
+predicateBloomSkipping = do
+  let -- Bloom filter built from i32 PLAIN payloads of 10, 20, 30
+      bf0 = newSbbf (optimalNumBytes 1024 0.01)
+      bf  = foldr sbbfInsert bf0
+              [ BS.pack [10, 0, 0, 0]
+              , BS.pack [20, 0, 0, 0]
+              , BS.pack [30, 0, 0, 0]
+              ]
+  expect "bloom keeps known-present 20"
+    (Pred.evalBloomChunk (physicalField PTInt32) bf
+       (Pred.PEq (Pred.PVInt32 20)) == Pred.PMaybeKeep)
+  expect "bloom skips known-absent 99"
+    (Pred.evalBloomChunk (physicalField PTInt32) bf
+       (Pred.PEq (Pred.PVInt32 99)) == Pred.PSkip)
+  expect "bloom keeps PIn that contains a present"
+    (Pred.evalBloomChunk (physicalField PTInt32) bf
+       (Pred.PIn [Pred.PVInt32 99, Pred.PVInt32 20]) == Pred.PMaybeKeep)
+  expect "bloom skips PIn of all-absent"
+    (Pred.evalBloomChunk (physicalField PTInt32) bf
+       (Pred.PIn [Pred.PVInt32 99, Pred.PVInt32 100]) == Pred.PSkip)
+
+arrowParquetProjection :: IO ()
+arrowParquetProjection = do
+  -- Write a 3-column file (a=int32, b=int32, c=utf8), then read
+  -- it back with target schema (c, a) (reordered + narrowed).
+  let !fullSchema = AT.Schema
+        { AT.arrowFields = V.fromList
+            [ AT.Field "a" False (AT.AInt 32 True) V.empty Nothing V.empty
+            , AT.Field "b" False (AT.AInt 32 True) V.empty Nothing V.empty
+            , AT.Field "c" False AT.AUtf8          V.empty Nothing V.empty
+            ]
+        , AT.arrowEndianness = AT.Little
+        , AT.arrowMetadata   = V.empty
+        , AT.arrowFeatures = V.empty
+        }
+      !batch = V.fromList
+        [ AC.primColumn AC.PInt32 (VS.fromList [10, 20, 30 :: Int32])
+        , AC.primColumn AC.PInt32 (VS.fromList [40, 50, 60 :: Int32])
+        , AC.fromTexts (V.fromList ["alpha", "beta", "gamma"])
+        ]
+  case PArrow.arrowToParquet fullSchema [batch] of
+    Left  e -> failTest $ "projection arrowToParquet: " ++ e
+    Right (pSchema, pRgs) -> do
+      let !opts = PHL.defaultWriteOptions
+                    { PHL.writePageVersion = PageV1
+                    , PHL.writeCompression = Uncompressed
+                    }
+          !bytes = PHL.encodeParquet opts pSchema pRgs
+      case PHL.decodeParquet PHL.defaultReadOptions bytes of
+        Left  e -> failTest $ "projection decodeParquet: " ++ e
+        Right pf -> do
+          -- Target: (c, a), reordered and projected.
+          let !target = AT.Schema
+                { AT.arrowFields = V.fromList
+                    [ AT.Field "c" False AT.AUtf8          V.empty Nothing V.empty
+                    , AT.Field "a" False (AT.AInt 32 True) V.empty Nothing V.empty
+                    ]
+                , AT.arrowEndianness = AT.Little
+                , AT.arrowMetadata   = V.empty
+                , AT.arrowFeatures = V.empty
+                }
+          case PArrow.parquetRowGroupToArrow target pf 0 of
+            Left  e    -> failTest $ "parquetRowGroupToArrow: " ++ show e
+            Right cols -> do
+              let !expected = V.fromList
+                    [ AC.fromTexts (V.fromList ["alpha", "beta", "gamma"])
+                    , AC.primColumn AC.PInt32 (VS.fromList [10, 20, 30 :: Int32])
+                    ]
+              if cols == expected
+                then putStrLn "OK: Parquet projection + reorder (c, a <- a, b, c)"
+                else failTest $ "projection mismatch:\n got "
+                                  ++ show (V.toList cols)
+
+          -- Test a missing column.
+          let !missing = AT.Schema
+                { AT.arrowFields = V.singleton
+                    (AT.Field "z" False (AT.AInt 32 True) V.empty Nothing V.empty)
+                , AT.arrowEndianness = AT.Little
+                , AT.arrowMetadata   = V.empty
+                , AT.arrowFeatures = V.empty
+                }
+          case PArrow.parquetRowGroupToArrow missing pf 0 of
+            Left (PArrow.MissingColumn "z") ->
+              putStrLn "OK: Parquet projection surfaces MissingColumn"
+            other -> failTest $ "expected MissingColumn, got " ++ show other
+
+          -- Test coercion: Int32 -> Int64.
+          let !widen = AT.Schema
+                { AT.arrowFields = V.singleton
+                    (AT.Field "a" False (AT.AInt 64 True) V.empty Nothing V.empty)
+                , AT.arrowEndianness = AT.Little
+                , AT.arrowMetadata   = V.empty
+                , AT.arrowFeatures = V.empty
+                }
+          case PArrow.parquetRowGroupToArrow widen pf 0 of
+            Left e -> failTest $ "projection coercion: " ++ show e
+            Right cols ->
+              if cols == V.singleton (AC.primColumn AC.PInt64 (VS.fromList [10, 20, 30 :: Int64]))
+                then putStrLn "OK: Parquet projection coerces Int32 -> Int64"
+                else failTest $ "coercion mismatch: " ++ show (V.toList cols)
+
+arrowParquetNestedBridge :: IO ()
+arrowParquetNestedBridge = do
+  -- Build an Arrow struct<i32, utf8> column + wrap it in a nested
+  -- Parquet file. Verifies that arrowFieldToNestedSchema +
+  -- columnArrayToNestedRows produce a valid NestedRow tree and
+  -- encodeParquetNested accepts it.
+  let structField = AT.Field "point" False AT.AStruct
+        (V.fromList
+           [ AT.Field "x" False (AT.AInt 32 True) V.empty Nothing V.empty
+           , AT.Field "name" False AT.AUtf8        V.empty Nothing V.empty
+           ])
+        Nothing
+        V.empty
+      structCol = either error id $ AC.mkStruct 3 Nothing (V.fromList
+        [ ("x",    AC.primColumn AC.PInt32 (VS.fromList [1, 2, 3 :: Int32]))
+        , ("name", AC.fromTexts (V.fromList ["a", "b", "c"]))
+        ])
+  case PArrow.arrowFieldToNestedSchema structField of
+    Left  e   -> failTest $ "arrowFieldToNestedSchema: " ++ e
+    Right sch -> case PArrow.columnArrayToNestedRows structField structCol of
+      Left  e   -> failTest $ "columnArrayToNestedRows: " ++ e
+      Right rows ->
+        let !cols = V.singleton ("point", sch)
+            !cr   = V.singleton rows
+        in  case PHL.encodeParquetNested cols cr of
+              Left  e  -> failTest $ "encodeParquetNested: " ++ e
+              Right bs ->
+                if BS.length bs > 4 && BS.take 4 bs == BSC.pack "PAR1"
+                  then putStrLn "OK: Arrow <-> Parquet nested bridge"
+                  else failTest $ "nested bridge produced invalid Parquet file"
+
+arrowParquetBridge :: IO ()
+arrowParquetBridge = do
+  let !arrowSchema = AT.Schema
+        { AT.arrowFields = V.fromList
+            [ AT.Field "i" False (AT.AInt 32 True) V.empty Nothing V.empty
+            , AT.Field "s" False AT.AUtf8           V.empty Nothing V.empty
+            ]
+        , AT.arrowEndianness = AT.Little
+        , AT.arrowMetadata   = V.empty
+        , AT.arrowFeatures = V.empty
+        }
+      !batch = V.fromList
+        [ AC.primColumn AC.PInt32 (VS.fromList ([10, 20, 30] :: [Int32]))
+        , AC.fromTexts (V.fromList ["alpha", "beta", "gamma"])
+        ]
+  case PArrow.arrowToParquet arrowSchema [batch] of
+    Left  e  -> failTest $ "arrowToParquet: " ++ e
+    Right (psSchema, rgs) -> do
+      let !opts = PHL.defaultWriteOptions
+                    { PHL.writePageVersion = PageV1
+                    , PHL.writeCompression = Uncompressed
+                    }
+          !bytes = PHL.encodeParquet opts psSchema rgs
+      case PHL.decodeParquet PHL.defaultReadOptions bytes of
+        Left  e -> failTest $ "decodeParquet (bridge): " ++ e
+        Right pf ->
+          case PArrow.parquetRowGroupToArrow arrowSchema pf 0 of
+            Left  e    -> failTest $ "parquetRowGroupToArrow: " ++ show e
+            Right cols ->
+              if cols == batch
+                then putStrLn "OK: Arrow ↔ Parquet bridge round-trip"
+                else failTest $ "bridge round-trip mismatch:\n got "
+                                 ++ show (V.toList cols)
+                                 ++ "\n exp " ++ show (V.toList batch)
+
+  -- streamRowGroups: drain the same single-row-group file as a
+  -- list and assert every row group materialises correctly.
+  case PArrow.arrowToParquet arrowSchema [batch] of
+    Left  e -> failTest $ "arrowToParquet (stream): " ++ e
+    Right (psSchema, rgs) -> do
+      let !opts = PHL.defaultWriteOptions
+                    { PHL.writePageVersion = PageV1
+                    , PHL.writeCompression = Uncompressed
+                    }
+          !bytes = PHL.encodeParquet opts psSchema rgs
+      case PHL.decodeParquet PHL.defaultReadOptions bytes of
+        Left  e -> failTest $ "decodeParquet (stream): " ++ e
+        Right pf -> do
+          let results = PArrow.streamRowGroups arrowSchema pf
+          case results of
+            [Left e] -> failTest $ "streamRowGroups (rg 0): " ++ e
+            [Right cols] ->
+              if cols == batch
+                then putStrLn "OK: streamRowGroups iterates row groups"
+                else failTest $ "streamRowGroups mismatch"
+            _ ->
+              failTest $ "streamRowGroups: expected 1 row group, got "
+                ++ show (length results)
+
+  -- Temporal bridge: Date32, Timestamp round-trip through the
+  -- Arrow -> Parquet -> Arrow path.
+  let !tempSchema = AT.Schema
+        { AT.arrowFields = V.fromList
+            [ AT.Field "d"  False (AT.ADate AT.DateDay) V.empty Nothing V.empty
+            , AT.Field "ts" False (AT.ATimestamp AT.Microsecond Nothing) V.empty Nothing V.empty
+            ]
+        , AT.arrowEndianness = AT.Little
+        , AT.arrowMetadata   = V.empty
+        , AT.arrowFeatures = V.empty
+        }
+      !tempBatch = V.fromList
+        [ AC.primColumn AC.PDate32    (VS.fromList ([19000, 19001, 19002] :: [Int32]))
+        , AC.primColumn AC.PTimestamp (VS.fromList ([1700000000000000, 1700001000000000, 1700002000000000] :: [Int64]))
+        ]
+  case PArrow.arrowToParquet tempSchema [tempBatch] of
+    Left  e -> failTest $ "temporal arrowToParquet: " ++ e
+    Right (tSchema, tRgs) -> do
+      let !tOpts = PHL.defaultWriteOptions
+                      { PHL.writePageVersion = PageV1
+                      , PHL.writeCompression = Uncompressed
+                      }
+          !tBytes = PHL.encodeParquet tOpts tSchema tRgs
+      case PHL.decodeParquet PHL.defaultReadOptions tBytes of
+        Left  e -> failTest $ "temporal decodeParquet: " ++ e
+        Right pf ->
+          case PArrow.parquetRowGroupToArrow tempSchema pf 0 of
+            Left  e    -> failTest $ "temporal parquetRowGroupToArrow: " ++ show e
+            Right cols ->
+              if cols == tempBatch
+                then putStrLn "OK: Arrow <-> Parquet temporal round-trip"
+                else failTest $ "temporal mismatch:\n got "
+                                  ++ show (V.toList cols)
+                                  ++ "\n exp " ++ show (V.toList tempBatch)
+
+  -- Nested bridge + Parquet.HighLevel.encodeParquetNested:
+  -- struct + list Arrow columns lower to Parquet.Nested.NestedRow
+  -- trees and the nested writer produces a valid Parquet file.
+  arrowParquetNestedBridge
+
+  -- Projection / schema evolution: read a 3-column file back with
+  -- a 2-column target schema in a different order.
+  arrowParquetProjection
+
+expectHash :: String -> String -> IO ()
+expectHash s expected = expectHashBs (BSC.pack s) expected
+
+expectHashBs :: BS.ByteString -> String -> IO ()
+expectHashBs bs expected =
+  let actual = pad16 (showHex (Hash.xxh64 0 bs) "")
+  in unless (actual == expected) $
+       failTest ("xxh64 " ++ show bs ++ " expected " ++ expected
+                  ++ " got " ++ actual)
+
+pad16 :: String -> String
+pad16 s = replicate (16 - length s) '0' ++ s
+
+expect :: String -> Bool -> IO ()
+expect what ok = do
+  if ok
+    then putStrLn ("OK: " ++ what)
+    else failTest what
+
+failTest :: String -> IO a
+failTest msg = do
+  putStrLn ("FAIL: " ++ msg)
+  exitFailure
+
+-- ============================================================
+-- Pyarrow availability + nested-list cross-language check
+-- ============================================================
+
+pyarrowAvailable :: IO Bool
+pyarrowAvailable = do
+  (code, _, _) <- Proc.readProcessWithExitCode
+                    "python3" ["-c", "import pyarrow.parquet"] ""
+  pure (code == ExitSuccess)
+
+validateNestedAgainstPyarrow :: IO ()
+validateNestedAgainstPyarrow = do
+  let rows = V.fromList
+        [ Just (V.fromList [Just (1 :: Int32), Nothing, Just 3])
+        , Just V.empty
+        , Nothing
+        ]
+      leaf = Nested.encodeOptionalListOptionalI32 "xs" rows
+      bytes = Nested.buildOptionalListFile PTInt32 leaf 3
+      filePath = "/tmp/wireform-nested-list.parquet"
+  BS.writeFile filePath bytes
+  pyarrowAssert "nested optional-list<optional INT32> reads back via pyarrow"
+    [ "t = pq.read_table('" ++ filePath ++ "').to_pylist()"
+    , "exp = [{'xs': [1, None, 3]}, {'xs': []}, {'xs': None}]"
+    , "assert t == exp, f'roundtrip mismatch: {t!r}'"
+    ]
+
+-- | Run a python snippet under pyarrow and assert that it prints
+-- 'PYARROW_OK'. Snippet header (importing pyarrow.parquet as pq) is
+-- prepended automatically.
+pyarrowAssert :: String -> [String] -> IO ()
+pyarrowAssert label snippet = do
+  (code, out, err) <- Proc.readProcessWithExitCode "python3"
+    [ "-c"
+    , unlines
+        ( "import pyarrow.parquet as pq"
+        : snippet
+       ++ ["print('PYARROW_OK')"]
+        )
+    ] ""
+  case code of
+    ExitSuccess
+      | "PYARROW_OK" `isInfixOf` out ->
+          expect label True
+      | otherwise -> failTest ("pyarrow: unexpected output: " ++ out)
+    _ -> failTest ("pyarrow rejected our nested file:\nstdout=" ++ out
+                    ++ "\nstderr=" ++ err)
+
+validateListStructAgainstPyarrow :: IO ()
+validateListStructAgainstPyarrow = do
+  -- Schema: optional list<optional struct<a: int32, b: string>>
+  let schema = Nested.NSOptional
+                 (Nested.NSList
+                   (Nested.NSOptional
+                     (Nested.NSStruct (V.fromList
+                       [ ("a", Nested.NSOptional (Nested.NSPrimitive Nested.LtInt32))
+                       , ("b", Nested.NSOptional (Nested.NSPrimitive Nested.LtString))
+                       ]))))
+      mkRec :: Maybe (Int32, T.Text) -> Nested.NestedRow
+      mkRec Nothing = Nested.NRNull
+      mkRec (Just (i, s)) = Nested.NRStruct (V.fromList
+        [ Nested.NRLeaf (Nested.LvInt32 i)
+        , Nested.NRLeaf (Nested.LvString s)
+        ])
+      rows = V.fromList
+        [ Nested.NRList (V.fromList
+            [ mkRec (Just (1, "x"))
+            , mkRec Nothing
+            , mkRec (Just (2, "y"))
+            ])
+        , Nested.NRList V.empty
+        , Nested.NRNull
+        , Nested.NRList (V.singleton (mkRec (Just (3, "z"))))
+        ]
+  case Nested.buildNestedFile (V.singleton ("xs", schema))
+                              (V.singleton rows) of
+    Left e -> failTest ("buildNestedFile (list<struct>): " ++ e)
+    Right bytes -> do
+      let filePath = "/tmp/wireform-list-struct.parquet"
+      BS.writeFile filePath bytes
+      pyarrowAssert "nested list<struct<a:int32,b:string>> reads back via pyarrow"
+        [ "t = pq.read_table('" ++ filePath ++ "').to_pylist()"
+        , "exp = [{'xs': [{'a': 1, 'b': 'x'}, None, {'a': 2, 'b': 'y'}]},"
+        , "       {'xs': []},"
+        , "       {'xs': None},"
+        , "       {'xs': [{'a': 3, 'b': 'z'}]}]"
+        , "assert t == exp, f'roundtrip mismatch: {t!r}'"
+        ]
+
+validateListListAgainstPyarrow :: IO ()
+validateListListAgainstPyarrow = do
+  -- Schema: optional list<optional list<optional int32>>
+  let schema = Nested.NSOptional
+                 (Nested.NSList
+                   (Nested.NSOptional
+                     (Nested.NSList
+                       (Nested.NSOptional
+                         (Nested.NSPrimitive Nested.LtInt32)))))
+      lit :: Int32 -> Nested.NestedRow
+      lit = Nested.NRLeaf . Nested.LvInt32
+      inner :: [Int32] -> Nested.NestedRow
+      inner xs = Nested.NRList (V.fromList (map lit xs))
+      rows = V.fromList
+        [ Nested.NRList (V.fromList [inner [1, 2], inner [3]])
+        , Nested.NRList (V.singleton (Nested.NRList V.empty))
+        , Nested.NRNull
+        , Nested.NRList (V.singleton (inner [4, 5, 6]))
+        ]
+  case Nested.buildNestedFile (V.singleton ("xs", schema))
+                              (V.singleton rows) of
+    Left e -> failTest ("buildNestedFile (list<list>): " ++ e)
+    Right bytes -> do
+      let filePath = "/tmp/wireform-list-list.parquet"
+      BS.writeFile filePath bytes
+      pyarrowAssert "nested list<list<int32>> reads back via pyarrow"
+        [ "t = pq.read_table('" ++ filePath ++ "').to_pylist()"
+        , "exp = [{'xs': [[1, 2], [3]]},"
+        , "       {'xs': [[]]},"
+        , "       {'xs': None},"
+        , "       {'xs': [[4, 5, 6]]}]"
+        , "assert t == exp, f'roundtrip mismatch: {t!r}'"
+        ]
+
+validateMapAgainstPyarrow :: IO ()
+validateMapAgainstPyarrow = do
+  -- Schema: optional map<string, int32> with optional value.
+  let schema = Nested.NSOptional
+                 (Nested.NSMap
+                   (Nested.NSRequired (Nested.NSPrimitive Nested.LtString))
+                   (Nested.NSOptional (Nested.NSPrimitive Nested.LtInt32)))
+      pair :: T.Text -> Maybe Int32 -> (Nested.NestedRow, Nested.NestedRow)
+      pair k mv =
+        ( Nested.NRLeaf (Nested.LvString k)
+        , maybe Nested.NRNull (Nested.NRLeaf . Nested.LvInt32) mv
+        )
+      rows = V.fromList
+        [ Nested.NRMapEntries (V.fromList
+            [ pair "k1" (Just 10)
+            , pair "k2" (Just 20)
+            ])
+        , Nested.NRMapEntries V.empty
+        , Nested.NRNull
+        , Nested.NRMapEntries (V.singleton (pair "k3" (Just 30)))
+        ]
+  case Nested.buildNestedFile (V.singleton ("xs", schema))
+                              (V.singleton rows) of
+    Left e -> failTest ("buildNestedFile (map): " ++ e)
+    Right bytes -> do
+      let filePath = "/tmp/wireform-map.parquet"
+      BS.writeFile filePath bytes
+      -- pyarrow reads MAP columns as a list of (key, value) tuples;
+      -- the dict ordering is preserved.
+      pyarrowAssert "nested map<string, int32> reads back via pyarrow"
+        [ "t = pq.read_table('" ++ filePath ++ "').to_pylist()"
+        , "exp = [{'xs': [('k1', 10), ('k2', 20)]},"
+        , "       {'xs': []},"
+        , "       {'xs': None},"
+        , "       {'xs': [('k3', 30)]}]"
+        , "assert t == exp, f'roundtrip mismatch: {t!r}'"
+        ]
+
+-- ============================================================
+-- Golden pyarrow fixtures
+-- ============================================================
+
+goldenSimpleInt :: IO ()
+goldenSimpleInt = do
+  bs <- BS.readFile "test/fixtures/simple_int.parquet"
+  case loadParquetFile bs of
+    Left e -> failTest ("golden simple_int: " ++ e)
+    Right pf -> do
+      let !rgs = fmRowGroups (pfFooter pf)
+          !rg  = V.unsafeIndex rgs 0
+          !cc  = V.unsafeIndex (rgColumns rg) 0
+      expect "golden simple_int: 5 rows" (rgNumRows rg == 5)
+      case ccMetadata cc of
+        Just m -> do
+          expect "golden simple_int: column type INT64"
+            (cmType m == PTInt64)
+          expect "golden simple_int: numValues == 5"
+            (cmNumValues m == 5)
+        Nothing -> failTest "golden simple_int: no metadata"
+
+goldenMixedTypes :: IO ()
+goldenMixedTypes = do
+  bs <- BS.readFile "test/fixtures/mixed_types.parquet"
+  case loadParquetFile bs of
+    Left e -> failTest ("golden mixed_types: " ++ e)
+    Right pf -> do
+      let !rgs = fmRowGroups (pfFooter pf)
+          !rg  = V.unsafeIndex rgs 0
+          !cols = rgColumns rg
+      expect "golden mixed_types: 3 columns" (V.length cols == 3)
+      let typeAt i = case ccMetadata (V.unsafeIndex cols i) of
+            Just m  -> Just (cmType m)
+            Nothing -> Nothing
+      expect "golden mixed_types: id is INT64"   (typeAt 0 == Just PTInt64)
+      expect "golden mixed_types: name is BYTE_ARRAY" (typeAt 1 == Just PTByteArray)
+      expect "golden mixed_types: val is DOUBLE" (typeAt 2 == Just PTDouble)
+      let codecAt i = case ccMetadata (V.unsafeIndex cols i) of
+            Just m  -> Just (cmCodec m)
+            Nothing -> Nothing
+      expect "golden mixed_types: gzip codec on every column"
+        (all (== Just GZip) (map codecAt [0, 1, 2]))
+
+goldenBloomIndex :: IO ()
+goldenBloomIndex = do
+  bs <- BS.readFile "test/fixtures/bloom_and_index.parquet"
+  case loadParquetFile bs of
+    Left e -> failTest ("golden bloom_and_index: " ++ e)
+    Right pf -> do
+      let !rgs = fmRowGroups (pfFooter pf)
+          !rg  = V.unsafeIndex rgs 0
+          !cc  = V.unsafeIndex (rgColumns rg) 0
+      expect "golden bloom_and_index: 100 rows" (rgNumRows rg == 100)
+      expect "golden bloom_and_index: page index offsets present"
+        (ccOffsetIndexOffset cc /= Nothing && ccColumnIndexOffset cc /= Nothing)
+
+
+physicalField :: ParquetType -> SchemaElement
+physicalField ty = SchemaElement "value" (Just Required) (Just ty) Nothing Nothing Nothing Nothing Nothing
+
+
+knownContext :: SchemaElement -> Pred.StatisticsContext
+knownContext field = Pred.StatisticsContext field (Just TypeDefinedOrder)
diff --git a/test/MetadataRegression.hs b/test/MetadataRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/MetadataRegression.hs
@@ -0,0 +1,69 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module MetadataRegression (tests) where
+
+import Control.Monad (unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Int (Int16)
+import Data.Vector qualified as V
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Footer qualified as Footer
+import Parquet.Types
+import Thrift.Encode qualified as Thrift
+import Thrift.Value qualified as TV
+import Thrift.Wire (ThriftType (..))
+
+
+-- Raw field numbers supply fixtures independently of the named field aliases.
+baseFields :: V.Vector (Int16, TV.Value)
+baseFields =
+  V.fromList
+    [ (1, TV.I32 1)
+    , (2, TV.List TT_STRUCT (V.singleton (TV.Struct (V.fromList [(4, TV.String "schema"), (5, TV.I32 0)]))))
+    , (3, TV.I64 0)
+    , (4, TV.List TT_STRUCT V.empty)
+    ]
+
+
+tests :: IO ()
+tests = do
+  let parse fields = Footer.readFooterRaw (Thrift.encodeCompact (TV.Struct (baseFields V.++ fields)))
+      check name condition = unless condition (fail ("metadata regression: " ++ name))
+      entry key value = TV.Struct (V.singleton (1, TV.Binary key) V.++ maybe V.empty (V.singleton . (2,) . TV.Binary) value)
+      rows = V.fromList [KeyValue "x" Nothing, KeyValue "x" (Just ""), KeyValue "x" (Just "last"), KeyValue (BS.pack [255, 0]) (Just (BS.pack [128, 0, 255]))]
+      wireRows = V.map (\row -> entry (kvKey row) (kvValue row)) rows
+  without <- either fail pure (parse V.empty)
+  check "absent list remains absent" (fmKeyValueMetadata without == Nothing)
+  empty <- either fail pure (parse (V.singleton (5, TV.List TT_STRUCT V.empty)))
+  check "present empty list remains present" (fmKeyValueMetadata empty == Just V.empty)
+  decoded <- either fail pure (parse (V.singleton (5, TV.List TT_STRUCT wireRows)))
+  check "raw fields preserve order, duplicate keys and optional/binary values" (fmKeyValueMetadata decoded == Just rows)
+  case Footer.fileMetadataToThrift decoded of
+    TV.Struct fields ->
+      check
+        "encoder uses field 5 and KeyValue fields 1/2"
+        (fmap snd (V.find ((== 5) . fst) fields) == Just (TV.List TT_STRUCT wireRows))
+    _ -> fail "metadata regression: encoder did not produce a struct"
+  text <- either fail pure (parse (V.singleton (5, TV.List TT_STRUCT (V.singleton (TV.Struct (V.fromList [(1, TV.String "crs"), (2, TV.String "EPSG:3857")]))))))
+  check "decoded Text is retained as UTF-8 bytes" (fmKeyValueMetadata text == Just (V.singleton (KeyValue "crs" (Just "EPSG:3857"))))
+  let malformed =
+        [ V.singleton (5, TV.I32 1)
+        , V.fromList [(5, TV.List TT_STRUCT V.empty), (5, TV.List TT_STRUCT V.empty)]
+        , V.singleton (5, TV.List TT_I32 (V.singleton (TV.I32 1)))
+        , V.singleton (5, TV.List TT_STRUCT (V.singleton (TV.Struct V.empty)))
+        , V.singleton (5, TV.List TT_STRUCT (V.singleton (TV.Struct (V.singleton (1, TV.I32 1)))))
+        , V.singleton (5, TV.List TT_STRUCT (V.singleton (TV.Struct (V.fromList [(1, TV.Binary "x"), (1, TV.Binary "x")]))))
+        , V.singleton (5, TV.List TT_STRUCT (V.singleton (TV.Struct (V.fromList [(1, TV.Binary "x"), (2, TV.Bool True)]))))
+        , V.singleton (5, TV.List TT_STRUCT (V.singleton (TV.Struct (V.fromList [(1, TV.Binary "x"), (2, TV.Binary "a"), (2, TV.Binary "b")]))))
+        ]
+  mapM_ (\fields -> check "malformed/duplicate known fields are rejected" (isLeft (parse fields))) malformed
+  passed <- H.check $ H.withTests 100 $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 40) (KeyValue <$> Gen.bytes (Range.linear 0 40) <*> Gen.maybe (Gen.bytes (Range.linear 0 40))))
+    let expected = V.fromList values
+        metadata = without {fmKeyValueMetadata = Just expected}
+    loaded <- H.evalEither (Footer.readFooterRaw (Thrift.encodeCompact (Footer.fileMetadataToThrift metadata)))
+    fmKeyValueMetadata loaded H.=== Just expected
+  check "opaque application metadata wire roundtrip property" passed
diff --git a/test/NestedOptionsRegression.hs b/test/NestedOptionsRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/NestedOptionsRegression.hs
@@ -0,0 +1,164 @@
+module NestedOptionsRegression (tests) where
+
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as Builder
+import Data.ByteString.Lazy qualified as BL
+import Data.Either (isLeft)
+import Data.Text.Encoding qualified
+import Data.Vector qualified as V
+import GHC.Float (castDoubleToWord64, castFloatToWord32, castWord32ToFloat)
+import Parquet.Arrow qualified as A
+import Parquet.BloomFilter qualified as Bloom
+import Parquet.Compress qualified as Compress
+import Parquet.HighLevel qualified as H
+import Parquet.Nested qualified as N
+import Parquet.Page qualified as Page
+import Parquet.PageIndex qualified as Index
+import Parquet.Read qualified as R
+import Parquet.Types
+import Parquet.Write qualified as W
+import System.Directory (createDirectoryIfMissing)
+import System.Environment (lookupEnv)
+import System.FilePath ((</>))
+
+
+check :: String -> Bool -> IO ()
+check label okay = unless okay (fail ("nested options: " ++ label))
+
+
+right :: Either String a -> IO a
+right = either fail pure
+
+
+tests :: IO ()
+tests = do
+  let primitive = N.NSPrimitive N.LtInt32
+      schema = V.singleton ("v", N.NSOptional (N.NSList (N.NSOptional primitive)))
+      rows = V.singleton (V.fromList [N.NRNull, N.NRList V.empty, N.NRList (V.fromList [N.NRLeaf (N.LvInt32 42), N.NRNull, N.NRLeaf (N.LvInt32 (-7))]), N.NRList (V.singleton (N.NRLeaf (N.LvInt32 9)))])
+  baseline <- right (N.buildNestedFile schema rows) >>= right . R.loadParquetFile
+  native <- right (A.parquetFileArrowSchemaChecked baseline)
+  expected <- either (fail . show) pure (A.parquetRowGroupToArrow native baseline 0)
+  forM_ [Uncompressed, GZip, Snappy, ZSTD, LZ4Raw, LZO, Brotli] $ \codec ->
+    case Compress.validateCompression codec of
+      Left _ -> pure ()
+      Right () -> forM_ [W.PageV1, W.PageV2] $ \version -> do
+        bytes <- right (H.encodeParquetNestedWith H.defaultWriteOptions {H.writeCompression = codec, H.writePageVersion = version} schema rows)
+        file <- right (R.loadParquetFile bytes)
+        actual <- either (fail . show) pure (A.parquetRowGroupToArrow native file 0)
+        check ("values: " ++ show codec ++ "/" ++ show version) (actual == expected)
+        let group = V.head (fmRowGroups (R.pfFooter file))
+            column = V.head (rgColumns group)
+        metadata <- maybe (fail "nested options: missing metadata") pure (ccMetadata column)
+        check "requested compression is recorded" (cmCodec metadata == codec)
+        check "row-group total is the uncompressed total" (rgTotalByteSize group == cmTotalUncompressedSize metadata)
+        chunk <- right (R.columnChunkSlice file 0 0)
+        (header, _) <- right (Page.readPageHeaderAt chunk 0)
+        check "requested page version is emitted" (case (version, Page.phType header) of (W.PageV1, Page.PtDataPage _) -> True; (W.PageV2, Page.PtDataPageV2 _) -> True; _ -> False)
+        index <- right (Index.readOffsetIndex file 0 0)
+        check "offset index describes actual page bytes" $ case index of
+          Just value -> case V.toList (oiPageLocations value) of
+            [location] -> plOffset location == cmDataPageOffset metadata && fromIntegral (plCompressedPageSize location) == BS.length chunk && plFirstRowIndex location == 0
+            _ -> False
+          Nothing -> False
+  let bloom = V.foldl' (\filter_ value -> Bloom.sbbfInsert (plainBloomValue (N.LvInt32 value)) filter_) (Bloom.newSbbf 256) (V.fromList [42, -7, 9])
+      aux = W.emptyColumnAux {W.caPageVersion = W.PageV2, W.caGeneratePageIndex = True, W.caBloomFilter = Just bloom}
+  bytes <- right (N.buildNestedFileWithAux (V.singleton aux) schema rows)
+  file <- right (R.loadParquetFile bytes)
+  restored <- right (Bloom.readBloomFilter file 0 0)
+  check "pre-built bloom filter is emitted" (restored == Just bloom)
+  let nullSchema = V.singleton ("v", N.NSOptional primitive)
+      nullRows = V.singleton (V.replicate 3 N.NRNull)
+  allNull <- right (N.buildNestedFileWithAux (V.singleton aux) nullSchema nullRows) >>= right . R.loadParquetFile
+  output <- lookupEnv "WIREFORM_PARQUET_PRIMITIVE_OUTPUT"
+  forM_ output $ \directory -> do
+    createDirectoryIfMissing True directory
+    BS.writeFile (directory </> "nested-bloom-with-options.parquet") bytes
+    let allNullBytes = N.buildNestedFileWithAux (V.singleton aux) nullSchema nullRows
+    right allNullBytes >>= BS.writeFile (directory </> "nested-all-null-with-options.parquet")
+  bounds <- right (Index.readColumnIndex allNull 0 0)
+  check "all-null page gets a truthful column index" (case bounds of Just value -> ciNullPages value == V.singleton True && ciNullCounts value == Just (V.singleton 3); _ -> False)
+  namedBloomTests
+  check "nested footer encryption cannot be silently ignored" (isLeft (H.encodeParquetNestedWith H.defaultWriteOptions {H.writeFooterEncryption = Just (W.FooterEncryption "invalid" "file" "" "")} schema rows))
+  check "wrong per-leaf auxiliary count is rejected" (isLeft (N.buildNestedFileWithAux (V.replicate 2 aux) schema rows))
+  check "deprecated LZ4 codec does not fall back to plaintext" (isLeft (H.encodeParquetNestedWith H.defaultWriteOptions {H.writeCompression = LZ4} schema rows))
+  let group = V.head (fmRowGroups (R.pfFooter file))
+  check "auxiliary layout detects final offset overflow" (isLeft (W.layoutColumnAuxiliaries (V.singleton group) (V.singleton (V.singleton aux)) maxBound))
+  putStrLn "Nested codec, page-version, index and option-boundary regressions passed."
+
+
+-- Mixed required/nullable and repeated data exercise every physical carrier.
+-- Expected filter bits are built from individual values, independently of
+-- the page's PLAIN framing and packed BOOLEAN representation.
+namedBloomTests :: IO ()
+namedBloomTests = do
+  output <- lookupEnv "WIREFORM_PARQUET_PRIMITIVE_OUTPUT"
+  let cases =
+        V.fromList
+          [ BloomCase N.LtInt32 (V.fromList [N.LvInt32 (-7), N.LvInt32 0, N.LvInt32 42])
+          , BloomCase N.LtInt64 (V.fromList [N.LvInt64 (-1099511627776), N.LvInt64 1099511627776])
+          , BloomCase N.LtFloat (V.fromList [N.LvFloat (castWord32ToFloat 0x7fc00001), N.LvFloat (-0), N.LvFloat 0, N.LvFloat (1 / 0)])
+          , BloomCase N.LtDouble (V.fromList [N.LvDouble (-0), N.LvDouble 0, N.LvDouble (1 / 0), N.LvDouble (-3.5)])
+          , BloomCase N.LtBool (V.generate 17 (N.LvBool . odd))
+          , BloomCase N.LtString (V.fromList [N.LvString "", N.LvString "alpha", N.LvString "λ\NULβ"])
+          , BloomCase N.LtBinary (V.fromList [N.LvBinary "", N.LvBinary "abc", N.LvBinary (BS.pack [0, 255, 4, 0, 0, 0])])
+          , BloomCase (N.LtFixedBinary 9) (V.fromList [N.LvFixedBinary (BS.replicate 9 0), N.LvFixedBinary (BS.replicate 9 255)])
+          , BloomCase N.LtUuid (V.singleton (N.LvFixedBinary (BS.pack [0 .. 15])))
+          , BloomCase N.LtInt96 (V.singleton (N.LvFixedBinary (BS.pack [0 .. 11])))
+          , BloomCase (N.LtTimestamp96 True LtNanos) (V.singleton (N.LvFixedBinary (BS.replicate 12 255)))
+          , BloomCase (N.LtDecimal 38 2) (V.fromList [N.LvFixedBinary (BS.replicate 16 255), N.LvFixedBinary (BS.replicate 16 0)])
+          , BloomCase (N.LtDecimal 76 2) (V.singleton (N.LvFixedBinary (BS.replicate 32 255)))
+          , BloomCase N.LtInt32 V.empty
+          , BloomCase N.LtBool (V.singleton (N.LvBool True))
+          , BloomCase N.LtBool (V.replicate 8 (N.LvBool False))
+          ]
+  V.imapM_
+    ( \index config -> forM_ [Uncompressed, GZip, Snappy, ZSTD, LZ4Raw, LZO, Brotli] $ \codec ->
+        case Compress.validateCompression codec of
+          Left _ -> pure ()
+          Right () -> forM_ [W.PageV1, W.PageV2] $ \version -> do
+            let name = "values.with.dot"
+                schema = V.fromList [(name, N.NSOptional (N.NSList (N.NSOptional (N.NSPrimitive (bloomCaseType config))))), ("unselected", N.NSPrimitive N.LtInt32)]
+                rows = V.fromList [V.fromList [N.NRNull, N.NRList V.empty, N.NRList (V.cons N.NRNull (V.map N.NRLeaf (bloomCaseValues config)))], V.fromList [N.NRLeaf (N.LvInt32 1), N.NRLeaf (N.LvInt32 2), N.NRLeaf (N.LvInt32 3)]]
+                options = H.defaultWriteOptions {H.writeCompression = codec, H.writePageVersion = version, H.writeBloomFilters = [name]}
+            bytes <- right (H.encodeParquetNestedWith options schema rows)
+            file <- right (R.loadParquetFile bytes)
+            found <- right (Bloom.readBloomFilter file 0 0) >>= maybe (fail "missing generated nested bloom") pure
+            let expected = V.foldl' (\filter_ value -> Bloom.sbbfInsert (plainBloomValue value) filter_) (Bloom.newSbbf (Bloom.sbbfNumBytes found)) (bloomCaseValues config)
+            check "nested bloom hashes every present value without page framing" (found == expected)
+            other <- right (Bloom.readBloomFilter file 0 1)
+            check "unrequested nested fields have no bloom" (other == Nothing)
+            forM_ output $ \directory -> BS.writeFile (directory </> ("nested-generated-bloom-" ++ show index ++ "-" ++ show codec ++ "-" ++ show version ++ ".parquet")) bytes
+            check "unknown nested bloom field is rejected" (isLeft (H.encodeParquetNestedWith options {H.writeBloomFilters = ["missing"]} schema rows))
+    )
+    cases
+  let struct = V.singleton ("record", N.NSStruct (V.fromList [("id", N.NSPrimitive N.LtInt32), ("flag", N.NSPrimitive N.LtBool)]))
+      rows = V.singleton (V.singleton (N.NRStruct (V.fromList [N.NRLeaf (N.LvInt32 42), N.NRLeaf (N.LvBool True)])))
+  file <- right (H.encodeParquetNestedWith H.defaultWriteOptions {H.writeCompression = Uncompressed, H.writeBloomFilters = ["record"]} struct rows) >>= right . R.loadParquetFile
+  forM_ [0, 1] $ \index -> right (Bloom.readBloomFilter file 0 index) >>= \value -> check "top-level field selects all physical descendants" (value /= Nothing)
+  let explicit = Bloom.sbbfInsert "caller-provided" (Bloom.sbbfInsert (plainBloomValue (N.LvInt32 42)) (Bloom.newSbbf 96))
+      auxes = V.fromList [W.emptyColumnAux {W.caBloomFilter = Just explicit}, W.emptyColumnAux]
+  custom <- right (N.buildNestedFileWithBloomFilters ["record"] auxes struct rows) >>= right . R.loadParquetFile
+  first <- right (Bloom.readBloomFilter custom 0 0)
+  check "explicit leaf bloom overrides name-based generation" (first == Just explicit)
+
+
+data BloomCase = BloomCase
+  { bloomCaseType :: !N.LeafType
+  , bloomCaseValues :: !(V.Vector N.LeafValue)
+  }
+
+
+plainBloomValue :: N.LeafValue -> BS.ByteString
+plainBloomValue value = case value of
+  N.LvInt32 x -> encode (Builder.int32LE x)
+  N.LvInt64 x -> encode (Builder.int64LE x)
+  N.LvFloat16 x -> encode (Builder.word16LE x)
+  N.LvFloat x -> encode (Builder.word32LE (castFloatToWord32 x))
+  N.LvDouble x -> encode (Builder.word64LE (castDoubleToWord64 x))
+  N.LvBool x -> BS.singleton (if x then 1 else 0)
+  N.LvString x -> Data.Text.Encoding.encodeUtf8 x
+  N.LvBinary x -> x
+  N.LvFixedBinary x -> x
+  where
+    encode = BL.toStrict . Builder.toLazyByteString
diff --git a/test/NestedPrimitiveRegression.hs b/test/NestedPrimitiveRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/NestedPrimitiveRegression.hs
@@ -0,0 +1,135 @@
+{-# LANGUAGE GADTs #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+module NestedPrimitiveRegression (tests) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Control.Exception (evaluate)
+import Control.Monad (forM_, unless)
+import Data.Bits (shiftR)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as B
+import Data.ByteString.Lazy qualified as BL
+import Data.Either (isLeft)
+import Data.Int (Int32)
+import Data.Vector qualified as V
+import Data.Vector.Storable qualified as S
+import Parquet.Arrow qualified as Arrow
+import Parquet.Nested qualified as N
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+import System.Directory (createDirectoryIfMissing)
+import System.Environment (lookupEnv)
+import System.FilePath ((</>))
+import System.Mem (performMajorGC)
+
+
+load :: Either String a -> IO a
+load = either fail pure
+
+
+check :: String -> Bool -> IO ()
+check label ok = unless ok (fail ("Nested primitive regression: " ++ label))
+
+
+fixed :: Int -> Integer -> BS.ByteString
+fixed width value = BS.pack (map (\index -> fromInteger (value `shiftR` (8 * (width - 1 - index)))) [0 .. width - 1])
+
+
+decimalRow :: Int -> Integer -> N.NestedRow
+decimalRow precision value = N.NRLeaf $ if precision <= 9 then N.LvInt32 (fromInteger value) else if precision <= 18 then N.LvInt64 (fromInteger value) else N.LvFixedBinary (fixed (if precision <= 38 then 16 else 32) value)
+
+
+tests :: IO ()
+tests = do
+  -- Exercise both sides of the payload-cache limit, retaining only the
+  -- public bytes after the producer and its input rows have gone away.
+  forM_ [False, True] $ \nested -> forM_ [131071, 131072, 131073] $ \count -> do
+    bytes <- ownedNumericPayload nested count
+    performMajorGC
+    let expected = BL.toStrict (B.toLazyByteString (foldMap (B.int64LE . fromIntegral) [0 .. count - 1]))
+    check "frozen payload retains exact bytes across GC and cache boundary" (bytes == expected)
+  output <- lookupEnv "WIREFORM_PARQUET_PRIMITIVE_OUTPUT"
+  forM_ output (createDirectoryIfMissing True)
+  forM_ [1 .. 76] $ \precision -> do
+    let bound = 10 ^ precision - 1
+        rows = V.fromList [decimalRow precision (negate bound), N.NRNull, decimalRow precision 0, decimalRow precision bound]
+        schema = N.NSOptional (N.NSPrimitive (N.LtDecimal (fromIntegral precision) (fromIntegral precision)))
+    bytes <- load (N.buildNestedFile (V.singleton ("d", schema)) (V.singleton rows))
+    file <- load (Read.loadParquetFile bytes)
+    let leaf = P.fmSchema (Read.pfFooter file) V.! 1
+        expectedPhysical = if precision <= 9 then P.PTInt32 else if precision <= 18 then P.PTInt64 else P.PTFixedLenByteArray
+    check "decimal precision/scale and carrier survive footer" (P.seLogicalType leaf == Just (P.LTDecimal (fromIntegral precision) (fromIntegral precision)) && P.seType leaf == Just expectedPhysical && P.seTypeLength leaf == (if precision <= 18 then Nothing else Just (if precision <= 38 then 16 else 32)))
+    arrowSchema <- load (Arrow.parquetFileArrowSchemaChecked file)
+    columns <- load (either (Left . show) Right (Arrow.parquetRowGroupToArrow arrowSchema file 0))
+    actual <- case V.head columns of
+      C.ColDecimal128 p s validity numbers -> do
+        check "decimal128 parameters retained" (p == precision && s == precision)
+        pure (map (\i -> if C.isValidAt validity i then Just (C.decimal128ToInteger (numbers S.! i)) else Nothing) [0 .. S.length numbers - 1])
+      C.ColDecimal256 p s validity numbers -> do
+        check "decimal256 parameters retained" (p == precision && s == precision)
+        pure (map (\i -> if C.isValidAt validity i then Just (C.decimal256ToInteger (numbers S.! i)) else Nothing) [0 .. S.length numbers - 1])
+      other -> fail ("expected a decimal column, got " ++ C.columnTag other)
+    check "signed extrema and nulls survive actual file decode" (actual == [Just (negate bound), Nothing, Just 0, Just bound])
+    forM_ output $ \dir -> BS.writeFile (dir </> ("decimal-" ++ show precision ++ ".parquet")) bytes
+    forM_ [negate bound - 1, bound + 1] $ \bad ->
+      check "coefficient outside precision rejected" (isLeft (N.shred schema (V.singleton (decimalRow precision bad))))
+  forM_ [(-1, 0), (0, 0), (77, 0), (10, -1), (10, 11), (maxBound, 0)] $ \(precision, scale) ->
+    check "invalid decimal schema rejected even without rows" (isLeft (N.buildNestedFile (V.singleton ("d", N.NSPrimitive (N.LtDecimal precision scale))) (V.singleton V.empty)))
+  forM_ [1, 2, 3, 16, 31, 32, 64] $ \width -> do
+    let value = BS.pack (map fromIntegral [0 .. width - 1])
+        rows = V.fromList [N.NRLeaf (N.LvFixedBinary value), N.NRNull, N.NRLeaf (N.LvFixedBinary (BS.replicate width 255))]
+        schema = N.NSOptional (N.NSPrimitive (N.LtFixedBinary (fromIntegral width)))
+    bytes <- load (N.buildNestedFile (V.singleton ("b", schema)) (V.singleton rows))
+    file <- load (Read.loadParquetFile bytes)
+    arrowSchema <- load (Arrow.parquetFileArrowSchemaChecked file)
+    columns <- load (either (Left . show) Right (Arrow.parquetRowGroupToArrow arrowSchema file 0))
+    check "fixed bytes have no BYTE_ARRAY prefix" (V.generate 3 (C.anyBytesAt (V.head columns)) == V.fromList [Just value, Nothing, Just (BS.replicate width 255)])
+    check "wrong fixed width rejected" (isLeft (N.shred schema (V.singleton (N.NRLeaf (N.LvFixedBinary (BS.replicate (width + 1) 0))))))
+    forM_ output $ \dir -> BS.writeFile (dir </> ("fixed-" ++ show width ++ ".parquet")) bytes
+  let uuid = BS.pack [0 .. 15]
+  uuidBytes <- load (N.buildNestedFile (V.singleton ("u", N.NSPrimitive N.LtUuid)) (V.singleton (V.singleton (N.NRLeaf (N.LvFixedBinary uuid)))))
+  uuidFile <- load (Read.loadParquetFile uuidBytes)
+  check "UUID has exact length16 and UUID annotation" (P.seLogicalType (P.fmSchema (Read.pfFooter uuidFile) V.! 1) == Just P.LTUUID)
+  forM_ output $ \dir -> BS.writeFile (dir </> "uuid.parquet") uuidBytes
+  forM_ [0, -1] $ \width -> check "invalid fixed width rejected without rows" (isLeft (N.buildNestedFile (V.singleton ("b", N.NSPrimitive (N.LtFixedBinary width))) (V.singleton V.empty)))
+  -- Exercise the public Arrow -> nested writer entry points for every carrier.
+  forM_ [(A.ADecimal32 9 2, C.primColumn (C.PDecimal32 9 2) (S.fromList [-999999999, 0, 123])), (A.ADecimal64 18 2, C.primColumn (C.PDecimal64 18 2) (S.fromList [-999999999999999999, 0, 123])), (A.ADecimal 38 2, C.primColumn (C.PDecimal128 38 2) (S.fromList (map C.decimal128FromInteger [-10 ^ 38 + 1, 0, 123]))), (A.ADecimal256 76 2, C.primColumn (C.PDecimal256 76 2) (S.fromList (map C.decimal256FromInteger [-10 ^ 76 + 1, 0, 123])))] $ \(typ, column) -> do
+    let field = A.defaultLeafField "d" False typ
+    schema <- load (Arrow.arrowFieldToNestedSchema field)
+    rows <- load (Arrow.columnArrayToNestedRows field column)
+    bytes <- load (N.buildNestedFile (V.singleton ("d", schema)) (V.singleton rows))
+    forM_ output $ \dir -> BS.writeFile (dir </> ("arrow-flat-" ++ show (case typ of A.ADecimal32 {} -> 32 :: Int; A.ADecimal64 {} -> 64; A.ADecimal {} -> 128; _ -> 256) ++ ".parquet")) bytes
+    list <- load (C.mkList Nothing (S.fromList [0, 1, 3]) column)
+    let listField = A.defaultField "l" False A.AList (V.singleton field)
+    listSchema <- load (Arrow.arrowFieldToNestedSchema listField)
+    listRows <- load (Arrow.columnArrayToNestedRows listField list)
+    listBytes <- load (N.buildNestedFile (V.singleton ("l", listSchema)) (V.singleton listRows))
+    forM_ output $ \dir -> BS.writeFile (dir </> ("arrow-list-" ++ show (case typ of A.ADecimal32 {} -> 32 :: Int; A.ADecimal64 {} -> 64; A.ADecimal {} -> 128; _ -> 256) ++ ".parquet")) listBytes
+    pure ()
+  let badDecimal = C.primColumn (C.PDecimal32 1 0) (S.singleton 10)
+  check "Arrow decimal conversion rejects out-of-precision values" (isLeft (Arrow.columnArrayToNestedRows (A.defaultLeafField "d" False (A.ADecimal32 1 0)) badDecimal))
+  let poison = C.primColumn (C.PDecimal32 1 0) (S.fromList [10, 1])
+      field = A.defaultLeafField "d" False (A.ADecimal32 1 0)
+  parent <- load (C.mkStruct 2 (C.validityFromBools (V.fromList [False, True])) (V.singleton ("d", poison)))
+  rows <- load (Arrow.columnArrayToNestedRows (A.defaultField "s" True A.AStruct (V.singleton field)) parent)
+  check "null parent masks invalid decimal child" (rows == V.fromList [N.NRNull, N.NRStruct (V.singleton (N.NRLeaf (N.LvInt32 1)))])
+  let uuidField = (A.defaultLeafField "u" False (A.AFixedSizeBinary 16)) {A.fieldMetadata = V.fromList [("ARROW:extension:name", "arrow.uuid"), ("ARROW:extension:metadata", "")]}
+  uuidColumn <- load (C.fromMaybeFixedSizeBinary 16 (V.singleton (Just uuid)))
+  uuidSchema <- load (Arrow.arrowFieldToNestedSchema uuidField)
+  uuidRows <- load (Arrow.columnArrayToNestedRows uuidField uuidColumn)
+  check "Arrow UUID maps to annotated fixed bytes" (uuidSchema == N.NSRequired (N.NSPrimitive N.LtUuid) && uuidRows == V.singleton (N.NRLeaf (N.LvFixedBinary uuid)))
+  forM_ [uuidField {A.fieldMetadata = A.fieldMetadata uuidField V.++ V.singleton ("ARROW:extension:name", "arrow.uuid")}, uuidField {A.fieldMetadata = V.fromList [("ARROW:extension:name", "arrow.uuid"), ("ARROW:extension:metadata", "wrong")]}] $ \invalid ->
+    check "UUID metadata is checked before writing" (isLeft (Arrow.arrowFieldToNestedSchema invalid))
+  putStrLn "Nested decimal/fixed/UUID precision, byte order, null and shape regressions passed"
+
+
+ownedNumericPayload :: Bool -> Int -> IO BS.ByteString
+ownedNumericPayload nested count = do
+  let values = V.generate count (N.NRLeaf . N.LvInt64 . fromIntegral)
+      rows = if nested then V.singleton (N.NRList values) else values
+      schema = if nested then N.NSOptional (N.NSList (N.NSOptional (N.NSPrimitive N.LtInt64))) else N.NSPrimitive N.LtInt64
+  leaves <- load (N.shred schema rows)
+  evaluate (N.nlValueBytes (V.head leaves))
+{-# NOINLINE ownedNumericPayload #-}
diff --git a/test/NestedStatisticsRegression.hs b/test/NestedStatisticsRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/NestedStatisticsRegression.hs
@@ -0,0 +1,180 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module NestedStatisticsRegression (tests) where
+
+import Arrow.Types qualified as A
+import Control.Monad (forM_, unless)
+import Data.Aeson qualified as J
+import Data.Bits (shiftR)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as B
+import Data.ByteString.Lazy qualified as BL
+import Data.Int (Int32, Int64)
+import Data.Ratio ((%))
+import Data.Text.Encoding qualified as TE
+import Data.Vector qualified as V
+import GHC.Float (castDoubleToWord64, castFloatToWord32, castWord32ToFloat, castWord64ToDouble)
+import Numeric (showHex)
+import Parquet.Arrow qualified as Arrow
+import Parquet.Compress qualified as Compress
+import Parquet.HighLevel qualified as H
+import Parquet.Nested qualified as N
+import Parquet.PageIndex qualified as Index
+import Parquet.Predicate qualified as Pred
+import Parquet.Read qualified as R
+import Parquet.Types
+import Parquet.Write qualified as W
+import System.Directory (createDirectoryIfMissing)
+import System.Environment (lookupEnv)
+import System.FilePath ((</>))
+
+
+check :: String -> Bool -> IO ()
+check label okay = unless okay (fail ("nested statistics: " ++ label))
+
+
+right :: Either String a -> IO a
+right = either fail pure
+
+
+data Case = Case
+  { caseName :: !String
+  , caseType :: !N.LeafType
+  , caseValues :: !(V.Vector N.LeafValue)
+  , caseMin :: !(Maybe N.LeafValue)
+  , caseMax :: !(Maybe N.LeafValue)
+  , caseOrder :: !ColumnOrder
+  , caseNans :: !(Maybe Int64)
+  , caseQueries :: ![Pred.PValue]
+  }
+
+
+cases :: V.Vector Case
+cases =
+  V.fromList
+    [ normal "i32" N.LtInt32 [N.LvInt32 minBound, N.LvInt32 7, N.LvInt32 maxBound, N.LvInt32 (-1)] (N.LvInt32 minBound) (N.LvInt32 maxBound) [Pred.PVInt32 minBound, Pred.PVInt32 7, Pred.PVInt32 maxBound, Pred.PVInt32 (-1)]
+    , normal "u32" (N.LtInteger 32 False) [N.LvInt32 (-1), N.LvInt32 0, N.LvInt32 minBound] (N.LvInt32 0) (N.LvInt32 (-1)) [Pred.PVUnsigned 4294967295, Pred.PVUnsigned 0, Pred.PVUnsigned 2147483648]
+    , normal "i64" N.LtInt64 [N.LvInt64 minBound, N.LvInt64 7, N.LvInt64 maxBound] (N.LvInt64 minBound) (N.LvInt64 maxBound) [Pred.PVInt64 minBound, Pred.PVInt64 7, Pred.PVInt64 maxBound]
+    , normal "u64" (N.LtInteger 64 False) [N.LvInt64 (-1), N.LvInt64 0, N.LvInt64 minBound] (N.LvInt64 0) (N.LvInt64 (-1)) [Pred.PVUnsigned maxBound, Pred.PVUnsigned 0, Pred.PVUnsigned 9223372036854775808]
+    , normal "decimal9" (N.LtDecimal 9 2) [N.LvInt32 17, N.LvInt32 (-99), N.LvInt32 0] (N.LvInt32 (-99)) (N.LvInt32 17) [Pred.PVDecimal ((-99) % 100), Pred.PVDecimal (17 % 100), Pred.PVDecimal 0]
+    , normal "decimal18" (N.LtDecimal 18 2) [N.LvInt64 17, N.LvInt64 (-100000000000000000), N.LvInt64 0] (N.LvInt64 (-100000000000000000)) (N.LvInt64 17) [Pred.PVDecimal ((-100000000000000000) % 100), Pred.PVDecimal (17 % 100), Pred.PVDecimal 0]
+    , wideDecimal 38 16
+    , wideDecimal 76 32
+    , normal "binary" N.LtBinary (map N.LvBinary ["a\0", "", "\xff", "a", "\0"]) (N.LvBinary "") (N.LvBinary "\xff") (map Pred.PVBinary ["a\0", "", "\xff", "a", "\0"])
+    , normal "text" N.LtString (map N.LvString ["α", "", "\0", "aaa", "日本"]) (N.LvString "") (N.LvString "日本") (map Pred.PVText ["α", "", "\0", "aaa", "日本"])
+    , normal "fixed9" (N.LtFixedBinary 9) (map (N.LvFixedBinary . BS.replicate 9) [128, 0, 255, 1]) (N.LvFixedBinary (BS.replicate 9 0)) (N.LvFixedBinary (BS.replicate 9 255)) []
+    , normal "uuid" N.LtUuid (map (N.LvFixedBinary . BS.replicate 16) [128, 0, 255, 1]) (N.LvFixedBinary (BS.replicate 16 0)) (N.LvFixedBinary (BS.replicate 16 255)) []
+    , floating "float-mixed" N.LtFloat (map (N.LvFloat . castWord32ToFloat) [0x7fc00001, 0x80000000, 0, 0xff800000, 0x7f800000]) (N.LvFloat (-1 / 0)) (N.LvFloat (1 / 0)) 1 [Pred.PVFloat (-1 / 0), Pred.PVFloat (-0), Pred.PVFloat 0, Pred.PVFloat (1 / 0)]
+    , floating "double-mixed" N.LtDouble [N.LvDouble (castWord64ToDouble 0xfff8000000000001), N.LvDouble (castWord64ToDouble 0x7ff8000000000002), N.LvDouble 0, N.LvDouble (-0), N.LvDouble (-1.5), N.LvDouble 7.5, N.LvDouble (castWord64ToDouble 0x7ff0000000000001)] (N.LvDouble (-1.5)) (N.LvDouble 7.5) 3 [Pred.PVDouble 0, Pred.PVDouble (-0), Pred.PVDouble (-1.5), Pred.PVDouble 7.5]
+    , floating "float-nans" N.LtFloat (map (N.LvFloat . castWord32ToFloat) [0x7fc00001, 0x7f800001, 0xffc00007, 0xff800002]) (N.LvFloat (castWord32ToFloat 0xffc00007)) (N.LvFloat (castWord32ToFloat 0x7fc00001)) 4 []
+    , floating "double-nans" N.LtDouble (map (N.LvDouble . castWord64ToDouble) [0x7ff8000000000011, 0xfff8000000000022, 0x7ff0000000000001]) (N.LvDouble (castWord64ToDouble 0xfff8000000000022)) (N.LvDouble (castWord64ToDouble 0x7ff8000000000011)) 3 []
+    , floating "float-minus-zero" N.LtFloat [N.LvFloat (-0)] (N.LvFloat (-0)) (N.LvFloat (-0)) 0 [Pred.PVFloat 0, Pred.PVFloat (-0)]
+    , floating "float-plus-zero" N.LtFloat [N.LvFloat 0] (N.LvFloat 0) (N.LvFloat 0) 0 [Pred.PVFloat 0, Pred.PVFloat (-0)]
+    , floating "double-zeros" N.LtDouble [N.LvDouble 0, N.LvDouble (-0)] (N.LvDouble (-0)) (N.LvDouble 0) 0 [Pred.PVDouble 0, Pred.PVDouble (-0)]
+    , floating "half-nans" N.LtFloat16 (map N.LvFloat16 [0x7e01, 0x7c01, 0xfe07, 0xfc02]) (N.LvFloat16 0xfe07) (N.LvFloat16 0x7e01) 4 []
+    , floating "half-values" N.LtFloat16 (map N.LvFloat16 [0, 0x8000, 0x3c00, 0xbc00, 0x0001]) (N.LvFloat16 0xbc00) (N.LvFloat16 0x3c00) 0 [Pred.PVDouble 0, Pred.PVDouble (-0), Pred.PVDouble (-1), Pred.PVDouble 1]
+    , normal "bool" N.LtBool (map N.LvBool [True, False, True, False, True, False, True, False, True]) (N.LvBool False) (N.LvBool True) [Pred.PVBool False, Pred.PVBool True]
+    , (normal "int96" N.LtInt96 [clock 0 0, clock minBound 0, clock maxBound (-1), clock minBound maxBound, clock maxBound maxBound, clock 0 minBound] (clock 0 minBound) (clock maxBound maxBound) []) {caseOrder = Int96TimestampOrder}
+    , (normal "int96-counterexample" N.LtInt96 [clock minBound 0, clock 0 0] (clock minBound 0) (clock 0 0) []) {caseOrder = Int96TimestampOrder}
+    , normal "timestamp96-counterexample" (N.LtTimestamp96 True LtNanos) [clock minBound 0, clock 0 0] (clock 0 0) (clock minBound 0) []
+    , normal "timestamp96-wide" (N.LtTimestamp96 False LtMicros) (map (N.LvFixedBinary . signedLittle12) [-(2 ^ 95), -1, 0, 2 ^ 63, 2 ^ 95 - 1]) (N.LvFixedBinary (signedLittle12 (-(2 ^ 95)))) (N.LvFixedBinary (signedLittle12 (2 ^ 95 - 1))) []
+    , Case "all-null-double" N.LtDouble V.empty Nothing Nothing IEEE754TotalOrder (Just 0) []
+    , Case "all-null-int96" N.LtInt96 V.empty Nothing Nothing Int96TimestampOrder Nothing []
+    ]
+  where
+    normal name typ vals low high queries = Case name typ (V.fromList vals) (Just low) (Just high) TypeDefinedOrder Nothing queries
+    floating name typ vals low high nans queries = (normal name typ vals low high queries) {caseOrder = IEEE754TotalOrder, caseNans = Just nans}
+    wideDecimal precision width =
+      let bound = 10 ^ precision - 1; value = N.LvFixedBinary . signedBig width
+      in normal ("decimal" ++ show precision) (N.LtDecimal (fromIntegral precision) 2) (map value [0, -1, bound, -bound]) (value (-bound)) (value bound) (map (Pred.PVDecimal . (% 100)) [0, -1, bound, -bound])
+
+
+clock :: Int64 -> Int32 -> N.LeafValue
+clock nanos day = N.LvFixedBinary (encode (B.int64LE nanos <> B.int32LE day))
+
+
+signedBig :: Int -> Integer -> BS.ByteString
+signedBig width value = BS.pack (map (\index -> fromInteger (value `shiftR` (8 * (width - 1 - index)))) [0 .. width - 1])
+
+
+signedLittle12 :: Integer -> BS.ByteString
+signedLittle12 value = BS.pack (map (\index -> fromInteger (value `shiftR` (8 * index))) [0 .. 11])
+
+
+encode :: B.Builder -> BS.ByteString
+encode = BL.toStrict . B.toLazyByteString
+
+
+plain :: N.LeafValue -> BS.ByteString
+plain value = case value of
+  N.LvInt32 x -> encode (B.int32LE x)
+  N.LvInt64 x -> encode (B.int64LE x)
+  N.LvFloat16 x -> encode (B.word16LE x)
+  N.LvFloat x -> encode (B.word32LE (castFloatToWord32 x))
+  N.LvDouble x -> encode (B.word64LE (castDoubleToWord64 x))
+  N.LvBool x -> BS.singleton (if x then 1 else 0)
+  N.LvString x -> TE.encodeUtf8 x
+  N.LvBinary x -> x
+  N.LvFixedBinary x -> x
+
+
+hex :: BS.ByteString -> String
+hex = concatMap (\byte -> let text = showHex byte "" in if length text == 1 then '0' : text else text) . BS.unpack
+
+
+tests :: IO ()
+tests = do
+  output <- lookupEnv "WIREFORM_PARQUET_PRIMITIVE_OUTPUT"
+  forM_ output $ \directory -> do
+    createDirectoryIfMissing True directory
+    BL.writeFile (directory </> "nested-stats-models.json") $
+      J.encode $
+        V.map
+          ( \config ->
+              J.object
+                [ "name" J..= caseName config
+                , "type" J..= show (caseType config)
+                , "values" J..= V.map (hex . plain) (caseValues config)
+                , "min" J..= fmap (hex . plain) (caseMin config)
+                , "max" J..= fmap (hex . plain) (caseMax config)
+                , "order" J..= show (caseOrder config)
+                , "nans" J..= caseNans config
+                ]
+          )
+          cases
+  forM_ [Uncompressed, GZip, Snappy, ZSTD, LZ4Raw, LZO, Brotli] $ \codec -> case Compress.validateCompression codec of
+    Left _ -> pure ()
+    Right () -> forM_ [W.PageV1, W.PageV2] $ \version -> forM_ [False, True] $ \indexed -> V.forM_ cases $ \config -> do
+      let schema = V.singleton ("v", N.NSOptional (N.NSList (N.NSOptional (N.NSPrimitive (caseType config)))))
+          rows = V.singleton (V.fromList [N.NRNull, N.NRList V.empty, N.NRList (V.cons N.NRNull (V.map N.NRLeaf (caseValues config)))])
+          options = H.defaultWriteOptions {H.writeCompression = codec, H.writePageVersion = version, H.writePageIndex = indexed, H.writeBloomFilters = ["v"]}
+      bytes <- right (H.encodeParquetNestedWith options schema rows)
+      file <- right (R.loadParquetFile bytes)
+      let metadata = R.pfFooter file; chunk = V.head (rgColumns (V.head (fmRowGroups metadata)))
+      cm <- maybe (fail "missing column metadata") pure (ccMetadata chunk)
+      stats <- maybe (fail "missing statistics") pure (cmStatistics cm)
+      context <- maybe (fail "missing statistics context") pure (Pred.statisticsContext metadata 0)
+      case caseType config of
+        N.LtFloat16 -> do
+          arrowSchema <- right (Arrow.parquetFileArrowSchemaChecked file)
+          arrowColumns <- either (fail . show) pure (Arrow.parquetRowGroupToArrow arrowSchema file 0)
+          actualRows <- right (Arrow.columnArrayToNestedRows (V.head (A.arrowFields arrowSchema)) (V.head arrowColumns))
+          check "binary16 nested Arrow round-trip retains all raw bits and nulls" (actualRows == V.head rows)
+        _ -> pure ()
+      check (caseName config ++ " min") (statMinValue stats == fmap plain (caseMin config))
+      check (caseName config ++ " max") (statMaxValue stats == fmap plain (caseMax config))
+      check "truthful null count" (statNullCount stats == Just 3)
+      check "truthful NaN count" (statNanCount stats == caseNans config)
+      check "explicit ordering survives footer" (fmColumnOrders metadata == Just (V.singleton (caseOrder config)))
+      ci <- right (Index.readColumnIndex file 0 0)
+      oi <- right (Index.readOffsetIndex file 0 0)
+      check "requested index presence" ((ci /= Nothing) == indexed && (oi /= Nothing) == indexed)
+      forM_ ci $ \index -> do
+        check "page bounds equal chunk bounds" (ciMinValues index == V.singleton (maybe BS.empty plain (caseMin config)) && ciMaxValues index == V.singleton (maybe BS.empty plain (caseMax config)))
+        check "page null and NaN counts" (ciNullCounts index == Just (V.singleton 3) && ciNanCounts index == fmap V.singleton (caseNans config))
+        check "null page marker" (ciNullPages index == V.singleton (V.null (caseValues config)))
+      forM_ (caseQueries config) $ \query -> do
+        check "chunk statistics must retain every matching value" (Pred.evalColumnChunk context chunk (Pred.PEq query) /= Pred.PSkip)
+        forM_ ci $ \index -> check "page statistics must retain every matching value" (V.all (/= Pred.PSkip) (Pred.evalPagesByColumnIndex context index (Pred.PEq query)))
+      forM_ output $ \directory -> BS.writeFile (directory </> ("nested-stats-" ++ caseName config ++ "-" ++ show codec ++ "-" ++ show version ++ "-" ++ show indexed ++ ".parquet")) bytes
+  putStrLn "Nested signed/unsigned/decimal/IEEE/INT96/signed96 statistics and pruning regressions passed."
diff --git a/test/SchemaBoundaryRegression.hs b/test/SchemaBoundaryRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/SchemaBoundaryRegression.hs
@@ -0,0 +1,91 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module SchemaBoundaryRegression (tests) where
+
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft, isRight)
+import Data.Text (Text)
+import Data.Vector qualified as V
+import Parquet.Arrow qualified as Arrow
+import Parquet.Footer qualified as Footer
+import Parquet.HighLevel qualified as High
+import Parquet.Levels qualified as Levels
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+
+
+check :: String -> Bool -> IO ()
+check name ok = unless ok (fail ("Schema boundary regression: " ++ name))
+
+
+node :: Text -> Maybe P.ParquetType -> Maybe P.Repetition -> Maybe Int -> P.SchemaElement
+node name typ repetition count =
+  P.SchemaElement
+    { P.seName = name
+    , P.seType = typ
+    , P.seRepetition = repetition
+    , P.seNumChildren = fromIntegral <$> count
+    , P.seConvertedType = Nothing
+    , P.seLogicalType = Nothing
+    , P.seFieldId = Nothing
+    , P.seTypeLength = Nothing
+    }
+
+
+root :: P.SchemaElement
+root = node "schema" Nothing Nothing (Just 1)
+
+
+leaf :: P.SchemaElement
+leaf = node "x" (Just P.PTInt32) (Just P.Required) Nothing
+
+
+tests :: IO ()
+tests = do
+  let group = node "g" Nothing (Just P.Optional) (Just 1)
+      depth n = V.singleton root <> V.replicate n (node "g" Nothing (Just P.Required) (Just 1)) <> V.singleton leaf
+      reject name schema path levelFailure = do
+        let metadata = P.FileMetadata 1 schema 0 V.empty Nothing Nothing Nothing
+            bytes = "PAR1" <> Footer.writeFooter metadata
+            input = Read.ParquetFile bytes metadata
+        check (name ++ " checked schema") (isLeft (Arrow.parquetFileArrowSchemaChecked input))
+        check (name ++ " public file decode") (isLeft (High.decodeParquet High.defaultReadOptions bytes))
+        if levelFailure then check (name ++ " selected path") (isLeft (Levels.maxLevelsForColumnPath schema (V.fromList path))) else pure ()
+  reject "missing leaf repetition" (V.fromList [root, leaf {P.seRepetition = Nothing}]) ["x"] True
+  reject "missing group repetition" (V.fromList [root, group {P.seRepetition = Nothing}, leaf]) ["g", "x"] True
+  reject "missing nested leaf repetition" (V.fromList [root, group, leaf {P.seRepetition = Nothing}]) ["g", "x"] True
+  forM_ [0, 1, -1] $ \count -> reject "primitive carrying num_children" (V.fromList [root, leaf {P.seNumChildren = Just count}]) ["x"] True
+  reject "missing root count" (V.singleton root {P.seNumChildren = Nothing}) ["x"] True
+  reject "negative root count" (V.fromList [root {P.seNumChildren = Just (-1)}, leaf]) ["x"] True
+  reject "oversized root count" (V.fromList [root {P.seNumChildren = Just maxBound}, leaf]) ["x"] True
+  reject "missing group count" (V.fromList [root, group {P.seNumChildren = Nothing}, leaf]) ["g", "x"] True
+  reject "negative group count" (V.fromList [root, group {P.seNumChildren = Just (-1)}, leaf]) ["g", "x"] True
+  reject "primitive root" (V.singleton leaf) ["x"] True
+  reject "trailing physical nodes" (V.fromList [root, leaf, leaf {P.seName = "extra"}]) ["x"] False
+  reject "malformed skipped sibling" (V.fromList [root {P.seNumChildren = Just 2}, leaf {P.seName = "bad", P.seRepetition = Nothing}, leaf]) ["x"] True
+  reject "oversized selected depth" (depth 129) (replicate 129 "g" ++ ["x"]) False
+  let skipped = V.singleton root {P.seNumChildren = Just 2} <> V.replicate 129 (node "g" Nothing (Just P.Required) (Just 1)) <> V.fromList [leaf {P.seName = "hidden"}, leaf]
+  reject "oversized skipped depth" skipped ["x"] False
+  -- Root markers occur in common producers but describe no parent relation.
+  -- They must never add levels or make an otherwise valid root unreadable.
+  forM_ [Nothing, Just P.Required, Just P.Optional, Just P.Repeated] $ \marker -> do
+    let schema = V.fromList [root {P.seRepetition = marker}, group, leaf {P.seRepetition = Just P.Repeated}]
+        metadata = P.FileMetadata 1 schema 0 V.empty Nothing Nothing Nothing
+        bytes = "PAR1" <> Footer.writeFooter metadata
+    check "valid root-marker compatibility" (isRight (High.decodeParquet High.defaultReadOptions bytes))
+    check "root marker does not alter levels" (Levels.maxLevelsForColumnPath schema (V.fromList ["g", "x"]) == Right (1, 2))
+  forM_ [0, 1, 127, 128] $ \n -> do
+    let schema = depth n
+        metadata = P.FileMetadata 1 schema 0 V.empty Nothing Nothing Nothing
+        bytes = "PAR1" <> Footer.writeFooter metadata
+    check "inclusive selected depth limit" (isRight (High.decodeParquet High.defaultReadOptions bytes))
+    check "inclusive level-lookup depth limit" (Levels.maxLevelsForColumnPath schema (V.fromList (replicate n "g" ++ ["x"])) == Right (0, 0))
+  let deep = depth 5000
+      deepPath = V.fromList (replicate 5000 "g" ++ ["x"])
+      deepSkipped = V.singleton root {P.seNumChildren = Just 2} <> V.replicate 5000 (node "g" Nothing (Just P.Required) (Just 1)) <> V.fromList [leaf {P.seName = "hidden"}, leaf]
+  check "low-level selected lookup preserves deep valid schemas" (Levels.maxLevelsForColumnPath deep deepPath == Right (0, 0))
+  check "skipped subtree scan is iterative at deep valid schemas" (Levels.maxLevelsForColumnPath deepSkipped (V.singleton "x") == Right (0, 0))
+  check "empty input schema" (isLeft (Levels.maxLevelsForColumnPath V.empty (V.singleton "x")))
+  check "empty path" (isLeft (Levels.maxLevelsForColumnPath (V.fromList [root, leaf]) V.empty))
+  check "empty file bytes remain rejected" (isLeft (High.decodeParquet High.defaultReadOptions BS.empty))
diff --git a/test/Selection.hs b/test/Selection.hs
new file mode 100644
--- /dev/null
+++ b/test/Selection.hs
@@ -0,0 +1,2453 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module Selection (run) where
+
+import Arrow.Column qualified as A
+import Arrow.Column.Buffer qualified as Buffer
+import Arrow.Types qualified as T
+import Control.Concurrent (forkIO, newEmptyMVar, putMVar, takeMVar)
+import Control.Exception (evaluate, finally)
+import Control.Monad (replicateM_, unless, when)
+import Data.Bits (setBit, shiftL, shiftR, testBit, xor, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as Builder
+import Data.ByteString.Internal qualified as BSI
+import Data.ByteString.Lazy qualified as Lazy
+import Data.Either (isLeft, isRight)
+import Data.Int (Int32, Int64)
+import Data.List qualified as List
+import Data.Text (Text)
+import Data.Text qualified as TextValue
+import Data.Text.Encoding qualified as Text
+import Data.Vector qualified as V
+import Data.Vector.Generic.Base qualified as VG
+import Data.Vector.Primitive qualified as P
+import Data.Vector.Storable qualified as S
+import Data.Word (Word32, Word64, Word8)
+import Foreign.ForeignPtr (mallocForeignPtrBytes)
+import GHC.Conc (getAllocationCounter)
+import GHC.Float (castDoubleToWord64, castFloatToWord32, castWord32ToFloat, castWord64ToDouble)
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Arrow qualified as Arrow
+import Parquet.ByteStreamSplit qualified as ByteStreamSplit
+import Parquet.DeltaEncode qualified as Delta
+import Parquet.Footer qualified as Footer
+import Parquet.LevelsEncode qualified as Levels
+import Parquet.Nested qualified as Nested
+import Parquet.Page qualified as Page
+import Parquet.PageIndex qualified as Index
+import Parquet.Predicate qualified as Pred
+import Parquet.Read qualified as Read
+import Parquet.Types
+import Parquet.Write qualified as Write
+import System.Mem (performGC)
+import Wireform.Hash qualified as Hash
+
+
+data TestPage = TestPage
+  { testBytes :: !ByteString
+  , testRows :: {-# UNPACK #-} !Int
+  , testStats :: !Statistics
+  }
+
+
+data Fixture = Fixture
+  { fixtureFile :: !Read.ParquetFile
+  , fixtureLocations :: !(V.Vector PageLocation)
+  , fixtureFooterStart :: {-# UNPACK #-} !Int
+  }
+
+
+run :: IO ()
+run = do
+  let leaf = SchemaElement "x" (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+      schema = V.fromList [root, leaf]
+      native = field (T.AInt 32 True) False
+      values = V.fromList [intPage [1, 2, 3], intPage [10, 20, 30]]
+      plain = indexed schema (V.singleton "x") values Nothing
+      file = fixtureFile plain
+      predicate = Pred.PGtEq (Pred.PVInt32 10)
+      selected input target = Arrow.readParquetColumnWithPagePruning input 0 0 target predicate
+      expected = A.primColumn A.PInt32 (S.fromList [10, 20, 30])
+  check
+    "dense selection returns only the retained page"
+    (selected file native == Right (Just (1, 2), expected))
+  check
+    "required file can be projected into a nullable selected target"
+    (selected file (native {T.fieldNullable = True}) == Right (Just (1, 2), expected))
+  check
+    "selected reads apply checked integer widening"
+    ( selected file (field (T.AInt 64 True) False)
+        == Right (Just (1, 2), A.primColumn A.PInt64 (S.fromList [10, 20, 30]))
+    )
+  mapM_
+    ( \wrong -> do
+        check
+          "selected reads reject physical reinterpretation"
+          (isLeft (selected file (field wrong True)))
+        check
+          "empty selections still reject an incompatible target"
+          (isLeft (Arrow.readParquetColumnWithPagePruning file 0 0 (field wrong True) (Pred.PGt (Pred.PVInt32 100))))
+    )
+    [T.ABool, T.AFloatingPoint T.Single, T.AInt 32 False]
+  let first = fixtureLocations plain V.! 0
+      corrupted =
+        file
+          { Read.pfBytes =
+              replace
+                (fromIntegral (plOffset first))
+                (BS.replicate (fromIntegral (plCompressedPageSize first)) 0xff)
+                (Read.pfBytes file)
+          }
+  check
+    "skipped pages are not parsed or decoded"
+    (selected corrupted native == Right (Just (1, 2), expected))
+  check
+    "a retained corrupt page is rejected"
+    (isLeft (Arrow.readParquetColumnWithPagePruning corrupted 0 0 native (Pred.PGtEq (Pred.PVInt32 0))))
+  let withoutIndexes =
+        mapChunk
+          ( \chunk ->
+              chunk
+                { ccColumnIndexOffset = Nothing
+                , ccColumnIndexLength = Nothing
+                , ccOffsetIndexOffset = Nothing
+                , ccOffsetIndexLength = Nothing
+                }
+          )
+          file
+  check
+    "fallback and indexed reads use the same widening rules"
+    ( selected withoutIndexes (field (T.AInt 64 True) False)
+        == Right (Nothing, A.primColumn A.PInt64 (S.fromList [1, 2, 3, 10, 20, 30]))
+    )
+  let noBounds =
+        mapChunk
+          ( \chunk ->
+              chunk
+                { ccColumnIndexOffset = Nothing
+                , ccColumnIndexLength = Nothing
+                , ccOffsetIndexOffset = Just (-1)
+                }
+          )
+          file
+  check
+    "fallback does not read an unused offset index"
+    (selected noBounds native == Right (Nothing, A.primColumn A.PInt32 (S.fromList [1, 2, 3, 10, 20, 30])))
+  let contexts = Read.PageSelection (fixtureLocations plain) (V.fromList [False, True]) Nothing (Just 6)
+  mapM_
+    ( \bad ->
+        check
+          "selected readers validate sizes/order/rows/masks before indexing"
+          (isLeft (Read.readInt32SelectedLevels Uncompressed 0 0 (Read.pfBytes file) bad))
+    )
+    [ contexts {Read.selectionKeep = V.empty}
+    , contexts {Read.selectionLocations = V.reverse (fixtureLocations plain)}
+    , contexts {Read.selectionLocations = fixtureLocations plain V.// [(1, first)]}
+    , contexts {Read.selectionLocations = fixtureLocations plain V.// [(1, (fixtureLocations plain V.! 1) {plOffset = -1})]}
+    , contexts {Read.selectionLocations = fixtureLocations plain V.// [(1, (fixtureLocations plain V.! 1) {plCompressedPageSize = 1})]}
+    , contexts {Read.selectionRowCount = Just 7}
+    ]
+  let tiny = mapChunk (\chunk -> chunk {ccMetadata = (\md -> md {cmTotalCompressedSize = 1}) <$> ccMetadata chunk}) file
+  check
+    "offset indexes cannot escape their column chunk"
+    (isLeft (Index.readOffsetIndex tiny 0 0))
+  check
+    "external-column page indexes cannot read local bytes"
+    (isLeft (selected (mapChunk (\chunk -> chunk {ccFilePath = Just "external.parquet"}) file) native))
+  let badCount = mapChunk (\chunk -> chunk {ccMetadata = (\md -> md {cmNumValues = 7}) <$> ccMetadata chunk}) file
+  check
+    "full column reads reject inconsistent column event counts"
+    (isLeft (Arrow.readParquetColumn badCount 0 0 native))
+  let shortMetadata =
+        mapChunk
+          (\chunk -> chunk {ccMetadata = (\md -> md {cmNumValues = 5}) <$> ccMetadata chunk})
+          (file {Read.pfFooter = (Read.pfFooter file) {fmRowGroups = (\group -> group {rgNumRows = 5}) <$> fmRowGroups (Read.pfFooter file)}})
+  check
+    "full column reads reject decoded rows differing from consistent footer counts"
+    (isLeft (Arrow.readParquetColumn shortMetadata 0 0 native))
+  check
+    "an empty selection cannot hide inconsistent column event counts"
+    (isLeft (Arrow.readParquetColumnWithPagePruning badCount 0 0 native (Pred.PGt (Pred.PVInt32 100))))
+  index <- either error (maybe (error "missing index") pure) (Index.readColumnIndex file 0 0)
+  let short =
+        Index.encodeColumnIndex
+          ( index
+              { ciNullPages = V.take 1 (ciNullPages index)
+              , ciMinValues = V.take 1 (ciMinValues index)
+              , ciMaxValues = V.take 1 (ciMaxValues index)
+              , ciNullCounts = V.take 1 <$> ciNullCounts index
+              }
+          )
+      chunk = rgColumns (V.head (fmRowGroups (Read.pfFooter file))) V.! 0
+      indexOffset = maybe (error "missing index offset") fromIntegral (ccColumnIndexOffset chunk)
+      mismatched =
+        mapChunk
+          (\column -> column {ccColumnIndexLength = Just (fromIntegral (BS.length short))})
+          (file {Read.pfBytes = replace indexOffset short (Read.pfBytes file)})
+  check
+    "column and offset indexes must describe the same page count"
+    (isLeft (selected mismatched native))
+  nullableSelection
+  nullableByteSelection
+  dictionarySelection
+  binaryBuffersRegression
+  dictionaryExpansionRegression
+  dictionaryAllocationRegression
+  dictionarySequenceRegression
+  scalarBuffersRegression
+  packedBoolRegression
+  byteStreamSplitRegression
+  legacyChunkAccumulationRegression
+  statisticsTraversalRegression
+  nullableAssemblyRegression
+  deltaEncodingRegression
+  deltaPackingRegression
+  dictionaryFloatingRegression
+  dictionaryConstructionRegression
+  dictionaryRefinementGrowthRegression
+  dictionaryBucketMixRegression
+  dictionaryScalarStorageRegression
+  dictionaryEqualityRegression
+  dictionaryEqualityCancellationRegression
+  dictionaryOwnerRegression
+  nestedAnnotationRegression
+  nestedPageBoundsRegression
+  nestedShredBoundsRegression
+  footerWriteBoundsRegression
+  nestedProjectionRegression
+
+
+data NestedTypeCase = NestedTypeCase
+  { nestedInputType :: !T.ArrowType
+  , nestedInputColumn :: !A.ColumnArray
+  , nestedExpectedType :: !T.ArrowType
+  , nestedExpectedColumn :: !A.ColumnArray
+  }
+
+
+footerWriteBoundsRegression :: IO ()
+footerWriteBoundsRegression = do
+  let name = TextValue.replicate (512 * 1024) "é"
+      count = 4096
+      element = SchemaElement name (Just Required) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+      schema = V.cons (root {seNumChildren = Just (fromIntegral count)}) (V.replicate count element)
+      metadata = FileMetadata 2 schema 0 V.empty Nothing Nothing Nothing
+  _ <- evaluate (TextValue.length name)
+  beforeMetadata <- getAllocationCounter
+  rejectedMetadata <- evaluate (Footer.writeFooterEither metadata)
+  afterMetadata <- getAllocationCounter
+  check "typed metadata exceeds footer budget before allocating a 4GiB encoded buffer" $
+    rejectedMetadata == Left "Thrift.Encode: encoded value exceeds size limit"
+  check ("typed oversized metadata sizing stays bounded: " ++ show (beforeMetadata - afterMetadata)) (beforeMetadata - afterMetadata < 16 * 1024 * 1024)
+  let footerEncryption = Write.FooterEncryption (BS.replicate 16 0) "fileid01" BS.empty "test-key"
+  beforeEncrypted <- getAllocationCounter
+  rejectedEncrypted <- Write.buildParquetFileWithIndexEncryptedFooter footerEncryption schema V.empty V.empty
+  afterEncrypted <- getAllocationCounter
+  check "encrypted footer rejects oversized schema before serialization or encryption" $
+    rejectedEncrypted == Left "Thrift.Encode: encoded value exceeds size limit"
+  check "encrypted oversized schema sizing stays bounded" (beforeEncrypted - afterEncrypted < 16 * 1024 * 1024)
+  check "raw footer writes a little-endian length and four-byte magic" $
+    Footer.writeRawFooterEither Footer.parquetMagic "abc" == Right ("abc" <> BS.pack [3, 0, 0, 0] <> "PAR1")
+  check "empty encrypted footer framing preserves PARE" $
+    Footer.writeRawFooterEither Footer.parquetEncryptedMagic BS.empty == Right (BS.replicate 4 0 <> "PARE")
+  mapM_
+    (\magic -> check "raw footer rejects magic with the wrong byte length" (isLeft (Footer.writeRawFooterEither magic "metadata")))
+    [BS.empty, "PAR", "PAR11"]
+  when (toInteger (maxBound :: Int) > toInteger (maxBound :: Word32)) $ do
+    storage <- mallocForeignPtrBytes 1
+    let limit = fromIntegral (maxBound :: Word32)
+        bytes n = BSI.fromForeignPtr storage 0 n
+    -- Synthetic length only: neither case may read the one-byte backing store.
+    cryptoRejected <-
+      Write.buildParquetFileWithIndexEncryptedFooter
+        (footerEncryption {Write.feKeyMetadata = bytes limit})
+        (V.singleton (root {seNumChildren = Just 0}))
+        V.empty
+        V.empty
+    check "encrypted footer reserves crypto headers, nonce and authentication tag" $
+      cryptoRejected == Left "Thrift.Encode: encoded value exceeds size limit"
+    combinedRejected <-
+      Write.buildParquetFileWithIndexEncryptedFooter
+        (footerEncryption {Write.feKeyMetadata = bytes (limit - 64)})
+        (V.fromList [root, element])
+        V.empty
+        V.empty
+    check "encrypted footer checks the combined crypto and plaintext metadata budget before copying either" $
+      combinedRejected == Left "Thrift.Encode: encoded value exceeds size limit"
+    before <- getAllocationCounter
+    rejected <- evaluate (Footer.writeRawFooterEither Footer.parquetMagic (bytes (limit + 1)))
+    accepted <- evaluate (isRight (Footer.writeRawFooterEither Footer.parquetMagic (bytes limit)))
+    after <- getAllocationCounter
+    check "raw footer rejects unsigned32 length overflow before reading/copying metadata" $
+      rejected == Left "Parquet.Footer: metadata length exceeds unsigned 32-bit footer limit"
+    check "raw footer accepts the full unsigned32 length range without forcing output" accepted
+    check "raw footer length checks have bounded allocation" (before - after < 65536)
+
+
+nestedShredBoundsRegression :: IO ()
+nestedShredBoundsRegression = do
+  let width = 1024 * 1024
+      count = 2048
+      binary = BS.replicate width 0
+      row = Nested.NRLeaf . Nested.LvBinary
+      binaryRows = V.replicate count (row binary)
+      binarySchema = Nested.NSPrimitive Nested.LtBinary
+      sources =
+        [ Nested.LvBinary binary
+        , Nested.LvString (TextValue.replicate (width `quot` 2) "é")
+        , Nested.LvString (TextValue.replicate (width `quot` 4) "🙂")
+        ]
+  mapM_
+    ( \value -> do
+        let typ = case value of Nested.LvBinary {} -> Nested.LtBinary; _ -> Nested.LtString
+            schema = Nested.NSPrimitive typ
+            rows = V.replicate count (Nested.NRLeaf value)
+        _ <- evaluate (Nested.NRLeaf value)
+        _ <- evaluate (V.length rows)
+        before <- getAllocationCounter
+        rejected <- evaluate (isLeft (Nested.shred schema rows))
+        after <- getAllocationCounter
+        check "shred rejects cumulative binary/UTF8 bytes before materializing a 2GiB buffer" rejected
+        check ("oversized binary/UTF8 preflight allocation remains bounded: " ++ show (before - after)) (before - after < 2 * 1024 * 1024)
+        beforeValid <- getAllocationCounter
+        accepted <- evaluate (isRight (Nested.shred schema (V.take (count - 1) rows)))
+        afterValid <- getAllocationCounter
+        check "shred accepts a near-limit valid cumulative byte count without forcing output bytes" accepted
+        check "accepted preflight does not materialize the large output buffer" (beforeValid - afterValid < 2 * 1024 * 1024)
+    )
+    sources
+  let variant = Nested.NSVariant
+  mapM_
+    ( \variantRow -> do
+        _ <- evaluate variantRow
+        let rows = V.replicate count variantRow
+        before <- getAllocationCounter
+        rejected <- evaluate (isLeft (Nested.shred variant rows))
+        after <- getAllocationCounter
+        check "shred bounds each Variant metadata/value leaf independently" rejected
+        check "oversized Variant rejection does not materialize either leaf" (before - after < 4 * 1024 * 1024)
+    )
+    [Nested.NRVariantBytes binary BS.empty, Nested.NRVariantBytes BS.empty binary]
+  _ <- evaluate (V.length binaryRows)
+  beforeFile <- getAllocationCounter
+  rejectedFile <- evaluate (isLeft (Nested.buildNestedFile (V.singleton ("v", binarySchema)) (V.singleton binaryRows)))
+  afterFile <- getAllocationCounter
+  check "nested whole-file builder rejects cumulative oversized values" rejectedFile
+  check "nested whole-file rejection happens before value allocation" (beforeFile - afterFile < 2 * 1024 * 1024)
+  let larger = BS.replicate (2 * width) 0
+      first = V.take (count - 1) binaryRows
+      second = V.replicate (count - 1) (row larger)
+  _ <- evaluate (BS.length larger)
+  _ <- evaluate (V.length second)
+  beforeColumns <- getAllocationCounter
+  rejectedColumns <- evaluate (isLeft (Nested.buildNestedFile (V.fromList [("a", binarySchema), ("b", binarySchema)]) (V.fromList [first, second])))
+  afterColumns <- getAllocationCounter
+  check "all column plans are checked before an earlier valid large column is materialized" rejectedColumns
+  check "later-column overflow leaves value allocation bounded" (beforeColumns - afterColumns < 4 * 1024 * 1024)
+  when (toInteger (maxBound :: Int) > toInteger (maxBound :: Int32)) $ do
+    storage <- mallocForeignPtrBytes 1
+    let limit = fromIntegral (maxBound :: Int32)
+        -- Only lengths are inspected: copying these metadata-only views is
+        -- a regression, as is traversing their tiny backing arrays.
+        bytes n = BSI.fromForeignPtr storage 0 n
+        leafInput payload = V.singleton (row payload)
+        listItems = VG.basicUnsafeSlice 0 (limit + 1) (V.singleton Nested.NRNull)
+        mapItems = VG.basicUnsafeSlice 0 (limit + 1) (V.singleton (Nested.NRLeaf (Nested.LvInt32 1), Nested.NRNull))
+        hugeRows = VG.basicUnsafeSlice 0 (limit + 1) (V.singleton Nested.NRNull)
+    before <- getAllocationCounter
+    single <- evaluate (isLeft (Nested.shred binarySchema (leafInput (bytes (limit - 3)))))
+    combined <- evaluate (Nested.shred (Nested.NSOptional binarySchema) (leafInput (bytes (limit - 4))))
+    lists <- evaluate (isLeft (Nested.shred (Nested.NSList (Nested.NSOptional (Nested.NSPrimitive Nested.LtInt32))) (V.singleton (Nested.NRList listItems))))
+    maps <- evaluate (isLeft (Nested.shred (Nested.NSMap (Nested.NSPrimitive Nested.LtInt32) (Nested.NSOptional (Nested.NSPrimitive Nested.LtInt32))) (V.singleton (Nested.NRMapEntries mapItems))))
+    rows <- evaluate (isLeft (Nested.shred (Nested.NSOptional binarySchema) hugeRows))
+    after <- getAllocationCounter
+    check "single oversized byte values are rejected before length-prefix narrowing" single
+    check "shred includes level streams before materializing near-limit value bytes" (combined == Left "Parquet.Nested: complete page payload exceeds signed 32-bit limit")
+    check "oversized list/map/row views are rejected before traversing elements" (lists && maps && rows)
+    check "metadata-only oversized cases do not allocate value buffers" (before - after < 65536)
+
+
+nestedPageBoundsRegression :: IO ()
+nestedPageBoundsRegression = do
+  let input = V.fromList [Just (V.fromList [Just 1, Nothing]), Nothing, Just V.empty]
+      leaf = Nested.encodeOptionalListOptionalI32 "v" input
+      encode = Nested.buildOptionalListFileEither PTInt32
+      invalidLeaves =
+        [ leaf {Nested.nlDefLevels = P.fromList [-1, 2, 0, 1]}
+        , leaf {Nested.nlDefLevels = P.fromList [4, 2, 0, 1]}
+        , leaf {Nested.nlDefLevels = P.fromList [0, 3, 0, 1]}
+        , leaf {Nested.nlDefLevels = P.fromList [3, 1, 0, 1]}
+        , leaf {Nested.nlRepLevels = P.fromList [0, -1, 0, 0]}
+        , leaf {Nested.nlRepLevels = P.fromList [0, 2, 0, 0]}
+        , leaf {Nested.nlRepLevels = P.fromList [1, 1, 0, 0]}
+        , leaf {Nested.nlRepLevels = P.singleton 0}
+        , leaf {Nested.nlValueCount = -1}
+        , leaf {Nested.nlValueCount = 5}
+        , leaf {Nested.nlValueCount = 0}
+        , leaf {Nested.nlMaxDef = -1}
+        , leaf {Nested.nlMaxDef = 2}
+        , leaf {Nested.nlMaxRep = -1}
+        , leaf {Nested.nlMaxRep = 2}
+        , leaf {Nested.nlPath = V.empty}
+        , leaf {Nested.nlPath = V.fromList ["v", "wrong", "element"]}
+        , leaf {Nested.nlPath = V.fromList ["v", "list", "wrong"]}
+        , leaf {Nested.nlValueBytes = BS.take 3 (Nested.nlValueBytes leaf)}
+        ]
+  check "checked optional-list writer accepts a valid leaf" (isRight (encode leaf 3))
+  mapM_ (\bad -> check "checked optional-list writer rejects malformed leaf metadata/levels/payload" (isLeft (encode bad 3))) invalidLeaves
+  mapM_ (\rows -> check "nested V2 counts must fit and match complete rows" (isLeft (encode leaf rows))) [-1, 0, 1, 4, maxBound]
+  check "legacy list schema rejects an unspecified fixed-byte width" (isLeft (Nested.buildOptionalListFileEither PTFixedLenByteArray leaf 3))
+  check "legacy list writer rejects a different fixed physical value width" (isLeft (Nested.buildOptionalListFileEither PTInt64 leaf 3))
+  let sliced =
+        leaf
+          { Nested.nlDefLevels = P.slice 1 4 (P.fromList [99, 3, 2, 0, 1, 99])
+          , Nested.nlRepLevels = P.slice 1 4 (P.fromList [99, 0, 1, 0, 0, 99])
+          }
+  check "nested page preflight respects sliced level vectors" (encode sliced 3 == encode leaf 3)
+  goodBytes <- either fail pure (encode leaf 3)
+  (header, bodyOffset) <- either fail pure (Page.readPageHeaderAt goodBytes 4)
+  case Page.phType header of
+    Page.PtDataPageV2 page ->
+      mapM_
+        ( \(defs, reps) -> do
+            -- Deliberately malformed reader fixture: mutate a valid page's
+            -- same-sized level streams, keeping its counts/footer intact.
+            -- The checked writer must not generate these invalid boundaries.
+            let definition = Levels.encodeRLEHybrid 2 (P.fromList defs)
+                repetition = Levels.encodeRLEHybrid 1 (P.fromList reps)
+                definitionOffset = bodyOffset + fromIntegral (Page.dph2RepLevelsLen page)
+            check "malformed ancestor fixture preserves encoded stream lengths" $
+              BS.length definition == fromIntegral (Page.dph2DefLevelsLen page)
+                && BS.length repetition == fromIntegral (Page.dph2RepLevelsLen page)
+            let badBytes = replace definitionOffset definition (replace bodyOffset repetition goodBytes)
+            file <- either fail pure (Read.loadParquetFile badBytes)
+            schema <- either fail pure (Arrow.parquetFileArrowSchemaChecked file)
+            check "nested reader rejects orphan/continued values beneath null or empty lists" $
+              isLeft (Arrow.parquetRowGroupToArrow schema file 0)
+        )
+        [([0, 3, 0, 1], [0, 1, 0, 0]), ([3, 1, 0, 1], [0, 1, 0, 0]), ([3, 2, 0, 1], [1, 0, 0, 0])]
+    _ -> fail "nested boundary fixture must use DATA_PAGE_V2"
+  let binary payload = Nested.buildOptionalListFileEither PTByteArray (leaf {Nested.nlValueBytes = payload}) 3
+  check "legacy BYTE_ARRAY accepts one complete empty value" (isRight (binary (BS.replicate 4 0)))
+  mapM_
+    ( \version -> do
+        let schema = V.fromList [root, SchemaElement "x" (Just Optional) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing]
+            values = V.singleton (V.singleton (Write.PCOptional (Write.OptInt32 (V.fromList [Just 1, Nothing, Just 2]))))
+            aux = V.singleton (V.singleton (Write.emptyColumnAux {Write.caPageVersion = version}))
+        bytes <- either fail pure (Write.buildParquetFileMixedWithAux schema values aux)
+        file <- either fail pure (Read.loadParquetFile bytes)
+        let chunk = V.head (rgColumns (V.head (fmRowGroups (Read.pfFooter file))))
+        check "nullable flat metadata advertises PLAIN values and RLE levels" $
+          fmap cmEncodings (ccMetadata chunk) == Just (V.fromList [Plain, RLE])
+    )
+    [Write.PageV1, Write.PageV2]
+  mapM_
+    (\payload -> check "legacy BYTE_ARRAY rejects truncated lengths/values and trailing data" (isLeft (binary payload)))
+    [BS.empty, BS.replicate 3 0, BS.pack [1, 0, 0, 0], BS.pack [255, 255, 255, 255], BS.replicate 5 0]
+  when (toInteger (maxBound :: Int) > toInteger (maxBound :: Int32)) $ do
+    storage <- mallocForeignPtrBytes 1
+    let limit = fromIntegral (maxBound :: Int32)
+        -- Metadata-only oversized views. Preflight must reject their lengths
+        -- without ever reading the deliberately tiny backing storage.
+        hugeBytes n = BSI.fromForeignPtr storage 0 n
+        oversizedEvents = leaf {Nested.nlDefLevels = VG.basicUnsafeSlice 0 (limit + 1) (P.singleton 0)}
+        oversizedRows = VG.basicUnsafeSlice 0 (limit + 1) (V.singleton (Nested.NRLeaf (Nested.LvInt32 1)))
+    before <- getAllocationCounter
+    eventResult <- evaluate (encode oversizedEvents 3)
+    payloadResult <- evaluate (binary (hugeBytes (limit + 1)))
+    combinedResult <- evaluate (binary (hugeBytes limit))
+    rowsResult <- evaluate (Nested.buildNestedFile (V.singleton ("v", Nested.NSPrimitive Nested.LtInt32)) (V.singleton oversizedRows))
+    after <- getAllocationCounter
+    check "nested event overflow is rejected before reading levels" (eventResult == Left "Parquet.Nested: event count exceeds signed 32-bit page limit")
+    check "nested payload overflow is rejected before copying bytes" (payloadResult == Left "Parquet.Nested: value payload size exceeds signed 32-bit page limit")
+    check "nested payload includes both level streams in the signed32 limit" (combinedResult == Left "Parquet.Nested: complete page payload exceeds signed 32-bit limit")
+    check "nested row overflow is rejected before shredding" (rowsResult == Left "Parquet.Nested: row count exceeds signed 32-bit page limit")
+    check "nested oversized rejection stays bounded in allocation" (before - after < 65536)
+  valid <- H.check $ H.withTests 100 $ H.property $ do
+    rows <- H.forAll (V.fromList <$> Gen.list (Range.linear 0 32) (Gen.maybe (V.fromList <$> Gen.list (Range.linear 0 16) (Gen.maybe (Gen.int32 Range.linearBounded)))))
+    let optionalValue = maybe Nested.NRNull (Nested.NRLeaf . Nested.LvInt32)
+        nestedRows = V.map (maybe Nested.NRNull (Nested.NRList . V.map optionalValue)) rows
+        schema = Nested.NSOptional (Nested.NSList (Nested.NSOptional (Nested.NSPrimitive Nested.LtInt32)))
+    legacy <- H.evalEither (Nested.buildOptionalListFileEither PTInt32 (Nested.encodeOptionalListOptionalI32 "v" rows) (V.length rows))
+    generic <- H.evalEither (Nested.buildNestedFile (V.singleton ("v", schema)) (V.singleton nestedRows))
+    legacy H.=== generic
+    file <- H.evalEither (Read.loadParquetFile legacy)
+    let chunk = V.head (rgColumns (V.head (fmRowGroups (Read.pfFooter file))))
+    fmap cmEncodings (ccMetadata chunk) H.=== Just (V.fromList [Plain, RLE])
+    arrowSchema <- H.evalEither (Arrow.parquetFileArrowSchemaChecked file)
+    columns <- H.evalEither (Arrow.parquetRowGroupToArrow arrowSchema file 0)
+    actual <- H.evalEither (Arrow.columnArrayToNestedRows (V.head (T.arrowFields arrowSchema)) (V.head columns))
+    actual H.=== nestedRows
+  check "checked legacy/generic nested pages preserve arbitrary null/list shapes" valid
+
+
+nestedAnnotationRegression :: IO ()
+nestedAnnotationRegression = do
+  let field name nullable typ = T.Field name nullable typ V.empty Nothing V.empty
+      same typ column = NestedTypeCase typ column typ column
+      cases =
+        [ same (T.AInt 8 True) (A.primColumn A.PInt8 (S.fromList [-128, -1, 0, 127]))
+        , same (T.AInt 16 True) (A.primColumn A.PInt16 (S.fromList [-32768, -1, 0, 32767]))
+        , same (T.AInt 32 True) (A.primColumn A.PInt32 (S.fromList [minBound, -1, 0, maxBound]))
+        , same (T.AInt 64 True) (A.primColumn A.PInt64 (S.fromList [minBound, -1, 0, maxBound]))
+        , same (T.AInt 8 False) (A.primColumn A.PUInt8 (S.fromList [0, 127, 128, 255]))
+        , same (T.AInt 16 False) (A.primColumn A.PUInt16 (S.fromList [0, 32767, 32768, 65535]))
+        , same (T.AInt 32 False) (A.primColumn A.PUInt32 (S.fromList [0, 2147483647, 2147483648, maxBound]))
+        , same (T.AInt 64 False) (A.primColumn A.PUInt64 (S.fromList [0, 9223372036854775807, 9223372036854775808, maxBound]))
+        , same (T.ADate T.DateDay) (A.primColumn A.PDate32 (S.fromList [-1, 0, 1, 20000]))
+        , NestedTypeCase
+            (T.ADate T.DateMillisecond)
+            (A.primColumn A.PDate64 (S.fromList [-86400000, 0, 86400000, 172800000]))
+            (T.ADate T.DateDay)
+            (A.primColumn A.PDate32 (S.fromList [-1, 0, 1, 2]))
+        , NestedTypeCase
+            (T.ATime T.Second 32)
+            (A.primColumn A.PTime32 (S.fromList [0, 1, 43200, 86399]))
+            (T.ATime T.Millisecond 32)
+            (A.primColumn A.PTime32 (S.fromList [0, 1000, 43200000, 86399000]))
+        , same (T.ATime T.Millisecond 32) (A.primColumn A.PTime32 (S.fromList [0, 1, 43200000, 86399999]))
+        , same (T.ATime T.Microsecond 64) (A.primColumn A.PTime64 (S.fromList [0, 1, 43200000000, 86399999999]))
+        , same (T.ATime T.Nanosecond 64) (A.primColumn A.PTime64 (S.fromList [0, 1, 43200000000000, 86399999999999]))
+        , same T.ABool (A.fromBools (V.fromList [True, False, True, True]))
+        ]
+          ++ concatMap
+            ( \zone ->
+                NestedTypeCase
+                  (T.ATimestamp T.Second zone)
+                  (A.primColumn A.PTimestamp (S.fromList [-1, 0, 1, 2147483648]))
+                  (T.ATimestamp T.Millisecond zone)
+                  (A.primColumn A.PTimestamp (S.fromList [-1000, 0, 1000, 2147483648000]))
+                  : map
+                    (\unit -> same (T.ATimestamp unit zone) (A.primColumn A.PTimestamp (S.fromList [minBound, -1, 0, maxBound])))
+                    [T.Millisecond, T.Microsecond, T.Nanosecond]
+            )
+            [Nothing, Just "UTC"]
+      roundtrip label inputField inputColumn expectedField expectedColumn = do
+        schema <- either fail pure (Arrow.arrowFieldToNestedSchema inputField)
+        rows <- either fail pure (Arrow.columnArrayToNestedRows inputField inputColumn)
+        bytes <- either fail pure (Nested.buildNestedFile (V.singleton (T.fieldName inputField, schema)) (V.singleton rows))
+        file <- either fail pure (Read.loadParquetFile bytes)
+        inferred <- either fail pure (Arrow.parquetFileArrowSchemaChecked file)
+        check ("nested annotations survive " ++ label) $
+          V.concatMap fieldTypes (T.arrowFields inferred) == fieldTypes expectedField
+        decoded <- either (fail . show) pure (Arrow.parquetRowGroupToArrow (T.Schema (V.singleton expectedField) T.Little V.empty V.empty) file 0)
+        check ("nested values survive " ++ label) (decoded == V.singleton expectedColumn)
+      fieldTypes f = V.cons (T.fieldType f) (V.concatMap fieldTypes (T.fieldChildren f))
+      mask = A.validityFromBools (V.fromList [True, False, True, True])
+  mapM_
+    ( \sample -> do
+        let inputField = field "v" False (nestedInputType sample)
+            expectedField = field "v" False (nestedExpectedType sample)
+            label = show (nestedInputType sample)
+        roundtrip label inputField (nestedInputColumn sample) expectedField (nestedExpectedColumn sample)
+        inputNullable <- either fail pure (A.maskValidity mask (nestedInputColumn sample))
+        expectedNullable <- either fail pure (A.maskValidity mask (nestedExpectedColumn sample))
+        roundtrip
+          (label ++ " nullable/sliced")
+          (inputField {T.fieldNullable = True})
+          (A.sliceColumnArray 1 3 inputNullable)
+          (expectedField {T.fieldNullable = True})
+          (A.sliceColumnArray 1 3 expectedNullable)
+        let struct f = T.Field "parent" False T.AStruct (V.singleton f) Nothing V.empty
+        inputStruct <- either fail pure (A.mkStruct 4 Nothing (V.singleton ("v", nestedInputColumn sample)))
+        expectedStruct <- either fail pure (A.mkStruct 4 Nothing (V.singleton ("v", nestedExpectedColumn sample)))
+        roundtrip (label ++ " struct") (struct inputField) inputStruct (struct expectedField) expectedStruct
+        let list typ f = T.Field "list" False typ (V.singleton (f {T.fieldName = "element"})) Nothing V.empty
+        inputList <- either fail pure (A.mkList Nothing (S.fromList [1, 3, 3, 4]) (nestedInputColumn sample))
+        expectedList <- either fail pure (A.mkList Nothing (S.fromList [1, 3, 3, 4]) (nestedExpectedColumn sample))
+        roundtrip (label ++ " list") (list T.AList inputField) inputList (list T.AList expectedField) expectedList
+        inputLarge <- either fail pure (A.mkLargeList Nothing (S.fromList [1, 3, 3, 4]) (nestedInputColumn sample))
+        -- Parquet stores both Arrow list widths as the standard LIST layout.
+        roundtrip (label ++ " large list") (list T.ALargeList inputField) inputLarge (list T.AList expectedField) expectedList
+        let keyField = field "key" False (T.AInt 32 False)
+            mapField f =
+              T.Field
+                "map"
+                False
+                (T.AMap False)
+                (V.singleton (T.Field "entries" False T.AStruct (V.fromList [keyField, f {T.fieldName = "value"}]) Nothing V.empty))
+                Nothing
+                V.empty
+            keys = A.primColumn A.PUInt32 (S.fromList [1, 2, 3, 4])
+        inputMap <- either fail pure (A.mkMap Nothing (S.fromList [1, 3, 3, 4]) keys (nestedInputColumn sample))
+        expectedMap <- either fail pure (A.mkMap Nothing (S.fromList [1, 3, 3, 4]) keys (nestedExpectedColumn sample))
+        roundtrip (label ++ " map") (mapField inputField) inputMap (mapField expectedField) expectedMap
+    )
+    cases
+  let boolValues = V.generate 12 ((== 0) . (`rem` 3))
+  leaves <- either fail pure (Nested.shred (Nested.NSPrimitive Nested.LtBool) (V.map (Nested.NRLeaf . Nested.LvBool) boolValues))
+  check "nested BOOLEAN PLAIN packs eight present values per byte, LSB first" $
+    Nested.nlValueBytes (V.unsafeHead leaves) == BS.pack [0x49, 0x02]
+  mapM_
+    ( \n -> do
+        let values = V.generate n (\i -> if i `rem` 4 == 0 then Nothing else Just (i `rem` 3 == 0))
+            column = A.fromMaybeBools values
+            boolField = field "v" True T.ABool
+        roundtrip ("BOOLEAN null/tail " ++ show n) boolField column boolField column
+    )
+    [0 .. 65]
+  check "nested integer annotation rejects invalid widths even with no rows" $
+    isLeft (Nested.shred (Nested.NSPrimitive (Nested.LtInteger 7 True)) V.empty)
+  let primitive = Nested.NSPrimitive Nested.LtInt32
+      invalidSchemas =
+        [ Nested.NSOptional (Nested.NSOptional primitive)
+        , Nested.NSOptional (Nested.NSRequired primitive)
+        , Nested.NSRequired (Nested.NSOptional primitive)
+        , Nested.NSRequired (Nested.NSRequired primitive)
+        , Nested.NSMap (Nested.NSOptional primitive) primitive
+        , Nested.NSStruct V.empty
+        , Nested.NSOptional (Nested.NSList (Nested.NSStruct V.empty))
+        , Nested.NSOptional (Nested.NSStruct (V.singleton ("hidden", Nested.NSMap (Nested.NSOptional primitive) primitive)))
+        ]
+  mapM_
+    ( \schema ->
+        mapM_
+          ( \rows -> do
+              check "invalid nested schema is rejected before shredding any rows" $
+                isLeft (Nested.shred schema rows)
+              check "invalid nested schema cannot become a Parquet file" $
+                isLeft (Nested.buildNestedFile (V.singleton ("v", schema)) (V.singleton rows))
+          )
+          [V.empty, V.singleton Nested.NRNull]
+    )
+    invalidSchemas
+  mapM_
+    ( \(typ, value) ->
+        check "nested logical integers reject out-of-range payloads" $
+          isLeft (Nested.shred (Nested.NSPrimitive typ) (V.singleton (Nested.NRLeaf (Nested.LvInt32 value))))
+    )
+    [(Nested.LtInteger 8 True, -129), (Nested.LtInteger 8 True, 128), (Nested.LtInteger 8 False, -1), (Nested.LtInteger 8 False, 256), (Nested.LtInteger 16 False, 65536)]
+  mapM_
+    ( \sample ->
+        check "nested temporal conversion rejects precision loss, invalid time and overflow" $
+          isLeft (Arrow.columnArrayToNestedRows (field "v" False (nestedInputType sample)) (nestedInputColumn sample))
+    )
+    [ same (T.ADate T.DateMillisecond) (A.primColumn A.PDate64 (S.singleton 1))
+    , same (T.ADate T.DateMillisecond) (A.primColumn A.PDate64 (S.singleton maxBound))
+    , same (T.ATime T.Second 32) (A.primColumn A.PTime32 (S.singleton (-1)))
+    , same (T.ATime T.Second 32) (A.primColumn A.PTime32 (S.singleton 86400))
+    , same (T.ATime T.Millisecond 32) (A.primColumn A.PTime32 (S.singleton 86400000))
+    , same (T.ATime T.Microsecond 64) (A.primColumn A.PTime64 (S.singleton 86400000000))
+    , same (T.ATime T.Nanosecond 64) (A.primColumn A.PTime64 (S.singleton (-1)))
+    , same (T.ATimestamp T.Second Nothing) (A.primColumn A.PTimestamp (S.singleton minBound))
+    , same (T.ATimestamp T.Second Nothing) (A.primColumn A.PTimestamp (S.singleton maxBound))
+    ]
+  check "nested duration rejects an unsupported logical type instead of silently writing an integer" $
+    isLeft (Arrow.arrowFieldToNestedSchema (field "v" False (T.ADuration T.Millisecond)))
+  let parentMask = A.validityFromBools (V.fromList [True, False, True])
+      dateField = field "date" False (T.ADate T.DateMillisecond)
+      expectedDateField = field "date" False (T.ADate T.DateDay)
+      parent child = T.Field "parent" True T.AStruct (V.singleton child) Nothing V.empty
+  inputDates <- either fail pure (A.mkPrim A.PDate64 parentMask (S.fromList [-86400000, 1, 86400000]))
+  expectedDates <- either fail pure (A.mkPrim A.PDate32 parentMask (S.fromList [-1, 0, 1]))
+  inputParent <- either fail pure (A.mkStruct 3 parentMask (V.singleton ("date", inputDates)))
+  expectedParent <- either fail pure (A.mkStruct 3 parentMask (V.singleton ("date", expectedDates)))
+  roundtrip "DATE64 poison and required null hidden beneath a null struct" (parent dateField) inputParent (parent expectedDateField) expectedParent
+  check "a visible null remains invalid for a required child" $
+    isLeft (Arrow.columnArrayToNestedRows dateField inputDates)
+  let secondsField = field "element" False (T.ATime T.Second 32)
+      millisField = field "element" False (T.ATime T.Millisecond 32)
+      listField child = T.Field "list" False T.AList (V.singleton child) Nothing V.empty
+      poisonTimes = A.primColumn A.PTime32 (S.fromList [maxBound, 0, 1, minBound])
+  inputTimes <- either fail pure (A.mkList Nothing (S.fromList [1, 3]) poisonTimes)
+  expectedTimes <- either fail pure (A.mkList Nothing (S.fromList [0, 2]) (A.primColumn A.PTime32 (S.fromList [0, 1000])))
+  roundtrip "unused poisoned list prefix/suffix" (listField secondsField) inputTimes (listField millisField) expectedTimes
+  let keyField = field "key" False (T.AInt 32 True)
+      valueField = field "value" False (T.AInt 32 True)
+      mapField sorted nullable =
+        T.Field
+          "map"
+          nullable
+          (T.AMap sorted)
+          (V.singleton (T.Field "entries" False T.AStruct (V.fromList [keyField, valueField]) Nothing V.empty))
+          Nothing
+          V.empty
+      values = A.primColumn A.PInt32 (S.fromList [10, 20])
+      nullMap = A.validityFromBools (V.singleton False)
+  unsorted <- either fail pure (A.mkMap Nothing (S.fromList [0, 2]) (A.primColumn A.PInt32 (S.fromList [2, 1])) values)
+  check "a sorted map field rejects visible out-of-order keys" $
+    isLeft (Arrow.columnArrayToNestedRows (mapField True False) unsorted)
+  hiddenUnsorted <- either fail pure (A.maskValidity nullMap unsorted)
+  check "null map rows do not inspect hidden sorted keys" $
+    Arrow.columnArrayToNestedRows (mapField True True) hiddenUnsorted == Right (V.singleton Nested.NRNull)
+  nullKeys <- either fail pure (A.mkPrim A.PInt32 (A.validityFromBools (V.fromList [False, True])) (S.fromList [1, 2]))
+  invalidMap <- either fail pure (A.mkMap Nothing (S.fromList [0, 2]) nullKeys values)
+  check "visible null map keys are rejected" (isLeft (Arrow.columnArrayToNestedRows (mapField False False) invalidMap))
+  hiddenKeys <- either fail pure (A.maskValidity nullMap invalidMap)
+  check "null map rows do not inspect hidden null keys" $
+    Arrow.columnArrayToNestedRows (mapField False True) hiddenKeys == Right (V.singleton Nested.NRNull)
+  let count = 32768
+      intField = field "v" False (T.AInt 32 True)
+      boolField = field "v" False T.ABool
+      intColumn = A.primColumn A.PInt32 (S.generate count fromIntegral)
+      boolColumn = A.fromBools (V.generate count odd)
+  mapM_
+    ( \(typ, column) -> do
+        _ <- evaluate (A.columnLength column)
+        before <- getAllocationCounter
+        rows <- either fail pure =<< evaluate (Arrow.columnArrayToNestedRows typ column)
+        after <- getAllocationCounter
+        check ("nested conversion allocates output rows without per-row result/index wrappers: " ++ show (before - after)) $
+          before - after < fromIntegral (count * 48 + 65536) && V.length rows == count
+    )
+    [(intField, intColumn), (boolField, boolColumn)]
+
+
+dictionaryOwnerRegression :: IO ()
+dictionaryOwnerRegression = do
+  let !count = 32768
+      !uniqueCount = 257
+      !width = 128
+      word key = BS.pack (map (\shift -> fromIntegral ((fromIntegral key :: Word64) `shiftR` shift)) [0, 8 .. 56])
+      value key = BS.replicate 8 97 <> word (key `rem` 2) <> word (key `quot` 2) <> BS.replicate (width - 24) 97
+      pool = V.generate uniqueCount value
+      buildOwned = do
+        -- IO allocation prevents the source from becoming a retained CAF.
+        owners <- V.generateM count (\i -> BS.useAsCStringLen (pool V.! (i `rem` uniqueCount)) BS.packCStringLen)
+        let source =
+              V.imap
+                ( \i owner ->
+                    let prefix = i `rem` 8
+                        bytes = BS.replicate prefix 0xa5 <> BS.copy owner <> BS.replicate 8 0x5a
+                    in BS.take width (BS.drop prefix bytes)
+                )
+                owners
+        evaluate (Write.buildDictionary (Write.ColByteArray source))
+  -- Lazy source payloads create allocation pressure during interning and
+  -- growth. Only the returned owners remain after this scope and a GC.
+  dictionary <- buildOwned
+  performGC
+  case Write.dictUniques dictionary of
+    Write.ColByteArray owners -> do
+      copied <- V.mapM (\bytes -> BS.useAsCStringLen bytes BS.packCStringLen) owners
+      check "dictionary cached addresses retain their sliced owners across growth, promotion and GC" (copied == pool)
+    _ -> error "dictionary owner regression returned a non-binary column"
+  check
+    "dictionary ownership changes preserve stable indices"
+    (Write.dictIndices dictionary == P.generate count (\i -> fromIntegral (i `rem` uniqueCount)))
+
+
+nullableSelection :: IO ()
+nullableSelection = do
+  let parent = SchemaElement "parent" (Just Optional) Nothing (Just 1) Nothing Nothing Nothing Nothing
+      leaf = SchemaElement "x" (Just Optional) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+      schema = V.fromList [root, parent, leaf]
+  mapM_
+    ( \v2 -> do
+        let first = levelPage v2 2 [2, 1, 0] [1] 0
+            second = levelPage v2 2 [2, 0, 1, 2] [10, 30] 0
+            fixture = indexed schema (V.fromList ["parent", "x"]) (V.fromList [first, second]) Nothing
+            file = fixtureFile fixture
+            target = field (T.AInt 32 True) True
+            predicate = Pred.PGtEq (Pred.PVInt32 10)
+            selected = Arrow.readParquetColumnWithPagePruning file 0 0 target predicate
+        check
+          "selected nullable ancestors use the real maximum definition level"
+          (selected == Right (Just (1, 2), A.fromMaybes A.PInt32 (V.fromList [Just 10, Nothing, Nothing, Just 30])))
+        check
+          "selected nulls cannot be hidden by a required target"
+          (isLeft (Arrow.readParquetColumnWithPagePruning file 0 0 (target {T.fieldNullable = False}) predicate))
+        let nullFile = fixtureFile (indexed schema (V.fromList ["parent", "x"]) (V.singleton (levelPage v2 2 [0, 1, 0] [] 0)) Nothing)
+            presentFile = fixtureFile (indexed schema (V.fromList ["parent", "x"]) (V.singleton (levelPage v2 2 [2, 2] [10, 30] 0)) Nothing)
+        check
+          "selected all-null primitive leaves retain their parent row count"
+          (Arrow.readParquetColumnWithPagePruning nullFile 0 0 target Pred.PIsNull == Right (Just (1, 1), A.fromMaybes A.PInt32 (V.replicate 3 Nothing)))
+        check
+          "selected optional primitive leaves also handle all-present pages"
+          (Arrow.readParquetColumnWithPagePruning presentFile 0 0 target predicate == Right (Just (1, 1), A.primColumn A.PInt32 (S.fromList [10, 30])))
+    )
+    [False, True]
+  let bad = levelPage True 2 [2, 0, 1, 2] [10, 30] 1
+  check
+    "V2 null counts must match the definition stream"
+    (isLeft (Read.readInt32Levels Uncompressed 0 2 (testBytes bad)))
+  let ordinary = levelPage True 1 [1, 0, 1] [10, 30] 0
+  (header, body) <- either error pure (Page.readPageHeaderAt (testBytes ordinary) 0)
+  case Page.phType header of
+    Page.PtDataPageV2 page -> do
+      let explicit =
+            Write.encodePageHeader
+              ( header
+                  { Page.phType = Page.PtDataPageV2 (page {Page.dph2RepLevelsLen = 1})
+                  , Page.phCompressedPageSize = (+ 1) <$> Page.phCompressedPageSize header
+                  , Page.phUncompressedPageSize = (+ 1) <$> Page.phUncompressedPageSize header
+                  }
+              )
+              <> BS.singleton 6
+              <> BS.drop body (testBytes ordinary)
+      decoded <- either error pure (Read.readInt32Levels Uncompressed 0 1 explicit)
+      check
+        "redundant zero-width V2 repetition streams remain readable"
+        (Read.clDefinition decoded == P.fromList [1, 0, 1] && Read.clValues decoded == P.fromList [10, 30])
+    _ -> error "missing V2 test page"
+
+
+nullableByteSelection :: IO ()
+nullableByteSelection = mapM_ checkType [False, True]
+  where
+    checkType text = do
+      let large = BS.replicate (1024 * 1024) 109
+          present = V.fromList [large, "a", "z"]
+          values = V.singleton (Just large) <> V.replicate 4096 Nothing <> V.fromList [Just "a", Just "z"]
+          leaf = SchemaElement "x" (Just Optional) (Just PTByteArray) Nothing Nothing (if text then Just LTString else Nothing) Nothing Nothing
+          bytes = either error id (Write.encodeOptionalColumnPageV2 Uncompressed (Write.OptByteArray values))
+          page = TestPage bytes (V.length values) ((Write.columnDataStatistics (Write.ColByteArray present)) {statNullCount = Just 4096})
+          file = fixtureFile (indexed (V.fromList [root, leaf]) (V.singleton "x") (V.singleton page) Nothing)
+          expected = if text then A.fromMaybeTexts ((Text.decodeUtf8 <$>) <$> values) else A.fromMaybeByteStrings values
+          target = field (if text then T.AUtf8 else T.ABinary) True
+      case Arrow.readParquetColumnWithPagePruning file 0 0 target Pred.PIsNull of
+        Right (Just (1, 1), column) -> do
+          check "sparse nullable byte/text selection retains all values" (column == expected)
+          let size = case column of
+                A.ColUtf8 _ _ dataBytes -> BS.length dataBytes
+                A.ColBinary _ _ dataBytes -> BS.length dataBytes
+                _ -> error "missing sparse byte/text column"
+          check "null rows do not duplicate a large first value" (size == BS.length large + 2)
+        other -> error ("sparse byte/text selection failed: " <> show other)
+
+
+dictionarySelection :: IO ()
+dictionarySelection = do
+  let leaf = SchemaElement "x" (Just Required) (Just PTByteArray) Nothing (Just CTUtf8) (Just LTString) Nothing Nothing
+      schema = V.fromList [root, leaf]
+      dictionary = Write.Dictionary (Write.ColByteArray (V.fromList ["a", "b", "c", "d"])) P.empty
+      page indexes texts =
+        TestPage
+          (Write.encodeDictDataPage (dictionary {Write.dictIndices = P.fromList indexes}))
+          (length indexes)
+          (Write.columnDataStatistics (Write.ColByteArray (V.fromList texts)))
+      fixture =
+        indexed
+          schema
+          (V.singleton "x")
+          (V.fromList [page [0, 1, 0] ["a", "b", "a"], page [2, 3] ["c", "d"]])
+          (Just (Write.encodeDictPage dictionary))
+      file = fixtureFile fixture
+      target = field T.AUtf8 False
+      predicate = Pred.PGtEq (Pred.PVText "c")
+      expected = A.fromTexts (V.fromList ["c", "d"])
+  check
+    "standard indexes initialize a dictionary stored outside data-page locations"
+    (Arrow.readParquetColumnWithPagePruning file 0 0 target predicate == Right (Just (1, 2), expected))
+  let footerless = file {Read.pfBytes = BS.take (fixtureFooterStart fixture) (Read.pfBytes file)}
+  check
+    "metadata-aware selection does not reparse the file footer"
+    (Arrow.readParquetColumnWithPagePruning footerless 0 0 target predicate == Right (Just (1, 2), expected))
+  check
+    "legacy selected API resolves a needed dictionary from full-file metadata"
+    ( Read.readGenericByteArraySelectedPages
+        Uncompressed
+        (Read.pfBytes file)
+        (fixtureLocations fixture)
+        (V.fromList [False, True])
+        == Right (V.fromList ["c", "d"])
+    )
+  let brokenDictionary = file {Read.pfBytes = replace 4 (BS.replicate (BS.length (Write.encodeDictPage dictionary)) 0xff) (Read.pfBytes file)}
+  check
+    "an empty selection does not read an unused dictionary"
+    ( Arrow.readParquetColumnWithPagePruning brokenDictionary 0 0 target (Pred.PGt (Pred.PVText "z"))
+        == Right (Just (0, 2), A.fromTexts V.empty)
+    )
+  check
+    "a needed corrupt dictionary is rejected"
+    (isLeft (Arrow.readParquetColumnWithPagePruning brokenDictionary 0 0 target predicate))
+
+
+binaryBuffersRegression :: IO ()
+binaryBuffersRegression = do
+  passed <- H.check $ H.withTests 100 $ H.property $ do
+    values <- H.forAll (V.fromList <$> Gen.list (Range.linear 0 128) (Gen.bytes (Range.linear 0 48)))
+    prefix <- H.forAll (Gen.bytes (Range.linear 1 15))
+    let raw = Lazy.toStrict (Builder.toLazyByteString (foldMap (\bytes -> Builder.word32LE (fromIntegral (BS.length bytes)) <> Builder.byteString bytes) values))
+        sliced = BS.take (BS.length raw) (BS.drop (BS.length prefix) (prefix <> raw <> "unused suffix"))
+        expectedOffsets = S.convert (V.scanl' (\n bytes -> n + fromIntegral (BS.length bytes)) (0 :: Int32) values)
+        expectedBytes = BS.concat (V.toList values)
+        page xs = let (header, body) = Write.encodeColumnDataPageParts (Write.ColByteArray xs) in header <> body
+        middle = V.length values `quot` 2
+        twoPages = page (V.take middle values) <> page (V.drop middle values)
+        assertBuffers buffers = do
+          Read.binaryOffsets buffers H.=== expectedOffsets
+          Read.binaryData buffers H.=== expectedBytes
+    direct <- H.evalEither (Read.decodePlainBinaryBuffers (V.length values) sliced)
+    assertBuffers direct
+    combined <- H.evalEither (Read.readBinaryBuffersColumnChunk Uncompressed twoPages)
+    assertBuffers combined
+  check "direct binary buffers preserve arbitrary sliced bytes and rebase multiple page offsets" passed
+  mapM_
+    (\(count, bytes) -> check "direct binary buffers reject invalid counts, lengths and trailing bytes" (isLeft (Read.decodePlainBinaryBuffers count bytes)))
+    [ (-1, BS.empty)
+    , (maxBound, BS.empty)
+    , (1, BS.pack [0, 0, 0])
+    , (1, BS.pack [255, 255, 255, 255])
+    , (1, BS.pack [4, 0, 0, 0, 1])
+    , (1, BS.pack [0, 0, 0, 0, 0])
+    , (0, "trailing")
+    ]
+  let dictionary entries indices =
+        let dict = Write.Dictionary (Write.ColByteArray entries) indices
+        in Write.encodeDictPage dict <> Write.encodeDictDataPage dict
+      -- Deliberately malformed reader fixture: index 3 fits width 2 but
+      -- exceeds the three-entry dictionary. Do not ask the writer to
+      -- produce an invalid dictionary now that it validates ordinals.
+      invalidBody = BS.singleton 2 <> Levels.encodeRLEHybrid 2 (P.fromList [0, 1, 3])
+      invalidDictionary =
+        Write.encodeDictPage (Write.Dictionary (Write.ColByteArray (V.fromList ["", "value", "other"])) P.empty)
+          <> invalidHeader
+          <> invalidBody
+      invalidHeader =
+        Write.encodePageHeader
+          Page.PageHeader
+            { Page.phType = Page.PtDataPage (Page.DataPageHeader 3 8)
+            , Page.phUncompressedPageSize = Just (fromIntegral (BS.length invalidBody))
+            , Page.phCompressedPageSize = Just (fromIntegral (BS.length invalidBody))
+            }
+  check
+    "direct dictionary buffers reject invalid keys before copying"
+    (isLeft (Read.readBinaryBuffersColumnChunk Uncompressed invalidDictionary))
+  -- About 1 MiB of input requests 2 GiB of output. This must fail in the
+  -- size preflight, without attempting that allocation or narrowing offsets.
+  check
+    "direct dictionary buffers reject expansion past signed 32-bit offsets"
+    (isLeft (Read.readBinaryBuffersColumnChunk Uncompressed (dictionary (V.singleton (BS.replicate (1024 * 1024) 120)) (P.replicate 2048 0))))
+  let largeDictionary = Write.Dictionary (Write.ColByteArray (V.singleton (BS.replicate (1024 * 1024) 120))) (P.replicate 1024 0)
+      largePage = Write.encodeDictDataPage largeDictionary
+      twoLargePages = Write.encodeDictPage largeDictionary <> largePage <> largePage
+  check
+    "combined binary pages reject 2 GiB before materializing either 1 GiB page"
+    (isLeft (Read.readBinaryBuffersColumnChunk Uncompressed twoLargePages))
+  let leaf = SchemaElement "x" (Just Required) (Just PTByteArray) Nothing (Just CTUtf8) (Just LTString) Nothing Nothing
+      invalid = Write.ColByteArray (V.fromList [BS.singleton 0xc3, BS.singleton 0xa9])
+      (header, body) = Write.encodeColumnDataPageParts invalid
+      fixture = indexed (V.fromList [root, leaf]) (V.singleton "x") (V.singleton (TestPage (header <> body) 2 (Write.columnDataStatistics invalid))) Nothing
+  check
+    "UTF-8 validation rejects a character split across two valid binary offsets"
+    (isLeft (Arrow.readParquetColumn (fixtureFile fixture) 0 0 (field T.AUtf8 False)))
+
+
+dictionaryExpansionRegression :: IO ()
+dictionaryExpansionRegression = do
+  valid <- H.check $ H.withTests 100 $ H.property $ do
+    sizes <- H.forAll (V.fromList <$> Gen.list (Range.linear 1 32) (Gen.int32 (Range.linear 0 64)))
+    keys <- H.forAll (P.fromList <$> Gen.list (Range.linear 0 128) (Gen.int32 (Range.linear 0 (fromIntegral (V.length sizes - 1)))))
+    count <- H.forAll (Gen.int (Range.linear 0 (P.length keys)))
+    limit <- H.forAll (Gen.int (Range.linear 0 2048))
+    let width = Levels.bitWidthFor (V.length sizes - 1)
+        encoded = BS.singleton (fromIntegral width) <> Levels.encodeRLEHybrid width keys
+        offsets = S.convert (V.scanl' (+) 7 sizes)
+        needed = P.foldl' (\total key -> total + fromIntegral (sizes V.! fromIntegral key)) (0 :: Int) (P.take count keys)
+    isRight (Read.validateDictionaryExpansion limit offsets count encoded) H.=== (needed <= limit)
+  check "dictionary expansion preflight matches independent prefix byte sums" valid
+  malformed <- H.check $ H.withTests 100 $ H.property $ do
+    encoded <- H.forAll (Gen.bytes (Range.linear 0 24))
+    count <- H.forAll (Gen.int (Range.linear 0 64))
+    limit <- H.forAll (Gen.int (Range.linear 0 256))
+    let offsets = S.fromList [0, 0, 2, 7]
+        expected = case Read.decodeDictionaryIndices count encoded of
+          Left _ -> False
+          Right keys ->
+            P.all (\key -> key >= 0 && key < 3) keys
+              && P.foldl' (\total key -> total + fromIntegral (offsets S.! (fromIntegral key + 1) - offsets S.! fromIntegral key)) (0 :: Int) keys <= limit
+    isRight (Read.validateDictionaryExpansion limit offsets count encoded) H.=== expected
+  check "dictionary expansion preflight agrees with bounded decoding of arbitrary malformed streams" malformed
+  mapM_
+    ( \width -> do
+        let offsets = S.fromList [0, 2, 5]
+            repeated = BS.pack (fromIntegral width : 2 : 1 : replicate ((width + 7) `quot` 8 - 1) 0)
+            keys = P.fromList ([0, 1, 1, 0, 1, 0, 0, 1] :: [Word32])
+            packedByte byte = foldl' (\acc bit -> let absolute = byte * 8 + bit in if testBit (keys P.! (absolute `quot` width)) (absolute `rem` width) then setBit acc bit else acc) 0 [0 .. 7]
+            packed = BS.pack (fromIntegral width : 3 : (packedByte <$> [0 .. width - 1]))
+        check "dictionary preflight handles every RLE width" (Read.validateDictionaryExpansion 3 offsets 1 repeated == Right ())
+        check "dictionary preflight checks RLE budgets" (isLeft (Read.validateDictionaryExpansion 2 offsets 1 repeated))
+        check "dictionary preflight handles unaligned bit-packed values" (Read.validateDictionaryExpansion 13 offsets 5 packed == Right ())
+        check "dictionary preflight checks packed prefix budgets" (isLeft (Read.validateDictionaryExpansion 12 offsets 5 packed))
+    )
+    [1 .. 32]
+  let clipped = BS.pack [2, 3, 244, 255, 128]
+      offsets = S.fromList [0, 2, 5]
+  check "unused invalid packed indices and truncated suffix are not inspected" (Read.validateDictionaryExpansion 5 offsets 2 clipped == Right ())
+  check "a requested invalid packed index is rejected" (isLeft (Read.validateDictionaryExpansion 100 offsets 3 clipped))
+  check "unsigned 32-bit dictionary indices are range checked before offset lookup" (isLeft (Read.validateDictionaryExpansion 100 offsets 1 (BS.pack [32, 2, 255, 255, 255, 255])))
+  check "an unused index stream and dictionary need not be inspected" (Read.validateDictionaryExpansion 0 S.empty 0 BS.empty == Right ())
+  check "implicit zero-width references need no run or vector allocation" (Read.validateDictionaryExpansion 0 (S.fromList [0, 0]) maxBound (BS.singleton 0) == Right ())
+  check "huge implicit references reject without multiplication overflow" (isLeft (Read.validateDictionaryExpansion 8 (S.fromList [0, 1]) maxBound (BS.singleton 0)))
+  -- Run lengths constrain the declared stream, even when only one value
+  -- is requested. Packed lengths count values, not groups of eight.
+  mapM_
+    ( \width -> do
+        let padded = BS.replicate ((width + 7) `quot` 8) 0
+            maxRepeated = BS.pack [254, 255, 255, 255, 15] <> padded
+            oversizedRepeated = BS.pack [128, 128, 128, 128, 16] <> padded
+            oversizedPacked = BS.pack [129, 128, 128, 128, 2]
+            validate payload = Read.validateDictionaryExpansion 0 (S.fromList [0, 0]) 1 (BS.singleton (fromIntegral width) <> payload)
+        check "maximum signed 32-bit repeated runs allow clipped decoding" $
+          Read.decodeHybridRleUnsigned32 width 1 maxRepeated == Right (P.singleton 0)
+            && validate maxRepeated == Right ()
+        mapM_
+          ( \(payload, expected) -> do
+              check "decoder rejects an oversized declared run before clipping" (Read.decodeHybridRleUnsigned32 width 1 payload == Left expected)
+              check "dictionary preflight rejects an oversized declared run before clipping" (validate payload == Left expected)
+          )
+          [ (oversizedRepeated, "Parquet.RLE: RLE run exceeds signed 32-bit length")
+          , (oversizedPacked, "Parquet.RLE: bit-packed run exceeds signed 32-bit length")
+          ]
+    )
+    [1 .. 32]
+  -- One million bit-packed references to an empty entry. The preflight
+  -- must scan them without allocating per-index nodes or an output vector.
+  let packedZeros = BS.pack [1, 145, 161, 15] <> BS.replicate 125000 0
+  _ <- evaluate (BS.length packedZeros)
+  beforePacked <- getAllocationCounter
+  packedValid <- evaluate (isRight (Read.validateDictionaryExpansion 0 (S.fromList [0, 0]) 1000000 packedZeros))
+  afterPacked <- getAllocationCounter
+  let packedAllocated = beforePacked - afterPacked
+  putStrLn ("packed dictionary preflight allocated " ++ show packedAllocated ++ " bytes for one million indices")
+  check "large packed dictionary preflight remains valid" packedValid
+  check "packed dictionary preflight has no per-index allocation" (packedAllocated < 64 * 1024)
+  mapM_
+    (\badOffsets -> check "dictionary preflight rejects invalid offset arrays" (isLeft (Read.validateDictionaryExpansion 8 badOffsets 1 (BS.singleton 0))))
+    [S.empty, S.singleton 0, S.fromList [-1, 0], S.fromList [0, 3, 2]]
+
+
+dictionaryAllocationRegression :: IO ()
+dictionaryAllocationRegression = do
+  let dictionary = Write.Dictionary (Write.ColByteArray (V.fromList [BS.empty, BS.replicate 4096 120])) P.empty
+      -- Width 1, RLE run of 1,000,000 references to entry 1. Entry 0 is
+      -- empty, so a minimum-entry-length estimate cannot detect overflow.
+      body = BS.pack [1, 128, 137, 122, 1]
+      header = Page.PageHeader (Page.PtDataPage (Page.DataPageHeader 1000000 8)) (Just 5) (Just 5)
+      chunk = Write.encodeDictPage dictionary <> Write.encodePageHeader header <> body
+  _ <- evaluate (BS.length chunk)
+  before <- getAllocationCounter
+  rejected <- evaluate (isLeft (Read.readBinaryBuffersColumnChunk Uncompressed chunk))
+  after <- getAllocationCounter
+  let allocated = before - after
+  putStrLn ("oversized dictionary rejection allocated " ++ show allocated ++ " bytes")
+  check "oversized dictionary expansion is rejected" rejected
+  check "oversized dictionary expansion is rejected before allocating index/offset vectors" (allocated < 1024 * 1024)
+  let emptyBody = BS.pack [1, 128, 137, 122, 0]
+      emptyChunk = Write.encodeDictPage dictionary <> Write.encodePageHeader header <> emptyBody
+  check
+    "large empty outputs remain valid despite an unused large dictionary entry"
+    ( case Read.readBinaryBuffersColumnChunk Uncompressed emptyChunk of
+        Left _ -> False
+        Right buffers -> S.length (Read.binaryOffsets buffers) == 1000001 && S.last (Read.binaryOffsets buffers) == 0 && BS.null (Read.binaryData buffers)
+    )
+
+
+dictionarySequenceRegression :: IO ()
+dictionarySequenceRegression = do
+  let values = V.fromList ["a", "b"]
+      dictionary = Write.Dictionary (Write.ColByteArray values) (P.fromList [0, 1])
+      dictionaryPage = Write.encodeDictPage dictionary
+      dictionaryData = Write.encodeDictDataPage dictionary
+      (header, body) = Write.encodeColumnDataPageParts (Write.ColByteArray values)
+      plain = header <> body
+      valid = dictionaryPage <> dictionaryData <> plain
+  check "a dictionary may fall back to PLAIN pages" (Read.readGenericByteArrayColumnChunk Uncompressed valid == Right (values <> values))
+  mapM_
+    ( \bad -> do
+        check "required byte reader rejects late or replacement dictionaries" (isLeft (Read.readGenericByteArrayColumnChunk Uncompressed bad))
+        check "buffer reader rejects late or replacement dictionaries" (isLeft (Read.readBinaryBuffersColumnChunk Uncompressed bad))
+        check "leveled reader rejects late or replacement dictionaries" (isLeft (Read.readByteArrayLevels Uncompressed 0 0 bad))
+    )
+    [plain <> dictionaryPage <> dictionaryData, dictionaryPage <> dictionaryPage <> dictionaryData, dictionaryPage <> dictionaryData <> dictionaryPage <> dictionaryData]
+  let ints = Write.Dictionary (Write.ColInt32 (P.fromList [1, 2])) (P.fromList [0, 1])
+      intsPage = Write.encodeDictPage ints
+      intsData = Write.encodeDictDataPage ints
+      duplicate = intsPage <> intsPage <> intsData
+  check "legacy required dictionary reader rejects duplicate dictionaries" (isLeft (Read.readPlainDictionaryInt32ColumnChunk Uncompressed duplicate))
+  check "legacy optional dictionary reader rejects duplicate dictionaries" (isLeft (Read.readDictionaryInt32OptionalColumnChunk Uncompressed 0 0 duplicate))
+
+
+scalarBuffersRegression :: IO ()
+scalarBuffersRegression = do
+  words32 <- H.check $ H.withTests 100 $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 128) (Gen.word32 Range.constantBounded))
+    let split = length values `quot` 2
+        bytes xs = Lazy.toStrict (Builder.toLazyByteString (foldMap Builder.word32LE xs))
+        chunk = plain split (bytes (take split values)) <> plain (length values - split) (bytes (drop split values))
+        decode physical = fmap (S.toList . (Buffer.bytesToStorable :: ByteString -> S.Vector Word32) . Read.scalarData) (Read.readScalarBuffersColumnChunk physical Uncompressed (BS.drop 1 (BS.cons 0 chunk)))
+    decode PTInt32 H.=== Right values
+    decode PTFloat H.=== Right values
+  check "native multi-page INT32/FLOAT buffers preserve arbitrary bits and unaligned input" words32
+  words64 <- H.check $ H.withTests 100 $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 128) (Gen.word64 Range.constantBounded))
+    let split = length values `quot` 2
+        bytes xs = Lazy.toStrict (Builder.toLazyByteString (foldMap Builder.word64LE xs))
+        chunk = plain split (bytes (take split values)) <> plain (length values - split) (bytes (drop split values))
+        decode physical = fmap (S.toList . (Buffer.bytesToStorable :: ByteString -> S.Vector Word64) . Read.scalarData) (Read.readScalarBuffersColumnChunk physical Uncompressed chunk)
+    decode PTInt64 H.=== Right values
+    decode PTDouble H.=== Right values
+  check "native multi-page INT64/DOUBLE buffers preserve arbitrary bits" words64
+  let entries = [0x80000000, 0x7fc00001, 0x7fa12345, 0xffffffff] :: [Word32]
+      raw = Lazy.toStrict (Builder.toLazyByteString (foldMap Builder.word32LE entries))
+      dictionary = page (Page.PtDictionaryPage (Page.DictionaryPageHeader 4 0)) raw
+      indices = P.fromList [3, 0, 2, 1, 2, 3]
+      encoded = BS.singleton 2 <> Levels.encodeRLEHybrid 2 indices
+      dataPage = page (Page.PtDataPage (Page.DataPageHeader 6 8)) encoded
+      decode chunk = fmap (S.toList . (Buffer.bytesToStorable :: ByteString -> S.Vector Word32) . Read.scalarData) (Read.readScalarBuffersColumnChunk PTFloat Uncompressed chunk)
+      expected = map (entries !!) [3, 0, 2, 1, 2, 3]
+  check "dictionary scalar gathers preserve NaN payloads and signed zero across pages" (decode (dictionary <> dataPage <> dataPage) == Right (expected <> expected))
+  check "dictionary scalar buffers preserve a PLAIN fallback" (decode (dictionary <> dataPage <> plain 4 raw) == Right (expected <> entries))
+  let entries64 = [0x8000000000000000, 0x7ff8000000000001, 0x7ff0123456789abc, 0xffffffffffffffff] :: [Word64]
+      raw64 = Lazy.toStrict (Builder.toLazyByteString (foldMap Builder.word64LE entries64))
+      dictionary64 = page (Page.PtDictionaryPage (Page.DictionaryPageHeader 4 0)) raw64
+      expected64 = map (entries64 !!) [3, 0, 2, 1, 2, 3]
+      chunk64 = dictionary64 <> dataPage <> plain 4 raw64
+  mapM_
+    ( \offset -> do
+        let input = BS.drop offset (BS.replicate offset 0 <> chunk64)
+            decoded physical = fmap (S.toList . (Buffer.bytesToStorable :: ByteString -> S.Vector Word64) . Read.scalarData) (Read.readScalarBuffersColumnChunk physical Uncompressed input)
+        check "64-bit dictionary scalar buffers preserve bits at every source alignment" (decoded PTDouble == Right (expected64 <> entries64) && decoded PTInt64 == Right (expected64 <> entries64))
+    )
+    [0 .. 7]
+  let bad = page (Page.PtDataPage (Page.DataPageHeader 1 8)) (BS.pack [3, 2, 4])
+  check "scalar buffers reject invalid dictionary indices" (isLeft (decode (dictionary <> bad)))
+  check "scalar buffers reject late dictionaries" (isLeft (decode (plain 4 raw <> dictionary <> dataPage)))
+  mapM_ (\n -> check "scalar buffers reject invalid counts before allocation" (isLeft (decode (plain n (BS.singleton 0))))) ([-1, 1, fromIntegral (maxBound :: Int32)] :: [Int])
+  check "scalar buffers reject unsupported physical types" (isLeft (Read.readScalarBuffersColumnChunk PTBoolean Uncompressed BS.empty))
+  where
+    plain :: Int -> ByteString -> ByteString
+    plain n = page (Page.PtDataPage (Page.DataPageHeader (fromIntegral n) 0))
+    page :: Page.PageType -> ByteString -> ByteString
+    page typ bytes =
+      Write.encodePageHeader (Page.PageHeader typ (Just (fromIntegral (BS.length bytes))) (Just (fromIntegral (BS.length bytes)))) <> bytes
+
+
+nullableAssemblyRegression :: IO ()
+nullableAssemblyRegression = do
+  mapM_
+    ( \width -> do
+        check "empty hybrid level streams do not read a first element" (Levels.encodeRLEHybrid width P.empty == BS.empty)
+        check "empty V1 level streams retain only the required length prefix" (Levels.encodeLengthPrefixedHybrid width P.empty == if width == 0 then BS.empty else BS.replicate 4 0)
+    )
+    [0 .. 32]
+  passed <- H.check $ H.withTests 200 $ H.property $ do
+    base <- H.forAll (Gen.list (Range.linear 0 128) (Gen.int32 Range.constantBounded))
+    flags <- H.forAll (Gen.list (Range.singleton (length base)) Gen.bool)
+    mode <- H.forAll (Gen.element [0 :: Int, 1, 2])
+    v2 <- H.forAll Gen.bool
+    let rows = zipWith (\present value -> if mode == 0 || (mode == 2 && present) then Just value else Nothing) flags base
+        definitions = map (maybe 0 (const 1)) rows
+        values = V.toList (V.mapMaybe id (V.fromList rows))
+        leaf = SchemaElement "x" (Just Optional) (Just PTInt32) Nothing Nothing Nothing Nothing Nothing
+        file = fixtureFile (indexed (V.fromList [root, leaf]) (V.singleton "x") (V.singleton (levelPage v2 1 definitions values 0)) Nothing)
+        target = field (T.AInt 32 True) True
+        verify column expected = do
+          array <- H.evalMaybe (A.asPrim A.PInt32 column)
+          V.generate (A.columnLength column) (A.unsafePrimAt array) H.=== V.fromList expected
+          A.nullCount column H.=== length (filter (== Nothing) expected)
+          case A.validity column of
+            Nothing -> H.assert (all (/= Nothing) expected)
+            Just validity -> do
+              let bits = A.validityBits validity
+                  bytes = Buffer.bitmapBytes bits
+                  remainder = length expected `rem` 8
+              Buffer.bitmapOffset bits H.=== 0
+              Buffer.bitmapLength bits H.=== length expected
+              if remainder == 0 then pure () else (BS.last bytes `shiftR` remainder) H.=== 0
+    H.cover 20 "all valid" (length values == length rows)
+    H.cover 20 "all null" (null values)
+    H.cover 10 "mixed mask" (not (null values) && length values < length rows)
+    H.annotate "full column decode"
+    column <- H.evalEither (Arrow.readParquetColumn file 0 0 target)
+    verify column rows
+    H.annotate "selected column decode"
+    selected <- H.evalEither (Arrow.readParquetColumnWithPagePruning file 0 0 target (Pred.PGtEq (Pred.PVInt32 minBound)))
+    verify (snd selected) (if null values then [] else rows)
+  check "nullable primitive assembly preserves rows, null counts and bitmap tails for both page versions" passed
+  let definitions = [1, 0, 1, 1, 0, 1, 1, 0, 1]
+      words32 = [0x80000000, 0x7fa00001, 0x7fc12345, 0xff800000, 0, 0xffffffff] :: [Word32]
+      words64 = [0x8000000000000000, 0x7ff0123456789abc, 0x7ff8000000000042, 0xfff0000000000000, 0, 0xffffffffffffffff] :: [Word64]
+      expected values = case values of
+        [a, b, c, d, e, f] -> [Just a, Nothing, Just b, Just c, Nothing, Just d, Just e, Nothing, Just f]
+        _ -> error "invalid floating bit-pattern fixture"
+      file typ column =
+        let leaf = SchemaElement "x" (Just Optional) (Just typ) Nothing Nothing Nothing Nothing Nothing
+            pages = V.fromList [levelPageData False 1 definitions column 0, levelPageData True 1 definitions column 0]
+        in fixtureFile (indexed (V.fromList [root, leaf]) (V.singleton "x") pages Nothing)
+  floats <- either error pure (Arrow.readParquetColumn (file PTFloat (Write.ColFloat (P.fromList (map castWord32ToFloat words32)))) 0 0 (field (T.AFloatingPoint T.Single) True))
+  doubles <- either error pure (Arrow.readParquetColumn (file PTDouble (Write.ColDouble (P.fromList (map castWord64ToDouble words64)))) 0 0 (field (T.AFloatingPoint T.DoublePrecision) True))
+  let floatArray = maybe (error "missing FLOAT array") id (A.asPrim A.PFloat floats)
+      doubleArray = maybe (error "missing DOUBLE array") id (A.asPrim A.PDouble doubles)
+  check "nullable FLOAT assembly preserves NaN payloads, infinities and signed zero across V1/V2 pages" (V.generate 18 (fmap castFloatToWord32 . A.unsafePrimAt floatArray) == V.fromList (expected words32 <> expected words32))
+  check "nullable DOUBLE assembly preserves NaN payloads, infinities and signed zero across V1/V2 pages" (V.generate 18 (fmap castDoubleToWord64 . A.unsafePrimAt doubleArray) == V.fromList (expected words64 <> expected words64))
+
+
+deltaEncodingRegression :: IO ()
+deltaEncodingRegression = do
+  let wrapUp = P.fromList [minBound, maxBound, minBound]
+      wrapDown = P.fromList [maxBound, minBound, maxBound]
+      upGolden = BS.pack [128, 1, 4, 3, 255, 255, 255, 255, 15, 1, 2, 0, 0, 0, 8] <> BS.replicate 7 0
+      downGolden = BS.pack [128, 1, 4, 3, 254, 255, 255, 255, 15, 1, 2, 0, 0, 0, 2] <> BS.replicate 7 0
+  check "INT32 delta differences wrap before widening (minimum to maximum)" (Delta.encodeDeltaBinaryPackedInt32 wrapUp == upGolden)
+  check "INT32 delta differences wrap before widening (maximum to minimum)" (Delta.encodeDeltaBinaryPackedInt32 wrapDown == downGolden)
+  let span64 = P.fromList [0, minBound, minBound + 1]
+      spanGolden =
+        BS.pack [128, 1, 4, 3, 0]
+          <> BS.replicate 9 255
+          <> BS.pack [1, 64, 0, 0, 0]
+          <> BS.replicate 8 0
+          <> BS.pack [1, 0, 0, 0, 0, 0, 0, 128]
+          <> BS.replicate 240 0
+  check "INT64 delta miniblocks retain adjusted values with their high bit set" (Delta.encodeDeltaBinaryPackedInt64 span64 == spanGolden)
+  check "INT64 high-bit delta golden decodes without losing the last value" (Read.decodeDeltaBinaryPackedInt64 3 spanGolden == Right span64)
+  let empty = BS.pack [128, 1, 4, 0, 0]
+  check "empty typed delta streams keep a complete header" (Delta.encodeDeltaBinaryPackedInt32 P.empty == empty && Delta.encodeDeltaBinaryPackedInt64 P.empty == empty)
+  int32 <- H.check $ H.withTests 200 $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 300) (Gen.int32 Range.constantBounded))
+    let vector = P.fromList values
+    Read.decodeDeltaBinaryPackedInt32 (length values) (Delta.encodeDeltaBinaryPackedInt32 vector) H.=== Right vector
+  check "typed INT32 delta round-trips cover the full numeric range and block boundaries" int32
+  int64 <- H.check $ H.withTests 200 $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 300) (Gen.int64 Range.constantBounded))
+    let vector = P.fromList values
+    Read.decodeDeltaBinaryPackedInt64 (length values) (Delta.encodeDeltaBinaryPackedInt64 vector) H.=== Right vector
+  check "typed INT64 delta round-trips cover the full numeric range and block boundaries" int64
+
+
+data DeltaPackingCase = DeltaPackingCase
+  { packingInput :: !(P.Vector Int64)
+  , packingExpected :: !ByteString
+  }
+
+
+deltaPackingCase :: Int -> P.Vector Word64 -> DeltaPackingCase
+deltaPackingCase width randomOffsets = DeltaPackingCase input (header <> payload)
+  where
+    count = P.length randomOffsets
+    mask = if width == 64 then maxBound else (1 `shiftL` width) - 1
+    offsets = P.imap (\i value -> if i == 0 then 0 else if i == 1 then 1 `shiftL` (width - 1) else value .&. mask) randomOffsets
+    deltas = P.map (\offset -> minBound + fromIntegral offset) offsets :: P.Vector Int64
+    input = P.scanl' (+) 0 deltas
+    header = BS.pack [128, 1, 4, fromIntegral (count + 1), 0] <> BS.replicate 9 255 <> BS.pack [1, fromIntegral width, 0, 0, 0]
+    payload = BS.pack (map byteAt [0 .. 4 * width - 1])
+    -- Independent bit-by-bit oracle, including zero padding of the
+    -- 32-value miniblock. The writer uses word-sized accumulator stores.
+    byteAt byte = foldl' (\acc bit -> let absolute = byte * 8 + bit; lane = absolute `quot` width in if lane < count && testBit (offsets P.! lane) (absolute `rem` width) then setBit acc bit else acc) (0 :: Word8) [0 .. 7]
+
+
+deltaPackingRegression :: IO ()
+deltaPackingRegression = do
+  mapM_
+    ( \width -> do
+        let sample = deltaPackingCase width (P.generate (2 + width `rem` 31) (\i -> fromIntegral i * 104729))
+        check "delta word packing matches the bit oracle at every width and padded tail" (Delta.encodeDeltaBinaryPackedInt64 (packingInput sample) == packingExpected sample)
+    )
+    [1 .. 64]
+  passed <- H.check $ H.withTests 200 $ H.property $ do
+    width <- H.forAll (Gen.int (Range.constant 1 64))
+    values <- H.forAll (Gen.list (Range.linear 2 32) (Gen.word64 Range.constantBounded))
+    let sample = deltaPackingCase width (P.fromList values)
+        encoded = Delta.encodeDeltaBinaryPackedInt64 (packingInput sample)
+    encoded H.=== packingExpected sample
+    Read.decodeDeltaBinaryPackedInt64 (length values + 1) encoded H.=== Right (packingInput sample)
+  check "delta word packing matches independent bytes for arbitrary widths, values and final padding" passed
+
+
+dictionaryFloatingRegression :: IO ()
+dictionaryFloatingRegression = do
+  let bits32 = P.fromList [0x3f800000, 0x7fc01234, 0xffa05678, 0x7fc01234, 0, 0x80000000, 0, 0x80000000]
+      bits64 = P.fromList [0x3ff0000000000000, 0x7ff8123456789abc, 0xfff056789abcdef0, 0x7ff8123456789abc, 0, 0x8000000000000000, 0, 0x8000000000000000]
+      expectedIndices = P.fromList [0, 1, 2, 1, 3, 4, 3, 4]
+      dictionary32 = Write.buildDictionary (Write.ColFloat (P.map castWord32ToFloat bits32))
+      dictionary64 = Write.buildDictionary (Write.ColDouble (P.map castWord64ToDouble bits64))
+  check "Float dictionaries distinguish NaN payloads and signed zero, retaining first appearance" $
+    Write.dictIndices dictionary32 == expectedIndices
+      && case Write.dictUniques dictionary32 of
+        Write.ColFloat values -> P.map castFloatToWord32 values == P.fromList [0x3f800000, 0x7fc01234, 0xffa05678, 0, 0x80000000]
+        _ -> False
+  check "Double dictionaries distinguish NaN payloads and signed zero, retaining first appearance" $
+    Write.dictIndices dictionary64 == expectedIndices
+      && case Write.dictUniques dictionary64 of
+        Write.ColDouble values -> P.map castDoubleToWord64 values == P.fromList [0x3ff0000000000000, 0x7ff8123456789abc, 0xfff056789abcdef0, 0, 0x8000000000000000]
+        _ -> False
+  let roundtrip32 bits =
+        let dictionary = Write.buildDictionary (Write.ColFloat (P.map castWord32ToFloat bits))
+            pages = Write.encodeDictPage dictionary <> Write.encodeDictDataPage dictionary
+        in P.map castFloatToWord32 . Read.clValues <$> Read.readFloatLevels Uncompressed 0 0 pages
+      roundtrip64 bits =
+        let dictionary = Write.buildDictionary (Write.ColDouble (P.map castWord64ToDouble bits))
+            pages = Write.encodeDictPage dictionary <> Write.encodeDictDataPage dictionary
+        in P.map castDoubleToWord64 . Read.clValues <$> Read.readDoubleLevels Uncompressed 0 0 pages
+  check "Float dictionary pages preserve NaNs and signed zero" (roundtrip32 bits32 == Right bits32)
+  check "Double dictionary pages preserve NaNs and signed zero" (roundtrip64 bits64 == Right bits64)
+  passed32 <- H.check $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 100) (Gen.word32 Range.constantBounded))
+    let bits = bits32 P.++ P.fromList (values ++ reverse values)
+    roundtrip32 bits H.=== Right bits
+  check "Float dictionary pages preserve arbitrary IEEE bits and duplicate entries" passed32
+  passed64 <- H.check $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 100) (Gen.word64 Range.constantBounded))
+    let bits = bits64 P.++ P.fromList (values ++ reverse values)
+    roundtrip64 bits H.=== Right bits
+  check "Double dictionary pages preserve arbitrary IEEE bits and duplicate entries" passed64
+
+
+-- An intentionally simple list oracle is independent of the writer's
+-- mutable hash table. It also specifies stable first-appearance ids.
+dictionaryModel :: Eq a => ([a] -> Write.ColumnData) -> [a] -> Write.Dictionary
+dictionaryModel makeColumn values = Write.Dictionary (makeColumn uniques) indices
+  where
+    uniques = List.nub values
+    indices = P.fromList (map (\value -> maybe (error "dictionary oracle lost a value") fromIntegral (List.elemIndex value uniques)) values)
+
+
+-- Independent copies force content equality rather than address equality.
+-- Interior mismatches share the sampled end key and must be rejected by
+-- the byte comparison before adaptive refinement can choose another key.
+dictionaryEqualityRegression :: IO ()
+dictionaryEqualityRegression = do
+  mapM_
+    ( \width ->
+        mapM_
+          ( \prefix ->
+              mapM_
+                ( \position -> do
+                    let original = BS.replicate width 97
+                        different = BS.take position original <> BS.singleton 98 <> BS.drop (position + 1) original
+                        sliced ordinal bytes = BS.take width (BS.drop prefix (BS.replicate prefix ordinal <> bytes <> BS.singleton ordinal))
+                        values = zipWith sliced [0 ..] [original, different, original, different]
+                    unless
+                      (Write.buildDictionary (Write.ColByteArray (V.fromList values)) == dictionaryModel (Write.ColByteArray . V.fromList) values)
+                      (fail ("dictionary byte equality: width " ++ show width ++ ", prefix " ++ show prefix ++ ", mismatch " ++ show position))
+                )
+                [0 .. width - 1]
+          )
+          [0 .. 7]
+    )
+    [9 .. 128]
+  putStrLn "OK: dictionary byte equality preserves all 65,760 length/alignment/mismatch cases"
+
+
+-- Two different interior words change the same bit, while both ends stay
+-- equal. These remain distinct values even when a parity-style reduction
+-- of their word differences would cancel. Independent slices also keep
+-- address equality and surrounding bytes out of the comparison.
+dictionaryEqualityCancellationRegression :: IO ()
+dictionaryEqualityCancellationRegression = do
+  let original = BS.replicate 64 97
+  mapM_
+    ( \firstWord ->
+        mapM_
+          ( \secondWord ->
+              mapM_
+                ( \byteInWord ->
+                    mapM_
+                      ( \bitInByte ->
+                          mapM_
+                            ( \prefix -> do
+                                let first = firstWord * 8 + byteInWord
+                                    second = secondWord * 8 + byteInWord
+                                    mask = 1 `shiftL` bitInByte
+                                    different = BS.pack $ map (\offset -> let value = BS.index original offset in if offset == first || offset == second then value `xor` mask else value) [0 .. 63]
+                                    sliced ordinal bytes = BS.take 64 (BS.drop prefix (BS.replicate prefix ordinal <> bytes <> BS.singleton ordinal))
+                                    values = zipWith sliced [0 ..] [original, different, original, different]
+                                unless
+                                  (Write.buildDictionary (Write.ColByteArray (V.fromList values)) == dictionaryModel (Write.ColByteArray . V.fromList) values)
+                                  (fail ("dictionary paired differences: words " ++ show firstWord ++ "/" ++ show secondWord ++ ", byte " ++ show byteInWord ++ ", bit " ++ show bitInByte ++ ", prefix " ++ show prefix))
+                            )
+                            [0 .. 7]
+                      )
+                      [0 .. 7]
+                )
+                [0 .. 7]
+          )
+          [firstWord + 1 .. 6]
+    )
+    [1 .. 5]
+  putStrLn "OK: dictionary byte equality preserves all 7,680 paired interior changes"
+
+
+dictionaryConstructionRegression :: IO ()
+dictionaryConstructionRegression = do
+  mapM_
+    ( \width -> do
+        let count = 32768
+            pool = V.generate 8 (\key -> BS.singleton (fromIntegral key) <> BS.replicate (width - 1) 97)
+        source <- V.generateM count (\i -> BS.useAsCStringLen (V.unsafeIndex pool (i `rem` 8)) BS.packCStringLen)
+        _ <- evaluate (V.foldl' (\total value -> total + BS.length value) 0 source)
+        before <- getAllocationCounter
+        dictionary <- evaluate (Write.buildDictionary (Write.ColByteArray source))
+        after <- getAllocationCounter
+        check ("dictionary row bookkeeping avoids per-row thunks: " ++ show (before - after) ++ " bytes") $
+          before - after < fromIntegral (count * 6 + 32768)
+            && Write.columnDataLength (Write.dictUniques dictionary) == 8
+            && P.length (Write.dictIndices dictionary) == count
+    )
+    ([1 .. 9] ++ [15, 16, 17, 31, 32, 33, 63, 64, 65, 127, 128, 129, 256])
+  let uniqueCount = 8192
+      uniqueBytes key = BS.pack (map (\shift -> fromIntegral ((fromIntegral key :: Word64) `shiftR` shift)) [0, 8 .. 56])
+  uniqueSource <- evaluate (V.generate uniqueCount uniqueBytes)
+  _ <- evaluate (V.foldl' (\total value -> total + BS.length value) 0 uniqueSource)
+  beforeUnique <- getAllocationCounter
+  uniqueDictionary <- evaluate (Write.buildDictionary (Write.ColByteArray uniqueSource))
+  afterUnique <- getAllocationCounter
+  check ("dictionary uniques avoid deferred indexing closures: " ++ show (beforeUnique - afterUnique) ++ " bytes") $
+    beforeUnique - afterUnique < fromIntegral (uniqueCount * 90 + 32768)
+      && Write.columnDataLength (Write.dictUniques uniqueDictionary) == uniqueCount
+  mapM_
+    ( \prefix -> do
+        let tagged = concatMap (\size -> [BS.replicate size 0, BS.replicate size 255, BS.pack (take size [1 .. 7])]) [0 .. 7]
+            eight = [BS.replicate 8 0, BS.replicate 8 255, BS.pack [255, 0, 255, 0, 255, 0, 255, 0]]
+            mixed = tagged ++ eight
+            sliced bytes = BS.take (BS.length bytes) (BS.drop prefix (BS.replicate prefix 0xa5 <> bytes <> BS.replicate 8 0x5a))
+        mapM_
+          ( \original -> do
+              let values = map sliced (original ++ reverse original)
+              check "exact short-key dispatch preserves lengths, full high bits and unaligned slices" $
+                Write.buildDictionary (Write.ColByteArray (V.fromList values)) == dictionaryModel (Write.ColByteArray . V.fromList) values
+          )
+          [tagged, eight, mixed]
+    )
+    [0 .. 7]
+  -- Matching ends with distinct middle bytes force the full-hash mode.
+  let promotionPrefix = [BS.replicate 64 0x42, BS.replicate 8 0x42 <> BS.singleton 0x43 <> BS.replicate 55 0x42, BS.replicate 24 0x42 <> BS.singleton 0x44 <> BS.replicate 39 0x42]
+  -- Distinct 64-byte values chosen to collide in the medium lookup mix.
+  -- One differs at the first word, the other only in the last 16 bytes.
+  let mediumBase = BS.replicate 64 97
+      earlyCollision = BS.concat [BS.pack [96, 97, 97, 97, 97, 97, 97, 97], BS.replicate 24 97, BS.pack [254, 171, 118, 155, 54, 239, 41, 199], BS.replicate 24 97]
+      lateCollision = BS.concat [BS.replicate 48 97, BS.pack [96, 97, 97, 97, 97, 97, 97, 97], BS.pack [45, 123, 240, 164, 64, 21, 0, 38]]
+      mediumSlice bytes = BS.take 64 (BS.drop 3 (BS.replicate 3 0xa5 <> bytes <> BS.replicate 8 0x5a))
+      mediumValues = map mediumSlice (promotionPrefix ++ [mediumBase, earlyCollision, mediumBase, lateCollision, earlyCollision, lateCollision])
+  check "medium-key collisions compare all words, including late mismatches in unaligned values" $
+    Write.buildDictionary (Write.ColByteArray (V.fromList mediumValues)) == dictionaryModel (Write.ColByteArray . V.fromList) mediumValues
+  let larger = BS.replicate 129 97
+      largerHash = Hash.xxh64 0 larger
+      sameKey = BS.pack (map (\shift -> fromIntegral (largerHash `shiftR` shift)) [0, 8 .. 56])
+      collisions = promotionPrefix ++ [larger, sameKey, larger, sameKey]
+  check "a large-value hash colliding with an exact short key still compares full payloads" $
+    Write.buildDictionary (Write.ColByteArray (V.fromList collisions)) == dictionaryModel (Write.ColByteArray . V.fromList) collisions
+  -- These distinct 129-byte fixtures collide in XXH64, including length.
+  -- Altering a pair of words in one lane preserves its accumulator.
+  let largeEarly = BS.concat [BS.pack [96, 97, 97, 97, 97, 97, 97, 97], BS.replicate 24 97, BS.pack [239, 26, 196, 184, 36, 158, 242, 163], BS.replicate 89 97]
+      largeLate = BS.concat [BS.replicate 64 97, BS.pack [96, 97, 97, 97, 97, 97, 97, 97], BS.replicate 24 97, BS.pack [56, 26, 164, 255, 164, 182, 226, 68], BS.replicate 25 97]
+      largeSlice bytes = BS.take 129 (BS.drop 5 (BS.replicate 5 0xa5 <> bytes <> BS.replicate 8 0x5a))
+      largeValues = promotionPrefix ++ map largeSlice [larger, largeEarly, larger, largeLate, largeEarly, largeLate]
+  check "large collision fixtures have equal hashes and distinct payloads" $
+    Hash.xxh64 0 larger == Hash.xxh64 0 largeEarly
+      && Hash.xxh64 0 larger == Hash.xxh64 0 largeLate
+      && length (List.nub largeValues) == 6
+  check "same-length large hashes still compare full unaligned payloads" $
+    Write.buildDictionary (Write.ColByteArray (V.fromList largeValues)) == dictionaryModel (Write.ColByteArray . V.fromList) largeValues
+  mapM_
+    ( \prefix -> do
+        let originals = map (\size -> BS.replicate size 0) [0 .. 9] ++ map (\size -> BS.pack (take size [1 .. 8])) [0 .. 8] ++ map (\size -> BS.pack (take size (cycle [1 .. 255]))) [15, 16, 17, 31, 32, 33, 63, 64, 65, 127, 128, 129, 255, 256, 257]
+            slice i bytes = BS.take (BS.length bytes) (BS.drop prefix (BS.replicate prefix (fromIntegral (i * 17)) <> bytes <> BS.replicate 8 (fromIntegral i)))
+            values = zipWith slice [0 :: Int ..] (originals ++ reverse originals)
+        check "short byte keys preserve lengths, zero padding and unaligned slices" $
+          Write.buildDictionary (Write.ColByteArray (V.fromList values)) == dictionaryModel (Write.ColByteArray . V.fromList) values
+    )
+    [0 .. 7]
+  mapM_
+    ( \distinct -> do
+        let values = take (if distinct == 0 then 0 else distinct * 2 + 19) (cycle [0 .. distinct - 1])
+            integers = map (\value -> fromIntegral value * 0x100000001) values :: [Int64]
+            bytes = map (\value -> BS.replicate (1 + value `rem` 7) (fromIntegral value)) values
+            sliced input = P.slice 1 (P.length input) (P.singleton 999 P.++ input P.++ P.singleton 999)
+            actual64 = Write.buildDictionary (Write.ColInt64 (sliced (P.fromList integers)))
+            actualBytes = Write.buildDictionary (Write.ColByteArray (V.slice 1 (length bytes) (V.fromList ("sentinel" : bytes ++ ["sentinel"]))))
+        check "dictionary growth/empty/sliced INT64 inputs retain stable values and ids" (actual64 == dictionaryModel (Write.ColInt64 . P.fromList) integers)
+        check "dictionary growth/empty/sliced byte inputs retain stable values and ids" (actualBytes == dictionaryModel (Write.ColByteArray . V.fromList) bytes)
+    )
+    [0, 1, 31, 32, 33, 63, 64, 65, 127, 128, 129, 257]
+  -- Re-key after earlier table growth, then grow again in full-hash mode.
+  -- Prefix rows, repetitions and the triggering row must keep their ids.
+  mapM_
+    ( \distinct -> do
+        let word :: Int -> ByteString
+            word key = BS.pack (map (\shift -> fromIntegral ((fromIntegral key :: Word64) `shiftR` shift)) [0, 8 .. 56])
+            value key = word key <> BS.replicate 56 97
+            prefix = map value [0 .. distinct - 1]
+            ambiguous = word 0 <> BS.singleton 98 <> BS.replicate 55 97
+            secondAmbiguous = word 0 <> BS.replicate 16 97 <> BS.singleton 99 <> BS.replicate 39 97
+            values = prefix ++ reverse prefix ++ [ambiguous] ++ map value [distinct .. distinct * 2 + 1] ++ [secondAmbiguous, value 0, ambiguous, secondAmbiguous] ++ prefix
+        check "adaptive dictionaries preserve ids across both late promotions and subsequent growth" $
+          Write.buildDictionary (Write.ColByteArray (V.fromList values)) == dictionaryModel (Write.ColByteArray . V.fromList) values
+    )
+    [1, 31, 32, 33, 63, 64, 65, 127, 128, 129, 257]
+  mapM_
+    ( \(width, refined) -> do
+        source <- V.generateM 32768 $ \i ->
+          let offset = if refined then 24 else 0
+              value = BS.replicate offset 97 <> BS.singleton (fromIntegral (i `rem` 8)) <> BS.replicate (width - offset - 1) 97
+          in BS.useAsCStringLen value BS.packCStringLen
+        _ <- evaluate (V.foldl' (\total value -> total + BS.length value) 0 source)
+        before <- getAllocationCounter
+        dictionary <- evaluate (Write.buildDictionary (Write.ColByteArray source))
+        after <- getAllocationCounter
+        check ("byte dictionary scan retains bounded allocation at " ++ show width ++ " bytes, refined " ++ show refined ++ ": " ++ show (before - after)) $
+          before - after < 32768 * 6 + 32768
+            && Write.columnDataLength (Write.dictUniques dictionary) == 8
+            && P.length (Write.dictIndices dictionary) == 32768
+    )
+    [(9, False), (64, False), (128, False), (64, True), (128, True)]
+  mapM_
+    ( \width ->
+        mapM_
+          ( \wideHint -> do
+              source <- V.generateM 32768 $ \i ->
+                let key = i `rem` 8
+                    (high, low) = key `quotRem` 2
+                    size = if wideHint && i == 3 then 256 else width
+                    value = BS.replicate 8 97 <> BS.singleton (fromIntegral low) <> BS.replicate 15 97 <> BS.singleton (fromIntegral high) <> BS.replicate (size - 25) 97
+                in BS.useAsCStringLen value BS.packCStringLen
+              _ <- evaluate (V.foldl' (\total value -> total + BS.length value) 0 source)
+              beforePromotion <- getAllocationCounter
+              dictionary <- evaluate (Write.buildDictionary (Write.ColByteArray source))
+              afterPromotion <- getAllocationCounter
+              check ("full-hash promotion retains bounded allocation at " ++ show width ++ " bytes, wide hint " ++ show wideHint ++ ": " ++ show (beforePromotion - afterPromotion)) $
+                beforePromotion - afterPromotion < 32768 * 6 + 32768
+                  && Write.columnDataLength (Write.dictUniques dictionary) == (if wideHint then 9 else 8)
+                  && P.length (Write.dictIndices dictionary) == 32768
+          )
+          (if width <= 128 then [False, True] else [False])
+    )
+    [64, 128, 256]
+  refinedSource <- V.generateM 32768 $ \i ->
+    let value = BS.replicate 24 97 <> BS.singleton (fromIntegral (i `rem` 8)) <> BS.replicate 231 97
+    in BS.useAsCStringLen value BS.packCStringLen
+  _ <- evaluate (V.foldl' (\total value -> total + BS.length value) 0 refinedSource)
+  beforeRefinement <- getAllocationCounter
+  refinedDictionary <- evaluate (Write.buildDictionary (Write.ColByteArray refinedSource))
+  afterRefinement <- getAllocationCounter
+  check ("refined-key scan retains bounded allocation: " ++ show (beforeRefinement - afterRefinement) ++ " bytes") $
+    beforeRefinement - afterRefinement < 32768 * 6 + 32768
+      && Write.columnDataLength (Write.dictUniques refinedDictionary) == 8
+      && P.length (Write.dictIndices refinedDictionary) == 32768
+  mapM_
+    ( \prefix -> do
+        let first = BS.replicate 64 0x42
+            second = BS.replicate 48 0x42 <> BS.singleton 0x43 <> BS.replicate 15 0x42
+            payloads = map (\size -> BS.pack (take size (cycle [1 .. 255]))) ([9 .. 47] ++ [0 .. 8])
+            originals = [first, second] ++ payloads ++ [first, second] ++ reverse payloads
+            sliced i bytes = BS.take (BS.length bytes) (BS.drop prefix (BS.replicate prefix (fromIntegral i) <> bytes <> BS.replicate 8 (fromIntegral (i * 17))))
+            values = zipWith sliced [0 :: Int ..] originals
+        check "refined pivots clamp to shorter logical slices without reading neighboring bytes" $
+          Write.buildDictionary (Write.ColByteArray (V.fromList values)) == dictionaryModel (Write.ColByteArray . V.fromList) values
+    )
+    [0 .. 7]
+  mapM_
+    ( \prefix -> do
+        let word key = BS.pack (map (\shift -> fromIntegral ((fromIntegral key :: Word64) `shiftR` shift)) [0, 8 .. 56])
+            small = map (\key -> word key <> BS.replicate 56 97) [0 :: Int .. 31]
+            wide = BS.replicate 4096 97
+            refined = BS.take 2000 wide <> BS.singleton 98 <> BS.drop 2001 wide
+            full = BS.take 2048 wide <> BS.singleton 99 <> BS.drop 2049 wide
+            originals = small ++ [wide, refined] ++ take 1 small ++ [full] ++ reverse small ++ [wide, refined, full]
+            sliced bytes = BS.take (BS.length bytes) (BS.drop prefix (BS.replicate prefix 0xa5 <> bytes <> BS.replicate 8 0x5a))
+            values = map sliced originals
+        check "medium-width hints allow later wide values through growth and both promotions" $
+          Write.buildDictionary (Write.ColByteArray (V.fromList values)) == dictionaryModel (Write.ColByteArray . V.fromList) values
+    )
+    [0 .. 7]
+  promoted <- H.check $ H.withTests 300 $ H.property $ do
+    keys <- H.forAll (Gen.list (Range.linear 0 300) (Gen.word64 (Range.linear 0 300)))
+    let word key = BS.pack (map (\shift -> fromIntegral (key `shiftR` shift)) [0, 8 .. 56])
+        value key = let (high, low) = key `quotRem` 4 in BS.replicate 8 97 <> word low <> word high <> BS.replicate 8 97
+        values = map value keys
+    Write.buildDictionary (Write.ColByteArray (V.fromList values)) H.=== dictionaryModel (Write.ColByteArray . V.fromList) values
+  check "sampled-key collisions promote before duplicate middle values can be merged" promoted
+  int32 <- H.check $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 400) (Gen.choice [Gen.int32 Range.constantBounded, Gen.int32 (Range.constant (-64) 64)]))
+    Write.buildDictionary (Write.ColInt32 (P.fromList values)) H.=== dictionaryModel (Write.ColInt32 . P.fromList) values
+  check "INT32 dictionaries match the independent model across collisions, duplicates and growth" int32
+  int64 <- H.check $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 400) (Gen.choice [Gen.int64 Range.constantBounded, Gen.int64 (Range.constant (-64) 64)]))
+    Write.buildDictionary (Write.ColInt64 (P.fromList values)) H.=== dictionaryModel (Write.ColInt64 . P.fromList) values
+  check "INT64 dictionaries match the independent model across collisions, duplicates and growth" int64
+  bytes <- H.check $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 300) (Gen.bytes (Range.linear 0 512)))
+    Write.buildDictionary (Write.ColByteArray (V.fromList values)) H.=== dictionaryModel (Write.ColByteArray . V.fromList) values
+  check "byte dictionaries match the independent model, including empty and duplicate payloads" bytes
+  booleans <- H.check $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 400) Gen.bool)
+    Write.buildDictionary (Write.ColBool (V.fromList values)) H.=== dictionaryModel (Write.ColBool . V.fromList) values
+  check "boolean dictionaries match the independent model" booleans
+
+
+root :: SchemaElement
+root = SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+
+
+field :: T.ArrowType -> Bool -> T.Field
+field typ nullable = T.Field "x" nullable typ V.empty Nothing V.empty
+
+
+intPage :: [Int32] -> TestPage
+intPage values =
+  let column = Write.ColInt32 (P.fromList values)
+      (header, body) = Write.encodeColumnDataPageParts column
+  in TestPage (header <> body) (length values) (Write.columnDataStatistics column)
+
+
+levelPage :: Bool -> Int -> [Int32] -> [Int32] -> Int -> TestPage
+levelPage v2 maximumDef definitions values = levelPageData v2 maximumDef definitions (Write.ColInt32 (P.fromList values))
+
+
+levelPageData :: Bool -> Int -> [Int32] -> Write.ColumnData -> Int -> TestPage
+levelPageData v2 maximumDef definitions column nullAdjustment =
+  let defs = P.fromList definitions
+      (_, payload) = Write.encodeColumnDataPageParts column
+      stream =
+        (if v2 then Levels.encodeRLEHybrid else Levels.encodeLengthPrefixedHybrid)
+          (Levels.bitWidthFor maximumDef)
+          defs
+      body = stream <> payload
+      n = length definitions
+      nulls = n - Write.columnDataLength column
+      pageHeader =
+        if v2
+          then
+            Page.PtDataPageV2
+              ( Page.DataPageHeaderV2
+                  (fromIntegral n)
+                  (fromIntegral (nulls + nullAdjustment))
+                  (fromIntegral n)
+                  0
+                  (fromIntegral (BS.length stream))
+                  0
+                  False
+              )
+          else Page.PtDataPage (Page.DataPageHeader (fromIntegral n) 0)
+      header = Page.PageHeader pageHeader (Just (fromIntegral (BS.length body))) (Just (fromIntegral (BS.length body)))
+  in TestPage
+       (Write.encodePageHeader header <> body)
+       n
+       ((Write.columnDataStatistics column) {statNullCount = Just (fromIntegral nulls)})
+
+
+indexed :: V.Vector SchemaElement -> V.Vector Text -> V.Vector TestPage -> Maybe ByteString -> Fixture
+indexed schema path pages dictionary =
+  let dictionaryBytes = maybe BS.empty id dictionary
+      start = 4 + BS.length dictionaryBytes
+      offsets = V.scanl' (+) start (BS.length . testBytes <$> pages)
+      rows = V.scanl' (+) 0 (testRows <$> pages)
+      locations =
+        V.imap
+          ( \i page ->
+              PageLocation
+                (fromIntegral (offsets V.! i))
+                (fromIntegral (BS.length (testBytes page)))
+                (fromIntegral (rows V.! i))
+          )
+          pages
+      offsetBytes = Index.encodeOffsetIndex (OffsetIndex locations Nothing)
+      columnIndex =
+        ColumnIndex
+          { ciNullPages = (\p -> statNullCount (testStats p) == Just (fromIntegral (testRows p))) <$> pages
+          , ciMinValues = maybe BS.empty id . statMinValue . testStats <$> pages
+          , ciMaxValues = maybe BS.empty id . statMaxValue . testStats <$> pages
+          , ciBoundaryOrder = OrderUnordered
+          , ciNullCounts = traverse (statNullCount . testStats) pages
+          , ciNanCounts = Nothing
+          , ciRepetitionLevelHistograms = Nothing
+          , ciDefinitionLevelHistograms = Nothing
+          }
+      columnBytes = Index.encodeColumnIndex columnIndex
+      offsetsStart = V.last offsets
+      columnsStart = offsetsStart + BS.length offsetBytes
+      footerStart = columnsStart + BS.length columnBytes
+      columnMetadata =
+        ColumnMetadata
+          { cmType = maybe (error "missing leaf") id (seType (V.last schema))
+          , cmEncodings = V.fromList [Plain, RLEDictionary]
+          , cmPathInSchema = path
+          , cmCodec = Uncompressed
+          , cmNumValues = fromIntegral (V.last rows)
+          , cmTotalUncompressedSize = fromIntegral (offsetsStart - 4)
+          , cmTotalCompressedSize = fromIntegral (offsetsStart - 4)
+          , cmDataPageOffset = fromIntegral start
+          , cmDictionaryPageOffset = (const 4) <$> dictionary
+          , cmStatistics = Nothing
+          , cmBloomFilterOffset = Nothing
+          , cmBloomFilterLength = Nothing
+          }
+      chunk =
+        ColumnChunk
+          Nothing
+          0
+          (Just columnMetadata)
+          (Just (fromIntegral offsetsStart))
+          (Just (fromIntegral (BS.length offsetBytes)))
+          (Just (fromIntegral columnsStart))
+          (Just (fromIntegral (BS.length columnBytes)))
+      group = RowGroup (V.singleton chunk) (fromIntegral (offsetsStart - 4)) (fromIntegral (V.last rows)) Nothing
+      metadata =
+        FileMetadata
+          2
+          schema
+          (fromIntegral (V.last rows))
+          (V.singleton group)
+          (Just "selection-regression")
+          (Just (V.singleton TypeDefinedOrder))
+          Nothing
+      bytes =
+        "PAR1"
+          <> dictionaryBytes
+          <> BS.concat (V.toList (testBytes <$> pages))
+          <> offsetBytes
+          <> columnBytes
+          <> Footer.writeFooter metadata
+  in Fixture (Read.ParquetFile bytes metadata) locations footerStart
+
+
+mapChunk :: (ColumnChunk -> ColumnChunk) -> Read.ParquetFile -> Read.ParquetFile
+mapChunk change file =
+  file
+    { Read.pfFooter =
+        (Read.pfFooter file)
+          { fmRowGroups = V.map (\group -> group {rgColumns = change <$> rgColumns group}) (fmRowGroups (Read.pfFooter file))
+          }
+    }
+
+
+replace :: Int -> ByteString -> ByteString -> ByteString
+replace offset replacement bytes = BS.take offset bytes <> replacement <> BS.drop (offset + BS.length replacement) bytes
+
+
+check :: String -> Bool -> IO ()
+check label passed = do
+  unless passed (error ("FAIL: " ++ label))
+  putStrLn ("OK: " ++ label)
+
+
+nestedProjectionRegression :: IO ()
+nestedProjectionRegression = do
+  let int = Nested.NSPrimitive Nested.LtInt32
+      float = Nested.NSPrimitive Nested.LtFloat
+      scalar = Nested.NRLeaf . Nested.LvInt32
+      optional = Nested.NSOptional
+      required = Nested.NSRequired
+      fld name nullable typ kids = T.Field name nullable typ kids Nothing V.empty
+      primitive name nullable typ = fld name nullable typ V.empty
+      listField typ child = fld "v" True typ (V.singleton child)
+      i64 name nullable = primitive name nullable (T.AInt 64 True)
+      dbl name nullable = primitive name nullable (T.AFloatingPoint T.DoublePrecision)
+      mask = A.validityFromBools (V.fromList [True, False, True, True])
+      offsets32 = S.fromList [0, 3, 3, 3, 4]
+      offsets64 = S.fromList [0, 3, 3, 3, 4]
+      listRows = V.fromList [Nested.NRList (V.fromList [scalar 1, Nested.NRNull, scalar 2]), Nested.NRNull, Nested.NRList V.empty, Nested.NRList (V.singleton (scalar 3))]
+      childValues = A.fromMaybes A.PInt64 (V.fromList [Just 1, Nothing, Just 2, Just 3])
+      fileFor schema rows = do
+        bytes <- either fail pure (Nested.buildNestedFile (V.singleton ("v", schema)) (V.singleton rows))
+        either fail pure (Read.loadParquetFile bytes)
+      project requested file = Arrow.parquetRowGroupToArrow (T.Schema (V.singleton requested) T.Little V.empty V.empty) file 0
+      matches label requested file expected =
+        check label (project requested file == Right (V.singleton expected))
+  listFile <- fileFor (optional (Nested.NSList (optional int))) listRows
+  expectedList <- either fail pure (A.mkList mask offsets32 childValues)
+  expectedLarge <- either fail pure (A.mkLargeList mask offsets64 childValues)
+  matches
+    "nested list projection accepts custom element name and integer widening"
+    (listField T.AList (i64 "my_item" True))
+    listFile
+    expectedList
+  matches
+    "nested list projection builds requested 64-bit offsets"
+    (listField T.ALargeList (i64 "my_item" True))
+    listFile
+    expectedLarge
+  check "nested required element projection rejects visible null elements" $
+    isLeft (project (listField T.AList (i64 "my_item" False)) listFile)
+  check "nested projection rejects incompatible leaf reinterpretation" $
+    isLeft (project (listField T.AList (dbl "my_item" True)) listFile)
+  let nativeStruct = Nested.NSStruct (V.fromList [("unused", required int), ("small", optional int), ("float", optional float)])
+      record a b c = Nested.NRStruct (V.fromList [scalar a, b, c])
+      structRows = V.fromList [record 9 (scalar 1) (Nested.NRLeaf (Nested.LvFloat 1.5)), Nested.NRNull, record 7 (scalar 2) Nested.NRNull, record 5 (scalar 3) (Nested.NRLeaf (Nested.LvFloat 4.5))]
+      requestedStruct name nullable = fld name nullable T.AStruct (V.fromList [dbl "float" True, i64 "small" False])
+      floats = A.fromMaybes A.PDouble (V.fromList [Just 1.5, Nothing, Nothing, Just 4.5])
+      ints = A.primColumn A.PInt64 (S.fromList [1, 1, 2, 3])
+  structFile <- fileFor (optional nativeStruct) structRows
+  expectedStruct <- either fail pure (A.mkStruct 4 mask (V.fromList [("float", floats), ("small", ints)]))
+  matches
+    "nested struct projection reorders, drops and widens fields; hidden parent nulls do not reject required children"
+    (requestedStruct "v" True)
+    structFile
+    expectedStruct
+  let footer = Read.pfFooter structFile
+      groups = V.map (\rg -> rg {rgColumns = V.imap (\i col -> if i == 0 then col {ccMetadata = Nothing} else col) (rgColumns rg)}) (fmRowGroups footer)
+      poisoned = structFile {Read.pfFooter = footer {fmRowGroups = groups}}
+  check "unprojected malformed column actually fails a full read" $
+    isLeft (Arrow.parquetFileArrowSchemaChecked poisoned >>= \schema -> either (Left . show) Right (Arrow.parquetRowGroupToArrow schema poisoned 0))
+  matches
+    "nested struct projection does not decode omitted physical leaves"
+    (requestedStruct "v" True)
+    poisoned
+    expectedStruct
+  check "nested required struct projection rejects visible parent nulls" $
+    isLeft (project (requestedStruct "v" False) structFile)
+  badStruct <- fileFor (optional nativeStruct) (structRows V.// [(2, record 7 Nested.NRNull Nested.NRNull)])
+  check "nested required child projection rejects a visible null under a present parent" $
+    isLeft (project (requestedStruct "v" True) badStruct)
+  check "nested struct projection reports absent children" $
+    isLeft (project (fld "v" True T.AStruct (V.singleton (i64 "missing" True))) structFile)
+  emptyStruct <- either fail pure (A.mkStruct 4 mask V.empty)
+  matches
+    "empty struct projection retains parent rows and validity"
+    (fld "v" True T.AStruct V.empty)
+    structFile
+    emptyStruct
+  listStructFile <-
+    fileFor (optional (Nested.NSList (optional nativeStruct))) $
+      V.fromList [Nested.NRList (V.take 3 structRows), Nested.NRNull, Nested.NRList V.empty, Nested.NRList (V.singleton (V.last structRows))]
+  listStruct <- either fail pure (A.mkLargeList mask offsets64 expectedStruct)
+  matches
+    "large-list projection recursively reorders and widens struct children"
+    (listField T.ALargeList (requestedStruct "custom_element" True))
+    listStructFile
+    listStruct
+  let mapRows = V.fromList [Nested.NRMapEntries (V.fromList [(scalar 1, Nested.NRLeaf (Nested.LvFloat 1.5)), (scalar 2, Nested.NRNull)]), Nested.NRNull, Nested.NRMapEntries V.empty, Nested.NRMapEntries (V.singleton (scalar 3, Nested.NRLeaf (Nested.LvFloat 3.5)))]
+      mapTarget = fld "v" True (T.AMap False) (V.singleton (fld "pairs" False T.AStruct (V.fromList [i64 "k" False, dbl "x" True])))
+  mapFile <- fileFor (optional (Nested.NSMap (required int) (optional float))) mapRows
+  expectedMap <- either fail pure (A.mkMap mask (S.fromList [0, 2, 2, 2, 3]) (A.primColumn A.PInt64 (S.fromList [1, 2, 3])) (A.fromMaybes A.PDouble (V.fromList [Just 1.5, Nothing, Just 3.5])))
+  matches
+    "nested map projection accepts custom wrapper names and widens keys and values"
+    mapTarget
+    mapFile
+    expectedMap
+
+
+-- Exercise real dictionary outputs rather than mirroring the private hash.
+-- A boxed high/low product on the row loop would exceed this allocation cap.
+dictionaryBucketMixRegression :: IO ()
+dictionaryBucketMixRegression = do
+  let count = 32768
+      uniqueCount = 257
+      word key = (fromIntegral key `shiftL` 48) `xor` 0x80000000000000ff :: Word64
+      numeric = Write.ColInt64 (P.generate count (\i -> fromIntegral (word (i `rem` uniqueCount))))
+      bytes key = Lazy.toStrict (Builder.toLazyByteString (Builder.word64LE (word key)))
+      pool = V.generate uniqueCount bytes
+      binary = Write.ColByteArray (V.generate count (\i -> V.unsafeIndex pool (i `rem` uniqueCount)))
+      checkAllocation label source expected = do
+        _ <- evaluate (Write.columnDataLength source)
+        before <- getAllocationCounter
+        actual <- evaluate (Write.buildDictionary source)
+        after <- getAllocationCounter
+        check (label ++ " dictionary mix has no per-row allocation: " ++ show (before - after)) $
+          before - after < fromIntegral (count * 6 + uniqueCount * 128 + 32768)
+        check (label ++ " dictionary retains upper key bits and stable first-appearance order") (actual == expected)
+      expectedIndices = P.generate count (\i -> fromIntegral (i `rem` uniqueCount))
+  checkAllocation "upper-bit numeric" numeric $
+    Write.Dictionary (Write.ColInt64 (P.generate uniqueCount (fromIntegral . word))) expectedIndices
+  _ <- evaluate (V.foldl' (\total value -> total + BS.length value) 0 pool)
+  checkAllocation "upper-bit binary" binary $
+    Write.Dictionary (Write.ColByteArray pool) expectedIndices
+  mapM_
+    ( \position -> do
+        let values = [0, bitWord position, maxBound, bitWord position, 0]
+            source = Write.ColInt64 (P.fromList (map fromIntegral values))
+        check "every high/low key bit survives dictionary construction" $
+          Write.buildDictionary source == dictionaryModel (Write.ColInt64 . P.fromList) (map fromIntegral values)
+    )
+    [0 .. 63]
+  where
+    bitWord position = 1 `shiftL` position :: Word64
+
+
+-- A scalar dictionary owns its native unique values directly. The bound
+-- catches the former source-row cache and final gather, while allowing
+-- geometric growth and one Int32 row index per input value.
+dictionaryScalarStorageRegression :: IO ()
+dictionaryScalarStorageRegression = do
+  let count = 8192
+      words32 = P.generate count (\i -> fromIntegral i * 1664525 + 1013904223) :: P.Vector Word32
+      words64 = P.generate count (\i -> fromIntegral i * 6364136223846793005 + 1442695040888963407) :: P.Vector Word64
+      int32 = Write.ColInt32 . P.map fromIntegral
+      int64 = Write.ColInt64 . P.map fromIntegral
+      float = Write.ColFloat . P.map castWord32ToFloat
+      double = Write.ColDouble . P.map castWord64ToDouble
+      int32Bits = \case
+        Write.ColInt32 values -> Just (P.map fromIntegral values :: P.Vector Word32)
+        _ -> Nothing
+      int64Bits = \case
+        Write.ColInt64 values -> Just (P.map fromIntegral values :: P.Vector Word64)
+        _ -> Nothing
+      floatBits = \case
+        Write.ColFloat values -> Just (P.map castFloatToWord32 values)
+        _ -> Nothing
+      doubleBits = \case
+        Write.ColDouble values -> Just (P.map castDoubleToWord64 values)
+        _ -> Nothing
+      storage label width makeColumn recover wireBits = do
+        let source = makeColumn wireBits
+        _ <- evaluate (Write.columnDataLength source)
+        before <- getAllocationCounter
+        dictionary <- evaluate (Write.buildDictionary source)
+        after <- getAllocationCounter
+        check (label ++ " scalar dictionary avoids source-row and gather buffers: " ++ show (before - after)) $
+          before - after < fromIntegral (count * (24 + width * 2) + 16384)
+        check (label ++ " scalar dictionary retains every wire bit and stable ids") $
+          recover (Write.dictUniques dictionary) == Just wireBits
+            && Write.dictIndices dictionary == P.generate count fromIntegral
+      boundary label makeColumn recover prefix salt distinct = do
+        let originals = take distinct (prefix ++ map salt [0 .. distinct])
+            wireBits = originals ++ reverse originals ++ take 7 originals
+            expected = List.nub wireBits
+            expectedIds = P.fromList (map (\value -> maybe (error "scalar oracle lost a value") fromIntegral (List.elemIndex value expected)) wireBits)
+            values = P.fromList wireBits
+        mapM_
+          ( \offset -> do
+              let sliced = P.slice offset (P.length values) (P.replicate offset 0x55 P.++ values P.++ P.singleton 0xaa)
+                  dictionary = Write.buildDictionary (makeColumn sliced)
+              check (label ++ " scalar dictionary preserves slices, growth and IEEE identity") $
+                recover (Write.dictUniques dictionary) == Just (P.fromList expected)
+                  && Write.dictIndices dictionary == expectedIds
+          )
+          [0, 1, 3, 7]
+  storage "INT32" 4 int32 int32Bits words32
+  storage "INT64" 8 int64 int64Bits words64
+  storage "FLOAT" 4 float floatBits words32
+  storage "DOUBLE" 8 double doubleBits words64
+  mapM_
+    ( \distinct -> do
+        let prefix32 = [0, maxBound, 0x80000000, 0x7f800000, 0xff800000, 0x7fc00001, 0x7fa00001, 0xffc00002]
+            prefix64 = [0, maxBound, 0x8000000000000000, 0x7ff0000000000000, 0xfff0000000000000, 0x7ff8000000000001, 0x7ff0000000000001, 0xfff8000000000002]
+            spread32 i = fromIntegral i * 1664525 + 1013904223 :: Word32
+            spread64 i = fromIntegral i * 6364136223846793005 + 1442695040888963407 :: Word64
+        boundary "INT32" int32 int32Bits prefix32 spread32 distinct
+        boundary "INT64" int64 int64Bits prefix64 spread64 distinct
+        boundary "FLOAT" float floatBits prefix32 spread32 distinct
+        boundary "DOUBLE" double doubleBits prefix64 spread64 distinct
+    )
+    [0, 1, 31, 32, 33, 63, 64, 65, 127, 128, 129, 257]
+
+
+-- Use independent list bounds, including prefixes whose padded word keys
+-- are equal. The allocation cap catches a boxed accumulator per input row.
+statisticsTraversalRegression :: IO ()
+statisticsTraversalRegression = do
+  let expected encode legacy values =
+        let low = if null values then Nothing else Just (encode (minimum values))
+            high = if null values then Nothing else Just (encode (maximum values))
+            exact = if null values then Nothing else Just True
+        in Statistics
+             { statMin = if legacy then low else Nothing
+             , statMax = if legacy then high else Nothing
+             , statNullCount = Just 0
+             , statDistinctCount = Nothing
+             , statMinValue = low
+             , statMaxValue = high
+             , statMinValueExact = exact
+             , statMaxValueExact = exact
+             , statNanCount = Nothing
+             }
+      enc32 value = Lazy.toStrict (Builder.toLazyByteString (Builder.int32LE value))
+      enc64 value = Lazy.toStrict (Builder.toLazyByteString (Builder.int64LE value))
+      check32 values =
+        mapM_
+          ( \offset -> do
+              let source = P.slice offset (length values) (P.replicate offset 17 P.++ P.fromList values P.++ P.singleton 23)
+              check "INT32 one-pass statistics preserve signed bounds, empty vectors and slices" $
+                Write.columnDataStatistics (Write.ColInt32 source) == expected enc32 True values
+          )
+          [0, 1, 3, 7]
+      check64 values =
+        mapM_
+          ( \offset -> do
+              let source = P.slice offset (length values) (P.replicate offset 17 P.++ P.fromList values P.++ P.singleton 23)
+              check "INT64 one-pass statistics preserve signed bounds, empty vectors and slices" $
+                Write.columnDataStatistics (Write.ColInt64 source) == expected enc64 True values
+          )
+          [0, 1, 3, 7]
+      checkBytes values =
+        mapM_
+          ( \prefix -> do
+              let sliced ordinal value =
+                    let marker = fromIntegral ordinal
+                    in BS.take (BS.length value) (BS.drop prefix (BS.replicate prefix marker <> value <> BS.singleton marker))
+                  source = V.fromList (zipWith sliced [0 :: Int ..] values)
+                  actual = Write.columnDataStatistics (Write.ColByteArray source)
+                  reference = expected id False values
+              unless (actual == reference) $
+                error ("byte statistics mismatch at slice offset " ++ show prefix ++ ": " ++ show values ++ "; actual " ++ show actual ++ "; expected " ++ show reference)
+              check "byte statistics preserve unsigned order, NUL padding and unaligned logical slices" (actual == reference)
+          )
+          [0 .. 7]
+      short = concatMap (\size -> [BS.replicate size 0, BS.replicate size 255, BS.pack (take size [0 .. 7])]) [0 .. 8]
+      prefixZeros = map (`BS.replicate` 0) [0 .. 128]
+  mapM_ check32 [[], [minBound], [maxBound, 0, minBound, -1, 1, maxBound], reverse [minBound, -1, 0, 1, maxBound]]
+  mapM_ check64 [[], [minBound], [maxBound, 0, minBound, -1, 1, maxBound], reverse [minBound, -1, 0, 1, maxBound]]
+  mapM_ checkBytes [[], [BS.empty], short, reverse short, prefixZeros, reverse prefixZeros]
+  mapM_
+    ( \prefixCount -> do
+        let initial = take prefixCount (cycle ["name_0", "name_7", "name_19"])
+        checkBytes (initial ++ [BS.replicate 9 0] ++ ["m", "z"])
+        checkBytes (initial ++ [BS.replicate 9 255] ++ ["a", "m"])
+    )
+    [1, 7, 31, 32, 257]
+  passed32 <- H.check $ H.withTests 1000 $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 500) (Gen.int32 Range.constantBounded))
+    Write.columnDataStatistics (Write.ColInt32 (P.fromList values)) H.=== expected enc32 True values
+  check "INT32 statistics match an independent list oracle" passed32
+  passed64 <- H.check $ H.withTests 1000 $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 500) (Gen.int64 Range.constantBounded))
+    Write.columnDataStatistics (Write.ColInt64 (P.fromList values)) H.=== expected enc64 True values
+  check "INT64 statistics match an independent list oracle" passed64
+  passedBytes <- H.check $ H.withTests 1000 $ H.property $ do
+    values <- H.forAll (Gen.list (Range.linear 0 150) (Gen.bytes (Range.linear 0 256)))
+    Write.columnDataStatistics (Write.ColByteArray (V.fromList values)) H.=== expected id False values
+  check "binary statistics match an independent list oracle" passedBytes
+  let count = 32768
+      measure label source = do
+        _ <- evaluate (Write.columnDataLength source)
+        case source of
+          Write.ColByteArray values -> evaluate (V.foldl' (\n value -> n + BS.length value) 0 values) >> pure ()
+          _ -> pure ()
+        before <- getAllocationCounter
+        stats <- evaluate (Write.columnDataStatistics source)
+        let checksum bytes = BS.foldl' (\acc byte -> acc + fromIntegral byte) (0 :: Word64) bytes
+        _ <- evaluate (maybe 0 checksum (statMinValue stats) + maybe 0 checksum (statMaxValue stats))
+        after <- getAllocationCounter
+        check (label ++ " statistics avoid per-row accumulator allocation: " ++ show (before - after)) (before - after < 32768)
+  measure "INT32" (Write.ColInt32 (P.generate count (\i -> fromIntegral i * 1664525 + 1013904223)))
+  measure "INT64" (Write.ColInt64 (P.generate count (\i -> fromIntegral i * 6364136223846793005 + 1442695040888963407)))
+  measure "ascending INT32" (Write.ColInt32 (P.generate count fromIntegral))
+  measure "descending INT32" (Write.ColInt32 (P.generate count (fromIntegral . negate)))
+  measure "ascending INT64" (Write.ColInt64 (P.generate count fromIntegral))
+  measure "descending INT64" (Write.ColInt64 (P.generate count (fromIntegral . negate)))
+  measure "ascending FLOAT" (Write.ColFloat (P.generate count fromIntegral))
+  measure "descending FLOAT" (Write.ColFloat (P.generate count (fromIntegral . negate)))
+  measure "ascending DOUBLE" (Write.ColDouble (P.generate count fromIntegral))
+  measure "descending DOUBLE" (Write.ColDouble (P.generate count (fromIntegral . negate)))
+  measure "short bytes" (Write.ColByteArray (V.generate count (\i -> V.unsafeIndex (V.fromList short) (i `rem` length short))))
+  measure "long common-prefix bytes" (Write.ColByteArray (V.generate count (\i -> BS.replicate 32 97 <> BS.singleton (fromIntegral (i `rem` 8)))))
+
+
+-- Adjacent middle words need the block mode; another difference outside
+-- that block needs full keys. Both modes must preserve owners and ids
+-- while growing and retrying rows of later, unrelated lengths.
+dictionaryRefinementGrowthRegression :: IO ()
+dictionaryRefinementGrowthRegression = do
+  let original = BS.replicate 64 97
+      firstMiddle = BS.replicate 16 97 <> BS.singleton 98 <> BS.replicate 47 97
+      secondMiddle = BS.replicate 24 97 <> BS.singleton 99 <> BS.replicate 39 97
+      outsideBlock = BS.replicate 40 97 <> BS.singleton 100 <> BS.replicate 23 97
+      -- Flipping bit 0 in word 2 and bit 40 in word 3 cancels after
+      -- their rotations by 17 and 41. The payloads are still distinct.
+      insideCollision = BS.replicate 16 97 <> BS.singleton 96 <> BS.replicate 12 97 <> BS.singleton 96 <> BS.replicate 34 97
+      shortValues = BS.empty : map (\size -> BS.replicate size (fromIntegral size)) [1 .. 8]
+      widths = V.fromList [9, 10, 11, 12, 13, 14, 15, 16, 17, 31, 32, 33, 63, 64, 65, 127, 128, 129, 255, 256, 257, 4096]
+      payload key =
+        let width = V.unsafeIndex widths (key `rem` V.length widths)
+        in Lazy.toStrict (Builder.toLazyByteString (Builder.word64LE (fromIntegral key))) <> BS.replicate (width - 8) 0xa5
+      lateShort = BS.singleton 255
+      lateWide = BS.replicate 4097 0x5a
+  mapM_
+    ( \full -> do
+        let promotion = [original, firstMiddle, secondMiddle] ++ if full then [outsideBlock] else []
+            initial = promotion ++ replicate (32 - length promotion) original
+            known = length promotion + length shortValues
+        mapM_
+          ( \uniqueCount -> do
+              let payloads = map payload [0 .. uniqueCount - known - 1]
+                  values = initial ++ shortValues ++ payloads ++ [lateShort, lateWide, insideCollision, outsideBlock] ++ reverse payloads ++ reverse shortValues ++ promotion ++ [lateWide, lateShort, insideCollision, outsideBlock]
+                  reference = dictionaryModel (Write.ColByteArray . V.fromList) values
+              mapM_
+                ( \prefix -> do
+                    let sliced ordinal value =
+                          let marker = fromIntegral ordinal
+                          in BS.take (BS.length value) (BS.drop prefix (BS.replicate prefix marker <> value <> BS.singleton marker))
+                        source = V.fromList (zipWith sliced [0 :: Int ..] values)
+                    check ("refined dictionary growth preserves mixed-width owners and retry ids at " ++ show uniqueCount ++ " entries, alignment " ++ show prefix ++ ", full mode " ++ show full) $
+                      Write.buildDictionary (Write.ColByteArray source) == reference
+                )
+                [0 .. 7]
+          )
+          [31, 32, 33, 63, 64, 65, 127, 128, 129, 255, 256, 257, 1024, 1025]
+    )
+    [False, True]
+
+  mapM_
+    ( \width -> do
+        let count = 32768
+            word key = Lazy.toStrict (Builder.toLazyByteString (Builder.word64LE (fromIntegral key)))
+        source <- V.generateM count $ \i ->
+          let (high, low) = (i `rem` 8) `quotRem` 4
+              size = if i < 32 then 64 else width
+              value = BS.replicate 16 97 <> word low <> word high <> BS.replicate (size - 32) 97
+          in BS.useAsCStringLen value BS.packCStringLen
+        _ <- evaluate (V.foldl' (\total value -> total + BS.length value) 0 source)
+        before <- getAllocationCounter
+        dictionary <- evaluate (Write.buildDictionary (Write.ColByteArray source))
+        after <- getAllocationCounter
+        check ("common-prefix byte dictionary scan retains bounded allocation at " ++ show width ++ " bytes: " ++ show (before - after)) $
+          before - after < fromIntegral (count * 6 + 32768)
+            && Write.columnDataLength (Write.dictUniques dictionary) == (if width == 64 then 8 else 16)
+            && P.length (Write.dictIndices dictionary) == count
+    )
+    [64, 128, 256]
+
+
+legacyChunkAccumulationRegression :: IO ()
+legacyChunkAccumulationRegression = do
+  let plain column =
+        let (header, body) = Write.encodeColumnDataPageParts column
+        in header <> body
+      rawPage encoding count body =
+        let size = fromIntegral (BS.length body)
+        in Write.encodePageHeader (Page.PageHeader (Page.PtDataPage (Page.DataPageHeader (fromIntegral count) encoding)) (Just size) (Just size)) <> body
+      rawBytes column = case column of
+        Write.ColByteArray values -> rawPage 0 (V.length values) (Lazy.toStrict (Builder.toLazyByteString (foldMap Builder.byteString values)))
+        _ -> error "legacy raw-byte fixture expects byte arrays"
+      bytes width first count = Write.ColByteArray $ V.generate count $ \row ->
+        BS.take width (Lazy.toStrict (Builder.toLazyByteString (Builder.word64LE (fromIntegral (first + row)) <> Builder.word64LE 0xff00ff00)))
+      binaryValue ordinal = BS.take (ordinal `rem` 9) (Lazy.toStrict (Builder.toLazyByteString (Builder.word64LE (fromIntegral ordinal))))
+      optionalValues :: Int -> Int -> (Int -> a) -> V.Vector (Maybe a)
+      optionalValues first count valueAt = V.generate count $ \row ->
+        let ordinal = first + row
+        in if ordinal `rem` 3 == 0 then Nothing else Just (valueAt ordinal)
+      sliced prefix chunk = BS.take (BS.length chunk) (BS.drop prefix (BS.replicate prefix 0xe3 <> chunk <> BS.singleton 0x77))
+  mapM_
+    ( \pageCount ->
+        mapM_
+          ( \pageRows -> do
+              let total = pageCount * pageRows
+                  firstRows = map (* pageRows) [0 .. pageCount - 1]
+                  required name make decode encode = do
+                    let pages = map (encode . (\first -> make first pageRows)) firstRows
+                        chunk = BS.concat (encode (make 0 0) : pages ++ [encode (make total 0)])
+                        expected = Right (make 0 total)
+                    mapM_
+                      (\prefix -> check (name ++ " legacy pages preserve order/empty pages/slices at " ++ show pageCount ++ "x" ++ show pageRows ++ "/" ++ show prefix) (decode (sliced prefix chunk) == expected))
+                      [0, 1, 3, 7]
+                  optional name make decode = do
+                    let pages = map (Write.encodeOptionalColumnPage . (\first -> make first pageRows)) firstRows
+                        chunk = BS.concat (Write.encodeOptionalColumnPage (make 0 0) : pages ++ [Write.encodeOptionalColumnPage (make total 0)])
+                        expected = Right (make 0 total)
+                    mapM_
+                      (\prefix -> check (name ++ " legacy optional pages preserve nulls/order/slices at " ++ show pageCount ++ "x" ++ show pageRows ++ "/" ++ show prefix) (decode (sliced prefix chunk) == expected))
+                      [0, 1, 3, 7]
+              required "INT32" (\first count -> Write.ColInt32 (P.generate count (\row -> fromIntegral (first + row) - 20000))) (fmap Write.ColInt32 . Read.readPlainInt32ColumnChunk Uncompressed) plain
+              required "INT64" (\first count -> Write.ColInt64 (P.generate count (\row -> fromIntegral (first + row) * 1000000007 - 9000000000))) (fmap Write.ColInt64 . Read.readPlainInt64ColumnChunk Uncompressed) plain
+              required "FLOAT" (\first count -> Write.ColFloat (P.generate count (\row -> fromIntegral (first + row) * 0.25 - 100))) (fmap Write.ColFloat . Read.readPlainFloatColumnChunk Uncompressed) plain
+              required "DOUBLE" (\first count -> Write.ColDouble (P.generate count (\row -> fromIntegral (first + row) * (-0.125) - 100))) (fmap Write.ColDouble . Read.readPlainDoubleColumnChunk Uncompressed) plain
+              required "BOOL" (\first count -> Write.ColBool (V.generate count (odd . (first +)))) (fmap Write.ColBool . Read.readPlainBoolColumnChunk Uncompressed) plain
+              required "BYTE_ARRAY" (\first count -> Write.ColByteArray (V.generate count (binaryValue . (first +)))) (fmap Write.ColByteArray . Read.readPlainByteArrayColumnChunk Uncompressed) plain
+              required "INT96" (bytes 12) (fmap Write.ColByteArray . Read.readPlainInt96ColumnChunk Uncompressed) rawBytes
+              required "FIXED_LEN_BYTE_ARRAY" (bytes 3) (fmap Write.ColByteArray . Read.readPlainFixedLenByteArrayColumnChunk 3 Uncompressed) rawBytes
+              optional "INT32" (\first count -> Write.OptInt32 (optionalValues first count (\value -> fromIntegral value - 10000))) (fmap Write.OptInt32 . Read.readPlainInt32OptionalColumnChunk Uncompressed 0 1)
+              optional "INT64" (\first count -> Write.OptInt64 (optionalValues first count (\value -> fromIntegral value * 1000000007))) (fmap Write.OptInt64 . Read.readPlainInt64OptionalColumnChunk Uncompressed 0 1)
+              optional "FLOAT" (\first count -> Write.OptFloat (optionalValues first count (\value -> fromIntegral value * 0.25))) (fmap Write.OptFloat . Read.readPlainFloatOptionalColumnChunk Uncompressed 0 1)
+              optional "DOUBLE" (\first count -> Write.OptDouble (optionalValues first count (\value -> fromIntegral value * (-0.125)))) (fmap Write.OptDouble . Read.readPlainDoubleOptionalColumnChunk Uncompressed 0 1)
+              optional "BOOL" (\first count -> Write.OptBool (optionalValues first count odd)) (fmap Write.OptBool . Read.readPlainBoolOptionalColumnChunk Uncompressed 0 1)
+              optional "BYTE_ARRAY" (\first count -> Write.OptByteArray (optionalValues first count binaryValue)) (fmap Write.OptByteArray . Read.readPlainByteArrayOptionalColumnChunk Uncompressed 0 1)
+          )
+          [0, 1, 7, 8, 9, 33]
+    )
+    [0, 1, 2, 7, 33]
+
+  let uniques = Write.ColInt32 (P.fromList [10, 11, 12, 13])
+      dict = Write.Dictionary uniques P.empty
+      dictionary = Write.encodeDictPage dict
+      dictionaryPage first count = Write.encodeDictDataPage (Write.Dictionary uniques (P.generate count (\row -> fromIntegral ((first + row) `rem` 4))))
+      emptyData = dictionaryPage 0 0
+      nullablePage first count =
+        let values = optionalValues first count (\ordinal -> 10 + fromIntegral (ordinal `rem` 4) :: Int32)
+            definitions = P.generate count (\row -> case V.unsafeIndex values row of Nothing -> 0; Just _ -> 1)
+            indices = P.fromList (foldMap (maybe [] (\value -> [value - 10])) values)
+            encoded = Write.encodeDictDataPage (Write.Dictionary uniques indices)
+            (_, _, body, _) = either error id (Read.decompressDataPageBody Uncompressed encoded 0)
+        in rawPage 8 count (Levels.encodeLengthPrefixedHybrid 1 definitions <> body)
+  mapM_
+    ( \pageCount -> do
+        let pageRows = 9
+            count = pageCount * pageRows
+            starts = map (* pageRows) [0 .. pageCount - 1]
+            chunk = dictionary <> emptyData <> BS.concat (map (`dictionaryPage` pageRows) starts) <> emptyData
+            expected = P.generate count (\row -> 10 + fromIntegral (row `rem` 4))
+            optionalChunk = dictionary <> nullablePage 0 0 <> BS.concat (map (`nullablePage` pageRows) starts) <> nullablePage count 0
+            optionalExpected = optionalValues 0 count (\ordinal -> 10 + fromIntegral (ordinal `rem` 4) :: Int32)
+            fallback first = plain (Write.ColInt32 (P.generate pageRows (\row -> fromIntegral (first + row))))
+            mixedChunk = dictionary <> BS.concat (concatMap (\first -> [dictionaryPage first pageRows, fallback first]) starts)
+            mixedExpected = P.concat (map (\first -> P.generate (pageRows * 2) (\row -> if row < pageRows then 10 + fromIntegral ((first + row) `rem` 4) else fromIntegral (first + row - pageRows))) starts)
+        mapM_
+          ( \prefix -> do
+              let source = sliced prefix chunk
+              check "legacy dictionary reader retains its empty-column rejection" $
+                if count == 0 then isLeft (Read.readPlainDictionaryInt32ColumnChunk Uncompressed source) else Read.readPlainDictionaryInt32ColumnChunk Uncompressed source == Right expected
+              check "legacy dictionary optional pages preserve empty pages, nulls and order" $
+                Read.readDictionaryInt32OptionalColumnChunk Uncompressed 0 1 (sliced prefix optionalChunk) == Right optionalExpected
+              check "legacy dictionary/plain fallback pages preserve order" $
+                if count == 0 then isLeft (Read.readPlainDictionaryInt32ColumnChunk Uncompressed (sliced prefix mixedChunk)) else Read.readPlainDictionaryInt32ColumnChunk Uncompressed (sliced prefix mixedChunk) == Right mixedExpected
+          )
+          [0, 1, 3, 7]
+    )
+    [0, 1, 2, 7, 33]
+
+  -- A copied source prevents a cached pure decode from satisfying this guard.
+  -- The old growing-vector append allocates 138/277 MB on these inputs.
+  let pages = 1024
+      pageRows = 64
+      rows = pages * pageRows
+      starts = map (* pageRows) [0 .. pages - 1]
+      ints first = P.generate pageRows (\row -> fromIntegral (first + row) - 20000 :: Int32)
+      booleans first = optionalValues first pageRows odd
+      intInput = BS.concat (map (plain . Write.ColInt32 . ints) starts)
+      boolInput = BS.concat (map (Write.encodeOptionalColumnPage . Write.OptBool . booleans) starts)
+  intSource <- BS.useAsCStringLen intInput BS.packCStringLen
+  _ <- evaluate (BS.length intSource)
+  performGC
+  beforeInts <- getAllocationCounter
+  actualInts <- evaluate (Read.readPlainInt32ColumnChunk Uncompressed intSource)
+  intRows <- evaluate (either error P.length actualInts)
+  afterInts <- getAllocationCounter
+  check ("legacy INT32 page accumulation has linear allocation: " ++ show (beforeInts - afterInts)) $
+    beforeInts - afterInts < fromIntegral (rows * 128 + 65536)
+  check "legacy INT32 large-page model" $
+    intRows == rows && actualInts == Right (P.generate rows (\row -> fromIntegral row - 20000))
+  boolSource <- BS.useAsCStringLen boolInput BS.packCStringLen
+  _ <- evaluate (BS.length boolSource)
+  performGC
+  beforeBools <- getAllocationCounter
+  actualBools <- evaluate (Read.readPlainBoolOptionalColumnChunk Uncompressed 0 1 boolSource)
+  boolRows <- evaluate (either error V.length actualBools)
+  afterBools <- getAllocationCounter
+  check ("legacy optional BOOL page accumulation has linear allocation: " ++ show (beforeBools - afterBools)) $
+    beforeBools - afterBools < fromIntegral (rows * 256 + 65536)
+  check "legacy optional BOOL large-page model" $
+    boolRows == rows && actualBools == Right (optionalValues 0 rows odd)
+
+
+packedBoolRegression :: IO ()
+packedBoolRegression = do
+  let dictionaryValues = V.fromList [False, True, False, True, False, True, False, True, False]
+      dictionary = Write.encodeDictPage (Write.Dictionary (Write.ColBool dictionaryValues) P.empty)
+      plainBits values = snd (Write.encodeColumnDataPageParts (Write.ColBool values))
+      boolPage v2 encoding nullable values =
+        let defs = P.generate (V.length values) (\i -> case V.unsafeIndex values i of Nothing -> 0; Just _ -> 1)
+            dense = V.mapMaybe id values
+            payload0
+              | encoding == 3 = Levels.encodeLengthPrefixedHybrid 1 (P.fromList (foldMap (\b -> [if b then 1 else 0]) dense))
+              | encoding == 8 || encoding == 2 =
+                  let ix = P.generate (V.length dense) (\i -> if V.unsafeIndex dense i then 1 else if odd i then 0 else 8)
+                      encoded = Write.encodeDictDataPage (Write.Dictionary (Write.ColBool dictionaryValues) ix)
+                      (_, _, body, _) = either error id (Read.decompressDataPageBody Uncompressed encoded 0)
+                  in body
+              | otherwise = plainBits dense
+            -- Padding is deliberately nonzero, and must never leak into the
+            -- next page when its preceding value count is not byte-aligned.
+            payload =
+              if encoding == 0 && not (BS.null payload0) && V.length dense `rem` 8 /= 0
+                then BS.init payload0 <> BS.singleton (BS.last payload0 .|. (255 `shiftL` (V.length dense `rem` 8)))
+                else payload0
+            levels = if nullable then (if v2 then Levels.encodeRLEHybrid else Levels.encodeLengthPrefixedHybrid) 1 defs else BS.empty
+            body = levels <> payload
+            count = V.length values
+            nulls = count - V.length dense
+            header =
+              if v2
+                then Page.PtDataPageV2 (Page.DataPageHeaderV2 (fromIntegral count) (fromIntegral nulls) (fromIntegral count) encoding (fromIntegral (BS.length levels)) 0 False)
+                else Page.PtDataPage (Page.DataPageHeader (fromIntegral count) encoding)
+            stats = (Write.columnDataStatistics (Write.ColBool dense)) {statNullCount = Just (fromIntegral nulls)}
+        in TestPage (Write.encodePageHeader (Page.PageHeader header (Just (fromIntegral (BS.length body))) (Just (fromIntegral (BS.length body)))) <> body) count stats
+      makeFile nullable encoding pages =
+        let schema = V.fromList [root, SchemaElement "x" (Just (if nullable then Optional else Required)) (Just PTBoolean) Nothing Nothing Nothing Nothing Nothing]
+            fixture = indexed schema (V.singleton "x") pages (if encoding == 8 || encoding == 2 then Just dictionary else Nothing)
+            old = fixtureFile fixture
+            update cm = cm {cmEncodings = V.fromList [Plain, RLE, RLEDictionary]}
+            changed = mapChunk (\cc -> cc {ccMetadata = update <$> ccMetadata cc}) old
+            bytes = BS.take (fixtureFooterStart fixture) (Read.pfBytes changed) <> Footer.writeFooter (Read.pfFooter changed)
+        in (fixture {fixtureFile = either error id (Read.loadParquetFile bytes)})
+      fromBits buffers = do
+        bits <- A.mkBitmap (Read.boolData buffers) 0 (Read.boolCount buffers)
+        A.mkBool Nothing bits
+      sourceValue i = odd (i `quot` 3 + i `quot` 11)
+      values nullable start n = V.generate n (\i -> if nullable && (start + i) `rem` 5 == 0 then Nothing else Just (sourceValue (start + i)))
+      verify v2 encoding nullable chunks = do
+        let pages = V.map (boolPage v2 encoding nullable) chunks
+            fixture = makeFile nullable encoding pages
+            file = fixtureFile fixture
+            expectedValues = V.concat (V.toList chunks)
+            expected = A.fromMaybeBools expectedValues
+            target = field T.ABool nullable
+            dense = A.fromBools (V.mapMaybe id expectedValues)
+            chunk = either error id (Read.columnChunkSlice file 0 0)
+            context = "BOOLEAN packed encoding " ++ show encoding ++ ", V2 " ++ show v2 ++ ", nullable " ++ show nullable
+        check (context ++ " Arrow roundtrip, rows " ++ show (map V.length (V.toList chunks))) (Arrow.readParquetColumn file 0 0 target == Right expected)
+        check (context ++ " legacy generic reader") $
+          if nullable
+            then Read.readGenericBoolOptionalColumnChunk Uncompressed 0 1 chunk == Right expectedValues
+            else Read.readGenericBoolColumnChunk Uncompressed chunk == Right (V.mapMaybe id expectedValues)
+        if nullable
+          then do
+            levels <- either fail pure (Read.readBoolBuffersLevels Uncompressed 0 1 chunk)
+            check (context ++ " dense packed defined values") (fromBits (Read.clValues levels) == Right dense)
+          else check (context ++ " packed required values") ((Read.readBoolBuffersColumnChunk Uncompressed chunk >>= fromBits) == Right dense)
+        when (V.all ((> 0) . V.length) chunks) $ do
+          selected <- either fail pure (Arrow.readParquetColumnWithPagePruning file 0 0 target (Pred.PIn [Pred.PVBool False, Pred.PVBool True]))
+          check (context ++ " indexed Arrow path") (snd selected == A.fromMaybeBools (V.concat (V.toList (V.filter (V.any (/= Nothing)) chunks))))
+          let keep = V.generate (V.length chunks) even
+              selection = Read.PageSelection (fixtureLocations fixture) keep (if encoding == 8 || encoding == 2 then Just 4 else Nothing) (Just (fromIntegral (V.length expectedValues)))
+              retained = V.concat (V.toList (V.ifilter (\i _ -> even i) chunks))
+              retainedDense = A.fromBools (V.mapMaybe id retained)
+          if nullable
+            then do
+              result <- either fail pure (Read.readBoolBuffersSelectedLevels Uncompressed 0 1 (Read.pfBytes file) selection)
+              check (context ++ " partial selected packed values") (fromBits (Read.clValues result) == Right retainedDense && P.length (Read.clDefinition result) == V.length retained)
+            else check (context ++ " partial selected required values") ((Read.readBoolBuffersSelectedValues Uncompressed (Read.pfBytes file) selection >>= fromBits) == Right retainedDense)
+  mapM_
+    ( \v2 ->
+        mapM_
+          ( \encoding ->
+              mapM_
+                ( \nullable ->
+                    mapM_
+                      (\n -> verify v2 encoding nullable (V.fromList [values nullable 0 n, values nullable n (n + 1), values nullable (2 * n + 1) 2]))
+                      [0, 1, 2, 7, 8, 9, 17, 65]
+                )
+                [False, True]
+          )
+          [0, 3, 8, 2]
+    )
+    [False, True]
+  passed <- H.check $ H.withTests 300 $ H.property $ do
+    v2 <- H.forAll Gen.bool
+    encoding <- H.forAll (Gen.element [0, 3, 8, 2])
+    chunks <- H.forAll (Gen.list (Range.linear 1 12) (Gen.list (Range.linear 0 90) (Gen.maybe Gen.bool)))
+    H.evalIO (verify v2 encoding True (V.fromList (map V.fromList chunks)))
+  check "packed BOOLEAN pages match independent nullable models" passed
+
+  let rawPage n encoding body =
+        Write.encodePageHeader (Page.PageHeader (Page.PtDataPage (Page.DataPageHeader n encoding)) (Just (fromIntegral (BS.length body))) (Just (fromIntegral (BS.length body)))) <> body
+      framed body = Lazy.toStrict (Builder.toLazyByteString (Builder.word32LE (fromIntegral (BS.length body)))) <> body
+  mapM_
+    (\body -> check "packed BOOLEAN RLE rejects malformed runs before allocating output" (isLeft (Read.readBoolBuffersColumnChunk Uncompressed (rawPage 1 3 body))))
+    [BS.empty, framed BS.empty, framed (BS.singleton 0), framed (BS.singleton 128), framed (BS.singleton 2), framed (BS.singleton 3), BS.pack [255, 255, 255, 255], framed (BS.replicate 10 255)]
+  mapM_
+    ( \dictionaryByte -> do
+        let literalHeader = Page.PageHeader (Page.PtDictionaryPage (Page.DictionaryPageHeader 2 0)) (Just 1) (Just 1)
+            literalDictionary = Write.encodePageHeader literalHeader <> BS.singleton dictionaryByte
+            literalData = rawPage 4 8 (BS.pack [1, 3, 6])
+            expected = if dictionaryByte == 2 then V.fromList [False, True, True, False] else V.fromList [True, False, False, True]
+        check "BOOLEAN dictionary matches literal LSB-first/index golden" $
+          Read.readGenericBoolColumnChunk Uncompressed (literalDictionary <> literalData) == Right expected
+    )
+    [2, 1]
+  let smallDict = Write.encodeDictPage (Write.Dictionary (Write.ColBool (V.fromList [False, True])) P.empty)
+      invalid = smallDict <> rawPage 1 8 (BS.pack [2, 2, 3])
+  check "packed BOOLEAN dictionary validates every index" (isLeft (Read.readBoolBuffersColumnChunk Uncompressed invalid))
+  check "legacy BOOLEAN dictionary validates every index" (isLeft (Read.readGenericBoolColumnChunk Uncompressed invalid))
+  check "packed BOOLEAN dictionary requires a preceding dictionary" (isLeft (Read.readBoolBuffersColumnChunk Uncompressed (rawPage 1 8 (BS.pack [0]))))
+  check "packed BOOLEAN rejects duplicate dictionaries" (isLeft (Read.readBoolBuffersColumnChunk Uncompressed (smallDict <> smallDict)))
+  check "packed BOOLEAN rejects a late dictionary" (isLeft (Read.readBoolBuffersColumnChunk Uncompressed (rawPage 1 0 (BS.singleton 1) <> smallDict)))
+
+  -- Fresh input makes these guards measure a real decode rather than a CAF.
+  mapM_
+    ( \nullable -> do
+        let pageCount = 257
+            rows = 1025
+            count = pageCount * rows
+            chunks = V.generate pageCount (\i -> values nullable (i * rows) rows)
+            file = fixtureFile (makeFile nullable 0 (V.map (boolPage True 0 nullable) chunks))
+        bytes <- BS.useAsCStringLen (Read.pfBytes file) BS.packCStringLen
+        parsed <- either fail pure (Read.loadParquetFile bytes)
+        performGC
+        before <- getAllocationCounter
+        result <- either fail pure =<< evaluate (Arrow.readParquetColumn parsed 0 0 (field T.ABool nullable))
+        actualCount <- evaluate (A.columnLength result)
+        after <- getAllocationCounter
+        check ("BOOLEAN buffer path avoids boxed rows, nullable " ++ show nullable ++ ": " ++ show (before - after)) $
+          before - after < fromIntegral (count * (if nullable then 20 else 4) + 524288)
+        check "large packed BOOLEAN roundtrip" (actualCount == count && result == A.fromMaybeBools (values nullable 0 count))
+    )
+    [False, True]
+
+
+-- Independent byte-lane models preserve every IEEE bit, including NaN
+-- payloads and signed zero. Slices cross both the SIMD tail and bounded
+-- unsafe / pinned-safe call transitions.
+byteStreamSplitRegression :: IO ()
+byteStreamSplitRegression = do
+  let counts = [0 .. 129] ++ [255, 256, 257, 1023, 1024, 1025, 8191, 8192, 8193, 16383, 16384, 16385, 65535, 65536, 65537]
+  mapM_
+    (\n -> mapM_ (\offset -> mapM_ (\mis -> bssCheck32 n offset mis >> bssCheck64 n offset mis) [0, 1, 7]) [0, 1, 3, 7])
+    counts
+  check "3480 BYTE_STREAM_SPLIT slice/IEEE/truncation models" True
+  mapM_
+    ( \n -> do
+        check "BYTE_STREAM_SPLIT FLOAT rejects invalid counts" (isLeft (Read.decodeByteStreamSplitFloat n BS.empty))
+        check "BYTE_STREAM_SPLIT DOUBLE rejects invalid counts" (isLeft (Read.decodeByteStreamSplitDouble n BS.empty))
+    )
+    [-1, minBound, maxBound]
+  passed <- H.check $ H.withTests 300 $ H.property $ do
+    words32 <- H.forAll (Gen.list (Range.linear 0 257) (Gen.word32 Range.constantBounded))
+    words64 <- H.forAll (Gen.list (Range.linear 0 257) (Gen.word64 Range.constantBounded))
+    let n32 = length words32
+        n64 = length words64
+        model32 = bssModel32 words32
+        model64 = bssModel64 words64
+        source32 = P.map castWord32ToFloat (P.fromList words32)
+        source64 = P.map castWord64ToDouble (P.fromList words64)
+    ByteStreamSplit.encodeByteStreamSplitFloat source32 H.=== model32
+    ByteStreamSplit.encodeByteStreamSplitDouble source64 H.=== model64
+    fmap (P.map castFloatToWord32) (Read.decodeByteStreamSplitFloat n32 model32) H.=== Right (P.fromList words32)
+    fmap (P.map castDoubleToWord64) (Read.decodeByteStreamSplitDouble n64 model64) H.=== Right (P.fromList words64)
+  check "BYTE_STREAM_SPLIT arbitrary IEEE bits match independent models" passed
+  done <- newEmptyMVar
+  _ <- forkIO (replicateM_ 100 performGC `finally` putMVar done ())
+  replicateM_ 20 (bssCheck32 65537 3 1 >> bssCheck64 65537 7 7)
+  takeMVar done
+  check "BYTE_STREAM_SPLIT pinned owners survive concurrent GC" True
+
+
+bssCheck32 :: Int -> Int -> Int -> IO ()
+bssCheck32 n offset mis = do
+  let bitPatterns = map (bssWord32At . (+ offset)) [0 .. n - 1]
+      values = P.slice offset n (P.generate (n + offset + 1) (castWord32ToFloat . bssWord32At))
+      golden = bssModel32 bitPatterns
+      input = BS.drop mis (BS.replicate mis 0xa5 <> golden)
+  unless (ByteStreamSplit.encodeByteStreamSplitFloat values == golden) (fail "BYTE_STREAM_SPLIT sliced FLOAT bytes differ")
+  unless (fmap (P.map castFloatToWord32) (Read.decodeByteStreamSplitFloat n input) == Right (P.fromList bitPatterns)) (fail "BYTE_STREAM_SPLIT FLOAT IEEE bits differ")
+  when (n > 0) $
+    unless (isLeft (Read.decodeByteStreamSplitFloat n (BS.take (BS.length input - 1) input))) (fail "BYTE_STREAM_SPLIT FLOAT accepted short input")
+
+
+bssCheck64 :: Int -> Int -> Int -> IO ()
+bssCheck64 n offset mis = do
+  let bitPatterns = map (bssWord64At . (+ offset)) [0 .. n - 1]
+      values = P.slice offset n (P.generate (n + offset + 1) (castWord64ToDouble . bssWord64At))
+      golden = bssModel64 bitPatterns
+      input = BS.drop mis (BS.replicate mis 0xa5 <> golden)
+  unless (ByteStreamSplit.encodeByteStreamSplitDouble values == golden) (fail "BYTE_STREAM_SPLIT sliced DOUBLE bytes differ")
+  unless (fmap (P.map castDoubleToWord64) (Read.decodeByteStreamSplitDouble n input) == Right (P.fromList bitPatterns)) (fail "BYTE_STREAM_SPLIT DOUBLE IEEE bits differ")
+  when (n > 0) $
+    unless (isLeft (Read.decodeByteStreamSplitDouble n (BS.take (BS.length input - 1) input))) (fail "BYTE_STREAM_SPLIT DOUBLE accepted short input")
+
+
+bssModel32 :: [Word32] -> ByteString
+bssModel32 bitPatterns = BS.pack (concatMap (\lane -> map (\word -> fromIntegral (word `shiftR` (lane * 8))) bitPatterns) [0 .. 3])
+
+
+bssModel64 :: [Word64] -> ByteString
+bssModel64 bitPatterns = BS.pack (concatMap (\lane -> map (\word -> fromIntegral (word `shiftR` (lane * 8))) bitPatterns) [0 .. 7])
+
+
+bssWord32At :: Int -> Word32
+bssWord32At i = case i of
+  0 -> 0
+  1 -> 0x80000000
+  2 -> 0x7f800000
+  3 -> 0xff800000
+  4 -> 0x7fc12345
+  5 -> 0x7f812345
+  6 -> 1
+  7 -> 0x7f7fffff
+  _ -> fromIntegral i * 1664525 + 1013904223
+
+
+bssWord64At :: Int -> Word64
+bssWord64At i = case i of
+  0 -> 0
+  1 -> 0x8000000000000000
+  2 -> 0x7ff0000000000000
+  3 -> 0xfff0000000000000
+  4 -> 0x7ff8123456789abc
+  5 -> 0x7ff0123456789abc
+  6 -> 1
+  7 -> 0x7fefffffffffffff
+  _ -> fromIntegral i * 6364136223846793005 + 1442695040888963407
diff --git a/test/TimestampRegression.hs b/test/TimestampRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/TimestampRegression.hs
@@ -0,0 +1,162 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module TimestampRegression (tests) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.ByteString.Builder qualified as B
+import Data.ByteString.Lazy qualified as BL
+import Data.Either (isLeft)
+import Data.Int (Int32, Int64)
+import Data.Vector qualified as V
+import Data.Vector.Storable qualified as S
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Arrow qualified as Arrow
+import Parquet.Nested qualified as N
+import Parquet.Predicate qualified as Predicate
+import Parquet.Read qualified as Read
+import Parquet.Timestamp qualified as TS
+import Parquet.Types qualified as P
+import System.Directory (createDirectoryIfMissing)
+import System.Environment (lookupEnv)
+import System.FilePath ((</>))
+
+
+load :: Either String a -> IO a
+load = either fail pure
+
+
+check :: String -> Bool -> IO ()
+check label = flip unless (fail ("Timestamp regression: " ++ label))
+
+
+signed :: Integer -> IO BS.ByteString
+signed value = TS.encodeTimestamp96 <$> load (TS.timestamp96FromInteger value)
+
+
+julian :: Int32 -> Int64 -> BS.ByteString
+julian day nanos = BL.toStrict (B.toLazyByteString (B.int64LE nanos <> B.int32LE day))
+
+
+file :: N.LeafType -> V.Vector (Maybe BS.ByteString) -> IO BS.ByteString
+file kind values = load (N.buildNestedFile (V.singleton ("t", N.NSOptional (N.NSPrimitive kind))) (V.singleton (V.map (maybe N.NRNull (N.NRLeaf . N.LvFixedBinary)) values)))
+
+
+decodeFile :: BS.ByteString -> IO (Read.ParquetFile, A.Schema, C.ColumnArray)
+decodeFile bytes = do
+  input <- load (Read.loadParquetFile bytes)
+  schema <- load (Arrow.parquetFileArrowSchemaChecked input)
+  columns <- load (either (Left . show) Right (Arrow.parquetRowGroupToArrow schema input 0))
+  pure (input, schema, V.head columns)
+
+
+readTarget :: A.Schema -> Read.ParquetFile -> A.Field -> Either String C.ColumnArray
+readTarget schema input target = V.head <$> either (Left . show) Right (Arrow.parquetRowGroupToArrow (schema {A.arrowFields = V.singleton target}) input 0)
+
+
+counts :: C.ColumnArray -> Either String (V.Vector (Maybe Int64))
+counts (C.ColTimestamp validity values) = Right (V.generate (S.length values) (\i -> if C.isValidAt validity i then Just (values S.! i) else Nothing))
+counts _ = Left "expected Arrow timestamp column"
+
+
+tests :: IO ()
+tests = do
+  output <- lookupEnv "WIREFORM_PARQUET_PRIMITIVE_OUTPUT"
+  forM_ output (createDirectoryIfMissing True)
+  let save name bytes = forM_ output (\path -> BS.writeFile (path </> name) bytes)
+      unitCases = [(P.LtMillis, A.Millisecond, "millis"), (P.LtMicros, A.Microsecond, "micros"), (P.LtNanos, A.Nanosecond, "nanos")]
+      bounds = V.fromList [negate (2 ^ (95 :: Int)), negate (2 ^ (63 :: Int)) - 1, negate (2 ^ (63 :: Int)), -1, 0, 2 ^ (63 :: Int) - 1, 2 ^ (63 :: Int), 2 ^ (95 :: Int) - 1]
+  payloads <- V.mapM signed bounds
+  let rows = V.map Just payloads `V.snoc` Nothing
+  forM_ unitCases $ \(unit, arrowUnit, label) -> forM_ [False, True] $ \adjusted -> do
+    bytes <- file (N.LtTimestamp96 adjusted unit) rows
+    (input, schema, column) <- decodeFile bytes
+    let field = V.head (A.arrowFields schema)
+        target = field {A.fieldType = A.ATimestamp arrowUnit (if adjusted then Just "UTC" else Nothing), A.fieldMetadata = V.empty}
+    check "modern96 annotation and units inferred losslessly" (TS.timestampEncoding field == Right (Just (TS.SignedTimestamp96 adjusted unit)))
+    check "all96bits and nulls preserved" (V.generate (V.length rows) (C.anyBytesAt column) == rows)
+    check "wide count cannot silently narrow" (isLeft (readTarget schema input target))
+    let wrong = TS.timestampField "t" True (TS.SignedTimestamp96 (not adjusted) unit)
+    check "same physical bytes cannot be relabeled with different timestamp semantics" (isLeft (readTarget schema input wrong))
+    nestedSchema <- load (Arrow.arrowFieldToNestedSchema field)
+    lowered <- load (Arrow.columnArrayToNestedRows field column)
+    copy <- load (N.buildNestedFile (V.singleton ("t", nestedSchema)) (V.singleton lowered))
+    (_, copiedSchema, copied) <- decodeFile copy
+    check "Arrow lowering retains96bit storage and annotation" (A.arrowFields copiedSchema == A.arrowFields schema && V.generate (V.length rows) (C.anyBytesAt copied) == rows)
+    save ("timestamp96-" ++ label ++ (if adjusted then "-utc" else "-local") ++ ".parquet") bytes
+    small <- V.mapM (signed . toInteger) (V.fromList [minBound :: Int64, -1, 0, maxBound])
+    narrowBytes <- file (N.LtTimestamp96 adjusted unit) (V.map Just small `V.snoc` Nothing)
+    (narrowInput, narrowSchema, _) <- decodeFile narrowBytes
+    projected <- load (readTarget narrowSchema narrowInput target >>= counts)
+    check "exact signed64 boundaries project" (projected == V.fromList [Just minBound, Just (-1), Just 0, Just maxBound, Nothing])
+    (_, pruned) <- load (Arrow.readParquetColumnWithPagePruning narrowInput 0 0 target Predicate.PIsNotNull)
+    check "page pruning fallback shares checked conversion" (counts pruned == Right projected)
+  let julianValues = V.fromList [Just (julian minBound 0), Just (julian (-1) 86399999999999), Just (julian 2440588 0), Nothing, Just (julian maxBound 86399999999999), Just (julian 2440588 minBound), Just (julian 2440588 maxBound)]
+  legacy <- file N.LtInt96 julianValues
+  (legacyInput, legacySchema, legacyColumn) <- decodeFile legacy
+  check "legacy schema remains distinct from signed96" (TS.timestampEncoding (V.head (A.arrowFields legacySchema)) == Right (Just TS.JulianInt96))
+  check "full legacy day domain preserved" (V.generate (V.length julianValues) (C.anyBytesAt legacyColumn) == julianValues)
+  let nanoTarget = A.defaultField "t" True (A.ATimestamp A.Nanosecond Nothing) V.empty
+  check "legacy overflow cannot wrap" (isLeft (readTarget legacySchema legacyInput nanoTarget))
+  save "int96-full.parquet" legacy
+  forM_ [(A.Second, 1000000000), (A.Millisecond, 1000000), (A.Microsecond, 1000), (A.Nanosecond, 1)] $ \(unit, factor) -> do
+    let source = TS.timestampField "t" True TS.JulianInt96
+        target = A.defaultField "t" True (A.ATimestamp unit Nothing) V.empty
+        values = V.fromList [Just (julian 2440587 (86400000000000 - factor)), Nothing, Just (julian 2440588 factor)]
+    bytes <- file N.LtInt96 values
+    (input, schema, _) <- decodeFile bytes
+    converted <- load (readTarget schema input target >>= counts)
+    check "legacy exact negative and positive units" (converted == V.fromList [Just (-1), Nothing, Just 1])
+    poison <- load (C.fromMaybeFixedSizeBinary 12 (V.fromList [Just (julian 2440588 factor), Nothing]))
+    check "scalar column projection agrees" ((TS.projectTimestampColumn source target poison >>= counts) == Right (V.fromList [Just 1, Nothing]))
+    if factor == 1
+      then pure ()
+      else do
+        lossy <- load (C.fromMaybeFixedSizeBinary 12 (V.singleton (Just (julian 2440588 1))))
+        check "legacy projection rejects sub-unit loss" (isLeft (TS.projectTimestampColumn source target lossy))
+  forM_ [minBound, -1, 86400000000000, maxBound] $ \nanos -> do
+    let bytes = julian 2440588 nanos
+    check "legacy signed/non-normalized nanoseconds preserved" ((TS.timestamp96ToInteger <$> TS.decodeJulianInt96 bytes) == Right (toInteger nanos))
+    check "legacy non-normalized values remain writable" (not (isLeft (N.shred (N.NSPrimitive N.LtInt96) (V.singleton (N.NRLeaf (N.LvFixedBinary bytes))))))
+  check "scalar signed96 bounds checked" (isLeft (TS.timestamp96FromInteger (negate (2 ^ (95 :: Int)) - 1)) && isLeft (TS.timestamp96FromInteger (2 ^ (95 :: Int))))
+  check "scalar twelve-byte bounds checked" (all (isLeft . TS.decodeTimestamp96 . (`BS.replicate` 0)) [0, 11, 13])
+  let base = TS.timestampField "t" True (TS.SignedTimestamp96 False P.LtNanos)
+      malformed = [base {A.fieldType = A.ABinary}, base {A.fieldMetadata = A.fieldMetadata base `V.snoc` ("ARROW:extension:name", "other")}, base {A.fieldMetadata = V.fromList [("ARROW:extension:name", "wireform.parquet.timestamp96"), ("ARROW:extension:metadata", "bad")]}]
+  forM_ malformed (\field -> check "malformed extension rejected even for empty schema" (isLeft (Arrow.arrowFieldToNestedSchema field)))
+  -- Reachability matters: the required timestamp child below a null struct
+  -- can contain arbitrary bits; it must not trigger semantic validation.
+  let child = TS.timestampField "t" False TS.JulianInt96
+      parent = A.defaultField "s" True A.AStruct (V.singleton child)
+  poisoned <- load (C.mkFixedSizeBinary 12 2 Nothing (julian 2440588 1 <> BS.replicate 12 255))
+  structure <- load (C.mkStruct 2 (C.validityGenerate 2 (== 0)) (V.singleton ("t", poisoned)))
+  parentSchema <- load (Arrow.arrowFieldToNestedSchema parent)
+  parentRows <- load (Arrow.columnArrayToNestedRows parent structure)
+  nested <- load (N.buildNestedFile (V.singleton ("s", parentSchema)) (V.singleton parentRows))
+  (nestedInput, nestedSchema, _) <- decodeFile nested
+  let nestedTarget = parent {A.fieldChildren = V.singleton (A.defaultField "t" False (A.ATimestamp A.Nanosecond Nothing) V.empty)}
+  nestedColumns <- load (either (Left . show) Right (Arrow.parquetRowGroupToArrow (nestedSchema {A.arrowFields = V.singleton nestedTarget}) nestedInput 0))
+  check "nested conversion retains parent null" (C.nullCount (V.head nestedColumns) == 1)
+  ok <- H.check $ H.withTests 500 $ H.property $ do
+    high <- H.forAll (Gen.choice [Gen.int32 Range.constantBounded, Gen.element [-1, 0]])
+    low <- H.forAll (Gen.word64 Range.constantBounded)
+    let value = TS.Timestamp96 high low
+    encoded <- H.evalEither (TS.timestamp96FromInteger (TS.timestamp96ToInteger value))
+    decoded <- H.evalEither (TS.decodeTimestamp96 (TS.encodeTimestamp96 encoded))
+    decoded H.=== value
+    let integer = toInteger high * 18446744073709551616 + toInteger low
+        unsignedBytes = BS.foldr (\byte rest -> rest * 256 + toInteger byte) 0 (TS.encodeTimestamp96 encoded)
+    unsignedBytes H.=== integer `mod` (2 ^ (96 :: Int))
+    column <- H.evalEither (C.mkFixedSizeBinary 12 1 Nothing (TS.encodeTimestamp96 value))
+    let source = TS.timestampField "t" False (TS.SignedTimestamp96 False P.LtNanos)
+        target = A.defaultField "t" False (A.ATimestamp A.Nanosecond Nothing) V.empty
+        projected = TS.projectTimestampColumn source target column >>= counts
+    if integer >= toInteger (minBound :: Int64) && integer <= toInteger (maxBound :: Int64)
+      then do
+        actual <- H.evalEither projected
+        actual H.=== V.singleton (Just (fromInteger integer))
+      else H.assert (isLeft projected)
+  check "generated96bit codec and independent checked-projection oracle" ok
diff --git a/test/VariantArrowRegression.hs b/test/VariantArrowRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/VariantArrowRegression.hs
@@ -0,0 +1,190 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module VariantArrowRegression (tests) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Control.Exception (evaluate)
+import Control.Monad (unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Int (Int64)
+import Data.Map.Strict qualified as M
+import Data.Text.Lazy qualified as TL
+import Data.Text.Lazy.Builder qualified as TB
+import Data.Text.Lazy.Builder.Int qualified as TBI
+import Data.Vector qualified as V
+import Data.Vector.Storable qualified as S
+import GHC.Conc (getAllocationCounter)
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Variant qualified as B
+import Parquet.Variant.Arrow qualified as R
+import Parquet.Variant.Schema qualified as Schema
+
+
+load :: Either String a -> IO a
+load = either fail pure
+
+
+check :: String -> Bool -> IO ()
+check name ok = unless ok (fail ("Variant Arrow regression: " ++ name))
+
+
+metadataField :: A.Field
+metadataField = A.defaultLeafField "metadata" False A.ABinary
+
+
+valueField :: A.Field
+valueField = A.defaultLeafField "value" True A.ABinary
+
+
+longField :: A.Field
+longField = A.defaultLeafField "typed_value" True (A.AInt 64 True)
+
+
+wrapper :: A.Field
+wrapper = A.defaultField "a" False A.AStruct (V.fromList [valueField, longField])
+
+
+root :: V.Vector A.Field -> A.Field
+root children = (A.defaultField "v" True A.AStruct children) {A.fieldMetadata = Schema.variantExtensionMetadata}
+
+
+-- A partial object whose fallback fragment uses a dictionary also containing
+-- the completely shredded name a. Encoding that fragment with a new dictionary
+-- would silently change its object IDs and lose/corrupt the rest field.
+data PartialCase = PartialCase {partialField :: !A.Field, partialColumn :: !C.ColumnArray, partialExpected :: !B.Variant}
+
+
+partial :: Int64 -> Either String PartialCase
+partial number = do
+  dictionary <- B.buildVariantMetadata (V.fromList ["a", "rest"])
+  let remainder = B.VObject (M.singleton "rest" (B.VArray (V.fromList [B.VInt8 1, B.VInt8 2])))
+  fallback <- B.encodeVariantValue dictionary remainder
+  child <- C.mkStruct 1 Nothing (V.fromList [("value", C.fromMaybeByteStrings (V.singleton Nothing)), ("typed_value", C.fromMaybes C.PInt64 (V.singleton (Just number)))])
+  typed <- C.mkStruct 1 Nothing (V.singleton ("a", child))
+  let typedField = A.defaultField "typed_value" True A.AStruct (V.singleton wrapper)
+      field = root (V.fromList [typedField, metadataField, valueField])
+      expected = B.VObject (M.insert "a" (B.VInt64 number) (M.singleton "rest" (B.VArray (V.fromList [B.VInt8 1, B.VInt8 2]))))
+  column <- C.mkStruct 1 Nothing (V.fromList [("typed_value", typed), ("metadata", C.fromMaybeByteStrings (V.singleton (Just (B.metadataBytes dictionary)))), ("value", C.fromMaybeByteStrings (V.singleton (Just fallback)))])
+  pure (PartialCase field column expected)
+
+
+tests :: IO ()
+tests = do
+  example <- load (partial minBound)
+  let field = partialField example; column = partialColumn example; expected = partialExpected example
+  reader <- load (R.compileVariantArrowReader field column)
+  check "partial object reconstructs typed plus fallback with original IDs" (R.variantArrowAt reader 0 == Right (Just expected))
+  check "row bounds reject" (isLeft (R.variantArrowAt reader (-1)) && isLeft (R.variantArrowAt reader 1))
+  let compile limits = R.compileVariantArrowReaderWithLimits limits Schema.defaultVariantSchemaLimits field column
+  limited <- load (compile (B.VariantLimits 500 4 100))
+  check "typed and fallback siblings share one global count budget" (isLeft (R.variantArrowAt limited 0))
+  exact <- load (compile (B.VariantLimits 2 5 2))
+  check "exact tree count/depth/dictionary budgets succeed" (R.variantArrowAt exact 0 == Right (Just expected))
+  shallow <- load (compile (B.VariantLimits 1 100 2))
+  check "fallback fragments retain their position in typed tree depth" (isLeft (R.variantArrowAt shallow 0))
+  let emptyMetadata = C.fromMaybeByteStrings (V.replicate 4 (Just (BS.pack [1, 0, 0])))
+      binary = C.fromMaybeByteStrings (V.fromList [Nothing, Just (BS.singleton 0), Nothing, Just "poison"])
+      typed = C.fromMaybes C.PInt64 (V.fromList [Nothing, Nothing, Just 34, Just 999])
+      validity = C.validityFromBools (V.fromList [True, True, True, False])
+      primitiveField = root (V.fromList [metadataField, valueField, longField])
+  primitiveColumn <- load (C.mkStruct 4 validity (V.fromList [("metadata", emptyMetadata), ("value", binary), ("typed_value", typed)]))
+  primitive <- load (R.compileVariantArrowReader primitiveField primitiveColumn)
+  actual <- load (V.generateM 4 (R.variantArrowAt primitive))
+  check "required missing root becomes Variant null; null root masks poison" (actual == V.fromList [Just B.VNull, Just B.VNull, Just (B.VInt64 34), Nothing])
+  let requiredTyped = primitiveField {A.fieldChildren = V.fromList [metadataField, valueField, longField {A.fieldNullable = False}]}
+      requiredValue = primitiveField {A.fieldChildren = V.fromList [metadataField, valueField {A.fieldNullable = False}, longField]}
+  typedRequired <- load (R.compileVariantArrowReader requiredTyped primitiveColumn)
+  check "visible required typed null is invalid instead of fallback" (isLeft (R.variantArrowAt typedRequired 0) && isLeft (R.variantArrowAt typedRequired 1))
+  check "present required typed value remains valid" (R.variantArrowAt typedRequired 2 == Right (Just (B.VInt64 34)))
+  valueRequired <- load (R.compileVariantArrowReader requiredValue primitiveColumn)
+  check "visible required fallback null is invalid instead of typed value" (isLeft (R.variantArrowAt valueRequired 0) && isLeft (R.variantArrowAt valueRequired 2))
+  check "present required fallback remains valid" (R.variantArrowAt valueRequired 1 == Right (Just B.VNull))
+  maskedColumn <- load (C.mkStruct 1 (C.validityFromBools (V.singleton False)) (V.fromList [("metadata", C.fromMaybeByteStrings (V.singleton (Just "poison"))), ("value", C.fromMaybeByteStrings (V.singleton (Just "poison"))), ("typed_value", C.fromMaybes C.PInt64 (V.singleton Nothing))]))
+  maskedReader <- load (R.compileVariantArrowReader requiredTyped maskedColumn)
+  check "null parent masks null required typed child and poison payloads" (R.variantArrowAt maskedReader 0 == Right Nothing)
+  check "non-nullable root cannot mask a null slot" (isLeft (R.compileVariantArrowReader primitiveField {A.fieldNullable = False} primitiveColumn))
+  let missing = C.fromMaybeByteStrings (V.singleton Nothing)
+      metadata = C.fromMaybeByteStrings (V.singleton (Just (BS.pack [1, 0, 0])))
+  elements <- load (C.mkStruct 3 Nothing (V.singleton ("value", C.fromMaybeByteStrings (V.fromList [Just (BS.singleton 0), Nothing, Just (BS.pack [12, 127])]))))
+  list <- load (C.mkList Nothing (S.fromList [0, 3]) elements)
+  let elementField = A.defaultField "element" False A.AStruct (V.singleton valueField)
+      listField = A.defaultField "typed_value" True A.AList (V.singleton elementField)
+      arrayField = root (V.fromList [metadataField, listField])
+  array <- load (C.mkStruct 1 Nothing (V.fromList [("metadata", metadata), ("typed_value", list)]))
+  arrays <- load (R.compileVariantArrowReader arrayField array)
+  check "missing array element materializes null and preserves cardinality" (R.variantArrowAt arrays 0 == Right (Just (B.VArray (V.fromList [B.VNull, B.VNull, B.VInt8 127]))))
+  check "bad root schema is rejected before column traversal" (isLeft (R.compileVariantArrowReader arrayField {A.fieldMetadata = V.empty} array))
+  let ordinaryRoot = root (V.fromList [metadataField, valueField])
+  metadataMissing <- load (C.mkStruct 1 Nothing (V.fromList [("metadata", missing), ("value", missing)]))
+  mm <- load (R.compileVariantArrowReader ordinaryRoot metadataMissing)
+  check "present root requires metadata even when its value is missing" (isLeft (R.variantArrowAt mm 0))
+  -- A fragment nested under a typed object starts at depth one. Resetting
+  -- its binary decoder to depth zero would incorrectly admit this array.
+  dict <- load (B.buildVariantMetadata (V.singleton "a"))
+  payload <- load (B.encodeVariantValue dict (B.VArray (V.singleton B.VNull)))
+  fragment <- load (C.mkStruct 1 Nothing (V.singleton ("value", C.fromMaybeByteStrings (V.singleton (Just payload)))))
+  containing <- load (C.mkStruct 1 Nothing (V.singleton ("a", fragment)))
+  let valueWrapper = A.defaultField "a" False A.AStruct (V.singleton valueField)
+      containingField = A.defaultField "typed_value" True A.AStruct (V.singleton valueWrapper)
+      nestedField = root (V.fromList [metadataField, containingField])
+  nestedColumn <- load (C.mkStruct 1 Nothing (V.fromList [("metadata", C.fromMaybeByteStrings (V.singleton (Just (B.metadataBytes dict)))), ("typed_value", containing)]))
+  tooShallow <- load (R.compileVariantArrowReaderWithLimits (B.VariantLimits 1 100 100) Schema.defaultVariantSchemaLimits nestedField nestedColumn)
+  check "nested fallback decoder never resets its actual depth" (isLeft (R.variantArrowAt tooShallow 0))
+  deepEnough <- load (R.compileVariantArrowReaderWithLimits (B.VariantLimits 2 3 1) Schema.defaultVariantSchemaLimits nestedField nestedColumn)
+  check "nested fallback decoder counts one semantic root" (R.variantArrowAt deepEnough 0 == Right (Just (B.VObject (M.singleton "a" (B.VArray (V.singleton B.VNull))))))
+  -- Directly sliced REE metadata retains a nonzero logical offset. No
+  -- expansion or assumption that logical row zero is physical run zero.
+  metadataValues <- load (C.mkBinary Nothing (S.fromList [0, 6, 9]) (BS.pack [112, 111, 105, 115, 111, 110, 1, 0, 0]))
+  runs <- load (C.mkRunEndEncoded (C.primColumn C.PInt16 (S.fromList [2, 5])) metadataValues)
+  let sliced = C.sliceColumnArray 1 4 runs
+      reeField = A.defaultField "metadata" False A.ARunEndEncoded (V.fromList [A.defaultLeafField "run_ends" False (A.AInt 16 True), A.defaultLeafField "values" True A.ABinary])
+      reeSchema = root (V.fromList [reeField, longField])
+      rootValidity = C.validityFromBools (V.fromList [False, True, True, True])
+  reeColumn <- load (C.mkStruct 4 rootValidity (V.fromList [("metadata", sliced), ("typed_value", C.primColumn C.PInt64 (S.fromList [999, 7, 8, 9]))]))
+  reeReader <- load (R.compileVariantArrowReader reeSchema reeColumn)
+  reeValues <- load (V.generateM 4 (R.variantArrowAt reeReader))
+  check "sliced run-end metadata preserves offset and masks unreachable poison" (reeValues == V.fromList [Nothing, Just (B.VInt64 7), Just (B.VInt64 8), Just (B.VInt64 9)])
+  -- Wide objects can share their all-missing child buffers. The schema
+  -- work budget bounds their compiled shape; names must not be rebound by
+  -- rescanning the whole column vector once for every sibling.
+  emptyFieldColumn <- load (C.mkStruct 1 Nothing (V.singleton ("value", missing)))
+  let width = 50000
+      nameAt i = TL.toStrict (TB.toLazyText ("k" <> TBI.decimal i))
+      wideFields = V.generate width (\i -> A.defaultField (nameAt i) False A.AStruct (V.singleton valueField))
+      wideColumns = V.map (\child -> (A.fieldName child, emptyFieldColumn)) wideFields
+      wideTyped = A.defaultField "typed_value" True A.AStruct wideFields
+      wideSchema = root (V.fromList [metadataField, wideTyped])
+  wideObject <- load (C.mkStruct 1 Nothing wideColumns)
+  wideColumn <- load (C.mkStruct 1 Nothing (V.fromList [("metadata", metadata), ("typed_value", wideObject)]))
+  wideReader <- load (R.compileVariantArrowReaderWithLimits (B.VariantLimits 1 1 0) Schema.defaultVariantSchemaLimits wideSchema wideColumn)
+  check "wide all-missing object consumes only its semantic root" (R.variantArrowAt wideReader 0 == Right (Just (B.VObject M.empty)))
+  -- Valid Arrow buffers, but a required shared dictionary name is absent.
+  -- Reject by presence before allocating 100000 reconstructed values.
+  let many = 100000
+      elementType = A.defaultField "element" False A.AStruct (V.singleton longField)
+      largeListType = A.defaultField "typed_value" True A.AList (V.singleton elementType)
+      largeWrapperType = A.defaultField "a" False A.AStruct (V.singleton largeListType)
+      largeObjectType = A.defaultField "typed_value" True A.AStruct (V.singleton largeWrapperType)
+      hostileSchema = root (V.fromList [metadataField, largeObjectType])
+  manyElements <- load (C.mkStruct many Nothing (V.singleton ("typed_value", C.primColumn C.PInt64 (S.replicate many 42))))
+  manyList <- load (C.mkList Nothing (S.fromList [0, fromIntegral many]) manyElements)
+  largeWrapper <- load (C.mkStruct 1 Nothing (V.singleton ("typed_value", manyList)))
+  largeObject <- load (C.mkStruct 1 Nothing (V.singleton ("a", largeWrapper)))
+  hostileColumn <- load (C.mkStruct 1 Nothing (V.fromList [("metadata", metadata), ("typed_value", largeObject)]))
+  hostileReader <- load (R.compileVariantArrowReader hostileSchema hostileColumn)
+  _ <- evaluate (R.variantArrowLength hostileReader)
+  before <- getAllocationCounter
+  rejected <- evaluate (isLeft (R.variantArrowAt hostileReader 0))
+  after <- getAllocationCounter
+  check "missing shared name rejects before typed subtree allocation" (rejected && before - after < 1024 * 1024)
+  good <- H.check $ H.withTests 1000 $ H.property $ do
+    number <- H.forAll (Gen.int64 Range.constantBounded)
+    exampleCase <- H.evalEither (partial number)
+    compiled <- H.evalEither (R.compileVariantArrowReader (partialField exampleCase) (partialColumn exampleCase))
+    R.variantArrowAt compiled 0 H.=== Right (Just (partialExpected exampleCase))
+  check "generated partial object semantic round trips" good
+  putStrLn "Variant Arrow typed/fallback/global-budget/missing/null regressions passed"
diff --git a/test/VariantParquetRegression.hs b/test/VariantParquetRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/VariantParquetRegression.hs
@@ -0,0 +1,213 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module VariantParquetRegression (tests) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Control.Exception (evaluate)
+import Control.Monad (forM_, unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft, isRight)
+import Data.Int (Int32)
+import Data.Map.Strict qualified as M
+import Data.Text qualified as T
+import Data.Vector qualified as V
+import GHC.Conc (getAllocationCounter)
+import Parquet.Arrow qualified as Arrow
+import Parquet.Nested qualified as N
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+import Parquet.Variant qualified as Variant
+import Parquet.Variant.Parquet qualified as VP
+import Parquet.Variant.Schema qualified as VariantSchema
+import VariantRegression qualified as Cases
+
+
+load :: Either String a -> IO a
+load = either fail pure
+
+
+tests :: IO ()
+tests = do
+  let check name condition = unless condition (fail ("Variant Parquet regression: " ++ name))
+      values = V.cons Nothing (Just <$> Cases.values)
+      canonical Nothing = Right Nothing
+      canonical (Just value) = Just <$> Variant.encodeVariant value
+  bytes <- load (VP.buildVariantParquetFile "v" values)
+  file <- load (Read.loadParquetFile bytes)
+  output <- load (VP.readVariantColumn file 0 "v")
+  check "all primitive/container payloads and IEEE bits survive the file" (traverse canonical output == traverse canonical values)
+  let footer = Read.pfFooter file
+      schema = P.fmSchema footer
+      withoutAnnotation = file {Read.pfFooter = footer {P.fmSchema = V.imap (\i element -> if i == 1 then element {P.seLogicalType = Nothing} else element) schema}}
+  check "native writer emits VARIANT(1)" (P.seLogicalType (schema V.! 1) == Just (P.LTVariant 1))
+  check "semantic file API requires annotation" (isLeft (VP.readVariantColumn withoutAnnotation 0 "v"))
+  check "missing column fails" (isLeft (VP.readVariantColumn file 0 "absent"))
+  -- Reorder footer children and column descriptors without touching their
+  -- data bytes. The semantic reader must use names instead of positions.
+  let reorderedSchema = V.fromList [schema V.! 0, schema V.! 1, schema V.! 3, schema V.! 2]
+      reorderedGroups = V.map (\group -> group {P.rgColumns = V.reverse (P.rgColumns group)}) (P.fmRowGroups footer)
+      reordered = file {Read.pfFooter = footer {P.fmSchema = reorderedSchema, P.fmRowGroups = reorderedGroups}}
+  reorderedValues <- load (VP.readVariantColumn reordered 0 "v")
+  check "metadata/value fields are accessed by name" (traverse canonical reorderedValues == traverse canonical values)
+  forM_ [0, 2] $ \version -> do
+    let changed = file {Read.pfFooter = footer {P.fmSchema = schema V.// [(1, (schema V.! 1) {P.seLogicalType = Just (P.LTVariant version)})]}}
+    check "unknown annotation version is not interpreted as v1" (isLeft (VP.readVariantColumn changed 0 "v"))
+  forM_ Cases.malformed $ \(name, metadata, value) ->
+    check ("writer rejects malformed " ++ name) (isLeft (N.buildNestedFile (V.singleton ("v", N.NSVariant)) (V.singleton (V.singleton (N.NRVariantBytes metadata value)))))
+  let invalidVariant = N.NRVariantBytes (BS.pack [1, 0, 0]) (BS.singleton 84)
+      integer = N.NRLeaf (N.LvInt32 1)
+      nestedShapes =
+        [ (N.NSStruct (V.fromList [("ordinary", N.NSPrimitive N.LtInt32), ("values", N.NSList (N.NSOptional N.NSVariant))]), N.NRStruct (V.fromList [integer, N.NRList (V.fromList [N.NRNull, invalidVariant])]))
+        , (N.NSMap N.NSVariant (N.NSPrimitive N.LtInt32), N.NRMapEntries (V.singleton (invalidVariant, integer)))
+        , (N.NSMap (N.NSPrimitive N.LtInt32) (N.NSOptional N.NSVariant), N.NRMapEntries (V.singleton (integer, invalidVariant)))
+        ]
+  forM_ nestedShapes $ \(shape, row) ->
+    check "deferred semantic validation visits nested structs/lists/map keys and values" (isLeft (N.shred shape (V.singleton row)))
+  -- Ordinary unannotated binary data must remain byte preserving even when
+  -- a caller chooses the names metadata/value and the bytes aren't Variants.
+  raw <- load (N.buildNestedFile (V.singleton ("v", N.NSStruct (V.fromList [("metadata", N.NSPrimitive N.LtBinary), ("value", N.NSPrimitive N.LtBinary)]))) (V.singleton (V.singleton (N.NRStruct (V.fromList [N.NRLeaf (N.LvBinary "invalid"), N.NRLeaf (N.LvBinary "bytes")])))))
+  rawFile <- load (Read.loadParquetFile raw)
+  rawSchema <- load (Arrow.parquetFileArrowSchemaChecked rawFile)
+  check "ordinary binary reads preserve arbitrary bytes" (isRight (Arrow.parquetRowGroupToArrow rawSchema rawFile 0))
+  let sample = V.fromList [Just (Variant.VInt8 4), Nothing, Just Variant.VNull, Just (Variant.VObject (M.singleton "nested" (Variant.VBool True)))]
+  encoded <- V.mapM (maybe (pure Nothing) (fmap Just . load . Variant.encodeVariant)) sample
+  let metadata = V.imap (\i value -> if i == 1 then Just "garbage" else Variant.variantMetadata <$> value) encoded
+      payload = V.imap (\i value -> if i == 1 then Just "garbage" else Variant.variantValue <$> value) encoded
+      validity = C.validityFromBools (V.fromList [True, False, True, True])
+  forM_ [(C.fromMaybeByteStrings metadata, C.fromMaybeByteStrings payload), (C.fromMaybeLargeByteStrings metadata, C.fromMaybeLargeByteStrings payload), (C.fromMaybeBinaryView metadata, C.fromMaybeBinaryView payload)] $ \(m, v) -> do
+    column <- load (C.mkStruct 4 validity (V.fromList [("value", v), ("metadata", m)]))
+    reader <- load (VP.compileVariantReader column)
+    actual <- load (V.generateM 4 (VP.variantAt reader))
+    check "parent null masks arbitrary children in all binary storage profiles" (traverse canonical actual == traverse canonical sample)
+    check "Variant null and absent slot stay distinct" (actual V.! 1 == Nothing && actual V.! 2 == Just Variant.VNull)
+    check "row bounds rejected" (isLeft (VP.variantAt reader (-1)) && isLeft (VP.variantAt reader 4))
+  missingMetadata <- load (C.mkStruct 1 Nothing (V.fromList [("metadata", C.fromMaybeByteStrings (V.singleton Nothing)), ("value", C.fromMaybeByteStrings (V.singleton (Just (BS.singleton 0))))]))
+  reader <- load (VP.compileVariantReader missingMetadata)
+  check "present parent requires metadata" (isLeft (VP.variantAt reader 0))
+  let deep = foldr (\_ value -> Variant.VArray (V.singleton value)) Variant.VNull [1 .. 501 :: Int]
+      raised = Variant.VariantLimits 501 502 0
+  deepBytes <- load (VP.buildVariantParquetFileWithLimits raised "v" (V.singleton (Just deep)))
+  deepFile <- load (Read.loadParquetFile deepBytes)
+  check "default depth limit applies on semantic file reads" (isLeft (VP.readVariantColumn deepFile 0 "v"))
+  deepOutput <- load (VP.readVariantColumnWithLimits raised deepFile 0 "v")
+  check "explicit resource override works through both file APIs" (deepOutput == V.singleton (Just deep))
+  -- The dictionary is valid and large, so a test using arbitrary invalid
+  -- bytes would miss eager validation before the cumulative page bound.
+  bigMetadata <- load (Variant.buildVariantMetadata (V.singleton (T.replicate (1024 * 1024) "a")))
+  let dictionaryBytes = Variant.metadataBytes bigMetadata
+      count = fromIntegral (maxBound :: Int32) `quot` (BS.length dictionaryBytes + 4) + 1
+      bigRows = V.replicate count (N.NRVariantBytes dictionaryBytes (BS.singleton 0))
+  _ <- evaluate (BS.length dictionaryBytes)
+  _ <- evaluate (V.length bigRows)
+  forM_ [N.shred N.NSVariant bigRows >> pure (), N.buildNestedFile (V.singleton ("v", N.NSVariant)) (V.singleton bigRows) >> pure ()] $ \operation -> do
+    before <- getAllocationCounter
+    rejected <- evaluate (isLeft operation)
+    after <- getAllocationCounter
+    check "cumulative size bound precedes valid dictionary parsing" rejected
+    check ("rejected valid Variant page stays below allocation bound: " ++ show (before - after)) (before - after < 8 * 1024 * 1024)
+  nativeTests
+  putStrLn "Variant Parquet annotation/semantic/null/limits regressions passed"
+
+
+-- Build real encoded physical leaves with the normal nested writer, then
+-- annotate the parsed group. The external suite also tests actual foreign
+-- footers; these cases isolate native schema/column/projection invariants.
+nativeTests :: IO ()
+nativeTests = do
+  let check name good = unless good (fail ("native Variant regression: " ++ name))
+      annotate file =
+        let footer = Read.pfFooter file
+            schema = P.fmSchema footer
+        in file {Read.pfFooter = footer {P.fmSchema = schema V.// [(1, (schema V.! 1) {P.seLogicalType = Just (P.LTVariant 1)})]}}
+      metadata = N.NRLeaf (N.LvBinary (BS.pack [1, 0, 0]))
+      value = N.NRLeaf (N.LvBinary (BS.singleton 0))
+      make shape rows = annotate <$> (load . Read.loadParquetFile =<< load (N.buildNestedFile (V.singleton ("v", shape)) (V.singleton rows)))
+      primitive leaf = N.NSStruct (V.fromList [("metadata", N.NSPrimitive N.LtBinary), ("value", N.NSOptional (N.NSPrimitive N.LtBinary)), ("typed_value", N.NSOptional (N.NSPrimitive leaf))])
+      row typed = N.NRStruct (V.fromList [metadata, N.NRNull, N.NRLeaf typed])
+      cases =
+        [ (N.LtDecimal 9 2, N.LvInt32 12345, A.ADecimal32 9 2, Variant.VDecimal4 2 12345)
+        , (N.LtDecimal 10 3, N.LvInt64 (-12345), A.ADecimal64 10 3, Variant.VDecimal8 3 (-12345))
+        , (N.LtDecimal 19 4, N.LvFixedBinary (BS.replicate 14 0 <> BS.pack [48, 57]), A.ADecimal 19 4, Variant.VDecimal16 4 12345)
+        , (N.LtUuid, N.LvFixedBinary (BS.pack [0 .. 15]), A.AFixedSizeBinary 16, Variant.VUuid (BS.pack [0 .. 15]))
+        , (N.LtTimestamp True P.LtNanos, N.LvInt64 0, A.ATimestamp A.Nanosecond (Just "UTC"), Variant.VTimestampNanos 0)
+        ]
+  forM_ cases $ \(leaf, input, typ, expected) -> do
+    file <- make (primitive leaf) (V.fromList [row input, N.NRStruct (V.fromList [metadata, value, N.NRNull])])
+    schema <- load (Arrow.parquetFileArrowSchemaChecked file)
+    let field = V.head (A.arrowFields schema)
+        typed = A.fieldChildren field V.! 2
+    check "native field carries canonical extension" (VariantSchema.isVariantField field)
+    check "exact typed decimal/timestamp/UUID field type" (A.fieldType typed == typ)
+    load (VariantSchema.validateVariantField field)
+    actual <- load (VP.readVariantColumn file 0 "v")
+    check "native typed value preserves Variant identity and null" (actual == V.fromList [Just expected, Just Variant.VNull])
+  intFile <- make (primitive N.LtInt32) (V.singleton (row (N.LvInt32 7)))
+  schema <- load (Arrow.parquetFileArrowSchemaChecked intFile)
+  let field = V.head (A.arrowFields schema)
+      fields = A.fieldChildren field
+      target changed = schema {A.arrowFields = V.singleton changed}
+      widened = field {A.fieldChildren = fields V.// [(2, (fields V.! 2) {A.fieldType = A.AInt 64 True})]}
+      dropped = field {A.fieldChildren = V.filter ((/= "value") . A.fieldName) fields}
+  check "retained Variant extension forbids integer widening" (isLeft (Arrow.parquetRowGroupToArrow (target widened) intFile 0))
+  check "retained Variant extension forbids dropping fallback storage" (isLeft (Arrow.parquetRowGroupToArrow (target dropped) intFile 0))
+  check "explicit raw projection may widen and omit fields" (isRight (Arrow.parquetRowGroupToArrow (target widened {A.fieldMetadata = V.empty, A.fieldChildren = V.singleton ((fields V.! 2) {A.fieldType = A.AInt 64 True})}) intFile 0))
+  let reordered = field {A.fieldChildren = V.reverse fields}
+  check "retained Variant permits lossless field reorder" (isRight (Arrow.parquetRowGroupToArrow (target reordered) intFile 0))
+  forM_ [N.LtDecimal 9 2, N.LtDecimal 18 2] $ \leaf -> do
+    file <- make (primitive leaf) (V.singleton (row (if leaf == N.LtDecimal 9 2 then N.LvInt32 1 else N.LvInt64 1)))
+    let footer = Read.pfFooter file
+        original = P.fmSchema footer
+        leafIndex = V.length original - 1
+        native = original V.! leafIndex
+        invalid = native {P.seType = if P.seType native == Just P.PTInt32 then Just P.PTInt64 else Just P.PTInt32}
+        malformed = file {Read.pfFooter = footer {P.fmSchema = original V.// [(leafIndex, invalid)]}}
+    check "wrong native decimal precision carrier rejected before decode" (isLeft (Arrow.parquetFileArrowSchemaChecked malformed))
+  forM_ [N.LtInteger 32 False, N.LtTimestamp False P.LtMillis, N.LtTime True P.LtMicros, N.LtJson, N.LtFixedBinary 16] $ \leaf -> do
+    -- No rows are needed: schema validity must not depend on row-group data.
+    file <- make (primitive leaf) V.empty
+    check "noncanonical typed primitive rejected on empty data" (isLeft (Arrow.parquetFileArrowSchemaChecked file))
+  -- A LIST wrapper called array normally triggers the legacy two-level
+  -- heuristic. Known Variant lists must always retain the required element.
+  let element = N.NSStruct (V.singleton ("typed_value", N.NSOptional (N.NSPrimitive N.LtInt32)))
+      arrayShape = N.NSStruct (V.fromList [("metadata", N.NSPrimitive N.LtBinary), ("typed_value", N.NSOptional (N.NSList element))])
+      arrayRow = N.NRStruct (V.fromList [metadata, N.NRList (V.fromList [N.NRStruct (V.singleton (N.NRLeaf (N.LvInt32 3))), N.NRStruct (V.singleton N.NRNull)])])
+  file <- make arrayShape (V.singleton arrayRow)
+  let footer = Read.pfFooter file
+      original = P.fmSchema footer
+      renamed = V.map (\se -> if P.seName se == "list" then se {P.seName = "array"} else se) original
+      renamePath name = if name == "list" then "array" else name
+      groups = V.map (\group -> group {P.rgColumns = V.map (\column -> column {P.ccMetadata = fmap (\meta -> meta {P.cmPathInSchema = V.map renamePath (P.cmPathInSchema meta)}) (P.ccMetadata column)}) (P.rgColumns group)}) (P.fmRowGroups footer)
+      changed = file {Read.pfFooter = footer {P.fmSchema = renamed, P.fmRowGroups = groups}}
+  actual <- load (VP.readVariantColumn changed 0 "v")
+  check "exact Variant three-level list bypasses legacy-name heuristic" (actual == V.singleton (Just (Variant.VArray (V.fromList [Variant.VInt32 3, Variant.VNull]))))
+
+  let mutate file change =
+        let footer = Read.pfFooter file
+        in file {Read.pfFooter = footer {P.fmSchema = change (P.fmSchema footer)}}
+      changeLast f elements = elements V.// [(V.length elements - 1, f (V.last elements))]
+  forM_ [(8, True, 128), (16, True, 32768), (8, False, 256), (16, False, 65536)] $ \(width, signed, badValue) -> do
+    wide <- make (primitive N.LtInt32) (V.singleton (row (N.LvInt32 badValue)))
+    let invalid = mutate wide (changeLast (\se -> se {P.seLogicalType = Just (P.LTInteger width signed)}))
+    check "out-of-domain narrow integer is rejected instead of wrapping" (isLeft (VP.readVariantColumn invalid 0 "v"))
+  decimal <- make (primitive (N.LtDecimal 9 0)) (V.singleton (row (N.LvInt32 999999999)))
+  let outOfRange = mutate decimal (changeLast (\se -> se {P.seLogicalType = Just (P.LTDecimal 8 0)}))
+  check "narrow decimal buffer enforces declared precision" (isLeft (VP.readVariantColumn outOfRange 0 "v"))
+  forM_ [(2, Just P.Optional), (3, Just P.Required), (4, Just P.Required)] $ \(index, repetition) -> do
+    let malformed = mutate intFile (\elements -> elements V.// [(index, (elements V.! index) {P.seRepetition = repetition})])
+    check "Variant metadata/value/typed repetition is validated before decode" (isLeft (Arrow.parquetFileArrowSchemaChecked malformed))
+  forM_ [0, 1] $ \count -> do
+    unshredded <- make (N.NSStruct (V.fromList [("metadata", N.NSPrimitive N.LtBinary), ("value", N.NSPrimitive N.LtBinary)])) (V.replicate count (N.NRStruct (V.fromList [metadata, value])))
+    let zeroTyped =
+          mutate
+            unshredded
+            ( \elements ->
+                let parent = (elements V.! 1) {P.seNumChildren = Just 3}
+                    fallback = (elements V.! 3) {P.seRepetition = Just P.Optional}
+                    typed = P.SchemaElement "typed_value" (Just P.Optional) Nothing (Just 0) Nothing Nothing Nothing Nothing
+                in (elements V.// [(1, parent), (3, fallback)]) `V.snoc` typed
+            )
+    inferred <- load (Arrow.parquetFileArrowSchemaChecked zeroTyped)
+    if count == 0
+      then check "zero-row native empty typed object has exact canonical schema" (isRight (Arrow.parquetRowGroupToArrow inferred zeroTyped 0))
+      else check "optional zero-leaf object presence cannot be invented" (isLeft (Arrow.parquetRowGroupToArrow inferred zeroTyped 0))
diff --git a/test/VariantRegression.hs b/test/VariantRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/VariantRegression.hs
@@ -0,0 +1,210 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module VariantRegression (tests, values, malformed) where
+
+import Control.Monad (forM_, unless)
+import Data.Bits ((.|.))
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Map.Strict qualified as M
+import Data.Text qualified as T
+import Data.Vector qualified as V
+import GHC.Float (castWord32ToFloat, castWord64ToDouble)
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Variant
+
+
+values :: V.Vector Variant
+values =
+  V.fromList
+    [ VNull
+    , VBool False
+    , VBool True
+    , VInt8 minBound
+    , VInt8 maxBound
+    , VInt16 minBound
+    , VInt16 maxBound
+    , VInt32 minBound
+    , VInt32 maxBound
+    , VInt64 minBound
+    , VInt64 maxBound
+    , VFloat 0
+    , VFloat (-0)
+    , VFloat (1 / 0)
+    , VFloat (-1 / 0)
+    , VFloat (castWord32ToFloat 0x7fc12345)
+    , VDouble 0
+    , VDouble (-0)
+    , VDouble (1 / 0)
+    , VDouble (-1 / 0)
+    , VDouble (castWord64ToDouble 0x7ff8123456789012)
+    , VDecimal4 0 0
+    , VDecimal4 38 (-999999999)
+    , VDecimal4 9 999999999
+    , VDecimal8 38 (-999999999999999999)
+    , VDecimal8 18 999999999999999999
+    , VDecimal16 38 (negate (10 ^ (38 :: Int) - 1))
+    , VDecimal16 0 (10 ^ (38 :: Int) - 1)
+    , VDate 0
+    , VDate (-40000)
+    , VTimestamp (-1)
+    , VTimestamp 2000000000000000
+    , VTimestampNtz (-1)
+    , VTimestampNtz 2000000000000000
+    , VTimestampNanos minBound
+    , VTimestampNanos maxBound
+    , VTimestampNtzNanos minBound
+    , VTimestampNtzNanos maxBound
+    , VTime 0
+    , VTime 86399999999
+    , VBinary BS.empty
+    , VBinary (BS.pack [0 .. 255])
+    , VString ""
+    , VString "a"
+    , VString "λ🦊"
+    , VString (T.replicate 63 "x")
+    , VString (T.replicate 64 "x")
+    , VString (T.replicate 128 "λ")
+    , VUuid (BS.pack [0 .. 15])
+    , VArray V.empty
+    , VObject M.empty
+    , VArray (V.fromList [VNull, VInt8 4, VString "five", VObject (M.singleton "nested" (VBool True))])
+    , VObject (M.fromList [("a", VInt8 1), ("b", VArray (V.fromList [VNull, VString "λ"])), ("c", VObject (M.singleton "d" (VInt64 (-2))))])
+    , VArray (V.replicate 300 (VString "wide"))
+    , VObject (M.fromList (map (\n -> (T.replicate n "a", VInt32 (fromIntegral n))) [1 .. 300]))
+    ]
+
+
+-- Each case has a complete enclosing buffer. These specifically distinguish
+-- validation from merely retrieving a prefix or parsing a leaf in isolation.
+malformed :: [(String, BS.ByteString, BS.ByteString)]
+malformed =
+  map
+    (\(name, metadata, value) -> (name, BS.pack metadata, BS.pack value))
+    [ ("trailing-value", [1, 0, 0], [0, 255])
+    , ("metadata-nonzero-start", [1, 1, 1, 2, 120, 97], [0])
+    , ("metadata-unused-tail", [1, 0, 0, 120], [0])
+    , ("metadata-false-sorted", [17, 2, 0, 1, 2, 98, 97], [0])
+    , ("metadata-duplicate-sorted", [17, 2, 0, 1, 2, 97, 97], [0])
+    , ("duplicate-object-key", [1, 1, 0, 1, 97], [2, 2, 0, 0, 0, 1, 2, 0, 0])
+    , ("unordered-object-key", [1, 2, 0, 1, 2, 97, 98], [2, 2, 1, 0, 0, 1, 2, 0, 0])
+    , ("shared-object-offset", [1, 2, 0, 1, 2, 97, 98], [2, 2, 0, 1, 0, 0, 1, 0])
+    , ("object-offset-gap", [1, 1, 0, 1, 97], [2, 1, 0, 1, 2, 0, 0])
+    , ("child-crosses-array-boundary", [1, 0, 0], [3, 1, 0, 1, 12, 127])
+    , ("child-crosses-object-boundary", [1, 1, 0, 1, 97], [2, 1, 0, 0, 1, 12, 127])
+    , ("array-child-trailing", [1, 0, 0], [3, 1, 0, 2, 0, 255])
+    , ("descending-array-offsets", [1, 0, 0], [3, 2, 0, 2, 1, 0, 0])
+    , ("decimal-bad-scale", [1, 0, 0], [32, 255, 0, 0, 0, 0])
+    , ("decimal4-bad-precision", [1, 0, 0], [32, 0, 0, 202, 154, 59])
+    , ("unknown-type", [1, 0, 0], [84])
+    , ("invalid-short-utf8", [1, 0, 0], [5, 255])
+    , ("invalid-long-utf8", [1, 0, 0], [64, 1, 0, 0, 0, 255])
+    , ("huge-array-count", [1, 0, 0], [19, 255, 255, 255, 255])
+    , ("huge-object-count", [1, 0, 0], [66, 255, 255, 255, 255])
+    , ("huge-dictionary-count", [193, 255, 255, 255, 255], [0])
+    , ("unsupported-version", [2, 0, 0], [0])
+    ]
+
+
+tests :: IO ()
+tests = do
+  let load = either fail pure
+      check name condition = unless condition (fail ("Variant regression: " ++ name))
+  V.forM_ values $ \value -> do
+    encoded <- load (encodeVariant value)
+    decoded <- load (decodeVariant (variantMetadata encoded) (variantValue encoded))
+    reencoded <- load (encodeVariant decoded)
+    -- Byte equality preserves NaN payloads and signed zero, unlike Eq Double.
+    check "all primitive/container representations, including IEEE bits" (encoded == reencoded)
+  forM_ malformed $ \(name, metadata, value) -> check name (isLeft (decodeVariant metadata value))
+  let dictionary = BS.pack [1, 2, 0, 1, 2, 97, 98]
+      shuffled = BS.pack [2, 2, 0, 1, 2, 0, 4, 12, 2, 12, 1]
+      expected = VObject (M.fromList [("a", VInt8 1), ("b", VInt8 2)])
+  check "nonmonotone object offsets remain valid" (decodeVariant dictionary shuffled == Right expected)
+  check "reserved metadata and object bits ignored" (decodeVariant (BS.cons (BS.head dictionary .|. 32) (BS.tail dictionary)) (BS.cons (BS.head shuffled .|. 128) (BS.tail shuffled)) == Right expected)
+  check "unsorted/nonunique dictionary permitted when not marked sorted" (decodeVariant (BS.pack [1, 3, 0, 1, 2, 3, 98, 97, 97]) (BS.pack [2, 1, 2, 0, 1, 0]) == Right (VObject (M.singleton "a" VNull)))
+  forM_ [1 .. 4] $ \width -> do
+    let word n = BS.pack (take width (n : repeat 0))
+        metadata = BS.singleton (1 + fromIntegral ((width - 1) * 64)) <> word 1 <> word 0 <> word 1 <> "a"
+        object = BS.singleton (2 + fromIntegral ((width - 1) * 4 + (width - 1) * 16)) <> BS.singleton 1 <> word 0 <> word 0 <> word 1 <> BS.singleton 0
+    check "all legal ID/offset widths" (decodeVariant metadata object == Right (VObject (M.singleton "a" VNull)))
+  forM_ [VUuid "short", VUuid (BS.replicate 17 0), VDecimal4 39 0, VDecimal4 0 1000000000, VDecimal8 0 1000000000000000000, VDecimal16 0 (10 ^ (38 :: Int)), VDecimal16 0 (negate (2 ^ (128 :: Int))), VTime (-1), VTime 86400000000] $ \value -> check "encoder never pads/truncates invalid values" (isLeft (encodeVariant value))
+  let nested = VArray (V.singleton (VArray (V.singleton VNull)))
+  encoded <- load (encodeVariant nested)
+  check "depth override" (isLeft (decodeVariantWithLimits (VariantLimits 1 10 10) (variantMetadata encoded) (variantValue encoded)))
+  check "aggregate value budget" (isLeft (decodeVariantWithLimits (VariantLimits 5 2 10) (variantMetadata encoded) (variantValue encoded)))
+  check "exact budget accepted" (decodeVariantWithLimits (VariantLimits 2 3 0) (variantMetadata encoded) (variantValue encoded) == Right nested)
+  check "encoder budget before collection" (isLeft (encodeVariantWithLimits (VariantLimits 1 10 10) nested))
+  check "dictionary budget" (isLeft (decodeVariantWithLimits (VariantLimits 5 10 1) dictionary shuffled))
+  shared <- load (buildVariantMetadata (V.fromList ["z", "a", "typed-only", "z"]))
+  let fragment = VObject (M.singleton "z" (VInt8 42))
+  fallback <- load (encodeVariantValue shared fragment)
+  check "shredded fallback uses the full shared dictionary" (metadataKeys shared == V.fromList ["a", "typed-only", "z"] && decodeVariant (metadataBytes shared) fallback == Right fragment)
+  check "undeclared fallback field fails instead of using a wrong field ID" (isLeft (encodeVariantValue shared (VObject (M.singleton "absent" VNull))))
+  originalMetadata <- load (compileVariantMetadata (BS.pack [1, 3, 0, 1, 2, 3, 98, 97, 97]))
+  preserved <- load (encodeVariantValue originalMetadata (VObject (M.singleton "a" VNull)))
+  check "existing unsorted nonunique dictionary is preserved and indexed correctly" (decodeVariantValue originalMetadata preserved == Right (VObject (M.singleton "a" VNull)) && metadataBytes originalMetadata == BS.pack [1, 3, 0, 1, 2, 3, 98, 97, 97])
+  let deep = foldr (\_ value -> VArray (V.singleton value)) VNull [1 .. 501 :: Int]
+      raised = VariantLimits 501 502 0
+  deepEncoded <- load (encodeVariantWithLimits raised deep)
+  check "default depth limit is overridable for valid deep trees" (isLeft (encodeVariant deep) && isLeft (decodeVariant (variantMetadata deepEncoded) (variantValue deepEncoded)) && decodeVariantWithLimits raised (variantMetadata deepEncoded) (variantValue deepEncoded) == Right deep)
+  properties <- sequence [H.check roundtripProperty, H.check mutatedProperty, H.check arbitraryBytesProperty]
+  check "generated and adversarial binary properties" (and properties)
+  putStrLn "Variant binary primitive/container/bounds regressions passed"
+
+
+genVariant :: H.Gen Variant
+genVariant =
+  Gen.recursive
+    Gen.choice
+    [ Gen.element (take 49 (V.toList values))
+    , VString <$> Gen.text (Range.linear 0 80) Gen.unicode
+    , VBinary <$> Gen.bytes (Range.linear 0 80)
+    , VInt64 <$> Gen.int64 Range.constantBounded
+    ]
+    [ VArray . V.fromList <$> Gen.list (Range.linear 0 8) genVariant
+    , VObject . M.fromList <$> Gen.list (Range.linear 0 8) ((,) <$> Gen.text (Range.linear 0 20) Gen.unicode <*> genVariant)
+    ]
+
+
+roundtripProperty :: H.Property
+roundtripProperty = H.withTests 1000 $ H.property $ do
+  value <- H.forAll genVariant
+  encoded <- H.evalEither (encodeVariant value)
+  decoded <- H.evalEither (decodeVariant (variantMetadata encoded) (variantValue encoded))
+  reencoded <- H.evalEither (encodeVariant decoded)
+  reencoded H.=== encoded
+
+
+mutatedProperty :: H.Property
+mutatedProperty = H.withTests 3000 $ H.property $ do
+  value <- H.forAll genVariant
+  encoded <- H.evalEither (encodeVariant value)
+  changeMetadata <- H.forAll Gen.bool
+  replacement <- H.forAll (Gen.bytes (Range.linear 0 10))
+  let target = if changeMetadata then variantMetadata encoded else variantValue encoded
+  offset <- H.forAll (Gen.int (Range.linear 0 (BS.length target)))
+  removed <- H.forAll (Gen.int (Range.linear 0 (BS.length target - offset)))
+  let changed = BS.take offset target <> replacement <> BS.drop (offset + removed) target
+      metadata = if changeMetadata then changed else variantMetadata encoded
+      bytes = if changeMetadata then variantValue encoded else changed
+  assertStable metadata bytes
+
+
+arbitraryBytesProperty :: H.Property
+arbitraryBytesProperty = H.withTests 3000 $ H.property $ do
+  metadata <- H.forAll (Gen.bytes (Range.linear 0 128))
+  bytes <- H.forAll (Gen.bytes (Range.linear 0 128))
+  assertStable metadata bytes
+
+
+assertStable :: BS.ByteString -> BS.ByteString -> H.PropertyT IO ()
+assertStable metadata bytes = case decodeVariant metadata bytes of
+  Left _ -> H.success
+  Right value -> do
+    encoded <- H.evalEither (encodeVariant value)
+    decoded <- H.evalEither (decodeVariant (variantMetadata encoded) (variantValue encoded))
+    stable <- H.evalEither (encodeVariant decoded)
+    stable H.=== encoded
diff --git a/test/VariantSchemaRegression.hs b/test/VariantSchemaRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/VariantSchemaRegression.hs
@@ -0,0 +1,97 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module VariantSchemaRegression (tests) where
+
+import Arrow.Types qualified as A
+import Control.Monad (forM_, unless)
+import Data.Either (isLeft, isRight)
+import Data.Text (Text)
+import Data.Text qualified as T
+import Data.Vector qualified as V
+import Parquet.Nested qualified as N
+import Parquet.Variant.Schema qualified as S
+
+
+leaf :: A.ArrowType -> A.Field
+leaf typ = A.defaultLeafField "typed_value" True typ
+
+
+node :: Text -> A.Field
+node name = A.defaultField name False A.AStruct (V.singleton (A.defaultLeafField "value" True A.ABinary))
+
+
+root :: [A.Field] -> A.Field
+root fields = (A.defaultField "v" True A.AStruct (V.fromList fields)) {A.fieldMetadata = S.variantExtensionMetadata}
+
+
+metadata :: A.Field
+metadata = A.defaultLeafField "metadata" False A.ABinary
+
+
+value :: A.Field
+value = A.defaultLeafField "value" True A.ABinary
+
+
+load :: Either String a -> IO a
+load = either fail pure
+
+
+check :: String -> Bool -> IO ()
+check name ok = unless ok (fail ("Variant schema regression: " ++ name))
+
+
+tests :: IO ()
+tests = do
+  let primitives = [A.ABool, A.AInt 8 True, A.AInt 16 True, A.AInt 32 True, A.AInt 64 True, A.AFloatingPoint A.Single, A.AFloatingPoint A.DoublePrecision, A.ADate A.DateDay, A.ATime A.Microsecond 64, A.ATimestamp A.Microsecond Nothing, A.ATimestamp A.Nanosecond Nothing, A.ATimestamp A.Microsecond (Just "UTC"), A.ATimestamp A.Nanosecond (Just "UTC"), A.ABinary, A.ALargeBinary, A.ABinaryView, A.AUtf8, A.ALargeUtf8, A.AUtf8View]
+      uuid = (leaf (A.AFixedSizeBinary 16)) {A.fieldMetadata = V.fromList [("ARROW:extension:name", "arrow.uuid"), ("ARROW:extension:metadata", "")]}
+  forM_ (map leaf primitives ++ [uuid]) $ \typed -> do
+    _ <- load (S.variantTypedLeaf typed)
+    schema <- load (S.variantField "v" True (Just typed))
+    check "primitive constructor emits canonical extension and fields" (S.isVariantField schema && isRight (S.validateVariantField schema))
+    check "typed-only storage is valid" (isRight (S.validateVariantField (root [metadata, typed])))
+  check "UUID maps to exact Parquet UUID physical type" (S.variantTypedLeaf uuid == Right N.LtUuid)
+  forM_ [(A.ADecimal32, 1, 9), (A.ADecimal64, 10, 18), (A.ADecimal, 19, 38)] $ \(make, low, high) -> do
+    forM_ [low .. high] $ \precision -> forM_ [0, precision] $ \scale ->
+      check "every canonical decimal precision/scale boundary maps exactly" (S.variantTypedLeaf (leaf (make precision scale)) == Right (N.LtDecimal (fromIntegral precision) (fromIntegral scale)))
+    forM_ [(low - 1, 0), (high + 1, 0), (low, -1), (low, low + 1), (maxBound, 0)] $ \(precision, scale) ->
+      check "wrong carrier or scale rejected" (isLeft (S.variantTypedLeaf (leaf (make precision scale))))
+  forM_ [A.ANull, A.AInt 8 False, A.AInt 64 False, A.AFloatingPoint A.Half, A.ADecimal256 76 0, A.ADecimal 9 0, A.ADate A.DateMillisecond, A.ATime A.Nanosecond 64, A.ATime A.Microsecond 32, A.ATimestamp A.Millisecond Nothing, A.ATimestamp A.Microsecond (Just "Europe/Amsterdam"), A.AFixedSizeBinary 16] $ \typ ->
+    check "Arrow types outside canonical table rejected" (isLeft (S.variantField "v" True (Just (leaf typ))))
+  let object = A.defaultField "typed_value" True A.AStruct (V.fromList [node "a", node "b"])
+  _ <- load (S.variantField "v" True (Just object))
+  forM_ [A.AList, A.ALargeList, A.AListView] $ \typ -> do
+    let list = A.defaultField "typed_value" True typ (V.singleton (node "element"))
+    _ <- load (S.variantField "v" False (Just list))
+    let child = (node "element") {A.fieldNullable = True}
+    check "array elements cannot be nullable wrappers" (isLeft (S.variantField "v" True (Just list {A.fieldChildren = V.singleton child})))
+  let optionalObject = object {A.fieldChildren = V.singleton ((node "a") {A.fieldNullable = True})}
+  check "object wrappers cannot be nullable" (isLeft (S.variantField "v" True (Just optionalObject)))
+  check "duplicate object field rejected" (isLeft (S.variantField "v" True (Just object {A.fieldChildren = V.fromList [node "a", node "a"]})))
+  let foreignExtension = V.singleton ("ARROW:extension:name", "arrow.parquet.file")
+  check "typed object cannot masquerade as another extension" (isLeft (S.variantField "v" True (Just object {A.fieldMetadata = foreignExtension})))
+  let huge = object {A.fieldChildren = V.generate 1000 (\i -> node (T.singleton (toEnum (65 + i))))}
+  check "field limit precedes wide object name allocation" (isLeft (S.validateVariantFieldWithLimits (S.VariantSchemaLimits 64 4) (root [metadata, huge])))
+  let ends = A.defaultLeafField "run_ends" False (A.AInt 16 True)
+      entries = A.defaultLeafField "values" False A.ABinary
+      ree = A.defaultField "metadata" False A.ARunEndEncoded (V.fromList [ends, entries])
+  check "run-end encoded metadata accepted" (isRight (S.validateVariantField (root [value, ree])))
+  check "invalid metadata run-end width rejected" (isLeft (S.validateVariantField (root [value, ree {A.fieldChildren = V.fromList [ends {A.fieldType = A.AInt 8 True}, entries]}])))
+  forM_ [8, 16, 32, 64] $ \width -> forM_ [True, False] $ \signed -> do
+    let dict = metadata {A.fieldDictionary = Just (A.DictionaryEncoding 42 (A.AInt width signed) False)}
+    check "all legal dictionary index widths accepted for metadata" (isRight (S.validateVariantField (root [value, dict])))
+  let wrongDict = metadata {A.fieldDictionary = Just (A.DictionaryEncoding 42 A.ABool False)}
+  check "metadata dictionary indices must be integers" (isLeft (S.validateVariantField (root [wrongDict, value])))
+  forM_ [root [value], root [metadata], root [metadata, value, value], root [metadata, value {A.fieldName = "Value"}], root [metadata {A.fieldNullable = True}, value], root [metadata {A.fieldType = A.AUtf8}, value], root [metadata, value {A.fieldDictionary = Just (A.DictionaryEncoding 42 (A.AInt 8 True) False)}]] $ \invalid ->
+    check "malformed storage shape rejected" (isLeft (S.validateVariantField invalid))
+  forM_ [V.empty, V.fromList [("ARROW:extension:name", "arrow.parquet.variant"), ("ARROW:extension:name", "arrow.parquet.variant")], V.fromList [("ARROW:extension:name", "arrow.parquet.variant"), ("ARROW:extension:metadata", "not empty")]] $ \extensions ->
+    check "missing/duplicate/parameterized extension rejected" (isLeft (S.validateVariantField (root [metadata, value]) {A.fieldMetadata = extensions}))
+  check "reordered and required unshredded fields accepted" (isRight (S.validateVariantField (root [value {A.fieldNullable = False}, metadata])))
+  let nested = A.defaultField "typed_value" True A.AList (V.singleton (node "element"))
+      schema = root [metadata, value, nested]
+  check "schema depth limit enforced" (isLeft (S.validateVariantFieldWithLimits (S.VariantSchemaLimits 2 100) schema))
+  check "schema field budget enforced" (isLeft (S.validateVariantFieldWithLimits (S.VariantSchemaLimits 64 2) schema))
+  let dag 0 = node "x"
+      dag n = let child = dag (n - 1); typed = A.defaultField "typed_value" True A.AStruct (V.fromList [child {A.fieldName = "left"}, child {A.fieldName = "right"}]) in A.defaultField "x" False A.AStruct (V.singleton typed)
+      shared = root [metadata, (A.defaultField "typed_value" True A.AStruct (V.singleton (dag (20 :: Int))))]
+  check "shared schema DAG cannot expand past its work budget" (isLeft (S.validateVariantFieldWithLimits (S.VariantSchemaLimits 64 100) shared))
+  putStrLn "Canonical Variant schema primitive/nesting/metadata/resource regressions passed"
diff --git a/test/VariantWriteRegression.hs b/test/VariantWriteRegression.hs
new file mode 100644
--- /dev/null
+++ b/test/VariantWriteRegression.hs
@@ -0,0 +1,168 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module VariantWriteRegression (tests) where
+
+import Arrow.Column qualified as C
+import Arrow.Types qualified as A
+import Control.Exception (evaluate)
+import Control.Monad (unless)
+import Data.ByteString qualified as BS
+import Data.Either (isLeft)
+import Data.Int (Int32)
+import Data.Map.Strict qualified as M
+import Data.Text qualified as T
+import Data.Vector qualified as V
+import Data.Vector.Storable qualified as S
+import GHC.Conc (getAllocationCounter)
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.Arrow qualified as Arrow
+import Parquet.Nested qualified as N
+import Parquet.Read qualified as Read
+import Parquet.Types qualified as P
+import Parquet.Variant qualified as B
+import Parquet.Variant.Arrow qualified as VariantArrow
+import Parquet.Variant.Parquet qualified as VP
+import Parquet.Variant.Schema qualified as Schema
+import Parquet.Variant.Shred qualified as Shred
+import VariantRegression qualified as Cases
+
+
+load :: Either String a -> IO a
+load = either fail pure
+
+
+file :: Schema.VariantStorageSchema -> V.Vector N.NestedRow -> Either String Read.ParquetFile
+file storage rows = N.buildNestedFile (V.singleton ("v", N.NSOptional (N.NSVariantTyped storage))) (V.singleton rows) >>= Read.loadParquetFile
+
+
+leaf :: BS.ByteString -> N.NestedRow
+leaf = N.NRLeaf . N.LvBinary
+
+
+tests :: IO ()
+tests = do
+  let check name good = unless good (fail ("typed Variant writer: " ++ name))
+      metadata = leaf (BS.pack [1, 0, 0])
+      int32 = A.defaultLeafField "typed_value" True (A.AInt 32 True)
+  -- Canonical fields are accessed by name, including when the column's
+  -- named children are in a different order than its declared Field.
+  plain <- load (Schema.variantField "v" True Nothing)
+  named <- load (C.mkStruct 1 Nothing (V.fromList [("value", C.fromByteStrings (V.singleton (BS.singleton 0))), ("metadata", C.fromByteStrings (V.singleton (BS.pack [1, 0, 0])))]))
+  namedSchema <- load (Arrow.arrowFieldToNestedSchema plain)
+  namedRows <- load (Arrow.columnArrayToNestedRows plain named)
+  namedBytes <- load (N.buildNestedFile (V.singleton ("v", namedSchema)) (V.singleton namedRows))
+  namedFile <- load (Read.loadParquetFile namedBytes)
+  namedValues <- load (VP.readVariantColumn namedFile 0 "v")
+  check "permuted metadata/value buffers bind by name before row lowering" (namedValues == V.singleton (Just B.VNull))
+  duplicate <- load (C.mkStruct 1 Nothing (V.fromList [("metadata", C.fromByteStrings (V.singleton (BS.pack [1, 0, 0]))), ("metadata", C.fromByteStrings (V.singleton (BS.singleton 0)))]))
+  check "duplicate named Variant children rejected before binding" (isLeft (Arrow.columnArrayToNestedRows plain duplicate) && isLeft (VariantArrow.compileVariantArrowReader plain duplicate))
+  let elementFields = V.fromList [A.defaultLeafField "value" True A.ABinary, int32]
+      elementField = A.defaultField "element" False A.AStruct elementFields
+      listField = A.defaultField "typed_value" True A.AList (V.singleton elementField)
+      namedField = (A.defaultField "v" True A.AStruct (V.fromList [A.defaultLeafField "metadata" False A.ABinary, listField])) {A.fieldMetadata = Schema.variantExtensionMetadata}
+  elementColumns <- load (C.mkStruct 2 Nothing (V.fromList [("typed_value", C.fromMaybes C.PInt32 (V.fromList [Just 3, Nothing])), ("value", C.fromMaybeByteStrings (V.fromList [Nothing, Just (BS.singleton 0)]))]))
+  listColumn <- load (C.mkList Nothing (S.fromList [0, 2 :: Int32]) elementColumns)
+  nestedNames <- load (C.mkStruct 1 Nothing (V.fromList [("typed_value", listColumn), ("metadata", C.fromByteStrings (V.singleton (BS.pack [1, 0, 0])))]))
+  directReader <- load (VariantArrow.compileVariantArrowReader namedField nestedNames)
+  directValue <- load (VariantArrow.variantArrowAt directReader 0)
+  let expectedNames = Just (B.VArray (V.fromList [B.VInt32 3, B.VNull]))
+  check "reader aligns different child types recursively before shape validation" (directValue == expectedNames)
+  nestedSchema <- load (Arrow.arrowFieldToNestedSchema namedField)
+  nestedRows <- load (Arrow.columnArrayToNestedRows namedField nestedNames)
+  nestedBytes <- load (N.buildNestedFile (V.singleton ("v", nestedSchema)) (V.singleton nestedRows))
+  nestedFile <- load (Read.loadParquetFile nestedBytes)
+  nestedValues <- load (VP.readVariantColumn nestedFile 0 "v")
+  check "writer aligns nested list element wrappers by name" (nestedValues == V.singleton expectedNames)
+  field <- load (Schema.variantField "v" True (Just int32))
+  storage <- load (Schema.compileVariantStorageSchema field)
+  let row value = N.NRStruct (V.fromList [metadata, N.NRNull, value])
+      rows = V.fromList [row (N.NRLeaf (N.LvInt32 7)), N.NRNull, row N.NRNull]
+  native <- load (file storage rows)
+  actual <- load (VP.readVariantColumn native 0 "v")
+  check "primitive, null root and implicit Variant null stay distinct" (actual == V.fromList [Just (B.VInt32 7), Nothing, Just B.VNull])
+  check "native annotation emitted" (P.seLogicalType (P.fmSchema (Read.pfFooter native) V.! 1) == Just (P.LTVariant 1))
+  let conflict = N.NRStruct (V.fromList [metadata, leaf (BS.singleton 0), N.NRLeaf (N.LvInt32 7)])
+  check "conflicting primitive storage rejected" (isLeft (file storage (V.singleton conflict)))
+  let wrapper = A.defaultField "element" False A.AStruct (V.singleton int32)
+      array = A.defaultField "typed_value" True A.AList (V.singleton wrapper)
+      root = (A.defaultField "v" True A.AStruct (V.fromList [A.defaultLeafField "metadata" False A.ABinary, array])) {A.fieldMetadata = Schema.variantExtensionMetadata}
+      elements = V.fromList [N.NRStruct (V.singleton (N.NRLeaf (N.LvInt32 3))), N.NRStruct (V.singleton N.NRNull), N.NRStruct (V.singleton N.NRNull)]
+      arrayRow = N.NRStruct (V.fromList [metadata, N.NRList elements])
+  arrays <- load (Schema.compileVariantStorageSchema root)
+  arrayFile <- load (file arrays (V.singleton arrayRow))
+  arrayValues <- load (VP.readVariantColumn arrayFile 0 "v")
+  check "typed-only arrays gain explicit null fallbacks without losing elements" (arrayValues == V.singleton (Just (B.VArray (V.fromList [B.VInt32 3, B.VNull, B.VNull]))))
+  forLimits <- load (Schema.compileVariantStorageSchemaWithLimits (B.VariantLimits 10 3 0) Schema.defaultVariantSchemaLimits root)
+  check "one budget covers typed array and materialized null elements" (isLeft (file forLimits (V.singleton arrayRow)))
+  noDepth <- load (Schema.compileVariantStorageSchemaWithLimits (B.VariantLimits 0 100 0) Schema.defaultVariantSchemaLimits root)
+  check "missing array elements still obey nesting depth" (isLeft (file noDepth (V.singleton arrayRow)))
+  let identified = field {A.fieldMetadata = A.fieldMetadata field `V.snoc` ("PARQUET:field_id", "-7"), A.fieldChildren = V.imap (\index child -> child {A.fieldMetadata = A.fieldMetadata child `V.snoc` ("PARQUET:field_id", if index == 0 then "11" else if index == 1 then "12" else "13")}) (A.fieldChildren field)}
+  ids <- load (Schema.compileVariantStorageSchema identified)
+  withIds <- load (file ids (V.singleton (row (N.NRLeaf (N.LvInt32 1)))))
+  check "field IDs preserved through native schema" (V.map P.seFieldId (V.tail (P.fmSchema (Read.pfFooter withIds))) == V.fromList [Just (-7), Just 11, Just 12, Just 13])
+  recovered <- load (Arrow.parquetFileArrowSchemaChecked withIds)
+  let recoveredField = V.head (A.arrowFields recovered)
+  check "native Arrow schema retains root and child field IDs" (V.elem ("PARQUET:field_id", "-7") (A.fieldMetadata recoveredField) && V.elem ("PARQUET:field_id", "13") (A.fieldMetadata (A.fieldChildren recoveredField V.! 2)))
+  let invalidId = field {A.fieldMetadata = A.fieldMetadata field V.++ V.fromList [("PARQUET:field_id", "1"), ("PARQUET:field_id", "2")]}
+  check "duplicate field IDs rejected" (isLeft (Schema.compileVariantStorageSchema invalidId))
+  -- Semantic selection must preserve all primitive tags, not just values
+  -- that happen to fit the target's numeric carrier.
+  target <- load (Schema.variantField "v" True (Just (A.defaultLeafField "typed_value" True (A.AInt 64 True))))
+  semantic <- load (Shred.compileVariantShredder target)
+  semanticRows <- V.mapM (load . Shred.shredVariant semantic . Just) Cases.values
+  semanticBytes <- load (N.buildNestedFile (V.singleton ("v", Shred.variantShredSchema semantic)) (V.singleton semanticRows))
+  semanticFile <- load (Read.loadParquetFile semanticBytes)
+  semanticValues <- load (VP.readVariantColumn semanticFile 0 "v")
+  actualBytes <- V.mapM (load . traverse B.encodeVariant) semanticValues
+  expectedBytes <- V.mapM (load . traverse B.encodeVariant) (Just <$> Cases.values)
+  check "semantic shreds preserve every Variant primitive/container/IEEE tag" (actualBytes == expectedBytes)
+  let decimalField = A.defaultLeafField "typed_value" True (A.ADecimal32 8 2)
+  decimalTarget <- load (Schema.variantField "v" True (Just decimalField))
+  decimalShred <- load (Shred.compileVariantShredder decimalTarget)
+  let decimalValues = V.fromList [B.VDecimal4 2 1, B.VDecimal4 3 1, B.VDecimal4 2 100000000, B.VDecimal8 2 1]
+  decimalRows <- V.mapM (load . Shred.shredVariant decimalShred . Just) decimalValues
+  decimalBytes <- load (N.buildNestedFile (V.singleton ("v", Shred.variantShredSchema decimalShred)) (V.singleton decimalRows))
+  decimalFile <- load (Read.loadParquetFile decimalBytes)
+  decimalOutput <- load (VP.readVariantColumn decimalFile 0 "v")
+  check "decimal scale, precision overflow and width mismatch use exact fallback" (decimalOutput == (Just <$> decimalValues))
+  emptyDictionary <- load (B.buildVariantMetadata V.empty)
+  objectTarget <- load (Schema.variantField "v" True (Just (A.defaultField "typed_value" True A.AStruct (V.singleton (A.defaultField "a" False A.AStruct (V.singleton int32))))))
+  objectShred <- load (Shred.compileVariantShredder objectTarget)
+  check "fully shredded names must exist in the supplied dictionary" (isLeft (Shred.shredVariantWithMetadata objectShred emptyDictionary (Just (B.VObject (M.singleton "a" (B.VInt32 1))))))
+  passed <-
+    H.check
+      ( H.withTests
+          500
+          ( H.property $ do
+              number <- H.forAll (Gen.int32 (Range.linear (-1000000) 1000000))
+              present <- H.forAll Gen.bool
+              remainder <- H.forAll Gen.bool
+              dictionary <- H.evalEither (B.buildVariantMetadata (V.fromList ["a", "rest"]))
+              let wrap = A.defaultField "a" False A.AStruct (V.singleton int32)
+                  object = A.defaultField "typed_value" True A.AStruct (V.singleton wrap)
+              objectField <- H.evalEither (Schema.variantField "v" True (Just object))
+              objectStorage <- H.evalEither (Schema.compileVariantStorageSchema objectField)
+              fragment <- H.evalEither (B.encodeVariantValue dictionary (B.VObject (if remainder then M.singleton "rest" (B.VInt8 9) else M.empty)))
+              let child = N.NRStruct (V.singleton (if present then N.NRLeaf (N.LvInt32 number) else N.NRNull))
+                  objectRow = N.NRStruct (V.fromList [leaf (B.metadataBytes dictionary), if remainder then leaf fragment else N.NRNull, N.NRStruct (V.singleton child)])
+                  expected = (if present then M.insert "a" (B.VInt32 number) else id) (if remainder then M.singleton "rest" (B.VInt8 9) else M.empty)
+              encoded <- H.evalEither (file objectStorage (V.singleton objectRow))
+              decoded <- H.evalEither (VP.readVariantColumn encoded 0 "v")
+              decoded H.=== V.singleton (Just (B.VObject expected))
+          )
+      )
+  check "generated partial objects with shared dictionaries" passed
+  dictionary <- load (B.buildVariantMetadata (V.singleton (T.replicate (1024 * 1024) "a")))
+  let bytes = B.metadataBytes dictionary
+      count = fromIntegral (maxBound :: Int32) `quot` (BS.length bytes + 4) + 1
+      oversized = V.replicate count (N.NRStruct (V.fromList [leaf bytes, N.NRNull, N.NRLeaf (N.LvInt32 1)]))
+  _ <- evaluate (BS.length bytes)
+  _ <- evaluate (V.length oversized)
+  before <- getAllocationCounter
+  rejected <- evaluate (isLeft (N.shred (N.NSOptional (N.NSVariantTyped storage)) oversized))
+  after <- getAllocationCounter
+  check "all byte preflights precede repeated dictionary decoding" rejected
+  check ("oversized typed page allocation: " ++ show (before - after)) (before - after < 8 * 1024 * 1024)
+  putStrLn "Typed Variant native writing, dictionaries, nulls, field IDs, budgets and preflight regressions passed"
diff --git a/test/WriterBounds.hs b/test/WriterBounds.hs
new file mode 100644
--- /dev/null
+++ b/test/WriterBounds.hs
@@ -0,0 +1,358 @@
+{-# LANGUAGE BangPatterns #-}
+
+module WriterBounds (run) where
+
+import Control.Exception (ErrorCall, evaluate, try)
+import Control.Monad (unless)
+import Data.Bits (setBit, shiftL, shiftR, testBit, (.&.), (.|.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.ByteString.Internal qualified as BSI
+import Data.Either (isLeft)
+import Data.Int (Int32)
+import Data.List (isInfixOf)
+import Data.Vector qualified as V
+import Data.Vector.Primitive qualified as P
+import Data.Word (Word32, Word64)
+import GHC.Conc (getAllocationCounter)
+import Hedgehog qualified as H
+import Hedgehog.Gen qualified as Gen
+import Hedgehog.Range qualified as Range
+import Parquet.LevelsEncode qualified as Levels
+import Parquet.Encryption qualified as Encryption
+import Parquet.Page qualified as Page
+import Parquet.Read qualified as Read
+import Parquet.Types (Compression (GZip, Uncompressed), ParquetType (PTByteArray), Repetition (Optional, Required), SchemaElement (..))
+import Parquet.Write qualified as Write
+
+
+check :: String -> Bool -> IO ()
+check message ok = unless ok (fail ("WriterBounds: " ++ message))
+
+
+rejects :: String -> a -> IO ()
+rejects message value = do
+  result <- try (evaluate value >> pure ()) :: IO (Either ErrorCall ())
+  check message (case result of Left err -> message `isInfixOf` show err; Right () -> False)
+
+
+run :: IO ()
+run = do
+  dictionaryBounds
+  payloadBounds
+  encryptionFramingBounds
+  hybridBounds
+  mixedHybridBounds
+  hybridAllocation
+
+
+encryptionFramingBounds :: IO ()
+encryptionFramingBounds = do
+  let key = BS.replicate 16 0x42
+      nonce = BS.replicate 12 0x11
+      -- The backing buffer is one byte: rejection must inspect only its
+      -- declared length, before attempting encryption or copying payload.
+      oversized overhead =
+        let (fp, offset, _) = BSI.toForeignPtr (BS.singleton 0)
+            limit = min (toInteger (maxBound :: Word32) - overhead) (toInteger (maxBound :: Int) - overhead - 4)
+        in BSI.fromForeignPtr fp offset (fromInteger (limit + 1))
+  check "explicit GCM rejects an unrepresentable frame before payload access" (isLeft (Encryption.encryptGcmModuleFramedWithNonce key nonce BS.empty (oversized 28)))
+  check "explicit CTR rejects an unrepresentable frame before payload access" (isLeft (Encryption.encryptCtrModuleFramedWithNonce key nonce (oversized 12)))
+  gcm <- Encryption.encryptGcmModuleFramed key BS.empty (oversized 28)
+  ctr <- Encryption.encryptCtrModuleFramed key (oversized 12)
+  check "random-nonce GCM rejects an unrepresentable frame" (isLeft gcm)
+  check "random-nonce CTR rejects an unrepresentable frame" (isLeft ctr)
+
+
+dictionaryBounds :: IO ()
+dictionaryBounds = do
+  let page entries indices = Write.encodeDictDataPage (Write.Dictionary (Write.ColInt32 (P.fromList entries)) (P.fromList indices))
+  mapM_
+    (\indices -> rejects "exceeds maximum" (BS.length (page [10, 20, 30] indices)))
+    [[-1], [3], [7], [0, 1, 3], [0, maxBound]]
+  rejects "nonempty indices require a nonempty dictionary" (BS.length (page [] [0]))
+  mapM_
+    ( \(entries, indices) -> do
+        let encoded = page entries indices
+        (header, offset) <- either fail pure (Page.readPageHeaderAt encoded 0)
+        check "valid dictionary indices survive page encoding" (Read.decodeDictionaryIndices (length indices) (BS.drop offset encoded) == Right (P.fromList indices))
+        check "dictionary header has the checked row count" (case Page.phType header of Page.PtDataPage h -> Page.dphNumValues h == fromIntegral (length indices); _ -> False)
+    )
+    [([], []), ([10], []), ([10], [0, 0]), ([10, 20, 30], [2, 0, 2])]
+
+
+payloadBounds :: IO ()
+payloadBounds = do
+  -- A shared 64 KiB source and 256 KiB of pointers request exactly 2 GiB
+  -- of PLAIN data. Failure must precede copying any of that output.
+  let bytes = BS.replicate 65532 120
+      entries = V.replicate 32768 bytes
+      column = Write.ColByteArray entries
+      optional = Write.OptByteArray (V.map Just entries)
+      dictionary = Write.Dictionary column P.empty
+  _ <- evaluate (BS.length bytes + V.length entries)
+  before <- getAllocationCounter
+  rejects "PLAIN page payload exceeds signed 32-bit limit" (BS.length (Write.encodeColumnDataPage column))
+  rejects "PLAIN page payload exceeds signed 32-bit limit" (BS.length (Write.encodeDictPage dictionary))
+  rejects "PLAIN page payload exceeds signed 32-bit limit" (BS.length (Write.encodeOptionalColumnPage optional))
+  check "required V2 returns its payload size failure" (case Write.encodeColumnDataPageV2 Uncompressed column of Left err -> "signed 32-bit limit" `isInfixOf` err; _ -> False)
+  check "optional V2 returns its payload size failure" (case Write.encodeOptionalColumnPageV2 Uncompressed optional of Left err -> "signed 32-bit limit" `isInfixOf` err; _ -> False)
+  after <- getAllocationCounter
+  check "oversized writer payloads fail without a large allocation" (before - after < 4 * 1024 * 1024)
+  let poisoned = V.snoc entries (error "inspected beyond overflowing payload")
+  rejects "PLAIN page payload exceeds signed 32-bit limit" (BS.length (Write.encodeColumnDataPage (Write.ColByteArray poisoned)))
+  -- The values alone fit. Their definition levels push both V1 and V2
+  -- over the page limit, so neither may materialize the near-2-GiB values.
+  let almost = Write.OptByteArray (V.map Just (V.snoc (V.take 32767 entries) (BS.replicate 65529 120)))
+  rejects "page payload exceeds signed 32-bit limit" (BS.length (Write.encodeOptionalColumnPage almost))
+  check "V2 includes level bytes in its size preflight" (case Write.encodeOptionalColumnPageV2 Uncompressed almost of Left err -> "page payload exceeds signed 32-bit limit" `isInfixOf` err; _ -> False)
+  mapM_
+    ( \version ->
+        mapM_
+          ( \codec ->
+              mapM_
+                ( \nullable -> do
+                    let schema =
+                          V.fromList
+                            [ SchemaElement "schema" Nothing Nothing (Just 1) Nothing Nothing Nothing Nothing
+                            , SchemaElement "x" (Just (if nullable then Optional else Required)) (Just PTByteArray) Nothing Nothing Nothing Nothing Nothing
+                            ]
+                        values = if nullable then Write.PCOptional optional else Write.PCRequired column
+                        options = Write.emptyColumnAux {Write.caCodec = codec, Write.caPageVersion = version}
+                        result = Write.buildParquetFileMixedWithAux schema (V.singleton (V.singleton values)) (V.singleton (V.singleton options))
+                    check "checked mixed writers return size errors rather than throwing" (case result of Left err -> "signed 32-bit limit" `isInfixOf` err; _ -> False)
+                )
+                [False, True]
+          )
+          [Uncompressed, GZip]
+    )
+    [Write.PageV1, Write.PageV2]
+
+
+hybridBounds :: IO ()
+hybridBounds = do
+  passed <- H.check $ H.withTests 300 $ H.property $ do
+    width <- H.forAll (Gen.int (Range.linear 0 32))
+    count <- H.forAll (Gen.int (Range.linear 0 257))
+    prefix <- H.forAll (Gen.int (Range.linear 1 17))
+    words32 <- H.forAll (Gen.list (Range.singleton count) (Gen.word32 Range.constantBounded))
+    let mask = fromIntegral (((1 :: Word64) `shiftL` width) - 1) :: Word32
+        values = P.fromList (map (fromIntegral . (.&. mask)) words32)
+        sliced = P.slice prefix count (P.replicate prefix (-1) P.++ values P.++ P.singleton (-1))
+        encoded = Levels.encodeRLEHybrid width sliced
+        prefixed = Levels.encodeLengthPrefixedHybrid width sliced
+    plan <- H.evalEither (Levels.planRLEHybrid width mask sliced)
+    encoded H.=== referenceHybrid width values
+    Levels.hybridEncodedSize plan H.=== BS.length encoded
+    Levels.encodeHybridPlan plan H.=== encoded
+    Read.decodeDictionaryIndices count (BS.cons (fromIntegral width) encoded) H.=== Right values
+    prefixed H.=== if width == 0 then BS.empty else littleEndian32 (fromIntegral (BS.length encoded)) <> encoded
+  check "hybrid streams match independent bit-position packing on sliced inputs" passed
+  -- Include all widths deterministically, and exercise high unsigned bits
+  -- stored in Int32, constant streams, padding boundaries and empty input.
+  mapM_
+    ( \width -> do
+        let mask = fromIntegral (((1 :: Word64) `shiftL` width) - 1) :: Word32
+        mapM_
+          ( \count ->
+              mapM_
+                (\values -> check "all widths and padding counts match independent bytes" (Levels.encodeRLEHybrid width values == referenceHybrid width values))
+                [P.replicate count (fromIntegral mask), P.generate count (\i -> fromIntegral (fromIntegral i .&. mask))]
+          )
+          [0, 1, 2, 7, 8, 9, 15, 16, 17, 127, 128, 129]
+    )
+    [0 .. 32]
+  mapM_
+    ( \width -> do
+        check "empty input still validates width" (case Levels.planRLEHybrid width 0 P.empty of Left _ -> True; _ -> False)
+        rejects "bit width out of range" (BS.length (Levels.encodeRLEHybrid width P.empty))
+    )
+    [-1, 33, maxBound]
+  rejects "negative maximum value" (Levels.bitWidthFor (-1))
+  rejects "exceeds maximum" (BS.length (Levels.encodeRLEHybrid 0 (P.singleton 1)))
+  rejects "exceeds maximum" (BS.length (Levels.encodeRLEHybrid 31 (P.singleton (-1))))
+  check "semantic maximum is checked independently of width" (case Levels.planRLEHybrid 2 2 (P.singleton 3) of Left _ -> True; _ -> False)
+  check "maximum must fit declared width" (case Levels.planRLEHybrid 1 2 P.empty of Left _ -> True; _ -> False)
+  check "a semantic bound is not treated as a contiguous bit mask" (case Levels.planRLEHybrid 4 10 (P.fromList [10, 7, 10, 7]) of Right _ -> True; _ -> False)
+  mapM_
+    ( \width ->
+        mapM_
+          ( \prefix ->
+              mapM_
+                ( \count ->
+                    mapM_
+                      ( \row -> do
+                          let bad = fromIntegral ((1 :: Word32) `shiftL` width)
+                              values = P.replicate count 0 P.// [(row, bad)]
+                              sliced = P.slice prefix count (P.replicate prefix (-1) P.++ values P.++ P.singleton (-1))
+                          check "paired range checks inspect every logical lane and report its row" (case Levels.planRLEHybrid width (fromIntegral (((1 :: Word64) `shiftL` width) - 1)) sliced of Left err -> ("row " ++ show row ++ " exceeds") `isInfixOf` err; _ -> False)
+                      )
+                      [0 .. count - 1]
+                )
+                [1 .. 33]
+          )
+          [0 .. 3]
+    )
+    [1, 7, 8, 9, 16, 31]
+  check "repeated plans reject a negative count" (case Levels.planRepeatedRLEHybrid 1 (-1) 0 of Left _ -> True; _ -> False)
+  check "repeated plans reject an oversized value" (case Levels.planRepeatedRLEHybrid 1 1 2 of Left _ -> True; _ -> False)
+  mapM_
+    ( \count ->
+        mapM_
+          ( \width -> do
+              let value = if width == 0 then 0 else (1 :: Word32) `shiftL` (width - 1)
+              plan <- either fail pure (Levels.planRepeatedRLEHybrid width count value)
+              let encoded = Levels.encodeHybridPlan plan
+              check "large repeated plans split into legal runs" (encoded == referenceRepeated width count value)
+              check "large repeated plans size their complete output" (BS.length encoded == Levels.hybridEncodedSize plan)
+          )
+          [0, 1, 7, 8, 9, 31, 32]
+    )
+    [0, 1, 63, 64, 127, 128, 2147483646, 2147483647, 2147483648, 4294967295]
+
+
+-- The independent oracle addresses every output bit by its absolute
+-- position, rather than sharing the encoder's accumulator/flush loop.
+referenceHybrid :: Int -> P.Vector Int32 -> ByteString
+referenceHybrid width values
+  | P.null values = BS.empty
+  | P.all (== P.head values) values = referenceRepeated width (P.length values) (fromIntegral (P.head values))
+  | otherwise = split (P.toList values) []
+  where
+    minimumCount = if width == 1 then 16 else 8
+    flush = referencePacked width . P.fromList . reverse
+    split [] pending = flush pending
+    split remaining@(first : _) pending =
+      let (same, rest) = span (== first) remaining
+      in if length same >= minimumCount || (null rest && (width /= 1 || length same >= 9))
+           then flush pending <> referenceRepeated width (length same) (fromIntegral first) <> split rest []
+           else let (group, tailValues) = splitAt 8 remaining in split tailValues (reverse group ++ pending)
+
+
+referencePacked :: Int -> P.Vector Int32 -> ByteString
+referencePacked width values
+  | P.null values = BS.empty
+  | otherwise =
+      let groups = (P.length values + 7) `quot` 8
+          byteAt byte = foldl bitAt 0 [0 .. 7]
+            where
+              bitAt acc bit =
+                let (row, valueBit) = (byte * 8 + bit) `quotRem` width
+                in if row < P.length values && testBit (values P.! row) valueBit then setBit acc bit else acc
+      in unsignedVarint (fromIntegral (groups * 2 + 1)) <> BS.pack (map byteAt [0 .. groups * width - 1])
+
+
+referenceRepeated :: Int -> Int -> Word32 -> ByteString
+referenceRepeated width count value
+  | count == 0 = BS.empty
+  | otherwise =
+      let here = min count 2147483647
+          bytes = (width + 7) `quot` 8
+      in unsignedVarint (fromIntegral here * 2)
+           <> BS.pack (map (\byte -> fromIntegral (value `shiftR` (byte * 8))) [0 .. bytes - 1])
+           <> referenceRepeated width (count - here) value
+
+
+unsignedVarint :: Word64 -> ByteString
+unsignedVarint value
+  | value < 128 = BS.singleton (fromIntegral value)
+  | otherwise = BS.cons (fromIntegral (value .&. 127) .|. 128) (unsignedVarint (value `shiftR` 7))
+
+
+littleEndian32 :: Word32 -> ByteString
+littleEndian32 value = BS.pack (map (\shift -> fromIntegral (value `shiftR` shift)) [0, 8, 16, 24])
+
+
+hybridAllocation :: IO ()
+hybridAllocation = do
+  let values = P.generate 65536 (\i -> fromIntegral (i * 1664525 + 1013904223))
+  _ <- evaluate (P.foldl' (+) 0 values)
+  before <- getAllocationCounter
+  size <- evaluate (BS.length (Levels.encodeRLEHybrid 32 values))
+  after <- getAllocationCounter
+  check "packed hybrid allocation stays near its final payload" (before - after < fromIntegral size + 8192)
+  mapM_
+    ( \width ->
+        mapM_
+          ( \raw -> do
+              let mask = fromIntegral (((1 :: Word64) `shiftL` width) - 1) :: Int32
+                  mixed = P.map (.&. mask) raw
+              _ <- evaluate (P.foldl' (+) 0 mixed)
+              beforeMixed <- getAllocationCounter
+              mixedSize <- evaluate (BS.length (Levels.encodeRLEHybrid width mixed))
+              afterMixed <- getAllocationCounter
+              check "mixed hybrid runs do not allocate segment lists or per-group closures" (beforeMixed - afterMixed < fromIntegral mixedSize + 8192)
+          )
+          ( map (\block -> P.generate 65536 (\i -> fromIntegral (i `quot` block))) [8, 64]
+              ++ [P.generate 65536 (\i -> fromIntegral (if i `rem` 16 < 8 then i else i `quot` 16))]
+          )
+    )
+    [1, 2, 9, 31, 32]
+
+
+mixedHybridBounds :: IO ()
+mixedHybridBounds = do
+  mapM_
+    ( \width -> do
+        let minimumCount = if width == 1 then 16 else 8
+            middleMismatch = P.generate minimumCount (\i -> if i == minimumCount `quot` 2 then 1 else 0)
+            lastMismatch = P.generate minimumCount (\i -> if i == minimumCount - 1 then 1 else 0)
+        mapM_
+          ( \prefix -> do
+              let values = prefix P.++ P.replicate 64 1 P.++ P.fromList [0, 1, 0]
+                  encoded = Levels.encodeRLEHybrid width values
+              check "run lookahead checks matching endpoints against the full interior" (encoded == referenceHybrid width values)
+              check "run lookahead preserves values and short final tails" (Read.decodeDictionaryIndices (P.length values) (BS.cons (fromIntegral width) encoded) == Right values)
+          )
+          [middleMismatch, lastMismatch]
+    )
+    [1 .. 32]
+  passed <- H.check $ H.withTests 300 $ H.property $ do
+    width <- H.forAll (Gen.int (Range.linear 1 32))
+    pieces <- H.forAll (Gen.list (Range.linear 0 32) (Gen.either (Gen.word32 Range.constantBounded) (Gen.word32 Range.constantBounded)))
+    runLengths <- H.forAll (Gen.list (Range.singleton (length pieces)) (Gen.int (Range.linear 1 96)))
+    prefix <- H.forAll (Gen.int (Range.linear 0 23))
+    let mask = fromIntegral (((1 :: Word64) `shiftL` width) - 1) :: Word32
+        chunk piece count = case piece of
+          Left value -> replicate count (fromIntegral (value .&. mask))
+          Right value -> map (\i -> fromIntegral ((value + fromIntegral i * 1664525) .&. mask)) [0 .. count - 1]
+        values = P.fromList (concat (zipWith chunk pieces runLengths))
+        sliced = P.slice prefix (P.length values) (P.replicate prefix (-1) P.++ values P.++ P.singleton (-1))
+        encoded = Levels.encodeRLEHybrid width sliced
+    plan <- H.evalEither (Levels.planRLEHybrid width mask sliced)
+    encoded H.=== referenceHybrid width values
+    Levels.hybridEncodedSize plan H.=== BS.length encoded
+    Read.decodeDictionaryIndices (P.length values) (BS.cons (fromIntegral width) encoded) H.=== Right values
+  check "mixed streams preserve arbitrary run lengths, slices and transitions" passed
+  mapM_
+    ( \width ->
+        mapM_
+          ( \prefix ->
+              mapM_
+                ( \count -> do
+                    let mask = fromIntegral (((1 :: Word64) `shiftL` width) - 1) :: Word32
+                        values =
+                          P.fromList
+                            ( map (\i -> fromIntegral (fromIntegral i .&. mask)) [0 .. prefix - 1]
+                                ++ replicate count (fromIntegral mask)
+                                ++ [0, fromIntegral mask, 0]
+                                ++ replicate (count + 1) (fromIntegral mask)
+                            )
+                        encoded = Levels.encodeRLEHybrid width values
+                    check "all mixed-run boundaries match independent bytes" (encoded == referenceHybrid width values)
+                    check "interior packed padding never inserts extra values" (Read.decodeDictionaryIndices (P.length values) (BS.cons (fromIntegral width) encoded) == Right values)
+                )
+                [7, 8, 9, 15, 16, 17, 23, 24, 31, 32, 33, 63, 64, 65]
+          )
+          [0 .. 15]
+    )
+    [1 .. 32]
+  mapM_
+    ( \width -> do
+        let mask = fromIntegral (((1 :: Word64) `shiftL` width) - 1) :: Int32
+            values = P.generate 65536 (\i -> fromIntegral (i `quot` 64) .&. mask)
+            encoded = Levels.encodeRLEHybrid width values
+            valueBytes = (width + 7) `quot` 8
+        check "sixty-four-value blocks use one compact repeated run each" (BS.length encoded == 1024 * (2 + valueBytes))
+    )
+    [1, 8, 16, 24, 32]
diff --git a/test/fixtures/bloom_and_index.parquet b/test/fixtures/bloom_and_index.parquet
new file mode 100644
Binary files /dev/null and b/test/fixtures/bloom_and_index.parquet differ
diff --git a/test/fixtures/file-zero-root-0-optional.parquet b/test/fixtures/file-zero-root-0-optional.parquet
new file mode 100644
Binary files /dev/null and b/test/fixtures/file-zero-root-0-optional.parquet differ
diff --git a/test/fixtures/file-zero-root-0-required.parquet b/test/fixtures/file-zero-root-0-required.parquet
new file mode 100644
Binary files /dev/null and b/test/fixtures/file-zero-root-0-required.parquet differ
diff --git a/test/fixtures/file-zero-root-3-optional.parquet b/test/fixtures/file-zero-root-3-optional.parquet
new file mode 100644
Binary files /dev/null and b/test/fixtures/file-zero-root-3-optional.parquet differ
diff --git a/test/fixtures/file-zero-root-3-required.parquet b/test/fixtures/file-zero-root-3-required.parquet
new file mode 100644
Binary files /dev/null and b/test/fixtures/file-zero-root-3-required.parquet differ
diff --git a/test/fixtures/file-zero-with-anchor.parquet b/test/fixtures/file-zero-with-anchor.parquet
new file mode 100644
Binary files /dev/null and b/test/fixtures/file-zero-with-anchor.parquet differ
diff --git a/test/fixtures/mixed_types.parquet b/test/fixtures/mixed_types.parquet
new file mode 100644
Binary files /dev/null and b/test/fixtures/mixed_types.parquet differ
diff --git a/test/fixtures/simple_int.parquet b/test/fixtures/simple_int.parquet
new file mode 100644
Binary files /dev/null and b/test/fixtures/simple_int.parquet differ
diff --git a/wireform-parquet.cabal b/wireform-parquet.cabal
new file mode 100644
--- /dev/null
+++ b/wireform-parquet.cabal
@@ -0,0 +1,412 @@
+cabal-version: 3.0
+name: wireform-parquet
+version: 0.1.0.0
+synopsis: Apache Parquet metadata, column pages, and read/write
+description:
+  Read and write Apache Parquet files, with column-page codecs,
+  Arrow column conversion, schema derivation, statistics, bloom filters,
+  and predicate pushdown.
+category: Codec
+homepage: https://github.com/iand675/wireform-
+bug-reports: https://github.com/iand675/wireform-/issues
+license: BSD-3-Clause
+license-file: LICENSE
+author: Ian Duncan
+maintainer: ian@iankduncan.com
+copyright: 2026 Ian Duncan
+build-type: Simple
+extra-source-files:
+  README.md
+  DEVELOPING.md
+  scripts/*.py
+  scripts/*.rs
+  scripts/*.lock
+  scripts/parquet_encrypted_reference.cc
+  test/fixtures/*.parquet
+
+-- Compression codec flags. Defaults are ON so out-of-the-box
+-- wireform can read what every other Parquet engine writes by
+-- default (pyarrow + duckdb default to Snappy; polars defaults
+-- to ZSTD; LZ4 / brotli are common enough on modern files).
+-- Disable with @-f-snappy@ etc. if you want a smaller dep tree.
+flag snappy
+  description: Snappy decompression for Parquet column chunks
+  manual: True
+  default: True
+
+flag zstd
+  description: Zstandard decompression for Parquet column chunks
+  manual: True
+  default: True
+
+flag lz4
+  description: Raw and legacy Hadoop LZ4 decompression for Parquet column chunks
+  manual: True
+  default: True
+
+flag brotli
+  description: Native Brotli compression and bounded decompression for Parquet pages
+  manual: True
+  default: False
+
+common defaults
+  ghc-options:
+    -Wall
+    -Wcompat
+    -Widentities
+    -Wincomplete-record-updates
+    -Wincomplete-uni-patterns
+    -Wpartial-fields
+    -Wredundant-constraints
+    -O2
+  default-language: GHC2021
+  default-extensions:
+    StrictData
+    DerivingStrategies
+    DeriveGeneric
+    DeriveAnyClass
+    OverloadedStrings
+    LambdaCase
+
+library
+  import: defaults
+  hs-source-dirs: src
+  exposed-modules:
+    Parquet
+    Parquet.Aggregate
+    Parquet.Alp
+    Parquet.BloomFilter
+    Parquet.Compress
+    Parquet.Delta
+    Parquet.ByteStreamSplit
+    Parquet.DeltaEncode
+    Parquet.Derive
+    Parquet.Encryption
+    Parquet.Decryption
+    Parquet.Footer
+    Parquet.File
+    Parquet.Variant
+    Parquet.Variant.Parquet
+    Parquet.Variant.Schema
+    Parquet.Variant.Shred
+    Parquet.Variant.Arrow
+    Parquet.Arrow
+    Parquet.HighLevel
+    Parquet.Levels
+    Parquet.LevelsEncode
+    Parquet.Nested
+    Parquet.NullPagesBitmap
+    Parquet.Page
+    Parquet.PageIndex
+    Parquet.Predicate
+    Parquet.Read
+    Parquet.Thrift.Schema
+    Parquet.Types
+    Parquet.Timestamp
+    Parquet.Write
+  other-modules:
+    Parquet.Decimal
+    Parquet.GZip
+    Parquet.Timestamp.Internal
+    Parquet.RLE
+    Parquet.Arrow.Nested
+    Parquet.Arrow.Geospatial
+    Parquet.Arrow.File
+    Parquet.Nested.Fast
+    Parquet.Nested.Plain
+    Parquet.Nested.Statistics
+    Parquet.Write.Encrypted
+    Parquet.Nested.Bloom
+    Parquet.Nested.Types
+    Parquet.Nested.Generate
+    Parquet.Variant.Array
+    Parquet.Variant.Nested
+  extra-libraries: z
+  build-depends:
+    base >= 4.20 && < 5,
+    aeson >= 2.1 && < 2.4,
+    wireform-core >= 0.3 && < 0.4,
+    wireform-columnar-core == 0.1.*,
+    wireform-arrow == 0.1.*,
+    wireform-derive == 0.2.*,
+    wireform-thrift == 0.1.*,
+    bytestring >= 0.11 && < 0.13,
+    text >= 2.0 && < 2.2,
+    vector >= 0.13 && < 0.14,
+    primitive >= 0.7 && < 0.10,
+    containers >= 0.7 && < 0.9,
+    zlib >= 0.6 && < 0.8,
+    deepseq >= 1.4 && < 1.6,
+    crypton >= 2.2.6 && < 2.3,
+    ram >= 0.20.1 && < 0.23,
+    template-haskell >= 2.18 && < 2.25
+
+  if flag(snappy)
+    cpp-options: -DHAVE_SNAPPY
+    build-depends: snappy >= 0.2 && < 0.3
+  if flag(zstd)
+    cpp-options: -DHAVE_ZSTD
+    build-depends: zstd >= 0.1 && < 0.2
+  -- LZ4 support is provided by Columnar.LZ4 (FFI bindings to
+  -- system liblz4 from wireform-columnar-core). The Cabal flag
+  -- still gates the codec at compile time so callers can drop
+  -- it; the package dep stays via wireform-columnar-core regardless,
+  -- so the only thing this controls is whether 'tryLZ4Raw' is
+  -- compiled in.
+  if flag(lz4)
+    cpp-options: -DHAVE_LZ4
+  if flag(brotli)
+    cpp-options: -DHAVE_BROTLI
+    other-modules: Parquet.Brotli
+    pkgconfig-depends:
+      libbrotlidec >= 1.0 && < 2,
+      libbrotlienc >= 1.0 && < 2
+
+test-suite wireform-parquet-test
+  import: defaults
+  ghc-options: -threaded
+  type: exitcode-stdio-1.0
+  main-is: Main.hs
+  hs-source-dirs: test
+  other-modules:
+    MetadataRegression
+    DecimalCapacityRegression
+    NestedPrimitiveRegression
+    TimestampRegression
+    SchemaBoundaryRegression
+    CodecBoundaryRegression
+    BloomBuilderRegression
+    NestedStatisticsRegression
+    NestedOptionsRegression
+    EncryptedWriterRegression
+    EncryptedReadRegression
+    EncryptionFooterRegression
+    LargeOffsetRegression
+    GeospatialRegression
+    FileRegression
+    FileArrowRegression
+    FileZeroRegression
+    VariantRegression
+    VariantSchemaRegression
+    VariantArrowRegression
+    VariantWriteRegression
+    VariantParquetRegression
+    Aggregate
+    AlpRegression
+    Selection
+    WriterBounds
+  build-depends:
+    base >= 4.20 && < 5,
+    aeson >= 2.1 && < 2.4,
+    wireform-core,
+    wireform-arrow,
+    wireform-columnar-core,
+    wireform-parquet,
+    wireform-thrift == 0.1.*,
+    bytestring >= 0.11 && < 0.13,
+    text >= 2.0 && < 2.2,
+    vector >= 0.13 && < 0.14,
+    primitive >= 0.7 && < 0.10,
+    crypton >= 2.2.6 && < 2.3,
+    filepath,
+    directory >= 1.3 && < 1.4,
+    containers >= 0.7 && < 0.9,
+    process >= 1.6 && < 1.7,
+    hedgehog >= 1.4 && < 1.8
+  if flag(brotli)
+    cpp-options: -DHAVE_BROTLI
+
+  if flag(lz4)
+    cpp-options: -DHAVE_LZ4
+
+test-suite wireform-parquet-derive-test
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: test-derive
+  main-is: Main.hs
+  other-modules:
+    Test.Parquet.Derive
+    Test.Parquet.Derive.Types
+    Test.Parquet.Derive.Instances
+  default-extensions:
+    ScopedTypeVariables
+    TemplateHaskell
+  build-depends:
+    base,
+    wireform-parquet,
+    wireform-derive,
+    template-haskell,
+    text,
+    vector,
+    bytestring,
+    sydtest
+
+executable wireform-parquet-interop-probe
+  import: defaults
+  hs-source-dirs: probe
+  main-is: Probe.hs
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-arrow,
+    wireform-parquet,
+    crypton >= 2.2.6 && < 2.3,
+    bytestring >= 0.11 && < 0.13,
+    directory >= 1.3 && < 1.4,
+    filepath >= 1.4 && < 1.6,
+    text >= 2.0 && < 2.2,
+    vector >= 0.13 && < 0.14
+
+executable wireform-parquet-reverse-probe
+  import: defaults
+  ghc-options: -rtsopts
+  hs-source-dirs: probe
+  main-is: Reverse.hs
+  build-depends:
+    aeson >= 2.1 && < 2.4,
+    containers >= 0.7 && < 0.9,
+    crypton >= 2.2.6 && < 2.3,
+    base >= 4.20 && < 5,
+    wireform-arrow,
+    wireform-parquet,
+    deepseq >= 1.4 && < 1.6,
+    bytestring >= 0.11 && < 0.13,
+    directory >= 1.3 && < 1.4,
+    filepath >= 1.4 && < 1.6,
+    text >= 2.0 && < 2.2,
+    vector >= 0.13 && < 0.14
+
+benchmark parquet-bench
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: Bench.hs
+  other-modules: XXH64Pure
+  ghc-options: -O2
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-core,
+    wireform-parquet,
+    bytestring >= 0.11 && < 0.13,
+    criterion >= 1.5 && < 1.7
+
+benchmark parquet-selection-throughput
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: SelectionThroughput.hs
+  ghc-options: -O2 -rtsopts
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-arrow,
+    wireform-parquet,
+    bytestring >= 0.11 && < 0.13,
+    criterion >= 1.5 && < 1.7,
+    deepseq >= 1.4 && < 1.6,
+    filepath >= 1.4 && < 1.6,
+    text >= 2.0 && < 2.2,
+    vector >= 0.13 && < 0.14
+
+benchmark parquet-delta-throughput
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: DeltaThroughput.hs
+  ghc-options: -O2 -rtsopts
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-parquet,
+    criterion >= 1.5 && < 1.7,
+    deepseq >= 1.4 && < 1.6,
+    vector >= 0.13 && < 0.14
+
+benchmark parquet-dictionary-throughput
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: DictionaryThroughput.hs
+  ghc-options: -O2 -rtsopts
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-parquet,
+    bytestring >= 0.11 && < 0.13,
+    criterion >= 1.5 && < 1.7,
+    deepseq >= 1.4 && < 1.6,
+    primitive >= 0.9 && < 0.10,
+    vector >= 0.13 && < 0.14
+
+benchmark parquet-rle-throughput
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: RleThroughput.hs
+  ghc-options: -O2 -rtsopts
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-parquet,
+    bytestring >= 0.11 && < 0.13,
+    criterion >= 1.5 && < 1.7,
+    vector >= 0.13 && < 0.14
+
+benchmark parquet-byte-stream-split-throughput
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: ByteStreamSplitThroughput.hs
+  ghc-options: -O2 -rtsopts
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-parquet,
+    bytestring >= 0.11 && < 0.13,
+    criterion >= 1.5 && < 1.7,
+    deepseq >= 1.4 && < 1.6,
+    vector >= 0.13 && < 0.14
+
+benchmark parquet-alp-throughput
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: AlpThroughput.hs
+  ghc-options: -O2 -rtsopts
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-parquet,
+    bytestring >= 0.11 && < 0.13,
+    criterion >= 1.5 && < 1.7,
+    deepseq >= 1.4 && < 1.6,
+    filepath >= 1.4 && < 1.6,
+    vector >= 0.13 && < 0.14
+
+benchmark parquet-throughput
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: Throughput.hs
+  ghc-options: -O2 -rtsopts
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-arrow,
+    wireform-parquet,
+    bytestring >= 0.11 && < 0.13,
+    criterion >= 1.5 && < 1.7,
+    deepseq >= 1.4 && < 1.6,
+    directory >= 1.3 && < 1.4,
+    filepath >= 1.4 && < 1.6,
+    text >= 2.0 && < 2.2,
+    vector >= 0.13 && < 0.14
+
+
+benchmark parquet-encryption-throughput
+  import: defaults
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: EncryptionThroughput.hs
+  ghc-options: -O2 -rtsopts
+  build-depends:
+    base >= 4.20 && < 5,
+    wireform-parquet,
+    bytestring >= 0.11 && < 0.13,
+    criterion >= 1.5 && < 1.7,
+    directory >= 1.3 && < 1.4,
+    filepath >= 1.4 && < 1.6,
+    text >= 2.0 && < 2.2,
+    vector >= 0.13 && < 0.14