Skip to content

Instantly share code, notes, and snippets.

@ChristopherWirt
Created October 31, 2026 13:44
Show Gist options
  • Select an option

  • Save ChristopherWirt/411be728b5bbd4849a2f2d28d9ae0331 to your computer and use it in GitHub Desktop.

Select an option

Save ChristopherWirt/411be728b5bbd4849a2f2d28d9ae0331 to your computer and use it in GitHub Desktop.
QC Vortex: frozen list layout, recursive Spark pruning, and upstream compatibility gates

QC Vortex: frozen list storage, recursive Spark pruning, and upstream upgrade safety

Status: proposed implementation and release plan, based on a read-only source audit on 31 October 2026. No implementation, Rust/Gradle build, integration run, or fuzz campaign was performed for this document. Findings explicitly distinguish observed source behavior, suspected defects requiring reproduction, and proposed policy.

1. Decision and intended outcome

QC can ship recursive list-leaf pruning without waiting for upstream to freeze vortex.list, but QC must establish and maintain its own persisted-data contract. The recommended first storage profile is one explicitly selected frozen upstream core edition plus a QC-owned list layout, with every other unstable/preview component disabled for production writes.

A frozen edition declaration alone is insufficient. The deliverable is the combination of a written wire contract, a retained decoder, constrained writers, immutable fixtures, cross-version tests using actual released binaries, release artifacts, and a required upstream-upgrade gate.

There are two separate completion milestones:

  1. Storage milestone: QC files remain readable and candidate QC writers remain readable by every supported QC reader, across the supported datatype and storage profile. List layout has a released, frozen QC contract.
  2. Pruning milestone: Spark requests and physically reads the necessary leaves through arbitrary supported nesting and expression shapes, on V1 and V2 file-source paths. Correct reads alone do not meet this milestone; tests must prove omitted leaves are not requested.

Freezing the storage contract does not require finishing all Catalyst optimizations. It does require validating that the chosen representation can support the nested structures and read operations we intend to add. Missing Spark planner support can be implemented after the freeze without changing the bytes.

“All nesting” in this plan covers arbitrary compositions of structs and variable-length lists, and includes a separate map-crossing workstream. It is not a claim that current Spark or the current map writer already supports this. Fixed-size lists, extension types, and other logical types need an explicit support decision; rejection is preferable to silent reinterpretation.

2. Reproducible baseline and evidence

Use these as research references, not as an automatic recommendation to ship an unreleased branch unchanged:

Source Audited commit Role
Upstream develop 96fc43dfc6fc30676c27482b2e99f15605819704 Current upstream formats, editions and compatibility infrastructure
QC develop 0d6492bb453ad3433bb7a3d5760b1633d1e8de3b Current fork baseline; still uses the older connector
Upstream FileFormat PR #9658 9c802c39b470c9f10132e90f80b43e49413d5124 Assumed future connector base
QC integration PR #35 2196b90bf5997ec4dbf0914ba51beecbd1443a9d FileFormat plus QC's existing fixes and array-pruning work

Links: upstream FileFormat #9658, QC integration #35.

Assume #9658 merges in the week beginning 2 November 2026, as requested. Rebase the relevant QC feature commits onto its actual merged result, then record the resulting SHA. Do not use the merge date as a storage-stability signal. PR #35 describes itself as an integration branch, not something to merge wholesale; select and preserve its relevant fixes as reviewable commits.

The list layout's mod.rs is identical between the audited upstream and QC FileFormat snapshots. QC carries additional reader/projection work. The current published documentation can lag develop: for example, the audited preview declaration now includes vortex.uncompressed_size_in_bytes, while the web registry still described preview as empty. Derive the production manifest from the pinned source and actual emitted files.

Primary source anchors:

3. Define the QC contract before implementing it

Create a decision record owned by the QC storage maintainers. Resolve the following before the first production writer is released:

Decision Proposed default Evidence required
Core base Explicit core2026.08.3 Manifest from pinned source; all required readers/plugins present; compatibility matrix passes
QC edition family qc, origin naming the QC Vortex distribution Registered family, immutable generated record, actual released QC version
First QC list wire ID qc.list.v1 (candidate name) Writer emits it; dedicated compatible reader resolves it; upstream vortex.list is distinct
QC edition ID Choose date at actual freeze, e.g. qc2026.11.0 only if released in November Do not predeclare a hypothetical release as frozen
Minimum QC reader First actual released QC build supporting the complete profile Retained release artifact, full SHA/digest, cross-version evidence
Writer permission set Frozen core plus the QC layout; no unstable or preview edition Output audit and negative tests
Storage type scope Spark-supported types actually required by QC; lists/structs explicitly recursive Written type/value-domain table and positive/negative tests
Map scope Whole-map reads initially possible; complete leaf pruning through maps is a separate milestone Explicit status in release notes; no claim of universal pruning before it is done
Native scan executor Proven list-capable executor, with deterministic fallback where necessary End-to-end tests that identify the executor actually used
Existing experimental files Inventory and migrate using their matching retained reader No blanket compatibility promise for all historical vortex.list bytes

core2026.08.3 is a practical proposal because the current JNI session uses it. Its recorded upstream minimum of 0.85.0 does not imply that upstream 0.85.0 can read QC's new layout. The QC storage profile needs a separate QC minimum and a compatible container/DType implementation. Upstream-only readers will ordinarily reject qc.list.v1 unless the QC plugin is installed.

Publish the exact guarantee: later supported QC readers retain the frozen decoder; writers targeting this profile emit only contracts that all supported QC readers understand. Distinguish this from API compatibility, performance guarantees, arbitrary upstream-reader interoperability, and byte-identical compression output.

