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>
4.6 KiB
Capture format and audit contract, version 1
Transport
Each input line contains one command, with space or tab separated tokens, at most
1022 bytes excluding the newline. Empty lines and lines whose first nonspace
character is # are ignored. There are at most ten tokens. A final newline is
optional. Decimal integers and 0x/0X hexadecimal integers are accepted;
leading zeroes remain decimal, and a leading plus sign is not accepted.
id and raw/old/set/clear/toggle are unsigned 64-bit integers.
Widths, offsets, field sizes and signed selectors fit an unsigned 32-bit integer.
Only INSERT's value may be negative and it fits a signed 64-bit integer.
Commands and layout names are case sensitive. Output uses decimal integers.
The process returns 0 after reading valid transport, including rejected records.
Input/output stream errors return 2. Stderr diagnostics are permitted.
Width model
A word width w is valid exactly when 1 <= w <= 64. Define M(w)=2^w-1.
All word calculations use mathematical nonnegative integers modulo 2^w.
Bits outside the word are ignored; normalized raw x is raw AND M(w).
Bit 0 is the least significant bit, independently of machine byte order.
No rule depends on the signedness of plain char or a machine representation.
WORD
WORD id w raw prints:
W id x M ones zeros low high all none parity runs
M is M(w), ones counts set bits of x, zeros=w-ones. low/high are the lowest
and highest set bit positions, or both -1 when x=0. all is 1 exactly if x=M;
none is 1 exactly if x=0. parity=ones modulo 2. runs counts maximal contiguous
runs of set bits within positions 0..w-1. All predicates print 0 or 1.
PATCH
PATCH id w old set clear toggle applies set, then clear, then toggle:
y = (((old OR set) AND (M(w) XOR (clear AND M(w)))) XOR toggle) AND M(w).
It prints P id y changed gained lost, with before=old AND M(w),
changed=before XOR y, gained=(M(w) XOR before) AND y,
lost=before AND (M(w) XOR y). There is no state shared between records.
FIELD
FIELD id w raw offset bits signed prints F id u v.
A field is valid exactly when 1 <= bits <= 32, offset < w,
bits <= w-offset, and signed is 0 or 1. Let u=(raw >> offset) AND M(bits).
If signed=0, v=u. If signed=1, v=u when u<2^(bits-1), otherwise v=u-2^bits.
These mathematical definitions specify a two's-complement encoded field even
when the host's implementation of an out-of-range signed cast is different.
INSERT
INSERT id w raw offset bits signed value prints I id y.
Field validity is identical to FIELD. Unsigned values must be in [0,M(bits)];
signed values must be in [-2^(bits-1),2^(bits-1)-1]. Encode value modulo 2^bits,
replace only that field in raw, then normalize the whole result to w bits.
All bits outside the field within the word are preserved.
LAYOUT
LAYOUT id w raw name decodes named fields in the order below and prints
L id count name=value name=value .... Each value follows FIELD's v rule.
drive, w>=24: enable=(offset 0,bits 1,unsigned), mode=(1,3,unsigned),
budget=(4,12,unsigned), channel=(16,8,unsigned). count is 4.
trim, w>=24: trim=(0,6,signed), slope=(6,10,signed), code=(16,8,unsigned).
edge, w>=17: top=(w-1,1,unsigned), delta=(w-9,8,signed), tag=(0,8,unsigned).
Both trim and edge have count 3. Higher unused bits are ignored.
Rejections and continuation
One rejected record prints E id code, and subsequent records still run.
Invalid word width produces WIDTH before other semantic checks.
Invalid field parameters produce FIELD before value range checks.
INSERT values outside the field's range produce RANGE.
An unknown layout name or too-small word for a named layout produces LAYOUT.
Malformed numbers, argument counts or unknown commands produce INPUT.
An unparseable or missing id, overlong line or too many tokens uses id=0.
Rejected records publish no partial W/P/F/I/L record.
C library boundary
Every API receives a nonnull output pointer; layout names are nonnull strings.
The functions and structures in include/flag_audit.h are the public interface.
On success, cfg_describe/cfg_apply/cfg_extract/cfg_insert/cfg_layout_decode return
CFG_OK and write the defined result. On semantic rejection they return the
corresponding status; no output-state assertion is made on rejection. Only the
first count layout entries have defined values; unused entries are unspecified.
cfg_mask returns M(w) for valid widths and 0 otherwise. cfg_width_valid is a
0/1 predicate. Building cleanly and reproducing the demos alone is insufficient:
all widths, field positions, named layouts and permitted input combinations
above are part of the contract.