解釋中心
部件分冊 · 第 13 頁 · LongLineage

LongLineage：PRIVATE research preview；frozen HCC1395 receipt 為 0 個 candidate topology units

這是 PRIVATE research-preview candidate；source-origin、license 與 dependency audit 尚待完成， 因此不能先宣稱 clean-room 或已適合公開。Immutable candidate 為 b9aaa12，狀態 NOT_READY/non-production，P3/P4/P5/P7/P8 仍 BLOCKED。 本頁的「0」只指該 revision 的 frozen HCC1395 dataset-gate receipt，不外推其他資料或 run。

Release boundary（2026-08-13 research handoff snapshot） Repository 目前為 PRIVATE；b9aaa12 是 public-preview candidate、不是已公開版本。 Production run 刻意 fail-closed，尚無 production tag 或 GitHub Release。 5daf50f 只作 private baseline/main capability snapshot。

一句話

LongLineage 把 ONT 資料算成「哪些 candidate somatic variants 共同出現在同一條 read 上」的證據表， 再用最少隱藏節點的超立方體建立 local、recurrence-allowed、model-conditional mutation-state candidate topology。 Same-read 共現是 molecule-level evidence；cellular clone/subclone 與 biological lineage 未被確認。

它與 InterSubMod 的根本差異：ISM 輸出是 per-region（每個位點一包結果）， LL 輸出是 per-read（每條 read 一列）；ISM 從 BAM 直接讀單倍型標籤， LL 明文禁止讀 BAM tag，只認 sidecar 檔案。

79,687
輸入的體細胞突變位點
12,851
通過甲基化關卡（16.1%）
5
通過第二道關卡
0
最終拓撲單元

01四個子命令：frozen HCC1395 receipt 中只有 dataset-gate 產生 research artifacts

下表限定 private candidate b9aaa12 與具名 frozen HCC1395 receipt；狀態由該次 exit code 或對應 source inspection 取得，不外推其他 revision/dataset。

子命令狀態實測依據
preflight可跑 驗證 8 個角色的 manifest 完整性。
dataset-gate可跑但綁死 在該 frozen HCC1395 receipt 中，唯一觀察到能產生 research artifacts 的介面；該次產出 8 個 artifact，不等於 production science validation。
run被鎖 回 KernelBlocked（exit 6）。實測 message="release attestation is NOT_READY"。
probe被鎖 同上。且其輸出依設計「永遠是 PARTIAL，不能成為驗證證據」。
● 一個很容易踩的誤解 很多人會想：「把 release_attestation.json 改成 READY 就能跑正式流程了吧？」 不行。就算通過 attestation 這道閘門，控制流走到函式最後一段， 仍會對 run 與 probe 無條件回傳 KernelBlocked。 正式入口與科學核心之間根本沒有接線。
但請注意這個關鍵區辨 P3/P4/P5/P7/P8 具名 gates 尚未通過，涵蓋 parity／validation、 source-origin、license、dependency 與 release-safety。部分 M1／M2／topology kernels 曾被 具名 dataset-gate receipt 執行，但不等於全部核心路徑、production entry、 生物驗證或公開 redistribution 資格完成。 （整體仍是 NOT_READY／non-production。）

周邊工具的真實狀態

longlineage-query、longlineage-export-legacy、longlineage-evaluate 這三支是真的空殼 —— 不是「跑不動」而是「沒寫」。 證據：它們在建置設定裡根本沒有連結科學程式庫， 二進位檔裡不存在任何讀取或轉換資料的程式碼。就算給它一個完美的凍結 run，也只會回 not implemented。

● 另外 longlineage-query 只接受狀態為 VALIDATED_FROZEN 的 run， 但 HCC1395 那個 run 的狀態是 VALIDATED_FROZEN_DATASET_GATE —— 實測回 exit 8 拒絕。要讀資料目前只能自己 zcat。

tagged-BAM 也有 revision boundary：private baseline/main snapshot 5daf50f 沒有 writer； private public-preview candidate b9aaa12 含 longlineage-tag-bam，但尚未發布，不能視為 production capability。

