Files
ComfyUI-H3-Continuum-Tiled/docs/V38_OPEN_INTEGRATION_CONTRACT.md
T

85 lines
3.7 KiB
Markdown

# V3.8 Open Integration Contract
This document defines the supported boundary between H3 Continuum V3.8 and
external processing, decoder, and acceleration nodes. It does not add a public
node or change the Sampling, State, Session, Run Storage, or Assembly Plan
schemas.
## Supported pipeline
```text
H3 Continuum Sampler V3.8
-> external latent processor or latent upscaler (optional)
-> H3 Continuum Second Pass
-> Core Video/Audio Decode
-> H3 Continuum Finalize
-> Core Save Video
```
Pixel upscalers remain outside the latent boundary. If a workflow decodes to
pixels for processing, it must encode the result back to one H3 video LATENT per
physical group before Second Pass.
## External processor contract
An external processor may change only the spatial geometry of the video
latents. It must preserve:
- physical-group count and order;
- one indivisible entry for every Long Terminal Merge group;
- video batch, 24 channels, and temporal latent length;
- one common target H/W across every physical group;
- the matching first-pass audio latent list and its order;
- the original Assembly Plan input.
Spatial video dimensions may be preserved or enlarged. Smaller dimensions,
NaN/Inf values, changed B/C/T geometry, a changed group count/order, or a changed
audio shape are rejected before Second Pass Sampling.
Second Pass rebuilds supported conditioning for the target geometry, samples
complete physical groups, and returns a copied Assembly Plan with only target
geometry and Second Pass execution metadata added. It does not mutate the input
plan or Run Storage. The accepted first-pass audio LATENT objects are returned
unchanged; temporary audio produced during video refinement is discarded.
## Decoder boundary
H3 Continuum has no decoder allowlist. Any Core or third-party Video/Audio VAE
path, including a TensorRT-backed VAE, is compatible when it implements the
public ComfyUI contracts and produces the normal decoded types consumed by
Finalize:
- `IMAGE`: `[frames, height, width, channels]` per physical group;
- `AUDIO`: a mapping with `waveform` and positive `sample_rate` per physical
group.
Finalize depends on those public decoded types and the Assembly Plan, not on a
decoder class name. Decoder fallback, tiling, device placement, and acceleration
are owned by the decoder or ComfyUI Core.
## Acceleration boundary
SageAttention, Sol-Attn, Spectrum, and comparable accelerators remain external
MODEL wrappers. Continuum uses ComfyUI's public ModelPatcher wrapper APIs,
preserves existing wrapper/model options on call-local clones, and publishes
only the documented `h3_continuum` interoperability hint when continuation
context exists.
Continuum does not select an attention backend, import accelerator-private
functions, or globally monkey-patch an accelerator. Missing optional accelerator
markers are informational and never become package dependencies.
## Ownership summary
| Owner | Responsibility |
|---|---|
| Continuum | Physical-group identity/order, temporal ownership, conditioning reconstruction, Second Pass validation/Sampling, first-pass audio passthrough, target-geometry plan copy, Finalize assembly |
| External processor | Spatial Video LATENT transformation while preserving B/C/T, group order, and finite values |
| Core or decoder node | Video/Audio VAE decode/encode behavior, tiling, fallback, device lifecycle |
| Accelerator wrapper | Sage/Sol/Spectrum backend selection and wrapper lifecycle |
| User workflow | Correctly wire the matching Video LATENT list, first-pass Audio LATENT list, and original Assembly Plan |
The contract deliberately avoids an All-in-One node. New processors and
decoders can integrate through public ComfyUI types without requiring a
Continuum release, provided these invariants remain true.