Why the handoff must reflect the runtime-ready semantic state

Constraint: The latest host state is no longer fallback-only; docs must show that torch/torchaudio/transformers are installed and the song-centric pipeline now reaches the runtime-ready placeholder branch
Rejected: Keep the old missing-dependency handoff | would mislead the next session into debugging an already-cleared blocker
Confidence: high
Scope-risk: narrow
Directive: Keep future handoff notes aligned with the latest runner report and import status before planning semantic-adapter implementation
Tested: installed torch-2.12.0+cpu, torchaudio-2.11.0+cpu, transformers-5.10.1; reran song-centric pipeline; markdown link check on /workspace/docs
Not-tested: Real MERT/MuQ adapter implementation is still pending; current semantic output is the runtime-ready placeholder

 # Changelog
 # Changelog
 
 
 ## 2026-06-04
 ## 2026-06-04
+- fresh runtime 进展：已在当前 host 成功安装 `torch-2.12.0+cpu`、`torchaudio-2.11.0+cpu` 与 `transformers-5.10.1`，重跑 song-centric 主链后确认 `semantic_runtime_available = true`、`semantic_runtime_ready_count = 5`、`semantic_fallback_count = 0`；当前 semantic 已从 fallback 推进到 `semantic_runtime_ready_placeholder`，下一步只差接真实 `MERT / MuQ` adapter。
 - 收敛 `docs/` 到当前 song-centric 主线，只保留 `README / start-here / session-handoff / postgresql-data-model / postgres_db_schema_samples / CHANGELOG` 六份核心文档，删除旧的 v2 / planner-worker / registry 扩展文档，避免新同学误入已退居次线的设计。
 - 收敛 `docs/` 到当前 song-centric 主线，只保留 `README / start-here / session-handoff / postgresql-data-model / postgres_db_schema_samples / CHANGELOG` 六份核心文档，删除旧的 v2 / planner-worker / registry 扩展文档，避免新同学误入已退居次线的设计。
 - 重写 `docs/postgresql-data-model.md`，明确 `保存切片的数据 + 模型 + feature` 的落表方案：`window` 落 `audio_object`，模型身份落 `feature_fact.model_name/model_version/feature_set_name`，具体 `fingerprint/embedding` 也统一落 `feature_fact`。
 - 重写 `docs/postgresql-data-model.md`，明确 `保存切片的数据 + 模型 + feature` 的落表方案：`window` 落 `audio_object`，模型身份落 `feature_fact.model_name/model_version/feature_set_name`，具体 `fingerprint/embedding` 也统一落 `feature_fact`。
 - 重写 `docs/postgres_db_schema_samples.md` 与入口文档，补充当前 4 表主链的流程图、典型 SQL 样例、查询回溯路径与写入顺序，统一文档口径到 `media_entity -> audio_object -> feature_fact -> set_membership`。
 - 重写 `docs/postgres_db_schema_samples.md` 与入口文档，补充当前 4 表主链的流程图、典型 SQL 样例、查询回溯路径与写入顺序，统一文档口径到 `media_entity -> audio_object -> feature_fact -> set_membership`。

@@ -62,8 +62,10 @@ acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.
 - `window_count = 5`
 - `window_count = 5`
 - `matcher_fingerprint_count = 5`
 - `matcher_fingerprint_count = 5`
 - `fallback_fingerprint_count = 0`
 - `fallback_fingerprint_count = 0`
