NS 遊戲到 Apple ARM 的原生移植

以原遊戲程式碼在目標裝置上產生可見、可操作、可儲存的結果為目標。CPU 同為 ARM64 只減少指令翻譯工作，不能省略 OS ABI、記憶體、執行緒、圖形、音訊與輸入相容層。

語言與架構要求

新建移植核心必須使用 Rust（.rs），以 Cargo workspace 分離資源解析、共享 ABI、離線改寫、著色器轉換與 host runtime。已有 Rust 專案直接複用；已有 C/C++ 原生模組透過明確的 FFI 邊界接入，不為統一語言重寫已驗證模組。使用者明確指定其他技術棧時遵從並記錄差異。
Swift 用於啟動器與 Apple 平台 UI；Objective-C/Objective-C++、C/C++ 用於必要的系統橋接或現成原生庫；AArch64 組合語言限於入口、暫存器儲存及呼叫跳板；Metal Shading Language（MSL）用於 GPU 程式。Python/Bash 只編排資源準備、建置、簽署與診斷，不承載逐幀回放或 guest 執行熱路徑。
路線為本地資源解析 → AArch64 離線改寫 → 原遊戲機器碼原生執行 → Horizon/SDK 相容 → NVN 命令錄製與 Metal 回放。保留原遊戲邏輯，不以重寫玩法、宿主示範畫面或僅有 API 空樁替代移植。
開始實現或跨遊戲複用前讀 architecture-and-workflow.md，確定模組邊界、遊戲版本配置與最短路徑縱向驗證。該參考提煉自 Rust/Cargo 的實際移植結構，不依賴原專案存在於本機。

從使用者指定目錄或當前工作區定位目標倉庫；參考倉庫只在使用者提供或當前工作區可發現時讀取，不假定任何開發者本機路徑。讀取目標倉庫說明、局部 AGENTS.md、Git 狀態、建置入口和最新驗證記錄。先確認使用者要實現、診斷還是只評估；評估任務保持唯讀。
建立輸入矩陣：遊戲/Title ID、本體/升級/DLC、顯示版本、NPDM 架構、實際 NSO 模組 build ID、目標 OS/晶片、原始碼版本、執行方式。以實際提取模組為準，不憑檔案名稱或遊戲名稱推定 AArch64。
保留既定路線。已有原生相容層基礎時複用提取、改寫、host 與 Metal 架構，逐模組比較；不要把其他遊戲的位址修補直接搬過來。新專案先檢查是否有可複用相容層，再決定工程量。AArch32 輸入不適用於這條 AArch64 直接執行路線；尋找使用者已有的合適版本或明確需要另一條執行路線。
先選一個可重複的最短路徑驗收：啟動 → 標題/選單 → 場景 → 操作 → 正常退出 → 新程序讀檔。階段性推進一個實際阻塞，使用日誌、程式碼和畫面確認原因。

先記錄故障所在層：提取/身份識別 → 指令改寫 → 裝載/重定位 → SDK/服務 → 命令錄製 → Metal 回放/提交 → 實際視窗 → 遊戲行為。
每輪用一個可證偽假設，收集最小必要證據，再作局部修復。診斷開關預設關閉，有數量/大小上限；異常應包含模組相對位置、請求或資源資訊，不能洩露金鑰。
為底層語意修復選擇合適驗證：指令等價、ABI 佈局、並行、真實 GPU 讀回。靜態檢查與建置後，按使用者授權範圍執行實際遊戲；使用者禁止測試時只記錄尚未驗證，不擅自執行。
對應版本的原始碼、建置、安裝包、執行 ID、日誌和截圖必須能關聯。新建置不能藉舊裝置日誌證明成功。
保留診斷反例，更新當前結論。抓幀/單步可能改變時序；修復後用關閉重診斷的新程序複測。不要為消除表面異常而硬改角色高度、水色、碰撞或遊戲進度。
未知服務、指令或格式保留明確失敗資訊；僅在證明呼叫端允許降級時實現有語意的降級。不要普遍回傳成功掩蓋未實現功能。

完成報告說明：修改了什麼、實際執行到哪一步、證據對應哪個建置和裝置、仍有哪些限制、下一步應驗證哪個阻塞。避免無法證實的完成百分比或「已全面相容」。