@trolleroof/tui 0.2.5 → 0.2.6

package/src/recording/trace-recorder.test.ts

@@ -0,0 +1,287 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { RecordingStore } from "./store.js";
+import { parseTerminalGrid } from "./terminal-grid.js";
+import { InteractionTraceRecorder, recoverActiveTraces } from "./trace-recorder.js";
+import { isTraceEvent, isTraceEventChunk } from "./types.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function sequenceFactory(prefix: string): () => string {
+  let next = 0;
+  return () => `${prefix}_${++next}`;
+}
+
+function setup(maxEventsPerChunk = 50) {
+  const root = mkdtempSync(join(tmpdir(), "gamepigeon-trace-"));
+  roots.push(root);
+  const store = new RecordingStore(root);
+  let wall = 1_000;
+  let monotonic = 10;
+  const recorder = new InteractionTraceRecorder({
+    store,
+    userId: "usr_test",
+    gameType: "tetris",
+    gameVersion: "1",
+    rulesetId: "classic",
+    seed: 7,
+    initialState: { board: [], active: "T" },
+    controlSchema: ["left", "right", "rotate-cw", "tick"],
+    viewport: { width: 8, height: 3 },
+    applicationVersion: "test",
+    config: { maxEventsPerChunk },
+    wallTimeMs: () => wall++,
+    monotonicTimeMs: () => monotonic++,
+    createGameId: () => "game_test",
+    createEventId: sequenceFactory("evt"),
+    createChunkId: sequenceFactory("chk"),
+    createObservationId: sequenceFactory("obs"),
+  });
+  return { recorder, store };
+}
+
+describe("InteractionTraceRecorder", () => {
+  it("never scans the global upload backlog from an individual recorder", () => {
+    const root = mkdtempSync(join(tmpdir(), "gamepigeon-trace-no-scan-"));
+    roots.push(root);
+    let scans = 0;
+    class CountingStore extends RecordingStore {
+      override listPending() {
+        scans++;
+        return super.listPending();
+      }
+    }
+    const recorder = new InteractionTraceRecorder({
+      store: new CountingStore(root),
+      userId: "usr_test",
+      gameType: "2048",
+      gameVersion: "1",
+      rulesetId: "classic",
+      seed: 1,
+      initialState: {},
+      controlSchema: ["left"],
+      viewport: { width: 80, height: 24 },
+      config: { maxEventsPerChunk: 1 },
+    });
+    recorder.endEpisode({ reason: "user_quit", finalScore: 0, completed: false });
+    expect(scans).toBe(0);
+  });
+
+  it("records a game-agnostic causal trace with four universal identity fields", () => {
+    const { recorder, store } = setup();
+    const initial = recorder.recordObservation({
+      grid: parseTerminalGrid(["TETRIS", "  []"], { width: 8, height: 3 }),
+      simulationTick: 0,
+    });
+    const control = recorder.recordControl({
+      control: "ArrowLeft",
+      action: "left",
+      actor: "human",
+      simulationTick: 1,
+      receivedTimeUs: 12_000,
+    });
+    recorder.recordObservation({
+      grid: parseTerminalGrid(["TETRIS", " [] "], { width: 8, height: 3 }),
+      simulationTick: 1,
+      causedByEventId: control,
+    });
+    recorder.recordOutcome({
+      scoreBefore: 0,
+      scoreAfter: 4,
+      engineReward: 4,
+      terminal: false,
+      causedByEventId: control,
+      simulationTick: 1,
+      performance: {
+        action_received_us: 12_000,
+        action_applied_us: 13_000,
+        action_completed_us: 15_000,
+        queueing_delay_us: 1_000,
+        simulation_tick_duration_us: 2_000,
+      },
+    });
+    recorder.recordCheckpoint({
+      state: { board: [["T"]] },
+      reason: "random_outcome",
+      randomEffects: { queuedPiece: "I" },
+      causedByEventId: control,
+      simulationTick: 1,
+    });
+    recorder.endEpisode({ reason: "user_quit", finalScore: 4, completed: false });
+
+    const completed = store.listCompletedGames()[0]!;
+    const events = completed.events.filter(isTraceEvent);
+    expect(events.map((event) => event.event_type)).toEqual([
+      "episode_started",
+      "engine_checkpoint",
+      "observation",
+      "control_changed",
+      "observation",
+      "outcome_changed",
+      "engine_checkpoint",
+      "episode_ended",
+    ]);
+    for (const event of events) {
+      expect(event.schema_version).toBe(2);
+      expect(event.user_id).toBe("usr_test");
+      expect(event.game_id).toBe("game_test");
+      expect(event.chunk_id).toMatch(/^chk_/);
+      expect(event.event_id).toMatch(/^evt_/);
+    }
+
+    const firstObservation = events[2]!;
+    expect(firstObservation.event_type).toBe("observation");
+    if (firstObservation.event_type !== "observation") throw new Error("expected observation");
+    expect(firstObservation.payload.observation_id).toBe(initial);
+
+    const controlEvent = events[3]!;
+    expect(controlEvent.event_type).toBe("control_changed");
+    if (controlEvent.event_type !== "control_changed") throw new Error("expected control");
+    expect(controlEvent.payload).toEqual({
+      based_on_observation_id: initial,
+      control: "ArrowLeft",
+      action: "left",
+      kind: "impulse",
+      actor: "human",
+      action_received_us: 12_000,
+    });
+
+    const resultingObservation = events[4]!;
+    if (resultingObservation.event_type !== "observation") throw new Error("expected observation");
+    expect(resultingObservation.payload).toMatchObject({
+      representation: "terminal_grid_delta_v1",
+      base_observation_id: initial,
+      caused_by_event_id: control,
+    });
+    const checkpoint = events[6]!;
+    expect(checkpoint.visibility).toBe("privileged");
+    expect(checkpoint.payload).toMatchObject({
+      reason: "random_outcome",
+      random_effects: { queuedPiece: "I" },
+      state_hash: expect.stringMatching(/^sha256:/),
+    });
+    const outcome = events[5]!;
+    if (outcome.event_type !== "outcome_changed") throw new Error("expected outcome");
+    expect(outcome.payload.performance).toEqual({
+      action_received_us: 12_000,
+      action_applied_us: 13_000,
+      action_completed_us: 15_000,
+      queueing_delay_us: 1_000,
+      simulation_tick_duration_us: 2_000,
+    });
+
+    const chunks = store.listPending();
+    expect(chunks).toHaveLength(1);
+    const chunk = chunks[0]!.chunk;
+    if (!isTraceEventChunk(chunk)) throw new Error("expected trace chunk");
+    expect(chunk).toMatchObject({
+      schema_version: 2,
+      user_id: "usr_test",
+      game_id: "game_test",
+      chunk_id: events[0]!.chunk_id,
+    });
+    expect(chunk.events.every((event) =>
+      event.chunk_id === chunk.chunk_id
+    )).toBe(true);
+  });
+
+  it("assigns the next chunk id before appending events after a flush boundary", () => {
+    const { recorder, store } = setup(2);
+    recorder.recordObservation({
+      grid: parseTerminalGrid(["one"], { width: 8, height: 3 }),
+      simulationTick: 0,
+    });
+    recorder.recordControl({
+      control: "ArrowRight",
+      action: "right",
+      actor: "human",
+      simulationTick: 1,
+    });
+    recorder.endEpisode({ reason: "user_quit", finalScore: 0, completed: false });
+
+    const chunks = store.listPending();
+    expect(chunks.length).toBeGreaterThan(1);
+    expect(new Set(chunks.map((chunk) => chunk.chunk.chunk_id)).size).toBe(chunks.length);
+    for (const persisted of chunks) {
+      if (!isTraceEventChunk(persisted.chunk)) throw new Error("expected trace chunk");
+      expect(persisted.chunk.events.every((event) =>
+        event.chunk_id === persisted.chunk.chunk_id
+      )).toBe(true);
+    }
+  });
+
+  it("keeps gameplay alive when a privileged checkpoint cannot be serialized", () => {
+    const { recorder } = setup();
+    expect(() => recorder.recordCheckpoint({
+      state: { unsupported: () => undefined },
+      reason: "periodic",
+    })).not.toThrow();
+    expect(recorder.health().status).toBe("degraded");
+    expect(recorder.health().last_error).toContain("cloned");
+    recorder.endEpisode({ reason: "user_quit", finalScore: 0, completed: false });
+  });
+
+  it("recovers missing chunks with the ids assigned before a crash", () => {
+    const root = mkdtempSync(join(tmpdir(), "gamepigeon-trace-recovery-"));
+    roots.push(root);
+    class InterruptedStore extends RecordingStore {
+      private writes = 0;
+
+      override persistChunk(chunk: Parameters<RecordingStore["persistChunk"]>[0]) {
+        this.writes++;
+        if (this.writes > 1) throw new Error("simulated crash");
+        return super.persistChunk(chunk);
+      }
+    }
+
+    const interrupted = new InterruptedStore(root);
+    const recorder = new InteractionTraceRecorder({
+      store: interrupted,
+      userId: "usr_test",
+      gameType: "tetris",
+      gameVersion: "1",
+      rulesetId: "classic",
+      seed: 7,
+      initialState: { board: [] },
+      controlSchema: ["left"],
+      viewport: { width: 8, height: 3 },
+      config: { maxEventsPerChunk: 2 },
+      createGameId: () => "game_recovery",
+      createEventId: sequenceFactory("evt"),
+      createChunkId: sequenceFactory("chk"),
+      createObservationId: sequenceFactory("obs"),
+    });
+    recorder.recordObservation({
+      grid: parseTerminalGrid(["TETRIS"], { width: 8, height: 3 }),
+    });
+    const control = recorder.recordControl({
+      control: "left",
+      action: "left",
+      actor: "human",
+    });
+    recorder.recordObservation({
+      grid: parseTerminalGrid([" TETRIS"], { width: 8, height: 3 }),
+      causedByEventId: control,
+    });
+    recorder.endEpisode({ reason: "user_quit", finalScore: 0, completed: false });
+
+    const store = new RecordingStore(root);
+    expect(recoverActiveTraces(store, { applicationVersion: "test" })).toEqual({
+      games: 1,
+      chunks: 1,
+      events: 4,
+    });
+    const chunks = store.listPending();
+    expect(chunks.map((item) => item.chunk.chunk_id)).toEqual(["chk_1", "chk_2"]);
+    expect(chunks.map((item) => item.chunk.chunk_sequence)).toEqual([1, 2]);
+    const recovered = chunks[1]!.chunk;
+    if (!isTraceEventChunk(recovered)) throw new Error("expected trace chunk");
+    expect(recovered.events.every((event) => event.chunk_id === "chk_2")).toBe(true);
+    expect(store.listActiveGameIds()).toEqual([]);
+  });
+});