amos 9d633e9e67 Batch 15 (20261023-C-hwe-scale-15): 320 HWE-derived repair tasks
One user-space repair task per eligible HWE debug-diag / compile-deploy base
ID: 320 admitted (C 218, C++ 97, build scripts 5), 1 skipped by the content
filter. Each ships a public spec with a check-to-basis table, at least two
defects with single-fix fixtures, a symptom-masking fixture and an alternative
correct implementation. Claude re-checked all 320: structure, the HWE quality
items and trace6 Docker calibration receipts against current digests
(320/320 USABLE). Difficulty is unmeasured. Known follow-up: 212 tasks use 120
ad-hoc family names; the next batch maps them to the canonical list.
The batch's 1,256-line progress log stays in its factory report and the
36-local branch batch15-hwe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 01:55:56 +08:00

6.0 KiB

Exception reader contract

  1. Reader is a C++17 service over Store. The public declarations in reader.hpp are the complete interface. A caller may reuse one Store for many requests. All byte strings are binary; embedded NUL is ordinary data.
  2. Store::put replaces an existing named file, but is called only while no handle for that name is open. Store::open returns the lowest free positive handle, up to the constructor capacity; absent name raises Missing, full handle table raises Exhausted. No handle is created on either failure.
  3. Store::read(handle, limit, fault_after) returns up to limit bytes from the current cursor. A zero limit is invalid. If fault_after >= 0, reading may return bytes only up to that absolute cursor offset; once the cursor reaches it while data remains, ReadFault is raised. EOF takes precedence over a fault at exactly EOF. An invalid handle raises BadHandle. Each successful read, including EOF, records a read event.
  4. Store::close releases a live handle and records a close event. Invalid handles raise BadHandle. open, read, and close append O, R, and C events respectively, each with the handle and bytes read for R. Events remain available across requests; events() returns a copy. A service may not falsify or discard them.
  5. Reader::run opens the requested primary path, scans bytes in chunks, and closes all handles opened by that request before returning. It does so on success, missing file, capacity exhaustion, injected read fault, or malformed optional index. It does not close handles that were already open before the call.
  6. The primary scan counts lines: each LF terminates one line, and a nonempty suffix without LF is another line. CR is an ordinary byte. bytes counts all bytes. longest is the maximum line length excluding LF, including CR. Empty input has all three counts zero.
  7. digest starts at 2166136261, then for every primary byte applies (digest XOR unsigned_byte) * 16777619 mod 2^32 in input order. Even partial data is reported on an injected read fault; a fault before the first byte retains the initial digest.
  8. Request::chunk may be 1..64. Other values yield BAD_REQUEST without opening a handle. fault_after is -1 for no fault or any nonnegative absolute primary byte offset. Other negative values yield BAD_REQUEST without opening a handle.
  9. If with_index is false, index_path is ignored and index_value is -1. If true, the index is opened only after a complete primary scan. The index content is one ASCII decimal integer in 0..1000000 followed optionally by one LF. Empty, nondecimal, signed, out of range, extra lines, or other bytes are malformed. It is read with the same chunk size and no injected fault. A valid index populates index_value.
  10. On primary ReadFault, status is READ_ERROR and partial line/byte/digest/longest results are returned. On malformed index status is INDEX_ERROR, with complete primary results and index_value -1. On missing path or full table status is MISSING or EXHAUSTED, with primary values gathered before the failure. A missing index is MISSING. On success status is OK. Primary opening errors have zero primary counts and initial digest. All failure statuses keep index_value -1.
  11. Result::opened and closed count Store O and C events emitted by this request; Result::live is Store live handles when the request returns. Every request must satisfy opened == closed and live == live_before; final state and the event log are observable independently. No diagnostic text on stderr is part of the result protocol.
  12. An exception from any Store operation is converted into the matching status. Reader::run does not throw for the errors above. Independent later requests on the same Store must behave as though the previous request returned all its handles.
  13. The public observer reads line-oriented commands from stdin: P name hex puts a file (- means empty); A name hex appends to an existing file with no open handles for that name and prints its new byte size; Q primary index_or_dash use_index chunk fault_after runs a request; S prints Store live handles and the event log since the preceding S, then clears that observer-only log position. Name is a nonempty ASCII token without spaces. Hex is lowercase or uppercase pairs. Unknown or malformed commands make observer exit 2. The observer prints one line per command with fields described in README. This observer is a demonstration; the grader may use the same public API with a different, observation-only harness.
  14. A returned Result is printed as Q status lines bytes longest digest index_value opened closed live; S is S live event_count followed by one line E kind handle amount per event. Numeric tokens use ordinary decimal notation. No additional stdout is permitted; stderr may contain diagnostics.
  15. Callers may hold Store handles across Reader requests. clone(handle) allocates the lowest free positive handle with an independent cursor copied from the source and emits O. Bad handles and full capacity have the same exception priorities as open. seek(handle, offset) moves a cursor to any offset from zero through file length; beyond EOF raises invalid_argument and leaves the cursor unchanged. position and remaining report cursor and unread bytes. These operations do not themselves read or close a handle. Reader requests leave preexisting handles and their cursors unchanged.
  16. The observer also supports raw handle commands: O name opens and prints O handle or O MISSING/EXHAUSTED; D handle clones and prints D handle or D BAD_HANDLE/EXHAUSTED; R handle limit fault_after reads and prints R hex (- for EOF), R READ_ERROR, or R BAD_HANDLE; C handle closes and prints C handle or C BAD_HANDLE; J handle offset seeks and prints J offset, J BAD_HANDLE, or J RANGE_ERROR; I handle prints I position remaining or I BAD_HANDLE. Malformed numeric syntax is an observer error (exit 2). R limit must be positive. Raw commands expose Store behavior, allowing a caller to verify that Reader preserves independently held handles.