# Logical resource map session, version 1 This is a deterministic C++17 userspace model. Addresses are integer labels; bytes live in arrays. No MMIO, kernel calls, hardware, clocks, threads, or external services are involved. Implement every clause below. Only the four candidate files listed in README are collected. ## Values and return records The public API is declared in `include/resource_map.hpp` in namespace `resource_map`. Create one `Manager`; copying and moving it are disabled. All operations are sequential. No API operation writes stdout or stderr; raw observer output is the only output. A valid observer invocation, including empty stdin, exits zero, emits the specified LF-terminated bytes on stdout, and emits zero bytes on stderr. There is no CRLF conversion or whitespace tolerance. `Code` has exact integer values: OK=0, ARG=1, STATE=2, MISSING=3, BUSY=4, MAPFAIL=5, STALE=6, RANGE=7, VALUE=8. `Kind` values are MEM=1 and IO=2. Device IDs are 0..7. A resource is `(kind, start, size)` with kind MEM or IO, start 0..65535, size 1..64, and start+size <=65536. A resource occupies the half-open interval [start,start+size). Resource lists contain 0..4 entries; order and duplicates are preserved. IO entries are descriptors only and are never mapped. The nth MEM means the zero-based ordinal among MEM entries, while mapping records contain the original resource-list index. Tokens are unsigned 64-bit integers. Zero is never a live token. Each created mapping consumes the next token, initially 1; a successful reset restarts token numbering at 1. Tests stay below token/counter overflow. Offsets and write values are uint64_t, including UINT64_MAX; widths, counts, IDs, ordinals and fault selectors are signed int. All numeric outputs are decimal. The header defines the full record field order used by the observer. Every error record sets all fields other than `code` to their default zero/empty values, except `DeviceInfo.mem_ordinal` defaults to -1. Querying never changes state or counters. A successful mapping record includes token, owner, original resource index, start, size and its own read/write/fill counters. ## Configuration, acquisition, and removal `reset()` removes all definitions and mappings, zeros every counter, and restarts tokens at 1. It has no return value. Old tokens are invalid until possibly reused after reset. `configure(id, resources)` returns ARG for an invalid ID, resource count, or any invalid descriptor, before considering device state. All descriptors are validated before any mutation. For valid arguments it returns STATE if the device is active; otherwise it stores an independent copy of the entire list, marks the device configured, and returns OK. Empty lists are valid configurations. Reconfiguration of an inactive device replaces its list atomically. Overlap within descriptors is allowed; conflicts concern live mappings only. `probe(id, mem_ordinal, fault)` returns a `ProbeResult(code,token)`. It returns ARG if the ID is outside 0..7, ordinal outside 0..3, or fault outside 0..2. With valid arguments it returns STATE if already active. For an inactive device it returns MISSING if unconfigured or no such MEM ordinal exists. For a selected resource it returns BUSY if the interval overlaps any live mapping. Otherwise the fault selector determines whether mapping succeeds or returns MAPFAIL. Adjacent intervals do not overlap. Errors before injection change no state, token sequence, or counters. Fault 0 creates a mapping with zero-filled bytes, activates only that device, increments created and probe_success, and returns its token. Fault 1 increments probe_faults and returns MAPFAIL without creating a mapping or consuming a token. Fault 2 creates a temporary mapping, consumes one token and increments created, then releases it and increments released and probe_faults; it returns MAPFAIL with token zero. Neither fault leaves an active device or reservation. A retry after either fault can succeed. Each mapping has independent bytes even when a later mapping reuses an address. No register is written implicitly by probe. `remove(id)` returns ARG for invalid ID. Otherwise it returns OK, releases the active mapping if any, and deactivates that device. Removing an inactive or unconfigured device is an idempotent OK. It preserves configuration, all other devices, and historical counters. A released token is STALE for all access and mapping queries. Released reservations cease to block overlap immediately. There is no user release API: the device lifecycle owns release. ## Register and byte operations For `read(token,offset,width)` and `write(token,offset,width,value)`, an unmapped token returns STALE. With a live token, a width other than 1, 2, or 4 returns ARG. With a supported width, an access outside the mapping returns RANGE. A write within the mapping returns VALUE if its value is not representable in width bytes. Widths need no alignment. The full half-open access [offset,offset+width) must lie in [0,size); check this without uint64_t wraparound before accessing bytes or changing counters. A failed access changes no bytes and no counters. Reads and writes use little-endian order. Successful read returns `ReadResult(OK,value)` and increments both its mapping read count and global read_ops once. Failed reads return value zero. Successful write changes width bytes, increments its mapping write count and global write_ops once, and returns OK. Value 0xffffffff is legal for width 4; 256 is VALUE for width 1. No high bits are silently truncated. `fill(token,offset,count,value)` returns STALE first, ARG if count is outside 0..64 or value outside 0..255, then RANGE unless [offset,offset+count) is inside [0,size). A zero-length operation permits offset==size, but not offset>size. A successful fill sets count bytes and increments mapping fills and global fill_ops once, even if count==0. A failure changes nothing. `dump(token,offset,count)` returns STALE for an unmapped token; with a live token it returns ARG for count outside 0..64, otherwise RANGE if the requested interval is outside the mapping. It uses the same zero-length rule and it returns the requested bytes and never increments counters. An error dump has an empty byte vector. No validation is allowed to overflow. ## Direct observation APIs `device(id)` returns ARG for invalid ID. Every valid ID returns OK with configured, active, resource_count, token, and mem_ordinal. A valid but undefined device has false flags and count/token zero, ordinal -1. Configured inactive devices keep resource_count, but token=0 and ordinal=-1. `resource(id,index)` returns ARG for invalid ID or index outside 0..3, then MISSING if the device is undefined or index is at/after its list length; otherwise OK and the exact stored descriptor. Errors leave kind/start/size zero. `mapping(token)` returns STALE if token is not live; otherwise the complete mapping record. `snapshot()` returns all live mapping records sorted by start ascending, then token ascending. It has no placeholders for released entries. These queries do not substitute for one another: both direct and list observations are part of the API. `statistics()` returns fields in this order: created, released, probe_success, probe_faults, read_ops, write_ops, fill_ops, live, live_bytes. The first seven are historical counters since reset. live is the number of currently mapped regions; live_bytes is the sum of their sizes. Fault-2 temporary mappings are included in created/released but absent from live/live_bytes. All records/counters reflect only completed calls. ## Raw observer transport `observer.cpp` is a public, noncandidate stdin adapter. Each whitespace-separated command line invokes exactly one API and emits one response line, with no automatic queries or hidden assertions. Input is syntactically well formed; command arguments have their header types. Empty stdin produces empty stdout. Unknown commands and malformed input are outside this transport contract; API-invalid numeric values are inside it. The grader uses an equivalent adapter with runtime inputs. Commands: `Z`; `C id n (kind start size)*n`; `P id ordinal fault`; `X id`; `R token offset width`; `W token offset width value`; `F token offset count value`; `B token offset count`; `D id`; `E id index`; `M token`; `L`; `S`. C uses n in 0..5 and may pass n=5 to exercise the API's count rejection. Commands Z/C/P/X/R/W/F/B/D/E/M/L/S call reset/configure/probe/remove/read/write/fill/dump/device/resource/mapping/snapshot/statistics respectively. Responses: `Z`; `C code`; `P code token`; `X code`; `R code value`; `W code`; `F code`; `B code n [byte ...]`; `D code configured active resource_count token mem_ordinal`; `E code kind start size`; `M code token owner resource_index start size reads writes fills`; `L n [token owner resource_index start size reads writes fills ...]`; `S created released probe_success probe_faults read_ops write_ops fill_ops live live_bytes`. Booleans are 0/1; [] denotes repeated space-prefixed fields, not literal brackets. Every response ends in one LF with no trailing spaces. Observer transport is fixed; fixes belong in the candidate API implementation.