Collapse the song-centric directory workflow into one live runner

Constraint: Keep the current real-directory onboarding path executable end-to-end on this host while exposing exact/semantic backend selection in one reproducible report.
Rejected: Leave the song-centric pipeline as multiple manual commands only | It raises handoff cost and makes repeated host validation slower and noisier.
Confidence: high
Scope-risk: narrow
Directive: Use run_songcentric_directory_pipeline_live.py as the default smoke/verification entrypoint for the current song-centric ingestion path.
Tested: /usr/local/miniconda3/bin/python acr-engine/scripts/run_songcentric_directory_pipeline_live.py --dsn postgres://d2:d2pass@127.0.0.1:5432/d2 --schema acr_songcentric_test --input-root acr-engine/data/songcentric_builder_smoke --output-dir acr-engine/data/pgvector_eval/music20; git diff --check; /usr/local/miniconda3/bin/python scripts/check_markdown_links.py --root docs returned OK for 11 active markdown files
Not-tested: very large directory trees and true semantic runtime readiness on this host

+{
+  "input_root": "/workspace/acr-engine/data/songcentric_builder_smoke",
+  "output": "/workspace/acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest.jsonl",
+  "song_count": 2,
+  "asset_count": 2,
+  "window_count": 5,
+  "window_ms": 5000,
+  "stride_ms": 2500,
+  "set_name": "phase1_hot_reference_v1"
+}
\ No newline at end of file

+{
+  "input_manifest": "/workspace/acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest.jsonl",
+  "output_manifest": "/workspace/acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest_with_features.jsonl",
+  "rows": 2,
+  "wav_windows_seen": 5,
+  "features_added": 10,
+  "matcher_fingerprint_count": 5,
+  "fallback_fingerprint_count": 0,
+  "semantic_runtime_available": false,
+  "semantic_runtime_missing": [
+    "torch",
+    "torchaudio",
+    "transformers"
+  ],
+  "semantic_runtime_ready_count": 0,
+  "semantic_fallback_count": 5
+}
\ No newline at end of file

+{
+  "schema": "acr_songcentric_test",
+  "manifest": "acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest_with_features.jsonl",
+  "imported": [
+    {
+      "song_id": 8,
+      "asset_id": 16,
+      "window_ids": [
+        17,
+        18,
+        19
+      ],
+      "feature_ids": [
+        20,
+        11,
+        21,
+        13,
+        22,
+        15
+      ],
+      "membership_ids": [
+        8
+      ]
+    },
+    {
+      "song_id": 9,
+      "asset_id": 20,
+      "window_ids": [
+        21,
+        22
+      ],
+      "feature_ids": [
+        23,
+        17,
+        24,
+        19
+      ],
+      "membership_ids": [
+        9
+      ]
+    }
+  ],
+  "counts": {
+    "media_entity": 9,
+    "audio_object": 22,
+    "feature_fact": 24,
+    "set_membership": 9
+  },
+  "window_lineage_sample": {
+    "window_id": 22,
+    "asset_id": 20,
+    "song_id": 9,
+    "title": "song beta",
+    "start_ms": 1000,
+    "end_ms": 6000
+  },
+  "feature_lineage_sample": {
+    "feature_type": "fingerprint",
+    "model_name": "chromaprint_matcher",
+    "model_version": "phase1_local",
+    "feature_set_name": "chromaprint_matcher_5s",
+    "window_id": 22,
+    "song_id": 9,
+    "title": "song beta"
+  }
+}
\ No newline at end of file

+{"song": {"biz_key": "song_alpha", "title": "song alpha", "artist_name": "artist a"}, "asset": {"source_type": "official", "storage_uri": "/workspace/acr-engine/data/songcentric_builder_smoke/song_alpha/artist_a/clip1.wav", "storage_scheme": "file", "checksum": "path:/workspace/acr-engine/data/songcentric_builder_smoke/song_alpha/artist_a/clip1.wav", "codec": "wav", "sample_rate": 16000, "channels": 1, "duration_ms": 8000}, "windows": [{"start_ms": 0, "end_ms": 5000}, {"start_ms": 2500, "end_ms": 7500}, {"start_ms": 3000, "end_ms": 8000}], "memberships": [{"set_type": "reference_set", "set_name": "phase1_hot_reference_v1", "member_type": "asset", "priority": 100}]}
+{"song": {"biz_key": "song_beta", "title": "song beta", "artist_name": "artist b"}, "asset": {"source_type": "official", "storage_uri": "/workspace/acr-engine/data/songcentric_builder_smoke/song_beta/artist_b/clip2.wav", "storage_scheme": "file", "checksum": "path:/workspace/acr-engine/data/songcentric_builder_smoke/song_beta/artist_b/clip2.wav", "codec": "wav", "sample_rate": 16000, "channels": 1, "duration_ms": 6000}, "windows": [{"start_ms": 0, "end_ms": 5000}, {"start_ms": 1000, "end_ms": 6000}], "memberships": [{"set_type": "reference_set", "set_name": "phase1_hot_reference_v1", "member_type": "asset", "priority": 100}]}

