D-20261028-04｜效能預算三層口徑¶
2026-10-29 關聯追補：第 5 節的「catch-up 最壞追趕耗時」已由 D-20261029-03 從只報告的診斷移入 provisional 回歸閘
catch-up-worst，並加單 tick 追趕耗時斷言；載入、日誌驗簽與重播分項仍只輸出診斷，其餘口徑不變。
背景與驅動力¶
issue 001090：效能目標散在三處、互相矛盾，且與現況脫節。
- network-sync.md 第 8 節：8 玩家 frame ≤ 16 ms、rollback 5 幀重播 ≤ 8 ms（約 1.6 ms／步）、snapshot 序列化 ≤ 4 ms、snapshot ≤ 64 KB。但當時
ROLLBACK_FRAME_BUFFER_DEFAULT是 8，不是 5。 - testing.md 第 8 節：
physics-step-60fps-8playersp99 4.0 ms、rollback-recovery8.0 ms，與上面的重播口徑互相矛盾。 - physics-engine.md 第 9 節再抄一次同一組數字。
- 都沒有區分 world step、
engine.step與saveState，也沒有定義量測機器與情境。
cost-r22 量測（八車三場）：每幀實付 P50 47–92 ms、saveState 約 25 ms（D-20261028-01 後 3.4–5.4 ms）、快照 2.65–4.07 MB。
寫死毫秒的數字一旦 Hz、R 或 D 改變就漂移（「5 幀 ≤ 8 ms」與 R＝8 矛盾就是這樣產生的）。
2026-10-27 使用者裁決：三層口徑（L0 每幀實付 P95 ≤ T÷k、L1 P50 ≤ T/2、L2 最深回滾頓挫 ≤ 3T），k＝2、參考機為一般中階筆電；預算集中在 network-sync 第 8 節、數字以常數表達；廢除 step／save 各 4 ms；快照上限改相對值。
2026-10-28 使用者核准：L2 不除以 k；效能常數放 network/ namespace；未達 L0 的裝置照常參賽並顯示效能警告；效能警告以本機每幀實付滾動 600 幀 P95 超過一個 tick 判定。
考慮過的選項¶
- 維持三處固定毫秒：持續矛盾、改常數即漂移（否決）。
- 只保留回歸閘（D-20260809-07）、不設產品目標：無法判斷即時可玩性（否決）。
- 沿用 001074 原建議的「穩態 step、save 各 P99 ≤ T/4」：P99 被 bounded-step 尖峰主宰，任何組合都差 4–16 倍，且 Worker 與 L2 已處理尖峰的可見影響（否決；P99 改為只報告）。
- 以 T、k、R 推導的三層口徑，單一權威集中在 network-sync 第 8 節（採納）。
決定¶
1. 記號¶
- T＝1000／
FIXED_FRAMERATE_HZms；R＝ROLLBACK_FRAME_BUFFER_DEFAULT；D＝INPUT_DELAY_FRAMES。 - k＝
PERF_LOW_END_FACTOR＝2：參考機效能 ÷ 最低支援裝置效能。 - 參考機：一般中階筆電。實際型號、CPU、OS、瀏覽器版本、電源模式由 testing 第 8 節登錄（待決事項 1）。
- 量測位置：產品目標在參考機的 Chromium、模擬 Worker 內量測。Node harness 的數字是代理指標，可用於研究與回歸，但不能單獨宣稱達標。
2. 每幀實付的定義¶
每幀實付＝engine.step（含 bounded-step 試算與內部快照）＋該幀實際發生的 saveState＋stateHash。依 D-20261028-03 的前緣快照規則，穩態只有對齊快照（每 CATCH_UP_OFFER_ALIGNMENT_FRAMES 幀一次）與 checksum 幀的 hash，量測取逐幀實際值，不另外攤提。只計前進幀；回滾重播與 catch-up 追趕的耗時屬 L2 與診斷，不併入每幀實付。
3. 三層口徑¶
| 層 | 目標 | 量測對象 | 意義 |
|---|---|---|---|
| L0 可玩底線 | P95(每幀實付) ≤ T ÷ k | 參考機，不注入延遲（不回滾）；觀戰 replay 同樣適用 | 最低支援裝置 95% 的幀能在一個 tick 內算完 |
| L1 穩態餘裕 | P50(每幀實付) ≤ T ÷ PERF_STEADY_HEADROOM_DIVISOR（＝2） |
同 L0 | 落後後能比即時更快追上：一次 3T 頓挫約 6T 內追回 |
| L2 回滾頓挫 | P95(最深回滾事件耗時) ≤ PERF_ROLLBACK_STUTTER_FRAMES × T（＝3T），不除以 k |
參考機；回滾事件＝loadOwnState＋重播 R 幀＋重播期間的必要 save |
有界頓挫：在 Worker 內只造成模擬落後，不凍結畫面 |
- L2 另報：在宣告的延遲模型下每分鐘回滾事件數與深度分佈。只報告，不設目標。
- P99 與 max 只報告，不設目標。
- 「回滾深度上限 3 幀」（
ROLLBACK_FRAME_BUFFER_MAX）是協定常數，屬 D-20261028-03；L2 的「3T」是時間預算。兩者數字相同但概念不同，各自獨立常數。
4. 未達 L0 的裝置與效能警告¶
未達 L0 的裝置照常參賽，不降為觀戰。正式比賽回合中，本機以每幀實付的滾動 600 幀 P95 超過一個 tick（T）時，在比賽頁顯示效能警告；警告不影響參賽、輸入或共識。每回合重新取樣，因此回合開頭約 10 秒內不判定；回滾重播成本不計入；local-test 與觀戰 replay 不產生警告。
5. 只報告、不設目標的診斷指標¶
每個各自一個基準 ID 或診斷輸出：world step、engine.step、saveState、loadOwnState、loadState（完整驗證，catch-up 與觀戰用）、stateHash、snapshot bytes、bounded-step 拒絕幀比例與試算數分佈、Rapier profiler 分項、catch-up 最壞追趕耗時。
6. 快照大小¶
- 硬上限仍是
SYNC_SNAPSHOT_MAX_BYTES（4 MiB）；超過是功能失敗（catch-up 與觀戰 checkpoint 無法送出），不是效能退化，另由 issue 001091 處理。 - 目標改為相對值：P100(snapshot bytes) ≤
SYNC_SNAPSHOT_MAX_BYTES÷PERF_SNAPSHOT_BYTES_TARGET_DIVISOR（＝4，即 1 MiB）。 - 刪除「≤ 64 KB」。
7. 頻寬¶
以公式表達、不寫死：送出＝HZ × 每則 input bytes；接收＝(PLAYERS_PER_RACE_MAX − 1) × HZ × 每則 input bytes ＋ checksum 攤提。input delay 不改頻寬。
8. 量測情境¶
- 公版三場地（urban、snowy、jungle）× 車組（heavy8、mixed8）× 起跑佈局。起跑佈局至少含正式起跑格（八車成團，列為壓力情境）與分散佈局；cost-r22 使用的四種佈局為現行研究基準。
- 每情境暖機 60 幀後量 ≥ 900 幀，兩次獨立行程，逐情境判定（不以幾何平均判達標），報表另列幾何平均。
- 量測時不得有並行重負載；CPU 負載與行程數納入報表。
9. 單一權威與回歸閘¶
- 公式、常數名與推導只寫在 network-sync 第 8 節。
- testing 第 8 節只列基準 ID、量測口徑與「引用 network-sync 第 8 節」，不再寫毫秒目標。
- physics-engine 第 9 節只留連結。
- 共享 runner 的回歸閘依 D-20260809-07 維持（相對 reference 惡化 10% 警告、25% 失敗）。
meetsProductTarget改為按 L0／L1／L2 分列，維持診斷、不阻擋 release，直到參考機成為可重現 runner。 perf-baseline.json：刪除physics-step-60fps-8players、rollback-recovery，改為race-frame-cost-8players（L0／L1）與rollback-worst-event（L2），目標由常數推導、json 不寫毫秒目標。兩項新基準的 reference 是本機代理量測的暫置值，標為 provisional：在參考機重建前惡化只警告、不失敗。snapshot-checksum-compute改為診斷；key-manager-unlock、ugc-sanitize-25k-tris不變。- D-20261021-01 的場地分段成本閘（
track-pieces-performance）是回歸閘、不是即時預算，維持不變。
10. 常數¶
新增 network/perf namespace（非協定、不進 wire、快照或 hash，改值不升 protocol）：
| 常數 | 值 | 用途 |
|---|---|---|
PERF_LOW_END_FACTOR |
2 | k |
PERF_STEADY_HEADROOM_DIVISOR |
2 | L1 |
PERF_ROLLBACK_STUTTER_FRAMES |
3 | L2 |
PERF_SNAPSHOT_BYTES_TARGET_DIVISOR |
4 | 快照目標相對值 |
後果與影響¶
- 三處 canon 不再矛盾，改 Hz、R、D 時預算自動跟著變。
- 現況距離目標仍遠。以 001074 取捨模型估計（D6 R2、前緣快照、Worker、降本全疊加）：L0 在 k＝2 仍差 2.0–5.9 倍，L2 約 3.2T（邊緣），且 jungle／urban 的 P95 尾巴幾乎全部來自 bounded-step 拒絕細分。達標依賴 bounded-step 放寬研究與靜態場地參照研究；若兩者完成後 L0 仍差 1.5 倍以上，才另案評估 30 Hz 對照量測。
- 參考機重建 reference 前，兩項 provisional 基準的回歸只能從警告輸出判斷。
- amends D-20260809-07：產品目標由固定毫秒改為由常數推導的三層口徑，並登錄參考機；回歸閘規則不變，只新增 provisional 基準的警告語意。
- 現況規格：network-sync 第 8 節、testing 第 8 節、程式參數/network.md 第 8 節。
待決事項¶
- 參考機的具體型號與環境（「一般中階筆電」需落到可重現的 CPU／OS／瀏覽器／電源模式）：保留。
- 未達 L0（k＝2）的裝置處置：已定照常參賽並顯示效能警告（第 4 項）。
- 效能常數放置位置：已定
network/perf。 - L2 是否除以 k：已定不除。
- 延遲模型與抖動分佈的具體參數（L2 頻率報告用）：保留。
- 與 bounded-step 研究、靜態場地參照研究的相依：保留；兩者完成後重量一次，再判斷是否需要 30 Hz 對照。