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

12 KiB
Raw Permalink Blame History

虚拟计时器取消账本公开合同

本文件是本工程的完整公开行为规范。公开 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 必须提供下面的类型、字段、常量和函数。内部表示、分配方法及文件内函数均不构成接口;不能用内部布局或源码相似度评分。

#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。时间计算使用整数,计算过程不得回绕。

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。工作区其他文件与新文件不会收集。实现须符合本文件全部条款。