Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

59.8 KB
Raw Blame
import { readJson, writeJson } from "./support/json.js";
import { workflowFixture } from "./support/workflow-fixture.js";
import { emptyNeighborhoodReviewer } from "./support/deduplication.js";
import { readFile } from "node:fs/promises";
import { createHash } from "node:crypto";
import { join } from "node:path";
import { expect, test, mock } from "bun:test";
import Ajv2020 from "ajv/dist/2020.js";
import type { Finding, FindingsDocument, ScanManifest } from "../src/models.js";
import { deriveFindingIdentity } from "../src/contract.js";
import type {
  FindingNeighborhood,
  FindingSourceSnapshot,
} from "../src/finding-retrieval.js";
import type { CodexReview } from "../src/deduplication/codex-review.js";
import {
  contradictionFreeSubgroups,
  FindingDeduplicator,
} from "../src/deduplication/deduplication.js";
import {
  CodexDeduplicationReviewer,
  CodexGroupingReviewer,
  pairKey,
  screeningPairSlot,
  validateReview,
  validateScreening,
  type DeduplicationReviewer,
  type DuplicateDecision,
  type ScreeningResult,
} from "../src/deduplication/deduplication-reviewer.js";
import { CodexSecurityError, DeduplicationReviewError } from "../src/errors.js";
import { FindingsClient } from "../src/findings-client.js";
import { deduplicateScanDirectory } from "../src/index.js";
import {
  deduplicateScanDirectoryInternal,
  deduplicateScanInternal,
} from "../src/deduplication/scan.js";
import { PLUGIN_ROOT } from "./plugin-root.js";
import type { JsonObject } from "../src/config.js";
import { fail } from "./support/errors.js";

const document = await readJson<FindingsDocument>(
  join(PLUGIN_ROOT, "examples/legacy-completed-scan/findings.json"),
);
function entry(index: number): Finding {
  return {
    ...structuredClone(document.findings[0]!),
    findingId: `csf_${index.toString(16).padStart(24, "0")}`,
    occurrenceId: `occ_${index.toString(16).padStart(24, "0")}`,
    title: `Synthetic finding ${index}`,
    extensions: {
      originalEvidence: {
        text: `Complete report ${index}`,
        repository: `synthetic-${index}`,
      },
    },
  };
}
function candidates(findings: Finding[], neighbors = findings) {
  return {
    potentialDuplicates: async (id: string) => ({
      finding: findings.find((finding) => finding.findingId === id)!,
      potentialDuplicates: neighbors.filter(
        (finding) => finding.findingId !== id,
      ),
    }),
  };
}

function same(
  findings: readonly Finding[],
): Extract<DuplicateDecision, { decision: "SAME" }> {
  return {
    decision: "SAME",
    rationale: "One existing control corrects every path.",
    canonicalFindingId: findings[0]!.findingId,
    mergedFinding: {
      ...findings[0],
      title: findings.map((finding) => finding.title).join("; "),
      extensions: { ...findings[0]!.extensions, mergedOriginals: findings },
    },
  };
}
const distinct: DuplicateDecision = {
  decision: "DISTINCT",
  rationale: "Independent controls require different corrections.",
};

test("saved-scan pair reviews submit decisions without generating replacement findings", async () => {
  const findings = [entry(1), entry(2)];
  const originals = structuredClone(findings);
  const calls: CodexReview<unknown>[] = [];
  const reviewer = new CodexGroupingReviewer(
    {
      async run<T>(review: CodexReview<T>): Promise<T> {
        calls.push(review);
        const result = {
          decision: "SAME",
          rationale: "One shared control closes both paths.",
        };
        const validateSchema = new Ajv2020({ strict: false }).compile(
          review.schema as object,
        );
        expect(validateSchema(result)).toBe(true);
        expect(
          validateSchema({
            ...result,
            mergedFinding: findings[0],
            canonicalFindingId: findings[0]!.findingId,
          }),
        ).toBe(false);
        return review.validate(result);
      },
    },
    { model: "synthetic-configured-model", model_reasoning_effort: "medium" },
  );
  expect(await reviewer.reviewPair(findings)).toEqual({
    decision: "SAME",
    rationale: "One shared control closes both paths.",
  });
  expect(calls[0]).toMatchObject({
    stage: "pair-review",
    model: "synthetic-configured-model",
    effort: "medium",
  });
  expect(calls[0]!.prompt).toContain(JSON.stringify({ findings }));
  expect(calls[0]!.prompt).not.toContain("actually synthesize");
  expect(findings).toEqual(originals);
  expect(() =>
    validateReview({ decision: "SAME", rationale: "Same control" }, findings),
  ).toThrow();
});

function screening(
  findings: readonly Finding[],
  nominated: ReadonlySet<string>,
): ScreeningResult {
  const decisions = findings.slice(1).map((finding, index) => {
    const pair: [string, string] = [findings[0]!.findingId, finding.findingId];
    return [
      screeningPairSlot(index),
      nominated.has(pairKey(pair))
        ? {
            decision: "SAME" as const,
            rationale: "One existing control corrects every path.",
          }
        : distinct,
    ] as const;
  });
  return {
    // Deliberately reverse insertion order: slot names, not object order, bind pairs.
    decisions: Object.fromEntries(decisions.reverse()),
  };
}

const reviewSame = async (findings: readonly Finding[]) => same(findings);
const screenNominations =
  (nominate: (findings: readonly Finding[]) => ReadonlySet<string>) =>
  async (findings: readonly Finding[]) =>
    screening(findings, nominate(findings));

test.each(["screening", "pair-review"])(
  "%s fills each free slot immediately and preserves serial grouping",
  async (stage) => {
    const entries = [entry(1), entry(2), entry(3), entry(4)];
    const neighbor = entry(5);
    const ids = entries.map((finding) => finding.findingId);
    const nominations = new Set(
      ids.map((id) => pairKey([id, neighbor.findingId])),
    );
    const candidateStore = candidates(entries, [neighbor]);
    const gates = entries.map(() => Promise.withResolvers<void>());
    const started = entries.map(() => Promise.withResolvers<void>());
    const starts: number[] = [];
    const phases: string[] = [];
    let active = 0;
    let peak = 0;
    const hold = async (findings: readonly Finding[]) => {
      const index = ids.indexOf(findings[0]!.findingId);
      starts.push(index);
      peak = Math.max(peak, ++active);
      started[index]!.resolve();
      await gates[index]!.promise;
      active--;
    };
    const reviewer: DeduplicationReviewer = {
      async screen(findings) {
        phases.push("screening");
        if (stage === "screening") await hold(findings);
        return screening(findings, nominations);
      },
      async reviewPair(findings) {
        phases.push("pair-review");
        if (stage === "pair-review") await hold(findings);
        return same(findings);
      },
    };
    const result = new FindingDeduplicator(
      candidateStore,
      reviewer,
      undefined,
      2,
    ).run(ids);
    await Promise.all([started[0]!.promise, started[1]!.promise]);
    expect(starts).toEqual([0, 1]);
    gates[1]!.resolve();
    await started[2]!.promise;
    expect(starts).toEqual([0, 1, 2]);
    gates[2]!.resolve();
    await started[3]!.promise;
    gates[3]!.resolve();
    gates[0]!.resolve();
    const parallel = await result;
    expect(peak).toBe(2);
    expect(phases.filter((phase) => phase === "screening")).toHaveLength(4);
    expect(phases.filter((phase) => phase === "pair-review")).toHaveLength(4);
    expect(parallel).toEqual(
      await new FindingDeduplicator(candidateStore, reviewer, undefined, 1).run(
        ids,
      ),
    );
  },
);

