perf(ptl): replay shared CUDA segmentation features

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to lucid-yolo are documented here, following the Keep a Chan
 
 ### Added
 
+- `capture_network` now replays shared backbone and neck stages for segmentation, independently of `capture_segment_heads`. The default remains off; modified heads/forwards, accumulation and unsupported signatures retain native execution, with transient graph state cleared at fit boundaries (WP-193g).
+
 - **Opt-in CUDA network replay for oriented training.** `--model.capture_network true` records the existing backbone, neck and both oriented head branches, including their angle outputs. The native objective and state updates remain outside capture. Accumulation and overridden objectives keep the native route; the default stays off. The speed claim is limited to a small-batch workload (Nano OBB at batch 4, BF16, one L4): a single batch-8 pair changed fit time by only 4.10%, and replay raised peak reserved memory from 3974 to 4300 MiB, so check throughput and memory on your own batch size. See [WP-200](docs/work_packages/wp-200.md) for complete-fit measurements and limits.
 
 - **Opt-in CUDA replay of detection assignment and loss.** `--model.capture_loss true` records the existing loss forward/backward with a masked target workspace that grows from observed counts. Current label checks and schedules stay live; returned values own their storage and fit exit releases the recording. Default off, compatible with network and orthogonalization replay. See [WP-199](docs/work_packages/wp-199.md) for measurements and limits.

docs/ROADMAP.md

