perf(ptl): replay independent CUDA segmentation predictions

CHANGELOG.md

@@ -10,6 +10,8 @@ All notable changes to lucid-yolo are documented here, following the Keep a Chan
 
 - **Opt-in shared-feature CUDA replay for pose training.** `--model.capture_network true` can record the existing backbone and neck for `task: keypoints`; the head stays native so a batch with no assigned positives keeps absent point-stem gradients. Accumulated pose runs, runs with a fully frozen backbone and neck, and heads with changed topology, hooks or forwards stay native. The default remains off. The speed claim is limited to a small-batch workload (batch 4, one L4): a single batch-16 pair changed fit time by 2.50%, and replay lowered peak allocated memory while raising peak reserved memory, so check throughput and both memory figures on your own batch size. See [WP-193d](docs/work_packages/wp-193d.md) for complete-fit measurements and validation limits.
 
+- **Opt-in replay of independent CUDA segmentation predictions.** `--model.capture_segment_heads true` records existing prediction calls and their first-order backward on single-device BF16 mixed training with torch 2.9 or newer, without accumulation. Byte-exact agreement with native training is verified only on NVIDIA L4 (sm_89) with torch 2.9.1+cu129; other GPUs and torch builds are unverified. Separate stem and mask-gradient boundaries retain absent gradients for unused masks. Unsupported contracts stay native; recording failures raise after restoring running buffers and RNG state. The default is off because graph pools retain device memory. See [WP-193e](docs/work_packages/wp-193e.md) for the measured small-batch scope and validation limits.
+
 - **Opt-in detection network CUDA replay.** `--model.capture_network true` records the existing backbone, neck and head forward/backward work while assignment, losses and state updates remain in the normal training loop. One signature is retained per fit; unsupported configurations stay eager, but a failure while recording raises (RNG state and buffers are restored first). BF16 replay requires a final torch 2.9 or newer release. Default off, separate from `compile_step`, and no graph state is checkpointed. The speed claim is limited to a small-batch workload: batch-32 screens changed direction. See [WP-193c](docs/work_packages/wp-193c.md) for measurements and validation limits.
 
 - **Opt-in CUDA replay of MuSGD update preparation.** `--model.capture_updates true` records the existing preparation and momentum work; changing learning rates and parameter writes stay outside capture. Warmup restores state, loading invalidates recordings, and unsupported inputs keep the native route; a failure while recording raises (gradients and momentum are restored first), so disable the flag if recording fails on your model. The default stays off because setup and device workspace have a cost.

docs/ROADMAP.md

