dsh-reference-session-collector 0.0.0-stage → 0.1.0

package/README.de.md

@@ -0,0 +1,75 @@
+# dsh-reference-session-collector (DRS) — Sitzungs-Projektionssynchronisierer
+
+**DeepSeek-Harness(DSH)-Plugin**: Liest die Sitzungsprotokolle unter
+`~/.dsh/sessions/**` **nur lesend**, dekodiert sie und projiziert sie in eine
+eigene SQLite-Projektion (segments / replaces / FTS5). Über eine einzelne
+fenced HTTP-Route `GET/POST /api/dsh-reference-session-collector` werden
+Surface-Markierungen, Recall-Abgleich und chinesisch-taugliche
+Volltextsuche bereitgestellt. **Es wird niemals in Sitzungsdateien
+geschrieben.**
+
+## Status
+
+**Geliefert (v0.1.0)**: die komplette Host-Hälfte — reiner
+Projektionskern, SQLite-Projektionsspeicher (node:sqlite / FTS5),
+inkrementeller Synchronisierungsmotor (Watermark-Vorprüfung,
+Archivverfolgung, Interval-Scheduling), Abfrageoberfläche mit
+3-Schicht-Caching, fenced HTTP-Route. Gate-Kette `pnpm check` komplett grün
+(9 Suiten / 66 Tests + Dist-Smoke). **Ausstehend**: Verbraucher-Anbindung
+(Phase 1 CCI-Abgleich, Phase 2 Steward-Korpusumschaltung, Phase 3
+Memory-Anker-Rückfüllung) und Effizienz-Benchmark T9.1.
+
+## Architektur
+
+```
+~/.dsh/sessions/** (nur lesend) ──→ ProjectionSync (inkrementell, watermark=bytes+mtime)
+                                   │ projectSessionEvents (reiner Kern)
+                                   ▼
+        ~/.dsh-reference-session-collector/projection.db (4 Tabellen + fts5 + 3-Schicht-Cache)
+                                   │
+              ┌────────────────────┼───────────────────┐
+   /api/dsh-reference-session-collector     CCI (Phase 1)   Steward (2) / Memory (3)
+```
+
+## HTTP-Routentabelle
+
+| op | Parameter | Rückgabe |
+|---|---|---|
+| `status` | — | Speicher-Selftest + Cache-Statistik + letzter Sync |
+| `sessions` | `offset/limit` | Sitzungsübersicht (residente Map, 0 SQL) |
+| `session` | `session=<id>`, optional `turn=` / `fields=search` | Segmente inkl. Suchfeldern |
+| `surface` | `session=<id>` | Surface-Ledger (aktuelle Oberfläche + Ersetzer-Zeiger) |
+| `recall` | `session=<id>` | Ersetzungspaare klassifiziert (Σb / Σ(a−b)) |
+| `search` | `q=<query>`, optional `session=` | FTS5-BM25-Treffer (zh/en gleichtsegmentiert) |
+| `sync` (POST) | `{op:'sync'}` | accepted + letztes Ergebnis |
+
+## Nur-lesend-Disziplin
+
+- Sitzungsdateien und `workspace.json` sind stets nur lesend;
+- sämtliche Schreibvorgänge gehen ausschließlich nach
+  `~/.dsh-reference-session-collector/projection.db`;
+- pro Sitzung vollständiger Neu-Schreib-Ersatz (DELETE+INSERT in einer
+  Transaktion), idempotent;
+- **Maskierung liegt nicht bei DRS**: Rohtext-Speicherung,
+  Expositionsfläche = die Sitzungsdateien selbst.
+
+## Umgebungsvariablen
+
+| Variable | Standard | Bedeutung |
+|---|---|---|
+| `DSH_HOME` | `~/.dsh` | Sitzungsprotokoll-Wurzel |
+| `DSH_REFERENCE_SESSION_COLLECTOR_DIR` | `~/.dsh-reference-session-collector` | Projektion-DB-Verzeichnis |
+| `DSH_REFERENCE_SESSION_COLLECTOR_SYNC_INTERVAL_MS` | `30000` | Sync-Intervall; `0` = nur manuell |
+
+## Installation / Entwicklung
+
+```
+dsh plugin --profile web add dsh-reference-session-collector
+pnpm install && pnpm check   # typecheck→lint→test→build→smoke
+```
+
+Node ≥ 22 erforderlich (`zlib.zstdDecompressSync` + `node:sqlite`).
+
+## Lizenz
+
+MIT

package/README.en.md