test("ready pairs take free slots before pending screenings and share the concurrency cap", async () => {
  const entries = [entry(1), entry(2), entry(3)];
  const neighbor = entry(4);
  const ids = entries.map((finding) => finding.findingId);
  const nominations = new Set(
    ids.map((id) => pairKey([id, neighbor.findingId])),
  );
  const screeningGates = entries.map(() => Promise.withResolvers<void>());
  const screeningStarts = entries.map(() => Promise.withResolvers<void>());
  const pairGates = entries.map(() => Promise.withResolvers<void>());
  const pairStarts = entries.map(() => Promise.withResolvers<void>());
  const events: string[] = [];
  let active = 0;
  let peak = 0;
  const hold = async (index: number, stage: "screen" | "pair") => {
    events.push(`${stage}:${index}`);
    peak = Math.max(peak, ++active);
    (stage === "screen" ? screeningStarts : pairStarts)[index]!.resolve();
    await (stage === "screen" ? screeningGates : pairGates)[index]!.promise;
    active--;
  };
  const result = new FindingDeduplicator(
    candidates(entries, [neighbor]),
    {
      async screen(findings) {
        await hold(ids.indexOf(findings[0]!.findingId), "screen");
        return screening(findings, nominations);
      },
      async reviewPair(findings) {
        await hold(ids.indexOf(findings[0]!.findingId), "pair");
        return same(findings);
      },
    },
    undefined,
    2,
  ).run(ids);
  try {
    await Promise.all(
      screeningStarts.slice(0, 2).map((start) => start.promise),
    );
    screeningGates[0]!.resolve();
    await pairStarts[0]!.promise;
    expect(events).toEqual(["screen:0", "screen:1", "pair:0"]);
    expect(active).toBe(2);
    pairGates[0]!.resolve();
    await screeningStarts[2]!.promise;
    screeningGates[1]!.resolve();
    await pairStarts[1]!.promise;
    expect(active).toBe(2);
    pairGates[1]!.resolve();
    screeningGates[2]!.resolve();
    await pairStarts[2]!.promise;
    pairGates[2]!.resolve();
    expect((await result).duplicateGroups).toEqual([
      [...ids, neighbor.findingId],
    ]);
    expect(peak).toBe(2);
    expect(events).toEqual([
      "screen:0",
      "screen:1",
      "pair:0",
      "screen:2",
      "pair:1",
      "pair:2",
    ]);
  } finally {
    for (const gate of [...screeningGates, ...pairGates]) gate.resolve();
    await result.catch(() => undefined);
  }
});

test("a pair waits for its delayed reciprocal screening and honors a DISTINCT veto", async () => {
  const entries = [entry(1), entry(2)];
  const ids = entries.map((finding) => finding.findingId);
  const gates = entries.map(() => Promise.withResolvers<void>());
  const started = entries.map(() => Promise.withResolvers<void>());
  const finished = Promise.withResolvers<void>();
  const reviewed: string[] = [];
  const result = new FindingDeduplicator(
    candidates(entries),
    {
      async screen(findings) {
        const index = ids.indexOf(findings[0]!.findingId);
        started[index]!.resolve();
        await gates[index]!.promise;
        if (index === 0) finished.resolve();
        return screening(
          findings,
          index === 0 ? new Set([pairKey(ids)]) : new Set(),
        );
      },
      async reviewPair(findings) {
        reviewed.push(pairKey(findings.map((finding) => finding.findingId)));
        return same(findings);
      },
    },
    undefined,
    2,
  ).run(ids);
  try {
    await Promise.all(started.map((start) => start.promise));
    gates[0]!.resolve();
    await finished.promise;
    await new Promise<void>((resolve) => setImmediate(resolve));
    expect(reviewed).toEqual([]);
    gates[1]!.resolve();
    expect(await result).toEqual({
      uniqueFindingIds: ids,
      duplicateGroups: [],
      deduplicationStatus: "completed",
    });
    expect(reviewed).toEqual([]);
  } finally {
    for (const gate of gates) gate.resolve();
    await result.catch(() => undefined);
  }
});

test("reverse completion preserves pair orientation and the final input-order finding records", async () => {
  const entries = [entry(1), entry(2), entry(3)];
  const ids = entries.map((finding) => finding.findingId);
  const finalA = {
    ...entry(1),
    title: "Final candidate record",
    severity: { ...entry(1).severity, level: "critical" as const },
  };
  const finalB = { ...entry(2), title: "Later anchor record" };
  const neighborhoods = [
    { finding: entries[0]!, potentialDuplicates: [entries[1]!] },
    {
      finding: finalB,
      potentialDuplicates: [
        { ...entries[0]!, title: "Intermediate candidate record" },
      ],
    },
    { finding: entries[2]!, potentialDuplicates: [finalA] },
  ];
  const lookupStarts = entries.map(() => Promise.withResolvers<void>());
  const lookupGates = entries.map(() => Promise.withResolvers<void>());
  const screenStarts = entries.map(() => Promise.withResolvers<void>());
  const screenGates = entries.map(() => Promise.withResolvers<void>());
  const pairStarted = Promise.withResolvers<void>();
  const reviewed: Finding[][] = [];
  const result = new FindingDeduplicator(
    {
      async potentialDuplicates(id) {
        const index = ids.indexOf(id);
        lookupStarts[index]!.resolve();
        await lookupGates[index]!.promise;
        return neighborhoods[index]!;
      },
    },
    {
      async screen(findings) {
        const index = ids.indexOf(findings[0]!.findingId);
        screenStarts[index]!.resolve();
        await screenGates[index]!.promise;
        return screening(findings, new Set([pairKey(ids.slice(0, 2))]));
      },
      async reviewPair(findings) {
        reviewed.push([...findings]);
        pairStarted.resolve();
        return same(findings);
      },
    },
    undefined,
    3,
  ).run(ids);
  try {
    await Promise.all(lookupStarts.map((start) => start.promise));
    for (const gate of [...lookupGates].reverse()) {
      gate.resolve();
      await new Promise<void>((resolve) => setImmediate(resolve));
    }
    await Promise.all(screenStarts.map((start) => start.promise));
    screenGates[1]!.resolve();
    await new Promise<void>((resolve) => setImmediate(resolve));
    expect(reviewed).toEqual([]);
    screenGates[0]!.resolve();
    await pairStarted.promise;
    expect(reviewed).toEqual([[finalB, finalA]]);
    screenGates[2]!.resolve();
    expect(await result).toEqual({
      uniqueFindingIds: [ids[0]!, ids[2]!],
      duplicateGroups: [ids.slice(0, 2)],
      deduplicationStatus: "completed",
    });
  } finally {
    for (const gate of [...lookupGates, ...screenGates]) gate.resolve();
    await result.catch(() => undefined);
  }
});

