pin_renorm: a band-matched mode, because sigma is a no-op here

The ratchet drifts the high-band FRACTION of the pin latent. A fraction
is scale-invariant, and a uniform rescale is all `pin_renorm=on` ever
did. Driven end to end with a 12.74% band drift planted in hop 2:
`sigma` applied x0.9651 and left the drift at +12.74%; `band` took it
to -0.04%. There is no gain or anchor choice that rescues a
scale-invariant statistic from a scale -- the lever was mis-specified,
not mis-tuned. Kept as `sigma` because pre-0.5 workflows saved "on".

pin_renorm is now ["off", "sigma", "band"]; "on" maps to "sigma", and
the combo keeps its widget slot.

Two defects caught on the way, both of the kind that look like success:

match_band first used `k = target * sigma / hi_sigma`, but scaling the
high band changes the sigma it is a fraction of, so the target moves as
you apply it -- it landed 5% short, in the right direction. It now
solves the orthogonal fixed point and refines against the measured
statistic.

The test fixture used torch.randn, whose high-band fraction is 0.966 --
against its ceiling, where the clamp does the correcting and every
assertion measures the clamp. Real latents sit at 0.3643; the fixture
now lands there and an assertion holds it in that regime.

Also: pin_cond was keyed into hop 1, which has no pin, so flipping a
lever re-rendered a byte-identical hop. A third of every A/B, on runs
already too slow to repeat.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015MGjcAV8bDy93qJfmLi9kw

CLAUDE.md

@@ -364,6 +364,7 @@ hop N-1 ends. Hop N opens by holding what it was handed.
 - Fewer than 3 wired reference stills triggers a warning log; unconnected `Load Image` nodes do not count as wired.
 - **Never judge texture drift with mean `|Laplacian|`, or with any whole-frame scalar.** Measured on two 44 s H3 chains whose faces visibly come apart, it reads **0.961 and 0.973** -- one of them says the clip improved. It is an area average (a face is ~6% of a portrait frame and loses to the background sixteen to one) and it pools every spatial frequency, so band-to-band movement cancels. On those clips global contrast FELL while mid-band energy ROSE. Use `tools/texture_probe.py`: three Gaussian-difference bands (fine <1px / **mid 1-2.5px, the one that moves** / coarse 2.5-6px), a subject box against a background control, and the within-hop slope. `--video` runs it on any file, including other people's rigs. See DEVLOG 26.
 - **The texture ratchet is injected AT the join, and nowhere else.** Measured off the hop cache on a 3x243f chain, head box, mid band: within each hop last/first is `0.996 / 1.003 / 1.018` -- flat -- and each join steps `x1.042`, twice, identically. It is a staircase, not a ramp. So the hand-off is the cause and not merely the carrier, which is the good news: a hand-off-side lever can remove this rather than damp it. `prev_imgs = imgs[-tail_n:]` and the pin latent are conditioning-only copies (`.clone()`, and `_condition_pin_latent` rebuilds rather than mutates), so they can be corrected without touching a single visible pixel.
+- **`pin_renorm=sigma` cannot fix the ratchet, and no tuning will rescue it.** The drifting statistic is the high-band *fraction* -- a ratio -- and a ratio is invariant under any uniform rescale, which is all a sigma match does. Measured end to end through the node: a 12.74% band drift stayed at **+12.74%** under `sigma` and went to **-0.04%** under `band`. Total sigma is not merely a weak proxy here; on the real chain it FELL 1.2% while the fraction rose, so it does not even point the right way. `sigma` is kept only because pre-0.5 workflows saved it as `on`.
 - **Texture drift is independent of exposure, but the metric is not.** A band-pass removes the local mean, so it ignores a brightness *offset* -- it is not scale-free, and a 5% brighter picture measures ~5% more band energy with texture unchanged. `texture_probe` prints both (`x` raw, `n` exposure-normalised); where they disagree the difference is the scene brightening. On the 3-hop chain whole-frame mid read `x1.084` raw but `n1.035` normalised. Do not expect `tone_compensate` to touch the ratchet, and do not tune on a 2-hop chain; the effect only separates at 3+.
 - Soundtrack is official H3, not a pack dialect: `(S1)` + `<d>…</d>` for lines, `overall_soundscape` for ambience/physical (or `N/A` for requested silence). Do not invent beat-keywords. “No speech” / “no dialogue” remains negation/gibberish.
 

