模块按 SPEC §7.5 组件划分职责,彼此通过注入式依赖解耦,不直接耦合 agent/broker 内部:
- runner.py:核心 LiveRunner 实现“halt → 主动过期 → 对账 → 自主 turn → 审计”的 fail-closed tick 顺序,并通过 Protocol + Callable 注入 scheduler、agent_caller、reconcile_fn、read_positions/balance/orders、flatten_fn、heartbeat_fn、clock 等外部依赖,使单 tick (run_once) 可无 broker 测试。
- scheduler.py:纯 asyncio 定时器,维护内存 job 集,按 next_run_at 最小堆唤醒;支持 interval/once schedule,带最大重检间隔防时钟漂移。
- jobstore.py:基于 JSON 的原子持久化(同目录 temp + fsync + os.replace),损坏文件 quarantine 为 .corrupt-<ts> 并抛 CorruptJobStoreError,保证崩溃恢复时不会静默空启动。
- liveness.py:每个 runner 写 live_root()/runtime/heartbeats/<id>.heartbeat,提供 is_runner_alive / reap_stale 供 reaper 消费。
- triggers.py:定义 Trigger(INTERVAL/MARKET/EVENT)与纯函数 due_now、market_is_open_at,市场时段由 MARKET_SPECS 配置(us_equity、crypto),仅薄包装读墙钟。
- reconcile.py:对账组件,将 broker 真实状态与 <broker>/runtime_state.json 持久基线 diff,分类为 matched/unknown_fill/orphan_order/mid_order_ambiguous,返回 ReconcileReport 指示 requires_halt,仅在安全时对账后原子覆盖基线。
- flatten.py:中止预扫动作,先 cancel 所有挂单再按 mandate 可选地 flatten 持仓,逐笔写入 live-action audit,遵循 no-retry 规则。
依赖方向单向:runner 组合 scheduler/jobstore/triggers/reconcile/flatten/liveness;scheduler 不反向依赖 runner;triggers 仅 stdlib;jobstore/liveness 共享 src.live.paths.runtime_dir()。包级 __init__.py 刻意不 re-export,要求调用方精确 import 子模块以避免并发 parcel 导入竞态。