@@ -0,0 +1,110 @@
+# dsh-reference-session-collector (DRS)
+
+**Session reference projection synchronizer** — a DeepSeek Harness (DSH) plugin.
+
+Reads session logs under `~/.dsh/sessions` (**read-only**) and decodes them into
+one shared SQLite **projection store**: original text indexed by
+`session × turn/step × seq`, DeepSeek-vocabulary token lengths, CCI surface
+replacement markers, recall pointers, and an FTS5 full-text index — so context
+compression (cci), the session steward, and prime-memory all read the same
+projection instead of each decoding logs on their own.
+
+> Naming: `dsh-reference-session-collector` abbreviates to **DRS**, which is also the
+> first three letters of drscrewdriver.
+
+## Status
+
+**Delivered (v0.1.0)**: the whole host half — pure projection core, SQLite
+projection store (node:sqlite, FTS5), incremental sync engine (watermark
+pre-check, archive-set following, interval scheduling), query surface with
+3-layer caching, and the fenced HTTP route. Gate chain `pnpm check` green
+(9 suites / 66 tests) plus dist smoke (`pnpm smoke`). **Remaining**: consumer
+wiring (phase 1 CCI reconciliation, phase 2 steward corpus switch, phase 3
+memory anchor backfill) and the efficiency benchmark (T9.1). The route table
+and store schema below are finalized.
+
+## Architecture
+
+```
+~/.dsh/sessions/** (read-only) ──→ ProjectionSync (incremental, watermark)
+                                   │ projectSessionEvents (pure core)
+                                   ▼
+       projection.db (~/.dsh-reference-session-collector/, 4 tables + fts5, 3-layer cache)
+                                   │
+           ┌───────────────────────┼────────────────────┐
+ /api/dsh-reference-session-collector     cci (phase 1)     steward (2) / memory (3)
+ (status/surface/recall/…)      savings/recheck   corpus / history backfill
+```
+
+- **Store**: `sessions` (watermark + aggregates) / `segments` (original text ×
+  turn/step × tokens × surface marker × search vista) / `replaces` (replace
+  pair pointers, a/b/kind) + `segments_fts` (bm25 over Intl.Segmenter('zh')
+  word-segmented text in a unicode61 table).
+- **CCI assists**: surface-marker recognition (what is on the surface now, and
+  what replaced it) + surface recall pointer statistics (replace pairs with
+  b>a are re-reads; Σb accounts for negative savings directly).
+- **Three cache layers**: SQLite mmap/WAL always on; sessions aggregates
+  resident in memory; per-session ledger LRU keyed by sync generation.
+
+## HTTP route
+
+Single fenced route, op dispatch:
+
+| op | params | returns |
+|---|---|---|
+| `status` (default) | — | store/cache/sync status |
+| `sessions` | `limit` `offset` | paginated session summaries |
+| `session` | `id`, optional `turn=` range, optional `fields=search` | session projection detail |
+| `surface` | `id` | surface marker ledger |
+| `recall` | `id` | recall pairs + Σb (negative-savings stats, range pointers) |
+| `search` | `q`, `limit`, `session?` | fts5 hits (CJK-capable) |
+| `sync` (POST) | — | kick incremental sync; returns accepted + lastResult |
+
+Without the webServer service the plugin still syncs; only the HTTP face is
+missing (fail-soft).
+
+## Read-only discipline
+
+`readFileSync` is the **only** call this plugin makes against session files,
+and it has no write counterpart — ever. The plugin writes only to
+`~/.dsh-reference-session-collector/projection.db`. That database holds **unsanitized
+original text**; its exposure equals the session files themselves. Any
+"sanitized corpus" requirement belongs to consumers, not DRS.
+
+## Configuration (v0)
+
+No settings face yet (lands with phase-2 wiring). Environment variables:
+
+| variable | default | meaning |
+|---|---|---|
+| `DSH_HOME` | `~/.dsh` | session log root |
+| `DSH_REFERENCE_SESSION_COLLECTOR_DIR` | `~/.dsh-reference-session-collector` | projection db dir |
+| `DSH_REFERENCE_SESSION_COLLECTOR_SYNC_INTERVAL_MS` | `30000` | sync interval; `0` = manual only |
+
+## Roadmap
+
+1. **Phase 1 · cci reconciliation**: monitor/verify gains a DRS recall column —
+   claims vs formula vs projection, three-column accounting (read-only HTTP).
+2. **Phase 2 · steward corpus switch**: the steward's inlined search engine
+   reads DRS (segments.time/on_surface/search_text + last_time_ms/archived
+   cover its whole hit face; field mapping in
+   `.agents/plans/drs-start/findings.md`).
+3. **Phase 3 · memory history projection (read-only)**: the l0 write path does
+   **not** move (sanitization/redaction/record_id ownership stays in memory's
+   capture side; it is semantically incompatible with full-session rewrite).
+   DRS only serves historical anchor backfill and corpus. Vector layer
+   (BGE-M3 int8) is a separate optional batch job.
+
+## Development
+
+```bash
+pnpm install
+pnpm check       # typecheck → lint → test → build → smoke (one chain)
+```
+
+Plan and progress: `.agents/plans/drs-start/` (spec / findings / checklist /
+tasks).
+
+## License
+
+MIT

