refactor(optimizer)!: unify SGD step arms + updateMath knob (#308, #310)

[LeoBuron]

Two-issue stack on the SGD update path, executed via SDD (per-task reviews + final whole-branch review, verdict: merge-ready).

#308 — unify SGD step arms

• sgdStepM gains a momentum==0 fast path: one stateless executeOp per parameter (param -= lr*(grad + wd*param)), mathematically identical to the two-op momentum path at momentum==0, and never touches optim->states.
• sgdMCreateOptim allocates no momentum-state buffers at momentumFactor==0 (optim->states == NULL) — real RAM back on MCU targets; freeOptimSgdM handles the no-states case. The ten duplicated per-layer state-building blocks collapsed into one uniform post-loop (−73 lines).
• The unreachable plain-SGD arm is gone: sgdStep deleted, optimizerType_t is now { SGD_M } (verified unserialized anywhere), vtable has one entry. Its three direct test callers (the mutation-hardened optimizer: SYM_INT32 param/momentum update has a fixed-scale dead-zone (sub-ULP updates vanish) #279 dead-zone fixtures) are ported to the unified step with fixture math, iteration counts, seeds, and assertions byte-identical.
• New semantic note: momentumFactor is creation-fixed — it now decides state allocation (documented in SgdApi.h).

#310 — updateMath knob

• sgdMCreateOptim gains a 7th parameter, by-value arithmetic_t updateMath, stored on sgd_t and fed into all three update opSpecs (previously hardcoded {ARITH_FLOAT32, HALF_AWAY} — a SYM-arithmetic update was structurally impossible).
• Default {ARITH_FLOAT32, HALF_AWAY} = zero numeric movement; all ~48 test call sites + 9 example call sites swept mechanically, no expectation changed anywhere.
• Anything but ARITH_FLOAT32 fails fast at creation (sgdInit) AND at step time (sgdStepM entry, protects hand-assembled optimizers — the update kernels raw-cast float*). Both guards death-tested; the creation death test doubles as an arg-forwarding pin.
• Rounding ownership documented at the arithmetic/executeOp: rounding mode is storage-owned (quantization) but is conceptually operation-owned #282 seam: updateMath.roundingMode governs the funnel prologue (inert for FLOAT32); the OUT_WRITE epilogue rounds by each target's own qConfig — where the optimizer: SYM_INT32 param/momentum update has a fixed-scale dead-zone (sub-ULP updates vanish) #279 SR dead-zone escape lives.
• Known accepted limit (from the plan): with only FLOAT32 admitted, the opSpec feed lines have no behaviorally distinguishing test; they are pinned by the two guards + a 7-arg _Static_assert signature contract. The first real second arm owns the distinguishing tests.

Also in this PR

• FEATURES.md optimizer section corrected (removed a false optimizerInit claim; exercised-vs-implied dtype wording; knob + stateless-SGD documented).
• Stale pre-feat(optimizer): route SGD update through executeOp — per-param dtype (#278), SRHTE dead-zone escape (#279), own momentum config (#277) #284/optimizer: remove now-vestigial qType param / qtype field (dead after #278 executeOp routing) #283 comments swept in train_c_sym.c, mem_instrument.c (plus a NULL-states guard there), and two test files.
• Rebased onto develop after d1060c3 (PR Develop #311 follow-up); overlapping comment rewrites resolved in favor of the branch's more complete versions (they include the knob semantics).

Verification

• ctest --preset unit_test_debug: 72/72 (re-run post-rebase), incl. 2 new death tests + 2 new optimizer: unify SGD step arms — plain sgdStep is unreachable; momentum==0 pays for momentum #308 contract tests; strict TDD evidence per task in .superpowers/sdd/task-*-report.md.
• cmake --build --preset examples: all example binaries build (rot guard).
• uv run pytest: 29/29.
• The in-flight HAR axis-1 sweep was never touched: no examples_memprofile build, no logs/ writes (verified via find -newer).

Closes #308
Closes #310

Note: develop-merge does not auto-close — close both manually after merge. Follow-up to file: sizeStates rename (doubles as param count; misnomer sharpened now that states can be NULL).

🤖 Generated with Claude Code