docs/DEVLOG.md

@@ -1211,3 +1211,78 @@ The 3-hop chain's luma rose 4.7%, so whole-frame mid read `x1.084` when the
 texture part was `n1.035`. Both columns are printed now. The head box was
 unaffected either way -- the brightening was in the background -- which is
 exactly the kind of thing a single whole-frame number cannot tell you.
+
+## 27. The band lever, and why the old one could never have worked (2026-09-01)
+
+Built after §26's correction, on the finding that the ratchet is a step at the
+join: +4.2% mid-band, twice, identically, on a 3-hop chain. Two identical steps
+is already a model -- constant multiplicative step per join, geometric in hop
+count. It predicts hop 3 at 1.042^2 = 1.086 against 1.079 measured. So the
+shape did not need a 4-5 hop run to pin down, which matters: those runs are
+expensive enough that the user does not do them.
+
+`pin_renorm` is now `["off", "sigma", "band"]`. `"on"` maps to `"sigma"`, so
+pre-0.5 workflows keep their behaviour, and the combo keeps its widget slot --
+adding options is safe, adding widgets is not.
+
+### The old lever is a no-op, provably
+
+The statistic that drifts is the high-band **fraction**, hi_sigma / sigma. A
+fraction is invariant under uniform rescaling, and a uniform rescale is the
+entirety of what `sigma` mode does. Driven end to end through
+`_condition_pin_latent` with a 12.74% band drift planted in hop 2:
+
+    mode=off     ratio after 0.3526 (anchor 0.3128)  err +12.74%
+    mode=sigma   ratio after 0.3526 (anchor 0.3128)  err +12.74%   x0.9651 applied
+    mode=band    ratio after 0.3127 (anchor 0.3128)  err  -0.04%   hi x0.8339
+
+`sigma` applied a real scale factor and moved the drift by nothing at all. This
+is stronger than §26's "corrects the wrong way": there is no gain, no strength
+knob and no anchor choice that makes a scale-invariant statistic respond to a
+scale. The lever was mis-specified, not mis-tuned. It is kept only for the
+workflows that saved it.
+
+### The fixed point that nearly shipped
+
+`match_band` first computed `k = target * sigma / hi_sigma`. That is wrong in a
+way that hides: scaling the high band changes the sigma it is a fraction of, so
+the target moves while you apply it. It landed at 0.3331 against a 0.3168
+target -- 5% short, in the right direction, which is the worst possible
+signature because it looks like it works.
+
+Now it solves the orthogonal fixed point in closed form,
+`k = r*L / (H*sqrt(1-r^2))`, then refines two or three passes against the
+statistic as actually measured, because a difference of Gaussians is not an
+exact projection. Lands at 0.3167 against 0.3168.
+
+### The fixture was also wrong, and would have hidden it
+
+The first test used `torch.randn` for the latent. White noise has a high-band
+fraction of **0.966** -- pinned against its ceiling of 1.0, where lifting the
+high band moves the statistic by 0.6% and the clamp does all the "correcting".
+Every assertion about the lever would have been measuring the clamp. Real
+latents sit at 0.3643, so the fixture is now built to land near there and an
+assertion holds it in that regime.
+
+The safety property is asserted as "the entire change lies along the high band"
+(cosine with `hi` > 0.99), not as "the low band is unchanged" -- re-splitting
+the result does not hand back the same `lo`, because the split is not a
+projection. The first version asserted the false one and failed correctly.
+
+### One cache key narrowed
+
+`pin_cond` was in every hop's key including hop 1, which has no pin --
+`_pin_mech_for` returns `"none"` at index 0 and the conditioning branch is
+`elif i > 0`. So flipping a lever discarded a byte-identical cached hop 1 and
+re-rendered it. That is a third of the cost of every lever A/B, on the one hop
+that provably could not have changed. Now keyed only from hop 2.
+
+### Still unknown
+
+The latent's band fraction moved 1.6% across the chain while the picture's mid
+band moved 8%. The decode is nonlinear so they are not expected to be
+proportional, but a full match to hop 1's fraction may therefore under-correct
+the picture. That is one A/B to find out, and it is readable off a 3-hop run:
+`texture_probe` reports each join separately, so two joins is two data points.
+If `band` shrinks the +4.2% step but does not close it, the next move is a gain
+above 1.0, fitted -- not guessed.