package/README.es.md

@@ -0,0 +1,74 @@
+# dsh-reference-session-collector (DRS) — sincronizador de proyección de sesiones
+
+**Complemento de DeepSeek Harness (DSH)**: escanea **solo en lectura** los
+registros de sesión en `~/.dsh/sessions/**`, los decodifica y los proyecta
+en una proyección SQLite propia (segments / replaces / FTS5). Una única
+ruta HTTP acotada `GET/POST /api/dsh-reference-session-collector` expone marcas de
+superficie, conciliación de recuperaciones (recall) y búsqueda de texto
+completo con soporte de chino. **Nunca escribe en los archivos de sesión.**
+
+## Estado
+
+**Entregado (v0.1.0)**: la mitad anfitriona completa — núcleo de proyección
+puro, almacén SQLite (node:sqlite / FTS5), motor de sincronización
+incremental (preconsulta de marca de agua, seguimiento de archivo,
+programación por intervalo), capa de consultas con caché de 3 niveles y
+ruta HTTP acotada. Cadena de puertas `pnpm check` totalmente en verde
+(9 suites / 66 pruebas + humo de dist). **Pendiente**: cableado de
+consumidores (fase 1 conciliación CCI, fase 2 cambio de corpus de steward,
+fase 3 relleno de anclas de memory) y banco de pruebas de eficiencia T9.1.
+
+## Arquitectura
+
+```
+~/.dsh/sessions/** (solo lectura) ──→ ProjectionSync (incremental, watermark=bytes+mtime)
+                                   │ projectSessionEvents (núcleo puro)
+                                   ▼
+        ~/.dsh-reference-session-collector/projection.db (4 tablas + fts5 + caché de 3 niveles)
+                                   │
+              ┌────────────────────┼───────────────────┐
+   /api/dsh-reference-session-collector     CCI (fase 1)   steward (2) / memory (3)
+```
+
+## Tabla de rutas HTTP
+
+| op | parámetros | devuelve |
+|---|---|---|
+| `status` | — | autodiagnóstico + estadísticas de caché + última sincronización |
+| `sessions` | `offset/limit` | resumen de sesiones (Map residente, 0 SQL) |
+| `session` | `session=<id>`, opcional `turn=` / `fields=search` | detalle de segments (campos de búsqueda) |
+| `surface` | `session=<id>` | registro de superficie (estado actual + punteros de reemplazo) |
+| `recall` | `session=<id>` | pares de reemplazo clasificados (Σb / Σ(a−b)) |
+| `search` | `q=<consulta>`, opcional `session=` | resultados FTS5 BM25 (segmentación idéntica zh/en) |
+| `sync` (POST) | `{op:'sync'}` | accepted + último resultado |
+
+## Disciplina de solo lectura
+
+- los archivos de sesión y `workspace.json` son siempre de solo lectura;
+- toda escritura del complemento va únicamente a
+  `~/.dsh-reference-session-collector/projection.db`;
+- reemplazo de reescritura completa por sesión (DELETE+INSERT en una
+  transacción), idempotente;
+- **la desensibilización no es responsabilidad de DRS**: almacena texto
+  original; la superficie de exposición son los propios archivos de sesión.
+
+## Variables de entorno
+
+| variable | valor por defecto | significado |
+|---|---|---|
+| `DSH_HOME` | `~/.dsh` | raíz de registros de sesión |
+| `DSH_REFERENCE_SESSION_COLLECTOR_DIR` | `~/.dsh-reference-session-collector` | directorio de la BD de proyección |
+| `DSH_REFERENCE_SESSION_COLLECTOR_SYNC_INTERVAL_MS` | `30000` | intervalo de sincronización; `0` = solo manual |
+
+## Instalación / desarrollo
+
+```
+dsh plugin --profile web add dsh-reference-session-collector
+pnpm install && pnpm check   # typecheck→lint→test→build→smoke
+```
+
+Requiere Node ≥ 22 (`zlib.zstdDecompressSync` + `node:sqlite`).
+
+## Licencia
+
+MIT