Assign an owner for protocol decisions, a native implementation owner, a Spark owner, and a release/compatibility owner. Names can be filled in during planning; do not leave compatibility ownership implicit.

4. Which other layouts and encodings do we freeze against?

The list layout is only the outer structural node. Its offsets, validity and elements are recursively stored through other layouts and array encodings. Freeze the transitive serialized dependency contract, rather than pinning a single list source file.

4.1 Production baseline

Select the contracts permitted by core2026.08.3 and record the full expanded set in a QC storage-profile manifest. The layout set in that frozen core record is:

  • vortex.flat
  • vortex.chunked
  • vortex.struct
  • vortex.dict
  • vortex.stats
  • vortex.zoned

These serve different purposes. flat stores array segments; the primitive values inside those segments use array wire formats, not a special “primitive layout.” Struct and chunked layouts compose children; dictionaries and zone maps bring additional arrays and aggregate dependencies.

Existing core array contracts include vortex.primitive, vortex.bool, vortex.bytebool, constants, nulls, struct/list/list-view/map arrays, dictionary, run-end, sparse, variable-width strings/binary, and the permitted compression encodings. Expand the actual record rather than copying a partial hand-maintained list. Include all recursively serialized children, zone-map tables and aggregate IDs, dictionaries, extension dtypes and their metadata.

Important naming trap: (array, vortex.list) is already a frozen array format. (layout, vortex.list) is the unstable structural layout. Audit IDs as (component kind, ID) pairs. The proposed (layout, qc.list.v1) must not be confused with either.

Core selection is an upper bound. If QC wants to exclude an otherwise core encoding such as OnPair or PCO operationally, define a narrower QC writer profile with compressor exclusions and an independent serialized-output check. Enabling a core edition by itself allows its full membership; adding a second QC edition is additive and cannot subtract core members.

4.2 Components to exclude from QC v1 by default

Observed in the audited upstream UNSTABLE declaration:

Kind Component QC v1 decision
Array fastlanes.bitpacked.v2 Exclude; use permitted stable encodings
Array fastlanes.delta Exclude; do not require it just to compress offsets
Array fastlanes.for.v2 Exclude; stable FoR or another permitted fallback is sufficient
Array vortex.decimal_byte_parts.v2 Exclude; retain stable decimal representation/fallback
Array vortex.patched Exclude
Array vortex.union Exclude; reject unsupported logical types before publication
Layout vortex.list Exclude from new QC production writes; write the QC-owned contract instead
Aggregate vortex.bloom_filter.sbbf Exclude from persisted QC zone maps
Aggregate vortex.sum_v2 Exclude from persisted QC zone maps
Aggregate, preview vortex.uncompressed_size_in_bytes Exclude from new persisted structures unless separately approved and frozen

In-memory use is a separate question. An optimizer may use a newer in-memory representation if serialization safely lowers it to the permitted wire contracts. Conversely, a stable parent ID does not authorize an unstable child. Inspect serializer output, not just the array's in-memory encoding ID or the compressor's declared capabilities.

The current QC list-layout option enables all of UNSTABLE for a forked write session. Replace that behavior for production. Keep an explicitly named experimental mode only if needed for development; it must not share the production profile's guarantee.

4.3 Contract versus implementation

Do not permanently freeze every source implementation or dependency version. Freeze the interpretation of bytes and the supported value/type domains. An upstream reader optimization, faster compressor, or new internal array structure can be accepted if it preserves those contracts and passes the cross-version matrix.

Audit changes to core formats too. Upstream PR #10399 reports historical compatibility gaps under unchanged core IDs, including nullable struct layout validity, dictionary code types, FSST, PCO and logical DTypes. Treat its results as reported evidence to investigate, not as independently reproduced results of this plan.

Also freeze/profile the file container version, footer/postscript features, DType serialization, buffer compression, endianness/alignment assumptions, and optional metadata/encryption features. These may not all be controlled by the four current edition component kinds. Disable unqualified experimental switches, including FLAT_LAYOUT_INLINE_ARRAY_NODE, until tested against the QC minimum reader. Newly supported logical DType variants need explicit profile gating even when they can be serialized using a permitted array ID.

5. Is current unstable list layout ready to freeze?

Not yet established. Its basic representation is plausible for QC v1, and this audit found no demonstrated need for a fundamentally new representation. There are concrete implementation and validation questions that must be resolved before freezing. They can be fixed on QC without waiting for an upstream merge; sending compatible fixes upstream is desirable.

F1. Multi-chunk sliced-list normalization: high-priority suspected writer defect

Observed source behavior:

  • canonicalize_to_list_parts accepts an existing ListArray and returns its parts without normalizing its referenced element range.
  • transpose_list_column advances element_base by the full elements.len().
  • global_offsets adds that base and drops the next chunk's first offset.
  • A valid ListArray can have a nonzero first offset and unused trailing elements. Its validation permits this, and slicing preserves the underlying elements buffer.

A small arithmetic example shows the suspected failure mode: two chunks each have 10 underlying elements and offsets [2,4], each representing one two-element list. Concatenating the whole element buffers and appending offsets as the current helper does yields [2,4,14]. The second list then spans [4,14) instead of the intended second chunk range [12,14).

This is a static trace, not a runtime reproduction through the complete writer pipeline. A preceding canonicalization may mask the issue on particular paths; that must not become an undocumented precondition of the standalone structural writer.

