@ecsia/rollback 0.25.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Aragon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @ecsia/rollback
+
+Checkpointing for [**ecsia**](https://github.com/andymai/ecsia), an entity component
+system (ECS) for TypeScript — entities are ids, components are typed data attached to
+them, and systems are functions that run over entities with matching components.
+
+`@ecsia/rollback` captures a whole world into a reusable image and restores it **in
+place**, so a rollback-netcode or prediction loop can rewind to a checkpoint and
+re-simulate. A restore is **handle-stable**: every entity keeps the exact handle it had
+at capture, every entity reference stored in a component still resolves, and queries
+stay valid — no remap table, unlike a network snapshot from
+[`@ecsia/serialization`](https://www.npmjs.com/package/@ecsia/serialization), which
+re-mints entities on the receiver.
+
+On top of that it ships the loop itself: `createRollbackSession` predicts the inputs
+that have not arrived, checkpoints every frame into a bounded ring, and — when a
+confirmed input contradicts a prediction — rewinds and re-simulates automatically.
+
+Images are reusable: after the live set stops growing, capturing into an existing image
+allocates nothing, so a ring of images costs no per-frame garbage.
+
+> **Status:** 0.x. v1 refuses (loudly) to capture a world that uses relations, has
+> entities in cold archetypes, or registers a rich (`'string'` / `object<T>`) field —
+> that state is not in the image, and failing fast beats restoring a partial world.
+
+## Install
+
+```sh
+pnpm add @ecsia/rollback @ecsia/core
+```
+
+```ts
+import { createWorld } from '@ecsia/core'
+import { createRollbackSurface } from '@ecsia/rollback'
+
+const world = createWorld({ components: [] })
+const rollback = createRollbackSurface(world)
+const checkpoint = rollback.newImage()
+
+rollback.captureImage(checkpoint) // between frames, world.phase === 'serial'
+// ...simulate, mispredict...
+rollback.restoreImage(checkpoint) // every handle is back, in place
+```
+
+## The rollback loop
+
+`createRollbackSession` owns the predict → confirm → rollback → re-simulate cycle. It
+takes no dependency on a scheduler (you hand it one fixed step) and knows nothing about
+your input format (opaque bytes it buffers and byte-compares); `applyInputs` is where you
+write them into whatever components your systems read.
+
+```ts
+import { createWorld, defineComponent } from '@ecsia/core'
+import { createRollbackSession } from '@ecsia/rollback'
+
+const Intent = defineComponent({ move: 'i32', fire: 'i32' }, { name: 'intent' })
+const world = createWorld({ components: [Intent] })
+const avatars = new Map<number, ReturnType<typeof world.spawnWith>>([
+  [0, world.spawnWith(Intent)],
+  [1, world.spawnWith(Intent)],
+])
+
+const session = createRollbackSession(world, {
+  maxRollbackFrames: 8, // ≈133 ms at 60Hz — the deepest correction the ring can absorb
+  players: [0, 1],
+  step: () => runOneFixedStep(), // e.g. () => scheduler.update(1 / 60)
+  applyInputs: (_frame, inputs) => {
+    for (const player of inputs.players) {
+      const bytes = inputs.get(player)
+      const intent = world.entity(avatars.get(player as number)!).write(Intent)
+      intent.move = bytes[0] ?? 0
+      intent.fire = bytes[1] ?? 0
+    }
+  },
+})
+
+// Per frame: feed the local input, advance. Remote inputs are predicted until they land.
+for (let i = 0; i < 2; i++) {
+  session.recordInput(0, session.currentFrame + 1, new Uint8Array([1, 0]))
+  session.advance()
+}
+
+// A remote input for a PAST frame that contradicts its prediction rewinds and re-simulates
+// inside this call; one that matches costs nothing but an advancing confirmedFrame. Only a frame
+// this session actually simulated is accepted — the first is the tick it was created at, plus one.
+session.recordInput(1, session.currentFrame - 1, new Uint8Array([0, 1]))
+
+declare function runOneFixedStep(): void
+```
+
+`step()` must advance `world.tick` exactly once and must end at a frame boundary (its
+observer drain done) — the session checkpoints immediately after it returns, and an image
+rewinds state, not the event stream. Both are asserted, not assumed.
+
+A correction for a frame further back than `maxRollbackFrames` is **unrecoverable**: the
+session leaves the world untouched (never a partial rewind) and reports it through
+`onUnrecoverable`, or throws when you did not supply one. Resync from a fresh
+authoritative state at that point.
+
+## Links
+
+- Repository & full docs: https://github.com/andymai/ecsia
+- Umbrella package: [`@ecsia/kit`](https://github.com/andymai/ecsia)
+
+## License
+
+[MIT](./LICENSE) © Andy Aragon

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createRollbackSurface } from './rollback.js';
+export type { RollbackSurface, RollbackImage } from './rollback.js';
+export { createRollbackSession } from './session.js';
+export type { Frame, FrameInputs, InputImage, PlayerId, PredictionPolicy, RollbackOptions, RollbackSession, UnrecoverableRollback, } from './session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACpD,YAAY,EACV,KAAK,EACL,WAAW,EACX,UAAU,EACV,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,qBAAqB,GACtB,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// @ecsia/rollback — handle-stable whole-world capture/restore: the checkpoint substrate a rollback
+// netcode / prediction loop re-simulates from. An OPT-IN package that attaches to @ecsia/core
+// through the `__installRollback` seam; core never imports it, so a world that never rolls back
+// bundles none of this.
+//
+// The opposite of @ecsia/serialization: a snapshot re-mints entities on the receiver and hands back
+// a remap table, while a restore rewrites the live world IN PLACE — every entity keeps its ORIGINAL
+// handle, every stored `eid` still resolves, and query iteration stays valid without a remap.
+export { createRollbackSurface } from './rollback.js';
+export { createRollbackSession } from './session.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,8FAA8F;AAC9F,gGAAgG;AAChG,wBAAwB;AACxB,EAAE;AACF,oGAAoG;AACpG,oGAAoG;AACpG,8FAA8F;AAE9F,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAErD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA"}

package/dist/rollback.d.ts

@@ -0,0 +1,66 @@
+import type { World } from '@ecsia/core';
+/**
+ * Opaque, reusable capture buffer. Allocate one per rollback-ring slot and reuse it: a capture only
+ * allocates when the live set outgrows the image's buffers (doubling), so a steady-state ring
+ * allocates nothing per frame. An image holds the world's Column references and is NOT portable to
+ * another world.
+ */
+declare const rollbackImageBrand: unique symbol;
+export interface RollbackImage {
+    readonly [rollbackImageBrand]: true;
+}
+/**
+ * The capture/restore handle for one world.
+ *
+ * WHAT AN IMAGE COVERS
+ *   • per-archetype SoA columns + the dense row→handle list over `[0, count + held)`, plus both
+ *     occupancy words. The HELD range (deferred-dead rows an onRemove observer has yet to read) is
+ *     part of the image: `world.phase === 'serial'` is equally true before the observer drain, so a
+ *     capture can legitimately see `held > 0` — restoring the occupancy without those rows' bytes
+ *     would fire removal observers with whatever the live world wrote there since.
+ *   • the five entity identity/record regions + the four allocator cursors (handle stability)
+ *   • the component bitmask: the u32 words AND the out-of-stride sparse overflow
+ *   • the changeVersion stamps, when stamping is enabled
+ *   • world.tick
+ *
+ * WHAT IT DELIBERATELY OMITS: the frame-transient reactivity structures — the write/shape log rings,
+ * the Changed lists, the per-frame added/removed query flavors and the topic rings. A rollback ring
+ * checkpoints between frames, where those are empty; not capturing them is what keeps the image small.
+ *
+ * CONSEQUENCE — the EVENT STREAM is not rewound, only the STATE. Capturing mid-frame (serial phase is
+ * equally true before the observer drain) leaves those rings outside the image, so a despawn journaled
+ * after the capture still drains after a restore: the observer fires for an entity the restore brought
+ * back. Held rows ARE captured, so such an event reports its at-capture values rather than a live
+ * entity's — the values are sound, the event count/identity is not. Checkpoint at a frame boundary
+ * (after the drain) if a client must not observe revoked events.
+ */
+export interface RollbackSurface {
+    /** A fresh, empty image (its buffers grow on first capture). */
+    newImage(): RollbackImage;
+    /**
+     * Capture the ENTIRE live world into `img`, overwriting whatever it held. Serial-phase only.
+     *
+     * THROWS on the v1 limitations, deliberately fail-fast rather than silently restoring a partial
+     * world: a world with a relation defined (relation state lives in JS maps behind a MONOTONIC
+     * synthetic pair-id counter, so re-simulating mints different pair ids and different archetype
+     * signatures), entities resident in the cold-archetype overflow store (per-TYPE blocks, outside
+     * the per-archetype hot walk), or a registered rich (`'string'` / `object<T>`) field (sidecar
+     * values the image cannot reach).
+     */
+    captureImage(img: RollbackImage): void;
+    /**
+     * Restore `img` over the live world IN PLACE and HANDLE-STABLY. Every entity alive at capture is
+     * alive again at its ORIGINAL handle; entities spawned after the capture are gone; archetypes
+     * created after the capture are emptied. Serial-phase only; same guards as `captureImage`.
+     */
+    restoreImage(img: RollbackImage): void;
+    /** RESTORE-ONLY tick assignment (`world.tick` is otherwise increment-only). */
+    setTick(tick: number): void;
+}
+/**
+ * Attach the rollback surface to `world`. Call once per world and keep the returned handle; each
+ * call re-installs the seam and mints a fresh image-ownership identity.
+ */
+export declare function createRollbackSurface(world: World): RollbackSurface;
+export {};
+//# sourceMappingURL=rollback.d.ts.map

package/dist/rollback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.d.ts","sourceRoot":"","sources":["../src/rollback.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAoE,KAAK,EAAE,MAAM,aAAa,CAAA;AAE1G;;;;;GAKG;AACH,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAA;AAC/C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAA;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,QAAQ,IAAI,aAAa,CAAA;IACzB;;;;;;;;;OASG;IACH,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAAA;IACtC;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAAA;IACtC,+EAA+E;IAC/E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AA2ED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,eAAe,CAuKnE"}

package/dist/rollback.js

@@ -0,0 +1,205 @@
+// The capture/restore mechanism: read the whole live world into a reusable image and write it back
+// IN PLACE, handle-stably. Drives `world.__installRollback()`; @ecsia/core never imports this.
+//
+// Growth discipline mirrors core's buffer layer: image buffers double, are reused across captures,
+// and NEVER alias a live column view (a fallback grow re-creates those).
+import { snapshotInto } from '@ecsia/core';
+class Image {
+    /** The surface that minted this image — an image is not portable between worlds. */
+    owner = null;
+    seq = 0;
+    tick = 0;
+    identity = {
+        sparse: new Uint32Array(0),
+        dense: new Uint32Array(0),
+        generation: new Uint32Array(0),
+        recordArchetypeId: new Uint32Array(0),
+        recordArchetypeRow: new Uint32Array(0),
+        aliveCount: 0,
+        denseLen: 0,
+        spawned: 0,
+        despawned: 0,
+    };
+    bitmaskWords = new Uint32Array(0);
+    bitmaskWordCount = 0;
+    bitmaskIndexCount = 0;
+    bitmaskSparse = new Map();
+    changeVersion = new Uint32Array(0);
+    changeVersionCount = 0;
+    archetypes = new Map();
+}
+/**
+ * `arr` when it already holds `length` elements, else a fresh doubled one. Contents are NOT
+ * preserved — a capture rewrites the whole prefix it later reads back.
+ */
+function ensureU32(arr, length) {
+    if (arr.length >= length)
+        return arr;
+    let cap = arr.length > 0 ? arr.length : 1;
+    while (cap < length)
+        cap *= 2;
+    return new Uint32Array(cap);
+}
+function scratchFor(col, elements) {
+    const Ctor = col.view.constructor;
+    let cap = 1;
+    while (cap < elements)
+        cap *= 2;
+    return new Ctor(cap);
+}
+function writeBack(col, data, length) {
+    const src = data.subarray(0, length);
+    col.view.set(src, 0);
+}
+function sizeIdentity(img, n) {
+    img.sparse = ensureU32(img.sparse, n);
+    img.dense = ensureU32(img.dense, n);
+    img.generation = ensureU32(img.generation, n);
+    img.recordArchetypeId = ensureU32(img.recordArchetypeId, n);
+    img.recordArchetypeRow = ensureU32(img.recordArchetypeRow, n);
+}
+/**
+ * Attach the rollback surface to `world`. Call once per world and keep the returned handle; each
+ * call re-installs the seam and mints a fresh image-ownership identity.
+ */
+export function createRollbackSurface(world) {
+    const host = world.__installRollback();
+    const owner = {};
+    const assertSerial = (verb) => {
+        if (world.phase !== 'serial') {
+            throw new Error(`rollback ${verb}() must run while the world is in its serial phase (between frames, outside scheduler.update / worker waves)`);
+        }
+    };
+    const assertOwned = (verb, img) => {
+        if (img.owner !== owner) {
+            throw new Error(`rollback ${verb}(): this image belongs to a different rollback surface — an image holds that world's column references, so it is not portable`);
+        }
+    };
+    const unsupported = (verb, what, remedy) => new Error(`rollback ${verb}(): ${what} — rollback would silently restore a partial world. ${remedy}`);
+    const coldResidents = () => {
+        let n = 0;
+        for (const arch of host.archetypes.byId)
+            if (arch.cold)
+                n += arch.count;
+        return n;
+    };
+    const assertCoverable = (verb) => {
+        const relations = world.__serialize.relations();
+        if (relations !== undefined && relations.relations().length > 0) {
+            throw unsupported(verb, 'relation state (JS maps behind a MONOTONIC synthetic pair-id counter) is not in the image, so re-simulating mints different pair ids and different archetype signatures', 'Relation-aware rollback is a follow-up; checkpoint relation-free worlds until then.');
+        }
+        const cold = coldResidents();
+        if (cold > 0) {
+            throw unsupported(verb, `${cold} entities live in the cold-archetype overflow store, outside the per-archetype hot walk the image captures`, 'Raise maxHotArchetypes so every archetype stays hot, or world.warm() the cold signatures before checkpointing.');
+        }
+        if (world.__serialize.richFields().length > 0) {
+            throw unsupported(verb, "rich ('string' / object<T>) field values live in the main-thread sidecar, which the image cannot reach", 'Rich-field rollback is a follow-up; checkpoint worlds with numeric-only components until then.');
+        }
+    };
+    const cellFor = (img, arch) => {
+        let cell = img.archetypes.get(arch.id);
+        if (cell === undefined) {
+            cell = { seq: 0, count: 0, held: 0, rows: new Uint32Array(0), cells: [] };
+            img.archetypes.set(arch.id, cell);
+        }
+        return cell;
+    };
+    const captureArchetype = (img, arch) => {
+        const entry = cellFor(img, arch);
+        entry.seq = img.seq;
+        entry.count = arch.count;
+        entry.held = arch.held;
+        // The held (deferred-dead) rows sit directly above the live region and are part of the image:
+        // their column bytes are what onRemove handlers read when the drain finally releases them.
+        const rowCount = arch.count + arch.held;
+        entry.rows = ensureU32(entry.rows, rowCount);
+        entry.rows.set(arch.rows.subarray(0, rowCount), 0);
+        let i = 0;
+        for (const set of arch.columnSets.values()) {
+            for (const col of set.columns) {
+                const elements = rowCount * col.layout.stride;
+                let cell = entry.cells[i];
+                // Re-resolve per capture: a cold→hot warm promotion attaches columns to an archetype that
+                // had none, so the cell list is not fixed for an archetype id.
+                if (cell === undefined || cell.col !== col) {
+                    cell = { col, data: scratchFor(col, elements), length: 0 };
+                    entry.cells[i] = cell;
+                }
+                else if (cell.data.length < elements) {
+                    cell.data = scratchFor(col, elements);
+                }
+                cell.length = snapshotInto(col, rowCount, cell.data, 0);
+                i += 1;
+            }
+        }
+        entry.cells.length = i;
+    };
+    const restoreArchetype = (img, arch) => {
+        const entry = img.archetypes.get(arch.id);
+        if (entry === undefined || entry.seq !== img.seq) {
+            // Not in the image: an archetype the re-sim created (or filled) after the checkpoint. Leaving
+            // it populated is silent cross-frame corruption — its rows reference entities that, post
+            // restore, live elsewhere or are dead.
+            host.archetypes.rollbackSetOccupancy(arch, 0, 0);
+            return;
+        }
+        arch.rows.set(entry.rows.subarray(0, entry.count + entry.held), 0);
+        for (const cell of entry.cells)
+            writeBack(cell.col, cell.data, cell.length);
+        host.archetypes.rollbackSetOccupancy(arch, entry.count, entry.held);
+    };
+    return {
+        newImage() {
+            const img = new Image();
+            img.owner = owner;
+            return img;
+        },
+        captureImage(image) {
+            assertSerial('captureImage');
+            assertCoverable('captureImage');
+            const img = image;
+            assertOwned('captureImage', img);
+            img.seq += 1;
+            img.tick = world.tick;
+            const indexCount = host.entities.index.denseLen;
+            sizeIdentity(img.identity, indexCount);
+            host.entities.captureIdentity(img.identity);
+            for (const arch of host.archetypes.byId) {
+                if (arch.cold)
+                    continue;
+                captureArchetype(img, arch);
+            }
+            img.bitmaskWords = ensureU32(img.bitmaskWords, indexCount * host.bitmask.stride);
+            img.bitmaskIndexCount = indexCount;
+            img.bitmaskWordCount = host.bitmask.captureInto(img.bitmaskWords, indexCount, img.bitmaskSparse);
+            img.changeVersion = ensureU32(img.changeVersion, indexCount);
+            img.changeVersionCount = host.changeVersion().captureInto(img.changeVersion, indexCount);
+        },
+        restoreImage(image) {
+            assertSerial('restoreImage');
+            assertCoverable('restoreImage');
+            const img = image;
+            assertOwned('restoreImage', img);
+            if (img.seq === 0)
+                throw new Error('rollback restoreImage(): the image has never been captured into');
+            // Widest index the bitmask must be coherent over: the checkpoint's, or the current denseLen
+            // when the re-sim minted past it (those slots must lose their bits).
+            const clearThrough = Math.max(img.bitmaskIndexCount, host.entities.index.denseLen);
+            for (const arch of host.archetypes.byId) {
+                if (arch.cold)
+                    continue;
+                restoreArchetype(img, arch);
+            }
+            host.entities.restoreIdentity(img.identity);
+            host.bitmask.restoreFrom(img.bitmaskWords, img.bitmaskIndexCount, clearThrough, img.bitmaskSparse);
+            host.changeVersion().restoreFrom(img.changeVersion, img.changeVersionCount);
+            host.setTick(img.tick);
+            host.resyncQueries();
+        },
+        setTick(tick) {
+            assertSerial('setTick');
+            host.setTick(tick >>> 0);
+        },
+    };
+}
+//# sourceMappingURL=rollback.js.map

package/dist/rollback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.js","sourceRoot":"","sources":["../src/rollback.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,88 @@
+import type { World } from '@ecsia/core';
+/** A fixed-step simulation frame. Aligned 1:1 with `world.tick`: one `step()` == one tick. */
+export type Frame = number;
+export type PlayerId = number | string;
+/** App-defined opaque input bytes. The engine never interprets them — it buffers and compares. */
+export type InputImage = Uint8Array;
+/**
+ * How to synthesize a remote player's input for a frame that has no confirmed one yet.
+ * `lastConfirmed` is that player's most recently confirmed input, or null before their first.
+ * Default: repeat it (the GGPO default — correct for held-button controls).
+ */
+export type PredictionPolicy = (player: PlayerId, frame: Frame, lastConfirmed: InputImage | null) => InputImage;
+/**
+ * One frame's inputs, as handed to `applyInputs`. A REUSED view valid only for the duration of that
+ * call — read it, don't retain it. The returned bytes alias the session's input buffer.
+ */
+export interface FrameInputs {
+    readonly frame: Frame;
+    /** The session's players, in the order given to {@link RollbackOptions.players}. */
+    readonly players: readonly PlayerId[];
+    /** This frame's input for `player` — real or predicted. */
+    get(player: PlayerId): InputImage;
+    /** True when this frame's input for `player` is a prediction rather than a confirmed input. */
+    isPredicted(player: PlayerId): boolean;
+}
+/** A rollback the session could not perform — the app must resync from a fresh authoritative state. */
+export interface UnrecoverableRollback {
+    /** The frame the correction was for. */
+    readonly frame: Frame;
+    readonly currentFrame: Frame;
+    readonly maxRollbackFrames: number;
+    readonly message: string;
+}
+export interface RollbackOptions {
+    /**
+     * Maximum rollback DEPTH in frames: a correction for a frame more than this far behind
+     * `currentFrame` is unrecoverable. Must exceed worst-case input latency. (The ring itself holds
+     * one more image than this — a rollback to the deepest allowed frame restores the checkpoint
+     * taken BEFORE it.)
+     */
+    readonly maxRollbackFrames: number;
+    readonly players: readonly PlayerId[];
+    /**
+     * ONE fixed-step advance of the app's frame loop — typically `() => scheduler.update(dt)`. It MUST
+     * advance `world.tick` exactly once and MUST end at a frame boundary (its observer drain done), or
+     * the session throws: the checkpoint taken right after it would otherwise be mid-frame.
+     */
+    readonly step: () => void;
+    /** Write `inputs` into the world so `step()` reads them. Called before every step, re-sims included. */
+    readonly applyInputs: (frame: Frame, inputs: FrameInputs) => void;
+    /** Default: repeat the player's last confirmed input (empty bytes before their first). */
+    readonly predict?: PredictionPolicy;
+    /** Misprediction test. Default: byte equality. */
+    readonly equalsInput?: (a: InputImage, b: InputImage) => boolean;
+    /** Called instead of throwing when a rollback is unrecoverable (the world is left untouched). */
+    readonly onUnrecoverable?: (info: UnrecoverableRollback) => void;
+}
+export interface RollbackSession {
+    /**
+     * Advance one frame: predict any missing input, `applyInputs`, `step()`, checkpoint. Returns the
+     * frame just simulated.
+     */
+    advance(): Frame;
+    /**
+     * Record a REAL input. A frame at or behind `currentFrame` whose prediction it contradicts
+     * triggers the rollback + re-simulation synchronously, inside this call; one that matches the
+     * prediction costs nothing but an advancing `confirmedFrame`. Future frames are buffered (up to
+     * `maxRollbackFrames` ahead). Transport is the caller's job.
+     */
+    recordInput(player: PlayerId, frame: Frame, input: InputImage): void;
+    readonly currentFrame: Frame;
+    /** The latest simulated frame no player's input was predicted at. */
+    readonly confirmedFrame: Frame;
+}
+/**
+ * Drive a world through a rollback-netcode loop. Creates its own {@link RollbackSurface} and
+ * checkpoints the world as it stands NOW as frame `world.tick` — construct it at a frame boundary,
+ * with the world in the state every peer agrees on.
+ *
+ * FRAME↔TICK: a session frame IS `world.tick`. `currentFrame` starts at the world's tick and every
+ * `step()` must advance both by exactly one; the session asserts it rather than assuming it.
+ *
+ * BOUND: `world.tick` is u32 while `currentFrame` is an unbounded JS number, so a single session
+ * running past 2^32 frames (~2.3 years at 60 Hz) trips that assert rather than silently desyncing.
+ * Unhandled by design — no real session reaches it, and failing loudly beats a wrapped comparison.
+ */
+export declare function createRollbackSession(world: World, opts: RollbackOptions): RollbackSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,8FAA8F;AAC9F,MAAM,MAAM,KAAK,GAAG,MAAM,CAAA;AAE1B,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAA;AAEtC,kGAAkG;AAClG,MAAM,MAAM,UAAU,GAAG,UAAU,CAAA;AAEnC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,GAAG,IAAI,KAAK,UAAU,CAAA;AAE/G;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAA;IACrC,2DAA2D;IAC3D,GAAG,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAA;IACjC,+FAA+F;IAC/F,WAAW,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAA;CACvC;AAED,uGAAuG;AACvG,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAA;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAA;IACrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAA;IACzB,wGAAwG;IACxG,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;IACjE,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAA;IACnC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,KAAK,OAAO,CAAA;IAChE,iGAAiG;IACjG,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,CAAA;CACjE;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,IAAI,KAAK,CAAA;IAChB;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IACpE,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAA;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAA;CAC/B;AAoDD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,GAAG,eAAe,CAkP1F"}

package/dist/session.js

@@ -0,0 +1,265 @@
+// The GGPO-style predict → confirm → rollback → re-simulate loop over the capture/restore seam
+// (rollback.ts): a bounded checkpoint ring, a per-player frame-indexed input buffer, and a
+// re-simulation from the last known-good frame when a prediction turns out wrong.
+//
+// DELIBERATELY DECOUPLED, twice over. There is no @ecsia/scheduler dependency — the caller hands in
+// `step`, ONE fixed-step advance of its own frame loop. And the engine is schema-agnostic — an input
+// is opaque bytes it buffers, predicts and byte-compares; `applyInputs` is what writes those bytes
+// into whatever components the systems read.
+import { createRollbackSurface } from './rollback.js';
+const EMPTY_INPUT = new Uint8Array(0);
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function capacityFor(length) {
+    let cap = 1;
+    while (cap < length)
+        cap *= 2;
+    return cap;
+}
+function writeSlot(slot, frame, input, confirmed) {
+    if (slot.bytes.length < input.length) {
+        slot.bytes = new Uint8Array(capacityFor(input.length));
+        slot.view = null;
+    }
+    if (slot.length !== input.length)
+        slot.view = null;
+    slot.bytes.set(input, 0);
+    slot.length = input.length;
+    slot.frame = frame;
+    slot.confirmed = confirmed;
+}
+function slotView(slot) {
+    slot.view ??= slot.bytes.subarray(0, slot.length);
+    return slot.view;
+}
+/**
+ * Drive a world through a rollback-netcode loop. Creates its own {@link RollbackSurface} and
+ * checkpoints the world as it stands NOW as frame `world.tick` — construct it at a frame boundary,
+ * with the world in the state every peer agrees on.
+ *
+ * FRAME↔TICK: a session frame IS `world.tick`. `currentFrame` starts at the world's tick and every
+ * `step()` must advance both by exactly one; the session asserts it rather than assuming it.
+ *
+ * BOUND: `world.tick` is u32 while `currentFrame` is an unbounded JS number, so a single session
+ * running past 2^32 frames (~2.3 years at 60 Hz) trips that assert rather than silently desyncing.
+ * Unhandled by design — no real session reaches it, and failing loudly beats a wrapped comparison.
+ */
+export function createRollbackSession(world, opts) {
+    const maxRollbackFrames = opts.maxRollbackFrames;
+    if (!Number.isInteger(maxRollbackFrames) || maxRollbackFrames < 1) {
+        throw new Error(`rollback session: maxRollbackFrames must be a positive integer (got ${String(maxRollbackFrames)})`);
+    }
+    if (opts.players.length === 0)
+        throw new Error('rollback session: players must not be empty');
+    const players = [...opts.players];
+    const playerIndex = new Map();
+    for (const id of players) {
+        if (playerIndex.has(id))
+            throw new Error(`rollback session: duplicate player id ${String(id)}`);
+        playerIndex.set(id, playerIndex.size);
+    }
+    const predict = opts.predict ?? ((_player, _frame, lastConfirmed) => lastConfirmed ?? EMPTY_INPUT);
+    const equals = opts.equalsInput ?? bytesEqual;
+    const surface = createRollbackSurface(world);
+    // Held-row census only: the frame-boundary proof below. No state is installed by reading it.
+    const host = world.__installRollback();
+    // depth + 1: rolling back to depth `maxRollbackFrames` restores the checkpoint of the frame BEFORE
+    // it, so the ring must still hold one image older than the deepest re-simulated frame.
+    const ringSize = maxRollbackFrames + 1;
+    const images = [];
+    const imageFrames = [];
+    for (let i = 0; i < ringSize; i++) {
+        images.push(surface.newImage());
+        imageFrames.push(-1);
+    }
+    // The input window must cover the deepest re-simulated frame (currentFrame - maxRollbackFrames + 1)
+    // through the furthest buffered future one (currentFrame + maxRollbackFrames) at once.
+    const inputCapacity = maxRollbackFrames * 2;
+    const states = players.map((id) => ({
+        id,
+        slots: Array.from({ length: inputCapacity }, () => ({
+            frame: -1,
+            bytes: new Uint8Array(0),
+            length: 0,
+            confirmed: false,
+            view: null,
+        })),
+        lastConfirmedFrame: -1,
+        lastConfirmed: new Uint8Array(0),
+        lastConfirmedLength: 0,
+        lastConfirmedView: null,
+    }));
+    const stateOf = (player) => {
+        const i = playerIndex.get(player);
+        if (i === undefined) {
+            throw new Error(`rollback session: unknown player ${String(player)} — players are fixed at createRollbackSession`);
+        }
+        return states[i];
+    };
+    const startFrame = world.tick;
+    let currentFrame = startFrame;
+    let confirmedFrame = startFrame;
+    let viewFrame = startFrame;
+    const slotAt = (state, frame) => state.slots[frame % inputCapacity];
+    const inputs = {
+        get frame() {
+            return viewFrame;
+        },
+        players,
+        get(player) {
+            const slot = slotAt(stateOf(player), viewFrame);
+            if (slot.frame !== viewFrame) {
+                throw new Error(`rollback session: no buffered input for player ${String(player)} at frame ${viewFrame}`);
+            }
+            return slotView(slot);
+        },
+        isPredicted(player) {
+            const slot = slotAt(stateOf(player), viewFrame);
+            return slot.frame !== viewFrame || !slot.confirmed;
+        },
+    };
+    const lastConfirmedOf = (state) => {
+        if (state.lastConfirmedFrame < 0)
+            return null;
+        state.lastConfirmedView ??= state.lastConfirmed.subarray(0, state.lastConfirmedLength);
+        return state.lastConfirmedView;
+    };
+    const noteConfirmed = (state, frame, input) => {
+        if (frame < state.lastConfirmedFrame)
+            return;
+        if (state.lastConfirmed.length < input.length) {
+            state.lastConfirmed = new Uint8Array(capacityFor(input.length));
+            state.lastConfirmedView = null;
+        }
+        if (state.lastConfirmedLength !== input.length)
+            state.lastConfirmedView = null;
+        state.lastConfirmed.set(input, 0);
+        state.lastConfirmedLength = input.length;
+        state.lastConfirmedFrame = frame;
+    };
+    const applyFrame = (frame) => {
+        for (const state of states) {
+            const slot = slotAt(state, frame);
+            // A re-simulated frame that is STILL unconfirmed re-predicts: a correction that landed since
+            // moved `lastConfirmed`, and the better guess is the whole point of replaying it.
+            if (slot.frame === frame && slot.confirmed)
+                continue;
+            writeSlot(slot, frame, predict(state.id, frame, lastConfirmedOf(state)), false);
+        }
+        viewFrame = frame;
+        opts.applyInputs(frame, inputs);
+    };
+    const runStep = (frame) => {
+        opts.step();
+        if (world.tick !== frame) {
+            throw new Error(`rollback session: step() left world.tick at ${world.tick}, expected ${frame} — one session frame is exactly ONE fixed step (one world.tick increment). ` +
+                'Pass a step that runs a single frame (e.g. scheduler.update(dt)) and never advance the tick outside the session.');
+        }
+    };
+    const captureInto = (frame) => {
+        // An image rewinds STATE, not the EVENT STREAM (see RollbackSurface): the reactivity log rings
+        // and the pending observer window sit OUTSIDE it, so a checkpoint taken mid-frame lets an event
+        // journaled after it still drain once the restore has revoked what it describes. A checkpoint is
+        // therefore only ever taken here — immediately after `step()` returns, which is a post-drain
+        // frame boundary — and the observable symptom of a step that ended early is asserted, not
+        // assumed: held rows are what the drain releases, so any left mean the drain has not run.
+        let held = 0;
+        for (const arch of host.archetypes.byId)
+            held += arch.held;
+        if (held > 0) {
+            throw new Error(`rollback session: frame ${frame} cannot be checkpointed — ${held} deferred-dead rows are still held for an observer drain that step() has not run. ` +
+                'A checkpoint must be taken at a frame boundary: an image rewinds state, not the event stream, so those events would drain after a restore that revoked them.');
+        }
+        const slot = frame % ringSize;
+        surface.captureImage(images[slot]);
+        imageFrames[slot] = frame;
+    };
+    const unrecoverable = (frame, message) => {
+        if (opts.onUnrecoverable === undefined)
+            throw new Error(`rollback session: ${message}`);
+        opts.onUnrecoverable({ frame, currentFrame, maxRollbackFrames, message });
+    };
+    const rollbackTo = (frame) => {
+        const depth = currentFrame - frame;
+        if (depth >= maxRollbackFrames) {
+            unrecoverable(frame, `frame ${frame} is ${depth} frames behind frame ${currentFrame}, past the ${maxRollbackFrames}-frame rollback window — the world is untouched (no partial rewind); resync from a fresh authoritative state`);
+            return;
+        }
+        const baseline = frame - 1;
+        const slot = baseline % ringSize;
+        if (imageFrames[slot] !== baseline) {
+            unrecoverable(frame, `the checkpoint for frame ${baseline} is no longer in the ring (slot holds frame ${String(imageFrames[slot])}) — the world is untouched (no partial rewind); resync from a fresh authoritative state`);
+            return;
+        }
+        surface.restoreImage(images[slot]);
+        // The image carries the tick, so this is a check of frame↔tick alignment, not a repair: a
+        // disagreement means a checkpoint was keyed to a frame it was not taken at.
+        if (world.tick !== baseline) {
+            throw new Error(`rollback session: the checkpoint keyed to frame ${baseline} restored world.tick ${world.tick} — frame/tick alignment is broken`);
+        }
+        for (let f = frame; f <= currentFrame; f++) {
+            applyFrame(f);
+            runStep(f);
+            captureInto(f);
+        }
+    };
+    const allConfirmedAt = (frame) => {
+        for (const state of states) {
+            const slot = slotAt(state, frame);
+            if (slot.frame !== frame || !slot.confirmed)
+                return false;
+        }
+        return true;
+    };
+    const advanceConfirmed = () => {
+        while (confirmedFrame < currentFrame && allConfirmedAt(confirmedFrame + 1))
+            confirmedFrame += 1;
+    };
+    // The frame-`startFrame` checkpoint: what a rollback to `startFrame + 1` rewinds to. Nothing has
+    // been stepped yet, so this is a frame boundary by construction.
+    captureInto(startFrame);
+    return {
+        advance() {
+            const frame = currentFrame + 1;
+            applyFrame(frame);
+            runStep(frame);
+            captureInto(frame);
+            currentFrame = frame;
+            advanceConfirmed();
+            return frame;
+        },
+        recordInput(player, frame, input) {
+            const state = stateOf(player);
+            if (!Number.isInteger(frame) || frame <= startFrame) {
+                throw new Error(`rollback session: frame ${String(frame)} is not a frame this session simulates — its first frame is ${startFrame + 1} (frames are world ticks)`);
+            }
+            if (frame > currentFrame + maxRollbackFrames) {
+                throw new Error(`rollback session: input for frame ${frame} is more than ${maxRollbackFrames} frames ahead of frame ${currentFrame} — the input buffer cannot hold it without evicting a frame a rollback still needs`);
+            }
+            const slot = slotAt(state, frame);
+            if (frame <= currentFrame && slot.frame !== frame) {
+                unrecoverable(frame, `frame ${frame} has already left the ${inputCapacity}-frame input buffer, so its prediction cannot be checked — the world is untouched (no partial rewind); resync from a fresh authoritative state`);
+                return;
+            }
+            const mispredicted = slot.frame === frame && !slot.confirmed && !equals(input, slotView(slot));
+            writeSlot(slot, frame, input, true);
+            noteConfirmed(state, frame, input);
+            if (frame <= currentFrame && mispredicted)
+                rollbackTo(frame);
+            advanceConfirmed();
+        },
+        get currentFrame() {
+            return currentFrame;
+        },
+        get confirmedFrame() {
+            return confirmedFrame;
+        },
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ecsia/rollback",
+  "version": "0.25.0",
+  "description": "Handle-stable whole-world capture and restore for ecsia: the checkpoint substrate for rollback netcode and prediction.",
+  "keywords": [
+    "ecs",
+    "entity-component-system",
+    "ecsia",
+    "rollback",
+    "netcode",
+    "prediction",
+    "snapshot",
+    "data-oriented",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Andy Aragon",
+  "homepage": "https://github.com/andymai/ecsia",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andymai/ecsia.git",
+    "directory": "packages/rollback"
+  },
+  "bugs": {
+    "url": "https://github.com/andymai/ecsia/issues"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@ecsia/core": "workspace:*",
+    "@ecsia/schema": "workspace:*"
+  }
+}