h3_ref_chain.py

@@ -628,77 +628,115 @@ def _rebuild_latent_samples(x, parts):
     return _latents.rebuild(x, parts)
 
 
-def _condition_pin_latent(lat, anchor_std, renorm=False, noise=0.0, seed=0):
+def _condition_pin_latent(lat, anchor, mode="off", noise=0.0, seed=0):
     """Anti-ratchet preprocessing for the latent handed to Motion-Context.
 
     MiniMaxH3MotionContext.apply() takes `context_latent` as-is and exposes no
-    hook, so both levers have to be applied to the latent before it goes in.
+    hook, so every lever has to be applied to the latent before it goes in.
 
-    `renorm` rescales this pin so its standard deviation matches hop 2's. The
-    pin's own sigma climbs hop over hop, and because that inflated pin is what
-    conditions the next hop the growth compounds upstream of anything a master
-    pass can reach. A scalar rescale moves no structure, so it cannot blur
-    detail. `noise` mixes in a seeded perturbation, which attacks the same
-    ratchet from the other side; measured gains reverse above 0.10, hence the
-    widget cap.
+    Two rescale modes, and the difference between them is the whole point.
+
+    `sigma` rescales the pin so its standard deviation matches the anchor hop's.
+    This is the original lever and **it is measurably the wrong statistic.** On
+    a 3-hop chain the pin's total sigma FELL (1.0414 -> 1.0289) while the
+    picture's mid-band energy climbed 8% and its high-band fraction rose 1.6%.
+    Matching sigma there scales the whole latent UP by 1.2%, lifting a high
+    band that was already too hot. Kept because it is what shipped, and old
+    workflows say "on".
+
+    `band` splits each spatial component into low and high and rescales only the
+    high part, so the *ratio* between them returns to the anchor hop's. That
+    ratio is what the ratchet actually moves. Still a scalar per band, so it
+    moves no structure and cannot blur or invent detail -- the property that
+    made `sigma` safe to run blind, kept.
+
+    `noise` mixes in a seeded perturbation, attacking the same ratchet from the
+    other side; measured gains reverse above 0.10, hence the widget cap.
 
     **Per component, not per latent** (fixed 2026-08-27). Video and audio are
-    two tensors in one NestedTensor and their sigmas drift independently, so
+    two tensors in one NestedTensor and their statistics drift independently, so
     each carries its own anchor. Before this, `.std()` raised on the nested
-    object and both levers were dead -- the failure announced itself once per
-    hop as `pin conditioning skipped` and was easy to read as routine noise.
-    A single global scale would also have been wrong on its own terms, letting
-    the much larger video component dictate the audio's correction.
-
-    Returns `(latent, new_anchor_std)` where the anchor is a list, one sigma
-    per component -- hop 2 establishes what hops 3+ are matched against. Both
-    levers default off, in which case the latent is returned untouched.
+    object and every lever was dead -- announced once per hop as `pin
+    conditioning skipped`, which read as routine noise.
+
+    Returns `(latent, anchor)` where `anchor` is a list, one dict per component
+    -- the first pinned hop establishes what later hops are matched against.
+    Every lever defaults off, in which case the latent is returned untouched.
     """
     if not isinstance(lat, dict) or "samples" not in lat:
-        return lat, anchor_std
+        return lat, anchor
     x = lat["samples"]
     parts = _latent_parts(x)
     if parts is None:
         print(f"[{TAG}] pin conditioning skipped: unrecognised latent "
               f"({type(x).__name__})", flush=True)
-        return lat, anchor_std
+        return lat, anchor
+    mode = str(mode)
+    if mode == "on":                       # pre-2026-09-01 workflows
+        mode = "sigma"
     try:
-        cur = [float(t.float().std()) for t in parts]
+        cur = []
+        for t in parts:
+            sig = float(t.float().std())
+            cur.append({"sigma": sig, "ratio": _latents.band_ratio(t)})
     except Exception as e:  # noqa: BLE001
         print(f"[{TAG}] pin conditioning skipped ({e!r})", flush=True)
