@cursor/july 0.1.26 → 0.1.28

package/src/internal/storage-coordinator.test.ts

@@ -1,517 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { ABMetricSample } from "../ab.js";
-import type { EvalRunSnapshot } from "../evals.js";
-import type { StorageContext } from "../storage.js";
-import { defineStorage, storageKeys } from "../storage.js";
-import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
-import type { ABSnapshot } from "./ab-snapshot.js";
-import type { ReminderRecord } from "./reminder-store.js";
-import { StorageCoordinator } from "./storage-coordinator.js";
-
-function makeRecord(
-  sessionId: string,
-  turnCount = 0,
-  continuationKey: string | null = null
-): SessionRecord {
-  const now = new Date().toISOString();
-  return {
-    sessionId,
-    channelId: "http",
-    mode: "chat",
-    continuationKey,
-    auth: null,
-    turnCount,
-    createdAt: now,
-    updatedAt: now,
-  };
-}
-
-let eventIndex = 0;
-function makeEvent(
-  sessionId: string,
-  type: SessionEvent["type"]
-): SessionEvent {
-  return {
-    sessionId,
-    index: eventIndex++,
-    at: new Date().toISOString(),
-    type,
-    data: {},
-  } as SessionEvent;
-}
-
-interface Call {
-  op: "put" | "delete";
-  key: string;
-  value?: JsonValue;
-  ctx: StorageContext;
-}
-
-function makeCoordinator(options?: {
-  policy?: Parameters<typeof defineStorage>[0]["policy"];
-  put?: (key: string, value: JsonValue) => void | Promise<void>;
-}): {
-  coordinator: StorageCoordinator;
-  calls: Call[];
-  store: Map<string, JsonValue>;
-} {
-  const calls: Call[] = [];
-  const store = new Map<string, JsonValue>();
-  const definition = defineStorage({
-    policy: options?.policy,
-    put: async (key, value, ctx) => {
-      calls.push({ op: "put", key, value, ctx });
-      await options?.put?.(key, value);
-      store.set(key, value);
-    },
-    delete: (key, ctx) => {
-      calls.push({ op: "delete", key, ctx });
-      store.delete(key);
-    },
-    get: (key) => store.get(key),
-    list: (prefix) =>
-      [...store.entries()]
-        .filter(([key]) => key.startsWith(prefix))
-        .sort(([a], [b]) => (a < b ? -1 : 1))
-        .map(([key, value]) => ({ key, value })),
-  });
-  const coordinator = new StorageCoordinator({
-    definition,
-    agentName: "test-agent",
-    projectRoot: "/tmp/test-agent",
-    logger: () => {},
-  });
-  return { coordinator, calls, store };
-}
-
-/**
- * Append + dispatch-settled, as the engine drives it: the boundary flush
- * only fires from eventDispatched, after the event's handlers ran.
- */
-function emit(coordinator: StorageCoordinator, event: SessionEvent): void {
-  coordinator.event(event);
-  coordinator.eventDispatched(event);
-}
-
-describe("StorageCoordinator", () => {
-  it("buffers events and coalesced records until a turn boundary", async () => {
-    const { coordinator, calls } = makeCoordinator();
-
-    coordinator.sessionRecord(makeRecord("s1", 0));
-    const first = makeEvent("s1", "session.started");
-    emit(coordinator, first);
-    emit(coordinator, makeEvent("s1", "message.received"));
-    coordinator.sessionRecord(makeRecord("s1", 1));
-    await coordinator.whenIdle();
-    expect(calls).toHaveLength(0);
-
-    emit(coordinator, makeEvent("s1", "turn.completed"));
-    await coordinator.whenIdle();
-
-    // One chunk put (keyed by the first event's index) + one record put.
-    expect(calls.map((call) => call.key)).toEqual([
-      storageKeys.sessionEvents("test-agent", "s1", first.index),
-      storageKeys.session("test-agent", "s1"),
-    ]);
-    const chunk = calls[0]?.value as unknown as SessionEvent[];
-    expect(chunk.map((event) => event.type)).toEqual([
-      "session.started",
-      "message.received",
-      "turn.completed",
-    ]);
-    // Only the newest record survives coalescing.
-    const record = calls[1]?.value as unknown as SessionRecord;
-    expect(record.turnCount).toBe(1);
-    expect(calls[0]?.ctx).toMatchObject({
-      agentName: "test-agent",
-      projectRoot: "/tmp/test-agent",
-      reason: "policy",
-    });
-  });
-
-  it("keeps sessions independent", async () => {
-    const { coordinator, calls } = makeCoordinator();
-    const s1 = makeEvent("s1", "message.received");
-    emit(coordinator, s1);
-    emit(coordinator, makeEvent("s2", "message.received"));
-    emit(coordinator, makeEvent("s1", "turn.completed"));
-    await coordinator.whenIdle();
-
-    expect(calls).toHaveLength(1);
-    expect(calls[0]?.key).toBe(
-      storageKeys.sessionEvents("test-agent", "s1", s1.index)
-    );
-  });
-
-  it("includes record updates from boundary-event handlers in the flush", async () => {
-    const { coordinator, calls } = makeCoordinator();
-    const boundary = makeEvent("s1", "turn.completed");
-    coordinator.event(boundary);
-    // The boundary event's own handler updates the record (e.g. channel
-    // state or a new continuation token) before dispatch settles.
-    coordinator.sessionRecord(makeRecord("s1", 7));
-    coordinator.eventDispatched(boundary);
-    await coordinator.whenIdle();
-
-    const record = calls.find(
-      (call) => call.key === storageKeys.session("test-agent", "s1")
-    )?.value as unknown as SessionRecord;
-    expect(record.turnCount).toBe(7);
-  });
-
-  it("maintains the continuation index across token changes", async () => {
-    const { coordinator, calls, store } = makeCoordinator();
-
-    coordinator.sessionRecord(makeRecord("s1", 0, "tok-a"));
-    emit(coordinator, makeEvent("s1", "turn.completed"));
-    await coordinator.whenIdle();
-    const keyA = storageKeys.continuation("test-agent", "http", "tok-a");
-    expect(store.get(keyA)).toEqual({ sessionId: "s1" });
-
-    // Token rotates: the stale index entry is deleted, the new one put.
-    coordinator.sessionRecord(makeRecord("s1", 1, "tok-b"));
-    emit(coordinator, makeEvent("s1", "turn.completed"));
-    await coordinator.whenIdle();
-    const keyB = storageKeys.continuation("test-agent", "http", "tok-b");
-    expect(store.has(keyA)).toBe(false);
-    expect(store.get(keyB)).toEqual({ sessionId: "s1" });
-    expect(
-      calls.some((call) => call.op === "delete" && call.key === keyA)
-    ).toBe(true);
-
-    // Unchanged token on the next flush emits no index writes.
-    const before = calls.length;
-    coordinator.sessionRecord(makeRecord("s1", 2, "tok-b"));
-    emit(coordinator, makeEvent("s1", "turn.completed"));
-    await coordinator.whenIdle();
-    const indexWrites = calls
-      .slice(before)
-      .filter((call) => call.key.includes("/continuation/"));
-    expect(indexWrites).toHaveLength(0);
-  });
-
-  it("bounds oversized continuation tokens in keys and round-trips them", async () => {
-    const { coordinator, store } = makeCoordinator();
-    // A hostile caller-supplied token: multi-byte characters inflate the
-    // URI-encoding well past any sane backend key limit.
-    const hugeToken = "TOKEN-\u{1F4A5}".repeat(600);
-    const key = storageKeys.continuation("test-agent", "http", hugeToken);
-    expect(key).toContain("/continuation/http/sha256:");
-    expect(Buffer.byteLength(key, "utf8")).toBeLessThan(512);
-    // Deterministic: the same token always mints the same key.
-    expect(storageKeys.continuation("test-agent", "http", hugeToken)).toBe(key);
-
-    // Write path (flush) and read path (lazy lookup) agree on the key.
-    coordinator.sessionRecord(makeRecord("s1", 0, hugeToken));
-    emit(coordinator, makeEvent("s1", "turn.completed"));
-    await coordinator.whenIdle();
-    expect(store.get(key)).toEqual({ sessionId: "s1" });
-    const record = await coordinator.getSessionByContinuation(
-      "http",
-      hugeToken
-    );
-    expect(record?.sessionId).toBe("s1");
-    await expect(coordinator.getSessionById("s1")).resolves.toMatchObject({
-      sessionId: "s1",
-    });
-    await expect(coordinator.getSessionById("ses_missing")).resolves.toBe(
-      undefined
-    );
-  });
-
-  it("drops writes once the delivery queue is full", async () => {
-    let release: (() => void) | undefined;
-    const gate = new Promise<void>((resolve) => {
-      release = resolve;
-    });
-    const logs: string[] = [];
-    const definition = defineStorage({
-      put: () => gate,
-    });
-    const coordinator = new StorageCoordinator({
-      definition,
-      agentName: "test-agent",
-      projectRoot: "/tmp/test-agent",
-      logger: (line) => logs.push(line),
-    });
-
-    // The first put blocks the queue; well past the bound, later flushes
-    // must be shed instead of growing memory without limit.
-    for (let i = 0; i < 1_200; i += 1) {
-      emit(coordinator, makeEvent(`s${i}`, "turn.completed"));
-    }
-    expect(logs.some((line) => line.includes("storage queue full"))).toBe(true);
-    release?.();
-    await coordinator.whenIdle();
-  });
-
-  it("flushes at the batch cap under a debounce policy", async () => {
-    const { coordinator, calls } = makeCoordinator({
-      policy: { debounceMs: 60_000 },
-    });
-    for (let i = 0; i < 200; i += 1) {
-      emit(coordinator, makeEvent("s1", "message.received"));
-    }
-    await coordinator.whenIdle();
-    expect(calls).toHaveLength(1);
-    expect((calls[0]?.value as unknown as SessionEvent[]).length).toBe(200);
-  });
-
-  it("debounce spans turn boundaries and carries the coalesced record", async () => {
-    vi.useFakeTimers();
-    try {
-      const { coordinator, calls } = makeCoordinator({
-        policy: { debounceMs: 1_000 },
-      });
-      const first = makeEvent("s1", "message.received");
-      emit(coordinator, first);
-      // Boundary events do NOT flush a debounced session.
-      emit(coordinator, makeEvent("s1", "turn.completed"));
-      coordinator.sessionRecord(makeRecord("s1", 1));
-      emit(coordinator, makeEvent("s1", "message.received"));
-      emit(coordinator, makeEvent("s1", "turn.completed"));
-      coordinator.sessionRecord(makeRecord("s1", 2));
-      await coordinator.whenIdle();
-      expect(calls).toHaveLength(0);
-
-      // Quiet period elapses: both turns land in one chunk, one record.
-      await vi.advanceTimersByTimeAsync(1_000);
-      await coordinator.whenIdle();
-      expect(calls.map((call) => call.key)).toEqual([
-        storageKeys.sessionEvents("test-agent", "s1", first.index),
-        storageKeys.session("test-agent", "s1"),
-      ]);
-      expect((calls[0]?.value as unknown as SessionEvent[]).length).toBe(4);
-      expect((calls[1]?.value as unknown as SessionRecord).turnCount).toBe(2);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it("close flushes buffered state with reason shutdown", async () => {
-    const { coordinator, calls } = makeCoordinator();
-    coordinator.event(makeEvent("s1", "message.received"));
-    coordinator.sessionRecord(makeRecord("s1", 1));
-    await coordinator.close();
-
-    expect(calls.length).toBe(2);
-    expect(calls.every((call) => call.ctx.reason === "shutdown")).toBe(true);
-    // Writes after close are ignored.
-    emit(coordinator, makeEvent("s1", "turn.completed"));
-    await coordinator.whenIdle();
-    expect(calls.length).toBe(2);
-  });
-
-  it("serializes writes and survives a throwing sink", async () => {
-    const order: string[] = [];
-    const { coordinator, calls } = makeCoordinator({
-      put: async (key) => {
-        order.push(`start ${key}`);
-        if (order.length === 1) {
-          await new Promise((resolve) => setTimeout(resolve, 5));
-          order.push(`end ${key}`);
-          throw new Error("sink down");
-        }
-        order.push(`end ${key}`);
-      },
-    });
-    const first = makeEvent("s1", "turn.completed");
-    emit(coordinator, first);
-    emit(coordinator, makeEvent("s2", "turn.completed"));
-    await coordinator.whenIdle();
-
-    // Serialized (no interleaving), and the throw dropped only its write.
-    expect(order).toEqual([
-      `start ${storageKeys.sessionEvents("test-agent", "s1", first.index)}`,
-      `end ${storageKeys.sessionEvents("test-agent", "s1", first.index)}`,
-      `start ${calls[1]?.key}`,
-      `end ${calls[1]?.key}`,
-    ]);
-    expect(calls).toHaveLength(2);
-  });
-
-  it("mirrors reminders onto the sink and lists them back", async () => {
-    const { coordinator, store } = makeCoordinator();
-    const now = new Date().toISOString();
-    const record: ReminderRecord = {
-      version: 1,
-      id: "rem_1",
-      purpose: "watch",
-      channelId: "drive",
-      continuationToken: "tok",
-      scheduleKind: "every",
-      scheduleValue: "30m",
-      intervalMs: 30 * 60_000,
-      prompt: "check",
-      hasRunHandler: false,
-      hasUntilFn: false,
-      busyPolicy: "skipIfBusy",
-      status: "armed",
-      fireCount: 0,
-      nextFireAtMs: Date.now() + 60_000,
-      createdAt: now,
-      updatedAt: now,
-    };
-    coordinator.reminder(record);
-    await coordinator.whenIdle();
-    expect(store.get(storageKeys.reminder("test-agent", "rem_1"))).toEqual(
-      record
-    );
-    await expect(coordinator.listReminders()).resolves.toEqual([record]);
-
-    store.set(storageKeys.reminder("test-agent", "garbage"), {
-      not: "a reminder",
-    });
-    await expect(coordinator.listReminders()).resolves.toEqual([record]);
-  });
-
-  it("routes eval runs through the dedicated evals table", async () => {
-    const table = new Map<string, EvalRunSnapshot>();
-    const contexts: StorageContext[] = [];
-    const coordinator = new StorageCoordinator({
-      definition: defineStorage({
-        put: () => {},
-        evals: {
-          put: (run, ctx) => {
-            contexts.push(ctx);
-            table.set(run.runId, run);
-          },
-          delete: (runId) => {
-            table.delete(runId);
-          },
-          list: () => [...table.values()],
-        },
-      }),
-      agentName: "test-agent",
-      projectRoot: "/tmp/test-agent",
-      logger: () => {},
-    });
-
-    const storage = coordinator.evalRuns();
-    expect(storage).toBeDefined();
-    const run = { runId: "run-1", status: "running" } as EvalRunSnapshot;
-    storage!.save(run);
-    // Mutations after enqueue must not leak into the delivered snapshot.
-    run.status = "completed";
-    await coordinator.whenIdle();
-    expect(table.get("run-1")?.status).toBe("running");
-    expect(contexts[0]).toMatchObject({
-      agentName: "test-agent",
-      reason: "policy",
-    });
-    await expect(storage!.list()).resolves.toHaveLength(1);
-
-    storage!.delete("run-1");
-    await coordinator.whenIdle();
-    expect(table.has("run-1")).toBe(false);
-  });
-
-  it("routes A/B samples and the throttled snapshot through the abs table", async () => {
-    const samples: ABMetricSample[] = [];
-    let storedSnapshot: ABSnapshot | undefined;
-    let snapshotWrites = 0;
-    const coordinator = new StorageCoordinator({
-      definition: defineStorage({
-        put: () => {},
-        abs: {
-          putSample: (sample) => {
-            samples.push(sample);
-          },
-          putSnapshot: (snapshot) => {
-            snapshotWrites += 1;
-            storedSnapshot = snapshot;
-          },
-          getSnapshot: () => storedSnapshot,
-        },
-      }),
-      agentName: "test-agent",
-      projectRoot: "/tmp/test-agent",
-      logger: () => {},
-    });
-
-    const sample = {
-      experiment: "exp",
-      variant: "a",
-      sessionId: "s1",
-      channelId: "http",
-      metrics: {},
-      reason: "turn.completed",
-      at: "2026-07-15T00:00:00.000Z",
-    } as unknown as ABMetricSample;
-    coordinator.abSample(sample);
-    await coordinator.whenIdle();
-    expect(samples).toEqual([sample]);
-
-    const snapshot = (id: string) =>
-      ({
-        experiments: [],
-        sessions: [],
-        config: { id },
-      }) as unknown as ABSnapshot;
-    coordinator.abSnapshot(snapshot("first"));
-    coordinator.abSnapshot(snapshot("suppressed"));
-    await coordinator.whenIdle();
-    expect(snapshotWrites).toBe(1);
-    await expect(coordinator.getLatestAbSnapshot()).resolves.toEqual(
-      snapshot("first")
-    );
-  });
-
-  it("treats missing evals/abs tables as memory-only", async () => {
-    const { coordinator } = makeCoordinator();
-    expect(coordinator.evalRuns()).toBeUndefined();
-    // No abs table: sample/snapshot writes are dropped, reads are absent.
-    coordinator.abSample({} as ABMetricSample);
-    coordinator.abSnapshot({} as ABSnapshot);
-    await coordinator.whenIdle();
-    await expect(coordinator.getLatestAbSnapshot()).resolves.toBeUndefined();
-  });
-
-  it("reads empty state from a write-only sink", async () => {
-    const definition = defineStorage({ put: () => {} });
-    const coordinator = new StorageCoordinator({
-      definition,
-      agentName: "test-agent",
-      projectRoot: "/tmp/test-agent",
-      logger: () => {},
-    });
-    expect(coordinator.canBulkRestore).toBe(false);
-    expect(coordinator.supportsAuthorKv).toBe(false);
-    await expect(coordinator.listSessions()).resolves.toEqual([]);
-    await expect(coordinator.listSessionEvents("s1")).resolves.toEqual([]);
-    await expect(
-      coordinator.getSessionByContinuation("http", "tok")
-    ).resolves.toBeUndefined();
-    await expect(coordinator.getLatestAbSnapshot()).resolves.toBeUndefined();
-  });
-
-  it("awaits author kv get/put/delete under storageKeys.kv", async () => {
-    const store = new Map<string, unknown>();
-    const coordinator = new StorageCoordinator({
-      definition: defineStorage({
-        put: (key, value) => {
-          store.set(key, value);
-        },
-        get: (key) => store.get(key) as never,
-        delete: (key) => {
-          store.delete(key);
-        },
-      }),
-      agentName: "test-agent",
-      projectRoot: "/tmp/test-agent",
-      logger: () => {},
-    });
-    expect(coordinator.supportsAuthorKv).toBe(true);
-    await coordinator.kvPut("alert-memory/1", { ok: true });
-    expect(store.get(storageKeys.kv("test-agent", "alert-memory/1"))).toEqual({
-      ok: true,
-    });
-    await expect(coordinator.kvGet("alert-memory/1")).resolves.toEqual({
-      ok: true,
-    });
-    await coordinator.kvPut("alert-memory/null", null);
-    await expect(coordinator.kvGet("alert-memory/null")).resolves.toBeNull();
-    await coordinator.kvDelete("alert-memory/1");
-    await expect(coordinator.kvGet("alert-memory/1")).resolves.toBeUndefined();
-  });
-});