baa-conductor

T-004-conductor-lease.md

 1---
 2task_id: T-004
 3title: Conductor Lease 与 Heartbeat
 4status: done
 5branch: feat/T-004-conductor-lease
 6repo: /Users/george/code/baa-conductor
 7base_ref: main@56e9a4f
 8depends_on:
 9  - T-002
10  - T-003
11write_scope:
12  - apps/conductor-daemon/**
13  - packages/db/**
14updated_at: 2026-03-21
15---
16
17# T-004 Conductor Lease 与 Heartbeat
18
19## 目标
20
21实现 conductor 的主备基础行为：注册、heartbeat、lease 获取与续租、standby 拒绝调度。
22
23## 统一开工要求
24
25- 必须从 `main@56e9a4f` 切出该分支
26- 新 worktree 进入后先执行 `npx --yes pnpm install`
27- 不允许从其他任务分支切分支
28
29## 本任务包含
30
31- conductor startup checklist 落代码
32- leader/standby 状态骨架
33- heartbeat loop 骨架
34- acquire/renew lease 调用路径
35
36## 本任务不包含
37
38- 完整 step 调度
39- worker 实际执行
40- checkpoint 恢复
41
42## 建议起始文件
43
44- `apps/conductor-daemon/src/index.ts`
45- `packages/db/src/index.ts`
46- `DESIGN.md` 第 8、16 节
47
48## 交付物
49
50- conductor 基础状态机骨架
51- leader 与 standby 的最小分支逻辑
52
53## 验收
54
55- 能表达 leader/standby/degraded
56- 能区分 acquire 与 renew
57- 结构上支持后续 scheduler 接入
58
59## files_changed
60
61- `apps/conductor-daemon/src/index.ts`
62- `apps/conductor-daemon/src/index.test.js`
63- `packages/db/src/index.ts`
64- `packages/db/src/index.test.js`
65
66## commands_run
67
68- `npx --yes pnpm install`
69- `npx --yes pnpm --filter @baa-conductor/db typecheck`
70- `npx --yes pnpm --filter @baa-conductor/conductor-daemon typecheck`
71- `node --test --experimental-strip-types packages/db/src/index.test.js`
72- `node --test --experimental-strip-types apps/conductor-daemon/src/index.test.js`
73
74## result
75
76- `packages/db` 新增 controller heartbeat helper、lease acquire/renew 数据模型，以及基于 `leader_lease` 的最小抢占/续租仓储方法。
77- `apps/conductor-daemon` 新增 startup checklist、control API client、heartbeat/lease loop、leader-only scheduler gate，并补了针对性的状态机测试。
78
79## risks
80
81- `apps/conductor-daemon` 当前内置了一份 lease/heartbeat payload 类型，后续适合和 `T-003` 的 control API 契约收敛到共享定义。
82- 当前 lease 时间字段按 epoch seconds 处理，后续接入真实 control API 时需要和响应约定保持一致。
83
84## next_handoff
85
86- `T-003` 可直接把 `/v1/controllers/heartbeat` 与 `/v1/leader/acquire` 接到 `packages/db` 新增的 helper 与仓储方法。
87- 后续 scheduler 与 status API 可直接复用 `ConductorDaemon.getStatusSnapshot()`、`canSchedule()`、`runSchedulerPass()` 作为主备门禁基线。
88
89## notes
90
91- `2026-03-21`: 创建任务卡