@its-not-rocket-science/ananke 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -10,6 +10,26 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.7] — 2026-03-23
+
+  ### Added
+
+  - **CE-9 · World-state Diffing and Incremental Snapshots** (`src/sim/cover.ts`)
+    - diffWorldState(prev, next): top-level-field diff per entity; world
+      scalar/subsystem diffs; added/removed entity tracking
+    - applyDiff(base, diff): reconstruct next state (non-mutating, copy-on-write)
+    - packDiff(diff): custom binary encoding — magic "ANKD", tagged-value
+      format (null/bool/uint8/int32/float64/string/array/object); zero
+      external dependencies, implemented with DataView/Uint8Array
+    - unpackDiff(bytes): full round-trip with magic and version validation
+    - isDiffEmpty(), diffStats() — helpers for logging and network budgeting
+    - 30 tests; verified binary size < full JSON for single-entity changes
+    - Export via src/index.ts
+
+---
+
+---
+
 ## [0.1.6] — 2026-03-23
 
   ### Added

package/dist/src/index.d.ts

@@ -20,3 +20,5 @@ export * from "./scenario.js";
 export * from "./catalog.js";
 export * from "./sim/formation-combat.js";
 export * from "./sim/cover.js";
+export * from "./sim/ai/behavior-trees.js";
+export * from "./snapshot.js";

package/dist/src/index.js

@@ -29,3 +29,5 @@ export * from "./scenario.js"; // loadScenario(), validateScenario(), AnankeScen
 export * from "./catalog.js"; // CE-12: registerArchetype(), registerWeapon(), registerArmour(), getCatalogEntry()
 export * from "./sim/formation-combat.js"; // Phase 69: FormationUnit, TacticalEngagement, resolveTacticalEngagement()
 export * from "./sim/cover.js"; // CE-15: CoverSegment, computeCoverProtection(), isLineOfSightBlocked(), applyExplosionToTerrain()
+export * from "./sim/ai/behavior-trees.js"; // CE-10: BehaviorNode, FlankTarget, RetreatTo, ProtectAlly, GuardPosition, HealTarget, Sequence, Fallback
+export * from "./snapshot.js"; // CE-9: diffWorldState(), applyDiff(), packDiff(), unpackDiff(), WorldStateDiff

package/dist/src/sim/ai/behavior-trees.d.ts

