# AGENTS.md - 八字时辰时间轴契约

## 目录用途

本目录定义 FateCat 时辰时间轴的机器语义：point、window、frame、transition、track、typed value、cursor 与失败类型。它不实现历法算法，也不保存运行态结果。

## 目录结构

```text
timeline/
├── AGENTS.md
├── README.md
├── proof-coverage.json
├── field-system.json
├── track-registry.json
├── schemas/              # Draft 2020-12 请求、响应、值和错误契约
└── examples/             # 脱敏正例、边界表和必须被拒绝的负例
```

## 职责边界

- 主行恒为半开时辰帧 `[effectiveStart, effectiveEnd)`，长度 7200 秒；秒和分钟只定位 point/transition，不生成主行。
- 帧内节气、DST、support boundary 或字段变化必须进入 `transitions[]`，不得把整帧涂成单一值。
- `FateValue` 必须显式区分 valid、invalid、unknown、conflict、candidate_set、not_applicable。
- cursor 是绑定 Profile、地点、time basis 和 track set 的不透明能力令牌；客户端不得解释或拼接。
- 上游是 CalendarProfile、field owner 与 location 契约；下游是 fate-core timeline projection、delivery API 和独立 timeline app。

## 变更规则

- 新增轨道先登记 `track-registry.json` 的 owner、来源、时间语义和 natal 要求，再实现投影。
- 一至五层八字扩展以 `field-system.json` 为完整清单；固定 61 项、五层数量和 authority，运行时目录与测试必须双向校验，禁止只加前端标签。
- `proof-coverage.json` 是时间轴结构化声明到 proof ref、测试选择器和反事实类别的机器覆盖注册表；`.github/scripts/timeline-proof-gate.py` 绑定当前摘要并拒绝 orphan。
- breaking schema 变更必须升级 `schemaVersion` / `projectionVersion` 并同步 API changelog、golden、SDK 类型和迁移说明。
- 不扩展当前 CalendarProfile 支持域；扩域必须发布新 Profile。