# Priority Mailqueue v1 public contract All clauses apply to the final submission, including parameter combinations absent from repro.in. C01. Build with C++17, no external libraries: `g++ -std=c++17 -O2 observer.cpp mailbox.cpp -o mailqueue`. Only mailbox.hpp and mailbox.cpp are submitted. observer.cpp and this document are public context. No OS message queues, threads, wall clock, files, or services are required. Standard allocation failures are outside the contract. C02. `mq::Mailbox` is a value object. Default configuration is count=8, bytes=1024, body=256, priority=31. It starts at logical now=0, next ticket=1, open for sending, empty, all counters/revision=0. Three objects in the observer start independently. Methods do not use shared mutable state. C03. Copy construction/assignment clone every field, including configuration, time, tickets, closed flag, records and counters. Later mutations are independent. Move construction/assignment transfer every field and leave the source in the default C02 state. Self copy and self move assignment preserve every field. Destroying another object does not affect a copy. C04. `Config{count,bytes,body,priority}` uses uint64_t fields. Valid ranges are count 1..64, bytes 1..4096, body 1..256 with body<=bytes, priority 0..31 (inclusive maximum allowed message priority). `configure(config)` returns -22 for any invalid field with no changes; success resets the object to C02 except for the supplied configuration. `reset()` restores C02. `resize(config)` validates config first (-22), then rejects with -28 if any live count/bytes, message body length, or message priority does not fit; errors preserve state. Success keeps all contents, clocks/counters/next-ticket/closed flag and increments revision once, even for an equal config. C05. All status methods return 0 on success. Errors: -22 invalid argument, -34 range/time overflow, -17 active duplicate id, -2 missing id, -28 capacity, -32 closed sender, -11 empty open mailbox, -61 empty closed mailbox, -90 message does not fit, -75 ticket exhaustion. Error calls preserve the entire object and every output argument. All integer API fields other than Edit.kind are uint64_t; Edit.kind is int. Record bodies are arbitrary std::string bytes, including empty/NUL/high bytes. C06. `Input{id,priority,ttl,body}`: id must be nonzero; priority must be <=config.priority. ttl=0 means immortal. For ttl>0, expiry is now+ttl; ttl and expiry must be <=1,000,000,000,000. Body length must be <=config.body. At most config.count live records and at most config.bytes total body bytes are permitted. Removed ids may be reused. Tickets are independent of ids and increase for successful sends only; UINT64_MAX is reserved, and a send when next ticket is UINT64_MAX fails -75. C07. `send(input,ticket_out)` checks in this exact order: closed (-32), invalid id/priority (-22), body too long (-90), ttl or expiry overflow (-34), active duplicate (-17), exhausted ticket (-75), count/bytes capacity (-28). Success inserts a record with the current next ticket, writes that ticket, advances next ticket by one, and increments sent, sent_bytes, and revision. `Record{id,priority,ticket,expires,body}` uses expires=0 for immortal. C08. Delivery order is greatest priority first and, for equal priorities, smallest original arrival ticket first. Id values never break ties. `peek(out)` copies the first record without mutation; `receive(out)` removes it and increments received, received_bytes and revision once. Empty status is -11 when open and -61 when closed. Output records remain exactly unchanged on error. C09. `cancel(id)` returns -22 for id=0, then -2 for absent id. Success removes exactly that id, releases capacity immediately, increments canceled and revision once. `reprioritize(id,priority)` validates nonzero id and priority range first (-22), then requires presence (-2). It updates priority, retains ticket/expiry/body and increments reprioritized/revision even for unchanged priority. These operations work while closed. C20. `inspect_id(id,out)` checks id=0 (-22), then presence (-2); success copies that record without mutation. `renew(id,ttl,old_expiry_out)` checks id=0 (-22), presence (-2), then the same ttl/expiry range as send (-34). Success returns the prior expiry, sets expiry to now+ttl (or immortal for ttl=0), retains every other record field and increments only revision once. Both work while closed. `cancel_priority(priority,ids_out)` first validates priority<=config.priority (-22); success removes every record of that priority and writes their ids in ascending original ticket order. It adds their count to canceled and increments revision once, including when nothing matches; no receive/expiry counter changes. Errors preserve all state/output. C10. `advance(delta)` rejects delta>10^12 or now+delta>10^12 with -34. Otherwise it advances logical now, removes every record with nonzero expires<=now regardless of delivery position, releases both capacities, increments expired for each removed record, and increments revision once even for delta=0 or no expiration. No other method advances time. Expiration is not counted as cancellation or reception. C11. `set_closed(bool)` controls only sending; repeated same value is a no-op. A changed value increments revision once. Queued records remain receivable, cancellable and reprioritizable. Reopening allows sending again. `closed()` returns the current flag. C12. `drain(limit,budget,out)` first requires limit 1..64 (-22), then budget<=4096 (-34), then a nonempty mailbox (-11/-61). If the first record's body exceeds budget it returns -90 unchanged. Otherwise it removes the longest nonempty prefix of delivery order whose count<=limit and total bytes<=budget, stopping before the next record that cannot fit (never skipping it). It replaces out with those records, increments received/received_bytes by the totals, and revision once. Empty bodies consume count but no bytes. Budget=0 is valid. Error leaves out unchanged. C13. `snapshot(out)` replaces out with all live records in delivery order without mutation. `inspect()` returns config, now, live count, live bytes, next ticket, sent/sent_bytes, received/received_bytes, canceled, expired, reprioritized, revision and closed. Counters and revision saturate at UINT64_MAX; capacity, time and ticket do not wrap. Queries never mutate anything. C14. `Edit{kind,input}` uses kind 1=send(input), 2=cancel(input.id), 3=reprioritize(input.id,input.priority). Other input fields are ignored for kinds 2/3. `batch(edits,tickets_out)` accepts at most 16 edits (-22 before processing); evaluates edits in order against a private tentative state, with the same validation/status order as each method. Invalid kind is -22 at that position. If any edit fails, no earlier tentative operation, counter or ticket is committed, and tickets_out is unchanged. On success commit all edits and replace tickets_out with one value per edit: send's ticket, or 0 for cancel/reprioritize. Empty batch succeeds and sets output to empty. Batch adds no revision beyond its individual successful edits. ## Observer stdin protocol C15. Whitespace-separated ASCII tokens, one command per line. Blank lines and lines whose first token starts `#` are ignored. Every numeric token must be complete decimal digits (leading zeroes allowed), no signs/suffixes; uint64_t overflow is rejected. Edit kinds are also digits and must fit int. Every command has exact arity. Hex body tokens are even-length case-insensitive hex; `-` is empty. Malformed lines print exactly `PROTO` and continue without any API call or selected-slot change. This behavior belongs to the public observer, which is fixed during grading. C16. There are slots 0..2 and an initially selected slot 0. `U slot` selects a slot and prints `U slot`. `CP src dst`, `CC src dst`, `MV src dst`, `MC src dst` perform copy assignment, copy construction then move assignment, move assignment, and move construction then move assignment. src/dst each 0..2, equal permitted; construction commands with equal src/dst follow self-preserving assignment semantics. They print `R 0`. `TRAITS` prints copy/move construction/assignment availability as four 0/1 values. These test the real class API. C17. Commands: `Z` reset; `C count bytes body priority` configure; `L count bytes body priority` resize; `S id priority ttl hex` send; `P nonce` peek; `R nonce` receive; `X id` cancel; `H id priority` reprioritize; `A delta` advance; `G 0|1` set closed; `D limit budget nonce` drain; `Q` inspect; `F` closed accessor; `V` snapshot; `I id nonce` inspect_id; `N id ttl` renew; `K priority` cancel_priority; `B n kind id priority ttl hex ...` batch with n five-token edit groups; `TRAITS` as above. The observer accepts n<=32 so n=17..32 reach the API batch bound. Other numeric API arguments accept full uint64_t range. `G` additionally requires a token value of 0 or 1; all other API validation belongs to Mailbox. C18. Mutations print `R status`; send prints `S status ticket`. P/R print `P|R status id priority ticket expires hex`. D prints `D status count` followed by each record's five fields; V prints `V count` followed by records. B prints `B status count ticket...`. Before send the ticket output is 777. Before P/R the output record has all four numeric fields=nonce and body bytes `seed`. Before D, output is one such record; before B, output tickets are [777,888]. These sentinels expose unchanged output on errors. F prints `F closed` as 0/1. I uses the same seeded record and field format as P/R. N prints `N status old_expiry` with initial output=777. K prints `K status count id...` with initial output [777,888]. Q prints `Q count_limit byte_limit body_limit priority_limit now count bytes next_ticket sent sent_bytes received received_bytes canceled expired reprioritized revision closed`. C19. Observer valid commands always exit 0 at EOF and print no additional stdout; stream I/O failure exits 2. API behavior is evaluated from raw observations by an external process. Public reproduction: build as C01 then `./mailqueue < repro.in`. The supplied transcript illustrates one observed symptom; all C01..C20 clauses remain required for all parameters.