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

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.