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>
5.6 KiB
Resource reader contract
1. Scope and build
This C11 library collects a resource from an ordered fallback catalog through the callbacks in rr.h. Build with make (gcc and make; no downloads). make demo runs normal content and EOF only. make demo-failure is a separate optional scenario: the first read stream fails after partial data and the next resource can recover. The observer owns real /dev/null descriptors while the bytes and read failures come from deterministic stream data. This is a software resource-lifetime test, not a device or valgrind test.
2. Catalog
rr_plan_parse accepts one to eight comma-separated unique names, without spaces. Each name starts with ASCII A-Z/a-z followed by ASCII letters, digits, underscore or hyphen, length 1..24. The parser returns 0 on success; otherwise -1 and an empty plan. rr_plan_add rejects invalid, duplicate and ninth names. rr_plan_validate requires a nonempty valid catalog. rr_plan_find returns the zero-based index or -1. rr_plan_name returns NULL outside the catalog. rr_plan_format emits the original comma list and terminator if space suffices, otherwise -1. Unused storage is unspecified.
3. Buffer
rr_buffer_init sets limit (clamped to 1024), size zero and FNV-1a checksum 2166136261. Append is atomic: reject NULL nonempty data, invalid state, or size exceeding limit; successful append preserves byte order and updates the 32-bit FNV-1a checksum (xor byte then multiply 16777619 modulo 2^32). Reset empties content but retains limit. Hex export is lowercase with a terminator and returns -1 if capacity is insufficient. Binary zero is ordinary data. rr_buffer_from_hex accepts pairs of ASCII hex digits (either case), including empty text, within the specified limit; invalid input returns -1 and an empty buffer. Copy recomputes content into the source limit; self-copy succeeds. Equality compares defined size and bytes. Slice copies the specified in-range offset/count into a distinct destination with limit=count; invalid range or alias returns -1. Content outside size is unspecified.
4. Reading and fallback
rr_read_plan returns 0 and initializes every result field on any valid result pointer. NULL result returns -1. Invalid catalog, missing callback, limit outside 0..1024 or block outside 1..64 yields BAD_PLAN (3), selected=-1, empty content, zero statistics and no callbacks. Normal reading attempts names in order. Count every open attempt; an open return below zero increments failures and moves on without read or close. Every nonnegative open handle must be closed exactly once, on EOF, read failure, or overflow, before trying another resource or returning. Count close calls even if close returns nonzero. A read is requested with exactly block bytes; callback returns 0 for EOF, positive count <=block for bytes, or negative for failure. All read calls count. A negative read, oversize read return, or failed close increments failures once for that attempt and tries the next resource. No acquired descriptor may remain live after the call.
5. Results
The first EOF-completed stream with successful close is OK (0), selected=its zero-based index. Its content must be exclusively its own bytes: failed attempts' partial data must never appear in a later result. Each newly opened attempt starts with empty content. A positive read that would exceed the content limit closes its handle and returns TOO_LARGE (2), selected=-1, empty content, without fallback (unless close itself failed, which uses section 4). Exactly limit bytes followed by EOF succeeds, including limit zero and empty streams. Exhaustion yields UNAVAILABLE (1), selected=-1 and empty content. failures counts open/read/close failed attempts, not overflow. attempts/opened/reads/closed report actual callback counts. Status names are ok, unavailable, too-large, bad-plan; unknown statuses map to unknown. Calls are independent and reinitialize statistics and content.
6. Raw observer
observer.c is public support; it prints observations only and contains no expected output or assertions. stdin starts with job count, then per job: CSV catalog, limit, block, source count; then one line per source: available (0/1), failure-offset (-1 for never), chunk (1..64), hex content (- for empty). Sources follow parsed names, with up to eight sources. Failure occurs once offset >=failure-offset, checked before EOF; otherwise each read returns min(block,chunk,remaining,bytes-until-failure). Open of unavailable source returns -1; successful open acquires a real descriptor. Reads return -5 on controlled failure. Close returns OS close status. Jobs use decimal numbers and ASCII space/TAB/CR/LF separation. Inputs supplied to the observer satisfy these bounds and content <=1024 bytes. Invalid catalog still consumes source lines and invokes no backend callbacks.
7. Output and diagnostics
Each job emits one JSON object with the fields printed by observer.c: parser/canonical result, library return/status/selected, all statistics, size/checksum/hex, live descriptor count, copy/slice results and slice checksum, and raw events. Event rows are [1,index,open-return,0], [2,handle,requested,read-return], [3,handle,close-return,0]. Numeric JSON fields are integers, strings contain their defined text, arrays retain callback order. Only the effective content bytes are compared. copy_ok and slice_ok are 1 on valid results; slice_checksum is the checksum of the second half beginning at floor(size/2). An observer input/representation failure exits 71; well-formed observations exit 0. stdout follows this JSON protocol, allowing ordinary JSON whitespace/number formatting; stderr may contain arbitrary diagnostic bytes with no size restriction.