feat(v7-c06): int8 + fp16 checkpoint compression helpers

Closes V7-C06 (cppmega-mlx-ylyh): per-tensor symmetric int8
quantisation (weights) + fp16 cast (opt-state moments).

  - quantize_int8(t) → (int8 q, fp32 scale) using
    scale = max(|t|) / 127.
  - dequantize_int8(q, scale) → fp32.
  - cast_fp16(t) + uncast_to_fp32(t) for the AdamW m/v path.

Expected size reduction: 4x weights, 2x opt-state.

Tests (tests/v4/test_checkpoint_quantize.py): 5/5 — round-trip
error bounded by scale, 4x size win, fp16 round-trip within
fp16 precision, zero tensor + wide-dynamic-range edge cases.

CheckpointStage wiring (weights_dtype=int8 / opt_state_dtype=fp16
modes + V7-C03 metadata round-trip flags) is the integration
follow-up; this lands the math.

Author: apstenku123

cppmega_v4/runtime/checkpoint_quantize.py

@@ -0,0 +1,40 @@
+"""V7-C06: per-tensor symmetric int8 quantisation + fp16 cast helpers.
+
+quantize_int8(t) → (q_int8, scale_fp32)
+dequantize_int8(q, scale) → fp32 tensor
+
+cast_fp16(t) → fp16; uncast_to_fp32 just calls .astype(mx.float32).
+"""
+
+from __future__ import annotations
+
+import mlx.core as mx
+
+
+def quantize_int8(t: mx.array) -> tuple[mx.array, float]:
+    """Symmetric int8: scale = max(abs(t)) / 127, q = round(t / scale)."""
+    if t.size == 0:
+        return mx.zeros(t.shape, dtype=mx.int8), 1.0
+    absmax = float(mx.max(mx.abs(t.astype(mx.float32))).item())
+    scale = max(absmax / 127.0, 1e-9)
+    q = mx.round(t.astype(mx.float32) / scale)
+    q = mx.clip(q, -127, 127).astype(mx.int8)
+    return q, float(scale)
+
+
+def dequantize_int8(q: mx.array, scale: float) -> mx.array:
+    return q.astype(mx.float32) * scale
+
+
+def cast_fp16(t: mx.array) -> mx.array:
+    return t.astype(mx.float16)
+
+
+def uncast_to_fp32(t: mx.array) -> mx.array:
+    return t.astype(mx.float32)
+
+
+__all__ = [
+    "quantize_int8", "dequantize_int8",
+    "cast_fp16", "uncast_to_fp32",
+]

tests/v4/test_checkpoint_quantize.py

@@ -0,0 +1,52 @@
+"""V7-C06: int8 + fp16 checkpoint compression helpers."""
+
+from __future__ import annotations
+
+import mlx.core as mx
+import pytest
+
+from cppmega_v4.runtime.checkpoint_quantize import (
+    cast_fp16, dequantize_int8, quantize_int8, uncast_to_fp32,
+)
+
+
+def test_v7_c06_int8_round_trip_bounded_error():
+    t = mx.random.normal(shape=(32, 32), key=mx.random.key(0))
+    q, scale = quantize_int8(t)
+    assert q.dtype == mx.int8
+    deq = dequantize_int8(q, scale)
+    # Quantisation error bounded by scale (one int8 step ≈ scale/2).
+    err = float(mx.max(mx.abs(t - deq)).item())
+    assert err <= scale * 1.0 + 1e-6
+
+
+def test_v7_c06_int8_size_savings_4x():
+    """fp32 → int8 should be 4x smaller in byte count."""
+    t = mx.zeros((128,), dtype=mx.float32)
+    q, _ = quantize_int8(t)
+    # fp32 = 4 bytes, int8 = 1 byte; per-element 4x.
+    assert q.dtype.size * 4 == 4  # int8 size * 4 == fp32 size
+
+
+def test_v7_c06_fp16_round_trip_close_to_fp32():
+    t = mx.random.normal(shape=(64,), key=mx.random.key(1))
+    h = cast_fp16(t)
+    back = uncast_to_fp32(h)
+    # fp16 to fp32 round trip within fp16 precision.
+    err = float(mx.max(mx.abs(t - back)).item())
+    assert err < 1e-2
+
+
+def test_v7_c06_int8_handles_zero_tensor():
+    t = mx.zeros((4, 4), dtype=mx.float32)
+    q, scale = quantize_int8(t)
+    deq = dequantize_int8(q, scale)
+    assert mx.allclose(deq, t, atol=1e-9)
+
+
+def test_v7_c06_int8_handles_large_dynamic_range():
+    t = mx.array([[-1000.0, 0.0, 1000.0], [-0.001, 0.0, 0.001]])
+    q, scale = quantize_int8(t)
+    deq = dequantize_int8(q, scale)
+    # Large dynamic range: error bounded by scale (8/127 ≈ ).
+    assert float(mx.max(mx.abs(t - deq)).item()) < scale * 1.1