OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
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.tsindex 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.tsindex 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")).reviewStatediff --git a/plugins/codex-security/mcp-app/tests/scan-identity-recovery-fixture.ts b/plugins/codex-security/mcp-app/tests/scan-identity-recovery-fixture.tsindex 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.tsindex 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", asynclabel: "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 reservedinitial.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 reservedtest("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.tsindex 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);elseawait 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", asyncseverity: { 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]),);elseawait 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.tsindex 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);elseawait 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],+ });elseawait 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 (tconst 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 (tfor (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);elseawait 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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;+}