Trace v0.1（draft）

Trace 是运行时的唯一事实来源：动画、计数器、重放、测试、审计都从它派生。存储格式：JSONL（开发/调试）或二进制（生产）；语义相同。

1. 事件模型

type Trace = {
  version: 1;
  run_id: string;
  net_id: string;
  program_hash: string;        // 源/字节码 hash
  start_ts: string;            // ISO 8601
  end_ts?: string;
  config: {
    mode: "deterministic" | "parallel" | "replay";
    workers: number;
    seed?: number;
    determinism: "ephemeral" | "at-least-once" | "exactly-once-effects" | "strict";
  };
  events: Event[];
  final_hash?: string;
};

type Event = StepEvent | EffectEvent | RemoteEvent | CheckpointEvent | ErrorEvent;

type StepEvent = {
  type: "step";
  seq: number;                 // 单调递增；从 0 开始
  ts: string;
  node?: string;
  worker?: number;
  redex: [CellId, CellId];     // 或 multiport 的 CellId[]
  rule: string;
  before: string;              // net hash
  after: string;
  delta?: NetDelta;            // 大网时用 delta 代替快照
  cost?: Cost;
};

type EffectEvent = {
  type: "effect";
  seq: number;
  ts: string;
  job_id: string;              // 稳定：hash(net_prefix, cell, request, attempt)
  phase: "request" | "done" | "fail" | "cancel" | "retry";
  op: string;                  // "llm" | "http" | "tool" | "human"
  input_hash: string;
  output_hash?: string;
  output?: unknown;            // 可配置：明文/密文/引用
  provider?: string;           // "openai" | "anthropic" | "mock" ...
  model?: string;
  cost?: Cost;
  error?: { code: string; message: string; retryable: boolean };
  attempt?: number;
};

type RemoteEvent = {
  type: "remote";
  seq: number;
  ts: string;
  wire: string;                // wire id
  from: string;                // node
  to: string;
  msg_seq: number;
  payload_hash: string;
  bytes: number;
};

type CheckpointEvent = {
  type: "checkpoint";
  seq: number;
  ts: string;
  snapshot_ref: string;        // 内容寻址；外部存储
  effect_offset: number;       // 已包含的 effect seq
  cells: number;
  bytes: number;
};

type ErrorEvent = {
  type: "error";
  seq: number;
  ts: string;
  code: string;                // "E-DEADLOCK" | "E-BUDGET" | ...
  message: string;
  cell?: CellId;
  recoverable: boolean;
};

type NetDelta = {
  add_cells: Cell[];
  remove_cells: CellId[];
  add_wires: Wire[];
  remove_wires: { a: PortRef; b: PortRef }[];
  free?: PortRef[];
};

type Cost = {
  interactions?: number;
  input_tokens?: number;
  output_tokens?: number;
  usd?: number;
  latency_us?: number;
};

2. 顺序与因果

seq 是全序：单节点按实际发生顺序；多节点用 Lamport 时钟/协调者分配（v1 可由 control plane 分配，开销可接受）。
effect.seq 与 step.seq 共享同一序列空间；重放时按 seq 执行。
因果：job_id 关联 request/done；trace_id 关联 agent 的多个 effect；parent_seq（可选）指向触发它的 step。
并发独立事件可以交换；trace 保留实际顺序，便于调试，但不作为语义依赖（纯子集）。

3. 哈希链

每个 StepEvent 的 before/after 是网 hash。
after 必须等于下一条 step 的 before（同一 net）；effect/remote 不改变网 hash（它们改变 pending/queue 状态）。
可选：event_hash = sha256(prev_hash || canonical_json(event))，形成不可篡改日志（strict 模式）。
重放校验：每步比较 after；不一致 → E-REPLAY-DIVERGENCE，dump diff。

4. 存储

形态	用途	说明
JSONL	开发/小网	一行一个事件；人类可读；gzip 可选
Binary	生产	protobuf/postcard；delta 编码；zstd
Snapshot	检查点	完整 `Net` + 元数据；内容寻址
Object store	长期	按 `run_id/date` 分区；保留策略

体积控制：

小网（< 10k cells）可存 full snapshot；大网用 delta。
每 N 步（默认 1000）或每 M 秒（默认 30s）存 checkpoint；trace 只保留自上一个 checkpoint 的 delta + 指针。
采样：高频纯 step 可降采样（只保留每 k 步），但 effect/remote/error 不采样。

5. 重放

ain replay --trace run.jsonl --until seq=5000
ain replay --checkpoint cp-123 --wal wal-123 --verify

语义：

加载初始快照/checkpoint。
按 seq 处理事件：
- step：按 redex+rule 点火；校验 after。
- effect：request 时创建 pending；done/fail 注入记录的结果（不调用 provider）。
- remote：按 msg_seq 注入；重复丢弃。
- checkpoint：可选校验快照 hash。
结束：比较 final_hash；输出报告。

保证：

同 trace 必同结果（给定相同代码/规则版本）。
代码/规则变更后，旧 trace 可能无法重放（program_hash 不匹配）；提供迁移/失效标记。
Effect 结果按记录注入，所以 LLM 非确定性不影响重放；但"重新调用会得到不同结果"是事实，文档必须说清楚。

6. 隐私与安全

output 可配置：
- full：明文（开发）。
- hash：只存 hash（默认生产）。
- encrypted：密文 + KMS key id。
- ref：对象存储引用（带租户前缀/ACL）。
input_hash 总是存；input 默认不存（避免 prompt 泄漏）。
审计模式可存完整输入/输出，但需显式开启 + 保留策略。
Trace 访问受租户/角色控制；导出需审批（企业版）。

7. 示例（JSONL）

{"type":"step","seq":0,"ts":"2026-11-10T12:00:00.000Z","redex":["c1","c2"],"rule":"gamma_gamma","before":"sha256:a1","after":"sha256:b2","cost":{"interactions":1}}
{"type":"effect","seq":1,"ts":"2026-11-10T12:00:00.010Z","job_id":"j-7f","phase":"request","op":"llm","input_hash":"sha256:c3","provider":"mock","model":"mock-fast","attempt":1}
{"type":"effect","seq":2,"ts":"2026-11-10T12:00:00.120Z","job_id":"j-7f","phase":"done","op":"llm","input_hash":"sha256:c3","output_hash":"sha256:d4","output":{"text":"..."},"cost":{"input_tokens":120,"output_tokens":80,"usd":0.0004}}
{"type":"step","seq":3,"ts":"2026-11-10T12:00:00.121Z","redex":["c3","c4"],"rule":"Researcher_Thinking__LLM_Response","before":"sha256:b2","after":"sha256:e5","cost":{"interactions":1}}

8. 版本与兼容

version: 1。
新增事件类型/可选字段 → minor；改变字段语义/删除 → major。
运行时对未知事件类型：跳过并警告（向前兼容）；对未知 major：拒绝。
测试向量：tests/golden/trace/*.jsonl；任何变更必须更新。

在 GitHub 编辑本文