@lagless/desync-diagnostics 0.0.48

package/src/lib/divergence-analysis.spec.ts

@@ -0,0 +1,178 @@
+import { analyzeDivergence } from './divergence-analysis.js';
+import type { DiagnosticsReport } from './report-generator.js';
+
+function makeReport(
+  playerSlot: number,
+  timeline: Array<{ tick: number; hash: number; physicsHash: number; wasRollback?: boolean }>,
+  rollbacks?: Array<{ atSimTick: number; rollbackToTick: number; timestamp: number }>,
+): DiagnosticsReport {
+  return {
+    version: 2,
+    generatedAt: new Date().toISOString(),
+    playerSlot,
+    config: { fps: 60, maxPlayers: 4, frameLength: 16.67, snapshotRate: 1, maxEntities: 1000 },
+    summary: {
+      totalTicks: timeline.length,
+      totalRollbacks: rollbacks?.length ?? 0,
+      firstDivergenceTick: null,
+      verifiedTickGapCount: 0,
+      latestPhysicsHash: timeline.length > 0 ? timeline[timeline.length - 1].physicsHash : 0,
+      oldestTick: timeline.length > 0 ? timeline[0].tick : 0,
+      newestTick: timeline.length > 0 ? timeline[timeline.length - 1].tick : 0,
+    },
+    timeline: timeline.map((t) => ({
+      tick: t.tick,
+      hash: t.hash,
+      physicsHash: t.physicsHash,
+      velocityHash: 0,
+      verifiedTick: t.tick - 1,
+      wasRollback: t.wasRollback ?? false,
+      inputCountBySlot: [0, 0, 0, 0],
+    })),
+    rollbacks: rollbacks ?? [],
+    inputHistory: {},
+  };
+}
+
+describe('analyzeDivergence', () => {
+  it('should return no divergence when all clients match', () => {
+    const timeline = [
+      { tick: 1, hash: 100, physicsHash: 1000 },
+      { tick: 2, hash: 200, physicsHash: 2000 },
+      { tick: 3, hash: 300, physicsHash: 3000 },
+    ];
+    const result = analyzeDivergence([
+      makeReport(0, timeline),
+      makeReport(1, timeline),
+    ]);
+
+    expect(result.firstEcsDivergenceTick).toBeNull();
+    expect(result.firstPhysicsDivergenceTick).toBeNull();
+  });
+
+  it('should find first ECS divergence tick', () => {
+    const result = analyzeDivergence([
+      makeReport(0, [
+        { tick: 1, hash: 100, physicsHash: 1000 },
+        { tick: 2, hash: 200, physicsHash: 2000 },
+        { tick: 3, hash: 999, physicsHash: 3000 },
+      ]),
+      makeReport(1, [
+        { tick: 1, hash: 100, physicsHash: 1000 },
+        { tick: 2, hash: 200, physicsHash: 2000 },
+        { tick: 3, hash: 300, physicsHash: 3000 },
+      ]),
+    ]);
+
+    expect(result.firstEcsDivergenceTick).toBe(3);
+    expect(result.firstPhysicsDivergenceTick).toBeNull();
+  });
+
+  it('should find first physics divergence tick', () => {
+    const result = analyzeDivergence([
+      makeReport(0, [
+        { tick: 1, hash: 100, physicsHash: 1000 },
+        { tick: 2, hash: 200, physicsHash: 9999 },
+      ]),
+      makeReport(1, [
+        { tick: 1, hash: 100, physicsHash: 1000 },
+        { tick: 2, hash: 200, physicsHash: 2000 },
+      ]),
+    ]);
+
+    expect(result.firstEcsDivergenceTick).toBeNull();
+    expect(result.firstPhysicsDivergenceTick).toBe(2);
+  });
+
+  it('should use LAST occurrence of a tick in timeline (rollback resimulation)', () => {
+    // Client 0 has tick 2 twice — original (hash=200) and resimulated (hash=250)
+    // The final hash is 250, which matches client 1's hash of 250
+    const result = analyzeDivergence([
+      makeReport(0, [
+        { tick: 1, hash: 100, physicsHash: 1000 },
+        { tick: 2, hash: 200, physicsHash: 2000 },  // original — stale
+        { tick: 3, hash: 300, physicsHash: 3000 },
+        { tick: 2, hash: 250, physicsHash: 2500, wasRollback: true },  // resimulated — final
+        { tick: 3, hash: 350, physicsHash: 3500, wasRollback: true },
+      ]),
+      makeReport(1, [
+        { tick: 1, hash: 100, physicsHash: 1000 },
+        { tick: 2, hash: 250, physicsHash: 2500 },
+        { tick: 3, hash: 350, physicsHash: 3500 },
+      ]),
+    ]);
+
+    expect(result.firstEcsDivergenceTick).toBeNull();
+    expect(result.firstPhysicsDivergenceTick).toBeNull();
+  });
+
+  it('should build checkpoint comparison at specified interval', () => {
+    const timeline = Array.from({ length: 120 }, (_, i) => ({
+      tick: i + 1,
+      hash: (i + 1) * 10,
+      physicsHash: (i + 1) * 100,
+    }));
+
+    const result = analyzeDivergence([
+      makeReport(0, timeline),
+      makeReport(1, timeline),
+    ], 60);
+
+    // Checkpoint at tick 60 and 120
+    expect(result.checkpointComparison.length).toBe(2);
+    expect(result.checkpointComparison[0].tick).toBe(60);
+    expect(result.checkpointComparison[0].ecsMatch).toBe(true);
+    expect(result.checkpointComparison[0].physicsMatch).toBe(true);
+    expect(result.checkpointComparison[1].tick).toBe(120);
+  });
+
+  it('should detect rollback overlap windows', () => {
+    const timeline = Array.from({ length: 20 }, (_, i) => ({
+      tick: i + 1,
+      hash: (i + 1) * 10,
+      physicsHash: (i + 1) * 100,
+    }));
+
+    const result = analyzeDivergence([
+      makeReport(0, timeline, [
+        { atSimTick: 15, rollbackToTick: 10, timestamp: 1000 },
+      ]),
+      makeReport(1, timeline, [
+        { atSimTick: 16, rollbackToTick: 12, timestamp: 1001 },
+      ]),
+    ]);
+
+    // Overlap: client 0 resims 10-15, client 1 resims 12-16 → overlap is 12-15
+    expect(result.rollbackOverlapWindows.length).toBeGreaterThan(0);
+    const window = result.rollbackOverlapWindows[0];
+    expect(window.startTick).toBe(12);
+    expect(window.endTick).toBe(15);
+    expect(window.affectedSlots).toContain(0);
+    expect(window.affectedSlots).toContain(1);
+  });
+
+  it('should return no divergence for a single client', () => {
+    const result = analyzeDivergence([
+      makeReport(0, [
+        { tick: 1, hash: 100, physicsHash: 1000 },
+      ]),
+    ]);
+
+    expect(result.firstEcsDivergenceTick).toBeNull();
+    expect(result.firstPhysicsDivergenceTick).toBeNull();
+    expect(result.checkpointComparison).toHaveLength(0);
+    expect(result.rollbackOverlapWindows).toHaveLength(0);
+  });
+
+  it('should handle clients with empty timelines', () => {
+    const result = analyzeDivergence([
+      makeReport(0, []),
+      makeReport(1, []),
+    ]);
+
+    expect(result.firstEcsDivergenceTick).toBeNull();
+    expect(result.firstPhysicsDivergenceTick).toBeNull();
+    expect(result.checkpointComparison).toHaveLength(0);
+    expect(result.rollbackOverlapWindows).toHaveLength(0);
+  });
+});