Required work:

  1. Add a direct structural-writer regression with multiple valid chunks having nonzero starts/unused suffixes, plus a default-writer version that introduces slices through repartitioning.
  2. Require it to fail before the fix if the suspected issue is reachable; otherwise document and test the actual invariant that rules it out.
  3. Normalize each chunk's elements to the referenced contiguous range and rebase offsets before concatenation, or enforce an equivalent correct invariant.
  4. Preserve null-list semantics and all legitimate element rows inside the referenced span.
  5. Add variants for zero-row chunks, empty lists, null lists carrying physical elements, nested lists and ListViews.

Source: QC writer functions starting at line 234, ListArray validation. The list slice implementation retains the elements buffer while slicing offsets and validity. The implementation phase must execute the regression through the real writer.

F2. Offset metadata accepts more than the proposed contract

ListLayoutMetadata::get_offsets_ptype currently checks that the value is a known PType; it does not restrict it to integers. The structural writer emits non-nullable u64 offsets, while some reader helpers convert offsets to u64 and expect that conversion to succeed.

Proposed QC v1 contract: offsets are non-nullable u64. Enforce this in construction and deserialization and reject unsupported metadata explicitly. If wider compatibility with legacy offset types is required, document and test that as a separate decoder contract rather than accidentally accepting every primitive PType.

This restriction is appropriate for a new QC ID. Do not silently redefine which historical upstream unstable files are accepted by an import decoder without inventorying them.

F3. Exact offset-count validation and checked arithmetic

The deserializer compares offsets.row_count().saturating_sub(1) with the parent row count. That admits zero offset rows when the parent has zero rows. Require checked parent_rows + 1, reject overflow, and require an exact offset row count for an actual QC list node.

Audit unchecked arithmetic in cumulative element counts, offset rebasing, row_range.end + 1, range subtraction, split offset calculations and u64-to-usize conversions. Cover realistic boundary arithmetic with metadata/helper tests rather than allocating impractically large buffers.

A zero-row file/stream may legitimately use a typed empty chunked layout instead of a QC list node. That is a separate valid representation, not a reason to accept malformed list-node offsets.

F4. Validate persisted offsets before relying on unsafe reconstruction

The list reader rebuilds arrays using ListArray::new_unchecked. Its safety comments assume monotonic, in-bounds offsets. The list metadata deserializer cannot establish those value-level properties merely by checking child counts.

Trace validation in every decoded offsets child and reader path. Establish where actual offset values are validated before any unsafe use, indexing, subtraction or element read. Add a controlled validation boundary if the current chain cannot prove the required invariants. Cover non-monotonic offsets, oversized terminal offsets, negative/signed metadata, truncated offsets, inconsistent element row counts and malformed validity.

A full eager scan of all offsets on file open would undermine pruning; choose a validation strategy that validates the portions and boundaries used, while providing a full offline validator for release fixtures and migration. A bounded read must validate the invariants it relies on; a metadata-only read need not fetch unrelated payload just to validate it. Reject malformed bytes with a controlled error, without promising detection of unvisited corruption.

F5. Specify list semantics and structural invariants

Document and test child order (elements, offsets, optional validity), nullability, row coordinate spaces, and exact dtype expectations. Decide whether direct segments on a QC list node are forbidden and enforce that decision. Specify protobuf field tags/default handling and unknown-field policy.

For the new QC writer, propose canonical outer offsets starting at zero and ending at the stored element count. Null lists may have a nonempty physical element span; their payload is logically unobservable, and fallible operations must not evaluate it. Empty lists and null lists must remain distinct. Decide the valid reader domain explicitly; avoid accepting a loose domain while testing only the writer's narrow output.

F6. Empty and degenerate representations

Upstream #10533, already merged and present in the baseline, handles empty nested streams by returning a typed zero-row chunked layout. Keep it. Its alternative #10534 is closed; do not treat that as an additional prerequisite.

Test no input chunks, empty chunks between nonempty chunks, every outer list empty, every outer list null, empty element structs, no selected output columns, zero selected rows, and all-null children at multiple levels. Decide whether empty structs are supported logically and through Spark; if not, reject the unsupported schema explicitly.

F7. Reader execution support and false-negative pruning

QC already carries the element-projection work from #10948, nullable struct projection fixes associated with #10952, and further QC handling of transformations through nullable fields. Retain these for the pruning product milestone. They are primarily reader/optimizer changes, not evidence that the format must change.

Native scan V2 has an observed list execution gap: #11035 restricts list-layout benchmarks because ListPack lacks a pipeline implementation. Explicitly select the working path or implement and qualify V2. Do not allow an upstream switch to V2 defaults to silently make frozen QC files unreadable. A rejected/unsupported executor must fall back before planning fails, if fallback is the product policy.

List element zone pruning remains unfinished. False-negative pruning is data loss even if a full read decodes the file correctly, so every new stats rewrite or pruning implementation needs differential query tests. A lack of zone pruning is a performance gap, not necessarily a wire-format freeze blocker.

6. Implement a QC-owned wire contract correctly

A new edition entry naming qc.list.v1 is not enough. The current writer checks permission for List.id() and builds a layout whose VTable ID is vortex.list; the reader is typed around that layout. An alias in the edition manifest will not change emitted bytes.