test.each(["screen", "pair", "cancel"])(
  "%s failure drains mixed active reviews and stops both pending queues",
  async (failureStage) => {
    const entries = [entry(1), entry(2), entry(3)];
    const neighbors = [entry(4), entry(5)];
    const ids = entries.map((finding) => finding.findingId);
    const starts: string[] = [];
    const completed: string[] = [];
    const screenGate = Promise.withResolvers<void>();
    const pairGate = Promise.withResolvers<void>();
    const pairStarted = Promise.withResolvers<void>();
    const controller = new AbortController();
    const failure = new Error("Synthetic mixed-stage failure");
    const result = new FindingDeduplicator(
      candidates(entries, neighbors),
      {
        async screen(findings) {
          const index = ids.indexOf(findings[0]!.findingId);
          starts.push(`screen:${index}`);
          if (index === 1) await screenGate.promise;
          completed.push(`screen:${index}`);
          return screening(
            findings,
            new Set(
              neighbors.map((neighbor) =>
                pairKey([findings[0]!.findingId, neighbor.findingId]),
              ),
            ),
          );
        },
        async reviewPair(findings) {
          starts.push("pair");
          pairStarted.resolve();
          await pairGate.promise;
          completed.push("pair");
          return same(findings);
        },
      },
      controller.signal,
      2,
    ).run(ids);
    const observeSettled = mock((error: unknown) => {
      return error;
    });
    const observed = result.catch(observeSettled);
    try {
      await pairStarted.promise;
      expect(starts).toEqual(["screen:0", "screen:1", "pair"]);
      if (failureStage === "screen") screenGate.reject(failure);
      else if (failureStage === "pair") pairGate.reject(failure);
      else controller.abort(failure);
      await new Promise<void>((resolve) => setImmediate(resolve));
      expect(observeSettled).not.toHaveBeenCalled();
      screenGate.resolve();
      pairGate.resolve();
      expect(await observed).toBe(failure);
      expect(starts).toEqual(["screen:0", "screen:1", "pair"]);
      expect(completed).toContain("screen:0");
      if (failureStage !== "screen") expect(completed).toContain("screen:1");
      if (failureStage !== "pair") expect(completed).toContain("pair");
    } finally {
      screenGate.resolve();
      pairGate.resolve();
      await observed;
    }
  },
);

test("terminal failure drains started reviews without starting queued jobs", async () => {
  const entries = [entry(1), entry(2), entry(3)];
  const gates = entries.map(() => Promise.withResolvers<void>());
  const started = entries.map(() => Promise.withResolvers<void>());
  const calls: string[] = [];
  const failure = new Error("Synthetic review failure");
  const result = new FindingDeduplicator(
    candidates(entries),
    {
      async screen(findings) {
        const index = entries.findIndex(
          (entry) => entry.findingId === findings[0]!.findingId,
        );
        calls.push(findings[0]!.findingId);
        started[index]!.resolve();
        await gates[index]!.promise;
        return screening(findings, new Set());
      },
      reviewPair: async () =>
        fail("Pair review must not start after screening failure"),
    },
    undefined,
    2,
  ).run(entries.map((entry) => entry.findingId));
  const observeSettled = mock((error: unknown) => {
    return error;
  });
  const observed = result.catch(observeSettled);
  await Promise.all([started[0]!.promise, started[1]!.promise]);
  gates[0]!.reject(failure);
  await new Promise<void>((resolve) => setImmediate(resolve));
  expect(observeSettled).not.toHaveBeenCalled();
  gates[1]!.resolve();
  expect(await observed).toBe(failure);
  expect(calls).toEqual(entries.slice(0, 2).map((entry) => entry.findingId));
});

test("SDK rejects invalid concurrency before reading scan artifacts or history", async () => {
  for (const concurrency of [
    0,
    -1,
    1.5,
    NaN,
    Infinity,
    Number.MAX_SAFE_INTEGER + 1,
  ]) {
    const options = { findingsUrl: "http://synthetic.test", concurrency };
    await expect(deduplicateScanInternal("synthetic", options)).rejects.toThrow(
      "concurrency must be a positive safe integer",
    );
    await expect(
      deduplicateScanDirectoryInternal("unused", {
        ...options,
        repository: "unused",
      }),
    ).rejects.toThrow("concurrency must be a positive safe integer");
  }
});

test("reviews nominated pairs once and groups non-conflicting accepted pairs by severity", async () => {
  const entries = [entry(1), entry(2), entry(3), entry(4)];
  entries[1]!.severity.level = "critical";
  const ids = entries.map((finding) => finding.findingId);
  const nominations = new Set([
    pairKey([ids[0]!, ids[1]!]),
    pairKey([ids[1]!, ids[2]!]),
    pairKey([ids[0]!, ids[3]!]),
  ]);
  const phases: string[] = [];
  const reviewedPairs: string[] = [];
  const reviewer: DeduplicationReviewer = {
    async screen(findings) {
      phases.push("screen");
      expect(findings).toHaveLength(4);
      for (const finding of findings)
        expect(finding).toEqual(
          entries.find((entry) => entry.findingId === finding.findingId)!,
        );
      return screening(findings, nominations);
    },
    async reviewPair(findings) {
      phases.push("pair");
      const key = pairKey(findings.map((finding) => finding.findingId));
      reviewedPairs.push(key);
      return findings.some((finding) => finding.findingId === ids[3])
        ? distinct
        : same(findings);
    },
  };
  const service = new FindingDeduplicator(candidates(entries), reviewer);
  expect(await service.run([...ids, ids[0]!])).toEqual({
    uniqueFindingIds: [ids[1]!, ids[2]!, ids[3]!],
    duplicateGroups: [[ids[1]!, ids[0]!]],
    deduplicationStatus: "completed",
  });
  expect(new Set(reviewedPairs)).toEqual(nominations);
  expect(reviewedPairs).toHaveLength(3);
  expect(phases.filter((phase) => phase === "screen")).toHaveLength(4);
  expect(phases.filter((phase) => phase === "pair")).toHaveLength(3);
});

test("groups accepted neighbors transitively without screening them as anchors", async () => {
  const entries = [entry(1), entry(2), entry(3)];
  const ids = entries.map((finding) => finding.findingId);
  const screened: string[] = [];
  const service = new FindingDeduplicator(candidates(entries), {
    async screen(findings) {
      screened.push(findings[0]!.findingId);
      return screening(
        findings,
        new Set([pairKey([ids[0]!, ids[1]!]), pairKey([ids[1]!, ids[2]!])]),
      );
    },
    reviewPair: reviewSame,
  });
  expect(await service.run([ids[1]!])).toEqual({
    uniqueFindingIds: [ids[0]!],
    duplicateGroups: [ids],
    deduplicationStatus: "completed",
  });
  expect(screened).toEqual([ids[1]!]);
});

test("an explicit DISTINCT screening vetoes the same unordered pair", async () => {
  const entries = [entry(1), entry(2)];
  const ids = entries.map((finding) => finding.findingId);
  for (const selected of [ids, [...ids].reverse()]) {
    const reviewPair = mock(reviewSame.bind(undefined, entries));
    const service = new FindingDeduplicator(candidates(entries), {
      screen: screenNominations((findings) =>
        findings[0]!.findingId === ids[0] ? new Set([pairKey(ids)]) : new Set(),
      ),
      reviewPair,
    });
    expect(await service.run(selected)).toEqual({
      uniqueFindingIds: selected,
      duplicateGroups: [],
      deduplicationStatus: "completed",
    });
    expect(reviewPair).toHaveBeenCalledTimes(0);
  }
});

