# Stream service contract v1 This is a deterministic software port for testing a persistent streaming mapping service. It has no real DMA, cache instructions, timing, threads, hardware or network. The two byte views are deliberately independent. All behavior below is part of the service API, including direction, ownership, reuse and cleanup. ## Workspace and build Build with `make` (g++ C++17, standard library only). Run `./stream-demo --demo`, `./stream-demo --receive-demo`, or `./stream-demo < examples/mixed.txt`. The Makefile and support files are public immutable scaffolding. Only `src/session.cpp` is submitted and rebuilt with the original support. The service library must leave stdout to the observation driver; stderr diagnostics are allowed. No particular internal representation or algorithm is required. ## Public API and limits `include/stream.hpp` declares `Session`, `Port`, `Reply`, `Receipt`, and all observation fields. A Session borrows one Port. Slot IDs are 0..3, maximum length is 96 bytes, seeds are unsigned 32-bit values. Input numbers fit unsigned 32-bit except tickets, which fit unsigned 64-bit. Requests are sequential; different slots can be pending concurrently. Every executable invocation creates a fresh Port and Session. Destruction need not implicitly reset; explicit `X` owns cleanup. Direction 1 is ToDevice (TX), 2 is FromDevice (RX), 3 is Both (exchange). Direction is fixed for the lifetime of a mapping. A successful map begins CPU-owned and idle; it does not transfer or synchronize bytes. CPU bytes at absolute index i start as P(seed,i), device bytes as P(seed XOR 0xA5,i). Mapping a previously unmapped slot increments that slot's generation and maps counter. Per-mapping completed count starts at zero. Generation and seven port counters persist across unmaps and remaps. The global next transfer ticket starts at 1 and persists across unmap/reset. P(seed,i) = ((seed XOR (29*i)) + i*i + 17) modulo 256. Arithmetic used for bytes may be reduced modulo 256 at any stage. Digest is 32-bit FNV-1a: start 2166136261, for each byte in order XOR the byte and multiply by 16777619 modulo 2^32. The digest of an empty byte sequence is 2166136261. An idle mapping is CPU-owned. A successful begin hands the entire mapping to the device and performs exactly one selected-range transfer, leaving a pending receipt and device ownership. A successful matching finish returns the entire mapping to CPU ownership, obtains the CPU digest, increments completed, and makes it idle again. Every begin/finish cycle needs a new pair of handoffs, including when neither data nor direction changed. A mapping remains live until explicit unmap/reset; finishing does not remap it. The direction of BOTH handoffs must equal the direction used at map. A CPU→device handoff copies the entire CPU view to device only for TX and Both; for RX it transfers ownership without copying. A device→CPU handoff copies the entire device view to CPU only for RX and Both; for TX it transfers ownership without copying. Each successful handoff increments its corresponding prepares/reclaims counter once; the to_bytes/from_bytes counters increase by mapping length only when that handoff actually copies. One transfer is allowed between each pair of handoffs. CPU access and unmap are permitted only with CPU ownership. Observations of either byte view do not alter state. For a transfer of [offset,offset+count), TX reads device bytes and does not change them; RX overwrites device bytes with P(seed,i) at their absolute indices and does not read an input payload; Both first reads device bytes, then XORs each selected device byte with P(seed,i). Bytes outside the selected range are untouched by the device operation. Synchronization still covers the whole mapping. A receipt has ticket, generation, offset, count, read_hash, write_hash, in that order. read_hash is the selected device range BEFORE the operation for TX/Both, and exactly zero for RX. write_hash is the selected device range AFTER the operation for RX/Both, and exactly zero for TX. Every successful transfer consumes the next global ticket and increments transfers once. Failed requests consume no ticket and change no state. ## Requests, replies, and error priority Each line is one command below. The driver emits one JSON observation after each command. It does no correctness assertions. A Reply has status and values. Status numbers are: 0 OK, 1 SLOT, 2 EXISTS, 3 MISSING, 4 BUSY, 5 RANGE, 6 DIRECTION, 7 TICKET, 8 PORT. PORT is reserved for a failed low-level call and must not occur for any defined request to a correctly implemented service. On every error values is empty and all service and port state is unchanged; invalid requests must be rejected before invoking invalid port operations. All Port operations are public for implementation; the service must keep Port.errors at zero. `M slot length direction seed`: check slot validity, then whether already mapped (EXISTS), then direction (DIRECTION), then length 1..96 (RANGE), in that priority. On success values is [generation]. Already mapped includes pending slots. It has no other effects beyond the map initialization above. `W slot offset count seed`: replace CPU bytes in the range with P(seed,i), using absolute indices. Check SLOT, MISSING, BUSY, then RANGE in that priority. Range fits if offset <= length and count <= length-offset. Zero count is allowed, including offset == length. On success values is empty. Writing is allowed on any idle direction; for RX this CPU write does not publish to device at the next handoff. `R slot offset count`: read CPU bytes. It has the same validation priority and range rules as W. On success values is the sequence of byte values in the requested range, including an empty sequence for count zero. It has no side effects. `B slot offset count seed`: begin a transfer. Check SLOT, MISSING, BUSY, then RANGE. In addition to the W range rules, count must be at least one. The successful result is the six receipt fields described above. No successful B is allowed while that slot is pending. CPU reads/writes, another B and unmap must return BUSY while pending, even when their requested range is invalid or empty. `F slot ticket`: finish the pending transfer with the exact matching ticket. Check SLOT, MISSING, then TICKET. TICKET covers an idle slot, a wrong ticket, an already-finished ticket, or a ticket from an older mapping generation. A rejected F must preserve the pending transfer. On success values is the original six receipt fields followed by digest of ALL CPU bytes after the CPU handoff and the new per-mapping completed count. Tickets cannot be used on a different slot. `U slot`: unmap an idle live slot. Check SLOT, MISSING, BUSY in that priority. On success values is empty, unmaps increases once, and the mapping and its service metadata become absent. CPU/device bytes are no longer in the defined observation range. Generation and port counters survive. `X`: drain all pending slots in ascending slot order with normal finish semantics, then unmap all live slots in ascending slot order. On success values is [number_finished, number_unmapped]. It neither allocates tickets nor changes next_ticket. An empty X succeeds with [0,0]. The final snapshots must show no live mappings, no pending work, and zero port errors. Subsequent M starts new mapping generations normally. ## Raw observation layout The JSON object contains status, values, slots and errors. slots has four objects in slot order. Each manager array is [live,pending,direction,length,completed,ticket]. ticket is zero when idle. All six manager fields are zero when unmapped. Each port array is [live,owner,direction,length,generation,maps,unmaps,prepares,reclaims,transfers,to_bytes,from_bytes]. owner is 0 absent, 1 CPU, 2 device; absent port direction and length are zero. Port counters and generation survive absence. cpu/device are lowercase hex encodings of exactly length bytes while mapped, and empty strings while absent. Storage beyond length is unspecified and must not affect correctness. errors is the cumulative number of invalid low-level operations. No extra restrictions apply to memory outside the defined view or to stderr diagnostics. The driver observes manager metadata separately from the Port's raw bytes, ownership, generation and counters. Correct reply text cannot conceal a missing handoff, discarded work, extra remapping, wrong direction or unreleased mapping. Correctness is determined by the defined observations, not by source text, chosen function names, or a required patch shape.