53 lines
3.1 KiB
Markdown
53 lines
3.1 KiB
Markdown
# OTP Dynamic Partitioning & Rebalancing Protocol Plan
|
|
|
|
## 1. Core Design Principles
|
|
|
|
1. **Strictly One `.state` File Per Pad (`<chksum>.state`)**:
|
|
- Every app/device maintains a single `<chksum>.state` file alongside `<chksum>.pad`.
|
|
- No `.split.state` files or device names/IDs are ever created.
|
|
2. **All Splits Emit a Pure-OTP Grant Message (`OTP-GRANT-V1`)**:
|
|
- Onboarding a brand-new device and rebalancing space to an existing device are the **exact same operation** (`split`).
|
|
- When `split` runs, the donor device cuts its remaining unused `[offset, end_offset)` in half at `mid` (aligned to 256-byte chunks), updates its own `<chksum>.state` (`end_offset=mid` and `peer_extent=mid:old_end`) **first** (`fsync`), and outputs a 256-byte ASCII-armored Pure-OTP message (`OTP-GRANT-V1`) encrypted at offset `mid`.
|
|
- Because the `OTP-GRANT-V1` message is encrypted at `mid` (256 bytes), the recipient's usable partition starts at `mid + 256` (`Grant-Start: mid + 256`), guaranteeing even the 256 bytes used to encrypt the grant itself are never reused!
|
|
3. **Nameless, Byte-Range Partition Tracking (`peer_extent=start:end`)**:
|
|
- Partitions are identified purely by their byte ranges `start:end`.
|
|
- When a donor splits off `[mid, old_end)`, it records `peer_extent=mid+256:old_end` in its `<chksum>.state` file.
|
|
- Whenever any app decrypts a regular OTP message at `Pad-Offset: P` of length `L` (`P + L`), if `P` falls within a known `peer_extent=start:end` (`start <= P < end`), the app automatically updates that `peer_extent` to `(P + L):end`!
|
|
- Thus, simply by exchanging normal OTP messages, an app passively sees how much space its peer partitions have left.
|
|
|
|
---
|
|
|
|
## 2. Single `.state` File Format
|
|
|
|
```ini
|
|
offset=10485760
|
|
end_offset=40000000
|
|
next_extent=95000000:120000000
|
|
peer_extent=40000256:65000000
|
|
peer_extent=70002048:95000000
|
|
```
|
|
|
|
- `offset`: Current write cursor for this app's active partition.
|
|
- `end_offset`: Exclusive upper bound of this app's active partition (defaults to `pad_size` if omitted in legacy `.state` files).
|
|
- `next_extent`: Zero or more `start:end` extents queued for this app (from received `OTP-GRANT-V1` messages). Automatically popped into `offset` / `end_offset` when the active partition runs out.
|
|
- `peer_extent`: Zero or more `start:end` extents known to belong to other apps/devices. Automatically advanced when decrypting messages whose `Pad-Offset` falls inside `[start, end)`.
|
|
|
|
---
|
|
|
|
## 3. Pure-OTP Grant Message Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant AppA as App 1 - Donor
|
|
participant AppB as App 2 - Recipient
|
|
|
|
Note over AppA: Owns [offset, end_offset)
|
|
AppA->>AppA: mid = align_256((offset + end_offset) / 2)
|
|
AppA->>AppA: grant_start = mid + 256, grant_end = old_end
|
|
AppA->>AppA: Save end_offset=mid & peer_extent=grant_start:grant_end to .state FIRST
|
|
AppA->>AppA: Encrypt OTP-GRANT-V1(grant_start, grant_end) using 256B at mid
|
|
AppA->>AppB: Send standard -----BEGIN OTP MESSAGE----- block
|
|
AppB->>AppB: Decrypt message at mid -> parse OTP-GRANT-V1
|
|
AppB->>AppB: Update single <chksum>.state with [grant_start, grant_end)
|
|
```
|