docs(09-06): translate Phase 9 README section to zh-CN/es/ja/ru + bump synced-with SHA

dzmitrys-dev · claude · dzmitrys-dev · commit d9a2a497b77d · 2026-05-03T00:58:52.000+03:00
- Add ⏳ feature-table row + full "Per-source temporal validity" section to all 4 translations, after the Phase 8 reranker section. - Code blocks, config keys, file paths, badges, and the worked-decay table cells stay in canonical English form (per AGENTS.md "README Translations" rule); only prose, headings, and explanatory text are translated. - Bump synced-with SHA marker on line 2 of each translation: f96d0a1 → dcd3185 (Task 1 commit). - AI-assistance disclosure on line 5 of each translation preserved. - Language switcher line 1 unchanged across all 5 files. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/README.es.md b/README.es.md
@@ -1,6 +1,6 @@
 **Idiomas:** [English](README.md) · [简体中文](README.zh-CN.md) · [Español](README.es.md) · [日本語](README.ja.md) · [Русский](README.ru.md)
 
-<!-- synced-with: README.md @ f96d0a1 -->
+<!-- synced-with: README.md @ dcd3185 -->
 
 > Esta traducción fue generada con asistencia de IA. Las correcciones de hablantes nativos son bienvenidas vía PR.
 
@@ -165,6 +165,7 @@ El **banner SessionStart** (v0.1.4+) también lanza una línea de estado en tu c
 |---|---|
 | 🔍 **Retrieval híbrido** | Fusión sparse (BM25) + dense (MiniLM) afinada, schema fijo D-25 |
 | 🎯 **Reranker consciente del código** | Cross-encoder `mxbai-rerank-base-v2` (Apache-2.0) re-puntúa los candidatos de `tuned_hybrid` por defecto. Desactívalo con `retrieval.reranker = "off"` para volver al comportamiento previo a v0.2.4a1. (Phase 8, RERANK-01..04) |
+| ⏳ **Validez temporal por fuente** | Cada chunk lleva `valid_from`/`valid_to`; reindexar un archivo modificado supersede atómicamente los chunks previos y el filtro de retrieval excluye los puntos superados en todos los backends. Decay de recencia opcional solo para transcripciones (apagado por defecto). Auto-GC tras `retention_days = 90` (`0` = conservar siempre / colecciones de auditoría). (Phase 9, TEMP-01..03) |
 | 📚 **Chunker Markdown** | Consciente de headers, chunks de 200-token con tope suave de 250-token (T-1) |
 | 🤖 **Servidor MCP** | Transportes `stdio` (default) y `http`, SDK oficial `mcp` |
 | 🪝 **Hooks multi-cliente** | session-start de Claude Code, session-start de OpenCode, MDC de Cursor |
@@ -480,6 +481,85 @@ través del pipeline de fetch de install/init/repair.
 
 ---
 
