feat(v7-h05): per-step train event helper from extras

Closes V7-H05 (cppmega-mlx-wvzv) building block: synthesises a
sequence of {step, loss, lr, grad_norm, mem_mb, throughput_tok_s,
ts} events from finalised stage_train extras — same payload shape a
real /ws/train/{job_id} WS push will eventually use.

The UI can render the per-step table + sparkline as soon as the
result modal opens, without waiting for a deeper stage_train
callback rewrite (deferred follow-up).

Tests (tests/v4/test_train_events.py): 4/4 — documented keys,
throughput + mem populated, missing lr_trajectory tolerated,
empty losses yields no events.

Author: apstenku123

cppmega_v4/runtime/train_events.py

@@ -0,0 +1,50 @@
+"""V7-H05: per-step training event extraction from stage_train extras.
+
+Produces a stream of {step, loss, lr, grad_norm, mem_mb,
+throughput_tok_s, ts} events derived from finalised extras. Until
+stage_train emits live callbacks (deeper rewrite), the UI can render
+post-hoc per-step events the moment the modal opens — same payload
+shape a real /ws/train/{job_id} stream will eventually push.
+
+Usage:
+  events = list(train_events_from_extras(extras, batch=1, seq=16))
+  for e in events:
+      ui.append_row(e)
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Iterator
+
+
+def train_events_from_extras(extras: dict, *,
+                              batch: int = 1, seq: int = 16,
+                              start_ts: float | None = None,
+                              ) -> Iterator[dict]:
+    """Yield per-step training events from stage_train extras."""
+    losses = list(extras.get("losses", []))
+    lrs = list(extras.get("lr_trajectory", []))
+    elapsed_ms = float(extras.get("elapsed_ms", 0.0)) or 1.0
+    n = max(1, len(losses))
+    per_step_ms = elapsed_ms / n
+    tokens_per_step = max(1, batch * seq)
+    throughput = tokens_per_step / max(per_step_ms / 1000.0, 1e-6)
+    base_ts = start_ts if start_ts is not None else time.time()
+    mem_peak = extras.get("memory_peak_bytes")
+    mem_mb = (round(int(mem_peak) / (1024 * 1024), 4)
+              if mem_peak else None)
+    for i, loss in enumerate(losses):
+        lr = float(lrs[i]) if i < len(lrs) else None
+        yield {
+            "step": i,
+            "loss": float(loss),
+            "lr": lr,
+            "grad_norm": None,  # not snapshotted per-step today
+            "mem_mb": mem_mb,
+            "throughput_tok_s": round(throughput, 4),
+            "ts": round(base_ts + (i + 1) * per_step_ms / 1000.0, 6),
+        }
+
+
+__all__ = ["train_events_from_extras"]

tests/v4/test_train_events.py

@@ -0,0 +1,50 @@
+"""V7-H05: per-step train event generator from extras."""
+
+from __future__ import annotations
+
+from cppmega_v4.runtime.train_events import train_events_from_extras
+
+
+def _extras() -> dict:
+    return {
+        "losses": [5.0, 4.5, 4.1],
+        "lr_trajectory": [1e-4, 3e-4, 1e-3],
+        "elapsed_ms": 30.0,
+        "memory_peak_bytes": 4 * 1024 * 1024,
+    }
+
+
+def test_v7_h05_events_per_step_with_documented_keys():
+    events = list(train_events_from_extras(_extras(),
+                                             batch=1, seq=16))
+    assert len(events) == 3
+    keys = {"step", "loss", "lr", "grad_norm", "mem_mb",
+            "throughput_tok_s", "ts"}
+    for e in events:
+        assert keys.issubset(e.keys()), f"missing keys in {e}"
+    assert [e["step"] for e in events] == [0, 1, 2]
+    assert [e["loss"] for e in events] == [5.0, 4.5, 4.1]
+    assert [e["lr"] for e in events] == [1e-4, 3e-4, 1e-3]
+
+
+def test_v7_h05_throughput_positive_and_mem_present():
+    events = list(train_events_from_extras(_extras(),
+                                             batch=1, seq=16))
+    for e in events:
+        assert e["throughput_tok_s"] > 0
+        assert e["mem_mb"] == 4.0
+        assert e["ts"] > 0
+
+
+def test_v7_h05_handles_missing_lr_trajectory():
+    e = {"losses": [1.0, 2.0]}
+    events = list(train_events_from_extras(e, batch=1, seq=8))
+    assert len(events) == 2
+    for ev in events:
+        assert ev["lr"] is None
+        assert ev["mem_mb"] is None
+
+
+def test_v7_h05_empty_losses_yields_no_events():
+    events = list(train_events_from_extras({"losses": []}))
+    assert events == []