first commit

docs/foundation/bitpacker/bitpacker-delta/src/delta-manager/delta-manager.md

@@ -0,0 +1,123 @@
+# DeltaManager
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`DeltaManager` is the field-level delta detector for bit-packed objects. Given a current state and a `BitPackerSchema` describing it, it returns the ordered list of fields whose value has changed since the previous snapshot stored under the same state key. Encoders use the returned `FieldChange[]` to build a fixed-width bitmask and send only the changed fields, dramatically reducing bandwidth for high-frequency state-sync workloads (game replication, multi-peer document sync, telemetry deltas).
+
+This is the port of suaveplan's upstream `core/delta/delta-manager.ts`. hardening replaces upstream's `Date.now()` with injectable `Clock` (CLAUDE.md determinism rule), upstream's `JSON.stringify`-based equality with a structural walker that respects `BitPackerSchema` field order (avoiding subtle false-positive diffs from key-order changes in nested objects), upstream's plain `Error` throws with `BitpackerError` codes, and validates `DeltaConfig` via Zod with strict-mode key rejection.
+
+## Features
+
+- Field-indexed `FieldChange[]` output matching `Object.keys(schema)` order for stable bit offsets
+- Per-state-key snapshot store with LRU eviction (delegates to `DeltaStateManager`)
+- Configurable `maxFieldCount` cap with `BITPACKER.DELTA_FIELD_LIMIT_EXCEEDED` enforcement
+- Structural equality default (matches schema semantics) with opt-in `equalityMode: "json"` for upstream byte-compat
+- Zod-validated `DeltaConfig`; unknown keys rejected with `BITPACKER.DELTA_INVALID_CONFIG`
+- Threshold-driven `shouldUseDelta(originalBits, deltaBits)` for bandwidth-savings decisions
+- Zero `Math.random` / `Date.now` in the implementation — fully deterministic given identical inputs
+
+## Usage: Basic Example
+
+```typescript
+import { DeltaManager } from "@suaveplan/bitpacker-delta";
+
+const schema = { x: "u32", y: "u32" } as const;
+const dm = new DeltaManager({ mode: "field-level" });
+
+// First call: no previous state, so no changes.
+dm.detectChanges({ x: 0, y: 0 }, schema); // → []
+dm.storePreviousState({ x: 0, y: 0 });
+
+// Second call: x changed.
+dm.detectChanges({ x: 5, y: 0 }, schema);
+// → [{ index: 0, key: "x", previousValue: 0, currentValue: 5 }]
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { DeltaManager } from "@suaveplan/bitpacker-delta";
+
+const schema = {
+    pos: { x: "f32", y: "f32" },
+    vel: { x: "f32", y: "f32" },
+    health: "u8",
+} as const;
+
+// Per-peer state streams: one DeltaManager, many state keys.
+const dm = new DeltaManager(
+    { mode: "field-level", threshold: 25, maxFieldCount: 16 },
+    { maxStates: 256 } // 256 simultaneous peers
+);
+
+for (const peer of peers) {
+    // Each peer is its own state stream.
+    const previous = dm.getPreviousState(peer.id);
+    const changes = dm.detectChanges(peer.state, schema, peer.id);
+
+    // Only send a delta if it saves at least 25% of bits.
+    const fullSize = bitWidthOf(schema);
+    const deltaSize = changes.length * 32 + Math.ceil(3 / 8) * 8;
+    if (dm.shouldUseDelta(fullSize, deltaSize)) {
+        sendDelta(peer.id, changes);
+    } else {
+        sendFull(peer.id, peer.state);
+    }
+
+    dm.storePreviousState(peer.state, peer.id);
+}
+```
+
+## API Reference
+
+### `new DeltaManager(config?: DeltaConfig, options?: DeltaManagerOptions)`
+
+`config.mode` ∈ `"none" | "xor" | "string-diff" | "field-level"`. Default `"none"`.
+`config.threshold` — bandwidth-savings %, 0–100. Default `0`.
+`config.maxFieldCount` — max fields the bitmask can address. Default `64`.
+`config.stateKey` — default key for `detectChanges` calls without one. Default `"default"`.
+`config.equalityMode` — `"structural"` (default) or `"json"` (upstream-compat).
+`options.maxStates` — capacity of the underlying state store. Default `100`.
+
+Throws `BitpackerError(BITPACKER.DELTA_INVALID_CONFIG)` on invalid config.
+
+### `detectChanges(current, schema, stateKey?) → FieldChange[]`
+
+Returns the ordered list of fields whose `current` value differs from the stored snapshot under `stateKey`. First call (no snapshot) returns `[]`. Schema with more keys than `maxFieldCount` throws `BITPACKER.DELTA_FIELD_LIMIT_EXCEEDED`.
+
+### `storePreviousState(state, stateKey?) → void`
+
+Stores a deep-cloned snapshot of `state` for the next diff.
+
+### `getPreviousState(stateKey?) → unknown | undefined`
+
+### `hasPreviousState(stateKey?) → boolean`
+
+Snapshot inspection helpers.
+
+### `calculateSavings(originalBits, deltaBits) → number`
+
+### `shouldUseDelta(originalBits, deltaBits) → boolean`
+
+Bandwidth-savings calculation against the configured `threshold`.
+
+### `clear() → void`
+
+### `clearState(stateKey) → void`
+
+### `getConfig() → Readonly<Required<DeltaConfig>>`
+
+Lifecycle and inspection helpers.
+
+## Implementation Notes
+
+The structural-equality walker treats every `ArrayBuffer.isView` value (every typed-array variant) as a byte-by-byte comparison. `Date` instances compare via `getTime()`. Plain objects compare key-sets first (size + key membership), then recurse on values. Arrays compare length-then-elements. This matches `BitPackerSchema` semantics: two values that pack to identical bytes are equal.
+
+The `"json"` equality mode is provided for upstream byte-compat but has known limitations: `JSON.stringify({ a: 1, b: 2 })` and `JSON.stringify({ b: 2, a: 1 })` produce different strings even though the values are semantically equal in a `BitPackerSchema` context. Consumers porting from upstream should switch to `"structural"` once they've verified no callers depend on key-order-sensitive equality.
+
+The `maxFieldCount` cap is a defence: a hostile peer that sends a schema with thousands of fields could exhaust memory if the bitmask were unbounded. The default (64) accommodates typical state-sync workloads; consumers with larger schemas raise it explicitly.
+
+Threshold semantics: `shouldUseDelta` returns `true` when `(originalBits - deltaBits) / originalBits * 100 >= threshold`. A `threshold` of `0` means "always prefer delta when smaller"; a `threshold` of `25` means "only prefer delta if it saves at least a quarter of the bits."