package/src/lib/divergence-analysis.ts

@@ -0,0 +1,179 @@
+import type { DiagnosticsReport } from './report-generator.js';
+
+export interface CheckpointComparison {
+  tick: number;
+  ecsHashes: Record<number, number>;
+  physicsHashes: Record<number, number>;
+  ecsMatch: boolean;
+  physicsMatch: boolean;
+}
+
+export interface RollbackOverlapWindow {
+  startTick: number;
+  endTick: number;
+  affectedSlots: number[];
+}
+
+export interface DivergenceAnalysis {
+  firstEcsDivergenceTick: number | null;
+  firstPhysicsDivergenceTick: number | null;
+  checkpointComparison: CheckpointComparison[];
+  rollbackOverlapWindows: RollbackOverlapWindow[];
+}
+
+interface FinalHashEntry {
+  hash: number;
+  physicsHash: number;
+}
+
+/**
+ * Build a map of tick → final hash for a client's timeline.
+ * For ticks that appear multiple times (rollback resimulation),
+ * the LAST occurrence is the correct "final" state.
+ */
+function buildFinalHashMap(report: DiagnosticsReport): Map<number, FinalHashEntry> {
+  const map = new Map<number, FinalHashEntry>();
+  for (const record of report.timeline) {
+    map.set(record.tick, { hash: record.hash, physicsHash: record.physicsHash });
+  }
+  return map;
+}
+
+const DEFAULT_CHECKPOINT_INTERVAL = 60;
+
+export function analyzeDivergence(
+  clients: DiagnosticsReport[],
+  checkpointInterval = DEFAULT_CHECKPOINT_INTERVAL,
+): DivergenceAnalysis {
+  if (clients.length < 2) {
+    return {
+      firstEcsDivergenceTick: null,
+      firstPhysicsDivergenceTick: null,
+      checkpointComparison: [],
+      rollbackOverlapWindows: [],
+    };
+  }
+
+  const finalHashMaps = clients.map((c) => buildFinalHashMap(c));
+
+  // Collect all ticks present in ALL clients
+  const allTicks = new Set<number>();
+  for (const [tick] of finalHashMaps[0]) {
+    if (finalHashMaps.every((m) => m.has(tick))) {
+      allTicks.add(tick);
+    }
+  }
+
+  const sortedTicks = [...allTicks].sort((a, b) => a - b);
+
+  // Find first divergence ticks
+  let firstEcsDivergenceTick: number | null = null;
+  let firstPhysicsDivergenceTick: number | null = null;
+
+  for (const tick of sortedTicks) {
+    if (firstEcsDivergenceTick === null) {
+      const ecsHashes = finalHashMaps.map((m) => m.get(tick)!.hash);
+      if (!ecsHashes.every((h) => h === ecsHashes[0])) {
+        firstEcsDivergenceTick = tick;
+      }
+    }
+    if (firstPhysicsDivergenceTick === null) {
+      const physicsHashes = finalHashMaps.map((m) => m.get(tick)!.physicsHash);
+      if (!physicsHashes.every((h) => h === physicsHashes[0])) {
+        firstPhysicsDivergenceTick = tick;
+      }
+    }
+    if (firstEcsDivergenceTick !== null && firstPhysicsDivergenceTick !== null) {
+      break;
+    }
+  }
+
+  // Build checkpoint comparison at interval
+  const checkpointComparison: CheckpointComparison[] = [];
+  for (const tick of sortedTicks) {
+    if (tick % checkpointInterval !== 0) continue;
+
+    const ecsHashes: Record<number, number> = {};
+    const physicsHashes: Record<number, number> = {};
+    for (let i = 0; i < clients.length; i++) {
+      const entry = finalHashMaps[i].get(tick)!;
+      ecsHashes[clients[i].playerSlot] = entry.hash;
+      physicsHashes[clients[i].playerSlot] = entry.physicsHash;
+    }
+
+    const ecsValues = Object.values(ecsHashes);
+    const physicsValues = Object.values(physicsHashes);
+
+    checkpointComparison.push({
+      tick,
+      ecsHashes,
+      physicsHashes,
+      ecsMatch: ecsValues.every((h) => h === ecsValues[0]),
+      physicsMatch: physicsValues.every((h) => h === physicsValues[0]),
+    });
+  }
+
+  // Find rollback overlap windows
+  const rollbackOverlapWindows = findRollbackOverlaps(clients);
+
+  return {
+    firstEcsDivergenceTick,
+    firstPhysicsDivergenceTick,
+    checkpointComparison,
+    rollbackOverlapWindows,
+  };
+}
+
+interface RollbackRange {
+  slot: number;
+  startTick: number;
+  endTick: number;
+}
+
+function findRollbackOverlaps(clients: DiagnosticsReport[]): RollbackOverlapWindow[] {
+  // Collect all rollback ranges from all clients
+  const ranges: RollbackRange[] = [];
+  for (const client of clients) {
+    for (const rb of client.rollbacks) {
+      ranges.push({
+        slot: client.playerSlot,
+        startTick: rb.rollbackToTick,
+        endTick: rb.atSimTick,
+      });
+    }
+  }
+
+  // Find overlapping ranges between different slots
+  const windows: RollbackOverlapWindow[] = [];
+  for (let i = 0; i < ranges.length; i++) {
+    for (let j = i + 1; j < ranges.length; j++) {
+      if (ranges[i].slot === ranges[j].slot) continue;
+
+      const overlapStart = Math.max(ranges[i].startTick, ranges[j].startTick);
+      const overlapEnd = Math.min(ranges[i].endTick, ranges[j].endTick);
+
+      if (overlapStart < overlapEnd) {
+        // Check if this window is already covered
+        const existing = windows.find(
+          (w) => w.startTick === overlapStart && w.endTick === overlapEnd,
+        );
+        if (existing) {
+          if (!existing.affectedSlots.includes(ranges[i].slot)) {
+            existing.affectedSlots.push(ranges[i].slot);
+          }
+          if (!existing.affectedSlots.includes(ranges[j].slot)) {
+            existing.affectedSlots.push(ranges[j].slot);
+          }
+        } else {
+          windows.push({
+            startTick: overlapStart,
+            endTick: overlapEnd,
+            affectedSlots: [ranges[i].slot, ranges[j].slot],
+          });
+        }
+      }
+    }
+  }
+
+  return windows.sort((a, b) => a.startTick - b.startTick);
+}