-        return lat, anchor_std
-    if not all(c == c and c for c in cur):  # zero or NaN in any stream
-        return lat, anchor_std
-    if anchor_std is None:
-        anchor_std = cur
-    if len(anchor_std) != len(cur):
+        return lat, anchor
+    if not all(c["sigma"] == c["sigma"] and c["sigma"] for c in cur):
+        return lat, anchor                 # zero or NaN in any stream
+    if anchor is None:
+        anchor = cur
+    if len(anchor) != len(cur):
         # Stream count changed mid-chain. Nothing sensible to match against.
         print(f"[{TAG}] pin conditioning skipped: latent has {len(cur)} "
-              f"component(s), anchor has {len(anchor_std)}", flush=True)
-        return lat, anchor_std
-    if not renorm and noise <= 0.0:
-        return lat, anchor_std
+              f"component(s), anchor has {len(anchor)}", flush=True)
+        return lat, anchor
+
+    # Always report the drift, even with every lever off. This is the number
+    # that says whether a lever is needed and whether one worked, and it costs
+    # nothing to read -- the alternative is inferring it from the master after
+    # a decode, which is how the wrong statistic went unnoticed for a release.
+    for i, (c, a) in enumerate(zip(cur, anchor)):
+        if c["ratio"] is not None and a["ratio"]:
+            print(f"[{TAG}] pin drift[{i}]: sigma {c['sigma']:.4f} "
+                  f"(x{c['sigma'] / a['sigma']:.4f} vs anchor)  "
+                  f"high-band fraction {c['ratio']:.4f} "
+                  f"(x{c['ratio'] / a['ratio']:.4f})", flush=True)
+
+    if mode not in ("sigma", "band") and noise <= 0.0:
+        return lat, anchor
+
     out_parts, notes = [], []
-    for idx, (t, c, a) in enumerate(zip(parts, cur, anchor_std)):
+    for idx, (t, c, a) in enumerate(zip(parts, cur, anchor)):
         o = t
-        if renorm:
-            scale = a / c
+        if mode == "sigma":
+            scale = a["sigma"] / c["sigma"]
             o = o * scale
-            notes.append(f"renorm[{idx}] x{scale:.4f} (sigma {c:.4f} -> {a:.4f})")
+            notes.append(f"sigma[{idx}] x{scale:.4f}")
+        elif mode == "band":
+            o, k = _latents.match_band(o, a["ratio"])
+            if k is None:
+                # An audio component has no bands; leaving it alone is correct,
+                # not a fallback -- `sigma` on it would be a different lever
+                # applied silently under this one's name.
+                notes.append(f"band[{idx}] skipped (no spatial extent)")
+            else:
+                notes.append(f"band[{idx}] hi x{k:.4f} "
+                             f"(fraction {c['ratio']:.4f} -> {a['ratio']:.4f})")
         if noise > 0.0:
             # Per component: `.shape` on the nested object reports only the
             # first component's shape, so one draw for the whole latent would
             # size its noise to the video and broadcast that onto the audio.
             g = torch.Generator(device="cpu").manual_seed((int(seed) + idx) & 0x7FFFFFFF)
             n = torch.randn(o.shape, generator=g, dtype=torch.float32)
-            o = o + n.to(dtype=o.dtype, device=o.device) * (float(noise) * a)
+            o = o + n.to(dtype=o.dtype, device=o.device) * (float(noise) * a["sigma"])
             notes.append(f"noise[{idx}] {float(noise):.3f}")
         out_parts.append(o)
     if notes:
         print(f"[{TAG}] pin conditioning: " + ", ".join(notes), flush=True)
     new = dict(lat)
     new["samples"] = _rebuild_latent_samples(x, out_parts)
-    return new, anchor_std
+    return new, anchor
 
 
 def _pin_mech_for(hop_index, overlap_n, prev_sampled):
@@ -1124,15 +1162,24 @@ class HandTieClips:
                         "follows the overlap widget."
                     ),
                 }),
