amos 73a5240295 Batches 21 and 18: add 74 calibrated tasks (40 Bos redo, 34 HWE code-gen)
Batch 21 (20261027-A-bos-redo-21) rebuilt 40 of the 53 rejected Bos-qiao
environments: hidden assertions that ran inside the candidate's process
now run in a trusted parent that reads observations from a low-UID
worker; gold bytes are unchanged. 9 were excluded for scope (ROS2,
oversize, security core), 3 are blocked because the source requires an
exec bit the platform does not freeze, 1 lacks requests/bs4 in trace6.

Batch 18 (20261026-C-hwe-codegen-18) adds its last 34 of 134 tasks; the
first 100 landed in 2f32624d.

Claude reviewed 74/74 USABLE against current digests, canonical
families, no ID or source overlap with main, plain public docs. Only the
new task directories are taken; the stale pre-batch-20 copies of
concur-release-capsule and resource-temp-link on the batch 21 branch and
both branches' progress notes stay as main has them. Difficulty is
unmeasured.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 10:23:12 +08:00

56 lines
8.1 KiB
Markdown
Raw 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.

# Buffer capacity contract
R01. 接口位于命名空间 `buffer_capacity`,声明于 `include/buffer_model.hpp`;所有数值参数和下述数值字段均为 `std::int64_t`,内容字节为 `std::uint8_t`,容器为 `std::vector`。接口在本文件规定的输入范围内执行同步、确定的内存操作。
R02. `Status` 的枚举值为 `OK=0`、`RANGE=1`、`EXISTS=2`、`ABSENT=3`、`BUSY=4`、`NOSPACE=5`。返回结构只包含下面列出的公开字段,字段顺序与下文顺序相同。
R03. `DeviceInfo` 的字段是 `id, capacity, allocation`;`SessionInfo` 的字段是 `id, device, cursor`;`ResourceInfo` 的字段是 `allocation, device, capacity`;`PoolInfo` 的字段是 `blocked, live_count, resources`,其中 `resources` 是 `ResourceInfo` 的向量。
R04. `DeviceResult` 的字段是 `status, value`,`value` 为 `DeviceInfo`;`SessionResult` 的字段是 `status, value`,`value` 为 `SessionInfo`;`WriteResult` 的字段是 `status, count`;`ReadResult` 的字段是 `status, bytes`,`bytes` 是字节向量。非 OK 的 DeviceResult 和 SessionResult 的 value 各字段为 0,非 OK 的 WriteResult.count 为 0,非 OK 的 ReadResult.bytes 为空。
R05. `Engine()` 创建无设备、无会话、无 live 资源且 blocked 为 0 的对象,`~Engine()` 释放该对象自己的全部状态。Engine 不可复制或移动。多个 Engine 可以同时存活,同样的设备 ID、会话 ID 和资源号在不同对象中分别使用;对一个对象的调用及销毁不改变另一个对象。
R06. 设备 ID 范围为 0..7,会话 ID 范围为 0..15,容量范围为 0..4096,计数范围为 0..4096,定位位置范围为 0..4096,写入字节范围为 0..255,blocked 参数范围为 0..1。每次调用先检查全部数值参数的这些范围,任一不符时返回 RANGE。
R07. `Status create(device, capacity)` 在设备已经存在时返回 EXISTS;否则创建全部 capacity 字节均为 0 的设备。正容量设备拥有一个独立存储资源,零容量设备的 allocation 为 0 且不占资源。创建失败时不创建设备。
R08. `Status drop(device)` 在设备不存在时返回 ABSENT,在仍有会话指向它时返回 BUSY;否则删除设备并释放它持有的资源。之后可以用同一设备 ID 创建新设备。
R09. `Status open(session, device)` 在会话已经存在时返回 EXISTS;否则在设备不存在时返回 ABSENT;否则打开指向该设备、cursor 为 0 的会话。一个设备可以有多个会话。
R10. `Status close(session)` 在会话不存在时返回 ABSENT;否则删除该会话,不改变设备内容或其他会话。之后可以用同一会话 ID 打开新会话。
R11. `Status seek(session, position)` 在会话不存在时返回 ABSENT;否则在 position 大于当前设备 capacity 时返回 RANGE;否则把该会话 cursor 设为 position,不改变设备或内容。
R12. `WriteResult write(session, count, byte)` 在会话不存在时返回 ABSENT。count 为 0 时返回 OK 和 count 0,不改变任何状态。count 为正且 cursor 大于 capacity,或 count 大于 capacity-cursor 时返回 NOSPACE。其余情况下,从 cursor 起写入 count 个给定 byte,当前会话 cursor 移到写入结束位置,返回 OK 和实际写入的 count。其他字节及其他会话 cursor 不变。
R13. `ReadResult read(session, count)` 在会话不存在时返回 ABSENT。cursor 已达到或超过 capacity 时返回空字节向量且 cursor 不变;其余情况下返回从 cursor 起的 min(count, capacity-cursor) 个字节,cursor 增加返回字节数。读取不改变内容、capacity 或其他会话。
R14. `Status resize(device, capacity)` 在设备不存在时返回 ABSENT;否则在 capacity 与原 capacity 相同时返回 OK 且不改变状态;否则把设备存储调整为该容量。新内容保留原来前 min(原 capacity, capacity) 个字节,其余字节为 0;所有仍打开的会话保留各自原 cursor。容量变为 0 时释放资源并把 allocation 设为 0。
R15. 正容量资源使用编号 1..9,新资源取调用时最小的未使用编号。创建正容量设备及把设备改为不同的正容量都先取得新资源;成功发布新容量和保留内容后才释放旧资源,因此这种 resize 的新 allocation 与旧 allocation 不同。pool 只列出已发布的 live 资源,同一资源号不会同时归属两个设备,释放的编号可供后续调用使用。
R16. `Status set_allocation_blocked(blocked)` 设置该对象的 blocked 标志并返回 OK。blocked 为 1 时,需要取得正容量新资源的 create 或 resize 返回 NOSPACE;其他调用按各自规定处理。失败不消耗标志或资源号,相同容量 resize、改为零容量和创建零容量设备均不需要新资源。
R17. 除返回值外,所有非 OK 调用均保持对象的全部设备、完整内容、会话、资源和 blocked 标志。任何成功操作仅改变其条款列出的字段和归属。
R18. `DeviceResult device(device) const` 在设备不存在时返回 ABSENT;否则返回 OK 及其当前 DeviceInfo。`SessionResult session(session) const` 在会话不存在时返回 ABSENT;否则返回 OK 及其当前 SessionInfo。这两个查询不改变对象状态。
R19. `PoolInfo pool() const` 返回当前 blocked、live 资源数量以及全部 live 资源记录;记录按 allocation 递增,每条记录的 device 和 capacity 等于其所属设备的对应值。查询不改变对象状态。
R20. `int run_cli(Engine& engine, std::istream& input, std::ostream& output)` 在传入的 Engine 上依次执行输入命令,返回 0。每次调用使用自己的输入行计数,同一对象可以再次调用 run_cli,保留前次已完成的状态。`main.cpp` 创建一个 Engine,把标准输入和标准输出交给 run_cli,并以其返回值退出。
R21. 输入由 LF 字节分隔为行;流末尾的非空片段也是一行,末尾 LF 后不产生额外行。空输入没有命令或输出。行内容不含 LF,允许可打印 ASCII 字节和 TAB;包含其他字节或内容长度超过 256 字节的行输出 `ERR SYNTAX`。空行也输出 `ERR SYNTAX`。
R22. 每行以 ASCII 空格和 TAB 分成 token,可带这些字节构成的行首、行尾和 token 间空白。动词为下面列出的大小写形式,不存在的动词或 token 数目不符均输出 `ERR SYNTAX`。数字 token 使用可带一个前导减号的十进制数字串,允许前导零;没有数字、带其他字符或数值不能由 int64_t 表示时输出 `ERR SYNTAX`。可表示的数值交给相应 API 处理。
R23. 命令及顺序参数为 `create device capacity`、`drop device`、`open session device`、`close session`、`seek session position`、`write session count byte`、`read session count`、`resize device capacity`、`block blocked`、`device device`、`session session` 和 `pool`;它们分别调用同名 API,block 调用 set_allocation_blocked。
R24. 每次 run_cli 最多处理前 4096 行,每个输入行都计入该数量。存在第 4097 行时,输出一次 `ERR LIMIT` 并结束本次调用,后面的输入不执行、不产生输出。语法无效的行不执行命令,也不改变对象状态。
R25. 每条已处理命令产生一行响应。API 非 OK 时输出 `ERR ` 和 Status 的枚举名称;create、drop、open、close、seek、resize、block 成功时输出 `OK`;write 成功时输出 `OK count`;read 成功时输出 `OK n hex`,n 为返回字节数,hex 为按字节顺序组成的两位小写十六进制串,空字节向量使用 `-`。
R26. device 成功时输出 `OK id capacity allocation`;session 成功时输出 `OK id device cursor`;pool 输出 `OK blocked live_count`,随后按返回顺序为每个资源追加一个 ` allocation:device:capacity` 字段。所有输出数值用无前导零的十进制形式,字段间使用一个 ASCII 空格,每行仅以一个 LF 结束。
R27. 程序仅通过规定的响应向标准输出写字节,标准错误为空;包括语法错误、API 错误、达到行数限制和空输入在内,处理完成后进程退出码均为 0。构建工具自身的诊断不属于程序标准错误。