dsh-reference-session-collector 0.1.0 → 0.2.0

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-reference-session-collector",
   "name": "dsh-reference-session-collector",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.0",
   "description": {
     "en": "Session reference projector (DRS): read-only scan of ~/.dsh/sessions logs, decoded into a private SQLite (segments/replaces/FTS5) with surface flags, recall-pair accounting and a Chinese-capable search face, served via /api/dsh-reference-session-collector. Never writes session files.",
     "zh": "会话原文投影同步器（DRS）：只读扫描 ~/.dsh/sessions 会话日志，解码后投影进自有 SQLite（segments/replaces/FTS5），经 /api/dsh-reference-session-collector 提供 surface 标记、召回对账与中文可用的内容检索面。绝不写会话文件。"

package/lib/index.d.ts

@@ -229,12 +229,14 @@ declare function projectSessionEvents(events: readonly DecodedEvent[], options:
 //#region src/schema.d.ts
 /** schema 版本（meta 表；断裂式迁移的比对基线）。
  * v2=加 sessions.format_generation；
- * v3=search_text 视界变更（剥离宿主注入样板段，strip-injected horizon v2）；
- * v4=账目双修（真机取证 2026-10-20）：① text/tokens 视界补 data.content 双臂
- *   （checkpoint 替身/用户消息旧视界全计 0）；② replaces 加 live 列——替身行
- *   被后续区间再覆盖时 delta 清除不入 gross（用户定标：checkpoint 只影响其后
- *   的积分）。旧行两项口径均错，整库清空重建（投影可重建，丢行无损）。 */
-declare const PROJECTION_SCHEMA_VERSION = "4";
+ * v3=search_text 视界变更（剥离宿主注入样板段）；
+ * v4=账目双修（data.content 双臂 + replaces.live）；
+ * v5=字块共享 + 脱敏派生臂（2026-10-20 用户定标）：text/search_text/
+ *   surface_text 实列退役→blocks 字典 hash 引用（surface 经 replaced_by
+ *   链派生）；新 redacted_text_hash/redacted_search_text_hash（redactSecrets
+ *   派生臂，CCI 口径 text 的 token 数学不动）；旧库列形状断裂→DROP 重建
+ *   + VACUUM（投影可重建，丢行无损）。 */
+declare const PROJECTION_SCHEMA_VERSION = "5";
 /** sessions 表原始行（snake_case 与 DDL 一致）。 */
 interface SessionRow {
   session_id: string;
@@ -322,15 +324,23 @@ declare function listSessions(ctx: QueryContext, offset?: number, limit?: number
   total: number;
   rows: SessionRow[];
 };
-/**
- * segments 明细。
- * @param turn - `turn=` 区间过滤（`a-b` 闭区间或单值）。
- * @param fields - `'search'` 返检索面字段（time/search_text/on_surface）。
- */
-declare function sessionDetail(ctx: QueryContext, sessionId: string, opts?: {
+/** sessionDetail 选项（turn 区间 / fields 检索臂 / tail 尾窗 / redact 脱敏臂）。 */
+interface SessionDetailOptions {
   turn?: string;
   fields?: string;
-}): {
+  /** R4 尾窗：正整数=会话尾 N 段（过滤后），升序返回；非法/缺省=全量。 */
+  tail?: number;
+  /** R3：true=切 redacted 列（含派生 surface_text 用链头 redacted 正文）。 */
+  redact?: boolean;
+}
+/**
+ * segments 明细（v4 逐字段同形还原）。
+ * @param opts.turn - `turn=` 区间过滤（`a-b` 闭区间或单值）。
+ * @param opts.fields - `'search'` 返检索面字段（time/search_text/on_surface）。
+ * @param opts.tail - 尾窗 N：先取 seq 降序 N 行再翻升序（与会话文件真实尾部对拍）。
+ * @param opts.redact - 脱敏臂：text/search_text/surface_text 取 redacted_* 列。
+ */
+declare function sessionDetail(ctx: QueryContext, sessionId: string, opts?: SessionDetailOptions): {
   session: SessionRow | undefined;
   rows: unknown[];
 };
@@ -341,10 +351,15 @@ declare function surfaceLedger(ctx: QueryContext, sessionId: string): Record<str
  * 毛节省只计 live=1 的对——替身被后续 checkpoint 再覆盖时 delta 清除（用户定标）。
  */
 declare function recallReport(ctx: QueryContext, sessionId: string): Record<string, unknown>;
-/** FTS5 BM25 内容搜索（中英同构切词，走 sanitizeFtsQuery）。 */
+/**
+ * FTS5 BM25 内容搜索（中英同构切词，走 sanitizeFtsQuery）。
+ * v5：fts 仍索引原文（R3）；snippet 经 blocks 还原，`redact` 只切 snippet
+ * 取材列（redacted_search_text_hash），命中/排序语义两臂一致。
+ */
 declare function search(ctx: QueryContext, query: string, opts?: {
   session?: string;
   limit?: number;
+  redact?: boolean;
 }): {
   query: string;
   match: string;
@@ -371,6 +386,14 @@ interface GroupedSearchRequest {
   /** 排序：缺省 relevance；'time'=会话 updated_at 降序、分数平手。 */
   sortBy?: 'relevance' | 'time';
   limit?: number;
+  /** R3：true=snippet 取材切 redacted_search_text（命中/排序不变，fts 仍原文）。 */
+  redact?: boolean;
+  /**
+   * 命中展开（steward「分开显示」开关，wire `expand=1`）：true=每条候选行
+   * 各自成命中（同会话多行按全局分数序出现）；缺省 false=会话分组各取
+   * 最强命中（既有聚合臂行为零改动，limit 语义随之从会话数变行数）。
+   */
+  expand?: boolean;
 }
 /** 分组命中（wire 蛇形，会话级最强命中）。 */
 interface GroupedSearchHit {
@@ -386,6 +409,7 @@ interface GroupedSearchHit {
  * 会话分组全文搜索（op=search&group=session）：BM25 候选窗 → 按会话取
  * 加权最强命中 → 排序分页。数学/视界与 steward engine.search 逐字同构：
  * score = −rank × weight(type)，时间排序键是会话 updated_at（非命中 time）。
+ * snippet 锚定文本经 blocks 还原（redact 臂切 redacted_search_text_hash）。
  */
 declare function searchGrouped(ctx: QueryContext, request: GroupedSearchRequest): {
   query: string;
@@ -532,7 +556,7 @@ interface SyncReplaceMeta {
 }
 /**
  * 投影库端口。真身 = schema.ts 的 ProjectionStore(L1);单测注入内存 mock。
- * 五个方法恰好是 sync 需要的全部写/读面——真身实现不得要求更多。
+ * 七个方法恰好是 sync 需要的全部写/读面——真身实现不得要求更多。
  */
 interface SyncStorePort {
   /** 目录水位预查(stat 命中免解码的关键);无记录返回 undefined。 */
@@ -548,6 +572,17 @@ interface SyncStorePort {
   }[];
   /** 级联清除一个会话的投影(WAL 事务内 segments/fts/replaces/sessions 四表+常驻 Map)。 */
   deleteSession(sessionId: string): void;
+  /**
+   * R5(v5 字块字典水位):current=blocks 现 max(rowid, 空典=0),
+   * last=上轮持久化值(meta 缺失=0)。current<last=字典被清/换——
+   * hash 引用悬空,stat 命中也不得 skip(防静默缺块)。
+   */
+  blocksWatermark(): {
+    current: number;
+    last: number;
+  };
+  /** 轮尾持久化本轮字典水位(下轮 skip 判定基线)。 */
+  setBlocksWatermark(value: number): void;
 }
 type SyncLog = (level: 'info' | 'warn', message: string, ...args: unknown[]) => void;
 /** DS 精确计数器探测:flash → pro 逐个试;全缺席 undefined(chars/4 降级)。 */