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

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.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",