test("does not connect DISTINCT findings through accepted transitive pairs", async () => {
  const entries = [entry(1), entry(2), entry(3)];
  const ids = entries.map((finding) => finding.findingId);
  const nominations = new Set([
    pairKey([ids[0]!, ids[1]!]),
    pairKey([ids[1]!, ids[2]!]),
  ]);
  const reviewedPairs: string[] = [];
  const service = new FindingDeduplicator(candidates(entries), {
    screen: screenNominations(() => nominations),
    async reviewPair(findings) {
      reviewedPairs.push(pairKey(findings.map((finding) => finding.findingId)));
      return same(findings);
    },
  });
  expect(await service.run(ids)).toEqual({
    uniqueFindingIds: [ids[0]!, ids[2]!],
    duplicateGroups: [[ids[0]!, ids[1]!]],
    deduplicationStatus: "completed",
  });
  expect(new Set(reviewedPairs)).toEqual(nominations);
  expect(reviewedPairs).toHaveLength(2);
});

test("does not connect findings through a pair rejected by Sol", async () => {
  const entries = [entry(1), entry(2), entry(3)];
  const ids = entries.map((finding) => finding.findingId);
  const nominations = new Set([
    pairKey([ids[0]!, ids[1]!]),
    pairKey([ids[0]!, ids[2]!]),
    pairKey([ids[1]!, ids[2]!]),
  ]);
  const reviewedPairs: string[] = [];
  const service = new FindingDeduplicator(candidates(entries), {
    screen: screenNominations(() => nominations),
    async reviewPair(findings) {
      const key = pairKey(findings.map((finding) => finding.findingId));
      reviewedPairs.push(key);
      return key === pairKey([ids[0]!, ids[2]!]) ? distinct : same(findings);
    },
  });
  expect(await service.run(ids)).toEqual({
    uniqueFindingIds: [ids[0]!, ids[2]!],
    duplicateGroups: [[ids[0]!, ids[1]!]],
    deduplicationStatus: "completed",
  });
  expect(new Set(reviewedPairs)).toEqual(nominations);
  expect(reviewedPairs).toHaveLength(3);
});

test("prefers the better-supported legal subgroup in a conflicted star", async () => {
  const entries = [entry(1), entry(2), entry(3), entry(4)];
  const ids = entries.map((finding) => finding.findingId);
  const nominations = new Set([
    pairKey([ids[0]!, ids[1]!]),
    pairKey([ids[0]!, ids[2]!]),
    pairKey([ids[0]!, ids[3]!]),
    pairKey([ids[2]!, ids[3]!]),
  ]);
  const neighborIndexes = [[1, 2, 3], [2, 3], [3], []];
  const service = new FindingDeduplicator(
    {
      async potentialDuplicates(findingId) {
        const index = ids.indexOf(findingId);
        return {
          finding: entries[index]!,
          potentialDuplicates: neighborIndexes[index]!.map(
            (neighbor) => entries[neighbor]!,
          ),
        };
      },
    },
    {
      screen: screenNominations(() => nominations),
      reviewPair: reviewSame,
    },
  );
  expect(await service.run(ids)).toEqual({
    uniqueFindingIds: [ids[0]!, ids[1]!],
    duplicateGroups: [[ids[0]!, ids[2]!, ids[3]!]],
    deduplicationStatus: "completed",
  });
});

test("keeps disconnected groups ordered and conflict ties in finding insertion order", async () => {
  const aCenter = entry(30);
  const bCenter = entry(40);
  const aLeft = entry(10);
  const bLeft = entry(20);
  const aRight = entry(50);
  const bRight = entry(60);
  const cleanCenter = entry(80);
  const cleanNeighbor = entry(70);
  const isolated = entry(90);
  const entries = [
    aCenter,
    bCenter,
    aLeft,
    bLeft,
    aRight,
    bRight,
    cleanCenter,
    cleanNeighbor,
    isolated,
  ];
  for (const finding of entries) finding.severity.level = "medium";
  aLeft.severity.level = aRight.severity.level = "critical";
  const nominations = new Set(
    [
      [aCenter, aLeft],
      [aCenter, aRight],
      [bCenter, bLeft],
      [bCenter, bRight],
      [cleanCenter, cleanNeighbor],
    ].map((pair) => pairKey(pair.map((finding) => finding.findingId))),
  );
  const selected = [aCenter, bCenter, aLeft, bLeft, cleanCenter, isolated];
  for (const reverse of [false, true]) {
    const aNeighbors = reverse ? [aRight, aLeft] : [aLeft, aRight];
    const bNeighbors = reverse ? [bRight, bLeft] : [bLeft, bRight];
    const neighborhoods = new Map<string, Finding[]>([
      [
        aCenter.findingId,
        [
          bCenter,
          aNeighbors[0]!,
          bNeighbors[0]!,
          aNeighbors[1]!,
          bNeighbors[1]!,
          cleanCenter,
          cleanNeighbor,
          isolated,
        ],
      ],
      [bCenter.findingId, [bLeft, bRight]],
      [aLeft.findingId, [aRight]],
      [bLeft.findingId, [bRight]],
      [cleanCenter.findingId, [cleanNeighbor]],
    ]);
    const service = new FindingDeduplicator(
      {
        async potentialDuplicates(findingId) {
          return {
            finding: entries.find((entry) => entry.findingId === findingId)!,
            potentialDuplicates: neighborhoods.get(findingId) ?? [],
          };
        },
      },
      {
        screen: screenNominations(() => nominations),
        reviewPair: reviewSame,
      },
    );
    expect(
      await service.run(selected.map((finding) => finding.findingId)),
    ).toEqual({
      uniqueFindingIds: (reverse
        ? [aRight, bCenter, aLeft, bLeft, cleanNeighbor, isolated]
        : [aLeft, bLeft, cleanNeighbor, isolated]
      ).map((finding) => finding.findingId),
      duplicateGroups: [
        [aNeighbors[0]!, aCenter],
        reverse ? [bCenter, bRight] : [bLeft, bCenter],
        [cleanNeighbor, cleanCenter],
      ].map((group) => group.map((finding) => finding.findingId)),
      deduplicationStatus: "completed",
    });
  }
});

test("scales contradiction grouping with conflict neighbors instead of all clusters", () => {
  const count = 200;
  const ids = Array.from(
    { length: count },
    (_value, index) => `finding-${index}`,
  );
  const samePairs: [string, string][] = [];
  for (let left = 0; left < count; left++) {
    for (let right = left + 1; right < Math.min(count, left + 51); right++)
      samePairs.push([ids[left]!, ids[right]!]);
  }
  const metrics = { candidateEvaluations: 0, conflictNeighborChecks: 0 };
  const groups = contradictionFreeSubgroups(
    ids,
    samePairs,
    [[ids[0]!, ids[count - 1]!]],
    undefined,
    metrics,
  );
  expect(groups).toHaveLength(1);
  expect(groups[0]!.size).toBe(count - 1);
  expect(groups[0]!.has(ids[0]!) && groups[0]!.has(ids[count - 1]!)).toBe(
    false,
  );
  expect(metrics.candidateEvaluations).toBeLessThan(count * samePairs.length);
  expect(metrics.conflictNeighborChecks).toBeLessThan(
    metrics.candidateEvaluations * 3,
  );
});

test("matches an import to an existing canonical", async () => {
  const existing = entry(1);
  const imported = entry(2);
  imported.severity.level = "low";
  const ids = [existing.findingId, imported.findingId];
  const service = new FindingDeduplicator(candidates([existing, imported]), {
    screen: screenNominations(() => new Set([pairKey(ids)])),
    reviewPair: reviewSame,
  });
  expect(await service.run([imported.findingId])).toEqual({
    uniqueFindingIds: [existing.findingId],
    duplicateGroups: [ids],
    deduplicationStatus: "completed",
  });
});

