@its-not-rocket-science/ananke 0.1.57 → 0.1.59

package/CHANGELOG.md

@@ -6,6 +6,48 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.59] — 2026-03-30
+
+### Added
+
+- **PA-10 — Deterministic Networking Kit (complete):**
+  - `src/netcode.ts` (new): determinism utilities for authoritative lockstep and desync diagnosis.
+    - **`hashWorldState(world): bigint`**: FNV-64 hash over `tick`, `seed`, and all entity state sorted by `id` (Map fields serialised as sorted entry arrays for canonical form). Use as a per-tick desync checksum in multiplayer loops.
+    - **`diffReplays(replayA, replayB, ctx): ReplayDiff`**: steps two replays in lock-step and returns the first tick where their hashes diverge. O(N) in replay length.
+    - **`diffReplayJson(jsonA, jsonB, ctx): ReplayDiff`**: convenience wrapper for CLI use.
+    - `ReplayDiff` interface: `{ divergeAtTick, hashA, hashB, ticksCompared }`.
+  - `"./netcode"` subpath export added to `package.json`.
+  - **`ananke replay diff` CLI subcommand**: extends the `npx ananke` CLI — reads two replay JSON files and prints the first divergence tick and hex hashes, or confirms they are identical. Exit code 0 = identical; exit code 1 = divergence.
+  - **`docs/netcode-host-checklist.md`** (new): 8-section guide covering fixed tick rate, no wall-clock reads in simulation path, input serialisation format, desync detection, state resync (full snapshot), replay recording and diff, rollback implementation outline, and KernelContext consistency requirements.
+  - **`examples/lockstep-server.ts`** (new): self-contained authoritative lockstep demo — one server steps the world, two virtual clients verify hash checksums every tick. Demonstrates replay recording and `serializeBridgeFrame` integration.
+  - **`examples/rollback-client.ts`** (new): rollback demo — client predicts speculatively, reconciles against server hash, and re-simulates from the last confirmed snapshot when a mismatch is detected.
+  - npm scripts: `example:lockstep`, `example:rollback`.
+- 16 new tests (189 test files, 5,569 tests total). Coverage: 97.11% stmt, 88.07% branch, 95.82% func. `netcode.ts`: 100%/100%/100%. Build: clean.
+
+---
+
+## [0.1.58] — 2026-03-30
+
+### Added
+
+- **PA-9 — Simulation Cookbook (complete):**
+  - `docs/cookbook.md` (new): 12 task-oriented recipes designed to take a developer from zero to running simulation in under 30 minutes.
+    - **Recipe 1 — Simulate a duel**: `mkWorld` + `stepWorld` + command loop; expected output showing injury accumulation and fight end.
+    - **Recipe 2 — Run a 500-agent battle**: entity loop with `buildAICommands`; timing guidance (≤6 ms/tick on modern hardware).
+    - **Recipe 3 — Author a new species**: custom `Archetype` → `generateIndividual`; species-specific attribute overrides.
+    - **Recipe 4 — Add a custom weapon**: `Item` definition with mass, blade length, and damage profile; `createWorld` with `customItems`.
+    - **Recipe 5 — Drive a renderer**: `serializeBridgeFrame` + WebSocket sidecar pattern; references `docs/quickstart-unity.md`, `docs/quickstart-godot.md`, `docs/quickstart-web.md`.
+    - **Recipe 6 — Create a campaign loop**: `createPolity` + `stepPolityDay`; campaign-to-tactical transition example.
+    - **Recipe 7 — Build a validation scenario**: empirical range-check pattern; tolerance bands and `±%` reporting.
+    - **Recipe 8 — Use the what-if engine**: `npm run run:what-if`; scenario customization via parameter override.
+    - **Recipe 9 — Stream events to an agent**: delta detection + `serializeBridgeFrame` push over Server-Sent Events.
+    - **Recipe 10 — Save and reload a world**: `JSON.stringify` / `JSON.parse` round-trip with tick continuity check.
+    - **Recipe 11 — Record and replay a fight**: `ReplayRecorder` + `replayTo` + `serializeReplay` / `deserializeReplay`.
+    - **Recipe 12 — Load a content pack**: `loadPack` + `validatePack` + pack JSON schema reference.
+  - `README.md`: cookbook cross-link added in intro and "Further reading" table.
+
+---
+
 ## [0.1.57] — 2026-03-30
 
 ### Added

package/README.md