+{"song": {"biz_key": "song_alpha", "title": "song alpha", "artist_name": "artist a"}, "asset": {"source_type": "official", "storage_uri": "/workspace/acr-engine/data/songcentric_builder_smoke/song_alpha/artist_a/clip1.wav", "storage_scheme": "file", "checksum": "path:/workspace/acr-engine/data/songcentric_builder_smoke/song_alpha/artist_a/clip1.wav", "codec": "wav", "sample_rate": 16000, "channels": 1, "duration_ms": 8000}, "windows": [{"start_ms": 0, "end_ms": 5000, "features": [{"feature_type": "fingerprint", "model_name": "chromaprint_matcher", "model_version": "phase1_local", "feature_set_name": "chromaprint_matcher_5s", "fingerprint_value": "dc0c731425f360787f462da693ff4a50", "checksum": "chromaprint:dc0c731425f36078", "metadata_json": {"hash_count": 2643, "hash_sample": [[1842187, 11], [1842188, 11], [1842189, 11], [1842201, 11], [1842212, 11], [1842213, 11], [1842214, 11], [1842438, 11]]}}, {"feature_type": "embedding", "model_name": "local_wavehash_embed", "model_version": "v1", "feature_set_name": "wavehash_embed_5s", "feature_schema_ver": "v1", "embedding_dim": 8, "embedding_uri": "inline://593c7a661cc87444:0:5000", "vector_table_name": "audio_embedding_vector_8_placeholder", "checksum": "emb:593c7a661cc87444", "metadata_json": {"energy": 30555200, "rate": 16000, "channels": 1, "semantic_backend": "local_fallback", "runtime_missing": ["torch", "torchaudio", "transformers"]}}]}, {"start_ms": 2500, "end_ms": 7500, "features": [{"feature_type": "fingerprint", "model_name": "chromaprint_matcher", "model_version": "phase1_local", "feature_set_name": "chromaprint_matcher_5s", "fingerprint_value": "dc0c731425f360787f462da693ff4a50", "checksum": "chromaprint:dc0c731425f36078", "metadata_json": {"hash_count": 2643, "hash_sample": [[1842187, 11], [1842188, 11], [1842189, 11], [1842201, 11], [1842212, 11], [1842213, 11], [1842214, 11], [1842438, 11]]}}, {"feature_type": "embedding", "model_name": "local_wavehash_embed", "model_version": "v1", "feature_set_name": "wavehash_embed_5s", "feature_schema_ver": "v1", "embedding_dim": 8, "embedding_uri": "inline://593c7a661cc87444:2500:7500", "vector_table_name": "audio_embedding_vector_8_placeholder", "checksum": "emb:593c7a661cc87444", "metadata_json": {"energy": 30555200, "rate": 16000, "channels": 1, "semantic_backend": "local_fallback", "runtime_missing": ["torch", "torchaudio", "transformers"]}}]}, {"start_ms": 3000, "end_ms": 8000, "features": [{"feature_type": "fingerprint", "model_name": "chromaprint_matcher", "model_version": "phase1_local", "feature_set_name": "chromaprint_matcher_5s", "fingerprint_value": "dc0c731425f360787f462da693ff4a50", "checksum": "chromaprint:dc0c731425f36078", "metadata_json": {"hash_count": 2643, "hash_sample": [[1842187, 11], [1842188, 11], [1842189, 11], [1842201, 11], [1842212, 11], [1842213, 11], [1842214, 11], [1842438, 11]]}}, {"feature_type": "embedding", "model_name": "local_wavehash_embed", "model_version": "v1", "feature_set_name": "wavehash_embed_5s", "feature_schema_ver": "v1", "embedding_dim": 8, "embedding_uri": "inline://593c7a661cc87444:3000:8000", "vector_table_name": "audio_embedding_vector_8_placeholder", "checksum": "emb:593c7a661cc87444", "metadata_json": {"energy": 30555200, "rate": 16000, "channels": 1, "semantic_backend": "local_fallback", "runtime_missing": ["torch", "torchaudio", "transformers"]}}]}], "memberships": [{"set_type": "reference_set", "set_name": "phase1_hot_reference_v1", "member_type": "asset", "priority": 100}]}
+{"song": {"biz_key": "song_beta", "title": "song beta", "artist_name": "artist b"}, "asset": {"source_type": "official", "storage_uri": "/workspace/acr-engine/data/songcentric_builder_smoke/song_beta/artist_b/clip2.wav", "storage_scheme": "file", "checksum": "path:/workspace/acr-engine/data/songcentric_builder_smoke/song_beta/artist_b/clip2.wav", "codec": "wav", "sample_rate": 16000, "channels": 1, "duration_ms": 6000}, "windows": [{"start_ms": 0, "end_ms": 5000, "features": [{"feature_type": "fingerprint", "model_name": "chromaprint_matcher", "model_version": "phase1_local", "feature_set_name": "chromaprint_matcher_5s", "fingerprint_value": "d8fc2442b4ec3ce5ae180c5845cffccb", "checksum": "chromaprint:d8fc2442b4ec3ce5", "metadata_json": {"hash_count": 2202, "hash_sample": [[2763289, 23], [2763524, 23], [2763541, 23], [2763549, 23], [2763566, 23], [2763801, 23], [2764050, 23], [2764075, 23]]}}, {"feature_type": "embedding", "model_name": "local_wavehash_embed", "model_version": "v1", "feature_set_name": "wavehash_embed_5s", "feature_schema_ver": "v1", "embedding_dim": 8, "embedding_uri": "inline://4ed2ccfa55b10b88:0:5000", "vector_table_name": "audio_embedding_vector_8_placeholder", "checksum": "emb:4ed2ccfa55b10b88", "metadata_json": {"energy": 30555680, "rate": 16000, "channels": 1, "semantic_backend": "local_fallback", "runtime_missing": ["torch", "torchaudio", "transformers"]}}]}, {"start_ms": 1000, "end_ms": 6000, "features": [{"feature_type": "fingerprint", "model_name": "chromaprint_matcher", "model_version": "phase1_local", "feature_set_name": "chromaprint_matcher_5s", "fingerprint_value": "d8fc2442b4ec3ce5ae180c5845cffccb", "checksum": "chromaprint:d8fc2442b4ec3ce5", "metadata_json": {"hash_count": 2202, "hash_sample": [[2763289, 23], [2763524, 23], [2763541, 23], [2763549, 23], [2763566, 23], [2763801, 23], [2764050, 23], [2764075, 23]]}}, {"feature_type": "embedding", "model_name": "local_wavehash_embed", "model_version": "v1", "feature_set_name": "wavehash_embed_5s", "feature_schema_ver": "v1", "embedding_dim": 8, "embedding_uri": "inline://4ed2ccfa55b10b88:1000:6000", "vector_table_name": "audio_embedding_vector_8_placeholder", "checksum": "emb:4ed2ccfa55b10b88", "metadata_json": {"energy": 30555680, "rate": 16000, "channels": 1, "semantic_backend": "local_fallback", "runtime_missing": ["torch", "torchaudio", "transformers"]}}]}], "memberships": [{"set_type": "reference_set", "set_name": "phase1_hot_reference_v1", "member_type": "asset", "priority": 100}]}