Implementation steps:

  1. Introduce the QC layout plugin/serializer under the chosen QC wire ID. Choose either a thin QC VTable with shared compatible reader helpers, or another explicit wire-to-in-memory adapter supported by the layout infrastructure. The current reader is typed around Layout<List>; factor or adapt it deliberately rather than assuming registration alone will make a different VTable work. Audit type/ID-based physical-plan lowering, split planning and optimizer dispatch too. Prove the design with a minimal write/read fixture before broad refactoring.
  2. Make list strategy selection aware of the QC layout. Refactor the hard-coded upstream List-ID permission check into an explicit selected layout factory/profile path. Avoid rewriting ID strings in serialized files after the fact.
  3. Ensure every nested structural-list occurrence emits the QC ID, including lists inside lists, structs, dictionaries where relevant, and output from all write entry points.
  4. Keep a legacy upstream vortex.list decoder available only for the specific experimental baseline(s) QC needs to import. Do not route a frozen QC ID to whatever upstream's current unstable decoder happens to mean.
  5. Register the QC family, declaration and plugin in every required session: driver/executor JVMs, native readers/writers, migration tools and compatibility runners. Reader registration and writer permission selection are distinct requirements.
  6. Define a QC write-session profile that preserves custom plugin registrations but isolates edition selection. Replace the current Spark option's broad UNSTABLE enablement. Test session isolation concurrently and after failures.
  7. Extend edition record generation: xtask enumerates default and selected optional declarations explicitly, so a QC declaration living in its own crate needs to be wired into the exporter. Generate records using repository tooling; verify the freeze guard covers the QC family against git history.
  8. Record origin and minimum version using an actual QC distribution release. The current version parser expects a numeric major.minor.patch; do not invent a Rust upstream version or rely on a SHA-only value fitting that field. Maintain a separate immutable mapping to QC artifact versions, source SHA, native-library digests and container digests.
  9. Add an explicit error for missing QC plugin/unsupported profile. A reader should identify the unknown wire ID and required distribution rather than falling through to an unrelated plugin.
  10. Retain QC v1 decoding indefinitely for as long as the stated storage guarantee promises. A later QC v2 gets a new ID and later edition. Never rewrite the frozen v1 record to accommodate an incompatible upstream change.

The custom ID intentionally sacrifices automatic reading by stock upstream builds. If stock interoperability is a hard requirement, pursue upstream promotion as a parallel workstream and retain an export/rewrite tool. Copying bytes to a different ID is not a substitute for proving the contracts equivalent.

7. Specify the immutable storage-profile manifest

Check in a machine-readable manifest alongside the QC protocol specification. It must describe:

  • selected edition IDs and full expanded (kind, wire ID) permission sets;
  • any narrower operational writer allowlist and compressor preset;
  • layout metadata schema and child/row/dtype invariants;
  • supported logical types, nested composition rules, decimals, timestamp units/ranges and extension metadata;
  • container version and permitted optional features, including buffer compression and metadata placement;
  • producer distributions and supported reader release floors;
  • fixture-manifest version, hashes, and the release at which each fixture became permanent;
  • baseline toolchains, architecture support and the external codec versions used by each frozen producer;
  • read-path policy, including native V1/V2 selection/fallback and supported Spark/Scala variants.

The manifest states permissions, not an obligation to emit every permitted compression format in every file. Add dedicated coverage that forces every enabled serialized format at least once. If a permitted component is unreachable and never supported by the actual product, remove it from the narrower writer allowlist or add the missing support evidence.

Freeze reader/writer value semantics as well as bytes. QC #35 has a timestamp-range policy difference from upstream; record it and test values near both accepted boundaries. Treat dtype/nullability, decimal precision/scale, timezone metadata, float special values, map key semantics and nested parent validity as part of the expected data contract.

8. Compatibility harness architecture

Use the existing vortex-test/compat-gen machinery where useful, but add a QC profile and QC structural-layout fixtures. The upstream synthetic list fixture is not proof of structural list-layout compatibility: it is an array fixture written through the ordinary compatibility adapter, and default core writes do not enable the unstable list layout.

Borrow or port the cross-version mechanisms in open #10399. Do not assume it already supplies a required CI job; its current description says that is not done. A QC harness can be built without merging the whole experimental PR.

Use three independent inputs:

  1. Immutable persisted files from each released QC writer.
  2. Immutable expected schemas and logical values, exported from an independent canonical source or explicitly specified data. Keep expected results separately from the current Vortex implementation.
  3. Retained reader/writer executables built from exact released QC artifacts, not historical source rebuilt against today's dependencies.

Run old/new native libraries in separate processes or containers. Do not load multiple JNI versions into one JVM or reuse one Spark session and mistake its classpath for an old reader. Match Java classes and native libraries as a distribution pair. Record the version actually loaded.

8.1 Required compatibility directions

Let R0/W0 be the first frozen QC release; Rprev/Wprev the currently deployed release; Rc/Wc the candidate built from the proposed upstream merge.

Writer/file source Reader Required result
Every archived frozen writer Wi Rc Correct full reads and query results; all historical frozen files remain readable
Wc targeting QC v1 R0 Correct reads and queries; catches new bytes that the original frozen reader cannot interpret
Wc targeting QC v1 Rprev and every other supported deployed reader Correct reads and queries; intermediate releases can have distinct bugs
Wc Rc Correct round-trip, but insufficient on its own
Archived upstream flat/core files Rc Existing table compatibility preserved
Experimental pre-freeze list files from inventoried baselines Matching retained import reader, then frozen writer, then Rc/R0 Explicit migration succeeds; no implicit promise for unknown experimental files
Frozen QC file Stock upstream reader without QC plugin Clear unsupported-layout error, not silent misdecode
Candidate upstream-feature file outside QC v1 QC production writer/profile Rejected before publication or safely serialized using a supported contract

Keep all frozen-release file sets permanently. If the deployment policy eventually supports fewer intermediate executable versions, record that policy separately; do not delete the files or relax future-reader compatibility with old QC v1 files.