test("empty and isolated imports avoid models, while review failures propagate", async () => {
  const first = entry(1);
  const second = entry(2);
  const findings = [first];
  const failure = new CodexSecurityError("Synthetic review failed");
  const reviewer: DeduplicationReviewer = {
    screen: (Promise.reject<never>).bind(Promise, failure),
    reviewPair: (Promise.reject<never>).bind(Promise, failure),
  };
  const service = new FindingDeduplicator(candidates(findings), reviewer);
  expect(await service.run([])).toEqual({
    uniqueFindingIds: [],
    duplicateGroups: [],
    deduplicationStatus: "completed",
  });
  expect((await service.run([first.findingId])).uniqueFindingIds).toEqual([
    first.findingId,
  ]);
  findings.push(second);
  await expect(service.run([first.findingId])).rejects.toBe(failure);
});

test.each(["screening", "pair-review"] as const)(
  "a %s refusal keeps affected pairs separate without stopping other reviews",
  async (stage) => {
    const findings = [entry(1), entry(2), entry(3)];
    const ids = findings.map((finding) => finding.findingId);
    const refusedPair = pairKey([ids[0]!, ids[2]!]);
    const nominations = new Set([
      pairKey(ids.slice(0, 2)),
      pairKey(ids.slice(1)),
      refusedPair,
    ]);
    const failure = new DeduplicationReviewError({
      stage,
      model: stage === "screening" ? "gpt-5.6-luna" : "gpt-5.6-sol",
      category: "refusal",
      attempts: 1,
      reason: "The model refused the deduplication review.",
    });
    const reviewed: string[] = [];
    const result = await new FindingDeduplicator(candidates(findings), {
      async screen(values) {
        if (stage === "screening" && values[0]!.findingId === ids[0])
          throw failure;
        return screening(values, nominations);
      },
      async reviewPair(values) {
        const key = pairKey(values.map((finding) => finding.findingId));
        reviewed.push(key);
        if (stage === "pair-review" && key === refusedPair) throw failure;
        return same(values);
      },
    }).run(ids);

    expect(result.deduplicationStatus).toBe("completed_with_refusals");
    expect(result.refusals).toEqual([
      {
        decision: "NO_DECISION",
        stage,
        model: failure.metadata.model,
        reason: failure.metadata.reason,
        findingIds: stage === "screening" ? ids : [ids[2]!, ids[0]!],
      },
    ]);
    expect(result.duplicateGroups.some((group) => group.length === 2)).toBe(
      true,
    );
    expect(result.uniqueFindingIds).toHaveLength(2);
    // A refused pair must not be reconnected through a third finding.
    expect(
      result.duplicateGroups.some(
        (group) => group.includes(ids[0]!) && group.includes(ids[2]!),
      ),
    ).toBe(false);
    if (stage === "screening") {
      expect(result.uniqueFindingIds).toContain(ids[0]!);
      expect(reviewed).toEqual([pairKey(ids.slice(1))]);
    }
  },
);

test("validates exact screening slots without model-owned finding identity", () => {
  const findings = [entry(1), entry(2), entry(3)];
  const ids = findings.map((finding) => finding.findingId);
  const result = screening(findings, new Set([pairKey([ids[0]!, ids[1]!])]));
  expect(validateScreening(result, findings)).toEqual(result);
  expect(Object.keys(result.decisions)).toEqual(["pair-2", "pair-1"]);
  for (const invalid of [
    {
      decisions: { "pair-1": result.decisions["pair-1"] },
    },
    {
      decisions: {
        ...result.decisions,
        "pair-3": { decision: "DISTINCT", rationale: "Outside assignment." },
      },
    },
    {
      decisions: Object.fromEntries(
        Object.entries(result.decisions).map(([slot, decision]) => [
          slot,
          { ...decision, findingIds: [ids[0], "outside"] },
        ]),
      ),
    },
    {
      decisions: Object.fromEntries(
        Object.entries(result.decisions).map(([slot, decision]) => [
          slot,
          { ...decision, rationale: " " },
        ]),
      ),
    },
    {
      decisions: Object.fromEntries(
        Object.entries(result.decisions).map(([slot, decision]) => [
          slot,
          decision.decision === "SAME"
            ? { ...decision, canonicalFindingId: ids[0] }
            : decision,
        ]),
      ),
    },
  ])
    expect(() => validateScreening(invalid, findings)).toThrow();
});

test("keeps recommendation-only screening independent from complete pair reviews", async () => {
  const findings = [entry(1), entry(2), entry(3)];
  const linkedId = entry(4).findingId;
  findings[0]!.extensions = {
    ...findings[0]!.extensions,
    parent: { id: "external-parent", url: "https://issues.example/parent" },
    duplicateOf: { id: linkedId, url: "https://issues.example/duplicate" },
  };
  const calls: CodexReview<unknown>[] = [];
  const reviewer = new CodexDeduplicationReviewer({
    async run<T>(review: CodexReview<T>): Promise<T> {
      calls.push(review);
      let result: ScreeningResult | DuplicateDecision;
      if (calls.length === 1) {
        result = screening(
          findings,
          new Set([
            pairKey(findings.slice(0, 2).map((finding) => finding.findingId)),
          ]),
        );
        for (const decision of Object.values(result.decisions))
          decision.rationale = "SCREENING_ONLY_RATIONALE";
      } else {
        result = same(
          calls.length === 2 ? findings.slice(0, 2) : findings.slice(1),
        );
        result.rationale = "PAIR_ONLY_RATIONALE";
        result.mergedFinding["title"] = "PAIR_ONLY_MERGED";
      }
      const validateSchema = new Ajv2020({ strict: false }).compile(
        review.schema as object,
      );
      expect(validateSchema(result)).toBe(true);
      if ("decisions" in result) {
        expect(
          validateSchema({
            decisions: { "pair-1": result.decisions["pair-1"] },
          }),
        ).toBe(false);
        expect(
          validateSchema({
            decisions: {
              ...result.decisions,
              "pair-3": result.decisions["pair-1"],
            },
          }),
        ).toBe(false);
        const decisionsWithFindingIds = Object.fromEntries(
          Object.entries(result.decisions).map(([slot, decision]) => [
            slot,
            {
              ...decision,
              findingIds: [findings[0]!.findingId, findings[1]!.findingId],
            },
          ]),
        );
        expect(validateSchema({ decisions: decisionsWithFindingIds })).toBe(
          false,
        );
        for (const field of ["canonicalFindingId", "mergedFinding"] as const) {
          const invalid = {
            decisions: Object.fromEntries(
              Object.entries(result.decisions).map(([slot, decision]) => [
                slot,
                decision.decision === "SAME"
                  ? { ...decision, [field]: null }
                  : decision,
              ]),
            ),
          };
          expect(validateSchema(invalid)).toBe(false);
        }
      } else {
        for (const field of ["canonicalFindingId", "mergedFinding"] as const) {
          for (const value of [undefined, null]) {
            const invalid = { ...result, [field]: value };
            expect(validateSchema(invalid)).toBe(false);
          }
        }
      }
      return review.validate(result);
    },
  });
  await reviewer.screen(findings);
  await reviewer.reviewPair(findings.slice(0, 2));
  await reviewer.reviewPair(findings.slice(1));
  expect(
    calls.map(({ stage, model, effort }) => [stage, model, effort]),
  ).toEqual([
    ["screening", "gpt-5.6-luna", "xhigh"],
    ["pair-review", "gpt-5.6-sol", "high"],
    ["pair-review", "gpt-5.6-sol", "high"],
  ]);
  expect(calls[0]!.prompt).toContain(JSON.stringify({ findings }));
  expect(calls[1]!.prompt).toContain(
    JSON.stringify({ findings: findings.slice(0, 2) }),
  );
  expect(calls[2]!.prompt).toContain(
    JSON.stringify({ findings: findings.slice(1) }),
  );
  expect(
    calls
      .slice(1)
      .every(
        ({ prompt }) =>
          !prompt.includes("SCREENING_ONLY_RATIONALE") &&
          !prompt.includes("PAIR_ONLY_RATIONALE") &&
          !prompt.includes("PAIR_ONLY_MERGED"),
      ),
  ).toBe(true);
  expect(calls[0]!.prompt).not.toContain("canonicalFindingId");
  expect(calls[0]!.prompt).not.toContain("mergedFinding");
  for (const { prompt } of calls) {
    expect(prompt).toMatch(/incomplete or insufficient.*DISTINCT/);
    expect(prompt).toMatch(/failure prevents a required check.*submit_error/);
    expect(prompt).toMatch(
      /failed optional lookup.*continue when other available evidence is sufficient/,
    );
  }
  for (const { prompt } of calls.slice(1)) {
    expect(prompt).toMatch(/exactly the two supplied findings/);
    expect(prompt).toMatch(
      /Linked parent tickets, duplicate targets, and related-ticket records are metadata/,
    );
    expect(prompt).toMatch(/Do not fetch those records or expand the pair/);
    expect(prompt).toMatch(
      /unsupplied linked duplicate target is not automatically the canonical finding.*not itself an error/,
    );
    expect(prompt).toMatch(
      /Necessary source-code investigation.*remains allowed/,
    );
  }
  expect(() =>
    validateReview(
      {
        ...same(findings.slice(0, 2)),
        canonicalFindingId: linkedId,
        mergedFinding: { ...findings[0], findingId: linkedId },
      },
      findings.slice(0, 2),
    ),
  ).toThrow("The canonical finding must belong to the assigned findings.");
});