package/README.fr.md

@@ -0,0 +1,74 @@
+# dsh-reference-session-collector (DRS) — Synchroniseur de projection de sessions
+
+**Plugin DeepSeek Harness (DSH)** : balaie les journaux de session sous
+`~/.dsh/sessions/**` en **lecture seule**, les décode et les projette dans
+une projection SQLite propriétaire (segments / replaces / FTS5). Une unique
+route HTTP cloisonnée `GET/POST /api/dsh-reference-session-collector` expose le marquage de
+surface, le rapprochement des rappels et une recherche en texte intégral
+compatible chinois. **N'écrit jamais dans les fichiers de session.**
+
+## Statut
+
+**Livré (v0.1.0)** : la moitié hôte complète — noyau de projection pur,
+dépôt SQLite (node:sqlite / FTS5), moteur de synchronisation incrémental
+(pré-vérification watermark, suivi des archivées, ordonnancement interval),
+face de requêtes à cache 3 couches, route HTTP cloisonnée. Chaîne de gates
+`pnpm check` entièrement verte (9 suites / 66 tests + smoke dist).
+**Restant** : câblage des consommateurs (phase 1 rapprochement CCI,
+phase 2 bascule du corpus steward, phase 3 réancrage mémoire) et benchmark
+d'efficacité T9.1.
+
+## Architecture
+
+```
+~/.dsh/sessions/** (lecture seule) ──→ ProjectionSync (incrémental, watermark=bytes+mtime)
+                                   │ projectSessionEvents (noyau pur)
+                                   ▼
+        ~/.dsh-reference-session-collector/projection.db (4 tables + fts5 + cache 3 couches)
+                                   │
+              ┌────────────────────┼───────────────────┐
+   /api/dsh-reference-session-collector     CCI (phase 1)   steward (2) / memory (3)
+```
+
+## Table des routes HTTP
+
+| op | paramètres | retour |
+|---|---|---|
+| `status` | — | auto-diagnostic dépôt + stats cache + dernier sync |
+| `sessions` | `offset/limit` | résumé des sessions (Map résidente, 0 SQL) |
+| `session` | `session=<id>`, `turn=` / `fields=search` optionnels | détail segments (champs de recherche) |
+| `surface` | `session=<id>` | registre de surface (état courant + pointeurs de remplacement) |
+| `recall` | `session=<id>` | paires de remplacement classées (Σb / Σ(a−b)) |
+| `search` | `q=<requête>`, `session=` optionnel | résultats FTS5 BM25 (segmentation zh/en identique) |
+| `sync` (POST) | `{op:'sync'}` | accepted + dernier résultat |
+
+## Discipline de lecture seule
+
+- fichiers de session et `workspace.json` toujours en lecture seule ;
+- toutes les écritures vont uniquement dans
+  `~/.dsh-reference-session-collector/projection.db` ;
+- remplacement réécriture-complète par session (DELETE+INSERT dans une
+  transaction), idempotent ;
+- **l'anonymisation n'est pas la responsabilité de DRS** : texte brut
+  stocké, surface d'exposition = les fichiers de session eux-mêmes.
+
+## Variables d'environnement
+
+| variable | défaut | signification |
+|---|---|---|
+| `DSH_HOME` | `~/.dsh` | racine des journaux de session |
+| `DSH_REFERENCE_SESSION_COLLECTOR_DIR` | `~/.dsh-reference-session-collector` | répertoire de la BD de projection |
+| `DSH_REFERENCE_SESSION_COLLECTOR_SYNC_INTERVAL_MS` | `30000` | intervalle de sync ; `0` = manuel uniquement |
+
+## Installation / Développement
+
+```
+dsh plugin --profile web add dsh-reference-session-collector
+pnpm install && pnpm check   # typecheck→lint→test→build→smoke
+```
+
+Node ≥ 22 requis (`zlib.zstdDecompressSync` + `node:sqlite`).
+
+## Licence
+
+MIT

package/README.it.md

