first commit

docs/foundation/bitpacker/bitpacker-game/src/reconciliation/index.md

@@ -0,0 +1,41 @@
+## Reconciliation
+
+**Path:** `src/reconciliation/reconciliation.ts`  
+**Export:** `StateReconciliation`
+
+### What it does
+
+Client-side prediction and server reconciliation for multiplayer games. Buffers inputs and server states, detects mispredictions, and smoothly reconciles client state.
+
+### Key API
+
+| Method | Description |
+|--------|-------------|
+| `processInput(input, timestamp)` | Buffer a player input, return sequence |
+| `predictClientState(state, applyPhysics, deltaTime)` | Apply unprocessed inputs locally |
+| `processServerUpdate(state, sequence, timestamp)` | Receive server-authoritative state |
+| `reconcileState(state, applyPhysics)` | Rewind + replay after server correction |
+| `extrapolateState(state, deltaTime)` | Predict forward for missing server data |
+| `sendPing()` / `receivePong()` | Latency measurement |
+
+### Buffers
+
+- **Input buffer** — stores client inputs with sequence numbers
+- **State buffer** — stores predicted and server states
+- **Jitter buffer** — optional delay for out-of-order server packets
+
+### Reconciliation Flow
+
+1. Client predicts state from inputs
+2. Server sends authoritative state
+3. If prediction error > threshold, reconcile:
+   - Find server state in buffer
+   - Rewind to server state
+   - Replay all inputs after that point
+   - Smoothly interpolate to reconciled state
+
+### Depends on
+
+- `../types.js` — `PlayerState`, `PlayerInput`, `ReconciliationOptions`
+- `../prediction/` — `PositionPredictor`
+- `../interpolation/` — `GameInterpolator`