8.2 Independent oracle and comparisons

Generate canonical source data and expected schemas outside the reader under test, e.g. a deterministic Arrow/Python model plus explicit null/type checks. For Parquet parity use zstd level 3, following repository policy. Parquet is an additional oracle for Spark semantics, not a replacement for bit-preservation checks or features Parquet cannot represent.

Compare row counts, row identity, nested lengths/order, validity at every level, field names/order, dtype/nullability, decimal precision/scale, temporal metadata and exact values. Preserve NaN payload bits and signed zero in physical round-trip checks where the selected format promises them; SQL comparisons may use Spark's semantic equality separately. Do not normalize away a real storage discrepancy merely to obtain equality.

For relational queries with no ordering guarantee, compare keyed results or multisets while checking duplicate counts. Separately test the native ordered-read mode and any bucket/sort guarantees. Always preserve order within each list. Use explicit SQL ordering for order-sensitive assertions rather than relying on Spark's incidental output order.

Compare metadata-only counts and pushed filtered results against independent full-read computation. Disable each optimization in a reference path where possible. A matching result hash alone is insufficient without schema/null checks and good diagnostics.

8.3 Immutable fixture storage

Use a QC-owned private artifact bucket/registry or another durable repository appropriate to binary size. A gist is the plan, not the fixture store.

Store original .vortex bytes with SHA-256, expected results, schemas, profile manifest, writer identity, configuration, codec versions and query descriptions. Preserve build/container digests. Enable immutability/version retention and backups. New fixtures receive new names; never replace an old fixture with bytes produced by the candidate writer. Separate mutable developer scratch fixtures from the protected release corpus.

A release cannot finish if its compatibility corpus and reader/writer artifacts have not been published and read back successfully by the retained runners.

9. Native and storage test inventory

Organize tests by behavior and guarantee, not by mirroring every implementation helper.

9.1 Structural and boundary cases

  • List of every enabled primitive/string/binary/decimal/temporal type; nullable lists and nullable elements independently.
  • list<struct<...>>, struct<list<...>>, list<list<...>>, alternating structs/lists at depth 3–8 and generated deeper trees within declared resource limits.
  • Struct/list siblings with different nullability, multiple selected leaves and whole-value consumers.
  • Zero rows, no chunks, zero-row chunks, every list empty, every list null, null elements, parent-null structs with arbitrary physical child payloads.
  • Multiple input batches with slices, nonzero offsets, unused leading/trailing payload, chunk boundaries inside long list columns, and ListViews with overlapping/reordered/gapped spans.
  • Very long lists, highly skewed lengths, one giant list among tiny lists, and rows crossing many element chunks.
  • Offset and row count boundaries around 32-bit conversions, checked u64 limits via synthetic metadata, and offset compression variants allowed by QC v1.
  • Dictionaries, run ends, sparse values and compressed children nested below list elements/offsets/validity, forcing enabled encodings instead of hoping the compressor selects them.
  • Missing/reordered/case-varied struct fields across files and evolved user schemas, including fields missing inside nested list elements.

9.2 Read operation matrix

For each important structure, exercise full read, partial contiguous row ranges, empty ranges, all-true/all-false/sparse masks, separated selected ranges, takes with duplicates and reordered indices, limit boundaries, filters and projection/filter on different leaves. Use native batch execution and Arrow export, not scalar probes alone.

Exercise reading only list validity, only lengths, a single leaf, multiple leaves, and full list plus a derived leaf in the same scan. Test all paths that reconstruct lists and every executor the product may select. Verify lazy batches are actually consumed and materialized before comparing results.

Use fallible bodies/casts with invalid values exclusively under filtered-out rows or null parent lists/structs. Assert those values are never evaluated. Include failure cases where the invalid value is selected and the correct error must occur.

9.3 Mutation, corruption and parser tests

Mutate metadata, child counts, child dtypes, row counts, offset values, segment IDs, file/footer lengths, truncation, and optional-field combinations. Include valid files whose buffers are encoded differently so validation is not dependent on one array representation.

Require controlled errors for invalid input and no panic, deadlock, out-of-bounds access or unbounded allocation in supported validation paths. Add fuzz targets for the QC layout deserializer, offset-driven reading, nested write/read cycles and candidate-versus-reference queries. Use sanitizers/Miri for suitable unsafe boundaries rather than treating ordinary tests as memory-safety proof.

Test missing plugins and forbidden output IDs explicitly. A writer must never silently disable edition checks or enable UNSTABLE to make a test pass.

9.4 Writer reliability and ownership

Inject failures in the element/offset/validity child writers, segment sink, Arrow import and stream producer. Exercise cancellation, early reader close, iterator abandonment, executor task retry and JVM shutdown. Verify errors surface, resources are released, and failed jobs do not publish partially valid datasets.

Retain QC's JNI Arrow-buffer ownership fixes and tests that reuse/mutate the source batch after native import. A compatible wire specification cannot compensate for writing the wrong data due to lifetime bugs. QC #35 carries the port of QC #49; upstream counterpart #11069 is separate work.

10. Spark integration and pruning implementation

10.1 Preserve the existing FileFormat work

Port the relevant commits from QC #35 after #9658 merges. Preserve QC #40 for nested resolution/pruning, QC #42 for array projection/JNI/layout writing, nullable-parent fixes, null-filled vectors, split reads and writer ownership. Confirm what is already upstream before cherry-picking; PR numbers alone are not dependency hashes.

