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

115 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.

# 逻辑线程运行时合同(版本 1)
实现必须符合本文件全部条款。全部数值、状态、排队和资源语义是本软件模型公开约定,不代表宿主内核行为。
## 1. 范围与数值
R01. 这是普通 Linux 用户态的确定性软件模型。线程、信号、等待及资源都是逻辑状态;调用不创建系统线程,不发送系统信号,不访问时间、文件、网络或环境,不输出日志。
R02. 所有数值参数都是 std::uint32_t。thread_limit 的有效域为 1..16,unit_limit 为 1..64,线程 id 为 1..65535,每线程 units 为 1..64,signal 为 1..31,等待 token 为 1..4294967295;均含两端。无效值产生 RANGE。有效 units 大于当前池总量或剩余量属于 NO_UNITS,不属于 RANGE。每个逻辑线程最多有 31 个不同的 pending 信号。
R03. 信号 9 命名为 EXIT,信号 29 命名为 IO;它们只是 ID。只有 EXIT 具有退出效果,其余 1..31 的合法信号(包括 IO)均是普通投递。允许掩码的 bit (signal-1) 表示许可;bit 31 永远为 0,不按宿主系统信号编号推导其它效果。
R04. 返回码:OK=0,COALESCED=1,RANGE=-1,NOT_FOUND=-2,EXISTS=-3,BAD_STATE=-4,NO_SLOTS=-5,NO_UNITS=-6,NOT_ALLOWED=-7,PENDING=-8,BUSY=-9。Phase 为 NONE=0、RUNNABLE=1、WAITING=2、EXITED=3;Reason 为 NONE=0、SIGNAL=1、STOP=2;Event 为 IDLE=0、DELIVERED=1、INTERRUPTED=2、EXIT=3。
R05. Runtime(thread_limit, unit_limit) 有效时建立空实例:used_threads=used_units=0;没有线程、许可、pending 或等待。任一构造参数越界必须抛出 std::invalid_argument,不能建立部分实例;其它本合同 API 对定义域内或域外 uint32_t 参数均不抛异常。分别显式构造的实例完全独立;本合同不要求 Runtime 对象的复制或移动语义,观察器不复制或移动 Runtime 对象。
## 2. 完整 API 与返回结构
R06. include/thread_signal.hpp 在 namespace thread_signal 中公开以下结构和方法;字段类型和方法签名必须保留。私有实现和内部文件可调整。容器 vector 的元素类型为 std::uint32_t,查询返回值为独立值,修改返回副本不得影响实例。
```cpp
struct StepResult {
int rc;
std::uint32_t event, signal, wait_token;
std::int32_t exit_code;
};
struct JoinResult {
int rc;
std::uint32_t reason;
std::int32_t exit_code;
std::uint32_t released_units;
};
struct ThreadView {
int rc;
std::uint32_t id, phase, allowed, wait_token, reserved_units, reason;
std::int32_t exit_code;
};
struct PendingView {
int rc;
std::vector<std::uint32_t> signals;
};
struct PoolView {
std::uint32_t thread_limit, unit_limit, used_threads, used_units;
};
class Runtime {
public:
Runtime(std::uint32_t thread_limit, std::uint32_t unit_limit);
int spawn(std::uint32_t id, std::uint32_t units);
int allow(std::uint32_t id, std::uint32_t signal);
int deny(std::uint32_t id, std::uint32_t signal);
int post(std::uint32_t id, std::uint32_t signal);
int arm_wait(std::uint32_t id, std::uint32_t token);
StepResult step(std::uint32_t id);
JoinResult join(std::uint32_t id);
JoinResult stop(std::uint32_t id);
ThreadView thread(std::uint32_t id) const;
PendingView pending(std::uint32_t id) const;
PoolView pool() const;
};
```
R07. StepResult 或 JoinResult 的 rc<0 时,其余所有字段为 0。ThreadView 的 rc<0 时,其余所有字段为 0;PendingView 的 rc<0 时 signals 为空。成功查询、失败调用和 COALESCED 均不得引入未说明的副作用。除 spawn/allow/deny/post/arm_wait/step/join/stop 明确规定的效果外,状态不变。
R08. 错误优先级严格按下列各 API 顺序:先检查该方法全部参数的数值域;存在性及业务状态校验随后进行。域外参数不得以 NOT_FOUND、BAD_STATE、COALESCED 或资源错误掩盖。任何返回 rc<0 的调用整体原子,许可、队列、等待、线程、完成记录和资源余额全部保持原值。这里的失败原子性不限制成功操作的明示副作用:成功 EXIT step 改变生命周期但继续占用预留,成功 join/stop 删除线程并归还计费;不得把这些成功效果一并回滚或提前归还。
## 3. 建立和许可
R09. spawn(id, units) 的顺序为 RANGE、EXISTS、NO_SLOTS、NO_UNITS、OK。已有 id(包括尚未 join 的 EXITED)产生 EXISTS;used_threads==thread_limit 产生 NO_SLOTS;used_units+units>unit_limit 产生 NO_UNITS。成功预留 1 线程槽及 units 工作单元,建立 RUNNABLE、allowed=0、wait_token=0、reserved_units=units、reason=NONE、exit_code=0、pending 为空的新记录。used_threads、used_units 必须相应增加。
R10. allow(id, signal) 和 deny(id, signal) 的顺序均为 RANGE、NOT_FOUND、BAD_STATE、OK;EXITED 属于 BAD_STATE,RUNNABLE 与 WAITING 均可操作。allow 设相应许可 bit,deny 清该 bit;已允许再 allow、已拒绝再 deny 均返回 OK。其它 bit 不变;操作不改变 Phase、wait_token、资源、退出信息或其它线程。
R11. allow/deny 只规定之后的 post 是否可接收。deny 不能撤销或删除之前成功接收的 pending,不能改变其 FIFO 位置;allow 不能补入曾被拒绝的 post。特别是已接收的 EXIT,在之后 deny(EXIT) 后仍必须由 step 正常退出;step 不得按当前许可再次过滤既有 pending。先 deny 再 post 与先 post 再 deny 的结果不同。
## 4. 接收与等待
R12. post(id, signal) 的顺序为 RANGE、NOT_FOUND、BAD_STATE、NOT_ALLOWED、COALESCED、OK;EXITED 属于 BAD_STATE。当前许可 bit 为 0 时返回 NOT_ALLOWED,即使该 signal 已在 pending。当前许可为 1 且 signal 已在 pending 时返回 COALESCED=1,队列完全不变;否则以 OK 接收并追加到 FIFO 队尾。不因等待而立即投递,不修改 Phase 或 token,不消耗资源。
R13. 每线程的 pending 按首次成功 post 的顺序排列。同一 signal 同时最多一项;重复 post 不移动其位置;step 消费后允许再次接收并排在当时队尾。不同线程完全独立。不得按 signal 数值排序,不得以位图扫描顺序代替 FIFO。
R14. arm_wait(id, token) 的顺序为 RANGE、NOT_FOUND、BAD_STATE、PENDING、OK。只有 RUNNABLE 可建立等待;WAITING(包括相同 token 再调用)和 EXITED 均 BAD_STATE。RUNNABLE 且 pending 非空返回 PENDING,不能偷消费。成功转为 WAITING 并保存 token;其它字段和资源不变。token 只用于标识原始等待,可以在不同线程或以后的等待中重复使用。
## 5. 显式投递
R15. step(id) 的顺序为 RANGE、NOT_FOUND、BAD_STATE、OK;EXITED 属于 BAD_STATE。没有 pending 时返回 {OK,IDLE,0,0,0},无论 RUNNABLE 或 WAITING 均不改变状态,不制造唤醒。
R16. 有 pending 时,step 只消费 FIFO 第一项。普通 signal 在 RUNNABLE 时返回 {OK,DELIVERED,signal,0,0} 并保持 RUNNABLE;在 WAITING 时返回 {OK,INTERRUPTED,signal,原token,0},转为 RUNNABLE 并清 wait_token。其它 pending 保留原顺序;资源、许可、退出信息不变。
R17. 被消费的 signal 为 EXIT 时,step 返回 {OK,EXIT,9,原token或0,-9},转为 EXITED,reason=SIGNAL、exit_code=-9,清等待和全部 pending。reserved_units、allowed、线程槽及单位预留仍保留,直至 join/stop 收集。此规则同样适用于从未等待的线程和 WAITING 线程,也适用于当前 EXIT 许可已被 deny 的线程。
## 6. 收集与资源
R18. join(id) 的顺序为 RANGE、NOT_FOUND、BUSY、OK;RUNNABLE 与 WAITING 均 BUSY。EXITED 时成功返回 {OK,原reason,原exit_code,原reserved_units},原子删除线程,归还 1 槽及全部预留单位;其它线程不变。此前是否等待、普通中断、deny 或重复 post,均不能改变应归还的 units。
R19. stop(id) 的顺序为 RANGE、NOT_FOUND、OK。RUNNABLE/WAITING 先同步结束(reason=STOP、exit_code=-125),丢弃 pending 并清等待,然后在同一调用内收集;EXITED 则保留原 reason 和 exit_code 并直接收集。成功返回 {OK,最终reason,最终exit_code,原reserved_units},删除线程并归还 1 槽及全部单位。stop 不需要 EXIT 许可,不等待后续 step,未接收的系统信号与本模型无关。
R20. join/stop 成功后 thread/pending/step/allow/deny/post/arm_wait/join/stop 对该 id 均 NOT_FOUND(参数域优先规则仍适用);重复收集不能再次归还。之后允许 spawn 复用该 id,重建完全干净的 RUNNABLE 记录;旧许可、pending、等待、退出原因和资源凭据均不得迁移。used_threads 与 used_units 在任何可观察时刻分别等于所有尚存在记录的数量与 reserved_units 之和,含 EXITED 记录;范围分别为 0..thread_limit、0..unit_limit。
## 7. 独立查询
R21. thread(id) 的顺序为 RANGE、NOT_FOUND、OK;成功逐字段返回该 id 的当前公开记录。RUNNABLE 的 wait_token 为0,WAITING 的 token 为原等待值,EXITED 的 token 为0;只有 EXITED 有非 NONE reason 和非0 exit_code。reserved_units 从 spawn 至收集保持不变,allowed 可在 EXITED 保留最后许可值。查询无副作用。
R22. pending(id) 的顺序为 RANGE、NOT_FOUND、OK;成功返回当前 FIFO 的完整独立副本,EXITED 返回 OK/空队列。pool() 总是返回本实例构造容量及当前 used_threads/used_units 的独立副本。重复查询不能消费队列、唤醒、退出、回收或改变任意实例;不能用 thread 的观察代替另一个 API 的行为。
## 8. 构建与原始观察协议
R23. 使用 C++17 标准库离线构建,不能引入第三方依赖。公开构建 argv 为 ["make", "observe"],产生 build/observe;运行 argv 为 ["./build/observe"],输入来自 stdin。正式评分会将五个候选文件和同一公开 tools/observe.cpp 重新编译,不使用已有构建产物。只交付并评分这五个候选文件,新增文件不会被收集;必须保留完整 API 与上述行为。
R24. observer 输入为 ASCII/LF 的命令行,每次进程最多4096行。首行且仅有一行 NEW thread_limit unit_limit,构造实例0并选中它;可另有一行 ALT thread_limit unit_limit,构造实例1但不改变选择;SELECT 0 或 SELECT 1 选择已经建立的实例。其余命令操作当前选择的实例:SPAWN id units、ALLOW id signal、DENY id signal、POST id signal、WAIT id token、STEP id、JOIN id、STOP id、THREAD id、PENDING id、POOL、COPY_THREAD id、COPY_PENDING id、COPY_POOL。所有参数是0..4294967295的无符号十进制整数,无空行、未知命令、重复NEW/ALT或未建立实例的选择。无效NEW后输入到此结束;无效ALT后实例0继续可用,但不能SELECT 1。其它脚本继续直到EOF;只保证此语法内输入,不要求处理其它字节。
R25. 每条命令恰好输出1行:NEW/ALT成功为 "命令名 OK",无效构造为 "命令名 INVALID_ARGUMENT";SELECT为 "SELECT index"。整数API结果为 "命令名 rc";STEP为 "STEP rc event signal wait_token exit_code";JOIN/STOP为 "命令名 rc reason exit_code released_units";THREAD为 "THREAD rc id phase allowed wait_token reserved_units reason exit_code";PENDING为 "PENDING rc count signal..."(空时无尾部空格);POOL为 "POOL thread_limit unit_limit used_threads used_units"。COPY_*按对应查询的格式输出,仅把首字段替换为COPY_THREAD、COPY_PENDING或COPY_POOL。所有整数为最短十进制,无正号,无前导0(0本身除外),字段间一个ASCII空格,每行恰好以单字节LF结束,无其它stdout字节。
R26. COPY_THREAD先取得thread返回值并将该本地副本全部字段置0,再调用thread打印后一次原始返回;COPY_PENDING先取得pending返回值、把本地副本rc置0并把signals改为[31],再调用pending打印后一次原始返回;COPY_POOL先取得pool返回值并把该本地副本全部字段置0,再调用pool打印后一次原始返回。ALT/SELECT和这些命令都只负责选择对象或修改本地返回副本,不含断言。库本身不能向stdout/stderr输出;observer/候选正常退出码为0,stderr必须为空。stdout以binary exact bytes核对,不允许额外空行、CRLF、NUL、非法UTF-8、缺行或诊断。正式harness只调用/打印,预期与断言在独立Python进程。
R27. 评分使用有效输入域中的组合、公开错误域、容量端点、信号与线程交错和确定性的长序列。成功必须来自全部必需行为,不由“最后一次池为空”或某个快照替代中间返回值;不要求内部数据结构、具体算法、代码布局或与某一参考实现相同。实现符合本合同全部条款即可。