Tracking Issue: Execute `RowFn` over Vortex arrays

[connortsui20]

This issue tracks the private machinery that executes a RowFn over Vortex arrays.

Parent Epic: #9128

Related API tracking issue: #9129

Design

A RowFn provides a typed row kernel. The batch executor adds the columnar behavior that every strict row function needs:

1. Validate every input length. Then plan the output dtype and nullable-row policy from the concrete dispatch.
2. Conjoin the input validities and short-circuit all-invalid or null-constant batches.
3. Probe reduce_encoded once on the original inputs.
4. Evaluate all-constant calls once and preserve batch constants as one decoded row.
5. Select dense, skip-invalid, or filter-and-scatter execution.
6. Validate the output length, dtype, and valid-row values. Then apply strict validity.

This machinery is private. A function author selects typed elements and an output capability. The executor owns the batch strategy.

Nullable-row policies

Planning selects one of two policies for each concrete dispatch:

• Dense evaluates every row and masks the output. It requires null-safe decoding and an infallible row computation.
• ValidOnly never evaluates the row closure for an invalid row. It selects skip-invalid or filter-and-scatter execution for a mixed validity mask.

Deferred computation selects ValidOnly. This prevents an error from an invalid row payload from becoming observable.

Executor results

Executors return VortexResult<ArrayRef> directly. Planning routes every deferred computation to ValidOnly, so failure evidence reduced after a row loop always came from valid rows and converts into an ordinary error immediately.

An earlier design threaded a three-outcome RowExecution type through the executors so that batch execution could decide whether a deferred failure came from a valid row. #9496 removed RowExecution and DenseWithRetry because the ValidOnly routing already guarantees that decision.

Deferred failures

visit_deferred returns an owned output and a small FailureEvidence value for each row. The executor OR-reduces those values in a loop-local. It constructs one rich error after the loop.

The concrete failure evidence must not be wider than the output value. A wider reduction lowers the vector width and can make checked arithmetic much slower. Keeping the accumulator out of the output sink also avoids a loop-carried memory dependency.

Sink visits can report these result forms:

• () for an infallible write into initialized storage.
• InitializedElement for an infallible write into uninitialized storage.
• VortexResult<()> for an immediate failure with initialized storage.
• VortexResult<InitializedElement> for an immediate failure with uninitialized storage.

The result's WriteToken must match OutputSink::WriteToken. This constraint keeps the visitor methods safe. It places the per-row unsafe operation inside the uninitialized-output closure. Deferred evidence belongs to the owned visit_deferred forms, not sink execution.

Integer division returns VortexResult<InitializedElement> with UninitElementSink. Division is already scalar and expensive. An immediate check can stop at the first failure. Uninitialized dense output avoids filling every slot before the row loop.

Skip-invalid and filter-and-scatter execution

For a mixed mask under ValidOnly, the executor can compute only valid row indices in the original inputs. This path requires two contracts:

• Every InputElement must provide a null-tolerant decode for the concrete array.
• OutputSink::skipped_rows_initializer must return an initializer for legal placeholders.

The executor masks those placeholders before it returns the output. If either contract declines, the executor filters every input to the valid rows. It runs the dense kernel and scatters the result into a full-length nullable array.

Owned output visits initialize skipped slots with Default. The executor masks those placeholders before returning the output. If null-tolerant decoding declines, the visitor uses filter-and-scatter. UninitElementSink supports skipped slots directly, which keeps nullable integer division on the original inputs.

The batch executor probes the original arrays for an encoding-aware reduction before strategy selection. ValidOnly then tries skip-invalid execution. If that attempt declines, it filters and scatters. There is no survivor threshold or FILTERED_DECODE_COST. Until the fallback in #9349 lands, a signature without direct valid-row support panics instead of filtering.

Constants and encodings

Constant decoding and prepared computation are separate. The tuple adapter stores a batch constant as one decoded row. A prepared visitor can derive shared state from that value once per batch.

The no-constant fast path borrows ElementTuple::Views. The tuple guard checks every decoded view length before unchecked row access, because ViewLen::len returns one member length after a debug assertion. When an argument is batch-constant, decoded_lens_match validates each non-constant column and exempts the validated one-row constant.

reduce_encoded returns an encoded or lazy output, or None to continue to the row loop. The executor probes the original arrays once before generic all-constant broadcast, strategy selection, slicing, or filtering. Retries do not probe compacted arrays. A returned array still uses the common output checks. Errors from the hook are immediately user-visible, so the hook must be total over stored payloads behind null rows.

Migration benchmark gate

Use pinned, alternating local x86 measurements and generated-code inspection before replacing a hand-written microkernel. CodSpeed CPU simulation measures a different cost model and does not replace native evidence. Keep a columnar fallback when RowFn produces slower native code, as the primitive comparison path does.

The current native gate uses Rust 1.97.1, LLVM 22.1.6, one codegen unit, fat LTO, and -C target-cpu=native. The full-stack comparison used two warm runs and seven alternating measured pairs on a Ryzen 9 7950X.

LLVM 22 leaves several mixed batch-constant/column primitive loops scalar. Those cases are 4.6 to 8.5 times slower than develop. The same kernels vectorized with LLVM 21. Treat this as a documented compiler regression, not as evidence for more framework plumbing. Keep the affected fallbacks until the generated code improves.

Unchanged controls moved by 10% to 35% in the same whole-binary comparison. Small isolated shifts need branch-local evidence before they justify execution changes.

Steps

• Derive arity, strictness, fallibility, output dtype, and validity from RowFn.
• Implement null-constant and all-constant handling.
• Implement input length checks, dense execution, filtering, and scattering.
• Validate kernel output length, dtype, and valid-row values before strict validity is applied.
• Implement skip-invalid execution for supporting sinks.
• Implement deferred failure reduction and valid-row execution.
• Preserve encoding-aware reductions in the batch executor.
• Add focused executor and validity benchmarks.
• Migrate primitive numeric arithmetic as the first production user.
• Migrate primitive comparisons with selective columnar fallbacks.
• Validate downstream InputElement implementations in vortex-tensor and vortex-spatial.
• Validate a downstream OutputSink implementation.
• Add migration benchmarks before replacing more hand-written kernels.

Decisions

• Use Default placeholders for owned valid-row execution. Mask them before returning the output.

Follow-ups

• Reduce the allocations and passes in filter-and-scatter.
• Measure skip-invalid against filter-and-scatter for each new element with substantial decode work.
• Keep generated-code checks for deferred arithmetic alongside wall-clock benchmarks.

Implementation history

• Define RowFn and RowVisitor #9386 defines the author-facing contracts used by the executor.
• Implement RowFn row execution #9353 adds shared row execution and blanket ScalarFnVTable integration.
• Simplify RowFn execution contracts #9496 renames the fallibility constants to INFALLIBLE, removes RowExecution and DenseWithRetry, and returns arrays directly from the executors.
• Implement RowFn batch execution #9450 adds constant handling, dense execution, sink-based valid-row execution, and output validation.
• Execute owned RowFn outputs over valid rows #9500 adds owned valid-row execution with Default placeholders (first landed on the stack as Execute owned RowFn outputs over valid rows #9468).
• Execute tensor L2 norm with RowFn #9347 adds encoding-aware reductions.
• Execute spatial distance with RowFn #9349 adds filter-and-scatter.
• Support nullary RowFn execution #9469 adds nullary execution.
• Execute primitive numeric operators with RowFn #9345 and Execute primitive comparisons with RowFn #9346 add the first primitive migrations.
• Automate RowFn benchmark comparisons #9351 adds the reusable native benchmark runner and metadata checks.