安裝版 app 自包含修復未生效：Bundle.module 仍吃 repo .build fallback，刪 .build 即崩（#99 殘留）

[kiki830621]

Problem

#99 的自包含修復（fee1e57 — Makefile 把 *.bundle 複製進 Contents/Resources/）未實際生效：安裝版 /Applications/Logos.app 的 Bundle.module（SwiftTerm fork 的 MetalTerminalRenderer.candidateBundles() 路徑）在 runtime 仍解析到 repo .build 的 dev-fallback，從未使用 Resources 內嵌的那份。結果是：

• repo .build/arm64-apple-macosx/release/ 存在 → app 正常。
• .build 被刪（例如 clean-gate rm -rf .build && swift test）→ 安裝版 app 啟動即崩（SIGTRAP，libswiftCore assertionFailure in NSBundle.module one-time init → MetalTerminalRenderer.candidateBundles()）。

Type

bug

實害（2026-08-01）

當日為另一 issue 跑 clean gate 刪了 .build，使用者執行中的 Logos（他的工作 terminal）隨之崩潰，且之後點開 app 都是啟動即崩（crash reports Logos-2026-08-01-164122/164221.ips），直到重建 release 產物才復活。「開發 repo 的清理動作可以殺掉已安裝的 app」——這正是 #99 想消滅的耦合，實測仍在。

Evidence

1. 安裝版（Jul 27，晚於 fee1e57 Jul 19）的 Contents/Resources/SwiftTerm_SwiftTerm.bundle 存在且含 Shaders.metal —— 內嵌步驟有跑。
2. strings 安裝版 binary：內嵌 fallback 絕對路徑為 <repo>/.build/arm64-apple-macosx/release/SwiftTerm_SwiftTerm.bundle（與 Highlightr_Highlightr.bundle 同）。
3. 決定性實驗（做過兩次，一次在 Installed Logos.app crashes at launch: SwiftPM resource bundles never embedded, Bundle.module dev-path fallback broken by .build clean #99、一次在今日）：不動安裝版、只重建 swift build -c release → app 復活。⇒ runtime 實際使用的是 .build 那份，Resources 那份從未被選中。

未定的根因細節（留給 diagnose）

SwiftPM 生成的 Bundle.module accessor 候選順序理論上是 Bundle.main.resourceURL 優先、build-dir fallback 在後。Resources копия存在卻仍走 fallback，可能性包括：Bundle(url:) 對「無 Info.plist 的裸 .bundle 目錄」回 nil（內嵌那份只有 Shaders.metal 一個檔案，無 bundle 結構）、或 accessor 候選順序與假設不符。需要對照 fork 內 accessor 生成物確認。

Expected

安裝版 app 完全自包含：.build 整個刪除後，/Applications/Logos.app 照常啟動、terminal/Metal 照常運作。驗收方式（#99 時記載過但顯然未以此驗過）：mv .build .build.away && open -a Logos → 存活；mv 回來。

Workaround（現行）

清 .build 後跑一次 swift build -c release 餵 fallback；或避免在安裝版可能被使用時清 .build。

Notes

• 環境：macOS 27.0（26A5388g）
• Related: Installed Logos.app crashes at launch: SwiftPM resource bundles never embedded, Bundle.module dev-path fallback broken by .build clean #99（原修復）、Track B 完全失效：app-hosted test runner 無法啟動（LaunchServices 錯誤），所有 hosted 測試跑不到 #104（因 clean gate 觸發本缺陷、實害發生於其 batch 過程）

Current Status

Phase: verified

[kiki830621]

Diagnosis

Root Cause（binary 取證確認）

strings 安裝版 binary 內的錯誤訊息為 could not load resource bundle: from —— 這是 SwiftPM 非 Xcode 建置的 Bundle.module accessor 變體，候選只有兩個：

1. Bundle.main.bundleURL + "<名稱>.bundle" —— 對安裝版 app 是 app 根目錄（Logos.app/SwiftTerm_SwiftTerm.bundle，Contents/ 的同層），不是 Contents/Resources/。而 app 根目錄不能放東西（macOS bundle 格式要求根層只有 Contents/，塞檔案 codesign 直接失敗），此候選對安裝版結構上永不命中。
2. 編譯時烙進 binary 的絕對路徑 <repo>/.build/arm64-apple-macosx/release/<名稱>.bundle。

所以 #99 把 bundle 內嵌進 Contents/Resources/ 的修復「沒生效」不是 embed 沒跑——是 accessor 從頭到尾不看那個位置。安裝版 runtime 只剩候選 2，.build 一刪即 fatalError（不可攔截）。dev 機上永遠正常（swift run 時 bundleURL = .build 內、候選 1 就命中），缺陷只在「.build 被清」或「別台機器」現形——與 memory 記載的 trap 完全吻合。

兩個受害 package、兩個 crash 向量

Package	觸發點	現況
SwiftTerm（fork）	啟動後 Metal renderer init（本次實害的向量）	v1.15.0 fork 的 candidateBundles() 已刻意繞開 Bundle.module、自行 probe Bundle.main.resourceURL（即 Resources 內嵌處）等候選——今晚 22:05 的安裝版應已免疫，待決定性實驗確認
Highlightr（外部 raspu/Highlightr）	CodeViewer 開任何 code 檔時 Highlightr() init 第一行 let bundle = Bundle.module（highlightPath override 也救不了——accessor 在其之前無條件求值）	未修。諷刺的是 CodeViewer 已寫好 guard let hl = Highlightr() else { return Text(content) } 優雅降級，被 fatalError 搶先殺掉

修法裁決