02為什麼輸出是 0？—— 甲基化是總開關，不是輔助

這是本頁最重要的一節。答案不在程式效能或資料量，而在科學設計的一個前提。

圖 1 · candidate b9aaa12 的 frozen HCC1395 dataset-gate receipt：79,687 個位點如何流失到 0 candidate units
LongLineage 位點流失漏斗 此圖僅描述 HCC1395-only frozen dataset-gate，非全樣本或 production 驗證。從 79,687 個凍結的體細胞突變位點開始，78,629 個可評估， 其中只有 12,851 個通過甲基化穩定分群關卡；這 12,851 個再經第二道關卡後只剩 5 個合格， 12,815 個被判為資訊不足、31 個被判為確實不合格；共現配對共 134,278 列但其中 134,276 列被前一道關卡擋掉； 聯合特徵檢定通過 0 個位點，最終拓撲單元為 0。 凍結的體細胞突變位點（chr1–22） 79,687 M1 可評估（突變型 read 數足夠） 78,629 突變型 read 太少 1,044 距離矩陣不完整 14 M1 甲基化分群「穩定」的位點 12,851 只佔全部的 16.1% 66,836 個位點 在共現層完全沒有任何列 （連配對都不會產生） M2 第二道關卡通過 5 資訊不足 12,815 （不是「被證明是假象」） 真正判定不合格 31 5 + 31 + 12,815 = 12,851 共現配對表 134,278 列 其中 134,276 列被前一道關卡標為不合格 聯合特徵檢定通過的位點 0 最終拓撲單元 0 為什麼這件事在科學上很重要 直覺會以為「突變共現是獨立的骨幹，甲基化只是旁證」。但在這套實作裡， 建立共現表的第一件事就是檢查甲基化有沒有分出穩定的群 —— 沒過就直接回空結果。 後果：79,687 個位點裡有 66,836 個（83.9%）在共現層根本不存在任何一列。 因此任何「共現覆蓋率」的解讀，都必須先扣掉這個甲基化前提，否則會嚴重高估。 這也正是它與 InterSubMod「甲基化絕不進重建」立場衝突的地方（見系統全景頁 §2）。
數字已驗算：5 + 31 + 12,815 = 12,851，與 M1 穩定位點數完全相符。
● 一個極易誤讀的統計：M2 沒通過的最大宗是 12,815 個「資訊不足以判斷」（佔 99.7%）， 這不是「99.7% 的甲基化分群都被證明是技術假象」。 前者是「測不出來」，後者是「測出來是假的」—— 真正被判定為確實不合格的只有 31 個。 在報告裡把這兩者混為一談，會得出完全相反的結論。
● candidate b9aaa12 尚無非空 candidate topology 的 run-level evidence 現存三個完整科學 run 的拓撲輸出檔都是 28 bytes（僅檔案結尾標記，零筆資料）。 如果直接拿 LL 當「已經算出亞群樹」的證據，會落空。
真正跑出區域樹的是另一條 descriptive-only 的相容路徑， 但該路徑的規格文件明文禁止它宣稱 clone／祖先／時序／正式拓撲發現。

03輸出的 artifact — 契約設計品質很高

即使拓撲是 0，前面幾層的 artifact 都有實體資料，而且格式被 schema 鎖死、每個檔都有 SHA-256 收據。 這些資料是可以拿來用的。

