amos 8b7616bfd8 Batch 22 (20261027-C-hwe-hard-22): add 63 calibrated HWE hard-design tasks
From the 101 lk/man/pth code-gen sources: 63 tasks (C11 36, C++17 27,
11 canonical families), 38 skipped for scope or duplication. Each task
has at least one independent contract-edge defect, boundary types
rotate, and public docs state trap clauses as plain contract prose.
Claude reviewed 63/63 USABLE against current digests. Difficulty is
unmeasured.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 16:14:57 +08:00

7.4 KiB

Group delivery contract

R01. group.hpp is the public C++17 interface. Word is an unsigned 64-bit integer. A Config contains width,capacity; an Item contains id,value; a Receipt contains ticket,count,total,digest. These fields are Word values. Const input arguments retain their contents after each call. Methods affect only the receiving object; two Engines and two Journals may be used independently in one process. No real concurrency is required.

R02. Return codes are 0 for success, -22 for malformed batch/text, -34 for values outside their domain, -17 for an already used identifier or conflicting ticket, -11 for an injected submission failure, -2 for a missing index, -19 for an unconfigured Engine, -32 for an Engine that has been closed, -28 for a full queue, and -16 for a configured Engine receiving another configuration. pump also returns 1 while it has no group to submit and 2 after closing when its queue is empty. No other return values are used.

R03. Every output reference retains all its fields on any nonzero return. Except for the submission attempts described in R09, unsuccessful operations leave all object state unchanged. Queries have no side effects. A successful configure initializes only an inactive Engine; it does not enqueue, submit, or increment any counters.

R04. validate_config(config) returns -34 unless width is in 1..16 and capacity is in width..64, otherwise 0. Engine::configure applies that validation before checking whether the Engine is already configured; a valid configuration on an active Engine returns -16. reset() makes the receiving object equivalent to a newly constructed object, discarding its queued and published history, identifiers and failure settings.

R05. Engine calls enqueue, close, fail_next, pump, peek and read return -19 before inspecting other arguments if the Engine is inactive. status and reset work on inactive Engines.

R06. Engine::enqueue(item) requires id in 1..1000000 and value in 0..1000000000. After the inactive check it tests the value domain, then whether the id was ever accepted by this Engine since reset, then closing, then queue capacity. The respective failures are -34, -17, -32, -28. Success appends one Item in acceptance order, reserves its id until reset, and increments generation by one. Published ids cannot be accepted again. Reading, closing and pumping do not reserve new ids.

R07. Engine::close() marks an active Engine as closing and increments generation once. Further close calls succeed without changing state. Closing performs no submission. Engine::fail_next(count) forwards the count to its own Journal. Count in 0..8 replaces the number of future new-ticket attempts that will fail; other counts return -34 and preserve the previous setting. Neither closing nor failure injection changes the queue or any published group.

R08. take_count(queued,width,closing) returns 0 for width outside 1..16 or queued outside 0..64. Otherwise the selected count is width when queued is at least width, queued when closing with fewer than width, and 0 otherwise. Each Engine::pump(out) uses this selection, submits the oldest selected Items as one group with next_ticket, and on success removes only those Items, increments next_ticket by one, and assigns the submission Receipt to out. If selection is zero, it returns 2 for an empty closing Engine and 1 otherwise, without contacting its Journal.

R09. Journal::commit(ticket,items,out) first applies validate_items. A published ticket with an identical ordered Item sequence returns its existing Receipt without a new attempt or consuming a failure; a published ticket with different Items returns -17. For a new ticket, attempts increments by one. If a failure is pending, failures decrements by one and the call returns -11; the published groups, item count and total retain their previous values. Otherwise one group is appended in publication order and its Receipt is returned. Engine pump forwards this outcome; on -11 its queue, accepted ids, generation, next_ticket and out retain their values.

R10. validate_items(ticket,items) returns -22 if the sequence length is outside 1..16. It then returns -34 if ticket or any Item id is outside 1..1000000 or any Item value is outside 0..1000000000. It then returns -17 if any id occurs more than once in the sequence. Otherwise it returns 0. Journal permits different tickets to contain the same Item ids. Failed validation, conflicts and repeated successful tickets do not change attempts or failures.

R11. Journal::fail_next(count) has the count semantics in R07. Journal::read(index,out) returns the Receipt at the zero-based publication index, or -2 if absent. Engine::read observes its Journal through the same rule after R05. Engine::peek(index,out) returns the zero-based queued Item after R05, or -2 if absent. Read and peek remain available after close.

R12. A Receipt has the submitted ticket, the submitted sequence length, the sum of its values modulo 2^64, and the digest in R13. summarize(ticket,items) computes this Receipt without validating the ticket or Items. same_items(left,right) returns whether both ordered sequences contain identical id and value fields. These helpers and digest_items(items) accept sequences of 0..64 Items with arbitrary Word fields; they do not change any input.

R13. digest_items starts at 14695981039346656037. In Item order it consumes the id and then value, each as eight bytes from least to most significant. For each byte it replaces h with (h XOR byte) * 1099511628211 modulo 2^64. An empty sequence retains the starting value.

R14. Journal::info() returns batches,items,total,attempts,failures: published group count, published Item count, sum of published values, new-ticket submission attempt count, and remaining injected failures. Every field starts at zero. Engine::status() returns active,width,capacity,closing,queued,accepted,generation,ready,next_ticket,journal; ready is 1 if active and R08 selects a nonzero count and 0 otherwise, and journal is that Engine's JournalInfo. A fresh Engine has next_ticket=1 and all other fields zero.

R15. parse_decimal(text,maximum,out) accepts a nonempty sequence of ASCII digits 0..9, with any number of leading zeros, whose value is at most maximum. It returns -22 if any byte is outside that grammar, then -34 if the value exceeds maximum, otherwise 0 and assigns the value to out. The whole std::string is considered, including embedded NUL, non-ASCII bytes and line separators; signs and whitespace are not part of this grammar. Both maximum and out may be any Word value.

R16. decode_config(text,out) accepts width=<digits>;capacity=<digits>, with zero or more ASCII spaces or tabs around each key, equals sign, digit sequence and semicolon, and around the whole text. Keys are case-sensitive, occur once, and appear in that order. Digits are the grammar from R15, including its leading-zero allowance. There are no other separators, comments or trailing bytes. Malformed structure or a nondigit returns -22, including when another field would exceed its domain. Structurally valid numeric values must fit Word and pass R04, otherwise -34. On success both Config fields are assigned.

R17. There is no text length limit for R15 or R16. Representations may use a long run of leading zeros. The public console accepts complete command lines without truncation and transports arbitrary string bytes using hexadecimal. This interface is an observation tool; diagnostics on stderr are not part of its result protocol.