跳轉到

D-20260808-02｜首次公開 builtin 資產 v1 基線

背景與驅動力

Open4WD 尚未首次公開，沒有已發布的 builtin 相容世代或必須延續的玩家快取；但 provisional AI 資產在內部重製、校準與修軸時，曾把 builtin_assets_version 由 1 逐次升到 8。這些中間產物仍會由 正式 Editor 手動重製，若把每次開發中替換都視為公開相容世代，不但沒有玩家受益，也會讓首次 公開基線從任意內部次數開始。當下另有 source／manifest 為 8、參數表為 6、生成的 version.json 為 1 的漂移。

現有版本規範已定義「公開後物理資產變動要 bump」，但沒有裁定首次公開前的 provisional 次數是否 形成公開世代；既有 ADR 也沒有涵蓋這個 release boundary，因此需補此決策。

考慮過的選項

  • 延續內部累計 8 作為首次公開版：不需重設 metadata，但把未發布的試作次數誤當相容承諾，否決。
  • 每次首次公開前重製都繼續 bump：可機械追蹤，卻會在沒有 public consumer 時製造無意義世代，否決。
  • 現在統一為 v1，首次公開後才開始單調升版（採納）。

決定

  • source constant、public／authoring manifest、pinning vendor、生成的 version.json 與現行規格立即 統一為 builtin_assets_version = 1；不得為此修改任何 GLB bytes、SHA-256、CID 或 extras hash。
  • 內部曾使用 2–8 是真實開發歷史，保留既有歷史記錄，不回寫或假裝未發生；它們不是 public compatibility era。
  • 首次公開前由正式 Editor 手動完成最終公版 GLB 時仍維持 v1。本階段的本地 CacheStorage 失效是 開發操作，不構成版本 bump。
  • 首次公開時凍結 v1 的 GLB bytes 與 provenance。公開後第一個會影響玩法、物理或 peer 一致性的 builtin 變更升為 v2，後續只允許單調增加。
  • Service Worker 主快取名稱同時包含 client 與 builtin 版本： open4wd-${client_version}-assets-${builtin_assets_version}。activate 只清除 open4wd- namespace 下的非 active cache，不得刪同 origin 的 foreign cache，也不碰 IndexedDB、localStorage、身分或帳號。

後果與影響

首次公開的版本語意從可驗證的 v1 開始，內部重製紀錄仍可稽核。builtin v2 之後可精確觸發新的 PWA cache namespace；開發期同為 v1 的再次手動重製，測試者需使用 /reset/ 或精確清除該 origin 的 Open4WD cache，不能靠虛增相容版本取代。若同 origin 還有其他應用，SW activation 會保留其 cache；完整重設頁仍是使用者明示的全站復原工具，與自動升版清理不同。