@@ -355,6 +355,7 @@ Opened by issue 2 on the tracker: R1 sec. 3.4.2 publishes the pose objective thi
 | 193b | `perf(optim): batch compatible MuSGD matrices and momentum` [DATA][GPU] | CUDA matrices sharing a smaller dimension of at most 256 run one native Newton--Schulz batch on zero-extended columns, cropped back before their own scale, gains and decay; independent CUDA momentum buffers advance through three foreach operations. Overlapping memory, parameter subclasses and other devices keep the scalar route. No coefficient, iteration count or schedule changes · [log](work_packages/wp-193b.md#wp-193b) | `tests/optim/test_padded_musgd.py` (mixed-width scalar oracle, storage budget, row region, DLPack overlap, alias and restored-state guards, foreach recurrence on CPU and CUDA); five paired isolated-L4 complete `Trainer.fit` runs with a median reduction of 11.19%; full `make gate` and `make gate-gpu` not run by the author, so the status does not move to done until they do | 193 | 🔄 |
 | 193c | `perf(ptl): replay detection network CUDA graphs` [DATA][GPU] | Opt-in forward/backward replay of the existing backbone, neck and head, leaving dynamic targets, losses, schedules, optimizer and EMA eager. One recording per fit; default off, no arithmetic changes · [log](work_packages/wp-193c.md#wp-193c) | Focused CUDA trajectory, buffer, precision, fallback and lifecycle regressions; five paired isolated-L4 complete fits above 8%; full `make gate`, accelerator goldens and final accuracy remain outstanding | 193b | 🔄 |
 | 193d | `perf(ptl): replay shared features in small-batch CUDA pose training` [DATA][GPU] | Pose replays the existing backbone and neck while its head stays native, preserving absent point gradients. The default stays off; accumulated runs, a fully frozen backbone and neck, and heads with changed topology, hooks or forwards keep the native route · [log](work_packages/wp-193d.md#wp-193d) | `tests/ptl/test_pose_network_capture.py`, whose synthetic `layout="empty"` case of `test_pose_trainer_matches_native` evidences the absent point-stem gradients of a batch with no assigned positives — the public-COCO parity run does not; public-COCO byte parity and five isolated-L4 complete fits with 11.17% median time reduction at batch 4 (one exploratory batch-16 pair: 2.50%; peak allocated memory down, reserved up); torch 2.4/2.9 focused checks and full pre-commit; full `make gate`, accelerator goldens and final accuracy not run | 193c | 🔄 |
+| 193e | `perf(ptl): replay independent segmentation predictions` [DATA][GPU] | Opt-in BF16 CUDA prediction groups preserve native gradient absence and per-stem accumulation. One topology pass and an attribute certificate retain live storage and observer checks; default, evaluation and unsupported modes stay native · [log](work_packages/wp-193e.md#wp-193e) | `tests/ptl/test_segment_head_capture.py`; exact public-COCO states; five paired isolated-L4 complete fits; full pre-commit; full `make gate` not run | 193c | 🔄 |
 | 194 | `refine(tests): static checks to hooks, plain test names` | File-content tests leave pytest: the `_viz`/matplotlib import boundary becomes ruff `TID251`, the top-k and packaged-recipe text pins the `content-pins` hook, and live-tree "hook passes" copies are dropped. Test names lose `a an the its their is are does that` · [log](work_packages/wp-194.md#wp-194) | `scripts/_tests/test_audit_content_pins.py`; collection count unchanged; `make gate` green | 193 | ✅ |
 | 195 | `perf(data): batch rotated-box clipping and refitting` [DATA][GPU] | Finite float32 CPU augmentation boxes without gradients share the existing clip and orientation-preserving fit in equal-vertex-count groups. Ring order and instance order are preserved; other inputs keep the scalar route · [log](work_packages/wp-195.md#wp-195) | `tests/data/test_rotated_clip_batch.py`; unchanged public-DOTA training states and five paired isolated-L4 complete fits; focused data tests and full pre-commit; full `make gate` not run | 194 | 🔄 |
 | 196 | `docs(site): tabs, method pages, one file per WP` | The single left menu listed every register at once, three pages ran past 500 lines, the site never explained the method, and findings and results were copied between pages. A four-tab top bar (Home, Results, Models, Project); two Method pages with animated SVGs (how the detector works; NMS against NMS-free). The report splits into one page per section; each WP's findings move to `work_packages/wp-<id>.md`, which the research and engineering phase pages include by section (D28), and the Project tab lists phases first. Model cards share one layout with an animated SVG, and include the report's result tables rather than copying them. Every WP named in the docs links to its page, each WP page opens with a roadmap-derived header (logs, dependencies, neighbours), and the README's Mermaid diagram becomes the animated SVG. For search engines and agents, a build hook gives every page a distinct title and description, Open Graph tags with a static preview card, JSON-LD on the home page, a markdown copy at `<page>/index.md`, and `llms.txt` / `llms-full.txt`; the README links the site and `CITATION.cff` lands · [decision](DECISIONS.md) | `make docs` strict-green (every anchor and include resolves); `audit_wp_links.py` (`wp-links`) refuses an unlinked mention or a stale WP header; `audit_docs_site.py` honours `not_in_nav`; `audit_docs_present.py` checks each roadmap log link against its own target file and `check_work_package_files` refuses unnumbered or unincluded WP files; `audit_figure_captions.py` reads the report pages; `_WP_FLOOR` 196, `_DECISION_FLOOR` 28; `make gate` green | 195 | ✅ |

docs/TRAINING.md

@@ -67,6 +67,14 @@ lucid-eval --checkpoint <checkpoint> --data_root /content/coco2017 --output seg_
 
 `lucid-eval` reads the task off the checkpoint and scores masks when the checkpoint has them, so the same command serves both COCO tiers. `--masks false` scores boxes only from a segmentation checkpoint.
 
+### Independent segmentation predictions on CUDA
+
+`--model.capture_segment_heads true --trainer.precision bf16-mixed` records the existing segmentation prediction routines, including their first-order backward work. The default is `false`. Box/class stems remain independent; coefficients, prototypes and semantic logits have separate backward nodes so an empty mask objective keeps absent gradients. Common features, prototype fusion, assignment, losses, state updates and schedules stay native.
+
+Byte-exact agreement with native training is verified only on NVIDIA L4 (sm_89) with torch 2.9.1+cu129; other GPUs and torch builds are unverified. The route requires PyTorch 2.9 or newer, one CUDA device, automatic optimisation and `accumulate_grad_batches=1`. Gradient accumulation stays native because replay was validated only at `accumulate_grad_batches=1`, not because of a known defect in the recorded backward. CPU, MPS, FP32, FP16 and older BF16 runtimes warn and use native calls; evaluation stays native too. Custom or changed prediction dispatch, hooks, frozen prediction parameters, aliased storage and retained feature gradients retire replay for the fit. Each prediction group records one input signature per fit (shape, stride, dtype, device, gradient flag and CUDA stream); a call with any other signature, a partial batch included, runs the native head without adding another graph, and the recorded graph pools stay reserved until the fit ends, so a run whose batch shapes keep changing pays that memory without replaying. Copying, checkpoints and fit teardown retain the original parameter names and no recording.
+
+A recording failure raises after restoring running buffers and RNG state; disable the flag to keep that run native. The flag retains CUDA graph pools, so check reserved memory and throughput on the actual batch size. A replayed step's mask coefficients, prototypes and semantic logits live in CUDA graph memory that the next replay overwrites in place; box and class predictions are copies. Anything that keeps those three tensors, or a gradient adopted from their backward, beyond the training step that produced them has to clone it. Measurements and rejected alternatives belong to [WP-193e](work_packages/wp-193e.md#wp-193e); a small-batch result does not establish a large-batch speed-up.
+
 ## 🕺 Keypoints — COCO 2017 `person_keypoints`
 
 The same COCO tree again, read through its other annotation file. `num_keypoints` is required and has no default — the point count is a property of the annotation schema, not something a model can pick.

docs/engineering/phase-17-pose-objective-parity.md

@@ -22,6 +22,8 @@
 
 --8<-- "work_packages/wp-193d.md:engineering"
 
+--8<-- "work_packages/wp-193e.md:engineering"
+
 --8<-- "work_packages/wp-194.md:engineering"
 
 --8<-- "work_packages/wp-195.md:engineering"

docs/work_packages/wp-193c.md

@@ -2,7 +2,7 @@
 
 > Engineering log · [Phase 17 — R1 pose-objective parity](../engineering/phase-17-pose-objective-parity.md)
 >
-> 🔗 Depends on [WP-193b](../work_packages/wp-193b.md) · Needed by [WP-193d](../work_packages/wp-193d.md)
+> 🔗 Depends on [WP-193b](../work_packages/wp-193b.md) · Needed by [WP-193d](../work_packages/wp-193d.md), [WP-193e](../work_packages/wp-193e.md)
 >
 > ⬅️ [WP-193b](../work_packages/wp-193b.md) · [Roadmap](../ROADMAP.md) · [WP-193d](../work_packages/wp-193d.md) ➡️
 

docs/work_packages/wp-193d.md

@@ -4,7 +4,7 @@
 >
 > 🔗 Depends on [WP-193c](../work_packages/wp-193c.md) · Needed by none
 >
-> ⬅️ [WP-193c](../work_packages/wp-193c.md) · [Roadmap](../ROADMAP.md) · [WP-194](../work_packages/wp-194.md) ➡️
+> ⬅️ [WP-193c](../work_packages/wp-193c.md) · [Roadmap](../ROADMAP.md) · [WP-193e](../work_packages/wp-193e.md) ➡️
 
 <!-- --8<-- [start:engineering] -->