@desplega.ai/agent-swarm 1.162.0 → 1.164.0

package/src/tests/memory-http-access.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Who may list and delete memories over HTTP (`POST /api/memory/list`,
+ * `DELETE /api/memory/{id}`).
+ *
+ * Drives the real `handleMemory` handler against the real SQLite store behind
+ * the same auth resolution `handleCore` performs, so each case presents a real
+ * credential: the shared key, the shared key with `X-Agent-ID` (what the script
+ * SDK's `memory_delete` sends), an `aseph_` agent session token, or an `aswt_`
+ * user token.
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import { closeDb, createAgent, createUser, initDb } from "../be/db";
+import { getMemoryStore } from "../be/memory";
+import { type IdentityActor, mintSessionToken, mintToken } from "../be/users";
+import { resolveHttpRequestAuth } from "../http/auth";
+import { handleMemory } from "../http/memory";
+import { setRequestAuth } from "../utils/request-auth-context";
+import { listenOnFreePort } from "./test-net";
+
+const TEST_DB_PATH = "./test-memory-http-access.sqlite";
+const API_KEY = "memory-http-access-test-key";
+const ACTOR: IdentityActor = { kind: "operator", id: "memory-http-access-test" };
+
+let server: Server;
+let baseUrl = "";
+let workerA = "";
+let workerB = "";
+let leadId = "";
+let workerASession = "";
+let userToken = "";
+
+function createAuthedServer(): Server {
+  return createServer(async (req, res) => {
+    const auth = await resolveHttpRequestAuth(req, API_KEY);
+    if (!auth) {
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Unauthorized" }));
+      return;
+    }
+    setRequestAuth(req, auth);
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const raw = req.headers["x-agent-id"];
+    const agentIdHeader = Array.isArray(raw) ? raw[0] : raw;
+    const handled = await handleMemory(
+      req,
+      res,
+      url.pathname.split("/").filter(Boolean),
+      agentIdHeader,
+    );
+    if (!handled) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found" }));
+    }
+  });
+}
+
+const operator = () => ({ Authorization: `Bearer ${API_KEY}` });
+const asAgent = (agentId: string) => ({ ...operator(), "X-Agent-ID": agentId });
+const bearer = (token: string) => ({ Authorization: `Bearer ${token}` });
+
+async function remember(agentId: string, scope: "agent" | "swarm", name: string) {
+  return getMemoryStore().store({
+    agentId,
+    scope,
+    name,
+    content: `${name} body`,
+    source: "manual",
+  });
+}
+
+async function del(id: string, headers: Record<string, string>) {
+  const res = await fetch(`${baseUrl}/api/memory/${id}`, { method: "DELETE", headers });
+  return res.status;
+}
+
+async function list(headers: Record<string, string>, body: Record<string, unknown> = {}) {
+  const res = await fetch(`${baseUrl}/api/memory/list`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify({ limit: 100, ...body }),
+  });
+  const json = (await res.json()) as {
+    results: { id: string; agentId: string | null; scope: string }[];
+    total: number;
+  };
+  return { status: res.status, ...json };
+}
+
+async function exists(id: string) {
+  return (await getMemoryStore().peek(id)) !== null;
+}
+
+beforeAll(async () => {
+  try {
+    await unlink(TEST_DB_PATH);
+  } catch {}
+  initDb(TEST_DB_PATH);
+
+  workerA = crypto.randomUUID();
+  workerB = crypto.randomUUID();
+  leadId = crypto.randomUUID();
+  await createAgent({ id: workerA, name: "memory-worker-a", isLead: false, status: "idle" });
+  await createAgent({ id: workerB, name: "memory-worker-b", isLead: false, status: "idle" });
+  await createAgent({ id: leadId, name: "memory-lead", isLead: true, status: "idle" });
+
+  workerASession = (await mintSessionToken(workerA, crypto.randomUUID(), 60_000)).plaintext;
+  const user = await createUser({ name: "Memory admin" });
+  userToken = (await mintToken(user.id, "memory-admin", ACTOR)).plaintext;
+
+  server = createAuthedServer();
+  const port = await listenOnFreePort(server);
+  baseUrl = `http://127.0.0.1:${port}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+});
+
+describe("DELETE /api/memory/{id}", () => {
+  test("a worker cannot delete another agent's memory", async () => {
+    const memory = await remember(workerB, "agent", "b-private");
+    expect(await del(memory.id, asAgent(workerA))).toBe(403);
+    expect(await exists(memory.id)).toBe(true);
+  });
+
+  test("an aseph_ session token is held to the same rule", async () => {
+    const memory = await remember(workerB, "agent", "b-private-session");
+    expect(await del(memory.id, bearer(workerASession))).toBe(403);
+    expect(await exists(memory.id)).toBe(true);
+  });
+
+  test("a worker cannot delete a swarm-scope memory, even one it wrote", async () => {
+    const theirs = await remember(workerB, "swarm", "b-swarm");
+    const own = await remember(workerA, "swarm", "a-swarm");
+    expect(await del(theirs.id, asAgent(workerA))).toBe(403);
+    expect(await del(own.id, asAgent(workerA))).toBe(403);
+    expect(await exists(theirs.id)).toBe(true);
+    expect(await exists(own.id)).toBe(true);
+  });
+
+  test("a worker deletes its own agent-scope memory", async () => {
+    const memory = await remember(workerA, "agent", "a-private");
+    expect(await del(memory.id, asAgent(workerA))).toBe(200);
+    expect(await exists(memory.id)).toBe(false);
+  });
+
+  test("the lead deletes a swarm-scope memory but not another agent's agent-scope memory", async () => {
+    const swarm = await remember(workerB, "swarm", "b-swarm-for-lead");
+    const priv = await remember(workerB, "agent", "b-private-for-lead");
+    expect(await del(swarm.id, asAgent(leadId))).toBe(200);
+    expect(await del(priv.id, asAgent(leadId))).toBe(403);
+    expect(await exists(swarm.id)).toBe(false);
+    expect(await exists(priv.id)).toBe(true);
+  });
+
+  test("the operator key and a user token delete any memory", async () => {
+    const one = await remember(workerB, "agent", "b-private-for-operator");
+    const two = await remember(workerB, "swarm", "b-swarm-for-user");
+    expect(await del(one.id, operator())).toBe(200);
+    expect(await del(two.id, bearer(userToken))).toBe(200);
+    expect(await exists(one.id)).toBe(false);
+    expect(await exists(two.id)).toBe(false);
+  });
+
+  test("a missing memory is a 404 for every caller", async () => {
+    expect(await del(crypto.randomUUID(), asAgent(workerA))).toBe(404);
+    expect(await del(crypto.randomUUID(), operator())).toBe(404);
+  });
+});
+
+describe("POST /api/memory/list", () => {
+  let aPrivate = "";
+  let bPrivate = "";
+  let bSwarm = "";
+
+  beforeAll(async () => {
+    aPrivate = (await remember(workerA, "agent", "list-a-private")).id;
+    bPrivate = (await remember(workerB, "agent", "list-b-private")).id;
+    bSwarm = (await remember(workerB, "swarm", "list-b-swarm")).id;
+  });
+
+  test("a worker sees its own rows and swarm rows, never another agent's private rows", async () => {
+    const res = await list(asAgent(workerA));
+    expect(res.status).toBe(200);
+    const ids = res.results.map((r) => r.id);
+    expect(ids).toContain(aPrivate);
+    expect(ids).toContain(bSwarm);
+    expect(ids).not.toContain(bPrivate);
+    expect(res.results.every((r) => r.agentId === workerA || r.scope === "swarm")).toBe(true);
+    expect(res.total).toBe(res.results.length);
+  });
+
+  test("filtering a worker's list by another agent returns only that agent's swarm rows", async () => {
+    const res = await list(asAgent(workerA), { agentId: workerB });
+    const ids = res.results.map((r) => r.id);
+    expect(ids).toContain(bSwarm);
+    expect(ids).not.toContain(bPrivate);
+  });
+
+  test("scope=agent for a worker is its own private rows only", async () => {
+    const res = await list(bearer(workerASession), { scope: "agent" });
+    const ids = res.results.map((r) => r.id);
+    expect(ids).toContain(aPrivate);
+    expect(ids).not.toContain(bPrivate);
+  });
+
+  test("the operator key, a user token and the lead see every agent's rows", async () => {
+    for (const headers of [operator(), bearer(userToken), asAgent(leadId)]) {
+      const ids = (await list(headers)).results.map((r) => r.id);
+      expect(ids).toEqual(expect.arrayContaining([aPrivate, bPrivate, bSwarm]));
+    }
+  });
+});

package/src/tests/memory-keys-endpoint.test.ts

@@ -0,0 +1,406 @@
+/**
+ * GET /api/memory/keys, GET /api/memory/chunks and the key/updatedAt/rating
+ * fields on POST /api/memory/list — the dashboard memory browser's reads.
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Readable } from "node:stream";
+import { closeDb, createAgent, getDbClient, initDb } from "../be/db";
+import { checkChunkIntegrity } from "../be/memory/key-browser";
+import { handleMemory } from "../http/memory";
+import { getPathSegments } from "../http/utils";
+import { setRequestAuth } from "../utils/request-auth-context";
+
+const TEST_DB_PATH = "./test-memory-keys-endpoint.sqlite";
+
+const AGENT_A = "aaaa0000-0000-4000-8000-00000000ke01";
+const AGENT_B = "aaaa0000-0000-4000-8000-00000000ke02";
+
+const LITMUS_KEY = "/longterm/facts/agenticos/litmus-check-allowlists";
+const SIGTERM_KEY = "/longterm/facts/swarm-deploy/worker-sigterm-handoff-vs-api-drain";
+const PERSON_KEY = "/longterm/entities/people/taras";
+
+const IDS = {
+  litmus0: "11110000-0000-4000-8000-000000000001",
+  litmus1: "11110000-0000-4000-8000-000000000002",
+  sigterm0: "11110000-0000-4000-8000-000000000003",
+  sigterm1: "11110000-0000-4000-8000-000000000004",
+  personA: "11110000-0000-4000-8000-000000000005",
+  personB: "11110000-0000-4000-8000-000000000006",
+  outside: "11110000-0000-4000-8000-000000000007",
+  unkeyed: "11110000-0000-4000-8000-000000000008",
+};
+
+async function insertMemory(row: {
+  id: string;
+  key: string | null;
+  name: string;
+  content: string;
+  scope?: "agent" | "swarm";
+  agentId?: string | null;
+  chunkIndex?: number;
+  totalChunks?: number;
+  accessCount?: number;
+  alpha?: number;
+  beta?: number;
+  createdAt?: string;
+  updatedAt?: string | null;
+}) {
+  const created = row.createdAt ?? "2026-10-01T00:00:00.000Z";
+  await getDbClient().run(
+    `INSERT INTO agent_memory (id, agentId, scope, key, name, content, source, chunkIndex,
+       totalChunks, tags, createdAt, updatedAt, accessedAt, accessCount, alpha, beta)
+     VALUES (?, ?, ?, ?, ?, ?, 'manual', ?, ?, '[]', ?, ?, ?, ?, ?, ?)`,
+    [
+      row.id,
+      row.agentId ?? null,
+      row.scope ?? "swarm",
+      row.key,
+      row.name,
+      row.content,
+      row.chunkIndex ?? 0,
+      row.totalChunks ?? 1,
+      created,
+      row.updatedAt ?? null,
+      created,
+      row.accessCount ?? 0,
+      row.alpha ?? 1,
+      row.beta ?? 1,
+    ],
+  );
+}
+
+function fakeReqRes(method: string, path: string, body?: unknown) {
+  const req = Readable.from(body === undefined ? [] : [JSON.stringify(body)]) as Readable &
+    Partial<IncomingMessage>;
+  req.method = method;
+  req.url = path;
+  req.headers = body === undefined ? {} : { "content-type": "application/json" };
+  setRequestAuth(req as IncomingMessage, { kind: "operator", fingerprint: "memory-keys-test" });
+
+  const captured = { status: 0, body: "" };
+  const res = {
+    writeHead(status: number) {
+      captured.status = status;
+      return this;
+    },
+    setHeader() {
+      return this;
+    },
+    end(chunk?: string) {
+      if (chunk) captured.body = chunk;
+      return this;
+    },
+  } as unknown as ServerResponse;
+  return { req: req as IncomingMessage, res, captured };
+}
+
+async function call(method: string, path: string, body?: unknown, agentId?: string) {
+  const { req, res, captured } = fakeReqRes(method, path, body);
+  const handled = await handleMemory(req, res, getPathSegments(path), agentId);
+  expect(handled).toBe(true);
+  return { status: captured.status, body: captured.body ? JSON.parse(captured.body) : null };
+}
+
+describe("memory browser endpoints", () => {
+  beforeAll(async () => {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {}
+    }
+    initDb(TEST_DB_PATH);
+    for (const id of [AGENT_A, AGENT_B]) {
+      await createAgent({ id, name: `keys-${id.slice(-4)}`, isLead: false, status: "idle" });
+    }
+
+    // Complete 2-chunk memory; names differ across chunks, as in production.
+    await insertMemory({
+      id: IDS.litmus1,
+      key: LITMUS_KEY,
+      name: "litmus allowlists (part 2)",
+      content: "B".repeat(10),
+      chunkIndex: 1,
+      totalChunks: 2,
+      accessCount: 2,
+      alpha: 1,
+      beta: 2,
+      updatedAt: "2026-10-03T00:00:00.000Z",
+    });
+    await insertMemory({
+      id: IDS.litmus0,
+      key: LITMUS_KEY,
+      name: "litmus allowlists",
+      content: "A".repeat(7),
+      chunkIndex: 0,
+      totalChunks: 2,
+      accessCount: 3,
+      alpha: 3,
+      beta: 1,
+    });
+    // Stale chunk 0 says 1 chunk; orphan chunk 1 says 2.
+    await insertMemory({
+      id: IDS.sigterm0,
+      key: SIGTERM_KEY,
+      name: "sigterm handoff",
+      content: "new single chunk",
+      chunkIndex: 0,
+      totalChunks: 1,
+    });
+    await insertMemory({
+      id: IDS.sigterm1,
+      key: SIGTERM_KEY,
+      name: "sigterm handoff (old tail)",
+      content: "orphan tail",
+      chunkIndex: 1,
+      totalChunks: 2,
+    });
+    // Same key, agent scope, two owners: two documents.
+    await insertMemory({
+      id: IDS.personA,
+      key: PERSON_KEY,
+      name: "person A",
+      content: "a",
+      scope: "agent",
+      agentId: AGENT_A,
+    });
+    await insertMemory({
+      id: IDS.personB,
+      key: PERSON_KEY,
+      name: "person B",
+      content: "b",
+      scope: "agent",
+      agentId: AGENT_B,
+    });
+    await insertMemory({ id: IDS.outside, key: "/notes/x", name: "outside", content: "x" });
+    await insertMemory({ id: IDS.unkeyed, key: null, name: "unkeyed", content: "plain" });
+
+    await getDbClient().run(
+      `INSERT INTO memory_rating (id, memoryId, taskId, source, signal, weight, reasoning, createdAt)
+       VALUES (?, ?, NULL, 'llm', 1, 0.5, NULL, ?), (?, ?, NULL, 'llm', -1, 0.5, NULL, ?)`,
+      [
+        crypto.randomUUID(),
+        IDS.litmus0,
+        "2026-10-02T00:00:00.000Z",
+        crypto.randomUUID(),
+        IDS.litmus1,
+        "2026-10-02T00:00:00.000Z",
+      ],
+    );
+  });
+
+  afterAll(async () => {
+    closeDb();
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {}
+    }
+  });
+
+  describe("GET /api/memory/keys", () => {
+    test("groups chunk rows into one row per document under /longterm/ by default", async () => {
+      const { status, body } = await call("GET", "/api/memory/keys");
+      expect(status).toBe(200);
+      expect(body.prefix).toBe("/longterm/");
+      expect(body.truncated).toBe(false);
+      const keys = body.keys.map((k: { key: string; agentId: string | null }) => k.key);
+      expect(keys).toEqual([PERSON_KEY, PERSON_KEY, LITMUS_KEY, SIGTERM_KEY]);
+    });
+
+    test("aggregates usage, tokens, rating and dates over chunks", async () => {
+      const { body } = await call("GET", "/api/memory/keys");
+      const litmus = body.keys.find((k: { key: string }) => k.key === LITMUS_KEY);
+      expect(litmus).toMatchObject({
+        memoryId: IDS.litmus0,
+        name: "litmus allowlists",
+        scope: "swarm",
+        agentId: null,
+        chunkRows: 2,
+        totalChunks: 2,
+        complete: true,
+        chars: 17,
+        estTokens: 5,
+        accessCount: 5,
+        alpha: 4,
+        beta: 3,
+        usefulRatings: 1,
+        notUsefulRatings: 1,
+        updatedAt: "2026-10-03T00:00:00.000Z",
+      });
+      expect(litmus.rating).toBeCloseTo(4 / 7, 6);
+    });
+
+    test("flags an orphan chunk as incomplete", async () => {
+      const { body } = await call("GET", "/api/memory/keys");
+      const sigterm = body.keys.find((k: { key: string }) => k.key === SIGTERM_KEY);
+      expect(sigterm).toMatchObject({ chunkRows: 2, totalChunks: 2, complete: false });
+    });
+
+    test("keeps agent-scope documents from different owners apart", async () => {
+      const { body } = await call("GET", "/api/memory/keys?prefix=/longterm/entities/");
+      expect(body.keys.map((k: { agentId: string }) => k.agentId).sort()).toEqual(
+        [AGENT_A, AGENT_B].sort(),
+      );
+    });
+
+    test("prefix is literal and limit truncates", async () => {
+      const none = await call("GET", "/api/memory/keys?prefix=/longterm/%25");
+      expect(none.body.keys).toEqual([]);
+      const one = await call("GET", "/api/memory/keys?limit=1");
+      expect(one.body.keys).toHaveLength(1);
+      expect(one.body.truncated).toBe(true);
+    });
+  });
+
+  describe("GET /api/memory/chunks", () => {
+    test("returns every chunk of a complete memory in chunkIndex order", async () => {
+      const { status, body } = await call("GET", `/api/memory/chunks?memoryId=${IDS.litmus1}`);
+      expect(status).toBe(200);
+      expect(body.key).toBe(LITMUS_KEY);
+      expect(body.chunks.map((c: { id: string }) => c.id)).toEqual([IDS.litmus0, IDS.litmus1]);
+      expect(body.estTokens).toBe(5);
+      expect(body.integrity.ok).toBe(true);
+      expect(body.integrity.issues).toEqual([]);
+    });
+
+    test("reports conflicting chunk counts for the orphan chunk", async () => {
+      const { body } = await call(
+        "GET",
+        `/api/memory/chunks?key=${encodeURIComponent(SIGTERM_KEY)}&scope=swarm&agentId=`,
+      );
+      expect(body.chunks.map((c: { id: string }) => c.id)).toEqual([IDS.sigterm0, IDS.sigterm1]);
+      expect(body.integrity).toMatchObject({
+        ok: false,
+        expectedChunks: 2,
+        conflictingTotals: [1, 2],
+        missingIndexes: [],
+        duplicateIndexes: [],
+      });
+      expect(body.integrity.issues[0]).toContain("disagree");
+    });
+
+    test("scopes a key lookup to its owner", async () => {
+      const { body } = await call(
+        "GET",
+        `/api/memory/chunks?key=${encodeURIComponent(PERSON_KEY)}&scope=agent&agentId=${AGENT_B}`,
+      );
+      expect(body.chunks.map((c: { id: string }) => c.id)).toEqual([IDS.personB]);
+    });
+
+    test("an unkeyed memory is its own document", async () => {
+      const { body } = await call("GET", `/api/memory/chunks?memoryId=${IDS.unkeyed}`);
+      expect(body.key).toBeNull();
+      expect(body.chunks).toHaveLength(1);
+      expect(body.integrity.ok).toBe(true);
+    });
+
+    test("does not count as an access", async () => {
+      await call("GET", `/api/memory/chunks?memoryId=${IDS.litmus0}`);
+      const row = await getDbClient().get<{ accessCount: number }>(
+        "SELECT accessCount FROM agent_memory WHERE id = ?",
+        [IDS.litmus0],
+      );
+      expect(row?.accessCount).toBe(3);
+    });
+
+    test("404 for an unknown memory, 400 without memoryId or key", async () => {
+      const missing = await call(
+        "GET",
+        "/api/memory/chunks?memoryId=99990000-0000-4000-8000-000000000000",
+      );
+      expect(missing.status).toBe(404);
+      const bad = await call("GET", "/api/memory/chunks");
+      expect(bad.status).toBe(400);
+    });
+  });
+
+  describe("agent viewer", () => {
+    test("keys show only the agent's own rows plus swarm-scope rows", async () => {
+      const { body } = await call("GET", "/api/memory/keys", undefined, AGENT_A);
+      const docs = body.keys.map((k: { key: string; agentId: string | null }) => [
+        k.key,
+        k.agentId,
+      ]);
+      expect(docs).toEqual([
+        [PERSON_KEY, AGENT_A],
+        [LITMUS_KEY, null],
+        [SIGTERM_KEY, null],
+      ]);
+    });
+
+    test("another agent's agent-scope chunks read as not found", async () => {
+      const hidden = await call(
+        "GET",
+        `/api/memory/chunks?memoryId=${IDS.personB}`,
+        undefined,
+        AGENT_A,
+      );
+      expect(hidden.status).toBe(404);
+      const own = await call(
+        "GET",
+        `/api/memory/chunks?memoryId=${IDS.personA}`,
+        undefined,
+        AGENT_A,
+      );
+      expect(own.status).toBe(200);
+      const swarm = await call(
+        "GET",
+        `/api/memory/chunks?memoryId=${IDS.litmus0}`,
+        undefined,
+        AGENT_A,
+      );
+      expect(swarm.status).toBe(200);
+    });
+
+    test("a key-only lookup never returns another owner's rows", async () => {
+      const path = `/api/memory/chunks?key=${encodeURIComponent(PERSON_KEY)}`;
+      const asB = await call("GET", path, undefined, AGENT_B);
+      expect(asB.status).toBe(200);
+      expect(asB.body.chunks.map((c: { id: string }) => c.id)).toEqual([IDS.personB]);
+      const asA = await call("GET", path, undefined, AGENT_A);
+      expect(asA.body.chunks.map((c: { id: string }) => c.id)).toEqual([IDS.personA]);
+    });
+
+    test("an operator key-only lookup returns one document, not every owner's rows", async () => {
+      const { body } = await call(
+        "GET",
+        `/api/memory/chunks?key=${encodeURIComponent(PERSON_KEY)}`,
+      );
+      expect(body.chunks).toHaveLength(1);
+      expect(body.chunks[0].agentId).toBe(body.agentId);
+    });
+  });
+
+  describe("POST /api/memory/list", () => {
+    test("includes key, updatedAt and rating", async () => {
+      const { status, body } = await call("POST", "/api/memory/list", { limit: 100 });
+      expect(status).toBe(200);
+      const litmus1 = body.results.find((r: { id: string }) => r.id === IDS.litmus1);
+      expect(litmus1).toMatchObject({ key: LITMUS_KEY, updatedAt: "2026-10-03T00:00:00.000Z" });
+      expect(litmus1.rating).toBeCloseTo(1 / 3, 6);
+      const unkeyed = body.results.find((r: { id: string }) => r.id === IDS.unkeyed);
+      expect(unkeyed).toMatchObject({ key: null, updatedAt: null, rating: 0.5 });
+    });
+  });
+});
+
+describe("checkChunkIntegrity", () => {
+  test("missing, duplicate and out-of-range chunks", () => {
+    const result = checkChunkIntegrity([
+      { id: "a", chunkIndex: 0, totalChunks: 3 },
+      { id: "b", chunkIndex: 0, totalChunks: 3 },
+      { id: "c", chunkIndex: 3, totalChunks: 3 },
+    ]);
+    expect(result.ok).toBe(false);
+    expect(result.missingIndexes).toEqual([1, 2]);
+    expect(result.duplicateIndexes).toEqual([0]);
+    expect(result.outOfRangeIds).toEqual(["c"]);
+    expect(result.issues).toHaveLength(3);
+  });
+
+  test("a single complete row is fine", () => {
+    expect(checkChunkIntegrity([{ id: "a", chunkIndex: 0, totalChunks: 1 }]).ok).toBe(true);
+  });
+});