docs(17-I): README + 4 translations — Phase 17 plugin surface

English canonical README plus all 4 translations (zh-CN, es, ja, ru)
gain a "AST chunker + HyDE retrieval (opt-in plugins; v0.3.0a7+)"
section documenting:

  - tree_sitter_code chunker plugin (opt-in via [ast-chunker] extra)
  - tuned_hybrid_hyde retrieval plugin (opt-in; Ollama warm-pool)
  - chunk-level recall metric + payload.chunk_id (bench-only)
  - Ollama warm-pool doctor panel (read-only)
  - ADR-0002 §9 deep-link with the [delta, delta] CI caveat

Honest disclosure: HyDE meets Track B recall floor but violates
D-LAT-01 hard ceiling on 4/5 cells (max p95 6069 ms) and produces a
−0.25 MRR regression on code_fact — opt-in only in 0.3.x; default-flip
gated on v0.4.

CLI surface row updated: `supamem eval --suite coderag` now lists
`--reingest-coderag` (v0.3.0a7+) and the new `[ast-chunker]` optional
extra.

Per AGENTS.md README Translations contract: code blocks, CLI commands,
file paths, plugin identifiers stay canonical English in all 4
translations; only prose, headings, and explanatory text are
translated. synced-with SHA bump follows in a separate commit per
AGENTS.md §2 one-liner.

Plan: 17-I (Task 2 step 1 of 2).

Author: dzmitrys-dev

README.es.md

