refactor(diffusion): centralize sampling and replay loops

[leviking98z-rgb]

Summary

• add model-neutral DiffusionRunner and VideoDiffusionRunner implementations for schedule validation, initial-latent handling, sparse trajectory capture, sampling, replay, autocast/precision policy, single-step prediction, and the default trainable surface
• place diffusion-specific contracts and control flow under unirl/models/diffusion/, while retaining the pre-existing unirl.models.types.diffusion and unirl.models.types.replay_result paths as compatibility facades
• migrate the ten ordinary image/video stages: SD3, Z-Image, Qwen-Image (including Edit-Plus by inheritance), Boogu-Image, Flux.2-Klein, WAN 2.1/2.2, HunyuanVideo 1.0/1.5, and HunyuanImage 3
• preserve model-specific behavior through narrow hooks for SD3 batched replay, Qwen packed geometry, Boogu CFG range/RoPE, Flux eval mode, WAN 2.2 secondary guidance, HunyuanVideo 1.5 vision constants, and HI3 late-bound noise/state
• keep BAGEL packed/Navit replay and LTX2 joint audio-video SDE as explicit transition-kernel exceptions, enforced by the stdlib framework guard
• update the contributor contract to route future ordinary diffusion models through the shared model-domain package

The layer is a net reduction of 1,667 lines against refactor/model-plugin-sdk while retaining concrete stage dotpaths and public stage methods.

Related Issue

Related to Tencent-Hunyuan#285.

Test Plan

• SKIP=no-commit-to-branch pre-commit run --all-files --show-diff-on-failure
• python lint/check_framework_contracts.py
• python lint/check_architecture_boundaries.py
• python lint/check_experimental_boundaries.py
• python lint/check_recipe_targets.py
• python -m compileall -q unirl lint experimental/refl/models/types.py
• one-off Python 3.12 import/identity check: canonical unirl.models.diffusion exports and the two retained unirl.models.types compatibility facades resolve to the same classes
• one-off Python 3.12 CPU fake-kernel harness: generic image/video sampling, sparse trajectory storage, replay, prediction, trainable surface, precision, and modality passed after the package move
• earlier one-off Python 3.12 CPU fake-kernel harness: sampling, sparse trajectory storage, replay/subset replay, prediction, trainable surface, precision, and modality passed for all 10 migrated stages
• earlier one-off model-hook checks: WAN 2.2 guidance fallback, HunyuanVideo 1.5 vision kwargs, HI3 state isolation and deterministic late-bound NoiseRecipe, Boogu CFG-range/RoPE cache, and Flux replay mode restoration passed
• earlier one-off SD3 FlowSDEStrategy harness: serial and one-forward batched replay produced identical log-probs and previous-sample means
• earlier one-off Hydra composition harness: 120/120 examples/**/*.yaml recipes composed and resolved
• GPU checkpoint/training parity not run; reason: this environment has no accelerator or model checkpoints. Numerical transformer/SDE kernels are unchanged, but a real-checkpoint smoke remains appropriate before merging.

Compatibility / Risk

• No recipe schema, _target_ path, checkpoint, dataset, request, or LatentSegment format changes.
• Concrete stages inherit the same diffuse, replay, predict_noise_at_step, and trainable_module surface from the runner. HI3 additionally accepts the common optional initial_latents argument.
• Existing imports from unirl.models.types.diffusion and unirl.models.types.replay_result remain valid. The temporary unirl.models.types.diffusion_runner path existed only inside this unmerged Draft stack and is replaced by the canonical unirl.models.diffusion package.
• Replay now consistently places stored trajectory tensors on bundle.device; this preserves existing SD3/Z-Image/Boogu dedicated-engine behavior and makes the same CPU-returned trajectory path available to the other ordinary stages.
• Video stages use one centralized 6D replay check and modality=VIDEO factory. BAGEL and LTX2 retain their specialized runners.
• This is a stacked Draft PR based on refactor/model-plugin-sdk; review commits 317d698 and 747f112 for this layer.

Reviewer Notes

• Suggested review order: unirl/models/diffusion/contracts.py, unirl/models/diffusion/runner.py, one image hook set, one video hook set, HI3, then lint/check_framework_contracts.py.
• The models/diffusion location is intentionally scoped to model-facing contracts and shared model execution. Sampling parameters remain under unirl/types, SDE math remains under unirl/sde, and training orchestration remains outside the model layer.
• AI assistance was used for implementation and validation; the complete base diff, package move, compatibility facades, and every model-specific hook were reviewed before publication.
• Duplicate-work check: upstream perf(diffusion): extend batched-step replay to qwen_image, z_image, flux2_klein Tencent-Hunyuan/UniRL#156 overlaps the same image-stage files to extend batched replay. This PR does not reimplement that optimization; _replay_batched is the integration seam, and a future rebase must retain the Qwen/Z/Flux fast paths from perf(diffusion): extend batched-step replay to qwen_image, z_image, flux2_klein Tencent-Hunyuan/UniRL#156. Upstream fix(fastvideo): use UniRL canonical UniPC strategy Tencent-Hunyuan/UniRL#251 touches WAN 2.1 timestep/FastVideo behavior and must likewise be preserved when rebasing. No open upstream PR provides a generic sampling/replay runner.
• One-off verification harnesses were intentionally not committed, following the repository policy against a tests/ replacement tree.
• Standalone current-main upstream submission: refactor(diffusion): share single-stream sampling and replay loops Tencent-Hunyuan/UniRL#299. This stacked Draft remains the fork-side decomposition and does not directly target the official repository.

Checklist

• I reviewed the changed code and removed unrelated/generated artifacts.
• I updated tests, docs, and configs where needed, or explained why not.