#Trace Index 总体架构

Trace Index 把分散的 Agent Trace 转换为可查询、可溯源、可重建的当前事实。总体架构只规定长期稳定的职责边界：系统怎样观察输入、保存物理证据、建立程序事实、完整发布结果，以及怎样向 Agent 提供查询与全文检索。具体 Runtime 字段、表结构、Relation 名称、命令和模块组织不属于本页。

#从 Trace 到当前事实

一次显式同步完成四项工作：

1. 确定本次允许观察的 Source 范围。
2. 读取范围内的输入，只接纳边界完整的 Record。
3. 根据 Adapter 对原生结构的解释和领域规则，建立受影响的 Session、Loop 与 Item。
4. 验证这些事实及其物理依据，并把完整结果发布给查询者。

Runtime 原生 Trace
      │
      ▼
有界观察 ──► Source / Record ──► Session / Loop / Item ──► 完整发布
                    │                    │                     │
                    └────── 物理溯源 ────┘                     ▼
                                                     直接查询与全文检索

查询只读取已经完整发布的结果。同步正在处理的候选数据、尚未完成的 Session 或仍引用失效证据的 Item 都不能提前暴露。

#有界观察

观察负责回答“本次允许检查什么”和“其中哪些输入已经达到可接纳边界”。同步范围可以是一份 Source，也可以是调用方明确选择的一组输入，但不能默认把全部历史都当作一次工作的必要范围。

只有完整观察一个发现范围，才能据此判断某个既有 Source 已经离开该范围。局部同步、预算耗尽或读取失败都不能证明 Source 消失。无法可靠缩小受影响范围时，系统必须扩大到仍然能够保证正确的上一级范围，而不是发布未经证明的局部结果。

候选位置如何发现、JSONL 怎样读取、Runtime 怎样识别，以及版本分支如何处理，由 Adapter 代码、fixture 和测试维护。

#物理证据

Source 与 Record 保存 Runtime 实际持久化了什么，以及原始内容位于哪里。物理证据层负责来源身份、记录边界、顺序、物理范围和校验依据，不把一条 Record 直接等同于一条消息或一个 Item。

程序事实必须能够通过自身字段返回支撑它的 Record，再由 Record 返回 Source。索引损坏、Adapter 规则升级或领域模型变化后，系统可以从仍然有效的 Source 重建当前事实。

#程序投影

程序投影根据领域模型，把物理 Record 建立为 Session、Loop、Item 及其字段。它只建立来源和模型允许的事实，不推断 Task、意图、偏好、失败根因或内容价值。

物理事实和程序事实的共同规则由 Trace Index 投影模型 定义。具体 Runtime 的原生事件和字段怎样满足这些规则，仍由 Adapter 代码与测试负责。

#完整发布

相互依赖的新事实必须作为一个完整结果对查询者可见。查询者只能看到发布前的完整状态，或者发布后的完整状态，不能看到新 Source 配旧 Record、新 Item 缺少来源，或者目标引用仍指向已经失效对象的混合结果。

一次处理失败时，上一个完整发布结果继续可查询，失败范围必须显式报告。互不依赖的其他结果仍可以成功发布。完整语义见 Trace Index 发布与一致性。

#直接查询领域对象

公共查询直接暴露 Source、Record、Session、Loop、Item 这五类领域对象，不在它们之上再建立一组公共派生 View。一个领域对象有哪些字段、嵌套值和多值属性，由相应领域模型决定；查询层不为了关系型展开而重新定义另一套事实。

例如，Session.source_ids、Item.record_ids 和 ShellToolCall.shell_fragments 都是领域对象内部的多值结构。实现可以在内部使用规范化表、物化结构或 JSON 索引来保证约束和性能，但这些内部结构不是新的公共领域对象。调用方需要展开数组或嵌套值时，可以在查询中按需展开。

精确 Relation 名称、字段序列化、SQL 方言和查询上限是代码接口契约，随实现一起在代码仓库维护。领域文档 只固定“直接查询领域事实”这一稳定边界。

#全文检索

全文检索是必要的访问能力，但不是独立领域模型，也不是公共派生 View。它从 Item 中具有文本含义的内容建立可重建索引，帮助 Agent 先找到候选事实，再回到命中的 Item、所属 Session 与 Loop，以及物理 Record。

搜索结果至少应让调用方知道命中了哪个 Item，以及怎样继续读取该 Item 的上下文和来源。哪些 SemanticRole 进入索引、怎样抽取文字、使用什么 tokenizer、如何排序、怎样生成 snippet，以及索引怎样增量更新，属于代码接口和实现。检索范围必须由接口明确说明，搜索无结果不能被误报成所有原始 Trace 都没有匹配内容。

全文索引可以为了性能物化一份搜索文本，但它仍然是由 Item 重建的访问结构。删除或重建全文索引不会删除 Item，也不会改变领域事实。

#审计与控制

审计沿领域对象已有的物理引用返回 Record、Source 和原始 Trace，并说明相应字段由什么领域规则和 Adapter 解释建立。同步控制限定本次同步范围、资源预算和运行状态。二者都不创造新的程序事实。

#依赖方向

产品边界与设计原则
  └─ 约束五实体领域模型与投影规则
       └─ 约束 Adapter、存储、查询与全文检索实现

新增 Runtime 通常只增加 Adapter 映射，不应迫使共同领域模型按它的字段重新组织。只有真实 Trace 或真实查询证明现有概念无法表达必要事实时，才修改上层模型。

#页面边界

本页不规定 Runtime 文件布局、数据库表、公共 Relation 名称、CLI 命令、全文索引技术、当前支持版本或实现进度。这些知识紧贴代码、测试和机器可读接口维护。