@@ -0,0 +1,74 @@
+# dsh-reference-session-collector (DRS) — sincronizzatore di proiezione delle sessioni
+
+**Plugin DeepSeek Harness (DSH)**: scansisce **in sola lettura** i log di
+sessione in `~/.dsh/sessions/**`, li decodifica e li proietta in una
+proiezione SQLite proprietaria (segments / replaces / FTS5). Un singolo
+endpoint HTTP delimitato `GET/POST /api/dsh-reference-session-collector` espone i
+marchi di superficie, la riconciliazione dei recall e la ricerca full-text
+con supporto del cinese. **Non scrive mai nei file di sessione.**
+
+## Stato
+
+**Consegnata (v0.1.0)**: tutta la metà host — nucleo di proiezione puro,
+archivio SQLite (node:sqlite / FTS5), motore di sincronizzazione
+incrementale (pre-verifica watermark, seguimento dell'archivio,
+pianificazione a intervallo), superficie di query con cache a 3 livelli,
+endpoint HTTP delimitato. Catena di gate `pnpm check` tutta verde
+(9 suite / 66 test + smoke di dist). **Rimanente**: cablaggio dei
+consumatori (fase 1 riconciliazione CCI, fase 2 commutazione del corpus
+steward, fase 3 riempimento ancore memory) e benchmark di efficienza T9.1.
+
+## Architettura
+
+```
+~/.dsh/sessions/** (sola lettura) ──→ ProjectionSync (incrementale, watermark=bytes+mtime)
+                                   │ projectSessionEvents (nucleo puro)
+                                   ▼
+        ~/.dsh-reference-session-collector/projection.db (4 tabelle + fts5 + cache a 3 livelli)
+                                   │
+              ┌────────────────────┼───────────────────┐
+   /api/dsh-reference-session-collector     CCI (fase 1)   steward (2) / memory (3)
+```
+
+## Tabella degli endpoint HTTP
+
+| op | parametri | restituisce |
+|---|---|---|
+| `status` | — | auto-diagnosi archivio + statistiche cache + ultima sincronizzazione |
+| `sessions` | `offset/limit` | riepilogo sessioni (Map residente, 0 SQL) |
+| `session` | `session=<id>`, opzionali `turn=` / `fields=search` | dettaglio segments (campi di ricerca) |
+| `surface` | `session=<id>` | registro di superficie (stato attuale + puntatori di sostituzione) |
+| `recall` | `session=<id>` | coppie di sostituzione classificate (Σb / Σ(a−b)) |
+| `search` | `q=<query>`, opzionale `session=` | risultati FTS5 BM25 (segmentazione identica zh/en) |
+| `sync` (POST) | `{op:'sync'}` | accepted + ultimo risultato |
+
+## Disciplina di sola lettura
+
+- i file di sessione e `workspace.json` sono sempre in sola lettura;
+- tutte le scritture del plugin finiscono esclusivamente in
+  `~/.dsh-reference-session-collector/projection.db`;
+- sostituzione con riscrittura completa per sessione (DELETE+INSERT in una
+  transazione), idempotente;
+- **la sanitizzazione non è responsabilità di DRS**: memorizza testo grezzo,
+  superficie di esposizione = i file di sessione stessi.
+
+## Variabili d'ambiente
+
+| variabile | predefinito | significato |
+|---|---|---|
+| `DSH_HOME` | `~/.dsh` | radice dei log di sessione |
+| `DSH_REFERENCE_SESSION_COLLECTOR_DIR` | `~/.dsh-reference-session-collector` | directory del DB di proiezione |
+| `DSH_REFERENCE_SESSION_COLLECTOR_SYNC_INTERVAL_MS` | `30000` | intervallo di sincronizzazione; `0` = solo manuale |
+
+## Installazione / sviluppo
+
+```
+dsh plugin --profile web add dsh-reference-session-collector
+pnpm install && pnpm check   # typecheck→lint→test→build→smoke
+```
+
+Richiede Node ≥ 22 (`zlib.zstdDecompressSync` + `node:sqlite`).
+
+## Licenza
+
+MIT

package/README.ja.md

