w

docs/black-regression-rollback/IMPLEMENTATION.md

@@ -0,0 +1,41 @@
+# Black regression rollback
+
+## Intent
+
+A previous deep-zoom root-cause attempt introduced a broad f32 perturbation error propagation guard and progressive publication of partially resolved FAST fields. User testing showed this regressed rendering severely: most of the viewport could become black.
+
+This pass is deliberately a rollback, not another numerical heuristic. It restores the pre-regression FAST perturbation and publication behavior while keeping the later removal of adaptive-primary hysteresis.
+
+## Removed from the failed attempt
+
+1. FAST primary propagated `errScaled` acceptance/rejection logic.
+2. Low-part delta rewrite that was bundled with that unvalidated FAST change.
+3. Per-strip `publishNumericProgress()` during FAST primary.
+4. Per-batch `publishNumericProgress()` during sparse correction.
+5. Same-reference DS correction pre-pass added solely to service the broad FAST guard.
+6. Publication of a FAST primary before numerical failure repair is complete.
+
+## Preserved
+
+- No adaptive-primary hysteresis.
+- Series approximation remains disabled.
+- Sparse active state, dynamic references, CPU fallback and the prior supported removal pass remain.
+- FAST frames are withheld until numerical failures are repaired, so UNKNOWN alpha=0 pixels are not intentionally exposed as a fresh-frame partial image.
+
+## Validation
+
+- `node tests/regression.mjs`: PASS.
+- 19 WGSL kernels pinned by SHA-256.
+- JavaScript syntax is checked by the regression suite.
+- Static invariants:
+  - no `ADAPTIVE_PRIMARY_HYSTERESIS`
+  - no `stabilizeAdaptiveInitialChoice`
+  - no `lastPrimaryPolicy`
+  - no `nearbyAdaptiveViewSafe`
+  - no failed-attempt progressive FAST publication
+  - no `same-reference-ds-guided-precision`
+  - `deferPrimaryColor=deferColor||fastExtended`
+
+## Scope / remaining issue
+
+This rollback fixes the newly introduced near-all-black regression. It does **not** claim that the earlier deep-view reference-dependence / coordinate-shift instability is solved. That issue must be addressed from numerical validity (perturbation/rebasing/reference-domain correctness), not from view-history hysteresis.