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

15 lines
4.2 KiB
Markdown

# Read-only text field reporting contract
1. The C11 API in text.h stores at most 16 keys. Keys are ASCII `[A-Za-z][A-Za-z0-9_]{0,14}` and are case-sensitive. Each record stores 0..96 bytes and a kind CSTR=1 or COUNTED=2. Data outside the stored length has no meaning.
2. CSTR data is accepted only when a NUL byte occurs within the stored length. Its logical text is exactly the bytes before the first NUL; terminator and all subsequent stored bytes are excluded. A leading NUL therefore gives logical length zero. No unbounded string read is permitted.
3. COUNTED data accepts every byte value and the empty sequence. Its logical text is exactly all stored bytes, including embedded/trailing NUL. Storage capacity, pointer size, or the host character encoding do not define either kind's logical length.
4. SET validates before changing anything. A valid new key uses a free slot or returns FULL=-3; replacement succeeds even when full. Invalid key/kind/data returns INVALID=-1. Success=0 increments the uint32 revision modulo 2^32 once; rejected operations leave records, count and revision unchanged.
5. DEL validates its key, returns MISSING=-2 when absent, otherwise removes it and increments revision once. COPY validates both keys, returns MISSING for an absent source, otherwise performs SET of a snapshot under the target key (including a same-key copy). Source bytes, kind and stored length are preserved. RESET empties the store and increments revision once, even if already empty. Initialization starts empty at revision zero.
6. GET returns a measurement with kind, stored length, logical length, escaped wire length and FNV-1a digest over logical bytes. Missing and invalid keys return MISSING/INVALID respectively and zero all measurement fields. Measurement never mutates the store.
7. FNV-1a starts at 2166136261; for each unsigned byte xor it into the hash then multiply by 16777619 modulo 2^32. Empty text has the initial digest. Printable ASCII 32..126 except backslash and vertical bar occupies one wire byte; every other byte occupies four bytes as a backslash-x-two-hex-digit escape. Only the wire length is reported.
8. VIEW selects keys with a case-sensitive prefix, sorts them by ASCII key order, then takes at most limit records. Empty prefix matches all. A nonempty prefix obeys the key grammar. Limit is 0..16 inclusive. Invalid prefix/limit returns INVALID with all report fields zero. An empty successful view has zero counts and the initial FNV digest.
9. A successful VIEW reports selected count, sum of logical lengths, and total wire length of each `key|escaped-text` plus one newline. Its digest consumes, for each sorted selected record, the key bytes, one NUL, the logical text bytes, and one byte 255. No terminator, padding or unselected data enters these measurements.
10. CLI reads ASCII lines of at most 1023 bytes including newline, without embedded NUL. Tokens are separated by ASCII space, TAB, CR or LF. Blank lines produce no output. Input contains SET key C|B hex, GET key, DEL key, COPY source target, VIEW prefix limit, or RESET. A single '-' denotes empty byte data or empty VIEW prefix; hex is an even number of upper/lowercase hex digits and represents at most 96 bytes. VIEW limit accepts decimal digits with optional leading '+' and any number of leading zeros within the line limit. Invalid syntax prints `ERR -1` and changes nothing. No other numeric or whitespace syntax is accepted.
11. CLI prints exactly one observation row per nonblank input line. SET/DEL/COPY/RESET print `NAME status count revision`. GET prints `GET status kind stored logical wire digest`. VIEW prints `VIEW status selected logical wire digest`. Decimal output tokens permit a leading sign and arbitrary leading zeros; separating whitespace is ASCII space/TAB/CR/LF. Labels and field counts are fixed. stdout contains only these rows; stderr may contain arbitrary diagnostic bytes. A normal completed input exits zero.
12. `make demo` loads examples/default.txt, which has only CSTR records. `make optional` separately demonstrates COUNTED bytes with embedded NUL. Both kinds, empty/count/capacity boundaries, replacement, copying, deletion, ordering and error recovery are supported independently of these examples. API NULL store/result behavior is defensive; the CLI supplies valid initialized objects.