@@ -0,0 +1,166 @@
+/**
+ * CE-10 — Pre-built AI Behavior Tree Library
+ *
+ * A thin, composable layer over the existing AI decision system.  Each
+ * `BehaviorNode` receives the ticking entity, the current world state, and
+ * kernel context, and either returns a `Command` (success) or `null` (failure /
+ * not applicable).
+ *
+ * ## Semantics
+ * - `null`  — node failed / condition not met
+ * - Command — node succeeded; caller should use this command
+ *
+ * ## Composite nodes
+ * - `Sequence`  — run children left-to-right; return first **non-null** result
+ *                 (priority / fallback selector pattern)
+ * - `Fallback`  — identical semantics to Sequence for this usage:
+ *                 try children in order, first non-null wins
+ *
+ * Note: The ROADMAP spec uses "first success wins" for both Sequence and
+ * Fallback (i.e. both are priority-selectors).  A traditional BT Sequence
+ * would return the *last* child result; here all composites return the first
+ * non-null command for practical game-AI use.
+ *
+ * ## Determinism constraint
+ * All nodes are deterministic.  Any tie-breaking or random sampling uses
+ * `eventSeed(world.seed, world.tick, entity.id, salt)` — never `Math.random()`.
+ */
+import type { Entity } from "../entity.js";
+import type { WorldState } from "../world.js";
+import type { KernelContext } from "../context.js";
+import type { Command } from "../commands.js";
+import { type Q } from "../../units.js";
+/**
+ * A single node in a behavior tree.
+ *
+ * `tick` is called once per AI frame (typically once per `stepWorld` tick).
+ * Returns a `Command` if this node produces an action, or `null` if the node's
+ * condition is not satisfied (pass control to the next node in a composite).
+ */
+export interface BehaviorNode {
+    tick(entity: Entity, world: WorldState, ctx: KernelContext): Command | null;
+}
+/**
+ * Move toward a target entity and attack when in range.
+ *
+ * If the target is dead or missing, returns null.
+ * Flanks by approaching from the target's perpendicular when `flankOffset > 0`.
+ *
+ * @param targetId     Id of the entity to flank/attack.
+ * @param flankOffset  Lateral offset in SCALE.m units (0 = direct approach).
+ */
+export declare function FlankTarget(targetId: number, flankOffset?: number): BehaviorNode;
+/**
+ * Move to a fixed world position and stop when within `arrivalRadius_m` metres.
+ *
+ * Returns null when already at the destination (no command needed).
+ *
+ * @param x_m           Destination x [SCALE.m].
+ * @param y_m           Destination y [SCALE.m].
+ * @param arrivalRadius_m  Stop radius [SCALE.m]. Default 5 000 (0.5 m).
+ */
+export declare function RetreatTo(x_m: number, y_m: number, arrivalRadius_m?: number): BehaviorNode;
+/**
+ * Move toward an allied entity and interpose between it and the nearest threat.
+ *
+ * - If ally is missing or dead, returns null.
+ * - If no threats (other entities) are present, returns null.
+ * - Otherwise moves toward the ally.
+ *
+ * @param allyId   Id of the entity to protect.
+ */
+export declare function ProtectAlly(allyId: number): BehaviorNode;
+/**
+ * Hold a position: move toward the guard point if outside `radius_m`, defend
+ * if inside.  Returns null when the entity is already inside the radius and
+ * there are no threats to defend against.
+ *
+ * @param x_m       Guard point x [SCALE.m].
+ * @param y_m       Guard point y [SCALE.m].
+ * @param radius_m  Patrol radius [SCALE.m].
+ */
+export declare function GuardPosition(x_m: number, y_m: number, radius_m: number): BehaviorNode;
+/**
+ * Move toward a target entity and issue a Treat command when in range.
+ *
+ * - Returns null if target is missing, already dead, or has no injuries.
+ * - Healing uses the first injured region found (deterministic iteration order).
+ *
+ * @param targetId   Id of the entity to heal.
+ */
+export declare function HealTarget(targetId: number): BehaviorNode;
+/**
+ * Priority selector: tries each child node in order and returns the first
+ * non-null command.  If all children return null, returns null.
+ *
+ * This is the most commonly used composite.  Place higher-priority behaviours
+ * earlier in the list.
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export declare function Sequence(...nodes: BehaviorNode[]): BehaviorNode;
+/**
+ * Fallback: identical to `Sequence` — tries children in order, returns first
+ * non-null result.  Provided as a semantic alias for callers who prefer the
+ * standard BT naming convention (Sequence = AND-chain; Fallback = OR-chain).
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export declare function Fallback(...nodes: BehaviorNode[]): BehaviorNode;
+/**
+ * Gate: return `inner.tick()` only if the entity's shock is below `maxShockQ`.
+ * When the entity is in severe shock it cannot act — returns null instead.
+ *
+ * Useful for wrapping aggressive nodes: "attack only if not badly shocked."
+ *
+ * @param maxShockQ  Q threshold; entity.injury.shock must be below this.
+ * @param inner      Wrapped node.
+ */
+export declare function IfNotShocked(maxShockQ: Q, inner: BehaviorNode): BehaviorNode;
+/**
+ * Gate: return `inner.tick()` only when `entity.energy.fatigue` is below
+ * `maxFatigueQ`.  Prevents exhausted entities from taking high-intensity actions.
+ *
+ * @param maxFatigueQ  Q threshold; fatigue must be below this.
+ * @param inner        Wrapped node.
+ */
+export declare function IfNotExhausted(maxFatigueQ: Q, inner: BehaviorNode): BehaviorNode;
+/**
+ * Probabilistic gate: run `inner` only when
+ * `eventSeed(world.seed, world.tick, entity.id, salt) % SCALE.Q < probability_Q`.
+ *
+ * Allows stochastic variation without `Math.random()`.
+ *
+ * @param probability_Q  Q probability [0..SCALE.Q]; q(1.0) = always, q(0) = never.
+ * @param salt           Arbitrary integer to distinguish independent rolls on the
+ *                       same entity+tick (default 0).
+ * @param inner          Wrapped node.
+ */
+export declare function WithProbability(probability_Q: Q, inner: BehaviorNode, salt?: number): BehaviorNode;
+/**
+ * Standard aggressive attacker: attack `targetId` at full intensity.
+ * Falls back to retreat if badly shocked (shock ≥ q(0.70)).
+ *
+ * @param targetId   Primary attack target.
+ * @param retreatX   Fallback retreat x [SCALE.m].
+ * @param retreatY   Fallback retreat y [SCALE.m].
+ */
+export declare function aggressorTree(targetId: number, retreatX: number, retreatY: number): BehaviorNode;
+/**
+ * Standard defender: hold position, heal allies when in range, defend otherwise.
+ *
+ * @param guardX     Guard point x [SCALE.m].
+ * @param guardY     Guard point y [SCALE.m].
+ * @param radius_m   Guard radius [SCALE.m].
+ * @param allyIds    Ally ids to heal (checked in order; first injured ally wins).
+ */
+export declare function defenderTree(guardX: number, guardY: number, radius_m: number, allyIds: number[]): BehaviorNode;
+/**
+ * Medic tree: prioritise healing each ally in the given list (first injured wins),
+ * then retreat to a safe point if badly shocked.
+ *
+ * @param allyIds    Allies to heal in priority order.
+ * @param safeX      Retreat x [SCALE.m].
+ * @param safeY      Retreat y [SCALE.m].
+ */
+export declare function medicTree(allyIds: number[], safeX: number, safeY: number): BehaviorNode;

package/dist/src/sim/ai/behavior-trees.js

