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>
30 lines
7.3 KiB
Markdown
30 lines
7.3 KiB
Markdown
# EEPROM software contract
|
|
|
|
R01. The C++17 interface is `include/eeprom.hpp` in namespace `eeprom`. `Number` is signed 64 bit. Each new `Bus` starts without devices; independent Bus objects have independent state even when they use the same device IDs. There is no hardware, wall clock, signal, file, or network effect.
|
|
|
|
R02. Device IDs are 0 through 3. Each device has 256 bytes, an address cursor initially 0, a configured busy cycle 0 through 4, busy remaining initially 0, page acceptance/commit/poll counters initially 0, pending start initially 0, and no pending bytes. `Snapshot` exposes `code,cursor,busy,accepted,committed,polls,pending_start,pending,bytes`; successful snapshots have all 256 bytes. The configured cycle does not change until the device is removed. `Reply` exposes `code,completed,data`.
|
|
|
|
R03. `Code` values are OK=0,RANGE=1,EXISTS=2,ABSENT=3,BUSY=4,TIMEOUT=5,SYNTAX=6,LIMIT=7. Except successful read results, `Reply.data` is empty. Except successful reads, successful page acknowledgments, and transfer results, `Reply.completed` is 0. RANGE, EXISTS, ABSENT, and BUSY from unmount, seek, page, read or transfer return completed=0 and no data and preserve every device field. BUSY from poll has the state changes specified for poll. TIMEOUT from transfer may retain the changes described below. Error snapshots contain their error code and zero scalars and empty vectors.
|
|
|
|
R04. Every method checks all its parameter domains before checking whether the device exists. Invalid IDs, invalid numeric arguments, invalid vector sizes, or vector elements outside 0 through 255 return RANGE. After valid parameters, mount returns EXISTS if present; other methods return ABSENT if absent. Existing pending transactions make unmount, seek, page, read and transfer return BUSY, including calls with zero byte count. inspect and poll remain available during a pending transaction. No method partially validates or mutates invalid input.
|
|
|
|
R05. `mount(id,fill,cycle)` accepts fill 0 through 255 and cycle 0 through 4, creates all 256 bytes equal to fill and the initial fields above, and returns OK. `unmount(id)` removes an idle device and returns OK. Later mount of that ID starts with the new fill/cycle and new counters.
|
|
|
|
R06. `seek(id,address)` accepts address 0 through 255, sets the cursor, and returns OK. `read(id,count)` accepts count 0 through 256, returns those bytes beginning at the cursor in increasing address order modulo 256, sets completed=count, and moves the cursor forward by count modulo 256. Zero count leaves the cursor unchanged.
|
|
|
|
R07. `page(id,values)` accepts 0 through 8 byte values. Empty values return OK without changing any field. Nonempty values are accepted as a pending transaction with pending_start equal to the current cursor, busy equal to the configured cycle, and accepted increased by 1. Accepted data is copied; later edits to the caller's vector do not change it. The cursor and committed bytes remain unchanged until acknowledgment.
|
|
|
|
R08. `poll(id)` increases polls by 1. Without pending data it returns OK with completed=0. If pending data exists and busy is positive, it decreases busy by 1 and returns BUSY. Otherwise it writes the pending bytes at addresses `8*(pending_start/8)+(pending_start+i)%8`, sets the cursor to `(pending_start+pending.size())%256`, increases committed by 1, clears pending and sets pending_start=0, and returns OK with completed equal to the number of committed bytes. busy remains 0 after a commit. A low level page transaction wraps within its starting page.
|
|
|
|
R09. `transfer(id,address,values,budget)` accepts address 0 through 255, 0 through 256 byte values, address+values.size() at most 256, and budget 0 through 5. After the general checks, empty values return OK without changing the cursor or other fields. Nonempty transfer seeks to address and submits consecutive page transactions covering the request in order. A transaction contains at most the remaining addresses of its current 8-byte page. Each transaction receives a first poll and up to budget further polls while BUSY. On acknowledgment the next transaction can begin. When those polls all return BUSY, return TIMEOUT with completed equal to the number of bytes acknowledged in earlier transactions. The current pending transaction and its remaining busy count remain available to later poll calls; unacknowledged bytes are not included in completed. On success return OK with completed=values.size(). The cursor progresses through acknowledged transactions.
|
|
|
|
R10. `inspect(id) const` returns the full snapshot of that ID, including pending data and counters, without changing any state. Returned vectors are copies. Methods on one ID preserve all other IDs. Methods on one Bus preserve every other Bus. Mount/unmount are the only operations that change whether an ID exists.
|
|
|
|
R11. `print_reply(out,reply)` emits `CODE completed DATA` followed by LF. `print_snapshot(out,snapshot)` emits `CODE cursor busy accepted committed polls pending_start PENDING BYTES` followed by LF. CODE uses the names above; an enum value outside the defined set is `INVALID(n)` with its signed decimal underlying integer. Every numeric field is signed decimal with no plus sign, leading zeros, padding or grouping. Formatting is independent of caller stream flags, width, fill and locale. Caller formatting settings remain unchanged after the function. Vectors of bytes are concatenated two-digit lowercase hex, or `-` if empty. If any element is outside 0 through 255, the entire vector is instead a comma-separated decimal list in square brackets, without spaces. These formatters accept arbitrary Number field values and vectors, not only values produced by Bus.
|
|
|
|
R12. `run_cli(bus,input,output)` returns 0, processes the supplied Bus, and starts a new physical line count on every call. Device state persists across calls using the same Bus. It reads physical lines separated by LF, also processing the final nonempty line without LF. A final LF does not create an additional line. Empty stdin produces no output. Blank lines are commands with invalid syntax. The first 4096 physical lines are eligible for dispatch; each following line emits `LIMIT 0 -` and has no device effect. A line containing more than 2048 bytes excluding LF, NUL, or CR emits `SYNTAX 0 -` without dispatch.
|
|
|
|
R13. Line tokens are separated by ASCII space or tab. Commands are case sensitive and have these complete token forms: `M id fill cycle`, `U id`, `S id address`, `W id HEX`, `P id`, `R id count`, `T id address budget HEX`, `I id`. All except I print Reply; I prints Snapshot. Unknown verbs, missing or extra tokens, and malformed tokens emit Reply `SYNTAX 0 -` and leave all state unchanged. Integers are one or more ASCII decimal digits, optionally preceded by a minus sign, within signed 64 bit; leading zeros and negative zero are accepted, plus signs are not. HEX is `-` for empty, or 2 through 512 hex digits in complete byte pairs, accepting either case. Values that parse but exceed the called API domain produce that API's error rather than SYNTAX. Each line yields one output line.
|
|
|
|
R14. The executable creates a fresh Bus, forwards stdin to run_cli and stdout from it, exits 0, and emits no additional stdout or stderr for valid input, empty input, or rejected input. Outputs are compared as bytes; no alternate newline, whitespace, extra banner or diagnostics are permitted. The model and its caller-facing functions must not write diagnostics to stderr.
|