+{
+  "schema": "acr_songcentric_test",
+  "input_root": "acr-engine/data/songcentric_builder_smoke",
+  "steps": [
+    {
+      "name": "build_manifest",
+      "command": "/usr/local/miniconda3/bin/python acr-engine/scripts/build_songcentric_manifest_from_directory.py --input-root acr-engine/data/songcentric_builder_smoke --output acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest.jsonl --report-output acr-engine/data/pgvector_eval/music20/songcentric_pipeline_build_report.json",
+      "returncode": 0
+    },
+    {
+      "name": "enrich_features",
+      "command": "/usr/local/miniconda3/bin/python acr-engine/scripts/enrich_songcentric_manifest_with_local_features.py --input-manifest acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest.jsonl --output-manifest acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest_with_features.jsonl --report-output acr-engine/data/pgvector_eval/music20/songcentric_pipeline_enrich_report.json",
+      "returncode": 0
+    },
+    {
+      "name": "import_manifest",
+      "command": "/usr/local/miniconda3/bin/python acr-engine/scripts/import_songcentric_manifest_live.py --dsn postgres://d2:d2pass@127.0.0.1:5432/d2 --schema acr_songcentric_test --manifest acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest_with_features.jsonl --output acr-engine/data/pgvector_eval/music20/songcentric_pipeline_import_report.json",
+      "returncode": 0
+    }
+  ],
+  "build_summary": {
+    "input_root": "/workspace/acr-engine/data/songcentric_builder_smoke",
+    "output": "/workspace/acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest.jsonl",
+    "song_count": 2,
+    "asset_count": 2,
+    "window_count": 5,
+    "window_ms": 5000,
+    "stride_ms": 2500,
+    "set_name": "phase1_hot_reference_v1"
+  },
+  "enrich_summary": {
+    "wav_windows_seen": 5,
+    "features_added": 10,
+    "matcher_fingerprint_count": 5,
+    "fallback_fingerprint_count": 0,
+    "semantic_runtime_available": false,
+    "semantic_runtime_missing": [
+      "torch",
+      "torchaudio",
+      "transformers"
+    ],
+    "semantic_runtime_ready_count": 0,
+    "semantic_fallback_count": 5
+  },
+  "import_counts": {
+    "media_entity": 9,
+    "audio_object": 22,
+    "feature_fact": 24,
+    "set_membership": 9
+  },
+  "feature_lineage_sample": {
+    "feature_type": "fingerprint",
+    "model_name": "chromaprint_matcher",
+    "model_version": "phase1_local",
+    "feature_set_name": "chromaprint_matcher_5s",
+    "window_id": 22,
+    "song_id": 9,
+    "title": "song beta"
+  }
+}
\ No newline at end of file