Keep the shared projection builder and per-file schema resolution. Use Spark's resolver consistently for case sensitivity, reject ambiguity, preserve field identities/order, fill allowed missing fields with nulls, and reject invalid type reinterpretation. These behaviors must work recursively below lists and eventually maps.

10.2 Cover both Spark file-source paths

V2 FileScanBuilder and V1 FileFormat have distinct planner plumbing. Spark's built-in V1 nested-schema rule recognizes Parquet/ORC, so retain and qualify QC's VortexSchemaPruning extension for catalog/fallback scans. Verify service discovery and the documented explicit extension configuration for PySpark 3.5.

Required variants: Spark 3.5/Scala 2.12 and 2.13; Spark 4.0/Scala 2.13; the branch's 4.1/4.2 compatibility runs where QC intends to claim support. Test JVM and PySpark entry points, row and columnar readers, whole-stage codegen disabled, wide schemas, partitioned/catalog/bucketed tables, _metadata where supported, and projection with partition-only columns/counts.

Make reader/profile versions observable in logs or diagnostics without exposing internal details in ordinary user-facing query output.

10.3 Add recursive Catalyst field-demand analysis

The current projection builder recurses through structs and arrays, but Spark often requests whole arrays for lambdas and generators. Introduce a Vortex-scoped planner rule that tracks demand through supported expressions rather than relying exclusively on the existing SelectedField/aliasing shapes.

Demand needs separate representations for whole value, selected struct fields, element demand, validity-only, and cardinality/offsets. Union demands from projections, filters, joins, aggregates and multiple consumers; whole-value use dominates narrower demands.

For example, transform(orders, o -> transform(o.items, i -> i.price)) should request orders: array<struct<items:array<struct<price:...>>>>. Spark can still execute both transformations. Native pushdown of arbitrary Spark lambda arithmetic or captures is unnecessary to obtain leaf I/O savings.

Resolve lambda variables by their binding identity and lexical scope; update element types, field ordinals, GetArrayStructFields field counts, expression IDs and generator output types consistently. Preserve names/metadata/nullability. Never prune fields used only by a residual filter or other consumer. Unknown expressions/UDFs or opaque whole-value uses conservatively demand the relevant whole subtree.

Handle direct getters, array indexes/element_at, nested transforms, filters/exists/forall as field-demand consumers, and multi-consumer combinations. Preserve ANSI error behavior and evaluation order where observable. An expression-demand optimization must not introduce evaluation of discarded data or suppress an error that the original query would produce.

10.4 Generators and deep nesting

Extend explode, explode_outer, posexplode, posexplode_outer, inline and inline_outer with explicit preservation of output shape, positions, cardinality and null behavior. Cover multiple output fields, nested arrays and chained generators. Do not claim full support based only on a single-field explode rewrite.

A direct index can enable field pruning without selective element I/O: reading arr[0].x does not itself prove only element zero was fetched. Track leaf skipping and element-range skipping as distinct capabilities.

10.5 Maps and other nested containers

Current NestedSchemaPruning and per-file shape discovery stop at maps, and TableStrategy decomposes structs/lists rather than DType::Map. Complete “any nesting” across maps needs more than an ArrayType branch:

  • recursive MapType/file-schema resolution and shape/null-filled vector handling;
  • a map-value/entry projection expression that preserves keys, order, nullability and map dtype;
  • physically separable key/value/entry storage, with its own frozen contract if it introduces a new layout;
  • keys retained wherever lookup/equality requires them; do not prune key fields in a way that changes key identity;
  • nested list/struct recursion below map values and map values below list elements;
  • tests for map lookup, map values, map generators, absent keys, null values and key metadata.

Plan this as a separate native/storage workstream if map leaf pruning is required. A later QC map layout can receive a later edition; it need not delay the list v1 wire contract. The overall universal-pruning milestone remains incomplete until the agreed map cases are done.

10.6 Predicate pruning and metadata-only operations

Do not equate field-demand pruning with evaluating list predicates in the native scan. Native translation of exists/forall/array_contains, parent-row reconstruction, three-valued null logic and list-element zone pruning needs a separate correctness plan. Retain Spark residual evaluation until native semantics are proven.

Likewise, optimizing standalone size(arr) requires a projection/expression bridge that can request lengths instead of the whole list; native length support already exists but Spark's required schema alone may not express it. Add shape-only demand transport explicitly. A zero-leaf element struct must not lose null-element identity.

The open capture designs #10702 and #10853 matter if arbitrary higher-order computation moves native. They are not prerequisites for schema-only lambda demand analysis. The alternative higher-order-node design #10696 is not a required dependency.

11. Tests proving pruning rather than just results

For each supported query shape assert three independent properties:

  1. Planner demand: optimized/physical scan schema or explicit demand contains the expected leaves, on V1 and V2.
  2. Correct values: pruning enabled matches pruning disabled and an independent reference where applicable, including all nested null/type semantics.
  3. Physical I/O: an instrumented SegmentSource or read adapter fails if an omitted sibling's segment is requested.

Create fixtures where each leaf occupies a separate known segment; record segment-to-field mapping in fixture metadata. Bytes-read assertions can supplement these tests, but Hadoop counters are sensitive to buffering, caches and coalescing. If read coalescing legitimately fetches adjacent bytes, distinguish logical segment requests from transferred byte ranges and use spaced fixture segments or a no-coalescing adapter for deterministic unit/integration assertions.

Add stable benchmark gates on wide realistic nested schemas, many tiny files, skewed lists and object-store latency. Measure bytes requested/transferred, segment count, decode CPU, peak memory and latency. Do not enforce exact byte counts on nondeterministic layouts. Performance regressions should be reported separately from compatibility failures, with an explicit approved budget rather than silently accepting full-list fallback.