@@ -357,6 +357,7 @@ Opened by issue 2 on the tracker: R1 sec. 3.4.2 publishes the pose objective thi
 | 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 | 🔄 |
 | 193f | `perf(ptl): replay independent CUDA pose prediction stems` [DATA][GPU] | The existing pose flag records eighteen native stems independently through the shared prediction runner, preserving absent point gradients and bounded fit ownership · [log](work_packages/wp-193f.md#wp-193f) | Focused CPU/CUDA, real replay and lifecycle regressions; five isolated-L4 complete pairs with 12.97% median time reduction at batch 4 and byte-identical states; reserved memory increases; full gate, aggregate coverage and goldens not run | 193d,193e | 🔄 |
+| 193g | `perf(ptl): replay shared segmentation features` [DATA][GPU] | Opt-in backbone/neck replay preserves independent segmentation prediction gradients. Combines with head replay; accumulation and modified forwards stay native, with one fit-scoped signature · [log](work_packages/wp-193g.md#wp-193g) | `tests/ptl/test_segment_network_capture.py`; public-COCO byte parity; five paired isolated-L4 complete fits; focused tooling; full `make gate` and accelerator goldens not run (offline CI green at PR head 8ebf10e) | 193d, 193e | 🔄 |
 | 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

@@ -69,7 +69,7 @@ lucid-eval --checkpoint <checkpoint> --data_root /content/coco2017 --output seg_
 
 ### 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.
+`--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. With this option alone, common features, prototype fusion, assignment, losses, state updates and schedules stay native. Enable `capture_network` separately to replay the common features too.
 
 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.
 
@@ -145,10 +145,12 @@ For `task: keypoints`, the same flag records backbone and neck plus eighteen ind
 
 For `task: obb`, the flag records backbone, neck and the complete dual head, including both angle outputs. The native classification and oriented losses stay outside capture. Their empty-target expressions retain zero angle gradients. Overridden training consumers, classification losses or oriented helpers keep the complete native call; gradient accumulation also stays native. The oriented speed-up is likewise limited to a small-batch workload (Nano OBB at batch 4, BF16, one L4): a single batch-8 pair changed fit time by only 4.10%, and replay raised peak reserved memory from 3974 to 4300 MiB, so check throughput and memory on your own batch size. The measurements and remaining limits are in [WP-200](work_packages/wp-200.md).
 
-This path requires single-device CUDA automatic optimisation and `task: detect`, `task: keypoints` or `task: obb`. BF16 replay requires a final PyTorch 2.9 or newer release; 2.9 pre-release and NGC `a0` builds are excluded by design. 2.9 is the first verified runtime: older BF16 runs warn and stay eager because the 2.4 comparison did not meet the exact eager oracle. FP32 and FP16 replay of detection, oriented detection and pose shared features are checked on 2.4 as well; pose stem replay has run on 2.9.1 only ([WP-193f](work_packages/wp-193f.md)). CPU, MPS and other strategies warn and stay eager; other tasks or `compile_step` raise at construction. One image signature is recorded per fit. A partial batch uses eager execution without growing a graph cache. Changes to the recorded stages’ parameter/buffer storage, module modes, hooks or precision retire replay for the rest of that fit. The supplied network must keep its ordinary stage implementations and static Python configuration. Root forward overrides, stage instance-forward overrides and registered hooks use the eager path. Anomaly detection (`--trainer.detect_anomaly true`) also stays eager so backward NaN checks run normally. A failure while recording raises instead of falling back to eager (RNG state and buffers are restored first), so disable `--model.capture_network` if recording fails on your model. Higher-order differentiation is not supported.
+This path requires single-device CUDA automatic optimisation and `task: detect`, `task: keypoints`, `task: obb` or `task: segment`. BF16 replay requires a final PyTorch 2.9 or newer release; 2.9 pre-release and NGC `a0` builds are excluded by design. 2.9 is the first verified runtime: older BF16 runs warn and stay eager because the 2.4 comparison did not meet the exact eager oracle. FP32 and FP16 replay of detection, oriented detection and pose shared features are checked on 2.4 as well; pose stem replay has run on 2.9.1 only ([WP-193f](work_packages/wp-193f.md)). CPU, MPS and other strategies warn and stay eager; other tasks or `compile_step` raise at construction. One image signature is recorded per fit. A partial batch uses eager execution without growing a graph cache. Changes to the recorded stages’ parameter/buffer storage, module modes, hooks or precision retire replay for the rest of that fit. The supplied network must keep its ordinary stage implementations and static Python configuration. Root forward overrides, stage instance-forward overrides and registered hooks use the eager path. Anomaly detection (`--trainer.detect_anomaly true`) also stays eager so backward NaN checks run normally. A failure while recording raises instead of falling back to eager (RNG state and buffers are restored first), so disable `--model.capture_network` if recording fails on your model. Higher-order differentiation is not supported.
 
 Recording warmup restores RNG and BatchNorm buffers before the first real batch. Accumulation or custom optimiser/zero-grad hooks preserve live gradients outside the graph-owned backward buffers before they can be overwritten. AMP uses an uncached autocast scope as the PyTorch API requires. Validation, prediction and public `forward` calls stay eager. Checkpoints retain the ordinary parameter names and the flag, with no graph state. Each fit records afresh and drops its recording on completion or an exception. CUDA graph pools can increase reserved memory even when peak allocated memory falls; measure both on the intended workload. The measured scope and remaining validation gaps are in [WP-193c](work_packages/wp-193c.md).
 
+For segmentation, the same `--model.capture_network true` option records only backbone and neck. Prediction groups, prototype fusion and both losses keep their existing arithmetic and gradient boundaries. It can combine with `--model.capture_segment_heads true`, which records the prediction groups separately. Gradient accumulation stays native, as do overridden or compiled segmentation forwards. The default remains `false`; a recording is transient and follows the same fit cleanup and input-signature rules above. See [WP-193g](work_packages/wp-193g.md) for the measured workload and limits.
+
 ## Optional detection loss CUDA replay
 
 `--model.capture_loss true` replays the existing detection assignment and loss forward/backward with fresh predictions, targets and the current alpha tensor. Default `false`: capture costs setup time and retains CUDA workspace, so short or compute-bound runs may not benefit. It requires `task: detect`, single-device CUDA automatic optimisation and `compile_step: false`. It can combine with `capture_network`, `capture_orthogonalization` and `capture_updates`; `capture_loss` itself records no optimizer update, so the optimizer step is whatever those two optimizer options select (the existing eager path when both are off).

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

@@ -26,6 +26,8 @@
 
 --8<-- "work_packages/wp-193f.md:engineering"
 
+--8<-- "work_packages/wp-193g.md:engineering"
+
 --8<-- "work_packages/wp-194.md:engineering"
 
 --8<-- "work_packages/wp-195.md:engineering"

docs/work_packages/wp-193d.md

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

docs/work_packages/wp-193e.md

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

docs/work_packages/wp-193f.md

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