@@ -0,0 +1,340 @@
+/**
+ * CE-10 — Pre-built AI Behavior Tree Library
+ *
+ * A thin, composable layer over the existing AI decision system.  Each
+ * `BehaviorNode` receives the ticking entity, the current world state, and
+ * kernel context, and either returns a `Command` (success) or `null` (failure /
+ * not applicable).
+ *
+ * ## Semantics
+ * - `null`  — node failed / condition not met
+ * - Command — node succeeded; caller should use this command
+ *
+ * ## Composite nodes
+ * - `Sequence`  — run children left-to-right; return first **non-null** result
+ *                 (priority / fallback selector pattern)
+ * - `Fallback`  — identical semantics to Sequence for this usage:
+ *                 try children in order, first non-null wins
+ *
+ * Note: The ROADMAP spec uses "first success wins" for both Sequence and
+ * Fallback (i.e. both are priority-selectors).  A traditional BT Sequence
+ * would return the *last* child result; here all composites return the first
+ * non-null command for practical game-AI use.
+ *
+ * ## Determinism constraint
+ * All nodes are deterministic.  Any tie-breaking or random sampling uses
+ * `eventSeed(world.seed, world.tick, entity.id, salt)` — never `Math.random()`.
+ */
+import { CommandKinds, MoveModes, DefenceModes } from "../kinds.js";
+import { q, SCALE } from "../../units.js";
+import { eventSeed } from "../seeds.js";
+// ── Internal geometry helpers ─────────────────────────────────────────────────
+/** Squared distance between two entities (position_m, 2-D x/y). */
+function distSq2D(a, b) {
+    const dx = b.position_m.x - a.position_m.x;
+    const dy = b.position_m.y - a.position_m.y;
+    return dx * dx + dy * dy;
+}
+/** Integer square-root approximation via Newton's method (no float dependency). */
+function isqrt(n) {
+    if (n <= 0)
+        return 0;
+    let x = Math.round(Math.sqrt(n));
+    // One Newton step for accuracy at fixed-point scales
+    x = Math.trunc((x + Math.trunc(n / Math.max(1, x))) / 2);
+    return Math.max(0, x);
+}
+/** Signed direction from `from` to `to`, normalised to unit Q vector. */
+function dirTo(fromX, fromY, toX, toY) {
+    const dx = toX - fromX;
+    const dy = toY - fromY;
+    const len = isqrt(dx * dx + dy * dy);
+    if (len === 0)
+        return { x: 0, y: 0, z: 0 };
+    return {
+        x: Math.round((dx * SCALE.Q) / len),
+        y: Math.round((dy * SCALE.Q) / len),
+        z: 0,
+    };
+}
+/** Find an entity by id in the world, or undefined. */
+function findEntity(world, id) {
+    return world.entities.find(e => e.id === id);
+}
+/** True if entity is dead or unconscious. */
+function isIncapacitated(e) {
+    return (e.injury?.dead ?? false) || (e.injury?.consciousness ?? SCALE.Q) <= 0;
+}
+// ── Leaf nodes ────────────────────────────────────────────────────────────────
+/**
+ * Move toward a target entity and attack when in range.
+ *
+ * If the target is dead or missing, returns null.
+ * Flanks by approaching from the target's perpendicular when `flankOffset > 0`.
+ *
+ * @param targetId     Id of the entity to flank/attack.
+ * @param flankOffset  Lateral offset in SCALE.m units (0 = direct approach).
+ */
+export function FlankTarget(targetId, flankOffset = 0) {
+    return {
+        tick(entity, world) {
+            const target = findEntity(world, targetId);
+            if (!target || isIncapacitated(target))
+                return null;
+            const tx = target.position_m.x + flankOffset;
+            const ty = target.position_m.y;
+            const threshold = 15_000 * 15_000; // ~1.5 m in SCALE.m
+            if (distSq2D(entity, target) <= threshold) {
+                // In melee range — attack
+                return { kind: CommandKinds.Attack, targetId, intensity: q(1.0) };
+            }
+            const dir = dirTo(entity.position_m.x, entity.position_m.y, tx, ty);
+            return { kind: CommandKinds.Move, dir, intensity: q(1.0), mode: MoveModes.Run };
+        },
+    };
+}
+/**
+ * Move to a fixed world position and stop when within `arrivalRadius_m` metres.
+ *
+ * Returns null when already at the destination (no command needed).
+ *
+ * @param x_m           Destination x [SCALE.m].
+ * @param y_m           Destination y [SCALE.m].
+ * @param arrivalRadius_m  Stop radius [SCALE.m]. Default 5 000 (0.5 m).
+ */
+export function RetreatTo(x_m, y_m, arrivalRadius_m = 5_000) {
+    return {
+        tick(entity) {
+            const dx = x_m - entity.position_m.x;
+            const dy = y_m - entity.position_m.y;
+            const r = arrivalRadius_m;
+            if (dx * dx + dy * dy <= r * r)
+                return null; // already there
+            const dir = dirTo(entity.position_m.x, entity.position_m.y, x_m, y_m);
+            return { kind: CommandKinds.Move, dir, intensity: q(1.0), mode: MoveModes.Run };
+        },
+    };
+}
+/**
+ * Move toward an allied entity and interpose between it and the nearest threat.
+ *
+ * - If ally is missing or dead, returns null.
+ * - If no threats (other entities) are present, returns null.
+ * - Otherwise moves toward the ally.
+ *
+ * @param allyId   Id of the entity to protect.
+ */
+export function ProtectAlly(allyId) {
+    return {
+        tick(entity, world) {
+            const ally = findEntity(world, allyId);
+            if (!ally || isIncapacitated(ally))
+                return null;
+            // Require at least one other living entity to protect against
+            const threats = world.entities.filter(e => e.id !== entity.id && e.id !== allyId && !isIncapacitated(e));
+            if (threats.length === 0)
+                return null;
+            const threshold = 20_000 * 20_000; // 2 m
+            if (distSq2D(entity, ally) <= threshold) {
+                // Close enough — defend
+                return { kind: CommandKinds.Defend, mode: DefenceModes.Block, intensity: q(1.0) };
+            }
+            const dir = dirTo(entity.position_m.x, entity.position_m.y, ally.position_m.x, ally.position_m.y);
+            return { kind: CommandKinds.Move, dir, intensity: q(1.0), mode: MoveModes.Run };
+        },
+    };
+}
+/**
+ * Hold a position: move toward the guard point if outside `radius_m`, defend
+ * if inside.  Returns null when the entity is already inside the radius and
+ * there are no threats to defend against.
+ *
+ * @param x_m       Guard point x [SCALE.m].
+ * @param y_m       Guard point y [SCALE.m].
+ * @param radius_m  Patrol radius [SCALE.m].
+ */
+export function GuardPosition(x_m, y_m, radius_m) {
+    return {
+        tick(entity, world) {
+            const dx = x_m - entity.position_m.x;
+            const dy = y_m - entity.position_m.y;
+            const rSq = radius_m * radius_m;
+            const insideRadius = dx * dx + dy * dy <= rSq;
+            if (!insideRadius) {
+                const dir = dirTo(entity.position_m.x, entity.position_m.y, x_m, y_m);
+                return { kind: CommandKinds.Move, dir, intensity: q(1.0), mode: MoveModes.Walk };
+            }
+            // Inside radius — defend if threats present
+            const threats = world.entities.filter(e => e.id !== entity.id && !isIncapacitated(e));
+            if (threats.length === 0)
+                return null;
+            return { kind: CommandKinds.Defend, mode: DefenceModes.Block, intensity: q(0.5) };
+        },
+    };
+}
+/**
+ * Move toward a target entity and issue a Treat command when in range.
+ *
+ * - Returns null if target is missing, already dead, or has no injuries.
+ * - Healing uses the first injured region found (deterministic iteration order).
+ *
+ * @param targetId   Id of the entity to heal.
+ */
+export function HealTarget(targetId) {
+    return {
+        tick(entity, world) {
+            const target = findEntity(world, targetId);
+            if (!target || target.injury?.dead)
+                return null;
+            // Find an injured region with surface or internal damage
+            const byRegion = target.injury?.byRegion;
+            if (!byRegion)
+                return null;
+            let injuredRegionId;
+            for (const [regionId, region] of Object.entries(byRegion)) {
+                if ((region.surfaceDamage ?? 0) > 0 || (region.internalDamage ?? 0) > 0) {
+                    injuredRegionId = regionId;
+                    break;
+                }
+            }
+            if (!injuredRegionId)
+                return null;
+            const threshold = 10_000 * 10_000; // 1 m
+            if (distSq2D(entity, target) > threshold) {
+                const dir = dirTo(entity.position_m.x, entity.position_m.y, target.position_m.x, target.position_m.y);
+                return { kind: CommandKinds.Move, dir, intensity: q(0.5), mode: MoveModes.Walk };
+            }
+            return {
+                kind: CommandKinds.Treat,
+                targetId,
+                action: "bandage",
+                tier: "bandage",
+                regionId: injuredRegionId,
+            };
+        },
+    };
+}
+// ── Composite nodes ───────────────────────────────────────────────────────────
+/**
+ * Priority selector: tries each child node in order and returns the first
+ * non-null command.  If all children return null, returns null.
+ *
+ * This is the most commonly used composite.  Place higher-priority behaviours
+ * earlier in the list.
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export function Sequence(...nodes) {
+    return {
+        tick(entity, world, ctx) {
+            for (const node of nodes) {
+                const result = node.tick(entity, world, ctx);
+                if (result !== null)
+                    return result;
+            }
+            return null;
+        },
+    };
+}
+/**
+ * Fallback: identical to `Sequence` — tries children in order, returns first
+ * non-null result.  Provided as a semantic alias for callers who prefer the
+ * standard BT naming convention (Sequence = AND-chain; Fallback = OR-chain).
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export function Fallback(...nodes) {
+    return Sequence(...nodes);
+}
+// ── Condition-gate nodes ──────────────────────────────────────────────────────
+/**
+ * Gate: return `inner.tick()` only if the entity's shock is below `maxShockQ`.
+ * When the entity is in severe shock it cannot act — returns null instead.
+ *
+ * Useful for wrapping aggressive nodes: "attack only if not badly shocked."
+ *
+ * @param maxShockQ  Q threshold; entity.injury.shock must be below this.
+ * @param inner      Wrapped node.
+ */
+export function IfNotShocked(maxShockQ, inner) {
+    return {
+        tick(entity, world, ctx) {
+            if ((entity.injury?.shock ?? 0) >= maxShockQ)
+                return null;
+            return inner.tick(entity, world, ctx);
+        },
+    };
+}
+/**
+ * Gate: return `inner.tick()` only when `entity.energy.fatigue` is below
+ * `maxFatigueQ`.  Prevents exhausted entities from taking high-intensity actions.
+ *
+ * @param maxFatigueQ  Q threshold; fatigue must be below this.
+ * @param inner        Wrapped node.
+ */
+export function IfNotExhausted(maxFatigueQ, inner) {
+    return {
+        tick(entity, world, ctx) {
+            if ((entity.energy?.fatigue ?? 0) >= maxFatigueQ)
+                return null;
+            return inner.tick(entity, world, ctx);
+        },
+    };
+}
+/**
+ * Probabilistic gate: run `inner` only when
+ * `eventSeed(world.seed, world.tick, entity.id, salt) % SCALE.Q < probability_Q`.
+ *
+ * Allows stochastic variation without `Math.random()`.
+ *
+ * @param probability_Q  Q probability [0..SCALE.Q]; q(1.0) = always, q(0) = never.
+ * @param salt           Arbitrary integer to distinguish independent rolls on the
+ *                       same entity+tick (default 0).
+ * @param inner          Wrapped node.
+ */
+export function WithProbability(probability_Q, inner, salt = 0) {
+    return {
+        tick(entity, world, ctx) {
+            const roll = eventSeed(world.seed, world.tick, entity.id, 0, salt) % SCALE.Q;
+            if (roll >= probability_Q)
+                return null;
+            return inner.tick(entity, world, ctx);
+        },
+    };
+}
+// ── Pre-built behavior tree presets ──────────────────────────────────────────
+/**
+ * Standard aggressive attacker: attack `targetId` at full intensity.
+ * Falls back to retreat if badly shocked (shock ≥ q(0.70)).
+ *
+ * @param targetId   Primary attack target.
+ * @param retreatX   Fallback retreat x [SCALE.m].
+ * @param retreatY   Fallback retreat y [SCALE.m].
+ */
+export function aggressorTree(targetId, retreatX, retreatY) {
+    return Sequence(IfNotShocked(q(0.70), FlankTarget(targetId)), RetreatTo(retreatX, retreatY));
+}
+/**
+ * Standard defender: hold position, heal allies when in range, defend otherwise.
+ *
+ * @param guardX     Guard point x [SCALE.m].
+ * @param guardY     Guard point y [SCALE.m].
+ * @param radius_m   Guard radius [SCALE.m].
+ * @param allyIds    Ally ids to heal (checked in order; first injured ally wins).
+ */
+export function defenderTree(guardX, guardY, radius_m, allyIds) {
+    const healNodes = allyIds.map(id => HealTarget(id));
+    return Sequence(...healNodes, GuardPosition(guardX, guardY, radius_m));
+}
+/**
+ * Medic tree: prioritise healing each ally in the given list (first injured wins),
+ * then retreat to a safe point if badly shocked.
+ *
+ * @param allyIds    Allies to heal in priority order.
+ * @param safeX      Retreat x [SCALE.m].
+ * @param safeY      Retreat y [SCALE.m].
+ */
+export function medicTree(allyIds, safeX, safeY) {
+    const healNodes = allyIds.map(id => HealTarget(id));
+    return Sequence(IfNotShocked(q(0.80), Sequence(...healNodes)), RetreatTo(safeX, safeY));
+}

