fix(serial): #370 ODTS wire format v2 — fixed-width LE fields, checked I/O

[LeoBuron]

Summary

The ODTS model format wrote every count/dimension/kernel field as raw host size_t (8 bytes on the host, 4 on Cortex-M) with host byte order, ignored every fwrite/fread return value, and qConfig.roundingMode even leaked the host's enum width onto the wire. A model serialized on a 64-bit host was structurally unreadable on a 32-bit MCU, and a truncated file deserialized as silent garbage.

This PR pins wire format v2 in one version bump:

• All counts, dims, orderOfDimensions, kernel geometry, normalizedShape, groups/outputPadding/outputSize, numNormDims/numGroups/numChannels: u32 little-endian.
• Floats (scale, eps, dropout p): IEEE bit pattern as u32 LE.
• roundingMode in qConfigs: u8 (was sizeof(roundingMode_t) = host enum width).
• SERIALIZE_FORMAT_VERSION = 2, existing fail-fast on version mismatch kept. No v1 back-compat shim — v1 files were host-local artifacts.

Design decisions

• SerialWire primitives (new small lib in src/serial/) — serialWrite/ReadU8|U32LE|I32LE|F32LE|Bytes + serialWriteSizeAsU32LE. Encoding is byte-by-byte LE (never a memcpy of a host integer), every fwrite/fread is length-checked and fails fast with the module's existing idiom (PRINT_ERROR + exit(1)), and serialWriteSizeAsU32LE fail-fasts on values > UINT32_MAX. Shared by Serialize.c, Deserialize.c, and PpcaReplaySerialize.c, so the two formats cannot drift apart. Bulk tensor DATA payloads stay raw packed storage bytes; a compile-time pin in SerialWire.h rejects big-endian hosts.
• ASYM zeroPoint = i32 LE on the wire NOW, even though the in-memory field is still int16_t: the parallel tensor: ASYM zeroPoint can overflow int16 for qBits>=16 with min<0 in quantizeFloatToAsym #246 PR widens the in-memory field to int32_t (lossless int16→int32), so pinning i32 here means the format breaks only once. tensor: ASYM zeroPoint can overflow int16 for qBits>=16 with min<0 in quantizeFloatToAsym #246 should merge after this PR. Until it lands, deserialize range-guards the int16 narrowing (guard drops with tensor: ASYM zeroPoint can overflow int16 for qBits>=16 with min<0 in quantizeFloatToAsym #246).
• ODTR (PPCA checkpoint) coupling — PpcaReplaySerialize.c mirrors the ODTS tensor-record layout in its peek-validate-rewind path, so it had to follow; its own scalars are now LE-pinned via SerialWire and PPCA_SERIALIZE_FORMAT_VERSION is bumped to 2 as well (its embedded tensor records changed shape — a silent-misparse hazard otherwise).
• New skeleton guards on deserialize (same fail-fast idiom): file rank vs skeleton rank (a mismatched record previously wrote file dims past the skeleton's arrays; an equal-element-count rank change slipped past the serial: deserializeTensor trusts the file dtype — heap overflow / NULL-qConfig write when a checkpoint's dtype differs from the pre-built skeleton #316 payload check entirely), and LayerNorm numNormDims mismatch (same OOB pattern for normalizedShape). Dtype validation (file record vs skeleton quantization->type) existed via the serial: deserializeTensor trusts the file dtype — heap overflow / NULL-qConfig write when a checkpoint's dtype differs from the pre-built skeleton #316 guard and is now pinned by tests in both directions.

Tests (TDD: each written first and observed red)

• Golden-bytes fixtures pin the exact v2 encoding byte-for-byte: FLOAT32 tensor record (shape u32 LE + payload), model header + RELU record with SYM_INT32/ASYM qConfigs (incl. zeroPoint -3 → FD FF FF FF), MAXPOOL1D kernel geometry.
• Short-I/O death tests (fork-based ASSERT_EXITS_WITH_FAILURE): truncated header, truncated DATA payload, unwritable stream on serialize.
• Guard death tests: SYM record into FLOAT32 skeleton (the issue's named direction) and the pre-existing FLOAT32→SYM_INT32 direction, rank mismatch, LayerNorm numNormDims mismatch, dimension > UINT32_MAX on serialize, out-of-int16-range zeroPoint on deserialize; plus an ASYM zeroPoint round-trip through the i32 wire.
• Mutation-checked: re-widening a shape field to raw size_t, removing the fread length check, and re-narrowing zeroPoint to i16 each turn at least one test red; implementation restored and re-verified after each.

Verification

100% tests passed, 0 tests failed out of 81        (ctest --preset unit_test_debug)
[397/397] Linking C executable examples/mixed_width_mlp/train_c_mixed_width_mlp   (examples preset, all targets)

Docs updated: docs/FEATURES.md (serialization section + gaps list), docs/CONTINUAL_LEARNING.md (ODTR v2, portability note).

Closes #370

🤖 Generated with Claude Code