Skip to content

docs(skill): record the HiCache outcome and the reset-path gotcha - #1362

Merged
DefTruth merged 1 commit into
mainfrom
docs/skill-hicache-outcome
Nov 18, 2026
Merged

DefTruth merged 1 commit into
mainfrom
docs/skill-hicache-outcome

Conversation

@DefTruth

Copy link
Copy Markdown
Member

Closes #1361

Docs-only follow-up to #1359 (HiCache). The cache-algorithm skill still judged HiCache as "worth integrating, do it as a ~40-line basis switch on TaylorSeer", while the shipped implementation landed differently and produced same-harness numbers. A skill that keeps a stale verdict is worse than no verdict, so this records the outcome.

Changes (3 files, documentation only)

File Change
SKILL.md HiCache verdict row: implemented, with the same-harness numbers and the "σ is still per-model" caveat; landing-point note gains an exception — when the user wants a separate file/algorithm name, go through option 1 but keep the basis a base-class hook (_basis_term) instead of copying the accumulation loop
references/landscape.md §2.1 landing note (equivalent recurrence, first-order gain is 2σ², and σ=1 is the undamped physicist-Hermite basis rather than a Taylor degeneracy); new §4.5 with the measured table
references/extension-points.md New hard rule: a calibrator's to_kwargs() must be dict(self.calibrator_kwargs or {}) — refresh_context() is the only reset=True caller and empty() nulls the field, which crashed TaylorSeer/DMD/SVD until #1359; points at tests/api/test_calibrator_reset.py. Also records the RandPipeline test trap

The measured table the skill now carries (§4.5)

FLUX.1-dev, 1024², 28 steps, seed 0, rdt 0.12, 12/28 steps cached with identical hit positions across rows, 1× RTX PRO 5000, torch 2.15.0:

Config PSNR SSIM Latency
base (no cache) — — 16.91s
DBCache reuse 31.72 0.9706 9.88s
+ TaylorSeer o2 30.91 0.9733 9.88s
+ HiCache o2 σ=0.5 33.33 0.9781 9.88s
+ HiCache o1 σ=0.5 33.36 0.9779 9.91s
+ HiCache o2 σ=1/√2 32.44 0.9770 9.88s
+ HiCache o2 σ=1.0 24.99 0.9280 9.89s
+ TaylorSeer o2 (mask-pinned) 27.77 0.9623 11.67s
+ HiCache o2 σ=0.5 (mask-pinned) 29.36 0.9738 11.68s

Three reusable readings recorded with it: (1) at ~1.7× HiCache is the best of the three, which narrows the earlier "the Bn_residual layer is saturated" conclusion to a per-operating-point statement; (2) σ=1 collapsing to 24.99 dB reproduces the paper's σ ablation and is the cheapest falsifier for "the basis is wired"; (3) a mask-pinned pair keeps the ordering, so the gap is the basis, not the hit sequence.

Two traps now written down

  • to_kwargs() and the reset path. cache_dit.refresh_context(transformer, **shorthand) is the only reset=True entry, it rebuilds through CalibratorConfig.empty() (every non-constant field becomes None), and the rebuilt context calls Calibrator(config) -> to_kwargs(). self.calibrator_kwargs.copy() crashes there; feat(cache): add HiCache damped-Hermite calibrator #1359 fixed the four sites and added tests/api/test_calibrator_reset.py.
  • RandPipeline cannot prove wiring by output diff. It feeds the same hidden_states to every step, so the feature trajectory is constant and any predictor's forecast equals the anchor. Tests must monkeypatch a counter on approximate() and assert the concrete state type / wired σ instead.

Scope

Pure documentation: no src/, csrc/, tests/ or CI change; no runtime, performance or accuracy impact. pre-commit run --files <3 files> passes (mixed-line-ending, end-of-file).

Judge the case as implemented rather than "worth integrating": HiCache ships as
calibrators/hicache.py (#1359), the landing point moved from "a basis switch on
Taylor" to the _basis_term hook plus a separate calibrator, and the same-harness
numbers now exist (FLUX 1.7x: 33.33 dB vs reuse 31.72 and TaylorSeer-o2 30.91,
sigma=1 collapses to 24.99 which reproduces the paper's sigma ablation).

Also record two things the next integration should not rediscover:

- a new calibrator's to_kwargs() must tolerate a null calibrator_kwargs, because
  refresh_context() rebuilds through empty(); TaylorSeer/DMD/SVD crashed there
  until #1359;
- RandPipeline feeds the same hidden_states to every step, so a predictor's
  forecast equals the anchor and "the output differs" cannot prove the wiring.

landscape.md gains the measured table (4.5): hit positions are identical across
rows, and a mask-pinned pair keeps the ordering, so the gap is the basis and not
the schedule.
@DefTruth
DefTruth merged commit a08768c into main Nov 18, 2026
2 checks passed
@DefTruth
DefTruth deleted the docs/skill-hicache-outcome branch November 18, 2026 12:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tooling: record the HiCache outcome in the cache-algorithm skill

1 participant