mandelbrot/IMPLEMENTATION_REPORT.md

# Mandelbrot Deep Zoom v23 実装報告

## 結論

`IMPROVEMENT_PROPOSAL.md`のv22向け設計判断をrenderer v23へ反映し、ローカル数値検証、WASM再現build、Hosted／Standalone成果物の生成まで実施した。提案は履歴文書であり、修正版のcoverage／Export／受入契約を現行基準とする。実ブラウザでのみ測定できる性能・表示・操作・download検証は、今回の環境にin-app browser bindingがないため未実行である。したがって、実装と確認済みの非ブラウザgate、未確認のbrowser acceptanceを分けて扱う。

## 実装済み

- 常時RAFを廃止し、invalidate時だけ動くevent-driven schedulerへ変更した。
- wheel／pinch／pan中は再投影だけを行い、settle後に計算を1回開始する。
- Preview時間予算を110msへ下げ、cold deep Previewは幅48px以下から開始する。以後は実測MPPでPreview寸法を決める。
- 標準deepのCoveredは実測MPPから約1.4秒のpixel budgetを算出する。未計測・再投影のみの場合は保守的MPPを使い、DPR下限は固定比率ではなく長辺64pxとするため4Kでも予算が効く。精細・精度優先ではこの時間適応を行わない。
- 処理モードの自動到達点を固定し、省電力はPreview、標準はCovered、精細はRefined、精度優先はValidatedで停止する。標準では境界AAと未確定追加反復を既定で実行しない。
- 精細の未確定追加反復は全未確定pixelではなくescape境界候補に限定し、1 viewあたりdeep 384点／shallow 4,096点を上限にする。
- `Reprojected → Preview → Covered → Refined → Validated／検証未完了`を分離した。
- Coveredはeffective DPRの表示Canvas全域をpixel中心`(x + 0.5, y + 0.5)`で計算する。
- escape field、分類、confidenceと彩色を分離し、palette変更時の反復再計算を廃止した。
- fieldへ各sampleの実escape iterationを保持し、再着色・未確定継続・Export監査で近似値ではなく同じ数値結果を使う。
- adaptive 2×／4× AA、linear-light resolve、byte-budget detail cacheを実装した。
- 深部Worker、deep/BLA/color WASM、reference資産を遅延生成し、Worker数を実測とmemory budgetで増減する。
- deep/BLA/colorはmainで各1回だけcompileし、compile済み`WebAssembly.Module`をWorkerへstructured cloneする。Worker sourceから埋込payload、palette LUT、RGBA生成の重複を除き、Workerは数値fieldだけを返す。
- 通常jobから学習したstrip時間とWorker数をkernel version・端末帯域keyで永続化し、30日TTL、schema version、storage拒否fallbackを付けて次回起動で再利用する。
- fixed-point direct、perturbation、rebase、BLA、局所guarded directを共通tile schedulerへ接続した。
- deep切替を固定zoom閾値ではなくpixel stepとULPの比、hysteresisで決める。
- deep切替とguard bitsへ直近orbitのglitch／未確定／補修率を加え、精度昇格時は低精度で作った基準軌道を破棄して再構築する。
- 高精度directを約6msでyieldする非同期処理へ変更し、取消可能にした。
- f64解析・収縮判定は`INTERIOR_LIKELY`のまま保持し、ValidatedではP／P+64双方の固定小数点整数不等式で主カージオイド／周期2球を証明できたsampleだけを`INTERIOR_PROVEN`へ昇格する。
- 精度優先のdeep描画では、基準軌道もP／P+64で独立再計算して疎なcheckpointとescape位置を照合し、不一致時はglobal reference全体を32 bit昇格して作り直す。
- 1×／2×／4×／custom、1×／2×2 AA、Balanced／Validated、進捗、取消に対応する独立tile exportを実装した。
- Balanced Exportは未確定数をmetadataへ記録して完了可能とし、Validated Exportは未確定sampleが残る場合にfinal PNGを出さず明示失敗する。
- Export sidecarへViewSpec、precision／iteration policy、未確定sample数、backend、全kernel SHA-256、色空間、encoder、paletteを記録する。
- version付きURL、戻る／進む、座標・spanの正確値入力／copy、Undo／Redoを実装した。
- 初回UI、一般statusと診断status、mobile compact status、keyboard操作、live region、visible focus、44px target、reduced motion／transparencyを実装した。
- Hosted版はcontent-hashed外部WASMとstreaming compile、Standalone版は3ファイル直開きを維持した。
- cacheは件数ではなくmobile 96 MiB／desktop 192 MiBのlogical byte ledgerで管理する。

