{"_id":"@buddhilive/dsh-session-query","name":"@buddhilive/dsh-session-query","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-session-query","description":"Combined session query service contract with concrete reads, traces, and filters","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/session-query/session-query"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@buddhilive/dsh-brand":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-session-title":"^0.1.2-alpha.3","@buddhilive/dsh-session-persistence":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection-cache":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-tool-todo":"^0.1.2-alpha.3"},"peerDependenciesMeta":{"@buddhilive/dsh-session-persistence":{"optional":true},"@buddhilive/dsh-session-projection":{"optional":true},"@buddhilive/dsh-session-projection-cache":{"optional":true}},"devDependencies":{"@buddhilive/dsh-brand":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-tool-todo":"^0.1.2-alpha.3","@buddhilive/dsh-session-title":"^0.1.2-alpha.3","@buddhilive/dsh-session-persistence":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection-cache":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3"},"_id":"@buddhilive/dsh-session-query@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-i/K/t3uBoZuFWRrwFeumd6IozPgtamdISe3Rm6q9p9dVIarSapAm59Qv0crkhS9p8l52RcNL4A0JmyeCSP1DZA==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-session-query-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-session-query-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-i/K/t3uBoZuFWRrwFeumd6IozPgtamdISe3Rm6q9p9dVIarSapAm59Qv0crkhS9p8l52RcNL4A0JmyeCSP1DZA==","shasum":"b892a496091d02b164521ac73f93d81b6d649a9d","tarball":"https://registry.npmjs.org/@buddhilive/dsh-session-query/-/dsh-session-query-0.1.2-alpha.3.tgz","fileCount":19,"unpackedSize":103171,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCwPPM/wJnBXzmQ/CotylpF1teKD95aw/aQ0aiN24PhYwIhAI7mqKr8o2l65lF8cQ5Rpen+rroKTyqbla85IDAGCMKe"}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-session-query_0.1.2-alpha.3_1788165431122_0.43964292935825044"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:37:10.901Z","0.1.2-alpha.3":"2026-08-31T08:37:11.284Z","modified":"2026-08-31T08:37:11.688Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Combined session query service contract with concrete reads, traces, and filters","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/session-query/session-query"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"面向消费方与后端作者的统一会话历史查询服务：对实时与持久会话日志的精确读取、关系追踪与提供方无关过滤。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-session-query\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-session-query` 为代码调用方提供检索会话历史的唯一服务：读取完整原始日志、列出并过滤会话、折叠标题、读取带边界上下文的事件、追踪会话血缘与事件关系，并执行全文搜索。实时会话优先于持久化会话，且返回的每条记录都是脱离存储的克隆，因此结果始终描述同一一致时刻。精确读取、过滤与追踪为内置行为；全文搜索来自挂载的后端，已发布实现为 `dsh-session-query-sqlite`。当你需要以编程方式访问模型所看到的内容时，直接从代码使用它。设置与用法在前；实现内部细节放在下方可折叠的开发者章节中。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n当你需要读取或搜索会话历史、而不直接触碰会话服务或存储后端时，从应用代码使用 `ctx.sessionQuery`。该服务由具体后端插件提供——已发布组合挂载 `@buddhilive/dsh-session-query-sqlite`（[README](../session-query-sqlite/README.zh.md)）——因此本包从不单独挂载。一旦组合了后端，以下全部能力都可在 `ctx.sessionQuery` 上使用。\n\n### 你可以做什么\n\n| 操作 | 你得到什么 |\n|---|---|\n| `listSessions()` | 每个逻辑会话，最新的在前，带 `live` 与 `persisted` 可用性标志 |\n| `readSession(id)` | 经过回放校验的完整原始事件日志，且不会让该会话变为实时 |\n| `filterSessions(filters)` | 匹配 AND 连接的元数据与可用性谓词的会话 |\n| `filterEvents(id, filters)` | 匹配元数据与字面文本谓词的语义事件文档 |\n| `readTitleSnapshots(ids)` | 每个会话的最新折叠标题，绑定到其来源 header |\n| `listEvents(id)` / `readSurface(id)` | 轻量逐事件记录，或完整的当前模型表层 |\n| `readEvent(request)` | 一个完整事件加其周围有界的原始日志窗口 |\n| `traceSession(id)` | 已知祖先链与递归后代树 |\n| `traceEvent(request)` | 一个事件的位置替换与被引用源事件关系 |\n| `searchSessions(request)` / `searchEvents(request)` | 全文搜索分页结果，由挂载的后端实现 |\n\n### 过滤器\n\n`SessionResultFilter` 按 id、可空 cwd、创建时间范围、可空父级或来源可用性缩小会话范围；`SessionEventResultFilter` 按 seq/时间范围、事件类型、表层或字面文本缩小事件范围。过滤器数组使用 AND 连接，同一子句内的列表值使用 OR；空列表值不匹配任何内容，范围包含端点，格式错误的范围或未知的封闭联合值以 `SESSION_QUERY_INVALID_FILTER` 失败。\n\n文本子句是对所提取语义文本的字面、不区分大小写、空白灵活的扫描——而非全文查询。需要任意子字符串召回时使用它；需要排序后的全文结果时使用挂载后端的搜索方法。\n\n### 配置\n\n两个继承的旋钮通过挂载后端的配置设置：\n\n| 字段 | 默认值 | 含义 |\n|---|---|---|\n| `readWindowMax` | `50` | `readEvent` 接受的 `before`/`after` 原始事件数上限 |\n| `persistedInspectConcurrency` | `4` | 一次批量标题读取中的并发持久化日志检查数 |\n\n### 失败与恢复\n\n失败带有稳定的 `SessionQueryError.code` 类型。你会遇到的包括：id 不存在时 `SESSION_QUERY_SESSION_NOT_FOUND`；同一会话的实时与持久化观察在不可变 header 上不一致时 `SESSION_QUERY_SOURCE_CONFLICT`；已挂载持久化不可读时 `SESSION_QUERY_PERSISTENCE_FAILED`；持久化记录未通过 Session 校验时 `SESSION_QUERY_CORRUPT_SESSION`；加载的日志破坏表层约定时 `SESSION_QUERY_INVALID_SURFACE`。针对已知实时会话的读取从不查询持久化，因此后端故障不会让当前内存历史变得不可读。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释服务背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。\n\n### 设计理念\n\n本服务建立在一个分离与三项承诺之上：\n\n- **实时优先的逻辑语料库。** 每次读取都解析一个一致的观察：实时 `ctx.sessions` 优先，可选的 `ctx.sessionPersistence` 补充其余部分，冲突的不可变 header 宁可失败也不合并。\n- **脱离存储的结果。** 所有返回的 header、事件与记录都是克隆；不暴露实时状态，也不保留订阅。\n- **精确读取具体，搜索抽象。** 读取、过滤与追踪在此只实现一次；两个全文方法是由后端拥有的唯一抽象表面。\n- **一次规范的表层折叠。** `listEvents`、`readSurface` 与 `traceEvent` 使用同一个 `dsh-session` 折叠校验整个日志，因此搜索与追踪和模型历史推导一致。\n\n决策历史记录在[统一服务决策](../../../.agents/notes/archived/architecture/2026-07-23-unified-session-query-service.md)、[追踪笔记](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md)与 [SQLite 提供方笔记](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md)中。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 服务定义：抽象 `SessionQueryEngine`、具体读取、配置校验 |\n| [`src/corpus.ts`](src/corpus.ts) | 实时优先的语料库解析、可选持久化绑定、批量投影 |\n| [`src/types.ts`](src/types.ts) | 公共记录、过滤器、请求与分页类型 |\n| [`src/config.ts`](src/config.ts) | 继承配置与封闭的 `SessionQueryError` 分类体系 |\n| [`src/filters.ts`](src/filters.ts) | 提供方无关谓词与字面文本扫描 |\n| [`src/extraction.ts`](src/extraction.ts) | 按事件类型的第一方语义文本提取 |\n| [`src/documents.ts`](src/documents.ts) | 表层感知的语义文档投影 |\n| [`src/tracing.ts`](src/tracing.ts) | 一次性会话血缘与事件关系追踪 |\n| [`src/sources.ts`](src/sources.ts) | 不可变 header 兼容性检查 |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；结果均为按调用投影） |\n\n### 语料库解析\n\n`SessionCorpus` 通过 fiber 绑定可选的 `ctx.sessionPersistence`，并实时优先解析每次读取：已知实时目标直接快照，不查询持久化；否则先列出会话，再以不修改日志的方式检查，并在克隆前重新检查是否出现实时挂载。列表与加载观察之间会断言 header 兼容性。批量标题读取执行一次元数据列表与有界并发检查，把逐会话失败隔离，而取消会拒绝整个批次。\n\n### 读取与追踪\n\n`readSession` 通过 `Session.create` 回放日志，复用恢复的校验。`readSurface`、`listEvents` 与 `traceEvent` 共用一次 `foldSurface` 遍历，把事件分类为 `current`、`shadowed` 或 `log-only`，并校验从零开始且连续的 seq、表层标记的适用性以及替换或引用完整性；任何违规都以 `SESSION_QUERY_INVALID_SURFACE` 失败。追踪是一次性的：会话血缘只读取一次语料库并确定性遍历父级与后代树；事件追踪沿位置替换者跟进到最终节点，同时保持被引用源事件链接不传递。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面。它们从共享查询词汇逐步进入具体后端与决策证据。\n\n- [会话查询子系统参考](../../../docs/subsystems/session-query.zh.md)——完整类型级约定：记录、过滤器、搜索页、血缘、有界读取与错误。\n- [dsh-session-query-sqlite](../session-query-sqlite/README.zh.md)——已发布的全文后端及其索引生命周期。\n- [dsh-tool-session-query](../tool-session-query/README.zh.md)——构建在本服务之上的面向模型消费方。\n- [会话查询关系追踪](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md)——追踪语义与校验边界。\n- [SQLite FTS5 会话搜索](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md)——搜索表面如何实现与对账。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n无，因为该可信查询服务只向调用方返回克隆记录，且不注册任何面向模型的内容。\n\n#### KV Cache 影响\n\n无；本包既不组装也不发送提供方请求。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明本包何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。\n\n- **无调用方授权**——这是上下文范围内的可信基础设施；模型工具或 UI 必须限制调用方可检查的会话。\n- **无提供方协调器或回退**——服务在搜索上是抽象的，组合必须挂载具体后端；没有搜索提供方注册表或回退实现。\n- **精确读取回放整个日志**——`readSession`、`readSurface`、`filterEvents` 与事件追踪会加载并校验完整逻辑日志，因此非常大的历史每次调用都要付出完整检查；`listSessions` 保持轻量。\n- **字面文本扫描，而非全文搜索**——`text` 过滤器用正则表达式扫描提取出的文档且不排序；排序搜索需要挂载后端。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n本开发备注是维护者的工作上下文：开放设计问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文、包代码和相关 Agent Note 为准。\n\n#### 未来：提取器与搜索提供方注册表\n\n对被引用源事件的递归遍历、提取器与搜索提供方注册表以及更多面向模型表面均被推迟；[面向模型的工具笔记](../../../.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md)记录了当前的消费方表面。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-59241dcd73dff8a98cd5d977467eca86"}