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>
5.5 KiB
Format buffer contract
C01 Lifecycle: fb_open(limit, allocator) opens the single closed session, with empty content and no allocation. Limit is 0..65535 inclusive; both callbacks are required. Invalid open returns FB_INVALID and preserves closed state. Open while active returns FB_STATE and preserves everything. Closed view is data NULL, length/capacity/limit/fields/active zero. Mutators and copy on closed return FB_STATE, except close which is idempotent and returns FB_OK. F/Q observer commands do not call a mutator.
C02 Ownership: all dynamic storage used by the library goes through the supplied allocator. resize(p, old_bytes, new_bytes, context) preserves min(old,new) bytes on success, releases the old block, and returns a block of exactly new_bytes; NULL with old_bytes=0 is an allocation. On NULL result the old block is untouched. release accepts a live non-NULL block with its exact allocation size. No zero-size allocation and no double/invalid release are allowed. At each API boundary exactly one live block of capacity bytes exists if capacity>0, otherwise none. fb_close releases the final block, clears session state and permits reopening. The ledger is cumulative across sessions and never clears evidence on close.
C03 Capacity: length counts logical bytes including embedded NULs, capacity includes room for a trailing NUL. If allocated, 1<=capacity<=limit+1 and capacity>=length+1. Allocation is lazy: open, append of zero bytes into an empty unallocated session, reset and reserve(0) do not allocate. Reserve(n) requires capacity>=n+1 for nonzero n without changing content/fields; n>limit returns FB_LIMIT. Existing adequate capacity is reused without any allocator call. Growth amount is otherwise unrestricted. No shrink occurs except close. Bytes after data[length] are unspecified and are never compared.
C04 Content: append concatenates exactly the supplied bytes, including NUL and bytes 128..255. NULL is valid only with length=0. Snapshot data[0:length] is the logical content, and data[length] is NUL whenever allocated. View returns current length, capacity, limit, number of fields and active=1. Append/escaped do not increment fields. Input buffers do not alias the session allocation and remain unchanged.
C05 Escaping: fb_escaped appends each input byte 32..126 literally except backslash, equal sign and semicolon; all other bytes and those three delimiters become four ASCII bytes backslash, lowercase x, and two uppercase hexadecimal digits. Empty input is valid. No Unicode interpretation is performed.
C06 Fields: fb_field appends key, '=', escaped value, ';', then increments fields once. Key is 1..24 ASCII letters, digits or underscores. Empty/NULL/invalid key returns FB_INVALID. Values follow C04/C05. fb_integer uses the same field representation with the signed decimal value, including INT64_MIN, zero and INT64_MAX, no plus sign or leading zeroes. Signed decimal has no bytes needing escape.
C07 Atomicity and errors: after closed-state and invalid-pointer/key validation, a raw length or escaped/field encoded result exceeding limit returns FB_LIMIT. On limit/invalid/state errors content, capacity, fields and allocator state are unchanged. Growth callback failure returns FB_MEMORY and preserves the old pointer, content, capacity and fields. Only that failed callback consumes the ledger failure arm. Successful operations may grow only when needed; no mutation commits before a required allocation succeeds. Input lengths 0..65536 are supported for boundary checks. No operation is allowed to overflow arithmetic.
C08 Reset: fb_reset preserves allocation/capacity and the active session limit/allocator, sets length/fields=0, writes a terminator if allocated, and allows reuse. Close after reset still releases that retained block.
C09 Copy: fb_copy(destination, capacity, written) copies logical bytes and one terminator if capacity>=length+1, writes length to *written and returns FB_OK. NULL destination/written returns FB_INVALID. Insufficient capacity returns FB_LIMIT and leaves destination and *written unchanged. It never allocates or changes session state. Destinations do not alias session data.
C10 Observer input: one command per line. O limit opens with ledger callbacks; R n reserves logical n; A hex appends; E hex appends escaped bytes; K key hex appends a field; I key signed_decimal appends an integer field; X resets; C closes; Q observes; F arms the next nonzero resize request to fail (an arm remains across close/open); N n calls append(NULL,n); Y capacity calls copy with destination filled with A7 and written initialized to 7. Hex '-' means empty and key '-' means empty. Command numeric tokens are unsigned decimal except I's signed value; inputs are well formed within the API's documented ranges. Ordinary clients may also call the header API directly.
C11 Observer output: each command prints space-separated result, active, length, capacity, limit, fields, ledger live block count, ledger live bytes, ledger error count, failure arm, logical content hex (or '-' empty), terminator-ok, copy-written, copy bytes hex (or '-' empty). Copy bytes are the first copy-written bytes, even on error. Non-Y commands use copy-written=0. Empty unallocated view has terminator-ok=1. Output is raw observation, no assertions. The ledger releases leftovers only after the last observation, so leaks remain visible. stdout must follow this protocol; stderr may contain arbitrary diagnostics and is ignored for business comparison. All commands must finish normally within the supplied execution deadline.