## 再現buildと配布

- `src/shallow_kernel.c`、`src/deep_kernel.c`、`src/bla_kernel_v18.c`、`src/color_kernel.c`、`src/abi.json`を配置した。
- `toolchain.lock.json`でclang 17.0.6、target、SIMD／scalar flagsを固定した。
- clang 17.0.6とNode.js v22.18.0で8 WASMを再buildした。tool配布archiveのURL／SHA-256はrepositoryに保持されていないため、再監査可能な証拠範囲はversion／flags、source hash、生成manifest、golden結果までとする。
- shallow、deep、BLA、colorのgoldenとSIMD／scalar同値gateに合格後、payloadと`kernels.js`を昇格した。
- `scripts/build-kernels.ps1`は同一payloadだけを自動deduplicateし、異なるCOLOR variantsも正しく保持する。
- `scripts/build-hosted.ps1`は現manifest以外の古いcontent-hashed WASMを削除する。

生成先:

- Hosted: `dist/hosted/`と`dist/wasm/`
- Standalone: `dist/standalone/`
- 再現build: `build/wasm-v23/`

現在の非圧縮基準値は、Hosted first view 144,044 bytes、Standalone 172,591 bytesである。詳細なfile hashは`audit/v23-source-baseline.json`に記録した。v22成果物が残っていないため、v22の転送bytes／compile timeに対するnon-regressionは判定不能であり、このv23値を今後の比較起点とする。

## 合格済みgate

- source contract: pass
- kernel source／ABI contract: pass
- fixed-point precision 256／320 bit: pass
- 基準軌道P／P+64 checkpoint一致と故意の不一致検出: pass
- analytic interior integer proof 256／320 bit: pass
- pixel mapping 851 samples、shallow／deep／BLA、2×／4× tile seam: pass
- 配布shallow WASM pixel contract 1,440 samples、mismatch 0: pass
- generated-WASM shallow／color／deep／BLA golden: pass
- SIMD／scalar結果比較: pass
- 本体、shallow Worker、deep WorkerのJavaScript構文: pass
- mock DOM初期化とv23 diagnostics: pass
- compile済みdeep／BLA／color Moduleのstructured clone・instantiate: pass
- Node固定sceneの計測記録と処理量予算式の構造契約: pass（`audit/v23-node-performance.json`）。browser時間目標の達成を意味しない
- Hosted／Standalone buildと全payload SHA-256: pass

toolchainを利用できる環境では次で省略なしに再実行できる。

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/test-all.ps1 -RequireToolchain
```

## Browser acceptance gate

`tests/browser-benchmark.html`は1 runを1 profile・1 buildへ限定し、`?profile=desktop&target=hosted`のように実行する。iframe寸法によるDPR模擬を廃止し、非zero wheelのtransform-to-paint、30回以上のPreview、実際のFine→Refined、raw pixel golden、long task、Export metadata／完了前download／再現性、keyboard操作を自動判定する。HostedとStandaloneを別に開く。visual golden未登録、observed browser/GPU memory、visible focus、page zoom/pinch、screen-reader順序は外部gateとして残り、自動項目が通ってもfull acceptanceを返さない。今回の環境ではbrowser bindingがなかったため、`audit/v23-browser-baseline.json`は`not-run`のままである。

残る実機確認:

- mobile／desktop／4Kの表示画像とnative coverage
- 操作反映p95、Preview／Covered／Refined所要時間
- idle時の予約RAF／timer／background job／Canvas・DOM write 0
- browser／GPUを含むobserved peak memory
- Export寸法、完了前downloadなし、取消、PNG／JSON内容
- keyboard-only、focus、44px target、live status、page zoomとcanvas pinchの操作確認

このgateが合格するまで、v23の実装完了と数値gate合格は主張できるが、固定実機に対する性能目標の達成は主張しない。

browser非依存の現行成果物監査は`audit/v23-browserless-baseline.json`に保存した。公式SHA-256を照合したNode.js v22.18.0 portable binaryで7 executable testsが合格し、source／document contract、851 pixel mapping、1,440 pixel contract、Module cloneを再確認した。deep runtimeは出典付きの混在境界sceneで特性を測るが、値は`measured-not-acceptance`である。v22比較は`not-verifiable`、source-WASM再buildは保存済みprior evidenceの再利用として明示している。