Initial Commit

packages/networking/drive/drive-template/src/validate/replay.md

@@ -0,0 +1,51 @@
+# replay
+
+## Purpose
+
+Per-client LRU of `(driveId, nonce)` tuples used to reject replayed templates (DTP-06). The cache holds at most `LRU_CAPACITY` entries (default 1024); inserting a new entry that exceeds the cap evicts the least-recently-used one. The LRU is kept in-memory only; the spec calls out that `Drive.initialize()` rebuilds it from the FileLocationIndex.
+
+## Features
+
+- `TemplateNonceLru` — bounded LRU keyed on `(driveId, nonce-hex)`.
+- `has(driveId, nonce)` — query without mutation.
+- `remember(driveId, nonce)` — insert; auto-evicts oldest past the cap.
+- `clear()` / `size` / `capacity` — utility surface for tests + persistence hooks.
+- `TEMPLATE_NONCE_LRU_DEFAULT_CAPACITY` — pinned at 1024 per DTP-06.
+
+## Usage: Basic Example
+
+```ts
+import { TemplateNonceLru } from "@suaveplan/drive-template";
+
+const lru = new TemplateNonceLru();
+lru.remember("drive-1", new Uint8Array(16).fill(7));
+console.log(lru.has("drive-1", new Uint8Array(16).fill(7))); // true
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    TEMPLATE_NONCE_LRU_DEFAULT_CAPACITY,
+    TemplateNonceLru,
+} from "@suaveplan/drive-template";
+
+const lru = new TemplateNonceLru(TEMPLATE_NONCE_LRU_DEFAULT_CAPACITY);
+
+async function rebuildFromFileLocationIndex(seen: Iterable<{ driveId: string; nonce: Uint8Array }>) {
+    lru.clear();
+    for (const entry of seen) {
+        lru.remember(entry.driveId, entry.nonce);
+    }
+    return lru.size;
+}
+```
+
+## API Reference
+
+- `class TemplateNonceLru` — `has`, `remember`, `clear`, `size`, `capacity`.
+- `TEMPLATE_NONCE_LRU_DEFAULT_CAPACITY: 1024`.
+
+## Implementation Notes
+
+The implementation uses an insertion-ordered `Map` and re-inserts duplicates on `remember` to refresh recency. The keys are `<driveId>:<nonce-hex>` strings rather than tuple objects so `Map`'s `===` equality works without needing a custom key class. The capacity check fires AFTER the insert so the eviction policy is "drop the actual oldest", not "drop the entry we're about to overwrite" — this matters when a template re-uses the same `(driveId, nonce)` shortly after another distribution. Persistence support lives in `Drive.initialize()` rather than this module: the LRU rebuilds from the FileLocationIndex on startup so a process restart does not open a replay window.