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

package/lib/index.d.ts

@@ -0,0 +1,668 @@
+import { DatabaseSync } from "node:sqlite";
+import { Context } from "@deepseek-ai/cordis";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/session-file-decode.d.ts
+/** 日志的物理编码（对齐宿主的 JsonlCompression 概念）。 */
+type LogCompression = 'zstd' | 'none';
+/** 一份日志产物在磁盘上的事实。 */
+interface LogArtifact {
+  /** 文件名（不含目录）。 */
+  name: string;
+  /** 绝对路径。 */
+  path: string;
+  bytes: number;
+  /** mtime（epoch ms）。 */
+  mtimeMs: number;
+}
+/** 一份规范代次产物。 */
+interface GenerationArtifact extends LogArtifact {
+  /** 该文件承载的格式代次；0 为无版本号的历史代。 */
+  version: number;
+  /** 该文件的物理编码。 */
+  compression: LogCompression;
+}
+/** 一个会话目录的代次事实。 */
+interface SessionGenerations {
+  /** 目录内全部规范产物，按代次升序（同代次再按 mtime 升序）。 */
+  canonical: GenerationArtifact[];
+  /** 当前代 = 规范产物中代次最高的一份；目录内没有规范产物时为 undefined。 */
+  current?: GenerationArtifact;
+  /** 历史代（代次 0）；宿主按契约保留已提交的旧代次，不删不改。 */
+  legacy?: GenerationArtifact;
+  /** 迁移暂存残留（发布源）。 */
+  staging: LogArtifact[];
+  /** 只有历史代、尚无更高代次。 */
+  legacyOnly: boolean;
+}
+/**
+ * 某代次的规范日志文件名。
+ *
+ * 注意：历史代的名字必须**拼接构造**（`'.'` 归入分支串），源码文本中不得
+ * 出现检查器正则的连续字面量（见文件头 D7 纪律）。
+ * @param version - 非负安全整数的格式代次。
+ * @param compression - 物理编码（缺省 zstd）。
+ * @returns 该代次在会话目录内的文件名。
+ */
+declare function generationLogFilename(version: number, compression?: LogCompression): string;
+/**
+ * 读取一个会话目录的代次事实（只读，不碰任何文件内容）。
+ * 目录在枚举与读取之间消失（宿主正在删会话）时如实返回「没有产物」，不抛。
+ * @param dir - 会话目录的绝对路径。
+ * @returns 规范产物（按代次升序）、当前代、历史代与暂存残留。
+ */
+declare function readSessionGenerations(dir: string): SessionGenerations;
+/** 解码后的事件（磁盘存储记录的结构子集；与宿主 SessionEvent 形状兼容但不 import 其类型，保持叶子零依赖）。 */
+interface DecodedEvent {
+  type: string;
+  seq: number;
+  time: number;
+  data?: Record<string, unknown>;
+  surfaceOp?: 'append' | {
+    op: 'replace';
+    start: number;
+    end: number;
+  };
+  sourceEventSeqs?: number[];
+}
+/** 一次读取的统计与问题清单。 */
+interface SessionLogRead {
+  events: DecodedEvent[];
+  /** 完整帧数。 */
+  frames: number;
+  /** 撕裂尾帧起始偏移（无撕裂为 undefined）。 */
+  tornStart?: number;
+  /** 从撕裂尾帧抢救出的明文字节数。 */
+  recoveredFromTorn: number;
+  /** 读取问题（解码失败/seq 缺口），按遇到顺序。 */
+  issues: {
+    line: number;
+    why: string;
+  }[];
+  /** 实际使用的解码器来源。 */
+  decoder: 'official' | 'local';
+  /** 尾部是否仍有未收尾的 open step。 */
+  openStep?: {
+    turn: number;
+    step: number;
+  };
+  /** 日志首行的 header（`type: 'session'` 记录）；首行不是 JSON 时为 undefined。 */
+  header?: Record<string, unknown>;
+}
+/** 官方解码器面（软加载所得）。 */
+interface OfficialDecoders {
+  decodeStorageRecord(value: unknown): DecodedEvent[];
+  decodeSeqRanges(value: unknown, seq: number): number[];
+}
+/**
+ * 解码一个会话日志（zstd 帧扫描 + 撕裂尾帧抢救 + 解包 + seq 连续性）。
+ * @param bytes - 文件内容（调用方读取，便于测试注入与 mtime/size 只读断言）。
+ * @param decoders - 可选官方解码器（缺省用本地等价实现；差异记入 decoder 字段，禁止静默回退）。
+ * @returns 事件、统计与问题清单。
+ */
+declare function decodeSessionLogBytes(bytes: Buffer, decoders?: OfficialDecoders): SessionLogRead;
+/** 从文件读取并解码（只读）。 */
+declare function decodeSessionLogFile(file: string, decoders?: OfficialDecoders): SessionLogRead;
+/** header 代次分类结果：`known` 可回填；其余调用方必须跳过该会话（fail-soft）。 */
+type SessionHeaderVerdict = {
+  readonly state: 'known';
+  readonly version: number;
+} | {
+  readonly state: 'missing-header';
+} | {
+  readonly state: 'not-session';
+} | {
+  readonly state: 'unknown-version';
+  readonly version: unknown;
+};
+/**
+ * 从解码结果的 header 判定格式代次是否可回填。
+ *
+ * 本模块只分类不告警——「跳过该会话 + 恰一条 warn」的裁决属于调用方
+ * （stats-backfill）的责任面，保证叶子模块无副作用。
+ * @param header - decodeSessionLog 结果里的 header（首行不是 JSON 时 undefined）。
+ * @param known - 已知代次集合（缺省 {@link KNOWN_SESSION_FORMAT_GENERATIONS}）。
+ */
+declare function classifySessionHeader(header: Record<string, unknown> | undefined, known?: ReadonlySet<number>): SessionHeaderVerdict;
+//#endregion
+//#region src/projection.d.ts
+/** 精确计数器（tokenizer.countText 的数值臂）；缺席时 chars/4 上界。 */
+type ExactCounter = (text: string) => number;
+/** segments 表一行（snake_case 列名映射在 schema.ts 完成）。 */
+interface ProjectionSegment {
+  seq: number;
+  turn: number;
+  step: number;
+  kind: string;
+  role: string;
+  /** 事件 epoch ms。 */
+  time: number;
+  /** 模型可见文本（CCI 视界）。 */
+  text: string;
+  tokens: number;
+  /** 检索视界（steward 抽取超集）。 */
+  searchText: string;
+  /** 1=当前表面；0=被某 replace 区间覆盖。 */
+  onSurface: 0 | 1;
+  /** 1=本行被替换对覆盖（compressed 标记，R3）。 */
+  compressed: 0 | 1;
+  /** 当前表面上是什么（链解析后的终替文本）；未压缩=null。 */
+  surfaceText: string | null;
+  surfaceTokens: number | null;
+  /** 被谁替换（链解析后的终替事件 seq）；未压缩=null。 */
+  replacedBy: number | null;
+}
+/** replaces 表一行（R4 替换对指针）。 */
+interface ProjectionReplace {
+  seq: number;
+  startSeq: number;
+  endSeq: number;
+  aTokens: number;
+  bTokens: number;
+  kind: 'compress' | 'recall';
+  turn: number;
+  step: number;
+  /**
+   * 1=替身行仍在面（delta 生效）；0=替身已被后续 checkpoint/replace 再覆盖，
+   * delta 清除不入 gross（用户定标 2026-10-20：checkpoint 只影响其后的积分，
+   * 被它吸收的先前对不再重复计费——与 CCI projectSavingsCore 「只算仍在
+   * surface 中的替换节点」同语义）。per-pair a/b 保持原始区间事实不回改。
+   */
+  live: 0 | 1;
+}
+/** sessions 表一行的投影侧字段（watermark/archived 由 sync 侧补写）。 */
+interface SessionSummary {
+  sessionId: string;
+  dirId: string;
+  title: string;
+  cwd: string;
+  eventCount: number;
+  maxSeq: number;
+  turnCount: number;
+  segmentTokens: number;
+  surfaceTokens: number;
+  grossSaved: number;
+  recallTokens: number;
+  compressPairs: number;
+  recallPairs: number;
+  basis: 'ds-token' | 'chars/4';
+  lastTimeMs: number;
+  /** 文件头自声明格式代次（0..4 放行；-1=无 header 版本，理论上不至）。 */
+  formatGeneration: number;
+}
+/** 一次完整投影结果。 */
+interface SessionProjection {
+  summary: SessionSummary;
+  segments: ProjectionSegment[];
+  replaces: ProjectionReplace[];
+}
+/** projectSessionEvents 选项。 */
+interface ProjectionOptions {
+  dirId: string;
+  /** 缺省=dirId（宿主目录名即会话 id 的代次布局）。 */
+  sessionId?: string;
+  /** 日志首行 header（decodeSessionLogBytes 产出），取 cwd/title 元数据。 */
+  header?: Record<string, unknown>;
+  /** 精确计数器；缺省 chars/4 降级并如实标注 basis。 */
+  exactCounter?: ExactCounter;
+  /** 预置标题（steward 式从事件流抽出的最后一帧标题）。 */
+  title?: string;
+}
+/**
+ * 检索视界——steward `extractSessionEventText`（extract.ts:161-199）逐字同构。
+ * @param event - 解码后的一个会话事件。
+ * @returns 换行拼接的检索文本；不可检索事件返回空串。
+ */
+declare function extractSearchEventText(event: DecodedEvent): string;
+/**
+ * 从事件流抽最后一帧标题——steward `extractTitleFromEvents`（extract.ts:28-43）
+ * 同构（形状三兼容：`{title}`、`{title:{title}}`、`{title:{val}}`）。
+ */
+declare function extractTitleFromEvents(events: readonly DecodedEvent[]): string;
+/**
+ * 投影一个会话的全部解码事件（两遍扫描）。
+ * @param events - decodeSessionLogBytes 产出的连续事件流（含 header 后的全部行）。
+ * @param options - 见 {@link ProjectionOptions}。
+ * @returns summary + segments（text/search_text 任一非空才收）+ replaces（R4）。
+ */
+declare function projectSessionEvents(events: readonly DecodedEvent[], options: ProjectionOptions): SessionProjection;
+//#endregion
+//#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";
+/** sessions 表原始行（snake_case 与 DDL 一致）。 */
+interface SessionRow {
+  session_id: string;
+  dir_id: string;
+  title: string;
+  cwd: string;
+  event_count: number;
+  max_seq: number;
+  turn_count: number;
+  segment_tokens: number;
+  surface_tokens: number;
+  gross_saved: number;
+  recall_tokens: number;
+  compress_pairs: number;
+  recall_pairs: number;
+  basis: string;
+  artifact_bytes: number;
+  artifact_mtime_ms: number;
+  last_time_ms: number;
+  format_generation: number;
+  archived: number;
+  synced_at: string;
+}
+/** replaceSession 的产物 watermark 附加项。 */
+interface ReplaceSessionExtra {
+  /** 归档集标志（sync 侧按 workspace.json 只读跟随）。 */
+  archived?: 0 | 1;
+  /** 预置标题（steward 切料同款，缺省用 projection.summary.title）。 */
+  title?: string;
+}
+/** 投影库句柄。 */
+interface ProjectionStore {
+  db: DatabaseSync;
+  /** 缓存层 2：sessions 全表常驻（~百行级），status/sessions 列表 0 SQL。 */
+  summaries: Map<string, SessionRow>;
+  /** 事务式全量重写一个会话；提交后增量更新常驻行。 */
+  replaceSession(projection: SessionProjection, artifactBytes: number, artifactMtimeMs: number, extra?: ReplaceSessionExtra): void;
+  /** 翻转归档旗标（不动投影内容）。 */
+  setArchived(sessionId: string, archived: 0 | 1): void;
+  /**
+   * 级联清除一个会话的全部投影（删除剪枝专用，2026-10-20 用户定标）：
+   * WAL 事务内删 segments/segments_fts/replaces/sessions 四表，提交后摘
+   * 常驻 Map；会话不存在返回 false（幂等，不抛）。投影可重建，删行无损。
+   */
+  deleteSession(sessionId: string): boolean;
+  close(): void;
+}
+/**
+ * 打开（或创建）投影库。
+ * @param dir - 库目录（缺省布局 ~/.dsh-reference-session-collector；env 覆盖在 sync 侧解析）。
+ * @returns {@link ProjectionStore}，已载入 sessions 常驻 Map。
+ */
+declare function openProjectionStore(dir: string): ProjectionStore;
+/** 重新打开时同步常驻 Map（内部工具；openProjectionStore 已在构造时载入）。 */
+declare function reloadSummaries(store: ProjectionStore): void;
+//#endregion
+//#region src/surface.d.ts
+/** 台账 LRU 容量（缓存层 3）。 */
+declare const LEDGER_LRU_CAP = 32;
+/** per-session 台账 LRU：键含 synced_at 代际；get 命中重插尾部。 */
+declare class LedgerCache<T> {
+  private readonly map;
+  hits: number;
+  misses: number;
+  get(key: string): T | undefined;
+  set(key: string, value: T): void;
+  get size(): number;
+  stats(): {
+    entries: number;
+    hits: number;
+    misses: number;
+  };
+}
+/** 一个 store 的查询上下文（持有两类台账 LRU 与计数）。 */
+interface QueryContext {
+  store: ProjectionStore;
+  surfaceLru: LedgerCache<unknown>;
+  recallLru: LedgerCache<unknown>;
+}
+declare function createQueryContext(store: ProjectionStore): QueryContext;
+/** status：库自检 + 缓存统计（spec §HTTP 面）。 */
+declare function status(ctx: QueryContext, lastSync?: unknown): Record<string, unknown>;
+/** sessions 汇总表分页（0 SQL，走常驻 Map；按 last_time_ms 降序）。 */
+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?: {
+  turn?: string;
+  fields?: string;
+}): {
+  session: SessionRow | undefined;
+  rows: unknown[];
+};
+/** surface 台账（R3）：当前表面行 + 被替换指针视图（LRU）。 */
+declare function surfaceLedger(ctx: QueryContext, sessionId: string): Record<string, unknown>;
+/**
+ * 召回对账（R4）：替换对分类 + Σb（回吐）+ Σ(a−b)（毛节省）（LRU）。
+ * 毛节省只计 live=1 的对——替身被后续 checkpoint 再覆盖时 delta 清除（用户定标）。
+ */
+declare function recallReport(ctx: QueryContext, sessionId: string): Record<string, unknown>;
+/** FTS5 BM25 内容搜索（中英同构切词，走 sanitizeFtsQuery）。 */
+declare function search(ctx: QueryContext, query: string, opts?: {
+  session?: string;
+  limit?: number;
+}): {
+  query: string;
+  match: string;
+  hits: Record<string, unknown>[];
+};
+/**
+ * 锤定查询词首次出现的节选（steward buildSnippet 逐字同构移植，
+ * 2026-10-20）：短文本直返；命中词居中开窗；无锚点退化为头部截断。
+ */
+declare function buildSearchSnippet(text: string, query: string, max?: number): string;
+/** 分组搜索请求（与 steward engine.search 入参同形；kinds 为原事件 type 列表）。 */
+interface GroupedSearchRequest {
+  query: string;
+  /** 允许的原事件 type（已由调用方展开粗类）；缺省= user+assistant（steward resolveTypes 同标）。 */
+  kinds?: readonly string[];
+  /** 检索域：'active' 仅活跃、'archived' 仅归档、缺省 'all'。 */
+  archived?: 'active' | 'archived' | 'all';
+  /** 会话末事件时间下界（epoch ms，含）。 */
+  from?: number;
+  /** 上界（排他）。 */
+  to?: number;
+  /** true（缺省）=仅当前表面行（on_surface=1，steward surface='current' 同款）。 */
+  surfaceOnly?: boolean;
+  /** 排序：缺省 relevance；'time'=会话 updated_at 降序、分数平手。 */
+  sortBy?: 'relevance' | 'time';
+  limit?: number;
+}
+/** 分组命中（wire 蛇形，会话级最强命中）。 */
+interface GroupedSearchHit {
+  session_id: string;
+  title: string;
+  seq: number;
+  type: string;
+  time: number;
+  updated_at: number;
+  snippet: string;
+}
+/**
+ * 会话分组全文搜索（op=search&group=session）：BM25 候选窗 → 按会话取
+ * 加权最强命中 → 排序分页。数学/视界与 steward engine.search 逐字同构：
+ * score = −rank × weight(type)，时间排序键是会话 updated_at（非命中 time）。
+ */
+declare function searchGrouped(ctx: QueryContext, request: GroupedSearchRequest): {
+  query: string;
+  hits: GroupedSearchHit[];
+};
+//#endregion
+//#region src/segment.d.ts
+/**
+ * ⚠ 同构移植（回搬件）——检索切分视界源自 dsh-session-steward
+ *   `src/host/index/extract.ts:62-95`（SEGMENTER/segmentForIndex/segmentQueryTerm）
+ *   与 `src/host/index/engine.ts:83-95`（sanitizeFtsQuery），回搬时点 2026-10-19。
+ *   回搬纪律：**逐字同构，禁止分叉**；索引侧与查询侧必须共用本文件的同一
+ *   切分函数（spec 决策「CJK 分词=DRS 自带 Intl.Segmenter 切分」）。
+ *   唯一非授权差异：导出面去掉 steward 内部类型耦合（行为零差异）。
+ */
+/**
+ * Space-separate word boundaries so the FTS5 unicode61 tokenizer indexes
+ * words instead of whole CJK runs: the index and query sides must apply the
+ * exact same segmentation for a token to meet its match.
+ * @param text - raw extracted text (or a query term).
+ * @returns text with a single space at every word boundary.
+ */
+declare function segmentForIndex(text: string): string;
+/**
+ * Segment one whitespace-delimited query term into FTS5 phrase tokens.
+ * @returns word-like segments, or the raw term when segmentation is unavailable.
+ */
+declare function segmentQueryTerm(term: string): string[];
+/**
+ * Sanitize free text into a safe FTS5 query over the segmented index: each
+ * whitespace term is segmented into word tokens, quoted as an adjacent
+ * phrase, and the last token carries a prefix `*` so partial input matches
+ * ("正在搜" hits 正在搜索). Terms AND together.
+ */
+declare function sanitizeFtsQuery(query: string): string;
+//#endregion
+//#region src/strip-injected.d.ts
+/**
+ * 宿主注入样板段剥离（检索视界专用，2026-10-20 真机取证定标）。
+ *
+ * 背景：user/message 原文头部含宿主注入的成对标记段（记忆召回/人格/工具指南/
+ * 场景导航/系统提醒/技能指令）。真机统计（46 会话/3100 条用户消息）：1210 条
+ * （39%）含注入段，标记全集七类——这些段落随原文进了 search_text 后成为检索
+ * 污染主因：关键词命中在用户没写过的注入样板里，节选与正文对不上。
+ *
+ * 纪律：**只作用于 search_text（检索面），绝不作用于 text/tokens**——后者是
+ * CCI verify 同口径视界（savings-verify 对 message.content 全文计数），
+ * 剥离会破坏对账数学（spec R5）。
+ * 只剥**完整成对**标记段；未闭合（撕裂尾行）原样保留，不伪造丢失。
+ */
+/** 注入标记全集（真机 tagscan 实测，按出现频降序）。 */
+declare const INJECTED_BLOCK_TAGS: readonly string[];
+/**
+ * 剥离一段文本里的全部注入样板块。
+ * @param text - 原始检索文本（任意事件视界产出均可过）。
+ * @returns 剥离并重整空白后的文本；无注入块时与原串仅可能差在首尾空白。
+ */
+declare function stripInjectedBlocks(text: string): string;
+//#endregion
+//#region src/token-count.d.ts
+/**
+ * ⚠ VENDORED（回搬件）——源自 dsh-context-compression-improved
+ *   `packages/selector/src/runtime/token-count.ts`，回搬时点 2026-10-19。
+ *   回搬纪律：**文件级拷贝，禁止分叉**；与源文件逐字节一致，无授权 diff。
+ */
+/** Token counts owned by the standalone compression runtime. */
+/** Exact count of one canonical value under a pinned tokenizer artifact. */
+interface ExactTokenizerTokenCount {
+  readonly kind: 'exact-tokenizer';
+  readonly tokens: number;
+  readonly tokenizerId: string;
+  readonly tokenizerRevision: string;
+}
+/** A value that the bundled tokenizer cannot safely count. */
+interface UnavailableTokenCount {
+  readonly kind: 'unavailable';
+  readonly reason: string;
+}
+/** Best-effort estimate carrying a conservative upper value when available. */
+interface TokenizerEstimateTokenCount {
+  readonly kind: 'tokenizer-estimate';
+  readonly tokens: number;
+  readonly upperBoundTokens: number;
+  readonly estimatorId: string;
+  readonly estimatorRevision: string;
+  readonly calibration?: Readonly<{
+    readonly sampleCount: number;
+    readonly conservativeMarginTokens: number;
+  }>;
+}
+/** Exact, conservative request estimate, or an explicit refusal. */
+type TokenCount = ExactTokenizerTokenCount | TokenizerEstimateTokenCount | UnavailableTokenCount;
+/** Bound exact text counter for one durable provider/model request target. */
+type CanonicalTextTokenCounter = (text: string) => TokenCount;
+//#endregion
+//#region src/sync.d.ts
+/** 一个会话目录的发现事实:目录名 + 当前代产物。 */
+interface DiscoveredSessionLog {
+  dirSessionId: string;
+  dir: string;
+  artifact: GenerationArtifact;
+}
+/** 单轮发现的目录上限(walk 兜底,防异常目录树拖死主线程)。 */
+declare const DISCOVERY_LIMIT = 5000;
+/**
+ * 走 `~/.dsh/sessions` 发现会话目录(与 CCI discoverBackfillSessionLogs 同构):
+ * 目录内无任何代次产物与暂存残留 → 视为路径中间层继续下钻;有当前代产物 →
+ * 收录。上限截断,不抛。
+ */
+declare function discoverSessionLogs(dshHome: string, limit?: number): DiscoveredSessionLog[];
+/** DSH home 解析:显式入参 > DSH_HOME 环境变量 > ~/.dsh。 */
+declare function resolveDshHome(explicit?: string, env?: NodeJS.ProcessEnv): string;
+/** 投影库目录解析:显式入参 > DSH_REFERENCE_SESSION_COLLECTOR_DIR > ~/.dsh-reference-session-collector。 */
+declare function resolveIndexDir(explicit?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * 读归档会话 id 集:~/.dsh/storages/workspace.json 的
+ * `global.archivedSessionIds`。任何形状不符/文件不可读 → 空集(无归档),
+ * 绝不抛——归档只是检索域标志,不配阻塞同步。
+ */
+declare function readArchivedSessionIds(dshHome: string): ReadonlySet<string>;
+/** 投影核心调用选项(与 L1 projectSessionEvents 第二参逐字对齐)。 */
+interface ProjectionCallOptions {
+  dirId: string;
+  header?: Record<string, unknown>;
+  exactCounter?: CanonicalTextTokenCounter;
+}
+/**
+ * 投影端口:同步引擎把解码事件交给投影核心,产物对 sync 不透明
+ * (由 store 端口解释)。L1 落地后由 index.ts 绑定 projectSessionEvents。
+ */
+type ProjectionPort = (events: readonly DecodedEvent[], options: ProjectionCallOptions) => unknown;
+/** sync 关心的 store 水位行(真身 schema 的窄投影)。 */
+interface SyncWatermark {
+  sessionId: string;
+  artifactBytes: number;
+  artifactMtimeMs: number;
+  archived: number;
+}
+/** replaceSession 附带元数据:水位 + 本轮归档态。 */
+interface SyncReplaceMeta {
+  artifactBytes: number;
+  artifactMtimeMs: number;
+  archived: number;
+}
+/**
+ * 投影库端口。真身 = schema.ts 的 ProjectionStore(L1);单测注入内存 mock。
+ * 五个方法恰好是 sync 需要的全部写/读面——真身实现不得要求更多。
+ */
+interface SyncStorePort {
+  /** 目录水位预查(stat 命中免解码的关键);无记录返回 undefined。 */
+  getSessionByDir(dirId: string): SyncWatermark | undefined;
+  /** 全会话重写式落库(事务内 DELETE+INSERT,真身职责);projection 不透明。 */
+  replaceSession(projection: unknown, meta: SyncReplaceMeta): void;
+  /** 仅翻归档旗标(stat 命中的会话随归档集变更走这里,免解码)。 */
+  setSessionArchived(sessionId: string, archived: number): void;
+  /** 已投影名册枚举(删除剪枝对照面):dirId=发现键,sessionId=删除键。 */
+  listProjectedDirs(): {
+    dirId: string;
+    sessionId: string;
+  }[];
+  /** 级联清除一个会话的投影(WAL 事务内 segments/fts/replaces/sessions 四表+常驻 Map)。 */
+  deleteSession(sessionId: string): void;
+}
+type SyncLog = (level: 'info' | 'warn', message: string, ...args: unknown[]) => void;
+/** DS 精确计数器探测:flash → pro 逐个试;全缺席 undefined(chars/4 降级)。 */
+declare function resolveExactCounter(): CanonicalTextTokenCounter | undefined;
+/** 长度口径:ds-token=精确词表;chars/4=如实降级;unprobed=本轮未探测(busy 空转)。 */
+type SyncBasis = 'ds-token' | 'chars/4' | 'unprobed';
+interface SyncFailure {
+  sessionId: string;
+  error: string;
+}
+interface SyncSoftSkip {
+  sessionId: string;
+  state: string;
+}
+interface SyncResult {
+  ok: boolean;
+  /** true=本轮撞上 syncing 旗标,直接返回(不计入进度)。 */
+  busy: boolean;
+  totalDiscovered: number;
+  updated: number;
+  skipped: number;
+  softSkips: SyncSoftSkip[];
+  failures: SyncFailure[];
+  /**
+   * 本轮被删除剪枝的 sessionId 列表:宿主删会话=磁盘目录消失,投影绝不
+   * 留陈旧行(真身 deleteSession 走 WAL 事务级联清四表)。守护条件见
+   * syncAll 剪枝段——sessions 根缺失或发现截断时**不动手**。
+   */
+  pruned: string[];
+  basis: SyncBasis;
+  durationMs: number;
+}
+interface ProjectionSyncOptions {
+  store: SyncStorePort;
+  project: ProjectionPort;
+  /** 缺省 console.warn 单臂(info 静默——宿主半另有 logger 接线面)。 */
+  log?: SyncLog;
+  /** 'auto'(缺省)=探测 DS 精确计数器;'off'=强制 chars/4(单测/省资产加载)。 */
+  counter?: 'auto' | 'off';
+}
+declare class ProjectionSync {
+  private readonly store;
+  private readonly project;
+  private readonly log;
+  private readonly counterMode;
+  private syncing;
+  private lastResult;
+  /** 软跳 warn 一次性:sessionId+state 为键,重复轮不再刷屏。 */
+  private readonly warnedSoftSkips;
+  constructor(options: ProjectionSyncOptions);
+  get isSyncing(): boolean;
+  /** 最近一轮完整结果(busy 空转轮不覆盖它);POST sync 响应体用它。 */
+  get lastSyncResult(): SyncResult | undefined;
+  /**
+   * 一轮增量同步:发现 → 逐会话(水位预查/软跳/投影/落库/让路)。
+   * 重入直接返回 busy(不排队——下一轮 interval 自然补上)。
+   */
+  syncAll(input?: {
+    dshHome?: string;
+    limit?: number;
+  }): Promise<SyncResult>;
+  private syncOne;
+}
+/** interval 轮缺省周期:steward 二期新鲜度(≤1 分钟)靠它,不靠手动 POST。 */
+declare const DEFAULT_SYNC_INTERVAL_MS = 30000;
+declare const SYNC_INTERVAL_ENV = "DSH_REFERENCE_SESSION_COLLECTOR_SYNC_INTERVAL_MS";
+/** 解析轮询周期:env 缺省 30s;0=关闭(纯手动);非法值回落缺省。 */
+declare function resolveSyncIntervalMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * interval 的目标面:结构最小型(单测可注返回部分结果的 mock;真身
+ * ProjectionSync 的 syncAll 结构兼容)。轮内只调用、不解读结果。
+ */
+interface IntervalSyncTarget {
+  syncAll: (input?: {
+    dshHome?: string;
+    limit?: number;
+  }) => Promise<unknown>;
+}
+/**
+ * 启动 interval 同步,返回 dispose(清定时器)。
+ * 轮与启动首轮/syncing 旗标不并发:syncAll 撞旗标返回 busy,无害。
+ * 周期 0(或负/非法)→ 不建定时器,dispose 为空操作。
+ */
+declare function startIntervalSync(target: IntervalSyncTarget, options?: {
+  intervalMs?: number;
+}): () => void;
+//#endregion
+//#region src/index.d.ts
+/** 本插件声明的宿主服务（唯一声明；webStartup 走 ctx.get 回退臂）。 */
+declare const inject: string[];
+/** API 路由前缀（fenced 单条）。 */
+declare const DRS_API_PATH = "/api/dsh-reference-session-collector";
+/** 启动首轮同步延迟（ms）——让路给宿主冷启动。 */
+declare const BOOT_SYNC_DELAY_MS = 2500;
+/** sync 端口 → ProjectionStore 真身适配（dir 水位经常驻 Map 扫描）。 */
+declare function createStorePort(store: ProjectionStore): SyncStorePort;
+/** 请求处理依赖（导出面便于路由单测直调）。 */
+interface DrsHandlerDeps {
+  query: QueryContext;
+  sync: {
+    syncAll: () => Promise<unknown>;
+    lastSyncResult: unknown;
+    isSyncing: boolean;
+  };
+  trustedHosts?: readonly string[];
+}
+/**
+ * op 分发：GET `?op=…`；POST `{op:'sync'}` 触发后台同步。
+ * 未知 op / 缺参 → 400（不留空壳）。
+ */
+declare function handleDrsRequest(deps: DrsHandlerDeps, req: IncomingMessage, res: ServerResponse): Promise<void>;
+/**
+ * 插件主体：开库 → 装配 sync（启动延迟首轮 + interval 轮）→ 双通道注册路由。
+ * @param ctx - host 插件上下文（webServer 声明注入；webStartup/webRuntime 回退臂）。
+ */
+declare function apply(ctx: Context): void;
+//#endregion
+export { BOOT_SYNC_DELAY_MS, DEFAULT_SYNC_INTERVAL_MS, DISCOVERY_LIMIT, DRS_API_PATH, type DecodedEvent, DrsHandlerDeps, type ExactCounter, type GroupedSearchHit, type GroupedSearchRequest, INJECTED_BLOCK_TAGS, LEDGER_LRU_CAP, LedgerCache, PROJECTION_SCHEMA_VERSION, type ProjectionOptions, type ProjectionPort, type ProjectionReplace, type ProjectionSegment, type ProjectionStore, ProjectionSync, type QueryContext, SYNC_INTERVAL_ENV, type SessionLogRead, type SessionProjection, type SessionRow, type SessionSummary, type SyncResult, type SyncStorePort, apply, buildSearchSnippet, classifySessionHeader, createQueryContext, createStorePort, decodeSessionLogBytes, decodeSessionLogFile, discoverSessionLogs, extractSearchEventText, extractTitleFromEvents, generationLogFilename, handleDrsRequest, inject, listSessions, openProjectionStore, projectSessionEvents, readArchivedSessionIds, readSessionGenerations, recallReport, reloadSummaries, resolveDshHome, resolveExactCounter, resolveIndexDir, resolveSyncIntervalMs, sanitizeFtsQuery, search, searchGrouped, segmentForIndex, segmentQueryTerm, sessionDetail, startIntervalSync, status, stripInjectedBlocks, surfaceLedger };