test("accepts complete canonical and merged reviews and rejects invalid assignments", () => {
  const findings = [entry(1), entry(2)];
  const result = {
    ...same(findings),
    mergedFinding: {
      ...findings[0],
      extensions: { preserved: "complete original evidence" },
    },
  };
  expect(validateReview(result, findings)).toEqual(result);
  expect(validateReview(distinct, findings)).toEqual(distinct);
  expect(
    validateReview(
      { ...distinct, canonicalFindingId: null, mergedFinding: null },
      findings,
    ),
  ).toEqual({
    ...distinct,
    canonicalFindingId: null,
    mergedFinding: null,
  });
  for (const invalid of [
    { decision: "SAME", rationale: "Missing canonical and merged finding." },
    { ...result, canonicalFindingId: undefined },
    { ...result, canonicalFindingId: null },
    { ...result, mergedFinding: undefined },
    { ...result, mergedFinding: null },
    { ...result, mergedFinding: {} },
    {
      ...result,
      mergedFinding: {
        ...result.mergedFinding,
        findingId: findings[1]!.findingId,
      },
    },
    { ...result, canonicalFindingId: "outside" },
    {
      ...result,
      canonicalFindingId: undefined,
      canonicalIssueId: result.canonicalFindingId,
    },
    { ...result, decision: "DISTINCT" },
  ]) {
    expect(() => validateReview(invalid, findings)).toThrow();
  }
});

