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>
22 lines
6.7 KiB
Markdown
22 lines
6.7 KiB
Markdown
# Width replay contract v1
|
|
|
|
1. This is a deterministic software model of eight 32-bit protocol lanes. It uses C11, gcc and make, without hardware or external services. Build with `make`; `make demo` runs only `examples/demo.txt`. The separate optional command `make edge` runs `examples/high-edge.txt`; it is not loaded by the default demo.
|
|
2. `width-replay [file]` reads the named file, or stdin with no file. The first line contains one signed 32-bit decimal seed. Each subsequent line contains exactly five signed 32-bit decimal integers: `op lane a b c`. Decimal tokens allow an optional leading + or -, arbitrary leading zeroes and digits 0..9 only. Separators within a line are space, TAB or CR; lines end in LF, and a final unterminated line is allowed. Empty request lines are skipped. Invalid lexical input exits 2; valid request streams exit 0 even when a request is rejected. stderr may contain arbitrary diagnostic bytes and does not affect the result.
|
|
3. The public API is `pw_init`, `pw_apply`, `pw_effective`, `pw_snapshot`, and the audit query helpers in `include/width.h`. `pw_apply` returns 0 for success, 1 for invalid op/lane/argument, 2 for an incompatible transaction state. All input arguments fit int32_t. All mathematical word, sequence, generation, count and audit arithmetic wraps modulo 2^32.
|
|
4. Initialization assigns lane i (0..7) the word `uint32(seed) XOR (0x9e3779b9 * (i+1) mod 2^32)`. Each lane starts inactive, not dirty, with generation/accepted/rejected zero. Global sequence/ok/bad are zero; audit starts at 2166136261. Port invalid_requests starts zero.
|
|
5. Every request, including a rejected one, increments global sequence. A successful request increments global ok and the addressed lane's accepted counter. A rejection increments global bad and, if lane is 0..7, that lane's rejected counter. There is no reset command. Unknown op or invalid lane returns 1 before other argument or state checks. All reserved arguments stated below must be zero, otherwise return 1 before state checks. Rejected requests leave words, active/dirty flags and generations unchanged.
|
|
6. `op=1 BIT`: a is a bit position in [0,31], b is 0 (clear) or 1 (set), c is reserved zero. On success set/clear that bit of the effective word. Reject any other a or b with 1.
|
|
7. `op=2 RANGE`: a and b are inclusive low/high positions with 0<=a<=b<32; c is 0 (clear), 1 (set), or 2 (toggle). Affect exactly those positions and no others. Reject any other range or mode with 1.
|
|
8. `op=3 WRITE`: use the 32-bit unsigned representation of a as the new effective word. b and c are reserved zero.
|
|
9. `op=4 BEGIN`: a,b,c are reserved zero. Return 2 if already active; otherwise capture the live word as pending, set active=1 and dirty=0. No generation change.
|
|
10. `op=5 COMMIT`: a,b,c are reserved zero. Return 2 if inactive. Otherwise publish pending as live, increment generation once if dirty=1, then clear active and dirty.
|
|
11. `op=6 ABORT`: a,b,c are reserved zero. Return 2 if inactive; otherwise discard pending, clear active and dirty; no generation change.
|
|
12. `op=7 COPY`: a is a source lane in [0,7]; b,c are reserved zero. Read that lane's effective word and assign it to the addressed lane's effective word. Self copy is valid; source counters do not change.
|
|
13. `op=8 SWAP`: a is a peer lane in [0,7]; b,c are reserved zero. Return 2 if either lane is active. Otherwise exchange their live words. Increment each generation iff that lane's word changed. For self swap no generation changes. Only the addressed lane's accepted/rejected counter changes.
|
|
14. `op=9 RESTORE`: a,b,c are reserved zero. Assign the addressed lane's initialization word to its effective word.
|
|
15. An inactive lane's effective word is live. An active lane's effective word is pending. Every successful data assignment (BIT/RANGE/WRITE/COPY/RESTORE) updates the effective word; while active, dirty becomes 1 if it ever changed during that transaction and stays 1 until COMMIT/ABORT. While inactive, increment generation exactly when that assignment changes live. A no-change successful assignment still counts as accepted. BEGIN/COMMIT/ABORT and SWAP follow their own generation rules above.
|
|
16. The port in `support/port.c` is a controlled replacement for a shift instruction: `pw_port_shift(port,value,exponent)` returns `(value << exponent) mod 2^32` for 0<=exponent<32. Other exponents increment invalid_requests and return zero without executing an invalid shift. Correct processing never requests an invalid exponent, including rejected commands. Direct arithmetic or other correct algorithms are allowed; the number of valid port requests is unconstrained.
|
|
17. Audit appends one event after each request. Before is the addressed lane's effective word before processing, or 0 for an invalid lane. After is its effective word afterwards, or 0 for invalid lane. Fold the eight unsigned 32-bit values `[new_sequence, uint32(op),uint32(lane),uint32(a),uint32(b),uint32(c),uint32(result),before]`, followed by after, into the current audit: `digest = (digest XOR value) * 16777619 mod 2^32` for each value. Keep the newest 16 events, oldest first. Each event stores sequence, op,lane,a,b,c,result,before,after. `pw_audit_at` returns 0 plus that event for a valid index, otherwise 1 without touching its output. `pw_audit_count` and `pw_audit_digest` report count and digest.
|
|
18. `pw_snapshot` copies all eight lane records and reports sequence/ok/bad/audit and invalid_requests without modifying anything. `pw_effective` returns 0 for an invalid lane. The observer prints one numeric row after initialization, then after every request. A row is `[result,sequence,ok,bad,audit,invalid_requests,audit_count]`, followed by seven numbers per lane `[live,pending,active,dirty,generation,accepted,rejected]`, then newest audit events oldest-first (nine numbers per event). Initial result is 0. All printed values are unsigned except result and the event op/lane/a/b/c/result, which are signed. Each row ends LF; arbitrary space/TAB/CR horizontal spacing, optional leading +, and leading zeroes are allowed. Inactive pending words are unspecified and are ignored; only the active prefix of the audit buffer is defined. No other stdout text is permitted. The observer contains no expected answers or assertions.
|
|
19. Submission consists only of `include/width.h`, `src/engine.c`, `src/audit.c`, and `src/format.c`. The public Makefile, support, observer and examples are fixed support and are restored unchanged for formal builds; edits to them are not submitted. Formal builds use gcc with `-std=c11 -O2 -Wall -Wextra -Iinclude -Isupport` on these C files plus `support/port.c` and `tools/observe.c`; no additional libraries. Keep this interface compatible with the fixed public build and satisfy all clauses above; implementation and data organization may vary.
|