+## ⏳ Validez temporal por fuente (v0.3.0a1+)
+
+Cada chunk indexado lleva un campo binario `valid_to`:
+
+- `valid_to = null` → vigente
+- `valid_to ≤ now()` → superado (filtrado fuera de toda búsqueda)
+
+Cuando un archivo cambia y lo reindexas, el indexador, atómicamente:
+
+1. Hace scroll de todos los chunks existentes para esa ruta de archivo.
+2. Aplica `set_payload(valid_to = now())` a cada uno (cierra la ventana de validez previa).
+3. Hace upsert de los nuevos chunks bajo UUIDs derivados de un hash de contenido,
+   con `valid_to = null`.
+
+Los chunks viejos y nuevos coexisten en Qdrant; solo los nuevos se devuelven en retrieval
+hasta que el barrido de auto-GC borra los viejos pasados de `retention_days`. El filtro
+de retrieval se construye en un único sitio y lo heredan todos los backends
+(`tuned_hybrid` ambas ramas Prefetch, `dense`, `bm25`, `qdrant_find`,
+`dual_memory_search`) — usa el `IsEmptyCondition` de Qdrant (NO `IsNullCondition`,
+ver [Qdrant#5342](https://github.com/qdrant/qdrant/issues/5342): `IsNull` no matchea
+campos ausentes).
+
+Configura en `.supamem/config.toml`:
+
+```toml
+[supamem.retrieval.temporal]
+retention_days = 90          # 0 = conservar siempre (compliance / auditoría)
+```
+
+### Decay de recencia solo para transcripciones (opt-in, apagado por defecto)
+
+El código, los ADRs y la documentación no "envejecen". Las transcripciones, sí — los
+turnos antiguos de soporte con APIs deprecadas distraen al agente del diálogo actual.
+Phase 9 incorpora un knob de decay multiplicativo con piso (multiplicative-floor) que
+corre **solo** sobre chunks de transcripción, después del rerank, y nunca se activa
+automáticamente para código / ADR / docs:
+
+```toml
+[supamem.retrieval.recency.per_source.transcript]
+enabled        = true            # default false
+half_life_days = 14.0
+alpha          = 0.7             # piso: la transcripción más vieja conserva 0.7x del score
+```
+
+Ejemplo trabajado con los defaults bloqueados (`alpha = 0.7`, `half_life_days = 14`):
+
+| Age (days) | Multiplier         |
+|------------|--------------------|
+| 0          | 1.000              |
+| 7          | 0.924              |
+| 14         | 0.850              |
+| 28         | 0.775              |
+| ∞          | 0.700 (floor at α) |
+
+El ranking de código / ADR / docs queda byte-idéntico cuando se cambia el knob —
+verificado por un test end-to-end de identidad de bytes (criterio TEMP-03).
+
+Referencias: [Customers.ai recency-weighted scoring](https://customers.ai/recency-weighted-scoring),
+[Snowflake Cortex Search scoring docs](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-customize-scoring).
+
+### Doctor
+
+`supamem doctor` muestra un panel `Temporal validity` (entre Reranker y Subagent
+reachability) que lista contadores de live / superseded / awaiting_gc / future-dated,
+desglose por fuente, `valid_from` más antiguo y más reciente, y la procedencia de
+`retention_days`. Solo lectura por construcción; nunca cambia el exit code de doctor.
+
+### Migración
+
+El primer `supamem index` post-upgrade rellena `valid_to=null` en puntos legados
+(controlado por una clave reservada del manifest, idempotente en sucesivas corridas).
+Defensa en profundidad junto al filtro `IsEmpty` de runtime.
+
+> ⚠ **El retention por defecto es destructivo** para usuarios que vienen de v0.2.x
+> con colecciones modo auditoría de más de 90 días. Setea
+> `[supamem.retrieval.temporal] retention_days = 0` para deshabilitar el auto-GC.
+
+---
+
 ## 🪛 Cableando a tu cliente
 
 <details>
diff --git a/README.ja.md b/README.ja.md
@@ -1,6 +1,6 @@
 **言語:** [English](README.md) · [简体中文](README.zh-CN.md) · [Español](README.es.md) · [日本語](README.ja.md) · [Русский](README.ru.md)
 
-<!-- synced-with: README.md @ f96d0a1 -->
+<!-- synced-with: README.md @ dcd3185 -->
 
 > この翻訳は AI 支援によるものです。ネイティブスピーカーによる修正 PR を歓迎します。
 
@@ -159,6 +159,7 @@ supamem doctor
 |---|---|
 | 🔍 **ハイブリッド検索** | 調整済み sparse(BM25) + dense(MiniLM) 融合、ロックされたスキーマ D-25 |
 | 🎯 **コード対応リランカー** | クロスエンコーダ `mxbai-rerank-base-v2`(Apache-2.0)が既定で `tuned_hybrid` の候補を再採点します。`retrieval.reranker = "off"` で無効化すると v0.2.4a1 以前の挙動に戻ります。(Phase 8, RERANK-01..04) |
+| ⏳ **ソース別の時間有効性** | 各 chunk に `valid_from`/`valid_to` を付与;変更されたファイルを再インデックスすると、旧 chunk をアトミックに無効化し、検索時フィルタが全バックエンド共通で無効化済み点を除外します。トランスクリプト専用の任意の recency 減衰(既定 OFF)。`retention_days = 90` を超えると自動 GC(`0` で恒久保持 / 監査用コレクション)。(Phase 9, TEMP-01..03) |
 | 📚 **Markdown チャンカー** | ヘッダー意識、200 トークン目標 / 250 トークン軟上限(T-1) |
 | 🤖 **MCP サーバー** | `stdio`(デフォルト)と `http` トランスポート、公式 `mcp` SDK |
 | 🪝 **マルチクライアントフック** | Claude Code セッション開始、OpenCode セッション開始、Cursor MDC |
@@ -469,6 +470,83 @@ fetch パイプラインで実行されます。
 
 ---
 
+## ⏳ ソース別の時間有効性(v0.3.0a1+)
+
+インデックスされた各 chunk は二値の `valid_to` フィールドを持ちます:
+
+- `valid_to = null` → 有効
+- `valid_to ≤ now()` → 置き換え済み(あらゆる検索で除外)
+
+ファイルが変更されて再インデックスを行うと、インデクサはアトミックに:
+
+1. そのファイルパスの既存 chunk すべてを scroll します。
+2. 各々に `set_payload(valid_to = now())` を適用(従前の有効期間を閉じる)。
+3. 内容ハッシュベースの UUID で `valid_to = null` の新 chunk を upsert します。
+
+新旧の chunk は Qdrant 内に共存し、検索結果には新 chunk のみが返ります。`retention_days`
+を超えた古い chunk は自動 GC スイープで削除されます。検索時フィルタは単一の場所で
+構築され、すべてのバックエンド(`tuned_hybrid` の両 Prefetch アーム、`dense`、
+`bm25`、`qdrant_find`、`dual_memory_search`)に継承されます。Qdrant の
+`IsEmptyCondition` を使用します(`IsNullCondition` は使いません — 詳細は
+[Qdrant#5342](https://github.com/qdrant/qdrant/issues/5342):`IsNull` は欠損フィールドに
+マッチしません)。
+
+`.supamem/config.toml` で設定:
+
+```toml
+[supamem.retrieval.temporal]
+retention_days = 90          # 0 = 恒久保持(コンプライアンス / 監査用コレクション)
+```
+
+### トランスクリプト専用の recency 減衰(opt-in、既定 OFF)
+
+コード、ADR、ドキュメントは「古くなる」ことはありません。しかしトランスクリプトはしばしば
+古くなります — 旧サポートチャットの非推奨 API がエージェントを現在の対話から逸脱させます。
+Phase 9 ではトランスクリプト chunk **のみ**に作用し、rerank 後に走り、コード / ADR /
+ドキュメントには絶対に自動適用されない、乗法フロア型の任意 decay knob を提供します:
+
+```toml
+[supamem.retrieval.recency.per_source.transcript]
+enabled        = true            # 既定 false
+half_life_days = 14.0
+alpha          = 0.7             # フロア:最古のトランスクリプトでも 0.7 倍の score を保つ
+```
+
+ロックされた既定値での例(`alpha = 0.7`、`half_life_days = 14`):
+
+| Age (days) | Multiplier         |
+|------------|--------------------|
+| 0          | 1.000              |
+| 7          | 0.924              |
+| 14         | 0.850              |
+| 28         | 0.775              |
+| ∞          | 0.700 (floor at α) |
+
+knob を切り替えてもコード / ADR / ドキュメントのランキングはバイト一致 — エンドツーエンド
+のバイト同一性テストで検証されています(TEMP-03 受け入れ基準)。
+
+参考:[Customers.ai recency-weighted scoring](https://customers.ai/recency-weighted-scoring)、
+[Snowflake Cortex Search scoring docs](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-customize-scoring)。
+
+### Doctor パネル
+
+`supamem doctor` は Reranker と Subagent reachability の間に `Temporal validity`
+パネルを追加し、live / superseded / awaiting_gc / future-dated のカウント、ソース別
+内訳、コレクション内の最古/最新の `valid_from`、そして `retention_days` のプロビナンス
+を表示します。構造的に読み取り専用で、doctor の終了コードを変えることはありません。
+
+### マイグレーション
+
+アップグレード後の最初の `supamem index` は、レガシーポイントに `valid_to=null` を
+バックフィルします(マニフェストの予約キーで管理、以降の実行は冪等)。ランタイムの
+`IsEmpty` フィルタと並行する、深層防御です。
+
+> ⚠ **既定の retention は破壊的**:90 日を超える監査モードコレクションを持つ v0.2.x
+> からのアップグレードユーザは要注意。`[supamem.retrieval.temporal] retention_days = 0`
+> に設定すれば自動 GC を完全に無効化できます。
+
+---
+
 ## 🪛 クライアントへの配線
 
 <details>
diff --git a/README.ru.md b/README.ru.md
@@ -1,6 +1,6 @@
 **Языки:** [English](README.md) · [简体中文](README.zh-CN.md) · [Español](README.es.md) · [日本語](README.ja.md) · [Русский](README.ru.md)
 
-<!-- synced-with: README.md @ f96d0a1 -->
+<!-- synced-with: README.md @ dcd3185 -->
 
 > Перевод выполнен с помощью ИИ. Корректировки от носителей языка приветствуются — открывайте PR.
 
@@ -164,6 +164,7 @@ supamem doctor
 |---|---|
 | 🔍 **Гибридный retrieval** | Настроенная фьюжн sparse (BM25) + dense (MiniLM), зафиксированная схема D-25 |
 | 🎯 **Code-aware reranker** | Cross-encoder `mxbai-rerank-base-v2` (Apache-2.0) по умолчанию переоценивает кандидатов `tuned_hybrid`. Отключается `retrieval.reranker = "off"` — возврат к поведению до v0.2.4a1. (Phase 8, RERANK-01..04) |
+| ⏳ **Per-source временная валидность** | Каждый чанк несёт `valid_from`/`valid_to`; переиндексация изменённого файла атомарно помечает прежние чанки как устаревшие, а фильтр на этапе retrieval единообразно исключает устаревшие точки во всех бэкендах. Опциональный recency-decay только для транскриптов (по умолчанию OFF). Авто-GC после `retention_days = 90` (`0` = хранить вечно / для аудит-коллекций). (Phase 9, TEMP-01..03) |
 | 📚 **Markdown-чанкер** | Header-aware, чанки по 200 токенов с мягким потолком 250 (T-1) |
 | 🤖 **MCP-сервер** | Транспорты `stdio` (по умолчанию) и `http`, официальный SDK `mcp` |
 | 🪝 **Multi-client хуки** | session-start Claude Code, session-start OpenCode, MDC Cursor |
@@ -478,6 +479,86 @@ fetch-pipeline команд install/init/repair.
 
 ---
 
+## ⏳ Per-source временная валидность (v0.3.0a1+)
+
+Каждый индексируемый чанк несёт бинарное поле `valid_to`:
+
+- `valid_to = null` → активный
+- `valid_to ≤ now()` → устаревший (отфильтровывается из любого retrieval-запроса)
+
+Когда файл изменяется и вы его переиндексируете, индексер атомарно:
+
+1. Скроллит все существующие чанки для этого пути.
+2. Выставляет `set_payload(valid_to = now())` на каждом (закрывает прежнее окно
+   валидности).
+3. Делает upsert новых чанков с UUID на основе хеша содержимого и `valid_to = null`.
+
+Старые и новые чанки сосуществуют в Qdrant; в выдачу попадают только новые — пока
+авто-GC не удалит устаревшие после `retention_days`. Фильтр на этапе retrieval
+конструируется в одном месте и наследуется всеми бэкендами (обеими ветвями Prefetch
+у `tuned_hybrid`, `dense`, `bm25`, `qdrant_find`, `dual_memory_search`) — использует
+`IsEmptyCondition` Qdrant (НЕ `IsNullCondition` — см.
+[Qdrant#5342](https://github.com/qdrant/qdrant/issues/5342): `IsNull` не матчит
+отсутствующие поля).
+
+Конфигурация в `.supamem/config.toml`:
+
+```toml
+[supamem.retrieval.temporal]
+retention_days = 90          # 0 = хранить вечно (compliance / аудит)
+```
+
+### Recency-decay только для транскриптов (opt-in, по умолчанию OFF)
+
+Код, ADR и документация не «устаревают». А вот транскрипты — часто: старые ходы
+саппорт-чатов с устаревшими API уводят агента от текущего диалога. Phase 9 даёт
+opt-in мультипликативный decay с полом, который применяется **только** к чанкам
+транскриптов, после rerank, и никогда не активируется автоматически для код / ADR /
+docs:
+
+```toml
+[supamem.retrieval.recency.per_source.transcript]
+enabled        = true            # default false
+half_life_days = 14.0
+alpha          = 0.7             # пол: самый старый транскрипт всё ещё получает 0.7x от score
+```
+
+Пример с зафиксированными дефолтами (`alpha = 0.7`, `half_life_days = 14`):
+
+| Age (days) | Multiplier         |
+|------------|--------------------|
+| 0          | 1.000              |
+| 7          | 0.924              |
+| 14         | 0.850              |
+| 28         | 0.775              |
+| ∞          | 0.700 (floor at α) |
+
+При переключении knob ранжирование код / ADR / docs остаётся побайтово идентичным —
+покрыто end-to-end тестом байтового равенства (приёмочный критерий TEMP-03).
+
+Источники: [Customers.ai recency-weighted scoring](https://customers.ai/recency-weighted-scoring),
+[Snowflake Cortex Search scoring docs](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-customize-scoring).
+
+### Панель doctor
+
+`supamem doctor` показывает панель `Temporal validity` (между Reranker и Subagent
+reachability) со счётчиками live / superseded / awaiting_gc / future-dated, разбивкой
+по источникам, самым старым и самым новым `valid_from` в коллекции и provenance-
+строкой `retention_days`. По построению read-only; никогда не меняет код выхода
+doctor.
+
+### Миграция
+
+Первый `supamem index` после апгрейда заполняет `valid_to=null` на легаси-точках
+(управляется зарезервированным ключом манифеста, идемпотентен на последующих
+запусках). Эшелонированная защита параллельно с runtime-фильтром `IsEmpty`.
+
+> ⚠ **Дефолтный retention — деструктивный** для пользователей, переходящих с v0.2.x
+> с аудит-коллекциями старше 90 дней. Установите
+> `[supamem.retrieval.temporal] retention_days = 0`, чтобы полностью отключить авто-GC.
+
+---
+
 ## 🪛 Подключение к клиенту
 
 <details>
diff --git a/README.zh-CN.md b/README.zh-CN.md