12. Upstream merge gate

Every upstream merge and QC PR must pass a required compatibility smoke matrix regardless of changed paths. A source-path filter alone misses dependency updates or generic serialization changes that alter output.

Every PR / upstream merge

  • Immutable edition/profile records checked against the merge base; regenerate declarations/records and require a clean result.
  • Candidate reader against the protected frozen corpus, including query/pruning paths.
  • Candidate production writer fixtures read by the original QC reader and current deployed reader.
  • Exact emitted-ID/type/container-feature audit against the QC profile, including nested child arrays and stats tables.
  • Focused structural edge-case regressions and deterministic Spark V1/V2 pruning smoke tests.
  • Fail-closed handling for missing artifacts, skipped cases, unexpected writer rejection, unsupported reader errors and panics. An infrastructure failure must not turn into a passing compatibility status.

Broader runs

  • Nightly: all retained supported readers, larger seeded generation, mutation tests and varied compression/layout parameters.
  • Weekly or release candidate: extended fuzzing, production-shaped corpus, complete Spark variants, cloud adapters, memory/cancellation stress and representative cross-architecture exchanges.
  • Release gate: full matrix, publication/retrieval of the new immutable corpus and binaries, rollout/rollback rehearsal and no unresolved correctness findings.

Use deterministic seeds for required jobs, rotate additional seeds nightly, and promote every discovered counterexample into a permanent minimized regression. Preserve crash artifacts and report producer/reader identities, fixture hashes, selected IDs, schema and query on failure.

Protect workflow changes and corpus updates with storage-owner review. Keep an append-only failure/decision record; do not change expected output to match a candidate implementation without independent semantic evidence.

13. Upstream change classification and review

Changes that require a storage review include list/struct/flat/chunked/dict/zoned metadata; array serialization and child construction; logical DTypes; offset conversion, validity or length kernels; footer/container schemas; external codecs; edition registries; compressor defaults; session/plugin initialization; and scan executor selection.

Also review generic mask/slice/filter/take/concat/Arrow conversion changes. They may alter actual values or nulls without changing any wire ID. JNI ownership, alignment and endianness changes affect the same guarantee.

Review procedure:

  1. Build the upstream merge in an isolated candidate branch/worktree against the recorded QC baseline.
  2. Produce a source/dependency/component manifest delta and classify wire-contract versus internal changes.
  3. Run the mandatory matrix and inspect its actual coverage; reject silent skips.
  4. If the change is compatible, merge it with normal review. If it requires new bytes, keep the old serializer/decoder for QC v1 and put the new contract behind a new ID/profile.
  5. If upstream changes its unstable vortex.list, leave QC v1 interpretation unchanged. Adopt only compatible helper improvements or adapt them behind the QC plugin.
  6. If an upstream change to a supposedly frozen core ID fails the matrix, hold it or add a compliant compatibility adaptation; do not “fix” QC's frozen fixture/record.

Static review and edition guards reduce risk, but passing a finite test suite is not a proof for every possible file. The strong operational guarantee comes from frozen contract ownership plus constrained output, retained implementations and release-by-release differential evidence.

14. Deployment, migration and rollback

Inventory existing datasets before enabling the new writer: flat/core-only, specific experimental list snapshots, mixed tables, and consumers outside Spark. Record all applications that read/write each dataset and the oldest artifact they actually run.

Deploy compatible QC readers/plugins everywhere first. Validate they can read old files and sample frozen-profile canaries. Then enable the QC writer on new canary paths/tables, followed by controlled expansion. Do not allow older stock readers to encounter new custom-ID files accidentally.

For legacy experimental files, retain the exact matching reader in an isolated migration image. Read and validate against independent source/count checks, rewrite into a new destination with the frozen writer, verify through both minimum and current QC readers, and publish through an atomic table/manifest transition appropriate to the storage system. Never overwrite source data during the validation phase.

Provide a rewrite/export path to stable upstream-only flat files for consumers that cannot install QC plugins. Track its I/O/performance tradeoff explicitly.

Rollback has two dimensions: stopping new QC writes and reading already-written QC files. Turning the write option off does not make an old binary able to read those files. Keep the compatible reader available through rollback; otherwise switch datasets back only after a validated rewrite/metadata transition.

Support mixed old/new files in the same table, schema merging, partition discovery, retries and aborted writes. Test task/job commit behavior so failures do not expose partial files. Collect profile/writer/reader version, unsupported-ID errors, read failures, row counts and unexpected fallbacks as operational telemetry.

15. Ordered implementation packages

These are proposed reviewable QC PRs, not existing PR numbers. Each package has an exit condition.