@@ -681,6 +681,50 @@ en
 [ADR-0002 §8](docs/adr/0002-coderag-eval-philosophy.md#8-mem0-peer-comparison-d-peer-04-live-phase-16-e-head-to-head).
 Instalar con `pip install supamem[peers-mem0]`.
 
+**Chunker AST + recuperación HyDE (plugins opt-in; v0.3.0a7+).** Phase 17
+incluye dos plugins **opt-in** para el stack de recuperación, más una
+métrica de recall a nivel de chunk y ADR-0002 §9 — la comparación de
+uplift (paired-bootstrap) contra la baseline-3 de Phase 16. **Los
+valores por defecto se mantienen sin cambios en la línea 0.3.x; el
+cambio de default está bloqueado hasta v0.4 según D-LAT-01.**
+
+- Plugin chunker `tree_sitter_code` — registrado en `supamem.chunker`
+  junto a `markdown_header` y `transcript`. Opt-in vía
+  `pip install supamem[ast-chunker]`. Solo Python en v1. Los errores de
+  parse hacen fallback a `chunk_markdown` con un aviso en `err_console`.
+  El uplift de recall es modesto; se mantiene bajo el techo de latencia
+  D-LAT-01.
+- Plugin de recuperación `tuned_hybrid_hyde` — registrado en
+  `supamem.retrieval`. Composición sobre herencia: envuelve
+  `TunedHybridBackend` (que queda byte-idéntico). Reescritor Ollama
+  localhost-only (`/api/generate`, `keep_alive=-1` para retención del
+  warm-pool, timeout 600 ms + 1 reintento, fallback a la query original
+  ante cualquier fallo). Veredicto: cumple exactamente el objetivo
+  Track B `decision_rationale.supamem_only.recall_at_1 ≥ 0.5`, pero
+  **viola el techo duro p95 de 5000 ms en 4 de 5 celdas (máximo
+  6069 ms)** y produce una regresión de −0.25 en MRR sobre `code_fact`.
+  Solo opt-in; sin ruta de cambio de default; seguimiento Phase 18 =
+  gating por axis.
+- Métrica de recall a nivel de chunk + `payload.chunk_id` bench-only —
+  claves `recall_at_*_chunk` como hermanas de las claves a nivel de
+  documento; el nuevo `_build_run_chunk` NO deduplica doc_ids
+  duplicados (el `_build_run` de Phase 16 colapsaba chunks del mismo
+  fichero a una sola fila, ocultando la señal). La ruta a nivel de
+  documento queda byte-idéntica — el test de floors de Phase 16 sigue
+  verde.
+- Panel `doctor` de warm-pool de Ollama — se renderiza solo cuando
+  `retrieval.backend = "tuned_hybrid_hyde"`. Sondea `/api/ps` con
+  timeout de 1s. Solo lectura — NUNCA lanza excepción, NUNCA cambia el
+  exit code (D-DOCTOR-04).
+
+Ver [ADR-0002 §9](docs/adr/0002-coderag-eval-philosophy.md#9-phase-17-uplift-comparison)
+para los deltas paired-bootstrap (default vs ast_on / hyde_on /
+ast_plus_hyde). Salvedad: los CI de §9 colapsan a `[delta, delta]`
+porque el envelope LIVE v1 registra solo medias por celda — los valores
+de delta son exactos, pero los límites de CI NO reflejan la
+incertidumbre a nivel de query (un bump futuro del esquema de envelope
+desbloqueará CIs reales).
+
 **LongMemEval degradado.** Desde v0.3.0a5 LongMemEval_S completo es
 on-demand-only; el fixture de 5 preguntas `longmemeval_scoped_smoke`
 sigue en PR-CI. Diagnóstico: LongMemEval mide memoria de largo plazo

README.ja.md

@@ -667,6 +667,48 @@ axis × カラム × メトリクスごとに paired-bootstrap delta + 95% CI 
 [ADR-0002 §8](docs/adr/0002-coderag-eval-philosophy.md#8-mem0-peer-comparison-d-peer-04-live-phase-16-e-head-to-head)
 を参照。`pip install supamem[peers-mem0]` でインストール。
 
+**AST チャンカー + HyDE 検索(オプトインプラグイン; v0.3.0a7+)。**
+Phase 17 では **オプトイン** の検索スタックプラグイン 2 種に加え、
+チャンクレベル recall メトリクス、Phase 16 baseline-3 に対する
+ペア・ブートストラップ・アップリフト比較である ADR-0002 §9 を提供。
+**0.3.x 系のデフォルトは据え置き。デフォルト切替は D-LAT-01 に従い
+v0.4 にゲート。**
+
+- `tree_sitter_code` チャンカープラグイン — `supamem.chunker`
+  エントリポイント配下に `markdown_header` / `transcript` と並列に
+  登録。`pip install supamem[ast-chunker]` でオプトイン。v1 は Python
+  のみ。パース失敗時は `chunk_markdown` にフォールバックし、
+  `err_console` に警告を出力。recall リフトは控えめだが、D-LAT-01
+  レイテンシ上限内に収まる。
+- `tuned_hybrid_hyde` 検索プラグイン — `supamem.retrieval` に登録。
+  継承ではなくコンポジションで `TunedHybridBackend` をラップ(後者は
+  バイト一致を維持)。localhost 限定 Ollama リライター
+  (`/api/generate`、`keep_alive=-1` のウォームプール保持、600 ms
+  タイムアウト + 1 回リトライ、失敗時は元クエリへフォールバック)。
+  判定:Track B の `decision_rationale.supamem_only.recall_at_1 ≥ 0.5`
+  目標をぎりぎり達成するが、**5 セル中 4 セルで 5000 ms p95 ハード
+  上限を違反(最大 6069 ms)** し、`code_fact` で −0.25 の MRR
+  リグレッションを発生させる。オプトインのみ;デフォルト切替の
+  経路なし。Phase 18 のフォローアップ = axis 単位のセレクティビティ
+  ゲーティング。
+- チャンクレベル recall メトリクス + bench 専用 `payload.chunk_id` —
+  doc レベルキーに `recall_at_*_chunk` を兄弟キーとして追加。新規の
+  `_build_run_chunk` は重複 doc_id を **重複排除しない**(Phase 16 の
+  `_build_run` は同一ファイルのチャンクを 1 行に畳み込み、シグナルを
+  覆い隠していた)。doc レベル経路はバイト一致を維持 —— Phase 16
+  floors テストは引き続きグリーン。
+- Ollama ウォームプール doctor パネル —
+  `retrieval.backend = "tuned_hybrid_hyde"` が設定されているときのみ
+  表示。1 秒タイムアウトで `/api/ps` を探査。読み取り専用 —
+  例外を投げず、exit code を反転させない(D-DOCTOR-04)。
+
+ペア・ブートストラップ差分(default vs ast_on / hyde_on /
+ast_plus_hyde)は [ADR-0002 §9](docs/adr/0002-coderag-eval-philosophy.md#9-phase-17-uplift-comparison)
+を参照。注意事項:§9 の CI は `[delta, delta]` に収束する。v1 LIVE
+envelope スキーマがセルごとの平均しか保持しないため — delta 値は
+正確だが、CI の上下限はクエリレベルの不確実性を反映しない(将来の
+envelope スキーマのバンプで真の CI を解放可能)。
+
 **LongMemEval の降格。** v0.3.0a5 以降、完全な LongMemEval_S は
 オンデマンドのみとなり、5 問の `longmemeval_scoped_smoke` フィクスチャは
 PR-CI に残ります。診断:LongMemEval は会話的長期記憶を測りますが、

README.md

@@ -333,7 +333,7 @@ discover this flow naturally.
 | `supamem stats` | Welford schema-v2 usage counters from `.supamem/state/` |
 | `supamem live` | 👀 Live dashboard tailing the audit JSONL — pipe-safe (plain JSONL when not a TTY); handles rotation, resize, Ctrl-C |
 | `supamem migrate` | Brownfield migration from a pre-existing `dev_memory` collection |
-| `supamem eval` | Run the bench harness. `--suite goldens` (default, bundled 33-query regression corpus), `--suite longmemeval_s` (lazy-fetched LongMemEval_S, ~3 GB on first run; **DEMOTED to on-demand-only in v0.3.0a5** per [ADR-0002](docs/adr/0002-coderag-eval-philosophy.md) — no longer the Phase 13 ship gate), `--suite longmemeval_scoped_smoke` (bundled, ≤5 questions, no lazy-fetch — stays on PR-CI), or **`supamem eval --suite coderag [--full] [--out PATH] [--peer mem0]`** (v0.3.0a5+, code-shaped retrieval suite — new Phase 13 ship gate). Outputs an MTEB-style JSON envelope to `~/.supamem/eval/<utc-iso>.json`. Default judge is heuristic (offline); pass `--judge ollama:<model>` for a localhost Ollama judge — SaaS endpoints are refused (D-07). Optional extras: `pip install supamem[eval]` for the RAGAS triad + `pytrec_eval`; `pip install supamem[peers-mem0]` for the mem0 peer adapter (v0.3.0a5+). Legacy `--regress` mode preserved. |
+| `supamem eval` | Run the bench harness. `--suite goldens` (default, bundled 33-query regression corpus), `--suite longmemeval_s` (lazy-fetched LongMemEval_S, ~3 GB on first run; **DEMOTED to on-demand-only in v0.3.0a5** per [ADR-0002](docs/adr/0002-coderag-eval-philosophy.md) — no longer the Phase 13 ship gate), `--suite longmemeval_scoped_smoke` (bundled, ≤5 questions, no lazy-fetch — stays on PR-CI), or **`supamem eval --suite coderag [--full] [--out PATH] [--peer mem0] [--reingest-coderag]`** (v0.3.0a5+, code-shaped retrieval suite — new Phase 13 ship gate; v0.3.0a7+ `--reingest-coderag` drops + rebuilds the bench collection via the `supamem.chunker` entry-point keyed on `cfg.chunker` — required to exercise `tree_sitter_code`). Outputs an MTEB-style JSON envelope to `~/.supamem/eval/<utc-iso>.json`. Default judge is heuristic (offline); pass `--judge ollama:<model>` for a localhost Ollama judge — SaaS endpoints are refused (D-07). Optional extras: `pip install supamem[eval]` for the RAGAS triad + `pytrec_eval`; `pip install supamem[peers-mem0]` for the mem0 peer adapter (v0.3.0a5+); `pip install supamem[ast-chunker]` for the `tree_sitter_code` Python AST chunker plugin (v0.3.0a7+; opt-in). Legacy `--regress` mode preserved. |
 | `supamem uninstall --client <name>` | Reverse `supamem install` cleanly. Strips supamem from BOTH project and user scopes. |
 | `supamem unpatch-agents` | 🔄 Reverse subagent reachability patches (v0.2.5+). Restores agent files to their pre-patch form per the manifest at `~/.cache/supamem/agent_patches.json`. Skips files you've edited since with a per-file warning. Run BEFORE `pip uninstall supamem` for a clean uninstall. |
 
@@ -748,6 +748,44 @@ delta = peer wins) at
 [ADR-0002 §8](docs/adr/0002-coderag-eval-philosophy.md#8-mem0-peer-comparison-d-peer-04-live-phase-16-e-head-to-head).
 Install with `pip install supamem[peers-mem0]`.
 
+**AST chunker + HyDE retrieval (opt-in plugins; v0.3.0a7+).** Phase 17
+ships two opt-in retrieval-stack plugins plus a chunk-level recall metric
+and ADR-0002 §9 — the paired-bootstrap uplift comparison vs the Phase 16
+baseline-3. **Defaults are unchanged in the 0.3.x line; default-flip is
+gated on v0.4 per D-LAT-01.**
+
+- `tree_sitter_code` chunker plugin — registered under `supamem.chunker`
+  alongside `markdown_header` and `transcript`. Opt-in via
+  `pip install supamem[ast-chunker]`. Python only at v1. Parse errors
+  fall back to `chunk_markdown` with an `err_console` warning. Recall
+  lift is modest; stays inside the D-LAT-01 latency ceiling.
+- `tuned_hybrid_hyde` retrieval plugin — registered under
+  `supamem.retrieval`. Composition-over-inheritance wrap of
+  `TunedHybridBackend` (kept byte-identical). Localhost-only Ollama
+  query rewriter (`/api/generate`, `keep_alive=-1` warm-pool retention,
+  600 ms timeout + 1 retry, falls back to original query on failure).
+  Verdict: meets the Track B `decision_rationale.supamem_only.recall_at_1`
+  ≥ 0.5 goal exactly but **violates the 5000 ms p95 hard ceiling on 4/5
+  cells (max 6069 ms)** and produces a −0.25 MRR regression on
+  `code_fact`. Opt-in only; no default-flip path; Phase 18 follow-up =
+  selectivity gating by axis.
+- Chunk-level recall metric + bench-only `payload.chunk_id` —
+  `recall_at_*_chunk` siblings beside doc-level keys; new
+  `_build_run_chunk` does NOT dedup duplicate doc_ids (Phase 16's
+  `_build_run` collapsed chunks of the same file to one row, hiding the
+  signal). Doc-level path stays byte-identical — Phase 16 floors test
+  still green.
+- Ollama warm-pool doctor panel — fires only when
+  `retrieval.backend = "tuned_hybrid_hyde"`; probes `/api/ps` with 1s
+  timeout. Read-only — NEVER raises, NEVER flips exit code (D-DOCTOR-04).
+
+See [ADR-0002 §9](docs/adr/0002-coderag-eval-philosophy.md#9-phase-17-uplift-comparison)
+for the paired-bootstrap deltas (default vs ast_on / hyde_on /
+ast_plus_hyde). Caveat: §9 CIs collapse to `[delta, delta]` because v1
+LIVE envelope schema records per-cell means only — delta values are
+exact, CI bounds do NOT reflect query-level uncertainty (future
+envelope-schema bump unlocks real CIs).
+
 **LongMemEval demoted.** Full LongMemEval_S becomes on-demand-only as
 of v0.3.0a5; the existing 5-question `longmemeval_scoped_smoke`
 fixture stays on PR-CI. The diagnosis: LongMemEval measures

README.ru.md

@@ -682,6 +682,49 @@ axis × колонка × метрика (соглашение знака `mem0_
 [ADR-0002 §8](docs/adr/0002-coderag-eval-philosophy.md#8-mem0-peer-comparison-d-peer-04-live-phase-16-e-head-to-head).
 Установка: `pip install supamem[peers-mem0]`.
 
+**AST-чанкер + HyDE-ретривал (опциональные плагины; v0.3.0a7+).**
+Phase 17 поставляет два **opt-in** плагина для retrieval-стека плюс
+chunk-уровневую метрику recall и ADR-0002 §9 — paired-bootstrap
+сравнение прироста относительно Phase 16 baseline-3. **Дефолты в
+линии 0.3.x не меняются; смена дефолта зашлюзована до v0.4 согласно
+D-LAT-01.**
+
+- Плагин-чанкер `tree_sitter_code` — зарегистрирован в группе
+  `supamem.chunker` рядом с `markdown_header` и `transcript`. Opt-in
+  через `pip install supamem[ast-chunker]`. В v1 только Python.
+  Ошибки парсинга приводят к fallback на `chunk_markdown` с
+  предупреждением в `err_console`. Прирост recall скромный; остаётся
+  внутри потолка D-LAT-01 по латентности.
+- Плагин-ретривал `tuned_hybrid_hyde` — зарегистрирован в
+  `supamem.retrieval`. Композиция вместо наследования: оборачивает
+  `TunedHybridBackend` (тот остаётся байт-в-байт идентичным).
+  Localhost-only Ollama-переписыватель запросов (`/api/generate`,
+  `keep_alive=-1` для удержания warm-pool, таймаут 600 мс + 1 повтор,
+  fallback на исходный запрос при любой ошибке). Вердикт: ровно
+  достигает цель Track B `decision_rationale.supamem_only.recall_at_1 ≥ 0.5`,
+  но **нарушает жёсткий потолок p95 5000 мс на 4 из 5 ячеек
+  (максимум 6069 мс)** и даёт регрессию MRR −0.25 по `code_fact`. Только
+  opt-in; пути смены дефолта нет; продолжение в Phase 18 = селективное
+  гейтирование по axis.
+- Chunk-уровневая метрика recall + bench-only `payload.chunk_id` —
+  ключи `recall_at_*_chunk` как сиблинги doc-уровневых; новый
+  `_build_run_chunk` НЕ дедуплицирует повторные doc_id (в Phase 16
+  `_build_run` сжимал чанки одного файла в одну строку, скрывая сам
+  сигнал). Doc-уровневый путь остаётся байт-идентичным — тест floors
+  Phase 16 по-прежнему зелёный.
+- Doctor-панель Ollama warm-pool — рендерится только при
+  `retrieval.backend = "tuned_hybrid_hyde"`; пингует `/api/ps` с
+  таймаутом 1с. Read-only — НИКОГДА не бросает исключений, НИКОГДА не
+  меняет exit code (D-DOCTOR-04).
+
+См. [ADR-0002 §9](docs/adr/0002-coderag-eval-philosophy.md#9-phase-17-uplift-comparison)
+для paired-bootstrap-дельт (default vs ast_on / hyde_on /
+ast_plus_hyde). Оговорка: CI в §9 коллапсируют в `[delta, delta]`,
+потому что v1 LIVE envelope хранит только средние по ячейкам — сами
+значения delta точные, но границы CI НЕ отражают per-query
+неопределённость (будущий апгрейд схемы envelope разблокирует
+настоящие CI).
+
 **LongMemEval демотирован.** С v0.3.0a5 полный LongMemEval_S — только
 on-demand; фикстура `longmemeval_scoped_smoke` из 5 вопросов остаётся в
 PR-CI. Диагноз: LongMemEval измеряет диалоговую долговременную память,

README.zh-CN.md

@@ -632,6 +632,39 @@ paired-bootstrap delta + 95% CI(符号约定 `mem0_vs_supamem` —— 正 delta
 [ADR-0002 §8](docs/adr/0002-coderag-eval-philosophy.md#8-mem0-peer-comparison-d-peer-04-live-phase-16-e-head-to-head)。
 通过 `pip install supamem[peers-mem0]` 安装。
 
+**AST 分块器 + HyDE 检索(可选插件;v0.3.0a7+)。** Phase 17 推出两个
+**可选启用**的检索栈插件,外加 chunk 级 recall 指标和 ADR-0002 §9 ——
+对比 Phase 16 baseline-3 的配对自举(paired-bootstrap)上升量。
+**0.3.x 系列默认值保持不变;按 D-LAT-01,默认切换被推迟到 v0.4。**
+
+- `tree_sitter_code` 分块器插件 —— 在 `supamem.chunker` 入口下与
+  `markdown_header`、`transcript` 并列注册。通过
+  `pip install supamem[ast-chunker]` 启用。v1 仅支持 Python。解析失败时
+  回退到 `chunk_markdown` 并向 `err_console` 输出告警。recall 提升
+  有限,但保持在 D-LAT-01 延迟上限内。
+- `tuned_hybrid_hyde` 检索插件 —— 在 `supamem.retrieval` 下注册。
+  采用组合优于继承的方式包装 `TunedHybridBackend`(后者保持字节一致)。
+  本地 Ollama 重写器(`/api/generate`,`keep_alive=-1` 暖池保留,
+  600 ms 超时 + 1 次重试,失败时回退到原始查询)。结论:正好达到
+  Track B `decision_rationale.supamem_only.recall_at_1 ≥ 0.5` 目标,
+  但 **在 5/4 个单元上违反 5000 ms p95 硬上限(最高 6069 ms)**,并在
+  `code_fact` 上产生 −0.25 的 MRR 回退。仅可选;不存在默认切换路径;
+  Phase 18 后续工作 = 按 axis 进行选择性门控。
+- Chunk 级 recall 指标 + bench 专用 `payload.chunk_id` —— 在 doc 级
+  键旁新增 `recall_at_*_chunk`;新的 `_build_run_chunk` 不再对相同
+  doc_id 去重(Phase 16 的 `_build_run` 把同一文件的多个 chunk 折叠
+  成单行,把信号本身遮蔽了)。doc 级路径保持字节一致 —— Phase 16
+  floors 测试依旧通过。
+- Ollama 暖池 doctor 面板 —— 仅当
+  `retrieval.backend = "tuned_hybrid_hyde"` 时显示;以 1s 超时探测
+  `/api/ps`。只读 —— 绝不抛异常、绝不改变退出码(D-DOCTOR-04)。
+
+详细的配对自举差值(default vs ast_on / hyde_on / ast_plus_hyde)
+参见 [ADR-0002 §9](docs/adr/0002-coderag-eval-philosophy.md#9-phase-17-uplift-comparison)。
+注意事项:§9 的 CI 收敛为 `[delta, delta]`,因为 v1 LIVE envelope 仅
+记录单元均值 —— delta 数值精确,但 CI 边界不反映 query 级别的不确定性
+(未来的 envelope schema 升级将解锁真正的 CI)。
+
 **LongMemEval 降级。** 自 v0.3.0a5 起,完整 LongMemEval_S 仅按需运行;
 原有 5 题 `longmemeval_scoped_smoke` 仍留在 PR-CI。诊断:LongMemEval
 衡量的是对话型长期记忆,而 supamem 索引的是 AI 编码 agent 用到的代码块