@@ -0,0 +1,68 @@
+# dsh-reference-session-collector (DRS) — セッション原文プロジェクション同期器
+
+**DeepSeek Harness (DSH) プラグイン**: `~/.dsh/sessions/**` のセッション
+ログを**読み取り専用**で走査し、復号後に独自 SQLite プロジェクション
+（segments / replaces / FTS5）へ投影。単一の fenced HTTP ルート
+`GET/POST /api/dsh-reference-session-collector` で surface マーク・リコール照合・
+中文対応の全文検索面を提供します。**セッションファイルへは一切書き込みません。**
+
+## ステータス
+
+**納品済み（v0.1.0）**: ホスト側全体——純投影コア、SQLite プロジェクション
+ストア（node:sqlite / FTS5）、増分同期エンジン（watermark 事前チェック /
+アーカイブ追従 / interval スケジューリング）、3層キャッシュ照会面、fenced
+HTTP ルート。ゲートチェーン `pnpm check` 全緑（9スイート / 66テスト + dist
+スモーク）。**残作業**: コンシューマー配線（第1期 CCI 照合 / 第2期 steward
+コーパス切替 / 第3期 memory アンカー補填）と効率ベンチマーク T9.1。
+
+## アーキテクチャ
+
+```
+~/.dsh/sessions/**（読み取り専用）──→ ProjectionSync（増分、watermark=bytes+mtime）
+                                   │ projectSessionEvents（純コア）
+                                   ▼
+        ~/.dsh-reference-session-collector/projection.db（4テーブル + fts5 + 3層キャッシュ）
+                                   │
+              ┌────────────────────┼───────────────────┐
+   /api/dsh-reference-session-collector     CCI(第1期)   steward(第2期)/memory(第3期)
+```
+
+## HTTP ルート表
+
+| op | パラメータ | 戻り値 |
+|---|---|---|
+| `status` | — | ストア自己診断 + キャッシュ統計 + 直近同期 |
+| `sessions` | `offset/limit` | セッション一覧（常駐 Map、0 SQL） |
+| `session` | `session=<id>`、任意 `turn=` / `fields=search` | segments 明細（検索面フィールド） |
+| `surface` | `session=<id>` | surface テーブル（現在の表面 + 置換ポインタ） |
+| `recall` | `session=<id>` | 置換ペア分類（Σb / Σ(a−b)） |
+| `search` | `q=<query>`、任意 `session=` | FTS5 BM25 ヒット（中日同形分割） |
+| `sync`（POST） | `{op:'sync'}` | accepted + 直近結果 |
+
+## 読み取り専用規律
+
+- セッションファイルと `workspace.json` は常時読み取り専用;
+- 本プラグインの全書き込みは `~/.dsh-reference-session-collector/projection.db` にのみ;
+- セッション単位の全量書換式置換（トランザクション内 DELETE+INSERT）、冪等;
+- **マスキング責任は DRS にない**: 原文を保存、露出面=セッションファイル自体。
+
+## 環境変数
+
+| 変数 | 既定値 | 意味 |
+|---|---|---|
+| `DSH_HOME` | `~/.dsh` | セッションログルート |
+| `DSH_REFERENCE_SESSION_COLLECTOR_DIR` | `~/.dsh-reference-session-collector` | プロジェクションDBディレクトリ |
+| `DSH_REFERENCE_SESSION_COLLECTOR_SYNC_INTERVAL_MS` | `30000` | 同期間隔; `0`=手動のみ |
+
+## インストール / 開発
+
+```
+dsh plugin --profile web add dsh-reference-session-collector
+pnpm install && pnpm check   # typecheck→lint→test→build→smoke
+```
+
+Node ≥ 22 必須（`zlib.zstdDecompressSync` + `node:sqlite`）。
+
+## ライセンス
+
+MIT

package/README.ko.md