package/dist/src/snapshot.d.ts

@@ -0,0 +1,117 @@
+/**
+ * CE-9 — World-State Diffing + Incremental Snapshots
+ *
+ * Reduces long-run storage from O(ticks × fullState) to O(initialState + Σ deltas).
+ *
+ * ## Diff model
+ * `WorldStateDiff` captures:
+ * - World-level scalar changes (`tick`, `seed`, optional subsystem fields).
+ * - Entity-level changes at **top-level-field granularity**: each field that
+ *   differs from the previous snapshot is stored in full; unchanged fields are
+ *   omitted.  This avoids deep-diffing complex nested types.
+ * - Newly added entities (stored in full).
+ * - Removed entity ids.
+ *
+ * ## Binary wire format (`packDiff` / `unpackDiff`)
+ * A compact, dependency-free binary encoding using a simple tag-value scheme.
+ * Zero external dependencies — implemented entirely with `DataView` / `Uint8Array`.
+ *
+ * Layout:
+ *   [4 bytes magic "ANKD"] [1 byte version=1] [tag-value payload...]
+ *
+ * Tag bytes:
+ *   0x01 null | 0x02 true | 0x03 false
+ *   0x04 uint8  (1 byte) | 0x05 int32 LE (4 bytes) | 0x06 float64 LE (8 bytes)
+ *   0x07 string (uint16 LE length + UTF-8 bytes)
+ *   0x08 array  (uint32 LE count + items)
+ *   0x09 object (uint32 LE count + key-value pairs, keys as 0x07 strings)
+ *   0x0A undefined/absent (skipped in round-trip)
+ */
+import type { WorldState } from "./sim/world.js";
+import type { Entity } from "./sim/entity.js";
+/** A patch for a single entity — only changed top-level fields are included. */
+export interface EntityPatch {
+    /** Entity id. */
+    id: number;
+    /** Changed top-level fields (field name → new value). */
+    changes: Record<string, unknown>;
+}
+/**
+ * Delta between two consecutive `WorldState` snapshots.
+ *
+ * Applying a `WorldStateDiff` to the `prev` snapshot must yield a state
+ * indistinguishable (JSON-round-trip-equal) from `next`.
+ */
+export interface WorldStateDiff {
+    /** `next.tick` — always present for sequencing. */
+    tick: number;
+    /** Changed world-level scalar/subsystem fields (excluding `entities`). */
+    worldChanges: Record<string, unknown>;
+    /** Entities present in `next` but not in `prev` — stored in full. */
+    added: Entity[];
+    /** Entity ids present in `prev` but not in `next`. */
+    removed: number[];
+    /** Top-level-field patches for entities present in both states. */
+    modified: EntityPatch[];
+}
+/**
+ * Compute the diff between two `WorldState` snapshots.
+ *
+ * The diff is guaranteed to be **idempotent**: `applyDiff(prev, diffWorldState(prev, next))`
+ * produces a state that is JSON-round-trip-equal to `next`.
+ *
+ * Complexity: O(E × F) where E = entity count and F = top-level field count per entity.
+ *
+ * @param prev  Base snapshot.
+ * @param next  New snapshot (must have the same `seed`; `tick` may differ).
+ * @returns     `WorldStateDiff` — empty diff if states are identical.
+ */
+export declare function diffWorldState(prev: WorldState, next: WorldState): WorldStateDiff;
+/**
+ * Apply a `WorldStateDiff` to a base `WorldState`, producing the `next` state.
+ *
+ * **Does not mutate `base`** — returns a new `WorldState` object.
+ * The returned state may share sub-object references with `base` for unchanged
+ * entities (copy-on-write semantics).
+ *
+ * @param base   The `prev` snapshot that was passed to `diffWorldState`.
+ * @param diff   The diff produced by `diffWorldState`.
+ * @returns      Reconstructed `next` state.
+ */
+export declare function applyDiff(base: WorldState, diff: WorldStateDiff): WorldState;
+/**
+ * Returns `true` when the diff contains no changes — states were identical.
+ */
+export declare function isDiffEmpty(diff: WorldStateDiff): boolean;
+/**
+ * Summary statistics for a diff (useful for logging / network budget monitoring).
+ */
+export interface DiffStats {
+    /** Number of world-level changed fields. */
+    worldChangedFields: number;
+    addedEntities: number;
+    removedEntities: number;
+    modifiedEntities: number;
+    /** Total changed fields across all modified entities. */
+    totalEntityChanges: number;
+}
+export declare function diffStats(diff: WorldStateDiff): DiffStats;
+/**
+ * Encode a `WorldStateDiff` as a compact binary `Uint8Array`.
+ *
+ * The binary format is self-describing (no schema required for decoding).
+ * `unpackDiff(packDiff(diff))` is guaranteed to produce a diff that when
+ * applied gives the same result as the original.
+ *
+ * @param diff  Diff to encode.
+ * @returns     Binary representation.
+ */
+export declare function packDiff(diff: WorldStateDiff): Uint8Array;
+/**
+ * Decode a `WorldStateDiff` previously encoded by `packDiff`.
+ *
+ * @param bytes  Binary data produced by `packDiff`.
+ * @returns      Decoded `WorldStateDiff`.
+ * @throws       If the magic bytes or version do not match.
+ */
+export declare function unpackDiff(bytes: Uint8Array): WorldStateDiff;

