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

test: share recovery and publication fixtures (#2138)

Michael D'Angeloab9da3b427aa
diff --git a/plugins/codex-security/mcp-app/tests/deep_scan_coverage_fixture.ts b/plugins/codex-security/mcp-app/tests/deep_scan_coverage_fixture.ts
index b42c6f887..3d3806da2 100644
--- a/plugins/codex-security/mcp-app/tests/deep_scan_coverage_fixture.ts
+++ b/plugins/codex-security/mcp-app/tests/deep_scan_coverage_fixture.ts
@@ -113,6 +113,11 @@ const {
},
loader: { ".md": "text" },
})) as FixtureRuntime;
+async function writeReceipt(file: string, contents: string) {
+ await mkdir(path.dirname(file), { recursive: true });
+ await writeFile(file, contents);
+}
+
export async function publishReceiptFixture(options: CoverageFixtureOptions) {
const root = await temporaryDirectory("retry-coverage-receipts-");
try {
@@ -210,34 +215,28 @@ runpy.run_path(sys.argv[0], run_name="__main__")
const context = await createScanArtifactContext(run.scanId, runWorkbench, {
requireRunning: true,
});
+ const recordWorkerDraft = (root: string, draft: JsonObject) =>
+ recordCodexSecurityWorkerScanDraft(
+ { root, layout: "worker", repoRoot: targetPath, scanId: run.scanId },
+ { scanId: run.scanId, ...draft },
+ );
const rawSources = new Map<string, string>();
const writeReceiptAttempt = async (artifactDir: string) => {
if (retryCoverage) {
await mkdir(artifactDir, { recursive: true });
- await recordCodexSecurityWorkerScanDraft(
- {
- root: artifactDir,
- layout: "worker",
- repoRoot: targetPath,
- scanId: run.scanId,
- },
- {
- scanId: run.scanId,
- complete: false,
- findings: retryFindings?.[0] ?? [],
- reviewState: retryCoverage[0],
- },
- );
+ await recordWorkerDraft(artifactDir, {
+ complete: false,
+ findings: retryFindings?.[0] ?? [],
+ reviewState: retryCoverage[0],
+ });
return;
}
- await mkdir(path.join(artifactDir, "artifacts"), { recursive: true });
- await writeFile(
+ await writeReceipt(
path.join(artifactDir, "artifacts", "prior.txt"),
emptyReceipt ? "" : "Archived receipt.\n",
);
if (receiptCollision) {
- await mkdir(path.join(run.scanDir, "artifacts"), { recursive: true });
- await writeFile(
+ await writeReceipt(
path.join(run.scanDir, "artifacts", "prior.txt"),
"Synthetic unrelated parent review.\n",
);
@@ -245,10 +244,7 @@ runpy.run_path(sys.argv[0], run_name="__main__")
const archivedRef = `${path.relative(run.scanDir, path.dirname(artifactDir)).split(path.sep).join("/")}/attempts/attempt-01/artifacts/prior.txt`;
const sharedPrior = "artifacts/01_context/false_positive_feedback.json";
if (receiptSpelling === "shared scan") {
- await mkdir(path.dirname(path.join(run.scanDir, sharedPrior)), {
- recursive: true,
- });
- await writeFile(
+ await writeReceipt(
path.join(run.scanDir, sharedPrior),
emptyReceipt ? "" : "Archived receipt.\n",
);
@@ -262,152 +258,125 @@ runpy.run_path(sys.argv[0], run_name="__main__")
? archivedRef
: `${path.relative(run.scanDir, artifactDir).split(path.sep).join("/")}/artifacts/prior.txt`;
if (receiptOwnershipRetry) {
- await recordCodexSecurityWorkerScanDraft(
- {
- root: artifactDir,
- layout: "worker",
- repoRoot: targetPath,
- scanId: run.scanId,
- },
- {
- scanId: run.scanId,
- complete: false,
- findings: [],
- reviewState: {
- completeness: "partial",
- surfaces: [
- {
- id: "current",
- label: "Current review",
- disposition:
- receiptOwnershipRetry === "unrelated"
- ? "no_issue_found"
- : "needs_follow_up",
- ...(receiptOwnershipRetry === "candidate"
- ? { candidateId: "prior-candidate" }
- : {}),
- receiptRefs: [receiptRef],
- },
- ...(receiptOwnershipRetry === "unrelated"
- ? [
- {
- id: "closed",
- label: "Separate review",
- disposition: "needs_follow_up",
- receiptRefs: [receiptRef],
- },
- ]
- : []),
- ],
- explicitExclusions: [],
- deferred:
- receiptOwnershipRetry === "ordinary"
- ? []
- : [
- {
- id: "prior-gap",
- ...(receiptOwnershipRetry === "candidate"
- ? { candidateId: "prior-candidate" }
- : {}),
- reason: "Verify the earlier boundary.",
- surfaceIds: [
- receiptOwnershipRetry === "unrelated"
- ? "closed"
- : "current",
- ],
- },
- ],
- },
+ await recordWorkerDraft(artifactDir, {
+ complete: false,
+ findings: [],
+ reviewState: {
+ completeness: "partial",
+ surfaces: [
+ {
+ id: "current",
+ label: "Current review",
+ disposition:
+ receiptOwnershipRetry === "unrelated"
+ ? "no_issue_found"
+ : "needs_follow_up",
+ ...(receiptOwnershipRetry === "candidate"
+ ? { candidateId: "prior-candidate" }
+ : {}),
+ receiptRefs: [receiptRef],
+ },
+ ...(receiptOwnershipRetry === "unrelated"
+ ? [
+ {
+ id: "closed",
+ label: "Separate review",
+ disposition: "needs_follow_up",
+ receiptRefs: [receiptRef],
+ },
+ ]
+ : []),
+ ],
+ explicitExclusions: [],
+ deferred:
+ receiptOwnershipRetry === "ordinary"
+ ? []
+ : [
+ {
+ id: "prior-gap",
+ ...(receiptOwnershipRetry === "candidate"
+ ? { candidateId: "prior-candidate" }
+ : {}),
+ reason: "Verify the earlier boundary.",
+ surfaceIds: [
+ receiptOwnershipRetry === "unrelated"
+ ? "closed"
+ : "current",
+ ],
+ },
+ ],
},
- );
+ });
return;
}
if (closeRetriedSurface) {
- await recordCodexSecurityWorkerScanDraft(
- {
- root: artifactDir,
- layout: "worker",
- repoRoot: targetPath,
- scanId: run.scanId,
- },
- {
- scanId: run.scanId,
- complete: false,
- findings: [],
- reviewState: {
- completeness: "partial",
- surfaces: [
- {
- id: "current",
- label: "Current review",
- disposition: "needs_follow_up",
- receiptRefs: [receiptRef],
- },
- ],
- explicitExclusions: [],
- deferred: [
- {
- id: "prior-gap",
- reason: "Verify the earlier boundary.",
- surfaceIds: ["current"],
- },
- ],
- },
- },
- );
- return;
- }
- await recordCodexSecurityWorkerScanDraft(
- {
- root: artifactDir,
- layout: "worker",
- repoRoot: targetPath,
- scanId: run.scanId,
- },
- {
- scanId: run.scanId,
+ await recordWorkerDraft(artifactDir, {
complete: false,
findings: [],
reviewState: {
completeness: "partial",
surfaces: [
{
- id: "prior",
- label: "Prior review",
+ id: "current",
+ label: "Current review",
disposition: "needs_follow_up",
- candidateId: "shared-prior-candidate",
receiptRefs: [receiptRef],
},
- {
- id: "prior-second",
- label: "Prior second surface",
- disposition: "needs_follow_up",
- candidateId: "shared-prior-candidate",
- receiptRefs: [
- receiptSpelling === "worker"
- ? receiptRef
- : receiptRef.replace("artifacts/", "artifacts/./"),
- ],
- },
],
explicitExclusions: [],
deferred: [
{
id: "prior-gap",
- candidateId: "shared-prior-candidate",
- reason: "Verify the earlier attempt's unresolved boundary.",
- surfaceIds: ["prior", "prior-second"],
- },
- {
- id: "prior-gap-2",
- candidateId: "shared-prior-candidate",
- reason: "Verify the same candidate's second boundary.",
- surfaceIds: ["prior", "prior-second"],
+ reason: "Verify the earlier boundary.",
+ surfaceIds: ["current"],
},
],
},
+ });
+ return;
+ }
+ await recordWorkerDraft(artifactDir, {
+ complete: false,
+ findings: [],
+ reviewState: {
+ completeness: "partial",
+ surfaces: [
+ {
+ id: "prior",
+ label: "Prior review",
+ disposition: "needs_follow_up",
+ candidateId: "shared-prior-candidate",
+ receiptRefs: [receiptRef],
+ },
+ {
+ id: "prior-second",
+ label: "Prior second surface",
+ disposition: "needs_follow_up",
+ candidateId: "shared-prior-candidate",
+ receiptRefs: [
+ receiptSpelling === "worker"
+ ? receiptRef
+ : receiptRef.replace("artifacts/", "artifacts/./"),
+ ],
+ },
+ ],
+ explicitExclusions: [],
+ deferred: [
+ {
+ id: "prior-gap",
+ candidateId: "shared-prior-candidate",
+ reason: "Verify the earlier attempt's unresolved boundary.",
+ surfaceIds: ["prior", "prior-second"],
+ },
+ {
+ id: "prior-gap-2",
+ candidateId: "shared-prior-candidate",
+ reason: "Verify the same candidate's second boundary.",
+ surfaceIds: ["prior", "prior-second"],
+ },
+ ],
},
- );
+ });
};
const writeDiscovery = async (
artifactDir: string,
@@ -423,30 +392,17 @@ runpy.run_path(sys.argv[0], run_name="__main__")
: "artifacts/first.txt";
const firstRoot =
firstCheckpointReceipt === "shared" ? run.scanDir : artifactDir;
- await mkdir(path.dirname(path.join(firstRoot, firstRef)), {
- recursive: true,
- });
- await writeFile(
+ await writeReceipt(
path.join(firstRoot, firstRef),
"Synthetic first checkpoint.\n",
);
if (firstCheckpointReceipt === "worker") {
- await mkdir(path.dirname(path.join(run.scanDir, firstRef)), {
- recursive: true,
- });
- await writeFile(
+ await writeReceipt(
path.join(run.scanDir, firstRef),
"Synthetic unrelated parent checkpoint.\n",
);
}
- const workerContext = {
- root: artifactDir,
- layout: "worker" as const,
- repoRoot: targetPath,
- scanId: run.scanId,
- };
- await recordCodexSecurityWorkerScanDraft(workerContext, {
- scanId: run.scanId,
+ await recordWorkerDraft(artifactDir, {
complete: false,
findings: [],
reviewState: {
@@ -479,15 +435,11 @@ runpy.run_path(sys.argv[0], run_name="__main__")
rawSources.set(checkpoint, await readFile(checkpoint, "utf8"));
}
const nextRef = receiptCollision ? firstRef : "artifacts/later.txt";
- await mkdir(path.dirname(path.join(artifactDir, nextRef)), {
- recursive: true,
- });
- await writeFile(
+ await writeReceipt(
path.join(artifactDir, nextRef),
"Synthetic later checkpoint.\n",
);
- await recordCodexSecurityWorkerScanDraft(workerContext, {
- scanId: run.scanId,
+ await recordWorkerDraft(artifactDir, {
complete,
findings: [],
reviewState: {
@@ -577,14 +529,12 @@ runpy.run_path(sys.argv[0], run_name="__main__")
};
}
}
- await mkdir(path.join(artifactDir, "artifacts"), { recursive: true });
- await writeFile(
+ await writeReceipt(
path.join(artifactDir, "artifacts", "review.md"),
emptyReceipt ? "" : "Synthetic review evidence.\n",
);
if (receiptCollision) {
- await mkdir(path.join(run.scanDir, "artifacts"), { recursive: true });
- await writeFile(
+ await writeReceipt(
path.join(run.scanDir, "artifacts", "review.md"),
"Synthetic unrelated parent review.\n",
);
@@ -596,24 +546,19 @@ runpy.run_path(sys.argv[0], run_name="__main__")
"01_context",
"false_positive_feedback.json",
);
- await mkdir(path.dirname(collision), { recursive: true });
- await writeFile(collision, "Synthetic unrelated retry receipt.\n");
+ await writeReceipt(collision, "Synthetic unrelated retry receipt.\n");
}
const activeQualifiedRef = `${path.relative(run.scanDir, artifactDir).split(path.sep).join("/")}/artifacts/review.md`;
const sharedRef = "artifacts/01_context/false_positive_feedback.json";
if (sharedReceipt) {
- await mkdir(path.dirname(path.join(run.scanDir, sharedRef)), {
- recursive: true,
- });
- await writeFile(
+ await writeReceipt(
path.join(run.scanDir, sharedRef),
emptyReceipt ? "" : "Synthetic review evidence.\n",
);
}
if (sameNamedNewSurface) {
const local = path.join(artifactDir, sharedRef);
- await mkdir(path.dirname(local), { recursive: true });
- await writeFile(local, "Synthetic review evidence.\n");
+ await writeReceipt(local, "Synthetic review evidence.\n");
}
const closureReceiptRef = receiptCollision
? receiptSpelling === "shared scan"
@@ -622,8 +567,7 @@ runpy.run_path(sys.argv[0], run_name="__main__")
: "artifacts/review.md";
if (closeRetriedSurface) {
const local = path.join(artifactDir, closureReceiptRef);
- await mkdir(path.dirname(local), { recursive: true });
- await writeFile(local, "Synthetic review evidence.\n");
+ await writeReceipt(local, "Synthetic review evidence.\n");
}
const activeReceiptRef = closeRetriedSurface
? closureReceiptRef
@@ -644,8 +588,7 @@ runpy.run_path(sys.argv[0], run_name="__main__")
: "artifacts/prior.txt"
: "artifacts/review.md";
const local = path.join(artifactDir, newRef);
- await mkdir(path.dirname(local), { recursive: true });
- await writeFile(local, "Synthetic review evidence.\n");
+ await writeReceipt(local, "Synthetic review evidence.\n");
const current = {
id: "current",
label: "Current review",
@@ -663,128 +606,92 @@ runpy.run_path(sys.argv[0], run_name="__main__")
: `${path.relative(run.scanDir, path.dirname(artifactDir)).split(path.sep).join("/")}/attempts/attempt-01/artifacts/prior.txt`,
];
}
- await recordCodexSecurityWorkerScanDraft(
- {
- root: artifactDir,
- layout: "worker",
- repoRoot: targetPath,
- scanId: run.scanId,
- },
- {
- scanId: run.scanId,
- complete,
- findings: [],
- reviewState: {
- completeness: status,
- surfaces: [
- current,
- ...(receiptOwnershipRetry === "unrelated"
- ? [
- {
- id: "closed",
- label: "Separate review",
- disposition: "no_issue_found",
- receiptRefs: [newRef],
- },
- ]
- : []),
- ],
- explicitExclusions: [],
- deferred: [],
+ await recordWorkerDraft(artifactDir, {
+ complete,
+ findings: [],
+ reviewState: {
+ completeness: status,
+ surfaces: [
+ current,
...(receiptOwnershipRetry === "unrelated"
- ? {
- resolvedDeferred: [
- {
- id: "prior-gap",
- reason: "The separate boundary is verified.",
- },
- ],
- }
- : {}),
- },
+ ? [
+ {
+ id: "closed",
+ label: "Separate review",
+ disposition: "no_issue_found",
+ receiptRefs: [newRef],
+ },
+ ]
+ : []),
+ ],
+ explicitExclusions: [],
+ deferred: [],
+ ...(receiptOwnershipRetry === "unrelated"
+ ? {
+ resolvedDeferred: [
+ {
+ id: "prior-gap",
+ reason: "The separate boundary is verified.",
+ },
+ ],
+ }
+ : {}),
},
- );
+ });
rawSources.set(resultPath, await readFile(resultPath, "utf8"));
return;
}
if (receiptRetry) {
- const saved = await recordCodexSecurityWorkerScanDraft(
- {
- root: artifactDir,
- repoRoot: targetPath,
- layout: "worker",
- scanId: run.scanId,
- },
- {
- scanId: run.scanId,
- complete,
- findings: [],
- reviewState: {
- completeness: retryPending ? "partial" : status,
- surfaces: [
- {
- id: "current",
- label: "Current review",
- disposition: "no_issue_found",
- receiptRefs: [activeReceiptRef],
- ...(receiptCollision
- ? { provenance: { scanReceiptRefs: [activeReceiptRef] } }
- : {}),
- },
- ],
- explicitExclusions: [],
- ...(closeRetriedSurface
- ? {
- resolvedDeferred: [
- { id: "prior-gap", reason: "The boundary is verified." },
- ],
- }
- : {}),
- deferred: retryPending
- ? [
- {
- id: "prior-gap",
- candidateId: "shared-prior-candidate",
- reason: "The earlier boundary still needs verification.",
- surfaceIds: ["prior", "prior-second"],
- },
- ]
- : [],
- },
+ const saved = await recordWorkerDraft(artifactDir, {
+ complete,
+ findings: [],
+ reviewState: {
+ completeness: retryPending ? "partial" : status,
+ surfaces: [
+ {
+ id: "current",
+ label: "Current review",
+ disposition: "no_issue_found",
+ receiptRefs: [activeReceiptRef],
+ ...(receiptCollision
+ ? { provenance: { scanReceiptRefs: [activeReceiptRef] } }
+ : {}),
+ },
+ ],
+ explicitExclusions: [],
+ ...(closeRetriedSurface
+ ? {
+ resolvedDeferred: [
+ { id: "prior-gap", reason: "The boundary is verified." },
+ ],
+ }
+ : {}),
+ deferred: retryPending
+ ? [
+ {
+ id: "prior-gap",
+ candidateId: "shared-prior-candidate",
+ reason: "The earlier boundary still needs verification.",
+ surfaceIds: ["prior", "prior-second"],
+ },
+ ]
+ : [],
},
- );
+ });
if (rewriteReturnedCoverage && index === 0) {
- await recordCodexSecurityWorkerScanDraft(
- {
- root: artifactDir,
- repoRoot: targetPath,
- layout: "worker",
- scanId: run.scanId,
- },
- {
- scanId: run.scanId,
- complete,
- findings: [],
- reviewState: structuredClone(saved.reviewState),
- },
- );
+ await recordWorkerDraft(artifactDir, {
+ complete,
+ findings: [],
+ reviewState: structuredClone(saved.reviewState),
+ });
}
} else {
- await recordCodexSecurityWorkerScanDraft(
- {
- root: artifactDir,
- repoRoot: targetPath,
- layout: "worker",
- scanId: run.scanId,
- },
- {
- scanId: run.scanId,
- complete: true,
- findings: index === 0 ? (retryFindings?.[1] ?? []) : [],
- coverage,
- },
- );
+ await recordWorkerDraft(artifactDir, {
+ complete: true,
+ findings: index === 0 ? (retryFindings?.[1] ?? []) : [],
+ coverage,
+ });
for (const name of await readdir(path.join(artifactDir, "checkpoints"))) {
const checkpointPath = path.join(artifactDir, "checkpoints", name);
rawSources.set(checkpointPath, await readFile(checkpointPath, "utf8"));
diff --git a/plugins/codex-security/mcp-app/tests/scan-draft-recovery-fixture.ts b/plugins/codex-security/mcp-app/tests/scan-draft-recovery-fixture.ts
index 8bade9deb..8e9246e82 100644
--- a/plugins/codex-security/mcp-app/tests/scan-draft-recovery-fixture.ts
+++ b/plugins/codex-security/mcp-app/tests/scan-draft-recovery-fixture.ts
@@ -170,14 +170,28 @@ export function draftFixture(root: string, layout: Layout) {
...reviewState,
},
});
+ const findingsDraft = (
+ findings: DraftFixture["findings"],
+ options: Pick<DraftFixture, "complete"> = {},
+ ) => ({ ...draft({}, options.complete), findings });
+ const write = (input: unknown) =>
+ layout === "worker"
+ ? draftApi.recordCodexSecurityWorkerScanDraft(context, input)
+ : recordCodexSecurityScanDraft(context, input);
return {
root,
context,
draft,
- write: (input: unknown) =>
- layout === "worker"
- ? draftApi.recordCodexSecurityWorkerScanDraft(context, input)
- : recordCodexSecurityScanDraft(context, input),
+ findingsDraft,
+ write,
+ writeReviewState: (...args: Parameters<typeof draft>) =>
+ write(draft(...args)),
+ writeFindings: (
+ findings: DraftFixture["findings"],
+ options?: Pick<DraftFixture, "complete">,
+ ) => write(findingsDraft(findings, options)),
+ checkpoint: (input: unknown) =>
+ draftApi.saveScanDraftCheckpoint(context, input, false),
read: async () =>
layout === "worker"
? (await readJson(root, "result.json")).reviewState
diff --git a/plugins/codex-security/mcp-app/tests/scan-identity-recovery-fixture.ts b/plugins/codex-security/mcp-app/tests/scan-identity-recovery-fixture.ts
index 5c53b5127..229d36ee8 100644
--- a/plugins/codex-security/mcp-app/tests/scan-identity-recovery-fixture.ts
+++ b/plugins/codex-security/mcp-app/tests/scan-identity-recovery-fixture.ts
@@ -3,7 +3,8 @@ import { readdir, utimes } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
-import type { draftFixture } from "./scan-draft-recovery-fixture.ts";
+import type { TestContext } from "node:test";
+import { fixture, type draftFixture } from "./scan-draft-recovery-fixture.ts";
const execFileAsync = promisify(execFile);
export type FixtureFinding = Record<string, unknown> & {
@@ -36,14 +37,52 @@ export const finding = (
...metadata,
});
+type RecoveryOptions = {
+ workers?: Record<string, unknown>[];
+ details?: boolean;
+ replay?: boolean;
+ provenanceDetails?: boolean;
+ source?: "saved" | "published";
+};
+
+export async function recoveryPair(
+ t: TestContext,
+ layout: Parameters<typeof fixture>[1],
+) {
+ const normal = await fixture(t, layout);
+ const recovered = await fixture(t, layout);
+ return {
+ normal,
+ recovered,
+ recover: (options?: RecoveryOptions) =>
+ recoverAndFinalize(normal, recovered, options),
+ };
+}
+
+export const savedWorker = (
+ root: string,
+ id = "reviewer",
+ status: "canceled" | "succeeded" = "canceled",
+) => ({
+ id,
+ kind: "discovery",
+ status,
+ artifact_dir: root,
+ result_manifest_path:
+ status === "succeeded" ? path.join(root, "result.json") : null,
+ attempt: 1,
+});
+
export async function recoverAndFinalize(
normal: DraftFixture,
recovered: DraftFixture,
- workers: Record<string, unknown>[] = [],
- details = false,
- replay = false,
- provenanceDetails = false,
- source: "saved" | "published" = "saved",
+ {
+ workers = [],
+ details = false,
+ replay = false,
+ provenanceDetails = false,
+ source = "saved",
+ }: RecoveryOptions = {},
): Promise<{
normal: RecoveredFinding[];
recovered: RecoveredFinding[];
diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts
index 4d5c8d28b..71f2cfe39 100644
--- a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts
+++ b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts
@@ -119,54 +119,41 @@ for (const [layout, status] of [
const initial = structuredClone(findings[0]);
initial.severity.level = "high";
initial.summary = "Initial assessment before reviewing the control.";
- await saveScanDraftCheckpoint(
- f.context,
- { ...f.draft(), findings: [initial] },
- false,
- );
+ await f.checkpoint(f.findingsDraft([initial]));
}
- await f.write({
- ...f.draft(),
- findings: variant.endsWith("-id") ? findings.slice(0, 1) : findings,
- });
+ await f.writeFindings(
+ variant.endsWith("-id") ? findings.slice(0, 1) : findings,
+ );
if (variant.endsWith("-id"))
- await saveScanDraftCheckpoint(
- f.context,
- { ...f.draft(), findings: findings.slice(1) },
- false,
- );
+ await f.checkpoint(f.findingsDraft(findings.slice(1)));
if (variant.endsWith("-added")) {
findings[0].extensions = {
[variant === "report-added" ? "reportId" : "ledgerRowId"]:
"synthetic-report-1",
};
- await f.write({ ...f.draft(), findings });
+ await f.writeFindings(findings);
}
if (variant === "title-revision") {
findings[0].title = "Revised synthetic review finding";
- await f.write({ ...f.draft(), findings });
+ await f.writeFindings(findings);
}
if (variant === "range-refinement") {
findings[0].locations[0].endLine = 1;
- await f.write({ ...f.draft(), findings });
+ await f.writeFindings(findings);
}
if (variant.startsWith("new-")) {
const file = path.join(f.root, "findings.json");
- const saved = JSON.parse(await readFile(file, "utf8"));
+ const saved = await readJson(file);
saved.findings = saved.findings.slice(0, 1);
await writeFile(file, JSON.stringify(saved));
}
if (variant.endsWith("-checkpoints")) {
findings[1].severity.level = "high";
- await saveScanDraftCheckpoint(
- f.context,
- { ...f.draft(), findings: findings.slice(1) },
- false,
- );
+ await f.checkpoint(f.findingsDraft(findings.slice(1)));
}
if (variant === "preserved") {
const file = path.join(f.root, "findings.json");
- const saved = JSON.parse(await readFile(file, "utf8"));
+ const saved = await readJson(file);
saved.findings[1].provenance.preservedIdentity = structuredClone(
saved.findings[1].identity,
);
@@ -218,27 +205,19 @@ for (const layout of ["standard", "diff", "worker"] as const) {
for (const title of [".env review", "/admin review", "_debug review"]) {
test(`${layout}: generated identity permits repeated writes for ${title}`, async (t) => {
const f = await fixture(t, layout);
- const submitted = {
- ...f.draft(),
- findings: [
- {
- ...findingFor("review"),
- title,
- provenance: { source: "local_plugin" },
- },
- ],
- };
+ const submitted = f.findingsDraft([
+ {
+ ...findingFor("review"),
+ title,
+ provenance: { source: "local_plugin" },
+ },
+ ]);
await f.write(submitted);
await f.write(submitted);
- await f.write(f.draft({}, true));
- const saved = JSON.parse(
- await readFile(
- path.join(
- f.root,
- layout === "worker" ? "result.json" : "findings.json",
- ),
- "utf8",
- ),
+ await f.writeReviewState({}, true);
+ const saved = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "findings.json",
);
assert.equal(saved.findings.length, 1);
});
@@ -246,16 +225,11 @@ for (const layout of ["standard", "diff", "worker"] as const) {
test(`${layout}: distinct candidates at one location survive draft merging`, async (t) => {
const f = await fixture(t, layout);
for (const candidate of ["first", "second", "third"])
- await f.write({ ...f.draft(), findings: [findingFor(candidate)] });
- await f.write(f.draft({}, true));
- const saved = JSON.parse(
- await readFile(
- path.join(
- f.root,
- layout === "worker" ? "result.json" : "findings.json",
- ),
- "utf8",
- ),
+ await f.writeFindings([findingFor(candidate)]);
+ await f.writeReviewState({}, true);
+ const saved = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "findings.json",
);
assert.equal(saved.findings.length, 3);
if (layout !== "worker") {
@@ -264,7 +238,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
3,
);
const manifestPath = path.join(f.root, "scan-manifest.json");
- const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+ const manifest = await readJson(manifestPath);
Object.assign(manifest.scan, {
id: f.context.scanId!,
producer: { name: "codex-security-plugin", version: "0.1.0" },
@@ -275,7 +249,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
await writeFile(manifestPath, JSON.stringify(manifest));
for (const file of ["findings.json", "coverage.json"]) {
const filePath = path.join(f.root, file);
- const document = JSON.parse(await readFile(filePath, "utf8"));
+ const document = await readJson(filePath);
document.scanId = f.context.scanId;
await writeFile(filePath, JSON.stringify(document));
}
@@ -286,9 +260,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
"--scan-dir",
f.root,
]);
- const completed = JSON.parse(
- await readFile(path.join(f.root, "findings.json"), "utf8"),
- );
+ const completed = await readJson(f.root, "findings.json");
assert.equal(completed.findings.length, 3);
}
assert.deepEqual(
@@ -302,25 +274,22 @@ for (const layout of ["standard", "diff", "worker"] as const) {
});
test(`${layout}: malformed deferred identity cannot poison subsequent writes`, async (t) => {
const f = await fixture(t, layout);
- await f.write(
- f.draft({
- deferred: [
- {
- id: "review",
- candidateId: "review",
- ...generic,
- finding: {
- ...findingFor("review"),
- identity: { anchor: ".invalid" },
- },
+ await f.writeReviewState({
+ deferred: [
+ {
+ id: "review",
+ candidateId: "review",
+ ...generic,
+ finding: {
+ ...findingFor("review"),
+ identity: { anchor: ".invalid" },
},
- ],
- }),
- );
- const submitted = {
- ...f.draft({}, true),
- findings: [findingFor("review")],
- };
+ },
+ ],
+ });
+ const submitted = f.findingsDraft([findingFor("review")], {
+ complete: true,
+ });
await f.write(submitted);
await f.write(submitted);
});
@@ -330,7 +299,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
test(`${layout}: parent checkpoint updates retain semantic scope metadata`, async (t) => {
const f = await fixture(t, layout);
await f.write({ ...f.draft(), scope: { summary: "Archive handling" } });
- await f.write(f.draft());
+ await f.writeReviewState();
const saved = await readJson(f.root, "scan-manifest.json");
assert.equal(saved.scan.scope.summary, "Archive handling");
assert.deepEqual(saved.scan.scope.includePaths, ["."]);
@@ -372,7 +341,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
// An empty tool update retains file-authored canonical history. Repeating
// it also reads the checkpoint produced by the first reconciliation.
for (let attempt = 0; attempt < 2; attempt++) {
- await f.write(f.draft());
+ await f.writeReviewState();
const saved = await readJson(f.root, name);
if (variant === "surface ID")
assert(
@@ -416,14 +385,12 @@ for (const layout of ["standard", "diff"] as const) {
disposition: "needs_follow_up",
receiptRefs: ["artifacts/original.md"],
};
- await f.write(
- f.draft({
- surfaces: [surface],
- deferred: [
- { id: "review", reason: "Review remains.", surfaceIds: ["api"] },
- ],
- }),
- );
+ await f.writeReviewState({
+ surfaces: [surface],
+ deferred: [
+ { id: "review", reason: "Review remains.", surfaceIds: ["api"] },
+ ],
+ });
await rm(path.join(f.root, "artifacts/original.md"));
const result = await recordCodexSecurityScanDraftViaWorkbench(
f.context,
@@ -475,7 +442,7 @@ for (const source of ["title", "candidateId", "reportId", "ledgerRowId"]) {
? { title: value, provenance: { source: "local_plugin" } }
: { extensions: { [source]: value } }),
};
- const draft = { ...f.draft(), findings: [finding] };
+ const draft = f.findingsDraft([finding]);
await f.write(draft);
const saved = (await readJson(f.root, "findings.json")).findings[0];
await f.write(draft);
@@ -494,20 +461,18 @@ for (const source of ["title", "candidateId", "reportId", "ledgerRowId"]) {
test("worker checkpoints retain typed surface IDs", async (t) => {
const f = await fixture(t, "worker");
- await f.write(
- f.draft({
- surfaces: [
- { id: "http-api", label: "HTTP API", disposition: "no_issue_found" },
- ],
- }),
- );
+ await f.writeReviewState({
+ surfaces: [
+ { id: "http-api", label: "HTTP API", disposition: "no_issue_found" },
+ ],
+ });
const head = await readJson(f.root, "checkpoint-head.json");
const checkpointPath = path.join(f.root, "checkpoints", head.checkpoint);
const checkpoint = await readJson(checkpointPath);
checkpoint.reviewState.surfaces[0].id = "HTTP API";
await writeJson(checkpointPath, checkpoint);
await assert.rejects(
- f.write(f.draft({ deferred: [generic] })),
+ f.writeReviewState({ deferred: [generic] }),
/Invalid string/,
);
});
@@ -515,9 +480,11 @@ test("worker checkpoints retain typed surface IDs", async (t) => {
test("parent: resume provisional deferred paths until the task is closed", async (t) => {
const f = await fixture(t, "standard");
const pending = { id: "review", ...generic, paths: ["../outside"] };
- await f.write(f.draft({ deferred: [pending] }));
- assert.deepEqual((await f.write(f.draft())).reviewState.deferred, [pending]);
- await f.write(f.draft({ resolvedDeferred: [close(pending.id)] }, true));
+ await f.writeReviewState({ deferred: [pending] });
+ assert.deepEqual((await f.writeReviewState()).reviewState.deferred, [
+ pending,
+ ]);
+ await f.writeReviewState({ resolvedDeferred: [close(pending.id)] }, true);
assert.deepEqual((await f.read()).deferred, []);
});
@@ -527,9 +494,9 @@ for (const observation of ["checkpoint head", "worker result"]) {
const task = { id: "review", ...generic };
const headPath = path.join(f.root, "checkpoint-head.json");
const resultPath = path.join(f.root, "result.json");
- await f.write(f.draft({ deferred: [task] }));
+ await f.writeReviewState({ deferred: [task] });
const reopenedHead = await readJson(headPath);
- await f.write(f.draft({ resolvedDeferred: [close(task.id)] }, true));
+ await f.writeReviewState({ resolvedDeferred: [close(task.id)] }, true);
assert.deepEqual((await f.read()).deferred, []);
const checkpoints = path.join(f.root, "checkpoints");
for (const name of await readdir(checkpoints)) {
@@ -596,7 +563,7 @@ for (const observation of ["checkpoint head", "worker result"]) {
return handle;
}) as typeof fsPromises.open);
}
- const result = await f.write(f.draft({}, true));
+ const result = await f.writeReviewState({}, true);
assert.equal(replaced, true);
for (const reviewState of [result.reviewState, await f.read()]) {
assert.deepEqual(reviewState.deferred, [task]);
@@ -614,7 +581,7 @@ for (const headTime of [1, 2, 3]) {
disposition: "no_issue_found",
receiptRefs: [],
});
- await f.write(f.draft({ surfaces: [surface("existing")] }, true));
+ await f.writeReviewState({ surfaces: [surface("existing")] }, true);
const added = {
surfaces: [surface("newly-reviewed")],
explicitExclusions: [
@@ -626,11 +593,9 @@ for (const headTime of [1, 2, 3]) {
};
const resultPath = path.join(f.root, "result.json");
await interruptDraftWrite(resultPath, () =>
- f.write(
- f.draft(
- { ...added, surfaces: [surface("existing"), ...added.surfaces] },
- true,
- ),
+ f.writeReviewState(
+ { ...added, surfaces: [surface("existing"), ...added.surfaces] },
+ true,
),
);
const headPath = path.join(f.root, "checkpoint-head.json");
@@ -708,17 +673,13 @@ for (const updateSavedSurface of [false, true]) {
disposition: "no_issue_found",
notes: "Initial review.",
};
- await f.write(
- f.draft({
- deferred: [reopened, stillClosed],
- surfaces: updateSavedSurface ? [independentSurface] : [],
- }),
- );
- await f.write(
- f.draft(
- { resolvedDeferred: [close(reopened.id), close(stillClosed.id)] },
- true,
- ),
+ await f.writeReviewState({
+ deferred: [reopened, stillClosed],
+ surfaces: updateSavedSurface ? [independentSurface] : [],
+ });
+ await f.writeReviewState(
+ { resolvedDeferred: [close(reopened.id), close(stillClosed.id)] },
+ true,
);
const independent = { id: "independent-review", ...generic };
const finding = {
@@ -902,9 +863,9 @@ for (const layout of ["standard", "diff", "worker"] as const) {
};
const a = { id: "a", ...generic, surfaceIds: [first.id] };
const b = { id: "b", ...generic, surfaceIds: [first.id] };
- await f.write(f.draft({ surfaces: [first, second], deferred: [a, b] }));
+ await f.writeReviewState({ surfaces: [first, second], deferred: [a, b] });
const moved = { ...a, surfaceIds: [second.id] };
- await f.write(f.draft({ deferred: [moved] }));
+ await f.writeReviewState({ deferred: [moved] });
for (const input of [
f.draft(
{
@@ -934,11 +895,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
test(`${layout}: a legacy ID-less checkpoint retains one closable task through host snapshots`, async (t) => {
const f = await fixture(t, layout);
- await saveScanDraftCheckpoint(
- f.context,
- f.draft({ deferred: [generic] }),
- false,
- );
+ await f.checkpoint(f.draft({ deferred: [generic] }));
let id;
for (const canonicalParent of [undefined, false, true]) {
if (canonicalParent !== undefined) {
@@ -958,13 +915,13 @@ for (const layout of ["standard", "diff", "worker"] as const) {
await writeFile(path.join(f.root, "checkpoints", checkpoint), contents);
await writeJson(headPath, { checkpoint });
}
- const result = await f.write(f.draft({}, true));
+ const result = await f.writeReviewState({}, true);
assert.equal(result.reviewState.deferred.length, 1);
id ??= result.reviewState.deferred[0].id;
assert.equal(result.reviewState.deferred[0].id, id);
}
- await f.write(f.draft({ resolvedDeferred: [close(id)] }, true));
- const retried = await f.write(f.draft({}, true));
+ await f.writeReviewState({ resolvedDeferred: [close(id)] }, true);
+ const retried = await f.writeReviewState({}, true);
assert.deepEqual(retried.reviewState.deferred, []);
assert.deepEqual(retried.reviewState.resolvedDeferred, [close(id)]);
});
@@ -974,16 +931,12 @@ for (const layout of ["standard", "diff", "worker"] as const) {
const f = await fixture(t, layout);
const surface = { label: "Uploads", disposition: "needs_follow_up" };
if (hasPublishedId) {
- await f.write(
- f.draft({ surfaces: [{ ...surface, id: "surface_uploads" }] }),
- );
+ await f.writeReviewState({
+ surfaces: [{ ...surface, id: "surface_uploads" }],
+ });
}
- await saveScanDraftCheckpoint(
- f.context,
- f.draft({ surfaces: [surface], deferred: [generic] }),
- false,
- );
- const restored = await f.write(f.draft({}, true));
+ await f.checkpoint(f.draft({ surfaces: [surface], deferred: [generic] }));
+ const restored = await f.writeReviewState({}, true);
assert.equal(restored.reviewState.surfaces.length, 1);
const restoredSurface = restored.reviewState.surfaces[0];
if (hasPublishedId) assert.equal(restoredSurface.id, "surface_uploads");
@@ -1009,23 +962,21 @@ for (const layout of ["standard", "diff", "worker"] as const) {
test(`${layout}: inheriting a candidate outcome keeps newer follow-up work`, async (t) => {
const f = await fixture(t, layout);
const surface = { id: "api", label: "API", disposition: "needs_follow_up" };
- await f.write(
- f.draft({
- deferred: [
- {
- id: "candidate-review",
- candidateId: "candidate-review",
- ...generic,
- },
- ],
- surfaces: [surface],
- }),
- );
+ await f.writeReviewState({
+ deferred: [
+ {
+ id: "candidate-review",
+ candidateId: "candidate-review",
+ ...generic,
+ },
+ ],
+ surfaces: [surface],
+ });
await f.write({
...f.draft({ surfaces: [surface] }),
findings: [findingFor("candidate-review")],
});
- const result = await f.write(f.draft({}, true));
+ const result = await f.writeReviewState({}, true);
assert.equal(result.findingCount, 1);
assert.deepEqual(result.reviewState.surfaces.map(surfaceDisposition), [
@@ -1042,7 +993,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
...generic,
};
const independent = { id: "independent-review", ...generic };
- await f.write(f.draft({ deferred: [pending, independent] }));
+ await f.writeReviewState({ deferred: [pending, independent] });
const terminal = f.draft(
{ resolvedDeferred: [close(pending.id), close(pending.candidateId)] },
true,
@@ -1078,13 +1029,13 @@ for (const layout of ["standard", "diff", "worker"] as const) {
const first = { id: "review", ...generic };
const second = { ...first, paths: ["src/other.py"] };
await assert.rejects(
- f.write(f.draft({ deferred: [first, second] })),
+ f.writeReviewState({ deferred: [first, second] }),
/reviewState.deferred repeats review/,
);
assert.deepEqual(await readdir(f.root), []);
second.id = "other-review";
- await f.write(f.draft({ deferred: [first, second] }));
- await f.write(f.draft({ resolvedDeferred: [close(first.id)] }, true));
+ await f.writeReviewState({ deferred: [first, second] });
+ await f.writeReviewState({ resolvedDeferred: [close(first.id)] }, true);
assert.deepEqual((await f.read()).deferred, [second]);
});
@@ -1096,13 +1047,9 @@ for (const layout of ["standard", "diff", "worker"] as const) {
{ id: "review", reason: "Review storage.", paths: ["src/storage.py"] },
];
if (savedIn === "checkpoint") {
- await saveScanDraftCheckpoint(
- f.context,
- f.draft({ deferred: tasks }),
- false,
- );
+ await f.checkpoint(f.draft({ deferred: tasks }));
} else {
- await f.write(f.draft({ deferred: [tasks[0]] }));
+ await f.writeReviewState({ deferred: [tasks[0]] });
await rm(path.join(f.root, "checkpoint-head.json"), { force: true });
await rm(path.join(f.root, "checkpoints"), { recursive: true });
const filename = path.join(
@@ -1127,19 +1074,19 @@ for (const layout of ["standard", "diff", "worker"] as const) {
const original = await snapshot();
for (let attempt = 0; attempt < 2; attempt += 1) {
await assert.rejects(
- f.write(f.draft({ resolvedDeferred: [close("review")] }, true)),
+ f.writeReviewState({ resolvedDeferred: [close("review")] }, true),
/cannot close ambiguous saved deferred work: review/,
);
assert.deepEqual(await snapshot(), original);
}
for (let attempt = 0; attempt < 2; attempt += 1) {
- const recovered = await f.write(f.draft({}, true));
+ const recovered = await f.writeReviewState({}, true);
assert.deepEqual(recovered.reviewState.deferred, tasks);
assert.deepEqual(recovered.reviewState.resolvedDeferred ?? [], []);
const beforeClosure = await snapshot();
await assert.rejects(
- f.write(f.draft({ resolvedDeferred: [close("review")] }, true)),
+ f.writeReviewState({ resolvedDeferred: [close("review")] }, true),
/cannot close ambiguous saved deferred work: review/,
);
assert.deepEqual(await snapshot(), beforeClosure);
@@ -1149,12 +1096,12 @@ for (const layout of ["standard", "diff", "worker"] as const) {
test(`${layout}: returned deferred IDs support closure, retries and explicit reopening`, async (t) => {
const f = await fixture(t, layout);
- const initial = await f.write(f.draft({ deferred: [generic] }));
+ const initial = await f.writeReviewState({ deferred: [generic] });
const original = initial.reviewState.deferred[0];
assert.equal(typeof original.id, "string");
assert.deepEqual(initial.reviewState, await f.read());
const enriched = { ...original, notes: "Both callers were inspected." };
- const updatedDraft = await f.write(f.draft({ deferred: [enriched] }));
+ const updatedDraft = await f.writeReviewState({ deferred: [enriched] });
assert.deepEqual(updatedDraft.reviewState.deferred, [enriched]);
const checkpointRoot = path.join(f.root, "checkpoints");
const originals = await Promise.all(
@@ -1164,13 +1111,13 @@ for (const layout of ["standard", "diff", "worker"] as const) {
]),
);
const closure = close(original.id);
- await f.write(f.draft({ resolvedDeferred: [closure] }, true));
+ await f.writeReviewState({ resolvedDeferred: [closure] }, true);
const updated = close(
original.id,
"A second review confirmed the decision.",
);
- await f.write(f.draft({ resolvedDeferred: [updated] }, true));
- await f.write(f.draft({}, true));
+ await f.writeReviewState({ resolvedDeferred: [updated] }, true);
+ await f.writeReviewState({}, true);
const saved = await f.read();
assert.deepEqual(saved.deferred, []);
@@ -1181,9 +1128,9 @@ for (const layout of ["standard", "diff", "worker"] as const) {
contents,
);
const reopened = { ...original, reason: "A new caller needs review." };
- await f.write(f.draft({ deferred: [reopened] }, true));
+ await f.writeReviewState({ deferred: [reopened] }, true);
for (const complete of [false, true]) {
- await f.write(f.draft({}, complete));
+ await f.writeReviewState({}, complete);
const pending = await f.read();
assert.deepEqual(pending.deferred, [reopened]);
@@ -1204,27 +1151,25 @@ for (const layout of ["standard", "diff", "worker"] as const) {
},
};
const independent = { id: "source-review", ...generic };
- await f.write(f.draft({ deferred: [pending, independent] }));
+ await f.writeReviewState({ deferred: [pending, independent] });
const closure = close(independent.id);
- await f.write(f.draft({ resolvedDeferred: [closure] }, true));
- await f.write(f.draft({}, true));
+ await f.writeReviewState({ resolvedDeferred: [closure] }, true);
+ await f.writeReviewState({}, true);
assert.deepEqual((await f.read()).deferred, [pending]);
- await f.write(
- f.draft(
- {
- surfaces: [
- {
- id: "candidate-outcome",
- candidateId: pending.candidateId,
- label: "Caller",
- disposition: "rejected",
- },
- ],
- },
- true,
- ),
+ await f.writeReviewState(
+ {
+ surfaces: [
+ {
+ id: "candidate-outcome",
+ candidateId: pending.candidateId,
+ label: "Caller",
+ disposition: "rejected",
+ },
+ ],
+ },
+ true,
);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
const saved = await f.read();
assert.deepEqual(saved.deferred, []);
assert.deepEqual(saved.resolvedDeferred, [closure]);
@@ -1254,15 +1199,15 @@ for (const layout of ["standard", "diff", "worker"] as const) {
...(payload === "generic" ? {} : { candidateId: "candidate-review" }),
};
const raw = { ...generic, ...evidence };
- await f.write(f.draft({ deferred: [named] }));
+ await f.writeReviewState({ deferred: [named] });
await interruptDraftWrite(
path.join(
f.root,
layout === "worker" ? "result.json" : "coverage.json",
),
- () => f.write(f.draft({ deferred: [raw] })),
+ () => f.writeReviewState({ deferred: [raw] }),
);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
const saved = await f.read();
assert.deepEqual(
@@ -1288,8 +1233,8 @@ for (const layout of ["standard", "diff", "worker"] as const) {
},
],
};
- await f.write(f.draft(outcome, true));
- await f.write(f.draft({}, true));
+ await f.writeReviewState(outcome, true);
+ await f.writeReviewState({}, true);
assert.deepEqual((await f.read()).deferred, [independent]);
});
}
@@ -1308,30 +1253,24 @@ for (const layout of ["standard", "diff", "worker"] as const) {
id: "another-api",
notes: "Independent entry point.",
};
- await f.write(
- f.draft({
- surfaces: [surface, other],
- deferred: [
- { id: "api-review", ...generic, surfaceIds: [surface.id] },
+ await f.writeReviewState({
+ surfaces: [surface, other],
+ deferred: [{ id: "api-review", ...generic, surfaceIds: [surface.id] }],
+ });
+ await f.writeReviewState(
+ {
+ resolvedDeferred: [close("api-review")],
+ surfaces: [
+ {
+ ...(submittedId ? { id: submittedId } : {}),
+ label: surface.label,
+ disposition: "no_issue_found",
+ },
],
- }),
- );
- await f.write(
- f.draft(
- {
- resolvedDeferred: [close("api-review")],
- surfaces: [
- {
- ...(submittedId ? { id: submittedId } : {}),
- label: surface.label,
- disposition: "no_issue_found",
- },
- ],
- },
- true,
- ),
+ },
+ true,
);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
const saved = await f.read();
assert.deepEqual(saved.deferred, []);
assert.deepEqual(
@@ -1374,28 +1313,27 @@ for (const layout of ["standard", "diff", "worker"] as const) {
notes: "The second caller still needs review.",
receiptRefs: ["artifacts/pending.md"],
};
- await f.write(
- f.draft({ surfaces: [surface], deferred: [first, remaining] }),
- );
+ await f.writeReviewState({
+ surfaces: [surface],
+ deferred: [first, remaining],
+ });
const closure = close(first.id);
for (const resolvedDeferred of [[closure], [closure], undefined]) {
- await f.write(
- f.draft(
- resolvedDeferred
- ? {
- resolvedDeferred,
- surfaces: [
- {
- ...surface,
- disposition: "no_issue_found",
- notes: "The first caller is reviewed.",
- receiptRefs: ["artifacts/reviewed.md"],
- },
- ],
- }
- : {},
- true,
- ),
+ await f.writeReviewState(
+ resolvedDeferred
+ ? {
+ resolvedDeferred,
+ surfaces: [
+ {
+ ...surface,
+ disposition: "no_issue_found",
+ notes: "The first caller is reviewed.",
+ receiptRefs: ["artifacts/reviewed.md"],
+ },
+ ],
+ }
+ : {},
+ true,
);
const saved = await f.read();
@@ -1421,7 +1359,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
disposition: "needs_follow_up",
receiptRefs: ["artifacts/original.md"],
};
- await f.write(f.draft({ deferred: [pending], surfaces: [surface] }));
+ await f.writeReviewState({ deferred: [pending], surfaces: [surface] });
const closed = f.draft(
{
resolvedDeferred: [close(pending.id)],
@@ -1456,13 +1394,11 @@ for (const layout of ["standard", "diff", "worker"] as const) {
observation === "surface-only"
? []
: [{ ...pending, reason: followUp.notes }];
- await saveScanDraftCheckpoint(
- f.context,
+ await f.checkpoint(
f.draft(
{ deferred, surfaces: [followUp] },
observation === "terminal" || observation === "tied",
),
- false,
);
for (const name of await readdir(checkpoints)) {
if (!before.has(name)) {
@@ -1471,7 +1407,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
}
}
for (const complete of [true, false, true]) {
- await f.write(f.draft({}, complete));
+ await f.writeReviewState({}, complete);
const saved = await f.read();
assert.deepEqual(saved.deferred, deferred);
@@ -1514,7 +1450,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
interruptDraftWrite(path.join(f.root, destination), () =>
f.write(input),
);
- await f.write(f.draft({ deferred: [pending] }));
+ await f.writeReviewState({ deferred: [pending] });
const checkpoints = path.join(f.root, "checkpoints");
for (const name of await readdir(checkpoints))
await utimes(path.join(checkpoints, name), 1, 1);
@@ -1523,7 +1459,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
: ["coverage.json", "scan-manifest.json", "findings.json"])
await utimes(path.join(f.root, name), 1, 1);
await fail(closing);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
assert.deepEqual((await f.read()).deferred, []);
assert.deepEqual((await f.read()).resolvedDeferred, [close(pending.id)]);
const checkpointRoot = path.join(f.root, "checkpoints");
@@ -1545,7 +1481,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
reason: "A newly inspected caller needs review.",
};
await fail(f.draft({ deferred: [reopened] }, true));
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
const saved = await f.read();
assert.deepEqual(saved.deferred, [reopened]);
@@ -1555,11 +1491,11 @@ for (const layout of ["standard", "diff", "worker"] as const) {
assert.deepEqual(await readFile(file), bytes);
if (fixedTime) assert.equal((await stat(file)).mtimeMs, modified);
}
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
const accepted = layout !== "worker" || destination === "result.json";
assert.deepEqual((await f.read()).deferred, accepted ? [] : [reopened]);
await f.write(closing);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
assert.deepEqual((await f.read()).deferred, []);
assert.deepEqual((await f.read()).resolvedDeferred, [close(pending.id)]);
});
@@ -1572,7 +1508,7 @@ test("worker: inherited closures cannot erase ambiguous legacy tasks", async (t)
{ id: "review", ...generic },
{ id: "review", reason: "Review storage.", paths: ["src/storage.py"] },
];
- await saveScanDraftCheckpoint(f.context, f.draft({ deferred: tasks }), false);
+ await f.checkpoint(f.draft({ deferred: tasks }));
await saveScanDraftCheckpoint(
f.context,
f.draft({ resolvedDeferred: [close("review")] }, true),
@@ -1585,7 +1521,7 @@ test("worker: inherited closures cannot erase ambiguous legacy tasks", async (t)
await utimes(filename, timestamp, timestamp);
}
for (let attempt = 0; attempt < 2; attempt += 1) {
- const recovered = await f.write(f.draft({}, true));
+ const recovered = await f.writeReviewState({}, true);
assert.deepEqual(recovered.reviewState.deferred, tasks);
assert.deepEqual(recovered.reviewState.resolvedDeferred ?? [], []);
@@ -1596,7 +1532,7 @@ for (const layout of ["standard", "diff"] as const) {
for (const taskCount of [1, 2]) {
test(`${layout}: an upgraded checkpoint retains ${taskCount} older canonical task IDs`, async (t) => {
const f = await fixture(t, layout);
- await f.write(f.draft({ deferred: [generic] }));
+ await f.writeReviewState({ deferred: [generic] });
const legacyId = `deferred-${hash(
"sha256",
JSON.stringify([generic.reason, generic.paths, []]),
@@ -1614,29 +1550,26 @@ for (const layout of ["standard", "diff"] as const) {
recursive: true,
force: true,
});
- await saveScanDraftCheckpoint(
- f.context,
+ await f.checkpoint(
f.draft({ deferred: Array.from({ length: taskCount }, () => generic) }),
- false,
);
- const resumed = await f.write(f.draft({}, true));
+ const resumed = await f.writeReviewState({}, true);
assert.deepEqual(resumed.reviewState.deferred, named);
- const partlyClosed = await f.write(
- f.draft({ resolvedDeferred: [close(legacyId)] }, true),
+ const partlyClosed = await f.writeReviewState(
+ { resolvedDeferred: [close(legacyId)] },
+ true,
);
assert.deepEqual(partlyClosed.reviewState.deferred, named.slice(1));
if (taskCount > 1)
- await f.write(
- f.draft(
- {
- resolvedDeferred: named
- .slice(1)
- .map(({ id }: { id: string }) => close(id)),
- },
- true,
- ),
+ await f.writeReviewState(
+ {
+ resolvedDeferred: named
+ .slice(1)
+ .map(({ id }: { id: string }) => close(id)),
+ },
+ true,
);
- const retried = await f.write(f.draft({}, true));
+ const retried = await f.writeReviewState({}, true);
assert.deepEqual(retried.reviewState.deferred, []);
assert.deepEqual(
new Set(
@@ -1659,12 +1592,10 @@ for (const layout of ["standard", "diff"] as const) {
disposition: "needs_follow_up",
receiptRefs: ["artifacts/api-review.md"],
};
- await f.write(
- f.draft({
- surfaces: [surface],
- deferred: [{ id: "review", ...generic, surfaceIds: [surface.id] }],
- }),
- );
+ await f.writeReviewState({
+ surfaces: [surface],
+ deferred: [{ id: "review", ...generic, surfaceIds: [surface.id] }],
+ });
const resolvedDeferred = [close("review")];
const closed = f.draft(
{
@@ -1694,7 +1625,7 @@ for (const layout of ["standard", "diff"] as const) {
/interrupted draft write/,
);
for (const reviewState of [{}, { resolvedDeferred }, {}]) {
- await f.write(f.draft(reviewState, true));
+ await f.writeReviewState(reviewState, true);
const saved = await f.read();
assert.deepEqual(saved.deferred, []);
@@ -1737,35 +1668,31 @@ for (const layout of ["standard", "diff", "worker"] as const) {
assert.deepEqual(checkpoint.reviewState.surfaces[0].receiptRefs, []);
assert.equal(checkpoint.reviewState.deferred[0].id, task.id);
}
- const linked = await f.write(
- f.draft({
- surfaces: [surface],
- deferred: [
- {
- ...task,
- surfaceIds: [surface.id],
- notes: "Both callers inspected.",
- },
- ],
- }),
- );
- assert.equal(linked.reviewState.deferred.length, 1);
- assert.equal(linked.reviewState.deferred[0].id, task.id);
- const terminal = await f.write(
- f.draft(
+ const linked = await f.writeReviewState({
+ surfaces: [surface],
+ deferred: [
{
- surfaces: [{ ...surface, disposition: "no_issue_found" }],
- resolvedDeferred: [close(task.id)],
+ ...task,
+ surfaceIds: [surface.id],
+ notes: "Both callers inspected.",
},
- true,
- ),
+ ],
+ });
+ assert.equal(linked.reviewState.deferred.length, 1);
+ assert.equal(linked.reviewState.deferred[0].id, task.id);
+ const terminal = await f.writeReviewState(
+ {
+ surfaces: [{ ...surface, disposition: "no_issue_found" }],
+ resolvedDeferred: [close(task.id)],
+ },
+ true,
);
assert.deepEqual(terminal.reviewState.deferred, []);
assert.deepEqual(terminal.reviewState.surfaces, [
{ ...surface, disposition: "no_issue_found", receiptRefs: [] },
]);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
assert.deepEqual(await f.read(), terminal.reviewState);
});
}
@@ -1778,20 +1705,20 @@ test("worker: duplicate authored surface IDs preserve each observation", async (
{ id: "api", label: "Second API", disposition: "needs_follow_up" },
{ id: "api-2", label: "Existing API", disposition: "needs_follow_up" },
];
- const initial = await f.write(f.draft({ surfaces: rows }));
+ const initial = await f.writeReviewState({ surfaces: rows });
assert.deepEqual(
initial.reviewState.surfaces.map(({ id }: { id: string }) => id),
["api", "api-3", "api-2"],
);
assert.deepEqual(
- (await f.write(f.draft({ surfaces: rows }))).reviewState.surfaces,
+ (await f.writeReviewState({ surfaces: rows })).reviewState.surfaces,
initial.reviewState.surfaces,
);
const updated = initial.reviewState.surfaces.map(
(row: Record<string, unknown>) =>
row.id === "api-3" ? { ...row, disposition: "no_issue_found" } : row,
);
- const saved = await f.write(f.draft({ surfaces: updated }));
+ const saved = await f.writeReviewState({ surfaces: updated });
assert.equal(saved.reviewState.surfaces.length, 3);
assert.equal(
saved.reviewState.surfaces.find(({ id }: { id: string }) => id === "api")
@@ -1812,14 +1739,15 @@ test("worker: surface IDs remain valid independently of candidate names", async
label: "API",
disposition: "needs_follow_up",
};
- const initial = await f.write(f.draft({ surfaces: [candidate] }));
+ const initial = await f.writeReviewState({ surfaces: [candidate] });
const [surface] = initial.reviewState.surfaces;
assert.match(surface.id, /^[a-z0-9][a-z0-9._/-]*$/u);
assert.equal(surface.candidateId, candidate.candidateId);
- await f.write(
- f.draft({ surfaces: [{ ...surface, disposition: "rejected" }] }, true),
+ await f.writeReviewState(
+ { surfaces: [{ ...surface, disposition: "rejected" }] },
+ true,
);
- const retried = await f.write(f.draft({}, true));
+ const retried = await f.writeReviewState({}, true);
assert.deepEqual(retried.reviewState.surfaces, [
{ ...surface, disposition: "rejected" },
]);
@@ -1843,7 +1771,7 @@ test("worker: generated surface IDs preserve distinct observations and reserved
initial.reviewState.surfaces,
);
const changed = { ...first, notes: "A newly found caller." };
- const updated = await f.write(f.draft({ surfaces: [changed] }));
+ const updated = await f.writeReviewState({ surfaces: [changed] });
assert.equal(updated.reviewState.surfaces.length, 3);
assert.ok(
updated.reviewState.surfaces.some(
@@ -1858,7 +1786,7 @@ test("worker: generated surface IDs preserve distinct observations and reserved
{ ...changed, id: ids[0] },
{ label: "Candidate", disposition: "needs_follow_up", candidateId: ids[1] },
];
- const saved = (await other.write(other.draft({ surfaces: reserved })))
+ const saved = (await other.writeReviewState({ surfaces: reserved }))
.reviewState.surfaces;
assert.equal(new Set(saved.map(({ id }: { id: string }) => id)).size, 4);
assert.equal(saved[2].id, ids[0]);
@@ -1881,16 +1809,16 @@ test("worker: generated surface IDs preserve distinct observations and reserved
test("worker: archived closures cannot discard a later explicitly reopened task", async (t) => {
const f = await fixture(t, "worker");
const pending = { id: "review", ...generic };
- await f.write(f.draft({ deferred: [pending] }));
- await f.write(f.draft({ resolvedDeferred: [close(pending.id)] }, true));
+ await f.writeReviewState({ deferred: [pending] });
+ await f.writeReviewState({ resolvedDeferred: [close(pending.id)] }, true);
const attempts = path.join(path.dirname(f.root), "attempts");
await mkdir(attempts);
await rename(f.root, path.join(attempts, "attempt-01"));
await mkdir(f.root);
- await f.write(f.draft({ deferred: [pending] }, true));
+ await f.writeReviewState({ deferred: [pending] }, true);
await rename(f.root, path.join(attempts, "attempt-02"));
await mkdir(f.root);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
assert.deepEqual((await f.read()).deferred, [pending]);
assert.deepEqual((await f.read()).resolvedDeferred ?? [], []);
});
@@ -1900,13 +1828,13 @@ for (const layout of ["standard", "diff"] as const) {
test(`${layout}: parent checkpoint selection at ${selectedTime} orders a closure`, async (t) => {
const f = await fixture(t, layout);
const pending = { id: "review", ...generic };
- await f.write(f.draft({ deferred: [pending] }));
+ await f.writeReviewState({ deferred: [pending] });
const closed = f.draft(
{ resolvedDeferred: [{ id: pending.id, reason: "Callers reviewed." }] },
true,
);
await f.write(closed);
- await f.write(f.draft({ deferred: [pending] }));
+ await f.writeReviewState({ deferred: [pending] });
let selected;
for (const name of await readdir(path.join(f.root, "checkpoints"))) {
const file = path.join(f.root, "checkpoints", name);
@@ -1926,7 +1854,7 @@ for (const layout of ["standard", "diff"] as const) {
const head = path.join(f.root, "checkpoint-head.json");
await writeJson(head, { checkpoint: selected });
await utimes(head, selectedTime, selectedTime);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
const saved = await f.read();
if (selectedTime > 200) {
assert.deepEqual(saved.deferred, []);
@@ -1957,12 +1885,8 @@ for (const payload of ["generic", "candidate"] as const) {
notes: "Saved caller context.",
...(payload === "candidate" ? { candidateId: "named-candidate" } : {}),
};
- await f.write(f.draft({ deferred: [named] }));
- await saveScanDraftCheckpoint(
- f.context,
- f.draft({ deferred: [raw] }),
- false,
- );
+ await f.writeReviewState({ deferred: [named] });
+ await f.checkpoint(f.draft({ deferred: [raw] }));
const outcome =
payload === "generic"
? { resolvedDeferred: [close(named.id)] }
@@ -1975,8 +1899,8 @@ for (const payload of ["generic", "candidate"] as const) {
},
],
};
- await f.write(f.draft(outcome, true));
- await f.write(f.draft({}, true));
+ await f.writeReviewState(outcome, true);
+ await f.writeReviewState({}, true);
const saved = await f.read();
assert.ok(saved.deferred.length > 0);
@@ -2004,7 +1928,7 @@ for (const complete of [false, true]) {
submitted,
);
await rm(destination);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
assert.deepEqual((await f.read()).deferred, submitted.reviewState.deferred);
});
}
@@ -2014,15 +1938,11 @@ for (const malformed of [false, true]) {
const f = await fixture(t, "worker");
if (malformed) await writeFile(path.join(f.root, "result.json"), "{broken");
await assert.rejects(
- f.write(
- f.draft(
- {
- resolvedDeferred: [
- { id: "unknown", reason: "Unsupported closure." },
- ],
- },
- true,
- ),
+ f.writeReviewState(
+ {
+ resolvedDeferred: [{ id: "unknown", reason: "Unsupported closure." }],
+ },
+ true,
),
malformed
? /stored JSON is malformed/
@@ -2037,9 +1957,9 @@ for (const layout of ["standard", "diff", "worker"] as const) {
test(`${layout}: accepted progress remains incomplete after a terminal draft, reopened=${reopened}`, async (t) => {
const f = await fixture(t, layout);
const task = { id: "review", ...generic };
- await f.write(f.draft({ deferred: [task] }, true));
+ await f.writeReviewState({ deferred: [task] }, true);
if (reopened)
- await f.write(f.draft({ resolvedDeferred: [close(task.id)] }, true));
+ await f.writeReviewState({ resolvedDeferred: [close(task.id)] }, true);
for (const input of [f.draft({ deferred: [task] }), f.draft()]) {
await f.write(input);
const published = await readJson(
@@ -2061,7 +1981,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
assert.deepEqual(checkpoint.reviewState.deferred, [task]);
}
}
- await f.write(f.draft({ resolvedDeferred: [close(task.id)] }, true));
+ await f.writeReviewState({ resolvedDeferred: [close(task.id)] }, true);
const finished = await readJson(
f.root,
layout === "worker" ? "result.json" : "scan-manifest.json",
@@ -2082,22 +2002,23 @@ for (const layout of ["standard", "diff", "worker"] as const) {
notes: "Initial evidence",
receiptRefs: ["artifacts/initial.md"],
};
- await f.write(
- f.draft({ completeness: "partial", surfaces: [initial] }, true),
+ await f.writeReviewState(
+ { completeness: "partial", surfaces: [initial] },
+ true,
);
const updated = {
...initial,
notes: "Updated evidence",
receiptRefs: ["artifacts/updated.md"],
};
- await f.write(f.draft({ surfaces: [updated] }));
+ await f.writeReviewState({ surfaces: [updated] });
assert.deepEqual(
(await f.read()).surfaces.find(
(row: { id: string }) => row.id === initial.id,
),
updated,
);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
assert.deepEqual(
(await f.read()).surfaces.find(
(row: { id: string }) => row.id === initial.id,
@@ -2113,13 +2034,11 @@ for (const layout of ["standard", "diff", "worker"] as const) {
label: "Existing review",
disposition: "no_issue_found",
};
- await f.write(f.draft({ surfaces: [reviewed] }, true));
- await f.write(
- f.draft({
- surfaces: [{ ...reviewed, disposition: "needs_follow_up" }],
- deferred: [{ id: "new-review", ...generic }],
- }),
- );
+ await f.writeReviewState({ surfaces: [reviewed] }, true);
+ await f.writeReviewState({
+ surfaces: [{ ...reviewed, disposition: "needs_follow_up" }],
+ deferred: [{ id: "new-review", ...generic }],
+ });
const coverage = await f.read();
assert.equal(
coverage.surfaces.find((row: { id: string }) => row.id === reviewed.id)
@@ -2142,11 +2061,9 @@ for (const layout of ["standard", "diff", "worker"] as const) {
};
const prior = { id: "prior-review", ...generic };
const later = { id: "later-review", ...generic };
- await f.write(
- f.draft(
- { surfaces: [reviewed], deferred: pendingBefore ? [prior] : [] },
- true,
- ),
+ await f.writeReviewState(
+ { surfaces: [reviewed], deferred: pendingBefore ? [prior] : [] },
+ true,
);
const followUp = {
...reviewed,
@@ -2178,17 +2095,15 @@ for (const layout of ["standard", "diff", "worker"] as const) {
if (pendingBefore || pendingAfter) assert.equal(complete, false);
else assert.notEqual(complete, false);
}
- await f.write(
- f.draft(
- {
- surfaces: [reviewed],
- resolvedDeferred: [
- ...(pendingBefore ? [close(prior.id)] : []),
- ...(pendingAfter ? [close(later.id)] : []),
- ],
- },
- true,
- ),
+ await f.writeReviewState(
+ {
+ surfaces: [reviewed],
+ resolvedDeferred: [
+ ...(pendingBefore ? [close(prior.id)] : []),
+ ...(pendingAfter ? [close(later.id)] : []),
+ ],
+ },
+ true,
);
const finished = await f.read();
assert.deepEqual(finished.deferred, []);
@@ -2207,8 +2122,8 @@ for (const layout of ["standard", "diff", "worker"] as const) {
test(`${layout}: late progress survives an identical terminal retry`, async (t) => {
const f = await fixture(t, layout);
- await f.write(f.draft({}, true));
- await f.write(f.draft({ deferred: [{ id: "late", ...generic }] }));
+ await f.writeReviewState({}, true);
+ await f.writeReviewState({ deferred: [{ id: "late", ...generic }] });
const published = await readJson(
f.root,
layout === "worker" ? "result.json" : "scan-manifest.json",
@@ -2219,7 +2134,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
);
const pending = (await f.read()).deferred;
assert.deepEqual(pending, [{ id: "late", ...generic }]);
- await f.write(f.draft({}, true));
+ await f.writeReviewState({}, true);
assert.deepEqual((await f.read()).deferred, pending);
});
@@ -2232,31 +2147,27 @@ for (const layout of ["standard", "diff", "worker"] as const) {
];
if (reverse) deferred.reverse();
await assert.rejects(
- f.write(f.draft({ deferred })),
+ f.writeReviewState({ deferred }),
/reviewState\.deferred repeats candidate-a/,
);
assert.deepEqual(await readdir(f.root), []);
- await f.write(
- f.draft({
- deferred: [
- { id: "candidate-a", candidateId: "candidate-a", ...generic },
+ await f.writeReviewState({
+ deferred: [
+ { id: "candidate-a", candidateId: "candidate-a", ...generic },
+ ],
+ });
+ await f.writeReviewState(
+ {
+ surfaces: [
+ {
+ id: "outcome",
+ candidateId: "candidate-a",
+ label: "Candidate",
+ disposition: "rejected",
+ },
],
- }),
- );
- await f.write(
- f.draft(
- {
- surfaces: [
- {
- id: "outcome",
- candidateId: "candidate-a",
- label: "Candidate",
- disposition: "rejected",
- },
- ],
- },
- true,
- ),
+ },
+ true,
);
assert.deepEqual((await f.read()).deferred, []);
});
@@ -2284,8 +2195,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
disposition: "needs_follow_up",
receiptRefs: [],
};
- await saveScanDraftCheckpoint(
- f.context,
+ await f.checkpoint(
f.draft({
deferred: [
task,
@@ -2294,10 +2204,9 @@ for (const layout of ["standard", "diff", "worker"] as const) {
],
surfaces: [followUp],
}),
- false,
);
for (let attempt = 0; attempt < 2; attempt += 1) {
- const restored = await f.write(f.draft());
+ const restored = await f.writeReviewState();
assert.equal(restored.reviewState.deferred.length, 3);
assert.ok(
restored.reviewState.deferred.some(
@@ -2349,7 +2258,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
);
}
await assert.rejects(
- f.write(f.draft({ resolvedDeferred: [close(task.id)] }, true)),
+ f.writeReviewState({ resolvedDeferred: [close(task.id)] }, true),
/ambiguous saved deferred work/,
);
});
@@ -2372,11 +2281,9 @@ for (const layout of ["standard", "diff", "worker"] as const) {
kind: "generic",
reason: "Independent work remains.",
};
- await f.write(
- f.draft(
- { surfaces: [surface], deferred: otherPending ? [other] : [] },
- true,
- ),
+ await f.writeReviewState(
+ { surfaces: [surface], deferred: otherPending ? [other] : [] },
+ true,
);
const next = {
id: linkedById ? "api" : "new-review",
@@ -2440,23 +2347,21 @@ for (const layout of ["standard", "diff", "worker"] as const) {
: [source],
originalCandidates: [null, { original: "candidate" }],
});
- await f.write(
- f.draft({
- deferred: [
- {
- id: "review",
- candidateId: "review",
- reason: "Review remains.",
- finding: old,
- },
- ],
- }),
- );
+ await f.writeReviewState({
+ deferred: [
+ {
+ id: "review",
+ candidateId: "review",
+ reason: "Review remains.",
+ finding: old,
+ },
+ ],
+ });
const reported = {
...old,
provenance: { source: "local_plugin", candidateId: "review" },
};
- const input = { ...f.draft({}, true), findings: [reported] };
+ const input = f.findingsDraft([reported], { complete: true });
await f.write(input);
await f.write(input);
const saved = await readJson(
@@ -2481,10 +2386,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
]);
const parent = layout === "worker" ? await fixture(t, "deep") : f;
if (layout === "worker")
- await parent.write({
- ...parent.draft({}, true),
- findings: saved.findings,
- });
+ await parent.writeFindings(saved.findings, { complete: true });
const manifestPath = path.join(parent.root, "scan-manifest.json");
const manifest = await readJson(manifestPath);
Object.assign(manifest.scan, {
@@ -2508,9 +2410,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
parent.root,
]);
assert.equal(
- JSON.parse(
- await readFile(path.join(parent.root, "findings.json"), "utf8"),
- ).findings.length,
+ (await readJson(parent.root, "findings.json")).findings.length,
1,
);
});
@@ -2538,10 +2438,7 @@ for (const additional of ["none", "surface", "task", "completed-surface"]) {
],
});
await f.write(progress);
- await f.write({
- ...f.draft({}, true),
- findings: [findingFor("candidate-review")],
- });
+ await f.writeFindings([findingFor("candidate-review")], { complete: true });
const { importSource } = await import("./import-module.ts");
const { validateDiscoveryArtifacts } = await importSource(
"../src/deep-scan/artifact-validation.ts",
diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_identity.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_identity.ts
index 17382a17d..7579e84c8 100644
--- a/plugins/codex-security/mcp-app/tests/test_artifact_scan_identity.ts
+++ b/plugins/codex-security/mcp-app/tests/test_artifact_scan_identity.ts
@@ -1,3 +1,4 @@
+import { readJson } from "./support/json.ts";
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { execFile } from "node:child_process";
@@ -14,7 +15,6 @@ import test from "node:test";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import {
- draftApi,
draftFixture,
fixture,
interruptDraftWrite,
@@ -25,19 +25,20 @@ import {
type RecoveredFinding,
type DraftFixture,
finding,
+ recoveryPair,
+ savedWorker,
recoverAndFinalize,
dateDraftFiles,
} from "./scan-identity-recovery-fixture.ts";
const execFileAsync = promisify(execFile);
-const savedWorker = (root: string) => ({
- id: "reviewer",
- kind: "discovery",
- status: "canceled",
- artifact_dir: root,
- result_manifest_path: null,
- attempt: 1,
-});
+
+function withWorkerId(rows: FixtureFinding[], workerId: string) {
+ return rows.map((row) => ({
+ ...row,
+ provenance: { ...row.provenance, workerId },
+ }));
+}
const checkpointName = (input: unknown) =>
createHash("sha256").update(JSON.stringify(input)).digest("hex") + ".json";
@@ -47,7 +48,7 @@ async function saveCheckpointAt(
draft: ReturnType<DraftFixture["draft"]>,
time: number,
) {
- await draftApi.saveScanDraftCheckpoint(writer.context, draft, false);
+ await writer.checkpoint(draft);
const { handoffClaimToken: _claim, ...snapshot } = draft;
await utimes(
path.join(writer.root, "checkpoints", checkpointName(snapshot)),
@@ -101,8 +102,7 @@ for (const variant of [
] as const) {
for (const reversed of [false, true]) {
test(`worker ${variant} identity survives recovery (reversed=${reversed})`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(normal.root, "worker");
const interruptedRoot = path.join(recovered.root, "worker");
await Promise.all([mkdir(workerRoot), mkdir(interruptedRoot)]);
@@ -130,42 +130,19 @@ for (const variant of [
];
if (reversed) rows.reverse();
for (const target of [worker, interrupted]) {
- await target.write({ ...target.draft(), findings: [rows[0]] });
+ await target.writeFindings([rows[0]]);
await dateDraftFiles(target.root, 100);
}
- await worker.write({ ...worker.draft(), findings: [rows[1]] });
- await draftApi.saveScanDraftCheckpoint(
- interrupted.context,
- { ...interrupted.draft(), findings: [rows[1]] },
- false,
- );
- const saved = JSON.parse(
- await readFile(path.join(workerRoot, "result.json"), "utf8"),
- );
- await normal.write({
- ...normal.draft(),
- findings: saved.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "worker" },
- })),
+ await worker.writeFindings([rows[1]]);
+ await interrupted.checkpoint(interrupted.findingsDraft([rows[1]]));
+ const saved = await readJson(workerRoot, "result.json");
+ await normal.writeFindings(withWorkerId(saved.findings, "worker"));
+ const result = await recover({
+ workers: [savedWorker(interruptedRoot, "worker", "succeeded")],
+ details: true,
+ replay: true,
+ provenanceDetails: true,
});
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [
- {
- id: "worker",
- kind: "discovery",
- status: "succeeded",
- artifact_dir: interruptedRoot,
- result_manifest_path: path.join(interruptedRoot, "result.json"),
- attempt: 1,
- },
- ],
- true,
- true,
- true,
- );
const expectedCount = variant === "additional locations" ? 1 : 2;
assert.equal(result.normal.length, expectedCount);
assert.equal(result.recovered.length, expectedCount);
@@ -222,10 +199,8 @@ for (const kind of ["object", "array", "string"] as const) {
}),
);
for (let replay = 0; replay < 3; replay++) {
- await worker.write({ ...worker.draft(), findings });
- const saved = JSON.parse(
- await readFile(path.join(worker.root, "result.json"), "utf8"),
- );
+ await worker.writeFindings(findings);
+ const saved = await readJson(worker.root, "result.json");
assert.deepEqual(saved.findings, findings);
}
});
@@ -240,8 +215,7 @@ for (const observations of [
[0, 2],
]) {
test(`worker checkpoints preserve reordered JSON identities ${observations.join("/")}`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(normal.root, "worker");
const interruptedRoot = path.join(recovered.root, "worker");
await Promise.all([mkdir(workerRoot), mkdir(interruptedRoot)]);
@@ -253,7 +227,7 @@ for (const observations of [
}),
);
for (const [index, rows] of [findings, [...findings].reverse()].entries()) {
- const snapshot = { ...worker.draft(), findings: rows };
+ const snapshot = worker.findingsDraft(rows);
await worker.write(snapshot);
if (
index === 1 &&
@@ -271,43 +245,20 @@ for (const observations of [
contents,
);
} else {
- await draftApi.saveScanDraftCheckpoint(
- interrupted.context,
- snapshot,
- false,
- );
+ await interrupted.checkpoint(snapshot);
}
if (index === 0) {
await dateDraftFiles(workerRoot, 100);
await dateDraftFiles(interruptedRoot, 100);
}
}
- const saved = JSON.parse(
- await readFile(path.join(workerRoot, "result.json"), "utf8"),
- );
- await normal.write({
- ...normal.draft(),
- findings: saved.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "worker" },
- })),
+ const saved = await readJson(workerRoot, "result.json");
+ await normal.writeFindings(withWorkerId(saved.findings, "worker"));
+ const result = await recover({
+ workers: [savedWorker(interruptedRoot, "worker")],
+ details: true,
+ replay: true,
});
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [
- {
- id: "worker",
- kind: "discovery",
- status: "canceled",
- artifact_dir: interruptedRoot,
- result_manifest_path: null,
- attempt: 1,
- },
- ],
- true,
- true,
- );
const identitiesByEvidence = (rows: RecoveredFinding[]) =>
new Map(
rows.map((row) => [
@@ -361,8 +312,7 @@ for (const [label, metadata, count] of [
],
] as const) {
test(`candidate selection retains moved evidence for ${label}`, async (t) => {
- const normal = await fixture(t, "standard"),
- recovered = await fixture(t, "standard");
+ const { normal, recovered, recover } = await recoveryPair(t, "standard");
for (const [index, location] of [
"src/first.py",
"src/second.py",
@@ -376,15 +326,11 @@ for (const [label, metadata, count] of [
...("provenance" in metadata ? metadata.provenance : {}),
},
});
- await normal.write({ ...normal.draft(), findings: [row] });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings: [row] },
- false,
- );
+ await normal.writeFindings([row]);
+ await recovered.checkpoint(recovered.findingsDraft([row]));
if (index === 0) await dateDraftFiles(recovered.root, 100);
}
- const result = await recoverAndFinalize(normal, recovered, [], true, true);
+ const result = await recover({ details: true, replay: true });
const byLocation = (rows: RecoveredFinding[]) =>
new Map(rows.map((row) => [row.locations[0]!.path, row]));
assert.equal(result.normal.length, count);
@@ -396,8 +342,7 @@ for (const [label, metadata, count] of [
for (const layout of ["standard", "diff", "deep"] as const) {
test(`${layout}: Unicode whitespace candidate IDs match recovered identities`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const candidates = {
bom: "\ufeff",
"next-line": "\u0085",
@@ -410,13 +355,9 @@ for (const layout of ["standard", "diff", "deep"] as const) {
provenance: { source: "local_plugin", candidateId },
}),
);
- await normal.write({ ...normal.draft(), findings });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings },
- false,
- );
- const result = await recoverAndFinalize(normal, recovered, [], true, true);
+ await normal.writeFindings(findings);
+ await recovered.checkpoint(recovered.findingsDraft(findings));
+ const result = await recover({ details: true, replay: true });
assert.deepEqual(
result.normal.map((row) => row.title).sort(),
Object.keys(candidates).sort(),
@@ -434,26 +375,21 @@ for (const layout of ["standard", "diff", "deep"] as const) {
[0, 2],
]) {
test(`${layout}: reordered JSON evidence ${observations.join("/")} keeps published identities`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const initial = observations.map((value) =>
finding("Synthetic review", {
extensions: { observation: { value } },
}),
);
for (const target of [normal, recovered]) {
- await target.write({ ...target.draft(), findings: initial });
+ await target.writeFindings(initial);
await dateDraftFiles(target.root, 100);
}
const findings = [...initial].reverse();
- await normal.write({ ...normal.draft(), findings });
- const snapshot = { ...recovered.draft(), findings };
+ await normal.writeFindings(findings);
+ const snapshot = recovered.findingsDraft(findings);
if (typeof observations[0] === "boolean") {
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- snapshot,
- false,
- );
+ await recovered.checkpoint(snapshot);
} else {
// Imported JSON can spell the same numbers differently than JSON.stringify.
const contents = (JSON.stringify(snapshot, null, 2) + "\n").replace(
@@ -468,13 +404,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
contents,
);
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, 2);
const byId = (left: RecoveredFinding, right: RecoveredFinding) =>
@@ -488,15 +418,10 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const layout of ["standard", "diff", "deep"] as const) {
for (const [variant, findings] of Object.entries(variants)) {
test(`${layout}: first checkpoint publication preserves ${variant} identities`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
- await normal.write({ ...normal.draft(), findings });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings },
- false,
- );
- const result = await recoverAndFinalize(normal, recovered);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
+ await normal.writeFindings(findings);
+ await recovered.checkpoint(recovered.findingsDraft(findings));
+ const result = await recover();
assert.equal(result.normal.length, findings.length);
assert.equal(result.recovered.length, findings.length);
assert.deepEqual(result.warnings, []);
@@ -528,8 +453,7 @@ const terminalDraftCases: Array<{
];
for (const { variant, expectedCount, observation } of terminalDraftCases) {
test(`worker: a newer terminal draft reconciles ${variant} observations`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(normal.root, "worker");
const interruptedRoot = path.join(recovered.root, "worker");
await Promise.all([mkdir(workerRoot), mkdir(interruptedRoot)]);
@@ -573,24 +497,16 @@ for (const { variant, expectedCount, observation } of terminalDraftCases) {
]
: [enriched];
for (const target of [worker, interrupted]) {
- await target.write({ ...target.draft({}, true), findings: initial });
+ await target.writeFindings(initial, { complete: true });
await dateDraftFiles(target.root, 100);
}
- await worker.write({ ...worker.draft({}, true), findings: latest });
- await draftApi.saveScanDraftCheckpoint(
- interrupted.context,
- { ...interrupted.draft({}, true), findings: latest },
- false,
- );
- const published = JSON.parse(
- await readFile(path.join(worker.root, "result.json"), "utf8"),
+ await worker.writeFindings(latest, { complete: true });
+ await interrupted.checkpoint(
+ interrupted.findingsDraft(latest, { complete: true }),
);
- await normal.write({
- ...normal.draft({}, true),
- findings: published.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "worker" },
- })),
+ const published = await readJson(worker.root, "result.json");
+ await normal.writeFindings(withWorkerId(published.findings, "worker"), {
+ complete: true,
});
const sourceBytes = new Map(
await Promise.all(
@@ -605,22 +521,11 @@ for (const { variant, expectedCount, observation } of terminalDraftCases) {
),
),
);
- const finalized = await recoverAndFinalize(
- normal,
- recovered,
- [
- {
- id: "worker",
- kind: "discovery",
- status: "canceled",
- artifact_dir: interrupted.root,
- result_manifest_path: null,
- attempt: 1,
- },
- ],
- true,
- true,
- );
+ const finalized = await recover({
+ workers: [savedWorker(interrupted.root, "worker")],
+ details: true,
+ replay: true,
+ });
assert.equal(finalized.normal.length, expectedCount);
assert.equal(finalized.recovered.length, expectedCount);
const byId = (left: RecoveredFinding, right: RecoveredFinding) =>
@@ -645,24 +550,16 @@ for (const layout of ["standard", "diff", "worker"] as const) {
const initial = finding("Synthetic report", {
extensions: { reportId: "report-1" },
});
- await f.write({ ...f.draft(), findings: [initial] });
- await f.write({
- ...f.draft(),
- findings: [
- {
- ...initial,
- provenance: { source: "local_plugin", candidateId: "candidate-1" },
- },
- ],
- });
- const saved = JSON.parse(
- await readFile(
- path.join(
- f.root,
- layout === "worker" ? "result.json" : "findings.json",
- ),
- "utf8",
- ),
+ await f.writeFindings([initial]);
+ await f.writeFindings([
+ {
+ ...initial,
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ },
+ ]);
+ const saved = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "findings.json",
);
assert.equal(saved.findings.length, 1);
assert.equal(saved.findings[0].provenance.candidateId, "candidate-1");
@@ -671,15 +568,14 @@ for (const layout of ["standard", "diff", "worker"] as const) {
for (const layout of ["standard", "diff", "deep"] as const) {
test(`${layout}: canonical rows without identities use their sibling context`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
for (const f of [normal, recovered])
- await f.write({ ...f.draft(), findings: variants.siblings });
+ await f.writeFindings(variants.siblings);
const destination = path.join(recovered.root, "findings.json");
- const document = JSON.parse(await readFile(destination, "utf8"));
+ const document = await readJson(destination);
for (const row of document.findings) delete row.identity;
await writeFile(destination, JSON.stringify(document));
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.recovered.length, 2);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -687,15 +583,14 @@ for (const layout of ["standard", "diff", "deep"] as const) {
}
for (const layout of ["standard", "diff"] as const) {
test(`${layout}: a new sibling survives a published singleton`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
for (const f of [normal, recovered])
- await f.write({ ...f.draft(), findings: variants.siblings.slice(0, 1) });
- await normal.write({ ...normal.draft(), findings: variants.siblings });
+ await f.writeFindings(variants.siblings.slice(0, 1));
+ await normal.writeFindings(variants.siblings);
await interruptDraftWrite(path.join(recovered.root, "findings.json"), () =>
- recovered.write({ ...recovered.draft(), findings: variants.siblings }),
+ recovered.writeFindings(variants.siblings),
);
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -704,8 +599,7 @@ for (const layout of ["standard", "diff"] as const) {
for (const reported of [false, true]) {
for (const cut of ["raw", "reconciled"]) {
test(`${layout}: ${metadata} enrichment (report=${reported}) retains identities after two ${cut} interruptions`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding(
"Synthetic report",
reported
@@ -719,21 +613,16 @@ for (const layout of ["standard", "diff"] as const) {
[metadata]: { ...first[metadata], candidateId: "candidate-1" },
};
for (const value of [first, second]) {
- await normal.write({ ...normal.draft(), findings: [value] });
- const input = { ...recovered.draft(), findings: [value] };
- if (cut === "raw")
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- input,
- false,
- );
+ await normal.writeFindings([value]);
+ const input = recovered.findingsDraft([value]);
+ if (cut === "raw") await recovered.checkpoint(input);
else
await interruptDraftWrite(
path.join(recovered.root, "findings.json"),
() => recovered.write(input),
);
}
- const result = await recoverAndFinalize(normal, recovered, [], true);
+ const result = await recover({ details: true });
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -751,8 +640,7 @@ for (const variant of [
"rejected sibling",
]) {
test(`deep: worker-local candidates match combined publication (${variant})`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workers = [];
const findings = [];
for (const [index, id] of ["reviewer-a", "reviewer-b"].entries()) {
@@ -777,45 +665,29 @@ for (const variant of [
);
if (variant === "authored anchor" && index === 0)
value.identity = { anchor: "established-review" };
- await worker.write({ ...worker.draft(), findings: [value] });
- const result = JSON.parse(
- await readFile(path.join(root, "result.json"), "utf8"),
- );
+ await worker.writeFindings([value]);
+ const result = await readJson(root, "result.json");
if (variant === "rejected sibling" && index === 1) {
- await worker.write(
- worker.draft(
- {
- surfaces: [
- {
- id: "review-completed",
- label: "Review completed",
- candidateId: "candidate-1",
- disposition: "rejected",
- },
- ],
- },
- true,
- ),
+ await worker.writeReviewState(
+ {
+ surfaces: [
+ {
+ id: "review-completed",
+ label: "Review completed",
+ candidateId: "candidate-1",
+ disposition: "rejected",
+ },
+ ],
+ },
+ true,
);
} else {
- findings.push(
- ...result.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: id },
- })),
- );
+ findings.push(...withWorkerId(result.findings, id));
}
- workers.push({
- id,
- kind: "discovery",
- status: "canceled",
- artifact_dir: root,
- result_manifest_path: null,
- attempt: 1,
- });
+ workers.push(savedWorker(root, id));
}
- await normal.write({ ...normal.draft(), findings });
- const result = await recoverAndFinalize(normal, recovered, workers);
+ await normal.writeFindings(findings);
+ const result = await recover({ workers });
assert.equal(result.normal.length, variant === "rejected sibling" ? 1 : 2);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -835,8 +707,7 @@ for (const [kind, metadata, identifier] of [
),
]) {
test(`deep: ${kind} via ${metadata}/${identifier ?? "plain"} matches published worker identities`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const normalRoot = path.join(normal.root, "reviewer");
const recoveryRoot = path.join(recovered.root, "reviewer");
await mkdir(normalRoot);
@@ -870,29 +741,14 @@ for (const [kind, metadata, identifier] of [
};
}
for (const worker of [publishedWorker, interruptedWorker])
- await worker.write({ ...worker.draft(), findings: [first] });
- await publishedWorker.write({
- ...publishedWorker.draft(),
- findings: [second],
- });
- await draftApi.saveScanDraftCheckpoint(
- interruptedWorker.context,
- { ...interruptedWorker.draft(), findings: [second] },
- false,
- );
- const result = JSON.parse(
- await readFile(path.join(normalRoot, "result.json"), "utf8"),
+ await worker.writeFindings([first]);
+ await publishedWorker.writeFindings([second]);
+ await interruptedWorker.checkpoint(
+ interruptedWorker.findingsDraft([second]),
);
- await normal.write({
- ...normal.draft(),
- findings: result.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "reviewer" },
- })),
- });
- const comparison = await recoverAndFinalize(normal, recovered, [
- savedWorker(recoveryRoot),
- ]);
+ const result = await readJson(normalRoot, "result.json");
+ await normal.writeFindings(withWorkerId(result.findings, "reviewer"));
+ const comparison = await recover({ workers: [savedWorker(recoveryRoot)] });
assert.equal(
comparison.normal.length,
kind === "candidate aliases" ? 2 : 1,
@@ -909,8 +765,7 @@ for (const [kind, metadata, identifier] of [
for (const layout of ["standard", "diff"] as const) {
test(`${layout}: growing raw cross-location siblings retain published identities`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("First review", {
provenance: { source: "local_plugin", candidateId: "shared-candidate" },
});
@@ -920,14 +775,10 @@ for (const layout of ["standard", "diff"] as const) {
locations: [{ path: "src/example.py", startLine: 2 }],
};
for (const findings of [[first], [first, second]]) {
- await normal.write({ ...normal.draft(), findings });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings },
- false,
- );
+ await normal.writeFindings(findings);
+ await recovered.checkpoint(recovered.findingsDraft(findings));
}
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -942,8 +793,7 @@ for (const variant of [
] as const) {
for (const reversed of [false, true]) {
test(`deep: explicit worker identity survives ${variant} revision (reverse=${reversed})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const nwroot = path.join(normal.root, "reviewer"),
rwroot = path.join(recovered.root, "reviewer");
await mkdir(nwroot);
@@ -974,27 +824,13 @@ for (const variant of [
: { candidateId: "shared-review" }),
},
};
- await nw.write({ ...nw.draft(), findings: ordered(first) });
- await rw.write({ ...rw.draft(), findings: ordered(first) });
- await nw.write({ ...nw.draft(), findings: ordered(second) });
- await draftApi.saveScanDraftCheckpoint(
- rw.context,
- { ...rw.draft(), findings: ordered(second) },
- false,
- );
- const result = JSON.parse(
- await readFile(path.join(nwroot, "result.json"), "utf8"),
- );
- await normal.write({
- ...normal.draft(),
- findings: result.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "reviewer" },
- })),
- });
- const comparison = await recoverAndFinalize(normal, recovered, [
- savedWorker(rwroot),
- ]);
+ await nw.writeFindings(ordered(first));
+ await rw.writeFindings(ordered(first));
+ await nw.writeFindings(ordered(second));
+ await rw.checkpoint(rw.findingsDraft(ordered(second)));
+ const result = await readJson(nwroot, "result.json");
+ await normal.writeFindings(withWorkerId(result.findings, "reviewer"));
+ const comparison = await recover({ workers: [savedWorker(rwroot)] });
assert.equal(comparison.normal.length, withSibling ? 2 : 1);
assert.deepEqual(comparison.recovered, comparison.normal);
assert.deepEqual(comparison.warnings, []);
@@ -1032,8 +868,10 @@ for (const layout of ["standard", "diff", "worker"] as const) {
"retained sibling",
]) {
test(`${layout}: checkpoint reconciliation preserves ${variant}`, async (t) => {
- const normal = await fixture(t, layout === "worker" ? "deep" : layout);
- const recovered = await fixture(t, layout === "worker" ? "deep" : layout);
+ const { normal, recovered, recover } = await recoveryPair(
+ t,
+ layout === "worker" ? "deep" : layout,
+ );
let normalSource = normal,
recoveredSource = recovered;
const workers = [];
@@ -1069,34 +907,19 @@ for (const layout of ["standard", "diff", "worker"] as const) {
const initial =
variant === "retained sibling" ? [first, second] : [first];
for (const f of [normalSource, recoveredSource])
- await f.write({ ...f.draft(), findings: initial });
- await normalSource.write({
- ...normalSource.draft({}, true),
- findings: [second],
- });
- await draftApi.saveScanDraftCheckpoint(
- recoveredSource.context,
- { ...recoveredSource.draft({}, true), findings: [second] },
- false,
+ await f.writeFindings(initial);
+ await normalSource.writeFindings([second], { complete: true });
+ await recoveredSource.checkpoint(
+ recoveredSource.findingsDraft([second], { complete: true }),
);
if (layout === "worker") {
- const saved = JSON.parse(
- await readFile(path.join(normalSource.root, "result.json"), "utf8"),
- );
- await normal.write({
- ...normal.draft(),
- findings: saved.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "reviewer" },
- })),
- });
+ const saved = await readJson(normalSource.root, "result.json");
+ await normal.writeFindings(withWorkerId(saved.findings, "reviewer"));
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
+ const result = await recover({
workers,
- variant === "metadata enrichment",
- );
+ details: variant === "metadata enrichment",
+ });
const count = ["metadata enrichment", "authored identity"].includes(
variant,
)
@@ -1122,23 +945,21 @@ for (const layout of ["standard", "diff", "worker"] as const) {
for (const layout of ["standard", "diff", "deep"] as const)
for (const metadata of ["provenance", "extensions"] as const) {
test(`${layout}: candidate-backed canonical duplicate without identity (${metadata})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const input = finding("Synthetic review", {
[metadata]: {
...(metadata === "provenance" ? { source: "local_plugin" } : {}),
candidateId: "candidate-1",
},
});
- for (const f of [normal, recovered])
- await f.write({ ...f.draft(), findings: [input] });
+ for (const f of [normal, recovered]) await f.writeFindings([input]);
const dest = path.join(recovered.root, "findings.json");
- const doc = JSON.parse(await readFile(dest, "utf8"));
+ const doc = await readJson(dest);
const duplicate = structuredClone(doc.findings[0]);
delete duplicate.identity;
doc.findings.push(duplicate);
await writeFile(dest, JSON.stringify(doc));
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
});
@@ -1147,8 +968,7 @@ for (const layout of ["standard", "diff", "deep"] as const)
for (const layout of ["standard", "diff", "deep"] as const)
for (const metadata of ["provenance", "extensions"] as const) {
test(`${layout}: raw candidate identity remains distinct when content matches (${metadata})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const one = finding("Synthetic review", {
[metadata]: {
...(metadata === "provenance" ? { source: "local_plugin" } : {}),
@@ -1159,16 +979,16 @@ for (const layout of ["standard", "diff", "deep"] as const)
...one,
[metadata]: { ...one[metadata], candidateId: "candidate-2" },
};
- await normal.write({ ...normal.draft(), findings: [one, two] });
- await recovered.write({ ...recovered.draft(), findings: [one] });
+ await normal.writeFindings([one, two]);
+ await recovered.writeFindings([one]);
const dest = path.join(recovered.root, "findings.json");
- const doc = JSON.parse(await readFile(dest, "utf8"));
+ const doc = await readJson(dest);
const second = structuredClone(doc.findings[0]);
delete second.identity;
second[metadata].candidateId = "candidate-2";
doc.findings.push(second);
await writeFile(dest, JSON.stringify(doc));
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
});
@@ -1176,8 +996,7 @@ for (const layout of ["standard", "diff", "deep"] as const)
for (const layout of ["standard", "diff", "deep"] as const) {
test(`${layout}: cumulative distinct owners retain publication identity`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("Synthetic ownership review", {
provenance: {
source: "local_plugin",
@@ -1191,14 +1010,10 @@ for (const layout of ["standard", "diff", "deep"] as const) {
provenance: { ...first.provenance, workerId: "worker-b" },
};
for (const findings of [[first], [first, second]]) {
- await normal.write({ ...normal.draft(), findings });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings },
- false,
- );
+ await normal.writeFindings(findings);
+ await recovered.checkpoint(recovered.findingsDraft(findings));
}
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, 2);
assert.deepEqual(result.warnings, []);
@@ -1209,22 +1024,17 @@ for (const layout of ["standard", "diff", "deep"] as const) {
["ledgerRowId", "\t"],
]) {
test(`${layout}: blank ${field} enrichment retains publication identity`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("Synthetic metadata review", {
provenance: { source: "local_plugin", candidateId: "candidate-1" },
extensions: { [field]: blank },
});
const second = { ...first, extensions: { [field]: "report-1" } };
for (const value of [first, second]) {
- await normal.write({ ...normal.draft(), findings: [value] });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings: [value] },
- false,
- );
+ await normal.writeFindings([value]);
+ await recovered.checkpoint(recovered.findingsDraft([value]));
}
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.normal.length, 1);
assert.equal(result.recovered.length, 1);
assert.deepEqual(result.warnings, []);
@@ -1234,8 +1044,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
}
for (const field of ["reportId", "ledgerRowId"]) {
test(`deep: worker blank ${field} enrichment retains publication identity`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const normalRoot = path.join(normal.root, "reviewer");
const recoveredRoot = path.join(recovered.root, "reviewer");
await mkdir(normalRoot);
@@ -1248,26 +1057,12 @@ for (const field of ["reportId", "ledgerRowId"]) {
});
const second = { ...first, extensions: { [field]: "report-1" } };
for (const value of [first, second]) {
- await normalWorker.write({ ...normalWorker.draft(), findings: [value] });
- await draftApi.saveScanDraftCheckpoint(
- recoveredWorker.context,
- { ...recoveredWorker.draft(), findings: [value] },
- false,
- );
+ await normalWorker.writeFindings([value]);
+ await recoveredWorker.checkpoint(recoveredWorker.findingsDraft([value]));
}
- const saved = JSON.parse(
- await readFile(path.join(normalRoot, "result.json"), "utf8"),
- );
- await normal.write({
- ...normal.draft(),
- findings: saved.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "reviewer" },
- })),
- });
- const result = await recoverAndFinalize(normal, recovered, [
- savedWorker(recoveredRoot),
- ]);
+ const saved = await readJson(normalRoot, "result.json");
+ await normal.writeFindings(withWorkerId(saved.findings, "reviewer"));
+ const result = await recover({ workers: [savedWorker(recoveredRoot)] });
assert.equal(result.normal.length, 1);
assert.equal(result.recovered.length, 1);
assert.deepEqual(result.warnings, []);
@@ -1277,21 +1072,16 @@ for (const field of ["reportId", "ledgerRowId"]) {
for (const layout of ["standard", "diff", "deep"] as const) {
test(`${layout}: later authored identity survives raw checkpoint recovery`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("Synthetic review", {
provenance: { source: "local_plugin", candidateId: "candidate-1" },
});
const second = { ...first, identity: { anchor: "authored-review" } };
for (const value of [first, second]) {
- await normal.write({ ...normal.draft(), findings: [value] });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings: [value] },
- false,
- );
+ await normal.writeFindings([value]);
+ await recovered.checkpoint(recovered.findingsDraft([value]));
}
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.normal.length, 2);
assert.deepEqual(
[...result.recovered].sort((a, b) =>
@@ -1307,8 +1097,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
["synthetic-worker"],
] as const) {
test(`${layout}: arbitrary worker provenance survives recovery (${Array.isArray(metadata) ? "array" : "object"})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const value = finding("Synthetic review", {
provenance: {
source: "local_plugin",
@@ -1316,9 +1105,8 @@ for (const layout of ["standard", "diff", "deep"] as const) {
workerId: metadata,
},
});
- for (const f of [normal, recovered])
- await f.write({ ...f.draft(), findings: [value] });
- const result = await recoverAndFinalize(normal, recovered);
+ for (const f of [normal, recovered]) await f.writeFindings([value]);
+ const result = await recover();
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.recovered[0].workerMetadata, metadata);
@@ -1328,8 +1116,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const layout of ["standard", "diff", "deep"] as const) {
for (const shape of ["summary revision", "shared ledger"]) {
test(`${layout}: report reconciliation ${shape}`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("First review", {
provenance: { source: "local_plugin", candidateId: "candidate-1" },
...(shape === "shared ledger"
@@ -1345,14 +1132,10 @@ for (const layout of ["standard", "diff", "deep"] as const) {
]
: [[first, second]];
for (const findings of snapshots) {
- await normal.write({ ...normal.draft(), findings });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings },
- false,
- );
+ await normal.writeFindings(findings);
+ await recovered.checkpoint(recovered.findingsDraft(findings));
}
- const result = await recoverAndFinalize(normal, recovered, [], true);
+ const result = await recover({ details: true });
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, result.normal.length);
@@ -1365,8 +1148,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
}
test("deep: refined candidate retains independent cross-location report", async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const normalRoot = path.join(normal.root, "reviewer");
const recoveredRoot = path.join(recovered.root, "reviewer");
await mkdir(normalRoot);
@@ -1388,29 +1170,15 @@ test("deep: refined candidate retains independent cross-location report", async
severity: { level: "low" },
};
for (const findings of [[first], [refined, second]]) {
- await normalWorker.write({ ...normalWorker.draft(), findings });
- await draftApi.saveScanDraftCheckpoint(
- recoveredWorker.context,
- { ...recoveredWorker.draft(), findings },
- false,
- );
+ await normalWorker.writeFindings(findings);
+ await recoveredWorker.checkpoint(recoveredWorker.findingsDraft(findings));
}
- const saved = JSON.parse(
- await readFile(path.join(normalRoot, "result.json"), "utf8"),
- );
- await normal.write({
- ...normal.draft(),
- findings: saved.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "reviewer" },
- })),
+ const saved = await readJson(normalRoot, "result.json");
+ await normal.writeFindings(withWorkerId(saved.findings, "reviewer"));
+ const result = await recover({
+ workers: [savedWorker(recoveredRoot)],
+ details: true,
});
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [savedWorker(recoveredRoot)],
- true,
- );
assert.ok(result.recovered.some((row) => row.title === "Second review"));
assert.equal(result.normal.length, 3);
@@ -1427,11 +1195,11 @@ for (const layout of ["standard", "diff"] as const) {
provenance: { source: "local_plugin", candidateId: "candidate-1" },
});
const second = { ...structuredClone(first), title: "Second review" };
- await f.write({ ...f.draft(), findings: [first, second] });
- await f.write({
- ...f.draft({}, true),
- findings: [{ ...first, summary: "Revised evidence." }, second],
- });
+ await f.writeFindings([first, second]);
+ await f.writeFindings(
+ [{ ...first, summary: "Revised evidence." }, second],
+ { complete: true },
+ );
const { stdout } = await execFileAsync(
process.env.PYTHON?.trim() || "python3",
[
@@ -1456,8 +1224,7 @@ print(len(prepared.findings['findings']))`,
}
for (const layout of ["standard", "diff", "deep"] as const) {
test(`${layout}: repeated shared-ledger publication preserves allocated identities`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("First review", {
provenance: { source: "local_plugin", candidateId: "candidate-1" },
extensions: { ledgerRowId: "ledger-1" },
@@ -1465,9 +1232,9 @@ for (const layout of ["standard", "diff", "deep"] as const) {
const second = { ...structuredClone(first), title: "Second review" };
for (let index = 0; index < 2; index++) {
for (const f of [normal, recovered])
- await f.write({ ...f.draft(), findings: [first, second] });
+ await f.writeFindings([first, second]);
}
- const result = await recoverAndFinalize(normal, recovered, [], true);
+ const result = await recover({ details: true });
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, 2);
assert.deepEqual(result.warnings, []);
@@ -1478,8 +1245,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const layout of ["standard", "diff", "deep"] as const) {
for (const cut of ["canonical", "raw"]) {
test(`${layout}: ownership enrichment preserves publication identity (${cut})`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("Synthetic ownership review", {
identity: { anchor: "authored-review" },
provenance: { source: "local_plugin", candidateId: "candidate-1" },
@@ -1489,17 +1255,11 @@ for (const layout of ["standard", "diff", "deep"] as const) {
provenance: { ...first.provenance, workerId: "worker-a" },
};
for (const row of [first, second]) {
- await normal.write({ ...normal.draft(), findings: [row] });
- if (cut === "canonical")
- await recovered.write({ ...recovered.draft(), findings: [row] });
- else
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings: [row] },
- false,
- );
+ await normal.writeFindings([row]);
+ if (cut === "canonical") await recovered.writeFindings([row]);
+ else await recovered.checkpoint(recovered.findingsDraft([row]));
}
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
@@ -1510,8 +1270,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const layout of ["standard", "diff", "deep"] as const) {
test(`${layout}: ownership enrichment keeps a newly known independent owner`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("Synthetic ownership review", {
identity: { anchor: "authored-first" },
provenance: { source: "local_plugin", candidateId: "candidate-1" },
@@ -1526,14 +1285,10 @@ for (const layout of ["standard", "diff", "deep"] as const) {
provenance: { ...first.provenance, workerId: "worker-b" },
};
for (const findings of [[first], [owned, independent]]) {
- await normal.write({ ...normal.draft(), findings });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings },
- false,
- );
+ await normal.writeFindings(findings);
+ await recovered.checkpoint(recovered.findingsDraft(findings));
}
- const result = await recoverAndFinalize(normal, recovered);
+ const result = await recover();
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
@@ -1541,8 +1296,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
}
for (const authored of [false, true]) {
test(`deep: ownership enrichment cannot bridge bound workers authored=${authored}`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workers = [],
findings = [];
for (const id of ["worker-a", "worker-b"]) {
@@ -1557,27 +1311,16 @@ for (const authored of [false, true]) {
value,
{ ...value, provenance: { ...value.provenance, workerId: id } },
]) {
- await draftApi.saveScanDraftCheckpoint(
- worker.context,
- { ...worker.draft(), findings: [row] },
- false,
- );
+ await worker.checkpoint(worker.findingsDraft([row]));
}
findings.push({
...value,
provenance: { ...value.provenance, workerId: id },
});
- workers.push({
- id,
- kind: "discovery",
- status: "canceled",
- artifact_dir: workerRoot,
- result_manifest_path: null,
- attempt: 1,
- });
+ workers.push(savedWorker(workerRoot, id));
}
- await normal.write({ ...normal.draft(), findings });
- const result = await recoverAndFinalize(normal, recovered, workers);
+ await normal.writeFindings(findings);
+ const result = await recover({ workers });
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
@@ -1588,8 +1331,7 @@ for (const order of ["earlier-first", "later-first"]) {
for (const metadata of ["extensions", "provenance"] as const) {
for (const initialLevel of ["low", "high"]) {
test(`worker revised raw checkpoint retains ${metadata} enrichment (${order}, ${initialLevel} to low)`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const normalRoot = path.join(normal.root, "reviewer"),
recoveredRoot = path.join(recovered.root, "reviewer");
for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
@@ -1606,7 +1348,7 @@ for (const order of ["earlier-first", "later-first"]) {
severity: { level: "low" },
[metadata]: { ...initial[metadata], candidateId: "candidate-1" },
};
- const oldDraft = { ...worker.draft(), findings: [initial] };
+ const oldDraft = worker.findingsDraft([initial]);
let newDraft,
suffix = 0;
do {
@@ -1623,26 +1365,16 @@ for (const order of ["earlier-first", "later-first"]) {
await worker.write(draft);
await saveCheckpointAt(recoveryWorker, draft, 100 + index * 100);
}
- const saved = JSON.parse(
- await readFile(path.join(normalRoot, "result.json"), "utf8"),
- );
+ const saved = await readJson(normalRoot, "result.json");
assert.equal(saved.findings.length, 1);
assert.equal(saved.findings[0].summary, revised.summary);
assert.equal(saved.findings[0].severity.level, "low");
assert.equal(saved.findings[0][metadata].candidateId, "candidate-1");
- await normal.write({
- ...normal.draft(),
- findings: saved.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "reviewer" },
- })),
+ await normal.writeFindings(withWorkerId(saved.findings, "reviewer"));
+ const result = await recover({
+ workers: [savedWorker(recoveredRoot)],
+ details: true,
});
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [savedWorker(recoveredRoot)],
- true,
- );
assert.deepEqual(result.warnings, []);
assert.equal(result.recovered.length, 1);
assert.deepEqual(result.recovered, result.normal);
@@ -1659,8 +1391,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
})) {
for (const authoredFirst of [true, false]) {
test(`${layout}: semantic identity reserves ${field} metadata (authored first=${authoredFirst})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const authored = finding("First review", {
identity: {
anchor: "candidate-1",
@@ -1685,13 +1416,9 @@ for (const layout of ["standard", "diff", "deep"] as const) {
const findings = authoredFirst
? [authored, generated, reserved]
: [generated, reserved, authored];
- await normal.write({ ...normal.draft(), findings });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings },
- false,
- );
- const result = await recoverAndFinalize(normal, recovered, [], true);
+ await normal.writeFindings(findings);
+ await recovered.checkpoint(recovered.findingsDraft(findings));
+ const result = await recover({ details: true });
assert.equal(result.normal.length, 3);
assert.equal(result.recovered.length, 3);
assert.deepEqual(result.warnings, []);
@@ -1713,8 +1440,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const sameTitle of [false, true]) {
test(`bound owner overrides shared metadata sameTitle=${sameTitle}`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workers = [],
findings = [];
for (const [index, id] of ["worker-a", "worker-b"].entries()) {
@@ -1733,22 +1459,13 @@ for (const sameTitle of [false, true]) {
},
},
);
- await worker.write({ ...worker.draft(), findings: [value] });
- const saved = JSON.parse(
- await readFile(path.join(workerRoot, "result.json"), "utf8"),
- );
+ await worker.writeFindings([value]);
+ const saved = await readJson(workerRoot, "result.json");
findings.push(...saved.findings);
- workers.push({
- id,
- kind: "discovery",
- status: "canceled",
- artifact_dir: workerRoot,
- result_manifest_path: null,
- attempt: 1,
- });
+ workers.push(savedWorker(workerRoot, id));
}
- await normal.write({ ...normal.draft(), findings });
- const result = await recoverAndFinalize(normal, recovered, workers);
+ await normal.writeFindings(findings);
+ const result = await recover({ workers });
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -1756,8 +1473,7 @@ for (const sameTitle of [false, true]) {
}
for (const authored of [false, true]) {
test(`bound owner keeps same worker metadata revision authored=${authored}`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(recovered.root, "worker-a"),
normalWorkerRoot = path.join(normal.root, "worker-a");
await mkdir(workerRoot);
@@ -1773,27 +1489,14 @@ for (const authored of [false, true]) {
},
...(authored ? { identity: { anchor: "authored-review" } } : {}),
});
- await normalWorker.write({ ...normalWorker.draft(), findings: [value] });
- await draftApi.saveScanDraftCheckpoint(
- worker.context,
- { ...worker.draft(), findings: [value] },
- false,
- );
+ await normalWorker.writeFindings([value]);
+ await worker.checkpoint(worker.findingsDraft([value]));
}
- const saved = JSON.parse(
- await readFile(path.join(normalWorkerRoot, "result.json"), "utf8"),
- );
- await normal.write({ ...normal.draft(), findings: saved.findings });
- const result = await recoverAndFinalize(normal, recovered, [
- {
- id: "worker-a",
- kind: "discovery",
- status: "canceled",
- artifact_dir: workerRoot,
- result_manifest_path: null,
- attempt: 1,
- },
- ]);
+ const saved = await readJson(normalWorkerRoot, "result.json");
+ await normal.writeFindings(saved.findings);
+ const result = await recover({
+ workers: [savedWorker(workerRoot, "worker-a")],
+ });
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -1803,8 +1506,7 @@ for (const authored of [false, true]) {
for (const metadata of ["provenance", "extensions"] as const) {
for (const shape of ["shared siblings", "reportId", "ledgerRowId"]) {
test(`raw group authority preserves ${shape} with ${metadata} candidates`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const normalRoot = path.join(normal.root, "reviewer"),
recoveredRoot = path.join(recovered.root, "reviewer");
for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
@@ -1828,38 +1530,24 @@ for (const metadata of ["provenance", "extensions"] as const) {
}),
};
for (const worker of [writer, interrupted])
- await worker.write({ ...worker.draft(), findings: initial });
+ await worker.writeFindings(initial);
await dateDraftFiles(recoveredRoot, 100);
- const update = { ...writer.draft(), findings: [revised] };
+ const update = writer.findingsDraft([revised]);
await writer.write(update);
- await draftApi.saveScanDraftCheckpoint(
- interrupted.context,
- update,
- false,
- );
+ await interrupted.checkpoint(update);
await utimes(
path.join(recoveredRoot, "checkpoints", checkpointName(update)),
200,
200,
);
- const saved = JSON.parse(
- await readFile(path.join(normalRoot, "result.json"), "utf8"),
- );
+ const saved = await readJson(normalRoot, "result.json");
assert.equal(saved.findings.length, initial.length);
- await normal.write({
- ...normal.draft(),
- findings: saved.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "reviewer" },
- })),
+ await normal.writeFindings(withWorkerId(saved.findings, "reviewer"));
+ const result = await recover({
+ workers: [savedWorker(recoveredRoot)],
+ details: true,
+ replay: true,
});
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [savedWorker(recoveredRoot)],
- true,
- true,
- );
const ordered = (rows: RecoveredFinding[]) =>
[...rows].sort((a, b) => a.findingId.localeCompare(b.findingId));
assert.equal(result.normal.length, initial.length);
@@ -1872,29 +1560,22 @@ for (const metadata of ["provenance", "extensions"] as const) {
for (const layout of ["standard", "diff", "deep"] as const) {
for (const authored of [false, true]) {
test(`${layout}: canonical group retains ownership enrichment (authored=${authored})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const initial = finding("Synthetic ownership", {
provenance: { source: "local_plugin", candidateId: "candidate-1" },
...(authored ? { identity: { anchor: "authored-review" } } : {}),
});
for (const writer of [normal, recovered])
- await writer.write({ ...writer.draft(), findings: [initial] });
+ await writer.writeFindings([initial]);
await dateDraftFiles(recovered.root, 100);
const revised = {
...initial,
provenance: { ...initial.provenance, workerId: "reviewer" },
};
- const update = { ...normal.draft(), findings: [revised] };
+ const update = normal.findingsDraft([revised]);
await normal.write(update);
await saveCheckpointAt(recovered, update, 200);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -1905,8 +1586,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const layout of ["standard", "diff"] as const) {
for (const metadata of ["provenance", "extensions"] as const) {
test(`${layout}: reciprocal containment preserves ${metadata} sibling identities`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("Synthetic review");
first[metadata] = { ...first[metadata], candidateId: "candidate-1" };
const second = {
@@ -1914,32 +1594,22 @@ for (const layout of ["standard", "diff"] as const) {
extensions: { ...first.extensions, reportId: "report-1" },
};
for (const writer of [normal, recovered])
- await writer.write({ ...writer.draft(), findings: [first, second] });
- const before = JSON.parse(
- await readFile(path.join(normal.root, "findings.json"), "utf8"),
- );
+ await writer.writeFindings([first, second]);
+ const before = await readJson(normal.root, "findings.json");
await dateDraftFiles(recovered.root, 100);
- const update = {
- ...normal.draft(),
- findings: [{ ...first, summary: "Revised evidence." }, second],
- };
+ const update = normal.findingsDraft([
+ { ...first, summary: "Revised evidence." },
+ second,
+ ]);
await normal.write(update);
- const saved = JSON.parse(
- await readFile(path.join(normal.root, "findings.json"), "utf8"),
- );
+ const saved = await readJson(normal.root, "findings.json");
assert.equal(saved.findings.length, 2);
assert.deepEqual(
saved.findings.map((row: FixtureFinding) => row.identity),
before.findings.map((row: FixtureFinding) => row.identity),
);
await saveCheckpointAt(recovered, update, 200);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -1959,25 +1629,22 @@ const revisionFinding = (level: string, summary: string) =>
});
for (const source of ["selected checkpoint", "published result"]) {
test(`finding precedence retains ${source} at tied timestamps`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const output = path.join(recovered.root, "reviewer");
await mkdir(output);
const worker = draftFixture(output, "worker");
- const initial = {
- ...worker.draft({}, true),
- findings: [revisionFinding("low", "Initial evidence.")],
- };
- const latest = {
- ...worker.draft({}, true),
- findings: [revisionFinding("high", "Completed evidence.")],
- };
+ const initial = worker.findingsDraft(
+ [revisionFinding("low", "Initial evidence.")],
+ { complete: true },
+ );
+ const latest = worker.findingsDraft(
+ [revisionFinding("high", "Completed evidence.")],
+ { complete: true },
+ );
await worker.write(initial);
await worker.write(latest);
- const saved = JSON.parse(
- await readFile(path.join(output, "result.json"), "utf8"),
- );
- await normal.write({ ...normal.draft({}, true), findings: saved.findings });
+ const saved = await readJson(output, "result.json");
+ await normal.writeFindings(saved.findings, { complete: true });
// Valid JSON whitespace controls filename order without changing the evidence.
const names = await readdir(path.join(output, "checkpoints"));
let contents = JSON.stringify(initial),
@@ -1992,13 +1659,11 @@ for (const source of ["selected checkpoint", "published result"]) {
await rm(path.join(output, "checkpoint-head.json"));
}
await dateDraftFiles(output, 100);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [savedWorker(output)],
- true,
- true,
- );
+ const result = await recover({
+ workers: [savedWorker(output)],
+ details: true,
+ replay: true,
+ });
assert.equal(result.normal[0].severity.level, "high");
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -2007,8 +1672,7 @@ for (const source of ["selected checkpoint", "published result"]) {
for (const layout of ["standard", "diff", "worker"] as const) {
test(`${layout}: finding precedence retains terminal evidence over later progress`, async (t) => {
const parentLayout = layout === "worker" ? "deep" : layout;
- const normal = await fixture(t, parentLayout),
- recovered = await fixture(t, parentLayout);
+ const { normal, recovered, recover } = await recoveryPair(t, parentLayout);
const normalRoot =
layout === "worker" ? path.join(normal.root, "reviewer") : normal.root;
const recoveredRoot =
@@ -2021,35 +1685,27 @@ for (const layout of ["standard", "diff", "worker"] as const) {
layout === "worker" ? draftFixture(normalRoot, "worker") : normal;
const interrupted =
layout === "worker" ? draftFixture(recoveredRoot, "worker") : recovered;
- const terminal = {
- ...writer.draft({}, true),
- findings: [revisionFinding("high", "Completed evidence.")],
- };
- const progress = {
- ...writer.draft(),
- findings: [revisionFinding("low", "Incomplete progress.")],
- };
+ const terminal = writer.findingsDraft(
+ [revisionFinding("high", "Completed evidence.")],
+ { complete: true },
+ );
+ const progress = writer.findingsDraft([
+ revisionFinding("low", "Incomplete progress."),
+ ]);
for (const f of [writer, interrupted]) await f.write(terminal);
await dateDraftFiles(recoveredRoot, 100);
await writer.write(progress);
await saveCheckpointAt(interrupted, progress, 200);
if (layout === "worker") {
- const saved = JSON.parse(
- await readFile(path.join(normalRoot, "result.json"), "utf8"),
- );
+ const saved = await readJson(normalRoot, "result.json");
assert.equal(saved.findings[0].severity.level, "high");
- await normal.write({
- ...normal.draft({}, true),
- findings: saved.findings,
- });
+ await normal.writeFindings(saved.findings, { complete: true });
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
- layout === "worker" ? [savedWorker(recoveredRoot)] : [],
- true,
- true,
- );
+ const result = await recover({
+ workers: layout === "worker" ? [savedWorker(recoveredRoot)] : [],
+ details: true,
+ replay: true,
+ });
assert.equal(result.normal[0].severity.level, "high");
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -2057,36 +1713,32 @@ for (const layout of ["standard", "diff", "worker"] as const) {
});
}
test("finding precedence compares parent and worker observation times", async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(recovered.root, "reviewer");
await mkdir(workerRoot);
const worker = draftFixture(workerRoot, "worker");
- await worker.write({
- ...worker.draft({}, true),
- findings: [revisionFinding("low", "Earlier worker evidence.")],
- });
- const latest = {
- ...normal.draft({}, true),
- findings: [revisionFinding("high", "Newer parent evidence.")],
- };
+ await worker.writeFindings(
+ [revisionFinding("low", "Earlier worker evidence.")],
+ { complete: true },
+ );
+ const latest = normal.findingsDraft(
+ [revisionFinding("high", "Newer parent evidence.")],
+ { complete: true },
+ );
for (const f of [normal, recovered]) await f.write(latest);
await dateDraftFiles(recovered.root, 200);
await dateDraftFiles(workerRoot, 100);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [savedWorker(workerRoot)],
- true,
- true,
- );
+ const result = await recover({
+ workers: [savedWorker(workerRoot)],
+ details: true,
+ replay: true,
+ });
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
});
for (const revised of [false, true]) {
test(`finding revision retains the published collision identity (revised=${revised})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const findings = [1, 2].map((line) =>
finding(`Synthetic report ${line}`, {
identity: { anchor: "shared" },
@@ -2101,9 +1753,9 @@ for (const revised of [false, true]) {
const workerRoot = path.join(recovered.root, "reviewer");
await mkdir(workerRoot);
const worker = draftFixture(workerRoot, "worker");
- await worker.write({ ...worker.draft({}, true), findings });
+ await worker.writeFindings(findings, { complete: true });
for (const f of [normal, recovered])
- await f.write({ ...f.draft({}, true), findings });
+ await f.writeFindings(findings, { complete: true });
await dateDraftFiles(recovered.root, 100);
const latest = findings.map((row) => ({
...row,
@@ -2114,15 +1766,12 @@ for (const revised of [false, true]) {
findings: latest,
threatModel: { summary: "New context." },
});
- if (revised)
- await normal.write({ ...normal.draft({}, true), findings: latest });
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [savedWorker(workerRoot)],
- true,
- true,
- );
+ if (revised) await normal.writeFindings(latest, { complete: true });
+ const result = await recover({
+ workers: [savedWorker(workerRoot)],
+ details: true,
+ replay: true,
+ });
assert.equal(result.normal[1].identity.instance, "saved-2");
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -2130,75 +1779,68 @@ for (const revised of [false, true]) {
}
test("finding precedence keeps a resumed worker revision despite newer archive timestamps", async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const output = path.join(recovered.root, "reviewer"),
archive = path.join(output, "attempts", "attempt-1");
await mkdir(archive, { recursive: true });
const oldWorker = draftFixture(archive, "worker"),
currentWorker = draftFixture(output, "worker");
- await oldWorker.write({
- ...oldWorker.draft({}, true),
- findings: [revisionFinding("high", "Archived assessment.")],
- });
- const latest = {
- ...currentWorker.draft({}, true),
- findings: [revisionFinding("low", "Corrected resumed assessment.")],
- };
+ await oldWorker.writeFindings(
+ [revisionFinding("high", "Archived assessment.")],
+ { complete: true },
+ );
+ const latest = currentWorker.findingsDraft(
+ [revisionFinding("low", "Corrected resumed assessment.")],
+ { complete: true },
+ );
await currentWorker.write(latest);
- await normal.write({ ...normal.draft({}, true), findings: latest.findings });
+ await normal.writeFindings(latest.findings, { complete: true });
await dateDraftFiles(output, 100);
await dateDraftFiles(archive, 200);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [{ ...savedWorker(output), attempt: 2 }],
- true,
- true,
- );
+ const result = await recover({
+ workers: [{ ...savedWorker(output), attempt: 2 }],
+ details: true,
+ replay: true,
+ });
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
});
test("finding precedence excludes archived attempts before comparing a parent revision", async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const output = path.join(recovered.root, "reviewer"),
archive = path.join(output, "attempts", "attempt-1");
await mkdir(archive, { recursive: true });
const oldWorker = draftFixture(archive, "worker"),
currentWorker = draftFixture(output, "worker");
- await oldWorker.write({
- ...oldWorker.draft({}, true),
- findings: [revisionFinding("low", "Archived assessment.")],
- });
- await currentWorker.write({
- ...currentWorker.draft({}, true),
- findings: [revisionFinding("low", "Current worker assessment.")],
- });
- const latest = {
- ...normal.draft({}, true),
- findings: [revisionFinding("high", "Newer parent assessment.")],
- };
+ await oldWorker.writeFindings(
+ [revisionFinding("low", "Archived assessment.")],
+ { complete: true },
+ );
+ await currentWorker.writeFindings(
+ [revisionFinding("low", "Current worker assessment.")],
+ { complete: true },
+ );
+ const latest = normal.findingsDraft(
+ [revisionFinding("high", "Newer parent assessment.")],
+ { complete: true },
+ );
for (const f of [normal, recovered]) await f.write(latest);
await dateDraftFiles(recovered.root, 150);
await dateDraftFiles(output, 100);
await dateDraftFiles(archive, 200);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [{ ...savedWorker(output), attempt: 2 }],
- true,
- true,
- );
+ const result = await recover({
+ workers: [{ ...savedWorker(output), attempt: 2 }],
+ details: true,
+ replay: true,
+ });
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
});
for (const reverse of [false, true]) {
test(`worker raw checkpoint retains ambiguous candidate siblings (reverse=${reverse})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
for (const f of [normal, recovered])
await mkdir(path.join(f.root, "reviewer"));
const writer = draftFixture(path.join(normal.root, "reviewer"), "worker"),
@@ -2218,23 +1860,14 @@ for (const reverse of [false, true]) {
const ordered = (rows: FixtureFinding[]) =>
reverse ? [...rows].reverse() : rows;
for (const f of [writer, recoveryWriter])
- await f.write({ ...f.draft(), findings: ordered([first, second]) });
+ await f.writeFindings(ordered([first, second]));
await dateDraftFiles(recoveryWriter.root, 100);
- await writer.write({
- ...writer.draft(),
- findings: ordered([revised, second]),
- });
- const published = JSON.parse(
- await readFile(path.join(writer.root, "result.json"), "utf8"),
- );
+ await writer.writeFindings(ordered([revised, second]));
+ const published = await readJson(writer.root, "result.json");
assert.equal(published.findings.length, 3);
await interruptDraftWrite(
path.join(recoveryWriter.root, "checkpoints", checkpointName(published)),
- () =>
- recoveryWriter.write({
- ...recoveryWriter.draft(),
- findings: ordered([revised, second]),
- }),
+ () => recoveryWriter.writeFindings(ordered([revised, second])),
);
const files = [
"result.json",
@@ -2246,20 +1879,12 @@ for (const reverse of [false, true]) {
const originals = await Promise.all(
files.map((name) => readFile(path.join(recoveryWriter.root, name))),
);
- await normal.write({
- ...normal.draft(),
- findings: published.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "reviewer" },
- })),
+ await normal.writeFindings(withWorkerId(published.findings, "reviewer"));
+ const result = await recover({
+ workers: [savedWorker(recoveryWriter.root)],
+ details: true,
+ replay: true,
});
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [savedWorker(recoveryWriter.root)],
- true,
- true,
- );
assert.equal(result.normal.length, 3);
assert.equal(result.recovered.length, 3);
const byTitle = (rows: RecoveredFinding[]) =>
@@ -2278,8 +1903,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const reverse of [false, true]) {
for (const published of [false, true]) {
test(`one-to-one ${layout} unreported revision (published=${published}, reverse=${reverse})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("First review");
const revised = {
...first,
@@ -2289,28 +1913,16 @@ for (const layout of ["standard", "diff", "deep"] as const) {
const second = finding("Independent review", {
extensions: { reportId: "report-2" },
});
- const initial = { ...normal.draft(), findings: [first] };
+ const initial = normal.findingsDraft([first]);
await normal.write(initial);
- if (published)
- await recovered.write({ ...recovered.draft(), findings: [first] });
- else
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings: [first] },
- false,
- );
+ if (published) await recovered.writeFindings([first]);
+ else await recovered.checkpoint(recovered.findingsDraft([first]));
await dateDraftFiles(recovered.root, 100);
const rows = reverse ? [second, revised] : [revised, second];
- await normal.write({ ...normal.draft(), findings: rows });
- const update = { ...recovered.draft(), findings: rows };
+ await normal.writeFindings(rows);
+ const update = recovered.findingsDraft(rows);
await saveCheckpointAt(recovered, update, 200);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, 2);
const ordered = (values: RecoveredFinding[]) =>
@@ -2320,8 +1932,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
});
}
test(`one-to-one ${layout} historical siblings (reverse=${reverse})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("Synthetic review", {
extensions: { candidateId: "candidate-1" },
});
@@ -2331,17 +1942,11 @@ for (const layout of ["standard", "diff", "deep"] as const) {
};
const finalRows = reverse ? [second, first] : [first, second];
for (const [index, rows] of [[first], [second], finalRows].entries()) {
- await normal.write({ ...normal.draft(), findings: rows });
- const update = { ...recovered.draft(), findings: rows };
+ await normal.writeFindings(rows);
+ const update = recovered.findingsDraft(rows);
await saveCheckpointAt(recovered, update, (index + 1) * 100);
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, 2);
const ordered = (values: RecoveredFinding[]) =>
@@ -2361,8 +1966,7 @@ for (const [field, value] of Object.entries({
})) {
for (const reservedFirst of [false, true]) {
test(`worker collision reserves semantic ${field} identity (reserved first=${reservedFirst})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workers = [],
findings = [];
for (const index of reservedFirst ? [2, 0, 1] : [0, 1, 2]) {
@@ -2382,25 +1986,12 @@ for (const [field, value] of Object.entries({
workerId: id,
},
});
- await worker.write({ ...worker.draft(), findings: [row] });
+ await worker.writeFindings([row]);
findings.push(row);
- workers.push({
- id,
- kind: "discovery",
- status: "canceled",
- artifact_dir: workerRoot,
- result_manifest_path: null,
- attempt: 1,
- });
+ workers.push(savedWorker(workerRoot, id));
}
- await normal.write({ ...normal.draft(), findings });
- const result = await recoverAndFinalize(
- normal,
- recovered,
- workers,
- true,
- true,
- );
+ await normal.writeFindings(findings);
+ const result = await recover({ workers, details: true, replay: true });
assert.equal(result.normal.length, 3);
assert.equal(result.recovered.length, 3);
const ordered = (rows: RecoveredFinding[]) =>
@@ -2419,31 +2010,20 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const metadata of ["extensions", "provenance"] as const) {
for (const reversed of [false, true]) {
test(`${layout}: unchanged report precedes ${metadata} enrichment matching (reversed=${reversed})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("Synthetic review");
const sibling = {
...structuredClone(first),
[metadata]: { ...first[metadata], candidateId: "candidate-1" },
};
- await normal.write({ ...normal.draft(), findings: [first] });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings: [first] },
- false,
- );
+ await normal.writeFindings([first]);
+ await recovered.checkpoint(recovered.findingsDraft([first]));
await dateDraftFiles(recovered.root, 100);
const rows = reversed ? [sibling, first] : [first, sibling];
- await normal.write({ ...normal.draft(), findings: rows });
- const update = { ...recovered.draft(), findings: rows };
+ await normal.writeFindings(rows);
+ const update = recovered.findingsDraft(rows);
await saveCheckpointAt(recovered, update, 200);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, 2);
const ordered = (rows: RecoveredFinding[]) =>
@@ -2459,8 +2039,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const candidate of [false, true]) {
for (const reversed of [false, true]) {
test(`${layout}: ambiguous unmatched sibling survives exact batch assignment (reversed=${reversed}, candidate=${candidate})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("First review"),
second = finding("Second review"),
added = finding(
@@ -2475,20 +2054,14 @@ for (const layout of ["standard", "diff", "deep"] as const) {
: {},
);
for (const f of [normal, recovered]) {
- await f.write({ ...f.draft(), findings: [first, second] });
+ await f.writeFindings([first, second]);
await dateDraftFiles(f.root, 100);
}
const rows = reversed ? [added, second] : [second, added];
- await normal.write({ ...normal.draft(), findings: rows });
- const update = { ...recovered.draft(), findings: rows };
+ await normal.writeFindings(rows);
+ const update = recovered.findingsDraft(rows);
await saveCheckpointAt(recovered, update, 200);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 3);
assert.equal(result.recovered.length, 3);
const ordered = (rows: RecoveredFinding[]) =>
@@ -2500,25 +2073,18 @@ for (const layout of ["standard", "diff", "deep"] as const) {
}
for (const field of ["reportId", "ledgerRowId"]) {
test(`${layout}: compatible ${field} enrichment identifies its existing sibling`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("First review"),
second = finding("Second review");
for (const f of [normal, recovered]) {
- await f.write({ ...f.draft(), findings: [first, second] });
+ await f.writeFindings([first, second]);
await dateDraftFiles(f.root, 100);
}
const refined = { ...first, extensions: { [field]: "report-1" } };
- await normal.write({ ...normal.draft(), findings: [refined] });
- const update = { ...recovered.draft(), findings: [refined] };
+ await normal.writeFindings([refined]);
+ const update = recovered.findingsDraft([refined]);
await saveCheckpointAt(recovered, update, 200);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, 2);
const ordered = (rows: RecoveredFinding[]) =>
@@ -2531,8 +2097,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const field of ["description", "source", "version"]) {
for (const candidate of [false, true]) {
test(`worker identity ${field} annotation revision keeps one report (candidate=${candidate})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(recovered.root, "reviewer");
await mkdir(workerRoot);
const worker = draftFixture(workerRoot, "worker");
@@ -2548,25 +2113,17 @@ for (const field of ["description", "source", "version"]) {
...(candidate ? { candidateId: "candidate-1" } : {}),
},
});
- await worker.write({ ...worker.draft(), findings: [first] });
+ await worker.writeFindings([first]);
await dateDraftFiles(workerRoot, 100);
const revised = {
...first,
identity: { ...first.identity, [field]: "revised" },
};
- await worker.write({ ...worker.draft(), findings: [revised] });
- const saved = JSON.parse(
- await readFile(path.join(workerRoot, "result.json"), "utf8"),
- );
- await normal.write({ ...normal.draft(), findings: saved.findings });
+ await worker.writeFindings([revised]);
+ const saved = await readJson(workerRoot, "result.json");
+ await normal.writeFindings(saved.findings);
const workers = [savedWorker(workerRoot)];
- const result = await recoverAndFinalize(
- normal,
- recovered,
- workers,
- true,
- true,
- );
+ const result = await recover({ workers, details: true, replay: true });
assert.equal(result.normal.length, 1);
assert.equal(result.recovered.length, 1);
assert.deepEqual(result.recovered, result.normal);
@@ -2578,34 +2135,27 @@ for (const field of ["description", "source", "version"]) {
for (const metadata of ["extensions", "provenance"] as const) {
for (const malformedFirst of [false, true]) {
test(`discarded ${metadata} sibling cannot change a valid identity (malformed first=${malformedFirst})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(recovered.root, "reviewer");
await mkdir(workerRoot);
const worker = draftFixture(workerRoot, "worker");
const row = finding("Synthetic review");
row[metadata] = { ...row[metadata], candidateId: "candidate-1" };
row.provenance = { ...row.provenance, workerId: "reviewer" };
- await worker.write({ ...worker.draft(), findings: [row] });
+ await worker.writeFindings([row]);
await dateDraftFiles(workerRoot, 100);
- await normal.write({ ...normal.draft(), findings: [row] });
+ await normal.writeFindings([row]);
const { summary: _summary, ...malformed } = {
...structuredClone(row),
locations: [{ path: "src/example.py", startLine: 2 }],
};
const resultFile = path.join(workerRoot, "result.json");
- const saved = JSON.parse(await readFile(resultFile, "utf8"));
+ const saved = await readJson(resultFile);
saved.findings = malformedFirst ? [malformed, row] : [row, malformed];
await writeFile(resultFile, JSON.stringify(saved));
await utimes(resultFile, 200, 200);
const workers = [savedWorker(workerRoot)];
- const result = await recoverAndFinalize(
- normal,
- recovered,
- workers,
- true,
- true,
- );
+ const result = await recover({ workers, details: true, replay: true });
assert.equal(result.normal.length, 1);
assert.equal(result.recovered.length, 1);
assert.deepEqual(result.recovered, result.normal);
@@ -2618,8 +2168,7 @@ for (const field of ["description", "source", "version"]) {
for (const candidate of [false, true]) {
for (const order of ["earlier-first", "later-first"]) {
test(`worker identity ${field} annotation revision survives checkpoint order (${order}, candidate=${candidate})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const normalRoot = path.join(normal.root, "reviewer"),
recoveredRoot = path.join(recovered.root, "reviewer");
for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
@@ -2643,7 +2192,7 @@ for (const field of ["description", "source", "version"]) {
severity: { level: "high" },
identity: { ...first.identity, [field]: "revised" },
};
- const oldDraft = { ...worker.draft(), findings: [first] };
+ const oldDraft = worker.findingsDraft([first]);
let newDraft,
suffix = 0;
do {
@@ -2660,20 +2209,12 @@ for (const field of ["description", "source", "version"]) {
await worker.write(draft);
await saveCheckpointAt(recoveryWorker, draft, 100 + index * 100);
}
- const saved = JSON.parse(
- await readFile(path.join(normalRoot, "result.json"), "utf8"),
- );
+ const saved = await readJson(normalRoot, "result.json");
assert.equal(saved.findings.length, 1);
assert.equal(saved.findings[0].identity[field], "revised");
- await normal.write({ ...normal.draft(), findings: saved.findings });
+ await normal.writeFindings(saved.findings);
const workers = [savedWorker(recoveredRoot)];
- const result = await recoverAndFinalize(
- normal,
- recovered,
- workers,
- true,
- true,
- );
+ const result = await recover({ workers, details: true, replay: true });
assert.equal(result.normal.length, 1);
assert.equal(result.recovered.length, 1);
assert.deepEqual(result.recovered, result.normal);
@@ -2686,14 +2227,12 @@ for (const field of ["description", "source", "version"]) {
for (const layout of ["standard", "diff", "deep"] as const) {
for (const metadata of ["extensions", "provenance"] as const) {
test(`${layout}: malformed canonical ${metadata} sibling cannot alter valid identity or frozen replay`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const valid = finding("Synthetic review");
valid[metadata] = { ...valid[metadata], candidateId: "candidate-1" };
- for (const f of [normal, recovered])
- await f.write({ ...f.draft(), findings: [valid] });
+ for (const f of [normal, recovered]) await f.writeFindings([valid]);
const destination = path.join(recovered.root, "findings.json");
- const document = JSON.parse(await readFile(destination, "utf8"));
+ const document = await readJson(destination);
const { summary: _summary, ...invalid } = {
...valid,
locations: [{ path: "src/example.py", startLine: 2 }],
@@ -2704,13 +2243,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
recursive: true,
force: true,
});
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
assert.equal(result.warnings.length, 1);
@@ -2721,8 +2254,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const sameLocation of [false, true]) {
for (const level of ["low", "high"]) {
test(`absorbed worker report keeps independent candidate sibling (same location=${sameLocation}, ${level})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(recovered.root, "reviewer");
await mkdir(workerRoot);
const worker = draftFixture(workerRoot, "worker");
@@ -2754,25 +2286,20 @@ for (const sameLocation of [false, true]) {
sourceFindings: [{ id: "reviewer:0", finding: first }],
},
};
- await worker.write({ ...worker.draft({}, true), findings: [first] });
+ await worker.writeFindings([first], { complete: true });
await dateDraftFiles(workerRoot, 100);
for (const f of [normal, recovered])
- await f.write({ ...f.draft({}, true), findings: [parent] });
+ await f.writeFindings([parent], { complete: true });
await dateDraftFiles(recovered.root, 200);
await dateDraftFiles(workerRoot, 100);
- const checkpoint = { ...worker.draft(), findings: [first, second] };
+ const checkpoint = worker.findingsDraft([first, second]);
await saveCheckpointAt(worker, checkpoint, 300);
- await normal.write({
- ...normal.draft({}, true),
- findings: [parent, second],
+ await normal.writeFindings([parent, second], { complete: true });
+ const result = await recover({
+ workers: [savedWorker(workerRoot)],
+ details: true,
+ replay: true,
});
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [savedWorker(workerRoot)],
- true,
- true,
- );
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -2782,8 +2309,10 @@ for (const sameLocation of [false, true]) {
for (const layout of ["standard", "diff", "deep", "worker"] as const) {
for (const update of ["omitted", "partial"] as const) {
test(`${layout}: accepted provenance arrays survive ${update} checkpoint details`, async (t) => {
- const normal = await fixture(t, layout === "worker" ? "deep" : layout),
- recovered = await fixture(t, layout === "worker" ? "deep" : layout);
+ const { normal, recovered, recover } = await recoveryPair(
+ t,
+ layout === "worker" ? "deep" : layout,
+ );
let normalWriter = normal,
recoveredWriter = recovered;
const workers: Record<string, unknown>[] = [];
@@ -2849,28 +2378,21 @@ for (const layout of ["standard", "diff", "deep", "worker"] as const) {
},
};
for (const writer of [normalWriter, recoveredWriter])
- await writer.write({ ...writer.draft(), findings: [first] });
+ await writer.writeFindings([first]);
await dateDraftFiles(recoveredWriter.root, 100);
- await normalWriter.write({
- ...normalWriter.draft(),
- findings: [revised],
- });
- const checkpoint = { ...recoveredWriter.draft(), findings: [revised] };
+ await normalWriter.writeFindings([revised]);
+ const checkpoint = recoveredWriter.findingsDraft([revised]);
await saveCheckpointAt(recoveredWriter, checkpoint, 200);
if (layout === "worker") {
- const accepted = JSON.parse(
- await readFile(path.join(normalWriter.root, "result.json"), "utf8"),
- );
- await normal.write({ ...normal.draft(), findings: accepted.findings });
+ const accepted = await readJson(normalWriter.root, "result.json");
+ await normal.writeFindings(accepted.findings);
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
+ const result = await recover({
workers,
- true,
- true,
- true,
- );
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -2880,8 +2402,10 @@ for (const layout of ["standard", "diff", "deep", "worker"] as const) {
for (const layout of ["standard", "diff", "deep", "worker"] as const) {
for (const field of ["reportId", "ledgerRowId"] as const) {
test(`${layout}: revised sibling keeps identity through ${field} enrichment`, async (t) => {
- const normal = await fixture(t, layout === "worker" ? "deep" : layout),
- recovered = await fixture(t, layout === "worker" ? "deep" : layout);
+ const { normal, recovered, recover } = await recoveryPair(
+ t,
+ layout === "worker" ? "deep" : layout,
+ );
let normalWriter = normal,
recoveredWriter = recovered;
const workers: Record<string, unknown>[] = [];
@@ -2901,7 +2425,7 @@ for (const layout of ["standard", "diff", "deep", "worker"] as const) {
);
const second = { ...first, title: "Second review" };
for (const writer of [normalWriter, recoveredWriter])
- await writer.write({ ...writer.draft(), findings: [first, second] });
+ await writer.writeFindings([first, second]);
await dateDraftFiles(recoveredWriter.root, 100);
const revised = {
...first,
@@ -2909,25 +2433,14 @@ for (const layout of ["standard", "diff", "deep", "worker"] as const) {
severity: { level: "high" },
extensions: { [field]: "report-1" },
};
- await normalWriter.write({
- ...normalWriter.draft(),
- findings: [revised],
- });
- const checkpoint = { ...recoveredWriter.draft(), findings: [revised] };
+ await normalWriter.writeFindings([revised]);
+ const checkpoint = recoveredWriter.findingsDraft([revised]);
await saveCheckpointAt(recoveredWriter, checkpoint, 200);
if (layout === "worker") {
- const accepted = JSON.parse(
- await readFile(path.join(normalWriter.root, "result.json"), "utf8"),
- );
- await normal.write({ ...normal.draft(), findings: accepted.findings });
+ const accepted = await readJson(normalWriter.root, "result.json");
+ await normal.writeFindings(accepted.findings);
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
- workers,
- true,
- true,
- );
+ const result = await recover({ workers, details: true, replay: true });
assert.equal(result.normal.length, 2);
const sorted = (rows: RecoveredFinding[]) =>
[...rows].sort((a, b) => a.title.localeCompare(b.title));
@@ -2944,16 +2457,16 @@ for (const layout of ["standard", "diff"] as const) {
const first = finding("Synthetic review", {
extensions: { [field]: "old-report" },
});
- await f.write({ ...f.draft(), findings: [first] });
- const initial: FixtureFinding = JSON.parse(
- await readFile(path.join(f.root, "findings.json"), "utf8"),
- ).findings[0];
+ await f.writeFindings([first]);
+ const initial: FixtureFinding = (await readJson(f.root, "findings.json"))
+ .findings[0];
assert.ok(initial.identity);
const revised = { ...initial, extensions: { [field]: "new-report" } };
- for (const input of [{ ...f.draft(), findings: [revised] }, f.draft()]) {
+ for (const input of [f.findingsDraft([revised]), f.draft()]) {
await f.write(input);
- const saved: { findings: FixtureFinding[] } = JSON.parse(
- await readFile(path.join(f.root, "findings.json"), "utf8"),
+ const saved: { findings: FixtureFinding[] } = await readJson(
+ f.root,
+ "findings.json",
);
assert.equal(saved.findings.length, 1);
const retained = saved.findings[0]!;
@@ -2978,18 +2491,15 @@ for (const layout of ["standard", "diff", "worker"] as const) {
summary: "Original evidence.",
});
const ancestor = { ...original, summary: "Earlier source evidence." };
- await f.write({
- ...f.draft(),
- findings: [
- {
- ...original,
- provenance: {
- ...original.provenance,
- previousFindings: [ancestor],
- },
+ await f.writeFindings([
+ {
+ ...original,
+ provenance: {
+ ...original.provenance,
+ previousFindings: [ancestor],
},
- ],
- });
+ },
+ ]);
const revised = {
...original,
...(separateIdentity ? { identity: { anchor: "revised-report" } } : {}),
@@ -3007,15 +2517,10 @@ for (const layout of ["standard", "diff", "worker"] as const) {
};
let saved: { findings: FixtureFinding[] };
for (let replay = 0; replay < 2; replay++) {
- await f.write({ ...f.draft(), findings: [revised] });
- saved = JSON.parse(
- await readFile(
- path.join(
- f.root,
- layout === "worker" ? "result.json" : "findings.json",
- ),
- "utf8",
- ),
+ await f.writeFindings([revised]);
+ saved = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "findings.json",
);
assert.ok(
containsAncestor(saved.findings),
@@ -3028,18 +2533,12 @@ for (const layout of ["standard", "diff", "worker"] as const) {
}
const parent = layout === "worker" ? await fixture(t, "deep") : f;
if (layout === "worker")
- await parent.write({
- ...parent.draft({}, true),
- findings: saved!.findings,
- });
- const finalized = await recoverAndFinalize(
- parent,
- parent,
- [],
- true,
- true,
- true,
- );
+ await parent.writeFindings(saved!.findings, { complete: true });
+ const finalized = await recoverAndFinalize(parent, parent, {
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
assert.ok(containsAncestor(finalized.normal));
assert.ok(containsAncestor(finalized.recovered));
assert.deepEqual(finalized.warnings, []);
@@ -3060,16 +2559,17 @@ for (const layout of ["standard", "diff", "deep"] as const) {
},
}),
);
- await f.write({ ...f.draft(), findings: initial });
+ await f.writeFindings(initial);
const revised = initial.map(({ identity: _identity, ...row }, index) => ({
...row,
title: index === 0 ? "Second review" : "Third review",
summary: "Revised evidence.",
}));
for (let replay = 0; replay < 2; replay++) {
- await f.write({ ...f.draft(), findings: revised });
- const saved: { findings: FixtureFinding[] } = JSON.parse(
- await readFile(path.join(f.root, "findings.json"), "utf8"),
+ await f.writeFindings(revised);
+ const saved: { findings: FixtureFinding[] } = await readJson(
+ f.root,
+ "findings.json",
);
for (const previous of initial) {
const retained = saved.findings.filter(
@@ -3088,7 +2588,10 @@ for (const layout of ["standard", "diff", "deep"] as const) {
}
}
}
- const finalized = await recoverAndFinalize(f, f, [], true, true);
+ const finalized = await recoverAndFinalize(f, f, {
+ details: true,
+ replay: true,
+ });
for (const rows of [finalized.normal, finalized.recovered]) {
for (const previous of initial) {
const retained = rows.filter(
@@ -3106,8 +2609,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const cut of ["raw", "published"]) {
for (const reversed of [false, true]) {
test(`${layout}: unchanged ownership selects its saved sibling (${cut}, reversed=${reversed})`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const initial = finding("Synthetic ownership review", {
provenance: { source: "local_plugin", candidateId: "candidate-1" },
});
@@ -3115,40 +2617,24 @@ for (const layout of ["standard", "diff", "deep"] as const) {
...initial,
provenance: { ...initial.provenance, workerId: "worker-a" },
};
- await normal.write({ ...normal.draft(), findings: [initial] });
- const published = JSON.parse(
- await readFile(path.join(normal.root, "findings.json"), "utf8"),
- );
+ await normal.writeFindings([initial]);
+ const published = await readJson(normal.root, "findings.json");
if (cut === "published") {
- await recovered.write({ ...recovered.draft(), findings: [initial] });
+ await recovered.writeFindings([initial]);
} else {
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings: [initial] },
- false,
- );
+ await recovered.checkpoint(recovered.findingsDraft([initial]));
}
const findings = reversed ? [owned, initial] : [initial, owned];
- await normal.write({ ...normal.draft(), findings });
+ await normal.writeFindings(findings);
if (cut === "published") {
await interruptDraftWrite(
path.join(recovered.root, "findings.json"),
- () => recovered.write({ ...recovered.draft(), findings }),
+ () => recovered.writeFindings(findings),
);
} else {
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(), findings },
- false,
- );
+ await recovered.checkpoint(recovered.findingsDraft(findings));
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, 2);
const contents = (rows: RecoveredFinding[]) =>
@@ -3185,8 +2671,10 @@ for (const layout of ["standard", "diff", "deep"] as const) {
for (const layout of ["standard", "diff", "deep", "worker"] as const) {
for (const candidate of [false, true]) {
test(`${layout}: live revisions inherit the published identity from retained history (candidate=${candidate})`, async (t) => {
- const normal = await fixture(t, layout === "worker" ? "deep" : layout);
- const recovered = await fixture(t, layout === "worker" ? "deep" : layout);
+ const { normal, recovered, recover } = await recoveryPair(
+ t,
+ layout === "worker" ? "deep" : layout,
+ );
let normalWriter = normal,
recoveredWriter = recovered;
const workers: Record<string, unknown>[] = [];
@@ -3211,36 +2699,21 @@ for (const layout of ["standard", "diff", "deep", "worker"] as const) {
revised.summary = "Revised evidence.";
revised.provenance.previousFindings = [original];
for (const writer of [normalWriter, recoveredWriter])
- await writer.write({ ...writer.draft(), findings: [original] });
+ await writer.writeFindings([original]);
for (let replay = 0; replay < 2; replay++) {
- await normalWriter.write({
- ...normalWriter.draft(),
- findings: [revised],
- });
+ await normalWriter.writeFindings([revised]);
await interruptDraftWrite(
path.join(
recoveredWriter.root,
layout === "worker" ? "result.json" : "findings.json",
),
- () =>
- recoveredWriter.write({
- ...recoveredWriter.draft(),
- findings: [revised],
- }),
+ () => recoveredWriter.writeFindings([revised]),
);
if (layout === "worker") {
- const saved = JSON.parse(
- await readFile(path.join(normalWriter.root, "result.json"), "utf8"),
- );
- await normal.write({ ...normal.draft(), findings: saved.findings });
+ const saved = await readJson(normalWriter.root, "result.json");
+ await normal.writeFindings(saved.findings);
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
- workers,
- true,
- true,
- );
+ const result = await recover({ workers, details: true, replay: true });
assert.equal(result.normal.length, 1);
assert.deepEqual(result.normal[0]!.identity, original.identity);
assert.equal(result.normal[0]!.summary, revised.summary);
@@ -3273,10 +2746,7 @@ for (const layout of ["standard", "diff", "deep", "worker"] as const) {
title: "Independent shared-candidate review",
summary: "Independent evidence remains active.",
};
- await f.write({
- ...f.draft(),
- findings: reversed ? [sibling, first] : [first, sibling],
- });
+ await f.writeFindings(reversed ? [sibling, first] : [first, sibling]);
const revised = {
...first,
summary: "Revised evidence.",
@@ -3287,15 +2757,10 @@ for (const layout of ["standard", "diff", "deep", "worker"] as const) {
};
let previous: unknown;
for (let replay = 0; replay < 2; replay++) {
- await f.write({ ...f.draft(), findings: [revised] });
- const saved = JSON.parse(
- await readFile(
- path.join(
- f.root,
- layout === "worker" ? "result.json" : "findings.json",
- ),
- "utf8",
- ),
+ await f.writeFindings([revised]);
+ const saved = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "findings.json",
);
assert.equal(
saved.findings.length,
@@ -3320,8 +2785,7 @@ for (const layout of ["standard", "diff", "deep", "worker"] as const) {
for (const evidence of ["identical", "distinct", "reordered"] as const) {
for (const includeResult of [false, true]) {
test(`unchanged worker batch retains ${evidence} provenance (result=${includeResult})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(recovered.root, "reviewer");
await mkdir(workerRoot);
const worker = draftFixture(workerRoot, "worker");
@@ -3336,32 +2800,21 @@ for (const evidence of ["identical", "distinct", "reordered"] as const) {
},
}),
);
- await worker.write({ ...worker.draft({}, true), findings });
+ await worker.writeFindings(findings, { complete: true });
if (evidence === "reordered")
- await worker.write({
- ...worker.draft({}, true),
- findings: [...findings].reverse(),
- });
- const saved = JSON.parse(
- await readFile(path.join(workerRoot, "result.json"), "utf8"),
- );
+ await worker.writeFindings([...findings].reverse(), { complete: true });
+ const saved = await readJson(workerRoot, "result.json");
assert.equal(saved.findings.length, 2);
- await normal.write({
- ...normal.draft({}, true),
- findings: saved.findings.map((row: FixtureFinding) => ({
- ...row,
- provenance: { ...row.provenance, workerId: "reviewer" },
- })),
+ await normal.writeFindings(withWorkerId(saved.findings, "reviewer"), {
+ complete: true,
});
if (!includeResult) await rm(path.join(workerRoot, "result.json"));
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [savedWorker(workerRoot)],
- true,
- true,
- true,
- );
+ const result = await recover({
+ workers: [savedWorker(workerRoot)],
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
const ordered = (rows: RecoveredFinding[]) =>
[...rows].sort((a, b) => a.findingId.localeCompare(b.findingId));
assert.equal(result.normal.length, 2);
@@ -3383,8 +2836,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
},
})) {
test(`${layout}: preserved identity metadata ${metadata} survives ${cut} interruption`, async (t) => {
- const normal = await fixture(t, layout === "worker" ? "deep" : layout);
- const recovered = await fixture(
+ const { normal, recovered, recover } = await recoveryPair(
t,
layout === "worker" ? "deep" : layout,
);
@@ -3410,7 +2862,7 @@ for (const layout of ["standard", "diff", "worker"] as const) {
},
});
for (const f of [writer, recoveryWriter])
- await f.write({ ...f.draft(), findings: [initial] });
+ await f.writeFindings([initial]);
await dateDraftFiles(recoveryWriter.root, 100);
const revised = {
...initial,
@@ -3418,41 +2870,31 @@ for (const layout of ["standard", "diff", "worker"] as const) {
severity: { level: "high" },
};
delete revised.identity;
- await writer.write({ ...writer.draft(), findings: [revised] });
+ await writer.writeFindings([revised]);
const filename = layout === "worker" ? "result.json" : "findings.json";
if (cut === "raw")
- await draftApi.saveScanDraftCheckpoint(
- recoveryWriter.context,
- { ...recoveryWriter.draft(), findings: [revised] },
- false,
+ await recoveryWriter.checkpoint(
+ recoveryWriter.findingsDraft([revised]),
);
else
await interruptDraftWrite(
path.join(recoveryWriter.root, filename),
- () =>
- recoveryWriter.write({
- ...recoveryWriter.draft(),
- findings: [revised],
- }),
+ () => recoveryWriter.writeFindings([revised]),
);
- const saved = JSON.parse(
- await readFile(path.join(writer.root, filename), "utf8"),
- );
+ const saved = await readJson(writer.root, filename);
assert.equal(saved.findings.length, 1);
assert.equal(saved.findings[0].severity.level, "high");
assert.deepEqual(
saved.findings[0].provenance.preservedIdentity,
preservedIdentity,
);
- if (layout === "worker")
- await normal.write({ ...normal.draft(), findings: saved.findings });
- const result = await recoverAndFinalize(
- normal,
- recovered,
- layout === "worker" ? [savedWorker(recoveryWriter.root)] : [],
- true,
- true,
- );
+ if (layout === "worker") await normal.writeFindings(saved.findings);
+ const result = await recover({
+ workers:
+ layout === "worker" ? [savedWorker(recoveryWriter.root)] : [],
+ details: true,
+ replay: true,
+ });
assert.deepEqual(result.preservedIdentities, [
[preservedIdentity],
[preservedIdentity],
@@ -3472,8 +2914,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
"explicit changed",
] as const) {
test(`${layout}: preserves canonical finding identity after revision (${variant})`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const initial = finding("Synthetic review", {
identity: {
anchor: "stable-authored",
@@ -3481,8 +2922,7 @@ for (const layout of ["standard", "diff", "deep"] as const) {
description: "Saved annotation",
},
});
- for (const f of [normal, recovered])
- await f.write({ ...f.draft(), findings: [initial] });
+ for (const f of [normal, recovered]) await f.writeFindings([initial]);
const revised = {
...structuredClone(initial),
summary: "Revised synthetic evidence.",
@@ -3494,30 +2934,18 @@ for (const layout of ["standard", "diff", "deep"] as const) {
instance: "report-2",
description: "Revised annotation",
};
- await normal.write({ ...normal.draft(), findings: [revised] });
+ await normal.writeFindings([revised]);
const dest = path.join(recovered.root, "findings.json");
- const doc = JSON.parse(await readFile(dest, "utf8"));
+ const doc = await readJson(dest);
doc.findings[0].summary = revised.summary;
if (variant === "legacy missing") delete doc.findings[0].identity;
else doc.findings[0].identity = revised.identity;
await writeFile(dest, JSON.stringify(doc));
// Canonical legacy documents accept an omitted identity; no newer raw checkpoint exists.
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- false,
- );
+ const result = await recover({ details: true });
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
- const replay = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const replay = await recover({ details: true, replay: true });
assert.deepEqual(replay.recovered, result.recovered);
});
}
@@ -3527,8 +2955,7 @@ for (const layout of ["standard", "diff", "deep"] as const)
for (const reversed of [false, true]) {
for (const historical of [false, true])
test(`${layout}: explicit sibling assignment preserves revised identity (reverse=${reversed}, history=${historical})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("First review", {
identity: { anchor: "saved-a" },
provenance: {
@@ -3544,7 +2971,7 @@ for (const layout of ["standard", "diff", "deep"] as const)
const ordered = (rows: FixtureFinding[]) =>
reversed ? rows.toReversed() : rows;
for (const f of [normal, recovered])
- await f.write({ ...f.draft(), findings: ordered([first, second]) });
+ await f.writeFindings(ordered([first, second]));
const revised = {
...structuredClone(first),
title: "Revised first review",
@@ -3552,18 +2979,10 @@ for (const layout of ["standard", "diff", "deep"] as const)
};
if (historical)
revised.provenance.previousFindings = [structuredClone(first)];
- await normal.write({
- ...normal.draft(),
- findings: ordered([revised, second]),
- });
+ await normal.writeFindings(ordered([revised, second]));
delete revised.identity;
- await recovered.write({
- ...recovered.draft(),
- findings: ordered([revised, second]),
- });
- const rows = JSON.parse(
- await readFile(path.join(recovered.root, "findings.json"), "utf8"),
- ).findings;
+ await recovered.writeFindings(ordered([revised, second]));
+ const rows = (await readJson(recovered.root, "findings.json")).findings;
assert.equal(rows.length, 2);
assert.deepEqual(
rows.find((row: FixtureFinding) => row.title === revised.title)
@@ -3575,22 +2994,13 @@ for (const layout of ["standard", "diff", "deep"] as const)
.identity,
second.identity,
);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- false,
- false,
- "published",
- );
+ const result = await recover({ details: true, source: "published" });
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
});
test(`${layout}: truly ambiguous revised siblings retain independent reports (reverse=${reversed})`, async (t) => {
- const normal = await fixture(t, layout),
- recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
const first = finding("First review", {
identity: { anchor: "saved-a" },
provenance: { source: "local_plugin", candidateId: "shared-candidate" },
@@ -3614,18 +3024,10 @@ for (const layout of ["standard", "diff", "deep"] as const)
];
for (const row of revised) delete row.identity;
for (const f of [normal, recovered]) {
- await f.write({
- ...f.draft(),
- findings: reversed ? [second, first] : [first, second],
- });
- await f.write({
- ...f.draft(),
- findings: reversed ? revised.toReversed() : revised,
- });
+ await f.writeFindings(reversed ? [second, first] : [first, second]);
+ await f.writeFindings(reversed ? revised.toReversed() : revised);
}
- const rows = JSON.parse(
- await readFile(path.join(normal.root, "findings.json"), "utf8"),
- ).findings;
+ const rows = (await readJson(normal.root, "findings.json")).findings;
assert.equal(rows.length, 4);
assert.deepEqual(
rows.find((row: FixtureFinding) => row.title === first.title).identity,
@@ -3635,13 +3037,7 @@ for (const layout of ["standard", "diff", "deep"] as const)
rows.find((row: FixtureFinding) => row.title === second.title).identity,
second.identity,
);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- );
+ const result = await recover({ details: true, replay: true });
assert.equal(result.normal.length, 4);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -3659,19 +3055,14 @@ for (const reversed of [false, true]) {
title: "Second review",
summary: "Second evidence.",
};
- await f.write({
- ...f.draft(),
- findings: reversed ? [second, first] : [first, second],
- });
+ await f.writeFindings(reversed ? [second, first] : [first, second]);
const revised = {
...structuredClone(first),
identity: { anchor: "saved-a" },
summary: "Revised first evidence.",
};
- await f.write({ ...f.draft(), findings: [revised] });
- const { findings } = JSON.parse(
- await readFile(path.join(f.root, "result.json"), "utf8"),
- );
+ await f.writeFindings([revised]);
+ const { findings } = await readJson(f.root, "result.json");
assert.equal(findings.length, 2);
assert.deepEqual(
findings.find((row: FixtureFinding) => row.title === first.title),
@@ -3689,8 +3080,7 @@ for (const reversed of [false, true]) {
for (const missing of [false, true]) {
test(`standard: restored parent absorbs worker with missing identity=${missing}`, async (t) => {
- const normal = await fixture(t, "standard"),
- recovered = await fixture(t, "standard");
+ const { normal, recovered, recover } = await recoveryPair(t, "standard");
const source = finding("Synthetic worker review", {
provenance: { source: "local_plugin", candidateId: "worker-candidate" },
});
@@ -3704,25 +3094,23 @@ for (const missing of [false, true]) {
},
});
for (const f of [normal, recovered])
- await f.write({ ...f.draft({}, true), findings: [parent] });
+ await f.writeFindings([parent], { complete: true });
if (missing) {
const file = path.join(recovered.root, "findings.json");
- const saved = JSON.parse(await readFile(file, "utf8"));
+ const saved = await readJson(file);
delete saved.findings[0].identity;
await writeFile(file, JSON.stringify(saved));
}
const workerRoot = path.join(recovered.root, "reviewer");
await mkdir(workerRoot);
const worker = draftFixture(workerRoot, "worker");
- await worker.write({ ...worker.draft({}, true), findings: [source] });
+ await worker.writeFindings([source], { complete: true });
for (const name of ["scan-manifest.json", "findings.json", "coverage.json"])
await utimes(path.join(recovered.root, name), 2, 2);
for (const name of await readdir(path.join(recovered.root, "checkpoints")))
await utimes(path.join(recovered.root, "checkpoints", name), 1.5, 1.5);
await utimes(path.join(workerRoot, "result.json"), 1, 1);
- const result = await recoverAndFinalize(normal, recovered, [
- savedWorker(workerRoot),
- ]);
+ const result = await recover({ workers: [savedWorker(workerRoot)] });
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -3740,18 +3128,12 @@ for (const reversed of [false, true]) {
provenance: { source: "local_plugin", candidateId: "candidate-1" },
}),
);
- await f.write({
- ...f.draft(),
- findings: reversed ? rows.toReversed() : rows,
- });
+ await f.writeFindings(reversed ? rows.toReversed() : rows);
for (let replay = 0; replay < 2; replay++) {
- await f.write({
- ...f.draft({}, true),
- findings: retained === 0 ? [] : [rows[retained - 1]!],
+ await f.writeFindings(retained === 0 ? [] : [rows[retained - 1]!], {
+ complete: true,
});
- const saved = JSON.parse(
- await readFile(path.join(f.root, "result.json"), "utf8"),
- );
+ const saved = await readJson(f.root, "result.json");
assert.equal(saved.findings.length, 2);
assert.deepEqual(
saved.findings
@@ -3773,23 +3155,15 @@ for (const reversed of [false, true]) {
...structuredClone(raw),
identity: { anchor: "shared-review", instance },
}));
- await f.write({
- ...f.draft(),
- findings: reversed ? rows.toReversed() : rows,
- });
+ await f.writeFindings(reversed ? rows.toReversed() : rows);
for (let replay = 0; replay < 2; replay++) {
const update = enriched
? { ...raw, extensions: { reportId: "report-1" } }
: raw;
- await f.write({ ...f.draft({}, true), findings: [update] });
- const saved = JSON.parse(
- await readFile(
- path.join(
- f.root,
- layout === "worker" ? "result.json" : "findings.json",
- ),
- "utf8",
- ),
+ await f.writeFindings([update], { complete: true });
+ const saved = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "findings.json",
);
assert.equal(saved.findings.length, 2);
assert.deepEqual(
diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_publication_recovery.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_publication_recovery.ts
index 6cad19806..3ea7bdfea 100644
--- a/plugins/codex-security/mcp-app/tests/test_artifact_scan_publication_recovery.ts
+++ b/plugins/codex-security/mcp-app/tests/test_artifact_scan_publication_recovery.ts
@@ -1,27 +1,20 @@
+import { readJson } from "./support/json.ts";
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
-import {
- copyFile,
- mkdir,
- writeFile,
- readFile,
- readdir,
- utimes,
-} from "node:fs/promises";
+import { copyFile, mkdir, writeFile, readdir, utimes } from "node:fs/promises";
import path from "node:path";
import test from "node:test";
import { importSource } from "./import-module.ts";
import {
- draftApi,
draftFixture,
- fixture,
interruptDraftWrite,
interruptDraftAfterRaw,
} from "./scan-draft-recovery-fixture.ts";
import {
type RecoveredFinding,
finding,
- recoverAndFinalize,
+ recoveryPair,
+ savedWorker,
dateDraftFiles,
} from "./scan-identity-recovery-fixture.ts";
@@ -29,8 +22,7 @@ for (const authored of [false, true]) {
for (const owner of [undefined, "reviewer"]) {
for (const changedCandidate of [false, true]) {
test(`parent and moved worker keep publication identities on frozen retry (authored=${authored}, owner=${owner ?? "omitted"}, changedCandidate=${changedCandidate})`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const first = finding("Review", {
...(authored ? { identity: { anchor: "review" } } : {}),
provenance: {
@@ -46,48 +38,33 @@ for (const authored of [false, true]) {
provenance: { source: "local_plugin", candidateId: "candidate-b" },
};
for (const target of [normal, recovered]) {
- await target.write({ ...target.draft(), findings: [first] });
+ await target.writeFindings([first]);
await dateDraftFiles(target.root, 100);
}
const workerRoot = path.join(recovered.root, "reviewer");
await mkdir(workerRoot);
const worker = draftFixture(workerRoot, "worker");
- await draftApi.saveScanDraftCheckpoint(
- worker.context,
- { ...worker.draft(), findings: [first] },
- false,
- );
+ await worker.checkpoint(worker.findingsDraft([first]));
await dateDraftFiles(workerRoot, 50);
await writeFile(
path.join(workerRoot, "result.json"),
- JSON.stringify({ ...worker.draft(), findings: [revised] }),
+ JSON.stringify(worker.findingsDraft([revised])),
);
- await normal.write({
- ...normal.draft({}, true),
- findings: [
+ await normal.writeFindings(
+ [
first,
{
...revised,
provenance: { ...revised.provenance, workerId: "reviewer" },
},
],
- });
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [
- {
- id: "reviewer",
- kind: "discovery",
- status: "succeeded",
- artifact_dir: workerRoot,
- result_manifest_path: path.join(workerRoot, "result.json"),
- attempt: 1,
- },
- ],
- true,
- true,
+ { complete: true },
);
+ const result = await recover({
+ workers: [savedWorker(workerRoot, "reviewer", "succeeded")],
+ details: true,
+ replay: true,
+ });
const byEvidence = (rows: RecoveredFinding[]) =>
new Map(rows.map((row) => [row.summary, row]));
assert.equal(result.normal.length, 2);
@@ -113,8 +90,7 @@ for (const layout of ["standard", "deep"] as const) {
"authored owned",
]) {
test(`${layout}: terminal replacement ${variant} matches frozen recovery (scoped=${scoped})`, async (t) => {
- const normal = await fixture(t, layout);
- const recovered = await fixture(t, layout);
+ const { normal, recovered, recover } = await recoveryPair(t, layout);
if (scoped)
for (const target of [normal, recovered]) {
target.context.scope = "src";
@@ -146,26 +122,18 @@ for (const layout of ["standard", "deep"] as const) {
},
};
for (const target of [normal, recovered]) {
- await target.write({
- ...target.draft({}, true),
- findings: [initial],
- });
+ await target.writeFindings([initial], { complete: true });
await dateDraftFiles(target.root, 100);
}
- await normal.write({ ...normal.draft({}, true), findings: [revised] });
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft({}, true), findings: [revised] },
- false,
- );
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- true,
+ await normal.writeFindings([revised], { complete: true });
+ await recovered.checkpoint(
+ recovered.findingsDraft([revised], { complete: true }),
);
+ const result = await recover({
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
const byEvidence = (rows: RecoveredFinding[]) =>
new Map(
rows.map(({ evidenceProvenance, ...row }) => [row.summary, row]),
@@ -193,8 +161,7 @@ for (const scoped of [false, true]) {
for (const time of [99, 100, 101]) {
for (const cut of ["raw input", "committed head"] as const) {
test(`terminal Deep identity follows producer context at time ${time} (scoped=${scoped}, cut=${cut})`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
if (scoped)
for (const f of [normal, recovered]) {
f.context.scope = "src";
@@ -209,19 +176,14 @@ for (const scoped of [false, true]) {
summary: "Revised synthetic evidence.",
};
for (const f of [normal, recovered]) {
- await f.write({ ...f.draft(), findings: [first] });
+ await f.writeFindings([first]);
await dateDraftFiles(f.root, 100);
}
const checkpoints = path.join(recovered.root, "checkpoints");
const original = new Set(await readdir(checkpoints));
- await normal.write({ ...normal.draft({}, true), findings: [revised] });
- const input = { ...recovered.draft({}, true), findings: [revised] };
- if (cut === "raw input")
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- input,
- false,
- );
+ await normal.writeFindings([revised], { complete: true });
+ const input = recovered.findingsDraft([revised], { complete: true });
+ if (cut === "raw input") await recovered.checkpoint(input);
else
await interruptDraftWrite(
path.join(recovered.root, "findings.json"),
@@ -236,14 +198,11 @@ for (const scoped of [false, true]) {
time,
time,
);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- true,
- );
+ const result = await recover({
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
assert.equal(result.normal.length, 1);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(result.warnings, []);
@@ -254,35 +213,30 @@ for (const scoped of [false, true]) {
for (const cut of ["raw input", "committed head"] as const) {
test(`later partial Deep evidence survives the terminal clock tie (${cut})`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const terminal = finding("Terminal review");
const later = finding("Later independent review", {
locations: [{ path: "src/later.py", startLine: 2 }],
});
for (const f of [normal, recovered])
- await f.write({ ...f.draft({}, true), findings: [terminal] });
+ await f.writeFindings([terminal], { complete: true });
const pending = {
deferred: [{ id: "later-work", reason: "More review remains." }],
};
await normal.write({ ...normal.draft(pending), findings: [later] });
if (cut === "raw input")
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- { ...recovered.draft(pending), findings: [later] },
- false,
- );
+ await recovered.checkpoint({
+ ...recovered.draft(pending),
+ findings: [later],
+ });
else
await recovered.write({ ...recovered.draft(pending), findings: [later] });
for (const f of [normal, recovered]) await dateDraftFiles(f.root, 100);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- true,
- );
+ const result = await recover({
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
const byId = (rows: RecoveredFinding[]) =>
new Map(rows.map((row) => [row.findingId, row]));
assert.equal(result.normal.length, 2);
@@ -292,20 +246,18 @@ for (const cut of ["raw input", "committed head"] as const) {
}
test("a later worker attempt survives the terminal parent's clock tie", async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const workerRoot = path.join(recovered.root, "reviewer");
const archiveRoot = path.join(workerRoot, "attempts", "attempt-1");
await mkdir(archiveRoot, { recursive: true });
const archived = draftFixture(archiveRoot, "worker");
- await archived.write({
- ...archived.draft({}, true),
- findings: [finding("Archived worker review")],
+ await archived.writeFindings([finding("Archived worker review")], {
+ complete: true,
});
await dateDraftFiles(archiveRoot, 99);
const terminal = finding("Terminal review");
for (const f of [normal, recovered]) {
- await f.write({ ...f.draft({}, true), findings: [terminal] });
+ await f.writeFindings([terminal], { complete: true });
for (const name of [
"findings.json",
"coverage.json",
@@ -319,33 +271,24 @@ test("a later worker attempt survives the terminal parent's clock tie", async (t
const later = finding("Later worker review", {
locations: [{ path: "src/later.py", startLine: 2 }],
});
- await worker.write({ ...worker.draft(), findings: [later] });
+ await worker.writeFindings([later]);
await dateDraftFiles(path.join(workerRoot, "checkpoints"), 100);
for (const name of ["result.json", "checkpoint-head.json"])
await utimes(path.join(workerRoot, name), 100, 100);
- await normal.write({
- ...normal.draft({}, true),
- findings: [
+ await normal.writeFindings(
+ [
terminal,
{ ...later, provenance: { ...later.provenance, workerId: "reviewer" } },
],
- });
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [
- {
- id: "reviewer",
- kind: "discovery",
- status: "succeeded",
- artifact_dir: workerRoot,
- result_manifest_path: path.join(workerRoot, "result.json"),
- attempt: 2,
- },
- ],
- true,
- true,
+ { complete: true },
);
+ const result = await recover({
+ workers: [
+ { ...savedWorker(workerRoot, "reviewer", "succeeded"), attempt: 2 },
+ ],
+ details: true,
+ replay: true,
+ });
assert.equal(result.normal.length, 2);
const byId = (rows: RecoveredFinding[]) =>
new Map(rows.map((row) => [row.findingId, row]));
@@ -355,8 +298,7 @@ test("a later worker attempt survives the terminal parent's clock tie", async (t
for (const reversed of [false, true]) {
test(`tied legacy surface observations retain distinct rows and frozen IDs (reversed=${reversed})`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const surfaces = ["First legacy surface", "Second legacy surface"].map(
(label) => ({
id: "legacy-shared",
@@ -373,28 +315,18 @@ for (const reversed of [false, true]) {
surfaceIds: ["legacy-shared"],
},
];
- await normal.write(
- normal.draft({
- surfaces: surfaces.map((row, index) => ({
- ...row,
- id: index === 0 ? row.id : "legacy-second",
- })),
- deferred,
- }),
- );
- await recovered.write(recovered.draft());
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- recovered.draft({ surfaces, deferred }),
- false,
- );
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- recovered.draft({}, true),
- false,
- );
+ await normal.writeReviewState({
+ surfaces: surfaces.map((row, index) => ({
+ ...row,
+ id: index === 0 ? row.id : "legacy-second",
+ })),
+ deferred,
+ });
+ await recovered.writeReviewState();
+ await recovered.checkpoint(recovered.draft({ surfaces, deferred }));
+ await recovered.checkpoint(recovered.draft({}, true));
await dateDraftFiles(recovered.root, 100);
- const result = await recoverAndFinalize(normal, recovered, [], true, true);
+ const result = await recover({ details: true, replay: true });
const rows = result.recoveredCoverage.surfaces as Array<{
id: string;
label: string;
@@ -405,13 +337,9 @@ for (const reversed of [false, true]) {
);
assert.equal(new Set(rows.map((row) => row.id)).size, 2);
assert.deepEqual(result.warnings, []);
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- recovered.draft(),
- false,
- );
+ await recovered.checkpoint(recovered.draft());
await dateDraftFiles(recovered.root, 100);
- const replay = await recoverAndFinalize(normal, recovered, [], true, true);
+ const replay = await recover({ details: true, replay: true });
assert.deepEqual(replay.recoveredCoverage.surfaces, rows);
});
}
@@ -420,8 +348,7 @@ for (const authored of [false, true]) {
for (const time of [99, 100, 101]) {
for (const cut of ["raw input", "committed head"] as const) {
test(`terminal Deep replacement retains unchanged siblings (authored=${authored}, time=${time}, cut=${cut})`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const [unchanged, removed, added] = [
"Unchanged",
"Removed",
@@ -433,28 +360,16 @@ for (const authored of [false, true]) {
),
);
for (const f of [normal, recovered]) {
- await f.write({
- ...f.draft({}, true),
- findings: [unchanged, removed],
- });
+ await f.writeFindings([unchanged, removed], { complete: true });
await dateDraftFiles(f.root, 100);
}
const checkpoints = path.join(recovered.root, "checkpoints");
const original = new Set(await readdir(checkpoints));
- await normal.write({
- ...normal.draft({}, true),
- findings: [unchanged, added],
+ await normal.writeFindings([unchanged, added], { complete: true });
+ const input = recovered.findingsDraft([unchanged, added], {
+ complete: true,
});
- const input = {
- ...recovered.draft({}, true),
- findings: [unchanged, added],
- };
- if (cut === "raw input")
- await draftApi.saveScanDraftCheckpoint(
- recovered.context,
- input,
- false,
- );
+ if (cut === "raw input") await recovered.checkpoint(input);
else
await interruptDraftWrite(
path.join(recovered.root, "findings.json"),
@@ -469,14 +384,11 @@ for (const authored of [false, true]) {
time,
time,
);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- true,
- );
+ const result = await recover({
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
assert.equal(result.normal.length, 2);
assert.deepEqual(result.recovered, result.normal);
for (const row of result.recovered)
@@ -493,16 +405,12 @@ for (const authored of [false, true]) {
for (const parentState of ["absent", "partial", "terminal"] as const) {
test(`a reducer preserves its claimed batch and unconsumed workers (${parentState} parent)`, async (t) => {
- const normal = await fixture(t, "deep");
- const recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const parentFinding = finding("Parent review", {
locations: [{ path: "src/parent.py", startLine: 1 }],
});
if (parentState === "partial") {
- await recovered.write({
- ...recovered.draft(),
- findings: [parentFinding],
- });
+ await recovered.writeFindings([parentFinding]);
await dateDraftFiles(recovered.root, 100);
}
const rows = ["Assigned", "Unconsumed"].map((title) =>
@@ -521,7 +429,7 @@ for (const parentState of ["absent", "partial", "terminal"] as const) {
);
await mkdir(root, { recursive: true });
const worker = draftFixture(root, "worker");
- await worker.write({ ...worker.draft({}, true), findings: [row] });
+ await worker.writeFindings([row], { complete: true });
await dateDraftFiles(root, 101 + index);
workers.push({
id,
@@ -567,9 +475,7 @@ for (const parentState of ["absent", "partial", "terminal"] as const) {
result_manifest_path: path.join(root, "result.json"),
attempt: 1,
});
- const reduced = JSON.parse(
- await readFile(path.join(root, "result.json"), "utf8"),
- );
+ const reduced = await readJson(root, "result.json");
const findings =
parentState === "terminal"
? [parentFinding]
@@ -581,9 +487,9 @@ for (const parentState of ["absent", "partial", "terminal"] as const) {
provenance: { ...rows[1].provenance, workerId: "worker-2" },
},
];
- await normal.write({ ...normal.draft({}, true), findings });
+ await normal.writeFindings(findings, { complete: true });
if (parentState === "terminal") {
- await recovered.write({ ...recovered.draft({}, true), findings });
+ await recovered.writeFindings(findings, { complete: true });
for (const name of [
"findings.json",
"coverage.json",
@@ -593,14 +499,12 @@ for (const parentState of ["absent", "partial", "terminal"] as const) {
await utimes(path.join(recovered.root, name), 104, 104);
await dateDraftFiles(path.join(recovered.root, "checkpoints"), 104);
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
+ const result = await recover({
workers,
- true,
- true,
- true,
- );
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
const byEvidence = (rows: RecoveredFinding[]) =>
new Map(rows.map((row) => [row.title, row]));
assert.equal(
@@ -614,19 +518,16 @@ for (const parentState of ["absent", "partial", "terminal"] as const) {
for (const abandonedTime of [99, 200, 300]) {
test(`an accepted Deep publication supersedes an abandoned terminal at time ${abandonedTime}`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
await interruptDraftAfterRaw(() =>
- recovered.write({
- ...recovered.draft({}, true),
- findings: [finding("Abandoned terminal draft")],
+ recovered.writeFindings([finding("Abandoned terminal draft")], {
+ complete: true,
}),
);
const abandoned = await readdir(path.join(recovered.root, "checkpoints"));
for (const f of [normal, recovered])
- await f.write({
- ...f.draft({}, true),
- findings: [finding("Accepted replacement")],
+ await f.writeFindings([finding("Accepted replacement")], {
+ complete: true,
});
await dateDraftFiles(recovered.root, 200);
for (const name of abandoned)
@@ -635,14 +536,11 @@ for (const abandonedTime of [99, 200, 300]) {
abandonedTime,
abandonedTime,
);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- true,
- );
+ const result = await recover({
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
assert.deepEqual(result.recovered, result.normal);
assert.equal(result.recovered[0]!.title, "Accepted replacement");
assert.deepEqual(result.warnings, []);
@@ -650,24 +548,22 @@ for (const abandonedTime of [99, 200, 300]) {
}
test("a newer file-authored canonical Deep result supersedes the accepted head", async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
for (const f of [normal, recovered]) {
- await f.write({
- ...f.draft({}, true),
- findings: [finding("Earlier accepted result")],
+ await f.writeFindings([finding("Earlier accepted result")], {
+ complete: true,
});
await dateDraftFiles(f.root, 100);
}
- await normal.write({
- ...normal.draft({}, true),
- findings: [
+ await normal.writeFindings(
+ [
finding("File authored update", {
identity: { anchor: "file-authored" },
locations: [{ path: "src/updated.py", startLine: 8 }],
}),
],
- });
+ { complete: true },
+ );
for (const name of ["scan-manifest.json", "findings.json", "coverage.json"]) {
await copyFile(
path.join(normal.root, name),
@@ -675,14 +571,11 @@ test("a newer file-authored canonical Deep result supersedes the accepted head",
);
await utimes(path.join(recovered.root, name), 300, 300);
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- true,
- );
+ const result = await recover({
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
assert.deepEqual(result.recovered, result.normal);
assert.equal(result.recovered[0]!.title, "File authored update");
assert.deepEqual(result.warnings, []);
@@ -690,33 +583,29 @@ test("a newer file-authored canonical Deep result supersedes the accepted head",
for (const reversed of [false, true]) {
test(`a raw terminal rewrite preserves authored identity collisions (reversed=${reversed})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const findings = [
"First independent report",
"Second independent report",
].map((title) => finding(title, { identity: { anchor: "same" } }));
if (reversed) findings.reverse();
for (const f of [normal, recovered]) {
- await f.write({ ...f.draft({}, true), findings });
+ await f.writeFindings(findings, { complete: true });
await dateDraftFiles(f.root, 100);
}
const revised = findings.map((row) => ({
...row,
summary: `Updated ${row.title}`,
}));
- await normal.write({ ...normal.draft({}, true), findings: revised });
+ await normal.writeFindings(revised, { complete: true });
await interruptDraftAfterRaw(() =>
- recovered.write({ ...recovered.draft({}, true), findings: revised }),
- );
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- true,
+ recovered.writeFindings(revised, { complete: true }),
);
+ const result = await recover({
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
assert.equal(result.recovered.length, 2);
assert.deepEqual(result.recovered, result.normal);
assert.deepEqual(
@@ -735,8 +624,7 @@ for (const [metadata, preservedIdentity] of Object.entries({
const preserved = preservedIdentity !== undefined;
for (const workerUpdate of ["none", "unchanged", "revised"]) {
test(`interrupted terminal collisions retain authored identity with ${workerUpdate} worker (metadata=${metadata})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const identity = { anchor: "same", description: "Authored identity" };
const findings = ["First report", "Second report"].map((title, index) =>
finding(title, {
@@ -750,9 +638,9 @@ for (const [metadata, preservedIdentity] of Object.entries({
},
}),
);
- await normal.write({ ...normal.draft({}, true), findings });
+ await normal.writeFindings(findings, { complete: true });
await interruptDraftAfterRaw(() =>
- recovered.write({ ...recovered.draft({}, true), findings }),
+ recovered.writeFindings(findings, { complete: true }),
);
await dateDraftFiles(recovered.root, 100);
const workers = [];
@@ -769,28 +657,12 @@ for (const [metadata, preservedIdentity] of Object.entries({
}
: {}),
};
- await worker.write({ ...worker.draft({}, true), findings: [revised] });
+ await worker.writeFindings([revised], { complete: true });
await dateDraftFiles(workerRoot, 200);
- workers.push({
- id: "reviewer",
- kind: "discovery",
- status: "succeeded",
- artifact_dir: workerRoot,
- result_manifest_path: path.join(workerRoot, "result.json"),
- attempt: 1,
- });
- await normal.write({
- ...normal.draft({}, true),
- findings: [findings[0]!, revised],
- });
+ workers.push(savedWorker(workerRoot, "reviewer", "succeeded"));
+ await normal.writeFindings([findings[0]!, revised], { complete: true });
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
- workers,
- true,
- true,
- );
+ const result = await recover({ workers, details: true, replay: true });
assert.equal(result.normal.length, 2);
assert.equal(result.recovered.length, 2);
assert.deepEqual(result.recovered, result.normal);
@@ -811,29 +683,25 @@ for (const [metadata, preservedIdentity] of Object.entries({
for (const cut of ["published", "pending"] as const) {
test(`reselecting an earlier Deep result retains its publication ancestry (${cut})`, async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const first = finding("First publication"),
second = finding("Second publication");
for (const row of [first, second, first])
for (const f of [normal, recovered])
- await f.write({ ...f.draft({}, true), findings: [row] });
+ await f.writeFindings([row], { complete: true });
await dateDraftFiles(recovered.root, 100);
if (cut === "pending") {
const revised = { ...second, summary: "Revised second publication" };
- await normal.write({ ...normal.draft({}, true), findings: [revised] });
+ await normal.writeFindings([revised], { complete: true });
await interruptDraftAfterRaw(() =>
- recovered.write({ ...recovered.draft({}, true), findings: [revised] }),
+ recovered.writeFindings([revised], { complete: true }),
);
}
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- true,
- );
+ const result = await recover({
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
assert.deepEqual(result.recovered, result.normal);
assert.equal(result.recovered.length, 1);
assert.deepEqual(result.warnings, []);
@@ -841,23 +709,18 @@ for (const cut of ["published", "pending"] as const) {
}
test("a backdated legacy terminal retains both possible publication histories", async (t) => {
- const normal = await fixture(t, "deep"),
- recovered = await fixture(t, "deep");
+ const { normal, recovered, recover } = await recoveryPair(t, "deep");
const accepted = finding("Accepted review"),
unordered = finding("Unordered legacy review");
for (const f of [normal, recovered]) {
- await f.write({ ...f.draft({}, true), findings: [accepted] });
+ await f.writeFindings([accepted], { complete: true });
await dateDraftFiles(f.root, 200);
}
- await normal.write({
- ...normal.draft({}, true),
- findings: [accepted, unordered],
- });
+ await normal.writeFindings([accepted, unordered], { complete: true });
// Older writers did not record whether this input preceded or followed the head.
- const contents = JSON.stringify({
- ...recovered.draft({}, true),
- findings: [unordered],
- });
+ const contents = JSON.stringify(
+ recovered.findingsDraft([unordered], { complete: true }),
+ );
const raw = path.join(
recovered.root,
"checkpoints",
@@ -865,14 +728,11 @@ test("a backdated legacy terminal retains both possible publication histories",
);
await writeFile(raw, contents);
await utimes(raw, 100, 100);
- const result = await recoverAndFinalize(
- normal,
- recovered,
- [],
- true,
- true,
- true,
- );
+ const result = await recover({
+ details: true,
+ replay: true,
+ provenanceDetails: true,
+ });
const byTitle = (rows: RecoveredFinding[]) =>
new Map(rows.map((row) => [row.title, row]));
assert.equal(result.recovered.length, 2);
diff --git a/sdk/typescript/tests-ts/publication-integration.test.ts b/sdk/typescript/tests-ts/publication-integration.test.ts
index 1e929ea86..ba7ab82d5 100644
--- a/sdk/typescript/tests-ts/publication-integration.test.ts
+++ b/sdk/typescript/tests-ts/publication-integration.test.ts
@@ -4,7 +4,8 @@ import {
captureCli,
runCapturedCli,
} from "./support/cli-run.js";
-import { setFindingIdentity, sha256 } from "./support/finding-identity.js";
+import { sha256 } from "./support/finding-identity.js";
+import { writePublicationFindings } from "./support/sealed-scan.js";
import { parseJsonLines, jsonLines } from "./support/json.js";
import { nodeCommand } from "./support/shell.js";
import { Database } from "bun:sqlite";
@@ -22,11 +23,6 @@ import { afterEach, describe, expect, test } from "bun:test";
import { main } from "../src/cli.js";
import { prepareScanPublication } from "../src/publication.js";
import { recordPublishedIssues } from "../src/publication-store.js";
-import type {
- CoverageDocument,
- FindingsDocument,
- ScanManifest,
-} from "../src/models.js";
import {
checkScanPublicationInternal,
forceTerminatePublicationProcesses,
@@ -95,37 +91,11 @@ async function fixture(count: number) {
await mkdir(repository, { mode: 0o700 });
if (process.platform !== "win32") await chmod(scanDirectory, 0o700);
- const manifestPath = join(scanDirectory, "scan-manifest.json");
- const findingsPath = join(scanDirectory, "findings.json");
- const coveragePath = join(scanDirectory, "coverage.json");
- const manifest = JSON.parse(
- await readFile(manifestPath, "utf8"),
- ) as ScanManifest;
- const findings = JSON.parse(
- await readFile(findingsPath, "utf8"),
- ) as FindingsDocument;
- const coverage = JSON.parse(
- await readFile(coveragePath, "utf8"),
- ) as CoverageDocument;
- manifest.scan.id = SCAN_ID;
- findings.scanId = SCAN_ID;
- coverage.scanId = SCAN_ID;
- const example = findings.findings[0]!;
- findings.findings = Array.from({ length: count }, (_, index) => {
- const finding = structuredClone(example);
- finding.identity.anchor = `${example.identity.anchor}-${index + 1}`;
- finding.title = `Synthetic finding ${index + 1}`;
- setFindingIdentity(manifest.scan, finding);
- return finding;
- });
- await writeFile(findingsPath, `${JSON.stringify(findings, null, 2)}\n`);
- await writeFile(coveragePath, `${JSON.stringify(coverage, null, 2)}\n`);
- for (const artifact of manifest.scan.artifacts) {
- artifact.sha256 = sha256(
- await readFile(join(scanDirectory, artifact.path)),
- );
- }
- await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+ const findings = await writePublicationFindings(
+ scanDirectory,
+ SCAN_ID,
+ count,
+ );
const python = (Bun.which("python3") ?? Bun.which("python"))!;
expect(python).not.toBeNull();
@@ -149,7 +119,7 @@ async function fixture(count: number) {
workspaceId: WORKSPACE_ID,
scanDirectory,
repository,
- findings: findings.findings,
+ findings,
}),
);
const seed = [
@@ -178,7 +148,7 @@ async function fixture(count: number) {
scanDirectory,
stateDirectory,
environment,
- findings: findings.findings,
+ findings,
};
}
diff --git a/sdk/typescript/tests-ts/publication-store.test.ts b/sdk/typescript/tests-ts/publication-store.test.ts
index 1c92b2e06..cc42476a2 100644
--- a/sdk/typescript/tests-ts/publication-store.test.ts
+++ b/sdk/typescript/tests-ts/publication-store.test.ts
@@ -23,12 +23,8 @@ import {
prepareScanPublication,
type PreparedScanPublication,
} from "../src/publication.js";
-import type {
- CoverageDocument,
- FindingsDocument,
- ScanManifest,
-} from "../src/models.js";
-import { setFindingIdentity, sha256 } from "./support/finding-identity.js";
+import type { FindingsDocument, ScanManifest } from "../src/models.js";
+import { writePublicationFindings } from "./support/sealed-scan.js";
import type { PublishedScanIssue } from "../src/publish.js";
import { runWorkbench } from "../src/runtime.js";
import * as runtime from "../src/runtime.js";
@@ -92,37 +88,7 @@ async function sealedPublication(
scanId = SCAN_ID,
): Promise<PreparedScanPublication> {
await copyCompletedScanFixture(scanDirectory);
- const manifestPath = join(scanDirectory, "scan-manifest.json");
- const findingsPath = join(scanDirectory, "findings.json");
- const coveragePath = join(scanDirectory, "coverage.json");
- const manifest = JSON.parse(
- await readFile(manifestPath, "utf8"),
- ) as ScanManifest;
- const findings = JSON.parse(
- await readFile(findingsPath, "utf8"),
- ) as FindingsDocument;
- const coverage = JSON.parse(
- await readFile(coveragePath, "utf8"),
- ) as CoverageDocument;
- manifest.scan.id = scanId;
- findings.scanId = scanId;
- coverage.scanId = scanId;
- const example = findings.findings[0]!;
- findings.findings = Array.from({ length: count }, (_, index) => {
- const finding = structuredClone(example);
- finding.identity.anchor = `${example.identity.anchor}-${index + 1}`;
- finding.title = `Synthetic finding ${index + 1}`;
- setFindingIdentity(manifest.scan, finding);
- return finding;
- });
- await writeFile(findingsPath, `${JSON.stringify(findings, null, 2)}\n`);
- await writeFile(coveragePath, `${JSON.stringify(coverage, null, 2)}\n`);
- for (const artifact of manifest.scan.artifacts) {
- artifact.sha256 = sha256(
- await readFile(join(scanDirectory, artifact.path)),
- );
- }
- await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+ await writePublicationFindings(scanDirectory, scanId, count);
return prepareScanPublication(scanDirectory, {
destination: "linear",
teamId: "team-example",
diff --git a/sdk/typescript/tests-ts/publication.test.ts b/sdk/typescript/tests-ts/publication.test.ts
index 9b7526f1b..2e88bdf42 100644
--- a/sdk/typescript/tests-ts/publication.test.ts
+++ b/sdk/typescript/tests-ts/publication.test.ts
@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { reseal } from "./support/sealed-scan.js";
import { chmod, mkdir, readFile, realpath, symlink } from "node:fs/promises";
import { dirname, join } from "node:path";
import { afterEach, describe, expect, test } from "bun:test";
@@ -39,14 +39,20 @@ async function copyExample(): Promise<string> {
return scanDirectory;
}
-async function reseal(scanDirectory: string): Promise<void> {
+async function issueDescription(scanDirectory: string) {
+ const { issues } = await prepareScanPublication(
+ scanDirectory,
+ publicationOptions(scanDirectory),
+ );
+ return issues[0]!.description;
+}
+
+async function useRevisionTarget(scanDirectory: string) {
const manifestPath = join(scanDirectory, "scan-manifest.json");
const manifest = await readJson<ScanManifest>(manifestPath);
- for (const artifact of manifest.scan.artifacts) {
- artifact.sha256 = createHash("sha256")
- .update(await readFile(join(scanDirectory, artifact.path)))
- .digest("hex");
- }
+ manifest.scan.target.kind = "git_revision";
+ manifest.scan.target.revision = "0123456789abcdef0123456789abcdef01234567";
+ delete manifest.scan.target.snapshotDigest;
await writeJson(manifestPath, manifest);
}
@@ -164,12 +170,7 @@ describe("scan publication preparation", () => {
await writeJson(findingsPath, findings);
await reseal(scanDirectory);
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
const metadata = description.indexOf("**Scan ID:**");
for (const text of [
@@ -227,12 +228,7 @@ describe("scan publication preparation", () => {
await writeJson(coveragePath, coverage);
await reseal(scanDirectory);
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
expect(description).toContain(`**Scan mode:** ${expectedMode}`);
expect(description).not.toContain("**Scan mode:** unknown");
@@ -309,12 +305,7 @@ describe("scan publication preparation", () => {
await writeJson(findingsPath, findings);
await reseal(scanDirectory);
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
expect(description).toContain("**Root control:** `src/archive.py:12`");
expect(description).toContain(
@@ -342,19 +333,9 @@ describe("scan publication preparation", () => {
test("only links source locations for a full immutable GitHub revision", async () => {
const scanDirectory = await copyExample();
- const manifestPath = join(scanDirectory, "scan-manifest.json");
- const manifest = await readJson<ScanManifest>(manifestPath);
- manifest.scan.target.kind = "git_revision";
- manifest.scan.target.revision = "0123456789abcdef0123456789abcdef01234567";
- delete manifest.scan.target.snapshotDigest;
- await writeJson(manifestPath, manifest);
+ await useRevisionTarget(scanDirectory);
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
expect(description).toContain(
"https://github.com/example/repo/blob/0123456789abcdef0123456789abcdef01234567/src/extract.py#L41-L44",
@@ -445,12 +426,7 @@ describe("scan publication preparation", () => {
await writeJson(findingsPath, findings);
await reseal(scanDirectory);
const saved = await readFile(findingsPath, "utf8");
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
for (const text of present) expect(description).toContain(text);
for (const text of absent) expect(description).not.toContain(text);
expect(await readFile(findingsPath, "utf8")).toBe(saved);
@@ -515,20 +491,10 @@ describe("scan publication preparation", () => {
},
];
await writeJson(findingsPath, findings);
- const manifestPath = join(scanDirectory, "scan-manifest.json");
- const manifest = await readJson<ScanManifest>(manifestPath);
- manifest.scan.target.kind = "git_revision";
- manifest.scan.target.revision = "0123456789abcdef0123456789abcdef01234567";
- delete manifest.scan.target.snapshotDigest;
- await writeJson(manifestPath, manifest);
+ await useRevisionTarget(scanDirectory);
await reseal(scanDirectory);
const saved = await readFile(findingsPath, "utf8");
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
for (const snippet of [
"canonical_source()",
"second_canonical_source()",
@@ -610,12 +576,7 @@ describe("scan publication preparation", () => {
await reseal(scanDirectory);
const saved = await readFile(findingsPath, "utf8");
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
const snippets = [
"canonical_source()",
@@ -697,21 +658,11 @@ describe("scan publication preparation", () => {
},
];
await writeJson(findingsPath, findings);
- const manifestPath = join(scanDirectory, "scan-manifest.json");
- const manifest = await readJson<ScanManifest>(manifestPath);
- manifest.scan.target.kind = "git_revision";
- manifest.scan.target.revision = "0123456789abcdef0123456789abcdef01234567";
- delete manifest.scan.target.snapshotDigest;
- await writeJson(manifestPath, manifest);
+ await useRevisionTarget(scanDirectory);
await reseal(scanDirectory);
const saved = await readFile(findingsPath, "utf8");
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
expect(description).toContain("src/canonical-nested.py#L20-L24)");
expect(description).toContain("[``app/api/`id`/route.ts:7``]");
@@ -751,12 +702,7 @@ describe("scan publication preparation", () => {
await reseal(scanDirectory);
const saved = await readFile(findingsPath, "utf8");
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
let previous = -1;
for (const section of [
@@ -808,21 +754,11 @@ describe("scan publication preparation", () => {
},
];
await writeJson(findingsPath, findings);
- const manifestPath = join(scanDirectory, "scan-manifest.json");
- const manifest = await readJson<ScanManifest>(manifestPath);
- manifest.scan.target.kind = "git_revision";
- manifest.scan.target.revision = "0123456789abcdef0123456789abcdef01234567";
- delete manifest.scan.target.snapshotDigest;
- await writeJson(manifestPath, manifest);
+ await useRevisionTarget(scanDirectory);
await reseal(scanDirectory);
const saved = await readFile(findingsPath, "utf8");
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
expect(description).toContain("`src/string.py:12 additional context`");
expect(description).toContain("`` `src/quoted.py:12` ``");
@@ -843,12 +779,7 @@ describe("scan publication preparation", () => {
delete manifest.scan.target.snapshotDigest;
await writeJson(manifestPath, manifest);
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
expect(description).toContain("**Remote:** ssh://github.com/example/repo");
expect(description).toContain("**Sink:** `src/extract.py:41-44`");
@@ -882,12 +813,7 @@ describe("scan publication preparation", () => {
test("preserves evidence snippets for valid paths without safe source links", async () => {
const scanDirectory = await copyExample();
- const manifestPath = join(scanDirectory, "scan-manifest.json");
- const manifest = await readJson<ScanManifest>(manifestPath);
- manifest.scan.target.kind = "git_revision";
- manifest.scan.target.revision = "0123456789abcdef0123456789abcdef01234567";
- delete manifest.scan.target.snapshotDigest;
- await writeJson(manifestPath, manifest);
+ await useRevisionTarget(scanDirectory);
const findingsPath = join(scanDirectory, "findings.json");
const findings = await readJson<FindingsDocument>(findingsPath);
@@ -917,12 +843,7 @@ describe("scan publication preparation", () => {
await writeJson(findingsPath, findings);
await reseal(scanDirectory);
- const { description } = (
- await prepareScanPublication(
- scanDirectory,
- publicationOptions(scanDirectory),
- )
- ).issues[0]!;
+ const description = await issueDescription(scanDirectory);
expect(description).toContain(
"https://github.com/example/repo/blob/0123456789abcdef0123456789abcdef01234567/src/extract.py#L41-L44",
diff --git a/sdk/typescript/tests-ts/support/multiscan.ts b/sdk/typescript/tests-ts/support/multiscan.ts
index ceac7b011..f315dd759 100644
--- a/sdk/typescript/tests-ts/support/multiscan.ts
+++ b/sdk/typescript/tests-ts/support/multiscan.ts
@@ -1,6 +1,7 @@
import { gitText } from "./shell.js";
import { readJsonLines } from "./json.js";
-import { createHash } from "node:crypto";
+import { reseal } from "./sealed-scan.js";
+export { reseal };
import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { zipSync } from "fflate";
@@ -91,19 +92,6 @@ export async function completedScan(
return { manifest: result.manifest, review: result.review } as ScanResult;
}
-export async function reseal(scanDir: string): Promise<void> {
- const manifestPath = join(scanDir, "scan-manifest.json");
- const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as {
- scan: { artifacts: Array<{ path: string; sha256: string }> };
- };
- for (const artifact of manifest.scan.artifacts) {
- artifact.sha256 = createHash("sha256")
- .update(await readFile(join(scanDir, artifact.path)))
- .digest("hex");
- }
- await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
-}
-
export async function customPlugin(
root: string,
format: "directory" | "zip",
diff --git a/sdk/typescript/tests-ts/support/sealed-scan.ts b/sdk/typescript/tests-ts/support/sealed-scan.ts
new file mode 100644
index 000000000..00f3f9a30
--- /dev/null
+++ b/sdk/typescript/tests-ts/support/sealed-scan.ts
@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+ CoverageDocument,
+ FindingsDocument,
+ ScanManifest,
+} from "../../src/models.js";
+import { readJson, writeJson } from "./json.js";
+import { setFindingIdentity, sha256 } from "./finding-identity.js";
+
+export async function reseal(scanDirectory: string, updated?: ScanManifest) {
+ const manifestPath = join(scanDirectory, "scan-manifest.json");
+ const manifest = updated ?? (await readJson<ScanManifest>(manifestPath));
+ for (const artifact of manifest.scan.artifacts) {
+ artifact.sha256 = sha256(
+ await readFile(join(scanDirectory, artifact.path)),
+ );
+ }
+ await writeJson(manifestPath, manifest);
+}
+
+export async function writePublicationFindings(
+ scanDirectory: string,
+ scanId: string,
+ count: number,
+) {
+ const manifest = await readJson<ScanManifest>(
+ join(scanDirectory, "scan-manifest.json"),
+ );
+ const findingsPath = join(scanDirectory, "findings.json");
+ const coveragePath = join(scanDirectory, "coverage.json");
+ const findings = await readJson<FindingsDocument>(findingsPath);
+ const coverage = await readJson<CoverageDocument>(coveragePath);
+ manifest.scan.id = scanId;
+ findings.scanId = scanId;
+ coverage.scanId = scanId;
+ const example = findings.findings[0]!;
+ findings.findings = Array.from({ length: count }, (_, index) => {
+ const finding = structuredClone(example);
+ finding.identity.anchor = `${example.identity.anchor}-${index + 1}`;
+ finding.title = `Synthetic finding ${index + 1}`;
+ setFindingIdentity(manifest.scan, finding);
+ return finding;
+ });
+ await writeJson(findingsPath, findings);
+ await writeJson(coveragePath, coverage);
+ await reseal(scanDirectory, manifest);
+ return findings.findings;
+}