@@ -0,0 +1,68 @@
+# dsh-reference-session-collector (DRS) — 세션 원문 투영 동기화기
+
+**DeepSeek Harness(DSH) 플러그인**: `~/.dsh/sessions/**` 세션 로그를
+**읽기 전용**으로 스캔하여 디코딩 후 자체 SQLite 투영
+(segments / replaces / FTS5)에 적재. 단일 fenced HTTP 라우트
+`GET/POST /api/dsh-reference-session-collector`로 surface 마크, 리콜 대사(對社),
+중국어 전문 검색면을 제공합니다. **세션 파일에는 절대 기록하지 않습니다.**
+
+## 상태
+
+**전달 완료(v0.1.0)**: 호스트 하프 전체 — 순수 투영 코어, SQLite 투영
+스토어(node:sqlite / FTS5), 증분 동기화 엔진(watermark 사전 조회 / 아카이브
+추종 / interval 스케줄링), 3계층 캐시 조회면, fenced HTTP 라우트. 게이트
+체인 `pnpm check` 전부 녹색(9 스위트 / 66 테스트 + dist 스모크).
+**남은 작업**: 컨슈머 배선(1단계 CCI 대사 / 2단계 steward 코퍼스 전환 /
+3단계 memory 앵커 백필)과 성능 벤치마크 T9.1.
+
+## 아키텍처
+
+```
+~/.dsh/sessions/**(읽기 전용) ──→ ProjectionSync(증분, watermark=bytes+mtime)
+                                   │ projectSessionEvents(순수 코어)
+                                   ▼
+        ~/.dsh-reference-session-collector/projection.db(4개 테이블 + fts5 + 3계층 캐시)
+                                   │
+              ┌────────────────────┼───────────────────┐
+   /api/dsh-reference-session-collector     CCI(1단계)   steward(2단계)/memory(3단계)
+```
+
+## HTTP 라우트 표
+
+| op | 파라미터 | 반환 |
+|---|---|---|
+| `status` | — | 스토어 자가 진단 + 캐시 통계 + 최근 동기화 |
+| `sessions` | `offset/limit` | 세션 요약 페이지(상주 Map, 0 SQL) |
+| `session` | `session=<id>`, 선택 `turn=` / `fields=search` | segments 상세(검색면 필드) |
+| `surface` | `session=<id>` | surface 대장(현재 표면 + 치환 포인터) |
+| `recall` | `session=<id>` | 치환 쌍 분류(Σb / Σ(a−b)) |
+| `search` | `q=<질의>`, 선택 `session=` | FTS5 BM25 히트(중·영 동일 분사) |
+| `sync`(POST) | `{op:'sync'}` | accepted + 최근 결과 |
+
+## 읽기 전용 규율
+
+- 세션 파일과 `workspace.json`은 상시 읽기 전용;
+- 모든 기록은 `~/.dsh-reference-session-collector/projection.db`에만;
+- 세션 단위 전체 재작성 치환(트랜잭션 내 DELETE+INSERT), 멱등;
+- **마스킹 책임은 DRS에 없음**: 원문 저장, 노출면=세션 파일 자체.
+
+## 환경 변수
+
+| 변수 | 기본값 | 의미 |
+|---|---|---|
+| `DSH_HOME` | `~/.dsh` | 세션 로그 루트 |
+| `DSH_REFERENCE_SESSION_COLLECTOR_DIR` | `~/.dsh-reference-session-collector` | 투영 DB 디렉터리 |
+| `DSH_REFERENCE_SESSION_COLLECTOR_SYNC_INTERVAL_MS` | `30000` | 동기화 주기; `0`=수동 전용 |
+
+## 설치 / 개발
+
+```
+dsh plugin --profile web add dsh-reference-session-collector
+pnpm install && pnpm check   # typecheck→lint→test→build→smoke
+```
+
+Node ≥ 22 필요(`zlib.zstdDecompressSync` + `node:sqlite`).
+
+## 라이선스
+
+MIT

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-reference-session-collector (DRS) — 会话原文投影同步器
+
+> 只读扫描 `~/.dsh/sessions/**` 会话日志，解码后投影进插件自有 SQLite
+> （segments / replaces / FTS5），经单条 fenced HTTP 路由对外提供
+> surface 标记、召回对账与中文可用的内容检索面。**绝不写会话文件。**
+
+# Session Reference Projector (DRS) — English summary
+
+DRS is a read-only projector over the host's session logs. It walks
+`~/.dsh/sessions/**`, decodes zstd/teiled-frame logs with a vendored leaf
+decoder, and rewrites per-session projections into
+`~/.dsh-reference-session-collector/projection.db` (SQLite via `node:sqlite`, four
+tables + one FTS5 virtual table). A single fenced HTTP route
+(`GET/POST /api/dsh-reference-session-collector`) exposes status, session listings,
+per-session segment windows, the surface ledger, recall/compress pair
+accounting and full-text search. Token counts share the exact same
+DeepSeek-V4 tokenizer and formula as CCI's `verify`, falling back to a
+labelled `chars/4` basis when assets are absent. DRS never writes to any
+session file; its only writes land in its own data directory.
+
+## 定位 / Positioning
+
+| 消费方 | 用 DRS 做什么 | 分期 |
+|---|---|---|
+| CCI（context-compression） | surface 标记（compressed/surface_text/replaced_by）、召回对账（Σb 回吐、Σ(a−b) 毛节省）、verify 免全量解码 | 一期 |
+| steward（会话管家） | 内容搜索语料源切换（search_text/time/on_surface 检索面） | 二期 |
+| prime-memory | 历史投影只读：`op=session&turn=` 锚点回填 l0 旧行 turn/step（l0 写路径不迁） | 三期 |
+
+## 状态 / Status
+
+**已交付（v0.1.0）**：宿主半身全量——纯投影核心、SQLite 投影库
+（node:sqlite, FTS5）、增量同步引擎（watermark 预查/归档集跟随/interval
+调度）、三层缓存查询面、fenced HTTP 路由；门禁链 `pnpm check` 全绿
+（9 测试文件 / 66 测试）含 dist 冒烟。**剩余**：消费方接线（一期 CCI
+对账 / 二期 steward 语料切换 / 三期 memory 锚点回填）与效率基准 T9.1。
+
+其余 8 语文档：README.en / ja / ko / de / es / fr / ru / it。
+
+## 架构
+
+```
+~/.dsh/sessions/**（只读）──→ ProjectionSync(增量, watermark=bytes+mtime)
+                                   │ projectSessionEvents(纯核心)
+                                   ▼
+        ~/.dsh-reference-session-collector/projection.db（四表 + fts5 + 缓存三层）
+                                   │
+              ┌────────────────────┼───────────────────┐
+   /api/dsh-reference-session-collector     CCI(一期)      steward(二期)/memory(三期)
+   (status/surface/recall/…)     monitor 对账      语料源/锚点回填
+```
+
+## HTTP 路由表
+
+单条 fenced 路由 `GET/POST /api/dsh-reference-session-collector`，`op` 分发：
+
+| op | 参数 | 返回 |
+|---|---|---|
+| `status` | — | 库自检 + 缓存统计 + 上次同步结果 |
+| `sessions` | `offset/limit` | 会话汇总表分页 |
+| `session` | `session=<id>`，可选 `turn=<区间>`、`fields=search` | segments 明细（`fields=search` 返 time/search_text/on_surface 检索面） |
+| `surface` | `session=<id>` | surface 台账（当前表面行 + 被替换指针） |
+| `recall` | `session=<id>` | 替换对分类账（compress/recall、Σb、Σ(a−b)） |
+| `search` | `q=<词>`，可选 `session=` | FTS5 BM25 命中（中英同构切词） |
+| `sync`（POST） | `{op:'sync'}` | accepted + 上次结果（后台增量同步） |
+
+## 只读纪律
+
+- 会话文件（`~/.dsh/sessions/**`）与 `workspace.json` 一律只读；
+- 插件的全部写入落在 `~/.dsh-reference-session-collector/projection.db`；
+- 每 session 全量重写式替换（事务内 DELETE+INSERT），幂等可重放；
+- **脱敏责任不在 DRS**：projection.db 存原文，泄露面=会话文件本身。
+
+## 分期路线
+
+1. **一期**：投影库 + HTTP 面 + CCI 对账接线（monitor 探针 + verify 对账列）；
+2. **二期**：steward 内容搜索语料源切换（interval 同步缺省 30s 保新鲜度 ≤1 分钟）；
+3. **三期**：memory 历史锚点回填（`op=session&turn=` 匹配补 l0 旧行 turn/step，
+   匹配不上留 NULL 不伪造）；向量层（BGE-M3 int8 vec 列）为独立可选批任务。
+
+## Token 口径
+
+`deepseek-v4-tokenizer`（flash→pro 顺序解析，资产带 SHA-256 验证）与 CCI
+verify 同公式同词表；资产缺席降级 `chars/4` 并在 `sessions.basis` 如实标注。
+
+## 安装 / 运行
+
+```
+dsh plugin --profile web add dsh-reference-session-collector
+```
+
+要求 node ≥ 22（`zlib.zstdDecompressSync` + `node:sqlite`）。
+环境变量：`DSH_REFERENCE_SESSION_COLLECTOR_DIR` 覆盖库目录；
+`DSH_REFERENCE_SESSION_COLLECTOR_SYNC_INTERVAL_MS` 调同步周期（0=关闭）。
+
+## 状态与开发
+
+**开发中(核心链路已全通)**:投影核心/落库(L1)、同步引擎(L3)、宿主半与
+路由(L4)已落地,门禁全绿(typecheck/lint/build/smoke,37/37 测试);
+收尾中:查询面正式测试(T4.2)、跨仓接线(cci 一期 / steward 二期 /
+memory 三期)。进度簿:`.agents/plans/drs-start/`
+(spec / findings / checklist / tasks)。
+
+```bash
+pnpm install && pnpm typecheck && pnpm lint && pnpm test && pnpm build
+```
+
+## Vendored
+
+`src/session-file-decode.ts`、`src/token-count.ts`、`src/deepseek-v4-tokenizer.ts`
+为 CCI 文件级回搬件（禁止分叉，头注登记 provenance 与唯一授权 diff）；
+检索视界/切词逻辑为 steward 逐字同构移植。