100 tasks from the HWE arm-linux code-gen pool (outside the lk/man/pth range given to batch 22), each with at least one independent contract-edge defect and plain public docs. Claude reviewed 100/100 USABLE against current digests; no ID or source overlap with main or batch 22. Difficulty is unmeasured. progress.md records the wrap-up: all Codex sessions and Qwen schedulers stopped for the user's rollout, Qwen results so far (57 HARD of 373), and what is left on each batch branch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
43 lines
11 KiB
Markdown
43 lines
11 KiB
Markdown
# Minor buffer router contract, version 1
|
|
|
|
[R01] This is a deterministic single-threaded C++17 user-space model, not a kernel driver. Implement every public method in minor_router.hpp. Each Router starts empty; instances share no state. Only the four declared candidate files are submitted. Helpers, containers and algorithms may be replaced.
|
|
[R02] Minor numbers are integers 0..7 inclusive. Capacities are 1..4096 bytes inclusive. Each linked minor has an independent byte buffer, initially empty. Stored bytes include every value 0..255. Each minor's first successful creation has generation 1; each later successful creation after remove increments that minor's generation by one. Failed creates do not consume generations. Tests perform fewer than 10000 calls between resets; generation overflow is outside scope.
|
|
[R03] Return codes are -22 invalid argument, -17 already linked, -2 minor absent, -9 descriptor absent, -13 permission denied, -24 descriptor table full. All failures preserve every object, route, session, generation, cursor and output argument. Success return values are specified below. No API writes stdout or stderr. Normal console runs return 0, emit only the raw observation records, and have empty stderr.
|
|
[R04] Every validation order below is left-to-right: return the first listed failure, with no side effects. There is no allocation-failure requirement. For fd-based read/write methods, “read access” means mode bit 1 and “write access” means bit 2. A valid fd need not refer to a currently linked object.
|
|
|
|
## Routes, descriptors and sessions
|
|
|
|
[R05] create(minor, capacity): check minor range, then capacity range, then already linked; return 0 and register a new independent object. All eight minors may be linked at once. Objects do not share bytes or generations, even if capacities match.
|
|
[R06] remove(minor): check minor range then presence; return 0 and detach that route. Existing sessions continue to operate on their original object and bytes. New opens fail -2 until create. Recreating the same minor produces an empty new generation, leaving all old sessions untouched. A detached object is retained exactly while some session references it, and is released after its last descriptor closes.
|
|
[R07] open(minor, mode, append): check minor range, mode in {1,2,3}, append in {0,1}, route presence, then free descriptor. Allocate the smallest free fd in 3..18 inclusive and return it. Bind a new session permanently to that exact registered object with cursor 0, requested mode and append flag. Each ordinary open has an independent cursor and append flag.
|
|
[R08] duplicate(fd): check descriptor presence then space. Return the smallest free fd in 3..18 referring to the same session, including shared cursor, mode and append flag. There are at most 16 descriptors per Router, with no separate session or object limit. close(fd) checks presence, erases just that descriptor and returns 0. Closed numbers are immediately reused; close twice fails -9. Closing a linked object's last descriptor does not remove that object.
|
|
[R09] set_append(fd, enabled): check fd then enabled in {0,1}; set the shared session's flag and return 0. This works for every mode and for detached sessions. It does not move the cursor or change bytes.
|
|
|
|
## Buffer operations
|
|
|
|
[R10] Bytes is vector<uint8_t>. read/pread/peek replace the output vector on every success, including an empty success; on failure they leave its previous contents exactly intact. count is any uint64_t (0..18446744073709551615); no count is rejected for being large. The returned byte count never exceeds 4096. Input vectors are never modified.
|
|
[R11] read(fd, count, out): check fd then read access. Return at most count bytes starting at the session cursor and stopping at the stored length. At or beyond the stored length return 0 and replace out with empty bytes. Advance the cursor by exactly the number of bytes actually returned, including zero at EOF. A request larger than the remaining bytes must not skip bytes appended later: the next read starts at the previous stored end. A zero-count read never moves the cursor.
|
|
[R12] write(fd, data): check fd, write access, then data.size() <=4096. Empty input returns 0 without changing cursor or bytes, including in append mode. Otherwise choose the current stored end when append=1, or the session cursor when append=0. Write as many bytes as fit before capacity, returning the actual number written. Overwrite existing bytes, extend length as needed and fill any gap with zero bytes. Set the cursor to chosen start plus actual completion, even for nonempty writes that fit zero bytes. Never exceed capacity. Append is evaluated separately for every write.
|
|
[R13] pread(fd, offset, count, out): check fd, read access, offset <=capacity. Return bytes with the same clamping and replacement rules as read, starting at offset. Neither the cursor nor append flag changes, even on success. Offset at capacity is valid and returns 0; above capacity fails -22.
|
|
[R14] pwrite(fd, offset, data): check fd, write access, offset <=capacity, then data.size() <=4096. Use write's byte storage, gap and short-completion rules at that exact offset; ignore append and never change any session's cursor. Empty data does not extend the buffer. Offset at capacity is valid and returns 0.
|
|
[R15] seek(fd, whence, delta): check fd then whence in {0,1,2}, then whether base+delta is in [0,capacity]. Base is 0/current cursor/current stored length respectively; delta is any int64_t (-9223372036854775808..9223372036854775807). Arithmetic must not wrap. On success set the shared cursor and return its value. Seeking beyond stored length is valid; it does not extend bytes. Read-only and write-only sessions may seek.
|
|
[R16] resize(fd, length): check fd, write access, length <=capacity. Return 0; shrink by discarding trailing bytes, grow with zero bytes, and leave every cursor unchanged even if now beyond stored length. The capacity and generation do not change. Repeating the same size succeeds. clear(fd) independently checks fd then write access, empties this object's bytes and returns 0; it also leaves all cursors unchanged and succeeds repeatedly.
|
|
|
|
## Direct observation APIs
|
|
|
|
[R17] device(minor,out): check minor range then linked presence; return 0 and replace all DeviceInfo fields. Fields are minor, generation, capacity, current stored length, count of distinct sessions on this exact object, and count of descriptors on it. No descriptor is required. Counts include all modes; duplicates add handles but not sessions.
|
|
[R18] session(fd,out): check fd; return 0 and replace every SessionInfo field: fd, bound minor, generation, capacity, current length, shared cursor, mode, append (0/1), linked (0/1), aliases (descriptor count for this exact session). An old generation remains observable after removal/recreation. Failed device/session calls leave every output field unchanged.
|
|
[R19] peek(minor, offset, count,out): check minor range, linked presence, then offset <=capacity. Return bytes using the same clamping/replacement rules as pread, from the linked object regardless of open descriptors or modes. It changes no state. Detached objects are observable through their sessions, not through minor lookup.
|
|
[R20] devices(out) replaces the vector with all linked DeviceInfo records sorted by increasing minor, including objects with zero sessions. sessions(out) replaces the vector with every SessionInfo record sorted by increasing fd; each duplicate fd has its own record. Both succeed with an empty result and have no state side effects. They must agree with individual direct device/session calls.
|
|
[R21] counts() returns linked=#registered objects, retired=#distinct detached retained objects, sessions=#distinct open sessions, handles=#descriptors, bytes=sum of current lengths over every linked or retained object once, capacity=sum of their capacities once. Alias descriptors do not multiply bytes/capacity; unreferenced removed objects count nowhere. reset() drops all routes, descriptors and retained objects and resets every generation counter; it affects only this Router. Old fd integers are invalid until reused by a new open.
|
|
|
|
## Console and test transport
|
|
|
|
[R22] Build with make, or c++ -std=c++17 -O2 minor_directory.cpp minor_io.cpp minor_query.cpp minor_console.cpp -o minor-console. minor_console.cpp is an observer, not submitted candidate code. The grader builds its own identical observer against only the declared candidate files. C++17 standard library is the only dependency.
|
|
[R23] The observer accepts only well-formed ASCII lines of the commands below with exact arity. Whitespace separates tokens; empty lines and lines beginning with # are ignored. Decimal integers have grammar -?[0-9]+ for signed types and [0-9]+ for unsigned types (no plus sign), and must fit their declared C++ type; int means signed 32-bit, u means uint64_t, d means int64_t. API-invalid but representable values are well-formed. Hex tokens are even-length byte pairs, case-insensitive, or - for empty; input byte vectors are at most 8192 bytes. Malformed transport is outside the required behavior. A process may receive many commands through stdin and has two independent Routers; B chooses index 0 or 1, initially 0, and prints B index.
|
|
[R24] Commands C minor:int cap:u=create; D minor:int=remove; O minor:int mode:int append:int=open; U fd:int=duplicate; X fd:int=close; A fd:int enabled:int=set_append; W fd:int hex=write; T fd:int offset:u hex=pwrite; S fd:int whence:int delta:d=seek; L fd:int length:u=resize; E fd:int=clear. Except W/T (see R25), these print R result. Z calls reset and prints R 0. H calls counts and prints H linked retired sessions handles bytes capacity.
|
|
[R25] R fd:int count:u seed:hex calls read; P fd:int offset:u count:u seed:hex calls pread; K minor:int offset:u count:u seed:hex calls peek. The seed is the output vector's initial contents. Print B result hex, with lowercase hex or - for empty. The observer also prints the original input byte vector after W/T as R result hex so input immutability is directly observed.
|
|
[R26] I minor:int seed:int calls device; Q fd:int seed:int calls session; the seed initializes all output fields, cast to each field's type. Print I result followed by DeviceInfo fields in declaration order, or Q result followed by SessionInfo fields in declaration order. V seed:int calls devices with one seed-filled DeviceInfo; N seed:int calls sessions with one seed-filled SessionInfo. Print V/N record_count followed by each record's fields in order, flattening into a single line. These records contain only observations, no expected values or assertions. All command lines produce exactly one output line. API and observer stderr must stay empty.
|
|
|
|
Read this entire contract when repairing the task. Every clause applies, including behavior not demonstrated by smoke.in. Do not replace the observer, change the interface or print canned responses.
|