artifact欄數 實測列數回答什麼問題
site_reads237,578,727
620 MB		 每條 read 在每個位點的觀測：read 識別碼、單倍型、定相組、以及該 read 在此位點是正常型/突變型/其他/未覆蓋。 不受甲基化關卡影響 —— 每個位點都無條件寫出，所以它是最完整、最可用的一份。
methyl_calls17261,130,339
4.56 GB		 每條 read 每個 CpG 的甲基化判讀。
m1_sites3079,687 每個位點的甲基化分群結果與穩定性判定。
m1_assignments—78,629 哪些 read 被分到哪一群。注意：這是甲基化的群，不是亞群譜系標籤。
cooccurrence_pairs74134,278 兩個位點在同一條 read 上的共現統計。
cooccurrence_sites2479,687 每個位點的共現彙總。
topology_units34 必填鍵0
28 bytes		 本來要放拓撲解的地方。目前是空的。
一個設計上的亮點值得學習 topology_unit 的 schema 把「解到什麼程度」拆成四個獨立狀態欄位 （用哪條求解路徑／目標函數狀態／候選家族狀態／排序狀態）， 並且每種放棄都有具名的理由。 這讓「沒解出來」不會被誤讀成「解出來是空的」—— 值得在自己的輸出格式裡沿用。
read_id 是怎麼算的 — 想把結果對回 BAM 時必看

read_id 是 SHA-256 雜湊，設計上是不可逆的（schema 的型別名稱就叫 opaque_sha256）。

● 但它不是 SHA-256(原始 QNAME)，而是 SHA-256(投影後的 QNAME)： 當 FLAG 顯示這是配對定序時，會先依 READ1／READ2 補上 /1 或 /2 再做雜湊。

ONT 是單端資料通常沒差別，但如果你想拿 read_id 回去 BAM 對回原始 read， 直接 sha256(QNAME) 在配對資料上會對不上。

好消息：因為是確定性的正向計算，讀 BAM 時對每條 QNAME 重算一次雜湊就能 join，不需要任何反查表。

04使用前必知的六個陷阱

這些會讓你「以為程式壞了」或「得到假結論」。

嚴重陷阱說明
● dataset-gate 硬編碼只認 HCC1395 不只樣本名稱要字面相符，連 VCF 記錄數都必須剛好是 113,061／79,687／33,374， 授權識別碼也要完全一致。想拿 COLO829 或 H1437 跑是不可能的，會直接被拒。換樣本必須改 C++ 重新編譯。
● repo 裡有 17 個 build 目錄，拿錯就得到假結論 各目錄的執行檔來自不同 commit。實測其中一個跑整合測試會 FAIL（回報 schema 識別碼不符）， 另一個跑就 PASS。隨手挑一個 build 目錄，很容易把「執行檔過期」誤判成「程式壞掉」。
● 從 tarball 編出來的版本直接拒跑 編譯時若沒有 .git（下載 tarball 或 CI 淺複製），內嵌的 commit 會是 40 個 0， dataset-gate 第一件事就是檢查這個並拒絕執行。
● 契約檔已經和凍結的 run 漂移 拿今天 repo 的 schema 去驗 2026-07-20 的 run 會不通過（catalog 與參數檔的 SHA 都已不同）。 而且 summary 的 schema 有版本斷層：catalog 指向 2.0.0，真實 run 產出的是 1.0.0。 照新版 schema 描述欄位，會描述到檔案裡根本沒有的東西。
中 sidecar 表頭必須一個位元組都不差 第一行必須逐位元組相符，而且必須是 BGZF 壓縮（不是普通 gzip）。 實測連 repo 自己的測試 fixture 拿去跑 preflight 都會被打回。
中 schema 列了但程式不會產出的狀態值 schema 列舉了四種求解路徑，但程式只會產出三種；另有兩個狀態值在整個原始碼裡搜不到。 照 schema 寫方法學章節，會多寫出實際不存在的分支。
● 最重要的語意警告：一條 read 對應到哪個節點，沒有唯一解 至少六種情況會讓一條 read 同時相容於多個候選節點（部分覆蓋的 read、並列的候選集合、 父節點映射並列……）。這是模型本身的性質，不是 bug，程式從頭到尾都刻意不做硬指派。
任何下游把「這條 read 屬於哪個亞群」當成確定值來統計，都是把「放棄判定」讀成了「已判定」。 輸出格式必須用狀態列舉來表達這件事，不可強制給唯一標籤 —— 否則就是 overclaim。
← 上一頁：ISM 部件 回系統全景 下一頁：上游與資料 →