amos 2f32624d3b Batch 18 (20261026-C-hwe-codegen-18): add 100 calibrated HWE code-gen tasks; pause production for rollout
100 tasks from the HWE arm-linux code-gen pool (outside the lk/man/pth
range given to batch 22), each with at least one independent
contract-edge defect and plain public docs. Claude reviewed 100/100
USABLE against current digests; no ID or source overlap with main or
batch 22. Difficulty is unmeasured.

progress.md records the wrap-up: all Codex sessions and Qwen schedulers
stopped for the user's rollout, Qwen results so far (57 HARD of 373),
and what is left on each batch branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 17:52:13 +08:00

111 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 虚拟计时器取消账本公开合同
本文件是本工程的完整公开行为规范。公开 smoke 仅用于复现,不代表全部合法输入或验收范围。
## A. 执行与输入域
R01. 这是 C11 Linux 用户态的确定性虚拟计时器模型;所有时刻都由 `tl_advance` 显式给出,没有线程、sleep、真实时钟、内核模块、板卡或外部服务。所有 API 调用按输入先后完整执行。
R02. 一个 bank 有 1–8 个 timer,ID 为 `0..slots-1`,各 timer 独立,唯一共享资源是虚拟时刻和递增的 fire ticket、cancel serial。初始时刻为 0,所有 timer 为 IDLE,generation、配置、计数与取消记录为 0。
R03. `TL_TIME_MAX=9223372036854775807`。deadline、period、now 在 `0..TL_TIME_MAX` 内;period=0 表示单次。tag 为任意 `uint64_t`,不能被当成时间或截断。每个 bank 最多接收 65536 个 API 调用,因此 generation、ticket、serial 与计数不会自然溢出。
R04. bank 指针和所有输出指针均是有效非空对象,这是调用前提;测试不会传悬空指针、别名输出对象或损坏的结构体存储。timer ID、mode、token 内数值则必须按后文校验。
R05. 除 `tl_create/tl_destroy` 外 API 只返回下述状态码。失败或 EMPTY 时 bank 和输出对象均原样不变。WAIT/DONE 是成功的取消观察;CANCEL 在首次请求时写 cookie,重复等待时仍返回同一 cookie。
## B. 固定公开 API
R06. `include/timer_ledger.h` 必须提供下面的类型、字段、常量和函数。内部表示、分配方法及文件内函数均不构成接口;不能用内部布局或源码相似度评分。
```c
#include <stdint.h>
#define TL_TIME_MAX UINT64_C(9223372036854775807)
enum tl_rc {
TL_OK = 0, TL_EMPTY = 1, TL_WAIT = 2, TL_DONE = 3,
TL_ARG = -1, TL_ID = -2, TL_BUSY = -3, TL_STALE = -4,
TL_RANGE = -5
};
enum tl_phase { TL_IDLE=0, TL_ARMED=1, TL_READY=2,
TL_RUNNING=3, TL_DRAINING=4 };
enum tl_cancel_state { TL_CANCEL_NONE=0, TL_CANCEL_WAIT=1,
TL_CANCEL_DONE=2 };
enum tl_end_mode { TL_STOP=0, TL_REARM=1 };
typedef struct tl_bank tl_bank;
typedef struct {
uint32_t timer_id;
uint64_t generation, ticket;
} tl_fire;
typedef struct {
uint32_t timer_id;
uint64_t generation, serial;
} tl_cancel;
typedef struct {
uint32_t timer_id;
uint64_t generation, deadline, period, tag;
} tl_due;
typedef struct {
uint32_t phase, cancel_state;
uint64_t generation, deadline, period, tag, ticket;
uint64_t cancel_generation, cancel_serial;
uint64_t arms, begins, ends, rearms, cancelled_armed, cancelled_ready;
} tl_timer_view;
typedef struct {
uint64_t now;
uint32_t slots, phase_count[5];
} tl_bank_view;
tl_bank *tl_create(uint32_t slots);
void tl_destroy(tl_bank *bank);
int tl_advance(tl_bank *bank, uint64_t now);
int tl_arm(tl_bank *bank, uint32_t id, uint64_t deadline,
uint64_t period, uint64_t tag);
int tl_next(tl_bank *bank, tl_due *out);
int tl_take(tl_bank *bank, tl_fire *out);
int tl_begin(tl_bank *bank, tl_fire fire);
int tl_end(tl_bank *bank, tl_fire fire, uint32_t mode);
int tl_cancel_sync(tl_bank *bank, uint32_t id, tl_cancel *out);
int tl_cancel_poll(tl_bank *bank, tl_cancel cookie);
int tl_view(tl_bank *bank, uint32_t id, tl_timer_view *out);
int tl_bank_snapshot(tl_bank *bank, tl_bank_view *out);
```
R07. `tl_create` 的 slots 是 1–8 的调用前提,返回初态 bank;若系统分配失败可返回 NULL。每次观察器进程只构建一次 bank,读完输入后调用 `tl_destroy`;它只释放本模型实例,可丢弃任意虚拟状态,不等待真实工作。不测试同进程多 bank 或销毁后访问。
## C. 时间、arm 与选择
R08. `tl_advance(now)` 先拒绝 now>TL_TIME_MAX 为 RANGE,再拒绝 now<当前时刻为 ARG;否则设置当前时刻并返回 OK。相等允许。它不认领或执行任何回调,也不改变 timer phase。
R09. `tl_arm` 在 ID 不存在时返回 ID;否则在 deadline 或 period 大于 TL_TIME_MAX 时返回 RANGE;否则在 phase 非 IDLE 时返回 BUSY;其余情况成功。deadline 可以小于或等于当前时刻,下一次 TAKE 可认领已到期的 timer。
R10. 成功 arm 令 generation 加 1、phase=ARMED、ticket=0,并记录原样 deadline/period/tag;arms 加 1。其他计数和最近 cancel 记录保留。失败 arm 不能消耗 generation 或改变旧配置。
R11. `tl_next` 从全部 ARMED timer 中按 `(deadline, timer_id)` 的字典序选最小者,包含尚未到期者;返回 OK 及 id/generation/deadline/period/tag。没有 ARMED 为 EMPTY。它是纯观察,不分配 ticket,不改变 phase。
R12. `tl_take` 只选 deadline<=now 的 ARMED timer,按同一 `(deadline, timer_id)` 顺序;没有符合者为 EMPTY。成功分配 bank 全局从 1 开始且恰好加 1 的 ticket,返回 id/generation/ticket,并把该 timer 置 READY。一次只能有一个 live fire token;READY/RUNNING/DRAINING 不可再次 take。
R13. 取消、结束、失败调用及 NEXT 不消耗 fire ticket;不同 timer 的成功 TAKE 共享同一 ticket 序列。时间不会自动推进,未到期 TAKE 的 EMPTY 也不推进时间。
## D. 回调生命周期
R14. `tl_begin` 在 ID 不存在时返回 ID;否则在 ticket=0、generation 或 ticket 与 live token 不符、或 token 已失效时返回 STALE;否则在 phase 为 RUNNING/DRAINING 时返回 BUSY;READY 转为 RUNNING,begins 加 1,并返回 OK。BEGIN 之外没有操作能增加 begins。
R15. `tl_end` 在 ID 不存在时返回 ID;否则在 mode 不是 STOP/REARM 时返回 ARG;否则在 token 不匹配时返回 STALE;否则在 phase 为 READY 时返回 BUSY。RUNNING/DRAINING 按下列 END 规则处理。失败保留 token、计数、取消记录和计划。
R16. 成功 END 使 ends 加 1 并使该 fire token 失效。STOP 或 period=0 时转 IDLE,ticket=0;deadline/period/tag 保留最近 arm 或重排的配置。
R17. phase 为 RUNNING 且 period 非零的回调以 REARM 结束时,令 k 为满足 `旧 deadline + k * period > now` 的最小正整数,新的 deadline 为 `旧 deadline + k * period`,其中 now 是 END 时的当前时刻。成功转 ARMED、rearms 加 1,generation 不变;漏过的周期不补发回调。
R18. R17 的新 deadline 大于 TL_TIME_MAX 时返回 RANGE;phase 保持 RUNNING、token 保持有效,ends/rearms 和其他状态不变。随后可 STOP 或先 CANCEL 再 END。时间计算使用整数,计算过程不得回绕。
## E. 取消请求与 cookie
R19. `tl_cancel_sync` 在 ID 不存在时返回 ID。最近请求为 WAIT 时返回 WAIT 及同一 cookie,不分配新 serial,也不改任何计数。其他情形创建新请求:分配 bank 全局从 1 开始且每次加 1 的 cancel serial,cookie=(id, 当前 generation, serial)。cancel serial 与 fire ticket 分别分配。
R20. 在 IDLE/ARMED/READY 上取消都立即完成为 DONE,并令 phase=IDLE、ticket=0。ARMED 的 cancelled_armed 加 1;READY 的 cancelled_ready 加 1 且未 begin 的 fire token 立即失效;IDLE 不增加这两个计数。DONE 不是 BEGIN 或 END,不能增加 begins/ends。
R21. 对 RUNNING 发起取消时,phase 转为 DRAINING,记录 WAIT 并返回 WAIT。该请求在同一 live token 成功 END 后完成;此前其他操作保持其 WAIT 记录。等待由 API 调用推进。
R22. DRAINING 中允许同一 live token 的 END;STOP 和 REARM 均返回 OK,并结束为 IDLE、cancel_state=DONE、ticket=0,ends 加 1。该分支不计算新的 deadline,rearms 保持不变。发起取消不增加 ends。
R23. DRAINING 中 ARM 返回 BUSY,TAKE/NEXT 不选它。成功 END 后可再次 ARM,并得到新 generation。已失效的 fire token 按 R14/R15 处理,不能改变新 generation 的配置、phase、ticket、取消记录或计数。
R24. `tl_cancel_poll` 在 ID 不存在时返回 ID;否则在 serial=0、没有取消记录、或 cookie 的任一字段与该 timer 最近记录不同时返回 STALE;其余情况返回记录的 WAIT/DONE,状态不变。完成的 cookie 在后续 ARM、TAKE、BEGIN、END 后仍为 DONE;只有同 timer 的另一次新 CANCEL 才让旧 cookie STALE。其他 timer 的 CANCEL 不影响它。
R25. 取消记录初态 NONE/0/0,首次 CANCEL 后只能 WAIT 或 DONE。generation 只在成功 ARM 时增加,cancel serial 只在新取消请求时分配,fire ticket 只在成功 TAKE 时分配。这三类标识不能互相替代或被错误路径消耗。
## F. 状态观察
R26. `tl_view` 对不存在 ID 返回 ID;否则 OK 并完整写 `tl_timer_view`。phase 为五个公开枚举之一,cancel_state 为三个公开枚举之一;ticket 仅 READY/RUNNING/DRAINING 为当前 live ticket,其他 phase 为 0。cancel_generation/serial 表示最近 cookie,NONE 时为 0。配置与计数按 R10/R16/R17/R19–R25 保留或改变,不能根据输出时刻补算。
R27. `tl_bank_snapshot` 返回 OK 和当前 now/slots,phase_count 分别记录各 phase 的 timer 数量,合计为 slots。它与 VIEW/NEXT/POLL 均不改变状态或标识分配;相同状态下的连续观察相同。
R28. 各 API 按其条款依次检查条件,并在首个未满足的条件处返回相应状态码;检查失败不产生副作用。所有失败输出对象的每个字段保留调用前内容。观察器使用 R32 的输出对象初值,并按 R31 打印返回值和所有字段。
## G. 原始 stdin 协议与构建
R29. 公开观察器和正式观察器使用同一份原始转接代码。输入为 ASCII,每行是一个已知命令且参数数量符合 R30,没有额外字段;数字为无符号十进制,id/mode/slots 可由 uint32_t 表示,其余可由 uint64_t 表示。INIT 恰好出现一次且为首行,slots 为 1–8。输入不含负数、超出字段整数类型的数字、缺参或其他不符合上述文本格式的内容。观察器将字段原值传入 API,API 依据各条款处理参数值。
R30. 命令按序为 `INIT slots`、`TIME now`、`ARM id deadline period tag`、`NEXT`、`TAKE`、`BEGIN id generation ticket`、`END id generation ticket mode`、`CANCEL id`、`POLL id generation serial`、`VIEW id`、`BANK`。除 INIT 外分别直接对应同名语义的公开 API;观察器不补调用、不生成用例、不筛掉语义错误、不判断期望。
R31. INIT 成功打印 `INIT 0`。其他行先打印命令名与十进制 rc;TIME/ARM/BEGIN/END/POLL 只有这两列。NEXT 后按 `timer_id generation deadline period tag` 输出;TAKE 后按 `timer_id generation ticket` 输出;CANCEL 后按 `timer_id generation serial` 输出。VIEW 后按结构声明顺序逐字段输出,BANK 后按 `now slots phase_count[0] ... phase_count[4]` 输出。每行单个空格分列,以 LF 结束;不得打印其他 stdout。
R32. 每次调用前 NEXT/TAKE/CANCEL 的 id 字段为 UINT32_MAX、其他字段为 UINT64_MAX;VIEW 的 uint32_t 字段均为 UINT32_MAX、uint64_t 字段均为 UINT64_MAX;BANK 的 now 为 UINT64_MAX,其余字段均为 UINT32_MAX。这是输入给 API 的输出对象初值,失败后原样打印。原始观察器只做解析、调用与打印。
R33. 公开构建为 `make observer`,产物 `build/timer-observer`;它链接本合同头文件、全部五个候选 C 实现与 `tools/raw_observer.c`。正式判据使用固定 argv 的 C11 编译命令重建同一组合,不执行候选 Makefile、不复用已有产物,不强制 Werror。观察器正常读完所有输入退出 0;候选错误、缺输出、额外输出、超时或崩溃都不能作为成功结果。
R34. 最终只提交并评分 `include/timer_ledger.h`、`src/timer_internal.h`、`src/timer_bank.c`、`src/timer_schedule.c`、`src/timer_dispatch.c`、`src/timer_cancel.c`、`src/timer_audit.c`。工作区其他文件与新文件不会收集。实现须符合本文件全部条款。