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

package/CHANGELOG.md

@@ -6,6 +6,69 @@ 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
+
+- **PA-8 — Host Integration SDKs (complete):**
+  - `src/host-loop.ts` (new): stable, versioned wire-format protocol for the Ananke sidecar ↔ renderer bridge. All values on the wire are real SI units (floats, not fixed-point).
+    - **Wire types**: `BridgeVec3`, `BridgeCondition`, `BridgeAnimation`, `BridgePoseModifier`, `BridgeGrappleConstraint`, `BridgeEntitySnapshot`, `BridgeFrame`, `HostLoopConfig`.
+    - **`serializeBridgeFrame(world, config)`**: canonical serializer — converts `WorldState` to `BridgeFrame`. Replaces per-sidecar serializer duplications in Unity and Godot reference implementations.
+    - **`derivePrimaryState(animation)`**: maps `AnimationHints` to a single state string (`"idle"` | `"attack"` | `"flee"` | `"prone"` | `"unconscious"` | `"dead"`). Suitable for top-level renderer state machines.
+    - **`derivePoseOffset(segmentId, impairmentQ)`**: anatomical local-space bone offset at a given impairment level (real metres), for injury deformation blend shapes.
+    - Constants: `BRIDGE_SCHEMA_VERSION = "ananke.bridge.frame.v1"`, `DEFAULT_TICK_HZ = 20`, `DEFAULT_BRIDGE_PORT = 3001`, `DEFAULT_BRIDGE_HOST`, `DEFAULT_STREAM_PATH`.
+  - `"./host-loop"` subpath export added to `package.json`.
+  - **Reference sidecar updates**: both `ananke-unity-reference` and `ananke-godot-reference` sidecars updated to v0.1.57 dependency and refactored to import `serializeBridgeFrame` from `@its-not-rocket-science/ananke/host-loop` — local serialization code removed.
+  - **Quickstart guides** (new):
+    - `docs/quickstart-unity.md`: 15-minute Unity integration guide (sidecar → WebSocket → `AnankeReceiver` → `AnimationDriver` → your mesh).
+    - `docs/quickstart-godot.md`: 15-minute Godot 4 integration guide (GDScript and C# addon variants).
+    - `docs/quickstart-web.md`: Three.js browser integration guide (zero-build-step HTML example + `serializeBridgeFrame` sidecar recipe).
+- 41 new tests (188 test files, 5,553 tests total). Coverage: 97.10% stmt, 88.05% branch, 95.81% func. Build: clean.
+
+---
+
 ## [0.1.56] — 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/host-loop.d.ts

@@ -0,0 +1,188 @@
+import type { WorldState } from "./sim/world.js";
+import { type AnimationHints } from "./model3d.js";
+/** Wire schema identifier — included in every BridgeFrame. */
+export declare const BRIDGE_SCHEMA_VERSION: "ananke.bridge.frame.v1";
+/** Default sidecar tick rate (Hz). */
+export declare const DEFAULT_TICK_HZ = 20;
+/** Default sidecar WebSocket/HTTP port. */
+export declare const DEFAULT_BRIDGE_PORT = 3001;
+/** Default sidecar host. */
+export declare const DEFAULT_BRIDGE_HOST = "127.0.0.1";
+/** Default WebSocket stream path. */
+export declare const DEFAULT_STREAM_PATH = "/stream";
+/**
+ * 3D vector in real metres (float).
+ * Converts from fixed-point SCALE.m: `x_m = x_Sm / SCALE.m`.
+ */
+export interface BridgeVec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Entity physiological condition (Q-values as [0, 1] floats).
+ * Divide the underlying Q value by SCALE.Q (10 000) to get floats.
+ */
+export interface BridgeCondition {
+    /** Shock intensity. q(0) = no shock; q(1.0) = incapacitating. */
+    shockQ: number;
+    /** Fear intensity. q(0) = calm; q(1.0) = panic. */
+    fearQ: number;
+    /** Consciousness level. q(0) = unconscious; q(1.0) = fully alert. */
+    consciousnessQ: number;
+    /** Cumulative fluid loss. q(0) = none; q(1.0) = lethal. */
+    fluidLossQ: number;
+    /** True if the entity is clinically dead. */
+    dead: boolean;
+}
+/**
+ * Animation blend weights and state flags for a renderer character controller.
+ * All Q-values are [0, 1] floats.
+ *
+ * Locomotive blends are mutually exclusive; typically only one is nonzero.
+ */
+export interface BridgeAnimation {
+    idle: number;
+    walk: number;
+    run: number;
+    sprint: number;
+    crawl: number;
+    guardingQ: number;
+    attackingQ: number;
+    shockQ: number;
+    fearQ: number;
+    prone: boolean;
+    unconscious: boolean;
+    dead: boolean;
+    /** Dominant animation state as a single string (see `derivePrimaryState`). */
+    primaryState: string;
+    /** Max locomotion blend weight — useful for speed-parameterised blend trees. */
+    locomotionBlend: number;
+    /** Worst-case injury deformation weight across all body segments. */
+    injuryWeight: number;
+}
+/**
+ * Per-body-segment pose modifier — drives deformation or damage blend shapes.
+ * Q-values are [0, 1] floats.
+ */
+export interface BridgePoseModifier {
+    segmentId: string;
+    /** Overall deformation blend: max(structuralQ, surfaceQ). */
+    impairmentQ: number;
+    structuralQ: number;
+    surfaceQ: number;
+    /**
+     * Anatomical offset for this segment at full impairment, in real metres.
+     * Apply to the bone's local position to show slumping/collapse.
+     */
+    localOffset_m: BridgeVec3;
+}
+/**
+ * Grapple constraint describing hold/held relationships between entities.
+ */
+export interface BridgeGrappleConstraint {
+    isHolder: boolean;
+    holdingEntityId: number;
+    isHeld: boolean;
+    heldByIds: number[];
+    /** Grapple positional state. */
+    position: "standing" | "prone" | "pinned" | "mounted";
+    /** Grip strength [0, 1]. */
+    gripQ: number;
+}
+/**
+ * Complete per-entity snapshot for one simulation tick.
+ */
+export interface BridgeEntitySnapshot {
+    entityId: number;
+    teamId: number;
+    tick: number;
+    /** World position in real metres. */
+    position_m: BridgeVec3;
+    /** Velocity in real m/s. */
+    velocity_mps: BridgeVec3;
+    /** Normalised facing direction (unit vector). */
+    facing: BridgeVec3;
+    /** Mass in real kg. */
+    massKg: number;
+    /** Centre-of-gravity offset from foot position (real metres). */
+    cogOffset_m: {
+        x: number;
+        y: number;
+    };
+    animation: BridgeAnimation;
+    pose: BridgePoseModifier[];
+    grapple: BridgeGrappleConstraint;
+    condition: BridgeCondition;
+}
+/**
+ * Complete serialized frame for one simulation tick.
+ * JSON-encoded and sent over WebSocket / HTTP.
+ */
+export interface BridgeFrame {
+    /** Fixed schema identifier — check this before deserializing. */
+    schema: typeof BRIDGE_SCHEMA_VERSION;
+    scenarioId: string;
+    tick: number;
+    tickHz: number;
+    /** ISO 8601 generation timestamp — for latency diagnostics only. */
+    generatedAt: string;
+    entities: BridgeEntitySnapshot[];
+}
+/**
+ * Sidecar configuration — passed to `serializeBridgeFrame` and used by
+ * host loop implementations.
+ */
+export interface HostLoopConfig {
+    /** Stable identifier for this scenario (e.g. `"knight-vs-brawler"`). */
+    scenarioId: string;
+    /** Simulation tick rate in Hz. Default: `DEFAULT_TICK_HZ` (20). */
+    tickHz?: number;
+    /** Listening port. Default: `DEFAULT_BRIDGE_PORT` (3001). */
+    port?: number;
+    /** Listening host. Default: `DEFAULT_BRIDGE_HOST`. */
+    host?: string;
+}
+/**
+ * Derive a single animation state string from `AnimationHints`.
+ *
+ * Priority: dead > unconscious > prone/crawl > attack > flee (run/sprint) > idle.
+ * Renderer character controllers use this to drive top-level state machines
+ * when a detailed blend tree is not available.
+ *
+ * @returns One of: `"dead"` | `"unconscious"` | `"prone"` | `"attack"` | `"flee"` | `"idle"`
+ */
+export declare function derivePrimaryState(animation: AnimationHints): string;
+/**
+ * Anatomical local-space offset for a body segment at maximum impairment.
+ *
+ * Applied as: `bone.localPosition += poseOffset * impairmentQ`.
+ * Values are in real metres (float).
+ *
+ * @param segmentId   Canonical segment identifier (e.g. `"head"`, `"leftArm"`).
+ * @param impairmentQ Impairment blend weight [0, 1] float.
+ * @returns Local-space offset in real metres.
+ */
+export declare function derivePoseOffset(segmentId: string, impairmentQ: number): BridgeVec3;
+/**
+ * Serialize a complete simulation tick into the stable bridge wire format.
+ *
+ * This is the canonical sidecar serializer.  Replaces per-project
+ * `serialiseFrame` implementations in Unity and Godot sidecars.
+ *
+ * @param world   Current world state after `stepWorld()`.
+ * @param config  Sidecar configuration.
+ * @returns       A `BridgeFrame` safe to `JSON.stringify` and send over WebSocket.
+ *
+ * @example
+ * ```ts
+ * import { serializeBridgeFrame } from "@its-not-rocket-science/ananke/host-loop";
+ *
+ * function tick() {
+ *   stepWorld(world, commands, ctx);
+ *   const frame = serializeBridgeFrame(world, { scenarioId: "my-duel", tickHz: 20 });
+ *   broadcast(JSON.stringify(frame));
+ * }
+ * ```
+ */
+export declare function serializeBridgeFrame(world: WorldState, config: HostLoopConfig): BridgeFrame;

package/dist/src/host-loop.js

@@ -0,0 +1,185 @@
+// src/host-loop.ts — PA-8: Host Integration Bridge Protocol
+//
+// Stable, versioned wire format for the Ananke sidecar ↔ renderer bridge.
+// All values on the wire are in real SI units (floats).
+//
+// Usage in a sidecar:
+//   import { serializeBridgeFrame, HostLoopConfig } from "@ananke/host-loop";
+//
+// Usage in a renderer client (Unity, Godot, Web):
+//   const frame: BridgeFrame = JSON.parse(rawWebSocketMessage);
+//   // field names and types are stable across minor versions
+//
+// Schema version string: BRIDGE_SCHEMA_VERSION.
+// Increment the version suffix (v1 → v2) only on breaking wire changes.
+import { SCALE, q, clampQ, qMul } from "./units.js";
+import { deriveAnimationHints, derivePoseModifiers, deriveGrappleConstraint, deriveMassDistribution, } from "./model3d.js";
+// ── Protocol constants ─────────────────────────────────────────────────────────
+/** Wire schema identifier — included in every BridgeFrame. */
+export const BRIDGE_SCHEMA_VERSION = "ananke.bridge.frame.v1";
+/** Default sidecar tick rate (Hz). */
+export const DEFAULT_TICK_HZ = 20;
+/** Default sidecar WebSocket/HTTP port. */
+export const DEFAULT_BRIDGE_PORT = 3001;
+/** Default sidecar host. */
+export const DEFAULT_BRIDGE_HOST = "127.0.0.1";
+/** Default WebSocket stream path. */
+export const DEFAULT_STREAM_PATH = "/stream";
+// ── Primary state derivation ──────────────────────────────────────────────────
+/**
+ * Derive a single animation state string from `AnimationHints`.
+ *
+ * Priority: dead > unconscious > prone/crawl > attack > flee (run/sprint) > idle.
+ * Renderer character controllers use this to drive top-level state machines
+ * when a detailed blend tree is not available.
+ *
+ * @returns One of: `"dead"` | `"unconscious"` | `"prone"` | `"attack"` | `"flee"` | `"idle"`
+ */
+export function derivePrimaryState(animation) {
+    if (animation.dead)
+        return "dead";
+    if (animation.unconscious)
+        return "unconscious";
+    if (animation.prone || animation.crawl > 0)
+        return "prone";
+    if (animation.attackingQ > 0)
+        return "attack";
+    if (animation.sprint > 0 || animation.run > 0)
+        return "flee";
+    return "idle";
+}
+// ── Pose offset per segment ───────────────────────────────────────────────────
+/**
+ * Anatomical local-space offset for a body segment at maximum impairment.
+ *
+ * Applied as: `bone.localPosition += poseOffset * impairmentQ`.
+ * Values are in real metres (float).
+ *
+ * @param segmentId   Canonical segment identifier (e.g. `"head"`, `"leftArm"`).
+ * @param impairmentQ Impairment blend weight [0, 1] float.
+ * @returns Local-space offset in real metres.
+ */
+export function derivePoseOffset(segmentId, impairmentQ) {
+    // 6% of stature at full impairment (clamp to [0, SCALE.Q])
+    const weightQ = clampQ(Math.round(impairmentQ * SCALE.Q), q(0), SCALE.Q);
+    const offsetQ = qMul(weightQ, q(0.06));
+    const offset = offsetQ / SCALE.Q;
+    // `+ 0` normalises IEEE-754 negative-zero (−0) to plain 0.
+    switch (segmentId) {
+        case "head": return { x: 0, y: (-offset * 0.35) + 0, z: 0 };
+        case "torso":
+        case "thorax":
+        case "abdomen": return { x: 0, y: (-offset * 0.50) + 0, z: 0 };
+        case "leftArm": return { x: (-offset) + 0, y: 0, z: 0 };
+        case "rightArm": return { x: offset, y: 0, z: 0 };
+        case "leftLeg": return { x: (-offset * 0.45) + 0, y: (-offset) + 0, z: 0 };
+        case "rightLeg": return { x: offset * 0.45, y: (-offset) + 0, z: 0 };
+        default: return { x: 0, y: 0, z: 0 };
+    }
+}
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function scaleVec3(v, divisor) {
+    return { x: v.x / divisor, y: v.y / divisor, z: v.z / divisor };
+}
+function normalizeFacing(v) {
+    const mag = Math.hypot(v.x, v.y, v.z) || 1;
+    return { x: v.x / mag, y: v.y / mag, z: v.z / mag };
+}
+function buildBridgeAnimation(animation, pose) {
+    const locomotionBlend = Math.max(animation.idle, animation.walk, animation.run, animation.sprint, animation.crawl) / SCALE.Q;
+    const injuryWeight = pose.reduce((worst, m) => Math.max(worst, m.impairmentQ), 0) / SCALE.Q;
+    return {
+        idle: animation.idle / SCALE.Q,
+        walk: animation.walk / SCALE.Q,
+        run: animation.run / SCALE.Q,
+        sprint: animation.sprint / SCALE.Q,
+        crawl: animation.crawl / SCALE.Q,
+        guardingQ: animation.guardingQ / SCALE.Q,
+        attackingQ: animation.attackingQ / SCALE.Q,
+        shockQ: animation.shockQ / SCALE.Q,
+        fearQ: animation.fearQ / SCALE.Q,
+        prone: animation.prone,
+        unconscious: animation.unconscious,
+        dead: animation.dead,
+        primaryState: derivePrimaryState(animation),
+        locomotionBlend,
+        injuryWeight,
+    };
+}
+function buildBridgeGrapple(grapple) {
+    return {
+        isHolder: grapple.isHolder,
+        holdingEntityId: grapple.holdingEntityId ?? 0,
+        isHeld: grapple.isHeld,
+        heldByIds: grapple.heldByIds,
+        position: grapple.position,
+        gripQ: grapple.gripQ / SCALE.Q,
+    };
+}
+function buildBridgeCondition(entity) {
+    return {
+        shockQ: entity.injury.shock / SCALE.Q,
+        fearQ: (entity.condition.fearQ ?? 0) / SCALE.Q,
+        consciousnessQ: entity.injury.consciousness / SCALE.Q,
+        fluidLossQ: entity.injury.fluidLoss / SCALE.Q,
+        dead: entity.injury.dead,
+    };
+}
+function buildEntitySnapshot(entity, tick) {
+    const animation = deriveAnimationHints(entity);
+    const pose = derivePoseModifiers(entity);
+    const grapple = deriveGrappleConstraint(entity);
+    const mass = deriveMassDistribution(entity);
+    return {
+        entityId: entity.id,
+        teamId: entity.teamId,
+        tick,
+        position_m: scaleVec3(entity.position_m, SCALE.m),
+        velocity_mps: scaleVec3(entity.velocity_mps, SCALE.m),
+        facing: normalizeFacing(entity.action.facingDirQ),
+        massKg: mass.totalMass_kg / SCALE.kg,
+        cogOffset_m: mass.cogOffset_m,
+        animation: buildBridgeAnimation(animation, pose),
+        pose: pose.map(pm => ({
+            segmentId: pm.segmentId,
+            impairmentQ: pm.impairmentQ / SCALE.Q,
+            structuralQ: pm.structuralQ / SCALE.Q,
+            surfaceQ: pm.surfaceQ / SCALE.Q,
+            localOffset_m: derivePoseOffset(pm.segmentId, pm.impairmentQ / SCALE.Q),
+        })),
+        grapple: buildBridgeGrapple(grapple),
+        condition: buildBridgeCondition(entity),
+    };
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Serialize a complete simulation tick into the stable bridge wire format.
+ *
+ * This is the canonical sidecar serializer.  Replaces per-project
+ * `serialiseFrame` implementations in Unity and Godot sidecars.
+ *
+ * @param world   Current world state after `stepWorld()`.
+ * @param config  Sidecar configuration.
+ * @returns       A `BridgeFrame` safe to `JSON.stringify` and send over WebSocket.
+ *
+ * @example
+ * ```ts
+ * import { serializeBridgeFrame } from "@its-not-rocket-science/ananke/host-loop";
+ *
+ * function tick() {
+ *   stepWorld(world, commands, ctx);
+ *   const frame = serializeBridgeFrame(world, { scenarioId: "my-duel", tickHz: 20 });
+ *   broadcast(JSON.stringify(frame));
+ * }
+ * ```
+ */
+export function serializeBridgeFrame(world, config) {
+    return {
+        schema: BRIDGE_SCHEMA_VERSION,
+        scenarioId: config.scenarioId,
+        tick: world.tick,
+        tickHz: config.tickHz ?? DEFAULT_TICK_HZ,
+        generatedAt: new Date().toISOString(),
+        entities: world.entities.map(e => buildEntitySnapshot(e, world.tick)),
+    };
+}

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.56",
+  "version": "0.1.59",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -193,6 +193,14 @@
     "./extended-senses": {
       "import": "./dist/src/extended-senses.js",
       "types": "./dist/src/extended-senses.d.ts"
+    },
+    "./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": [
@@ -258,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",