Package Work Depends on Exit condition
P0: contract and baseline Inventory readers/data; choose type scope, ID/profile/core edition; record baseline and owners None Approved decision record and reproducible baseline
P1: permanent reproductions Add F1 sliced-chunk and F2–F6 metadata/offset/empty-input regressions P0 Suspected gaps reproduced or invariant documented; independent expected results
P2: native hardening Fix reproduced writer issues; exact validation/overflow/error paths; qualify unsafe reconstruction P1 Regressions fail before and pass after fixes; no unresolved storage-correctness blocker
P3: QC plugin and edition Implement QC ID, recursive writer factory, registrations, exporter and profile selection P0, P2 Minimal and nested files emit QC ID and only allowed dependencies; original QC reader candidate reads them
P4: compatibility harness Immutable corpus/oracles; retained executable runners; cross-version and output audits P0; integrates P3 Both directions run in isolated processes and detect an injected same-ID wire break
P5: FileFormat integration Rebase selected QC fixes onto merged #9658; writer option/profile; V1/V2 reader qualification Actual FileFormat merge, P3 Existing field/index pruning, schema/null handling and distribution loading pass
P6: required merge gates QC edition guards, corpus protection, PR/nightly/release jobs, source/dependency delta P4, P5 Upstream merge cannot bypass failing compatibility status
P7: Spark recursive demand Lambdas, indexes, multiple consumers, ordinals/types, shape demand P5 Planner + result + physical-I/O assertions for agreed expression matrix
P8: generator coverage Explode/posexplode/inline families and deep compositions P7 Multi-field/deep/null/outer semantics and leaf skipping proven
P9: map-crossing support Map projection, output shape and physical storage design; later frozen contract if needed P0, P7; native work can run alongside Agreed map/list/struct combinations physically prune correctly
P10: storage release Full compatibility/ops qualification, immutable QC release and reader-first deployment P2–P6 Storage freeze checklist below complete
P11: full pruning release Complete all agreed nesting/query cases and performance evidence P7–P9 Universal-pruning scope explicitly met; no undocumented whole-read gaps
P12: upstream convergence Propose contract/promotion; retain dual decoders/export; migrate only with evidence Can start at P0 Upstream interoperability plan independent of QC freeze timing

P7–P9 can continue after P10 if storage is ready first. Do not label P10 as completion of all recursive Spark pruning. Do not claim a date based on the next upstream edition; no promotion PR or promised freeze date was found during this investigation.

If an early storage release is valuable, keep its documented scope narrow and explicit, while retaining P7–P9 as required follow-up work for the original full-pruning objective. Avoid a hidden scope reduction.

16. Existing PR dependency decisions

Existing upstream/QC work Proposed handling
Upstream #9658 FileFormat Base future connector work on its merged form; not a storage stability prerequisite by itself
QC #35 integration Source of feature/fix commits and tests; do not merge the entire integration branch blindly
QC #40 / #42 Preserve nested resolution, array projection, JNI and null handling; replace broad UNSTABLE write selection
Upstream #10948 Keep its functionality already carried by QC; audit integration with QC plugin and fallible/null cases
Upstream #10952 plus QC nullable-transform fix Keep for actual deep leaf I/O pruning; pure wire freeze does not depend on upstream merge timing
Upstream #10533, merged Keep empty nested stream fix
Upstream #10563, merged Preserve edition-driven behavior but refactor hard-coded List ID for the QC writer factory
Upstream #10399, open Reuse/port cross-version harness ideas and investigate findings; add QC required CI independently
Upstream #10805, open Reuse edition selection/session isolation and permitted writer-strategy behavior as needed; explicit QC profile still required
Upstream #11030 / #11035, merged Useful benchmark qualification; bench edition never freezes and is not a production contract
Upstream #10928, open Optional zone-strategy work; qualify against frozen profile and query oracle before adopting; not required to freeze list v1
Upstream #10970, open Optional grouped-aggregate performance work; not list-layout stability or schema-pruning infrastructure
Upstream #10702 / #10853 / #10696 Do not block schema-only pruning on alternative capture/HOF designs
QC #49 / upstream #11069 Preserve independent Arrow-buffer ownership fixes as write-correctness requirements

Do not treat every listed performance PR as mandatory before freeze. Conversely, no current open PR substitutes for QC contract ownership and the missing regression/compatibility work identified above.

17. Final storage-freeze checklist

  • Exact baseline commits, required consumers, supported types and owners recorded.
  • F1–F7 resolved with reproduction/evidence or an explicit documented scope decision; no known data corruption or unsafe malformed-input path left unresolved.
  • QC wire metadata, allowed values, children, row spaces and validation rules written and reviewed.
  • QC layout emitted under an owned ID, with a retained independent contract and no accidental unstable-ID aliasing.
  • Fixed core-plus-QC profile enforced recursively; preview/unstable leakage tests pass.
  • Logical DType/container/codec feature gates cover requirements beyond the current edition member model.
  • Full expanded profile manifest generated and stored with protected immutable records.
  • First QC reader release artifacts and source/container/JAR/native digests preserved.
  • Old-file/new-reader and new-file/minimum-reader matrices pass, including queries and all enabled physical formats.
  • Independent oracle and immutable corpus policy in place; no candidate-regenerated expected fixture substitution.
  • Required CI catches an intentionally injected same-ID metadata break and a dropped old decoder; negative tests run against the actual gate, then injected breaks are removed.
  • Spark FileFormat V1/V2 and native executor selection/fallback qualified for the release scope.
  • Writer failure/cancellation/JNI ownership and no-partial-publication checks pass.
  • Supported architecture exchanges and large/skewed/resource-limit cases qualified.
  • Reader-first rollout, mixed-table migration, retained legacy importer and rollback rehearsed.
  • Actual QC release published; edition minimum records that real version, never a hypothetical future build.

Full recursive pruning additionally requires the planner/result/I/O matrix for lambdas, generators, shape-only operations and agreed map paths. Record each unsupported case visibly until that separate milestone is complete.

18. What this plan does and does not establish today

This is a detailed implementation plan and static readiness assessment. It does not certify the current unstable layout as production-ready, prove the suspected sliced-chunk failure in a running writer, or claim that existing tests already cover the proposed matrix. Those are concrete implementation gates above.

No estimate of the next upstream edition is a dependency of this plan. QC can freeze a carefully specified and tested contract independently, then continue adopting upstream implementation improvements behind the required compatibility gate.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment