從零到 synthetic smoke：公開步驟與真實資料邊界

● 一定要先做這步。Git 不發布受版控的 build output；請依 release manifest checkout immutable commit，再在 repo 外 clean build。

git clone https://github.com/liaoyoyo/InterSubMod.git
cd InterSubMod
HANDOFF_COMMIT="<IMMUTABLE_HANDOFF_COMMIT_SHA>"
git checkout --detach "$HANDOFF_COMMIT"
test "$(git rev-parse HEAD)" = "$HANDOFF_COMMIT"
test -z "$(git status --porcelain)"

REPO_ROOT="$(pwd -P)"
BUILD_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/ism-build.XXXXXXXX")"
# repo 外的全新 Release build；不產生受版控 build output
cmake -S "$REPO_ROOT" -B "$BUILD_ROOT" -DCMAKE_BUILD_TYPE=Release
cmake --build "$BUILD_ROOT" -j$(nproc)
test -z "$(git -C "$REPO_ROOT" status --porcelain)"

執行檔數量與名稱是 commit-specific；由該次 clean-build receipt 動態保存，不手抄固定六個：

find "$BUILD_ROOT/bin" -maxdepth 1 -type f -perm -u+x -printf '%f\n' | sort
test -x "$BUILD_ROOT/bin/inter_sub_mod"
test -x "$BUILD_ROOT/bin/run_tests"

"$BUILD_ROOT/bin/run_tests"
ctest --test-dir "$BUILD_ROOT" --output-on-failure

本輪實跑的真實輸出：

[==========] <N> tests from <S> test suites ran.
[  PASSED  ] <N> tests.

$ echo $?
0

動態 N/N 通過，0 failure 如果這裡有任何失敗，先不要往下走 —— 後面跑出來的數字都不可信。

# 建立與 hosted acceptance 相同的 hash-locked Python 3.10 環境
PYTHON_ENV="$(mktemp -d "${TMPDIR:-/tmp}/ism-python.XXXXXXXX")/venv"
python3.10 -m venv "$PYTHON_ENV"
"$PYTHON_ENV/bin/python" -m pip install --require-hashes \
  --requirement "$REPO_ROOT/requirements-ci.lock"
export PATH="$PYTHON_ENV/bin:$PATH"

DEMO tracked synthetic FASTA／VCF／SAM會在新暫存目錄轉成BAM/index，完成build→run→schema validation。 這不是生物資料、benchmark或science validation。

"$REPO_ROOT/scripts/handoff/run_tiny_public_e2e.sh" --repo-root "$REPO_ROOT" --jobs 4

TINY_E2E_RESULT {"all_pass": true, ...,
  "tree_semantics": "read_dendrogram_from_methylation_distance_not_cellular_lineage"}

驗收：exit 0、all_pass=true；scope固定為 DEMO，不寫入science validation ledger。

進階：自備／內部真實資料（internal-data example）

INTERNAL-ONLY 下列三個輸入路徑未隨公開 GitHub 發布； 只有已取得資料與授權的環境才能執行；歷史 HCC1395 receipt 不是一般 runtime promise。

# 將 placeholder 換成本機 profile；絕對路徑只維護於 untracked machine profile／registry
SITE_PROFILE="<SITE_PROFILE>"
"$REPO_ROOT/scripts/site/doctor" --profile "$SITE_PROFILE" --mode real-preflight
eval "$("$REPO_ROOT/scripts/site/site_profile.py" shell \
  --profile "$SITE_PROFILE" --sample HCC1395)"
SP="${TMPDIR:-/tmp}/ism_demo" && mkdir -p "$SP"

# 準備只含第一筆 biallelic SNV 的 smoke-test VCF
bcftools view -h "$SOMATIC_VCF" > "$SP/one_snv.vcf"
bcftools view -m2 -M2 -v snps -H "$SOMATIC_VCF" | head -n 1 >> "$SP/one_snv.vcf"
test "$(bcftools view -H "$SP/one_snv.vcf" | wc -l)" -eq 1

# 跑（只給三個必填參數）
"$BUILD_ROOT/bin/inter_sub_mod" \
  --tumor-bam  "$TUMOR_BAM" \
  --reference  "$REFERENCE" \
  --vcf        "$SP/one_snv.vcf" \
  --output-dir "$SP/out_min"

2026-08-06 內部環境的歷史實跑輸出（只屬具名輸入 receipt，不作 runtime 驗收值）：

Total regions: 1 / Successful: 1 / Failed: 0
Total reads processed: 85
Forward strand (+): 40 / Reverse strand (-): 45
Total CpG sites found: 11
Metric: NHD / Total valid read pairs: 3443 / Total invalid pairs: 127

find $SP/out_min -type f | head -20

輸出分兩層。先看這三個檔：

cd docs/methodology/_assets/20260627_subclone_4axis_teaching/scripts
python3 verify_pipeline_numbers.py

這支只重算歷史 35,332-site pipeline 的 TP/FP 與共現分類數字。它不驗證 2026-07-24 exact-PS、LongLineage、storage、程式碼/測試計數或本頁 Step 4 的公開可重現性。歷史實跑輸出：

sSNV 總數 35,332（TP 30,490 / FP 4,842）              ✓
共現連上 21,554 · 訊號不足 5,458 · 孤立 8,320        （加總 = 35,332 ✓）

對得上，只代表該歷史方法文件的受管數字與它所讀取的 artifacts 一致；其他 claim family 必須各用 authority manifest、receipt 與專用 validator 驗證。

07全流程速查

08常見狀況排除