# TX frame service contract v1 1. Build with `make`; C11, gcc and make are the only build dependencies. `./tx-demo < demo.txt` is the public reproduction. No hardware, threads, timing, network, or downloads are involved. 2. The service owns four frame slots numbered 0..3, each with 256 bytes. Initial CPU and device memory bytes are 0x5a. Reset selects cache line 16, 32, or 64; the initial selection is 32. 3. The CPU writes a private cached view. The device reads a separate memory view. `port_clean(slot,offset,length)` publishes every cache line intersecting the specified nonempty valid range, clipped to the slot. A queue operation captures slot/id/length only; completion reads device memory at that later instant. These are explicit deterministic semantics, not actual CPU cache instructions. 4. A frame identifier is an integer 1..65535. Length is 1..256. Active identifiers are unique. A begin allocates the lowest free slot and starts an empty draft, with coverage cleared but existing byte contents preserved. All four slots may be active. 5. Writing or filling is permitted only for drafts. Offset is 0..255; length is 1..256 and offset+length must not exceed the frame length. Each successful write/fill covers that byte range. Overlap is allowed; the latest bytes win. The write counter increments once per successful write or fill call, even if it covers an already covered range. 6. Send is permitted only for a fully covered draft. It queues the frame for the device and marks it pending. Every successful completion with status 0 must return exactly the latest written bytes for the entire frame, in offset order. No pending frame may be reused or changed before its own completion. 7. Completions may arrive in any order. Completing an active pending id with status 0 or 1 removes that exact descriptor and frees that exact slot. Status 0 returns its id and frame bytes; status 1 returns its id with no payload. Other frames retain their state, coverage, and contents. Ids and slots can be reused after release. 8. Cancel frees a draft and increments cancelled; cancelling pending is BUSY. A completed/cancelled id is absent. Beginning again clears coverage. Only initialization/reset discards pending work without completion and resets all statistics and both byte views to 0x5a. 9. API result codes are OK=0, INVALID=-1 (invalid id/length/range/status), ABSENT=-2 (valid id not active), BUSY=-3 (begin duplicate/full or mutation of pending), INCOMPLETE=-4 (send draft with holes). For valid arguments, duplicate/full begin is BUSY; absent lookup is ABSENT; pending write/fill/send/cancel is BUSY; completion of draft is BUSY. Invalid arguments take precedence over state checks. An error leaves all service/port state and counters unchanged. 10. Statistics are cumulative successful begins, writes, submits, completed successes, device failures, cancelled drafts, and successfully transmitted bytes, in that order. Live draft/pending counts are computed from actual slots. Failed completions increment device failures, successful completions increment completed and bytes; both release the slot. Inspect returns the frame state (1 draft or 2 pending), slot, length and number of covered bytes; absent/error outputs contain zeros. A completion error returns id 0 and length 0. Unused bytes of any C output structure are unspecified. 11. Public C API signatures and structures are declared in `tx.h`. Candidate `tx_engine.c` implements every `tx_*` function; `port.c` and `main.c` are public supporting code. The grader rebuilds the candidate with those unmodified support files and may call the same public API directly. Alternative internal algorithms and data organizations are allowed if all observable behavior conforms. 12. CLI accepts whitespace separated decimal integers and hex payloads without a 0x prefix, with one command per line. `R line`, `B id length`, `W id offset hex`, `F id offset length value`, `S id`, `C id status`, `X id`, `P id`, `D id`, `Q` are the commands. Value is 0..255; W has an even number of hex digits representing 1..256 bytes. Blank lines and lines whose first nonspace character is # have no output. Malformed commands print `ERROR` without changing state. Lines fit in 2048 bytes. Decimal fields are plain optional-sign decimal integers within C int range. 13. B/W/F/S/X print `RESULT op rc`; R prints `RESULT R rc`. Successful reset returns 0, invalid cache line returns -1 without change. P prints `FRAME rc state slot length covered`; C prints `COMPLETE rc id length hex` where empty payload is `-`; Q prints `STATS begins writes submits completed failures cancelled bytes drafts pending`. No other stdout is permitted; stderr diagnostics are allowed. Stream processing and EOF return exit status 0; input/output failure may return nonzero. 14. Correctness applies to all legal line sizes, full/partial/overlapping writes, maximum lengths, slot pressure, invalid operations and reuse, including arbitrary completion order. Integer counters use uint64_t; test totals remain below 2^32. Public builds may use any equivalent C11 implementation; no source spelling, exact function call count, or unused output tail contents are part of acceptance. 15. D is an independent read-only device observation: `DEVICE rc id length hex`. It reads the queued descriptor and device memory directly without calling candidate code. For a pending frame it must show the latest payload from successful send until its completion. A draft or absent id returns ABSENT with id/length 0 and `-`; invalid id returns INVALID likewise. D does not change any counters.