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>
19 lines
5.5 KiB
Markdown
19 lines
5.5 KiB
Markdown
# Field-bank public contract
|
|
|
|
C01. The bank is a deterministic C11 software codec, with at most eight fields in insertion order. All arithmetic state is uint32_t and counters wrap modulo 2^32. No hardware, thread or wall-clock behavior is involved.
|
|
C02. A field has id 1..255, width 1..16, offset 0..31 with width+offset<=32, scale 0..5 and bias 0..5 with bias<=2^width-1. Its occupied bits are (2^width-1)*2^offset. IDs must be distinct and occupied bits must not overlap.
|
|
C03. A logical value is in 0..floor(((2^width-1)-bias)/2^scale). Its encoded token is value*2^scale+bias; the complete word is the sum of token*2^offset for every field. These are mathematical expressions, not requirements about source spelling or parentheses. All operands and shift counts can be bounded so C11 unsigned arithmetic has defined behavior.
|
|
C04. pf_init creates an empty bank with zero word and zero counters. Each field added starts with logical value zero. Empty-word encoding is zero. The fields array's unused tail has no observable requirement.
|
|
C05. A(id,width,offset,scale,bias) adds a field; R with the same arguments replaces an existing field's shape while preserving its logical value and insertion position; D(id) removes one field and preserves the order of the others. Each successful A/R/D increments epoch once and recomputes the word. A uses error order: shape, duplicate ID, full bank, overlap. R uses error order: missing ID, shape, overlap, preserved value range. Successful identical replacement still increments epoch.
|
|
C06. W(id,value) preserves layout, changes one value, recomputes word and increments writes once, even when the value was already equal. Error order: missing ID, range. Z sets all values to zero, recomputes the word and increments writes once, even for an empty bank.
|
|
C07. I(word) imports a raw word. Reject nonzero bits outside occupied bits. For each field, extracted token must be >=bias and (token-bias) divisible by 2^scale. On success install all decoded values, preserve layout/epoch/writes, cache exactly word, and increment imports once. Empty bank accepts only zero.
|
|
C08. Every rejected mutating operation increments rejects once and changes nothing else: word, values, field order/shape, epoch, writes and imports must remain as previously committed. All operations commit atomically. C clears layout and word, increments epoch once, and preserves writes/imports/rejects.
|
|
C09. Status numbers are OK=0, BAD_ID=1, BAD_LAYOUT=2, OVERLAP=3, NOT_FOUND=4, RANGE=5, BAD_WORD=6, FULL=7. Shape validation checks ID before other shape checks. R/D/W missing ID is NOT_FOUND, including IDs outside 1..255. Q(id) returns current field information or NOT_FOUND; Q and S are read-only and never increment rejects.
|
|
C10. pf_mask, pf_limit, pf_bits, pf_find, pf_layout, pf_occupied, pf_token, pf_untoken, pf_encode, pf_decode and read/info are public support APIs described by their declarations. pf_layout validates shape/overlap and value range; encoding and decoding follow C02/C03/C07. Public observer calls the bank operations and telemetry; acceptance is based on observable behavior, not a particular helper decomposition.
|
|
C11. Telemetry: occupied is the bitwise union of occupied bits. Fingerprint starts at 5381, folds count, then id,width,offset,scale,bias for each field in insertion order, replacing h by (33*h+x) mod 2^32 each time. Minimum and maximum words use all logical values zero and all per-field maximum values respectively, regardless of current values.
|
|
C12. Further telemetry: value_sum is the sum of logical values; value_weight is the sum of id*value, both modulo 2^32. layout_span is max(offset+width), or zero for empty bank. free_bits is 32 minus the sum of widths.
|
|
C13. tools/observe.c is a raw observer. Input consists of command letters A,R,D,W,I,Z,C,Q,S and their arguments from C05-C09 separated by space, TAB, CR or LF. Unsigned decimal arguments may have a leading + and arbitrarily many leading zeros, and their value is <=4294967295. No other input forms are part of this command protocol. A command may be immediately followed by its first numeric argument; command boundaries follow the documented arity.
|
|
C14. The observer emits one row per command, with exactly 23 decimal integers: status,count,word,epoch,writes,imports,rejects,occupied,fingerprint,minimum_word,maximum_word,value_sum,value_weight,layout_span,free_bits,present,width,offset,scale,bias,value,limit,token. The last eight are all zero except for a successful Q; its token is extracted from the cached word. A missing Q has all eight zero. Decimal outputs may use optional signs and leading zeros, horizontal whitespace between integers, and one LF-terminated row per command. The library and observer may write arbitrary diagnostic bytes to stderr; diagnostics do not change acceptance.
|
|
C15. The public Makefile builds with gcc, C11 and the standard C library, using only repository files. Run make demo for the default encoding report. make replacement is an independent optional configuration-recovery report and is not loaded by make demo. Source/header changes must satisfy all clauses, for all publicly allowed inputs, not just the two reports.
|
|
C16. Submission is include/fields.h, src/layout.c, src/codec.c, src/bank.c, src/metrics.c and Makefile. tools/observe.c and this document are fixed support material. Fresh verification builds the submitted sources together with the same raw observer; runtime nonzero exit or missing/malformed rows is a failure. Successful observer execution exits zero. Compilation must succeed with the public CFLAGS; stderr has no size limit.
|