package/dist/src/snapshot.js

@@ -0,0 +1,379 @@
+/**
+ * CE-9 — World-State Diffing + Incremental Snapshots
+ *
+ * Reduces long-run storage from O(ticks × fullState) to O(initialState + Σ deltas).
+ *
+ * ## Diff model
+ * `WorldStateDiff` captures:
+ * - World-level scalar changes (`tick`, `seed`, optional subsystem fields).
+ * - Entity-level changes at **top-level-field granularity**: each field that
+ *   differs from the previous snapshot is stored in full; unchanged fields are
+ *   omitted.  This avoids deep-diffing complex nested types.
+ * - Newly added entities (stored in full).
+ * - Removed entity ids.
+ *
+ * ## Binary wire format (`packDiff` / `unpackDiff`)
+ * A compact, dependency-free binary encoding using a simple tag-value scheme.
+ * Zero external dependencies — implemented entirely with `DataView` / `Uint8Array`.
+ *
+ * Layout:
+ *   [4 bytes magic "ANKD"] [1 byte version=1] [tag-value payload...]
+ *
+ * Tag bytes:
+ *   0x01 null | 0x02 true | 0x03 false
+ *   0x04 uint8  (1 byte) | 0x05 int32 LE (4 bytes) | 0x06 float64 LE (8 bytes)
+ *   0x07 string (uint16 LE length + UTF-8 bytes)
+ *   0x08 array  (uint32 LE count + items)
+ *   0x09 object (uint32 LE count + key-value pairs, keys as 0x07 strings)
+ *   0x0A undefined/absent (skipped in round-trip)
+ */
+// ── Diff ──────────────────────────────────────────────────────────────────────
+/**
+ * Compute the diff between two `WorldState` snapshots.
+ *
+ * The diff is guaranteed to be **idempotent**: `applyDiff(prev, diffWorldState(prev, next))`
+ * produces a state that is JSON-round-trip-equal to `next`.
+ *
+ * Complexity: O(E × F) where E = entity count and F = top-level field count per entity.
+ *
+ * @param prev  Base snapshot.
+ * @param next  New snapshot (must have the same `seed`; `tick` may differ).
+ * @returns     `WorldStateDiff` — empty diff if states are identical.
+ */
+export function diffWorldState(prev, next) {
+    // ── World-level scalar/subsystem changes ──────────────────────────────────
+    const worldChanges = {};
+    const worldKeys = [
+        "tick", "seed",
+        "activeFieldEffects",
+        "__sensoryEnv",
+        "__factionRegistry",
+        "__partyRegistry",
+        "__relationshipGraph",
+        "__nutritionAccum",
+    ];
+    for (const key of worldKeys) {
+        if (key === "entities")
+            continue;
+        const pv = prev[key];
+        const nv = next[key];
+        if (!jsonEqual(pv, nv)) {
+            worldChanges[key] = nv;
+        }
+    }
+    // ── Entity diff ───────────────────────────────────────────────────────────
+    const prevMap = new Map(prev.entities.map(e => [e.id, e]));
+    const nextMap = new Map(next.entities.map(e => [e.id, e]));
+    const added = [];
+    const removed = [];
+    const modified = [];
+    // Removed or modified
+    for (const [id, pe] of prevMap) {
+        const ne = nextMap.get(id);
+        if (!ne) {
+            removed.push(id);
+        }
+        else {
+            const changes = entityChanges(pe, ne);
+            if (Object.keys(changes).length > 0) {
+                modified.push({ id, changes });
+            }
+        }
+    }
+    // Added
+    for (const [id, ne] of nextMap) {
+        if (!prevMap.has(id)) {
+            added.push(ne);
+        }
+    }
+    return { tick: next.tick, worldChanges, added, removed, modified };
+}
+/**
+ * Apply a `WorldStateDiff` to a base `WorldState`, producing the `next` state.
+ *
+ * **Does not mutate `base`** — returns a new `WorldState` object.
+ * The returned state may share sub-object references with `base` for unchanged
+ * entities (copy-on-write semantics).
+ *
+ * @param base   The `prev` snapshot that was passed to `diffWorldState`.
+ * @param diff   The diff produced by `diffWorldState`.
+ * @returns      Reconstructed `next` state.
+ */
+export function applyDiff(base, diff) {
+    // Reconstruct world-level fields
+    const next = {
+        ...base,
+        ...diff.worldChanges,
+        tick: diff.tick,
+    };
+    // Remove entities
+    const removedSet = new Set(diff.removed);
+    let entities = base.entities.filter(e => !removedSet.has(e.id));
+    // Modify entities (patch changed fields)
+    entities = entities.map(e => {
+        const patch = diff.modified.find(p => p.id === e.id);
+        if (!patch)
+            return e;
+        return { ...e, ...patch.changes };
+    });
+    // Add new entities
+    entities = [...entities, ...diff.added];
+    // Restore canonical sort order (ascending id)
+    entities.sort((a, b) => a.id - b.id);
+    return { ...next, entities };
+}
+// ── isEmpty / stats ───────────────────────────────────────────────────────────
+/**
+ * Returns `true` when the diff contains no changes — states were identical.
+ */
+export function isDiffEmpty(diff) {
+    return (Object.keys(diff.worldChanges).length === 0 &&
+        diff.added.length === 0 &&
+        diff.removed.length === 0 &&
+        diff.modified.length === 0);
+}
+export function diffStats(diff) {
+    return {
+        worldChangedFields: Object.keys(diff.worldChanges).length,
+        addedEntities: diff.added.length,
+        removedEntities: diff.removed.length,
+        modifiedEntities: diff.modified.length,
+        totalEntityChanges: diff.modified.reduce((s, p) => s + Object.keys(p.changes).length, 0),
+    };
+}
+// ── Binary pack / unpack ──────────────────────────────────────────────────────
+const MAGIC = 0x414E4B44; // "ANKD"
+const VERSION = 1;
+const TAG = {
+    NULL: 0x01,
+    TRUE: 0x02,
+    FALSE: 0x03,
+    UINT8: 0x04,
+    INT32: 0x05,
+    FLOAT64: 0x06,
+    STRING: 0x07,
+    ARRAY: 0x08,
+    OBJECT: 0x09,
+};
+/**
+ * Encode a `WorldStateDiff` as a compact binary `Uint8Array`.
+ *
+ * The binary format is self-describing (no schema required for decoding).
+ * `unpackDiff(packDiff(diff))` is guaranteed to produce a diff that when
+ * applied gives the same result as the original.
+ *
+ * @param diff  Diff to encode.
+ * @returns     Binary representation.
+ */
+export function packDiff(diff) {
+    const buf = new Writer();
+    buf.writeUint32(MAGIC);
+    buf.writeUint8(VERSION);
+    buf.writeValue(diff);
+    return buf.toUint8Array();
+}
+/**
+ * Decode a `WorldStateDiff` previously encoded by `packDiff`.
+ *
+ * @param bytes  Binary data produced by `packDiff`.
+ * @returns      Decoded `WorldStateDiff`.
+ * @throws       If the magic bytes or version do not match.
+ */
+export function unpackDiff(bytes) {
+    const r = new Reader(bytes);
+    const magic = r.readUint32();
+    if (magic !== MAGIC)
+        throw new Error(`snapshot: invalid magic 0x${magic.toString(16)}`);
+    const version = r.readUint8();
+    if (version !== VERSION)
+        throw new Error(`snapshot: unsupported version ${version}`);
+    return r.readValue();
+}
+// ── Internal: JSON equality ───────────────────────────────────────────────────
+function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== "object" || typeof b !== "object")
+        return false;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Compute changed top-level fields between two entity versions. */
+function entityChanges(prev, next) {
+    const changes = {};
+    const allKeys = new Set([...Object.keys(prev), ...Object.keys(next)]);
+    for (const key of allKeys) {
+        if (!jsonEqual(prev[key], next[key])) {
+            changes[key] = next[key];
+        }
+    }
+    return changes;
+}
+class Writer {
+    chunks = [];
+    size = 0;
+    writeUint8(v) {
+        const b = new Uint8Array(1);
+        b[0] = v & 0xFF;
+        this.push(b);
+    }
+    writeUint16(v) {
+        const b = new Uint8Array(2);
+        new DataView(b.buffer).setUint16(0, v, true);
+        this.push(b);
+    }
+    writeUint32(v) {
+        const b = new Uint8Array(4);
+        new DataView(b.buffer).setUint32(0, v >>> 0, true);
+        this.push(b);
+    }
+    writeInt32(v) {
+        const b = new Uint8Array(4);
+        new DataView(b.buffer).setInt32(0, v, true);
+        this.push(b);
+    }
+    writeFloat64(v) {
+        const b = new Uint8Array(8);
+        new DataView(b.buffer).setFloat64(0, v, true);
+        this.push(b);
+    }
+    writeString(s) {
+        const enc = new TextEncoder().encode(s);
+        this.writeUint8(TAG.STRING);
+        this.writeUint16(enc.length);
+        this.push(enc);
+    }
+    writeValue(v) {
+        if (v === null || v === undefined) {
+            this.writeUint8(TAG.NULL);
+        }
+        else if (typeof v === "boolean") {
+            this.writeUint8(v ? TAG.TRUE : TAG.FALSE);
+        }
+        else if (typeof v === "number") {
+            if (Number.isInteger(v) && v >= 0 && v <= 255) {
+                this.writeUint8(TAG.UINT8);
+                this.writeUint8(v);
+            }
+            else if (Number.isInteger(v) && v >= -2147483648 && v <= 2147483647) {
+                this.writeUint8(TAG.INT32);
+                this.writeInt32(v);
+            }
+            else {
+                this.writeUint8(TAG.FLOAT64);
+                this.writeFloat64(v);
+            }
+        }
+        else if (typeof v === "string") {
+            this.writeString(v);
+        }
+        else if (Array.isArray(v)) {
+            this.writeUint8(TAG.ARRAY);
+            this.writeUint32(v.length);
+            for (const item of v)
+                this.writeValue(item);
+        }
+        else {
+            const entries = Object.entries(v).filter(([, val]) => val !== undefined);
+            this.writeUint8(TAG.OBJECT);
+            this.writeUint32(entries.length);
+            for (const [key, val] of entries) {
+                this.writeString(key);
+                this.writeValue(val);
+            }
+        }
+    }
+    push(b) {
+        this.chunks.push(b);
+        this.size += b.length;
+    }
+    toUint8Array() {
+        const out = new Uint8Array(this.size);
+        let off = 0;
+        for (const c of this.chunks) {
+            out.set(c, off);
+            off += c.length;
+        }
+        return out;
+    }
+}
+// ── Binary Reader ─────────────────────────────────────────────────────────────
+class Reader {
+    view;
+    pos = 0;
+    constructor(bytes) {
+        this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    }
+    readUint8() {
+        return this.view.getUint8(this.pos++);
+    }
+    readUint16() {
+        const v = this.view.getUint16(this.pos, true);
+        this.pos += 2;
+        return v;
+    }
+    readUint32() {
+        const v = this.view.getUint32(this.pos, true);
+        this.pos += 4;
+        return v;
+    }
+    readInt32() {
+        const v = this.view.getInt32(this.pos, true);
+        this.pos += 4;
+        return v;
+    }
+    readFloat64() {
+        const v = this.view.getFloat64(this.pos, true);
+        this.pos += 8;
+        return v;
+    }
+    readString() {
+        const len = this.readUint16();
+        const bytes = new Uint8Array(this.view.buffer, this.view.byteOffset + this.pos, len);
+        this.pos += len;
+        return new TextDecoder().decode(bytes);
+    }
+    readValue() {
+        const tag = this.readUint8();
+        switch (tag) {
+            case TAG.NULL: return null;
+            case TAG.TRUE: return true;
+            case TAG.FALSE: return false;
+            case TAG.UINT8: return this.readUint8();
+            case TAG.INT32: return this.readInt32();
+            case TAG.FLOAT64: return this.readFloat64();
+            case TAG.STRING: {
+                const len = this.readUint16();
+                const bytes = new Uint8Array(this.view.buffer, this.view.byteOffset + this.pos, len);
+                this.pos += len;
+                return new TextDecoder().decode(bytes);
+            }
+            case TAG.ARRAY: {
+                const count = this.readUint32();
+                const arr = [];
+                for (let i = 0; i < count; i++)
+                    arr.push(this.readValue());
+                return arr;
+            }
+            case TAG.OBJECT: {
+                const count = this.readUint32();
+                const obj = {};
+                for (let i = 0; i < count; i++) {
+                    // key is always a STRING tag
+                    const keyTag = this.readUint8();
+                    if (keyTag !== TAG.STRING)
+                        throw new Error(`snapshot: expected string key tag, got 0x${keyTag.toString(16)}`);
+                    const keyLen = this.readUint16();
+                    const keyBytes = new Uint8Array(this.view.buffer, this.view.byteOffset + this.pos, keyLen);
+                    this.pos += keyLen;
+                    const key = new TextDecoder().decode(keyBytes);
+                    obj[key] = this.readValue();
+                }
+                return obj;
+            }
+            default:
+                throw new Error(`snapshot: unknown tag 0x${tag.toString(16)}`);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",