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>
56 lines
8.1 KiB
Markdown
56 lines
8.1 KiB
Markdown
# 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。构建工具自身的诊断不属于程序标准错误。
|