docs(可视化合同): 明确 Ledger Trace 与只读投影边界

文档改为描述真实运行事实来源、历史回放边界、Data 使用边界和可观察 Reasoning。明确界面只读投影持久化记录，不伪造隐藏思维链，也不反向修改 Agent 状态。

visualization/DATA_CONTRACT.md

@@ -1,28 +1,46 @@
-# Fake 数据合同与已知缺口
+# 真实运行可视化数据合同
 
-新版只提供 fake 数据，但顶层字段不使用自创命名。`backend/app/contracts.py` 逐项镜像以下当前源码合同：
+## 事实来源
 
-- Host：`ScriptBuildInputSnapshotV1`、`MissionBinding`、`MissionOwnerToken`、全部 Phase 1/2/3 Artifact、`Publication`、`PublicationResult`、HTTP command journal、旧 `script_build_record`。
-- Agent wire：`TaskView`、`TaskSpecView`、`OperationView`、`AttemptView`、`ValidationView`、`PlannerDecisionView`。
-- 枚举：Build / Task / Attempt / Validation / Artifact / Publication 状态，以及全部 `ScriptTaskKind`。
+后端是只读适配器，不复制 Agent 业务状态，也不向领域模型写入可视化坐标。
 
-每个画布节点的 `record.model_name` 指向其中一个合同，`record.payload` 必须与合同完全同键。后端测试同时拒绝缺键和额外键。
+| 界面信息 | 权威来源 | 证据等级 |
+| --- | --- | --- |
+| Task 树、状态、父子关系、Attempt/Validation/Decision 数量 | `TaskLedger` | 已持久化事实 |
+| Planner 步骤、工具参数、模型主动说明 | Root Planner Trace messages | 已持久化事实 |
+| 某一步后已经出现的 Task | Planner 工具结果累计集合 | 确定性投影 |
+| Worker 工具循环与确认读取 | Worker Trace messages | 已持久化事实 |
+| 冻结输入闭包 | TaskSpec context refs + ScriptTaskContract | 已持久化事实 |
+| Artifact 输出 | Attempt submission | 已持久化事实 |
+| 采用、重试、取消、回退 | PlannerDecision | 已持久化事实 |
 
-## 不能由当前源码进一步约束的字段
+## 历史回放边界
 
-以下字段在业务源码中本身就是开放的 `dict[str, Any]` / JSON，没有更窄的稳定 schema，因此 fake 数据只能保持顶层字段精确，不能声称其嵌套键是产品合同：
+当前 Ledger 只保存最新 Task 状态。因此选择旧 Planner 步骤时：
 
-- `topic`、`account`、`persona_points`、`section_patterns`、`strategies`
-- `prompt_manifest`、`datasource_manifest`、`model_manifest`
-- `query`、`source_lineage`、`change_manifest`
-- Agent `payload`、ArtifactRef `metadata`、HTTP `response_json`
-- Paragraph 的 `content_range` 与各类 `*_elements`
-- Element 的 `commonality_analysis`、`topic_support`、`weight_score`、`support_elements`
+- Task 是否已经出现，按当时 Planner 工具结果累计回放；
+- Task 的状态仍显示当前 Ledger 状态；
+- UI 明示“Planner 工具调用顺序 + 当前 TaskLedger 持久化快照”，不伪造历史状态。
 
-## 接真实数据前仍缺少
+如果以后需要逐 revision 的精确状态回放，应新增 Host 事件投影或 Ledger revision snapshot；不能由前端猜测。
 
-1. Host 面向可视化的只读聚合 API；当前没有一个接口能直接返回 Phase 1→3 的完整闭包和连接关系。
-2. TraceStore 中消息父链、policy migration、owner acquire/release/fence、publication attempt/rollback/commit/readback 的统一脱敏投影。
-3. Candidate Artifact / Validation / Decision 的批量分页读取接口，避免前端逐节点请求。
-4. 对上述开放 JSON 字段的版本化 strict schema。没有这些 schema 时，任何“嵌套字段一模一样”的承诺都不可验证。
+## Data 使用边界
 
+详情中的数据分成四组，不能混称为“模型用过”：
+
+1. `进入 Task 的数据`：在冻结输入闭包或合同中，只能证明可用；
+2. `Worker 确认读取`：Worker Trace 中出现真实 read/get/search/query/inspect 工具调用；
+3. `Task 产生的数据`：Attempt submission 中的 Artifact 引用；
+4. `采用与回退`：PlannerDecision 的实际 action 与 reason。
+
+## Reasoning 边界
+
+`reasoning_content` 在当前真实 Qwen Trace 中可能为空。界面只展示：
+
+- assistant `text`；
+- 工具调用名和参数；
+- 工具结果摘要；
+- Validator recommendation / criterion reason；
+- PlannerDecision reason。
+
+这些是可观察运行证据，不等同于、也不命名为隐藏思维链。