open-standards/wai/changes/2026-11-09-conditioned-refinement.md

### A refinement conditioned on side information both ends hold: `wai.image.int_cond_refine`

- **One capability registered** (SPEC §5, *Refinement capabilities*): `wai.image.int_cond_refine`,
  refinement-only, `StandardDefined`, with the staged form *conditioned residual* and the
  payload `WCP1`. Its row of *Base admission* is `wai.image.int_refine`'s. A layer's next
  stage is three integer steps over the unit's current output and the **side planes** its
  `refines.side` names: the base prediction (the current output, or its `up2_predict` at the
  output's size), an integer network carried in the payload that reads the base prediction
  and the side planes and adds a correction clamped to `[0, 255]`, and a `WIR1` residual
  decoded over that prediction with the identity predictor. Every sink that holds the same
  side planes computes the same bytes, so the output is as exact as the base and the planes.
  The base, each side object and the layer are objects of their own, each named by its
  content hash and covered by its own receipt; the sink composes them and computes the
  stage, whose stage hash is the digest a signed `stage` claim states and a presenting sink
  checks.
- **One mechanism, two uses.** Over rendered content the side planes are G-buffers both sides
  hold (depth, normals, albedo), each carried as an exact object of its own, or the frame the
  sink renders itself from a `wai.splat.int_codec` object at a pinned pose with
  `wai-splat-render:i1`, which costs nothing on the wire. With no side plane, over a base at a
  lower resolution, the layer is the detail stream of a dual stream: the up2 of the
  low-resolution reference, and the detail the network reconstructs from it.
- **Side planes** ([staged-delivery](extensions/staged-delivery.md) §3.1): `refines.side`, read
  for the conditioned form and ignored for any other, is absent, `null`, or 1 to 4 entries,
  each a content hash or `{"object", "renderer": "wai-splat-render:i1", "pose"}` with a pose of
  splat-exact §2; any other value is `refines-malformed`. A plane is exact when its object was
  decoded through its manifest's capability, not a fallback, at `decode-equivalence`. §4.1
  step 4 checks each entry in order after base admission: the sink holds its plane
  (`side-absent`), and the plane is exact (`side-not-exact`). The two reasons join §4.2's
  closed list and the reasons a `stage` claim names (jwp-receipts §2.4.10). A plane is the
  sink's, held beside its chains and no part of a chain's state.
- **The payload** (staged-delivery §6.3, Appendix B): `WCP1`, a 12-byte header (`predictor`,
  `n_side`, `n_layers`, `act_hi`), the network in the layer form of
  [exact-upscale](extensions/exact-upscale.md) §3.1 (the first layer reads `3·(1 + n_side)`
  channels, the last writes 3), and a `WIR1` residual of the RGB8 unit kind with the identity
  predictor. Its checks run in a stated order with Appendix A.6's codes; `n_side` must be the
  count `side` names. Its declared cost adds the network's working bytes and its
  multiply-accumulates, which a sink may limit (`cost-over-limit`, `multiply-accumulates`).
- **Through the integer operator set.** The network is one `WHG1` graph, lowered by `wcp1/1`
  ([integer-operators](extensions/integer-operators.md) §11, Appendix B.6 of staged-delivery):
  `concat`, `rescale`, `conv`, `clamp` and `add`, loaded under `acc64` with its bounds
  certificate, which every payload that parses meets. The capability's `ops` member names the
  set, `acc64`, `wcp1/1` and E1's modes.
- **Carriage.** A layer that reads side planes travels as a `WAI1` object: a `WAI2`
  refinement component carries no `side` (SPEC §7.1, `refinement-side`), and a packer refuses
  a `WAI1` layer that carries one. One with no side plane packs and explodes as any layer.
- **Reference implementation.** `wai-rs`: `staged::wcp1` (the parse, the cost, the lowering,
  the decode through the graph, the arithmetic loop by loop, which the encoder holds the graph
  to, and the encoder), `staged::side` (`SideEntry`, `SidePose`, `read`, `with_side`),
  `staged::{is_conditioned, layer_units}`, `StageSink::{add_side, add_render,
  set_macs_limit}`, `StageChain::set_macs_limit`, `codecs::CAP_IMAGE_INT_COND_REFINE` with
  `AppliedForm::Conditioned`, the `WCP1` framing check, `RoleError::RefinementSide`; the
  session claim reads a conditioned layer's units from its `WCP1` payload.
- **Conformance.** `staged-conformance/cond/`, written and checked by `wai_staged_vectors`
  (which now builds with `splat_exact`): exact side planes; the dual stream; both together, an
  8 × 8 render with three 16 × 16 G-buffers; a rendered plane; a plane not held, then held;
  planes that are not exact (an unpinned decode, a fallback, the render of an unpinned splat
  set); a plane of another size; a base the row does not admit; `side` broken each way; each
  `WCP1` check broken once; cost limits on working bytes and on multiply-accumulates; and
  `cond/wai2/`. `staged_verify.py` replays every case with its own `WCP1` parser, its own
  network loop and its own sink, decodes each side object's PNG, and renders each plane with
  `live-conformance/splat_exact_verify.py`'s renderer.
- **Breaking:** `staged::StageRefusal` gains `SideAbsent` and `SideNotExact`, so
  `StageRefusal::ALL` holds 16 reasons where it held 14, and `codecs::AppliedForm` gains
  `Conditioned`: `api:rust:wai::staged::StageRefusal::ALL`,
  `api:rust:wai::codecs::AppliedForm::Conditioned`. A caller that matches `AppliedForm`
  exhaustively adds an arm for the conditioned form; one that reads `StageRefusal::ALL` as an
  array of 14 reads its length.