Add ArrayConverter for array payload members

[glopesdev]

A payload member spanning several elements of one type could not be given an honest annotation. ArrayConverter closes that, and the harp-benchmarks package that exercised the gap is brought under pyright so the next drift is caught by CI.

The member that could not be typed

A payloadSpec member declaring its own length is emitted as a passthrough over a sub-array dtype:

accelerometer: NDArray[np.float32] = Field(IdentityConverter(np.dtype((np.float32, (3,)))), offset=3)

pyright rejects the assignment with Type "void" is not assignable to declared type "NDArray[float32]", because numpy types a sub-array dtype as dtype[void], so the converter type parameter binds to np.void.

Both obvious repairs were measured on a probe and both fail:

• IdentityConverter[np.float32](np.dtype((np.float32, (3,)))), pinning the parameter explicitly, yields Field[np.float32], and a scalar is not assignable to an array either
• casting the dtype to np.dtype[np.float32] before passing it does the same thing for the same reason

So the element type and the length have to arrive as separate arguments, because a sub-array dtype has already discarded the element type by the time any overload could inspect it. ArrayConverter(np.float32, 3) does that and resolves as NDArray[np.float32].

Nothing about Field changes. Converter is generic in its decoded type with no bound, and decode_batch already returns Any, so an array-valued converter was expressible all along. StringConverter is the existing precedent: it takes a length, builds the identical sub-array dtype, decodes to a non-scalar, and appears in generated output today as core_id: str = Field(StringConverter(3), offset=9).

Why it routes through IdentityConverter at runtime

ArrayConverter is declared under TYPE_CHECKING and is a factory outside it, returning an IdentityConverter over the equivalent sub-array dtype. The runtime object is therefore the passthrough converter every existing code path already expects, and _payload.py has a zero-line delta.

Preserving the runtime identity is important. Sub-array column expansion, the step that renders accelerometer as accelerometer_0, accelerometer_1 and accelerometer_2, is selected by an isinstance check against IdentityConverter. A genuinely separate converter class would fail that check, taking the whole-element branch, and handing pandas a 2D column, which would end up raising ValueError: Per-column arrays must each be 1-dimensional. Routing to the same runtime class avoids introducing that divergence at all.

Measured after the change: the constructed object is an IdentityConverter, its dtype equals the direct spelling at itemsize 12, all fourteen registers round-trip, and harp-benchmark --head still produces six columns for AnalogData.

Checking harp-benchmarks

harp-benchmarks/src was the one package src tree absent from the pyright include, and no test imports its benchmark module, only register_models. Three parse_to_dataframe calls would still have passed timestamp and raised TypeError at runtime; they now pass time_index. Two further errors were found in that package: a masked np.int32 member was given a Python int, and the StartPulseTrain default check omitted two members that @dataclass_transform makes required. Adding the tree to the include will prevent future drift.

The tests/conformance.py fixture also enforces the typed contract. If a change causes an array member to revert to a scalar value without warning, the build process will fail.

What this does not change

tests/device/expected_device.py keeps its two array errors, because it is a byte copy of generator output and resyncs by copying rather than by hand. It sits outside the pyright include, so CI is unaffected. Once the Python generator target emits ArrayConverter, those should clear.