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