test.each(
  (
    [
      "stable",
      "changed",
      "missing",
      "same-body-missing",
      "same-body-changed",
      "empty",
    ] as const
  ).flatMap((kind) => [false, true].map((reverse) => ({ kind, reverse }))),
)(
  "saved-scan provenance follows each retrieved record: %j",
  async ({ kind, reverse }) => {
    const fixture = await workflowFixture();
    const gates = [
      Promise.withResolvers<void>(),
      Promise.withResolvers<void>(),
    ];
    let pending: Promise<unknown> | undefined;
    try {
      const manifestPath = join(fixture.scanDir, "scan-manifest.json");
      const findingsPath = join(fixture.scanDir, "findings.json");
      const manifest = await readJson<ScanManifest>(manifestPath);
      const targetId = manifest.scan.target.targetId;
      const first = fixture.document.findings[0]!;
      const second: Finding = {
        ...structuredClone(first),
        ...deriveFindingIdentity(manifest.scan.id, targetId, first.ruleId, {
          anchor: "second-synthetic-control",
        }),
        title: "Second saved finding",
      };
      await writeJson(findingsPath, {
        ...fixture.document,
        findings: [first, second],
      });
      const findingsBytes = await readFile(findingsPath, "utf8");
      manifest.scan.artifacts.find(
        (artifact) => artifact.path === "findings.json",
      )!.sha256 = createHash("sha256").update(findingsBytes).digest("hex");
      await writeJson(manifestPath, manifest);
      const manifestBytes = await readFile(manifestPath, "utf8");
      const latest = [first, second].map((finding): Finding => {
        if (
          kind === "stable" ||
          kind.startsWith("same-body") ||
          kind === "empty"
        )
          return structuredClone(finding);
        return {
          ...structuredClone(finding),
          ...deriveFindingIdentity(
            "scan_later_observation",
            targetId,
            finding.ruleId,
            finding.identity,
          ),
          title: `Later observation: ${finding.title}`,
        };
      });
      const initialSnapshot = {
        repositoryId: "target_initial",
        revision: manifest.scan.target.revision!,
        snapshotDigest: manifest.scan.target.snapshotDigest ?? null,
      } satisfies FindingSourceSnapshot;
      const laterSnapshot =
        kind === "stable"
          ? initialSnapshot
          : {
              repositoryId: "target_later",
              revision: "a".repeat(40),
              snapshotDigest: `codex-security-snapshot/v1:sha256:${"b".repeat(64)}`,
            };
      const ids = [first.findingId, second.findingId];
      const repositories = (repositoryIds: string[]) =>
        Object.fromEntries(ids.map((id) => [id, repositoryIds]));
      const snapshots = (snapshot: FindingSourceSnapshot) =>
        Object.fromEntries(ids.map((id) => [id, snapshot]));
      const neighborhoods: FindingNeighborhood[] = [
        {
          finding: first,
          potentialDuplicates: [second],
          repositoryIds: repositories([initialSnapshot.repositoryId]),
          sourceSnapshots: snapshots(initialSnapshot),
        },
        {
          finding: latest[1]!,
          potentialDuplicates: [latest[0]!],
          ...(kind.includes("missing")
            ? {}
            : {
                repositoryIds: repositories(
                  kind === "empty" ? [] : [laterSnapshot.repositoryId],
                ),
                sourceSnapshots:
                  kind === "empty" ? {} : snapshots(laterSnapshot),
              }),
        },
      ];
      const originalNeighborhoods = structuredClone(neighborhoods);
      const starts = [
        Promise.withResolvers<void>(),
        Promise.withResolvers<void>(),
      ];
      const reviewed: string[][] = [];
      const writes: unknown[] = [];
      pending = deduplicateScanInternal(
        manifest.scan.id,
        {
          findingsUrl: "https://synthetic.test/api",
          allRepositories: true,
          concurrency: 2,
        },
        {
          environment: fixture.environment,
          resolveReviewEnvironment: async () => ({
            CODEX_HOME: fixture.environment.CODEX_HOME,
          }),
          runWorkbench: async () => ({
            scan: {
              scanId: manifest.scan.id,
              scanDir: fixture.scanDir,
              targetPath: fixture.repository,
              progress: { status: "complete" },
            },
          }),
          fetch: async (url, options) => {
            if (options.method === "POST") {
              writes.push(JSON.parse(String(options.body)));
              return Response.json({});
            }
            const id = decodeURIComponent(url.pathname.split("/").at(-2)!);
            const index = ids.indexOf(id);
            expect(index).toBeGreaterThanOrEqual(0);
            starts[index]!.resolve();
            await gates[index]!.promise;
            return Response.json(neighborhoods[index]);
          },
          reviewRunner: {
            async run<T>(review: CodexReview<T>): Promise<T> {
              const assignedIds =
                review.findingIds ?? fail("Missing review participants");
              const origin =
                review.stage === "screening" ? ids.indexOf(assignedIds[0]!) : 1;
              const neighborhood = neighborhoods[origin]!;
              const expected = [
                neighborhood.finding,
                ...neighborhood.potentialDuplicates,
              ];
              const records: { findings: Finding[] } = JSON.parse(
                review.prompt
                  .split("\n")
                  .find((line) => line.startsWith('{"findings":'))!,
              );
              expect(records.findings).toEqual(expected);
              const context: {
                approvedRepositoryId: string;
                findings: {
                  findingId: string;
                  repositoryIds: string[];
                  sourceSnapshot?: FindingSourceSnapshot;
                }[];
              } = JSON.parse(
                review.prompt
                  .split("\n")
                  .find((line) => line.startsWith('{"approvedRepositoryId":'))!,
              );
              expect(context.approvedRepositoryId).toBe(targetId);
              expect(context.findings).toHaveLength(expected.length);
              for (const [index, finding] of expected.entries()) {
                const snapshot =
                  neighborhood.sourceSnapshots?.[finding.findingId];
                expect(context.findings[index]).toEqual({
                  findingId: finding.findingId,
                  repositoryIds: neighborhood.repositoryIds?.[
                    finding.findingId
                  ] ?? [targetId],
                  ...(snapshot === undefined
                    ? {}
                    : { sourceSnapshot: snapshot }),
                });
                expect(
                  Object.hasOwn(context.findings[index]!, "sourceSnapshot"),
                ).toBe(snapshot !== undefined);
              }
              reviewed.push([...assignedIds]);
              return review.validate(
                review.stage === "screening"
                  ? {
                      decisions: {
                        "pair-1": {
                          decision: "SAME",
                          rationale: "Inspect the supplied source.",
                        },
                      },
                    }
                  : {
                      decision: "SAME",
                      rationale: "One correction covers both findings.",
                    },
              );
            },
          },
        },
      );
      await Promise.race([
        Promise.all(starts.map((start) => start.promise)),
        pending.then(() =>
          fail("Review completed before both lookups started"),
        ),
      ]);
      for (const index of reverse ? [1, 0] : [0, 1]) {
        gates[index]!.resolve();
        await new Promise<void>((resolve) => setImmediate(resolve));
      }
      const group = [...ids].sort();
      expect(await pending).toEqual({
        scanId: manifest.scan.id,
        uniqueFindingIds: [group[0]],
        scanRepresentativeFindingIds: [group[0]],
        duplicateGroups: [group],
        deduplicationStatus: "completed",
      });
      expect(reviewed).toEqual([ids, [...ids].reverse(), [...ids].reverse()]);
      expect(writes).toEqual([{ groups: [group] }]);
      expect(neighborhoods).toEqual(originalNeighborhoods);
      expect(await readFile(findingsPath, "utf8")).toBe(findingsBytes);
      expect(await readFile(manifestPath, "utf8")).toBe(manifestBytes);
    } finally {
      for (const gate of gates) gate.resolve();
      await pending?.catch(() => undefined);
      await fixture[Symbol.asyncDispose]();
    }
  },
);

test.each(
  [false, true].flatMap((allRepositories) =>
    [false, true].map((emptyMaps) => ({ allRepositories, emptyMaps })),
  ),
)(
  "saved-scan repository fallback respects selection: %j",
  async ({ allRepositories, emptyMaps }) => {
    await using fixture = await workflowFixture();
    const manifest = await readJson<ScanManifest>(
      join(fixture.scanDir, "scan-manifest.json"),
    );
    const selected = fixture.document.findings[0]!;
    const neighbor = entry(2);
    let reviews = 0;
    const result = await deduplicateScanInternal(
      manifest.scan.id,
      { findingsUrl: "https://synthetic.test/api", allRepositories },
      {
        environment: fixture.environment,
        resolveReviewEnvironment: async () => ({
          CODEX_HOME: fixture.environment.CODEX_HOME,
        }),
        runWorkbench: async () => ({
          scan: {
            scanId: manifest.scan.id,
            scanDir: fixture.scanDir,
            targetPath: fixture.repository,
            progress: { status: "complete" },
          },
        }),
        fetch: async () =>
          Response.json({
            finding: selected,
            potentialDuplicates: [neighbor],
            ...(emptyMaps ? { repositoryIds: {}, sourceSnapshots: {} } : {}),
          }),
        reviewRunner: {
          async run<T>(review: CodexReview<T>): Promise<T> {
            reviews++;
            const context = JSON.parse(
              review.prompt
                .split("\n")
                .find((line) => line.startsWith('{"approvedRepositoryId":'))!,
            );
            expect(context.findings).toEqual([
              {
                findingId: selected.findingId,
                repositoryIds: [manifest.scan.target.targetId],
              },
              {
                findingId: neighbor.findingId,
                repositoryIds: allRepositories
                  ? []
                  : [manifest.scan.target.targetId],
              },
            ]);
            return review.validate({
              decisions: {
                "pair-1": {
                  decision: "DISTINCT",
                  rationale: "Independent controls.",
                },
              },
            });
          },
        },
      },
    );
    expect(reviews).toBe(1);
    expect(result.duplicateGroups).toEqual([]);
  },
);