package/src/lib/hash-bytes.spec.ts

@@ -0,0 +1,29 @@
+import { hashBytes } from './hash-bytes.js';
+
+describe('hashBytes', () => {
+  it('should return 0 for empty input', () => {
+    expect(hashBytes(new Uint8Array(0))).toBe(0);
+  });
+
+  it('should produce consistent hash for same input', () => {
+    const data = new Uint8Array([1, 2, 3, 4, 5]);
+    const hash1 = hashBytes(data);
+    const hash2 = hashBytes(data);
+    expect(hash1).toBe(hash2);
+    expect(hash1).not.toBe(0);
+  });
+
+  it('should produce different hashes for different input', () => {
+    const a = new Uint8Array([1, 2, 3]);
+    const b = new Uint8Array([3, 2, 1]);
+    expect(hashBytes(a)).not.toBe(hashBytes(b));
+  });
+
+  it('should return a 32-bit unsigned integer', () => {
+    const data = new Uint8Array(1000);
+    for (let i = 0; i < data.length; i++) data[i] = i & 0xFF;
+    const hash = hashBytes(data);
+    expect(hash).toBeGreaterThanOrEqual(0);
+    expect(hash).toBeLessThanOrEqual(0xFFFFFFFF);
+  });
+});

package/src/lib/hash-bytes.ts

@@ -0,0 +1,11 @@
+/**
+ * Polynomial hash (same algorithm as Mem.getHash) but using direct Uint8Array indexing
+ * instead of DataView for better performance on large buffers (e.g. Rapier snapshots).
+ */
+export function hashBytes(data: Uint8Array): number {
+  let hash = 0;
+  for (let i = 0; i < data.length; i++) {
+    hash = (hash * 31 + data[i]) >>> 0;
+  }
+  return hash;
+}