-- `semantic_runtime_available = false`
-- `import_counts.feature_fact = 24`
+- `semantic_runtime_available = true`
+- `semantic_runtime_ready_count = 5`
+- `semantic_fallback_count = 0`
+- `import_counts.feature_fact = 29
 
 
 ---
 ---
 
 

@@ -29,9 +29,11 @@ acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.
 - `window_count = 5`
 - `window_count = 5`
 - `matcher_fingerprint_count = 5`
 - `matcher_fingerprint_count = 5`
 - `fallback_fingerprint_count = 0`
 - `fallback_fingerprint_count = 0`
-- `semantic_runtime_available = false`
-- `semantic_runtime_missing = [torch, torchaudio, transformers]`
-- `import_counts = media_entity:9 / audio_object:22 / feature_fact:24 / set_membership:9`
+- `semantic_runtime_available = true`
+- `semantic_runtime_missing = []`
+- `semantic_runtime_ready_count = 5`
+- `semantic_fallback_count = 0`
+- `import_counts = media_entity:9 / audio_object:22 / feature_fact:29 / set_membership:9`
 
 
 ---
 ---
 
 
@@ -112,19 +114,18 @@ flowchart TD
 5. 真实目录 -> manifest -> import 已验证通过
 5. 真实目录 -> manifest -> import 已验证通过
 6. 真实目录 -> fingerprint enrichment -> import 已验证通过
 6. 真实目录 -> fingerprint enrichment -> import 已验证通过
 7. exact lane 已优先复用仓库内 `ChromaprintMatcher`
 7. exact lane 已优先复用仓库内 `ChromaprintMatcher`
-8. semantic lane 已 runtime-aware，但当前 host 因依赖缺失仍走 fallback
+8. semantic lane 已 runtime-ready，当前 host 已可进入 placeholder runtime 分支
 
 
 ---
 ---
 
 
 ## 7. 当前 host 的真实 blocker
 ## 7. 当前 host 的真实 blocker
 
 
-- 缺 `torch`
-- 缺 `torchaudio`
-- 缺 `transformers`
-- 因此当前 `semantic_runtime_available = false`
+- `torch / torchaudio / transformers` 已可导入
+- 当前 `semantic_runtime_available = true`
+- 当前 semantic 仍不是 `MERT / MuQ`，而是 `semantic_runtime_ready_placeholder`
 
 
-这说明当前主要 blocker 是：
-> **语义 encoder runtime 还没就绪，不是 schema 没设计好。**
+这说明当前主要 blocker 已从“依赖缺失”推进为：
+> **runtime 已就绪，但真实 semantic adapter 还没接入。**
 
 
 ---
 ---
 
 
@@ -172,9 +173,9 @@ flowchart TD
 
 
 - exact lane 已优先复用 `ChromaprintMatcher`
 - exact lane 已优先复用 `ChromaprintMatcher`
 - semantic lane 还没有真实接入 `MERT / MuQ`
 - semantic lane 还没有真实接入 `MERT / MuQ`
-- runtime 就绪时，当前仍只会产出：
+- runtime 就绪时，当前会产出：
   - `model_name = semantic_runtime_ready_placeholder`
   - `model_name = semantic_runtime_ready_placeholder`
-- runtime 不就绪时，会走：
+- fallback 分支仍保留：
   - `model_name = local_wavehash_embed`
   - `model_name = local_wavehash_embed`
 
 
 ### fresh 依赖检查事实
 ### fresh 依赖检查事实

@@ -27,9 +27,11 @@ acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.
 - `window_count = 5`
 - `window_count = 5`
 - `matcher_fingerprint_count = 5`
 - `matcher_fingerprint_count = 5`
 - `fallback_fingerprint_count = 0`
 - `fallback_fingerprint_count = 0`
-- `semantic_runtime_available = false`
-- `semantic_runtime_missing = [torch, torchaudio, transformers]`
-- `import_counts = media_entity:9 / audio_object:22 / feature_fact:24 / set_membership:9`
+- `semantic_runtime_available = true`
+- `semantic_runtime_missing = []`
+- `semantic_runtime_ready_count = 5`
+- `semantic_fallback_count = 0`
+- `import_counts = media_entity:9 / audio_object:22 / feature_fact:29 / set_membership:9`
 
 
 ---
 ---
 
 
@@ -97,8 +99,8 @@ flowchart TD
 - live PostgreSQL schema 已真实建表通过
 - live PostgreSQL schema 已真实建表通过
 - 真实目录 -> manifest -> import 已打通
 - 真实目录 -> manifest -> import 已打通
 - 真实目录 -> fingerprint enrichment -> import 已打通
 - 真实目录 -> fingerprint enrichment -> import 已打通
-- semantic lane 已做成 runtime-aware
-- 当前 host 无 `torch/torchaudio/transformers` 时会明确 fallback，不会伪装成功
+- semantic lane 已做成 runtime-ready
+- 当前 host 已能进入 runtime-ready placeholder 分支，下一步只差接真实 `MERT / MuQ`
 - 当前 exact lane 已优先复用仓库内 `ChromaprintMatcher`
 - 当前 exact lane 已优先复用仓库内 `ChromaprintMatcher`
 
 
 ---
 ---
@@ -106,13 +108,14 @@ flowchart TD
 ## 7. 当前最该继续什么
 ## 7. 当前最该继续什么
 
 
 ### 第一优先级
 ### 第一优先级
-把 semantic lane 从 fallback 升级成真实 encoder adapter，且不破坏现有宿主链。
+把 semantic lane 从 `semantic_runtime_ready_placeholder` 升级成真实 encoder adapter，且不破坏现有宿主链。
 
 
 ### 当前 host 事实
 ### 当前 host 事实
-- `torch` 缺失
-- `torchaudio` 缺失
-- `transformers` 缺失
-- 当前因此 `semantic_runtime_available = false`
+- `torch` 已可导入
+- `torchaudio` 已可导入
+- `transformers` 已可导入
+- 当前 `semantic_runtime_available = true`
+- 当前最新主链产出仍是 `semantic_runtime_ready_placeholder`，不是真实 `MERT / MuQ`
 
 
 ---
 ---