@@ -96,6 +96,9 @@ for (let tick = 0; tick < 2000; tick++) {
 `stepWorld` is the only function that mutates state.  Everything else is pure computation.
 Call it at 20 Hz for real-time simulation; 1 Hz or lower for campaign-scale time.
 
+For task-oriented walkthroughs, see the **[Simulation Cookbook](docs/cookbook.md)** — 12 recipes
+from "Simulate a duel" to "Load a content pack", each with step-by-step code and expected output.
+
 ---
 
 ## Quick start A — Melee combat
@@ -411,6 +414,7 @@ Ananke's outputs are validated against historical and experimental sources:
 
 | Document | What's in it |
 |---|---|
+| [`docs/cookbook.md`](docs/cookbook.md) | Task-oriented recipes — duel, 500-agent battle, species, renderer, campaign, replay, and more |
 | [`docs/module-index.md`](docs/module-index.md) | All 41 entry points — stability tier, use case, key exports, doc links |
 | [`docs/host-contract.md`](docs/host-contract.md) | Stable integration surface — everything needed to embed Ananke without reading `src/` |
 | [`docs/integration-primer.md`](docs/integration-primer.md) | Data-flow diagrams, type glossary, gotchas |

package/dist/src/netcode.d.ts

@@ -0,0 +1,50 @@
+import type { WorldState } from "./sim/world.js";
+import type { KernelContext } from "./sim/context.js";
+import { type Replay } from "./replay.js";
+/**
+ * Compute a deterministic 64-bit hash of the simulation's core state.
+ *
+ * Covers `tick`, `seed`, and all entity data sorted by `id`.  Optional
+ * subsystem fields (`__sensoryEnv`, `__factionRegistry`, etc.) are excluded —
+ * they are host concerns and do not affect simulation determinism.
+ *
+ * Use this as a desync checksum in multiplayer loops:
+ *
+ * ```ts
+ * const hash = hashWorldState(world);
+ * socket.emit("tick-ack", { tick: world.tick, hash: hash.toString() });
+ * ```
+ *
+ * @returns An unsigned 64-bit bigint.
+ */
+export declare function hashWorldState(world: WorldState): bigint;
+/** Result of comparing two replay traces. */
+export interface ReplayDiff {
+    /** Tick at which the two replays first diverge. `-1` means the initial
+     *  states differ before any step.  `undefined` means the replays are
+     *  identical up to the last compared tick. */
+    divergeAtTick: number | undefined;
+    /** Hash from replay A at the divergence tick (`undefined` when identical). */
+    hashA: bigint | undefined;
+    /** Hash from replay B at the divergence tick (`undefined` when identical). */
+    hashB: bigint | undefined;
+    /** Total ticks compared (including the initial-state check). */
+    ticksCompared: number;
+}
+/**
+ * Compare two replay traces tick-by-tick and find the first divergence.
+ *
+ * Steps both replays from their initial states in lock-step, computing
+ * `hashWorldState` after each tick.  O(N) in replay length.
+ *
+ * @param replayA  First replay (e.g. client A's recording).
+ * @param replayB  Second replay (e.g. client B's recording).
+ * @param ctx      KernelContext forwarded to `stepWorld`.
+ */
+export declare function diffReplays(replayA: Replay, replayB: Replay, ctx: KernelContext): ReplayDiff;
+/**
+ * Parse two replay JSON strings and diff them.
+ *
+ * Convenience wrapper over `diffReplays` for CLI use.
+ */
+export declare function diffReplayJson(jsonA: string, jsonB: string, ctx: KernelContext): ReplayDiff;

package/dist/src/netcode.js

@@ -0,0 +1,115 @@
+// src/netcode.ts — PA-10: Deterministic Networking Kit
+//
+// Utilities for authoritative lockstep and desync diagnosis.
+//
+// Core guarantee: two clients running identical commands from identical seeds
+// must produce identical hashWorldState() outputs at every tick.  A mismatch
+// pinpoints the first tick where state diverged.
+import { stepWorld } from "./sim/kernel.js";
+import { deserializeReplay } from "./replay.js";
+// ── FNV-64 hash ───────────────────────────────────────────────────────────────
+// 64-bit Fowler–Noll–Vo (FNV-1a) over UTF-16 code units.  Pure arithmetic,
+// no external dependencies, portable across Node and browsers.
+const FNV64_OFFSET = 14695981039346656037n;
+const FNV64_PRIME = 1099511628211n;
+const UINT64_MASK = 0xffffffffffffffffn;
+function fnv64(data) {
+    let hash = FNV64_OFFSET;
+    for (let i = 0; i < data.length; i++) {
+        hash ^= BigInt(data.charCodeAt(i));
+        hash = (hash * FNV64_PRIME) & UINT64_MASK;
+    }
+    return hash;
+}
+// ── Stable JSON serialiser ────────────────────────────────────────────────────
+// JSON.stringify with sorted object keys so property insertion order does not
+// affect the hash.  Maps (armourState, foodInventory, reputations) are
+// serialised as sorted entry arrays to guarantee a canonical form.
+function stableReplacer(_key, value) {
+    if (value instanceof Map) {
+        const entries = [...value.entries()]
+            .sort(([a], [b]) => String(a).localeCompare(String(b)));
+        return { __map__: entries };
+    }
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const sorted = {};
+        for (const k of Object.keys(value).sort()) {
+            sorted[k] = value[k];
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Compute a deterministic 64-bit hash of the simulation's core state.
+ *
+ * Covers `tick`, `seed`, and all entity data sorted by `id`.  Optional
+ * subsystem fields (`__sensoryEnv`, `__factionRegistry`, etc.) are excluded —
+ * they are host concerns and do not affect simulation determinism.
+ *
+ * Use this as a desync checksum in multiplayer loops:
+ *
+ * ```ts
+ * const hash = hashWorldState(world);
+ * socket.emit("tick-ack", { tick: world.tick, hash: hash.toString() });
+ * ```
+ *
+ * @returns An unsigned 64-bit bigint.
+ */
+export function hashWorldState(world) {
+    const sorted = [...world.entities].sort((a, b) => a.id - b.id);
+    const canonical = JSON.stringify({ tick: world.tick, seed: world.seed, entities: sorted }, stableReplacer);
+    return fnv64(canonical);
+}
+/**
+ * Compare two replay traces tick-by-tick and find the first divergence.
+ *
+ * Steps both replays from their initial states in lock-step, computing
+ * `hashWorldState` after each tick.  O(N) in replay length.
+ *
+ * @param replayA  First replay (e.g. client A's recording).
+ * @param replayB  Second replay (e.g. client B's recording).
+ * @param ctx      KernelContext forwarded to `stepWorld`.
+ */
+export function diffReplays(replayA, replayB, ctx) {
+    const worldA = structuredClone(replayA.initialState);
+    const worldB = structuredClone(replayB.initialState);
+    // Check initial state before any steps.
+    const initA = hashWorldState(worldA);
+    const initB = hashWorldState(worldB);
+    if (initA !== initB) {
+        return { divergeAtTick: -1, hashA: initA, hashB: initB, ticksCompared: 0 };
+    }
+    const maxFrames = Math.min(replayA.frames.length, replayB.frames.length);
+    for (let i = 0; i < maxFrames; i++) {
+        const frameA = replayA.frames[i];
+        const frameB = replayB.frames[i];
+        const cmdsA = new Map(frameA.commands.map(([id, cmds]) => [id, cmds]));
+        const cmdsB = new Map(frameB.commands.map(([id, cmds]) => [id, cmds]));
+        stepWorld(worldA, cmdsA, ctx);
+        stepWorld(worldB, cmdsB, ctx);
+        const hA = hashWorldState(worldA);
+        const hB = hashWorldState(worldB);
+        if (hA !== hB) {
+            return {
+                divergeAtTick: worldA.tick,
+                hashA: hA,
+                hashB: hB,
+                ticksCompared: i + 1,
+            };
+        }
+    }
+    // If one replay has more frames, that's not a divergence — just a shorter
+    // recording on one side.
+    return { divergeAtTick: undefined, hashA: undefined, hashB: undefined, ticksCompared: maxFrames };
+}
+/**
+ * Parse two replay JSON strings and diff them.
+ *
+ * Convenience wrapper over `diffReplays` for CLI use.
+ */
+export function diffReplayJson(jsonA, jsonB, ctx) {
+    const replayA = deserializeReplay(jsonA);
+    const replayB = deserializeReplay(jsonB);
+    return diffReplays(replayA, replayB, ctx);
+}

package/dist/tools/pack-cli.js

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
-// tools/pack-cli.ts — PA-4: Ananke content pack CLI
+// tools/pack-cli.ts — PA-4 / PA-10: Ananke CLI
 //
 // Usage (after npm run build):
 //   node dist/tools/pack-cli.js pack validate <file.json>
 //   node dist/tools/pack-cli.js pack bundle <directory>
+//   node dist/tools/pack-cli.js replay diff <a.json> <b.json>
 //
 // Or via the installed binary:
 //   npx ananke pack validate <file.json>
 //   npx ananke pack bundle <directory>
+//   npx ananke replay diff <a.json> <b.json>
 import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve, extname, basename } from "node:path";
 import { validatePack, loadPack } from "../src/content-pack.js";
+import { diffReplayJson } from "../src/netcode.js";
+import { q } from "../src/units.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function readJson(filePath) {
     try {
@@ -122,34 +126,99 @@ function cmdLoad(args) {
     console.log(`   scenarios:  ${result.scenarioIds.join(", ") || "none"}`);
     console.log(`   fingerprint: ${result.fingerprint}`);
 }
+function cmdReplayDiff(args) {
+    const fileA = args[0];
+    const fileB = args[1];
+    if (!fileA || !fileB) {
+        console.error("Usage: ananke replay diff <replay-a.json> <replay-b.json>");
+        process.exit(1);
+    }
+    let jsonA;
+    let jsonB;
+    try {
+        jsonA = readFileSync(resolve(fileA), "utf8");
+    }
+    catch (e) {
+        console.error(`Cannot read ${fileA}: ${String(e)}`);
+        process.exit(1);
+    }
+    try {
+        jsonB = readFileSync(resolve(fileB), "utf8");
+    }
+    catch (e) {
+        console.error(`Cannot read ${fileB}: ${String(e)}`);
+        process.exit(1);
+    }
+    const ctx = { tractionCoeff: q(1.0) };
+    const result = diffReplayJson(jsonA, jsonB, ctx);
+    console.log(`Ticks compared: ${result.ticksCompared}`);
+    if (result.divergeAtTick === undefined) {
+        console.log("✓  Replays are identical — no divergence detected.");
+        process.exit(0);
+    }
+    if (result.divergeAtTick === -1) {
+        console.error("✗  Initial states differ (before tick 0).");
+        console.error(`   hash A: ${result.hashA?.toString(16)}`);
+        console.error(`   hash B: ${result.hashB?.toString(16)}`);
+        process.exit(1);
+    }
+    console.error(`✗  Divergence at tick ${result.divergeAtTick}.`);
+    console.error(`   hash A: ${result.hashA?.toString(16)}`);
+    console.error(`   hash B: ${result.hashB?.toString(16)}`);
+    process.exit(1);
+}
 // ── Entry point ───────────────────────────────────────────────────────────────
 function main() {
     const argv = process.argv.slice(2);
-    if (argv[0] !== "pack") {
-        console.log("Ananke CLI");
-        console.log("");
-        console.log("Commands:");
-        console.log("  pack validate <file.json>           — validate a pack manifest");
-        console.log("  pack bundle <directory> [out.json]  — merge JSON files into one pack");
-        console.log("  pack load <file.json>               — load a pack and report registered ids");
+    const cmd = argv[0];
+    if (!cmd) {
+        printHelp();
         process.exit(0);
     }
     const sub = argv[1];
     const rest = argv.slice(2);
-    switch (sub) {
-        case "validate":
-            cmdValidate(rest);
+    switch (cmd) {
+        case "pack":
+            switch (sub) {
+                case "validate":
+                    cmdValidate(rest);
+                    break;
+                case "bundle":
+                    cmdBundle(rest);
+                    break;
+                case "load":
+                    cmdLoad(rest);
+                    break;
+                default:
+                    console.error(`Unknown subcommand: pack ${sub ?? ""}`);
+                    console.error("Available: validate, bundle, load");
+                    process.exit(1);
+            }
             break;
-        case "bundle":
-            cmdBundle(rest);
-            break;
-        case "load":
-            cmdLoad(rest);
+        case "replay":
+            switch (sub) {
+                case "diff":
+                    cmdReplayDiff(rest);
+                    break;
+                default:
+                    console.error(`Unknown subcommand: replay ${sub ?? ""}`);
+                    console.error("Available: diff");
+                    process.exit(1);
+            }
             break;
         default:
-            console.error(`Unknown subcommand: pack ${sub ?? ""}`);
-            console.error("Available: validate, bundle, load");
+            console.error(`Unknown command: ${cmd}`);
+            printHelp();
             process.exit(1);
     }
 }
+function printHelp() {
+    console.log("Ananke CLI");
+    console.log("");
+    console.log("Commands:");
+    console.log("  pack validate <file.json>                  — validate a pack manifest");
+    console.log("  pack bundle <directory> [out.json]         — merge JSON files into one pack");
+    console.log("  pack load <file.json>                      — load a pack and report registered ids");
+    console.log("  replay diff <replay-a.json> <replay-b.json> — find the first tick divergence between two replays");
+}
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -197,6 +197,10 @@
     "./host-loop": {
       "import": "./dist/src/host-loop.js",
       "types": "./dist/src/host-loop.d.ts"
+    },
+    "./netcode": {
+      "import": "./dist/src/netcode.js",
+      "types": "./dist/src/netcode.d.ts"
     }
   },
   "workspaces": [
@@ -262,6 +266,8 @@
     "example:combat": "node dist/examples/quickstart-combat.js",
     "example:campaign": "node dist/examples/quickstart-campaign.js",
     "example:species": "node dist/examples/quickstart-species.js",
+    "example:lockstep": "node dist/examples/lockstep-server.js",
+    "example:rollback": "node dist/examples/rollback-client.js",
     "generate-module-index": "node dist/tools/generate-module-index.js",
     "pack": "node dist/tools/pack-cli.js pack",
     "generate-fixtures": "node dist/tools/generate-fixtures.js",