+#!/usr/bin/env /usr/local/miniconda3/bin/python
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+PYTHON = '/usr/local/miniconda3/bin/python'
+
+
+def run_step(name: str, cmd: list[str]) -> dict:
+    proc = subprocess.run(cmd, cwd=str(ROOT.parent), capture_output=True, text=True)
+    return {
+        'name': name,
+        'command': ' '.join(cmd),
+        'returncode': proc.returncode,
+        'stdout': proc.stdout,
+        'stderr': proc.stderr,
+    }
+
+
+def load_json(path: Path) -> dict:
+    return json.loads(path.read_text())
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--dsn', required=True)
+    parser.add_argument('--schema', default='acr_songcentric_test')
+    parser.add_argument('--input-root', default='acr-engine/data/songcentric_builder_smoke')
+    parser.add_argument('--output-dir', default='acr-engine/data/pgvector_eval/music20')
+    args = parser.parse_args()
+
+    out_dir = (ROOT.parent / args.output_dir).resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    manifest = out_dir / 'songcentric_pipeline_manifest.jsonl'
+    build_report = out_dir / 'songcentric_pipeline_build_report.json'
+    enriched_manifest = out_dir / 'songcentric_pipeline_manifest_with_features.jsonl'
+    enrich_report = out_dir / 'songcentric_pipeline_enrich_report.json'
+    import_report = out_dir / 'songcentric_pipeline_import_report.json'
+
+    steps = []
+    steps.append(run_step('build_manifest', [
+        PYTHON, 'acr-engine/scripts/build_songcentric_manifest_from_directory.py',
+        '--input-root', args.input_root,
+        '--output', str(manifest.relative_to(ROOT.parent)),
+        '--report-output', str(build_report.relative_to(ROOT.parent)),
+    ]))
+    if steps[-1]['returncode'] != 0:
+        raise SystemExit(json.dumps({'failed_step': steps[-1]}, ensure_ascii=False, indent=2))
+
+    steps.append(run_step('enrich_features', [
+        PYTHON, 'acr-engine/scripts/enrich_songcentric_manifest_with_local_features.py',
+        '--input-manifest', str(manifest.relative_to(ROOT.parent)),
+        '--output-manifest', str(enriched_manifest.relative_to(ROOT.parent)),
+        '--report-output', str(enrich_report.relative_to(ROOT.parent)),
+    ]))
+    if steps[-1]['returncode'] != 0:
+        raise SystemExit(json.dumps({'failed_step': steps[-1]}, ensure_ascii=False, indent=2))
+
+    steps.append(run_step('import_manifest', [
+        PYTHON, 'acr-engine/scripts/import_songcentric_manifest_live.py',
+        '--dsn', args.dsn,
+        '--schema', args.schema,
+        '--manifest', str(enriched_manifest.relative_to(ROOT.parent)),
+        '--output', str(import_report.relative_to(ROOT.parent)),
+    ]))
+    if steps[-1]['returncode'] != 0:
+        raise SystemExit(json.dumps({'failed_step': steps[-1]}, ensure_ascii=False, indent=2))
+
+    build = load_json(build_report)
+    enrich = load_json(enrich_report)
+    imp = load_json(import_report)
+
+    summary = {
+        'schema': args.schema,
+        'input_root': args.input_root,
+        'steps': [{k: v for k, v in s.items() if k in ('name', 'command', 'returncode')} for s in steps],
+        'build_summary': build,
+        'enrich_summary': {
+            'wav_windows_seen': enrich['wav_windows_seen'],
+            'features_added': enrich['features_added'],
+            'matcher_fingerprint_count': enrich['matcher_fingerprint_count'],
+            'fallback_fingerprint_count': enrich['fallback_fingerprint_count'],
+            'semantic_runtime_available': enrich['semantic_runtime_available'],
+            'semantic_runtime_missing': enrich['semantic_runtime_missing'],
+            'semantic_runtime_ready_count': enrich['semantic_runtime_ready_count'],
+            'semantic_fallback_count': enrich['semantic_fallback_count'],
+        },
+        'import_counts': imp['counts'],
+        'feature_lineage_sample': imp.get('feature_lineage_sample'),
+    }
+    report_path = out_dir / 'songcentric_pipeline_runner_report.json'
+    report_path.write_text(json.dumps(summary, ensure_ascii=False, indent=2))
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

 ## 2026-06-04
 ## 2026-06-04
 
 
