# Architecture
## Mathematical Model
Let state $T$ be represented as a byte sequence of length $S = \text{size\_of::<T>()}$.
At frame step $i \in \mathbb{N}$, the state is given by $S_i \in [0, 255]^S$.
### Differential XOR State Space
The raw byte delta $\Delta_i$ between consecutive frames $S_i$ and $S_{i-1}$ is:
$$
\Delta_i = S_i \oplus S_{i-1}
$$
The sparse delta codec partition operator $\mathcal{P}(\Delta_i)$ splits $\Delta_i$ into $k$ discrete 64-bit words:
$$
k = \left\lceil \frac{S}{8} \right\rceil
$$
For each word $w_j \in \{0, \dots, k-1\}$, the byte-mask flag $b_j$ and byte-mask byte $m_j \in [0, 255]$ are defined as:
$$
b_j = \begin{cases} 0 & \text{if } w_j = \mathbf{0}_8 \\ 1 & \text{if } w_j \neq \mathbf{0}_8 \end{cases}, \quad m_j = \sum_{n=0}^{7} 2^n \cdot \mathbb{I}(w_{j, n} \neq 0)
$$
Where $\mathbb{I}$ is the indicator function and $w_{j, n}$ is the $n$-th byte of word $j$.
### Worst-Case Frame Expansion
The bitstream writer emits 1 bit for $b_j$ plus an 8-bit mask $m_j$ and up to 8 non-zero bytes (64 bits) for active words.
Because `BitWriter::write_u8` byte-aligns before writing the mask, each active word's flag bit wastes up to 7 padding bits — flag bits do not pack across words.
The worst-case upper bound on compressed delta payload size $E_{\max}$ in bytes occurs when all $k$ words are fully mutated:
$$
E_{\max} = 10 \cdot k = 10 \cdot \left\lceil \frac{S}{8} \right\rceil
$$
The code uses `MAX_ENCODED = 10 * k + 1` as a conservative upper bound that also accounts for a partial trailing byte.
## Slot and Arena Layout
The arena consists of a 32-byte header followed by a continuous sequence of variable length slot records,
where each slot comprises a 16-byte header and a variable $L_{\text{payload}}$ byte payload.
### Enforced `#[repr(C)]`
By default, the Rust compiler makes no guarantees about struct field layout, field ordering or padding insertion.
Field ordering can change from one compiler version to another, and may introduce non-deterministic byte padding.
### `ArenaHeader` Specification
Located statically at byte offset 0 of the arena slice.
$$
\text{ArenaHeader} = \Big\langle \text{magic}_{4\text{B}},\, \text{version}_{2\text{B}},\, \text{flags}_{2\text{B}},\, L_{\text{data}},\, \text{off}_{\text{head}},\, \text{off}_{\text{tail}},\, N_{\text{slots}},\, F_{\text{total}} \Big\rangle
$$
- $\text{magic} \in \{0x4250\_5242\}$: Magic constant ("BPRB").
- $\text{version} \in [0, 2^{16}-1]$: Header structure version layout identifier.
- $\text{flags} \in [0, 2^{16}-1]$: Operational state bitmask.
- $L_{\text{data}} \in [0, 2^{32}-1]$: Usable ring buffer capacity in bytes.
- $\text{off}_{\text{head}} \in [0, L_{\text{data}}-1]$: Physical byte offset marking the oldest active slot.
- $\text{off}_{\text{tail}} \in [0, L_{\text{data}}-1]$: Physical byte offset where the next slot is written.
- $N_{\text{slots}} \in [0, 2^{32}-1]$: Number of active, unevicted slots in the arena.
- $F_{\text{total}} \in [0, 2^{64}-1]$: Monotonic lifetime recorded frame counter.
### `SlotHeader` Specification
Prefixes every version entry stored inside the ring buffer.
$$
\text{SlotHeader} = \Big\langle \text{frame}_{8\text{B}},\, L_{\text{payload}\,2\text{B}},\, \text{checksum}_{2\text{B}},\, \text{kind}_{1\text{B}},\, \mathbf{0}_{3\text{B}} \Big\rangle
$$
- $\text{frame} \in [0, 2^{64}-1]$: Monotonic tick/frame index.
- $L_{\text{payload}} \in [0, 2^{16}-1]$: Byte length of the immediately following payload.
- $\text{checksum} \in [0, 2^{16}-1]$: CRC16 integrity validation code across header metadata and payload.
- $\text{kind} \in \{0x01, 0x02\}$: Frame classification where $0x01 = \text{FullSnapshot}$ and $0x02 = \text{Delta}$.
- $\mathbf{0}_{3\text{B}}$: $3$-byte explicit alignment padding.
### `Payload` Specification
The payload immediately follows its corresponding `SlotHeader`. The memory structure is defined by $\text{kind}$:
#### FullSnapshot Payload ($\text{kind} = 0x01$)
A contiguous byte array of fixed size $S = \text{size\_of::<T>()}$:
$$
\text{Payload}_{\text{full}} = [b_0, b_1, \dots, b_{S-1}] \in [0, 255]^S
$$
#### Delta Payload ($\text{kind} = 0x02$)
A variable-length bit-packed sparse XOR delta of length $L_{\text{payload}} \le E_{\max}$:
$$
\text{Payload}_{\text{delta}} = \Big\langle \mathbf{B}_{\text{words}},\, \mathbf{M}_{\text{active}},\, \mathbf{V}_{\text{bytes}} \Big\rangle
$$
- $\mathbf{B}_{\text{words}} \in \{0, 1\}^k$: Bitstream indicating mutated 64-bit word positions across $k = \lceil S / 8 \rceil$ total words.
- $\mathbf{M}_{\text{active}} \in [1, 255]^m$: Array of $m$ 8-bit masks specifying non-zero byte positions within mutated words.
- $\mathbf{V}_{\text{bytes}} \in [0, 255]^n$: Sequence of $n$ raw changed byte values corresponding to set bits across all active word masks.
## Sequence Diagrams
### Snapshot
```mermaid
sequenceDiagram
autonumber
participant App as Application
participant BPRB as BPRB Buffer
participant Codec as Codec
participant Storage as ArenaStorage
App->>BPRB: snapshot(&state)
alt Frame is Anchor (i % interval == 0 OR forced)
BPRB->>Storage: Write SlotHeader (FullSnapshot)
BPRB->>Storage: Write raw state bytes (S bytes)
BPRB->>BPRB: Insert frame into AnchorIndex
else Frame is Delta
BPRB->>Codec: XOR state against head_state
Codec-->>BPRB: Encoded Delta Payload
alt Payload Size > S * threshold
BPRB->>Storage: Fallback to FullSnapshot
BPRB->>BPRB: Insert frame into AnchorIndex
else Payload Size <= S * threshold
BPRB->>Storage: Write SlotHeader (Delta)
BPRB->>Storage: Write byte-masked payload
end
end
BPRB-->>App: Ok(())
```
### Rollback Reconstruction
```mermaid
sequenceDiagram
autonumber
participant App as Application
participant BPRB as BPRB Buffer
participant Index as AnchorIndex
participant Codec as Codec
App->>BPRB: rollback_to(target_frame)
BPRB->>Index: find_nearest_le(target_frame)
Index-->>BPRB: Anchor Entry (anchor_frame, offset)
BPRB->>BPRB: Read Anchor FullSnapshot into stack working buffer
loop f = anchor_frame + 1 to target_frame
BPRB->>BPRB: Read SlotHeader at offset
alt Kind == FullSnapshot
BPRB->>BPRB: Overwrite working buffer
else Kind == Delta
BPRB->>Codec: byte_masked_decode(payload)
Codec-->>BPRB: Decoded delta bytes
BPRB->>BPRB: XOR decoded bytes into working buffer
end
end
BPRB-->>App: Reconstructed State T
```
## Eviction and Capacity Bounds
Let $A_i$ represent snapshot anchor frames and $D_i$ represent deltas.
Because deltas depend sequentially on preceding frames, eviction must drop entire segments bounded by anchors:
$$
\text{Evicted Segment} = \{ A_k, D_{k+1}, D_{k+2}, \dots, D_{m-1} \} \quad \text{where } A_m \text{ is the next anchor}
$$
### Minimum Arena Size
To ensure the buffer holds at least $N_{frames}$ without triggering eviction, the total arena capacity $C_{arena}$ must satisfy:
$$
C_{\text{arena}} \ge 32 + N_{\text{frames}} \cdot \left( 16 + S_{\text{avg}} \right)
$$
Where:
- $S_{\text{avg}} = \frac{S_{\text{anchor}} + (K-1) \cdot S_{\text{delta}}}{K}$.
- $K$ is the anchor interval (anchor_interval).
- $S_{\text{anchor}} = S$ (full state size in bytes).
- $S_{\text{delta}}$ is the average sparse delta byte payload size.