-                "pin_renorm": (["off", "on"], {
+                "pin_renorm": (["off", "sigma", "band"], {
                     "default": "off",
                     "tooltip": (
-                        "Rescale each pinned latent so its spread matches hop 1's. "
-                        "The pin's own sigma climbs every hop and that inflated pin "
-                        "conditions the next one, so texture ratchets up along a "
-                        "long chain. A scalar rescale moves no structure, so it "
-                        "cannot blur detail. Off reproduces chain_00038 exactly; "
-                        "turn it on for chains of 3+ hops."
+                        "Rescale each pinned latent back toward the first pinned "
+                        "hop's, to fight the texture ratchet -- measured at +4.2% "
+                        "mid-band per join, flat inside each hop. Both modes are "
+                        "scalar rescales, so neither moves structure or can blur "
+                        "detail. "
+                        "band: match the HIGH-BAND FRACTION, the statistic the "
+                        "ratchet actually moves. "
+                        "sigma: match total spread -- the original lever, kept "
+                        "for old workflows, and measurably the wrong statistic: "
+                        "total sigma FALLS across a chain whose picture is "
+                        "baking, so it corrects the wrong way. Saved as `on` "
+                        "before 0.5. "
+                        "off reproduces chain_00038 exactly. The log prints "
+                        "`pin drift` every hop either way, so you can read the "
+                        "ratchet without changing anything."
                     ),
                 }),
                 "pin_noise": ("FLOAT", {
@@ -1513,13 +1560,16 @@ class HandTieClips:
         pbar = comfy.utils.ProgressBar(n)
 
         hop_store = None
-        pin_renorm_on = str(pin_renorm) == "on"
+        # "on" is what pre-0.5 workflows saved for what is now "sigma".
+        pin_renorm_mode = {"on": "sigma"}.get(str(pin_renorm), str(pin_renorm))
+        if pin_renorm_mode not in ("sigma", "band"):
+            pin_renorm_mode = "off"
         pin_noise_v = max(0.0, min(0.10, float(pin_noise)))
         audio_ctx = int(audio_pin_frames) if int(audio_pin_frames) > 0 else int(overlap_n)
-        pin_anchor_std = None   # hop 2's pin sets the sigma hops 3+ match
-        if pin_renorm_on or pin_noise_v > 0.0:
+        pin_anchor = None   # the first pinned hop sets what 3+ match
+        if pin_renorm_mode != "off" or pin_noise_v > 0.0:
             print(f"[{TAG}] pin conditioning enabled: "
-                  f"renorm={'on' if pin_renorm_on else 'off'} "
+                  f"renorm={pin_renorm_mode} "
                   f"noise={pin_noise_v:.3f}", flush=True)
         tone_mode = str(tone_compensate)
         tone_on = tone_mode != "off" and tone_mode in _tone.MODES
@@ -1753,7 +1803,15 @@ class HandTieClips:
                     # has no sampler latent and falls back to AddGuide, which
                     # is a different render of the same inputs.
                     "pin_mech": pin_mech_pred,
-                    "pin_cond": (pin_renorm_on, round(pin_noise_v, 4), audio_ctx),
+                    # Only from hop 2. Hop 1 has no pin -- `_pin_mech_for`
+                    # returns "none" for index 0 and the conditioning branch is
+                    # `elif i > 0` -- so its frames cannot depend on these
+                    # levers, and keying them in threw away a byte-identical
+                    # cached hop 1 every time one was flipped. That is a third
+                    # of the cost of every lever A/B, on the one hop nobody
+                    # needed to re-render.
+                    "pin_cond": ((pin_renorm_mode, round(pin_noise_v, 4), audio_ctx)
+                                 if i > 0 else None),
                 })
                 # A locked shot reuses its last render even though its inputs
                 # changed -- that is the point of locking. The content key would
@@ -1804,9 +1862,9 @@ class HandTieClips:
                 elif i > 0:
                     pin_latent = prev_sampled
                     if pin_latent is not None:
-                        pin_latent, pin_anchor_std = _condition_pin_latent(
-                            pin_latent, pin_anchor_std,
-                            renorm=pin_renorm_on, noise=pin_noise_v,
+                        pin_latent, pin_anchor = _condition_pin_latent(
+                            pin_latent, pin_anchor,
+                            mode=pin_renorm_mode, noise=pin_noise_v,
                             seed=(int(seed) + i))
                     cond, pin_mech_used = _pin_continue(
                         cond, latent, vae, audio_vae, overlap_n,

latents.py

@@ -46,3 +46,100 @@ def from_dict(lat):
     if not isinstance(lat, dict) or "samples" not in lat:
         return None
     return parts(lat["samples"])
+
+
+def _gauss1d(sigma, device, dtype):
+    r = max(1, int(round(3.0 * float(sigma))))
+    x = torch.arange(-r, r + 1, dtype=torch.float32, device=device)
+    k = torch.exp(-(x * x) / (2.0 * float(sigma) ** 2))
+    return (k / k.sum()).to(dtype)
+
+
+def band_split(t, sigma=2.0):
+    """Separable Gaussian low/high split over the last two dims. -> (lo, hi).
+
+    Returns None when the tensor has no spatial extent to speak of -- an audio
+    component is a different object and blurring across it means nothing.
+
+    Replicate padding, not reflect: a latent's spatial dims are small (a
+    736x1280 frame is 46x80 here) and reflect needs the pad to be smaller than
+    the dimension, which stops being true for a large sigma on a small latent.
+    """
+    if t.dim() < 2 or t.shape[-1] < 8 or t.shape[-2] < 8:
+        return None
+    import torch.nn.functional as F  # noqa: PLC0415
+    h, w = int(t.shape[-2]), int(t.shape[-1])
+    flat = t.reshape(-1, 1, h, w)
+    k = _gauss1d(sigma, t.device, t.dtype)
+    pad = k.numel() // 2
+    lo = F.conv2d(F.pad(flat, (pad, pad, 0, 0), mode="replicate"),
+                  k.view(1, 1, 1, -1))
+    lo = F.conv2d(F.pad(lo, (0, 0, pad, pad), mode="replicate"),
+                  k.view(1, 1, -1, 1))
+    lo = lo.reshape(t.shape)
+    return lo, t - lo
+
+
+def band_ratio(t, sigma=2.0):
+    """High-band sigma as a fraction of total sigma. -> float, or None.
+
+    This is the statistic the texture ratchet actually moves. Measured across a
+    3-hop chain it went 0.3643 -> 0.3673 -> 0.3702, monotone, while the total
+    sigma it is normalised by FELL 1.2% -- which is why matching total sigma
+    cannot see this and, worse, corrects the wrong way.
+    """
+    got = band_split(t, sigma)
+    if got is None:
+        return None
+    tot = float(t.float().std())
+    if not tot or tot != tot:
+        return None
+    return float(got[1].float().std()) / tot
+
+
+def match_band(t, target_ratio, sigma=2.0, clamp=(0.5, 2.0)):
+    """Rescale t's high band so its high-band fraction becomes `target_ratio`.
+
+    -> (tensor, k), or (t, None) when the tensor has no bands to match.
+
+    Only the high half is scaled, so the low-frequency structure that carries
+    the scene is bit-identical and the correction is one scalar. It cannot blur,
+    sharpen unevenly, or invent detail; the worst it can do is get the gain
+    wrong, which is why `clamp` exists.
+
+    Note the fraction is against the tensor's own sigma, so restoring the ratio
+    does move total sigma a little. That is deliberate: the ratio is the drifting
+    statistic and sigma is the one that lies.
+    """
+    got = band_split(t, sigma)
+    if got is None or not target_ratio:
+        return t, None
+    lo, hi = got
+    cur_hi = float(hi.float().std())
+    if not cur_hi or cur_hi != cur_hi:
+        return t, None
+
+    # The naive `k = target * sigma / hi_sigma` is wrong, and quietly so:
+    # scaling the high band changes the sigma it is a fraction OF, so the
+    # target moves as you apply it. Measured, it undershot by 5% on a
+    # latent-shaped tensor -- a correction that silently does most, but not
+    # all, of its job is the worst kind to ship.
+    #
+    # First guess solves the fixed point assuming lo and hi are orthogonal:
+    # k*H / sqrt(L^2 + k^2*H^2) = r, so k = r*L / (H*sqrt(1 - r^2)) ...
+    r = min(float(target_ratio), 0.999)
+    lo_sd = float(lo.float().std())
+    k = (r * lo_sd) / (cur_hi * max(1e-6, (1.0 - r * r) ** 0.5))
+    # ... then refine against the statistic as actually measured, because a
+    # difference of Gaussians is not an exact orthogonal projection. Two or
+    # three passes converge, and a latent is small enough that this is free.
+    for _ in range(4):
+        k = min(max(k, clamp[0]), clamp[1])
+        got_r = band_ratio(lo + hi * k, sigma)
+        if not got_r:
+            break
+        if abs(got_r - r) <= 1e-4 * max(r, 1e-6):
+            break
+        k *= r / got_r
+    k = min(max(k, clamp[0]), clamp[1])
+    return lo + hi * k, k

tools/check_texture.py

@@ -188,6 +188,71 @@ def main():
     ck("rebuild round-trips a plain tensor",
        torch.equal(lat.rebuild(t, [t]), t))
 
+    print()
+    print("latents.match_band -- the lever undoes a known tilt")
+    g = torch.Generator().manual_seed(3)
+    # Latent-SHAPED, not white noise. Plain randn has a high-band fraction of
+    # 0.966 -- pinned against its ceiling of 1.0, where lifting the high band
+    # barely moves the statistic and the clamp does the "correcting". Real
+    # latents measured 0.3643, so the fixture is built to land near there, and
+    # the first assertion holds it there.
+    w = torch.randn((2, 4, 46, 80), generator=g)
+    smooth = lat.band_split(w, 4.0)[0]
+    rough = torch.randn((2, 4, 46, 80), generator=g)
+    base = smooth / smooth.std() + rough / rough.std() * 0.30
+    r0 = lat.band_ratio(base)
+    ck("the fixture sits where real latents sit", 0.20 < r0 < 0.50,
+       "ratio %.4f (measured on a real chain: 0.3643)" % r0)
+
+    # Bake it: lift the high band the way a hop's pin drifts.
+    lo, hi = lat.band_split(base)
+    baked = lo + hi * 1.25
+    r1 = lat.band_ratio(baked)
+    ck("lifting the high band raises the fraction", r1 > r0 * 1.10,
+       "%.4f -> %.4f" % (r0, r1))
+    fixed, k = lat.match_band(baked, r0)
+    r2 = lat.band_ratio(fixed)
+    ck("match_band restores it to the anchor", abs(r2 / r0 - 1.0) < 0.005,
+       "%.4f vs %.4f (k=%.4f)" % (r2, r0, k))
+    ck("and scales the high band down to do it", k < 1.0, "k=%.4f" % k)
+
+    # The safety property -- but NOT "the low band is unchanged". Re-splitting
+    # the result does not hand back the same lo, because a difference of
+    # Gaussians is not an exact projection. What is true, and what makes this
+    # safe to run blind, is that the entire change lies along the high band:
+    # no structure is added, one scalar is moved.
+    d = (fixed - baked).reshape(-1)
+    hf = hi.reshape(-1)
+    cos = float((d * hf).sum() / (d.norm() * hf.norm()))
+    ck("the entire change lies along the high band", abs(cos) > 0.99,
+       "cos %.4f" % cos)
+    ck("an audio-shaped component is skipped, not sigma-matched",
+       lat.match_band(torch.randn(2, 1024), 0.4)[1] is None)
+    ck("a zero target is a no-op", lat.match_band(base, 0.0)[1] is None)
+
+    # The measured case reproduced: sigma FALLS while the fraction RISES, so
+    # the two levers disagree about which way to correct. This is the whole
+    # argument for `band` over `sigma` -- on the real chain, matching sigma
+    # would have scaled a pin UP whose high band was already too hot.
+    shrunk = baked * (0.99 * float(base.std()) / float(baked.std()))
+    ck("sigma and band disagree in DIRECTION on this signal",
+       float(shrunk.std()) < float(base.std())
+       and lat.band_ratio(shrunk) > r0 * 1.10,
+       "sigma x%.4f but fraction x%.4f"
+       % (float(shrunk.std()) / float(base.std()),
+          lat.band_ratio(shrunk) / r0))
+
+    # And the reason `sigma` cannot be rescued by tuning: the fraction is a
+    # RATIO, so it is invariant under any uniform rescale. Whatever scale a
+    # sigma match picks, it leaves this statistic exactly where it found it.
+    # That makes `sigma` a no-op on the texture ratchet by construction, not
+    # merely a weak correction -- measured end to end through the node, drift
+    # stayed at +12.74% under `sigma` and went to -0.04% under `band`.
+    for factor in (0.5, 0.9651, 2.0):
+        ck("a uniform x%.4g rescale does not move the fraction" % factor,
+           abs(lat.band_ratio(baked * factor) / r1 - 1.0) < 1e-4,
+           "%.6f vs %.6f" % (lat.band_ratio(baked * factor), r1))
+
     print("\nhopcache.chains -- two renders stay two renders")
     mk = lambda hops: [(h, "k%d" % i, {"written": float(i)})
                        for i, h in enumerate(hops)]