+- 新增 `acr-engine/scripts/run_songcentric_directory_pipeline_live.py`，把“真实目录 -> manifest -> 特征补全 -> live PostgreSQL 导入”收敛为一条可重复执行的 runner，并输出 exact/semantic backend 选择与导入计数摘要。
+
 - 升级 `enrich_songcentric_manifest_with_local_features.py` 为 runtime-aware 语义适配器选择：当前 host 上因缺少 `torch/torchaudio/transformers`，semantic lane 明确写入 `local_wavehash_embed` fallback，并把缺失依赖固化到 report/metadata 中。
 - 升级 `enrich_songcentric_manifest_with_local_features.py` 为 runtime-aware 语义适配器选择：当前 host 上因缺少 `torch/torchaudio/transformers`，semantic lane 明确写入 `local_wavehash_embed` fallback，并把缺失依赖固化到 report/metadata 中。
 
 
 - 升级 `enrich_songcentric_manifest_with_local_features.py`：目录链中的 fingerprint 现优先复用仓库内 `ChromaprintMatcher`，并在 live PostgreSQL 上验证 5 个 wav windows 全部命中 matcher 路径、`fallback_fingerprint_count=0`。
 - 升级 `enrich_songcentric_manifest_with_local_features.py`：目录链中的 fingerprint 现优先复用仓库内 `ChromaprintMatcher`，并在 live PostgreSQL 上验证 5 个 wav windows 全部命中 matcher 路径、`fallback_fingerprint_count=0`。

@@ -326,6 +326,25 @@ flowchart TD
 
 
 这说明当前 host 上 semantic lane 还未接真实模型，但链路已经具备明确的运行时分流与可审计证据。
 这说明当前 host 上 semantic lane 还未接真实模型，但链路已经具备明确的运行时分流与可审计证据。
 
 
+
+### 4.10 一键 song-centric 目录链 runner
+
+```mermaid
+flowchart TD
+    A[run_songcentric_directory_pipeline_live.py] --> B[build manifest]
+    B --> C[enrich features]
+    C --> D[import manifest]
+    D --> E[runner report]
+```
+
+当前 runner：[`acr-engine/scripts/run_songcentric_directory_pipeline_live.py`](../acr-engine/scripts/run_songcentric_directory_pipeline_live.py)
+
+它会在一条命令里输出：
+- 目录扫描结果
+- exact lane 是否走 `ChromaprintMatcher`
+- semantic lane 是否 runtime-ready
+- live PostgreSQL 导入后的计数与 lineage 样例
+
 ---
 ---
 
 
 ## 5. 最常用 SQL 样例
 ## 5. 最常用 SQL 样例

@@ -153,6 +153,7 @@ model_registry -> feature_set_registry -> audio_embedding / audio_fingerprint ->
 - `acr-engine/scripts/run_phase1_worker_contract_smoke_live.py`
 - `acr-engine/scripts/run_phase1_worker_contract_smoke_live.py`
 - `acr-engine/scripts/run_embedding_vector_table_negative_matrix_live.py`
 - `acr-engine/scripts/run_embedding_vector_table_negative_matrix_live.py`
 - `acr-engine/scripts/validate_audio_embedding_asset_upsert_live.py`
 - `acr-engine/scripts/validate_audio_embedding_asset_upsert_live.py`
+- `acr-engine/scripts/run_songcentric_directory_pipeline_live.py`
 
 
 ---
 ---