feat(vortex-row): row-oriented byte encoder (size + encode passes)

[joseph-isaacs]

Summary

Adds vortex-row, a new crate that encodes one or more columnar Vortex arrays into a single
ListView<u8> whose per-row byte slices are lexicographically comparable. The byte order
matches tuple ordering of the input values under per-column sort options, so the output works
directly as a sort key / row key — the Vortex analogue of arrow-row.

This is the base of the row-encoding work: the byte codec, the two-pass converter, the
public API, tests, and benches. Codec hot-path performance tuning and the per-encoding
(Constant / Dict / Patched / RunEnd / BitPacked / FoR / Delta) fast-path kernels land in
follow-up PRs and are intentionally out of scope here.

Design

Encoding runs as two scalar functions wired behind the RowEncoder API:

1. Size pass — RowSize. Walks the N input columns once, classifies each column as
   fixed- or variable-width, accumulates the fixed-width prefix per row, and lazily collects
   per-row variable lengths. Returns Struct { fixed: u32, var: u32 } so callers read per-row
   widths without materializing the constant fixed slot as a per-row buffer.
2. Encode pass — RowEncode. Uses those sizes to compute totals, allocate one contiguous
   elements buffer, build per-row absolute offsets, then writes each column left-to-right into
   its per-row slot via a write cursor that doubles as the ListView sizes array — so no
   separate finalize step is needed.

The converter is effectively 2 passes for the pure-fixed-width case and 3 when
variable-length columns require the prefix-sum offsets pass.

Per-column ordering is controlled by RowSortField { descending, nulls_first }: descending
reverses the encoded value bytes, and a leading sentinel byte (0x00 / 0x01 / 0x02) places
nulls before or after non-nulls independently of sort direction.

Public API

• RowEncoder — primary entry point: new / with_options, encode, row_sizes, options.
• convert_columns / compute_row_sizes — convenience helpers around RowEncoder.
• RowEncodingOptions + RowSortField — per-column sort configuration.
• initialize(session) — registers RowSize and RowEncode on a VortexSession so row
  encoding is reachable through the expression layer.

convert_columns and where the API lives

convert_columns(cols: &[ArrayRef], fields: &[RowSortField], ctx) -> VortexResult<ListViewArray>
is the one-shot entry point; RowEncoder is the reusable form (build once with options, encode
many). Each public item is defined in a single file:

Item	File
RowEncoder, convert_columns(_with_options), compute_row_sizes(_with_options)	src/encoder.rs
RowEncode scalar fn + the 5-phase encode driver	src/encode.rs
RowSize scalar fn + the size/classify pass (compute_sizes)	src/size.rs
RowEncodingOptions, RowSortField	src/options.rs
per-dtype byte codec (field_size / field_encode)	src/codec.rs
initialize(session) + re-exports	src/lib.rs

Implementation. convert_columns validates the columns (non-empty, equal lengths, one
RowSortField per column) and delegates to a RowEncoder, which runs RowSize then
RowEncode: the size pass canonicalizes each column once and classifies it fixed- vs
variable-width, accumulating a constant fixed_per_row and — only when needed — per-row
var_lengths; the encode pass sums those into the total byte length, allocates one contiguous
elements buffer, computes per-row offsets (i * fixed_per_row plus a varlen prefix sum), then
writes each column left-to-right into its per-row slot using a cursor that becomes the ListView
sizes array, producing the final ListView<u8> with no separate finalize step.

Type coverage

Supported: nulls, booleans, integer/float primitives, decimals up to 128 bits, UTF-8 and
binary, structs, fixed-size lists, and extensions whose storage type is supported. Variant,
union, and variable-size list arrays are rejected — this crate does not define an ordering for
them.

Testing

• cargo nextest run -p vortex-row — sort-order round-trip tests (bool, i64 asc/desc, u32,
  f64, utf8, multi-column, nulls first/last, struct), the single-buffer ListView invariant, and
  RowSize output shape.
• cargo bench -p vortex-row — row_encode divan benchmarks against an arrow-row baseline
  (primitive i64, utf8, struct_mixed).

[codspeed-hq]

Merging this PR will degrade performance by 11.29%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 1 regressed benchmark
✅ 1506 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Simulation	baseline_lt[16, 65536]	216.1 µs	243.7 µs	-11.29%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing ji/row-pr1-base (e5c07bb) with develop (3ac6c77)}