refactor(starpuff): W3 前置債務車——enemyUpdates 依品種家族分檔（1188→201 行）

[s123104]

審查未收斂前請勿合併（PM 派雙席審查後裁決）

摘要

W3 前置債務車：enemyUpdates.ts 1188 行逼近 max-lines 1200 硬閘（餘裕僅 12 行），W3 落地 L26 Reflector（鏡界館長）／L28 Gravion（引力侯爵）新小怪 update 邏輯必撞閘。本 PR 行為零改變地把 per-kind update 本體依品種家族機械式分檔，主檔 1188 → 201 行（要求 ≤850，對 1200 閘餘裕 999 行）。

沿用 #807（GameScene 2121→1196）與 #906（GameScene 1180→875）兩次成功先例的方法：機械搬移＋新模組單元測試＋既有回歸套件不變三重證據鏈，並依 AGENTS.md v5.7 採兩段式 commit（①新模組＋測試、舊路徑仍在 → ②切 wiring），git 史可證。

拆分前後行數對照

檔案	拆分前	拆分後	說明
enemyUpdates.ts	1188	201	ctx 契約＋單一分派點＋§16 基礎品種內聯
groundEnemies.ts	—	497	新檔（機械搬移）
flyerEnemies.ts	—	378	新檔（機械搬移）
fieldEnemies.ts	—	127	新檔（機械搬移；W3 鏡界/引力落點，餘裕 1073）
enemyWindupRing.ts	—	40	新檔（機械搬移）
enemies.ts	1044	1046	僅 import 重接（4 常數改自 groundEnemies 取得）

模組清單與職責

• enemyUpdates.ts：EnemyUpdateContext 契約（對外 import 路徑不變）＋updateEnemyKind 單一分派點（never 窮舉不變）＋§16 基礎品種內聯（jelly/floaty/spiky/puffy）。
• groundEnemies.ts：地面走動／定點據點系——shelly、drilly、spora、boomy、bubbla、splatta、chompy。
• flyerEnemies.ts：飛行漂浮系——glowy、gusty、twinkla、cometa、zappy（自分派器內聯 case 機械抽出）。
• fieldEnemies.ts：場域機制系——magno（磁場）、mirri（鏡面）；W3 鏡界（L26）／引力（L28）家族小怪 update 的預定落點。
• enemyWindupRing.ts：windup 預警圈共用件（WindupRingSpec／updateWindupRing／clearWindupRing）；ring spec 常數隨消費者模組持有。

切點與派工建議的差異說明

派工建議四組（走動/飛行/水潮/特殊機制）；實際落地三組＋共用件：水／潮系現役僅 bubbla（foamy/manta/frosty 已在 finaleEnemies.ts），單獨成檔過度碎片化——bubbla 與 spora 同屬「定點據點怪」語彙，併入地面系；W4 若擴水系再析出。#914 的 enemyFacing.ts 完全未動——家族模組僅 import 其三個 helper，DIRECTIONAL 分類與表驅動守門原樣生效；enemies.spawn 單一重建點契約不變（生成/傷害/回收/池衛生全數留在 enemies.ts）。

三重證據

① 機械搬移 diff 逐字可驗（最高權重）

git diff --color-moved=plain --color-moved-ws=allow-indentation-change 022db08b7..HEAD（5 個 source 檔，不含測試）：

• 新增行中判定為搬移（moved-to）：1001 行
• 全新新增行：57 行——逐行自查全數為 import、模組標頭註解、export function 簽名（對應舊 function 簽名在刪除側）、zappy 分派呼叫；零邏輯行
• 刪除行中判定為搬移走（moved-from）：980 行；真刪除 23 行（舊 import／舊標頭註解／zappy 舊 case 包裝）
• 兩段式 git 史：commit ①（314dc1bf）新模組＋測試、enemyUpdates.ts 未動；commit ②（2bcf75a1）僅切 wiring（-1007/+22）

② 既有測試零修改全綠

• git diff 022db08b7..HEAD -- '**/*.test.ts'：僅新增 4 檔（+839 行），既有測試檔 0 修改 0 放寬
• pnpm --filter @app/starpuff test：89 檔 1205 案全綠（既有 1169 案＋新模組 characterization 36 案）
• pnpm typecheck（全 workspace）、prettier --check、eslint（含 max-lines 1200 閘）、pnpm --filter @app/starpuff build 全數通過
• 不變式檢查：events 凍結（零觸碰）、save migration（零觸碰）、池衛生 acquirePooled＋POOL_TRANSIENT_FLAGS（零觸碰，均在 enemies.ts）、禁 emoji、禁硬編 854、座標經 rotation.pointerToLocal（本 diff 不涉指標處理）

③ level-audit 抽驗（走動關 ×2：L21 星港集散地／L23 冰晶潮灣）

L21 混編 drilly/chompy/boomy/glowy（搬移品種）＋cargo/ticketa/scanna；L23 混編 spora/bubbla/chompy（搬移品種）＋frosty/foamy/manta——兩關合計覆蓋三個新家族模組。

檔案層前提：git diff 022db08b7..HEAD -- apps/starpuff/src/game/logic/ 為空（靜態軸輸入零改動）。

實測（mid bot、serialized ×7 輪、兩側同協定）：

關卡	側	靜態軸 d/m/pStatic	clearRate（×7）
L21	base（794875baf）	8.5 / 8.6 / 10（total 9）	1.00（7/7 cleared）
L21	HEAD	8.5 / 8.6 / 10（total 9）	1.00（7/7 cleared）
L23	base（794875baf）	9 / 8.6 / 10（total 9.2）	1.00（7/7 cleared）
L23	HEAD	9 / 8.6 / 10（total 9.2）	1.00（7/7 cleared）

靜態軸兩側全等；clearRate 為 bot 觀測值（僅觀測不作裁決真值，AGENTS.md v5.7）。

002 與 changeset

• 002：單一聚合條目 reward-starpuff-w3prep-enemyupdates-split，檔頭 +1 → 累計 +330
• changeset：patch（純重構零使用者可感知）

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None