test("resolves a saved scan and retrieves its IDs without uploading or modifying artifacts", async () => {
  const fixture = await workflowFixture();
  const { scanDir: directory } = fixture;
  try {
    const original = await readFile(join(directory, "findings.json"), "utf8");
    for (const [requestedId, allRepositories] of [
      ["scan_example", false],
      ["latest", false],
      ["scan_example_001", true],
    ] as const) {
      const commands: string[][] = [];
      const requests: string[] = [];
      const result = await deduplicateScanInternal(
        requestedId,
        { findingsUrl: "http://synthetic.test/api", allRepositories },
        {
          currentDirectory: () => directory,
          runWorkbench: async (args): Promise<JsonObject> => {
            commands.push([...args]);
            return args[0] === "list-scans"
              ? { scans: [{ scanId: "scan_example_001" }] }
              : {
                  scan: {
                    scanId: "scan_example_001",
                    scanDir: directory,
                    progress: { status: "complete" },
                  },
                };
          },
          fetch: async (url, options) => {
            requests.push(String(url));
            expect(options?.method).toBeUndefined();
            expect(options?.body).toBeUndefined();
            expect(options?.headers).toBeUndefined();
            return Response.json({
              finding: document.findings[0],
              potentialDuplicates: [],
            });
          },
          reviewer: emptyNeighborhoodReviewer(),
        },
      );
      expect(result).toEqual({
        scanId: "scan_example_001",
        uniqueFindingIds: document.findings.map((finding) => finding.findingId),
        scanRepresentativeFindingIds: document.findings.map(
          (finding) => finding.findingId,
        ),
        duplicateGroups: [],
        deduplicationStatus: "completed",
      });
      expect(commands.at(-1)).toEqual([
        "get-scan",
        "--scan-id",
        requestedId === "latest" ? "scan_example_001" : requestedId,
      ]);
      if (requestedId === "latest")
        expect(commands[0]).toEqual([
          "list-scans",
          "--repository",
          directory,
          "--status",
          "complete",
        ]);
      expect(requests).toEqual([
        `http://synthetic.test/api/v1/finding/${document.findings[0]!.findingId}/potential-duplicates?${allRepositories ? "allRepositories=true" : "repositoryId=target_sha256_example"}`,
      ]);
    }
    expect(await readFile(join(directory, "findings.json"), "utf8")).toBe(
      original,
    );
    await expect(
      deduplicateScanInternal(
        "wrong-scan",
        { findingsUrl: "http://synthetic.test" },
        {
          runWorkbench: async () => ({
            scan: {
              scanId: "wrong-scan",
              scanDir: directory,
              progress: { status: "complete" },
            },
          }),
          fetch: async () =>
            fail("Must not retrieve candidates for a mismatched scan"),
        },
      ),
    ).rejects.toThrow("do not match selected scan");
  } finally {
    await fixture[Symbol.asyncDispose]();
  }
});

test("deduplicates an explicit sealed scan directory without reading scan history", async () => {
  const fixture = await workflowFixture();
  const { scanDir: directory, repository } = fixture;
  try {
    const original = await readFile(join(directory, "findings.json"), "utf8");
    const commands: string[][] = [];
    const requests: string[] = [];
    const result = await deduplicateScanDirectoryInternal(
      directory,
      {
        repository,
        expectedScanId: "scan_example_001",
        findingsUrl: "http://synthetic.test/api",
      },
      {
        runWorkbench: async (args) => {
          commands.push([...args]);
          throw new Error("Explicit scan directories must not read history");
        },
        fetch: async (url, options) => {
          requests.push(String(url));
          expect(options?.method).toBeUndefined();
          return Response.json({
            finding: document.findings[0],
            potentialDuplicates: [],
          });
        },
        reviewer: emptyNeighborhoodReviewer(),
      },
    );
    expect(result).toEqual({
      scanId: "scan_example_001",
      uniqueFindingIds: document.findings.map((finding) => finding.findingId),
      scanRepresentativeFindingIds: document.findings.map(
        (finding) => finding.findingId,
      ),
      duplicateGroups: [],
      deduplicationStatus: "completed",
    });
    expect(commands).toEqual([]);
    expect(requests).toEqual([
      `http://synthetic.test/api/v1/finding/${document.findings[0]!.findingId}/potential-duplicates?repositoryId=target_sha256_example`,
    ]);
    expect(await readFile(join(directory, "findings.json"), "utf8")).toBe(
      original,
    );
    await expect(
      deduplicateScanDirectory(directory, {
        repository,
        expectedScanId: "scan_other",
        findingsUrl: "http://synthetic.test/api",
      }),
    ).rejects.toThrow("do not match selected scan");
  } finally {
    await fixture[Symbol.asyncDispose]();
  }
});

test("lookup failures and cancellation never produce a completed uniqueness result", async () => {
  for (const status of [404, 502]) {
    const client = new FindingsClient(
      "http://synthetic.test",
      undefined,
      async () => new Response("", { status }),
    );
    await expect(
      client.potentialDuplicates(entry(1).findingId, { allRepositories: true }),
    ).rejects.toThrow(`HTTP ${status}`);
  }
  const controller = new AbortController();
  controller.abort("synthetic cancellation");
  await expect(
    new FindingDeduplicator(
      candidates([]),
      {} as DeduplicationReviewer,
      controller.signal,
    ).run([]),
  ).rejects.toBe("synthetic cancellation");
  await expect(
    deduplicateScanInternal("scan-id", {
      findingsUrl: "http://synthetic.test",
      signal: controller.signal,
    }),
  ).rejects.toBe("synthetic cancellation");
});

test("writes accepted groups only after all reviews and fails on review or write-back errors", async () => {
  const fixture = await workflowFixture();
  const { scanDir: directory } = fixture;
  try {
    const findings = [document.findings[0]!, entry(2), entry(3)];
    const ids = findings.map((finding) => finding.findingId);
    for (const failure of ["none", "write", "review", "refusal"]) {
      const phases: string[] = [];
      const controller = new AbortController();
      const result = deduplicateScanInternal(
        "scan_example_001",
        {
          findingsUrl: "http://synthetic.test/api/",
          signal: controller.signal,
        },
        {
          runWorkbench: async () => ({
            scan: {
              scanId: "scan_example_001",
              scanDir: directory,
              progress: { status: "complete" },
            },
          }),
          fetch: async (url, options) => {
            expect(options.signal).toBe(controller.signal);
            if (options.method === "POST") {
              phases.push("store");
              expect(String(url)).toBe(
                "http://synthetic.test/api/v1/dedupe-groups",
              );
              expect(JSON.parse(options.body as string)).toEqual({
                groups: [
                  failure === "refusal"
                    ? ids.slice(0, 2).sort()
                    : [...ids].sort(),
                ],
              });
              return Response.json([], {
                status: failure === "write" ? 409 : 201,
              });
            }
            phases.push("lookup");
            return Response.json({
              finding: findings[0],
              potentialDuplicates: findings.slice(1),
            });
          },
          reviewer: {
            async screen(values) {
              phases.push("screen");
              return screening(
                values,
                new Set(
                  values
                    .slice(1)
                    .map((value) => pairKey([ids[0]!, value.findingId])),
                ),
              );
            },
            async reviewPair(values) {
              phases.push("pair");
              if (failure === "refusal" && values[1]!.findingId === ids[2])
                throw new DeduplicationReviewError({
                  stage: "pair-review",
                  model: "gpt-5.6-sol",
                  category: "refusal",
                  attempts: 1,
                  reason: "The model refused the deduplication review.",
                });
              if (failure === "review" && values[1]!.findingId === ids[2])
                throw new CodexSecurityError(
                  "Required source revision could not be read.",
                );
              return same(values);
            },
          },
        },
      );
      if (failure === "none") {
        expect((await result).duplicateGroups).toEqual([[...ids].sort()]);
      } else if (failure === "refusal") {
        expect(await result).toMatchObject({
          deduplicationStatus: "completed_with_refusals",
          duplicateGroups: [ids.slice(0, 2).sort()],
          refusals: [
            {
              decision: "NO_DECISION",
              stage: "pair-review",
              findingIds: [ids[0], ids[2]],
            },
          ],
        });
      } else if (failure === "review") {
        await expect(result).rejects.toThrow(
          "Required source revision could not be read.",
        );
      } else {
        await expect(result).rejects.toThrow(
          "POST /v1/dedupe-groups failed (HTTP 409)",
        );
      }
      expect(phases).toEqual([
        "lookup",
        "screen",
        "pair",
        "pair",
        ...(failure === "review" ? [] : ["store"]),
      ]);
    }
    expect(
      JSON.parse(await readFile(join(directory, "findings.json"), "utf8")),
    ).toEqual(document);
  } finally {
    await fixture[Symbol.asyncDispose]();
  }
});