refactor(test): #270 shared BorrowedLayer.h builders; FLOAT32 factory gate settled as by-design

[LeoBuron]

Summary

Implements the maintainer decision on #270 (2026-07-20): the requireFloat32 factory gate is by design — no SYM_INT32-aware factory init is added to the public API. Instead, the test-side workaround is consolidated into one shared helper, and the docs now present the public-API path as the documented pattern rather than a workaround.

Shared test helper

• New test/unit/support/include/BorrowedLayer.h (header-only, DeathTest.h precedent) with buildBorrowedLinearLayer, buildBorrowedConv1dLayer, freeLinearLayerShellOnly as static inline; carried by a new odt_test_layer_builders INTERFACE lib in test/unit/support/CMakeLists.txt.
• Migrated all duplicated copies found by grep (the issue named three; there were more):
  • buildBorrowedLinearLayer: UnitTestLinear, UnitTestSgd, UnitTestAdamW, UnitTestInferenceApi, UnitTestMultiLayerTraining, UnitTestOptimizerScaling, UnitTestTrainingLoopApi (7 copies)
  • buildBorrowedConv1dLayer: UnitTestConv1d (1 copy)
  • freeLinearLayerShellOnly: additionally deduped from UnitTestMnistSmoke, UnitTestCalculateGradsSequential, and UnitTestQuantLayerIntegration (freeLinearLayerShell, identical body)
  • Hand-wired sites migrated onto the helper: testLayerLoadWeightsLinearQuantizesForSymStorage (UnitTestLayerWeightsApi) and the config-wiring tail of buildTrainableLinear (UnitTestQuantLayerIntegration)
• The unified builder sets weightGradAccMode/biasGradAccMode explicitly (the fullest of the seven variants). The four files that previously left them calloc-zeroed never exercise a backward pass on these layers (verified by grep for backward/calculateGrads/trainingRun), so behavior is identical; fixtures and assertions are untouched.
• ConvT1d has no borrowed-builder copy — its tests use stack-config wiring through the public initConv1dTransposedConfigWithWeightsAndBias, so nothing to consolidate there. buildSymLinearLayer in UnitTestCalculateGradsSequential stays local: it is a genuinely different two-Q (mathQ/propLossQ-divergent) shape, now documented as the two-Q variant of the shared helper.
• Left deliberately untouched: buildLinearStub (UnitTestModelValidationApi, parameter-free NULL-weights stub) and the grad-optional partial config in UnitTestLinear — both test different wiring shapes than the helper produces.

Docs / example

• examples/mixed_width_mlp/train_c.c: comments no longer call FLOAT32-init + requantizeTensorInPlace() "temporary" — it is the documented public-API path to SYM_INT32-native params (structure unchanged).
• docs/FEATURES.md: table cells ✗ (#270 gate) → ~ requantize path (#270); "Quant params" note and Known-gaps bullet rewritten to the settled design.
• src/userApi/LayerCommon.c: rationale comment at requireFloat32 (comment only, no semantic change).
• Project-memory Known-Issues bullet updated to the settled design.

Design rationale

Per the maintainer comment (2026-07-20), a public factory knob for SYM_INT32-native random init "does not help anyone": random init is defined on floats anyway (Kaiming/Xavier bounds, scale derivation), so any factory-native path would internally do float-init-then-quantize — exactly what the user can already do explicitly. Keeping the gate keeps the API honest about what the init actually computes.

Honest assessment — what remains unreachable via the public API

I looked for a concrete user-facing capability that FLOAT32-init + requantize or constant-fill cannot deliver. Verdict: no hard gap; two soft costs worth recording:

1. requantizeTensorInPlace() is example code, not a framework API. The pattern is ~15 lines over public primitives (getQLike, getDataLike, convertTensor, freeData, freeQuantization), documented in examples/mixed_width_mlp/train_c.c. Each downstream user re-implements it. When to revisit: the moment a second example or a downstream consumer copies it, promote it to TensorApi as a small utility — that is a tensor-level requantize helper, not a factory knob, so it would not conflict with this decision.
2. Direct-to-SYM random init without FLOAT32 staging is impossible (transient double-residency of one param tensor during requantize). This only matters for from-scratch on-device init under extreme RAM pressure — and carries no steady-state memory win, since SYM_INT32 mantissas are 4 bytes just like FLOAT32, and no layer supports packed sub-byte native param storage anyway. Deployment of already-quantized models is unaffected: deserializeTensor overwrites a FLOAT32 factory skeleton in place with SYM_INT32 quantization + mantissas (equal 4-byte payload passes the serial: deserializeTensor trusts the file dtype — heap overflow / NULL-qConfig write when a checkpoint's dtype differs from the pre-built skeleton #316 size guard) — no float staging, no requantize step.

Verification

• ctest --preset unit_test_debug: 100% tests passed out of 81 (baseline before refactor: same).
• cmake --build --preset examples: all 395 targets build, every example binary compiles.
• Mutation checks on the shared helper (temporarily broken, rebuilt, restored):
  • cfg->bias = NULL → UnitTestLinear, UnitTestSgd, UnitTestLayerWeightsApi, UnitTestQuantLayerIntegration all FAIL
  • conv groups 1→2 → UnitTestConv1d FAILS
• All touched .c/.h files clang-formatted (repo .clang-format).

Suggested closing comment for #270

Resolved per the 2026-07-20 decision: requireFloat32 stays — public factories require FLOAT32 param storage by design, since random init is defined on floats. SYM_INT32-native params are reached via FLOAT32-init + in-place requantize (documented in examples/mixed_width_mlp) or the LayerNorm/GroupNorm constant-fill factories; tests build SYM-native layers via the shared BorrowedLayer.h helpers (test/unit/support/), which replaced all eight file-local copies. No public-API capability is lost (details in PR); if a second consumer ever needs the requantize helper, promote it to TensorApi as a tensor utility.

Closes #270

🤖 Generated with Claude Code