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

5.1 KiB

Record reader contract

  1. Build and public reproduction

The project uses C11, gcc and make, with no downloads. Run make, then ./borrowed-reader examples/default.br. A conforming default import reports status=ok, accepted=2, rejected=0, sum=1, minimum=-2, maximum=3. Run ./borrowed-reader examples/recovery.br 1 -1 0 0 for tolerant recovery, ./borrowed-reader examples/recovery.br 64 -1 1 0 for strict mode, and ./borrowed-reader examples/default.br 2 12 0 0 for an input fault.

The CLI is ./borrowed-reader FILE [CHUNK [FAIL_AT [STRICT [LIMIT]]]]. CHUNK is 1..64 (default 7), FAIL_AT is -1 or a byte offset 0..input length (default -1), STRICT is 0 or 1 (default 0), LIMIT is 0..4096 (default 0). Inputs have 0..16384 bytes. Only these valid argument ranges are graded.

  1. Public API and lifetime

rb_collect(source, options, report) is declared in include/borrowed_reader.h. It returns the same rb_status that it writes in report.status. The caller supplies nonnull pointers, an already open source, and the documented options. The source is borrowed: rb_collect and its helpers must never call close, including successful reads, header rejection, strict rejection, limit stops, and input failures. The caller retains the same valid handle after return, can perform a zero-capacity read, and closes it exactly once. No read may be attempted with an invalid handle. The reader must not store a source or handle for use by a later rb_collect call. Calls may reuse port slots with new handles.

  1. Stream port semantics

stream_port.h provides safe integer handles tagged with a generation. A close invalidates only that live handle. Invalid reads/closes return -9. Read returns 0 for EOF, a positive byte count for data, or -5 for an input failure. A valid zero-capacity read always returns 0 and consumes nothing, even at FAIL_AT. Positive reads return at most min(capacity,CHUNK,bytes before EOF or FAIL_AT). With FAIL_AT >= 0, a positive read at that offset returns -5, including when the offset equals input length. FAIL_AT=-1 disables the fault. The reader may buffer or read one byte at a time; read call counts and read-ahead positions are not prescribed. The port never accesses arbitrary memory through handles.

  1. Header and line boundaries

The first line must be exactly the three bytes BR1 followed by LF. Missing, unterminated, different, or overlong headers return RB_BAD_HEADER with an empty report. A read failure before the terminating LF returns RB_IO_ERROR. After the header, LF separates records. A final nonempty line without LF is processed as a record. A final empty EOF does not create a record. Payloads longer than RB_LINE_MAX=79 bytes are drained to LF/EOF and rejected once. An input failure while collecting or draining a line returns RB_IO_ERROR; that unfinished line is discarded, with no accepted/rejected increment.

  1. Record grammar and recovery

A blank line, or a line whose first byte is #, is ignored when its length is at most 79; an overlong comment is rejected. Other lines must be NAME,VALUE. NAME has 1..12 bytes: first is a..z, and the rest a..z or underscore. VALUE has an optional + or - followed by one or more ASCII decimal digits, with magnitude <=1000000; leading zeros and signed zero are valid. No whitespace, CR, embedded NUL, extra comma, or trailing bytes are permitted in a record. A malformed or overlong record increments rejected. STRICT=0 skips it and continues; STRICT=1 immediately returns RB_BAD_RECORD. Ignored lines do not increment either count. Header bytes are never treated as records.

  1. Reports, limits and errors

Each call starts an empty report: accepted/rejected/sum/minimum/maximum=0, checksum=2166136261. Each accepted record increments accepted, adds its signed value to int64 sum, and updates minimum/maximum over accepted values. When there are no accepted records minimum/maximum remain 0. Checksum is FNV-1a 32: for each accepted record feed its original payload bytes followed by LF, each byte applying hash=(hash XOR byte)*16777619 modulo 2^32. A missing final LF is normalized to one LF for hashing. Ignored/rejected/header bytes do not contribute. LIMIT=0 is unlimited; otherwise immediately after accepting the LIMITth record return RB_LIMIT, even if it was the last record. No later line is processed. Reaching EOF normally returns RB_OK. IO failure returns RB_IO_ERROR. Every stop retains the report for fully processed earlier lines; no incomplete line contributes. Every public report field is defined. There is no requirement on struct padding, unused buffers, diagnostics on stderr, or the exact number/size of reads.

  1. Submission and observable diagnostics

Submit only src/borrowed_reader.c. Other public files are fixed support and are rebuilt cleanly for grading. The CLI prints its report and then raw port observations: open=1, probe=0, reader_closes=0, invalid_reads=0, owner_close=0, live=0 for every conforming run. Its exit status is 0 for this correct owner handoff, including parsing/input failures reported in the report; malformed CLI arguments return 2. Grading calls the same API on multiple streams in a single process, and compares report values and these lifetime observations.