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.2 KiB

Reverse cursor contract

1. Journal and selections

The C11 API is declared in include/reverse.h. A journal has capacity 1..64. Initialization empties it and starts sequence numbers at 1. Appends accept bank 0..7, level 0..3 and value -1000000..1000000; each successful append gets the next sequence. At capacity the oldest record is evicted. Ordinal 0 always means the oldest retained record; reads outside the retained count return -1. Invalid operations do not mutate state, and unsuccessful appends report sequence 0 through the observer. Selection masks are 0..255, minimum level 0..4, and inclusive value bounds within -1000000..1000000 in ascending order. A record is selected exactly when its bank bit is set, its level is at least the minimum, and its value lies in the closed bounds. Mask 0 or minimum level 4 is valid and can select nothing.

2. Opening and lifecycle

cursor_clear returns an uninitialized cursor with all six observable info fields 0. cursor_open replaces one cursor with an immutable copy of the current journal, selection and ordinal range. Later appends or eviction cannot alter that copy. For a nonempty journal the endpoints satisfy 0 <= low <= high < count and are inclusive. For an empty journal only low=high=0 is accepted and the cursor starts done. A new nonempty cursor starts initialized, not done, and with examined/emitted/invalid counts 0. Opening or stepping with invalid parameters returns -1 and preserves all cursor state. Stepping an uninitialized cursor returns -1. Reopening discards the old snapshot and counters; the two slots are independent. Clearing either affects only it. No implementation-specific fields of Cursor are part of the observation contract.

3. Bounded reverse traversal

cursor_step accepts scan budget and output capacity independently in 0..64. Each examined ordinal consumes exactly one scan unit, including records rejected by selection. Ordinals are examined high, high-1, ..., low, exactly once each. Accepted records are emitted in that order. Rejected records are consumed without emission. A call stops before examining another record if its scan budget or output capacity has been exhausted. The next call resumes after the last examined ordinal. Stop reason precedence is DONE(0) if there are no remaining ordinals, otherwise BUDGET(1) if budget is exhausted, otherwise OUTPUT(2) if output capacity is exhausted. This precedence applies before the first examination and after every examination. A done cursor remains done and emits/scans nothing even with zero budgets. A zero budget cannot examine anything; zero output capacity cannot examine anything. Batch.scanned and .emitted count only this call; info examined/emitted are cumulative. Only the first Batch.emitted rows are defined. Unused rows and private struct storage are not observable and have no required byte pattern.

4. Controlled port

The supplied port in src/cursor.c records each attempted read and refuses an ordinal outside the snapshot or opened interval before accessing memory. Each refused ordinal increments info.invalid_reads and does not emit a row. At most 64 attempts are allowed per call; a further attempted read returns PORT(3). This is a deterministic diagnostic substitute for a device read, not a license to exceed the scan budget. Correct operation never reaches PORT, never makes an invalid read, and Batch.port_calls equals scanned. Implementations may use any safe algorithm and signed or unsigned internal indices.

5. Raw observer protocol

reverse-observer starts with a capacity-64 empty journal and two cleared cursors. Input is a stream of one-character commands and decimal integer arguments separated only by ASCII space, TAB, CR or LF. Decimal tokens allow a leading + or - and any number of leading zeros; mathematical values must fit int64. Other characters, missing arguments, overflow or unknown commands terminate with code 2. Earlier complete commands may already have produced output. API parameter errors are reported as -1 and the observer continues. Legal input completes with code 0. H capacity: initialize journal; on success clear both cursors. Output H rc capacity count next_sequence overwritten. A bank level value: append; output A rc assigned_sequence capacity count next_sequence overwritten. V ordinal: output V rc and, on success, sequence bank level value. G mask min_level min_value max_value: output G rc and, on success, count sum minimum maximum fingerprint, four level counts then eight bank counts. An empty summary has all fields zero. Fingerprint folds selected records in increasing ordinal order: f = f65599 + sequence131 + bank17 + level5 + value+1000000, modulo 2^64. O slot low high mask min_level min_value max_value: open; output O rc followed by info for a valid slot, including when the API rejects the operation. Slots are 0 or 1. N slot budget output_capacity: step; output N rc. If rc=0 append reason scanned emitted port_calls then info then the emitted records as sequence bank level value quadruples. If rc=-1 append only info when the slot is valid. I slot and C slot inspect and clear; output command rc then info for valid slots. Invalid slots have no info suffix. Info is initialized done snapshot_count examined emitted invalid_reads, in that order. Output is one record per input command. Within each output record integer tokens may use any signed decimal representation with leading zeros and space/TAB/CR separators; command letters and LF record boundaries remain as specified. No extra stdout records. Stderr is unrestricted diagnostic bytes and is not part of the numeric protocol. The observer prints raw state; it has no hidden assertions or expected results.

6. Public examples

make demo runs examples/default.txt: four records, full selection, one full-range cursor and two ample steps. It should finish once, then remain done without more reads. The independent optional make filtered example uses examples/optional-filtered.txt: a subrange, bank filter and scan budget 1. Each call may examine at most one retained record whether or not it emits. It is intentionally separate from the default demo. Both examples are illustrations; all documented capacities, ranges, filters, budgets, interleavings, empty/singleton snapshots and invalid API arguments remain supported.