• 採：fork Highlightr（PsychQuant/Highlightr，branch logos-base），把 #if SWIFT_PACKAGE 的 Bundle.module 換成與 SwiftTerm candidateBundles() 同 pattern 的安全 probe（main.resourceURL → main.bundleURL → Bundle(for:)），找不到回 nil —— CodeViewer 現成的降級（純文字顯示）自然接手，process 不死。Xcode 建置的其他使用者不受影響（probe 候選 1 命中 Xcode 自動內嵌處）。
• 確認 Installed Logos.app crashes at launch: SwiftPM resource bundles never embedded, Bundle.module dev-path fallback broken by .build clean #99 的 Resources 內嵌是 load-bearing：兩個 fork probe 的第一候選就是 Contents/Resources/——Makefile embed 保留，從「無效」變成「正解的另一半」。
• 不採：app 根目錄放 bundle（codesign 拒收）；binary 字串 patch .build 路徑（hack、搬移 app 即失效）；install pipeline 改走 xcodebuild（結構性大改，SwiftPM 是 app build 的 source of truth——若日後 dmg 分發需要更徹底的自包含，再另 issue 評估）。

Layer V

V2：依賴的生成程式碼（accessor）行為與打包假設不相容——修在我們可控的層（fork probe），不對抗生成器。

Conflict Class

B_resource_serialize（動 Package.swift/project.yml 依賴宣告 + 新 fork repo；與 #108 共用「fork / 依賴」資源面，兩者相鄰序列化不交錯）

Complexity

Plan

Residue

• dmg 分發（make release-signed）情境下若使用者把 app 放非 /Applications 也能運作——fork probe 的 main.resourceURL 與位置無關，理論上覆蓋；發佈前應在乾淨機器實測（現階段無此需求）。
• 未來任何新增「帶 resources 的 SwiftPM 依賴」都會重新引入同型 trap——需要時考慮在 CI 加 strings 掃描 guard。

[kiki830621]

Implementation Complete

做了什麼

Repo	變更
PsychQuant/Highlightr（新 fork）	branch logos-base，commit 2a47153：Highlightr.init? 的 #if SWIFT_PACKAGE 分支不再碰 Bundle.module，改走 locateResourceBundle() 安全 probe（Contents/Resources → main-bundle root → class bundle，各候選驗 highlight.min.js 存在才採用）；真的找不到 → init 回 nil，CodeViewer 現成的純文字降級接手
PsychQuant/logos	75932b8：Package.swift / project.yml 改指 fork（branch: logos-base）+ CHANGELOG

SwiftTerm 側無需變更——v1.15.0 fork 的 candidateBundles() 已內建同 pattern 的 probe（今晚 22:05 的安裝版即含）。Makefile 的 Resources embed 保留：兩個 fork probe 的第一候選就是 Contents/Resources/，#99 的內嵌從「無效」變成「正解的另一半」。

意外紅利：fallback 路徑被 dead-strip

兩個 package 都不再引用 Bundle.module 後，linker 把整個生成 accessor 連同烙死的 .build 絕對路徑一起 dead-strip——strings 安裝版 binary 對 .build.*\.bundle 零命中。fatalError 的程式路徑在 binary 層面已不存在，不是「不會走到」而是「沒得走」。

Checklist

• fork 建立、patch、push（2a47153；程式碼零 Bundle.module 引用，僅註解提及）
• logos 依賴改指 fork、swift package update resolve 成功
• 全套 hard gate：641 tests / 85 suites GREEN
• make install（Apple Development 簽章）
• 決定性實驗（Installed Logos.app crashes at launch: SwiftPM resource bundles never embedded, Bundle.module dev-path fallback broken by .build clean #99 當年缺的那個驗收）：mv .build 移走 → 直接啟動安裝版 → launch finished + Metal renderer engaged + 8s 存活 + SIGTERM 乾淨終止 + 零新 crash report → .build 還原

[kiki830621]

Verify

證據鏈

1. 決定性實驗（fallback 實體不存在）：.build 整個 mv 走 → /Applications/Logos.app 直接啟動 → unified log launch finished — main scene up + terminal Metal renderer engaged（兩次，= shader 從 Contents/Resources 內嵌處載入成功）→ +8s 進程存活 → SIGTERM 乾淨終止 → 觀察窗內零新 crash report → .build 還原。這正是 Installed Logos.app crashes at launch: SwiftPM resource bundles never embedded, Bundle.module dev-path fallback broken by .build clean #99 的驗收缺口（memory 記載「decisive test 從未跑過」）——本次跑了、PASS。
2. Binary 層結構性證明：strings 安裝版 binary 對 .build/.*\.bundle 零命中——Bundle.module accessor（含 fatalError 與烙死路徑）被 dead-strip，crash 路徑不存在於 binary。
3. Highlightr 降級路徑：viewer 的 end-to-end GUI 驗證未做（headless 驅動不了開檔），但結構證據充分：fork init 內唯一的 bundle 取得路徑是 probe（miss → nil），CodeViewer 的 guard let hl = Highlightr() else { return Text(content) } 已存在；且安裝版 Contents/Resources/Highlightr_Highlightr.bundle 完整（css/js 都在），正常情境 probe 第一候選即命中、高亮照常。
4. 迴歸：全套 641/85 GREEN（fork 切換後）。

Residue（沿 Diagnosis）

• dmg 分發（非 /Applications 安裝位置）理論上被 probe 覆蓋（main.resourceURL 與位置無關），發佈前在乾淨機器實測。
• 未來新增帶 resources 的 SwiftPM 依賴會重新引入同型 trap——strings <binary> | grep '.build' 可作 CI guard，需要時另 file。

Phase → verified。注意：使用者目前執行中的 Logos 是 22:05 的舊 build（含 SwiftTerm probe、不含 Highlightr fork 與 #109 padding）——重啟後才載入本修復。