53 lines
3.3 KiB
Markdown

# Window desk protocol revision 1
The logical store contains capacity bytes at addresses [0, capacity). All ranges
are mathematical intervals: a range (offset,length) is valid iff offset<=capacity
and length<=capacity-offset. The empty range at capacity is valid. Capacity and
individual operands range from 0 through 4294967295. No storage is allocated.
The session has eight slots, initially zero, capacity=1024, seed=0 and zero counters.
Choose the first inactive slot on allocation. IDs are nonzero and unique among
active slots. Each active slot records active=1,id,absolute origin,length,parent.
Top-level views have parent=0. Reserved is the sum of lengths of all active views,
including nested ones; it cannot exceed capacity. Empty views consume a slot.
Z capacity seed resets all state and counters; result value=capacity, detail=seed.
O id origin length opens a top-level view whose range fits the store and budget.
S parent child offset length creates a child from a range fitting the parent,
with absolute origin=parent.origin+offset. The child's length also consumes budget.
Opening/slicing requires a free slot, new nonzero ID, and (for S) active parent.
Each successful allocation increments opens; result value=slot index, detail=length.
R id offset sample_count sample_width previews count consecutive samples of width
1,2,4,8 or16 bytes each within the named active view. The full byte extent is the
mathematical product count*width, and (offset,extent) must fit the view. A valid
empty read at the end is allowed. Successful reads increment reads; result value
is the full extent, detail=min(extent,64), hash=FNV-1a-32 of the first detail bytes
at view.origin+offset. A zero-byte preview hashes to2166136261. Never allocate or
scan the full view: only the first64 bytes are part of the preview.
Q id observes an active view: value=origin, detail=length, hash=parent. It does not
increment reads. C id closes an active view only if it has no active children;
result value=length, detail=slot index. It releases budget, zeros all slot fields,
increments closes. Reusing an ID or slot after close is permitted.
Every rejected logical command has rc=-1 and result value/detail/hash=0; it changes
only rejects (increment1). A successful command has rc=0; result fields not
specified above are zero. Syntax errors produce I sequence without state changes.
The sequence counts all nonempty, noncomment input lines, including syntax errors.
Data adapter byte(seed,address): low=address mod2^32, high=floor(address/2^32).
x=seed XOR low XOR ((high*2654435761) mod2^32); x=x XOR (x>>16);
x=(x*2246822519) mod2^32; x=x XOR (x>>13); byte=x AND255.
FNV-1a-32 begins2166136261, then for each byte XOR and multiply16777619 modulo2^32.
O fields, decimal separated by spaces: sequence, rc, result.value, result.detail,
result.hash, capacity, seed, reserved, opens, closes, reads, rejects, active_count,
followed by eight slots in index order, each active,id,origin,length,parent.
An inactive slot has all fields zero. Counters wrap modulo2^32 if exhausted.
JSON mode groups result fields as result:{rc,value,detail,hash}, counters as
counters:{opens,closes,reads,rejects}, and slots as eight objects each with
active,id,origin,length,parent. Top-level fields are sequence,result,capacity,seed,
reserved,counters,active_count,slots. Invalid syntax emits sequence,input_error=true.