Make the Phase-1 planner carry live validation entrypoints

Constraint: The repo now has multiple verified smoke and audit scripts, so leaving them outside the planner would force future sessions to rediscover the right validation commands by reading docs.
Rejected: Document the commands only in markdown | That would drift from the executable plan artifact and slow restart execution.
Confidence: high
Scope-risk: narrow
Directive: Treat validation_commands in the planner as the first-stop entrypoints before running individual extraction jobs on a new host.
Tested: /usr/local/miniconda3/bin/python -m py_compile scripts/plan_phase1_extraction_jobs_live.py; git diff --check; /usr/local/miniconda3/bin/python scripts/plan_phase1_extraction_jobs_live.py --dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' --schema acr_test --job-status pending --output data/pgvector_eval/music20/phase1_extraction_plan_report.json
Not-tested: The planner still emits commands for an environment-blocked host and does not prove successful extraction by itself.

@@ -467,6 +467,12 @@
       }
     ]
   },
+  "validation_commands": {
+    "prereq_audit": "cd /workspace/acr-engine && PG_DSN=\"${PG_DSN:?set PG_DSN}\" /usr/local/miniconda3/bin/python scripts/run_phase1_prereq_audit_live.py --dsn \"$PG_DSN\" --schema acr_test --output data/pgvector_eval/music20/phase1_prereq_audit_report.json",
+    "worker_contract_smoke": "cd /workspace/acr-engine && PG_DSN=\"${PG_DSN:?set PG_DSN}\" /usr/local/miniconda3/bin/python scripts/run_phase1_worker_contract_smoke_live.py --dsn \"$PG_DSN\" --schema acr_test --output data/pgvector_eval/music20/phase1_worker_contract_smoke_report.json",
+    "semantic_vector_negative_matrix": "cd /workspace/acr-engine && PG_DSN=\"${PG_DSN:?set PG_DSN}\" /usr/local/miniconda3/bin/python scripts/run_embedding_vector_table_negative_matrix_live.py --dsn \"$PG_DSN\" --output data/pgvector_eval/music20/embedding_vector_table_negative_matrix_report.json",
+    "asset_level_upsert_validation": "cd /workspace/acr-engine && PG_DSN=\"${PG_DSN:?set PG_DSN}\" /usr/local/miniconda3/bin/python scripts/validate_audio_embedding_asset_upsert_live.py --dsn \"$PG_DSN\" --schema acr_asset_upsert_test --output data/pgvector_eval/music20/audio_embedding_asset_upsert_live_report.json"
+  },
   "execution_order_summary": [
     {
       "order": 1,

@@ -60,6 +60,29 @@ def build_command_suggestions(job: dict[str, Any], schema: str) -> list[str]:
     return commands
 
 
+def build_validation_commands(schema: str) -> dict[str, str]:
+    command_prefix = 'cd /workspace/acr-engine && '
+    base = command_prefix + 'PG_DSN="${PG_DSN:?set PG_DSN}" '
+    return {
+        'prereq_audit': (
+            base
+            + f"{PYTHON_BIN} scripts/run_phase1_prereq_audit_live.py --dsn \"$PG_DSN\" --schema {schema} --output data/pgvector_eval/music20/phase1_prereq_audit_report.json"
+        ),
+        'worker_contract_smoke': (
+            base
+            + f"{PYTHON_BIN} scripts/run_phase1_worker_contract_smoke_live.py --dsn \"$PG_DSN\" --schema {schema} --output data/pgvector_eval/music20/phase1_worker_contract_smoke_report.json"
+        ),
+        'semantic_vector_negative_matrix': (
+            base
+            + f"{PYTHON_BIN} scripts/run_embedding_vector_table_negative_matrix_live.py --dsn \"$PG_DSN\" --output data/pgvector_eval/music20/embedding_vector_table_negative_matrix_report.json"
+        ),
+        'asset_level_upsert_validation': (
+            base
+            + f"{PYTHON_BIN} scripts/validate_audio_embedding_asset_upsert_live.py --dsn \"$PG_DSN\" --schema acr_asset_upsert_test --output data/pgvector_eval/music20/audio_embedding_asset_upsert_live_report.json"
+        ),
+    }
+
+
 def main() -> None:
     ap = argparse.ArgumentParser()
     ap.add_argument('--dsn', required=True)
@@ -166,6 +189,7 @@ def main() -> None:
         },
         'ordered_jobs': jobs,
         'by_lane': by_lane,
+        'validation_commands': build_validation_commands(schema),
         'execution_order_summary': [
             {
                 'order': idx + 1,

 ## 2026-06-04
 
+- 更新 `scripts/plan_phase1_extraction_jobs_live.py` 与 `phase1_extraction_plan_report.json`，除了 per-job `command_suggestions` 之外，又补充了 `validation_commands`：`prereq_audit`、`worker_contract_smoke`、`semantic_vector_negative_matrix`、`asset_level_upsert_validation`，使 planner 本身也成为下次 session 的执行入口。
 - 新增 `scripts/run_phase1_prereq_audit_live.py` 与 `phase1_prereq_audit_report.json`，把 `/workspace/downloads` 挂载状态、`torch/torchaudio/transformers/speechbrain` 依赖状态与 5 条 Phase-1 jobs 的 readiness 汇总到一份 live 审计报告；当前结果为 `ready_jobs=0`、`blocked_jobs=5`。
 - 新增 `scripts/run_embedding_vector_table_negative_matrix_live.py` 与 `embedding_vector_table_negative_matrix_report.json`，在 live PostgreSQL 上补齐 semantic preflight 的三类向量表负例：维度不匹配、未 allowlist、schema 缺表；三类 case 都会稳定落到 `preflight_failed`，且 `vector_table_report.reason` 与预期一致。
 - 新增 `scripts/run_phase1_worker_contract_smoke_live.py` 与 `phase1_worker_contract_smoke_report.json`，把 exact lane 非 dry-run 验证与 semantic preflight matrix 合成一条 live smoke 命令；当前总览结果为 exact=`failed/unreadable_audio_assets`、semantic=`4/4 failed`，说明阻塞点已经收敛到环境挂载与模型 runtime，而不是 worker contract 本身。

@@ -450,3 +450,21 @@ cd /workspace/acr-engine && PG_DSN="${PG_DSN:?set PG_DSN}" EXTRACTION_JOB_ID=2 F
 ```
 
 这意味着下个 session 不需要先手工拼环境变量和 job 绑定关系，而可以直接从 planner 报告里复制命令模板。
+
+### 10.4 planner 现在也会附带 validation commands
+
+除了 per-job command suggestion，当前 planner 还会输出一组全局验证入口：
+
+- `prereq_audit`
+- `worker_contract_smoke`
+- `semantic_vector_negative_matrix`
+- `asset_level_upsert_validation`
+
+也就是：
+
+1. 先审计 host 前置条件
+2. 再跑 exact+semantic 的 contract smoke
+3. 再检查 semantic vector-table 负例是否稳定
+4. 再验证 asset-level upsert contract
+
+这让 planner 从“只会排任务”升级成“同时给出执行前检查入口”的交付物。

@@ -140,6 +140,10 @@ Phase-1 的交付目标不是“证明某个新模型绝对最优”，而是：
 - [ ] 做 query encode
 - [ ] 返回 `retrieval_candidate`
 - [ ] 聚合到 `recording / work / canonical_song`
+- [ ] 跑 `phase1_prereq_audit`
+- [ ] 跑 `phase1_worker_contract_smoke`
+- [ ] 跑 `semantic_vector_negative_matrix`
+- [ ] 跑 `asset_level_upsert_validation`
 
 ### 第一版聚合建议
 - max score
@@ -224,3 +228,15 @@ flowchart TD
 4. encoder-only 抽特征
 5. 双路召回与聚合
 6. benchmark 与门禁
+
+
+## 6.1 当前 planner 已提供的 validation entrypoints
+
+`acr-engine/scripts/plan_phase1_extraction_jobs_live.py` 现在除了 job 级 `command_suggestions`，还会在 `phase1_extraction_plan_report.json` 里附带：
+
+- `validation_commands.prereq_audit`
+- `validation_commands.worker_contract_smoke`
+- `validation_commands.semantic_vector_negative_matrix`
+- `validation_commands.asset_level_upsert_validation`
+
+这意味着下次启动时可以先跑“全局验证入口”，再决定是否执行具体 job，而不必手工拼测试命令。

@@ -196,6 +196,7 @@ sed -n '1,320p' acr-engine/sql/acr_pg_schema_v2.sql
 - `scripts/run_phase1_worker_contract_smoke_live.py` 已提供一条命令的全局 smoke：当前 exact lane = `failed/unreadable_audio_assets`，semantic lane = `4/4 failed`，共性 blocker 已固化为音频挂载缺失 + 语义模型 runtime 缺失
 - `scripts/run_embedding_vector_table_negative_matrix_live.py` 已在 live PostgreSQL 上补齐 semantic vector-table 负例矩阵：`vector_table_dim_mismatch`、`vector_table_not_allowlisted`、`vector_table_missing_in_schema` 三类错误都能被稳定写入 `vector_table_report.reason`
 - `scripts/run_phase1_prereq_audit_live.py` 已给出当前 host 的先决条件审计：`downloads_root_exists=false`、`ready_jobs=0/5`，并把 `torch/torchaudio/transformers/speechbrain` 的缺失状态按 job 落成 JSON 报告
+- `phase1_extraction_plan_report.json` 现已附带 `validation_commands`，下次 session 可以直接从 planner 复制 `prereq_audit / worker_contract_smoke / semantic_vector_negative_matrix / asset_level_upsert_validation` 四类命令
 - `phase1_hot_reference_v1` 在 `acr_test` 里已经真实补齐 `20` 个 reference members，因此 worker dry-run 当前看到的 scope 已是 `20 recordings / 20 assets / 20 windows`
 - worker contract 现在已有基础前置状态保护；重复执行同一 chromaprint dry-run job 会被 `expected_status=pending` 明确拒绝，证据见 `phase1_worker_double_claim_guard_report.json`
 - exact lane 的 `run_chromaprint_job.py` 已具备非 dry-run 写入路径；当前在 `acr_test` 的 live 结果是因为 `/workspace/downloads/...` 缺失而明确 `failed`，不是继续假装 `completed`