Skip to content

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

fix(artifacts): keep saved findings consistent through recovery (#1310)

Michael D'Angeloe6c7b28ad39e
diff --git a/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts b/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts
index bb9397b88..04dda1623 100644
--- a/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts
+++ b/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts
@@ -22,13 +22,16 @@ import {
import { artifactSchemaDocuments } from "./artifact-contracts.js";
import { projectArtifactToolSchema } from "./artifact-schema-loader.js";
import { saveThreatModelDocument } from "./threat-model-document.js";
+import coverageDocument from "../../schemas/coverage.schema.json" with { type: "json" };
+import findingsDocument from "../../schemas/findings.schema.json" with { type: "json" };
+import scanManifestDocument from "../../schemas/scan-manifest.schema.json" with { type: "json" };
import { requireFiniteNumbers } from "./helpers/json.js";
const draftDefinitions = artifactSchemaDocuments["tools/scan-draft"].$defs;
export const scanDraftInputSchema = projectArtifactToolSchema(
draftDefinitions.scanDraftInput,
);
-// File-authored scan IDs are host-owned; their finding fields use the same contract.
+// File-authored scan IDs are host-owned.
const fileScanDraftInputSchema = scanDraftInputSchema.extend({
scanId: z.string().min(1),
});
@@ -37,6 +40,61 @@ export type ScanDraftInput = z.infer<typeof scanDraftInputSchema>;
type DraftCoverage = ScanDraftInput["coverage"];
export type CompletedScanInput = z.infer<typeof completedScanInputSchema>;
+function canonicalFieldSchema(schema: object): z.ZodType {
+ return z.fromJSONSchema(schema as Parameters<typeof z.fromJSONSchema>[0]);
+}
+
+// Canonical files can retain fields that the compact tool input does not accept.
+const canonicalScanDraftInputSchema = fileScanDraftInputSchema.extend({
+ scope: canonicalFieldSchema({
+ ...scanManifestDocument.properties.scan.properties.scope,
+ $defs: scanManifestDocument.$defs,
+ required:
+ z.toJSONSchema(draftDefinitions.scope, { io: "input" }).required ?? [],
+ }).optional(),
+ threatModel: canonicalFieldSchema({
+ ...scanManifestDocument.properties.scan.properties.threatModel,
+ $defs: scanManifestDocument.$defs,
+ }).optional(),
+ findings: canonicalFieldSchema({
+ ...findingsDocument.properties.findings,
+ $defs: findingsDocument.$defs,
+ items: {
+ ...findingsDocument.properties.findings.items,
+ required: z.toJSONSchema(draftDefinitions.finding, { io: "input" })
+ .required,
+ },
+ }),
+ coverage: draftDefinitions.coverage.extend({
+ surfaces: canonicalFieldSchema({
+ ...coverageDocument.properties.surfaces,
+ items: {
+ ...coverageDocument.properties.surfaces.items,
+ required: z.toJSONSchema(draftDefinitions.surface, { io: "input" })
+ .required,
+ },
+ }),
+ deferred: canonicalFieldSchema({
+ ...coverageDocument.properties.deferred,
+ items: {
+ ...coverageDocument.properties.deferred.items,
+ required: z.toJSONSchema(
+ draftDefinitions.coverage.shape.deferred.element,
+ { io: "input" },
+ ).required,
+ },
+ }),
+ openQuestions: z
+ .array(
+ z.union([
+ z.string(),
+ canonicalFieldSchema(coverageDocument.properties.openQuestions.items),
+ ]),
+ )
+ .optional(),
+ }),
+}) as z.ZodType<ScanDraftInput>;
+
export interface ScanDraftResult {
scanId: string;
findingCount: number;
@@ -70,6 +128,9 @@ interface SavedScanDraft {
attempt?: string;
}
+const findingIdentitySchema = draftDefinitions.identity;
+const findingProvenanceSchema = draftDefinitions.finding.shape.provenance;
+
/** Stage a parent draft, then publish it under the workbench completion lock. */
export async function recordCodexSecurityScanDraftViaWorkbench(
context: ArtifactContext,
@@ -345,9 +406,27 @@ export async function saveScanDraftCheckpoint(
input: Omit<ScanDraftInput, "coverage">,
updateHead = true,
): Promise<void> {
- const { handoffClaimToken: _claim, ...snapshot } = input;
+ const { handoffClaimToken: _claim, ...raw } = input;
+ const head =
+ context.layout === "scan" &&
+ context.mode === "deep" &&
+ input.complete !== false
+ ? await readCheckpointHead(context, "current")
+ : undefined;
+ const snapshot =
+ context.layout === "scan" &&
+ context.mode === "deep" &&
+ input.complete !== false
+ ? {
+ ...raw,
+ publication: {
+ previousCheckpoint: head?.checkpoint ?? null,
+ previousInputCheckpoint: head?.inputCheckpoint ?? null,
+ },
+ }
+ : raw;
const contents = JSON.stringify(snapshot, null, 2) + "\n";
- const name = scanDraftCheckpointName(input);
+ const name = scanDraftCheckpointName(snapshot);
const destination = await artifactDestination(
context,
["checkpoints", name],
@@ -555,17 +634,68 @@ async function preserveScanDraft(
.map(({ input }) => input)
.reverse();
progressSources.push(input);
- let acceptProgress = coverageHasOutstandingWork(result.coverage);
+ const terminalSurfaceIds = new Set(
+ (result.coverage.surfaces as JsonObject[])
+ .filter((row) => row.disposition !== "needs_follow_up")
+ .flatMap((row) =>
+ [row.id, row.candidateId].filter(
+ (id): id is string => typeof id === "string",
+ ),
+ ),
+ );
+ const terminalWorkIds = new Set([
+ ...terminalSurfaceIds,
+ ...closedIds,
+ ...terminalOutcomeIds,
+ ...(result.coverage.deferred as JsonObject[]).flatMap((row) =>
+ [row.id, row.candidateId].filter(
+ (id): id is string => typeof id === "string",
+ ),
+ ),
+ ]);
+ const retainedHasOutstandingWork = coverageHasOutstandingWork(
+ result.coverage,
+ );
+ let acceptProgress = retainedHasOutstandingWork;
for (const observation of progressSources) {
const progress = structuredClone(observation);
+ const deferred = progress.coverage.deferred.filter(
+ (row) =>
+ keepsGenericWork(row) ||
+ !terminalOutcomeIds.has((row.candidateId ?? row.id) as string),
+ );
+ const pending = new Set(deferred);
+ const linked = (row: JsonObject, surface: JsonObject) =>
+ row.id === surface.id ||
+ ((row.surfaceIds as string[] | undefined) ?? []).includes(
+ surface.id as string,
+ );
+ progress.coverage.surfaces = progress.coverage.surfaces.filter(
+ (surface) =>
+ surface.disposition !== "needs_follow_up" ||
+ !progress.coverage.deferred.some(
+ (row) => !pending.has(row) && linked(row, surface),
+ ) ||
+ deferred.some((row) => linked(row, surface)),
+ );
const reopenedIds = new Set(
- progress.coverage.deferred.flatMap((row) =>
+ deferred.flatMap((row) =>
[row.id, row.candidateId].filter(
- (id): id is string => typeof id === "string" && closedIds.has(id),
+ (id): id is string =>
+ typeof id === "string" &&
+ (closedIds.has(id) || terminalSurfaceIds.has(id)),
),
),
);
- if (reopenedIds.size > 0) acceptProgress = true;
+ const newWork = [
+ ...progress.coverage.deferred,
+ ...progress.coverage.surfaces.filter(
+ (row) => row.disposition === "needs_follow_up",
+ ),
+ ].some(
+ (row) => !terminalWorkIds.has((row.candidateId ?? row.id) as string),
+ );
+ if (reopenedIds.size > 0 || newWork) acceptProgress = true;
if (!acceptProgress) continue;
result.complete = false;
const resolved = reconcileDeferredSurfaces(
@@ -580,16 +710,21 @@ async function preserveScanDraft(
result.coverage = preserveScanCoverage(
{
...result.coverage,
- deferred: progress.coverage.deferred.filter(
- (row) =>
- keepsGenericWork(row) ||
- !terminalOutcomeIds.has((row.candidateId ?? row.id) as string),
- ),
+ deferred,
surfaces: progress.coverage.surfaces.filter(
(surface) =>
- keepsGenericWork(surface) ||
- (!terminalOutcomeIds.has(surface.id as string) &&
- !terminalOutcomeIds.has(surface.candidateId as string)),
+ (keepsGenericWork(surface) ||
+ (!terminalOutcomeIds.has(surface.id as string) &&
+ !terminalOutcomeIds.has(surface.candidateId as string))) &&
+ (retainedHasOutstandingWork ||
+ surface.disposition !== "needs_follow_up" ||
+ !terminalSurfaceIds.has(
+ (surface.candidateId ?? surface.id) as string,
+ ) ||
+ reopenedIds.has(
+ (surface.candidateId ?? surface.id) as string,
+ ) ||
+ deferred.some((row) => linked(row, surface))),
),
},
result.coverage,
@@ -644,6 +779,20 @@ async function preserveScanDraft(
);
});
+ const preserveDetails = (current: JsonObject, previous: JsonObject) => {
+ const reservedIdentity =
+ current.identity === undefined &&
+ previous.identity !== undefined &&
+ result.findings.some(
+ (finding) =>
+ finding !== current &&
+ finding.identity !== undefined &&
+ sameSavedFinding(finding, previous),
+ );
+ preserveFindingDetails(current, previous);
+ if (reservedIdentity) delete current.identity;
+ };
+
for (const source of sources) {
const deferred = result.coverage.deferred;
const dispositions = result.coverage.surfaces.filter(
@@ -684,6 +833,19 @@ async function preserveScanDraft(
}
}
}
+ const assignedFindings = new Set<JsonObject>();
+ const unmatchedFindings = new Set(
+ source.findings.filter((previous) => {
+ const matches = result.findings.filter(
+ (current) =>
+ current.identity !== undefined &&
+ previous.identity !== undefined &&
+ sameSavedFinding(current, previous),
+ );
+ for (const current of matches) assignedFindings.add(current);
+ return matches.length === 0;
+ }),
+ );
for (const finding of source.findings) {
const candidateId = findingCandidateId(finding);
const disposition =
@@ -697,18 +859,83 @@ async function preserveScanDraft(
disposition.finding ??= structuredClone(finding);
continue;
}
- const matches = result.findings.filter((current) =>
+ const available = result.findings.filter(
+ (current) =>
+ !assignedFindings.has(current) ||
+ (current.identity !== undefined &&
+ finding.identity !== undefined &&
+ sameSavedFinding(current, finding)),
+ );
+ const matches = available.filter((current) =>
sameSavedFinding(current, finding),
);
+ const containing = matches.filter((current) =>
+ containsSavedFinding(current, finding),
+ );
+ const revisions = matches.filter((current) =>
+ sameSavedRevision(current, finding),
+ );
if (
matches.length === 1 &&
- source.findings.filter((current) => sameSavedFinding(current, finding))
- .length === 1
+ source.findings.filter(
+ (current) =>
+ (finding.identity === undefined ||
+ matches[0]!.identity === undefined ||
+ current.identity !== undefined) &&
+ (current === finding ||
+ unmatchedFindings.has(current) ||
+ (current.identity !== undefined &&
+ finding.identity !== undefined &&
+ sameSavedFinding(current, finding))) &&
+ sameSavedFinding(
+ current,
+ containing.length === 1 ? finding : matches[0]!,
+ ),
+ ).length === 1
) {
- preserveFindingDetails(matches[0]!, finding);
- } else {
- if (!matches.some((current) => containsSavedFinding(current, finding)))
- result.findings.push(structuredClone(finding));
+ preserveDetails(matches[0]!, finding);
+ assignedFindings.add(matches[0]!);
+ } else if (
+ containing.length === 1 &&
+ source.findings.filter((previous) =>
+ containsSavedFinding(containing[0]!, previous),
+ ).length === 1
+ ) {
+ // An unchanged sibling still owns its previously published identity.
+ preserveDetails(containing[0]!, finding);
+ assignedFindings.add(containing[0]!);
+ } else if (
+ revisions.length === 1 &&
+ source.findings.filter((current) =>
+ sameSavedRevision(current, revisions[0]!),
+ ).length === 1
+ ) {
+ preserveDetails(revisions[0]!, finding);
+ assignedFindings.add(revisions[0]!);
+ } else if (
+ !available.some((current) => {
+ const history = (current.provenance as JsonObject).previousFindings;
+ return (
+ Array.isArray(history) &&
+ history.some((previous) => {
+ if (
+ !isObject(previous) ||
+ !containsSavedFinding(previous, finding) ||
+ source.findings.filter((sibling) =>
+ containsSavedFinding(previous, sibling),
+ ).length !== 1
+ )
+ return false;
+ preserveFindingDetails(previous, finding);
+ return true;
+ })
+ );
+ }) &&
+ containing.length === 0
+ ) {
+ const retained = structuredClone(finding);
+ result.findings.push(retained);
+ assignedFindings.add(retained);
}
}
const resolvedIds = new Set(
@@ -952,6 +1179,11 @@ async function preserveScanDraft(
receiptPaths.set(key, normalized);
}
}
+ result = (
+ context.layout === "scan"
+ ? canonicalScanDraftInputSchema
+ : scanDraftInputSchema
+ ).parse(result);
if (saveCheckpoint) await saveScanDraftCheckpoint(context, result);
return {
input: result,
@@ -1334,7 +1566,10 @@ function reconcileDeferredSurfaces(
async function readCheckpointHead(
context: ArtifactContext,
kind: "current" | "archived",
-): Promise<{ checkpoint: string; modifiedMs: number } | undefined> {
+): Promise<
+ | { checkpoint: string; inputCheckpoint?: string; modifiedMs: number }
+ | undefined
+> {
const metadata = await lstatIfExists(
join(context.root, "checkpoint-head.json"),
);
@@ -1356,7 +1591,13 @@ async function readCheckpointHead(
)
throw new Error(`scan checkpoint: ${kind} checkpoint head is invalid.`);
// Reselecting an immutable checkpoint updates only the head file.
- return { checkpoint: head.checkpoint, modifiedMs: saved.modifiedMs };
+ return {
+ checkpoint: head.checkpoint,
+ ...(typeof head.inputCheckpoint === "string"
+ ? { inputCheckpoint: head.inputCheckpoint }
+ : {}),
+ modifiedMs: saved.modifiedMs,
+ };
}
async function readSavedCheckpoints(
@@ -1742,6 +1983,28 @@ function sameSavedFinding(left: JsonObject, right: JsonObject): boolean {
if (left.ruleId !== right.ruleId) return false;
if (left.identity && right.identity)
return scanFindingIdentity(left) === scanFindingIdentity(right);
+ const leftExplicitCandidate = findingIdentityCandidate(left);
+ const rightExplicitCandidate = findingIdentityCandidate(right);
+ if (
+ leftExplicitCandidate &&
+ rightExplicitCandidate &&
+ leftExplicitCandidate !== rightExplicitCandidate
+ )
+ return false;
+ // Report identifiers distinguish siblings that share the same candidate.
+ const reportIds = ["reportId", "ledgerRowId"].map((field) =>
+ [left, right].map((finding) => {
+ const value = (finding.extensions as JsonObject | undefined)?.[field];
+ return typeof value === "string" && value.trim() ? value : undefined;
+ }),
+ );
+ if (
+ reportIds.some(([left]) => left) &&
+ reportIds.some(([, right]) => right) &&
+ (!reportIds.some(([left, right]) => left && right) ||
+ reportIds.some(([left, right]) => left && right && left !== right))
+ )
+ return false;
const leftCandidate = findingCandidateId(left);
if (leftCandidate && leftCandidate === findingCandidateId(right)) return true;
return (
@@ -1750,6 +2013,19 @@ function sameSavedFinding(left: JsonObject, right: JsonObject): boolean {
);
}
+function sameSavedRevision(left: JsonObject, right: JsonObject): boolean {
+ const leftOwner = (left.provenance as JsonObject | undefined)?.workerId;
+ const rightOwner = (right.provenance as JsonObject | undefined)?.workerId;
+ return (
+ (typeof leftOwner !== "string" ||
+ typeof rightOwner !== "string" ||
+ leftOwner === rightOwner) &&
+ left.title === right.title &&
+ isDeepStrictEqual(left.locations, right.locations) &&
+ sameSavedFinding(left, right)
+ );
+}
+
function withoutPreviousFindings(finding: JsonObject): JsonObject {
const result = structuredClone(finding);
if (isObject(result.provenance)) delete result.provenance.previousFindings;
@@ -1761,7 +2037,10 @@ export function preserveFindingDetails(
current: JsonObject,
previous: JsonObject,
): void {
- if (current.identity === undefined && previous.identity !== undefined) {
+ if (
+ current.identity === undefined &&
+ findingIdentitySchema.safeParse(previous.identity).success
+ ) {
current.identity = structuredClone(previous.identity);
}
const provenance = requireObject(
@@ -1781,11 +2060,25 @@ export function preserveFindingDetails(
Array.isArray(provenance[field]) ? provenance[field] : [],
Array.isArray(oldProvenance[field]) ? oldProvenance[field] : [],
);
- if (values.length) provenance[field] = values;
+ const fieldSchema =
+ field === "sourceFindingIds" || field === "sourceFindings"
+ ? findingProvenanceSchema.shape[field]
+ : undefined;
+ if (
+ values.length &&
+ (!fieldSchema || fieldSchema.safeParse(values).success)
+ )
+ provenance[field] = values;
}
if (!containsSavedFinding(current, previous)) {
const original = withoutPreviousFindings(previous);
- if (isObject(original.provenance))
+ if (
+ isObject(original.provenance) &&
+ containsSavedValue(
+ provenance.sourceFindings,
+ original.provenance.sourceFindings,
+ )
+ )
delete original.provenance.sourceFindings;
provenance.previousFindings = exactUnion(
Array.isArray(provenance.previousFindings)
@@ -1800,6 +2093,10 @@ function containsSavedFinding(
current: JsonObject,
previous: JsonObject,
): boolean {
+ const currentOwner = (current.provenance as JsonObject | undefined)?.workerId;
+ const previousOwner = (previous.provenance as JsonObject | undefined)
+ ?.workerId;
+ if (!isDeepStrictEqual(currentOwner, previousOwner)) return false;
const original = withoutPreviousFindings(previous);
if (current.identity === undefined) delete original.identity;
return containsSavedValue(current, original);
@@ -1969,6 +2266,16 @@ export function scanFindingIdentity(finding: JsonObject): string {
]);
}
+function findingIdentityCandidate(finding: JsonObject): string | undefined {
+ return [
+ (finding.extensions as JsonObject | undefined)?.candidateId,
+ (finding.provenance as JsonObject | undefined)?.candidateId,
+ ].find(
+ (value): value is string =>
+ typeof value === "string" && Boolean(value.trim()),
+ );
+}
+
function findingCandidateId(finding: JsonObject): string | undefined {
const provenance = finding.provenance;
if (
@@ -2096,7 +2403,7 @@ export function parseCanonicalScanDraft(input: {
function parseCanonicalCheckpoint(
input: Record<string, unknown>,
): ScanDraftInput {
- const parsed = parsePersistedCheckpoint(input);
+ const parsed = parsePersistedCheckpoint(input, canonicalScanDraftInputSchema);
for (const [index, finding] of parsed.findings.entries()) {
for (const field of ["locations", "codeEvidence"] as const) {
for (const [locationIndex, location] of (
@@ -2152,8 +2459,10 @@ export function parsePersistedScanDraft(
function parsePersistedCheckpoint(
input: Record<string, unknown>,
+ schema: z.ZodType<ScanDraftInput> = fileScanDraftInputSchema,
): ScanDraftInput {
const compatible = structuredClone(input);
+ delete compatible.publication;
if (isObject(compatible.scope)) {
delete compatible.scope.includePaths;
delete compatible.scope.excludePaths;
@@ -2180,7 +2489,7 @@ function parsePersistedCheckpoint(
delete finding.fingerprints;
}
}
- return parsePersistedScanDraft(compatible, fileScanDraftInputSchema);
+ return parsePersistedScanDraft(compatible, schema);
}
function requireBoundScan(
@@ -2343,12 +2652,8 @@ function buildScope(
function buildFindings(findings: JsonObject[], mode?: string): JsonObject[] {
const anchorCounts = new Map<string, number>();
const anchors = findings.map((finding, index) => {
- const candidateId = (finding.extensions as JsonObject | undefined)
- ?.candidateId;
const identitySource =
- typeof candidateId === "string" && candidateId.trim()
- ? candidateId
- : (finding.title as string);
+ findingIdentityCandidate(finding) ?? (finding.title as string);
const anchor =
finding.identity === undefined
? semanticIdentifier(identitySource, `finding-${index + 1}`)
@@ -2384,15 +2689,22 @@ function buildFindings(findings: JsonObject[], mode?: string): JsonObject[] {
identity,
};
});
- if (mode !== "deep") return identified;
+ // Keep generated identities distinct without replacing an authored identity.
+ const authored = new Set(
+ findings
+ .filter((finding) => finding.identity !== undefined)
+ .map(scanFindingIdentity),
+ );
// Keep both findings when workers reuse an ID.
// Add a numeric suffix to make each ID unique.
const reserved = new Set(identified.map(scanFindingIdentity));
const used = new Set<string>();
- return identified.map((finding) => {
+ return identified.map((finding, index) => {
+ const explicit = findings[index]!.identity !== undefined;
+ if (mode !== "deep" && explicit) return finding;
const key = scanFindingIdentity(finding);
- if (!used.has(key)) {
+ if (!used.has(key) && (explicit || !authored.has(key))) {
used.add(key);
return finding;
}
@@ -2410,12 +2722,14 @@ function buildFindings(findings: JsonObject[], mode?: string): JsonObject[] {
reserved.has(scanFindingIdentity(distinct)) ||
used.has(scanFindingIdentity(distinct))
);
- const provenance = finding.provenance as JsonObject;
- distinct.provenance = {
- ...provenance,
- preservedIdentity:
- provenance.preservedIdentity ?? structuredClone(identity),
- };
+ if (explicit) {
+ const provenance = finding.provenance as JsonObject;
+ distinct.provenance = {
+ ...provenance,
+ preservedIdentity:
+ provenance.preservedIdentity ?? structuredClone(identity),
+ };
+ }
used.add(scanFindingIdentity(distinct));
return distinct;
});
diff --git a/plugins/codex-security/mcp-app/tests/scan-draft-recovery-fixture.ts b/plugins/codex-security/mcp-app/tests/scan-draft-recovery-fixture.ts
index e73d4f97f..4e0681df6 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
@@ -36,11 +36,33 @@ export async function recordCodexSecurityScanDraft(
input,
async (args: string[]) => {
const draft = await readJson(args[args.indexOf("--draft-path") + 1]);
- const rawContents = await fs.readFile(
+ let rawContents = await fs.readFile(
args[args.indexOf("--checkpoint-path") + 1],
"utf8",
);
const checkpoint = JSON.parse(rawContents);
+ const { complete, scope, threatModel } = draft.manifest.scan;
+ const projected = {
+ scanId: checkpoint.scanId,
+ ...(complete === undefined ? {} : { complete }),
+ ...(scope === undefined ? {} : { scope }),
+ ...(threatModel === undefined ? {} : { threatModel }),
+ findings: draft.findings.findings,
+ coverage: draft.coverage,
+ };
+ if (context.mode === "deep") {
+ const head = await readJson(context.root, "checkpoint-head.json").catch(
+ (error) => {
+ if (error.code !== "ENOENT") throw error;
+ return undefined;
+ },
+ );
+ checkpoint.publication = {
+ previousCheckpoint: head?.checkpoint ?? null,
+ previousInputCheckpoint: head?.inputCheckpoint ?? null,
+ };
+ rawContents = JSON.stringify(checkpoint);
+ }
const rawName =
createHash("sha256").update(rawContents).digest("hex") + ".json";
await replaceArtifactText(
@@ -51,16 +73,23 @@ export async function recordCodexSecurityScanDraft(
),
rawContents,
);
- const { complete, scope, threatModel } = draft.manifest.scan;
await draftApi.saveScanDraftCheckpoint(
{ ...context, layout: "worker" },
+ projected,
+ false,
+ );
+ await replaceArtifactJson(
+ await artifactDestination(
+ context,
+ ["checkpoint-head.json"],
+ "scan checkpoint head",
+ ),
{
- scanId: checkpoint.scanId,
- ...(complete === undefined ? {} : { complete }),
- ...(scope === undefined ? {} : { scope }),
- ...(threatModel === undefined ? {} : { threatModel }),
- findings: draft.findings.findings,
- coverage: draft.coverage,
+ checkpoint:
+ createHash("sha256")
+ .update(JSON.stringify(projected))
+ .digest("hex") + ".json",
+ ...(checkpoint.publication ? { inputCheckpoint: rawName } : {}),
},
);
for (const [key, name] of [
@@ -190,3 +219,23 @@ export const surfaceDisposition = ({
id: string;
disposition: string;
}) => ({ id, disposition });
+
+/** Stop after the admitted raw checkpoint and before the projected checkpoint. */
+export async function interruptDraftAfterRaw(action: () => Promise<unknown>) {
+ const rename = fs.rename;
+ let checkpoints = 0;
+ fs.rename = async (source, destination) => {
+ if (
+ path.basename(path.dirname(String(destination))) === "checkpoints" &&
+ ++checkpoints === 2
+ )
+ throw new Error("interrupted projected checkpoint");
+ return rename(source, destination);
+ };
+ try {
+ await assert.rejects(action(), /interrupted projected checkpoint/);
+ assert.equal(checkpoints, 2);
+ } finally {
+ fs.rename = rename;
+ }
+}
diff --git a/plugins/codex-security/mcp-app/tests/scan-identity-recovery-fixture.ts b/plugins/codex-security/mcp-app/tests/scan-identity-recovery-fixture.ts
new file mode 100644
index 000000000..192ab9715
--- /dev/null
+++ b/plugins/codex-security/mcp-app/tests/scan-identity-recovery-fixture.ts
@@ -0,0 +1,111 @@
+import { execFile } from "node:child_process";
+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";
+
+const execFileAsync = promisify(execFile);
+export type FixtureFinding = Record<string, unknown> & {
+ title: string;
+ summary: string;
+ severity: { level: string };
+ locations: Array<{ path: string; startLine: number }>;
+ provenance: Record<string, unknown>;
+ extensions?: Record<string, unknown>;
+ identity?: { anchor?: string; instance?: string; [key: string]: unknown };
+};
+export type RecoveredFinding = FixtureFinding & {
+ identity: { anchor: string; instance?: string; [key: string]: unknown };
+ findingId: string;
+};
+export type DraftFixture = ReturnType<typeof draftFixture>;
+export const finding = (
+ title: string,
+ metadata: Record<string, unknown> = {},
+): FixtureFinding => ({
+ ruleId: "fixture.review",
+ title,
+ summary: "Synthetic saved evidence must retain its identity.",
+ severity: { level: "low" },
+ confidence: { level: "high", rationale: "Synthetic persistence fixture." },
+ taxonomy: { category: "other", cwe: [] },
+ locations: [{ path: "src/example.py", startLine: 1 }],
+ remediation: "Complete the review.",
+ provenance: { source: "local_plugin" },
+ ...metadata,
+});
+
+export async function recoverAndFinalize(
+ normal: DraftFixture,
+ recovered: DraftFixture,
+ workers: Record<string, unknown>[] = [],
+ details = false,
+ replay = false,
+ provenanceDetails = false,
+ source: "saved" | "published" = "saved",
+): Promise<{
+ normal: RecoveredFinding[];
+ recovered: RecoveredFinding[];
+ warnings: unknown[];
+ historySummaries: string[];
+ preservedIdentities: unknown[][];
+ normalCoverage: Record<string, unknown>;
+ recoveredCoverage: Record<string, unknown>;
+}> {
+ const { stdout } = await execFileAsync(
+ process.env.PYTHON?.trim() || "python3",
+ [
+ "-c",
+ `import json,sys
+from pathlib import Path
+sys.path.insert(0,sys.argv[1])
+from workbench_saved_results import merge_saved_results
+from finalize_scan_contract import _prepare_scan_finalization
+normal,recovered=map(Path,sys.argv[2:4])
+scan_id=sys.argv[4]
+manifest=json.loads((normal/'scan-manifest.json').read_text())
+coverage=json.loads((normal/'coverage.json').read_text())
+binding={'status':'failed','allowedTargetKinds':[manifest['scan']['target']['kind']],'target':manifest['scan']['target'],'scope':manifest['scan']['scope'],'coverageMode':coverage['mode']}
+binding.update(scanId=scan_id,producer={'name':'codex-security-plugin','version':'0.1.0'},startedAt='2026-05-31T18:00:00Z',completedAt='2026-05-31T18:09:00Z')
+warnings=[]
+recovery=merge_saved_results(recovered,scan_id,binding,json.loads(sys.argv[5]),warnings,stopped=True,reason='Synthetic interruption',scan_mode=sys.argv[10]) if sys.argv[9]=='saved' else tuple(json.loads((recovered/name).read_text()) for name in ['scan-manifest.json','findings.json','coverage.json'])
+if json.loads(sys.argv[7]):
+ replayed=merge_saved_results(recovered,scan_id,binding,json.loads(sys.argv[5]),[],stopped=True,reason='Synthetic interruption',frozen_source_digests=recovery[0]['scan']['preservedSources'],scan_mode=sys.argv[10])
+ assert replayed == recovery, 'Frozen recovery changed the retained documents'
+ordinary=(manifest,json.loads((normal/'findings.json').read_text()),coverage)
+results=[]
+preserved_identities=[]
+for root,documents in [(normal,ordinary),(recovered,recovery)]:
+ documents[0]['scan'].update(id=scan_id,producer={'name':'codex-security-plugin','version':'0.1.0'},status='failed',startedAt='2026-05-31T18:00:00Z',completedAt='2026-05-31T18:09:00Z')
+ for document in documents[1:]: document['scanId']=scan_id
+ prepared=_prepare_scan_finalization(root,completion_binding=binding,recover_unsealed=True,draft_documents=documents)
+ warnings.extend(prepared.warnings)
+ preserved_identities.append([row.get('provenance',{}).get('preservedIdentity') for row in prepared.findings['findings']])
+ results.append([{'title':row['title'],'identity':row['identity'],'fingerprints':row['fingerprints'],'findingId':row['findingId'],'occurrenceId':row['occurrenceId'],'workerMetadata':row.get('provenance',{}).get('workerId'),**({'evidenceProvenance':{key:row.get('provenance',{}).get(key,[]) for key in ['sourceFindingIds','sourceFindings','previousFindings','originalCandidates']}} if json.loads(sys.argv[8]) else {}),**({'summary':row['summary'],'locations':row['locations'],'severity':row['severity'],'candidateMetadata':{'provenance':row.get('provenance',{}).get('candidateId'),'extensions':row.get('extensions')}} if json.loads(sys.argv[6]) else {})} for row in prepared.findings['findings']])
+print(json.dumps({'normal':results[0],'recovered':results[1],'warnings':warnings,'normalCoverage':ordinary[2],'recoveredCoverage':recovery[2],'preservedIdentities':preserved_identities,'historySummaries':[previous.get('summary') for row in recovery[1]['findings'] for previous in row.get('provenance',{}).get('previousFindings',[]) if isinstance(previous,dict)]}))`,
+ fileURLToPath(new URL("../../scripts", import.meta.url)),
+ normal.root,
+ recovered.root,
+ normal.context.scanId!,
+ JSON.stringify(workers),
+ JSON.stringify(details),
+ JSON.stringify(replay),
+ JSON.stringify(provenanceDetails),
+ source,
+ normal.context.mode!,
+ ],
+ );
+ return JSON.parse(stdout);
+}
+
+export async function dateDraftFiles(
+ root: string,
+ time: number,
+): Promise<void> {
+ for (const entry of await readdir(root, { withFileTypes: true })) {
+ const target = path.join(root, entry.name);
+ if (entry.isDirectory()) await dateDraftFiles(target, time);
+ else await utimes(target, time, time);
+ }
+}
diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft.ts
index bea88fc75..78f938de8 100644
--- a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft.ts
+++ b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft.ts
@@ -265,10 +265,10 @@ try {
"checkpoints",
acceptedHead.checkpoint,
);
- assert.notEqual(
+ assert.equal(
acceptedHeadDraft.complete,
false,
- "a rejected incomplete write must not become the authoritative checkpoint head",
+ "new late work must remain incomplete in the authoritative checkpoint",
);
assert.deepEqual(acceptedHeadDraft.findings, [finding]);
const acceptedResult = await readJson(rejectedIncompleteRoot, "result.json");
@@ -276,8 +276,8 @@ try {
acceptedResult.coverage.deferred.some(
(item: FixtureFinding) => item.candidateId === "late-incomplete-review",
),
- false,
- "a rejected incomplete write must not change the completed result",
+ true,
+ "new late work must survive alongside the completed candidate",
);
const deferredDoesNotRejectContext = await createWorkerContext(
@@ -2376,13 +2376,13 @@ try {
),
[
{ anchor: "candidate-authored-instance", instance: "dss-147-a" },
- { anchor: "candidate-authored-instance", instance: "dss-147-a" },
+ { anchor: "candidate-authored-instance", instance: "dss-147-a-2" },
{
anchor: "candidate-authored-instance",
instance: "ledger-row-c",
},
],
- "duplicate stable instance sources remain collisions for finalization",
+ "generated instances avoid an existing authored identity",
);
const collisionFindings = [
@@ -2449,10 +2449,17 @@ try {
assert.deepEqual(
standardFindings.map((item: FixtureFinding) => item.identity),
collisionCase.findings.map(
- (item: FixtureFinding) =>
- item.identity ?? collisionCase.originalIdentity,
+ (item: FixtureFinding, index) =>
+ item.identity ?? {
+ ...collisionCase.originalIdentity,
+ ...(index === 0
+ ? {}
+ : {
+ instance: `${(collisionCase.originalIdentity as { instance?: string }).instance}-${index + 1}`,
+ }),
+ },
),
- `${collisionCase.label} identity collisions retain the existing Standard shape`,
+ `${collisionCase.label} identities preserve authored values and split generated collisions`,
);
assert.deepEqual(
standardFindings.map((item: FixtureFinding) => item.provenance),
@@ -2486,7 +2493,7 @@ try {
assert.deepEqual(
deepFindings.map((item: FixtureFinding) => item.provenance),
collisionCase.findings.map((item: FixtureFinding, index) =>
- index === 1 || index === 2
+ item.identity !== undefined && (index === 1 || index === 2)
? {
...item.provenance,
preservedIdentity: collisionCase.originalIdentity,
diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts
index 70d3a71f7..8d07964d7 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
@@ -15,6 +15,7 @@ import {
} from "node:fs/promises";
import path from "node:path";
import test from "node:test";
+import { fileURLToPath } from "node:url";
import { isDeepStrictEqual, promisify } from "node:util";
import {
draftApi,
@@ -28,7 +29,14 @@ const { recordCodexSecurityScanDraftViaWorkbench, saveScanDraftCheckpoint } =
const execFileAsync = promisify(execFile);
const generic = { reason: "Review remains.", paths: ["src/example.py"] };
const close = (id: string, reason = "Review completed.") => ({ id, reason });
-const findingFor = (candidateId: string) => ({
+type FixtureFinding = Record<string, unknown> & {
+ title: string;
+ severity: { level: string };
+ provenance: Record<string, unknown>;
+ extensions?: Record<string, unknown>;
+ locations: Array<{ path: string; startLine: number; endLine?: number }>;
+};
+const findingFor = (candidateId: string): FixtureFinding => ({
ruleId: "fixture.review",
title: "Synthetic review finding",
summary: "The candidate outcome must survive publication.",
@@ -40,6 +48,352 @@ const findingFor = (candidateId: string) => ({
provenance: { source: "local_plugin", candidateId },
});
+for (const layout of ["standard", "diff", "deep"] as const) {
+ for (const variant of [
+ "one",
+ "three",
+ "legacy",
+ "owner",
+ "siblings",
+ "preserved",
+ "new-sibling",
+ "new-worker-sibling",
+ "range-refinement",
+ "report-added",
+ "ledger-added",
+ "report-id",
+ "ledger-id",
+ "worker-report-id",
+ "worker-ledger-id",
+ "cross-field-id",
+ "severity-revision",
+ "title-revision",
+ "new-sibling-checkpoints",
+ "new-worker-sibling-checkpoints",
+ ]) {
+ for (const status of ["failed", "canceled"]) {
+ test(`${layout}: stopped ${status} recovery retains ${variant} candidate identities`, async (t) => {
+ const f = await fixture(t, layout);
+ const count =
+ variant === "three"
+ ? 3
+ : variant.includes("sibling") || variant === "preserved"
+ ? 2
+ : variant.endsWith("-id")
+ ? 2
+ : 1;
+ const findings = Array.from({ length: count }, (_, index) => {
+ const finding = findingFor(
+ variant.includes("sibling") || variant.endsWith("-id")
+ ? "shared-review"
+ : `review-${index + 1}`,
+ );
+ if (
+ variant === "owner" ||
+ variant.startsWith("new-worker-") ||
+ variant.startsWith("worker-")
+ )
+ finding.provenance.workerId = "worker-1";
+ if (variant.includes("sibling"))
+ finding.title = `Synthetic sibling ${index + 1}`;
+ if (variant.endsWith("-id"))
+ finding.extensions = {
+ [variant.includes("report") ||
+ (variant === "cross-field-id" && index === 0)
+ ? "reportId"
+ : "ledgerRowId"]: `synthetic-report-${index + 1}`,
+ };
+ if (variant === "preserved")
+ finding.locations[0].startLine = index + 1;
+ return finding;
+ });
+ if (variant === "legacy")
+ Object.assign(findings[0], {
+ identity: { anchor: "synthetic-review-finding" },
+ });
+ if (variant === "severity-revision") {
+ 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.write({
+ ...f.draft(),
+ findings: variant.endsWith("-id") ? findings.slice(0, 1) : findings,
+ });
+ if (variant.endsWith("-id"))
+ await saveScanDraftCheckpoint(
+ f.context,
+ { ...f.draft(), findings: findings.slice(1) },
+ false,
+ );
+ if (variant.endsWith("-added")) {
+ findings[0].extensions = {
+ [variant === "report-added" ? "reportId" : "ledgerRowId"]:
+ "synthetic-report-1",
+ };
+ await f.write({ ...f.draft(), findings });
+ }
+ if (variant === "title-revision") {
+ findings[0].title = "Revised synthetic review finding";
+ await f.write({ ...f.draft(), findings });
+ }
+ if (variant === "range-refinement") {
+ findings[0].locations[0].endLine = 1;
+ await f.write({ ...f.draft(), findings });
+ }
+ if (variant.startsWith("new-")) {
+ const file = path.join(f.root, "findings.json");
+ const saved = JSON.parse(await readFile(file, "utf8"));
+ 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,
+ );
+ }
+ if (variant === "preserved") {
+ const file = path.join(f.root, "findings.json");
+ const saved = JSON.parse(await readFile(file, "utf8"));
+ saved.findings[1].provenance.preservedIdentity = structuredClone(
+ saved.findings[1].identity,
+ );
+ saved.findings[1].identity.instance = "saved-distinct-location";
+ await writeFile(file, JSON.stringify(saved));
+ }
+ const { stdout } = await execFileAsync(
+ process.env.PYTHON?.trim() || "python3",
+ [
+ "-c",
+ `import sys,json
+from pathlib import Path
+sys.path.insert(0,sys.argv[1])
+from workbench_saved_results import merge_saved_results
+from finalize_scan_contract import _prepare_scan_finalization, _write_prepared_scan_finalization
+root,scan_id,status=Path(sys.argv[2]),sys.argv[3],sys.argv[4]
+manifest=json.loads((root/'scan-manifest.json').read_text())
+coverage=json.loads((root/'coverage.json').read_text())
+binding={'status':status,'allowedTargetKinds':[manifest['scan']['target']['kind']],'target':manifest['scan']['target'],'scope':manifest['scan']['scope'],'coverageMode':coverage['mode']}
+binding.update(scanId=scan_id,producer={'name':'codex-security-plugin','version':'0.1.0'},startedAt='2026-05-31T18:00:00Z',completedAt='2026-05-31T18:09:00Z')
+warnings=[]
+documents=merge_saved_results(root,scan_id,binding,[],warnings,stopped=True,reason='Synthetic interruption')
+documents[0]['scan'].update(id=scan_id,producer={'name':'codex-security-plugin','version':'0.1.0'},status=status,startedAt='2026-05-31T18:00:00Z',completedAt='2026-05-31T18:09:00Z')
+for document in documents[1:]: document['scanId']=scan_id
+prepared=_prepare_scan_finalization(root,completion_binding=binding,recover_unsealed=True,draft_documents=documents)
+warnings.extend(prepared.warnings)
+published=_write_prepared_scan_finalization(prepared)
+print(json.dumps({'count':len(published[1]['findings']),'sealed':bool(published[0]['scan'].get('sealedAt')),'warnings':warnings,'assessments':sorted([row['title'],row['severity']['level']] for row in published[1]['findings'])}))`,
+ fileURLToPath(new URL("../../scripts", import.meta.url)),
+ f.root,
+ f.context.scanId!,
+ status,
+ ],
+ );
+ assert.deepEqual(JSON.parse(stdout), {
+ count,
+ sealed: true,
+ warnings: [],
+ assessments: findings
+ .map((finding) => [finding.title, finding.severity.level])
+ .sort(),
+ });
+ });
+ }
+ }
+}
+
+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" },
+ },
+ ],
+ };
+ 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",
+ ),
+ );
+ assert.equal(saved.findings.length, 1);
+ });
+ }
+ 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",
+ ),
+ );
+ assert.equal(saved.findings.length, 3);
+ if (layout !== "worker") {
+ assert.equal(
+ new Set(saved.findings.map(draftApi.scanFindingIdentity)).size,
+ 3,
+ );
+ const manifestPath = path.join(f.root, "scan-manifest.json");
+ const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+ Object.assign(manifest.scan, {
+ id: f.context.scanId!,
+ producer: { name: "codex-security-plugin", version: "0.1.0" },
+ status: "completed",
+ startedAt: "2026-05-31T18:00:00Z",
+ completedAt: "2026-05-31T18:09:00Z",
+ });
+ 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"));
+ document.scanId = f.context.scanId;
+ await writeFile(filePath, JSON.stringify(document));
+ }
+ await execFileAsync(process.env.PYTHON?.trim() || "python3", [
+ fileURLToPath(
+ new URL("../../scripts/finalize_scan_contract.py", import.meta.url),
+ ),
+ "--scan-dir",
+ f.root,
+ ]);
+ const completed = JSON.parse(
+ await readFile(path.join(f.root, "findings.json"), "utf8"),
+ );
+ assert.equal(completed.findings.length, 3);
+ }
+ assert.deepEqual(
+ new Set(
+ saved.findings.map(
+ (finding: FixtureFinding) => finding.provenance.candidateId,
+ ),
+ ),
+ new Set(["first", "second", "third"]),
+ );
+ });
+ 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" },
+ },
+ },
+ ],
+ }),
+ );
+ const submitted = {
+ ...f.draft({}, true),
+ findings: [findingFor("review")],
+ };
+ await f.write(submitted);
+ await f.write(submitted);
+ });
+}
+
+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());
+ const saved = await readJson(f.root, "scan-manifest.json");
+ assert.equal(saved.scan.scope.summary, "Archive handling");
+ assert.deepEqual(saved.scan.scope.includePaths, ["."]);
+ assert.deepEqual(saved.scan.scope.excludePaths, []);
+
+ await f.write({ ...f.draft(), scope: { summary: "Updated assessment" } });
+ const updated = await readJson(f.root, "scan-manifest.json");
+ assert.equal(updated.scan.scope.summary, "Updated assessment");
+ });
+ for (const variant of ["surface ID", "path spelling", "source annotation"]) {
+ test(`${layout}: checkpoints preserve canonical ${variant}`, async (t) => {
+ const f = await fixture(t, layout);
+ await f.write({
+ ...f.draft({
+ surfaces: [
+ {
+ id: "http-api",
+ label: "HTTP API",
+ disposition: "no_issue_found",
+ },
+ ],
+ }),
+ findings: [findingFor("review")],
+ });
+ const name = variant === "surface ID" ? "coverage.json" : "findings.json";
+ const document = await readJson(f.root, name);
+ if (variant === "surface ID") document.surfaces[0].id = "HTTP API";
+ else if (variant === "path spelling")
+ document.findings[0].locations[0].path = "src//example.py";
+ else
+ document.findings[0].provenance.sourceFindings = [
+ {
+ id: "source",
+ finding: findingFor("source"),
+ annotation: "retained",
+ },
+ ];
+ await writeJson(path.join(f.root, name), document);
+ // 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());
+ const saved = await readJson(f.root, name);
+ if (variant === "surface ID")
+ assert(
+ saved.surfaces.some(
+ (surface: { id: string }) => surface.id === "HTTP API",
+ ),
+ );
+ else {
+ const retained = saved.findings.find(
+ (finding: FixtureFinding) =>
+ finding.provenance.candidateId === "review",
+ );
+ if (variant === "path spelling")
+ assert.equal(retained.locations[0].path, "src//example.py");
+ else
+ assert.deepEqual(
+ retained.provenance.sourceFindings,
+ document.findings[0].provenance.sourceFindings,
+ );
+ }
+ }
+ });
+ }
+}
+
for (const layout of ["standard", "diff"] as const) {
test(`${layout}: parent writes return receipt repairs and workbench warnings`, async (t) => {
const f = await fixture(t, layout);
@@ -114,7 +468,7 @@ for (const source of ["title", "candidateId", "reportId", "ledgerRowId"]) {
const finding = {
...findingFor("candidate-example"),
...(source === "title"
- ? { title: value }
+ ? { title: value, provenance: { source: "local_plugin" } }
: { extensions: { [source]: value } }),
};
const draft = { ...f.draft(), findings: [finding] };
@@ -1680,7 +2034,139 @@ for (const layout of ["standard", "diff", "worker"] as const) {
});
}
- test(`${layout}: ignored late progress keeps an accepted terminal marker`, async (t) => {
+ test(`${layout}: unfinished surfaces retain later notes and receipts`, async (t) => {
+ const f = await fixture(t, layout);
+ const initial = {
+ id: "api",
+ label: "API review",
+ disposition: "needs_follow_up",
+ notes: "Initial evidence",
+ receiptRefs: ["artifacts/initial.md"],
+ };
+ await f.write(
+ f.draft({ completeness: "partial", surfaces: [initial] }, true),
+ );
+ const updated = {
+ ...initial,
+ notes: "Updated evidence",
+ receiptRefs: ["artifacts/updated.md"],
+ };
+ await f.write(f.draft({ surfaces: [updated] }));
+ assert.deepEqual(
+ (await f.read()).surfaces.find(
+ (row: { id: string }) => row.id === initial.id,
+ ),
+ updated,
+ );
+ await f.write(f.draft({}, true));
+ assert.deepEqual(
+ (await f.read()).surfaces.find(
+ (row: { id: string }) => row.id === initial.id,
+ ),
+ updated,
+ );
+ });
+
+ test(`${layout}: new late work does not undo an already reviewed surface`, async (t) => {
+ const f = await fixture(t, layout);
+ const reviewed = {
+ id: "existing",
+ 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 }],
+ }),
+ );
+ const coverage = await f.read();
+ assert.equal(
+ coverage.surfaces.find((row: { id: string }) => row.id === reviewed.id)
+ .disposition,
+ "no_issue_found",
+ );
+ assert.deepEqual(coverage.deferred, [{ id: "new-review", ...generic }]);
+ });
+
+ for (const pendingBefore of [false, true]) {
+ for (const pendingAfter of [false, true]) {
+ test(`${layout}: surface-only progress respects retained pending work, before=${pendingBefore}, after=${pendingAfter}`, async (t) => {
+ const f = await fixture(t, layout);
+ const reviewed = {
+ id: "api",
+ label: "API review",
+ disposition: "no_issue_found",
+ notes: "The original caller was reviewed.",
+ receiptRefs: ["artifacts/original.md"],
+ };
+ const prior = { id: "prior-review", ...generic };
+ const later = { id: "later-review", ...generic };
+ await f.write(
+ f.draft(
+ { surfaces: [reviewed], deferred: pendingBefore ? [prior] : [] },
+ true,
+ ),
+ );
+ const followUp = {
+ ...reviewed,
+ disposition: "needs_follow_up",
+ notes: "A newly discovered caller still needs review.",
+ receiptRefs: ["artifacts/new-caller.md"],
+ };
+ for (const progress of [
+ f.draft({
+ surfaces: [followUp],
+ deferred: pendingAfter ? [later] : [],
+ }),
+ f.draft(),
+ ]) {
+ await f.write(progress);
+ const saved = await f.read();
+ assert.deepEqual(
+ saved.surfaces.find(
+ (row: { id: string }) => row.id === reviewed.id,
+ ),
+ pendingBefore ? followUp : reviewed,
+ );
+ const published = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "scan-manifest.json",
+ );
+ const complete =
+ layout === "worker" ? published.complete : published.scan.complete;
+ 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,
+ ),
+ );
+ const finished = await f.read();
+ assert.deepEqual(finished.deferred, []);
+ assert.equal(finished.surfaces[0].disposition, "no_issue_found");
+ const published = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "scan-manifest.json",
+ );
+ assert.notEqual(
+ layout === "worker" ? published.complete : published.scan.complete,
+ false,
+ );
+ });
+ }
+ }
+
+ 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 }] }));
@@ -1688,11 +2174,14 @@ for (const layout of ["standard", "diff", "worker"] as const) {
f.root,
layout === "worker" ? "result.json" : "scan-manifest.json",
);
- assert.notEqual(
+ assert.equal(
layout === "worker" ? published.complete : published.scan.complete,
false,
);
- assert.deepEqual((await f.read()).deferred, []);
+ const pending = (await f.read()).deferred;
+ assert.deepEqual(pending, [{ id: "late", ...generic }]);
+ await f.write(f.draft({}, true));
+ assert.deepEqual((await f.read()).deferred, pending);
});
for (const reverse of [false, true]) {
@@ -1828,3 +2317,250 @@ for (const layout of ["standard", "diff", "worker"] as const) {
}
}
}
+
+for (const layout of ["standard", "diff", "worker"] as const) {
+ for (const linkedById of [false, true]) {
+ for (const otherPending of [false, true]) {
+ test(`${layout}: newly deferred work reopens reviewed surface id=${linkedById} otherPending=${otherPending}`, async (t) => {
+ const f = await fixture(t, layout);
+ const surface = {
+ id: "api",
+ label: "API",
+ disposition: "no_issue_found",
+ };
+ const other = {
+ id: "independent",
+ kind: "generic",
+ reason: "Independent work remains.",
+ };
+ await f.write(
+ f.draft(
+ { surfaces: [surface], deferred: otherPending ? [other] : [] },
+ true,
+ ),
+ );
+ const next = {
+ id: linkedById ? "api" : "new-review",
+ kind: "generic",
+ reason: "Review the new caller.",
+ ...(linkedById ? {} : { surfaceIds: ["api"] }),
+ };
+ const progress = f.draft({
+ surfaces: [{ ...surface, disposition: "needs_follow_up" }],
+ deferred: [next],
+ });
+ for (const input of [progress, f.draft()]) {
+ const result = await f.write(input);
+ assert.equal(
+ result.coverage.surfaces.find(
+ ({ id }: { id: string }) => id === surface.id,
+ ).disposition,
+ "needs_follow_up",
+ );
+ assert.ok(
+ result.coverage.deferred.some(
+ ({ id }: { id: string }) => id === next.id,
+ ),
+ );
+ assert.equal(
+ result.coverage.deferred.some(
+ ({ id }: { id: string }) => id === other.id,
+ ),
+ otherPending,
+ );
+ assert.equal(result.coverage.completeness, undefined);
+ const document = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "scan-manifest.json",
+ );
+ assert.equal(
+ layout === "worker" ? document.complete : document.scan.complete,
+ false,
+ );
+ }
+ });
+ }
+ }
+}
+
+for (const layout of ["standard", "diff", "worker"] as const) {
+ for (const malformed of ["sourceFindingIds", "sourceFindings", "none"]) {
+ test(`${layout}: deferred provenance promotion ${malformed}`, async (t) => {
+ const f = await fixture(t, layout);
+ const source = {
+ id: "source-1",
+ finding: { summary: "Original source." },
+ };
+ const old = findingFor("review");
+ Object.assign(old.provenance, {
+ sourceFindingIds:
+ malformed === "sourceFindingIds" ? [null] : ["source-1"],
+ sourceFindings:
+ malformed === "sourceFindings"
+ ? [{ id: "source-1", finding: null }]
+ : [source],
+ originalCandidates: [null, { original: "candidate" }],
+ });
+ await f.write(
+ f.draft({
+ 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] };
+ await f.write(input);
+ await f.write(input);
+ const saved = await readJson(
+ f.root,
+ layout === "worker" ? "result.json" : "findings.json",
+ );
+ assert.equal(saved.findings.length, 1);
+ const provenance = saved.findings[0].provenance;
+ for (const field of ["sourceFindingIds", "sourceFindings"] as const) {
+ if (malformed === field) {
+ assert.equal(provenance[field], undefined);
+ assert.ok(
+ (provenance.previousFindings as FixtureFinding[]).some((row) =>
+ isDeepStrictEqual(row.provenance[field], old.provenance[field]),
+ ),
+ );
+ } else assert.deepEqual(provenance[field], old.provenance[field]);
+ }
+ assert.deepEqual(provenance.originalCandidates, [
+ null,
+ { original: "candidate" },
+ ]);
+ const parent = layout === "worker" ? await fixture(t, "deep") : f;
+ if (layout === "worker")
+ await parent.write({
+ ...parent.draft({}, true),
+ findings: saved.findings,
+ });
+ const manifestPath = path.join(parent.root, "scan-manifest.json");
+ const manifest = await readJson(manifestPath);
+ Object.assign(manifest.scan, {
+ id: parent.context.scanId,
+ producer: { name: "codex-security-plugin", version: "0.1.0" },
+ status: "completed",
+ startedAt: "2026-05-31T18:00:00Z",
+ completedAt: "2026-05-31T18:09:00Z",
+ });
+ await writeFile(manifestPath, JSON.stringify(manifest));
+ for (const file of ["findings.json", "coverage.json"]) {
+ const document = await readJson(parent.root, file);
+ document.scanId = parent.context.scanId;
+ await writeFile(path.join(parent.root, file), JSON.stringify(document));
+ }
+ await execFileAsync(process.env.PYTHON?.trim() || "python3", [
+ fileURLToPath(
+ new URL("../../scripts/finalize_scan_contract.py", import.meta.url),
+ ),
+ "--scan-dir",
+ parent.root,
+ ]);
+ assert.equal(
+ JSON.parse(
+ await readFile(path.join(parent.root, "findings.json"), "utf8"),
+ ).findings.length,
+ 1,
+ );
+ });
+ }
+}
+
+for (const additional of ["none", "surface", "task", "completed-surface"]) {
+ test(`worker: resolved linked candidate replay preserves completion (${additional})`, async (t) => {
+ const f = await fixture(t, "worker");
+ const surface = {
+ id: "api",
+ label: "API",
+ disposition: "needs_follow_up",
+ receiptRefs: [],
+ };
+ const progress = f.draft({
+ surfaces: [surface],
+ deferred: [
+ {
+ id: "review",
+ candidateId: "candidate-review",
+ surfaceIds: [surface.id],
+ reason: "Review candidate.",
+ },
+ ],
+ });
+ await f.write(progress);
+ await f.write({
+ ...f.draft({}, true),
+ findings: [findingFor("candidate-review")],
+ });
+ const { importSource } = await import("./import-module.ts");
+ const { validateDiscoveryArtifacts } = await importSource(
+ "../src/deep-scan/artifact-validation.ts",
+ { absWorkingDir: import.meta.dirname },
+ );
+ const validate = () =>
+ validateDiscoveryArtifacts(
+ { workersRoot: f.root },
+ path.join(f.root, "result.json"),
+ f.context.scanId,
+ );
+ await validate();
+ if (additional === "surface")
+ (progress.coverage.surfaces as Record<string, unknown>[]).push({
+ id: "independent",
+ label: "Independent review",
+ disposition: "needs_follow_up",
+ });
+ if (additional === "task")
+ (progress.coverage.deferred as Record<string, unknown>[]).push({
+ id: "independent",
+ surfaceIds: [surface.id],
+ reason: "Independent review remains.",
+ });
+ if (additional === "completed-surface") {
+ Object.assign(
+ (progress.coverage.surfaces as Record<string, unknown>[])[0],
+ {
+ disposition: "no_issue_found",
+ notes: "Additional completed surface evidence.",
+ },
+ );
+ (progress.coverage.deferred as Record<string, unknown>[]).push({
+ id: "other-task",
+ reason: "Independent review remains.",
+ });
+ }
+ await f.write(progress);
+ const saved = await readJson(f.root, "result.json");
+ assert.equal(saved.complete, additional === "none");
+ assert.equal(saved.findings.length, 1);
+ if (additional === "completed-surface")
+ assert.deepEqual(saved.coverage.surfaces, progress.coverage.surfaces);
+ if (additional === "none") {
+ await validate();
+ assert.ok(
+ !saved.coverage.surfaces.some(
+ (row: Record<string, unknown>) => row.id === surface.id,
+ ),
+ );
+ } else {
+ await assert.rejects(validate(), /only a checkpoint/);
+ assert.ok(
+ saved.coverage.surfaces.some(
+ (row: Record<string, unknown>) =>
+ row.id === (additional === "surface" ? "independent" : surface.id),
+ ),
+ );
+ }
+ });
+}
diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_identity.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_identity.ts
new file mode 100644
index 000000000..80f4df041
--- /dev/null
+++ b/plugins/codex-security/mcp-app/tests/test_artifact_scan_identity.ts
@@ -0,0 +1,4006 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import {
+ readFile,
+ writeFile,
+ mkdir,
+ utimes,
+ readdir,
+ rm,
+} from "node:fs/promises";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import {
+ draftApi,
+ draftFixture,
+ fixture,
+ interruptDraftWrite,
+} from "./scan-draft-recovery-fixture.ts";
+
+import {
+ type FixtureFinding,
+ type RecoveredFinding,
+ type DraftFixture,
+ finding,
+ recoverAndFinalize,
+ dateDraftFiles,
+} from "./scan-identity-recovery-fixture.ts";
+
+const execFileAsync = promisify(execFile);
+const variants = {
+ provenance: [
+ finding("Synthetic review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ }),
+ ],
+ extension: [
+ finding("Synthetic review", { extensions: { candidateId: "candidate-1" } }),
+ ],
+ unicode: [
+ finding("Café review", {
+ provenance: { source: "local_plugin", candidateId: "Évidence /réview._" },
+ }),
+ ],
+ title: [finding("Café /réview._")],
+ siblings: ["First review", "Second review"].map((title) =>
+ finding(title, {
+ provenance: { source: "local_plugin", candidateId: "shared-candidate" },
+ }),
+ ),
+ report: [
+ finding("Synthetic review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ extensions: { reportId: "Synthetic Report" },
+ }),
+ ],
+ ledger: [
+ finding("Synthetic review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ extensions: { ledgerRowId: "Synthetic Ledger" },
+ }),
+ ],
+ "no candidate siblings": [finding("First review"), finding("Second review")],
+ "shared ledger": ["First review", "Second review"].map((title) =>
+ finding(title, { extensions: { ledgerRowId: "shared-ledger" } }),
+ ),
+};
+
+for (const variant of [
+ "primary location",
+ "primary range",
+ "additional locations",
+] 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 workerRoot = path.join(normal.root, "worker");
+ const interruptedRoot = path.join(recovered.root, "worker");
+ await Promise.all([mkdir(workerRoot), mkdir(interruptedRoot)]);
+ const worker = draftFixture(workerRoot, "worker");
+ const interrupted = draftFixture(interruptedRoot, "worker");
+ const locations = [
+ { path: "src/first.py", startLine: 1 },
+ { path: "src/second.py", startLine: 2 },
+ { path: "src/third.py", startLine: 3 },
+ ];
+ const rows = [
+ finding("First synthetic review", {
+ summary: "First synthetic evidence.",
+ locations,
+ }),
+ finding("Second synthetic review", {
+ summary: "Second synthetic evidence.",
+ locations:
+ variant === "primary location"
+ ? [locations[1], locations[0], locations[2]]
+ : variant === "primary range"
+ ? [{ ...locations[0], endLine: 1 }, ...locations.slice(1)]
+ : [locations[0], locations[2], locations[1]],
+ }),
+ ];
+ if (reversed) rows.reverse();
+ for (const target of [worker, interrupted]) {
+ await target.write({ ...target.draft(), findings: [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" },
+ })),
+ });
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [
+ {
+ id: "worker",
+ kind: "discovery",
+ 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);
+ const reports = (findings: RecoveredFinding[]) =>
+ new Map(
+ findings.map((row) => [
+ row.summary,
+ {
+ identity: row.identity,
+ findingId: row.findingId,
+ occurrenceId: row.occurrenceId,
+ locations: row.locations,
+ history: (
+ row.evidenceProvenance as { previousFindings: FixtureFinding[] }
+ ).previousFindings.map((previous) => ({
+ title: previous.title,
+ summary: previous.summary,
+ locations: previous.locations,
+ })),
+ },
+ ]),
+ );
+ const published = reports(result.normal);
+ for (const report of published.values()) {
+ assert.deepEqual(
+ report.history,
+ variant === "additional locations"
+ ? [
+ {
+ title: rows[0]!.title,
+ summary: rows[0]!.summary,
+ locations: rows[0]!.locations,
+ },
+ ]
+ : [],
+ );
+ }
+ assert.deepEqual(reports(result.recovered), published);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+for (const kind of ["object", "array", "string"] as const) {
+ test(`unchanged worker drafts preserve ${kind} owner metadata`, async (t) => {
+ const worker = await fixture(t, "worker");
+ const findings = ["first", "second"].map((id) =>
+ finding("Synthetic review", {
+ provenance: {
+ source: "local_plugin",
+ candidateId: "shared-candidate",
+ workerId: kind === "object" ? { id } : kind === "array" ? [id] : id,
+ },
+ }),
+ );
+ 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"),
+ );
+ assert.deepEqual(saved.findings, findings);
+ }
+ });
+}
+
+for (const observations of [
+ [1, true],
+ [true, 1],
+ [0, false],
+ [false, 0],
+ [1, 2],
+ [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 workerRoot = path.join(normal.root, "worker");
+ const interruptedRoot = path.join(recovered.root, "worker");
+ await Promise.all([mkdir(workerRoot), mkdir(interruptedRoot)]);
+ const worker = draftFixture(workerRoot, "worker");
+ const interrupted = draftFixture(interruptedRoot, "worker");
+ const findings = observations.map((value) =>
+ finding("Synthetic review", {
+ extensions: { observations: [{ value }] },
+ }),
+ );
+ for (const [index, rows] of [findings, [...findings].reverse()].entries()) {
+ const snapshot = { ...worker.draft(), findings: rows };
+ await worker.write(snapshot);
+ if (
+ index === 1 &&
+ observations.every((value) => typeof value === "number")
+ ) {
+ const contents = (JSON.stringify(snapshot, null, 2) + "\n").replace(
+ /"value": (\d+)/g,
+ (_, value: string) =>
+ `"value": ${value === "0" ? "-0.0" : `${value}.0`}`,
+ );
+ const name =
+ createHash("sha256").update(contents).digest("hex") + ".json";
+ await writeFile(
+ path.join(interruptedRoot, "checkpoints", name),
+ contents,
+ );
+ } else {
+ await draftApi.saveScanDraftCheckpoint(
+ interrupted.context,
+ snapshot,
+ false,
+ );
+ }
+ 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 result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [
+ {
+ id: "worker",
+ kind: "discovery",
+ artifact_dir: interruptedRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ],
+ true,
+ true,
+ );
+ const identitiesByEvidence = (rows: RecoveredFinding[]) =>
+ new Map(
+ rows.map((row) => [
+ JSON.stringify(
+ (row.candidateMetadata as { extensions: unknown }).extensions,
+ ),
+ {
+ identity: row.identity,
+ findingId: row.findingId,
+ occurrenceId: row.occurrenceId,
+ },
+ ]),
+ );
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ assert.deepEqual(
+ identitiesByEvidence(result.recovered),
+ identitiesByEvidence(result.normal),
+ );
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+for (const [label, metadata, count] of [
+ ["absent", {}, 2],
+ ["ASCII blank", { provenance: { candidateId: " \t" } }, 2],
+ ["BOM provenance", { provenance: { candidateId: "\ufeff" } }, 2],
+ ["BOM extension", { extensions: { candidateId: "\ufeff" } }, 2],
+ ["BOM report", { extensions: { reportId: "\ufeff" } }, 2],
+ ["BOM ledger", { extensions: { ledgerRowId: "\ufeff" } }, 2],
+ ["candidate", { provenance: { candidateId: "candidate-1" } }, 1],
+ ["next line", { provenance: { candidateId: "\u0085" } }, 1],
+ ["separator", { provenance: { candidateId: "\u001c" } }, 1],
+ [
+ "extension fallback",
+ {
+ provenance: { candidateId: "\ufeff" },
+ extensions: { candidateId: "candidate-1" },
+ },
+ 1,
+ ],
+ [
+ "report fallback",
+ { extensions: { candidateId: "\ufeff", reportId: "report-1" } },
+ 1,
+ ],
+ [
+ "ledger fallback",
+ { extensions: { reportId: "\ufeff", ledgerRowId: "ledger-1" } },
+ 1,
+ ],
+] as const) {
+ test(`candidate selection retains moved evidence for ${label}`, async (t) => {
+ const normal = await fixture(t, "standard"),
+ recovered = await fixture(t, "standard");
+ for (const [index, location] of [
+ "src/first.py",
+ "src/second.py",
+ ].entries()) {
+ const row = finding("Synthetic review", {
+ ...metadata,
+ summary: `Synthetic evidence at ${location}`,
+ locations: [{ path: location, startLine: 1 }],
+ provenance: {
+ source: "local_plugin",
+ ...("provenance" in metadata ? metadata.provenance : {}),
+ },
+ });
+ await normal.write({ ...normal.draft(), findings: [row] });
+ await draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ { ...recovered.draft(), findings: [row] },
+ false,
+ );
+ if (index === 0) await dateDraftFiles(recovered.root, 100);
+ }
+ const result = await recoverAndFinalize(normal, recovered, [], true, true);
+ const byLocation = (rows: RecoveredFinding[]) =>
+ new Map(rows.map((row) => [row.locations[0]!.path, row]));
+ assert.equal(result.normal.length, count);
+ assert.equal(result.recovered.length, count);
+ assert.deepEqual(byLocation(result.recovered), byLocation(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+for (const layout of ["standard", "diff", "deep"] as const) {
+ for (const [label, candidateId] of Object.entries({
+ bom: "\ufeff",
+ nextLine: "\u0085",
+ controlSeparators: "\u001c\u001f",
+ spaces: " \u00a0\u2003\u3000",
+ })) {
+ test(`${layout}: ${label} candidate metadata matches recovered identity`, async (t) => {
+ const normal = await fixture(t, layout);
+ const recovered = await fixture(t, layout);
+ const findings = [
+ finding("Synthetic review", {
+ 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,
+ );
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+for (const layout of ["standard", "diff", "deep"] as const) {
+ for (const observations of [
+ [true, 1],
+ [false, 0],
+ [1, 2],
+ [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 initial = observations.map((value) =>
+ finding("Synthetic review", {
+ extensions: { observation: { value } },
+ }),
+ );
+ for (const target of [normal, recovered]) {
+ await target.write({ ...target.draft(), findings: initial });
+ await dateDraftFiles(target.root, 100);
+ }
+ const findings = [...initial].reverse();
+ await normal.write({ ...normal.draft(), findings });
+ const snapshot = { ...recovered.draft(), findings };
+ if (typeof observations[0] === "boolean") {
+ await draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ snapshot,
+ false,
+ );
+ } else {
+ // Imported JSON can spell the same numbers differently than JSON.stringify.
+ const contents = (JSON.stringify(snapshot, null, 2) + "\n").replace(
+ /"value": (\d+)/g,
+ (_, value: string) =>
+ `"value": ${value === "0" ? "-0.0" : `${value}.0`}`,
+ );
+ const name =
+ createHash("sha256").update(contents).digest("hex") + ".json";
+ await writeFile(
+ path.join(recovered.root, "checkpoints", name),
+ contents,
+ );
+ }
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ const byId = (left: RecoveredFinding, right: RecoveredFinding) =>
+ left.findingId.localeCompare(right.findingId);
+ assert.deepEqual(result.recovered.sort(byId), result.normal.sort(byId));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+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);
+ assert.equal(result.normal.length, findings.length);
+ assert.equal(result.recovered.length, findings.length);
+ assert.deepEqual(result.warnings, []);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+ }
+}
+
+const terminalDraftCases: Array<{
+ variant: string;
+ expectedCount: number;
+ observation?: [unknown, unknown];
+}> = [
+ { variant: "candidate", expectedCount: 1 },
+ { variant: "report", expectedCount: 1 },
+ { variant: "ledger", expectedCount: 1 },
+ { variant: "metadata", expectedCount: 1 },
+ { variant: "moved", expectedCount: 2 },
+ { variant: "true-to-number", expectedCount: 2, observation: [true, 1] },
+ { variant: "false-to-number", expectedCount: 2, observation: [false, 0] },
+ { variant: "number-to-true", expectedCount: 2, observation: [1, true] },
+ { variant: "same-boolean", expectedCount: 1, observation: [true, true] },
+ { variant: "same-number", expectedCount: 1, observation: [1, 1.0] },
+ {
+ variant: "different-string",
+ expectedCount: 2,
+ observation: ["old", "new"],
+ },
+];
+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 workerRoot = path.join(normal.root, "worker");
+ const interruptedRoot = path.join(recovered.root, "worker");
+ await Promise.all([mkdir(workerRoot), mkdir(interruptedRoot)]);
+ const worker = draftFixture(workerRoot, "worker");
+ const interrupted = draftFixture(interruptedRoot, "worker");
+ const plain = finding(
+ "Synthetic review",
+ observation
+ ? { extensions: { observation: { value: observation[0] } } }
+ : {},
+ );
+ const enriched = finding("Synthetic review", {
+ ...(variant === "candidate" || variant === "metadata"
+ ? { provenance: { source: "local_plugin", candidateId: "candidate-1" } }
+ : {}),
+ ...(variant === "candidate"
+ ? {}
+ : {
+ extensions: {
+ [variant === "ledger" ? "ledgerRowId" : "reportId"]: "report-1",
+ ...(observation
+ ? {
+ observation: {
+ value: observation[1],
+ note: "Additional synthetic observation.",
+ },
+ }
+ : {}),
+ },
+ }),
+ });
+ const initial =
+ variant === "metadata" || variant === "moved" || observation
+ ? [enriched, plain]
+ : [enriched, enriched];
+ const latest =
+ variant === "moved"
+ ? [
+ { ...plain, locations: [{ path: "src/example.py", startLine: 2 }] },
+ enriched,
+ ]
+ : [enriched];
+ for (const target of [worker, interrupted]) {
+ await target.write({ ...target.draft({}, true), findings: initial });
+ 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 normal.write({
+ ...normal.draft({}, true),
+ findings: published.findings.map((row: FixtureFinding) => ({
+ ...row,
+ provenance: { ...row.provenance, workerId: "worker" },
+ })),
+ });
+ const sourceBytes = new Map(
+ await Promise.all(
+ (await readdir(interrupted.root, { recursive: true }))
+ .filter((name) => name.endsWith(".json"))
+ .map(
+ async (name) =>
+ [
+ name,
+ await readFile(path.join(interrupted.root, name)),
+ ] as const,
+ ),
+ ),
+ );
+ const finalized = await recoverAndFinalize(
+ normal,
+ recovered,
+ [
+ {
+ id: "worker",
+ kind: "discovery",
+ artifact_dir: interrupted.root,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ],
+ true,
+ true,
+ );
+ assert.equal(finalized.normal.length, expectedCount);
+ assert.equal(finalized.recovered.length, expectedCount);
+ const byId = (left: RecoveredFinding, right: RecoveredFinding) =>
+ left.findingId.localeCompare(right.findingId);
+ assert.deepEqual(
+ finalized.recovered.sort(byId),
+ finalized.normal.sort(byId),
+ );
+ assert.deepEqual(finalized.warnings, []);
+ for (const [name, bytes] of sourceBytes) {
+ assert.deepEqual(
+ await readFile(path.join(interrupted.root, name)),
+ bytes,
+ );
+ }
+ });
+}
+
+for (const layout of ["standard", "diff", "worker"] as const) {
+ test(`${layout}: adding candidate metadata preserves a report-backed finding`, async (t) => {
+ const f = await fixture(t, layout);
+ 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",
+ ),
+ );
+ assert.equal(saved.findings.length, 1);
+ assert.equal(saved.findings[0].provenance.candidateId, "candidate-1");
+ });
+}
+
+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);
+ for (const f of [normal, recovered])
+ await f.write({ ...f.draft(), findings: variants.siblings });
+ const destination = path.join(recovered.root, "findings.json");
+ const document = JSON.parse(await readFile(destination, "utf8"));
+ for (const row of document.findings) delete row.identity;
+ await writeFile(destination, JSON.stringify(document));
+ const result = await recoverAndFinalize(normal, recovered);
+ assert.equal(result.recovered.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+}
+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);
+ 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 interruptDraftWrite(path.join(recovered.root, "findings.json"), () =>
+ recovered.write({ ...recovered.draft(), findings: variants.siblings }),
+ );
+ const result = await recoverAndFinalize(normal, recovered);
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ for (const metadata of ["provenance", "extensions"] 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 first = finding(
+ "Synthetic report",
+ reported
+ ? {
+ extensions: { reportId: "report-1" },
+ }
+ : {},
+ );
+ const second = {
+ ...first,
+ [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,
+ );
+ else
+ await interruptDraftWrite(
+ path.join(recovered.root, "findings.json"),
+ () => recovered.write(input),
+ );
+ }
+ const result = await recoverAndFinalize(normal, recovered, [], true);
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+ }
+}
+
+for (const variant of [
+ "different titles",
+ "same title",
+ "normalized aliases",
+ "authored anchor",
+ "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 workers = [];
+ const findings = [];
+ for (const [index, id] of ["reviewer-a", "reviewer-b"].entries()) {
+ const root = path.join(recovered.root, id);
+ await mkdir(root);
+ const worker = draftFixture(root, "worker");
+ const value = finding(
+ variant === "same title" || index === 0
+ ? "First review"
+ : "Second review",
+ {
+ provenance: {
+ source: "local_plugin",
+ candidateId:
+ variant === "normalized aliases"
+ ? index === 0
+ ? "Case"
+ : "Caſe"
+ : "candidate-1",
+ },
+ },
+ );
+ 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"),
+ );
+ if (variant === "rejected sibling" && index === 1) {
+ await worker.write(
+ worker.draft(
+ {
+ 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 },
+ })),
+ );
+ }
+ workers.push({
+ id,
+ kind: "discovery",
+ artifact_dir: root,
+ result_manifest_path: null,
+ attempt: 1,
+ });
+ }
+ await normal.write({ ...normal.draft(), findings });
+ const result = await recoverAndFinalize(normal, recovered, workers);
+ assert.equal(result.normal.length, variant === "rejected sibling" ? 1 : 2);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+for (const [kind, metadata, identifier] of [
+ ["candidate aliases", "provenance"],
+ ["report enrichment", "extensions", "reportId"],
+ ["report enrichment", "extensions", "ledgerRowId"],
+ ...[undefined, "reportId", "ledgerRowId"].flatMap((identifier) =>
+ ["provenance", "extensions"].map((metadata) => [
+ "candidate enrichment",
+ metadata,
+ identifier,
+ ]),
+ ),
+]) {
+ 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 normalRoot = path.join(normal.root, "reviewer");
+ const recoveryRoot = path.join(recovered.root, "reviewer");
+ await mkdir(normalRoot);
+ await mkdir(recoveryRoot);
+ const publishedWorker = draftFixture(normalRoot, "worker");
+ const interruptedWorker = draftFixture(recoveryRoot, "worker");
+ const first = finding("First review", {
+ ...(kind === "candidate enrichment"
+ ? {}
+ : {
+ provenance: {
+ source: "local_plugin",
+ candidateId:
+ kind === "candidate aliases" ? "CASE" : "candidate-1",
+ },
+ }),
+ ...(kind === "candidate enrichment" && identifier
+ ? { extensions: { [identifier!]: "report-1" } }
+ : {}),
+ });
+ const second = structuredClone(first);
+ if (kind === "candidate aliases") {
+ second.title = "Second review";
+ second.provenance.candidateId = "case";
+ } else if (kind === "report enrichment") {
+ second.extensions = { [identifier!]: "report-1" };
+ } else {
+ second[metadata!] = {
+ ...(second[metadata!] as Record<string, unknown>),
+ candidateId: "candidate-1",
+ };
+ }
+ 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 normal.write({
+ ...normal.draft(),
+ findings: result.findings.map((row: FixtureFinding) => ({
+ ...row,
+ provenance: { ...row.provenance, workerId: "reviewer" },
+ })),
+ });
+ const comparison = await recoverAndFinalize(normal, recovered, [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: recoveryRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ]);
+ assert.equal(
+ comparison.normal.length,
+ kind === "candidate aliases" ? 2 : 1,
+ );
+ const byTitle = (left: FixtureFinding, right: FixtureFinding) =>
+ left.title.localeCompare(right.title);
+ assert.deepEqual(
+ comparison.recovered.sort(byTitle),
+ comparison.normal.sort(byTitle),
+ );
+ assert.deepEqual(comparison.warnings, []);
+ });
+}
+
+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 first = finding("First review", {
+ provenance: { source: "local_plugin", candidateId: "shared-candidate" },
+ });
+ const second = {
+ ...first,
+ title: "Second review",
+ 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,
+ );
+ }
+ const result = await recoverAndFinalize(normal, recovered);
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+for (const variant of [
+ "unchanged",
+ "candidate-collision",
+ "no-candidate-enrichment",
+ "no-sibling",
+] 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 nwroot = path.join(normal.root, "reviewer"),
+ rwroot = path.join(recovered.root, "reviewer");
+ await mkdir(nwroot);
+ await mkdir(rwroot);
+ const nw = draftFixture(nwroot, "worker"),
+ rw = draftFixture(rwroot, "worker");
+ const first = finding("First review", {
+ identity: { anchor: "authored-review" },
+ });
+ const sibling = finding("Second review", {
+ provenance: { source: "local_plugin", candidateId: "shared-review" },
+ locations: [{ path: "src/other.py", startLine: 2 }],
+ });
+ const withSibling = variant !== "unchanged" && variant !== "no-sibling";
+ const ordered = (current: FixtureFinding) => {
+ const rows = withSibling ? [current, sibling] : [current];
+ return reversed ? rows.toReversed() : rows;
+ };
+ const second = {
+ ...first,
+ ...(variant === "unchanged"
+ ? {}
+ : { title: "Revised first review", summary: "Revised evidence." }),
+ provenance: {
+ ...first.provenance,
+ ...(variant === "no-candidate-enrichment"
+ ? {}
+ : { 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, [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: rwroot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ]);
+ assert.equal(comparison.normal.length, withSibling ? 2 : 1);
+ assert.deepEqual(comparison.recovered, comparison.normal);
+ assert.deepEqual(comparison.warnings, []);
+ assert.deepEqual(
+ comparison.normal.map((row) => row.title).sort(),
+ ordered(second)
+ .map((row) => row.title)
+ .sort(),
+ );
+ const revised = result.findings.find(
+ (row: FixtureFinding) => row.title === second.title,
+ );
+ assert.deepEqual(revised.identity, first.identity);
+ if (variant !== "unchanged") {
+ assert.deepEqual(revised.provenance.previousFindings, [first]);
+ }
+ if (withSibling) {
+ assert.deepEqual(
+ result.findings.find(
+ (row: FixtureFinding) => row.title === sibling.title,
+ ),
+ sibling,
+ );
+ }
+ });
+ }
+}
+
+for (const layout of ["standard", "diff", "worker"] as const) {
+ for (const variant of [
+ "reportId",
+ "ledgerRowId",
+ "metadata enrichment",
+ "authored identity",
+ "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);
+ let normalSource = normal,
+ recoveredSource = recovered;
+ const workers = [];
+ if (layout === "worker") {
+ for (const f of [normal, recovered])
+ await mkdir(path.join(f.root, "reviewer"));
+ normalSource = draftFixture(
+ path.join(normal.root, "reviewer"),
+ "worker",
+ );
+ recoveredSource = draftFixture(
+ path.join(recovered.root, "reviewer"),
+ "worker",
+ );
+ workers.push({
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: recoveredSource.root,
+ result_manifest_path: null,
+ attempt: 1,
+ });
+ }
+ const first = finding("First review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ });
+ let second = structuredClone(first);
+ if (["reportId", "ledgerRowId", "authored identity"].includes(variant)) {
+ const field = variant === "authored identity" ? "reportId" : variant;
+ first.extensions = { [field]: "report-1" };
+ second.extensions = { [field]: "report-2" };
+ }
+ if (variant === "metadata enrichment")
+ second.extensions = { reportId: "report-1" };
+ if (variant === "authored identity") {
+ first.identity = { anchor: "authored-review" };
+ second.identity = { anchor: "authored-review" };
+ }
+ if (variant === "retained sibling") second.title = "Second review";
+ 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,
+ );
+ 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 result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ variant === "metadata enrichment",
+ );
+ const count = ["metadata enrichment", "authored identity"].includes(
+ variant,
+ )
+ ? 1
+ : 2;
+ assert.equal(result.normal.length, count);
+ assert.equal(result.recovered.length, count);
+ if (variant === "retained sibling")
+ assert.deepEqual(result.normal.map((row) => row.title).sort(), [
+ "First review",
+ "Second review",
+ ]);
+ const ordered = (rows: RecoveredFinding[]) =>
+ rows.sort((left, right) =>
+ left.findingId.localeCompare(right.findingId),
+ );
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+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 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] });
+ const dest = path.join(recovered.root, "findings.json");
+ const doc = JSON.parse(await readFile(dest, "utf8"));
+ 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);
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+ }
+
+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 one = finding("Synthetic review", {
+ [metadata]: {
+ ...(metadata === "provenance" ? { source: "local_plugin" } : {}),
+ candidateId: "candidate-1",
+ },
+ });
+ const two = {
+ ...one,
+ [metadata]: { ...one[metadata], candidateId: "candidate-2" },
+ };
+ await normal.write({ ...normal.draft(), findings: [one, two] });
+ await recovered.write({ ...recovered.draft(), findings: [one] });
+ const dest = path.join(recovered.root, "findings.json");
+ const doc = JSON.parse(await readFile(dest, "utf8"));
+ 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);
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+ }
+
+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 first = finding("Synthetic ownership review", {
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ workerId: "worker-a",
+ },
+ });
+ const second = {
+ ...structuredClone(first),
+ identity: { anchor: "authored-worker-b" },
+ 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,
+ );
+ }
+ const result = await recoverAndFinalize(normal, recovered);
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ assert.deepEqual(result.warnings, []);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+ for (const [field, blank] of [
+ ["reportId", " "],
+ ["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 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,
+ );
+ }
+ const result = await recoverAndFinalize(normal, recovered);
+ assert.equal(result.normal.length, 1);
+ assert.equal(result.recovered.length, 1);
+ assert.deepEqual(result.warnings, []);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+ }
+}
+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 normalRoot = path.join(normal.root, "reviewer");
+ const recoveredRoot = path.join(recovered.root, "reviewer");
+ await mkdir(normalRoot);
+ await mkdir(recoveredRoot);
+ const normalWorker = draftFixture(normalRoot, "worker");
+ const recoveredWorker = draftFixture(recoveredRoot, "worker");
+ const first = finding("Synthetic worker review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ extensions: { [field]: " \t " },
+ });
+ 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,
+ );
+ }
+ 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, [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: recoveredRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ]);
+ assert.equal(result.normal.length, 1);
+ assert.equal(result.recovered.length, 1);
+ assert.deepEqual(result.warnings, []);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+}
+
+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 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,
+ );
+ }
+ const result = await recoverAndFinalize(normal, recovered);
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(
+ [...result.recovered].sort((a, b) =>
+ a.identity.anchor.localeCompare(b.identity.anchor),
+ ),
+ [...result.normal].sort((a, b) =>
+ a.identity.anchor.localeCompare(b.identity.anchor),
+ ),
+ );
+ });
+ for (const metadata of [
+ { id: "synthetic-worker" },
+ ["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 value = finding("Synthetic review", {
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ workerId: metadata,
+ },
+ });
+ for (const f of [normal, recovered])
+ await f.write({ ...f.draft(), findings: [value] });
+ const result = await recoverAndFinalize(normal, recovered);
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.recovered[0].workerMetadata, metadata);
+ });
+ }
+}
+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 first = finding("First review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ ...(shape === "shared ledger"
+ ? { extensions: { ledgerRowId: "ledger-1" } }
+ : {}),
+ });
+ const second = { ...structuredClone(first), title: "Second review" };
+ const snapshots =
+ shape === "summary revision"
+ ? [
+ [first, second],
+ [{ ...first, summary: "Revised evidence." }, second],
+ ]
+ : [[first, second]];
+ for (const findings of snapshots) {
+ await normal.write({ ...normal.draft(), findings });
+ await draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ { ...recovered.draft(), findings },
+ false,
+ );
+ }
+ const result = await recoverAndFinalize(normal, recovered, [], true);
+
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, result.normal.length);
+ assert.deepEqual(result.warnings, []);
+ const ordered = (rows: RecoveredFinding[]) =>
+ [...rows].sort((a, b) => a.findingId.localeCompare(b.findingId));
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ });
+ }
+}
+
+test("deep: refined candidate retains independent cross-location report", async (t) => {
+ const normal = await fixture(t, "deep");
+ const recovered = await fixture(t, "deep");
+ const normalRoot = path.join(normal.root, "reviewer");
+ const recoveredRoot = path.join(recovered.root, "reviewer");
+ await mkdir(normalRoot);
+ await mkdir(recoveredRoot);
+ const normalWorker = draftFixture(normalRoot, "worker");
+ const recoveredWorker = draftFixture(recoveredRoot, "worker");
+ const first = finding("First review", {
+ severity: { level: "high" },
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ });
+ const refined = {
+ ...first,
+ locations: [{ path: "src/example.py", startLine: 2 }],
+ };
+ const second = {
+ ...structuredClone(first),
+ title: "Second review",
+ summary: "Independent evidence.",
+ severity: { level: "low" },
+ };
+ for (const findings of [[first], [refined, second]]) {
+ await normalWorker.write({ ...normalWorker.draft(), findings });
+ await draftApi.saveScanDraftCheckpoint(
+ recoveredWorker.context,
+ { ...recoveredWorker.draft(), findings },
+ false,
+ );
+ }
+ 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,
+ [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: recoveredRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ],
+ true,
+ );
+
+ assert.ok(result.recovered.some((row) => row.title === "Second review"));
+ assert.equal(result.normal.length, 3);
+ assert.equal(result.recovered.length, 3);
+ assert.deepEqual(result.warnings, []);
+ const ordered = (rows: RecoveredFinding[]) =>
+ [...rows].sort((a, b) => a.findingId.localeCompare(b.findingId));
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+});
+for (const layout of ["standard", "diff"] as const) {
+ test(`${layout}: revised sibling publication completes with unique identities`, async (t) => {
+ const f = await fixture(t, layout);
+ const first = finding("First review", {
+ 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],
+ });
+ const { stdout } = await execFileAsync(
+ process.env.PYTHON?.trim() || "python3",
+ [
+ "-c",
+ `import json,sys
+from pathlib import Path
+sys.path.insert(0,sys.argv[1])
+from finalize_scan_contract import _prepare_scan_finalization
+root=Path(sys.argv[2])
+documents=tuple(json.loads((root/name).read_text()) for name in ('scan-manifest.json','findings.json','coverage.json'))
+documents[0]['scan'].update(id=sys.argv[3],status='completed',producer={'name':'test','version':'1'},startedAt='2026-05-31T18:00:00Z',completedAt='2026-05-31T18:09:00Z')
+for document in documents[1:]: document['scanId']=sys.argv[3]
+prepared=_prepare_scan_finalization(root,draft_documents=documents)
+print(len(prepared.findings['findings']))`,
+ fileURLToPath(new URL("../../scripts", import.meta.url)),
+ f.root,
+ f.context.scanId!,
+ ],
+ );
+ assert.equal(stdout.trim(), "2");
+ });
+}
+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 first = finding("First review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ extensions: { ledgerRowId: "ledger-1" },
+ });
+ 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] });
+ }
+ const result = await recoverAndFinalize(normal, recovered, [], true);
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ assert.deepEqual(result.warnings, []);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+}
+
+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 first = finding("Synthetic ownership review", {
+ identity: { anchor: "authored-review" },
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ });
+ const second = {
+ ...first,
+ 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,
+ );
+ }
+ const result = await recoverAndFinalize(normal, recovered);
+
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+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 first = finding("Synthetic ownership review", {
+ identity: { anchor: "authored-first" },
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ });
+ const owned = {
+ ...first,
+ provenance: { ...first.provenance, workerId: "worker-a" },
+ };
+ const independent = {
+ ...first,
+ identity: { anchor: "authored-second" },
+ 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,
+ );
+ }
+ const result = await recoverAndFinalize(normal, recovered);
+
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+}
+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 workers = [],
+ findings = [];
+ for (const id of ["worker-a", "worker-b"]) {
+ const workerRoot = path.join(recovered.root, id);
+ await mkdir(workerRoot);
+ const worker = draftFixture(workerRoot, "worker");
+ const value = finding("Synthetic bound owner review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ ...(authored ? { identity: { anchor: "authored-review" } } : {}),
+ });
+ for (const row of [
+ value,
+ { ...value, provenance: { ...value.provenance, workerId: id } },
+ ]) {
+ await draftApi.saveScanDraftCheckpoint(
+ worker.context,
+ { ...worker.draft(), findings: [row] },
+ false,
+ );
+ }
+ findings.push({
+ ...value,
+ provenance: { ...value.provenance, workerId: id },
+ });
+ workers.push({
+ id,
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ });
+ }
+ await normal.write({ ...normal.draft(), findings });
+ const result = await recoverAndFinalize(normal, recovered, workers);
+
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+}
+
+const checkpointName = (input: unknown) =>
+ createHash("sha256").update(JSON.stringify(input)).digest("hex") + ".json";
+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 normalRoot = path.join(normal.root, "reviewer"),
+ recoveredRoot = path.join(recovered.root, "reviewer");
+ for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
+ const worker = draftFixture(normalRoot, "worker"),
+ recoveryWorker = draftFixture(recoveredRoot, "worker");
+ const initial = {
+ ...finding("Synthetic review"),
+ summary: "Initial assessment.",
+ severity: { level: initialLevel },
+ };
+ const revised = {
+ ...initial,
+ summary: "Corrected assessment.",
+ severity: { level: "low" },
+ [metadata]: { ...initial[metadata], candidateId: "candidate-1" },
+ };
+ const oldDraft = { ...worker.draft(), findings: [initial] };
+ let newDraft,
+ suffix = 0;
+ do {
+ newDraft = {
+ ...worker.draft(),
+ findings: [revised],
+ threatModel: { summary: `Synthetic checkpoint ${suffix++}.` },
+ };
+ } while (
+ checkpointName(oldDraft) < checkpointName(newDraft) !==
+ (order === "earlier-first")
+ );
+ for (const [index, draft] of [oldDraft, newDraft].entries()) {
+ await worker.write(draft);
+ await draftApi.saveScanDraftCheckpoint(
+ recoveryWorker.context,
+ draft,
+ false,
+ );
+ await utimes(
+ path.join(recoveredRoot, "checkpoints", checkpointName(draft)),
+ 100 + index * 100,
+ 100 + index * 100,
+ );
+ }
+ const saved = JSON.parse(
+ await readFile(path.join(normalRoot, "result.json"), "utf8"),
+ );
+ 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" },
+ })),
+ });
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: recoveredRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ],
+ true,
+ );
+ assert.deepEqual(result.warnings, []);
+ assert.equal(result.recovered.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ });
+ }
+ }
+}
+
+for (const layout of ["standard", "diff", "deep"] as const) {
+ for (const [field, value] of Object.entries({
+ description: "Synthetic annotation",
+ source: "authored",
+ version: 1,
+ })) {
+ 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 authored = finding("First review", {
+ identity: {
+ anchor: "candidate-1",
+ instance: "second-review",
+ [field]: value,
+ },
+ extensions: { candidateId: "candidate-1" },
+ });
+ const generated = finding("Second review", {
+ locations: [{ path: "src/example.py", startLine: 2 }],
+ extensions: { candidateId: "candidate-1" },
+ });
+ const reserved = finding("Reserved review", {
+ identity: {
+ anchor: "candidate-1",
+ instance: "second-review-2",
+ [field]: value,
+ },
+ locations: [{ path: "src/example.py", startLine: 3 }],
+ extensions: { candidateId: "candidate-1" },
+ });
+ 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);
+ assert.equal(result.normal.length, 3);
+ assert.equal(result.recovered.length, 3);
+ assert.deepEqual(result.warnings, []);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(
+ result.recovered.find((row) => row.title === "First review")!
+ .identity,
+ authored.identity,
+ );
+ assert.equal(
+ result.recovered.find((row) => row.title === "Second review")!
+ .identity.instance,
+ "second-review-3",
+ );
+ });
+ }
+ }
+}
+
+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 workers = [],
+ findings = [];
+ for (const [index, id] of ["worker-a", "worker-b"].entries()) {
+ const workerRoot = path.join(recovered.root, id);
+ await mkdir(workerRoot);
+ const worker = draftFixture(workerRoot, "worker");
+ const value = finding(
+ sameTitle
+ ? "Synthetic shared review"
+ : `${index === 0 ? "First" : "Second"} review`,
+ {
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ workerId: "discovery",
+ },
+ },
+ );
+ await worker.write({ ...worker.draft(), findings: [value] });
+ const saved = JSON.parse(
+ await readFile(path.join(workerRoot, "result.json"), "utf8"),
+ );
+ findings.push(...saved.findings);
+ workers.push({
+ id,
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ });
+ }
+ await normal.write({ ...normal.draft(), findings });
+ const result = await recoverAndFinalize(normal, recovered, workers);
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+}
+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 workerRoot = path.join(recovered.root, "worker-a"),
+ normalWorkerRoot = path.join(normal.root, "worker-a");
+ await mkdir(workerRoot);
+ await mkdir(normalWorkerRoot);
+ const worker = draftFixture(workerRoot, "worker"),
+ normalWorker = draftFixture(normalWorkerRoot, "worker");
+ for (const alias of ["discovery", "refined"]) {
+ const value = finding("Synthetic shared review", {
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ workerId: alias,
+ },
+ ...(authored ? { identity: { anchor: "authored-review" } } : {}),
+ });
+ await normalWorker.write({ ...normalWorker.draft(), findings: [value] });
+ await draftApi.saveScanDraftCheckpoint(
+ worker.context,
+ { ...worker.draft(), findings: [value] },
+ false,
+ );
+ }
+ 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",
+ artifact_dir: workerRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ]);
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+const savedWorker = (root: string) => ({
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: root,
+ result_manifest_path: null,
+ attempt: 1,
+});
+
+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 normalRoot = path.join(normal.root, "reviewer"),
+ recoveredRoot = path.join(recovered.root, "reviewer");
+ for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
+ const writer = draftFixture(normalRoot, "worker"),
+ interrupted = draftFixture(recoveredRoot, "worker");
+ const first = finding("First review");
+ first[metadata] = { ...first[metadata], candidateId: "candidate-1" };
+ if (shape === "shared siblings")
+ first.extensions = { ...first.extensions, ledgerRowId: "ledger-1" };
+ const second = { ...structuredClone(first), title: "Second review" };
+ const initial = shape === "shared siblings" ? [first, second] : [first];
+ const revised = {
+ ...(shape === "shared siblings" ? second : first),
+ summary: "Revised evidence.",
+ severity: { level: "high" },
+ ...(shape === "shared siblings"
+ ? {}
+ : {
+ locations: [{ path: "src/example.py", startLine: 1, endLine: 2 }],
+ extensions: { ...first.extensions, [shape]: "report-1" },
+ }),
+ };
+ for (const worker of [writer, interrupted])
+ await worker.write({ ...worker.draft(), findings: initial });
+ await dateDraftFiles(recoveredRoot, 100);
+ const update = { ...writer.draft(), findings: [revised] };
+ await writer.write(update);
+ await draftApi.saveScanDraftCheckpoint(
+ interrupted.context,
+ update,
+ false,
+ );
+ await utimes(
+ path.join(recoveredRoot, "checkpoints", checkpointName(update)),
+ 200,
+ 200,
+ );
+ const saved = JSON.parse(
+ await readFile(path.join(normalRoot, "result.json"), "utf8"),
+ );
+ assert.equal(saved.findings.length, initial.length);
+ 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)],
+ true,
+ true,
+ );
+ const ordered = (rows: RecoveredFinding[]) =>
+ [...rows].sort((a, b) => a.findingId.localeCompare(b.findingId));
+ assert.equal(result.normal.length, initial.length);
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+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 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 dateDraftFiles(recovered.root, 100);
+ const revised = {
+ ...initial,
+ provenance: { ...initial.provenance, workerId: "reviewer" },
+ };
+ const update = { ...normal.draft(), findings: [revised] };
+ await normal.write(update);
+ await draftApi.saveScanDraftCheckpoint(recovered.context, update, false);
+ const { handoffClaimToken: _claim, ...checkpoint } = update;
+ await utimes(
+ path.join(recovered.root, "checkpoints", checkpointName(checkpoint)),
+ 200,
+ 200,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+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 first = finding("Synthetic review");
+ first[metadata] = { ...first[metadata], candidateId: "candidate-1" };
+ const second = {
+ ...structuredClone(first),
+ 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 dateDraftFiles(recovered.root, 100);
+ const update = {
+ ...normal.draft(),
+ findings: [{ ...first, summary: "Revised evidence." }, second],
+ };
+ await normal.write(update);
+ const saved = JSON.parse(
+ await readFile(path.join(normal.root, "findings.json"), "utf8"),
+ );
+ assert.equal(saved.findings.length, 2);
+ assert.deepEqual(
+ saved.findings.map((row: FixtureFinding) => row.identity),
+ before.findings.map((row: FixtureFinding) => row.identity),
+ );
+ await draftApi.saveScanDraftCheckpoint(recovered.context, update, false);
+ const { handoffClaimToken: _claim, ...checkpoint } = update;
+ await utimes(
+ path.join(recovered.root, "checkpoints", checkpointName(checkpoint)),
+ 200,
+ 200,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+const revisionFinding = (level: string, summary: string) =>
+ finding("Synthetic review", {
+ identity: { anchor: "candidate-1" },
+ severity: { level },
+ summary,
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ workerId: "reviewer",
+ },
+ });
+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 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.")],
+ };
+ 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 });
+ // Valid JSON whitespace controls filename order without changing the evidence.
+ const names = await readdir(path.join(output, "checkpoints"));
+ let contents = JSON.stringify(initial),
+ name = "";
+ do {
+ contents += "\n";
+ name = createHash("sha256").update(contents).digest("hex") + ".json";
+ } while (names.some((existing) => existing > name));
+ await writeFile(path.join(output, "checkpoints", name), contents);
+ if (source === "published result") {
+ const { rm } = await import("node:fs/promises");
+ await rm(path.join(output, "checkpoint-head.json"));
+ }
+ await dateDraftFiles(output, 100);
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [savedWorker(output)],
+ true,
+ true,
+ );
+ assert.equal(result.normal[0].severity.level, "high");
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+}
+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 normalRoot =
+ layout === "worker" ? path.join(normal.root, "reviewer") : normal.root;
+ const recoveredRoot =
+ layout === "worker"
+ ? path.join(recovered.root, "reviewer")
+ : recovered.root;
+ if (layout === "worker")
+ for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
+ const writer =
+ 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.")],
+ };
+ for (const f of [writer, interrupted]) await f.write(terminal);
+ await dateDraftFiles(recoveredRoot, 100);
+ await writer.write(progress);
+ await draftApi.saveScanDraftCheckpoint(
+ interrupted.context,
+ progress,
+ false,
+ );
+ const { handoffClaimToken: _claim, ...rawProgress } = progress;
+ await utimes(
+ path.join(recoveredRoot, "checkpoints", checkpointName(rawProgress)),
+ 200,
+ 200,
+ );
+ if (layout === "worker") {
+ const saved = JSON.parse(
+ await readFile(path.join(normalRoot, "result.json"), "utf8"),
+ );
+ assert.equal(saved.findings[0].severity.level, "high");
+ await normal.write({
+ ...normal.draft({}, true),
+ findings: saved.findings,
+ });
+ }
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ layout === "worker" ? [savedWorker(recoveredRoot)] : [],
+ true,
+ true,
+ );
+ assert.equal(result.normal[0].severity.level, "high");
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ assert.ok(result.historySummaries.includes("Incomplete progress."));
+ });
+}
+test("finding precedence compares parent and worker observation times", async (t) => {
+ const normal = await fixture(t, "deep"),
+ recovered = await fixture(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.")],
+ };
+ 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,
+ );
+ 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 findings = [1, 2].map((line) =>
+ finding(`Synthetic report ${line}`, {
+ identity: { anchor: "shared" },
+ locations: [{ path: "src/example.py", startLine: line }],
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ workerId: "reviewer",
+ },
+ }),
+ );
+ const workerRoot = path.join(recovered.root, "reviewer");
+ await mkdir(workerRoot);
+ const worker = draftFixture(workerRoot, "worker");
+ await worker.write({ ...worker.draft({}, true), findings });
+ for (const f of [normal, recovered])
+ await f.write({ ...f.draft({}, true), findings });
+ await dateDraftFiles(recovered.root, 100);
+ const latest = findings.map((row) => ({
+ ...row,
+ summary: revised ? "Updated evidence." : row.summary,
+ }));
+ await worker.write({
+ ...worker.draft({}, 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,
+ );
+ assert.equal(result.normal[1].identity.instance, "saved-2");
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+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 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 currentWorker.write(latest);
+ await normal.write({ ...normal.draft({}, true), findings: latest.findings });
+ await dateDraftFiles(output, 100);
+ await dateDraftFiles(archive, 200);
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [{ ...savedWorker(output), attempt: 2 }],
+ true,
+ 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 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.")],
+ };
+ 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,
+ );
+ 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");
+ for (const f of [normal, recovered])
+ await mkdir(path.join(f.root, "reviewer"));
+ const writer = draftFixture(path.join(normal.root, "reviewer"), "worker"),
+ recoveryWriter = draftFixture(
+ path.join(recovered.root, "reviewer"),
+ "worker",
+ );
+ const first = finding("First independent review", {
+ provenance: { source: "local_plugin", candidateId: "shared-candidate" },
+ });
+ const second = { ...first, title: "Second independent review" };
+ const revised = {
+ ...first,
+ title: "New review",
+ summary: "New synthetic evidence.",
+ };
+ const ordered = (rows: FixtureFinding[]) =>
+ reverse ? [...rows].reverse() : rows;
+ for (const f of [writer, recoveryWriter])
+ await f.write({ ...f.draft(), findings: 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"),
+ );
+ assert.equal(published.findings.length, 3);
+ await interruptDraftWrite(
+ path.join(recoveryWriter.root, "checkpoints", checkpointName(published)),
+ () =>
+ recoveryWriter.write({
+ ...recoveryWriter.draft(),
+ findings: ordered([revised, second]),
+ }),
+ );
+ const files = [
+ "result.json",
+ "checkpoint-head.json",
+ ...(await readdir(path.join(recoveryWriter.root, "checkpoints"))).map(
+ (name) => path.join("checkpoints", name),
+ ),
+ ];
+ 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" },
+ })),
+ });
+ 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[]) =>
+ [...rows].sort((a, b) => a.title.localeCompare(b.title));
+ assert.deepEqual(byTitle(result.recovered), byTitle(result.normal));
+ assert.deepEqual(result.warnings, []);
+ for (const [index, name] of files.entries())
+ assert.deepEqual(
+ await readFile(path.join(recoveryWriter.root, name)),
+ originals[index],
+ );
+ });
+}
+
+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 first = finding("First review");
+ const revised = {
+ ...first,
+ summary: "Revised synthetic evidence.",
+ severity: { level: "high" },
+ };
+ const second = finding("Independent review", {
+ extensions: { reportId: "report-2" },
+ });
+ const initial = { ...normal.draft(), findings: [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,
+ );
+ 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 draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ update,
+ false,
+ );
+ const { handoffClaimToken: _claim, ...checkpoint } = update;
+ await utimes(
+ path.join(recovered.root, "checkpoints", checkpointName(checkpoint)),
+ 200,
+ 200,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ const ordered = (values: RecoveredFinding[]) =>
+ [...values].sort((a, b) => a.title.localeCompare(b.title));
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ test(`one-to-one ${layout} historical siblings (reverse=${reverse})`, async (t) => {
+ const normal = await fixture(t, layout),
+ recovered = await fixture(t, layout);
+ const first = finding("Synthetic review", {
+ extensions: { candidateId: "candidate-1" },
+ });
+ const second = {
+ ...structuredClone(first),
+ locations: [{ path: "src/example.py", startLine: 2 }],
+ };
+ 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 draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ update,
+ false,
+ );
+ const { handoffClaimToken: _claim, ...checkpoint } = update;
+ await utimes(
+ path.join(recovered.root, "checkpoints", checkpointName(checkpoint)),
+ (index + 1) * 100,
+ (index + 1) * 100,
+ );
+ }
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ const ordered = (values: RecoveredFinding[]) =>
+ [...values].sort(
+ (a, b) => a.locations[0]!.startLine - b.locations[0]!.startLine,
+ );
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+for (const [field, value] of Object.entries({
+ description: "Synthetic annotation",
+ source: "authored",
+ version: 1,
+})) {
+ 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 workers = [],
+ findings = [];
+ for (const index of reservedFirst ? [2, 0, 1] : [0, 1, 2]) {
+ const id = `worker-${index}`;
+ const workerRoot = path.join(recovered.root, id);
+ await mkdir(workerRoot);
+ const worker = draftFixture(workerRoot, "worker");
+ const row = finding(`Review ${index}`, {
+ identity: {
+ anchor: "shared",
+ ...(index === 2 ? { instance: "saved-2", [field]: value } : {}),
+ },
+ locations: [{ path: "src/example.py", startLine: index + 1 }],
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ workerId: id,
+ },
+ });
+ await worker.write({ ...worker.draft(), findings: [row] });
+ findings.push(row);
+ workers.push({
+ id,
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ });
+ }
+ await normal.write({ ...normal.draft(), findings });
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 3);
+ assert.equal(result.recovered.length, 3);
+ const ordered = (rows: RecoveredFinding[]) =>
+ [...rows].sort((a, b) => a.title.localeCompare(b.title));
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ assert.deepEqual(
+ result.recovered.find((row) => row.title === "Review 2")!.identity,
+ { anchor: "shared", instance: "saved-2", [field]: value },
+ );
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+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 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 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 draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ update,
+ false,
+ );
+ const { handoffClaimToken: _claim, ...checkpoint } = update;
+ await utimes(
+ path.join(recovered.root, "checkpoints", checkpointName(checkpoint)),
+ 200,
+ 200,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ const ordered = (rows: RecoveredFinding[]) =>
+ [...rows].sort((a, b) => a.findingId.localeCompare(b.findingId));
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+}
+
+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 first = finding("First review"),
+ second = finding("Second review"),
+ added = finding(
+ "Added review",
+ candidate
+ ? {
+ provenance: {
+ source: "local_plugin",
+ candidateId: "new-candidate",
+ },
+ }
+ : {},
+ );
+ for (const f of [normal, recovered]) {
+ await f.write({ ...f.draft(), findings: [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 draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ update,
+ false,
+ );
+ const { handoffClaimToken: _claim, ...checkpoint } = update;
+ await utimes(
+ path.join(recovered.root, "checkpoints", checkpointName(checkpoint)),
+ 200,
+ 200,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 3);
+ assert.equal(result.recovered.length, 3);
+ const ordered = (rows: RecoveredFinding[]) =>
+ [...rows].sort((a, b) => a.title.localeCompare(b.title));
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+ 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 first = finding("First review"),
+ second = finding("Second review");
+ for (const f of [normal, recovered]) {
+ await f.write({ ...f.draft(), findings: [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 draftApi.saveScanDraftCheckpoint(recovered.context, update, false);
+ const { handoffClaimToken: _claim, ...checkpoint } = update;
+ await utimes(
+ path.join(recovered.root, "checkpoints", checkpointName(checkpoint)),
+ 200,
+ 200,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ const ordered = (rows: RecoveredFinding[]) =>
+ [...rows].sort((a, b) => a.title.localeCompare(b.title));
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+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 workerRoot = path.join(recovered.root, "reviewer");
+ await mkdir(workerRoot);
+ const worker = draftFixture(workerRoot, "worker");
+ const first = finding("Synthetic review", {
+ identity: {
+ anchor: "authored",
+ instance: "report-1",
+ [field]: "initial",
+ },
+ provenance: {
+ source: "local_plugin",
+ workerId: "reviewer",
+ ...(candidate ? { candidateId: "candidate-1" } : {}),
+ },
+ });
+ await worker.write({ ...worker.draft(), findings: [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 });
+ const workers = [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ];
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 1);
+ assert.equal(result.recovered.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.equal(result.recovered[0]!.identity[field], "revised");
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+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 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 dateDraftFiles(workerRoot, 100);
+ await normal.write({ ...normal.draft(), findings: [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"));
+ saved.findings = malformedFirst ? [malformed, row] : [row, malformed];
+ await writeFile(resultFile, JSON.stringify(saved));
+ await utimes(resultFile, 200, 200);
+ const workers = [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ];
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 1);
+ assert.equal(result.recovered.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.ok(result.warnings.length > 0);
+ });
+ }
+}
+
+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 normalRoot = path.join(normal.root, "reviewer"),
+ recoveredRoot = path.join(recovered.root, "reviewer");
+ for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
+ const worker = draftFixture(normalRoot, "worker"),
+ recoveryWorker = draftFixture(recoveredRoot, "worker");
+ const first = finding("Synthetic review", {
+ identity: {
+ anchor: "authored",
+ instance: "report-1",
+ [field]: "initial",
+ },
+ provenance: {
+ source: "local_plugin",
+ workerId: "reviewer",
+ ...(candidate ? { candidateId: "candidate-1" } : {}),
+ },
+ });
+ const revised = {
+ ...first,
+ summary: "Revised synthetic assessment.",
+ severity: { level: "high" },
+ identity: { ...first.identity, [field]: "revised" },
+ };
+ const oldDraft = { ...worker.draft(), findings: [first] };
+ let newDraft,
+ suffix = 0;
+ do {
+ newDraft = {
+ ...worker.draft(),
+ findings: [revised],
+ threatModel: { summary: `Synthetic checkpoint ${suffix++}.` },
+ };
+ } while (
+ checkpointName(oldDraft) < checkpointName(newDraft) !==
+ (order === "earlier-first")
+ );
+ for (const [index, draft] of [oldDraft, newDraft].entries()) {
+ await worker.write(draft);
+ await draftApi.saveScanDraftCheckpoint(
+ recoveryWorker.context,
+ draft,
+ false,
+ );
+ await utimes(
+ path.join(recoveredRoot, "checkpoints", checkpointName(draft)),
+ 100 + index * 100,
+ 100 + index * 100,
+ );
+ }
+ const saved = JSON.parse(
+ await readFile(path.join(normalRoot, "result.json"), "utf8"),
+ );
+ assert.equal(saved.findings.length, 1);
+ assert.equal(saved.findings[0].identity[field], "revised");
+ await normal.write({ ...normal.draft(), findings: saved.findings });
+ const workers = [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: recoveredRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ];
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 1);
+ assert.equal(result.recovered.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.equal(result.recovered[0]!.identity[field], "revised");
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+}
+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 valid = finding("Synthetic review");
+ valid[metadata] = { ...valid[metadata], candidateId: "candidate-1" };
+ for (const f of [normal, recovered])
+ await f.write({ ...f.draft(), findings: [valid] });
+ const destination = path.join(recovered.root, "findings.json");
+ const document = JSON.parse(await readFile(destination, "utf8"));
+ const { summary: _summary, ...invalid } = {
+ ...valid,
+ locations: [{ path: "src/example.py", startLine: 2 }],
+ };
+ document.findings = [valid, invalid];
+ await writeFile(destination, JSON.stringify(document));
+ await rm(path.join(recovered.root, "checkpoints"), {
+ recursive: true,
+ force: true,
+ });
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.equal(result.warnings.length, 1);
+ assert.match(String(result.warnings[0]), /summary/);
+ });
+ }
+}
+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 workerRoot = path.join(recovered.root, "reviewer");
+ await mkdir(workerRoot);
+ const worker = draftFixture(workerRoot, "worker");
+ const first = finding("First review", {
+ summary: "Original first assessment.",
+ severity: { level: "medium" },
+ provenance: {
+ source: "local_plugin",
+ workerId: "reviewer",
+ candidateId: "shared-candidate",
+ },
+ });
+ const second = {
+ ...first,
+ title: "Independent second review",
+ summary: "Independent second assessment.",
+ severity: { level },
+ locations: [
+ { path: "src/example.py", startLine: sameLocation ? 1 : 20 },
+ ],
+ };
+ const parent = {
+ ...first,
+ identity: { anchor: "shared-candidate" },
+ summary: "Consolidated first assessment.",
+ provenance: {
+ ...first.provenance,
+ sourceFindingIds: ["reviewer:0"],
+ sourceFindings: [{ id: "reviewer:0", finding: first }],
+ },
+ };
+ await worker.write({ ...worker.draft({}, true), findings: [first] });
+ await dateDraftFiles(workerRoot, 100);
+ for (const f of [normal, recovered])
+ await f.write({ ...f.draft({}, true), findings: [parent] });
+ await dateDraftFiles(recovered.root, 200);
+ await dateDraftFiles(workerRoot, 100);
+ const checkpoint = { ...worker.draft(), findings: [first, second] };
+ await draftApi.saveScanDraftCheckpoint(worker.context, checkpoint, false);
+ await utimes(
+ path.join(workerRoot, "checkpoints", checkpointName(checkpoint)),
+ 300,
+ 300,
+ );
+ await normal.write({
+ ...normal.draft({}, true),
+ findings: [parent, second],
+ });
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+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);
+ let normalWriter = normal,
+ recoveredWriter = recovered;
+ const workers: Record<string, unknown>[] = [];
+ if (layout === "worker") {
+ const normalRoot = path.join(normal.root, "reviewer"),
+ recoveredRoot = path.join(recovered.root, "reviewer");
+ for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
+ normalWriter = draftFixture(normalRoot, "worker");
+ recoveredWriter = draftFixture(recoveredRoot, "worker");
+ workers.push({
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: recoveredRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ });
+ }
+ const raw = finding("Synthetic finding", {
+ identity: { anchor: "stable" },
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ ...(layout === "worker" ? { workerId: "reviewer" } : {}),
+ },
+ });
+ const source = { ...raw, summary: "Original source evidence." };
+ const history = { ...raw, summary: "Previously accepted assessment." };
+ const first = {
+ ...raw,
+ provenance: {
+ ...raw.provenance,
+ sourceFindingIds: ["origin:0", "origin:1"],
+ sourceFindings: [
+ { id: "origin:0", finding: source },
+ {
+ id: "origin:1",
+ finding: { ...source, summary: "Additional source evidence." },
+ },
+ ],
+ originalCandidates: [
+ { id: "candidate-1", summary: "Original candidate evidence." },
+ ],
+ previousFindings: [history],
+ },
+ };
+ const revised =
+ update === "omitted"
+ ? raw
+ : {
+ ...raw,
+ provenance: {
+ ...raw.provenance,
+ sourceFindingIds: ["origin:2", "origin:0"],
+ sourceFindings: [
+ {
+ id: "origin:2",
+ finding: { ...source, summary: "New source evidence." },
+ },
+ first.provenance.sourceFindings[0],
+ ],
+ originalCandidates: [
+ { id: "candidate-1", summary: "Updated candidate evidence." },
+ ...first.provenance.originalCandidates,
+ ],
+ previousFindings: [
+ { ...history, summary: "New historical assessment." },
+ history,
+ ],
+ },
+ };
+ for (const writer of [normalWriter, recoveredWriter])
+ await writer.write({ ...writer.draft(), findings: [first] });
+ await dateDraftFiles(recoveredWriter.root, 100);
+ await normalWriter.write({
+ ...normalWriter.draft(),
+ findings: [revised],
+ });
+ const checkpoint = { ...recoveredWriter.draft(), findings: [revised] };
+ await draftApi.saveScanDraftCheckpoint(
+ recoveredWriter.context,
+ checkpoint,
+ false,
+ );
+ const { handoffClaimToken: _claim, ...snapshot } = checkpoint;
+ await utimes(
+ path.join(
+ recoveredWriter.root,
+ "checkpoints",
+ checkpointName(snapshot),
+ ),
+ 200,
+ 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 result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ true,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+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);
+ let normalWriter = normal,
+ recoveredWriter = recovered;
+ const workers: Record<string, unknown>[] = [];
+ if (layout === "worker") {
+ const normalRoot = path.join(normal.root, "reviewer"),
+ recoveredRoot = path.join(recovered.root, "reviewer");
+ for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
+ normalWriter = draftFixture(normalRoot, "worker");
+ recoveredWriter = draftFixture(recoveredRoot, "worker");
+ workers.push({
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: recoveredRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ });
+ }
+ const first = finding(
+ "First review",
+ layout === "worker"
+ ? { provenance: { source: "local_plugin", workerId: "reviewer" } }
+ : {},
+ );
+ const second = { ...first, title: "Second review" };
+ for (const writer of [normalWriter, recoveredWriter])
+ await writer.write({ ...writer.draft(), findings: [first, second] });
+ await dateDraftFiles(recoveredWriter.root, 100);
+ const revised = {
+ ...first,
+ summary: "Revised assessment.",
+ severity: { level: "high" },
+ extensions: { [field]: "report-1" },
+ };
+ await normalWriter.write({
+ ...normalWriter.draft(),
+ findings: [revised],
+ });
+ const checkpoint = { ...recoveredWriter.draft(), findings: [revised] };
+ await draftApi.saveScanDraftCheckpoint(
+ recoveredWriter.context,
+ checkpoint,
+ false,
+ );
+ const { handoffClaimToken: _claim, ...snapshot } = checkpoint;
+ await utimes(
+ path.join(
+ recoveredWriter.root,
+ "checkpoints",
+ checkpointName(snapshot),
+ ),
+ 200,
+ 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 result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ const sorted = (rows: RecoveredFinding[]) =>
+ [...rows].sort((a, b) => a.title.localeCompare(b.title));
+ assert.deepEqual(sorted(result.recovered), sorted(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+for (const layout of ["standard", "diff"] as const) {
+ for (const field of ["reportId", "ledgerRowId"]) {
+ test(`${layout}: historical ${field} change does not resurrect raw checkpoint`, async (t) => {
+ const f = await fixture(t, layout);
+ 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];
+ assert.ok(initial.identity);
+ const revised = { ...initial, extensions: { [field]: "new-report" } };
+ for (const input of [{ ...f.draft(), findings: [revised] }, f.draft()]) {
+ await f.write(input);
+ const saved: { findings: FixtureFinding[] } = JSON.parse(
+ await readFile(path.join(f.root, "findings.json"), "utf8"),
+ );
+ assert.equal(saved.findings.length, 1);
+ const retained = saved.findings[0]!;
+ assert.deepEqual(retained.identity, initial.identity);
+ assert.equal(retained.extensions?.[field], "new-report");
+ const history = retained.provenance
+ .previousFindings as FixtureFinding[];
+ assert.ok(
+ history.some((row) => row.extensions?.[field] === "old-report"),
+ );
+ }
+ });
+ }
+}
+
+for (const layout of ["standard", "diff", "worker"] as const) {
+ for (const separateIdentity of [false, true]) {
+ test(`${layout}: represented historical findings retain nested ancestry (separateIdentity=${separateIdentity})`, async (t) => {
+ const f = await fixture(t, layout);
+ const original = finding("Synthetic ancestry review", {
+ identity: { anchor: "saved-report" },
+ summary: "Original evidence.",
+ });
+ const ancestor = { ...original, summary: "Earlier source evidence." };
+ await f.write({
+ ...f.draft(),
+ findings: [
+ {
+ ...original,
+ provenance: {
+ ...original.provenance,
+ previousFindings: [ancestor],
+ },
+ },
+ ],
+ });
+ const revised = {
+ ...original,
+ ...(separateIdentity ? { identity: { anchor: "revised-report" } } : {}),
+ summary: "Revised evidence.",
+ provenance: { ...original.provenance, previousFindings: [original] },
+ };
+ const containsAncestor = (value: unknown): boolean => {
+ if (Array.isArray(value)) return value.some(containsAncestor);
+ if (typeof value !== "object" || value === null) return false;
+ const row = value as Record<string, unknown>;
+ return (
+ row.summary === ancestor.summary ||
+ Object.values(row).some(containsAncestor)
+ );
+ };
+ 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",
+ ),
+ );
+ assert.ok(
+ containsAncestor(saved.findings),
+ "Saved ancestry must survive the published revision and replay.",
+ );
+ const current = saved.findings.find(
+ (row) => row.summary === revised.summary,
+ )!;
+ assert.deepEqual(current.identity, revised.identity);
+ }
+ 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,
+ );
+ assert.ok(containsAncestor(finalized.normal));
+ assert.ok(containsAncestor(finalized.recovered));
+ assert.deepEqual(finalized.warnings, []);
+ });
+ }
+}
+
+for (const layout of ["standard", "diff", "deep"] as const) {
+ test(`${layout}: sibling revisions preserve independent worker identities`, async (t) => {
+ const f = await fixture(t, layout);
+ const initial = ["First review", "Second review"].map((title, index) =>
+ finding(title, {
+ identity: { anchor: `saved-${index}` },
+ provenance: {
+ source: "local_plugin",
+ candidateId: "shared-review",
+ workerId: `worker-${index}`,
+ },
+ }),
+ );
+ await f.write({ ...f.draft(), findings: 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"),
+ );
+ for (const previous of initial) {
+ const retained = saved.findings.filter(
+ (row) => row.identity?.anchor === previous.identity!.anchor,
+ );
+ assert.equal(retained.length, 1);
+ assert.equal(
+ retained[0]!.provenance.workerId,
+ previous.provenance.workerId,
+ );
+ }
+ for (const row of saved.findings) {
+ for (const previous of (row.provenance.previousFindings ??
+ []) as FixtureFinding[]) {
+ assert.equal(previous.provenance.workerId, row.provenance.workerId);
+ }
+ }
+ }
+ const finalized = await recoverAndFinalize(f, f, [], true, true);
+ for (const rows of [finalized.normal, finalized.recovered]) {
+ for (const previous of initial) {
+ const retained = rows.filter(
+ (row) => row.identity.anchor === previous.identity!.anchor,
+ );
+ assert.equal(retained.length, 1);
+ assert.equal(retained[0]!.workerMetadata, previous.provenance.workerId);
+ }
+ }
+ assert.deepEqual(finalized.warnings, []);
+ });
+}
+
+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 initial = finding("Synthetic ownership review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ });
+ const owned = {
+ ...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"),
+ );
+ if (cut === "published") {
+ await recovered.write({ ...recovered.draft(), findings: [initial] });
+ } else {
+ await draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ { ...recovered.draft(), findings: [initial] },
+ false,
+ );
+ }
+ const findings = reversed ? [owned, initial] : [initial, owned];
+ await normal.write({ ...normal.draft(), findings });
+ if (cut === "published") {
+ await interruptDraftWrite(
+ path.join(recovered.root, "findings.json"),
+ () => recovered.write({ ...recovered.draft(), findings }),
+ );
+ } else {
+ await draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ { ...recovered.draft(), findings },
+ false,
+ );
+ }
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ const contents = (rows: RecoveredFinding[]) =>
+ rows
+ .map(
+ ({
+ identity: _identity,
+ fingerprints: _fingerprints,
+ findingId: _findingId,
+ occurrenceId: _occurrenceId,
+ ...row
+ }) => row,
+ )
+ .sort((left, right) =>
+ String(left.workerMetadata).localeCompare(
+ String(right.workerMetadata),
+ ),
+ );
+ assert.deepEqual(contents(result.recovered), contents(result.normal));
+ assert.equal(
+ new Set(result.recovered.map((row) => row.occurrenceId)).size,
+ 2,
+ );
+ assert.deepEqual(
+ result.recovered.find((row) => row.workerMetadata === null)?.identity,
+ published.findings[0].identity,
+ );
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+}
+
+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);
+ let normalWriter = normal,
+ recoveredWriter = recovered;
+ const workers: Record<string, unknown>[] = [];
+ if (layout === "worker") {
+ const normalRoot = path.join(normal.root, "reviewer"),
+ recoveredRoot = path.join(recovered.root, "reviewer");
+ for (const root of [normalRoot, recoveredRoot]) await mkdir(root);
+ normalWriter = draftFixture(normalRoot, "worker");
+ recoveredWriter = draftFixture(recoveredRoot, "worker");
+ workers.push({
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: recoveredRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ });
+ }
+ const original = finding("Synthetic historical revision", {
+ identity: { anchor: "stable-report" },
+ summary: "Original evidence.",
+ provenance: {
+ source: "local_plugin",
+ ...(candidate ? { candidateId: "candidate-1" } : {}),
+ ...(layout === "worker" ? { workerId: "reviewer" } : {}),
+ },
+ });
+ const { identity: _identity, ...revised } = structuredClone(original);
+ revised.summary = "Revised evidence.";
+ revised.provenance.previousFindings = [original];
+ for (const writer of [normalWriter, recoveredWriter])
+ await writer.write({ ...writer.draft(), findings: [original] });
+ for (let replay = 0; replay < 2; replay++) {
+ await normalWriter.write({
+ ...normalWriter.draft(),
+ findings: [revised],
+ });
+ await interruptDraftWrite(
+ path.join(
+ recoveredWriter.root,
+ layout === "worker" ? "result.json" : "findings.json",
+ ),
+ () =>
+ recoveredWriter.write({
+ ...recoveredWriter.draft(),
+ findings: [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 result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.normal[0]!.identity, original.identity);
+ assert.equal(result.normal[0]!.summary, revised.summary);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ }
+ });
+ }
+}
+
+for (const layout of ["standard", "diff", "deep", "worker"] as const) {
+ for (const history of [false, true]) {
+ for (const reversed of [false, true]) {
+ test(`${layout}: assigned siblings survive ambiguous matches (history=${history}, reversed=${reversed})`, async (t) => {
+ const f = await fixture(t, layout);
+ const original = finding("Synthetic shared review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ });
+ const first = {
+ ...structuredClone(original),
+ identity: { anchor: "shared-review", instance: "first" },
+ };
+ const sibling = history
+ ? {
+ ...structuredClone(original),
+ identity: { anchor: "shared-review", instance: "second" },
+ }
+ : {
+ ...structuredClone(original),
+ title: "Independent shared-candidate review",
+ summary: "Independent evidence remains active.",
+ };
+ await f.write({
+ ...f.draft(),
+ findings: reversed ? [sibling, first] : [first, sibling],
+ });
+ const revised = {
+ ...first,
+ summary: "Revised evidence.",
+ provenance: {
+ ...first.provenance,
+ ...(history ? { previousFindings: [original] } : {}),
+ },
+ };
+ 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",
+ ),
+ );
+ assert.equal(
+ saved.findings.length,
+ 2,
+ `Active findings after replay ${replay}`,
+ );
+ assert.equal(saved.findings[0].summary, revised.summary);
+ const retained = saved.findings.find((row: FixtureFinding) =>
+ history
+ ? row.identity?.instance === "second"
+ : row.summary === sibling.summary,
+ );
+ assert.ok(retained, "Independent evidence remains an active finding");
+ if (previous) assert.deepEqual(saved.findings, previous);
+ previous = saved.findings;
+ }
+ });
+ }
+ }
+}
+
+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 workerRoot = path.join(recovered.root, "reviewer");
+ await mkdir(workerRoot);
+ const worker = draftFixture(workerRoot, "worker");
+ const findings = ["first", "second"].map((id) =>
+ finding("Synthetic saved review", {
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ originalCandidates: [
+ { id: evidence === "identical" ? "same" : id },
+ ],
+ },
+ }),
+ );
+ await worker.write({ ...worker.draft({}, true), findings });
+ if (evidence === "reordered")
+ await worker.write({
+ ...worker.draft({}, true),
+ findings: [...findings].reverse(),
+ });
+ const saved = JSON.parse(
+ await readFile(path.join(workerRoot, "result.json"), "utf8"),
+ );
+ assert.equal(saved.findings.length, 2);
+ await normal.write({
+ ...normal.draft({}, true),
+ findings: saved.findings.map((row: FixtureFinding) => ({
+ ...row,
+ provenance: { ...row.provenance, workerId: "reviewer" },
+ })),
+ });
+ if (!includeResult) await rm(path.join(workerRoot, "result.json"));
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [savedWorker(workerRoot)],
+ true,
+ true,
+ true,
+ );
+ const ordered = (rows: RecoveredFinding[]) =>
+ [...rows].sort((a, b) => a.findingId.localeCompare(b.findingId));
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ assert.deepEqual(ordered(result.recovered), ordered(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+for (const layout of ["standard", "diff", "worker"] as const) {
+ for (const cut of ["raw", "result"]) {
+ for (const [metadata, preservedIdentity] of Object.entries({
+ note: "Synthetic annotation",
+ incomplete: { description: "Synthetic annotation" },
+ valid: {
+ anchor: "authored",
+ description: "Synthetic identity annotation",
+ },
+ })) {
+ test(`${layout}: preserved identity metadata ${metadata} survives ${cut} interruption`, async (t) => {
+ const normal = await fixture(t, layout === "worker" ? "deep" : layout);
+ const recovered = await fixture(
+ t,
+ layout === "worker" ? "deep" : layout,
+ );
+ let writer: DraftFixture = normal,
+ recoveryWriter: DraftFixture = recovered;
+ if (layout === "worker") {
+ for (const f of [normal, recovered])
+ await mkdir(path.join(f.root, "reviewer"));
+ writer = draftFixture(path.join(normal.root, "reviewer"), "worker");
+ recoveryWriter = draftFixture(
+ path.join(recovered.root, "reviewer"),
+ "worker",
+ );
+ }
+ const initial = finding("Synthetic preserved identity review", {
+ identity:
+ metadata === "valid" ? preservedIdentity : { anchor: "authored" },
+ provenance: {
+ source: "local_plugin",
+ candidateId: "candidate-1",
+ preservedIdentity,
+ ...(layout === "worker" ? { workerId: "reviewer" } : {}),
+ },
+ });
+ for (const f of [writer, recoveryWriter])
+ await f.write({ ...f.draft(), findings: [initial] });
+ await dateDraftFiles(recoveryWriter.root, 100);
+ const revised = {
+ ...initial,
+ summary: "Revised synthetic assessment.",
+ severity: { level: "high" },
+ };
+ delete revised.identity;
+ await writer.write({ ...writer.draft(), findings: [revised] });
+ const filename = layout === "worker" ? "result.json" : "findings.json";
+ if (cut === "raw")
+ await draftApi.saveScanDraftCheckpoint(
+ recoveryWriter.context,
+ { ...recoveryWriter.draft(), findings: [revised] },
+ false,
+ );
+ else
+ await interruptDraftWrite(
+ path.join(recoveryWriter.root, filename),
+ () =>
+ recoveryWriter.write({
+ ...recoveryWriter.draft(),
+ findings: [revised],
+ }),
+ );
+ const saved = JSON.parse(
+ await readFile(path.join(writer.root, filename), "utf8"),
+ );
+ 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,
+ );
+ assert.deepEqual(result.preservedIdentities, [
+ [preservedIdentity],
+ [preservedIdentity],
+ ]);
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+}
+
+for (const layout of ["standard", "diff", "deep"] as const) {
+ for (const variant of [
+ "legacy missing",
+ "explicit same",
+ "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 initial = finding("Synthetic review", {
+ identity: {
+ anchor: "stable-authored",
+ instance: "report-1",
+ description: "Saved annotation",
+ },
+ });
+ for (const f of [normal, recovered])
+ await f.write({ ...f.draft(), findings: [initial] });
+ const revised = {
+ ...structuredClone(initial),
+ summary: "Revised synthetic evidence.",
+ };
+ if (variant === "legacy missing") delete revised.identity;
+ if (variant === "explicit changed")
+ revised.identity = {
+ anchor: "new-authored",
+ instance: "report-2",
+ description: "Revised annotation",
+ };
+ await normal.write({ ...normal.draft(), findings: [revised] });
+ const dest = path.join(recovered.root, "findings.json");
+ const doc = JSON.parse(await readFile(dest, "utf8"));
+ 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,
+ );
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ const replay = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.deepEqual(replay.recovered, result.recovered);
+ });
+ }
+}
+
+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 first = finding("First review", {
+ identity: { anchor: "saved-a" },
+ provenance: {
+ source: "local_plugin",
+ candidateId: "shared-candidate",
+ },
+ });
+ const second = {
+ ...structuredClone(first),
+ identity: { anchor: "saved-b" },
+ title: "Second review",
+ };
+ const ordered = (rows: FixtureFinding[]) =>
+ reversed ? rows.toReversed() : rows;
+ for (const f of [normal, recovered])
+ await f.write({ ...f.draft(), findings: ordered([first, second]) });
+ const revised = {
+ ...structuredClone(first),
+ title: "Revised first review",
+ summary: "Updated first evidence.",
+ };
+ if (historical)
+ revised.provenance.previousFindings = [structuredClone(first)];
+ await normal.write({
+ ...normal.draft(),
+ findings: 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;
+ assert.equal(rows.length, 2);
+ assert.deepEqual(
+ rows.find((row: FixtureFinding) => row.title === revised.title)
+ .identity,
+ first.identity,
+ );
+ assert.deepEqual(
+ rows.find((row: FixtureFinding) => row.title === second.title)
+ .identity,
+ second.identity,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ false,
+ false,
+ "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 first = finding("First review", {
+ identity: { anchor: "saved-a" },
+ provenance: { source: "local_plugin", candidateId: "shared-candidate" },
+ });
+ const second = {
+ ...structuredClone(first),
+ identity: { anchor: "saved-b" },
+ title: "Second review",
+ };
+ const revised = [
+ {
+ ...structuredClone(first),
+ title: "New first review",
+ summary: "New first evidence.",
+ },
+ {
+ ...structuredClone(second),
+ title: "New second review",
+ summary: "New second evidence.",
+ },
+ ];
+ 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,
+ });
+ }
+ const rows = JSON.parse(
+ await readFile(path.join(normal.root, "findings.json"), "utf8"),
+ ).findings;
+ assert.equal(rows.length, 4);
+ assert.deepEqual(
+ rows.find((row: FixtureFinding) => row.title === first.title).identity,
+ first.identity,
+ );
+ assert.deepEqual(
+ rows.find((row: FixtureFinding) => row.title === second.title).identity,
+ second.identity,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 4);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+
+for (const reversed of [false, true]) {
+ test(`an explicit revision cannot absorb an unidentified worker sibling (reverse=${reversed})`, async (t) => {
+ const f = await fixture(t, "worker");
+ const first = finding("First review", {
+ provenance: { source: "local_plugin", candidateId: "shared-candidate" },
+ });
+ const second = {
+ ...structuredClone(first),
+ title: "Second review",
+ summary: "Second evidence.",
+ };
+ await f.write({
+ ...f.draft(),
+ findings: 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"),
+ );
+ assert.equal(findings.length, 2);
+ assert.deepEqual(
+ findings.find((row: FixtureFinding) => row.title === first.title),
+ {
+ ...revised,
+ provenance: { ...revised.provenance, previousFindings: [first] },
+ },
+ );
+ assert.deepEqual(
+ findings.find((row: FixtureFinding) => row.title === second.title),
+ second,
+ );
+ });
+}
+
+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 source = finding("Synthetic worker review", {
+ provenance: { source: "local_plugin", candidateId: "worker-candidate" },
+ });
+ const parent = finding("Consolidated review", {
+ identity: { anchor: "consolidated-review" },
+ provenance: {
+ source: "local_plugin",
+ candidateId: "parent-candidate",
+ sourceFindingIds: ["reviewer:0"],
+ sourceFindings: [{ id: "reviewer:0", finding: source }],
+ },
+ });
+ for (const f of [normal, recovered])
+ await f.write({ ...f.draft({}, true), findings: [parent] });
+ if (missing) {
+ const file = path.join(recovered.root, "findings.json");
+ const saved = JSON.parse(await readFile(file, "utf8"));
+ 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] });
+ 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, [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: null,
+ attempt: 1,
+ },
+ ]);
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+for (const reversed of [false, true]) {
+ for (const retained of [0, 1, 2]) {
+ test(`worker: colliding authored identities retain independent findings (reversed=${reversed}, retained=${retained})`, async (t) => {
+ const f = await fixture(t, "worker");
+ const rows = [1, 2].map((line) =>
+ finding("Synthetic shared review", {
+ identity: { anchor: "shared-review" },
+ locations: [{ path: "src/example.py", startLine: line }],
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ }),
+ );
+ await f.write({
+ ...f.draft(),
+ findings: reversed ? rows.toReversed() : rows,
+ });
+ for (let replay = 0; replay < 2; replay++) {
+ await f.write({
+ ...f.draft({}, true),
+ findings: retained === 0 ? [] : [rows[retained - 1]!],
+ });
+ const saved = JSON.parse(
+ await readFile(path.join(f.root, "result.json"), "utf8"),
+ );
+ assert.equal(saved.findings.length, 2);
+ assert.deepEqual(
+ saved.findings
+ .map((row: FixtureFinding) => row.locations[0]!.startLine)
+ .sort(),
+ [1, 2],
+ );
+ }
+ });
+ }
+ for (const layout of ["standard", "diff", "worker"] as const) {
+ for (const enriched of [false, true]) {
+ test(`${layout}: content-only replay retains ambiguous saved identities (reversed=${reversed}, enriched=${enriched})`, async (t) => {
+ const f = await fixture(t, layout);
+ const raw = finding("Synthetic shared review", {
+ provenance: { source: "local_plugin", candidateId: "candidate-1" },
+ });
+ const rows = ["first", "second"].map((instance) => ({
+ ...structuredClone(raw),
+ identity: { anchor: "shared-review", instance },
+ }));
+ await f.write({
+ ...f.draft(),
+ findings: 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",
+ ),
+ );
+ assert.equal(saved.findings.length, 2);
+ assert.deepEqual(
+ saved.findings
+ .map((row: FixtureFinding) => row.identity?.instance)
+ .sort(),
+ ["first", "second"],
+ );
+ if (enriched) {
+ assert.ok(
+ saved.findings.some(
+ (row: FixtureFinding) =>
+ row.extensions?.reportId === "report-1",
+ ),
+ );
+ }
+ }
+ });
+ }
+ }
+}
diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_publication_recovery.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_publication_recovery.ts
new file mode 100644
index 000000000..f0401e8da
--- /dev/null
+++ b/plugins/codex-security/mcp-app/tests/test_artifact_scan_publication_recovery.ts
@@ -0,0 +1,878 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import {
+ copyFile,
+ mkdir,
+ writeFile,
+ readFile,
+ 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,
+ dateDraftFiles,
+} from "./scan-identity-recovery-fixture.ts";
+
+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 first = finding("Review", {
+ ...(authored ? { identity: { anchor: "review" } } : {}),
+ provenance: {
+ source: "local_plugin",
+ ...(owner ? { workerId: owner } : {}),
+ ...(changedCandidate ? { candidateId: "candidate-a" } : {}),
+ },
+ });
+ const revised = {
+ ...first,
+ summary: "Second synthetic location.",
+ locations: [{ path: "src/example.py", startLine: 2 }],
+ provenance: { source: "local_plugin", candidateId: "candidate-b" },
+ };
+ for (const target of [normal, recovered]) {
+ await target.write({ ...target.draft(), findings: [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 dateDraftFiles(workerRoot, 50);
+ await writeFile(
+ path.join(workerRoot, "result.json"),
+ JSON.stringify({ ...worker.draft(), findings: [revised] }),
+ );
+ await normal.write({
+ ...normal.draft({}, true),
+ findings: [
+ first,
+ {
+ ...revised,
+ provenance: { ...revised.provenance, workerId: "reviewer" },
+ },
+ ],
+ });
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: path.join(workerRoot, "result.json"),
+ attempt: 1,
+ },
+ ],
+ true,
+ true,
+ );
+ const byEvidence = (rows: RecoveredFinding[]) =>
+ new Map(rows.map((row) => [row.summary, row]));
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ assert.deepEqual(
+ byEvidence(result.recovered),
+ byEvidence(result.normal),
+ );
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+}
+
+for (const layout of ["standard", "deep"] as const) {
+ for (const scoped of [false, true]) {
+ for (const variant of [
+ "anonymous",
+ "authored",
+ "changed candidate",
+ "authored changed candidate",
+ "owned",
+ "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);
+ if (scoped)
+ for (const target of [normal, recovered]) {
+ target.context.scope = "src";
+ (
+ target.context.targetContract!.scope as Record<string, unknown>
+ ).requiredIncludePaths = ["src"];
+ }
+ const initial = finding("First review", {
+ ...(variant.includes("authored")
+ ? { identity: { anchor: "authored-review" } }
+ : {}),
+ provenance: {
+ source: "local_plugin",
+ ...(variant.includes("candidate")
+ ? { candidateId: "candidate-a" }
+ : {}),
+ ...(variant.includes("owned") ? { workerId: "reviewer" } : {}),
+ },
+ });
+ const revised = {
+ ...initial,
+ title: "Revised review",
+ summary: "Revised synthetic evidence.",
+ provenance: {
+ ...initial.provenance,
+ ...(variant.includes("candidate")
+ ? { candidateId: "candidate-b" }
+ : {}),
+ },
+ };
+ for (const target of [normal, recovered]) {
+ await target.write({
+ ...target.draft({}, true),
+ findings: [initial],
+ });
+ 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,
+ );
+ const byEvidence = (rows: RecoveredFinding[]) =>
+ new Map(
+ rows.map(({ evidenceProvenance, ...row }) => [row.summary, row]),
+ );
+ assert.equal(result.recovered.length, result.normal.length);
+ assert.deepEqual(
+ byEvidence(result.recovered),
+ byEvidence(result.normal),
+ );
+ if (layout === "deep")
+ for (const row of [...result.normal, ...result.recovered]) {
+ assert.deepEqual(
+ (row.evidenceProvenance as { previousFindings: unknown[] })
+ .previousFindings,
+ [],
+ );
+ }
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+}
+
+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");
+ if (scoped)
+ for (const f of [normal, recovered]) {
+ f.context.scope = "src";
+ (
+ f.context.targetContract!.scope as Record<string, unknown>
+ ).requiredIncludePaths = ["src"];
+ }
+ const first = finding("First review");
+ const revised = {
+ ...first,
+ title: "Revised review",
+ summary: "Revised synthetic evidence.",
+ };
+ for (const f of [normal, recovered]) {
+ await f.write({ ...f.draft(), findings: [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,
+ );
+ else
+ await interruptDraftWrite(
+ path.join(recovered.root, "findings.json"),
+ () => recovered.write(input),
+ );
+ for (const name of await readdir(checkpoints))
+ if (!original.has(name))
+ await utimes(path.join(checkpoints, name), time, time);
+ if (cut === "committed head")
+ await utimes(
+ path.join(recovered.root, "checkpoint-head.json"),
+ time,
+ time,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 1);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+}
+
+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 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] });
+ 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,
+ );
+ else
+ await recovered.write({ ...recovered.draft(pending), findings: [later] });
+ for (const f of [normal, recovered]) await dateDraftFiles(f.root, 100);
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ true,
+ );
+ const byId = (rows: RecoveredFinding[]) =>
+ new Map(rows.map((row) => [row.findingId, row]));
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(byId(result.recovered), byId(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+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 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 dateDraftFiles(archiveRoot, 99);
+ const terminal = finding("Terminal review");
+ for (const f of [normal, recovered]) {
+ await f.write({ ...f.draft({}, true), findings: [terminal] });
+ for (const name of [
+ "findings.json",
+ "coverage.json",
+ "scan-manifest.json",
+ "checkpoint-head.json",
+ ])
+ await utimes(path.join(f.root, name), 100, 100);
+ await dateDraftFiles(path.join(f.root, "checkpoints"), 100);
+ }
+ const worker = draftFixture(workerRoot, "worker");
+ const later = finding("Later worker review", {
+ locations: [{ path: "src/later.py", startLine: 2 }],
+ });
+ await worker.write({ ...worker.draft(), findings: [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: [
+ terminal,
+ { ...later, provenance: { ...later.provenance, workerId: "reviewer" } },
+ ],
+ });
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [
+ {
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: path.join(workerRoot, "result.json"),
+ attempt: 2,
+ },
+ ],
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ const byId = (rows: RecoveredFinding[]) =>
+ new Map(rows.map((row) => [row.findingId, row]));
+ assert.deepEqual(byId(result.recovered), byId(result.normal));
+ assert.deepEqual(result.warnings, []);
+});
+
+for (const reversed of [false, true]) {
+ test(`tied legacy surface observations retain distinct rows and frozen IDs (reversed=${reversed})`, async (t) => {
+ const normal = await fixture(t, "deep");
+ const recovered = await fixture(t, "deep");
+ const surfaces = ["First legacy surface", "Second legacy surface"].map(
+ (label) => ({
+ id: "legacy-shared",
+ label,
+ disposition: "needs_follow_up",
+ receiptRefs: [],
+ }),
+ );
+ if (reversed) surfaces.reverse();
+ const deferred = [
+ {
+ id: "review",
+ reason: "Review remains.",
+ 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 dateDraftFiles(recovered.root, 100);
+ const result = await recoverAndFinalize(normal, recovered, [], true, true);
+ const rows = result.recoveredCoverage.surfaces as Array<{
+ id: string;
+ label: string;
+ }>;
+ assert.deepEqual(
+ rows.map((row) => row.label).sort(),
+ surfaces.map((row) => row.label).sort(),
+ );
+ assert.equal(new Set(rows.map((row) => row.id)).size, 2);
+ assert.deepEqual(result.warnings, []);
+ await draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ recovered.draft(),
+ false,
+ );
+ await dateDraftFiles(recovered.root, 100);
+ const replay = await recoverAndFinalize(normal, recovered, [], true, true);
+ assert.deepEqual(replay.recoveredCoverage.surfaces, rows);
+ });
+}
+
+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 [unchanged, removed, added] = [
+ "Unchanged",
+ "Removed",
+ "Added",
+ ].map((title) =>
+ finding(
+ title,
+ authored ? { identity: { anchor: title.toLowerCase() } } : {},
+ ),
+ );
+ for (const f of [normal, recovered]) {
+ await f.write({
+ ...f.draft({}, true),
+ findings: [unchanged, removed],
+ });
+ 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],
+ });
+ const input = {
+ ...recovered.draft({}, true),
+ findings: [unchanged, added],
+ };
+ if (cut === "raw input")
+ await draftApi.saveScanDraftCheckpoint(
+ recovered.context,
+ input,
+ false,
+ );
+ else
+ await interruptDraftWrite(
+ path.join(recovered.root, "findings.json"),
+ () => recovered.write(input),
+ );
+ for (const name of await readdir(checkpoints))
+ if (!original.has(name))
+ await utimes(path.join(checkpoints, name), time, time);
+ if (cut === "committed head")
+ await utimes(
+ path.join(recovered.root, "checkpoint-head.json"),
+ time,
+ time,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ for (const row of result.recovered)
+ assert.deepEqual(
+ (row.evidenceProvenance as { previousFindings: unknown[] })
+ .previousFindings,
+ [],
+ );
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+ }
+}
+
+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 parentFinding = finding("Parent review", {
+ locations: [{ path: "src/parent.py", startLine: 1 }],
+ });
+ if (parentState === "partial") {
+ await recovered.write({
+ ...recovered.draft(),
+ findings: [parentFinding],
+ });
+ await dateDraftFiles(recovered.root, 100);
+ }
+ const rows = ["Assigned", "Unconsumed"].map((title) =>
+ finding(title, {
+ locations: [{ path: `src/${title.toLowerCase()}.py`, startLine: 1 }],
+ }),
+ );
+ const workers: Record<string, unknown>[] = [];
+ for (const [index, row] of rows.entries()) {
+ const id = `worker-${index + 1}`;
+ const root = path.join(
+ recovered.root,
+ "artifacts/deep_discovery/workers",
+ id,
+ "output",
+ );
+ await mkdir(root, { recursive: true });
+ const worker = draftFixture(root, "worker");
+ await worker.write({ ...worker.draft({}, true), findings: [row] });
+ await dateDraftFiles(root, 101 + index);
+ workers.push({
+ id,
+ kind: "discovery",
+ status: "succeeded",
+ completed_at: `2026-10-11T20:00:0${index}Z`,
+ artifact_dir: root,
+ result_manifest_path: path.join(root, "result.json"),
+ attempt: 1,
+ });
+ }
+ const reducer = await importSource("../src/artifact-deep-reducer.ts", {
+ absWorkingDir: import.meta.dirname,
+ });
+ const root = path.join(
+ recovered.root,
+ "artifacts/deep_discovery/dedup/reducer-1/output",
+ );
+ await mkdir(root, { recursive: true });
+ const receipt = await reducer.recordCodexSecurityDeepReduction(
+ {
+ root,
+ repoRoot: recovered.root,
+ scanId: recovered.context.scanId,
+ layout: "reducer",
+ deepReducer: {
+ scanRoot: recovered.root,
+ claimedWorkers: [
+ { id: workers[0].id, resultPath: workers[0].result_manifest_path },
+ ],
+ },
+ },
+ { scanId: recovered.context.scanId, complete: true, findings: [rows[0]] },
+ );
+ assert.deepEqual(receipt.consumedWorkerIds, ["worker-1"]);
+ await dateDraftFiles(root, 103);
+ workers.push({
+ id: "reducer-1",
+ kind: "dedup",
+ status: "succeeded",
+ completed_at: "2026-10-11T20:00:02Z",
+ artifact_dir: root,
+ result_manifest_path: path.join(root, "result.json"),
+ attempt: 1,
+ });
+ const reduced = JSON.parse(
+ await readFile(path.join(root, "result.json"), "utf8"),
+ );
+ const findings =
+ parentState === "terminal"
+ ? [parentFinding]
+ : [
+ ...(parentState === "partial" ? [parentFinding] : []),
+ ...reduced.findings,
+ {
+ ...rows[1],
+ provenance: { ...rows[1].provenance, workerId: "worker-2" },
+ },
+ ];
+ await normal.write({ ...normal.draft({}, true), findings });
+ if (parentState === "terminal") {
+ await recovered.write({ ...recovered.draft({}, true), findings });
+ for (const name of [
+ "findings.json",
+ "coverage.json",
+ "scan-manifest.json",
+ "checkpoint-head.json",
+ ])
+ await utimes(path.join(recovered.root, name), 104, 104);
+ await dateDraftFiles(path.join(recovered.root, "checkpoints"), 104);
+ }
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ true,
+ true,
+ true,
+ );
+ const byEvidence = (rows: RecoveredFinding[]) =>
+ new Map(rows.map((row) => [row.title, row]));
+ assert.equal(
+ result.normal.length,
+ parentState === "terminal" ? 1 : parentState === "partial" ? 3 : 2,
+ );
+ assert.deepEqual(byEvidence(result.recovered), byEvidence(result.normal));
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+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");
+ await interruptDraftAfterRaw(() =>
+ recovered.write({
+ ...recovered.draft({}, true),
+ findings: [finding("Abandoned terminal draft")],
+ }),
+ );
+ 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 dateDraftFiles(recovered.root, 200);
+ for (const name of abandoned)
+ await utimes(
+ path.join(recovered.root, "checkpoints", name),
+ abandonedTime,
+ abandonedTime,
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ true,
+ );
+ assert.deepEqual(result.recovered, result.normal);
+ assert.equal(result.recovered[0]!.title, "Accepted replacement");
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+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");
+ for (const f of [normal, recovered]) {
+ await f.write({
+ ...f.draft({}, true),
+ findings: [finding("Earlier accepted result")],
+ });
+ await dateDraftFiles(f.root, 100);
+ }
+ await normal.write({
+ ...normal.draft({}, true),
+ findings: [
+ finding("File authored update", {
+ identity: { anchor: "file-authored" },
+ locations: [{ path: "src/updated.py", startLine: 8 }],
+ }),
+ ],
+ });
+ for (const name of ["scan-manifest.json", "findings.json", "coverage.json"]) {
+ await copyFile(
+ path.join(normal.root, name),
+ path.join(recovered.root, name),
+ );
+ await utimes(path.join(recovered.root, name), 300, 300);
+ }
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ true,
+ );
+ assert.deepEqual(result.recovered, result.normal);
+ assert.equal(result.recovered[0]!.title, "File authored update");
+ assert.deepEqual(result.warnings, []);
+});
+
+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 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 dateDraftFiles(f.root, 100);
+ }
+ const revised = findings.map((row) => ({
+ ...row,
+ summary: `Updated ${row.title}`,
+ }));
+ await normal.write({ ...normal.draft({}, true), findings: revised });
+ await interruptDraftAfterRaw(() =>
+ recovered.write({ ...recovered.draft({}, true), findings: revised }),
+ );
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ true,
+ );
+ assert.equal(result.recovered.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(
+ result.preservedIdentities[1],
+ result.preservedIdentities[0],
+ );
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+for (const [metadata, preservedIdentity] of Object.entries({
+ omitted: undefined,
+ annotation: "Synthetic preserved annotation",
+ authored: { anchor: "same", description: "Earlier authored identity" },
+})) {
+ 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 identity = { anchor: "same", description: "Authored identity" };
+ const findings = ["First report", "Second report"].map((title, index) =>
+ finding(title, {
+ identity,
+ locations: [{ path: "src/example.py", startLine: index + 1 }],
+ provenance: {
+ source: "local_plugin",
+ workerId: "reviewer",
+ candidateId: `candidate-${index}`,
+ ...(preserved ? { preservedIdentity } : {}),
+ },
+ }),
+ );
+ await normal.write({ ...normal.draft({}, true), findings });
+ await interruptDraftAfterRaw(() =>
+ recovered.write({ ...recovered.draft({}, true), findings }),
+ );
+ await dateDraftFiles(recovered.root, 100);
+ const workers = [];
+ if (workerUpdate !== "none") {
+ const workerRoot = path.join(recovered.root, "reviewer");
+ await mkdir(workerRoot);
+ const worker = draftFixture(workerRoot, "worker");
+ const revised = {
+ ...findings[1]!,
+ ...(workerUpdate === "revised"
+ ? {
+ summary: "Revised synthetic evidence.",
+ severity: { level: "high" },
+ }
+ : {}),
+ };
+ await worker.write({ ...worker.draft({}, true), findings: [revised] });
+ await dateDraftFiles(workerRoot, 200);
+ workers.push({
+ id: "reviewer",
+ kind: "discovery",
+ artifact_dir: workerRoot,
+ result_manifest_path: path.join(workerRoot, "result.json"),
+ attempt: 1,
+ });
+ await normal.write({
+ ...normal.draft({}, true),
+ findings: [findings[0]!, revised],
+ });
+ }
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ workers,
+ true,
+ true,
+ );
+ assert.equal(result.normal.length, 2);
+ assert.equal(result.recovered.length, 2);
+ assert.deepEqual(result.recovered, result.normal);
+ assert.deepEqual(result.preservedIdentities, [
+ [
+ preserved ? preservedIdentity : null,
+ preserved ? preservedIdentity : identity,
+ ],
+ [
+ preserved ? preservedIdentity : null,
+ preserved ? preservedIdentity : identity,
+ ],
+ ]);
+ assert.deepEqual(result.warnings, []);
+ });
+ }
+}
+
+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 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 dateDraftFiles(recovered.root, 100);
+ if (cut === "pending") {
+ const revised = { ...second, summary: "Revised second publication" };
+ await normal.write({ ...normal.draft({}, true), findings: [revised] });
+ await interruptDraftAfterRaw(() =>
+ recovered.write({ ...recovered.draft({}, true), findings: [revised] }),
+ );
+ }
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ true,
+ );
+ assert.deepEqual(result.recovered, result.normal);
+ assert.equal(result.recovered.length, 1);
+ assert.deepEqual(result.warnings, []);
+ });
+}
+
+test("a backdated legacy terminal retains both possible publication histories", async (t) => {
+ const normal = await fixture(t, "deep"),
+ recovered = await fixture(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 dateDraftFiles(f.root, 200);
+ }
+ await normal.write({
+ ...normal.draft({}, true),
+ findings: [accepted, unordered],
+ });
+ // Older writers did not record whether this input preceded or followed the head.
+ const contents = JSON.stringify({
+ ...recovered.draft({}, true),
+ findings: [unordered],
+ });
+ const raw = path.join(
+ recovered.root,
+ "checkpoints",
+ createHash("sha256").update(contents).digest("hex") + ".json",
+ );
+ await writeFile(raw, contents);
+ await utimes(raw, 100, 100);
+ const result = await recoverAndFinalize(
+ normal,
+ recovered,
+ [],
+ true,
+ true,
+ true,
+ );
+ const byTitle = (rows: RecoveredFinding[]) =>
+ new Map(rows.map((row) => [row.title, row]));
+ assert.equal(result.recovered.length, 2);
+ assert.deepEqual(byTitle(result.recovered), byTitle(result.normal));
+ assert.deepEqual(result.warnings, []);
+});
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_publication_integration.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_publication_integration.ts
index d9fd6c882..c208b9957 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_publication_integration.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_publication_integration.ts
@@ -675,7 +675,15 @@ async function assertInterleavedProgressRetained(fixture: PublicationFixture) {
(name) => !(name in before.checkpoints),
);
assert.equal(added.length, 1);
- assert.deepEqual(JSON.parse(after.checkpoints[added[0]]), progress);
+ const { publication, ...checkpoint } = JSON.parse(
+ after.checkpoints[added[0]],
+ );
+ assert.deepEqual(checkpoint, progress);
+ const previousHead = JSON.parse(before.files["checkpoint-head.json"]);
+ assert.deepEqual(publication, {
+ previousCheckpoint: previousHead.checkpoint ?? null,
+ previousInputCheckpoint: previousHead.inputCheckpoint ?? null,
+ });
}
async function createFixture(t: TestContext, paths: FixturePaths = {}) {
diff --git a/plugins/codex-security/plugin-files.json b/plugins/codex-security/plugin-files.json
index 62c6caeb4..146d8899a 100644
--- a/plugins/codex-security/plugin-files.json
+++ b/plugins/codex-security/plugin-files.json
@@ -11,22 +11,22 @@
"examples/completed-scan/findings.json",
"examples/completed-scan/report.md",
"examples/completed-scan/scan-manifest.json",
+ "mcp/helpers.mjs",
+ "mcp/helpers.mjs.br.part-000",
"mcp/native/COPYRIGHT-library.html",
"mcp/native/THIRD_PARTY_NOTICES.txt",
"mcp/native/darwin-arm64/unix.node",
"mcp/native/darwin-x64/unix.node",
- "mcp/native/linux-arm64-gnu/unix.node",
- "mcp/native/linux-arm64-musl/unix.node",
- "mcp/native/linux-x64-gnu/unix.node",
- "mcp/native/linux-x64-musl/unix.node",
"mcp/native/licenses/Apache-2.0.txt",
"mcp/native/licenses/BSD-2-Clause.txt",
"mcp/native/licenses/MIT.txt",
"mcp/native/licenses/Unicode-3.0.txt",
+ "mcp/native/linux-arm64-gnu/unix.node",
+ "mcp/native/linux-arm64-musl/unix.node",
+ "mcp/native/linux-x64-gnu/unix.node",
+ "mcp/native/linux-x64-musl/unix.node",
"mcp/native/win32-arm64/windows.node",
"mcp/native/win32-x64/windows.node",
- "mcp/helpers.mjs",
- "mcp/helpers.mjs.br.part-000",
"mcp/permission-profile-preflight.mjs",
"mcp/server.mjs",
"mcp/server.mjs.br.part-000",
@@ -109,14 +109,14 @@
"scripts/workbench_validation.py",
"shared/workbench-history-repairs.json",
"shared/workbench-migrations.json",
- "skills/attack-path-analysis/SKILL.md",
- "skills/attack-path-analysis/agents/openai.yaml",
- "skills/attack-path-analysis/references/attack-path-facts.md",
- "skills/attack-path-analysis/references/severity-policy.md",
"skills/assess-patch-risk/SKILL.md",
"skills/assess-patch-risk/agents/openai.yaml",
"skills/assess-patch-risk/references/risk-rubric.md",
"skills/assess-patch-risk/references/windows-validation.md",
+ "skills/attack-path-analysis/SKILL.md",
+ "skills/attack-path-analysis/agents/openai.yaml",
+ "skills/attack-path-analysis/references/attack-path-facts.md",
+ "skills/attack-path-analysis/references/severity-policy.md",
"skills/cloud-findings/SKILL.md",
"skills/cloud-findings/agents/openai.yaml",
"skills/deep-security-scan/SKILL.md",
diff --git a/plugins/codex-security/scripts/finalize_scan_contract.py b/plugins/codex-security/scripts/finalize_scan_contract.py
index 02f027328..0917daf8c 100644
--- a/plugins/codex-security/scripts/finalize_scan_contract.py
+++ b/plugins/codex-security/scripts/finalize_scan_contract.py
@@ -203,11 +203,7 @@ def _read_saved_threat_model(
if filename == "scan-manifest.json"
else manifest
)
- if (
- validate_seal
- and filename == "scan-manifest.json"
- and (scan.get("sealedAt") is not None or scan.get("artifacts"))
- ):
+ if validate_seal and filename == "scan-manifest.json" and manifest_is_sealed(scan):
if "threatModel" not in scan:
_validate_manifest(manifest)
recorded_paths = {
@@ -2867,13 +2863,20 @@ def csv_cell(value: Any) -> Any:
return value
+def _has_identity_text(value: Any) -> bool:
+ # Match JavaScript String.trim when selecting optional identity metadata.
+ return isinstance(value, str) and bool(
+ value.strip(
+ "\u0009\u000a\u000b\u000c\u000d\u0020\u00a0\u1680"
+ "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a"
+ "\u2028\u2029\u202f\u205f\u3000\ufeff"
+ )
+ )
+
+
def finding_candidate_id(finding: dict[str, Any]) -> str | None:
provenance = finding.get("provenance")
- if (
- isinstance(provenance, dict)
- and isinstance(value := provenance.get("candidateId"), str)
- and value.strip()
- ):
+ if isinstance(provenance, dict) and _has_identity_text(value := provenance.get("candidateId")):
return value
extensions = finding.get("extensions")
if not isinstance(extensions, dict):
@@ -2882,12 +2885,29 @@ def finding_candidate_id(finding: dict[str, Any]) -> str | None:
(
value
for field in ("candidateId", "reportId", "ledgerRowId")
- if isinstance(value := extensions.get(field), str) and value.strip()
+ if _has_identity_text(value := extensions.get(field))
),
None,
)
+def _csv_candidate_id(finding: dict[str, Any]) -> str | None:
+ candidate_id = finding_candidate_id(finding)
+ if candidate_id is not None:
+ return candidate_id
+ # Preserve literal CSV metadata, such as FEFF, that is not a canonical identity.
+ for metadata, fields in (
+ (finding.get("provenance"), ("candidateId",)),
+ (finding.get("extensions"), ("candidateId", "reportId", "ledgerRowId")),
+ ):
+ if isinstance(metadata, dict):
+ for field in fields:
+ value = metadata.get(field)
+ if isinstance(value, str) and value.strip():
+ return value
+ return None
+
+
def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
return (
"occurrence_id",
@@ -2918,7 +2938,7 @@ def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) ->
(
csv_cell(finding["occurrenceId"]),
csv_cell(finding["findingId"]),
- *((csv_cell(finding_candidate_id(finding)),) if deep_scan else ()),
+ *((csv_cell(_csv_candidate_id(finding)),) if deep_scan else ()),
csv_cell(finding["title"]),
csv_cell(finding["summary"]),
csv_cell(finding["severity"]["level"]),
@@ -2955,6 +2975,30 @@ def build_findings_export(
return build_csv_projection(findings, coverage)
+def _is_sealed_artifact(scan_dir: Path, relative_output: str, artifact_paths: list[str]) -> bool:
+ try:
+ output_metadata = (scan_dir / relative_output).stat(follow_symlinks=False)
+ except FileNotFoundError:
+ output_metadata = None
+ except OSError as exc:
+ raise ContractError(f"{relative_output}: unable to inspect export output") from exc
+ for artifact_path in artifact_paths:
+ if artifact_path == relative_output:
+ return True
+ if output_metadata is None:
+ continue
+ descriptor = open_scan_local_file_descriptor(
+ scan_dir, artifact_path, f"sealed artifact {artifact_path}"
+ )
+ try:
+ artifact_metadata = os.fstat(descriptor)
+ finally:
+ os.close(descriptor)
+ if os.path.samestat(output_metadata, artifact_metadata):
+ return True
+ return False
+
+
def write_export_output(scan_dir: Path, output: Path, export_format: str, contents: bytes) -> None:
output_paths = {**EXPORT_PATHS, "md": THREAT_MODEL_EXPORT_PATH}
if export_format not in output_paths:
@@ -3005,40 +3049,25 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
for index, artifact in enumerate(artifacts)
if isinstance(artifact, dict)
]
- try:
- output_metadata = output.stat(follow_symlinks=False)
- except FileNotFoundError:
- output_metadata = None
- except OSError as exc:
- raise ContractError(f"{relative_output}: unable to inspect export output") from exc
- for artifact_path in artifact_paths:
- if artifact_path == relative_output:
- raise SealedArtifactError(
- f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
- )
- if output_metadata is None:
- continue
- descriptor = open_scan_local_file_descriptor(
- scan_dir, artifact_path, f"sealed artifact {artifact_path}"
+ if _is_sealed_artifact(scan_dir, relative_output, artifact_paths):
+ raise SealedArtifactError(
+ f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
)
- try:
- artifact_metadata = os.fstat(descriptor)
- finally:
- os.close(descriptor)
- if os.path.samestat(output_metadata, artifact_metadata):
- raise SealedArtifactError(
- f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
- )
write_scan_local_bytes(
scan_dir, relative_output, contents, owner_read_write=export_format == "md"
)
def _write_sarif_projection_if_possible(
- scan_dir: Path, source_root: Path | None = None, schema_dir: Path | None = None
+ scan_dir: Path,
+ source_root: Path | None = None,
+ schema_dir: Path | None = None,
+ *,
+ sealed_paths: list[str],
) -> None:
try:
- write_sarif_projection(scan_dir, source_root, schema_dir)
+ if not _is_sealed_artifact(scan_dir, "exports/results.sarif", sealed_paths):
+ write_sarif_projection(scan_dir, source_root, schema_dir)
except (ContractError, OSError) as error:
print(
f"codex-security: warning: automatic SARIF export failed: {error}. "
@@ -3058,6 +3087,10 @@ class PreparedScanFinalization(NamedTuple):
warnings: list[str]
+def manifest_is_sealed(scan: dict[str, Any]) -> bool:
+ return scan.get("sealedAt") is not None or scan.get("artifacts") not in (None, [])
+
+
def _prepare_scan_finalization(
scan_dir: Path,
schema_dir: Path | None = None,
@@ -3082,7 +3115,7 @@ def _prepare_scan_finalization(
scan = _require_dict(manifest, "scan", "manifest")
if scan.get("sealedAt") is None and scan.get("artifacts") == []:
del scan["artifacts"]
- was_sealed = scan.get("sealedAt") is not None or scan.get("artifacts") is not None
+ was_sealed = manifest_is_sealed(scan)
if not was_sealed:
_populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
_validate_contract_refs(scan)
@@ -3262,12 +3295,19 @@ def _write_prepared_scan_finalization(
)
_write_scan_local_json(scan_dir, "findings.json", prepared.findings)
_write_scan_local_json(scan_dir, "coverage.json", prepared.coverage)
- write_scan_local_bytes(scan_dir, "report.md", prepared.report_markdown_bytes)
- _remove_scan_local_file_if_exists(scan_dir, "report.html")
+ sealed_paths = (
+ [artifact["path"] for artifact in scan["artifacts"]] if prepared.was_sealed else []
+ )
+ if not _is_sealed_artifact(scan_dir, "report.md", sealed_paths):
+ write_scan_local_bytes(scan_dir, "report.md", prepared.report_markdown_bytes)
+ if not _is_sealed_artifact(scan_dir, "report.html", sealed_paths):
+ _remove_scan_local_file_if_exists(scan_dir, "report.html")
if not prepared.was_sealed:
_write_scan_local_json(scan_dir, "scan-manifest.json", prepared.manifest)
_validate_existing_seal(scan_dir, scan)
- _write_sarif_projection_if_possible(scan_dir, source_root, prepared.schema_dir)
+ _write_sarif_projection_if_possible(
+ scan_dir, source_root, prepared.schema_dir, sealed_paths=sealed_paths
+ )
warning = write_threat_model_projection_if_possible(scan_dir, prepared.manifest)
if (
warning is not None
diff --git a/plugins/codex-security/scripts/workbench/retained_coverage.py b/plugins/codex-security/scripts/workbench/retained_coverage.py
index fdf1a95f8..f5f2a26c9 100644
--- a/plugins/codex-security/scripts/workbench/retained_coverage.py
+++ b/plugins/codex-security/scripts/workbench/retained_coverage.py
@@ -1,18 +1,19 @@
-"""Reconcile retained coverage observations during saved-result recovery."""
+"""Retain semantic scan drafts without rerunning analysis or changing run state."""
from __future__ import annotations
import copy
-import hashlib
-import json
import os
import re
+import unicodedata
+from collections import Counter
from collections.abc import Callable, Iterator
from pathlib import Path
from typing import Any
from finalize_scan_contract import (
ContractError,
+ _has_identity_text,
_read_json,
_require_portable_relative_path,
_require_str,
@@ -21,53 +22,94 @@ from finalize_scan_contract import (
finding_candidate_id,
open_scan_local_file_descriptor,
)
-from workbench.saved_coverage import _project_worker_coverage_row, _saved_coverage_id
+from workbench.saved_coverage import (
+ _project_worker_coverage_row,
+ _saved_coverage_id,
+)
+from workbench.saved_sources import (
+ _digest,
+ _encoded,
+)
+_FINDING_IDENTITY_SCHEMA = _read_json(
+ Path(__file__).resolve().parents[2] / "schemas" / "findings.schema.json"
+)["properties"]["findings"]["items"]["properties"]["identity"]
-def _encoded(value: Any) -> bytes:
- return json.dumps(
- value, ensure_ascii=True, allow_nan=False, sort_keys=True, separators=(",", ":")
- ).encode()
+import hashlib
+from pathlib import PurePosixPath
-def _digest(value: Any) -> str:
- return hashlib.sha256(_encoded(value)).hexdigest()
+from finalize_scan_contract import (
+ _finding_strength,
+ _recover_unsealed_coverage,
+ _recover_unsealed_findings,
+ _require_safe_json_value,
+ _validate_current_findings,
+ write_scan_local_bytes,
+)
+from workbench.saved_coverage import _prepare_worker_coverage_recovery
+from workbench.saved_sources import (
+ _capture_parent_observation,
+ _capture_saved_source,
+ _checkpoint_head_directory,
+ _checkpoint_paths,
+ _freeze_source_times,
+ _frozen_source_times,
+ _is_source_order_snapshot,
+ _latest_successful_reducer,
+ _parent_publication_ancestors,
+ _read_saved_parent_result,
+ _read_saved_result,
+ _worker_outputs,
+)
+from workbench_target import committed_diff_snapshot_digest
+from workbench_validation import path_within_scope
-def _finding_key(finding: dict[str, Any]) -> str:
+def _finding_identity(finding: dict[str, Any]) -> Any:
+ provenance = finding.get("provenance")
+ if isinstance(provenance, dict) and "preservedIdentity" in provenance:
+ try:
+ _validate_schema_node(
+ provenance["preservedIdentity"], _FINDING_IDENTITY_SCHEMA, "finding.identity"
+ )
+ except ContractError:
+ pass
+ else:
+ return provenance["preservedIdentity"]
+ return finding.get("identity")
+
+
+def _finding_key(finding: dict[str, Any], owner: str | None = None) -> str:
# Wording and evidence may improve between checkpoints; distinct source locations
# must not collide merely because two workers chose the same semantic identity.
provenance = finding.get("provenance")
- identity = (
- provenance.get("preservedIdentity", finding.get("identity"))
- if isinstance(provenance, dict)
- else finding.get("identity")
- )
+ identity = _finding_identity(finding)
if not isinstance(identity, dict):
normalized = dict(finding)
normalized.pop("identity", None)
_ensure_finding_identity(normalized)
identity = normalized["identity"]
+ owner = provenance.get("workerId", owner) if isinstance(provenance, dict) else owner
+ parts = [finding.get("ruleId"), identity, _finding_locations(finding)]
+ if owner is not None and finding_candidate_id(finding):
+ parts.append(owner)
+ return _digest(parts)
+
+
+def _finding_locations(finding: dict[str, Any]) -> list[tuple[Any, Any, Any]]:
locations = finding.get("locations", [])
- if not isinstance(locations, list):
- locations = []
- return _digest(
- [
- finding.get("ruleId"),
- identity,
- sorted(
- (
- (
- location.get("path"),
- location.get("startLine"),
- location.get("endLine", location.get("startLine")),
- )
- for location in locations
- if isinstance(location, dict)
- ),
- key=_encoded,
- ),
- ]
+ return sorted(
+ (
+ (
+ location.get("path"),
+ location.get("startLine"),
+ location.get("endLine", location.get("startLine")),
+ )
+ for location in (locations if isinstance(locations, list) else [])
+ if isinstance(location, dict)
+ ),
+ key=_encoded,
)
@@ -75,12 +117,7 @@ def _worker_candidate_key(
worker_id: str, candidate_id: str, finding: dict[str, Any]
) -> tuple[str, str, Any, Any, Any]:
"""Identify one worker-local candidate without merging unrelated locations."""
- provenance = finding.get("provenance")
- identity = (
- provenance.get("preservedIdentity", finding.get("identity"))
- if isinstance(provenance, dict)
- else finding.get("identity")
- )
+ identity = _finding_identity(finding)
if not isinstance(identity, dict):
normalized = dict(finding)
_ensure_finding_identity(normalized)
@@ -99,19 +136,103 @@ def _finding_content(finding: dict[str, Any]) -> dict[str, Any]:
}
-def _ensure_finding_identity(finding: Any, *, candidate_only: bool = False) -> None:
- if not isinstance(finding, dict) or "identity" in finding:
- return
- if candidate_only and not finding_candidate_id(finding):
- return
- extensions = finding.get("extensions")
- source = str(
- (extensions.get("candidateId") if isinstance(extensions, dict) else None)
- or finding.get("title")
- or "finding"
+def _identity_candidate(finding: dict[str, Any]) -> str | None:
+ return next(
+ (
+ value
+ for section in (finding.get("extensions"), finding.get("provenance"))
+ if isinstance(section, dict) and _has_identity_text(value := section.get("candidateId"))
+ ),
+ None,
+ )
+
+
+def _ensure_finding_identity(finding: Any) -> None:
+ _ensure_finding_identities([finding])
+
+
+def _semantic_identifier(value: str, fallback: str) -> str:
+ normalized = re.sub(r"[\u0300-\u036f]", "", unicodedata.normalize("NFKD", value))
+ identifier = re.sub(r"[^a-z0-9._/-]+", "-", normalized.lower())
+ return re.sub(r"^[^a-z0-9]+|-+$", "", identifier) or fallback
+
+
+def _semantic_identity_key(finding: dict[str, Any], identity: Any = None) -> bytes:
+ identity = finding.get("identity") if identity is None else identity
+ if isinstance(identity, dict):
+ identity = {key: identity.get(key) for key in ("anchor", "instance")}
+ return _encoded([finding.get("ruleId"), identity])
+
+
+def _ensure_finding_identities(findings: list[Any], *, deep: bool = False) -> None:
+ """Use the same candidate, anchor and sibling rules as draft publication."""
+ anchors: dict[int, Any] = {}
+ for index, finding in enumerate(findings):
+ if not isinstance(finding, dict):
+ continue
+ identity = finding.get("identity")
+ if "identity" in finding:
+ anchors[index] = identity.get("anchor") if isinstance(identity, dict) else None
+ continue
+ candidate = _identity_candidate(finding)
+ anchors[index] = _semantic_identifier(
+ candidate or str(finding.get("title") or "finding"), f"finding-{index + 1}"
+ )
+ counts = Counter(
+ _digest([findings[index].get("ruleId"), anchor]) for index, anchor in anchors.items()
)
- anchor = re.sub(r"[^a-z0-9._/-]+", "-", source.lower()).strip("._/-") or "finding"
- finding["identity"] = {"anchor": anchor}
+
+ authored = {
+ _semantic_identity_key(finding)
+ for finding in findings
+ if isinstance(finding, dict) and "identity" in finding
+ }
+ generated = []
+ for index, anchor in anchors.items():
+ finding = findings[index]
+ if "identity" in finding:
+ continue
+ identity = {"anchor": anchor}
+ extensions = finding.get("extensions")
+ sibling = next(
+ (
+ value
+ for field in ("reportId", "ledgerRowId")
+ if isinstance(extensions, dict)
+ and _has_identity_text(value := extensions.get(field))
+ ),
+ None,
+ )
+ if sibling or counts[_digest([finding.get("ruleId"), anchor])] > 1:
+ identity["instance"] = _semantic_identifier(
+ sibling or str(finding.get("title") or "finding"), f"finding-{index + 1}"
+ )
+ finding["identity"] = identity
+ generated.append(finding)
+
+ reserved = {
+ _semantic_identity_key(finding) for finding in findings if isinstance(finding, dict)
+ }
+ used = set() if deep else authored.copy()
+ generated_ids = {id(finding) for finding in generated}
+ for finding in findings if deep else generated:
+ key = _semantic_identity_key(finding)
+ if key in used or (id(finding) in generated_ids and key in authored):
+ identity = finding["identity"]
+ if id(finding) not in generated_ids:
+ finding.setdefault("provenance", {}).setdefault(
+ "preservedIdentity", copy.deepcopy(identity)
+ )
+ base_instance = identity.get("instance", "saved")
+ suffix = 2
+ while True:
+ identity["instance"] = f"{base_instance}-{suffix}"
+ key = _semantic_identity_key(finding)
+ if key not in reserved:
+ reserved.add(key)
+ break
+ suffix += 1
+ used.add(key)
def _retained_findings(finding: dict[str, Any]) -> Iterator[dict[str, Any]]:
@@ -164,6 +285,10 @@ def _coverage_rows(coverage: dict[str, Any], field: str) -> list[Any]:
return rows if isinstance(rows, list) else []
+def _deferred_rows(coverage: dict[str, Any]) -> list[Any]:
+ return _coverage_rows(coverage, "deferred")
+
+
def _resolved_deferred_rows(draft: dict[str, Any], schema: dict[str, Any]) -> list[dict[str, Any]]:
if draft.get("complete") is False:
return []
@@ -216,6 +341,19 @@ def _merge_tied_parent_observations(
return merged
+def _deferred_candidate_id(
+ row: dict[str, Any],
+ owner: str | None,
+ ambiguous_deferred: set[tuple[str | None, str]],
+) -> str | None:
+ identity = row.get("candidateId") or row.get("id")
+ if not isinstance(identity, str):
+ return None
+ if (owner, identity) in ambiguous_deferred and not _has_candidate_metadata(row):
+ return None
+ return identity
+
+
def _inherit_coverage_sources(
row: Any,
originals: list[Any],
@@ -474,7 +612,7 @@ def _generic_surface_updates(
id(row)
for _, row in matches
if reopening
- or row.get("disposition") in {"needs_follow_up", surface.get("disposition")}
+ or row.get("disposition") in ("needs_follow_up", surface.get("disposition"))
}
replaced.update(replaced_sources)
existing = next(
@@ -498,14 +636,2526 @@ def _generic_surface_updates(
return replaced, updates
-def _deferred_candidate_id(
- row: dict[str, Any],
- owner: str | None,
- ambiguous_deferred: set[tuple[str | None, str]],
-) -> str | None:
- identity = row.get("candidateId") or row.get("id")
- if not isinstance(identity, str):
+def merge_saved_results(
+ scan_dir: Path,
+ scan_id: str,
+ binding: dict[str, Any],
+ workers: list[Any],
+ warnings: list[str],
+ *,
+ stopped: bool,
+ reason: str,
+ scan_mode: str | None = None,
+ frozen_source_digests: dict[str, str] | None = None,
+ allow_frozen_legacy_parent: bool = False,
+ frozen_model_source: str | None = None,
+ selected_model_source: list[str] | None = None,
+ finding_scope: list[tuple[str, bool]] | None = None,
+ preserve_canonical_parent: bool = False,
+ project_worker_coverage: bool = False,
+ created_paths: set[str] | None = None,
+ current_contract: bool = False,
+) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None:
+ """Read only bound parent/worker files; return an unsealed loss-preserving union."""
+ initial_warnings = set(warnings)
+ parent_context: dict[str, str] = {}
+ try:
+ source_times = _frozen_source_times(
+ scan_dir, scan_id, frozen_source_digests or {}, parent_context
+ )
+ except (ContractError, OSError, ValueError) as exc:
+ raise ContractError("Frozen stopped-scan checkpoint set is incomplete.") from exc
+ parent: dict[str, Any] | None = None
+ parent_manifest: dict[str, Any] | None = None
+ parent_is_canonical = False
+ parent_modified = 0
+ if frozen_source_digests is None or allow_frozen_legacy_parent:
+ try:
+ parent_manifest, parent = _read_saved_parent_result(scan_dir, scan_id)
+ # Without an accepted head, file-authored coverage is a full replacement.
+ parent_modified = (scan_dir / "coverage.json").lstat().st_mtime_ns
+ parent_is_canonical = True
+ except (ContractError, OSError, ValueError) as exc:
+ if not stopped:
+ raise
+ if (scan_dir / "scan-manifest.json").exists():
+ warnings.append(f"Could not read the saved parent draft: {exc}")
+ parent_manifest = None
+ parent = None
+ if parent_manifest is not None and parent is not None and not preserve_canonical_parent:
+ parent_scan = parent_manifest["scan"]
+ try:
+ _, _, head_modified = _read_saved_result(scan_dir, "checkpoint-head.json", scan_id)
+ except (ContractError, OSError, ValueError):
+ head_modified = None
+ if head_modified is not None:
+ # A partial tool publication must not outrank its accepted head.
+ parent_modified = min(
+ (scan_dir / name).lstat().st_mtime_ns
+ for name in ("findings.json", "coverage.json", "scan-manifest.json")
+ )
+ if not parent_scan.get("sealedAt") or allow_frozen_legacy_parent:
+ payload = _encoded(parent)
+ parent_digest = hashlib.sha256(payload).hexdigest()
+ parent_checkpoint = f"checkpoints/{parent_digest}.json"
+ parent_context["canonical"] = parent_checkpoint
+ parent_context["canonicalObservedAtNs"] = str(parent_modified)
+ checkpoint_path = scan_dir / parent_checkpoint
+ if not checkpoint_path.exists():
+ if created_paths is not None and not os.path.lexists(checkpoint_path):
+ created_paths.add(parent_checkpoint)
+ write_scan_local_bytes(scan_dir, parent_checkpoint, payload)
+ # A recovery copy must not appear newer than the review it copies.
+ os.utime(checkpoint_path, ns=(parent_modified, parent_modified))
+ captured = (
+ _capture_saved_source(
+ scan_dir, "checkpoint-head.json", scan_id, created_paths=created_paths
+ )
+ if head_modified is not None
+ else _capture_parent_observation(
+ scan_dir,
+ checkpoint_path.name,
+ parent_modified,
+ allow_frozen_legacy_parent,
+ created_paths=created_paths,
+ )
+ )
+ if head_modified is not None or allow_frozen_legacy_parent:
+ parent_context["head"] = next(iter(captured))
+ if frozen_source_digests is not None:
+ frozen_source_digests = {
+ **frozen_source_digests,
+ parent_checkpoint: parent_digest,
+ **{path: value[0] for path, value in captured.items()},
+ }
+
+ sources: list[tuple[str, dict[str, Any], str | None]] = []
+ parent_preserved_sources: dict[str, str] = {}
+ source_digests: dict[str, str] = {}
+ source_order: dict[str, tuple[int, int]] = {}
+ worker_attempts: dict[str, tuple[str, int]] = {}
+ saved_heads: dict[str, str] = {}
+ saved_inputs: dict[str, str] = {}
+ if parent_manifest:
+ recorded = parent_manifest["scan"].get("preservedSources", {})
+ if isinstance(recorded, dict):
+ parent_preserved_sources = recorded
+ source_digests.update(parent_preserved_sources)
+ if frozen_source_digests is None:
+ source_times.update(_frozen_source_times(scan_dir, scan_id, recorded))
+ paths: dict[str, str | None] = {}
+ reducer_paths: set[str] = set()
+ current_results: set[str] = set()
+ reducer_outputs: list[tuple[Any, str, list[str], int]] = []
+ reducer = _latest_successful_reducer(workers)
+ latest_reducer: str | None = None
+ if reducer is not None:
+ try:
+ latest_reducer = Path(reducer["result_manifest_path"]).relative_to(scan_dir).as_posix()
+ paths[latest_reducer] = None
+ reducer_paths.add(latest_reducer)
+ except ValueError:
+ warnings.append("Skipped a reducer result outside the scan directory.")
+
+ def checkpoints(directory: str, worker_id: str | None, attempt: int = 0) -> None:
+ if worker_id is not None:
+ root = Path(directory).parent.as_posix()
+ worker_attempts[root] = (worker_id, attempt)
+ paths[f"{root}/checkpoint-head.json"] = worker_id
+ head_snapshots = (Path(directory).parent / "checkpoint-heads").as_posix()
+ for saved_directory in (directory, head_snapshots):
+ paths.update(dict.fromkeys(_checkpoint_paths(scan_dir, saved_directory), worker_id))
+
+ if not preserve_canonical_parent:
+ paths["checkpoint-head.json"] = None
+ checkpoints("checkpoints", None)
+ for worker in workers:
+ try:
+ outputs = _worker_outputs(scan_dir, worker)
+ except (TypeError, ValueError):
+ warnings.append("Skipped a worker checkpoint outside the scan directory.")
+ continue
+ if worker["kind"] == "dedup":
+ for directory, attempt in outputs:
+ checkpoint_paths = _checkpoint_paths(scan_dir, f"{directory}/checkpoints")
+ if not checkpoint_paths:
+ continue
+ result_path = f"{directory}/result.json"
+ retained_paths = [result_path, *checkpoint_paths]
+ paths.update(dict.fromkeys(retained_paths))
+ reducer_paths.update(retained_paths)
+ reducer_outputs.append((worker, result_path, checkpoint_paths, attempt))
+ continue
+ if worker["kind"] != "discovery":
+ continue
+ output, attempt = outputs[0]
+ paths[f"{output}/result.json"] = worker["id"]
+ current_results.add(f"{output}/result.json")
+ for archived, archived_attempt in outputs[1:]:
+ paths[f"{archived}/result.json"] = worker["id"]
+ checkpoints(f"{archived}/checkpoints", worker["id"], archived_attempt)
+ checkpoints(f"{output}/checkpoints", worker["id"], attempt)
+ if worker["result_manifest_path"]:
+ try:
+ current_path = Path(worker["result_manifest_path"]).relative_to(scan_dir).as_posix()
+ paths[current_path] = worker["id"]
+ current_results.add(current_path)
+ except ValueError:
+ warnings.append("Skipped a worker result outside the scan directory.")
+
+ if frozen_source_digests is None:
+ for relative, worker_id in list(paths.items()):
+ if Path(relative).name != "checkpoint-head.json":
+ continue
+ del paths[relative]
+ try:
+ captured = _capture_saved_source(
+ scan_dir, relative, scan_id, created_paths=created_paths
+ )
+ if relative == "checkpoint-head.json" and frozen_source_digests is None:
+ parent_context["head"] = next(iter(captured))
+ paths.update({path: worker_id for path in captured})
+ except (ContractError, OSError, ValueError) as exc:
+ if (scan_dir / relative).exists() and not (
+ relative == "checkpoint-head.json" and parent is not None
+ ):
+ warnings.append(f"Preserved unreadable checkpoint {relative}: {exc}")
+
+ if frozen_source_digests is not None:
+ source_digests.update(
+ {
+ path: digest
+ for path, digest in frozen_source_digests.items()
+ if _is_source_order_snapshot(path)
+ }
+ )
+ paths = {
+ relative: worker_id
+ for relative, worker_id in paths.items()
+ if relative in frozen_source_digests
+ }
+ current_results.intersection_update(frozen_source_digests)
+ if latest_reducer not in frozen_source_digests:
+ latest_reducer = None
+
+ discarded_by_source: dict[str, list[str]] = {}
+ for relative, worker_id in paths.items():
+ try:
+ draft, digest, observed = _read_saved_result(
+ scan_dir, relative, scan_id, kind="dedup" if relative in reducer_paths else None
+ )
+ if frozen_source_digests is not None and frozen_source_digests[relative] != digest:
+ raise ContractError("checkpoint changed after the scan stopped")
+ source_digests[relative] = digest
+ source_times.setdefault(relative, observed)
+ source_order[relative] = (0, source_times[relative])
+ if _checkpoint_head_directory(relative) is not None:
+ saved_heads[relative] = draft["checkpoint"]
+ if isinstance(draft.get("inputCheckpoint"), str):
+ saved_inputs[relative] = draft["inputCheckpoint"]
+ continue
+ if preserve_canonical_parent and worker_id is not None:
+ # Recover imported records without relaxing canonical parent validation.
+ if "complete" in draft and not isinstance(draft["complete"], bool):
+ draft["complete"] = False
+ warnings.append(
+ f"{relative}: Invalid complete marker; retained as a progress checkpoint."
+ )
+ schema_dir = Path(__file__).resolve().parents[2] / "schemas"
+ if "threatModel" in draft:
+ try:
+ model = draft["threatModel"]
+ if isinstance(model, dict):
+ model = {**model, "origin": "recovered"}
+ schema = _read_json(schema_dir / "scan-manifest.schema.json")
+ _validate_schema_node(
+ model,
+ schema["properties"]["scan"]["properties"]["threatModel"],
+ "threatModel",
+ schema,
+ )
+ _require_safe_json_value(model, "threatModel")
+ except ContractError as exc:
+ draft.pop("threatModel")
+ warnings.append(f"{relative}: Skipped malformed threat model: {exc}.")
+ directory = Path(relative).parent
+ if directory.name == "checkpoints":
+ directory = directory.parent
+ recovered_findings = []
+ for index, finding in enumerate(draft["findings"]):
+ needs_identity = isinstance(finding, dict) and "identity" not in finding
+ _ensure_finding_identity(finding)
+ recovered = {"scanId": scan_id, "findings": [finding]}
+ source_warnings: list[str] = []
+ discarded = _recover_unsealed_findings(
+ {"scan": {"id": scan_id, "target": binding["target"]}},
+ recovered,
+ schema_dir,
+ scan_dir / directory,
+ source_warnings,
+ )
+ if recovered["findings"]:
+ try:
+ _validate_current_findings(recovered, schema_dir)
+ except ContractError as exc:
+ warning = f"Skipped malformed finding: {exc}."
+ source_warnings.append(warning)
+ discarded.append(warning)
+ recovered["findings"] = []
+ if discarded:
+ discarded_by_source.setdefault(relative, []).extend(discarded)
+ for recovered_finding in recovered["findings"]:
+ if needs_identity:
+ # Reconcile anonymous revisions before assigning sibling identities.
+ recovered_finding.pop("identity", None)
+ writeup = recovered_finding.pop("writeup", None)
+ if writeup is not None:
+ source_warnings.append(
+ "Retained worker writeup at "
+ f"{directory.as_posix()}/{writeup['reportPath']}; "
+ "the parent report renders this finding inline."
+ )
+ recovered_findings.extend(recovered["findings"])
+ warnings.extend(
+ f"{relative} finding {index + 1}: {warning}" for warning in source_warnings
+ )
+ draft["findings"] = recovered_findings
+ for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions"):
+ rows = draft["coverage"].get(field)
+ if not isinstance(rows, list):
+ continue
+ for index, row in enumerate(rows):
+ if field == "openQuestions" and isinstance(row, str):
+ row = rows[index] = {"question": row}
+ if not isinstance(row, dict):
+ continue
+ row["workerId"] = worker_id
+ refs = row.get("receiptRefs")
+ if not isinstance(refs, list):
+ continue
+ for ref_index, ref in enumerate(refs):
+ if not isinstance(ref, str):
+ continue
+ try:
+ normalized = _require_portable_relative_path(ref, "receiptRef")
+ except ContractError:
+ # Keep malformed references for the finalizer's diagnostics.
+ continue
+ if normalized.startswith("artifacts/"):
+ refs[ref_index] = f"{directory.as_posix()}/{normalized}"
+ # Recovery expects coverage, but reducer results only contain findings
+ # and context. Add an empty value after hashing the original result.
+ sources.append((relative, {"coverage": {}, **draft}, worker_id))
+ except (ContractError, OSError, ValueError) as exc:
+ if (scan_dir / relative).exists():
+ warnings.append(f"Preserved unreadable checkpoint {relative}: {exc}")
+ if frozen_source_digests is not None:
+ if frozen_source_digests.keys() - source_digests.keys():
+ raise ContractError("Frozen stopped-scan checkpoint set is incomplete.")
+
+ # Frozen observations retain checkpoint selection even if a worker moves its head.
+ headed_workers = {
+ worker_attempts[_checkpoint_head_directory(head).as_posix()][0]
+ for head in saved_heads
+ if _checkpoint_head_directory(head) != Path(".")
+ }
+ for relative, _, worker_id in sources:
+ if worker_id not in headed_workers:
+ continue
+ directory = Path(relative).parent
+ if directory.name == "checkpoints":
+ directory = directory.parent
+ _, attempt = worker_attempts.get(directory.as_posix(), (worker_id, 0))
+ source_order[relative] = (attempt, source_order[relative][1])
+ selected_observations: dict[str, tuple[int, int]] = {}
+ parent_heads: list[tuple[int, str]] = []
+ for head, checkpoint in saved_heads.items():
+ directory = _checkpoint_head_directory(head)
+ selected = (directory / "checkpoints" / checkpoint).as_posix()
+ if selected not in source_order:
+ raise ContractError("Checkpoint head is outside the saved source set.")
+ observed = source_order[head][1]
+ if directory == Path("."):
+ order = (0, max(source_order[selected][1], observed))
+ parent_heads.append((observed, selected))
+ else:
+ _, attempt = worker_attempts[directory.as_posix()]
+ order = (attempt, observed)
+ selected_observations[selected] = max(selected_observations.get(selected, order), order)
+ source_order.update(selected_observations)
+
+ drafts_by_path = {relative: draft for relative, draft, _ in sources}
+ if frozen_source_digests is not None and "canonical" in parent_context:
+ canonical = parent_context["canonical"]
+ parent = drafts_by_path[canonical]
+ parent_modified = int(
+ parent_context.get("canonicalObservedAtNs", source_order[canonical][1])
+ )
+ parent_is_canonical = True
+ if "head" in parent_context:
+ head = parent_context["head"]
+ parent_heads = [(source_order[head][1], f"checkpoints/{saved_heads[head]}")]
+ latest_reducer_key = (
+ (reducer["completed_at"] or "", reducer["id"], int(reducer["attempt"] or 0))
+ if reducer is not None and latest_reducer in drafts_by_path
+ else None
+ )
+ if latest_reducer_key is None:
+ latest_reducer = None
+ for worker, result_path, checkpoint_paths, attempt in reducer_outputs:
+ result = drafts_by_path.get(result_path)
+ if result is None or not any(
+ drafts_by_path.get(checkpoint_path) == result for checkpoint_path in checkpoint_paths
+ ):
+ continue
+ current_results.add(result_path)
+ candidate_key = (worker["completed_at"] or "", worker["id"], attempt)
+ if latest_reducer_key is None or candidate_key > latest_reducer_key:
+ latest_reducer_key = candidate_key
+ latest_reducer = result_path
+
+ if parent_heads:
+ latest_observation = max(observed for observed, _ in parent_heads)
+ for observed, parent_path in parent_heads:
+ if observed != latest_observation:
+ continue
+ draft = drafts_by_path[parent_path]
+ modified = source_order[parent_path][1]
+ if parent is None or modified > parent_modified:
+ parent = draft
+ parent_modified = modified
+ parent_is_canonical = False
+ elif modified == parent_modified and draft != parent:
+ parent = _merge_tied_parent_observations(parent, draft)
+ parent_is_canonical = False
+ parent_is_root = parent is not None
+ if parent is None and latest_reducer is not None:
+ parent = drafts_by_path[latest_reducer]
+
+ if preserve_canonical_parent:
+ project_worker_coverage, surface_links = False, []
+ else:
+ project_worker_coverage, surface_links = _prepare_worker_coverage_recovery(
+ sources, parent, source_order, enabled=project_worker_coverage
+ )
+ # Keep the actual retained row even when recovery adds previous findings.
+ linked_surface_sources = {id(surface) for _, _, surface, _, _ in surface_links}
+ linked_surface_outputs: dict[int, dict[str, Any]] = {}
+ worker_row_owners: dict[int, str] = {}
+ worker_surface_outputs: dict[tuple[str, str], dict[int, dict[str, Any]]] = {}
+
+ def record_coverage_owner(retained: Any, item: Any, owner: str | None, field: str) -> None:
+ # Parent aggregates can carry worker metadata without originating in
+ # that worker's retained source. Track the actual source of output rows.
+ if project_worker_coverage and owner is not None and isinstance(retained, dict):
+ worker_row_owners[id(retained)] = owner
+ if field == "surfaces" and isinstance(item.get("id"), str):
+ worker_surface_outputs.setdefault((owner, item["id"]), {})[id(retained)] = retained
+
+ def append_coverage_row(output: list[Any], item: Any, owner: str | None, field: str) -> Any:
+ retained = _project_worker_coverage_row(
+ item, owner if project_worker_coverage else None, field
+ )
+ if retained not in output:
+ output.append(retained)
+ retained = output[output.index(retained)]
+ record_coverage_owner(retained, item, owner, field)
+ _inherit_coverage_sources(retained, [item], coverage_sources)
+ if preserve_canonical_parent:
+ if id(item) in canonical_rows:
+ canonical_rows.add(id(retained))
+ if field == "surfaces":
+ retained_surface_rows.add(id(item))
+ return retained
+
+ def linked_tasks(
+ task: dict[str, Any],
+ published_id: str,
+ source_task: dict[str, Any] | None,
+ candidates: list[tuple[str | None, Any]],
+ ) -> list[Any]:
+ expected = (
+ _project_worker_coverage_row(source_task, source_task["workerId"], "deferred")
+ if source_task is not None
+ else None
+ )
+ return [
+ retained
+ for owner, retained in candidates
+ if retained == task
+ or (
+ expected is not None
+ and owner == expected["workerId"]
+ and isinstance(retained, dict)
+ and retained.get("id") == expected.get("id")
+ and isinstance(retained.get("surfaceIds"), list)
+ and published_id in retained["surfaceIds"]
+ )
+ ]
+
+ def linked_surface(surface, outputs, named_outputs):
+ retained = outputs.get(id(surface))
+ if (
+ retained is None
+ and isinstance(owner := surface.get("workerId"), str)
+ and isinstance(identity := surface.get("id"), str)
+ ):
+ matches = named_outputs.get((owner, identity), {})
+ if len(matches) == 1:
+ retained = next(iter(matches.values()))
+ return retained
+
+ all_sources = ([("parent", parent, None)] if parent else []) + sources
+ # Older checkpoints can omit IDs already assigned in their published output.
+ for field in ("deferred", "surfaces"):
+ named_rows: dict[str | None, list[dict[str, Any]]] = {}
+ for _, draft, owner in all_sources:
+ named_rows.setdefault(owner, []).extend(
+ row
+ for row in _coverage_rows(draft["coverage"], field)
+ if isinstance(row, dict) and isinstance(row.get("id"), str)
+ )
+ for _, draft, owner in all_sources:
+ rows = _coverage_rows(draft["coverage"], field)
+ reserved = {
+ row["id"]
+ for row in rows
+ if isinstance(row, dict) and isinstance(row.get("id"), str)
+ }
+ for row in rows:
+ if not isinstance(row, dict) or "id" in row:
+ continue
+ if field == "deferred" and _has_candidate_metadata(row):
+ continue
+ content = {"receiptRefs": [], **row} if field == "surfaces" else row
+ identity = next(
+ (
+ named["id"]
+ for named in named_rows[owner]
+ if named["id"] not in reserved
+ and {
+ **({"receiptRefs": []} if field == "surfaces" else {}),
+ **{key: value for key, value in named.items() if key != "id"},
+ }
+ == content
+ ),
+ None,
+ )
+ if identity is not None:
+ row["id"] = identity
+ reserved.add(identity)
+
+ # A discarded local surface must not fall back to another source's reused ID.
+ surface_ids_by_source: dict[tuple[str, str], list[str]] = {
+ (relative, row["id"]): []
+ for relative, draft, _ in all_sources
+ for row in (
+ draft["coverage"].get("surfaces", [])
+ if isinstance(draft["coverage"].get("surfaces"), list)
+ else []
+ )
+ if isinstance(row, dict) and isinstance(row.get("id"), str)
+ }
+ discarded_coverage_sources: set[str] = set()
+ if preserve_canonical_parent:
+ for relative, draft, worker_id in sources:
+ if worker_id is None:
+ continue
+ for field in ("surfaces", "explicitExclusions", "deferred"):
+ rows = draft["coverage"].get(field)
+ for row in rows if isinstance(rows, list) else []:
+ if isinstance(row, dict):
+ row.setdefault("id", _saved_coverage_id(row))
+ if field == "surfaces":
+ row.setdefault("receiptRefs", [])
+ source_warnings = []
+ discarded_fields = _recover_unsealed_coverage(
+ draft["coverage"],
+ Path(__file__).resolve().parents[2] / "schemas",
+ scan_dir,
+ source_warnings,
+ discarded_by_source.get(relative, []),
+ # Reconcile local IDs and valid outcomes against worker history below.
+ worker_draft=True,
+ )
+ if discarded_fields & {
+ "surfaces",
+ "explicitExclusions",
+ "deferred",
+ "resolvedDeferred",
+ }:
+ discarded_coverage_sources.add(relative)
+ for row in draft["coverage"]["deferred"]:
+ row["workerId"] = worker_id
+ warnings.extend(f"{relative}: {warning}" for warning in source_warnings)
+
+ if parent is None and not sources:
return None
- if (owner, identity) in ambiguous_deferred and not _has_candidate_metadata(row):
+ if (
+ parent_manifest
+ and parent_manifest["scan"].get("sealedAt")
+ and parent_manifest["scan"].get("status") == binding["status"]
+ and parent_manifest["scan"].get("preservedSources") == source_digests
+ and all(warning in initial_warnings for warning in warnings)
+ ):
return None
- return identity
+
+ if (
+ frozen_source_digests is None
+ or any(_is_source_order_snapshot(path) for path in source_digests)
+ or allow_frozen_legacy_parent
+ ):
+ _freeze_source_times(
+ scan_dir,
+ scan_id,
+ source_digests,
+ source_times,
+ parent_context,
+ created_paths=created_paths,
+ )
+
+ target_kind = binding["allowedTargetKinds"][0]
+ if (
+ target_kind == "git_worktree"
+ and "snapshotDigest" not in binding["target"]
+ and "git_revision" in binding["allowedTargetKinds"]
+ ):
+ target_kind = "git_revision"
+ target = {"kind": target_kind, **binding["target"]}
+ if target["kind"] == "git_diff" and "snapshotDigest" not in target:
+ diff_kind = {"commit": "commit", "branch_diff": "range"}[binding["coverageMode"]]
+ target["snapshotDigest"] = committed_diff_snapshot_digest(
+ diff_kind, target["baseRevision"], target["headRevision"]
+ )
+ manifest = (
+ copy.deepcopy(parent_manifest)
+ if parent_manifest
+ else {"scan": {"target": target, "scope": binding["scope"]}}
+ )
+ for key in ("sealedAt", "artifacts"):
+ manifest["scan"].pop(key, None)
+ manifest["scan"]["preservedSources"] = source_digests
+ # Completion follows the selected parent, including legacy terminal drafts
+ # that omit the optional marker, rather than an older canonical manifest.
+ if parent is not None:
+ manifest["scan"].pop("complete", None)
+ if "complete" in parent:
+ manifest["scan"]["complete"] = parent["complete"]
+ for key in ("scope", "threatModel"):
+ if isinstance(parent.get(key), dict):
+ manifest["scan"][key] = copy.deepcopy(parent[key])
+ if isinstance(manifest["scan"].get("scope"), dict):
+ manifest["scan"]["scope"].update(copy.deepcopy(binding["scope"]))
+ model_checks: dict[str, dict[str, Any] | None] = {}
+
+ def recovered_model(
+ relative: str, draft: dict[str, Any], owner: str | None
+ ) -> dict[str, Any] | None:
+ if relative not in model_checks:
+ model = copy.deepcopy(draft.get("threatModel"))
+ if isinstance(model, dict) and owner is not None:
+ model["origin"] = "recovered"
+ schema = _read_json(
+ Path(__file__).resolve().parents[2] / "schemas/scan-manifest.schema.json"
+ )
+ try:
+ _require_safe_json_value(model, f"Saved threat model {relative}")
+ _validate_schema_node(
+ model,
+ schema["properties"]["scan"]["properties"]["threatModel"],
+ f"Saved threat model {relative}",
+ schema,
+ )
+ except ContractError as exc:
+ warnings.append(f"Skipped malformed saved threat model {relative}: {exc}")
+ model = None
+ model_checks[relative] = model
+ return model_checks[relative]
+
+ if "threatModel" in manifest["scan"]:
+ model = recovered_model("parent", manifest["scan"], None)
+ if model is None:
+ manifest["scan"].pop("threatModel")
+ else:
+ manifest["scan"]["threatModel"] = model
+
+ if frozen_model_source is not None:
+ # Publication retries retain a valid choice from the frozen source set.
+ model = drafts_by_path.get(frozen_model_source, {}).get("threatModel")
+ if not isinstance(model, dict):
+ raise ContractError("Frozen stopped-scan model source is unavailable.")
+ model = recovered_model(
+ frozen_model_source, drafts_by_path[frozen_model_source], paths[frozen_model_source]
+ )
+ if model is not None:
+ manifest["scan"]["threatModel"] = model
+ if selected_model_source is not None:
+ selected_model_source[:] = [] if model is None else [frozen_model_source]
+ coverage = (
+ copy.deepcopy(parent["coverage"])
+ if parent and parent["coverage"]
+ else {
+ "mode": binding["coverageMode"],
+ "inventoryStrategy": "diff"
+ if binding["coverageMode"] in {"commit", "branch_diff", "working_tree"}
+ else "scoped_path"
+ if binding["coverageMode"] == "scoped_path"
+ else "repository",
+ **binding["scope"],
+ "surfaces": [],
+ "explicitExclusions": [],
+ "deferred": [],
+ }
+ )
+ if isinstance(coverage.get("openQuestions"), list):
+ coverage["openQuestions"] = [
+ {"question": item.strip()} if isinstance(item, str) else item
+ for item in coverage["openQuestions"]
+ ]
+ # Closure reconciliation can reuse original parent rows instead of their copies.
+ canonical_rows = (
+ {
+ id(item)
+ for parent_coverage in (
+ (coverage, parent["coverage"]) if preserve_canonical_parent else (coverage,)
+ )
+ for field in ("surfaces", "explicitExclusions", "deferred")
+ for item in _coverage_rows(parent_coverage, field)
+ }
+ if parent_is_canonical
+ else set()
+ )
+ # Links use source-local IDs until all retained surfaces receive their final IDs.
+ coverage_sources: dict[int, tuple[dict[str, Any], list[str]]] = {}
+ source_owners = {relative: owner for relative, _, owner in all_sources}
+ retained_surface_rows: set[int] = set()
+ for relative, draft, _ in all_sources:
+ for field in ("surfaces", "deferred"):
+ rows = draft["coverage"].get(field)
+ for row in rows if isinstance(rows, list) else []:
+ if isinstance(row, dict):
+ paths_for_row = coverage_sources.setdefault(id(row), (row, []))[1]
+ if relative not in paths_for_row:
+ paths_for_row.append(relative)
+ if parent:
+ for field in ("surfaces", "deferred"):
+ rows, originals = coverage.get(field), parent["coverage"].get(field)
+ if isinstance(rows, list) and isinstance(originals, list):
+ for row, original in zip(rows, originals):
+ _inherit_coverage_sources(row, [original], coverage_sources)
+ if field == "surfaces":
+ retained_surface_rows.update(id(original) for original in originals)
+
+ findings: list[dict[str, Any]] = []
+ finding_positions: dict[str, tuple[int, dict[str, Any] | None]] = {}
+ canonical_finding_keys: set[str] = set()
+ represented: dict[str, str | None] = {}
+ represented_candidates: dict[tuple[str, str, Any, Any, Any], str | None] = {}
+ represented_history: dict[str, set[str]] = {}
+ represented_candidate_history: dict[tuple[str, str, Any, Any, Any], set[str]] = {}
+ rejected_history: dict[tuple[str, str], list[dict[str, Any]]] = {}
+ stopped_parent_seal = bool(
+ stopped and parent_manifest and parent_manifest["scan"].get("sealedAt")
+ )
+
+ # A damaged canonical row must not replace a checkpoint's established identity.
+ legacy_identities: dict[str, dict[str, Any] | None] = {}
+ legacy_identity_sources: set[str] = set()
+
+ def legacy_identity_key(finding: dict[str, Any], owner: str | None) -> str:
+ content = _finding_content(finding)
+ locations = content.get("locations")
+ if isinstance(locations, list):
+ content["locations"] = sorted(
+ [
+ {**row, "endLine": row.get("endLine", row.get("startLine"))}
+ if isinstance(row, dict)
+ else row
+ for row in locations
+ ],
+ key=_encoded,
+ )
+ return _digest([owner, _identity_candidate(finding), content])
+
+ def restore_legacy_identity(
+ finding: Any, normalized: Any = None, *, allow_synthesis: bool = True
+ ) -> None:
+ if isinstance(finding, dict) and "identity" not in finding:
+ provenance = finding.get("provenance")
+ owner = provenance.get("workerId") if isinstance(provenance, dict) else None
+ key = legacy_identity_key(finding, owner)
+ identity = legacy_identities.get(key)
+ if identity is not None:
+ finding["identity"] = copy.deepcopy(identity)
+ allow_synthesis = allow_synthesis or key in legacy_identity_sources
+ if not allow_synthesis:
+ return
+ if isinstance(finding, dict) and isinstance(normalized, dict):
+ finding.setdefault("identity", normalized["identity"])
+ else:
+ _ensure_finding_identity(finding)
+
+ def finding_within_scope(finding: dict[str, Any]) -> bool:
+ locations = finding.get("locations", [])
+ return isinstance(locations, list) and any(
+ isinstance(location, dict)
+ and isinstance(location.get("path"), str)
+ and any(
+ PurePosixPath(location["path"]) == PurePosixPath(path)
+ if is_file
+ else path_within_scope(location["path"], path)
+ for path, is_file in (
+ finding_scope
+ if finding_scope is not None
+ else [(path, False) for path in binding["scope"]["includePaths"]]
+ )
+ )
+ for location in locations
+ )
+
+ valid_findings: dict[bytes, bool] = {}
+
+ def valid_finding(value: Any) -> bool:
+ # Use the finalizer's own per-record recovery before a draft can suppress
+ # an earlier checkpoint. Invalid latest records must not hide valid history.
+ document = {"scanId": scan_id, "findings": [copy.deepcopy(value)]}
+ if isinstance(document["findings"][0], dict):
+ restore_legacy_identity(document["findings"][0])
+ key = _encoded(document["findings"][0])
+ if key in valid_findings:
+ return valid_findings[key]
+ _recover_unsealed_findings(
+ {"scan": {"id": scan_id, "target": binding["target"]}},
+ document,
+ Path(__file__).resolve().parents[2] / "schemas",
+ scan_dir,
+ [],
+ current_contract=current_contract,
+ )
+ valid_findings[key] = bool(document["findings"])
+ return valid_findings[key]
+
+ for _, draft, owner in all_sources:
+ for value in draft["findings"]:
+ if not isinstance(value, dict):
+ continue
+ for saved in _retained_findings(value):
+ identity = saved.get("identity")
+ provenance = saved.get("provenance")
+ saved_owner = (
+ provenance.get("workerId", owner) if isinstance(provenance, dict) else owner
+ )
+ key = legacy_identity_key(saved, saved_owner)
+ if "identity" in saved:
+ legacy_identity_sources.add(key)
+ if not isinstance(identity, dict) or not valid_finding(saved):
+ continue
+ if key not in legacy_identities:
+ legacy_identities[key] = identity
+ elif legacy_identities[key] != identity:
+ legacy_identities[key] = None
+
+ source_order["parent"] = (0, parent_modified)
+ deferred_rows = {
+ relative: _coverage_rows(draft["coverage"], "deferred")
+ for relative, draft, _ in all_sources
+ }
+ # Accepted heads can replace equal tasks before they reach output coalescing.
+ equivalent_tasks: dict[str | None, list[dict[str, Any]]] = {}
+ for relative, _, owner in all_sources:
+ known = equivalent_tasks.setdefault(owner, [])
+ for row in deferred_rows[relative]:
+ if not isinstance(row, dict):
+ continue
+ for previous in known:
+ if previous == row:
+ _inherit_coverage_sources(previous, [row], coverage_sources)
+ coverage_sources[id(row)] = (row, coverage_sources[id(previous)][1])
+ break
+ else:
+ known.append(row)
+ # A legacy source can contain independent tasks with the same explicit ID.
+ # Later rewrites cannot make an ID-only closure identify one of those tasks.
+ ambiguous_deferred: set[tuple[str | None, str]] = set()
+ for relative, _, owner in all_sources:
+ by_id: dict[str, dict[str, Any]] = {}
+ candidate_aliases = {
+ identity
+ for row in deferred_rows[relative]
+ if isinstance(row, dict) and _has_candidate_metadata(row)
+ for identity in (row.get("id"), row.get("candidateId"))
+ if isinstance(identity, str)
+ }
+ for row in deferred_rows[relative]:
+ if not isinstance(row, dict) or not isinstance(identity := row.get("id"), str):
+ continue
+ if _has_candidate_metadata(row):
+ continue
+ if identity in candidate_aliases or (identity in by_id and row != by_id[identity]):
+ ambiguous_deferred.add((owner, identity))
+ by_id[identity] = row
+ current_drafts = ([("parent", parent, None)] if parent else []) + [
+ source for source in sources if source[0] in current_results | selected_observations.keys()
+ ]
+ # Generic closures belong to one logical scan or worker, just like candidates.
+ # Keep them when recovering a terminal checkpoint without its canonical write.
+ closed_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]] = {}
+
+ candidate_ids: set[tuple[str | None, str]] = set()
+ accepted_deferred_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
+ active_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]] = {}
+ coverage_schema = _read_json(
+ Path(__file__).resolve().parents[2] / "schemas" / "coverage.schema.json"
+ )["properties"]
+ for relative, draft, owner in all_sources:
+ order = source_order[relative]
+ for item in deferred_rows[relative]:
+ if not isinstance(item, dict):
+ continue
+ if isinstance(item.get("candidateId"), str) or "candidate" in item or "finding" in item:
+ candidate_ids.update(
+ (owner, identity)
+ for identity in (item.get("id"), item.get("candidateId"))
+ if isinstance(identity, str)
+ )
+ identity = item.get("id") or item.get("candidateId")
+ if isinstance(identity, str):
+ key = (owner, identity)
+ previous = active_deferred.get(key)
+ if previous is None or order > previous[0]:
+ active_deferred[key] = (order, item, relative)
+ if (
+ relative == "parent"
+ or relative in current_results
+ or relative in selected_observations
+ ):
+ try:
+ # A malformed update cannot discard valid saved evidence.
+ _validate_schema_node(
+ item, coverage_schema["deferred"]["items"], "coverage.deferred"
+ )
+ except ContractError:
+ continue
+ accepted_deferred_orders[key] = max(
+ accepted_deferred_orders.get(key, order), order
+ )
+ for closure in _resolved_deferred_rows(draft, coverage_schema["resolvedDeferred"]):
+ key = (owner, closure["id"])
+ previous = closed_deferred.get(key)
+ if previous is None or order > previous[0]:
+ # The parent comes first, preserving its reason on equal timestamps.
+ closed_deferred[key] = (order, closure, relative)
+ reopened_rows: list[tuple[str | None, dict[str, Any]]] = []
+ reopened_generic: set[tuple[str | None, str]] = set()
+ for key, (order, _, _) in list(closed_deferred.items()):
+ # Equal timestamps cannot distinguish closure from reopened work.
+ reopened = [
+ active
+ for (owner, identity), active in active_deferred.items()
+ if owner == key[0]
+ and (identity == key[1] or active[1].get("candidateId") == key[1])
+ and active[0] >= order
+ ]
+ if key in candidate_ids or key in ambiguous_deferred or reopened:
+ del closed_deferred[key]
+ for _, item, _ in reopened:
+ reopened_rows.append((key[0], item))
+ if key not in candidate_ids:
+ reopened_generic.add(key)
+ # Retain every distinct ambiguous task even when a terminal result supersedes
+ # its source. Existing output ID normalization keeps each row distinct.
+ for relative, _, owner in all_sources:
+ for row in deferred_rows[relative]:
+ if (
+ isinstance(row, dict)
+ and isinstance(identity := row.get("id"), str)
+ and (owner, identity) in ambiguous_deferred
+ and not _has_candidate_metadata(row)
+ and (owner, row) not in reopened_rows
+ ):
+ reopened_rows.append((owner, row))
+ parent_closures = [
+ closure for (owner, _), (_, closure, _) in closed_deferred.items() if owner is None
+ ]
+ coverage.pop("resolvedDeferred", None)
+ if parent_closures:
+ coverage["resolvedDeferred"] = copy.deepcopy(parent_closures)
+ if parent:
+ coverage["deferred"] = [
+ row
+ for row in deferred_rows["parent"]
+ if not isinstance(row, dict)
+ or not isinstance(row.get("id"), str)
+ or (None, row["id"]) not in closed_deferred
+ ]
+ resolved: dict[tuple[str | None, str], str] = {}
+
+ ordered_candidates = {
+ (owner, identity)
+ for owner, row in reopened_rows
+ if (identity := _deferred_candidate_id(row, owner, ambiguous_deferred)) is not None
+ and (owner, identity) in candidate_ids
+ }
+ ordered_outcomes: dict[tuple[str | None, str], tuple[tuple[int, int], str]] = {}
+
+ outcomes: list[tuple[str, str | None, str, str]] = []
+ for relative, draft, owner in current_drafts:
+ for finding in draft["findings"]:
+ if (
+ isinstance(finding, dict)
+ and valid_finding(finding)
+ and (candidate_id := finding_candidate_id(finding))
+ ):
+ outcomes.append((relative, owner, candidate_id, "reported"))
+ for field in ("surfaces", "explicitExclusions"):
+ for item in _coverage_rows(draft["coverage"], field):
+ if (
+ isinstance(item, dict)
+ and isinstance(item.get("candidateId"), str)
+ and item.get("disposition") in ("rejected", "not_applicable")
+ ):
+ outcomes.append((relative, owner, item["candidateId"], item["disposition"]))
+ ordered_candidates.update(
+ (owner, candidate_id)
+ for relative, owner, candidate_id, _ in outcomes
+ if owner is not None and relative in selected_observations
+ )
+ # Reopened work and selected checkpoint outcomes follow the saved source order.
+ for relative, owner, candidate_id, disposition in outcomes:
+ key = (owner, candidate_id)
+ if key not in ordered_candidates:
+ if relative == "parent" or relative in current_results:
+ resolved.setdefault(key, disposition)
+ continue
+ order = source_order[relative]
+ if any(
+ saved_owner == owner
+ and _deferred_candidate_id(row, owner, ambiguous_deferred) == candidate_id
+ and modified >= order
+ for (saved_owner, _), (modified, row, _) in active_deferred.items()
+ ):
+ continue
+ if key not in ordered_outcomes or order > ordered_outcomes[key][0]:
+ resolved[key] = disposition
+ ordered_outcomes[key] = (order, relative)
+ # Only the current parent may claim that another worker finding was absorbed.
+ # A superseded checkpoint must not suppress a newer independent result.
+ if parent:
+ for finding in parent["findings"]:
+ if valid_finding(finding):
+ canonical = copy.deepcopy(finding)
+ restore_legacy_identity(canonical)
+ canonical_key = _finding_key(canonical)
+ for retained in _retained_findings(finding):
+ retained_key = _finding_key(retained)
+ if retained is not finding:
+ represented_history.setdefault(retained_key, set()).add(
+ _digest(_finding_content(retained))
+ )
+ previous_key = represented.get(retained_key)
+ if retained_key not in represented:
+ represented[retained_key] = canonical_key
+ elif previous_key != canonical_key:
+ # Ambiguous history cannot suppress an independent source.
+ represented[retained_key] = None
+ originals = finding["provenance"].get("sourceFindings", [])
+ for original in originals if isinstance(originals, list) else []:
+ if isinstance(original, dict) and isinstance(original.get("finding"), dict):
+ source_id = original.get("id")
+ candidate_id = finding_candidate_id(original["finding"])
+ if isinstance(source_id, str) and ":" in source_id and candidate_id:
+ candidate_key = _worker_candidate_key(
+ source_id.rsplit(":", 1)[0],
+ candidate_id,
+ original["finding"],
+ )
+ previous_key = represented_candidates.get(candidate_key)
+ if candidate_key not in represented_candidates:
+ represented_candidates[candidate_key] = canonical_key
+ elif previous_key != canonical_key:
+ # Candidate ids are only authoritative within one
+ # logical worker. Multiple canonical owners make
+ # that worker-local identity ambiguous.
+ represented_candidates[candidate_key] = None
+ represented_candidate_history.setdefault(candidate_key, set()).add(
+ _digest(_finding_content(original["finding"]))
+ )
+ selected_terminal_orders: dict[str, tuple[int, int]] = {}
+ for relative, draft, worker_id in sources:
+ if (
+ worker_id is not None
+ and relative in selected_observations
+ and draft.get("complete") is not False
+ and relative not in discarded_by_source
+ and relative not in discarded_coverage_sources
+ ):
+ order = source_order[relative]
+ selected_terminal_orders[worker_id] = max(
+ selected_terminal_orders.get(worker_id, order), order
+ )
+ terminal_worker_orders: dict[str | None, tuple[int, int]] = {}
+ terminal_coverage_orders: dict[str | None, tuple[int, int]] = {}
+ for relative, draft, worker_id in sources:
+ if (
+ relative in current_results
+ and draft.get("complete") is not False
+ and relative not in discarded_by_source
+ ):
+ order = source_order[relative]
+ terminal_worker_orders[worker_id] = max(
+ terminal_worker_orders.get(worker_id, order), order
+ )
+ if relative not in discarded_coverage_sources:
+ terminal_coverage_orders[worker_id] = max(
+ terminal_coverage_orders.get(worker_id, order), order
+ )
+ # Reconcile raw records before generating context-dependent publication IDs.
+ logical_rows: dict[tuple[Any, ...], dict[str, dict[str, Any]]] = {}
+ row_groups: dict[tuple[str, int], dict[str, Any]] = {}
+ published_groups: list[dict[str, Any]] = []
+
+ def identifiers(value: dict[str, Any]) -> tuple[Any, Any]:
+ extensions = value.get("extensions")
+ return tuple(
+ identifier if _has_identity_text(identifier) else None
+ for identifier in (
+ extensions.get(field) if isinstance(extensions, dict) else None
+ for field in ("reportId", "ledgerRowId")
+ )
+ )
+
+ def distinct_reports(left: dict[str, Any] | None, right: dict[str, Any] | None) -> bool:
+ return (
+ left is not None
+ and right is not None
+ and any(
+ a is not None and b is not None and a != b
+ for a, b in zip(
+ identifiers(left["latest"]), identifiers(right["latest"]), strict=True
+ )
+ )
+ )
+
+ def raw_owner(value: dict[str, Any], source_owner: str | None) -> str | None:
+ if source_owner is not None:
+ return source_owner
+ provenance = value.get("provenance", {})
+ owner = provenance.get("workerId")
+ return owner if isinstance(owner, str) else source_owner
+
+ def raw_scope(value: dict[str, Any]) -> tuple[Any, ...]:
+ # Match scanFindingIdentity's primary location for anonymous reports.
+ location = value["locations"][0]
+ return (
+ value.get("ruleId"),
+ location["path"],
+ location["startLine"],
+ location.get("endLine"),
+ )
+
+ def same_owner(left: str | None, right: str | None) -> bool:
+ # Canonical recovery needs identity or recorded lineage to absorb worker evidence.
+ return left == right or (not preserve_canonical_parent and (left is None or right is None))
+
+ def same_raw_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:
+ if isinstance(left.get("identity"), dict) and isinstance(right.get("identity"), dict):
+ return _semantic_identity_key(left, _finding_identity(left)) == _semantic_identity_key(
+ right, _finding_identity(right)
+ )
+ candidates = (_identity_candidate(left), _identity_candidate(right))
+ if all(candidates) and candidates[0] != candidates[1]:
+ return False
+ pairs = list(zip(identifiers(left), identifiers(right), strict=True))
+ if any(a is not None for a, _ in pairs) and any(b is not None for _, b in pairs):
+ if not any(a is not None and b is not None for a, b in pairs) or any(
+ a is not None and b is not None and a != b for a, b in pairs
+ ):
+ return False
+ return True
+
+ def same_raw_value(left: Any, right: Any) -> bool:
+ if isinstance(left, dict):
+ return (
+ isinstance(right, dict)
+ and left.keys() == right.keys()
+ and all(same_raw_value(value, right[key]) for key, value in left.items())
+ )
+ if isinstance(left, list):
+ return (
+ isinstance(right, list)
+ and len(left) == len(right)
+ and all(same_raw_value(a, b) for a, b in zip(left, right, strict=True))
+ )
+ # JSON numbers compare by value, but booleans are a distinct scalar type.
+ return isinstance(left, bool) == isinstance(right, bool) and left == right
+
+ def same_raw_content(left: dict[str, Any], right: dict[str, Any]) -> bool:
+ def content(value: dict[str, Any]) -> dict[str, Any]:
+ result = _finding_content(value)
+ if isinstance(result.get("extensions"), dict):
+ result["extensions"] = {
+ key: value
+ for key, value in result["extensions"].items()
+ if key not in {"candidateId", "reportId", "ledgerRowId"}
+ }
+ if not result["extensions"]:
+ result.pop("extensions")
+ return result
+
+ return same_raw_value(content(left), content(right))
+
+ def contains_raw_value(current: Any, previous: Any) -> bool:
+ if isinstance(previous, dict):
+ return isinstance(current, dict) and all(
+ key in current and contains_raw_value(current[key], value)
+ for key, value in previous.items()
+ )
+ if isinstance(previous, list):
+ return isinstance(current, list) and all(
+ any(contains_raw_value(item, value) for item in current) for value in previous
+ )
+ return isinstance(current, bool) == isinstance(previous, bool) and current == previous
+
+ def finding_source_order(source, within_worker: bool = False):
+ relative, draft, _ = source
+ attempt, modified = source_order[relative]
+ return (
+ draft.get("complete") is not False,
+ attempt if within_worker else 0,
+ modified,
+ relative in selected_observations,
+ relative in current_results,
+ relative == "parent",
+ )
+
+ terminal_findings: dict[str, list[dict[str, Any]]] = {}
+ # A reducer replaces only its claimed batch, not the whole parent scan.
+ parent_sources = {
+ relative
+ for relative, _, _ in all_sources
+ if Path(relative).parent == Path("checkpoints") or (relative == "parent" and parent_is_root)
+ }
+ projected_paths = {
+ relative
+ for relative, draft, _ in all_sources
+ if relative in parent_sources
+ and (
+ relative == "parent"
+ or relative == parent_context.get("canonical")
+ # The semantic tool schema forbids this host-owned projection field.
+ or draft["coverage"].get("mode") == binding["coverageMode"]
+ )
+ }
+ projected_parents = [draft for relative, draft, _ in all_sources if relative in projected_paths]
+
+ def same_published_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:
+ if not valid_finding(left) or not valid_finding(right):
+ return False
+ return (
+ same_raw_value(_finding_content(left), _finding_content(right))
+ and (
+ "identity" not in left
+ or same_raw_value(_finding_identity(left), _finding_identity(right))
+ )
+ and same_raw_value(
+ {
+ key: value
+ for key, value in left.get("provenance", {}).items()
+ if key not in ("previousFindings", "preservedIdentity")
+ },
+ {
+ key: value
+ for key, value in right.get("provenance", {}).items()
+ if key not in ("previousFindings", "preservedIdentity")
+ },
+ )
+ )
+
+ def represented_by_parent(values: list[dict[str, Any]], draft: dict[str, Any]) -> bool:
+ remaining = [row for row in draft["findings"] if isinstance(row, dict)]
+ for value in values:
+ match = next(
+ (
+ index
+ for index, row in enumerate(remaining)
+ if same_published_finding(value, row)
+ ),
+ None,
+ )
+ if match is None:
+ return False
+ remaining.pop(match)
+ return True
+
+ terminal_sources: set[str] = set()
+ for relative, draft, _ in all_sources:
+ if (
+ scan_mode == "deep"
+ and not allow_frozen_legacy_parent
+ and relative in parent_sources
+ and draft.get("complete") is not False
+ and all(valid_finding(value) for value in draft["findings"])
+ ):
+ terminal_sources.add(relative)
+ if relative not in projected_paths:
+ identified = copy.deepcopy(draft["findings"])
+ _ensure_finding_identities(identified)
+ terminal_findings[relative] = identified
+ # Legacy projections alone do not record the submitted replacement batch.
+ if not terminal_findings:
+ terminal_sources.clear()
+ head_path = (
+ f"checkpoints/{saved_heads[parent_context['head']]}"
+ if "head" in parent_context and not allow_frozen_legacy_parent
+ else None
+ )
+ head_input = saved_inputs.get(parent_context.get("head"))
+ ancestors = _parent_publication_ancestors(head_input, drafts_by_path)
+ committed_parent = parent
+ committed_path = "parent" if parent_is_root else None
+ if head_path and (
+ not parent_is_canonical or any(parent == drafts_by_path.get(path) for path in ancestors)
+ ):
+ committed_path = head_path
+ committed_parent = drafts_by_path[head_path]
+ committed_time = source_order.get(committed_path, (0, 0))[1]
+ pending_terminals = set()
+ superseded_terminals = set()
+ unordered_terminals = set()
+ for relative, values in terminal_findings.items():
+ publication = drafts_by_path[relative].get("publication")
+ if isinstance(publication, dict):
+ previous = publication.get("previousCheckpoint")
+ if Path(relative).name == head_input:
+ continue
+ if (
+ f"checkpoints/{previous}" if previous is not None else None
+ ) != head_path or publication.get("previousInputCheckpoint") != head_input:
+ superseded_terminals.add(relative)
+ continue
+ pending_terminals.add(relative)
+ elif not any(represented_by_parent(values, draft) for draft in projected_parents):
+ # Legacy inputs have no causal link to an accepted publication. A
+ # backdated observation cannot prove that accepted findings were removed.
+ if source_order[relative][1] >= committed_time:
+ pending_terminals.add(relative)
+ else:
+ unordered_terminals.add(relative)
+ terminal_cutoffs = (
+ {committed_path}
+ if committed_path in terminal_sources
+ else terminal_sources - superseded_terminals
+ )
+ terminal_parent_time = max(
+ (source_order[relative][1] for relative in pending_terminals or terminal_cutoffs),
+ default=None,
+ )
+ pending_terminals = {
+ relative
+ for relative in pending_terminals
+ if source_order[relative][1] == terminal_parent_time
+ }
+ for relative in pending_terminals | unordered_terminals:
+ identified = copy.deepcopy(drafts_by_path[relative]["findings"])
+ _ensure_finding_identities(identified, deep=True)
+ terminal_findings[relative] = identified
+ current_findings = [
+ previous
+ for value in (committed_parent["findings"] if committed_parent else [])
+ if isinstance(value, dict)
+ for previous in _retained_findings(value)
+ ]
+ replaced_findings = [
+ value
+ for draft in projected_parents
+ for value in draft["findings"]
+ if isinstance(value, dict)
+ and (
+ pending_terminals
+ or (
+ terminal_sources
+ and not any(
+ same_published_finding(value, previous) for previous in current_findings
+ )
+ )
+ )
+ ]
+
+ def replaced_parent_finding(relative: str, owner: str | None, value: Any) -> bool:
+ if (
+ owner is not None
+ or relative in pending_terminals | unordered_terminals
+ or not isinstance(value, dict)
+ ):
+ return False
+ return any(same_published_finding(value, previous) for previous in replaced_findings)
+
+ terminal_worker_attempts: dict[str, int] = {}
+ if terminal_parent_time is not None:
+ for relative, _, owner in all_sources:
+ attempt, modified = source_order[relative]
+ if owner is not None and modified <= terminal_parent_time:
+ terminal_worker_attempts[owner] = max(
+ terminal_worker_attempts.get(owner, attempt), attempt
+ )
+
+ def precedes_terminal_parent(relative: str, owner: str | None) -> bool:
+ attempt, modified = source_order[relative]
+ return relative in superseded_terminals or (
+ relative not in unordered_terminals
+ and terminal_parent_time is not None
+ and (
+ modified < terminal_parent_time
+ or attempt < terminal_worker_attempts.get(owner, attempt)
+ )
+ )
+
+ finding_sources = [
+ source for source in all_sources if not precedes_terminal_parent(source[0], source[2])
+ ]
+ # Publication chronology spans workers; attempt numbers only order one worker's revisions.
+ for source in sorted(finding_sources, key=lambda item: finding_source_order(item)[2:]):
+ relative, draft, source_owner = source
+ explicit_identity_counts = Counter(
+ _semantic_identity_key(sibling, _finding_identity(sibling))
+ for sibling in draft["findings"]
+ if isinstance(sibling, dict)
+ and isinstance(sibling.get("identity"), dict)
+ and ((relative == "parent" and parent_is_canonical) or finding_within_scope(sibling))
+ )
+ pending = []
+ for index, value in enumerate(draft["findings"]):
+ if (
+ not isinstance(value, dict)
+ or replaced_parent_finding(relative, source_owner, value)
+ or not valid_finding(value)
+ or (
+ not (relative == "parent" and parent_is_canonical)
+ and not finding_within_scope(value)
+ )
+ ):
+ continue
+ owner = raw_owner(value, source_owner)
+ scope = raw_scope(value)
+ candidate = finding_candidate_id(value)
+ scopes = [scope, (scope[0], candidate)] if candidate else [scope]
+ publication_identity = (
+ _finding_identity(
+ value if "identity" in value else terminal_findings[relative][index]
+ )
+ if relative in terminal_findings
+ else None
+ )
+ matches = [
+ group
+ for group in {
+ key: group
+ for saved_scope in scopes
+ for key, group in logical_rows.get(saved_scope, {}).items()
+ }.values()
+ if same_owner(owner, group["owner"])
+ and (
+ publication_identity is None
+ or group["identity"] is None
+ or _semantic_identity_key(value, group["identity"])
+ == _semantic_identity_key(value, publication_identity)
+ )
+ and (
+ (relative == "parent" and parent_is_canonical)
+ or group["identity"] is None
+ or "identity" not in value
+ or _semantic_identity_key(value, group["identity"])
+ == _semantic_identity_key(value, _finding_identity(value))
+ )
+ and all(same_raw_finding(value, previous) for previous in group["rows"])
+ ]
+ ranked = []
+ for group in matches:
+ latest = group["latest"]
+ if (
+ isinstance(value.get("identity"), dict)
+ and explicit_identity_counts[
+ _semantic_identity_key(value, _finding_identity(value))
+ ]
+ == 1
+ and group["identity"] is not None
+ and _semantic_identity_key(value, _finding_identity(value))
+ == _semantic_identity_key(value, group["identity"])
+ ):
+ rank = 4
+ elif (
+ owner == group["owner"]
+ and same_raw_content(value, latest)
+ and _identity_candidate(value) == _identity_candidate(latest)
+ and identifiers(value) == identifiers(latest)
+ ):
+ rank = 3
+ elif any(same_raw_content(value, previous) for previous in group["rows"]):
+ rank = 2
+ elif (
+ latest.get("title") == value.get("title")
+ and raw_scope(latest) == scope
+ and all(
+ previous is None or current == previous
+ for current, previous in zip(
+ identifiers(value), identifiers(latest), strict=True
+ )
+ )
+ ):
+ rank = 1
+ else:
+ rank = 0
+ ranked.append((group, rank))
+ pending.append((index, value, owner, scopes, ranked))
+ assigned = {}
+ claimed = set()
+ for index, value, owner, _, matches in pending:
+ for group, _ in matches:
+ if (
+ group["key"] not in claimed
+ and owner == group["owner"]
+ and same_raw_value(value, group["latest"])
+ ):
+ assigned[index] = group
+ claimed.add(group["key"])
+ break
+ for rank in (4, 3, 2, 1, 0):
+ identity_claims = {
+ group["key"]
+ for index, _, _, _, matches in pending
+ for group, score in matches
+ if score == 4 and assigned.get(index) is group
+ }
+ options = {
+ index: [
+ group
+ for group, score in matches
+ if score >= rank
+ and (
+ group["key"] not in claimed
+ or (rank == 0 and group["key"] not in identity_claims)
+ )
+ ]
+ for index, _, _, _, matches in pending
+ if index not in assigned
+ }
+ counts = {}
+ for groups in options.values():
+ for group in groups:
+ counts[group["key"]] = counts.get(group["key"], 0) + 1
+ chosen = {
+ index: groups[0]
+ for index, groups in options.items()
+ if len(groups) == 1
+ and groups[0]["key"] not in claimed
+ and counts[groups[0]["key"]] == 1
+ }
+ assigned.update(chosen)
+ claimed.update(group["key"] for group in chosen.values())
+ current_groups: list[tuple[int, dict[str, Any]]] = []
+ for index, value, owner, scopes, _ in pending:
+ match = assigned.get(index)
+ if match is None:
+ match = {
+ "owner": owner,
+ "rows": [],
+ "identity": None,
+ "key": f"raw:{len(row_groups)}",
+ }
+ for saved_scope in scopes:
+ logical_rows.setdefault(saved_scope, {})[match["key"]] = match
+ if match["owner"] is None:
+ match["owner"] = owner
+ if not any(same_raw_value(value, previous) for previous in match["rows"]):
+ match["rows"].append(value)
+ observations = match.setdefault("observations", {})
+ previous = observations.get(source_owner)
+ if previous is None or (
+ finding_source_order(source, True),
+ _finding_strength(value),
+ ) > (
+ finding_source_order(previous[0], True),
+ _finding_strength(previous[1]),
+ ):
+ observations[source_owner] = (source, value)
+ match["latest"] = max(
+ observations.values(),
+ key=lambda observation: (
+ finding_source_order(observation[0]),
+ _finding_strength(observation[1]),
+ ),
+ )[1]
+ if relative in terminal_findings:
+ match["identity"] = copy.deepcopy(
+ _finding_identity(
+ value if "identity" in value else terminal_findings[relative][index]
+ )
+ )
+ elif "identity" in value and (match["identity"] is None or relative == "parent"):
+ match["identity"] = copy.deepcopy(_finding_identity(value))
+ row_groups[(relative, index)] = match
+ current_groups.append((index, match))
+ if source_owner is None:
+ current_ordered = [
+ group for _, group in sorted(current_groups, key=lambda item: item[0])
+ ]
+ ordered = current_ordered + [
+ group for group in published_groups if group not in current_ordered
+ ]
+ normalized = []
+ for group in ordered:
+ value = copy.deepcopy(group["latest"])
+ if group["identity"] is not None:
+ value["identity"] = copy.deepcopy(group["identity"])
+ normalized.append(value)
+ _ensure_finding_identities(normalized)
+ for group, value in zip(ordered, normalized, strict=True):
+ group["identity"] = value["identity"]
+ published_groups = ordered
+
+ # A later worker draft can collapse raw duplicates that it fully contains.
+ # Keep established identities and any evidence absent from the newer report.
+ contained_groups = set()
+ for group in {group["key"]: group for group in row_groups.values()}.values():
+ owner = group["owner"]
+ previous = group["observations"].get(owner)
+ if owner is None or group["identity"] is not None or previous is None:
+ continue
+ for current in logical_rows.get(raw_scope(group["latest"]), {}).values():
+ observed = current["observations"].get(owner)
+ if (
+ current["owner"] == owner
+ and observed is not None
+ and finding_source_order(observed[0], True)
+ > finding_source_order(previous[0], True)
+ and all(contains_raw_value(current["latest"], row) for row in group["rows"])
+ ):
+ contained_groups.add(group["key"])
+ break
+
+ # An absorbed source represents every reconciled version of that worker report.
+ for groups in logical_rows.values():
+ for group in groups.values():
+ destinations = set()
+ for value in group["rows"]:
+ history_key = _finding_key(value)
+ if _digest(_finding_content(value)) in represented_history.get(history_key, set()):
+ destinations.add(represented.get(history_key))
+ elif group["owner"] and (candidate_id := finding_candidate_id(value)):
+ candidate_key = _worker_candidate_key(group["owner"], candidate_id, value)
+ if _digest(_finding_content(value)) in represented_candidate_history.get(
+ candidate_key, set()
+ ):
+ destinations.add(represented_candidates[candidate_key])
+ if len(destinations) == 1 and None not in destinations:
+ group["parent_key"] = destinations.pop()
+
+ generated_worker_findings: list[dict[str, Any]] = []
+
+ def source_coverage_selection(
+ relative: str,
+ worker_id: str | None,
+ ) -> tuple[bool, set[str], bool, bool, bool]:
+ worker_result_order = terminal_worker_orders.get(worker_id)
+ selected_coverage_superseded = worker_id in selected_terminal_orders and (
+ source_order[relative] < selected_terminal_orders[worker_id]
+ or (
+ relative in current_results
+ and source_order[relative] <= selected_terminal_orders[worker_id]
+ )
+ )
+ selected_candidates = {
+ candidate_id
+ for (owner, candidate_id), (_, source) in ordered_outcomes.items()
+ if owner == worker_id and source == relative
+ }
+ superseded = (
+ worker_id is None
+ and parent is not None
+ and parent.get("complete") is not False
+ and relative != "parent"
+ and source_order[relative] <= (0, parent_modified)
+ and (not stopped_parent_seal or relative in parent_preserved_sources)
+ ) or (
+ relative not in current_results
+ and worker_result_order is not None
+ and (
+ relative not in selected_observations
+ or source_order[relative] < worker_result_order
+ )
+ )
+ worker_coverage_order = terminal_coverage_orders.get(worker_id)
+ coverage_superseded = (
+ superseded
+ if worker_id is None
+ else (
+ relative not in current_results
+ and worker_coverage_order is not None
+ and (
+ relative not in selected_observations
+ or source_order[relative] < worker_coverage_order
+ )
+ )
+ )
+ # A failed result write can leave pending work outside the accepted result.
+ accepted_order = (
+ (0, parent_modified)
+ if worker_id is None and parent is not None
+ else worker_coverage_order
+ )
+ retain_pending = (
+ coverage_superseded
+ and (worker_id in headed_workers or (worker_id is None and parent_heads))
+ and accepted_order is not None
+ and source_order[relative] >= accepted_order
+ and any(isinstance(row, dict) for row in deferred_rows[relative])
+ )
+ return (
+ selected_coverage_superseded,
+ selected_candidates,
+ superseded,
+ retain_pending,
+ coverage_superseded,
+ )
+
+ def coverage_row_is_retained(
+ field: str,
+ item: Any,
+ worker_id: str | None,
+ selection: tuple[bool, set[str], bool, bool, bool],
+ ) -> bool:
+ (
+ selected_coverage_superseded,
+ selected_candidates,
+ superseded,
+ retain_pending,
+ coverage_superseded,
+ ) = selection
+ # A selected terminal checkpoint replaces ordinary coverage, while
+ # candidate evidence and pending tasks retain their own reconciliation.
+ if (
+ selected_coverage_superseded
+ and field != "deferred"
+ and not (isinstance(item, dict) and _has_candidate_metadata(item))
+ ):
+ return False
+ # A selected outcome must retain its evidence even if its result write failed.
+ if coverage_superseded and not (
+ isinstance(item, dict)
+ and (
+ (field == "deferred" and retain_pending)
+ or (
+ isinstance(item.get("candidateId"), str)
+ and item["candidateId"] in selected_candidates
+ and item.get("disposition") == resolved.get((worker_id, item["candidateId"]))
+ )
+ )
+ ):
+ return False
+ if (
+ isinstance(item, dict)
+ and isinstance(
+ identity := _deferred_candidate_id(item, worker_id, ambiguous_deferred)
+ if field == "deferred"
+ else item.get("candidateId"),
+ str,
+ )
+ and (worker_id, identity) in resolved
+ and (field == "deferred" or item.get("disposition") == "needs_follow_up")
+ ):
+ return False
+ return True
+
+ ambiguous_surface_ids = {
+ (owner, identity)
+ for owner, row in reopened_rows
+ if isinstance(row.get("id"), str)
+ and (owner, row["id"]) in ambiguous_deferred
+ and not _has_candidate_metadata(row)
+ for identity in [
+ row["id"],
+ *(row.get("surfaceIds", []) if isinstance(row.get("surfaceIds", []), list) else []),
+ ]
+ if isinstance(identity, str)
+ }
+ for _, draft, owner in all_sources:
+ by_id: dict[str, dict[str, Any]] = {}
+ for surface in _coverage_rows(draft["coverage"], "surfaces"):
+ if not isinstance(surface, dict) or not isinstance(identity := surface.get("id"), str):
+ continue
+ if identity in by_id and surface != by_id[identity]:
+ ambiguous_surface_ids.add((owner, identity))
+ by_id[identity] = surface
+
+ def ambiguous_pending_surface(row: dict[str, Any], owner: str | None) -> bool:
+ return (
+ isinstance(row.get("id"), str)
+ and (owner, row["id"]) in ambiguous_surface_ids
+ and row.get("disposition") == "needs_follow_up"
+ and not _has_candidate_metadata(row)
+ )
+
+ replaced_deferred = {
+ id(row)
+ for relative, _, owner in all_sources
+ for row in deferred_rows[relative]
+ if isinstance(row, dict)
+ and isinstance(identity := row.get("id"), str)
+ and (key := (owner, identity)) not in candidate_ids
+ and key not in ambiguous_deferred
+ and (updated := accepted_deferred_orders.get(key)) is not None
+ and updated > source_order[relative]
+ }
+ fallback_surfaces = []
+ if surface_links and isinstance(coverage.get("surfaces"), list):
+ # Plan the surviving associations before historical receipts can claim
+ # a spelling needed by a surface that must be restored for its task.
+ prospective_tasks = []
+ prospective_surfaces = {}
+ prospective_named = {}
+ for relative, draft, owner in all_sources:
+ selection = source_coverage_selection(relative, owner)
+ for row in deferred_rows[relative]:
+ if (
+ coverage_row_is_retained("deferred", row, owner, selection)
+ and id(row) not in replaced_deferred
+ and not (
+ isinstance(row, dict)
+ and isinstance(row.get("id"), str)
+ and (owner, row["id"]) in closed_deferred
+ )
+ ):
+ prospective_tasks.append(
+ (owner, _project_worker_coverage_row(row, owner, "deferred"))
+ )
+ for row in _coverage_rows(draft["coverage"], "surfaces"):
+ if owner is None or not isinstance(row, dict):
+ continue
+ emitted = coverage_row_is_retained("surfaces", row, owner, selection)
+ if not emitted and not ambiguous_pending_surface(row, owner):
+ continue
+ projected = _project_worker_coverage_row(row, owner, "surfaces")
+ if isinstance(row.get("id"), str):
+ named = prospective_named.setdefault((owner, row["id"]), {})
+ projected = next(
+ (existing for existing in named.values() if existing == projected),
+ projected,
+ )
+ named[id(projected)] = projected
+ if emitted:
+ prospective_surfaces[id(row)] = projected
+ prospective_tasks.extend(
+ (owner, _project_worker_coverage_row(row, owner, "deferred"))
+ for owner, row in reopened_rows
+ if (owner, _deferred_candidate_id(row, owner, ambiguous_deferred)) not in resolved
+ )
+ bound = {
+ (id(retained), published_id)
+ for task, published_id, surface, _, task_source in surface_links
+ if linked_surface(surface, prospective_surfaces, prospective_named) is not None
+ for retained in linked_tasks(task, published_id, task_source, prospective_tasks)
+ }
+ for task, published_id, _, parent_surface, task_source in surface_links:
+ for retained in linked_tasks(task, published_id, task_source, prospective_tasks):
+ key = (id(retained), published_id)
+ if key not in bound:
+ fallback_surfaces.append(parent_surface)
+ bound.add(key)
+
+ replaced_surfaces, surface_updates = _generic_surface_updates(
+ all_sources,
+ source_order,
+ closed_deferred,
+ active_deferred,
+ resolved,
+ reopened_generic,
+ coverage_schema["surfaces"]["items"],
+ deferred_rows,
+ ambiguous_deferred,
+ canonical_rows,
+ coverage_sources,
+ receipt_root=scan_dir if project_worker_coverage else None,
+ receipt_warnings=warnings,
+ fallback_surfaces=fallback_surfaces,
+ surface_is_retained=lambda relative, owner, row: coverage_row_is_retained(
+ "surfaces", row, owner, source_coverage_selection(relative, owner)
+ ),
+ eligible_receipt_sources={
+ relative
+ for relative, draft, _ in all_sources
+ if draft.get("complete") is not False or relative in selected_observations
+ },
+ )
+ replaced_rows = {
+ "surfaces": replaced_surfaces,
+ "deferred": replaced_deferred,
+ }
+ for field, replaced in replaced_rows.items():
+ if parent and isinstance(coverage.get(field), list):
+ previous = parent["coverage"].get(field, [])
+ if isinstance(previous, list):
+ removed_parent = [row for row in previous if id(row) in replaced]
+ coverage[field] = [row for row in coverage[field] if row not in removed_parent]
+ if isinstance(coverage.get("surfaces"), list):
+ for owner, surface, replaced_sources in surface_updates:
+ retained = append_coverage_row(coverage["surfaces"], surface, owner, "surfaces")
+ for source_id in replaced_sources & linked_surface_sources:
+ linked_surface_outputs[source_id] = retained
+ for surface in coverage["surfaces"]:
+ if isinstance(surface, dict):
+ surface.setdefault("receiptRefs", [])
+
+ # Reopened work survives a superseded checkpoint, but current candidate
+ # outcomes still apply. Parent closures cannot remove another worker's row.
+ for owner, item in reopened_rows:
+ if (identity := _deferred_candidate_id(item, owner, ambiguous_deferred)) is not None and (
+ owner,
+ identity,
+ ) in resolved:
+ continue
+ pending = coverage.setdefault("deferred", [])
+ if isinstance(pending, list):
+ append_coverage_row(pending, item, owner, "deferred")
+ for _, draft, owner in all_sources:
+ for surface in _coverage_rows(draft["coverage"], "surfaces"):
+ if (
+ isinstance(surface, dict)
+ and ambiguous_pending_surface(surface, owner)
+ and isinstance(coverage.get("surfaces"), list)
+ ):
+ retained = append_coverage_row(
+ coverage["surfaces"],
+ {**surface, "receiptRefs": surface.get("receiptRefs", [])},
+ owner,
+ "surfaces",
+ )
+ _inherit_coverage_sources(retained, [surface], coverage_sources)
+ retained_surface_rows.add(id(surface))
+ for relative, draft, worker_id in all_sources:
+ selection = source_coverage_selection(relative, worker_id)
+ (
+ selected_coverage_superseded,
+ selected_candidates,
+ superseded,
+ retain_pending,
+ coverage_superseded,
+ ) = selection
+ skip_superseded_findings = (
+ superseded
+ and not stopped
+ and all(valid_finding(finding) for finding in (parent["findings"] if parent else []))
+ )
+ if (
+ skip_superseded_findings
+ and coverage_superseded
+ and not selected_candidates
+ and not retain_pending
+ ):
+ continue
+ if (
+ not skip_superseded_findings
+ and "threatModel" not in manifest["scan"]
+ and isinstance(draft.get("threatModel"), dict)
+ ):
+ model = recovered_model(relative, draft, worker_id)
+ model_path = relative
+ checkpoint_dir = Path(relative).parent
+ prefer_worker_head = worker_id is not None and (
+ checkpoint_dir.name == "checkpoints" or draft.get("complete") is False
+ )
+ if worker_id is not None:
+ if checkpoint_dir.name != "checkpoints":
+ checkpoint_dir /= "checkpoints"
+ selected_models = [
+ path
+ for path in selected_observations
+ if Path(path).parent == checkpoint_dir
+ and isinstance(drafts_by_path[path].get("threatModel"), dict)
+ and recovered_model(path, drafts_by_path[path], worker_id) is not None
+ ]
+ if selected_models:
+ head_path = max(selected_models, key=source_order.__getitem__)
+ current = drafts_by_path[head_path]
+ # A terminal checkpoint is committed before result.json is replaced.
+ # Use the admitted observation, including its frozen ordering on retries.
+ if not prefer_worker_head and current.get("complete") is not False:
+ prefer_worker_head = source_order[head_path] >= source_order[relative]
+ if prefer_worker_head:
+ model = recovered_model(head_path, current, worker_id)
+ model_path = head_path
+ if model is not None:
+ manifest["scan"]["threatModel"] = model
+ if selected_model_source is not None and worker_id is not None:
+ selected_model_source[:] = [model_path]
+ normalized_findings = copy.deepcopy(draft["findings"])
+ _ensure_finding_identities(
+ [finding for finding in normalized_findings if valid_finding(finding)]
+ )
+ for index, (value, normalized) in enumerate(
+ zip(draft["findings"], normalized_findings, strict=True)
+ ):
+ if precedes_terminal_parent(relative, worker_id) or replaced_parent_finding(
+ relative, worker_id, value
+ ):
+ continue
+ _ensure_finding_identity(normalized)
+ group = row_groups.get((relative, index))
+ if group is not None and group["key"] in contained_groups:
+ continue
+ if skip_superseded_findings and not (
+ isinstance(value, dict)
+ and (candidate_id := finding_candidate_id(value)) in selected_candidates
+ and resolved.get((worker_id, candidate_id)) == "reported"
+ ):
+ continue
+ if relative == "parent" and parent_is_canonical:
+ finding = copy.deepcopy(value)
+ group = row_groups.get((relative, index))
+ restore_legacy_identity(
+ finding,
+ group or normalized,
+ allow_synthesis=stopped
+ or (isinstance(finding, dict) and _identity_candidate(finding) is not None)
+ or (group is not None and any("identity" in row for row in group["rows"])),
+ )
+ provenance = finding.get("provenance") if isinstance(finding, dict) else None
+ owner = provenance.get("workerId") if isinstance(provenance, dict) else None
+ candidate_id = finding_candidate_id(finding) if isinstance(finding, dict) else None
+ if (
+ stopped_parent_seal
+ and isinstance(owner, str)
+ and candidate_id
+ and resolved.get((owner, candidate_id)) in ("rejected", "not_applicable")
+ ):
+ rejected_history.setdefault((owner, candidate_id), []).append(finding)
+ continue
+ if valid_finding(finding):
+ key = _finding_key(finding)
+ if group is not None:
+ key = group.setdefault("merge_key", key)
+ finding_positions.setdefault(key, (len(findings), group))
+ if preserve_canonical_parent:
+ canonical_finding_keys.add(key)
+ findings.append(finding)
+ continue
+ if (
+ relative != "parent"
+ and parent
+ and value in parent["findings"]
+ and not precedes_terminal_parent("parent", None)
+ and not replaced_parent_finding("parent", None, value)
+ ):
+ continue
+ if not isinstance(value, dict):
+ warnings.append(f"Retained malformed finding evidence in {relative}.")
+ continue
+ finding = copy.deepcopy(value)
+ candidate_id = finding_candidate_id(finding)
+ if relative != "parent" and resolved.get((worker_id, candidate_id)) in {
+ "rejected",
+ "not_applicable",
+ }:
+ if preserve_canonical_parent:
+ rejected_history.setdefault((worker_id, candidate_id), []).append(finding)
+ for item in _coverage_rows(coverage, "surfaces"):
+ if (
+ isinstance(item, dict)
+ and item.get("candidateId") == candidate_id
+ and (not preserve_canonical_parent or item.get("workerId") == worker_id)
+ ):
+ _append_previous_finding(item, finding)
+ continue
+ for key in ("findingId", "occurrenceId", "fingerprints"):
+ finding.pop(key, None)
+ if not finding_within_scope(finding):
+ warnings.append(f"Skipped out-of-scope finding from {relative}.")
+ continue
+ provenance = finding.setdefault("provenance", {"source": "local_plugin"})
+ if not isinstance(provenance, dict):
+ findings.append(finding)
+ continue
+ if worker_id:
+ provenance.setdefault("workerId", worker_id)
+ group = row_groups.get((relative, index))
+ if relative in terminal_findings:
+ terminal = terminal_findings[relative][index]
+ finding["identity"] = copy.deepcopy(terminal["identity"])
+ if "preservedIdentity" in terminal.get("provenance", {}):
+ provenance.setdefault(
+ "preservedIdentity",
+ copy.deepcopy(terminal["provenance"]["preservedIdentity"]),
+ )
+ elif group is not None and group["identity"] is not None:
+ finding.setdefault("identity", copy.deepcopy(group["identity"]))
+ if worker_id is not None and "identity" not in finding:
+ generated_worker_findings.append(finding)
+ finding.setdefault("identity", normalized["identity"])
+ if not valid_finding(finding):
+ findings.append(finding)
+ continue
+ # Terminal siblings remain separate even when their preserved authored
+ # identities and locations coincide. Worker revisions reuse the group.
+ key = (
+ group["key"]
+ if group is not None
+ and (group["identity"] is None or relative in terminal_findings)
+ else _finding_key(finding)
+ )
+ if group is not None:
+ key = group.setdefault("merge_key", key)
+ # Distinct reconciled reports may share an anchor and source location.
+ if key in finding_positions and distinct_reports(group, finding_positions[key][1]):
+ key = group["merge_key"] = group["key"]
+ key = group.get("parent_key", key)
+ represented_by_parent = False
+ if relative != "parent":
+ history_key = _finding_key(value)
+ # A singleton key is not evidence that a new batch sibling was
+ # absorbed. Only recorded content may reuse that historical edge.
+ if _digest(_finding_content(value)) not in represented_history.get(
+ history_key, set()
+ ):
+ history_key = key
+ if history_key in represented:
+ mapped_key = represented[history_key]
+ historical_contents = represented_history.get(history_key, set())
+ elif worker_id and candidate_id:
+ candidate_key = _worker_candidate_key(worker_id, candidate_id, finding)
+ mapped_key = represented_candidates.get(candidate_key)
+ historical_contents = represented_candidate_history.get(candidate_key, set())
+ else:
+ mapped_key = None
+ historical_contents = set()
+ if mapped_key is not None:
+ key = mapped_key
+ represented_by_parent = _digest(_finding_content(value)) in historical_contents
+ if key in finding_positions:
+ position, retained_group = finding_positions[key]
+ retained = findings[position]
+ for field in ("anchor", "instance"):
+ if field in retained["identity"]:
+ finding["identity"][field] = retained["identity"][field]
+ else:
+ finding["identity"].pop(field, None)
+ if finding != retained:
+ if (
+ key not in canonical_finding_keys
+ and not represented_by_parent
+ and (
+ value is group["latest"]
+ if group is not None and group is retained_group
+ else _finding_strength(finding) > _finding_strength(retained)
+ )
+ ):
+ previous = copy.deepcopy(retained)
+ previous_history = previous["provenance"].pop("previousFindings", [])
+ if "preservedIdentity" in retained["provenance"]:
+ finding["provenance"]["preservedIdentity"] = copy.deepcopy(
+ retained["provenance"]["preservedIdentity"]
+ )
+ retained = finding
+ findings[position] = retained
+ finding_positions[key] = (position, group)
+ else:
+ previous = copy.deepcopy(value)
+ previous_history = previous.get("provenance", {}).pop(
+ "previousFindings", []
+ )
+ retained_provenance = retained["provenance"]
+ for field in ("sourceFindingIds", "sourceFindings", "originalCandidates"):
+ values = retained_provenance.get(field, [])
+ values = list(values) if isinstance(values, list) else []
+ previous_values = previous.get("provenance", {}).get(field, [])
+ for item in previous_values if isinstance(previous_values, list) else []:
+ if item not in values:
+ values.append(copy.deepcopy(item))
+ if values:
+ retained_provenance[field] = values
+ retained_history = retained_provenance.get("previousFindings")
+ history = (
+ [item for item in retained_history if isinstance(item, dict)]
+ if isinstance(retained_history, list)
+ else []
+ )
+ for original in [
+ *(previous_history if isinstance(previous_history, list) else []),
+ previous,
+ ]:
+ if not isinstance(original, dict):
+ continue
+ owner = retained_provenance.get("workerId", worker_id)
+ source_key = _finding_key(original, owner)
+ source_content = _finding_content(original)
+ already_retained = any(
+ source_key == _finding_key(historical, owner)
+ and source_content == _finding_content(historical)
+ for historical in _retained_findings(retained)
+ )
+ if (
+ not already_retained
+ and original not in history
+ and original != retained
+ ):
+ history.append(original)
+ if history or retained_history is not None:
+ retained_provenance["previousFindings"] = history
+ continue
+ finding_positions[key] = (len(findings), group)
+ findings.append(finding)
+ if coverage_superseded and not selected_candidates and not retain_pending:
+ continue
+ for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions"):
+ if coverage_superseded and field not in {"surfaces", "explicitExclusions", "deferred"}:
+ continue
+ items = draft["coverage"].get(field, [])
+ if field == "deferred":
+ items = deferred_rows[relative]
+ if not isinstance(items, list):
+ continue
+ output = coverage.setdefault(field, [])
+ if not isinstance(output, list):
+ # Keep malformed canonical collections for the existing finalizer's
+ # recovery and warnings rather than silently changing its contract.
+ continue
+ for item in items:
+ source_item = original_item = item
+ if not coverage_row_is_retained(field, item, worker_id, selection):
+ continue
+ if id(item) in replaced_rows.get(field, ()):
+ continue
+ if (
+ field == "deferred"
+ and isinstance(item, dict)
+ and isinstance(item.get("id"), str)
+ and (worker_id, item["id"]) in closed_deferred
+ ):
+ continue
+ if field == "openQuestions" and isinstance(item, str):
+ item = {"question": item.strip()}
+ if (
+ field == "surfaces"
+ and isinstance(item, dict)
+ and item.get("disposition") in ("rejected", "not_applicable")
+ and isinstance(item.get("candidateId"), str)
+ and (history_findings := rejected_history.get((worker_id, item["candidateId"])))
+ ):
+ item = copy.deepcopy(item)
+ for finding in history_findings:
+ _append_previous_finding(item, finding, clone=True)
+ if field == "surfaces" and isinstance(item, dict):
+ item = {**item, "receiptRefs": item.get("receiptRefs", [])}
+ if isinstance(item, dict) and "id" not in item:
+ semantic_item = dict(item)
+ existing = next(
+ (
+ row
+ for row in output
+ if isinstance(row, dict)
+ and {key: value for key, value in row.items() if key != "id"}
+ == semantic_item
+ ),
+ None,
+ )
+ if existing is not None:
+ if project_worker_coverage and worker_id is not None:
+ worker_row_owners[id(existing)] = worker_id
+ if field == "surfaces" and id(source_item) in linked_surface_sources:
+ linked_surface_outputs[id(source_item)] = existing
+ _inherit_coverage_sources(existing, [original_item], coverage_sources)
+ if field == "surfaces":
+ retained_surface_rows.add(id(original_item))
+ continue
+ retained = append_coverage_row(output, item, worker_id, field)
+ _inherit_coverage_sources(retained, [original_item], coverage_sources)
+ if field == "surfaces":
+ retained_surface_rows.add(id(original_item))
+ if field == "surfaces" and id(source_item) in linked_surface_sources:
+ linked_surface_outputs[id(source_item)] = retained
+
+ # Generate new worker identities from the retained collection, as a normal
+ # Deep parent does. Authored, restored and canonical identities stay stable.
+ generated_worker_ids = {id(finding) for finding in generated_worker_findings}
+ for finding in generated_worker_findings:
+ finding.pop("identity", None)
+
+ def publication_order(item):
+ _, group = item
+ source, value = group["observations"][group["owner"]]
+ index = next(index for index, row in enumerate(source[1]["findings"]) if row is value)
+ return finding_source_order(source, True), -index
+
+ identity_order = list(findings)
+ for owner in {group["owner"] for _, group in finding_positions.values() if group is not None}:
+ positions = [
+ (position, group)
+ for position, group in finding_positions.values()
+ if group is not None and group["owner"] == owner and group["identity"] is None
+ ]
+
+ for (position, _), (published_position, _) in zip(
+ positions, sorted(positions, key=publication_order, reverse=True), strict=True
+ ):
+ identity_order[position] = findings[published_position]
+ identity_order = [
+ finding
+ for finding in identity_order
+ if valid_finding(finding) and ("identity" in finding or id(finding) in generated_worker_ids)
+ ]
+ _ensure_finding_identities(identity_order)
+
+ identities: dict[bytes, list[tuple[str, dict[str, Any] | None, str | None]]] = {}
+ retained_groups = {
+ position: group for position, group in finding_positions.values() if group is not None
+ }
+ reserved_identities = {_semantic_identity_key(finding) for finding in identity_order}
+ for position, finding in enumerate(findings):
+ if not valid_finding(finding):
+ continue
+ identity = finding.get("identity")
+ if not isinstance(identity, dict):
+ continue
+ key = _semantic_identity_key(finding)
+ variant = _finding_key(finding)
+ group = retained_groups.get(position)
+ previous = next(
+ (
+ entry
+ for entry in identities.get(key, [])
+ if entry[0] == variant and not distinct_reports(group, entry[1])
+ ),
+ None,
+ )
+ if previous is not None and previous[2] is not None:
+ if identity.get("instance") != previous[2]:
+ finding.setdefault("provenance", {}).setdefault(
+ "preservedIdentity", copy.deepcopy(identity)
+ )
+ identity["instance"] = previous[2]
+ elif previous is None and key in identities:
+ finding.setdefault("provenance", {}).setdefault(
+ "preservedIdentity", copy.deepcopy(identity)
+ )
+ base_instance = identity.get("instance", "saved")
+ suffix = 2
+ while True:
+ identity["instance"] = f"{base_instance}-{suffix}"
+ distinct = _semantic_identity_key(finding)
+ if distinct not in reserved_identities:
+ reserved_identities.add(distinct)
+ break
+ suffix += 1
+ identities.setdefault(key, []).append((variant, group, identity.get("instance")))
+ recovered_worker_ids = {worker_id for _, _, worker_id in sources if worker_id is not None}
+ surface_positions: dict[str, int] = {}
+ resolved_surface_targets: dict[tuple[str | None, str], list[str]] = {}
+
+ def remember_surface_id(item: dict[str, Any], local_id: str) -> None:
+ final_id = item["id"]
+ surface_positions.setdefault(final_id, len(surface_positions))
+ shadowed_alias = (
+ project_worker_coverage
+ and id(item) not in named_surface_outputs
+ and (named := worker_surfaces.get((worker_row_owners.get(id(item)), local_id)))
+ is not None
+ and id(named) in named_surface_outputs
+ )
+ for relative in coverage_sources.get(id(item), (item, []))[1]:
+ # A candidate-derived ID cannot claim a link explicitly naming another surface.
+ if not shadowed_alias:
+ targets = surface_ids_by_source.setdefault((relative, local_id), [])
+ if final_id not in targets:
+ targets.append(final_id)
+ candidate_id = item.get("candidateId")
+ if isinstance(candidate_id, str):
+ key = (source_owners[relative], candidate_id)
+ if key in resolved and resolved[key] == item.get("disposition"):
+ targets = resolved_surface_targets.setdefault(key, [])
+ if final_id not in targets:
+ targets.append(final_id)
+
+ # Bind links to retained output objects before their IDs become unique.
+ # Candidate metadata can give an anonymous row the same preliminary ID as
+ # another surface, so only the final surface ID can be used for its links.
+ retained_surface_links: dict[int, tuple[dict[str, Any], dict[str, dict[str, Any]]]] = {}
+ output_tasks = _coverage_rows(coverage, "deferred")
+ task_candidates = [(worker_row_owners.get(id(row)), row) for row in output_tasks]
+ for task, published_id, surface, _, task_source in surface_links:
+ retained_surface = linked_surface(surface, linked_surface_outputs, worker_surface_outputs)
+ if retained_surface is None or not isinstance(retained_surface.get("id"), str):
+ continue
+ for retained_task in linked_tasks(task, published_id, task_source, task_candidates):
+ _, links = retained_surface_links.setdefault(id(retained_task), (retained_task, {}))
+ links.setdefault(published_id, retained_surface)
+ # A newer worker checkpoint may omit a surface still needed by a retained
+ # task. Restore its parent copy only when no worker replacement survived.
+ for task, published_id, surface, parent_surface, task_source in surface_links:
+ for retained_task in linked_tasks(task, published_id, task_source, task_candidates):
+ _, links = retained_surface_links.setdefault(id(retained_task), (retained_task, {}))
+ if published_id not in links and isinstance(coverage.get("surfaces"), list):
+ retained_surface = append_coverage_row(
+ coverage["surfaces"], parent_surface, None, "surfaces"
+ )
+ record_coverage_owner(
+ retained_surface, surface, surface.get("workerId"), "surfaces"
+ )
+ links[published_id] = retained_surface
+ if project_worker_coverage:
+ worker_surfaces: dict[tuple[str, str], dict[str, Any]] = {}
+ named_surface_outputs = {
+ identity for outputs in worker_surface_outputs.values() for identity in outputs
+ }
+ for surface in _coverage_rows(coverage, "surfaces"):
+ if not isinstance(surface, dict):
+ continue
+ owner, identity = worker_row_owners.get(id(surface)), surface.get("id")
+ if isinstance(owner, str) and isinstance(identity, str):
+ key = (owner, identity)
+ existing = worker_surfaces.get(key)
+ # An anonymous candidate ID can collide with an explicit surface ID.
+ # Bind a named worker link to the explicitly named source.
+ if existing is None or (
+ id(surface) in named_surface_outputs
+ and id(existing) not in named_surface_outputs
+ ):
+ worker_surfaces[key] = surface
+ for task in output_tasks:
+ if (
+ not isinstance(task, dict)
+ or (owner := worker_row_owners.get(id(task))) is None
+ or not isinstance(task.get("surfaceIds"), list)
+ ):
+ continue
+ for identity in task["surfaceIds"]:
+ if (
+ isinstance(identity, str)
+ and (surface := worker_surfaces.get((owner, identity))) is not None
+ ):
+ _, links = retained_surface_links.setdefault(id(task), (task, {}))
+ links.setdefault(identity, surface)
+ for field in ("surfaces", "explicitExclusions", "deferred"):
+ used: set[str] = set()
+ items = coverage.setdefault(field, [])
+ if not isinstance(items, list):
+ continue
+ reserved = {
+ row["id"] for row in items if isinstance(row, dict) and isinstance(row.get("id"), str)
+ }
+ normalized_items = []
+ for item in items:
+ normalized_items.append(item)
+ if not isinstance(item, dict):
+ continue
+ if id(item) in canonical_rows:
+ if isinstance(item.get("id"), str):
+ used.add(item["id"])
+ if field == "surfaces":
+ remember_surface_id(item, item["id"])
+ continue
+ item.setdefault("id", _saved_coverage_id(item))
+ if not isinstance(item["id"], str):
+ # Preserve malformed rows for per-record recovery, including frozen replay.
+ continue
+ local_id = item["id"]
+ scoped = (
+ preserve_canonical_parent
+ and isinstance(worker_id := item.get("workerId"), str)
+ and worker_id in recovered_worker_ids
+ )
+ if scoped:
+ # Resolve worker-local candidate/deferred history before scoping IDs.
+ item["id"] = f"{worker_id}/{item['id']}"
+ if isinstance(item.get("surfaceIds"), list):
+ links: list[Any] = []
+ for surface_id in item["surfaceIds"]:
+ targets: list[str] = []
+ declared = False
+ if field == "deferred" and isinstance(surface_id, str):
+ for relative in coverage_sources.get(id(item), (item, []))[1]:
+ source_key = (relative, surface_id)
+ history_keys = [source_key]
+ if source_key not in surface_ids_by_source:
+ # A deferred-only checkpoint can refer to an earlier
+ # observation from this logical worker, including retries.
+ # Reused IDs can denote several retained observations.
+ history_keys = [
+ (historical, surface_id)
+ for historical, _, owner in all_sources
+ if owner == source_owners[relative]
+ and source_order[historical] <= source_order[relative]
+ ]
+ for key in history_keys:
+ declared |= key in surface_ids_by_source
+ for target in surface_ids_by_source.get(key, []):
+ if target not in targets:
+ targets.append(target)
+ if targets:
+ targets.sort(key=surface_positions.__getitem__)
+ for target in targets:
+ if target not in links:
+ links.append(target)
+ elif not declared:
+ links.append(
+ f"{worker_id}/{surface_id}"
+ if scoped and isinstance(surface_id, str)
+ else surface_id
+ )
+ item["surfaceIds"] = links
+ if scoped:
+ if item in normalized_items[:-1]:
+ # A previous finish may have published files before its DB commit.
+ if field == "surfaces":
+ remember_surface_id(item, local_id)
+ normalized_items.pop()
+ continue
+ if item["id"] in used:
+ if project_worker_coverage:
+ base = item["id"]
+ suffix = 2
+ while item["id"] in used or item["id"] in reserved:
+ item["id"] = f"{base}-{suffix}"
+ suffix += 1
+ else:
+ item["id"] = f"{item['id']}-{_digest(item)[:16]}"
+ if preserve_canonical_parent and item in normalized_items[:-1]:
+ if field == "surfaces":
+ remember_surface_id(item, local_id)
+ normalized_items.pop()
+ continue
+ used.add(item["id"])
+ if field == "surfaces":
+ item.setdefault("receiptRefs", [])
+ remember_surface_id(item, local_id)
+ if preserve_canonical_parent and isinstance(items, list):
+ coverage[field] = normalized_items
+ if field == "surfaces":
+ # Candidate resolution replaces pending surfaces independently of generic
+ # tasks. Preserve their original links, even when the outcome changes ID
+ # or a distinct retained surface shares the old source-local ID.
+ for relative, draft, owner in all_sources:
+ originals = draft["coverage"].get("surfaces", [])
+ for original in originals if isinstance(originals, list) else []:
+ if (
+ not isinstance(original, dict)
+ or id(original) in retained_surface_rows
+ or original.get("disposition") != "needs_follow_up"
+ or not isinstance(local_id := original.get("id"), str)
+ or not isinstance(candidate_id := original.get("candidateId"), str)
+ ):
+ continue
+ targets = surface_ids_by_source.setdefault((relative, local_id), [])
+ for target in resolved_surface_targets.get((owner, candidate_id), []):
+ if target not in targets:
+ targets.append(target)
+ for task, links in retained_surface_links.values():
+ task["surfaceIds"] = [
+ links[identity]["id"] if isinstance(identity, str) and identity in links else identity
+ for identity in task["surfaceIds"]
+ ]
+ coverage.pop("completeness", None)
+ if stopped:
+ if not isinstance(coverage.get("deferred"), list):
+ coverage["deferred"] = []
+ item = {"id": "scan-stopped", "reason": reason}
+ if item not in coverage["deferred"]:
+ coverage["deferred"].append(item)
+ return manifest, {"findings": findings}, coverage
diff --git a/plugins/codex-security/scripts/workbench/saved_sources.py b/plugins/codex-security/scripts/workbench/saved_sources.py
index 585ebdf60..dce2fd9af 100644
--- a/plugins/codex-security/scripts/workbench/saved_sources.py
+++ b/plugins/codex-security/scripts/workbench/saved_sources.py
@@ -1,19 +1,81 @@
-"""Read immutable saved-result observations and their frozen ordering."""
+"""Read and freeze saved scan checkpoint observations."""
from __future__ import annotations
+import argparse
+import hashlib
import json
import os
import re
+import stat
+from collections.abc import Iterator
from pathlib import Path
from typing import Any
from finalize_scan_contract import (
ContractError,
+ _read_scan_local_json,
_read_scan_local_json_with_metadata,
+ manifest_is_sealed,
write_scan_local_bytes,
)
-from workbench.retained_coverage import _digest, _encoded
+
+
+def _encoded(value: Any) -> bytes:
+ return json.dumps(
+ value, ensure_ascii=True, allow_nan=False, sort_keys=True, separators=(",", ":")
+ ).encode()
+
+
+def _digest(value: Any) -> str:
+ return hashlib.sha256(_encoded(value)).hexdigest()
+
+
+def _source_digests(value: Any, error: str) -> dict[str, str]:
+ if not isinstance(value, dict) or not all(
+ isinstance(relative, str) and isinstance(digest, str) for relative, digest in value.items()
+ ):
+ raise ContractError(error)
+ return value
+
+
+def _retained_source_state(value: Any) -> tuple[dict[str, str], str | None]:
+ if isinstance(value, dict) and isinstance(value.get("sources"), dict):
+ sources = _source_digests(
+ value["sources"], "Saved stopped-scan source digests are malformed."
+ )
+ model_source = value.get("threatModelSource")
+ if not isinstance(model_source, str) or model_source not in sources:
+ raise ContractError("Saved stopped-scan model source is outside its checkpoint set.")
+ return sources, model_source
+ return _source_digests(value, "Saved stopped-scan source digests are malformed."), None
+
+
+def _encode_retained_sources(sources: dict[str, str], model_source: list[str]) -> str:
+ state = {"sources": sources, "threatModelSource": model_source[0]} if model_source else sources
+ return json.dumps(state, sort_keys=True)
+
+
+def _children(scan_dir: Path, relative: str) -> list[str]:
+ cursor = scan_dir
+ for part in Path(relative).parts:
+ if part in {"..", "."}:
+ return []
+ cursor = cursor / part
+ try:
+ if not stat.S_ISDIR(cursor.lstat().st_mode):
+ return []
+ except FileNotFoundError:
+ return []
+ return sorted(child.name for child in cursor.iterdir())
+
+
+def _checkpoint_paths(scan_dir: Path, directory: str) -> list[str]:
+ return [
+ f"{directory}/{name}"
+ for name in _children(scan_dir, directory)
+ if re.fullmatch(r"[0-9a-f]{64}\.json", name)
+ ]
def _checkpoint_head_directory(relative: str) -> Path | None:
@@ -39,10 +101,17 @@ def _capture_saved_source(
_, digest, observed = _read_saved_result(scan_dir, relative, scan_id, kind=kind)
return {relative: (digest, observed)}
head, _, observed = _read_saved_result(scan_dir, relative, scan_id)
- observation = {"checkpoint": head["checkpoint"], "observedAtNs": str(observed)}
+ observation = {
+ **{key: head[key] for key in ("checkpoint", "inputCheckpoint") if key in head},
+ "observedAtNs": str(observed),
+ }
directory = Path(relative).parent
- selected = (directory / "checkpoints" / observation["checkpoint"]).as_posix()
- _, selected_digest, selected_time = _read_saved_result(scan_dir, selected, scan_id)
+ selected_sources = {}
+ for key in ("checkpoint", "inputCheckpoint"):
+ if key in head:
+ selected = (directory / "checkpoints" / head[key]).as_posix()
+ _, selected_digest, selected_time = _read_saved_result(scan_dir, selected, scan_id)
+ selected_sources[selected] = (selected_digest, selected_time)
digest = _digest(observation)
snapshot = (directory / "checkpoint-heads" / f"{digest}.json").as_posix()
# Capture the selected file even if the worker created it after directory enumeration.
@@ -52,17 +121,10 @@ def _capture_saved_source(
write_scan_local_bytes(scan_dir, snapshot, _encoded(observation))
return {
snapshot: (digest, int(observation["observedAtNs"])),
- selected: (selected_digest, selected_time),
+ **selected_sources,
}
-def _is_source_order_snapshot(relative: str) -> bool:
- path = Path(relative)
- return path.parent == Path("source-order") and bool(
- re.fullmatch(r"[0-9a-f]{64}\.json", path.name)
- )
-
-
def _read_saved_result(
scan_dir: Path, relative: str, scan_id: str, *, kind: str | None = None
) -> tuple[dict[str, Any], str, int]:
@@ -75,6 +137,11 @@ def _read_saved_result(
if not isinstance(checkpoint, str) or not re.fullmatch(r"[0-9a-f]{64}\.json", checkpoint):
raise ContractError("checkpoint head does not name a saved checkpoint")
_read_saved_result(scan_dir, (directory / "checkpoints" / checkpoint).as_posix(), scan_id)
+ if "inputCheckpoint" in draft:
+ raw = draft["inputCheckpoint"]
+ if not isinstance(raw, str) or not re.fullmatch(r"[0-9a-f]{64}\.json", raw):
+ raise ContractError("checkpoint head does not name a saved input checkpoint")
+ _read_saved_result(scan_dir, (directory / "checkpoints" / raw).as_posix(), scan_id)
if Path(relative).name == "checkpoint-head.json":
return draft, _digest([draft, metadata.st_mtime_ns]), metadata.st_mtime_ns
observed = draft.get("observedAtNs")
@@ -91,13 +158,50 @@ def _read_saved_result(
return draft, _digest(draft), metadata.st_mtime_ns
-def _frozen_source_times(scan_dir: Path, scan_id: str, sources: dict[str, str]) -> dict[str, int]:
+def _is_source_order_snapshot(relative: str) -> bool:
+ path = Path(relative)
+ return path.parent == Path("source-order") and bool(
+ re.fullmatch(r"[0-9a-f]{64}\.json", path.name)
+ )
+
+
+def _frozen_source_times(
+ scan_dir: Path,
+ scan_id: str,
+ sources: dict[str, str],
+ parent_context: dict[str, str] | None = None,
+) -> dict[str, int]:
times: dict[str, int] = {}
snapshots = [path for path in sources if _is_source_order_snapshot(path)]
for path in snapshots:
record, digest, _ = _read_saved_result(scan_dir, path, scan_id)
if digest != sources[path] or not isinstance(record.get("sources"), dict):
raise ContractError("saved source ordering changed after the scan stopped")
+ context = record.get("parentContext")
+ if parent_context is not None and context is not None:
+ if not isinstance(context, dict) or any(
+ (
+ "canonical" not in context
+ or not isinstance(relative, str)
+ or not re.fullmatch(r"-?[0-9]+", relative)
+ )
+ if role == "canonicalObservedAtNs"
+ else (
+ role not in ("canonical", "head")
+ or not isinstance(relative, str)
+ or relative not in sources
+ or (role == "canonical" and Path(relative).parent != Path("checkpoints"))
+ or (role == "head" and _checkpoint_head_directory(relative) != Path("."))
+ )
+ for role, relative in context.items()
+ ):
+ raise ContractError("saved parent context is outside the frozen sources")
+ if any(
+ role in parent_context and parent_context[role] != relative
+ for role, relative in context.items()
+ ):
+ raise ContractError("saved parent context has conflicting observations")
+ parent_context.update(context)
for relative, observation in record["sources"].items():
if (
not isinstance(observation, dict)
@@ -121,6 +225,7 @@ def _freeze_source_times(
scan_id: str,
sources: dict[str, str],
times: dict[str, int],
+ parent_context: dict[str, str] | None = None,
*,
created_paths: set[str] | None = None,
) -> None:
@@ -133,6 +238,8 @@ def _freeze_source_times(
if not observations:
return
record = {"scanId": scan_id, "sources": observations}
+ if parent_context:
+ record["parentContext"] = parent_context
digest = _digest(record)
path = f"source-order/{digest}.json"
if not (scan_dir / path).exists():
@@ -141,29 +248,260 @@ def _freeze_source_times(
write_scan_local_bytes(scan_dir, path, _encoded(record))
if _read_saved_result(scan_dir, path, scan_id)[1] != digest:
raise ContractError("saved source ordering does not match its digest")
+ if parent_context:
+ for previous in [relative for relative in sources if _is_source_order_snapshot(relative)]:
+ previous_record, _, _ = _read_saved_result(scan_dir, previous, scan_id)
+ if previous_record.get("parentContext"):
+ del sources[previous]
sources[path] = digest
-def _source_digests(value: Any, error: str) -> dict[str, str]:
- if not isinstance(value, dict) or not all(
- isinstance(relative, str) and isinstance(digest, str) for relative, digest in value.items()
- ):
- raise ContractError(error)
- return value
+def _parent_publication_ancestors(
+ input_checkpoint: str | None, drafts: dict[str, dict[str, Any]]
+) -> set[str]:
+ """Find stale canonical projections without relying on publication clocks."""
+ ancestors = set()
+ inputs = set()
+ # Input hashes distinguish repeated publication of the same projected result.
+ while isinstance(input_checkpoint, str) and input_checkpoint not in inputs:
+ inputs.add(input_checkpoint)
+ publication = drafts.get(f"checkpoints/{input_checkpoint}", {}).get("publication")
+ if not isinstance(publication, dict):
+ break
+ previous = publication.get("previousCheckpoint")
+ if isinstance(previous, str):
+ ancestors.add(f"checkpoints/{previous}")
+ input_checkpoint = publication.get("previousInputCheckpoint")
+ return ancestors
-def _retained_source_state(value: Any) -> tuple[dict[str, str], str | None]:
- if isinstance(value, dict) and isinstance(value.get("sources"), dict):
- sources = _source_digests(
- value["sources"], "Saved stopped-scan source digests are malformed."
+def _admit_parent_checkpoint(
+ scan_dir: Path, scan_id: str, checkpoint: dict[str, Any], projected: dict[str, Any]
+) -> bytes:
+ """Bind a Deep input to the accepted head under the host's publication lock."""
+ previous = {}
+ try:
+ previous, _, _ = _read_saved_result(scan_dir, "checkpoint-head.json", scan_id)
+ if (
+ previous.get("checkpoint") == f"{_digest(projected)}.json"
+ and "inputCheckpoint" in previous
+ ):
+ accepted, _, _ = _read_saved_result(
+ scan_dir, f"checkpoints/{previous['inputCheckpoint']}", scan_id
+ )
+ if {key: value for key, value in accepted.items() if key != "publication"} == {
+ key: value for key, value in checkpoint.items() if key != "publication"
+ }:
+ for relative in _checkpoint_paths(scan_dir, "checkpoints"):
+ pending, _, _ = _read_saved_result(scan_dir, relative, scan_id)
+ publication = pending.get("publication")
+ if (
+ isinstance(publication, dict)
+ and publication.get("previousInputCheckpoint")
+ == previous["inputCheckpoint"]
+ ):
+ break
+ else:
+ return _encoded(accepted)
+ except (ContractError, OSError, ValueError):
+ pass # An absent or unreadable previous head contributes no predecessor.
+ return _encoded(
+ {
+ **checkpoint,
+ "publication": {
+ "previousCheckpoint": previous.get("checkpoint"),
+ "previousInputCheckpoint": previous.get("inputCheckpoint"),
+ },
+ }
+ )
+
+
+def _capture_parent_observation(
+ scan_dir: Path,
+ checkpoint: str,
+ observed: int,
+ legacy_head: bool = False,
+ *,
+ created_paths: set[str] | None = None,
+) -> dict[str, tuple[str, int]]:
+ """Freeze canonical input, preserving the legacy sealed-parent migration."""
+ if legacy_head:
+ write_scan_local_bytes(
+ scan_dir, "checkpoint-head.json", _encoded({"checkpoint": checkpoint})
)
- model_source = value.get("threatModelSource")
- if not isinstance(model_source, str) or model_source not in sources:
- raise ContractError("Saved stopped-scan model source is outside its checkpoint set.")
- return sources, model_source
- return _source_digests(value, "Saved stopped-scan source digests are malformed."), None
+ os.utime(scan_dir / "checkpoint-head.json", ns=(observed, observed))
+ observation = {"checkpoint": checkpoint, "observedAtNs": str(observed)}
+ digest = _digest(observation)
+ snapshot = f"checkpoint-heads/{digest}.json"
+ if not (scan_dir / snapshot).exists():
+ if created_paths is not None and not os.path.lexists(scan_dir / snapshot):
+ created_paths.add(snapshot)
+ write_scan_local_bytes(scan_dir, snapshot, _encoded(observation))
+ return {snapshot: (digest, observed)}
-def _encode_retained_sources(sources: dict[str, str], model_source: list[str]) -> str:
- state = {"sources": sources, "threatModelSource": model_source[0]} if model_source else sources
- return json.dumps(state, sort_keys=True)
+def _parent_scan_draft(
+ scan_id: str,
+ parent_scan: dict[str, Any],
+ findings: dict[str, Any],
+ coverage: dict[str, Any],
+) -> dict[str, Any]:
+ parent = {
+ "scanId": scan_id,
+ "findings": findings.get("findings"),
+ "coverage": coverage,
+ **{
+ key: parent_scan[key]
+ for key in ("scope", "threatModel", "complete")
+ if key in parent_scan
+ },
+ }
+ if not isinstance(parent["findings"], list):
+ raise ContractError("Saved parent draft has no findings array")
+ return parent
+
+
+def _read_saved_parent_result(
+ scan_dir: Path, scan_id: str
+) -> tuple[dict[str, Any], dict[str, Any]]:
+ manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "Saved parent manifest")
+ findings = _read_scan_local_json(scan_dir, "findings.json", "Saved parent findings")
+ coverage = _read_scan_local_json(scan_dir, "coverage.json", "Saved parent coverage")
+ parent_scan = manifest.get("scan")
+ if not isinstance(parent_scan, dict):
+ raise ContractError("Saved parent manifest has no scan object")
+ if manifest_is_sealed(parent_scan) and (
+ parent_scan.get("id", scan_id) != scan_id
+ or findings.get("scanId", scan_id) != scan_id
+ or coverage.get("scanId", scan_id) != scan_id
+ ):
+ raise ContractError("Saved parent documents belong to a different scan")
+ return manifest, _parent_scan_draft(scan_id, parent_scan, findings, coverage)
+
+
+def _require_current_deep_publication(
+ db: Any, connection: Any, scan: Any, draft: dict[str, Any]
+) -> None:
+ scan_id = scan["id"]
+ run = connection.execute(
+ "SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
+ ).fetchone()
+ publication = draft.get("deepScanPublication")
+ if (
+ publication is None
+ and draft["manifest"]["scan"].get("complete") is False
+ and (run is None or run["status"] == "running")
+ ):
+ return
+ if run is None:
+ run = db.deep_scan.require_deep_scan_run(connection, scan_id)
+ # Finished discovery-only runs hand remaining publication back to the parent.
+ if (
+ publication is None
+ and run["status"] != "running"
+ and run["manifest_path"] != str(Path(scan["scan_dir"]) / "scan-manifest.json")
+ ):
+ return
+ db.deep_scan.require_current_coordinator(
+ run,
+ argparse.Namespace(
+ coordinator_generation=publication.get("coordinatorGeneration") if publication else None
+ ),
+ )
+ # Once finish selects the canonical parent, only completion may replay it.
+ if publication is None:
+ if run["status"] != "running" and run["manifest_path"] == str(
+ Path(scan["scan_dir"]) / "scan-manifest.json"
+ ):
+ raise SystemExit("Deep Scan is terminal; drafts cannot replace its publication.")
+ return
+
+ # Match the durable reducer sequence used by coordinator recovery.
+ def reducer_order(worker: Any) -> tuple[int, str]:
+ match = re.fullmatch(r"dedup-([0-9]+)", Path(worker["prompt_path"]).parent.name)
+ return (int(match[1]) if match else 0, worker["id"])
+
+ reducer = max(
+ (
+ worker
+ for worker in connection.execute(
+ "SELECT * FROM deep_scan_workers WHERE scan_id = ?", (scan_id,)
+ )
+ if worker["kind"] == "dedup"
+ and worker["status"] == "succeeded"
+ and worker["result_manifest_path"]
+ ),
+ key=reducer_order,
+ default=None,
+ )
+ selected_result = reducer["result_manifest_path"] if reducer is not None else None
+ if publication["resultPath"] != selected_result:
+ raise SystemExit("Deep Scan aggregate belongs to a superseded publication selection.")
+
+
+if __name__ == "__main__":
+ argparse.ArgumentParser(description=__doc__).parse_args()
+
+
+def _latest_successful_reducer(workers: list[Any]) -> Any | None:
+ return max(
+ (
+ worker
+ for worker in workers
+ if worker["kind"] == "dedup"
+ and worker["status"] == "succeeded"
+ and worker["result_manifest_path"]
+ ),
+ key=lambda worker: (worker["completed_at"] or "", worker["id"]),
+ default=None,
+ )
+
+
+def _worker_outputs(scan_dir: Path, worker: Any) -> list[tuple[str, int]]:
+ output = Path(worker["artifact_dir"]).relative_to(scan_dir)
+ attempts = (output.parent if output.name == "output" else output) / "attempts"
+ archived = [
+ ((attempts / name).as_posix(), int(name.split("-")[1]))
+ for name in _children(scan_dir, attempts.as_posix())
+ if re.fullmatch(r"attempt-\d+", name)
+ ]
+ attempt = int(worker["attempt"] or 0) if "attempt" in worker.keys() else 0
+ if worker["kind"] == "discovery" and not attempt:
+ attempt = max((attempt for _, attempt in archived), default=0) + 1
+ return [(output.as_posix(), attempt), *archived]
+
+
+def _saved_result_paths(scan_dir: Path, workers: list[Any]) -> Iterator[tuple[str, str | None]]:
+ latest_reducer = _latest_successful_reducer(workers)
+ yield "checkpoint-head.json", None
+ for directory in ("checkpoint-heads", "checkpoints"):
+ yield from ((path, None) for path in _checkpoint_paths(scan_dir, directory))
+ for worker in workers:
+ if worker["kind"] not in {"dedup", "discovery"}:
+ continue
+ try:
+ outputs = _worker_outputs(scan_dir, worker)
+ except (TypeError, ValueError):
+ continue
+ for directory, _ in outputs:
+ if worker["kind"] == "discovery":
+ yield f"{directory}/checkpoint-head.json", worker["kind"]
+ yield from (
+ (path, worker["kind"])
+ for path in _checkpoint_paths(scan_dir, f"{directory}/checkpoint-heads")
+ )
+ checkpoint_paths = _checkpoint_paths(scan_dir, f"{directory}/checkpoints")
+ if worker["kind"] == "discovery" or checkpoint_paths:
+ yield f"{directory}/result.json", worker["kind"]
+ yield from ((path, worker["kind"]) for path in checkpoint_paths)
+ if worker["result_manifest_path"] and (
+ worker["kind"] == "discovery"
+ or (latest_reducer is not None and worker["id"] == latest_reducer["id"])
+ ):
+ try:
+ yield (
+ Path(worker["result_manifest_path"]).relative_to(scan_dir).as_posix(),
+ worker["kind"],
+ )
+ except ValueError:
+ continue
diff --git a/plugins/codex-security/scripts/workbench_db.py b/plugins/codex-security/scripts/workbench_db.py
index 6fcb505f3..32d10e5a2 100644
--- a/plugins/codex-security/scripts/workbench_db.py
+++ b/plugins/codex-security/scripts/workbench_db.py
@@ -51,6 +51,7 @@ from finalize_scan_contract import (
_write_prepared_scan_finalization,
finalize_scan,
finding_candidate_id,
+ manifest_is_sealed,
open_scan_local_file_descriptor,
write_scan_local_bytes,
)
@@ -1365,7 +1366,7 @@ def budget_exhausted_draft(
for key in ("surfaces", "explicitExclusions", "deferred"):
if not isinstance(coverage.get(key), list):
raise SystemExit("Budget-exhausted scan contains invalid canonical coverage.")
- if manifest["scan"].get("sealedAt") is not None or manifest["scan"].get("artifacts"):
+ if manifest_is_sealed(manifest["scan"]):
raise SystemExit("Budget-exhausted scan cannot replace an already sealed scan draft.")
else:
contract = scan_contract(scan)
@@ -1530,10 +1531,7 @@ def complete_scan_locked(
already_sealed = (
current_manifest_path is not None
and isinstance(current_manifest.get("scan"), dict)
- and (
- current_manifest["scan"].get("sealedAt") is not None
- or current_manifest["scan"].get("artifacts") is not None
- )
+ and manifest_is_sealed(current_manifest["scan"])
)
completion_binding = workbench_completion_binding(scan, completion_timestamp, current_manifest)
if scan["recipe_json"] is not None:
@@ -1576,6 +1574,7 @@ def complete_scan_locked(
).fetchall(),
warnings,
stopped=False,
+ scan_mode=scan["mode"],
reason="",
)
if merge_parent_draft
diff --git a/plugins/codex-security/scripts/workbench_saved_results.py b/plugins/codex-security/scripts/workbench_saved_results.py
index d9a94ff31..75e6d5900 100644
--- a/plugins/codex-security/scripts/workbench_saved_results.py
+++ b/plugins/codex-security/scripts/workbench_saved_results.py
@@ -10,7 +10,6 @@ import json
import os
import re
import sqlite3
-import stat
import sys
from collections.abc import Iterator
from contextlib import contextmanager
@@ -21,47 +20,24 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
from finalize_scan_contract import (
ContractError,
ScanLocalIOError,
- _finding_strength,
_populate_unsealed_artifact_envelope,
_populate_unsealed_manifest_envelope,
_prepare_scan_finalization,
- _read_json,
_read_saved_threat_model,
_read_scan_local_json,
_read_scan_local_json_bytes,
_recover_unsealed_coverage,
_recover_unsealed_findings,
_remove_scan_local_file_if_exists,
- _require_portable_relative_path,
- _require_safe_json_value,
_validate_completion_binding,
- _validate_current_findings,
- _validate_schema_node,
_write_prepared_scan_finalization,
finalize_scan,
- finding_candidate_id,
+ manifest_is_sealed,
open_scan_local_file_descriptor,
write_scan_local_bytes,
write_threat_model_projection_if_possible,
)
-from workbench.saved_coverage import (
- _prepare_worker_coverage_recovery,
- _project_worker_coverage_row,
- _saved_coverage_id,
-)
-from workbench.saved_outputs import _restore_published_outputs, _snapshot_published_outputs
-from workbench_constants import PHASES
-from workbench_target import committed_diff_snapshot_digest
-from workbench_validation import path_within_scope
-
-_PUBLICATION_FOLLOW_UP_WARNING = (
- "Saved scan evidence remains on disk; result publication needs follow-up:"
-)
-_RESERVED_ARTIFACT_PATHS = json.loads(
- Path(__file__).with_name("reserved_artifact_paths.json").read_text(encoding="utf-8")
-)
-
-
+from finalize_scan_contract import finding_candidate_id as finding_candidate_id
from workbench.retained_coverage import (
_append_previous_finding as _append_previous_finding,
)
@@ -72,10 +48,10 @@ from workbench.retained_coverage import (
_deferred_candidate_id as _deferred_candidate_id,
)
from workbench.retained_coverage import (
- _digest as _digest,
+ _deferred_rows as _deferred_rows,
)
from workbench.retained_coverage import (
- _encoded as _encoded,
+ _ensure_finding_identities as _ensure_finding_identities,
)
from workbench.retained_coverage import (
_ensure_finding_identity as _ensure_finding_identity,
@@ -83,6 +59,9 @@ from workbench.retained_coverage import (
from workbench.retained_coverage import (
_finding_content as _finding_content,
)
+from workbench.retained_coverage import (
+ _finding_identity as _finding_identity,
+)
from workbench.retained_coverage import (
_finding_key as _finding_key,
)
@@ -92,6 +71,9 @@ from workbench.retained_coverage import (
from workbench.retained_coverage import (
_has_candidate_metadata as _has_candidate_metadata,
)
+from workbench.retained_coverage import (
+ _identity_candidate as _identity_candidate,
+)
from workbench.retained_coverage import (
_inherit_coverage_sources as _inherit_coverage_sources,
)
@@ -104,35 +86,59 @@ from workbench.retained_coverage import (
from workbench.retained_coverage import (
_retained_findings as _retained_findings,
)
+from workbench.retained_coverage import (
+ _semantic_identity_key as _semantic_identity_key,
+)
from workbench.retained_coverage import (
_worker_candidate_key as _worker_candidate_key,
)
-from workbench.saved_sources import (
- _capture_saved_source as _capture_saved_source,
+from workbench.retained_coverage import merge_saved_results as merge_saved_results
+from workbench.saved_coverage import (
+ _saved_coverage_id as _saved_coverage_id,
)
+from workbench.saved_outputs import _restore_published_outputs, _snapshot_published_outputs
from workbench.saved_sources import (
- _checkpoint_head_directory as _checkpoint_head_directory,
+ _admit_parent_checkpoint,
+ _capture_saved_source,
+ _checkpoint_paths,
+ _encode_retained_sources,
+ _encoded,
+ _freeze_source_times,
+ _frozen_source_times,
+ _is_source_order_snapshot,
+ _parent_scan_draft,
+ _read_saved_parent_result,
+ _read_saved_result,
+ _require_current_deep_publication,
+ _retained_source_state,
+ _saved_result_paths,
+ _source_digests,
)
from workbench.saved_sources import (
- _encode_retained_sources as _encode_retained_sources,
+ _capture_parent_observation as _capture_parent_observation,
)
from workbench.saved_sources import (
- _freeze_source_times as _freeze_source_times,
+ _checkpoint_head_directory as _checkpoint_head_directory,
)
from workbench.saved_sources import (
- _frozen_source_times as _frozen_source_times,
+ _digest as _digest,
)
from workbench.saved_sources import (
- _is_source_order_snapshot as _is_source_order_snapshot,
+ _latest_successful_reducer as _latest_successful_reducer,
)
from workbench.saved_sources import (
- _read_saved_result as _read_saved_result,
+ _parent_publication_ancestors as _parent_publication_ancestors,
)
from workbench.saved_sources import (
- _retained_source_state as _retained_source_state,
+ _worker_outputs as _worker_outputs,
)
-from workbench.saved_sources import (
- _source_digests as _source_digests,
+from workbench_constants import PHASES
+
+_PUBLICATION_FOLLOW_UP_WARNING = (
+ "Saved scan evidence remains on disk; result publication needs follow-up:"
+)
+_RESERVED_ARTIFACT_PATHS = json.loads(
+ Path(__file__).with_name("reserved_artifact_paths.json").read_text(encoding="utf-8")
)
@@ -191,131 +197,6 @@ def refresh_completed_scan(
return db.scan_context(connection, scan["id"])
-def _children(scan_dir: Path, relative: str) -> list[str]:
- cursor = scan_dir
- for part in Path(relative).parts:
- if part in {"..", "."}:
- return []
- cursor = cursor / part
- try:
- if not stat.S_ISDIR(cursor.lstat().st_mode):
- return []
- except FileNotFoundError:
- return []
- return sorted(child.name for child in cursor.iterdir())
-
-
-def _latest_successful_reducer(workers: list[Any]) -> Any | None:
- return max(
- (
- worker
- for worker in workers
- if worker["kind"] == "dedup"
- and worker["status"] == "succeeded"
- and worker["result_manifest_path"]
- ),
- key=lambda worker: (worker["completed_at"] or "", worker["id"]),
- default=None,
- )
-
-
-def _checkpoint_paths(scan_dir: Path, directory: str) -> list[str]:
- return [
- f"{directory}/{name}"
- for name in _children(scan_dir, directory)
- if re.fullmatch(r"[0-9a-f]{64}\.json", name)
- ]
-
-
-def _worker_outputs(scan_dir: Path, worker: Any) -> list[tuple[str, int]]:
- output = Path(worker["artifact_dir"]).relative_to(scan_dir)
- attempts = (output.parent if output.name == "output" else output) / "attempts"
- archived = [
- ((attempts / name).as_posix(), int(name.split("-")[1]))
- for name in _children(scan_dir, attempts.as_posix())
- if re.fullmatch(r"attempt-\d+", name)
- ]
- attempt = int(worker["attempt"] or 0) if "attempt" in worker.keys() else 0
- if worker["kind"] == "discovery" and not attempt:
- attempt = max((attempt for _, attempt in archived), default=0) + 1
- return [(output.as_posix(), attempt), *archived]
-
-
-def _saved_result_paths(scan_dir: Path, workers: list[Any]) -> Iterator[tuple[str, str | None]]:
- latest_reducer = _latest_successful_reducer(workers)
- yield "checkpoint-head.json", None
- for directory in ("checkpoint-heads", "checkpoints"):
- yield from ((path, None) for path in _checkpoint_paths(scan_dir, directory))
- for worker in workers:
- if worker["kind"] not in {"dedup", "discovery"}:
- continue
- try:
- outputs = _worker_outputs(scan_dir, worker)
- except (TypeError, ValueError):
- continue
- for directory, _ in outputs:
- if worker["kind"] == "discovery":
- yield f"{directory}/checkpoint-head.json", worker["kind"]
- yield from (
- (path, worker["kind"])
- for path in _checkpoint_paths(scan_dir, f"{directory}/checkpoint-heads")
- )
- checkpoint_paths = _checkpoint_paths(scan_dir, f"{directory}/checkpoints")
- if worker["kind"] == "discovery" or checkpoint_paths:
- yield f"{directory}/result.json", worker["kind"]
- yield from ((path, worker["kind"]) for path in checkpoint_paths)
- if worker["result_manifest_path"] and (
- worker["kind"] == "discovery"
- or (latest_reducer is not None and worker["id"] == latest_reducer["id"])
- ):
- try:
- yield (
- Path(worker["result_manifest_path"]).relative_to(scan_dir).as_posix(),
- worker["kind"],
- )
- except ValueError:
- continue
-
-
-def _parent_scan_draft(
- scan_id: str,
- parent_scan: dict[str, Any],
- findings: dict[str, Any],
- coverage: dict[str, Any],
-) -> dict[str, Any]:
- parent = {
- "scanId": scan_id,
- "findings": findings.get("findings"),
- "coverage": coverage,
- **{
- key: parent_scan[key]
- for key in ("scope", "threatModel", "complete")
- if key in parent_scan
- },
- }
- if not isinstance(parent["findings"], list):
- raise ContractError("Saved parent draft has no findings array")
- return parent
-
-
-def _read_saved_parent_result(
- scan_dir: Path, scan_id: str
-) -> tuple[dict[str, Any], dict[str, Any]]:
- manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "Saved parent manifest")
- findings = _read_scan_local_json(scan_dir, "findings.json", "Saved parent findings")
- coverage = _read_scan_local_json(scan_dir, "coverage.json", "Saved parent coverage")
- parent_scan = manifest.get("scan")
- if not isinstance(parent_scan, dict):
- raise ContractError("Saved parent manifest has no scan object")
- if (parent_scan.get("sealedAt") or parent_scan.get("artifacts")) and (
- parent_scan.get("id", scan_id) != scan_id
- or findings.get("scanId", scan_id) != scan_id
- or coverage.get("scanId", scan_id) != scan_id
- ):
- raise ContractError("Saved parent documents belong to a different scan")
- return manifest, _parent_scan_draft(scan_id, parent_scan, findings, coverage)
-
-
def _saved_results_changed(db: Any, connection: Any, scan: Any) -> bool:
try:
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
@@ -399,9 +280,7 @@ def _recovery_source_digests(db: Any, connection: Any, scan: Any) -> tuple[dict[
manifest_scan = manifest.get("scan")
if not isinstance(manifest_scan, dict):
raise ContractError("Saved scan manifest has no scan object")
- if scan["seal_manifest_digest"] is not None or (
- manifest_scan.get("sealedAt") is not None or manifest_scan.get("artifacts") is not None
- ):
+ if scan["seal_manifest_digest"] is not None or manifest_is_sealed(manifest_scan):
if "preservedSources" in manifest_scan:
published_sources = _source_digests(
manifest_scan["preservedSources"],
@@ -426,7 +305,8 @@ def _recovery_source_digests(db: Any, connection: Any, scan: Any) -> tuple[dict[
).fetchall()
paths = dict(_saved_result_paths(scan_dir, workers))
recovery_sources = dict(frozen_sources or {})
- source_times = _frozen_source_times(scan_dir, scan["id"], recovery_sources)
+ parent_context: dict[str, str] = {}
+ source_times = _frozen_source_times(scan_dir, scan["id"], recovery_sources, parent_context)
for relative, expected_digest in recovery_sources.items():
try:
_, digest, observed = _read_saved_result(
@@ -444,12 +324,14 @@ def _recovery_source_digests(db: Any, connection: Any, scan: Any) -> tuple[dict[
captured = _capture_saved_source(scan_dir, relative, scan["id"], kind=paths[relative])
except (ContractError, OSError, ValueError):
continue
+ if relative == "checkpoint-head.json":
+ parent_context["head"] = next(iter(captured))
for path, (digest, observed) in captured.items():
if path in recovery_sources and recovery_sources[path] != digest:
raise ContractError("checkpoint changed after the scan stopped")
recovery_sources[path] = digest
source_times.setdefault(path, observed)
- _freeze_source_times(scan_dir, scan["id"], recovery_sources, source_times)
+ _freeze_source_times(scan_dir, scan["id"], recovery_sources, source_times, parent_context)
return recovery_sources, include_parent
@@ -510,1742 +392,6 @@ def preserve_parent_head_on_error(scan_dir: Path) -> Iterator[None]:
raise
-def merge_saved_results(
- scan_dir: Path,
- scan_id: str,
- binding: dict[str, Any],
- workers: list[Any],
- warnings: list[str],
- *,
- stopped: bool,
- reason: str,
- frozen_source_digests: dict[str, str] | None = None,
- allow_frozen_legacy_parent: bool = False,
- frozen_model_source: str | None = None,
- selected_model_source: list[str] | None = None,
- preserve_canonical_parent: bool = False,
- project_worker_coverage: bool = False,
- created_paths: set[str] | None = None,
- current_contract: bool = False,
-) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None:
- """Read only bound parent/worker files; return an unsealed loss-preserving union."""
- initial_warnings = set(warnings)
- try:
- source_times = _frozen_source_times(scan_dir, scan_id, frozen_source_digests or {})
- except (ContractError, OSError, ValueError) as exc:
- raise ContractError("Frozen stopped-scan checkpoint set is incomplete.") from exc
- parent: dict[str, Any] | None = None
- parent_manifest: dict[str, Any] | None = None
- parent_is_canonical = False
- parent_modified = 0
- if frozen_source_digests is None or allow_frozen_legacy_parent:
- try:
- parent_manifest, parent = _read_saved_parent_result(scan_dir, scan_id)
- # Without an accepted head, file-authored coverage is a full replacement.
- parent_modified = (scan_dir / "coverage.json").lstat().st_mtime_ns
- parent_is_canonical = True
- except (ContractError, OSError, ValueError) as exc:
- if not stopped:
- raise
- if (scan_dir / "scan-manifest.json").exists():
- warnings.append(f"Could not read the saved parent draft: {exc}")
- parent_manifest = None
- parent = None
- if parent_manifest is not None and parent is not None and not preserve_canonical_parent:
- parent_scan = parent_manifest["scan"]
- try:
- previous_head, _, head_modified = _read_saved_result(
- scan_dir, "checkpoint-head.json", scan_id
- )
- except (ContractError, OSError, ValueError):
- head_modified = None
- if head_modified is not None:
- # A partial tool publication must not outrank its accepted head.
- parent_modified = min(
- (scan_dir / name).lstat().st_mtime_ns
- for name in ("findings.json", "coverage.json", "scan-manifest.json")
- )
- if not parent_scan.get("sealedAt") or allow_frozen_legacy_parent:
- head_path = scan_dir / "checkpoint-head.json"
- tied_observations = False
- if head_modified == parent_modified:
- previous_parent, _, _ = _read_saved_result(
- scan_dir, f"checkpoints/{previous_head['checkpoint']}", scan_id
- )
- if previous_parent != parent:
- # Tied observations cannot decide which pending work came last.
- parent = _merge_tied_parent_observations(parent, previous_parent)
- parent_is_canonical = False
- tied_observations = True
- payload = _encoded(parent)
- parent_digest = hashlib.sha256(payload).hexdigest()
- parent_checkpoint = f"checkpoints/{parent_digest}.json"
- checkpoint_path = scan_dir / parent_checkpoint
- if not checkpoint_path.exists():
- if created_paths is not None and not os.path.lexists(checkpoint_path):
- created_paths.add(parent_checkpoint)
- write_scan_local_bytes(scan_dir, parent_checkpoint, payload)
- # A recovery copy must not appear newer than the review it copies.
- os.utime(checkpoint_path, ns=(parent_modified, parent_modified))
- if head_modified is None or head_modified < parent_modified or tied_observations:
- write_scan_local_bytes(
- scan_dir,
- "checkpoint-head.json",
- _encoded({"checkpoint": checkpoint_path.name}),
- )
- os.utime(head_path, ns=(parent_modified, parent_modified))
- if frozen_source_digests is not None:
- captured = _capture_saved_source(
- scan_dir, "checkpoint-head.json", scan_id, created_paths=created_paths
- )
- frozen_source_digests = {
- **frozen_source_digests,
- parent_checkpoint: parent_digest,
- **{path: value[0] for path, value in captured.items()},
- }
-
- sources: list[tuple[str, dict[str, Any], str | None]] = []
- parent_preserved_sources: dict[str, str] = {}
- source_digests: dict[str, str] = {}
- source_order: dict[str, tuple[int, int]] = {}
- worker_attempts: dict[str, tuple[str, int]] = {}
- saved_heads: dict[str, str] = {}
- if parent_manifest:
- recorded = parent_manifest["scan"].get("preservedSources", {})
- if isinstance(recorded, dict):
- parent_preserved_sources = recorded
- source_digests.update(parent_preserved_sources)
- if frozen_source_digests is None:
- source_times.update(_frozen_source_times(scan_dir, scan_id, recorded))
- paths: dict[str, str | None] = {}
- reducer_paths: set[str] = set()
- current_results: set[str] = set()
- reducer_outputs: list[tuple[Any, str, list[str], int]] = []
- reducer = _latest_successful_reducer(workers)
- latest_reducer: str | None = None
- if reducer is not None:
- try:
- latest_reducer = Path(reducer["result_manifest_path"]).relative_to(scan_dir).as_posix()
- paths[latest_reducer] = None
- reducer_paths.add(latest_reducer)
- except ValueError:
- warnings.append("Skipped a reducer result outside the scan directory.")
-
- def checkpoints(directory: str, worker_id: str | None, attempt: int = 0) -> None:
- if worker_id is not None:
- root = Path(directory).parent.as_posix()
- worker_attempts[root] = (worker_id, attempt)
- paths[f"{root}/checkpoint-head.json"] = worker_id
- head_snapshots = (Path(directory).parent / "checkpoint-heads").as_posix()
- for saved_directory in (directory, head_snapshots):
- paths.update(dict.fromkeys(_checkpoint_paths(scan_dir, saved_directory), worker_id))
-
- if not preserve_canonical_parent:
- paths["checkpoint-head.json"] = None
- checkpoints("checkpoints", None)
- for worker in workers:
- try:
- outputs = _worker_outputs(scan_dir, worker)
- except (TypeError, ValueError):
- warnings.append("Skipped a worker checkpoint outside the scan directory.")
- continue
- if worker["kind"] == "dedup":
- for directory, attempt in outputs:
- checkpoint_paths = _checkpoint_paths(scan_dir, f"{directory}/checkpoints")
- if not checkpoint_paths:
- continue
- result_path = f"{directory}/result.json"
- retained_paths = [result_path, *checkpoint_paths]
- paths.update(dict.fromkeys(retained_paths))
- reducer_paths.update(retained_paths)
- reducer_outputs.append((worker, result_path, checkpoint_paths, attempt))
- continue
- if worker["kind"] != "discovery":
- continue
- output, attempt = outputs[0]
- paths[f"{output}/result.json"] = worker["id"]
- current_results.add(f"{output}/result.json")
- for archived, archived_attempt in outputs[1:]:
- paths[f"{archived}/result.json"] = worker["id"]
- checkpoints(f"{archived}/checkpoints", worker["id"], archived_attempt)
- checkpoints(f"{output}/checkpoints", worker["id"], attempt)
- if worker["result_manifest_path"]:
- try:
- current_path = Path(worker["result_manifest_path"]).relative_to(scan_dir).as_posix()
- paths[current_path] = worker["id"]
- current_results.add(current_path)
- except ValueError:
- warnings.append("Skipped a worker result outside the scan directory.")
-
- if frozen_source_digests is None:
- for relative, worker_id in list(paths.items()):
- if Path(relative).name != "checkpoint-head.json":
- continue
- del paths[relative]
- try:
- captured = _capture_saved_source(
- scan_dir, relative, scan_id, created_paths=created_paths
- )
- paths.update({path: worker_id for path in captured})
- except (ContractError, OSError, ValueError) as exc:
- if (scan_dir / relative).exists():
- warnings.append(f"Preserved unreadable checkpoint {relative}: {exc}")
-
- if frozen_source_digests is not None:
- source_digests.update(
- {
- path: digest
- for path, digest in frozen_source_digests.items()
- if _is_source_order_snapshot(path)
- }
- )
- paths = {
- relative: worker_id
- for relative, worker_id in paths.items()
- if relative in frozen_source_digests
- }
- current_results.intersection_update(frozen_source_digests)
- if latest_reducer not in frozen_source_digests:
- latest_reducer = None
-
- discarded_by_source: dict[str, list[str]] = {}
- for relative, worker_id in paths.items():
- try:
- draft, digest, observed = _read_saved_result(
- scan_dir, relative, scan_id, kind="dedup" if relative in reducer_paths else None
- )
- if frozen_source_digests is not None and frozen_source_digests[relative] != digest:
- raise ContractError("checkpoint changed after the scan stopped")
- source_digests[relative] = digest
- source_times.setdefault(relative, observed)
- source_order[relative] = (0, source_times[relative])
- if _checkpoint_head_directory(relative) is not None:
- saved_heads[relative] = draft["checkpoint"]
- continue
- if preserve_canonical_parent and worker_id is not None:
- # Recover imported records without relaxing canonical parent validation.
- if "complete" in draft and not isinstance(draft["complete"], bool):
- draft["complete"] = False
- warnings.append(
- f"{relative}: Invalid complete marker; retained as a progress checkpoint."
- )
- schema_dir = Path(__file__).resolve().parent.parent / "schemas"
- if "threatModel" in draft:
- try:
- model = draft["threatModel"]
- if isinstance(model, dict):
- model = {**model, "origin": "recovered"}
- schema = _read_json(schema_dir / "scan-manifest.schema.json")
- _validate_schema_node(
- model,
- schema["properties"]["scan"]["properties"]["threatModel"],
- "threatModel",
- schema,
- )
- _require_safe_json_value(model, "threatModel")
- except ContractError as exc:
- draft.pop("threatModel")
- warnings.append(f"{relative}: Skipped malformed threat model: {exc}.")
- directory = Path(relative).parent
- if directory.name == "checkpoints":
- directory = directory.parent
- recovered_findings = []
- for index, finding in enumerate(draft["findings"]):
- _ensure_finding_identity(finding)
- recovered = {"scanId": scan_id, "findings": [finding]}
- source_warnings: list[str] = []
- discarded = _recover_unsealed_findings(
- {"scan": {"id": scan_id, "target": binding["target"]}},
- recovered,
- schema_dir,
- scan_dir / directory,
- source_warnings,
- )
- if recovered["findings"]:
- try:
- _validate_current_findings(recovered, schema_dir)
- except ContractError as exc:
- warning = f"Skipped malformed finding: {exc}."
- source_warnings.append(warning)
- discarded.append(warning)
- recovered["findings"] = []
- if discarded:
- discarded_by_source.setdefault(relative, []).extend(discarded)
- for recovered_finding in recovered["findings"]:
- writeup = recovered_finding.pop("writeup", None)
- if writeup is not None:
- source_warnings.append(
- "Retained worker writeup at "
- f"{directory.as_posix()}/{writeup['reportPath']}; "
- "the parent report renders this finding inline."
- )
- recovered_findings.extend(recovered["findings"])
- warnings.extend(
- f"{relative} finding {index + 1}: {warning}" for warning in source_warnings
- )
- draft["findings"] = recovered_findings
- for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions"):
- rows = draft["coverage"].get(field)
- if not isinstance(rows, list):
- continue
- for index, row in enumerate(rows):
- if field == "openQuestions" and isinstance(row, str):
- row = rows[index] = {"question": row}
- if not isinstance(row, dict):
- continue
- row["workerId"] = worker_id
- refs = row.get("receiptRefs")
- if not isinstance(refs, list):
- continue
- for ref_index, ref in enumerate(refs):
- if not isinstance(ref, str):
- continue
- try:
- normalized = _require_portable_relative_path(ref, "receiptRef")
- except ContractError:
- # Keep malformed references for the finalizer's diagnostics.
- continue
- if normalized.startswith("artifacts/"):
- refs[ref_index] = f"{directory.as_posix()}/{normalized}"
- # Recovery expects coverage, but reducer results only contain findings
- # and context. Add an empty value after hashing the original result.
- sources.append((relative, {"coverage": {}, **draft}, worker_id))
- except (ContractError, OSError, ValueError) as exc:
- if (scan_dir / relative).exists():
- warnings.append(f"Preserved unreadable checkpoint {relative}: {exc}")
- if frozen_source_digests is not None:
- if frozen_source_digests.keys() - source_digests.keys():
- raise ContractError("Frozen stopped-scan checkpoint set is incomplete.")
-
- # Frozen observations retain checkpoint selection even if a worker moves its head.
- headed_workers = {
- worker_attempts[_checkpoint_head_directory(head).as_posix()][0]
- for head in saved_heads
- if _checkpoint_head_directory(head) != Path(".")
- }
- for relative, _, worker_id in sources:
- if worker_id not in headed_workers:
- continue
- directory = Path(relative).parent
- if directory.name == "checkpoints":
- directory = directory.parent
- _, attempt = worker_attempts.get(directory.as_posix(), (worker_id, 0))
- source_order[relative] = (attempt, source_order[relative][1])
- selected_observations: dict[str, tuple[int, int]] = {}
- parent_heads: list[tuple[int, str]] = []
- for head, checkpoint in saved_heads.items():
- directory = _checkpoint_head_directory(head)
- selected = (directory / "checkpoints" / checkpoint).as_posix()
- if selected not in source_order:
- raise ContractError("Checkpoint head is outside the saved source set.")
- observed = source_order[head][1]
- if directory == Path("."):
- order = (0, max(source_order[selected][1], observed))
- parent_heads.append((observed, selected))
- else:
- _, attempt = worker_attempts[directory.as_posix()]
- order = (attempt, observed)
- selected_observations[selected] = max(selected_observations.get(selected, order), order)
- source_order.update(selected_observations)
-
- drafts_by_path = {relative: draft for relative, draft, _ in sources}
- latest_reducer_key = (
- (reducer["completed_at"] or "", reducer["id"], int(reducer["attempt"] or 0))
- if reducer is not None and latest_reducer in drafts_by_path
- else None
- )
- if latest_reducer_key is None:
- latest_reducer = None
- for worker, result_path, checkpoint_paths, attempt in reducer_outputs:
- result = drafts_by_path.get(result_path)
- if result is None or not any(
- drafts_by_path.get(checkpoint_path) == result for checkpoint_path in checkpoint_paths
- ):
- continue
- current_results.add(result_path)
- candidate_key = (worker["completed_at"] or "", worker["id"], attempt)
- if latest_reducer_key is None or candidate_key > latest_reducer_key:
- latest_reducer_key = candidate_key
- latest_reducer = result_path
-
- if parent_heads:
- latest_observation = max(observed for observed, _ in parent_heads)
- for observed, parent_path in parent_heads:
- if observed != latest_observation:
- continue
- draft = drafts_by_path[parent_path]
- modified = source_order[parent_path][1]
- if parent is None or modified > parent_modified:
- parent = draft
- parent_modified = modified
- parent_is_canonical = False
- elif modified == parent_modified and draft != parent:
- parent = _merge_tied_parent_observations(parent, draft)
- parent_is_canonical = False
- if parent is None and latest_reducer is not None:
- parent = drafts_by_path[latest_reducer]
-
- if preserve_canonical_parent:
- project_worker_coverage, surface_links = False, []
- else:
- project_worker_coverage, surface_links = _prepare_worker_coverage_recovery(
- sources, parent, source_order, enabled=project_worker_coverage
- )
- # Keep the actual retained row even when recovery adds previous findings.
- linked_surface_sources = {id(surface) for _, _, surface, _, _ in surface_links}
- linked_surface_outputs: dict[int, dict[str, Any]] = {}
- worker_row_owners: dict[int, str] = {}
- worker_surface_outputs: dict[tuple[str, str], dict[int, dict[str, Any]]] = {}
-
- def record_coverage_owner(retained: Any, item: Any, owner: str | None, field: str) -> None:
- # Parent aggregates can carry worker metadata without originating in
- # that worker's retained source. Track the actual source of output rows.
- if project_worker_coverage and owner is not None and isinstance(retained, dict):
- worker_row_owners[id(retained)] = owner
- if field == "surfaces" and isinstance(item.get("id"), str):
- worker_surface_outputs.setdefault((owner, item["id"]), {})[id(retained)] = retained
-
- def append_coverage_row(output: list[Any], item: Any, owner: str | None, field: str) -> Any:
- retained = _project_worker_coverage_row(
- item, owner if project_worker_coverage else None, field
- )
- if retained not in output:
- output.append(retained)
- retained = output[output.index(retained)]
- record_coverage_owner(retained, item, owner, field)
- _inherit_coverage_sources(retained, [item], coverage_sources)
- if preserve_canonical_parent:
- if id(item) in canonical_rows:
- canonical_rows.add(id(retained))
- if field == "surfaces":
- retained_surface_rows.add(id(item))
- return retained
-
- def linked_tasks(
- task: dict[str, Any],
- published_id: str,
- source_task: dict[str, Any] | None,
- candidates: list[tuple[str | None, Any]],
- ) -> list[Any]:
- expected = (
- _project_worker_coverage_row(source_task, source_task["workerId"], "deferred")
- if source_task is not None
- else None
- )
- return [
- retained
- for owner, retained in candidates
- if retained == task
- or (
- expected is not None
- and owner == expected["workerId"]
- and isinstance(retained, dict)
- and retained.get("id") == expected.get("id")
- and isinstance(retained.get("surfaceIds"), list)
- and published_id in retained["surfaceIds"]
- )
- ]
-
- def linked_surface(surface, outputs, named_outputs):
- retained = outputs.get(id(surface))
- if (
- retained is None
- and isinstance(owner := surface.get("workerId"), str)
- and isinstance(identity := surface.get("id"), str)
- ):
- matches = named_outputs.get((owner, identity), {})
- if len(matches) == 1:
- retained = next(iter(matches.values()))
- return retained
-
- all_sources = ([("parent", parent, None)] if parent else []) + sources
- # Older checkpoints can omit IDs already assigned in their published output.
- for field in ("deferred", "surfaces"):
- named_rows: dict[str | None, list[dict[str, Any]]] = {}
- for _, draft, owner in all_sources:
- named_rows.setdefault(owner, []).extend(
- row
- for row in _coverage_rows(draft["coverage"], field)
- if isinstance(row, dict) and isinstance(row.get("id"), str)
- )
- for _, draft, owner in all_sources:
- rows = _coverage_rows(draft["coverage"], field)
- reserved = {
- row["id"]
- for row in rows
- if isinstance(row, dict) and isinstance(row.get("id"), str)
- }
- for row in rows:
- if not isinstance(row, dict) or "id" in row:
- continue
- if field == "deferred" and _has_candidate_metadata(row):
- continue
- content = {"receiptRefs": [], **row} if field == "surfaces" else row
- identity = next(
- (
- named["id"]
- for named in named_rows[owner]
- if named["id"] not in reserved
- and {
- **({"receiptRefs": []} if field == "surfaces" else {}),
- **{key: value for key, value in named.items() if key != "id"},
- }
- == content
- ),
- None,
- )
- if identity is not None:
- row["id"] = identity
- reserved.add(identity)
-
- # A discarded local surface must not fall back to another source's reused ID.
- surface_ids_by_source: dict[tuple[str, str], list[str]] = {
- (relative, row["id"]): []
- for relative, draft, _ in all_sources
- for row in (
- draft["coverage"].get("surfaces", [])
- if isinstance(draft["coverage"].get("surfaces"), list)
- else []
- )
- if isinstance(row, dict) and isinstance(row.get("id"), str)
- }
- discarded_coverage_sources: set[str] = set()
- if preserve_canonical_parent:
- for relative, draft, worker_id in sources:
- if worker_id is None:
- continue
- for field in ("surfaces", "explicitExclusions", "deferred"):
- rows = draft["coverage"].get(field)
- for row in rows if isinstance(rows, list) else []:
- if isinstance(row, dict):
- row.setdefault("id", _saved_coverage_id(row))
- if field == "surfaces":
- row.setdefault("receiptRefs", [])
- source_warnings = []
- discarded_fields = _recover_unsealed_coverage(
- draft["coverage"],
- Path(__file__).resolve().parent.parent / "schemas",
- scan_dir,
- source_warnings,
- discarded_by_source.get(relative, []),
- # Reconcile local IDs and valid outcomes against worker history below.
- worker_draft=True,
- )
- if discarded_fields & {
- "surfaces",
- "explicitExclusions",
- "deferred",
- "resolvedDeferred",
- }:
- discarded_coverage_sources.add(relative)
- for row in draft["coverage"]["deferred"]:
- row["workerId"] = worker_id
- warnings.extend(f"{relative}: {warning}" for warning in source_warnings)
-
- if parent is None and not sources:
- return None
- if (
- parent_manifest
- and parent_manifest["scan"].get("sealedAt")
- and parent_manifest["scan"].get("status") == binding["status"]
- and parent_manifest["scan"].get("preservedSources") == source_digests
- and all(warning in initial_warnings for warning in warnings)
- ):
- return None
-
- if (
- frozen_source_digests is None
- or any(_is_source_order_snapshot(path) for path in source_digests)
- or allow_frozen_legacy_parent
- ):
- _freeze_source_times(
- scan_dir, scan_id, source_digests, source_times, created_paths=created_paths
- )
-
- target_kind = binding["allowedTargetKinds"][0]
- if (
- target_kind == "git_worktree"
- and "snapshotDigest" not in binding["target"]
- and "git_revision" in binding["allowedTargetKinds"]
- ):
- target_kind = "git_revision"
- target = {"kind": target_kind, **binding["target"]}
- if target["kind"] == "git_diff" and "snapshotDigest" not in target:
- diff_kind = {"commit": "commit", "branch_diff": "range"}[binding["coverageMode"]]
- target["snapshotDigest"] = committed_diff_snapshot_digest(
- diff_kind, target["baseRevision"], target["headRevision"]
- )
- manifest = (
- copy.deepcopy(parent_manifest)
- if parent_manifest
- else {"scan": {"target": target, "scope": binding["scope"]}}
- )
- for key in ("sealedAt", "artifacts"):
- manifest["scan"].pop(key, None)
- manifest["scan"]["preservedSources"] = source_digests
- # Completion follows the selected parent, including legacy terminal drafts
- # that omit the optional marker, rather than an older canonical manifest.
- if parent is not None:
- manifest["scan"].pop("complete", None)
- if "complete" in parent:
- manifest["scan"]["complete"] = parent["complete"]
- for key in ("scope", "threatModel"):
- if isinstance(parent.get(key), dict):
- manifest["scan"][key] = copy.deepcopy(parent[key])
- if isinstance(manifest["scan"].get("scope"), dict):
- manifest["scan"]["scope"].update(copy.deepcopy(binding["scope"]))
- model_checks: dict[str, dict[str, Any] | None] = {}
-
- def recovered_model(
- relative: str, draft: dict[str, Any], owner: str | None
- ) -> dict[str, Any] | None:
- if relative not in model_checks:
- model = copy.deepcopy(draft.get("threatModel"))
- if isinstance(model, dict) and owner is not None:
- model["origin"] = "recovered"
- schema = _read_json(
- Path(__file__).resolve().parent.parent / "schemas/scan-manifest.schema.json"
- )
- try:
- _require_safe_json_value(model, f"Saved threat model {relative}")
- _validate_schema_node(
- model,
- schema["properties"]["scan"]["properties"]["threatModel"],
- f"Saved threat model {relative}",
- schema,
- )
- except ContractError as exc:
- warnings.append(f"Skipped malformed saved threat model {relative}: {exc}")
- model = None
- model_checks[relative] = model
- return model_checks[relative]
-
- if "threatModel" in manifest["scan"]:
- model = recovered_model("parent", manifest["scan"], None)
- if model is None:
- manifest["scan"].pop("threatModel")
- else:
- manifest["scan"]["threatModel"] = model
-
- if frozen_model_source is not None:
- # Publication retries retain a valid choice from the frozen source set.
- model = drafts_by_path.get(frozen_model_source, {}).get("threatModel")
- if not isinstance(model, dict):
- raise ContractError("Frozen stopped-scan model source is unavailable.")
- model = recovered_model(
- frozen_model_source, drafts_by_path[frozen_model_source], paths[frozen_model_source]
- )
- if model is not None:
- manifest["scan"]["threatModel"] = model
- if selected_model_source is not None:
- selected_model_source[:] = [] if model is None else [frozen_model_source]
- coverage = (
- copy.deepcopy(parent["coverage"])
- if parent and parent["coverage"]
- else {
- "mode": binding["coverageMode"],
- "inventoryStrategy": "diff"
- if binding["coverageMode"] in {"commit", "branch_diff", "working_tree"}
- else "scoped_path"
- if binding["coverageMode"] == "scoped_path"
- else "repository",
- **binding["scope"],
- "surfaces": [],
- "explicitExclusions": [],
- "deferred": [],
- }
- )
- if isinstance(coverage.get("openQuestions"), list):
- coverage["openQuestions"] = [
- {"question": item.strip()} if isinstance(item, str) else item
- for item in coverage["openQuestions"]
- ]
- # Closure reconciliation can reuse original parent rows instead of their copies.
- canonical_rows = (
- {
- id(item)
- for parent_coverage in (
- (coverage, parent["coverage"]) if preserve_canonical_parent else (coverage,)
- )
- for field in ("surfaces", "explicitExclusions", "deferred")
- for item in _coverage_rows(parent_coverage, field)
- }
- if parent_is_canonical
- else set()
- )
- # Links use source-local IDs until all retained surfaces receive their final IDs.
- coverage_sources: dict[int, tuple[dict[str, Any], list[str]]] = {}
- source_owners = {relative: owner for relative, _, owner in all_sources}
- retained_surface_rows: set[int] = set()
- for relative, draft, _ in all_sources:
- for field in ("surfaces", "deferred"):
- rows = draft["coverage"].get(field)
- for row in rows if isinstance(rows, list) else []:
- if isinstance(row, dict):
- paths_for_row = coverage_sources.setdefault(id(row), (row, []))[1]
- if relative not in paths_for_row:
- paths_for_row.append(relative)
- if parent:
- for field in ("surfaces", "deferred"):
- rows, originals = coverage.get(field), parent["coverage"].get(field)
- if isinstance(rows, list) and isinstance(originals, list):
- for row, original in zip(rows, originals):
- _inherit_coverage_sources(row, [original], coverage_sources)
- if field == "surfaces":
- retained_surface_rows.update(id(original) for original in originals)
-
- findings: list[dict[str, Any]] = []
- finding_positions: dict[str, int] = {}
- canonical_finding_keys: set[str] = set()
- represented: dict[str, str | None] = {}
- represented_candidates: dict[tuple[str, str, Any, Any, Any], str | None] = {}
- represented_history: dict[str, set[str]] = {}
- represented_candidate_history: dict[tuple[str, str, Any, Any, Any], set[str]] = {}
- rejected_history: dict[tuple[str, str], list[dict[str, Any]]] = {}
- stopped_parent_seal = bool(
- stopped and parent_manifest and parent_manifest["scan"].get("sealedAt")
- )
-
- def valid_finding(value: Any) -> bool:
- # Use the finalizer's own per-record recovery before a draft can suppress
- # an earlier checkpoint. Invalid latest records must not hide valid history.
- document = {"scanId": scan_id, "findings": [copy.deepcopy(value)]}
- if isinstance(document["findings"][0], dict):
- _ensure_finding_identity(document["findings"][0], candidate_only=True)
- _recover_unsealed_findings(
- {"scan": {"id": scan_id, "target": binding["target"]}},
- document,
- Path(__file__).resolve().parent.parent / "schemas",
- scan_dir,
- [],
- current_contract=current_contract,
- )
- return bool(document["findings"])
-
- source_order["parent"] = (0, parent_modified)
- deferred_rows = {
- relative: _coverage_rows(draft["coverage"], "deferred")
- for relative, draft, _ in all_sources
- }
- # Accepted heads can replace equal tasks before they reach output coalescing.
- equivalent_tasks: dict[str | None, list[dict[str, Any]]] = {}
- for relative, _, owner in all_sources:
- known = equivalent_tasks.setdefault(owner, [])
- for row in deferred_rows[relative]:
- if not isinstance(row, dict):
- continue
- for previous in known:
- if previous == row:
- _inherit_coverage_sources(previous, [row], coverage_sources)
- coverage_sources[id(row)] = (row, coverage_sources[id(previous)][1])
- break
- else:
- known.append(row)
- # A legacy source can contain independent tasks with the same explicit ID.
- # Later rewrites cannot make an ID-only closure identify one of those tasks.
- ambiguous_deferred: set[tuple[str | None, str]] = set()
- for relative, _, owner in all_sources:
- by_id: dict[str, dict[str, Any]] = {}
- candidate_aliases = {
- identity
- for row in deferred_rows[relative]
- if isinstance(row, dict) and _has_candidate_metadata(row)
- for identity in (row.get("id"), row.get("candidateId"))
- if isinstance(identity, str)
- }
- for row in deferred_rows[relative]:
- if not isinstance(row, dict) or not isinstance(identity := row.get("id"), str):
- continue
- if _has_candidate_metadata(row):
- continue
- if identity in candidate_aliases or (identity in by_id and row != by_id[identity]):
- ambiguous_deferred.add((owner, identity))
- by_id[identity] = row
- current_drafts = ([("parent", parent, None)] if parent else []) + [
- source for source in sources if source[0] in current_results | selected_observations.keys()
- ]
- # Generic closures belong to one logical scan or worker, just like candidates.
- # Keep them when recovering a terminal checkpoint without its canonical write.
- closed_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]] = {}
-
- candidate_ids: set[tuple[str | None, str]] = set()
- accepted_deferred_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
- active_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]] = {}
- coverage_schema = _read_json(
- Path(__file__).resolve().parent.parent / "schemas" / "coverage.schema.json"
- )["properties"]
- for relative, draft, owner in all_sources:
- order = source_order[relative]
- for item in deferred_rows[relative]:
- if not isinstance(item, dict):
- continue
- if isinstance(item.get("candidateId"), str) or "candidate" in item or "finding" in item:
- candidate_ids.update(
- (owner, identity)
- for identity in (item.get("id"), item.get("candidateId"))
- if isinstance(identity, str)
- )
- identity = item.get("id") or item.get("candidateId")
- if isinstance(identity, str):
- key = (owner, identity)
- previous = active_deferred.get(key)
- if previous is None or order > previous[0]:
- active_deferred[key] = (order, item, relative)
- if (
- relative == "parent"
- or relative in current_results
- or relative in selected_observations
- ):
- try:
- # A malformed update cannot discard valid saved evidence.
- _validate_schema_node(
- item, coverage_schema["deferred"]["items"], "coverage.deferred"
- )
- except ContractError:
- continue
- accepted_deferred_orders[key] = max(
- accepted_deferred_orders.get(key, order), order
- )
- for closure in _resolved_deferred_rows(draft, coverage_schema["resolvedDeferred"]):
- key = (owner, closure["id"])
- previous = closed_deferred.get(key)
- if previous is None or order > previous[0]:
- # The parent comes first, preserving its reason on equal timestamps.
- closed_deferred[key] = (order, closure, relative)
- reopened_rows: list[tuple[str | None, dict[str, Any]]] = []
- reopened_generic: set[tuple[str | None, str]] = set()
- for key, (order, _, _) in list(closed_deferred.items()):
- # Equal timestamps cannot distinguish closure from reopened work.
- reopened = [
- active
- for (owner, identity), active in active_deferred.items()
- if owner == key[0]
- and (identity == key[1] or active[1].get("candidateId") == key[1])
- and active[0] >= order
- ]
- if key in candidate_ids or key in ambiguous_deferred or reopened:
- del closed_deferred[key]
- for _, item, _ in reopened:
- reopened_rows.append((key[0], item))
- if key not in candidate_ids:
- reopened_generic.add(key)
- # Retain every distinct ambiguous task even when a terminal result supersedes
- # its source. Existing output ID normalization keeps each row distinct.
- for relative, _, owner in all_sources:
- for row in deferred_rows[relative]:
- if (
- isinstance(row, dict)
- and isinstance(identity := row.get("id"), str)
- and (owner, identity) in ambiguous_deferred
- and not _has_candidate_metadata(row)
- and (owner, row) not in reopened_rows
- ):
- reopened_rows.append((owner, row))
- parent_closures = [
- closure for (owner, _), (_, closure, _) in closed_deferred.items() if owner is None
- ]
- coverage.pop("resolvedDeferred", None)
- if parent_closures:
- coverage["resolvedDeferred"] = copy.deepcopy(parent_closures)
- if parent:
- coverage["deferred"] = [
- row
- for row in deferred_rows["parent"]
- if not isinstance(row, dict)
- or not isinstance(row.get("id"), str)
- or (None, row["id"]) not in closed_deferred
- ]
- resolved: dict[tuple[str | None, str], str] = {}
-
- ordered_candidates = {
- (owner, identity)
- for owner, row in reopened_rows
- if (identity := _deferred_candidate_id(row, owner, ambiguous_deferred)) is not None
- and (owner, identity) in candidate_ids
- }
- ordered_outcomes: dict[tuple[str | None, str], tuple[tuple[int, int], str]] = {}
-
- outcomes: list[tuple[str, str | None, str, str]] = []
- for relative, draft, owner in current_drafts:
- for finding in draft["findings"]:
- if (
- isinstance(finding, dict)
- and valid_finding(finding)
- and (candidate_id := finding_candidate_id(finding))
- ):
- outcomes.append((relative, owner, candidate_id, "reported"))
- for field in ("surfaces", "explicitExclusions"):
- for item in _coverage_rows(draft["coverage"], field):
- if (
- isinstance(item, dict)
- and isinstance(item.get("candidateId"), str)
- and item.get("disposition") in {"rejected", "not_applicable"}
- ):
- outcomes.append((relative, owner, item["candidateId"], item["disposition"]))
- ordered_candidates.update(
- (owner, candidate_id)
- for relative, owner, candidate_id, _ in outcomes
- if owner is not None and relative in selected_observations
- )
- # Reopened work and selected checkpoint outcomes follow the saved source order.
- for relative, owner, candidate_id, disposition in outcomes:
- key = (owner, candidate_id)
- if key not in ordered_candidates:
- if relative == "parent" or relative in current_results:
- resolved.setdefault(key, disposition)
- continue
- order = source_order[relative]
- if any(
- saved_owner == owner
- and _deferred_candidate_id(row, owner, ambiguous_deferred) == candidate_id
- and modified >= order
- for (saved_owner, _), (modified, row, _) in active_deferred.items()
- ):
- continue
- if key not in ordered_outcomes or order > ordered_outcomes[key][0]:
- resolved[key] = disposition
- ordered_outcomes[key] = (order, relative)
- # Only the current parent may claim that another worker finding was absorbed.
- # A superseded checkpoint must not suppress a newer independent result.
- if parent:
- for finding in parent["findings"]:
- if valid_finding(finding):
- canonical_key = _finding_key(finding)
- for retained in _retained_findings(finding):
- retained_key = _finding_key(retained)
- if retained is not finding:
- represented_history.setdefault(retained_key, set()).add(
- _digest(_finding_content(retained))
- )
- previous_key = represented.get(retained_key)
- if retained_key not in represented:
- represented[retained_key] = canonical_key
- elif previous_key != canonical_key:
- # Ambiguous history cannot suppress an independent source.
- represented[retained_key] = None
- originals = finding["provenance"].get("sourceFindings", [])
- for original in originals if isinstance(originals, list) else []:
- if isinstance(original, dict) and isinstance(original.get("finding"), dict):
- source_id = original.get("id")
- candidate_id = finding_candidate_id(original["finding"])
- if isinstance(source_id, str) and ":" in source_id and candidate_id:
- candidate_key = _worker_candidate_key(
- source_id.rsplit(":", 1)[0],
- candidate_id,
- original["finding"],
- )
- previous_key = represented_candidates.get(candidate_key)
- if candidate_key not in represented_candidates:
- represented_candidates[candidate_key] = canonical_key
- elif previous_key != canonical_key:
- # Candidate ids are only authoritative within one
- # logical worker. Multiple canonical owners make
- # that worker-local identity ambiguous.
- represented_candidates[candidate_key] = None
- represented_candidate_history.setdefault(candidate_key, set()).add(
- _digest(_finding_content(original["finding"]))
- )
- selected_terminal_orders: dict[str, tuple[int, int]] = {}
- for relative, draft, worker_id in sources:
- if (
- worker_id is not None
- and relative in selected_observations
- and draft.get("complete") is not False
- and relative not in discarded_by_source
- and relative not in discarded_coverage_sources
- ):
- order = source_order[relative]
- selected_terminal_orders[worker_id] = max(
- selected_terminal_orders.get(worker_id, order), order
- )
- terminal_worker_orders: dict[str | None, tuple[int, int]] = {}
- terminal_coverage_orders: dict[str | None, tuple[int, int]] = {}
- for relative, draft, worker_id in sources:
- if (
- relative in current_results
- and draft.get("complete") is not False
- and relative not in discarded_by_source
- ):
- order = source_order[relative]
- terminal_worker_orders[worker_id] = max(
- terminal_worker_orders.get(worker_id, order), order
- )
- if relative not in discarded_coverage_sources:
- terminal_coverage_orders[worker_id] = max(
- terminal_coverage_orders.get(worker_id, order), order
- )
-
- def source_coverage_selection(
- relative: str,
- worker_id: str | None,
- ) -> tuple[bool, set[str], bool, bool, bool]:
- worker_result_order = terminal_worker_orders.get(worker_id)
- selected_coverage_superseded = worker_id in selected_terminal_orders and (
- source_order[relative] < selected_terminal_orders[worker_id]
- or (
- relative in current_results
- and source_order[relative] <= selected_terminal_orders[worker_id]
- )
- )
- selected_candidates = {
- candidate_id
- for (owner, candidate_id), (_, source) in ordered_outcomes.items()
- if owner == worker_id and source == relative
- }
- superseded = (
- worker_id is None
- and parent is not None
- and parent.get("complete") is not False
- and relative != "parent"
- and source_order[relative] <= (0, parent_modified)
- and (not stopped_parent_seal or relative in parent_preserved_sources)
- ) or (
- relative not in current_results
- and worker_result_order is not None
- and (
- relative not in selected_observations
- or source_order[relative] < worker_result_order
- )
- )
- worker_coverage_order = terminal_coverage_orders.get(worker_id)
- coverage_superseded = (
- superseded
- if worker_id is None
- else (
- relative not in current_results
- and worker_coverage_order is not None
- and (
- relative not in selected_observations
- or source_order[relative] < worker_coverage_order
- )
- )
- )
- # A failed result write can leave pending work outside the accepted result.
- accepted_order = (
- (0, parent_modified)
- if worker_id is None and parent is not None
- else worker_coverage_order
- )
- retain_pending = (
- coverage_superseded
- and (worker_id in headed_workers or (worker_id is None and parent_heads))
- and accepted_order is not None
- and source_order[relative] >= accepted_order
- and any(isinstance(row, dict) for row in deferred_rows[relative])
- )
- return (
- selected_coverage_superseded,
- selected_candidates,
- superseded,
- retain_pending,
- coverage_superseded,
- )
-
- def coverage_row_is_retained(
- field: str,
- item: Any,
- worker_id: str | None,
- selection: tuple[bool, set[str], bool, bool, bool],
- ) -> bool:
- (
- selected_coverage_superseded,
- selected_candidates,
- superseded,
- retain_pending,
- coverage_superseded,
- ) = selection
- # A selected terminal checkpoint replaces ordinary coverage, while
- # candidate evidence and pending tasks retain their own reconciliation.
- if (
- selected_coverage_superseded
- and field != "deferred"
- and not (isinstance(item, dict) and _has_candidate_metadata(item))
- ):
- return False
- # A selected outcome must retain its evidence even if its result write failed.
- if coverage_superseded and not (
- isinstance(item, dict)
- and (
- (field == "deferred" and retain_pending)
- or (
- isinstance(item.get("candidateId"), str)
- and item["candidateId"] in selected_candidates
- and item.get("disposition") == resolved.get((worker_id, item["candidateId"]))
- )
- )
- ):
- return False
- if (
- isinstance(item, dict)
- and isinstance(
- identity := _deferred_candidate_id(item, worker_id, ambiguous_deferred)
- if field == "deferred"
- else item.get("candidateId"),
- str,
- )
- and (worker_id, identity) in resolved
- and (field == "deferred" or item.get("disposition") == "needs_follow_up")
- ):
- return False
- return True
-
- ambiguous_surface_ids = {
- (owner, identity)
- for owner, row in reopened_rows
- if isinstance(row.get("id"), str)
- and (owner, row["id"]) in ambiguous_deferred
- and not _has_candidate_metadata(row)
- for identity in [
- row["id"],
- *(row.get("surfaceIds", []) if isinstance(row.get("surfaceIds", []), list) else []),
- ]
- if isinstance(identity, str)
- }
- for _, draft, owner in all_sources:
- by_id: dict[str, dict[str, Any]] = {}
- for surface in _coverage_rows(draft["coverage"], "surfaces"):
- if not isinstance(surface, dict) or not isinstance(identity := surface.get("id"), str):
- continue
- if identity in by_id and surface != by_id[identity]:
- ambiguous_surface_ids.add((owner, identity))
- by_id[identity] = surface
-
- def ambiguous_pending_surface(row: dict[str, Any], owner: str | None) -> bool:
- return (
- isinstance(row.get("id"), str)
- and (owner, row["id"]) in ambiguous_surface_ids
- and row.get("disposition") == "needs_follow_up"
- and not _has_candidate_metadata(row)
- )
-
- replaced_deferred = {
- id(row)
- for relative, _, owner in all_sources
- for row in deferred_rows[relative]
- if isinstance(row, dict)
- and isinstance(identity := row.get("id"), str)
- and (key := (owner, identity)) not in candidate_ids
- and key not in ambiguous_deferred
- and (updated := accepted_deferred_orders.get(key)) is not None
- and updated > source_order[relative]
- }
- fallback_surfaces = []
- if surface_links and isinstance(coverage.get("surfaces"), list):
- # Plan the surviving associations before historical receipts can claim
- # a spelling needed by a surface that must be restored for its task.
- prospective_tasks = []
- prospective_surfaces = {}
- prospective_named = {}
- for relative, draft, owner in all_sources:
- selection = source_coverage_selection(relative, owner)
- for row in deferred_rows[relative]:
- if (
- coverage_row_is_retained("deferred", row, owner, selection)
- and id(row) not in replaced_deferred
- and not (
- isinstance(row, dict)
- and isinstance(row.get("id"), str)
- and (owner, row["id"]) in closed_deferred
- )
- ):
- prospective_tasks.append(
- (owner, _project_worker_coverage_row(row, owner, "deferred"))
- )
- for row in _coverage_rows(draft["coverage"], "surfaces"):
- if owner is None or not isinstance(row, dict):
- continue
- emitted = coverage_row_is_retained("surfaces", row, owner, selection)
- if not emitted and not ambiguous_pending_surface(row, owner):
- continue
- projected = _project_worker_coverage_row(row, owner, "surfaces")
- if isinstance(row.get("id"), str):
- named = prospective_named.setdefault((owner, row["id"]), {})
- projected = next(
- (existing for existing in named.values() if existing == projected),
- projected,
- )
- named[id(projected)] = projected
- if emitted:
- prospective_surfaces[id(row)] = projected
- prospective_tasks.extend(
- (owner, _project_worker_coverage_row(row, owner, "deferred"))
- for owner, row in reopened_rows
- if (owner, _deferred_candidate_id(row, owner, ambiguous_deferred)) not in resolved
- )
- bound = {
- (id(retained), published_id)
- for task, published_id, surface, _, task_source in surface_links
- if linked_surface(surface, prospective_surfaces, prospective_named) is not None
- for retained in linked_tasks(task, published_id, task_source, prospective_tasks)
- }
- for task, published_id, _, parent_surface, task_source in surface_links:
- for retained in linked_tasks(task, published_id, task_source, prospective_tasks):
- key = (id(retained), published_id)
- if key not in bound:
- fallback_surfaces.append(parent_surface)
- bound.add(key)
-
- replaced_surfaces, surface_updates = _generic_surface_updates(
- all_sources,
- source_order,
- closed_deferred,
- active_deferred,
- resolved,
- reopened_generic,
- coverage_schema["surfaces"]["items"],
- deferred_rows,
- ambiguous_deferred,
- canonical_rows,
- coverage_sources,
- receipt_root=scan_dir if project_worker_coverage else None,
- receipt_warnings=warnings,
- fallback_surfaces=fallback_surfaces,
- surface_is_retained=lambda relative, owner, row: coverage_row_is_retained(
- "surfaces", row, owner, source_coverage_selection(relative, owner)
- ),
- eligible_receipt_sources={
- relative
- for relative, draft, _ in all_sources
- if draft.get("complete") is not False or relative in selected_observations
- },
- )
- replaced_rows = {
- "surfaces": replaced_surfaces,
- "deferred": replaced_deferred,
- }
- for field, replaced in replaced_rows.items():
- if parent and isinstance(coverage.get(field), list):
- previous = parent["coverage"].get(field, [])
- if isinstance(previous, list):
- removed_parent = [row for row in previous if id(row) in replaced]
- coverage[field] = [row for row in coverage[field] if row not in removed_parent]
- if isinstance(coverage.get("surfaces"), list):
- for owner, surface, replaced_sources in surface_updates:
- retained = append_coverage_row(coverage["surfaces"], surface, owner, "surfaces")
- for source_id in replaced_sources & linked_surface_sources:
- linked_surface_outputs[source_id] = retained
- for surface in coverage["surfaces"]:
- if isinstance(surface, dict):
- surface.setdefault("receiptRefs", [])
-
- # Reopened work survives a superseded checkpoint, but current candidate
- # outcomes still apply. Parent closures cannot remove another worker's row.
- for owner, item in reopened_rows:
- if (identity := _deferred_candidate_id(item, owner, ambiguous_deferred)) is not None and (
- owner,
- identity,
- ) in resolved:
- continue
- pending = coverage.setdefault("deferred", [])
- if isinstance(pending, list):
- append_coverage_row(pending, item, owner, "deferred")
- for _, draft, owner in all_sources:
- for surface in _coverage_rows(draft["coverage"], "surfaces"):
- if (
- isinstance(surface, dict)
- and ambiguous_pending_surface(surface, owner)
- and isinstance(coverage.get("surfaces"), list)
- ):
- retained = append_coverage_row(
- coverage["surfaces"],
- {**surface, "receiptRefs": surface.get("receiptRefs", [])},
- owner,
- "surfaces",
- )
- _inherit_coverage_sources(retained, [surface], coverage_sources)
- retained_surface_rows.add(id(surface))
- for relative, draft, worker_id in all_sources:
- selection = source_coverage_selection(relative, worker_id)
- (
- selected_coverage_superseded,
- selected_candidates,
- superseded,
- retain_pending,
- coverage_superseded,
- ) = selection
- skip_superseded_findings = (
- superseded
- and not stopped
- and all(valid_finding(finding) for finding in (parent["findings"] if parent else []))
- )
- if (
- skip_superseded_findings
- and coverage_superseded
- and not selected_candidates
- and not retain_pending
- ):
- continue
- if (
- not skip_superseded_findings
- and "threatModel" not in manifest["scan"]
- and isinstance(draft.get("threatModel"), dict)
- ):
- model = recovered_model(relative, draft, worker_id)
- model_path = relative
- checkpoint_dir = Path(relative).parent
- prefer_worker_head = worker_id is not None and (
- checkpoint_dir.name == "checkpoints" or draft.get("complete") is False
- )
- if worker_id is not None:
- if checkpoint_dir.name != "checkpoints":
- checkpoint_dir /= "checkpoints"
- selected_models = [
- path
- for path in selected_observations
- if Path(path).parent == checkpoint_dir
- and isinstance(drafts_by_path[path].get("threatModel"), dict)
- and recovered_model(path, drafts_by_path[path], worker_id) is not None
- ]
- if selected_models:
- head_path = max(selected_models, key=source_order.__getitem__)
- current = drafts_by_path[head_path]
- # A terminal checkpoint is committed before result.json is replaced.
- # Use the admitted observation, including its frozen ordering on retries.
- if not prefer_worker_head and current.get("complete") is not False:
- prefer_worker_head = source_order[head_path] >= source_order[relative]
- if prefer_worker_head:
- model = recovered_model(head_path, current, worker_id)
- model_path = head_path
- if model is not None:
- manifest["scan"]["threatModel"] = model
- if selected_model_source is not None and worker_id is not None:
- selected_model_source[:] = [model_path]
- for value in draft["findings"]:
- if skip_superseded_findings and not (
- isinstance(value, dict)
- and (candidate_id := finding_candidate_id(value)) in selected_candidates
- and resolved.get((worker_id, candidate_id)) == "reported"
- ):
- continue
- if relative == "parent" and parent_is_canonical:
- finding = copy.deepcopy(value)
- _ensure_finding_identity(finding, candidate_only=True)
- provenance = finding.get("provenance") if isinstance(finding, dict) else None
- owner = provenance.get("workerId") if isinstance(provenance, dict) else None
- candidate_id = finding_candidate_id(finding) if isinstance(finding, dict) else None
- if (
- stopped_parent_seal
- and isinstance(owner, str)
- and candidate_id
- and resolved.get((owner, candidate_id)) in {"rejected", "not_applicable"}
- ):
- rejected_history.setdefault((owner, candidate_id), []).append(finding)
- continue
- if valid_finding(finding):
- finding_positions.setdefault(_finding_key(finding), len(findings))
- if preserve_canonical_parent:
- canonical_finding_keys.add(_finding_key(finding))
- findings.append(finding)
- continue
- if relative != "parent" and parent and value in parent["findings"]:
- continue
- if not isinstance(value, dict):
- warnings.append(f"Retained malformed finding evidence in {relative}.")
- continue
- finding = copy.deepcopy(value)
- candidate_id = finding_candidate_id(finding)
- if relative != "parent" and resolved.get((worker_id, candidate_id)) in {
- "rejected",
- "not_applicable",
- }:
- if preserve_canonical_parent:
- rejected_history.setdefault((worker_id, candidate_id), []).append(finding)
- for item in _coverage_rows(coverage, "surfaces"):
- if (
- isinstance(item, dict)
- and item.get("candidateId") == candidate_id
- and (not preserve_canonical_parent or item.get("workerId") == worker_id)
- ):
- _append_previous_finding(item, finding)
- continue
- for key in ("findingId", "occurrenceId", "fingerprints"):
- finding.pop(key, None)
- locations = finding.get("locations", [])
- if not isinstance(locations, list) or not any(
- isinstance(location, dict)
- and isinstance(location.get("path"), str)
- and any(
- path_within_scope(location["path"], path)
- for path in binding["scope"]["includePaths"]
- )
- for location in locations
- ):
- warnings.append(f"Skipped out-of-scope finding from {relative}.")
- continue
- provenance = finding.setdefault("provenance", {"source": "local_plugin"})
- if not isinstance(provenance, dict):
- findings.append(finding)
- continue
- if worker_id:
- provenance.setdefault("workerId", worker_id)
- _ensure_finding_identity(finding)
- if not valid_finding(finding):
- findings.append(finding)
- continue
- key = _finding_key(finding)
- represented_by_parent = False
- if relative != "parent":
- if key in represented:
- mapped_key = represented[key]
- historical_contents = represented_history.get(key, set())
- elif worker_id and candidate_id:
- candidate_key = _worker_candidate_key(worker_id, candidate_id, finding)
- if candidate_key not in represented_candidates:
- represented_candidates[candidate_key] = key
- mapped_key = represented_candidates[candidate_key]
- historical_contents = represented_candidate_history.get(candidate_key, set())
- else:
- mapped_key = None
- historical_contents = set()
- if mapped_key is not None:
- key = mapped_key
- represented_by_parent = _digest(_finding_content(value)) in historical_contents
- if key in finding_positions:
- retained = findings[finding_positions[key]]
- if finding != retained:
- if (
- key not in canonical_finding_keys
- and not represented_by_parent
- and _finding_strength(finding) > _finding_strength(retained)
- ):
- previous = copy.deepcopy(retained)
- previous_history = previous["provenance"].pop("previousFindings", [])
- retained = finding
- findings[finding_positions[key]] = retained
- else:
- previous = copy.deepcopy(value)
- previous_history = previous.get("provenance", {}).pop(
- "previousFindings", []
- )
- retained_provenance = retained["provenance"]
- retained_history = retained_provenance.get("previousFindings")
- history = (
- [item for item in retained_history if isinstance(item, dict)]
- if isinstance(retained_history, list)
- else []
- )
- retained_provenance["previousFindings"] = history
- for original in [
- *(previous_history if isinstance(previous_history, list) else []),
- previous,
- ]:
- if not isinstance(original, dict):
- continue
- source_key = _finding_key(original)
- source_content = _finding_content(original)
- already_retained = any(
- source_key == _finding_key(historical)
- and source_content == _finding_content(historical)
- for historical in _retained_findings(retained)
- )
- if (
- not already_retained
- and original not in history
- and original != retained
- ):
- history.append(original)
- continue
- finding_positions[key] = len(findings)
- findings.append(finding)
- if coverage_superseded and not selected_candidates and not retain_pending:
- continue
- for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions"):
- if coverage_superseded and field not in {"surfaces", "explicitExclusions", "deferred"}:
- continue
- items = draft["coverage"].get(field, [])
- if field == "deferred":
- items = deferred_rows[relative]
- if not isinstance(items, list):
- continue
- output = coverage.setdefault(field, [])
- if not isinstance(output, list):
- # Keep malformed canonical collections for the existing finalizer's
- # recovery and warnings rather than silently changing its contract.
- continue
- for item in items:
- source_item = original_item = item
- if not coverage_row_is_retained(field, item, worker_id, selection):
- continue
- if id(item) in replaced_rows.get(field, ()):
- continue
- if (
- field == "deferred"
- and isinstance(item, dict)
- and isinstance(item.get("id"), str)
- and (worker_id, item["id"]) in closed_deferred
- ):
- continue
- if field == "openQuestions" and isinstance(item, str):
- item = {"question": item.strip()}
- if (
- field == "surfaces"
- and isinstance(item, dict)
- and item.get("disposition") in {"rejected", "not_applicable"}
- and isinstance(item.get("candidateId"), str)
- and (history_findings := rejected_history.get((worker_id, item["candidateId"])))
- ):
- item = copy.deepcopy(item)
- for finding in history_findings:
- _append_previous_finding(item, finding, clone=True)
- if field == "surfaces" and isinstance(item, dict):
- item = {**item, "receiptRefs": item.get("receiptRefs", [])}
- if isinstance(item, dict) and "id" not in item:
- semantic_item = dict(item)
- existing = next(
- (
- row
- for row in output
- if isinstance(row, dict)
- and {key: value for key, value in row.items() if key != "id"}
- == semantic_item
- ),
- None,
- )
- if existing is not None:
- if project_worker_coverage and worker_id is not None:
- worker_row_owners[id(existing)] = worker_id
- if field == "surfaces" and id(source_item) in linked_surface_sources:
- linked_surface_outputs[id(source_item)] = existing
- _inherit_coverage_sources(existing, [original_item], coverage_sources)
- if field == "surfaces":
- retained_surface_rows.add(id(original_item))
- continue
- retained = append_coverage_row(output, item, worker_id, field)
- _inherit_coverage_sources(retained, [original_item], coverage_sources)
- if field == "surfaces":
- retained_surface_rows.add(id(original_item))
- if field == "surfaces" and id(source_item) in linked_surface_sources:
- linked_surface_outputs[id(source_item)] = retained
-
- identities: dict[str, str] = {}
- for finding in findings:
- if not valid_finding(finding):
- continue
- identity = finding.get("identity")
- if not isinstance(identity, dict):
- continue
- key = _encoded([finding.get("ruleId"), identity]).decode()
- variant = _finding_key(finding)
- if key in identities and identities[key] != variant:
- finding.setdefault("provenance", {})["preservedIdentity"] = copy.deepcopy(identity)
- identity["instance"] = f"{identity.get('instance', 'saved')}-{variant[:16]}"
- identities[key] = variant
- recovered_worker_ids = {worker_id for _, _, worker_id in sources if worker_id is not None}
- surface_positions: dict[str, int] = {}
- resolved_surface_targets: dict[tuple[str | None, str], list[str]] = {}
-
- def remember_surface_id(item: dict[str, Any], local_id: str) -> None:
- final_id = item["id"]
- surface_positions.setdefault(final_id, len(surface_positions))
- shadowed_alias = (
- project_worker_coverage
- and id(item) not in named_surface_outputs
- and (named := worker_surfaces.get((worker_row_owners.get(id(item)), local_id)))
- is not None
- and id(named) in named_surface_outputs
- )
- for relative in coverage_sources.get(id(item), (item, []))[1]:
- # A candidate-derived ID cannot claim a link explicitly naming another surface.
- if not shadowed_alias:
- targets = surface_ids_by_source.setdefault((relative, local_id), [])
- if final_id not in targets:
- targets.append(final_id)
- candidate_id = item.get("candidateId")
- if isinstance(candidate_id, str):
- key = (source_owners[relative], candidate_id)
- if key in resolved and resolved[key] == item.get("disposition"):
- targets = resolved_surface_targets.setdefault(key, [])
- if final_id not in targets:
- targets.append(final_id)
-
- # Bind links to retained output objects before their IDs become unique.
- # Candidate metadata can give an anonymous row the same preliminary ID as
- # another surface, so only the final surface ID can be used for its links.
- retained_surface_links: dict[int, tuple[dict[str, Any], dict[str, dict[str, Any]]]] = {}
- output_tasks = _coverage_rows(coverage, "deferred")
- task_candidates = [(worker_row_owners.get(id(row)), row) for row in output_tasks]
- for task, published_id, surface, _, task_source in surface_links:
- retained_surface = linked_surface(surface, linked_surface_outputs, worker_surface_outputs)
- if retained_surface is None or not isinstance(retained_surface.get("id"), str):
- continue
- for retained_task in linked_tasks(task, published_id, task_source, task_candidates):
- _, links = retained_surface_links.setdefault(id(retained_task), (retained_task, {}))
- links.setdefault(published_id, retained_surface)
- # A newer worker checkpoint may omit a surface still needed by a retained
- # task. Restore its parent copy only when no worker replacement survived.
- for task, published_id, surface, parent_surface, task_source in surface_links:
- for retained_task in linked_tasks(task, published_id, task_source, task_candidates):
- _, links = retained_surface_links.setdefault(id(retained_task), (retained_task, {}))
- if published_id not in links and isinstance(coverage.get("surfaces"), list):
- retained_surface = append_coverage_row(
- coverage["surfaces"], parent_surface, None, "surfaces"
- )
- record_coverage_owner(
- retained_surface, surface, surface.get("workerId"), "surfaces"
- )
- links[published_id] = retained_surface
- if project_worker_coverage:
- worker_surfaces: dict[tuple[str, str], dict[str, Any]] = {}
- named_surface_outputs = {
- identity for outputs in worker_surface_outputs.values() for identity in outputs
- }
- for surface in _coverage_rows(coverage, "surfaces"):
- if not isinstance(surface, dict):
- continue
- owner, identity = worker_row_owners.get(id(surface)), surface.get("id")
- if isinstance(owner, str) and isinstance(identity, str):
- key = (owner, identity)
- existing = worker_surfaces.get(key)
- # An anonymous candidate ID can collide with an explicit surface ID.
- # Bind a named worker link to the explicitly named source.
- if existing is None or (
- id(surface) in named_surface_outputs
- and id(existing) not in named_surface_outputs
- ):
- worker_surfaces[key] = surface
- for task in output_tasks:
- if (
- not isinstance(task, dict)
- or (owner := worker_row_owners.get(id(task))) is None
- or not isinstance(task.get("surfaceIds"), list)
- ):
- continue
- for identity in task["surfaceIds"]:
- if (
- isinstance(identity, str)
- and (surface := worker_surfaces.get((owner, identity))) is not None
- ):
- _, links = retained_surface_links.setdefault(id(task), (task, {}))
- links.setdefault(identity, surface)
- for field in ("surfaces", "explicitExclusions", "deferred"):
- used: set[str] = set()
- items = coverage.setdefault(field, [])
- if not isinstance(items, list):
- continue
- reserved = {
- row["id"] for row in items if isinstance(row, dict) and isinstance(row.get("id"), str)
- }
- normalized_items = []
- for item in items:
- normalized_items.append(item)
- if not isinstance(item, dict):
- continue
- if id(item) in canonical_rows:
- if isinstance(item.get("id"), str):
- used.add(item["id"])
- if field == "surfaces":
- remember_surface_id(item, item["id"])
- continue
- item.setdefault("id", _saved_coverage_id(item))
- if not isinstance(item["id"], str):
- # Preserve malformed rows for per-record recovery, including frozen replay.
- continue
- local_id = item["id"]
- scoped = (
- preserve_canonical_parent
- and isinstance(worker_id := item.get("workerId"), str)
- and worker_id in recovered_worker_ids
- )
- if scoped:
- # Resolve worker-local candidate/deferred history before scoping IDs.
- item["id"] = f"{worker_id}/{item['id']}"
- if isinstance(item.get("surfaceIds"), list):
- links: list[Any] = []
- for surface_id in item["surfaceIds"]:
- targets: list[str] = []
- declared = False
- if field == "deferred" and isinstance(surface_id, str):
- for relative in coverage_sources.get(id(item), (item, []))[1]:
- source_key = (relative, surface_id)
- history_keys = [source_key]
- if source_key not in surface_ids_by_source:
- # A deferred-only checkpoint can refer to an earlier
- # observation from this logical worker, including retries.
- # Reused IDs can denote several retained observations.
- history_keys = [
- (historical, surface_id)
- for historical, _, owner in all_sources
- if owner == source_owners[relative]
- and source_order[historical] <= source_order[relative]
- ]
- for key in history_keys:
- declared |= key in surface_ids_by_source
- for target in surface_ids_by_source.get(key, []):
- if target not in targets:
- targets.append(target)
- if targets:
- targets.sort(key=surface_positions.__getitem__)
- for target in targets:
- if target not in links:
- links.append(target)
- elif not declared:
- links.append(
- f"{worker_id}/{surface_id}"
- if scoped and isinstance(surface_id, str)
- else surface_id
- )
- item["surfaceIds"] = links
- if scoped:
- if item in normalized_items[:-1]:
- # A previous finish may have published files before its DB commit.
- if field == "surfaces":
- remember_surface_id(item, local_id)
- normalized_items.pop()
- continue
- if item["id"] in used:
- if project_worker_coverage:
- base = item["id"]
- suffix = 2
- while item["id"] in used or item["id"] in reserved:
- item["id"] = f"{base}-{suffix}"
- suffix += 1
- else:
- item["id"] = f"{item['id']}-{_digest(item)[:16]}"
- if preserve_canonical_parent and item in normalized_items[:-1]:
- if field == "surfaces":
- remember_surface_id(item, local_id)
- normalized_items.pop()
- continue
- used.add(item["id"])
- if field == "surfaces":
- item.setdefault("receiptRefs", [])
- remember_surface_id(item, local_id)
- if preserve_canonical_parent and isinstance(items, list):
- coverage[field] = normalized_items
- if field == "surfaces":
- # Candidate resolution replaces pending surfaces independently of generic
- # tasks. Preserve their original links, even when the outcome changes ID
- # or a distinct retained surface shares the old source-local ID.
- for relative, draft, owner in all_sources:
- originals = draft["coverage"].get("surfaces", [])
- for original in originals if isinstance(originals, list) else []:
- if (
- not isinstance(original, dict)
- or id(original) in retained_surface_rows
- or original.get("disposition") != "needs_follow_up"
- or not isinstance(local_id := original.get("id"), str)
- or not isinstance(candidate_id := original.get("candidateId"), str)
- ):
- continue
- targets = surface_ids_by_source.setdefault((relative, local_id), [])
- for target in resolved_surface_targets.get((owner, candidate_id), []):
- if target not in targets:
- targets.append(target)
- for task, links in retained_surface_links.values():
- task["surfaceIds"] = [
- links[identity]["id"] if isinstance(identity, str) and identity in links else identity
- for identity in task["surfaceIds"]
- ]
- coverage.pop("completeness", None)
- if stopped:
- if not isinstance(coverage.get("deferred"), list):
- coverage["deferred"] = []
- item = {"id": "scan-stopped", "reason": reason}
- if item not in coverage["deferred"]:
- coverage["deferred"].append(item)
- return manifest, {"findings": findings}, coverage
-
-
def coverage_for_comparison(db: Any, scan: Any) -> dict[str, Any]:
if scan["seal_manifest_digest"] is None:
raise SystemExit("Only sealed scans can be compared.")
@@ -2306,6 +452,9 @@ def preserve_deep_deadline_draft(
stopped=not preserve_reduction,
preserve_canonical_parent=preserve_reduction,
project_worker_coverage=True,
+ # Without reduction, the coordinator's empty draft cannot replace worker evidence.
+ scan_mode="deep" if preserve_reduction else None,
+ finding_scope=db.requested_finding_scope(scan),
created_paths=created_paths,
current_contract=True,
reason=(
@@ -2489,10 +638,7 @@ def preserve_scan_results_locked(
existing_scan = db.read_json_object(existing_path).get("scan", {}) if existing_path else {}
existing = None
if scan["seal_manifest_digest"] is not None or (
- isinstance(existing_scan, dict)
- and (
- existing_scan.get("sealedAt") is not None or existing_scan.get("artifacts") is not None
- )
+ isinstance(existing_scan, dict) and manifest_is_sealed(existing_scan)
):
db.require_recorded_manifest_digest(scan, scan_dir)
existing, existing_findings, _ = finalize_scan(
@@ -2535,6 +681,8 @@ def preserve_scan_results_locked(
).fetchall(),
warnings,
stopped=True,
+ scan_mode=scan["mode"],
+ finding_scope=db.requested_finding_scope(scan) if scan["mode"] == "deep" else None,
reason=(
f"Scan {outcome}; saved findings and pending review were preserved. "
f"{scan['failure_message'] or ''}"
@@ -2686,7 +834,7 @@ def save_scan_artifact(db: Any, connection: Any, args: Any) -> dict[str, Any]:
manifest_path = db.artifact_path(scan_dir, "scan-manifest.json", required=False)
if manifest_path is not None:
manifest = db.read_json_object(manifest_path).get("scan", {})
- if manifest.get("sealedAt") is not None or manifest.get("artifacts") is not None:
+ if manifest_is_sealed(manifest):
raise SystemExit("The scan is sealed; its artifacts cannot be modified.")
output = args.artifact_path
key = output.lower()
@@ -2702,66 +850,6 @@ def save_scan_artifact(db: Any, connection: Any, args: Any) -> dict[str, Any]:
return {"scanId": scan_id, "path": str(scan_dir / output)}
-def _require_current_deep_publication(
- db: Any, connection: Any, scan: Any, draft: dict[str, Any]
-) -> None:
- scan_id = scan["id"]
- run = connection.execute(
- "SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
- ).fetchone()
- publication = draft.get("deepScanPublication")
- if (
- publication is None
- and draft["manifest"]["scan"].get("complete") is False
- and (run is None or run["status"] == "running")
- ):
- return
- if run is None:
- run = db.deep_scan.require_deep_scan_run(connection, scan_id)
- # Finished discovery-only runs hand remaining publication back to the parent.
- if (
- publication is None
- and run["status"] != "running"
- and run["manifest_path"] != str(Path(scan["scan_dir"]) / "scan-manifest.json")
- ):
- return
- db.deep_scan.require_current_coordinator(
- run,
- argparse.Namespace(
- coordinator_generation=publication.get("coordinatorGeneration") if publication else None
- ),
- )
- # Once finish selects the canonical parent, only completion may replay it.
- if publication is None:
- if run["status"] != "running" and run["manifest_path"] == str(
- Path(scan["scan_dir"]) / "scan-manifest.json"
- ):
- raise SystemExit("Deep Scan is terminal; drafts cannot replace its publication.")
- return
-
- # Match the durable reducer sequence used by coordinator recovery.
- def reducer_order(worker: Any) -> tuple[int, str]:
- match = re.fullmatch(r"dedup-([0-9]+)", Path(worker["prompt_path"]).parent.name)
- return (int(match[1]) if match else 0, worker["id"])
-
- reducer = max(
- (
- worker
- for worker in connection.execute(
- "SELECT * FROM deep_scan_workers WHERE scan_id = ?", (scan_id,)
- )
- if worker["kind"] == "dedup"
- and worker["status"] == "succeeded"
- and worker["result_manifest_path"]
- ),
- key=reducer_order,
- default=None,
- )
- selected_result = reducer["result_manifest_path"] if reducer is not None else None
- if publication["resultPath"] != selected_result:
- raise SystemExit("Deep Scan aggregate belongs to a superseded publication selection.")
-
-
def write_scan_draft(db: Any, connection: Any, args: Any) -> dict[str, Any]:
scan_id = db.require_uuid(args.scan_id, "scan-id")
with db.scan_completion_lock(scan_id):
@@ -2791,6 +879,8 @@ def write_scan_draft(db: Any, connection: Any, args: Any) -> dict[str, Any]:
_populate_unsealed_manifest_envelope(manifest, manifest["scan"], binding)
_populate_unsealed_artifact_envelope(manifest, findings, coverage, binding)
_validate_completion_binding(manifest, findings, coverage, binding)
+ projected = _parent_scan_draft(scan_id, manifest["scan"], findings, coverage)
+ admitted_input = None
checkpoint = manifest["scan"]
checkpoint_contents = None
if args.checkpoint_path is not None:
@@ -2810,6 +900,10 @@ def write_scan_draft(db: Any, connection: Any, args: Any) -> dict[str, Any]:
accepted_checkpoint = checkpoint
if checkpoint.get("scanId") != scan_id:
raise SystemExit("Staged scan checkpoint belongs to another scan.")
+ if scan["mode"] == "deep":
+ checkpoint_contents = _admit_parent_checkpoint(
+ scan_dir, scan_id, checkpoint, projected
+ )
checkpoint_only = (
scan["mode"] == "deep"
and draft.get("deepScanPublication") is None
@@ -2855,6 +949,8 @@ def write_scan_draft(db: Any, connection: Any, args: Any) -> dict[str, Any]:
)
if checkpoint_contents is not None:
checkpoint_digest = hashlib.sha256(checkpoint_contents).hexdigest()
+ if scan["mode"] == "deep":
+ admitted_input = f"{checkpoint_digest}.json"
write_scan_local_bytes(
scan_dir,
f"checkpoints/{checkpoint_digest}.json",
@@ -2862,17 +958,17 @@ def write_scan_draft(db: Any, connection: Any, args: Any) -> dict[str, Any]:
)
if checkpoint_only:
return {"scanId": scan_id, "status": "draft_written"}
- checkpoint = _parent_scan_draft(scan_id, manifest["scan"], findings, coverage)
- checkpoint_contents = _encoded(checkpoint)
- checkpoint_name = f"{hashlib.sha256(checkpoint_contents).hexdigest()}.json"
+ projected_contents = _encoded(projected)
+ checkpoint_name = f"{hashlib.sha256(projected_contents).hexdigest()}.json"
checkpoint_relative = f"checkpoints/{checkpoint_name}"
if not (scan_dir / checkpoint_relative).exists():
- write_scan_local_bytes(scan_dir, checkpoint_relative, checkpoint_contents)
+ write_scan_local_bytes(scan_dir, checkpoint_relative, projected_contents)
if checkpoint_only:
return {"scanId": scan_id, "status": "draft_written"}
- write_scan_local_bytes(
- scan_dir, "checkpoint-head.json", _encoded({"checkpoint": checkpoint_name})
- )
+ head = {"checkpoint": checkpoint_name}
+ if admitted_input is not None:
+ head["inputCheckpoint"] = admitted_input
+ write_scan_local_bytes(scan_dir, "checkpoint-head.json", _encoded(head))
documents = {
filename: (json.dumps(document, allow_nan=False, indent=2) + "\n").encode()
for filename, document in (
diff --git a/plugins/codex-security/scripts/workbench_scan_history.py b/plugins/codex-security/scripts/workbench_scan_history.py
index 76a43f986..69aa02015 100644
--- a/plugins/codex-security/scripts/workbench_scan_history.py
+++ b/plugins/codex-security/scripts/workbench_scan_history.py
@@ -20,6 +20,7 @@ from finalize_scan_contract import (
_prepare_scan_finalization,
_read_scan_local_json_bytes,
_read_sealed_scan,
+ manifest_is_sealed,
)
from report_projection import SEVERITY_ORDER
from workbench_constants import ARTIFACTS, FINDINGS_PAGE_MAX
@@ -128,10 +129,7 @@ def cli_scan_resume(
if manifest_path is not None:
manifest = wb.read_json_object(manifest_path)
manifest_scan = manifest.get("scan")
- if isinstance(manifest_scan, dict) and (
- manifest_scan.get("sealedAt") is not None
- or manifest_scan.get("artifacts") is not None
- ):
+ if isinstance(manifest_scan, dict) and manifest_is_sealed(manifest_scan):
try:
binding = wb.workbench_completion_binding(scan, scan["started_at"], manifest)
_prepare_scan_finalization(
diff --git a/plugins/codex-security/tests/finalize_sarif_cases.py b/plugins/codex-security/tests/finalize_sarif_cases.py
new file mode 100644
index 000000000..c84bf5fb6
--- /dev/null
+++ b/plugins/codex-security/tests/finalize_sarif_cases.py
@@ -0,0 +1,472 @@
+from __future__ import annotations
+
+import io
+import os
+import tempfile
+import threading
+from pathlib import Path
+from unittest import mock, skipUnless
+
+import pytest
+from workbench_test_support import load_script, windows_file_backend
+
+FINALIZER = load_script("finalize_scan_contract")
+EXAMPLE_DIR = Path(__file__).resolve().parent.parent / "examples" / "completed-scan"
+CANONICAL_FILES = ("scan-manifest.json", "findings.json", "coverage.json")
+
+
+class FinalizerSarifCases:
+ def test_sarif_encodes_location_as_relative_uri(self) -> None:
+ self.finding["locations"][0]["path"] = "src/archive handlers/extract.py"
+ sarif_finding = self.sarif_finding("fingerprint")
+ result = FINALIZER._sarif_result(sarif_finding, 0)
+ location = result["locations"][0]["physicalLocation"]["artifactLocation"]
+ uri = location["uri"]
+ self.assertEqual(uri, "src/archive%20handlers/extract.py")
+ self.assertNotIn("uriBaseId", location)
+
+ def test_sarif_omits_unresolved_source_root_metadata(self) -> None:
+ sarif = FINALIZER.build_sarif(self.manifest, {"findings": []})
+
+ self.assertNotIn("originalUriBaseIds", sarif["runs"][0])
+
+ def test_sarif_keeps_root_first_and_preserves_sink_and_evidence_locations(self) -> None:
+ sarif_finding = self.sarif_finding("fingerprint")
+ sarif_finding["locations"] = [
+ {"path": "src/route.py", "startLine": 10, "role": "entrypoint/wrapper"},
+ {"path": "src/control.py", "startLine": 20, "role": "root_control"},
+ {"path": "src/write.py", "startLine": 30, "role": "sink"},
+ ]
+ sarif_finding["codeEvidence"] = [
+ {
+ "id": "template-sink",
+ "label": "Template sink",
+ "path": "src/template.html",
+ "startLine": 44,
+ "endLine": 45,
+ "code": "{{ user_input|safe }}",
+ "explanation": "The vulnerable template occurrence.",
+ },
+ {
+ "id": "duplicate-sink",
+ "label": "Duplicate sink",
+ "path": "src/write.py",
+ "startLine": 30,
+ "code": "write(user_input)",
+ "explanation": "Already present in locations.",
+ },
+ ]
+
+ result = FINALIZER._sarif_result(sarif_finding, 0)
+
+ self.assertEqual(
+ result["locations"],
+ [
+ {
+ "physicalLocation": {
+ "artifactLocation": {"uri": "src/control.py"},
+ "region": {"startLine": 20, "endLine": 20},
+ },
+ "message": {"text": "root_control"},
+ },
+ {
+ "physicalLocation": {
+ "artifactLocation": {"uri": "src/route.py"},
+ "region": {"startLine": 10, "endLine": 10},
+ },
+ "message": {"text": "entrypoint/wrapper"},
+ },
+ {
+ "physicalLocation": {
+ "artifactLocation": {"uri": "src/write.py"},
+ "region": {"startLine": 30, "endLine": 30},
+ },
+ "message": {"text": "sink"},
+ },
+ {
+ "physicalLocation": {
+ "artifactLocation": {"uri": "src/template.html"},
+ "region": {"startLine": 44, "endLine": 45},
+ },
+ "message": {"text": "evidence:template-sink"},
+ },
+ ],
+ )
+ self.assertNotIn("relatedLocations", result)
+
+ def test_sarif_deduplicates_dot_prefixed_location_paths(self) -> None:
+ sarif_finding = self.sarif_finding("fingerprint")
+ sarif_finding["locations"] = [{"path": "./src/write.py", "startLine": 30, "role": "sink"}]
+ sarif_finding["codeEvidence"] = [
+ {
+ "id": "duplicate-sink",
+ "label": "Duplicate sink",
+ "path": "src/write.py",
+ "startLine": 30,
+ "code": "write(user_input)",
+ "explanation": "Already present in locations.",
+ }
+ ]
+
+ result = FINALIZER._sarif_result(sarif_finding, 0)
+
+ self.assertEqual(len(result["locations"]), 1)
+ self.assertEqual(result["locations"][0]["message"], {"text": "sink"})
+
+ @pytest.mark.cross_platform
+ def test_sarif_includes_legacy_code_evidence_locations(self) -> None:
+ sarif_finding = self.sarif_finding("fingerprint")
+ sarif_finding["codeEvidence"] = [
+ {
+ "id": "canonical-source",
+ "label": "Canonical source",
+ "path": "src/canonical.py",
+ "startLine": 12,
+ "code": "canonical_source()",
+ "explanation": "Canonical evidence.",
+ }
+ ]
+ sarif_finding["code_evidence"] = [
+ {
+ "id": "legacy-sink",
+ "path": "src/legacy.py",
+ "startLine": 37,
+ "endLine": 39,
+ "code": "legacy_sink()",
+ }
+ ]
+
+ result = FINALIZER._sarif_result(sarif_finding, 0)
+
+ locations = {
+ location["physicalLocation"]["artifactLocation"]["uri"]: location
+ for location in result["locations"]
+ }
+ self.assertEqual(
+ locations["src/canonical.py"]["physicalLocation"]["region"],
+ {"startLine": 12, "endLine": 12},
+ )
+ self.assertEqual(
+ locations["src/legacy.py"],
+ {
+ "physicalLocation": {
+ "artifactLocation": {"uri": "src/legacy.py"},
+ "region": {"startLine": 37, "endLine": 39},
+ },
+ "message": {"text": "evidence:legacy-sink"},
+ },
+ )
+
+ @pytest.mark.cross_platform
+ def test_sarif_normalizes_invalid_legacy_code_evidence_bounds(self) -> None:
+ sarif_finding = self.sarif_finding("fingerprint")
+ sarif_finding["code_evidence"] = [
+ {
+ "id": "legacy-null-end",
+ "path": "src/null_end.py",
+ "startLine": 37,
+ "endLine": None,
+ "code": "null_end()",
+ },
+ {
+ "id": "legacy-reversed-end",
+ "path": "src/reversed_end.py",
+ "startLine": 48,
+ "endLine": 47,
+ "code": "reversed_end()",
+ },
+ {
+ "id": "legacy-text-end",
+ "path": "src/text_end.py",
+ "startLine": 59,
+ "endLine": "60",
+ "code": "text_end()",
+ },
+ ]
+
+ result = FINALIZER._sarif_result(sarif_finding, 0)
+
+ regions = {
+ location["physicalLocation"]["artifactLocation"]["uri"]: location["physicalLocation"][
+ "region"
+ ]
+ for location in result["locations"]
+ }
+ self.assertEqual(regions["src/null_end.py"], {"startLine": 37, "endLine": 37})
+ self.assertEqual(regions["src/reversed_end.py"], {"startLine": 48, "endLine": 48})
+ self.assertEqual(regions["src/text_end.py"], {"startLine": 59, "endLine": 59})
+
+ @pytest.mark.cross_platform
+ def test_sarif_omits_invalid_legacy_code_evidence_locations(self) -> None:
+ sarif_finding = self.sarif_finding("fingerprint")
+ sarif_finding["code_evidence"] = [
+ {
+ "id": "legacy-zero-start",
+ "path": "src/zero.py",
+ "startLine": 0,
+ "code": "zero_start()",
+ },
+ {
+ "id": "legacy-negative-start",
+ "path": "src/negative.py",
+ "startLine": -1,
+ "code": "negative_start()",
+ },
+ {
+ "id": "legacy-unsafe-path",
+ "path": "../outside.py",
+ "startLine": 81,
+ "code": "unsafe_path()",
+ },
+ ]
+
+ result = FINALIZER._sarif_result(sarif_finding, 0)
+
+ uris = {
+ location["physicalLocation"]["artifactLocation"]["uri"]
+ for location in result["locations"]
+ }
+ self.assertNotIn("src/zero.py", uris)
+ self.assertNotIn("src/negative.py", uris)
+ self.assertNotIn("../outside.py", uris)
+
+ def test_sarif_only_emits_provenance_for_immutable_revision(self) -> None:
+ sarif = FINALIZER.build_sarif(self.manifest, {"findings": []})
+ self.assertNotIn("versionControlProvenance", sarif["runs"][0])
+
+ self.manifest["scan"]["target"]["kind"] = "git_revision"
+ sarif = FINALIZER.build_sarif(self.manifest, {"findings": []})
+ self.assertEqual(
+ sarif["runs"][0]["versionControlProvenance"],
+ [{"repositoryUri": "https://github.com/example/repo", "revisionId": "deadbeef"}],
+ )
+
+ def test_sarif_emits_github_line_hash_when_source_is_available(self) -> None:
+ source_root = self.write_line_hash_source()
+ sarif_finding = self.sarif_finding("semantic-fingerprint")
+ result = self.sarif_result(sarif_finding, source_root)
+ fingerprints = result["partialFingerprints"]
+ self.assertEqual(fingerprints["codexSecurity/v1"], "semantic-fingerprint")
+ self.assertEqual(fingerprints["primaryLocationLineHash"], "614150a715d5311d:1")
+
+ def test_sarif_emits_github_line_hash_through_windows_backend(self) -> None:
+ source_root = self.write_line_hash_source()
+ sarif_finding = self.sarif_finding("semantic-fingerprint")
+ backend = windows_file_backend()
+
+ with (
+ mock.patch.object(FINALIZER.os, "supports_dir_fd", set()),
+ mock.patch.object(FINALIZER, "_is_windows", return_value=True),
+ mock.patch.object(FINALIZER, "_windows_scan_local_files", return_value=backend),
+ ):
+ result = self.sarif_result(sarif_finding, source_root)
+
+ backend.open_read_fd.assert_called_once_with(
+ source_root, "src/extract.py", "source file src/extract.py"
+ )
+ self.assertEqual(
+ result["partialFingerprints"]["primaryLocationLineHash"],
+ "614150a715d5311d:1",
+ )
+
+ def test_sarif_line_hash_uses_root_control_location(self) -> None:
+ source_root = self.scan_dir / "source"
+ entrypoint_path = source_root / "src" / "route.py"
+ control_path = source_root / "src" / "control.py"
+ entrypoint_path.parent.mkdir(parents=True)
+ entrypoint_path.write_text("entrypoint\n", encoding="utf-8")
+ control_path.write_text("root control\n", encoding="utf-8")
+ sarif_finding = self.sarif_finding("semantic-fingerprint")
+ sarif_finding["locations"] = [
+ {"path": "src/route.py", "startLine": 1, "role": "entrypoint/wrapper"},
+ {"path": "./src//control.py", "startLine": 1, "role": "root_control"},
+ ]
+
+ result = self.sarif_result(sarif_finding, source_root)
+
+ self.assertEqual(
+ result["locations"][0]["physicalLocation"]["artifactLocation"]["uri"],
+ "./src//control.py",
+ )
+ self.assertEqual(
+ result["partialFingerprints"]["primaryLocationLineHash"], "41499a4b14756ba2:1"
+ )
+
+ def test_sarif_line_hash_tolerates_non_utf8_source(self) -> None:
+ source_root = self.scan_dir / "source"
+ source_path = source_root / "src" / "extract.py"
+ source_path.parent.mkdir(parents=True)
+ source_path.write_bytes(b"\n" * 40 + b"invalid: \xff\n")
+ sarif_finding = self.sarif_finding("semantic-fingerprint")
+ result = self.sarif_result(sarif_finding, source_root)
+ self.assertIn("primaryLocationLineHash", result["partialFingerprints"])
+
+ def test_sarif_line_hash_skips_symlink_source(self) -> None:
+ source_root = self.scan_dir / "source"
+ source_path = source_root / "src" / "extract.py"
+ source_path.parent.mkdir(parents=True)
+ with tempfile.TemporaryDirectory() as external_dir:
+ external_path = Path(external_dir) / "extract.py"
+ external_path.write_text(
+ "\n".join(f"line {index}" for index in range(1, 60)), encoding="utf-8"
+ )
+ source_path.symlink_to(external_path)
+ sarif_finding = self.sarif_finding("semantic-fingerprint")
+ result = self.sarif_result(sarif_finding, source_root)
+ self.assertNotIn("primaryLocationLineHash", result["partialFingerprints"])
+
+ @skipUnless(hasattr(os, "mkfifo"), "requires FIFO support")
+ def test_sarif_line_hash_skips_fifo_source_without_blocking(self) -> None:
+ source_root = self.scan_dir / "source"
+ source_root.mkdir()
+ source_path = source_root / "named-pipe"
+ os.mkfifo(source_path)
+ results: list[object] = []
+
+ thread = threading.Thread(
+ target=lambda: results.append(FINALIZER._open_source_file(source_root, "named-pipe")),
+ daemon=True,
+ )
+ thread.start()
+ thread.join(1)
+ blocked = thread.is_alive()
+ if blocked:
+ with source_path.open("w", encoding="utf-8"):
+ pass
+ thread.join(1)
+ for handle in results:
+ if handle is not None:
+ handle.close()
+
+ self.assertFalse(blocked)
+ self.assertEqual(results, [None])
+
+ def test_sarif_line_hash_skips_nul_source_path(self) -> None:
+ source_root = self.scan_dir / "source"
+ (source_root / "src").mkdir(parents=True)
+
+ self.assertIsNone(FINALIZER._open_source_file(source_root, "src/bad\0.py"))
+
+ def test_sarif_line_hash_uses_opened_source_file(self) -> None:
+ source_root = self.scan_dir / "source"
+ source_path = source_root / "src" / "extract.py"
+ source_path.parent.mkdir(parents=True)
+ source_path.write_text(
+ "\n".join(f"inside {index}" for index in range(1, 60)), encoding="utf-8"
+ )
+ with tempfile.TemporaryDirectory() as external_dir:
+ external_path = Path(external_dir) / "extract.py"
+ external_path.write_text(
+ "\n".join(f"outside {index}" for index in range(1, 60)), encoding="utf-8"
+ )
+ handle = FINALIZER._open_source_file(source_root, "src/extract.py")
+ self.assertIsNotNone(handle)
+ source_path.unlink()
+ source_path.symlink_to(external_path)
+ with handle:
+ line_hashes = FINALIZER._github_line_hashes(handle)
+ with external_path.open("r", encoding="utf-8") as external_handle:
+ external_hashes = FINALIZER._github_line_hashes(external_handle)
+ self.assertNotEqual(line_hashes[41], external_hashes[41])
+
+ def test_sarif_line_hash_skips_source_read_error(self) -> None:
+ source_root = self.write_line_hash_source()
+ sarif_finding = self.sarif_finding("semantic-fingerprint")
+ with mock.patch.object(FINALIZER, "_github_line_hashes", side_effect=PermissionError):
+ result = self.sarif_result(sarif_finding, source_root)
+ self.assertNotIn("primaryLocationLineHash", result["partialFingerprints"])
+
+ def test_sarif_line_hash_streams_source(self) -> None:
+ source_path = self.scan_dir / "extract.py"
+ source_path.write_text("line 1\nline 2\n", encoding="utf-8")
+ with mock.patch.object(Path, "read_text", side_effect=AssertionError("not streamed")):
+ with source_path.open("r", encoding="utf-8") as handle:
+ line_hashes = FINALIZER._github_line_hashes(handle)
+ self.assertEqual(line_hashes[1], "a4060029c94de37e:1")
+
+ def test_sarif_line_hash_includes_lines_beyond_previous_limit(self) -> None:
+ source = io.StringIO("line\n" * 100_001)
+
+ self.assertIn(100_001, FINALIZER._github_line_hashes(source, {100_001}))
+
+ def test_sarif_line_hashes_every_source_file(self) -> None:
+ source_root = self.scan_dir / "source"
+ source_dir = source_root / "src"
+ source_dir.mkdir(parents=True)
+ findings = []
+ for index in range(2):
+ relative_path = f"src/extract-{index}.py"
+ (source_root / relative_path).write_text(" " * (6 * 1024 * 1024) + "x")
+ finding = self.sarif_finding(f"fingerprint-{index}", str(index))
+ finding["locations"][0] = {"path": relative_path, "startLine": 1}
+ findings.append(finding)
+
+ sarif = FINALIZER.build_sarif(self.manifest, {"findings": findings}, source_root)
+
+ results = sarif["runs"][0]["results"]
+ for result in results:
+ self.assertIn("primaryLocationLineHash", result["partialFingerprints"])
+
+ def test_sarif_keeps_captured_hash_when_source_root_changes(self) -> None:
+ read_hashes = FINALIZER._github_line_hashes_for_source
+ for change in ("disappear", "retarget"):
+ with self.subTest(change=change):
+ source_root = self.write_line_hash_source()
+ moved_root = source_root.with_name(f"moved-source-{change}")
+
+ def read_then_move(
+ *args, source_root=source_root, moved_root=moved_root, change=change
+ ):
+ hashes = read_hashes(*args)
+ source_root.rename(moved_root)
+ if change == "retarget":
+ replacement = self.scan_dir / "replacement"
+ (replacement / "src").mkdir(parents=True)
+ (replacement / "src" / "extract.py").write_text(
+ "replacement source\n" * 41, encoding="utf-8"
+ )
+ source_root.symlink_to(replacement, target_is_directory=True)
+ return hashes
+
+ with mock.patch.object(
+ FINALIZER, "_github_line_hashes_for_source", side_effect=read_then_move
+ ) as source_reads:
+ result = self.sarif_result(
+ self.sarif_finding("semantic-fingerprint"), source_root
+ )
+
+ self.assertEqual(
+ result["partialFingerprints"]["primaryLocationLineHash"], "614150a715d5311d:1"
+ )
+ self.assertEqual(source_reads.call_count, 1)
+
+ def test_sarif_does_not_retry_source_root_that_appears_after_capture(self) -> None:
+ source_root = self.scan_dir / "source"
+ sarif_rule = FINALIZER._sarif_rule
+
+ def create_source_then_render_rule(*args):
+ self.write_line_hash_source()
+ return sarif_rule(*args)
+
+ with mock.patch.object(
+ FINALIZER, "_sarif_rule", side_effect=create_source_then_render_rule
+ ):
+ result = self.sarif_result(self.sarif_finding("semantic-fingerprint"), source_root)
+
+ self.assertNotIn("primaryLocationLineHash", result["partialFingerprints"])
+
+ def test_sarif_caches_line_hashes_per_source_file(self) -> None:
+ source_root = self.write_line_hash_source()
+ findings = []
+ for index in range(2):
+ finding = self.sarif_finding(f"fingerprint-{index}", str(index))
+ finding["locations"][0]["startLine"] += index
+ finding["locations"][0]["endLine"] += index
+ findings.append(finding)
+
+ with mock.patch.object(
+ FINALIZER, "_github_line_hashes", wraps=FINALIZER._github_line_hashes
+ ) as line_hashes:
+ FINALIZER.build_sarif(self.manifest, {"findings": findings}, source_root)
+
+ self.assertEqual(line_hashes.call_count, 1)
diff --git a/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py b/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py
index 08b897f1f..654c51bd1 100644
--- a/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py
+++ b/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py
@@ -431,7 +431,7 @@ def test_deadline_interrupt_preserves_only_committed_publication(
def test_mid_merge_failure_removes_only_created_recovery_evidence(
tmp_path: Path, monkeypatch, workbench_api, write_kind: str
):
- from workbench import saved_sources
+ from workbench import retained_coverage, saved_sources
scan = deadline_fixture(tmp_path, "valid")
canonical_parent(scan, saved_draft(scan.scan_id, findings=[scan.finding]))
@@ -461,6 +461,7 @@ def test_mid_merge_failure_removes_only_created_recovery_evidence(
monkeypatch.setattr(saved, "write_scan_local_bytes", fail_during_merge)
monkeypatch.setattr(saved_sources, "write_scan_local_bytes", fail_during_merge)
+ monkeypatch.setattr(retained_coverage, "write_scan_local_bytes", fail_during_merge)
with sqlite3.connect(scan.database) as connection:
connection.row_factory = sqlite3.Row
record = workbench_api["require_scan"](connection, scan.scan_id)
@@ -479,7 +480,7 @@ def test_mid_merge_failure_removes_only_created_recovery_evidence(
def test_failed_head_snapshot_does_not_interrupt_publication_rollback(
tmp_path, monkeypatch, workbench_api, snapshot_failure
):
- from workbench import saved_sources
+ from workbench import retained_coverage, saved_sources
scan = deadline_fixture(tmp_path, "valid")
canonical_parent(scan, saved_draft(scan.scan_id, findings=[scan.finding]))
@@ -501,6 +502,7 @@ def test_failed_head_snapshot_does_not_interrupt_publication_rollback(
monkeypatch.setattr(saved, "write_scan_local_bytes", fail_before_snapshot_directory)
monkeypatch.setattr(saved_sources, "write_scan_local_bytes", fail_before_snapshot_directory)
+ monkeypatch.setattr(retained_coverage, "write_scan_local_bytes", fail_before_snapshot_directory)
with sqlite3.connect(scan.database) as connection:
connection.row_factory = sqlite3.Row
connection.execute(
diff --git a/plugins/codex-security/tests/test_deep_deadline_rollback.py b/plugins/codex-security/tests/test_deep_deadline_rollback.py
index 8e0a517a7..aa2ca8f2a 100644
--- a/plugins/codex-security/tests/test_deep_deadline_rollback.py
+++ b/plugins/codex-security/tests/test_deep_deadline_rollback.py
@@ -40,6 +40,36 @@ def publication_context(tmp_path, scan_id):
return binding, db, scan
+def test_deadline_rollback_removes_new_parent_observation_without_a_selected_head(tmp_path):
+ scan_id = "00000000-0000-4000-8000-000000000001"
+ parent = saved_draft(
+ scan_id, deferred=[{"id": "review", "reason": "Review remains."}], complete=True
+ )
+ write_saved_parent(tmp_path, parent, 100)
+ _, db, scan = publication_context(tmp_path, scan_id)
+ original = {
+ path.relative_to(tmp_path): (path.read_bytes(), path.stat().st_mtime_ns)
+ for path in tmp_path.rglob("*")
+ if path.is_file()
+ }
+
+ class Connection:
+ def execute(self, sql, _args):
+ if sql.startswith("UPDATE"):
+ raise RuntimeError("Synthetic publication failure")
+ return SimpleNamespace(fetchall=list)
+
+ with pytest.raises(RuntimeError, match="Synthetic publication failure"):
+ saved.preserve_deep_deadline_draft(db, Connection(), scan)
+
+ restored = {
+ path.relative_to(tmp_path): (path.read_bytes(), path.stat().st_mtime_ns)
+ for path in tmp_path.rglob("*")
+ if path.is_file()
+ }
+ assert restored == original
+
+
@pytest.mark.parametrize("local_failure", [False, True], ids=["caller-rollback", "local-failure"])
def test_deadline_rollback_does_not_reintroduce_a_later_rejected_worker_finding(
tmp_path, local_failure
diff --git a/plugins/codex-security/tests/test_deep_scan_successful_publication.py b/plugins/codex-security/tests/test_deep_scan_successful_publication.py
index 74d9a95fb..9deb22653 100644
--- a/plugins/codex-security/tests/test_deep_scan_successful_publication.py
+++ b/plugins/codex-security/tests/test_deep_scan_successful_publication.py
@@ -941,6 +941,42 @@ def test_stopped_deep_projection_filters_the_canonical_parent(
assert json.loads((scan.scan_dir / "findings.json").read_text())["findings"] == []
[email protected]("scope", ["subdir/extract.py", "./subdir/extract.py"])
+def test_stopped_file_scope_filters_siblings_before_assigning_identity(
+ workbench_api, workbench_db, publication_scan, scope
+):
+ scan = publication_scan(paths=[scope])
+ finding = copy.deepcopy(scan.findings[0])
+ for key in ("identity", "findingId", "occurrenceId", "fingerprints"):
+ finding.pop(key, None)
+ finding["extensions"] = {"candidateId": "candidate-review"}
+ descendant = copy.deepcopy(finding)
+ descendant["locations"] = [{"path": "subdir/extract.py/generated", "startLine": 1}]
+ checkpoint = write_checkpoint(
+ scan.scan_dir / "checkpoints",
+ saved_draft(scan.scan_id, findings=[finding, descendant]),
+ )
+ checkpoint_bytes = checkpoint.read_bytes()
+ for name in ("scan-manifest.json", "findings.json", "coverage.json"):
+ (scan.scan_dir / name).unlink()
+ workbench_api["saved_results"].fail_scan(
+ workbench_api["_WORKBENCH_DB_CONTEXT"],
+ workbench_db,
+ Namespace(scan_id=scan.scan_id, claim_token=None, cost_json=None, message="Interrupted."),
+ )
+ findings = json.loads((scan.scan_dir / "findings.json").read_text())["findings"]
+ assert len(findings) == 1
+ assert findings[0]["locations"][0]["path"] == "subdir/extract.py"
+ assert findings[0]["identity"] == {"anchor": "candidate-review"}
+ names = ("scan-manifest.json", "findings.json", "coverage.json")
+ published = {name: (scan.scan_dir / name).read_bytes() for name in names}
+ workbench_api["saved_results"].recover_scan_results(
+ workbench_api["_WORKBENCH_DB_CONTEXT"], workbench_db, Namespace(scan_id=scan.scan_id)
+ )
+ assert {name: (scan.scan_dir / name).read_bytes() for name in names} == published
+ assert checkpoint.read_bytes() == checkpoint_bytes
+
+
def test_already_sealed_legacy_capped_scan_remains_immutable(
workbench_api, workbench_db, publication_scan
):
diff --git a/plugins/codex-security/tests/test_finalize_scan_contract.py b/plugins/codex-security/tests/test_finalize_scan_contract.py
index fa35e2582..3baed8055 100644
--- a/plugins/codex-security/tests/test_finalize_scan_contract.py
+++ b/plugins/codex-security/tests/test_finalize_scan_contract.py
@@ -9,21 +9,20 @@ import os
import subprocess
import sys
import tempfile
-import threading
from collections.abc import Iterator
from contextlib import contextmanager
from pathlib import Path
-from unittest import main, mock, skipIf, skipUnless
+from unittest import main, mock, skipIf
import pytest
-from workbench_test_support import ScanFixtureTestCase, load_script, windows_file_backend
+from finalize_sarif_cases import FINALIZER, FinalizerSarifCases
+from workbench_test_support import ScanFixtureTestCase, windows_file_backend
-FINALIZER = load_script("finalize_scan_contract")
EXAMPLE_DIR = Path(__file__).resolve().parent.parent / "examples" / "completed-scan"
CANONICAL_FILES = ("scan-manifest.json", "findings.json", "coverage.json")
-class FinalizeScanContractTest(ScanFixtureTestCase):
+class FinalizeScanContractTest(FinalizerSarifCases, ScanFixtureTestCase):
def setUp(self) -> None:
self.temp_dir = tempfile.TemporaryDirectory()
self.scan_dir = Path(self.temp_dir.name).resolve()
@@ -873,6 +872,26 @@ The extraction root is not enforced.
self.assertIn("candidate_id", reader.fieldnames or [])
self.assertEqual(next(reader)["candidate_id"], f"legacy-{field}")
+ def test_deep_csv_candidate_selection_preserves_precedence_and_unicode_whitespace(self) -> None:
+ self.coverage["mode"] = "deep_repository"
+ for provenance, candidate, report, ledger, identity, exported in (
+ ("provenance", "candidate", "report", "ledger", "provenance", "provenance"),
+ ("\ufeff", "candidate", "report", "ledger", "candidate", "candidate"),
+ ("\ufeff", "\ufeff", "report", "ledger", "report", "report"),
+ ("\ufeff", "\ufeff", "\ufeff", "ledger", "ledger", "ledger"),
+ ("\ufeff", "\ufeff", "\ufeff", "\ufeff", None, "\ufeff"),
+ ("\u0085", "candidate", "report", "ledger", "\u0085", "\u0085"),
+ ):
+ with self.subTest(identity=identity, exported=exported):
+ self.finding["provenance"]["candidateId"] = provenance
+ self.finding["extensions"] = {
+ "candidateId": candidate,
+ "reportId": report,
+ "ledgerRowId": ledger,
+ }
+ self.assertEqual(FINALIZER.finding_candidate_id(self.finding), identity)
+ self.assertEqual(next(self.export_csv())["candidate_id"], exported)
+
def test_scoped_csv_export_does_not_classify_ordinary_ledger_ids_as_deep(self) -> None:
self.coverage["mode"] = "scoped_path"
self.finding["extensions"] = {"ledgerRowId": "SCAN-001-parser"}
@@ -967,6 +986,59 @@ The extraction root is not enforced.
)
self.assertEqual(output.read_bytes(), sealed_export)
+ @pytest.mark.cross_platform
+ def test_finalization_preserves_sealed_projection_aliases_and_distinct_paths(self) -> None:
+ root = self.scan_dir
+ for relative, alias, media_type in (
+ ("report.md", "Report.md", "text/markdown"),
+ ("report.html", "REPORT.HTML", "text/html"),
+ ("exports/results.sarif", "Exports/Results.SARIF", "application/sarif+json"),
+ ):
+ for hardlink in (False, True):
+ with self.subTest(relative=relative, hardlink=hardlink):
+ with tempfile.TemporaryDirectory(dir=root) as directory:
+ self.scan_dir = Path(directory)
+ self.write_sealed_scan()
+ output = self.scan_dir / relative
+ artifact = self.scan_dir / alias
+ artifact.parent.mkdir(exist_ok=True)
+ contents = b"Sealed authored projection.\n"
+ output.write_bytes(contents)
+ # Probe native case lookup before creating any hardlink alias.
+ case_alias = artifact.exists()
+ if not case_alias:
+ if hardlink:
+ os.link(output, artifact)
+ else:
+ artifact.write_bytes(contents)
+ same_file = output.samefile(artifact)
+ self.assertEqual(same_file, case_alias or hardlink)
+ manifest = self.read_json("scan-manifest.json")
+ manifest["scan"]["artifacts"].append(
+ {
+ "path": alias,
+ "mediaType": media_type,
+ "sha256": hashlib.sha256(contents).hexdigest(),
+ }
+ )
+ self.write_json("scan-manifest.json", manifest)
+ sealed_manifest = (self.scan_dir / "scan-manifest.json").read_bytes()
+ for _ in range(2):
+ FINALIZER.finalize_scan(self.scan_dir)
+ self.assertEqual(artifact.read_bytes(), contents)
+ self.assertEqual(
+ (self.scan_dir / "scan-manifest.json").read_bytes(),
+ sealed_manifest,
+ )
+ if same_file:
+ self.assertTrue(output.samefile(artifact))
+ self.assertEqual(output.read_bytes(), contents)
+ elif relative == "report.html":
+ self.assertFalse(output.exists())
+ else:
+ self.assertNotEqual(output.read_bytes(), contents)
+ self.scan_dir = root
+
def test_export_entrypoint_rejects_a_case_aliased_scan_directory(self) -> None:
self.write_sealed_scan()
alias = self.scan_dir.parent / self.scan_dir.name.swapcase()
@@ -1342,6 +1414,35 @@ The extraction root is not enforced.
self.assertNotIn("sealedAt", self.read_json("scan-manifest.json")["scan"])
+ @pytest.mark.cross_platform
+ def test_optional_sarif_failure_does_not_abort_first_or_repeated_finalization(self) -> None:
+ root = self.scan_dir
+ for sealed in (False, True):
+ with self.subTest(sealed=sealed):
+ with tempfile.TemporaryDirectory(dir=root) as directory:
+ self.scan_dir = Path(directory)
+ if sealed:
+ self.write_sealed_scan()
+ (self.scan_dir / "exports" / "results.sarif").unlink()
+ (self.scan_dir / "exports").rmdir()
+ else:
+ self.write_scan()
+ contents = b"Saved optional export destination.\n"
+ (self.scan_dir / "exports").write_bytes(contents)
+ errors = io.StringIO()
+ with mock.patch.object(FINALIZER.sys, "stderr", errors):
+ FINALIZER.finalize_scan(self.scan_dir)
+ manifest = (self.scan_dir / "scan-manifest.json").read_bytes()
+ FINALIZER.finalize_scan(self.scan_dir)
+ self.assertIn("automatic SARIF export failed", errors.getvalue())
+ self.assertEqual((self.scan_dir / "exports").read_bytes(), contents)
+ self.assertEqual((self.scan_dir / "scan-manifest.json").read_bytes(), manifest)
+ self.assertEqual(
+ self.read_json("scan-manifest.json")["scan"]["status"], "completed"
+ )
+ self.assertEqual(len(self.read_json("findings.json")["findings"]), 1)
+ self.scan_dir = root
+
def test_sarif_output_fails_closed_without_secure_file_backend(self) -> None:
with mock.patch.object(FINALIZER.os, "supports_dir_fd", set()):
with self.assertRaisesRegex(FINALIZER.ContractError, "descriptor-relative"):
@@ -2839,461 +2940,6 @@ The extraction root is not enforced.
with self.assertRaisesRegex(FINALIZER.ContractError, "requires artifact records"):
FINALIZER.finalize_scan(self.scan_dir)
- def test_sarif_encodes_location_as_relative_uri(self) -> None:
- self.finding["locations"][0]["path"] = "src/archive handlers/extract.py"
- sarif_finding = self.sarif_finding("fingerprint")
- result = FINALIZER._sarif_result(sarif_finding, 0)
- location = result["locations"][0]["physicalLocation"]["artifactLocation"]
- uri = location["uri"]
- self.assertEqual(uri, "src/archive%20handlers/extract.py")
- self.assertNotIn("uriBaseId", location)
-
- def test_sarif_omits_unresolved_source_root_metadata(self) -> None:
- sarif = FINALIZER.build_sarif(self.manifest, {"findings": []})
-
- self.assertNotIn("originalUriBaseIds", sarif["runs"][0])
-
- def test_sarif_keeps_root_first_and_preserves_sink_and_evidence_locations(self) -> None:
- sarif_finding = self.sarif_finding("fingerprint")
- sarif_finding["locations"] = [
- {"path": "src/route.py", "startLine": 10, "role": "entrypoint/wrapper"},
- {"path": "src/control.py", "startLine": 20, "role": "root_control"},
- {"path": "src/write.py", "startLine": 30, "role": "sink"},
- ]
- sarif_finding["codeEvidence"] = [
- {
- "id": "template-sink",
- "label": "Template sink",
- "path": "src/template.html",
- "startLine": 44,
- "endLine": 45,
- "code": "{{ user_input|safe }}",
- "explanation": "The vulnerable template occurrence.",
- },
- {
- "id": "duplicate-sink",
- "label": "Duplicate sink",
- "path": "src/write.py",
- "startLine": 30,
- "code": "write(user_input)",
- "explanation": "Already present in locations.",
- },
- ]
-
- result = FINALIZER._sarif_result(sarif_finding, 0)
-
- self.assertEqual(
- result["locations"],
- [
- {
- "physicalLocation": {
- "artifactLocation": {"uri": "src/control.py"},
- "region": {"startLine": 20, "endLine": 20},
- },
- "message": {"text": "root_control"},
- },
- {
- "physicalLocation": {
- "artifactLocation": {"uri": "src/route.py"},
- "region": {"startLine": 10, "endLine": 10},
- },
- "message": {"text": "entrypoint/wrapper"},
- },
- {
- "physicalLocation": {
- "artifactLocation": {"uri": "src/write.py"},
- "region": {"startLine": 30, "endLine": 30},
- },
- "message": {"text": "sink"},
- },
- {
- "physicalLocation": {
- "artifactLocation": {"uri": "src/template.html"},
- "region": {"startLine": 44, "endLine": 45},
- },
- "message": {"text": "evidence:template-sink"},
- },
- ],
- )
- self.assertNotIn("relatedLocations", result)
-
- def test_sarif_deduplicates_dot_prefixed_location_paths(self) -> None:
- sarif_finding = self.sarif_finding("fingerprint")
- sarif_finding["locations"] = [{"path": "./src/write.py", "startLine": 30, "role": "sink"}]
- sarif_finding["codeEvidence"] = [
- {
- "id": "duplicate-sink",
- "label": "Duplicate sink",
- "path": "src/write.py",
- "startLine": 30,
- "code": "write(user_input)",
- "explanation": "Already present in locations.",
- }
- ]
-
- result = FINALIZER._sarif_result(sarif_finding, 0)
-
- self.assertEqual(len(result["locations"]), 1)
- self.assertEqual(result["locations"][0]["message"], {"text": "sink"})
-
- @pytest.mark.cross_platform
- def test_sarif_includes_legacy_code_evidence_locations(self) -> None:
- sarif_finding = self.sarif_finding("fingerprint")
- sarif_finding["codeEvidence"] = [
- {
- "id": "canonical-source",
- "label": "Canonical source",
- "path": "src/canonical.py",
- "startLine": 12,
- "code": "canonical_source()",
- "explanation": "Canonical evidence.",
- }
- ]
- sarif_finding["code_evidence"] = [
- {
- "id": "legacy-sink",
- "path": "src/legacy.py",
- "startLine": 37,
- "endLine": 39,
- "code": "legacy_sink()",
- }
- ]
-
- result = FINALIZER._sarif_result(sarif_finding, 0)
-
- locations = {
- location["physicalLocation"]["artifactLocation"]["uri"]: location
- for location in result["locations"]
- }
- self.assertEqual(
- locations["src/canonical.py"]["physicalLocation"]["region"],
- {"startLine": 12, "endLine": 12},
- )
- self.assertEqual(
- locations["src/legacy.py"],
- {
- "physicalLocation": {
- "artifactLocation": {"uri": "src/legacy.py"},
- "region": {"startLine": 37, "endLine": 39},
- },
- "message": {"text": "evidence:legacy-sink"},
- },
- )
-
- @pytest.mark.cross_platform
- def test_sarif_normalizes_invalid_legacy_code_evidence_bounds(self) -> None:
- sarif_finding = self.sarif_finding("fingerprint")
- sarif_finding["code_evidence"] = [
- {
- "id": "legacy-null-end",
- "path": "src/null_end.py",
- "startLine": 37,
- "endLine": None,
- "code": "null_end()",
- },
- {
- "id": "legacy-reversed-end",
- "path": "src/reversed_end.py",
- "startLine": 48,
- "endLine": 47,
- "code": "reversed_end()",
- },
- {
- "id": "legacy-text-end",
- "path": "src/text_end.py",
- "startLine": 59,
- "endLine": "60",
- "code": "text_end()",
- },
- ]
-
- result = FINALIZER._sarif_result(sarif_finding, 0)
-
- regions = {
- location["physicalLocation"]["artifactLocation"]["uri"]: location["physicalLocation"][
- "region"
- ]
- for location in result["locations"]
- }
- self.assertEqual(regions["src/null_end.py"], {"startLine": 37, "endLine": 37})
- self.assertEqual(regions["src/reversed_end.py"], {"startLine": 48, "endLine": 48})
- self.assertEqual(regions["src/text_end.py"], {"startLine": 59, "endLine": 59})
-
- @pytest.mark.cross_platform
- def test_sarif_omits_invalid_legacy_code_evidence_locations(self) -> None:
- sarif_finding = self.sarif_finding("fingerprint")
- sarif_finding["code_evidence"] = [
- {
- "id": "legacy-zero-start",
- "path": "src/zero.py",
- "startLine": 0,
- "code": "zero_start()",
- },
- {
- "id": "legacy-negative-start",
- "path": "src/negative.py",
- "startLine": -1,
- "code": "negative_start()",
- },
- {
- "id": "legacy-unsafe-path",
- "path": "../outside.py",
- "startLine": 81,
- "code": "unsafe_path()",
- },
- ]
-
- result = FINALIZER._sarif_result(sarif_finding, 0)
-
- uris = {
- location["physicalLocation"]["artifactLocation"]["uri"]
- for location in result["locations"]
- }
- self.assertNotIn("src/zero.py", uris)
- self.assertNotIn("src/negative.py", uris)
- self.assertNotIn("../outside.py", uris)
-
- def test_sarif_only_emits_provenance_for_immutable_revision(self) -> None:
- sarif = FINALIZER.build_sarif(self.manifest, {"findings": []})
- self.assertNotIn("versionControlProvenance", sarif["runs"][0])
-
- self.manifest["scan"]["target"]["kind"] = "git_revision"
- sarif = FINALIZER.build_sarif(self.manifest, {"findings": []})
- self.assertEqual(
- sarif["runs"][0]["versionControlProvenance"],
- [{"repositoryUri": "https://github.com/example/repo", "revisionId": "deadbeef"}],
- )
-
- def test_sarif_emits_github_line_hash_when_source_is_available(self) -> None:
- source_root = self.write_line_hash_source()
- sarif_finding = self.sarif_finding("semantic-fingerprint")
- result = self.sarif_result(sarif_finding, source_root)
- fingerprints = result["partialFingerprints"]
- self.assertEqual(fingerprints["codexSecurity/v1"], "semantic-fingerprint")
- self.assertEqual(fingerprints["primaryLocationLineHash"], "614150a715d5311d:1")
-
- def test_sarif_emits_github_line_hash_through_windows_backend(self) -> None:
- source_root = self.write_line_hash_source()
- sarif_finding = self.sarif_finding("semantic-fingerprint")
- backend = windows_file_backend()
-
- with (
- mock.patch.object(FINALIZER.os, "supports_dir_fd", set()),
- mock.patch.object(FINALIZER, "_is_windows", return_value=True),
- mock.patch.object(FINALIZER, "_windows_scan_local_files", return_value=backend),
- ):
- result = self.sarif_result(sarif_finding, source_root)
-
- backend.open_read_fd.assert_called_once_with(
- source_root, "src/extract.py", "source file src/extract.py"
- )
- self.assertEqual(
- result["partialFingerprints"]["primaryLocationLineHash"],
- "614150a715d5311d:1",
- )
-
- def test_sarif_line_hash_uses_root_control_location(self) -> None:
- source_root = self.scan_dir / "source"
- entrypoint_path = source_root / "src" / "route.py"
- control_path = source_root / "src" / "control.py"
- entrypoint_path.parent.mkdir(parents=True)
- entrypoint_path.write_text("entrypoint\n", encoding="utf-8")
- control_path.write_text("root control\n", encoding="utf-8")
- sarif_finding = self.sarif_finding("semantic-fingerprint")
- sarif_finding["locations"] = [
- {"path": "src/route.py", "startLine": 1, "role": "entrypoint/wrapper"},
- {"path": "./src//control.py", "startLine": 1, "role": "root_control"},
- ]
-
- result = self.sarif_result(sarif_finding, source_root)
-
- self.assertEqual(
- result["locations"][0]["physicalLocation"]["artifactLocation"]["uri"],
- "./src//control.py",
- )
- self.assertEqual(
- result["partialFingerprints"]["primaryLocationLineHash"], "41499a4b14756ba2:1"
- )
-
- def test_sarif_line_hash_tolerates_non_utf8_source(self) -> None:
- source_root = self.scan_dir / "source"
- source_path = source_root / "src" / "extract.py"
- source_path.parent.mkdir(parents=True)
- source_path.write_bytes(b"\n" * 40 + b"invalid: \xff\n")
- sarif_finding = self.sarif_finding("semantic-fingerprint")
- result = self.sarif_result(sarif_finding, source_root)
- self.assertIn("primaryLocationLineHash", result["partialFingerprints"])
-
- def test_sarif_line_hash_skips_symlink_source(self) -> None:
- source_root = self.scan_dir / "source"
- source_path = source_root / "src" / "extract.py"
- source_path.parent.mkdir(parents=True)
- with tempfile.TemporaryDirectory() as external_dir:
- external_path = Path(external_dir) / "extract.py"
- external_path.write_text(
- "\n".join(f"line {index}" for index in range(1, 60)), encoding="utf-8"
- )
- source_path.symlink_to(external_path)
- sarif_finding = self.sarif_finding("semantic-fingerprint")
- result = self.sarif_result(sarif_finding, source_root)
- self.assertNotIn("primaryLocationLineHash", result["partialFingerprints"])
-
- @skipUnless(hasattr(os, "mkfifo"), "requires FIFO support")
- def test_sarif_line_hash_skips_fifo_source_without_blocking(self) -> None:
- source_root = self.scan_dir / "source"
- source_root.mkdir()
- source_path = source_root / "named-pipe"
- os.mkfifo(source_path)
- results: list[object] = []
-
- thread = threading.Thread(
- target=lambda: results.append(FINALIZER._open_source_file(source_root, "named-pipe")),
- daemon=True,
- )
- thread.start()
- thread.join(1)
- blocked = thread.is_alive()
- if blocked:
- with source_path.open("w", encoding="utf-8"):
- pass
- thread.join(1)
- for handle in results:
- if handle is not None:
- handle.close()
-
- self.assertFalse(blocked)
- self.assertEqual(results, [None])
-
- def test_sarif_line_hash_skips_nul_source_path(self) -> None:
- source_root = self.scan_dir / "source"
- (source_root / "src").mkdir(parents=True)
-
- self.assertIsNone(FINALIZER._open_source_file(source_root, "src/bad\0.py"))
-
- def test_sarif_line_hash_uses_opened_source_file(self) -> None:
- source_root = self.scan_dir / "source"
- source_path = source_root / "src" / "extract.py"
- source_path.parent.mkdir(parents=True)
- source_path.write_text(
- "\n".join(f"inside {index}" for index in range(1, 60)), encoding="utf-8"
- )
- with tempfile.TemporaryDirectory() as external_dir:
- external_path = Path(external_dir) / "extract.py"
- external_path.write_text(
- "\n".join(f"outside {index}" for index in range(1, 60)), encoding="utf-8"
- )
- handle = FINALIZER._open_source_file(source_root, "src/extract.py")
- self.assertIsNotNone(handle)
- source_path.unlink()
- source_path.symlink_to(external_path)
- with handle:
- line_hashes = FINALIZER._github_line_hashes(handle)
- with external_path.open("r", encoding="utf-8") as external_handle:
- external_hashes = FINALIZER._github_line_hashes(external_handle)
- self.assertNotEqual(line_hashes[41], external_hashes[41])
-
- def test_sarif_line_hash_skips_source_read_error(self) -> None:
- source_root = self.write_line_hash_source()
- sarif_finding = self.sarif_finding("semantic-fingerprint")
- with mock.patch.object(FINALIZER, "_github_line_hashes", side_effect=PermissionError):
- result = self.sarif_result(sarif_finding, source_root)
- self.assertNotIn("primaryLocationLineHash", result["partialFingerprints"])
-
- def test_sarif_line_hash_streams_source(self) -> None:
- source_path = self.scan_dir / "extract.py"
- source_path.write_text("line 1\nline 2\n", encoding="utf-8")
- with mock.patch.object(Path, "read_text", side_effect=AssertionError("not streamed")):
- with source_path.open("r", encoding="utf-8") as handle:
- line_hashes = FINALIZER._github_line_hashes(handle)
- self.assertEqual(line_hashes[1], "a4060029c94de37e:1")
-
- def test_sarif_line_hash_includes_lines_beyond_previous_limit(self) -> None:
- source = io.StringIO("line\n" * 100_001)
-
- self.assertIn(100_001, FINALIZER._github_line_hashes(source, {100_001}))
-
- def test_sarif_line_hashes_every_source_file(self) -> None:
- source_root = self.scan_dir / "source"
- source_dir = source_root / "src"
- source_dir.mkdir(parents=True)
- findings = []
- for index in range(2):
- relative_path = f"src/extract-{index}.py"
- (source_root / relative_path).write_text(" " * (6 * 1024 * 1024) + "x")
- finding = self.sarif_finding(f"fingerprint-{index}", str(index))
- finding["locations"][0] = {"path": relative_path, "startLine": 1}
- findings.append(finding)
-
- sarif = FINALIZER.build_sarif(self.manifest, {"findings": findings}, source_root)
-
- results = sarif["runs"][0]["results"]
- for result in results:
- self.assertIn("primaryLocationLineHash", result["partialFingerprints"])
-
- def test_sarif_keeps_captured_hash_when_source_root_changes(self) -> None:
- read_hashes = FINALIZER._github_line_hashes_for_source
- for change in ("disappear", "retarget"):
- with self.subTest(change=change):
- source_root = self.write_line_hash_source()
- moved_root = source_root.with_name(f"moved-source-{change}")
-
- def read_then_move(
- *args, source_root=source_root, moved_root=moved_root, change=change
- ):
- hashes = read_hashes(*args)
- source_root.rename(moved_root)
- if change == "retarget":
- replacement = self.scan_dir / "replacement"
- (replacement / "src").mkdir(parents=True)
- (replacement / "src" / "extract.py").write_text(
- "replacement source\n" * 41, encoding="utf-8"
- )
- source_root.symlink_to(replacement, target_is_directory=True)
- return hashes
-
- with mock.patch.object(
- FINALIZER, "_github_line_hashes_for_source", side_effect=read_then_move
- ) as source_reads:
- result = self.sarif_result(
- self.sarif_finding("semantic-fingerprint"), source_root
- )
-
- self.assertEqual(
- result["partialFingerprints"]["primaryLocationLineHash"], "614150a715d5311d:1"
- )
- self.assertEqual(source_reads.call_count, 1)
-
- def test_sarif_does_not_retry_source_root_that_appears_after_capture(self) -> None:
- source_root = self.scan_dir / "source"
- sarif_rule = FINALIZER._sarif_rule
-
- def create_source_then_render_rule(*args):
- self.write_line_hash_source()
- return sarif_rule(*args)
-
- with mock.patch.object(
- FINALIZER, "_sarif_rule", side_effect=create_source_then_render_rule
- ):
- result = self.sarif_result(self.sarif_finding("semantic-fingerprint"), source_root)
-
- self.assertNotIn("primaryLocationLineHash", result["partialFingerprints"])
-
- def test_sarif_caches_line_hashes_per_source_file(self) -> None:
- source_root = self.write_line_hash_source()
- findings = []
- for index in range(2):
- finding = self.sarif_finding(f"fingerprint-{index}", str(index))
- finding["locations"][0]["startLine"] += index
- finding["locations"][0]["endLine"] += index
- findings.append(finding)
-
- with mock.patch.object(
- FINALIZER, "_github_line_hashes", wraps=FINALIZER._github_line_hashes
- ) as line_hashes:
- FINALIZER.build_sarif(self.manifest, {"findings": findings}, source_root)
-
- self.assertEqual(line_hashes.call_count, 1)
-
if __name__ == "__main__":
main()
diff --git a/plugins/codex-security/tests/test_sarif_projection.py b/plugins/codex-security/tests/test_sarif_projection.py
index c3a15934e..e146a8f85 100644
--- a/plugins/codex-security/tests/test_sarif_projection.py
+++ b/plugins/codex-security/tests/test_sarif_projection.py
@@ -10,6 +10,7 @@ import tempfile
import unittest
from contextlib import redirect_stderr
from pathlib import Path
+from unittest import mock
from workbench_test_support import load_script
@@ -271,9 +272,15 @@ class SarifProjectionTest(unittest.TestCase):
self.assertEqual(before, {path: path.read_bytes() for path in before})
stderr = io.StringIO()
- with redirect_stderr(stderr):
+ with (
+ redirect_stderr(stderr),
+ mock.patch.object(
+ FINALIZER, "write_sarif_projection", wraps=FINALIZER.write_sarif_projection
+ ) as write_projection,
+ ):
FINALIZER.finalize_scan(scan_dir)
- self.assertIn(f"warning: automatic SARIF export failed: {error}", stderr.getvalue())
+ write_projection.assert_not_called()
+ self.assertEqual(stderr.getvalue(), "")
self.assertEqual(before, {path: path.read_bytes() for path in before})
self.assertEqual(
FINALIZER.build_findings_export(scan_dir, "json"),
diff --git a/plugins/codex-security/tests/test_saved_deferred_identity.py b/plugins/codex-security/tests/test_saved_deferred_identity.py
index 6359b2648..c316fad90 100644
--- a/plugins/codex-security/tests/test_saved_deferred_identity.py
+++ b/plugins/codex-security/tests/test_saved_deferred_identity.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+import copy
import json
import os
import sys
@@ -13,7 +14,9 @@ from test_workbench_standard_deep_results import (
write_saved_parent,
)
from workbench_test_support import (
+ fail_deep_scan,
preserve_scan_results,
+ run_workbench,
saved_discovery_worker,
saved_draft,
write_checkpoint,
@@ -44,7 +47,7 @@ def save_worker(root: Path, module, worker_id: str, drafts: list[dict], result:
return saved_discovery_worker(output, worker_id, 1)
-def recover(root: Path, module, workers, frozen=None):
+def recover(root: Path, module, workers, frozen=None, *, preserve_reduction=False):
binding = {
"status": "interrupted",
"allowedTargetKinds": ["git_revision"],
@@ -63,14 +66,316 @@ def recover(root: Path, module, workers, frozen=None):
binding,
workers,
[],
- stopped=True,
+ stopped=not preserve_reduction,
reason="interrupted",
frozen_source_digests=frozen,
+ preserve_canonical_parent=preserve_reduction,
+ current_contract=preserve_reduction,
+ scan_mode="deep" if preserve_reduction else None,
)
assert result is not None
return result
[email protected]("reserved", [False, True])
+def test_repeated_colliding_variant_keeps_its_assigned_identity(
+ tmp_path: Path, saved_results, reserved: bool
+):
+ from finalize_scan_contract import _recover_unsealed_findings
+
+ first = {
+ "ruleId": "fixture.review",
+ "identity": {"anchor": "shared-review"},
+ "title": "First independent review",
+ "summary": "Synthetic evidence at the first location.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin"},
+ }
+ second = {
+ **copy.deepcopy(first),
+ "title": "Second independent review",
+ "locations": [{"path": "src/example.py", "startLine": 2}],
+ }
+ revision = {
+ **copy.deepcopy(second),
+ "title": "Revised second review",
+ "severity": {"level": "high"},
+ }
+ findings = [first, second, revision]
+ if reserved:
+ findings.append(
+ {
+ **copy.deepcopy(first),
+ "title": "Reserved independent review",
+ "identity": {"anchor": "shared-review", "instance": "saved-2"},
+ "locations": [{"path": "src/example.py", "startLine": 3}],
+ }
+ )
+ write_saved_parent(tmp_path, saved_draft("identity-scan", findings=findings), 100)
+ documents = recover(tmp_path, saved_results, [])
+ recovered = documents[1]["findings"]
+ assert recovered[0]["identity"] != recovered[1]["identity"]
+ assert recovered[1]["identity"] == recovered[2]["identity"]
+ warnings = []
+ documents[1]["scanId"] = "identity-scan"
+ _recover_unsealed_findings(
+ {"scan": {"id": "identity-scan", "target": {"targetId": "synthetic"}}},
+ documents[1],
+ Path(__file__).resolve().parents[1] / "schemas",
+ tmp_path,
+ warnings,
+ )
+ assert [row["title"] for row in documents[1]["findings"]] == [
+ "First independent review",
+ "Revised second review",
+ *(["Reserved independent review"] if reserved else []),
+ ]
+ assert documents[1]["findings"][1]["provenance"]["previousFindings"][0]["title"] == (
+ "Second independent review"
+ )
+
+
[email protected]("retain_roles", [False, True])
+def test_legacy_frozen_source_order_parent_context_remains_readable(
+ tmp_path, saved_results, retain_roles
+):
+ finding = {
+ "ruleId": "fixture.review",
+ "identity": {"anchor": "review"},
+ "title": "Review",
+ "summary": "Synthetic evidence.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin"},
+ }
+ write_saved_parent(tmp_path, saved_draft("identity-scan", findings=[finding]), 100)
+ first = recover(tmp_path, saved_results, [])
+ legacy_sources = dict(first[0]["scan"]["preservedSources"])
+ for relative in list(legacy_sources):
+ if not saved_results._is_source_order_snapshot(relative):
+ continue
+ record = json.loads((tmp_path / relative).read_text())
+ if retain_roles:
+ observed_at = record["parentContext"].pop("canonicalObservedAtNs")
+ assert observed_at
+ else:
+ parent_context = record.pop("parentContext")
+ assert parent_context
+ digest = saved_results._digest(record)
+ legacy_path = f"source-order/{digest}.json"
+ (tmp_path / legacy_path).write_bytes(saved_results._encoded(record))
+ del legacy_sources[relative]
+ legacy_sources[legacy_path] = digest
+ replay = recover(tmp_path, saved_results, [], legacy_sources)
+ assert replay[1:] == first[1:]
+
+
[email protected]("field", ["disposition", "completeness"])
+def test_malformed_coverage_does_not_interrupt_saved_evidence(
+ tmp_path: Path, saved_results, field: str
+):
+ draft = saved_draft("identity-scan", deferred=[{"id": "review", "reason": "Review remains."}])
+ if field == "disposition":
+ draft["coverage"]["surfaces"] = [
+ {"id": "review", "candidateId": "review", "disposition": ["rejected"]}
+ ]
+ else:
+ draft["coverage"]["completeness"] = ["complete"]
+ write_saved_parent(tmp_path, draft, 100)
+ worker = save_worker(tmp_path, saved_results, "reviewer", [], draft)
+ result = recover(tmp_path, saved_results, [worker])
+ assert any(row["id"] == "review" for row in result[2]["deferred"])
+
+
+def test_missing_parent_identity_is_identical_on_frozen_replay(tmp_path: Path, saved_results):
+ finding = {
+ "ruleId": "fixture.review",
+ "title": "Synthetic review finding",
+ "summary": "Retain the saved result.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin"},
+ }
+ draft = saved_draft("identity-scan", findings=[finding])
+ write_saved_parent(tmp_path, draft, 100)
+ first = recover(tmp_path, saved_results, [])
+ for name in ("scan-manifest.json", "findings.json", "coverage.json"):
+ (tmp_path / name).unlink()
+ replay = recover(tmp_path, saved_results, [], first[0]["scan"]["preservedSources"])
+ assert len(first[1]["findings"]) == len(replay[1]["findings"]) == 1
+ assert first[1]["findings"][0]["identity"] == replay[1]["findings"][0]["identity"]
+
+
[email protected]("stopped", [False, True])
[email protected]("saved_anchor", ["stable-anchor", 42])
[email protected]("explicit_end_line", [False, True])
+def test_missing_parent_identity_reuses_established_checkpoint(
+ tmp_path: Path, saved_results, stopped, saved_anchor, explicit_end_line
+):
+ from finalize_scan_contract import _recover_unsealed_findings
+ from workbench_test_support import saved_binding
+
+ finding = {
+ "ruleId": "fixture.review",
+ "title": "Synthetic review finding",
+ "summary": "Retain the saved result.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin"},
+ }
+ checkpoint = write_checkpoint(
+ tmp_path / "checkpoints",
+ saved_draft(
+ "identity-scan",
+ complete=True,
+ findings=[{**finding, "identity": {"anchor": saved_anchor}}],
+ ),
+ )
+ os.utime(checkpoint, ns=(100, 100))
+ if explicit_end_line:
+ finding["locations"][0]["endLine"] = 1
+ write_saved_parent(
+ tmp_path, saved_draft("identity-scan", complete=True, findings=[finding]), 200
+ )
+ binding = saved_binding()
+ binding["target"] = {
+ "kind": "git_revision",
+ "targetId": "synthetic",
+ "displayName": "test",
+ "revision": "head",
+ }
+ warnings = []
+ documents = saved_results.merge_saved_results(
+ tmp_path, "identity-scan", binding, [], warnings, stopped=stopped, reason="interrupted"
+ )
+ documents[0]["scan"].update(id="identity-scan", target=binding["target"])
+ documents[1]["scanId"] = "identity-scan"
+ _recover_unsealed_findings(
+ documents[0],
+ documents[1],
+ Path(__file__).resolve().parents[1] / "schemas",
+ tmp_path,
+ warnings,
+ )
+ expected = saved_anchor if isinstance(saved_anchor, str) else "synthetic-review-finding"
+ assert [row["identity"] for row in documents[1]["findings"]] == [{"anchor": expected}], warnings
+
+
[email protected]("artifacts", ["omitted", None, []])
[email protected]("outcome", ["failed", "canceled"])
+def test_empty_artifact_envelope_remains_a_recoverable_draft(tmp_path: Path, artifacts, outcome):
+ state, codex_home, _, scan_dir, scan_id = deep_scan_fixture(tmp_path)
+ accepted_standard_worker(state, codex_home, scan_dir, scan_id)
+ write_saved_parent(
+ scan_dir,
+ saved_draft(scan_id, deferred=[{"id": "review", "reason": "Review remains."}]),
+ 100,
+ )
+ manifest_path = scan_dir / "scan-manifest.json"
+ manifest = json.loads(manifest_path.read_text())
+ if artifacts != "omitted":
+ manifest["scan"]["artifacts"] = artifacts
+ manifest_path.write_text(json.dumps(manifest))
+ run_workbench(
+ state,
+ "save-scan-artifact",
+ "--scan-id",
+ scan_id,
+ "--artifact-path",
+ "artifacts/review.txt",
+ input_text="Synthetic review receipt.",
+ environment={"CODEX_HOME": str(codex_home)},
+ )
+ assert (scan_dir / "artifacts/review.txt").read_text() == "Synthetic review receipt."
+ if outcome == "failed":
+ fail_deep_scan(state, codex_home, scan_id)
+ else:
+ run_workbench(
+ state,
+ "cancel-scan",
+ "--scan-id",
+ scan_id,
+ "--thread-id",
+ "standard-worker-thread",
+ environment={"CODEX_HOME": str(codex_home)},
+ )
+ sealed = json.loads(manifest_path.read_text())
+ assert sealed["scan"]["status"] == outcome
+ assert sealed["scan"]["sealedAt"]
+ original = manifest_path.read_bytes()
+ if outcome == "failed":
+ run_workbench(
+ state,
+ "recover-scan-results",
+ "--scan-id",
+ scan_id,
+ environment={"CODEX_HOME": str(codex_home)},
+ )
+ else:
+ run_workbench(
+ state,
+ "preserve-scan-results",
+ "--scan-id",
+ scan_id,
+ "--thread-id",
+ "standard-worker-thread",
+ environment={"CODEX_HOME": str(codex_home)},
+ )
+ assert manifest_path.read_bytes() == original
+
+
+def test_stopped_deep_recovery_uses_host_mode_for_terminal_replacement(tmp_path: Path):
+ state, codex_home, _, scan_dir, scan_id = deep_scan_fixture(tmp_path)
+ accepted_standard_worker(state, codex_home, scan_dir, scan_id)
+ first = {
+ "ruleId": "fixture.review",
+ "identity": {"anchor": "first-review"},
+ "title": "First review",
+ "summary": "Earlier synthetic evidence.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "app.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin"},
+ }
+ write_saved_parent(scan_dir, saved_draft(scan_id, findings=[first], complete=True), 100)
+ revised = {**first, "title": "Revised review", "summary": "Revised synthetic evidence."}
+ del revised["identity"]
+ checkpoint = write_checkpoint(
+ scan_dir / "checkpoints", saved_draft(scan_id, findings=[revised], complete=True)
+ )
+ os.utime(checkpoint, ns=(200, 200))
+ fail_deep_scan(state, codex_home, scan_id)
+ findings_path = scan_dir / "findings.json"
+ findings = json.loads(findings_path.read_text())["findings"]
+ assert [(row["title"], row["identity"]) for row in findings] == [
+ ("Revised review", {"anchor": "revised-review"})
+ ]
+ original = findings_path.read_bytes()
+ run_workbench(
+ state,
+ "recover-scan-results",
+ "--scan-id",
+ scan_id,
+ environment={"CODEX_HOME": str(codex_home)},
+ )
+ assert findings_path.read_bytes() == original
+
+
@pytest.mark.parametrize("reason", ["Review remains.", "Unicode review: é \ud800"])
@pytest.mark.parametrize("task_count", [1, 2])
def test_torn_worker_closure_reuses_observed_legacy_identity(
@@ -622,3 +927,474 @@ def test_legacy_summary_stays_pending_after_an_explicit_closure(
{key: value for key, value in row.items() if key != "id"} == summary for row in pending
)
assert replay[2] == first[2]
+
+
[email protected]("same_title", [False, True])
+def test_worker_local_candidates_remain_distinct_on_frozen_recovery(
+ tmp_path, saved_results, same_title
+):
+ finding = {
+ "ruleId": "fixture.review",
+ "title": "First review",
+ "summary": "Retain the saved result.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin", "candidateId": "candidate-1"},
+ }
+ workers = [
+ save_worker(
+ tmp_path,
+ saved_results,
+ worker,
+ [],
+ saved_draft("identity-scan", findings=[{**finding, "title": title}]),
+ )
+ for worker, title in [
+ ("reviewer-a", "First review"),
+ ("reviewer-b", "First review" if same_title else "Second review"),
+ ]
+ ]
+ documents = recover(tmp_path, saved_results, workers)
+ replay = recover(tmp_path, saved_results, workers, documents[0]["scan"]["preservedSources"])
+ for result in (documents, replay):
+ rows = result[1]["findings"]
+ assert len(rows) == 2
+ assert {row["provenance"]["workerId"] for row in rows} == {"reviewer-a", "reviewer-b"}
+ assert len({json.dumps(row["identity"], sort_keys=True) for row in rows}) == 2
+ assert documents[1] == replay[1]
+
+
[email protected]("revised", [False, True])
+def test_recovery_finalization_coalesces_repeated_authored_reports(
+ tmp_path, saved_results, revised
+):
+ from finalize_scan_contract import _recover_unsealed_findings
+
+ first = {
+ "ruleId": "fixture.review",
+ "title": "Existing report",
+ "summary": "Synthetic evidence.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin", "candidateId": "candidate-1"},
+ "identity": {"anchor": "shared"},
+ "extensions": {"reportId": "report-1"},
+ }
+ latest = (
+ {
+ **first,
+ "summary": "Synthetic evidence with additional detail.",
+ "severity": {"level": "high"},
+ }
+ if revised
+ else first
+ )
+ draft = saved_draft("identity-scan", findings=[first, latest])
+ worker = save_worker(tmp_path, saved_results, "reviewer", [draft], draft)
+ manifest, findings, _ = recover(tmp_path, saved_results, [worker])
+ manifest["scan"]["id"] = "identity-scan"
+ findings["scanId"] = "identity-scan"
+ _recover_unsealed_findings(
+ manifest, findings, Path(__file__).resolve().parents[1] / "schemas", tmp_path, []
+ )
+ assert len(findings["findings"]) == 1
+ assert findings["findings"][0]["identity"] == first["identity"]
+ assert findings["findings"][0]["summary"] == latest["summary"]
+
+
[email protected]("identifier", ["reportId", "ledgerRowId"])
[email protected]("saved_result", [False, True])
+def test_recovery_finalization_preserves_distinct_reports_at_a_revised_location(
+ tmp_path, saved_results, identifier, saved_result
+):
+ from finalize_scan_contract import _recover_unsealed_findings
+
+ first = {
+ "ruleId": "fixture.review",
+ "title": "Existing report",
+ "summary": "Synthetic evidence.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 2}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin", "candidateId": "candidate-1"},
+ "identity": {"anchor": "shared"},
+ }
+ independent = {
+ **first,
+ "title": "Independent report",
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "provenance": {"source": "local_plugin"},
+ "extensions": {identifier: "report-2"},
+ }
+ revised = {
+ **first,
+ "locations": independent["locations"],
+ "extensions": {identifier: "report-1"},
+ }
+ del revised["identity"]
+ drafts = [
+ saved_draft("identity-scan", findings=[first]),
+ saved_draft("identity-scan", findings=[independent, revised]),
+ ]
+ output = tmp_path / "reviewer"
+ for sequence, draft in enumerate(drafts, 1):
+ path = write_checkpoint(output / "checkpoints", draft)
+ os.utime(path, ns=(sequence * 1_000_000_000, sequence * 1_000_000_000))
+ if saved_result:
+ result = output / "result.json"
+ result.write_text(json.dumps(drafts[-1]))
+ os.utime(result, ns=(3_000_000_000, 3_000_000_000))
+ worker = saved_discovery_worker(output, "reviewer")
+ sources = {path: path.read_bytes() for path in output.rglob("*.json")}
+ documents = recover(tmp_path, saved_results, [worker])
+ replay = recover(tmp_path, saved_results, [worker], documents[0]["scan"]["preservedSources"])
+ for manifest, findings, _ in (documents, replay):
+ # The moved checkpoint revises the existing report without adding a third row.
+ assert len(findings["findings"]) == 2
+ manifest["scan"]["id"] = "identity-scan"
+ findings["scanId"] = "identity-scan"
+ warnings = []
+ _recover_unsealed_findings(
+ manifest,
+ findings,
+ Path(__file__).resolve().parents[1] / "schemas",
+ tmp_path,
+ warnings,
+ )
+ rows = findings["findings"]
+ assert {row["extensions"][identifier] for row in rows} == {"report-1", "report-2"}, warnings
+ assert len(rows) == 2
+ assert all(row["locations"] == independent["locations"] for row in rows)
+ assert len({json.dumps(row["identity"], sort_keys=True) for row in rows}) == 2
+ existing = next(row for row in rows if row["extensions"][identifier] == "report-1")
+ assert any(
+ previous["locations"] == first["locations"]
+ for previous in existing["provenance"]["previousFindings"]
+ )
+ assert documents[1] == replay[1]
+ assert all(path.read_bytes() == original for path, original in sources.items())
+
+
[email protected]("metadata", ["extensions", "provenance"])
[email protected]("identifier", ["reportId", "ledgerRowId"])
+def test_worker_report_metadata_enrichment_matches_published_identity(
+ tmp_path, saved_results, metadata, identifier
+):
+ first = {
+ "ruleId": "fixture.review",
+ "title": "Synthetic report",
+ "summary": "Retain the saved result.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin"},
+ "extensions": {identifier: "report-1"},
+ }
+ second = {**first, metadata: {**first[metadata], "candidateId": "candidate-1"}}
+ drafts = [saved_draft("identity-scan", findings=[value]) for value in (first, second)]
+ worker = save_worker(tmp_path, saved_results, "reviewer", drafts, drafts[1])
+ documents = recover(tmp_path, saved_results, [worker])
+ replay = recover(tmp_path, saved_results, [worker], documents[0]["scan"]["preservedSources"])
+ for result in (documents, replay):
+ assert len(result[1]["findings"]) == 1
+ assert result[1]["findings"][0]["identity"] == {
+ "anchor": "candidate-1",
+ "instance": "report-1",
+ }
+ assert documents[1] == replay[1]
+
+
[email protected]("metadata", ["provenance", "extensions"])
+def test_parent_represents_worker_versions_before_candidate_enrichment(
+ tmp_path, saved_results, metadata
+):
+ first = {
+ "ruleId": "fixture.review",
+ "title": "Synthetic review",
+ "summary": "Synthetic evidence.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin"},
+ }
+ latest = {**first, metadata: {**first.get(metadata, {}), "candidateId": "candidate-1"}}
+ reduced = {
+ **latest,
+ "summary": "Consolidated evidence.",
+ "provenance": {
+ **latest["provenance"],
+ "sourceFindingIds": ["reviewer:0"],
+ "sourceFindings": [{"id": "reviewer:0", "finding": latest}],
+ },
+ }
+ parent = {**reduced, "identity": {"anchor": "candidate-1"}}
+ write_saved_parent(
+ tmp_path, saved_draft("identity-scan", findings=[parent], complete=True), 2000
+ )
+ worker = save_worker(
+ tmp_path,
+ saved_results,
+ "reviewer",
+ [saved_draft("identity-scan", findings=[first])],
+ saved_draft("identity-scan", findings=[latest], complete=True),
+ )
+ output = tmp_path / "reducer"
+ output.mkdir()
+ draft = {"scanId": "identity-scan", "complete": True, "findings": [reduced]}
+ result = output / "result.json"
+ result.write_text(json.dumps(draft))
+ os.utime(result, ns=(1500, 1500))
+ checkpoint = write_checkpoint(output / "checkpoints", draft)
+ os.utime(checkpoint, ns=(1500, 1500))
+ reducer = {
+ "id": "reducer",
+ "kind": "dedup",
+ "status": "succeeded",
+ "completed_at": "2026-05-31T18:08:00Z",
+ "artifact_dir": str(output),
+ "result_manifest_path": str(result),
+ "attempt": 1,
+ }
+ documents = recover(tmp_path, saved_results, [worker, reducer])
+ replay = recover(
+ tmp_path, saved_results, [worker, reducer], documents[0]["scan"]["preservedSources"]
+ )
+ for recovered in (documents, replay):
+ assert len(recovered[1]["findings"]) == 1
+ assert recovered[1]["findings"][0]["summary"] == "Consolidated evidence."
+ assert recovered[1]["findings"][0]["identity"] == {"anchor": "candidate-1"}
+ assert documents[1] == replay[1]
+
+
[email protected]("reversed_rows", [False, True])
[email protected]("revised_identity", ["explicit", "implicit", "anonymous"])
[email protected]("preserve_reduction", [False, True])
+def test_worker_revision_keeps_assigned_sibling_on_frozen_recovery(
+ tmp_path, saved_results, reversed_rows, revised_identity, preserve_reduction
+):
+ first = {
+ "ruleId": "fixture.review",
+ "title": "Synthetic first review",
+ "summary": "Original first evidence.",
+ "identity": {"anchor": "shared-review", "instance": "first"},
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin", "candidateId": "candidate-1"},
+ }
+ sibling = {
+ **{key: value for key, value in first.items() if key != "identity"},
+ "title": "Independent review",
+ "summary": "Independent evidence remains active.",
+ }
+ if revised_identity == "anonymous":
+ first.pop("identity")
+ original, unchanged = (first, sibling) if revised_identity == "explicit" else (sibling, first)
+ revised = {**original, "title": "Revised review", "summary": "Revised evidence."}
+ rows = [first, sibling]
+ latest_rows = [revised, sibling] if revised_identity == "explicit" else [first, revised]
+ if reversed_rows:
+ rows.reverse()
+ latest_rows.reverse()
+ initial = saved_draft("identity-scan", findings=rows)
+ latest = saved_draft("identity-scan", findings=latest_rows, complete=True)
+ worker = save_worker(tmp_path, saved_results, "reviewer", [initial, latest], initial)
+ output = Path(worker["artifact_dir"])
+ # Publication stopped after selecting the reconciled checkpoint, before replacing result.json.
+ os.utime(output / "result.json", ns=(100, 100))
+ head = output / "checkpoint-head.json"
+ head.write_text(json.dumps({"checkpoint": f"{saved_results._digest(latest)}.json"}))
+ os.utime(head, ns=(300, 300))
+ if preserve_reduction:
+ write_saved_parent(tmp_path, saved_draft("identity-scan", complete=True), 2000)
+ documents = recover(tmp_path, saved_results, [worker], preserve_reduction=preserve_reduction)
+ replay = recover(
+ tmp_path,
+ saved_results,
+ [worker],
+ documents[0]["scan"]["preservedSources"],
+ preserve_reduction=preserve_reduction,
+ )
+ for result in (documents, replay):
+ findings = result[1]["findings"]
+ assert len(findings) == (3 if revised_identity == "anonymous" else 2)
+ retained = next(row for row in findings if row["title"] == revised["title"])
+ assert retained["summary"] == revised["summary"]
+ if revised_identity == "explicit":
+ assert retained["identity"] == first["identity"]
+ assert any(row["summary"] == unchanged["summary"] for row in findings)
+ if revised_identity == "anonymous":
+ assert any(row["summary"] == original["summary"] for row in findings)
+ else:
+ assert any(
+ row["summary"] == original["summary"]
+ for row in retained["provenance"]["previousFindings"]
+ )
+ assert documents[1] == replay[1]
+
+
[email protected]("identifier", ["reportId", "ledgerRowId"])
[email protected]("reversed_rows", [False, True])
[email protected]("with_independent", [False, True])
+def test_claimed_report_does_not_resolve_an_independent_recovery_match(
+ tmp_path, saved_results, identifier, reversed_rows, with_independent
+):
+ from finalize_scan_contract import _recover_unsealed_findings
+
+ first = {
+ "ruleId": "fixture.review",
+ "title": "First independent report",
+ "summary": "Synthetic evidence.",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic evidence."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete the review.",
+ "provenance": {"source": "local_plugin"},
+ "extensions": {identifier: "report-1"},
+ }
+ independent = {
+ **{key: value for key, value in first.items() if key != "extensions"},
+ "title": "Second independent report",
+ "locations": [{"path": "src/example.py", "startLine": 2}],
+ "provenance": {"source": "local_plugin", "candidateId": "candidate-2"},
+ }
+ latest = {
+ **first,
+ "title": "New report at second location",
+ "locations": independent["locations"],
+ "identity": {"anchor": "new-report"},
+ }
+ initial_rows = [first, independent] if with_independent else [first]
+ latest_rows = [first, latest]
+ if reversed_rows:
+ initial_rows.reverse()
+ latest_rows.reverse()
+ initial = saved_draft("identity-scan", findings=initial_rows)
+ terminal = saved_draft("identity-scan", findings=latest_rows, complete=True)
+ worker = save_worker(tmp_path, saved_results, "reviewer", [initial, terminal], initial)
+ output = Path(worker["artifact_dir"])
+ os.utime(output / "result.json", ns=(150, 150))
+ head = output / "checkpoint-head.json"
+ head.write_text(json.dumps({"checkpoint": f"{saved_results._digest(initial)}.json"}))
+ os.utime(head, ns=(150, 150))
+ sources = {path: path.read_bytes() for path in output.rglob("*.json")}
+ documents = recover(tmp_path, saved_results, [worker])
+ replay = recover(tmp_path, saved_results, [worker], documents[0]["scan"]["preservedSources"])
+ expected = {row["title"] for row in [*initial_rows, latest]}
+ for manifest, findings, _ in (documents, replay):
+ manifest["scan"]["id"] = "identity-scan"
+ findings["scanId"] = "identity-scan"
+ warnings = []
+ _recover_unsealed_findings(
+ manifest,
+ findings,
+ Path(__file__).resolve().parents[1] / "schemas",
+ tmp_path,
+ warnings,
+ )
+ assert {row["title"] for row in findings["findings"]} == expected
+ assert len(findings["findings"]) == len(expected)
+ assert warnings == []
+ assert documents[1] == replay[1]
+ assert all(path.read_bytes() == original for path, original in sources.items())
+
+
[email protected]("reverse_checkpoints", [False, True])
+def test_latest_eligible_worker_revision_survives_out_of_scope_result(
+ tmp_path, saved_results, monkeypatch, reverse_checkpoints
+):
+ first = {
+ "ruleId": "fixture.review",
+ "title": "Synthetic review",
+ "summary": "Older assessment 0",
+ "severity": {"level": "low"},
+ "confidence": {"level": "high", "rationale": "Synthetic fixture."},
+ "taxonomy": {"category": "other", "cwe": []},
+ "locations": [{"path": "src/example.py", "startLine": 1}],
+ "remediation": "Complete review.",
+ "provenance": {"source": "local_plugin", "candidateId": "candidate-1"},
+ "identity": {"anchor": "stable"},
+ }
+ latest = {
+ **first,
+ "summary": "Confirmed newer high severity assessment",
+ "severity": {"level": "high"},
+ }
+ excluded = {
+ **latest,
+ "summary": "Excluded revision",
+ "locations": [{"path": "unselected/example.py", "startLine": 1}],
+ }
+ worker = save_worker(
+ tmp_path,
+ saved_results,
+ "reviewer",
+ [saved_draft("identity-scan", findings=[row]) for row in (first, latest)],
+ saved_draft("identity-scan", findings=[excluded]),
+ )
+ checkpoint_paths = saved_results._checkpoint_paths
+ monkeypatch.setattr(
+ saved_results,
+ "_checkpoint_paths",
+ lambda *args: sorted(checkpoint_paths(*args), reverse=reverse_checkpoints),
+ )
+ binding = {
+ "status": "interrupted",
+ "allowedTargetKinds": ["git_revision"],
+ "target": {
+ "kind": "git_revision",
+ "targetId": "synthetic",
+ "displayName": "Synthetic",
+ "revision": "head",
+ },
+ "scope": {"includePaths": ["src"], "excludePaths": []},
+ "coverageMode": "scoped_path",
+ }
+ frozen = None
+ original = None
+ for _ in range(2):
+ warnings = []
+ documents = saved_results.merge_saved_results(
+ tmp_path,
+ "identity-scan",
+ binding,
+ [worker],
+ warnings,
+ stopped=True,
+ reason="Synthetic interruption",
+ frozen_source_digests=frozen,
+ )
+ assert documents is not None
+ findings = documents[1]["findings"]
+ assert len(findings) == 1
+ assert findings[0]["summary"] == latest["summary"]
+ assert findings[0]["severity"] == latest["severity"]
+ assert any(
+ row["summary"] == first["summary"]
+ for row in findings[0]["provenance"]["previousFindings"]
+ )
+ assert warnings == ["Skipped out-of-scope finding from reviewer/result.json."]
+ assert "completeness" not in documents[2]
+ if original is not None:
+ assert documents == original
+ original = documents
+ frozen = documents[0]["scan"]["preservedSources"]
diff --git a/plugins/codex-security/tests/test_scan_finalizer_schema_and_writeups.py b/plugins/codex-security/tests/test_scan_finalizer_schema_and_writeups.py
new file mode 100644
index 000000000..59ed56fe2
--- /dev/null
+++ b/plugins/codex-security/tests/test_scan_finalizer_schema_and_writeups.py
@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import copy
+import os
+
+import pytest
+from workbench_test_support import load_script, windows_file_backend
+
+FINALIZER = load_script("finalize_scan_contract")
+
+
[email protected](("expected", "value"), [("integer", 1), ("number", 1.5)])
+def test_schema_numeric_types_do_not_accept_booleans(expected, value) -> None:
+ schema = {"type": expected}
+ FINALIZER._validate_schema_node(value, schema, "value")
+ with pytest.raises(FINALIZER.ContractError, match="expected schema type"):
+ FINALIZER._validate_schema_node(True, schema, "value")
+
+
[email protected](os.name == "nt", reason="POSIX symlinks and file permissions")
+ "kind", ["unsafe", "symlink", "dangling-symlink", "parent-symlink", "directory", "unreadable"]
+)
+def test_missing_writeup_recovery_rejects_other_file_errors(tmp_path, kind):
+ scan_dir = tmp_path / "scan"
+ scan_dir.mkdir()
+ report = scan_dir / "findings" / "report.md"
+ report.parent.mkdir()
+ outside = tmp_path / "outside.md"
+ outside.write_text("# Outside the scan\n")
+ report_path = "findings/report.md"
+ if kind == "unsafe":
+ report_path = "../outside.md"
+ elif kind == "symlink":
+ report.symlink_to(outside)
+ elif kind == "dangling-symlink":
+ report.symlink_to(report.parent / "missing.md")
+ elif kind == "parent-symlink":
+ report.parent.rmdir()
+ report.parent.symlink_to(tmp_path, target_is_directory=True)
+ elif kind == "directory":
+ report.mkdir()
+ else:
+ if os.geteuid() == 0:
+ pytest.skip("root can read files without permission bits")
+ report.write_text("# Unreadable writeup\n")
+ report.chmod(0)
+ findings = {"findings": [{"writeup": {"reportPath": report_path}}]}
+ original = copy.deepcopy(findings)
+ with pytest.raises(FINALIZER.ContractError):
+ FINALIZER._prepare_derived_writeups(scan_dir, findings, allow_missing=True)
+ assert findings == original
+
+
[email protected]("error_code", [2, 3, 5, 22, 32, 33])
+def test_windows_writeup_recovery_only_omits_missing_files(tmp_path, monkeypatch, error_code):
+ backend = windows_file_backend()
+ windows_error = load_script("windows_scan_local_files").WindowsScanLocalFileError
+ backend.open_read_fd.side_effect = windows_error(error_code, "Synthetic Windows file error")
+ monkeypatch.setattr(FINALIZER.os, "supports_dir_fd", set())
+ monkeypatch.setattr(FINALIZER, "_is_windows", lambda: True)
+ monkeypatch.setattr(FINALIZER, "_windows_scan_local_files", lambda: backend)
+ findings = {"findings": [{"writeup": {"reportPath": "findings/report.md"}}]}
+ if error_code in {2, 3}:
+ warnings = FINALIZER._prepare_derived_writeups(tmp_path, findings, allow_missing=True)
+ assert findings == {"findings": [{}]}
+ assert len(warnings) == 1
+ else:
+ with pytest.raises(FINALIZER.ContractError):
+ FINALIZER._prepare_derived_writeups(tmp_path, findings, allow_missing=True)
+ assert "writeup" in findings["findings"][0]
+
+
+def test_schema_references_preserve_constraints_siblings_and_cycle_errors() -> None:
+ root = {"$defs": {"text": {"type": "string", "minLength": 1}}}
+ reference = {"$ref": "#/$defs/text"}
+ FINALIZER._validate_schema_node("yes", reference, "value", root)
+ with pytest.raises(FINALIZER.ContractError, match="string is too short"):
+ FINALIZER._validate_schema_node("", reference, "value", root)
+ with pytest.raises(FINALIZER.ContractError, match="string does not match schema pattern"):
+ FINALIZER._validate_schema_node("no", {**reference, "pattern": "^yes$"}, "value", root)
+ with pytest.raises(RecursionError):
+ FINALIZER._validate_schema_node("yes", {"$ref": "#"}, "value")
diff --git a/plugins/codex-security/tests/test_workbench_checkpoint_heads.py b/plugins/codex-security/tests/test_workbench_checkpoint_heads.py
index 014f294e9..397057c06 100644
--- a/plugins/codex-security/tests/test_workbench_checkpoint_heads.py
+++ b/plugins/codex-security/tests/test_workbench_checkpoint_heads.py
@@ -1134,3 +1134,97 @@ def test_older_attempt_selected_head_cannot_supersede_current_result(tmp_path):
replay = replay_saved_results(saved, first, tmp_path, scan_id, binding, workers)
for result in (first, replay):
assert result[2]["surfaces"] == [current]
+
+
[email protected]("complete", [False, True])
[email protected]("abandoned_time", [100, 200, 300])
+def test_accepted_head_survives_superseded_terminal_timestamps(
+ tmp_path: Path, complete: bool, abandoned_time: int
+) -> None:
+ scan_id = "accepted-publication"
+ write_completed_contract(
+ tmp_path, scan_id, tmp_path, target_kind="git_revision", target_revision="head"
+ )
+ manifest = json.loads((tmp_path / "scan-manifest.json").read_text())
+ binding = saved_binding("deep_repository")
+ binding["target"] = manifest["scan"]["target"]
+ findings = json.loads((tmp_path / "findings.json").read_text())["findings"]
+ findings.append(copy.deepcopy(findings[0]))
+ findings[1]["identity"]["anchor"] = "second-accepted-finding"
+ findings[1]["title"] = "Second accepted finding"
+ accepted = saved_draft(
+ scan_id,
+ complete=complete,
+ findings=findings,
+ )
+ checkpoints = tmp_path / "checkpoints"
+ raw = write_checkpoint(
+ checkpoints,
+ {
+ **accepted,
+ "publication": {"previousCheckpoint": None, "previousInputCheckpoint": None},
+ },
+ )
+ projected = {
+ **accepted,
+ "scope": binding["scope"],
+ "coverage": {
+ **accepted["coverage"],
+ "mode": "deep_repository",
+ "inventoryStrategy": "repository",
+ "includePaths": ["."],
+ "excludePaths": [],
+ },
+ }
+ head = write_checkpoint(checkpoints, projected)
+ abandoned = write_checkpoint(
+ checkpoints,
+ {
+ **saved_draft(scan_id, complete=True),
+ "publication": {"previousCheckpoint": None, "previousInputCheckpoint": None},
+ },
+ )
+ write_saved_parent(tmp_path, projected, 200)
+ manifest["scan"]["complete"] = complete
+ (tmp_path / "scan-manifest.json").write_text(json.dumps(manifest))
+ selection = tmp_path / "checkpoint-head.json"
+ selection.write_text(json.dumps({"checkpoint": head.name, "inputCheckpoint": raw.name}))
+ for file in (
+ raw,
+ head,
+ selection,
+ tmp_path / "scan-manifest.json",
+ tmp_path / "findings.json",
+ tmp_path / "coverage.json",
+ ):
+ os.utime(file, ns=(200, 200))
+ os.utime(abandoned, ns=(abandoned_time, abandoned_time))
+ original = {path: path.read_bytes() for path in (raw, head, abandoned)}
+ warnings: list[str] = []
+ result = saved.merge_saved_results(
+ tmp_path,
+ scan_id,
+ binding,
+ [],
+ warnings,
+ stopped=True,
+ reason="interrupted",
+ scan_mode="deep",
+ )
+ assert result is not None
+ assert [row["title"] for row in result[1]["findings"]] == [row["title"] for row in findings]
+ assert warnings == []
+ replay = saved.merge_saved_results(
+ tmp_path,
+ scan_id,
+ binding,
+ [],
+ warnings,
+ stopped=True,
+ reason="interrupted",
+ scan_mode="deep",
+ frozen_source_digests=result[0]["scan"]["preservedSources"],
+ )
+ assert replay[1] == result[1]
+ assert warnings == []
+ assert all(path.read_bytes() == content for path, content in original.items())
diff --git a/plugins/codex-security/tests/test_workbench_completion_binding.py b/plugins/codex-security/tests/test_workbench_completion_binding.py
index 60322e3dd..960c06ff0 100644
--- a/plugins/codex-security/tests/test_workbench_completion_binding.py
+++ b/plugins/codex-security/tests/test_workbench_completion_binding.py
@@ -1185,6 +1185,26 @@ def test_completion_rejects_malformed_finding_identity(tmp_path: Path, field: st
assert findings_path.read_bytes() == original
+def test_completion_rejects_canonical_finding_without_identity(tmp_path: Path) -> None:
+ state_dir, scan_id, scan_dir = _start_scan_with_draft_findings(tmp_path)
+ findings_path = scan_dir / "findings.json"
+ findings = json.loads(findings_path.read_text())
+ del findings["findings"][0]["identity"]
+ findings_path.write_text(json.dumps(findings))
+ original = {
+ name: (scan_dir / name).read_bytes()
+ for name in ("scan-manifest.json", "findings.json", "coverage.json", "report.md")
+ }
+
+ rejected = scan_command(state_dir, "complete-scan", scan_id, check=False)
+
+ assert rejected["returncode"] != 0
+ assert "Scan result contains invalid findings" in rejected["stderr"]
+ assert "identity" in rejected["stderr"]
+ assert get_scan(state_dir, scan_id)["scan"]["progress"]["status"] == "running"
+ assert {name: (scan_dir / name).read_bytes() for name in original} == original
+
+
def test_completion_rejects_bad_findings_and_failed_scan_preserves_valid_rows(
tmp_path: Path,
) -> None:
@@ -1198,7 +1218,7 @@ def test_completion_rejects_bad_findings_and_failed_scan_preserves_valid_rows(
unsafe_location["identity"]["anchor"] = "unsafe-location"
unsafe_location["locations"][0]["path"] = "../outside.py"
missing_identity = copy.deepcopy(valid)
- missing_identity.pop("identity")
+ missing_identity["identity"] = {}
invalid_evidence_id = copy.deepcopy(valid)
invalid_evidence_id["identity"]["anchor"] = "invalid-evidence-id"
invalid_evidence_id["codeEvidence"][0]["id"] = "src/extract.py:41"
diff --git a/plugins/codex-security/tests/test_workbench_db_exports.py b/plugins/codex-security/tests/test_workbench_db_exports.py
index 1dfa65f2e..dda92c487 100644
--- a/plugins/codex-security/tests/test_workbench_db_exports.py
+++ b/plugins/codex-security/tests/test_workbench_db_exports.py
@@ -1236,8 +1236,9 @@ def test_remediation_apply_rejects_replaced_scan_directory_ancestor(tmp_path: Pa
@pytest.mark.parametrize("interrupted", [False, True])
[email protected]("mode", ["standard", "deep"])
def test_parent_draft_preserves_reconciled_candidate_identity_before_publication(
- tmp_path: Path, monkeypatch: pytest.MonkeyPatch, interrupted: bool
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, interrupted: bool, mode: str
) -> None:
monkeypatch.syspath_prepend(str(Path(__file__).resolve().parents[1] / "scripts"))
import workbench_db as db
@@ -1247,8 +1248,14 @@ def test_parent_draft_preserves_reconciled_candidate_identity_before_publication
monkeypatch.setenv("CODEX_SECURITY_STATE_DIR", str(state_dir))
target = tmp_path / "target"
target.mkdir()
- scan_id, scan_dir = start_saved_scan(state_dir, target, tmp_path / "scans")
- write_completed_contract(scan_dir, scan_id, target)
+ workspace = create_saved_workspace(state_dir, target, mode=mode)
+ scan_id, scan_dir = start_workspace_scan(state_dir, str(workspace["id"]), tmp_path / "scans")
+ write_completed_contract(
+ scan_dir,
+ scan_id,
+ target,
+ coverage_mode="deep_repository" if mode == "deep" else "repository",
+ )
documents = {
key: json.loads((scan_dir / filename).read_text())
for key, filename in (
@@ -1257,6 +1264,8 @@ def test_parent_draft_preserves_reconciled_candidate_identity_before_publication
("coverage", "coverage.json"),
)
}
+ if mode == "deep":
+ documents["manifest"]["scan"]["complete"] = False
documents["findings"]["findings"] = []
documents["coverage"].update(surfaces=[], deferred=[])
for identity in ("review-a", "review-b"):
@@ -1312,8 +1321,21 @@ def test_parent_draft_preserves_reconciled_candidate_identity_before_publication
normalized = json.loads(normalized_bytes)
assert normalized["coverage"]["deferred"] == documents["coverage"]["deferred"]
assert normalized["scanId"] == scan_id
+ retained = raw
+ if mode == "deep":
+ retained = {
+ **raw,
+ "publication": {
+ "previousCheckpoint": None,
+ "previousInputCheckpoint": None,
+ },
+ }
+ raw_bytes = results._encoded(retained)
retained_raw = scan_dir / "checkpoints" / f"{hashlib.sha256(raw_bytes).hexdigest()}.json"
assert retained_raw.read_bytes() == raw_bytes
+ assert json.loads(raw_bytes) == retained
+ if mode == "deep":
+ assert head["inputCheckpoint"] == retained_raw.name
rejected = copy.deepcopy(documents["coverage"]["deferred"][0])
documents["coverage"]["deferred"] = documents["coverage"]["deferred"][1:]
@@ -1370,3 +1392,114 @@ def test_parent_draft_preserves_reconciled_candidate_identity_before_publication
canonical = json.loads((scan_dir / "coverage.json").read_text())
assert [row["id"] for row in canonical["deferred"]] == ["review-b"]
assert canonical["resolvedDeferred"] == raw["coverage"]["resolvedDeferred"]
+
+
[email protected]("replay_accepted", [False, True])
[email protected]("empty_interruption", [False, True])
+def test_deep_draft_admission_survives_interrupted_projection(
+ tmp_path, monkeypatch, replay_accepted, empty_interruption
+):
+ monkeypatch.syspath_prepend(str(Path(__file__).resolve().parents[1] / "scripts"))
+ import workbench_db as db
+ import workbench_saved_results as results
+
+ state_dir = tmp_path / "state"
+ monkeypatch.setenv("CODEX_SECURITY_STATE_DIR", str(state_dir))
+ target = tmp_path / "target"
+ target.mkdir()
+ workspace = create_saved_workspace(state_dir, target, mode="deep")
+ scan_id, scan_dir = start_workspace_scan(state_dir, str(workspace["id"]), tmp_path / "scans")
+ write_completed_contract(scan_dir, scan_id, target, coverage_mode="deep_repository")
+ documents = {
+ key: json.loads((scan_dir / filename).read_text())
+ for key, filename in (
+ ("manifest", "scan-manifest.json"),
+ ("findings", "findings.json"),
+ ("coverage", "coverage.json"),
+ )
+ }
+ documents["manifest"]["scan"]["complete"] = False
+ raw = {
+ "scanId": scan_id,
+ "findings": documents["findings"]["findings"],
+ "coverage": saved_coverage(),
+ }
+ drafts = scan_dir / "drafts"
+ drafts.mkdir()
+ staged = drafts / f"{uuid.uuid4()}.json"
+ raw_path = drafts / f"{uuid.uuid4()}.checkpoint.json"
+ args = SimpleNamespace(
+ scan_id=scan_id,
+ claim_token=None,
+ draft_path=str(staged),
+ checkpoint_path=str(raw_path),
+ expected_draft_digest=None,
+ )
+ with closing(db.connect()) as connection:
+ staged.write_text(json.dumps(documents))
+ raw_path.write_text(json.dumps(raw))
+ results.write_scan_draft(db._WORKBENCH_DB_CONTEXT, connection, args)
+ previous_head = json.loads((scan_dir / "checkpoint-head.json").read_text())
+ accepted_documents = copy.deepcopy(documents)
+ accepted_raw = copy.deepcopy(raw)
+ original = results.write_scan_local_bytes
+ writes = 0
+
+ def interrupt_projection(root, relative, contents):
+ nonlocal writes
+ if relative.startswith("checkpoints/"):
+ writes += 1
+ if writes == 2:
+ raise OSError("Interrupted projected checkpoint")
+ original(root, relative, contents)
+
+ if empty_interruption:
+ raw["findings"].clear()
+ else:
+ raw["findings"][0]["summary"] = "Updated synthetic evidence."
+ staged.write_text(json.dumps(documents))
+ raw_path.write_text(json.dumps(raw))
+ with monkeypatch.context() as context:
+ context.setattr(results, "write_scan_local_bytes", interrupt_projection)
+ with pytest.raises(OSError, match="Interrupted projected checkpoint"):
+ results.write_scan_draft(db._WORKBENCH_DB_CONTEXT, connection, args)
+ assert writes == 2
+ assert json.loads((scan_dir / "checkpoint-head.json").read_text()) == previous_head
+ if replay_accepted:
+ staged.write_text(json.dumps(accepted_documents))
+ raw_path.write_text(json.dumps(accepted_raw))
+ results.write_scan_draft(db._WORKBENCH_DB_CONTEXT, connection, args)
+ replay_head = json.loads((scan_dir / "checkpoint-head.json").read_text())
+ assert replay_head["inputCheckpoint"] != previous_head["inputCheckpoint"]
+ assert replay_head["checkpoint"] == previous_head["checkpoint"]
+ expected_findings = accepted_raw["findings"] if replay_accepted else raw["findings"]
+ binding = db.workbench_completion_binding(db.require_scan(connection, scan_id), db.now())
+ warnings = []
+ recovered = results.merge_saved_results(
+ scan_dir,
+ scan_id,
+ binding,
+ [],
+ warnings,
+ stopped=True,
+ reason="interrupted",
+ scan_mode="deep",
+ )
+ assert [row["summary"] for row in recovered[1]["findings"]] == [
+ row["summary"] for row in expected_findings
+ ]
+ assert warnings == []
+ replayed = results.merge_saved_results(
+ scan_dir,
+ scan_id,
+ binding,
+ [],
+ [],
+ stopped=True,
+ reason="interrupted",
+ scan_mode="deep",
+ frozen_source_digests=recovered[0]["scan"]["preservedSources"],
+ )
+ assert replayed[1:] == recovered[1:]
+ for field in ("target", "scope", "preservedSources"):
+ assert replayed[0]["scan"][field] == recovered[0]["scan"][field]
diff --git a/plugins/codex-security/tests/test_workbench_progress.py b/plugins/codex-security/tests/test_workbench_progress.py
index cb70de3ab..9970117b5 100644
--- a/plugins/codex-security/tests/test_workbench_progress.py
+++ b/plugins/codex-security/tests/test_workbench_progress.py
@@ -9,6 +9,14 @@ from workbench_test_support import (
)
+def test_usage_list_coverage_is_invalid(workbench_api):
+ from workbench_validation import _valid_measured_scan_usage
+
+ assert not _valid_measured_scan_usage(
+ {"coverage": ["complete"], "source": "codex_rollout", "threadCount": 0}
+ )
+
+
def test_validation_clears_discovery_finding_count(tmp_path: Path) -> None:
state_dir = tmp_path / "state"
target = tmp_path / "target"
diff --git a/plugins/codex-security/tests/test_workbench_saved_source_order.py b/plugins/codex-security/tests/test_workbench_saved_source_order.py
index 719f29618..e4757095a 100644
--- a/plugins/codex-security/tests/test_workbench_saved_source_order.py
+++ b/plugins/codex-security/tests/test_workbench_saved_source_order.py
@@ -21,6 +21,7 @@ from workbench_test_support import (
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
import workbench_db
import workbench_saved_results as saved
+from workbench import saved_sources
def call_workbench(monkeypatch, state, codex_home, *args):
@@ -105,7 +106,7 @@ def test_head_capture_includes_checkpoint_published_after_enumeration(
result.write_bytes(result.read_bytes())
os.utime(result, ns=(300, 300))
directory = (output / "checkpoints").relative_to(scan_dir).as_posix()
- children = saved._children
+ children = saved_sources._children
published = []
def publish_after_listing(root, relative):
@@ -117,7 +118,7 @@ def test_head_capture_includes_checkpoint_published_after_enumeration(
published.append(checkpoint)
return names
- monkeypatch.setattr(saved, "_children", publish_after_listing)
+ monkeypatch.setattr(saved_sources, "_children", publish_after_listing)
call_workbench(
monkeypatch,
state,
diff --git a/plugins/codex-security/tests/test_workbench_standard_deep_results.py b/plugins/codex-security/tests/test_workbench_standard_deep_results.py
index 1df180120..ed945717f 100644
--- a/plugins/codex-security/tests/test_workbench_standard_deep_results.py
+++ b/plugins/codex-security/tests/test_workbench_standard_deep_results.py
@@ -461,12 +461,14 @@ def test_explicit_recovery_preserves_sealed_parent_with_empty_source_map(
wrapper,
state_dir,
codex_home,
+ "from workbench import retained_coverage\n"
"original_write = workbench_saved_results.write_scan_local_bytes\n"
"def fail_parent_checkpoint(scan_dir, relative_path, payload, **kwargs):\n"
" if relative_path.startswith('checkpoints/'):\n"
" raise OSError('injected parent checkpoint failure')\n"
" return original_write(scan_dir, relative_path, payload, **kwargs)\n"
- "workbench_saved_results.write_scan_local_bytes = fail_parent_checkpoint\n",
+ "workbench_saved_results.write_scan_local_bytes = fail_parent_checkpoint\n"
+ "retained_coverage.write_scan_local_bytes = fail_parent_checkpoint\n",
"recover-scan-results",
"--scan-id",
scan_id,
@@ -3256,6 +3258,9 @@ def test_equal_time_parent_and_head_preserve_pending_on_replay(
assert other in first[2]["deferred"] and other in replay[2]["deferred"]
assert not replay[2].get("resolvedDeferred")
+ assert replay[1:] == first[1:]
+ assert replay[0]["scan"].get("complete") == first[0]["scan"].get("complete")
+ assert replay[0]["scan"]["preservedSources"] == first[0]["scan"]["preservedSources"]
@pytest.mark.parametrize("stopped", [False, True])
diff --git a/sdk/typescript/src/contract.ts b/sdk/typescript/src/contract.ts
index 9ff3c0ecf..6cb9125c8 100644
--- a/sdk/typescript/src/contract.ts
+++ b/sdk/typescript/src/contract.ts
@@ -208,12 +208,45 @@ function validateCanonicalContract(
findings: FindingsDocument,
coverage: CoverageDocument,
): void {
+ const requireText = (values: Record<string, string | undefined>) => {
+ for (const [context, value] of Object.entries(values)) {
+ if (value !== undefined && !hasRequiredFindingText(value))
+ throw new ContractValidationError(
+ `${context}: expected a non-empty string.`,
+ );
+ }
+ };
+ requireText({
+ "manifest.scan.id": manifest.scan.id,
+ "scan.target.targetId": manifest.scan.target.targetId,
+ "scan.target.displayName": manifest.scan.target.displayName,
+ "scan.target.revision":
+ manifest.scan.target.kind === "git_revision"
+ ? manifest.scan.target.revision
+ : undefined,
+ "scan.target.snapshotDigest":
+ manifest.scan.target.kind !== "git_revision"
+ ? manifest.scan.target.snapshotDigest
+ : undefined,
+ "manifest.scan.producer.name": manifest.scan.producer.name,
+ "manifest.scan.producer.version": manifest.scan.producer.version,
+ "coverage.inventoryStrategy": coverage.inventoryStrategy,
+ });
+ for (const [index, surface] of coverage.surfaces.entries())
+ requireText({
+ [`coverage.surfaces[${index}].id`]: surface.id,
+ [`coverage.surfaces[${index}].label`]: surface.label,
+ });
const remote = manifest.scan.target.remote;
if (remote !== undefined) {
const authority = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/([^/?#]+)/.exec(
remote,
)?.[1];
- if (remote.includes("\\") || authority === undefined) {
+ if (
+ remote.includes("\\") ||
+ /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(remote) ||
+ authority === undefined
+ ) {
throw new ContractValidationError(
"scan.target.remote: expected a sanitized canonical absolute URL.",
);
@@ -276,30 +309,26 @@ function validateCanonicalContract(
}
}
- const findingIds = new Set<string>();
+ const occurrenceIds = new Set<string>();
for (const [findingIndex, finding] of findings.findings.entries()) {
const context = `findings.findings[${findingIndex}]`;
- if (findingIds.has(finding.findingId)) {
- throw new ContractValidationError(`${context}: duplicate finding id.`);
- }
- findingIds.add(finding.findingId);
- for (const [field, value] of [
- ["title", finding.title],
- ["summary", finding.summary],
- ["remediation", finding.remediation],
- ["confidence.rationale", finding.confidence.rationale],
- ["taxonomy.category", finding.taxonomy.category],
- ["provenance.source", finding.provenance.source],
- ...(finding.severity.score === undefined
- ? []
- : [["severity.scoringSystem", finding.severity.scoringSystem]]),
- ]) {
- if (!hasRequiredFindingText(value ?? "")) {
- throw new ContractValidationError(
- `${context}.${field}: expected a non-empty string.`,
- );
- }
- }
+ requireText({
+ [`${context}.title`]: finding.title,
+ [`${context}.summary`]: finding.summary,
+ [`${context}.remediation`]: finding.remediation,
+ [`${context}.confidence.rationale`]: finding.confidence.rationale,
+ [`${context}.severity.scoringSystem`]:
+ finding.severity.score === undefined
+ ? undefined
+ : (finding.severity.scoringSystem ?? ""),
+ [`${context}.taxonomy.category`]: finding.taxonomy.category,
+ [`${context}.provenance.source`]: finding.provenance.source,
+ });
+ if (occurrenceIds.has(finding.occurrenceId))
+ throw new ContractValidationError(
+ `${context}: duplicate finding occurrence identity; use identity.instance to split siblings.`,
+ );
+ occurrenceIds.add(finding.occurrenceId);
for (const [locationIndex, location] of finding.locations.entries()) {
const locationContext = `${context}.locations[${locationIndex}]`;
try {
diff --git a/sdk/typescript/src/custom-validation.ts b/sdk/typescript/src/custom-validation.ts
index dd2eda111..d4a1797c0 100644
--- a/sdk/typescript/src/custom-validation.ts
+++ b/sdk/typescript/src/custom-validation.ts
@@ -211,8 +211,12 @@ export async function runCustomValidation(options: {
];
if (
manifest.scan?.scope?.validationMode !== "custom_pending" ||
- manifest.scan.sealedAt !== undefined ||
- manifest.scan.artifacts !== undefined ||
+ manifest.scan.sealedAt != null ||
+ (manifest.scan.artifacts != null &&
+ !(
+ Array.isArray(manifest.scan.artifacts) &&
+ manifest.scan.artifacts.length === 0
+ )) ||
manifest.scan.id !== scanId ||
findingsDocument.scanId !== scanId ||
coverage.scanId !== scanId
diff --git a/sdk/typescript/tests-ts/api-audit-admission.test.ts b/sdk/typescript/tests-ts/api-audit-admission.test.ts
index d25ba02a2..0db0cabab 100644
--- a/sdk/typescript/tests-ts/api-audit-admission.test.ts
+++ b/sdk/typescript/tests-ts/api-audit-admission.test.ts
@@ -35,6 +35,7 @@ const {
createDeepScanArtifacts,
recordCodexSecurityScanDraftViaWorkbench,
parseCanonicalScanDraft,
+ parseScanDraft,
validateDiscoveryArtifacts,
DeepScanWorkerRunner,
} = await import(pathToFileURL(bundlePath).href);
@@ -54,6 +55,7 @@ type Mutation =
| "inverted-lines"
| "wrong-scan"
| "legacy-details"
+ | "legacy-evidence"
| "legacy-surface";
const cases: {
name: string;
@@ -61,6 +63,7 @@ const cases: {
complete?: boolean;
mutation?: Mutation;
accepted: boolean;
+ canonicalAccepted?: boolean;
}[] = [
{ name: "scope notes", complete: true, accepted: true },
{
@@ -75,7 +78,18 @@ const cases: {
mutation: "legacy-details",
accepted: false,
},
- { name: "legacy surface ID", mutation: "legacy-surface", accepted: false },
+ {
+ name: "legacy evidence coordinates",
+ mutation: "legacy-evidence",
+ accepted: false,
+ canonicalAccepted: true,
+ },
+ {
+ name: "legacy surface ID",
+ mutation: "legacy-surface",
+ accepted: false,
+ canonicalAccepted: true,
+ },
{ name: "unfinished checkpoint", complete: false, accepted: false },
{ name: "missing findings", mutation: "missing-findings", accepted: false },
{
@@ -172,6 +186,10 @@ for (const scenario of cases) {
},
);
const submitted = mutateDraft(semantic, scenario.mutation);
+ if (scenario.mutation === "legacy-evidence") {
+ expect(() => parseScanDraft(semantic)).not.toThrow();
+ expect(() => parseScanDraft(submitted)).toThrow(/code_evidence/);
+ }
const findings = {
scanId: submitted.scanId,
findings: submitted.findings?.map((finding) => ({
@@ -245,9 +263,15 @@ for (const scenario of cases) {
"discovery-1",
);
expect(executions).toBe(1);
- if (scenario.accepted) {
+ if (scenario.canonicalAccepted ?? scenario.accepted) {
expect(standard.error).toBe(standard.finalization);
expect(standard.finalizations).toBe(1);
+ } else {
+ expect(standard.error).toBeInstanceOf(Error);
+ expect(standard.error).not.toBe(standard.finalization);
+ expect(standard.finalizations).toBe(0);
+ }
+ if (scenario.accepted) {
expect(deepResult.status).toBe("succeeded");
expect(acceptedPaths).toEqual([deepResult.worker.resultPath]);
const deepDraft: DraftFixture = await validateDiscoveryArtifacts(
@@ -268,9 +292,6 @@ for (const scenario of cases) {
expect(deepDraft.scope).toEqual(canonicalDraft.scope);
expect(deepDraft.threatModel).toEqual(canonicalDraft.threatModel);
} else {
- expect(standard.error).toBeInstanceOf(Error);
- expect(standard.error).not.toBe(standard.finalization);
- expect(standard.finalizations).toBe(0);
expect(deepResult.status).toBe("failed");
expect(acceptedPaths).toHaveLength(0);
}
@@ -316,7 +337,7 @@ test.each(["scan-manifest.json", "findings.json", "coverage.json"])(
},
);
-test("sealed legacy evidence stays readable but is not admitted as a new draft", async () => {
+test("sealed legacy evidence stays readable during canonical admission", async () => {
const scanDir = await copyCompletedScan(await temporaryDirectory());
const file = join(scanDir, "findings.json");
const findings = JSON.parse(await readFile(file, "utf8"));
@@ -354,14 +375,13 @@ test("sealed legacy evidence stays readable but is not admitted as a new draft",
const coverage = JSON.parse(
await readFile(join(scanDir, "coverage.json"), "utf8"),
);
- expect(() =>
- parseCanonicalScanDraft({
- scanId: manifest.scan.id,
- manifest,
- findings,
- coverage,
- }),
- ).toThrow();
+ const canonical = parseCanonicalScanDraft({
+ scanId: manifest.scan.id,
+ manifest,
+ findings,
+ coverage,
+ });
+ expect(canonical.findings[0]?.code_evidence).toEqual([evidence]);
});
test("canonical admission still rejects reversed typed evidence bounds", async () => {
@@ -444,6 +464,16 @@ function mutateDraft(input: DraftFixture, mutation?: Mutation): DraftFixture {
if (mutation === "legacy-surface")
(draft.coverage["surfaces"] as Record<string, unknown>[])[0]!["id"] =
"HTTP API";
+ if (mutation === "legacy-evidence")
+ draft.findings[0]!["code_evidence"] = [
+ {
+ id: "legacy-reversed-end",
+ code: "read(input)",
+ path: "src/legacy.py",
+ startLine: 48,
+ endLine: 47,
+ },
+ ];
if (mutation === "legacy-details")
draft.findings[0]!["validation"] = {
method: null,
diff --git a/sdk/typescript/tests-ts/compact-diff-scan.test.ts b/sdk/typescript/tests-ts/compact-diff-scan.test.ts
index ecd290131..44248a083 100644
--- a/sdk/typescript/tests-ts/compact-diff-scan.test.ts
+++ b/sdk/typescript/tests-ts/compact-diff-scan.test.ts
@@ -602,7 +602,7 @@ describe("compact diff scan", () => {
).findings.map((draftFinding) => draftFinding["identity"]),
).toEqual([
{ anchor: "candidate-duplicate-instance", instance: "dss-147-a" },
- { anchor: "candidate-duplicate-instance", instance: "dss-147-a" },
+ { anchor: "candidate-duplicate-instance", instance: "dss-147-a-2" },
]);
await call("record_codex_security_scan_draft", {
scanId,
@@ -729,7 +729,7 @@ describe("compact diff scan", () => {
instance: "dss-147-b",
},
{ anchor: "candidate-authored-instance", instance: "ledger-row-c" },
- { anchor: "candidate-duplicate-instance", instance: "dss-147-a" },
+ { anchor: "candidate-duplicate-instance", instance: "dss-147-a-2" },
]);
expect(
((completed["manifest"] as JsonObject)["scan"] as JsonObject)[
diff --git a/sdk/typescript/tests-ts/contract.test.ts b/sdk/typescript/tests-ts/contract.test.ts
index 5c1f26b7b..f8a33720b 100644
--- a/sdk/typescript/tests-ts/contract.test.ts
+++ b/sdk/typescript/tests-ts/contract.test.ts
@@ -79,6 +79,78 @@ function expectation(
}
describe("canonical scan contract", () => {
+ test.each(["report.md", "report.html", "exports/results.sarif"])(
+ "re-finalizing an imported bundle preserves sealed %s",
+ async (projection) => {
+ const scanDir = await copyExample();
+ const destination = join(scanDir, projection);
+ const content = "Synthetic externally sealed projection.\n";
+ await mkdir(dirname(destination), { recursive: true });
+ await writeFile(destination, content);
+ const manifestPath = join(scanDir, "scan-manifest.json");
+ const manifest = await readJson(manifestPath);
+ manifest["scan"].artifacts.push({
+ path: projection,
+ sha256: sha256(content),
+ mediaType: "text/plain",
+ });
+ await writeJson(manifestPath, manifest);
+ await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
+ const result = runPython(
+ process.env["PYTHON"] ?? Bun.which("python3") ?? "python",
+ [
+ join(PLUGIN_ROOT, "scripts", "finalize_scan_contract.py"),
+ "--scan-dir",
+ scanDir,
+ ],
+ );
+ expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
+ expect(await readFile(destination, "utf8")).toBe(content);
+ await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
+ },
+ );
+
+ test.each([
+ "duplicate finding",
+ "blank title",
+ "inverted range",
+ "backslash remote",
+ ])("both readers reject %s in a sealed contract", async (variant) => {
+ const scanDir = await copyExample();
+ const findingsPath = join(scanDir, "findings.json");
+ const findings = await readJson(findingsPath);
+ const manifestPath = join(scanDir, "scan-manifest.json");
+ const manifest = await readJson(manifestPath);
+ if (variant === "duplicate finding")
+ findings["findings"].push(structuredClone(findings["findings"][0]));
+ if (variant === "blank title") findings["findings"][0].title = " ";
+ if (variant === "inverted range")
+ Object.assign(findings["findings"][0].locations[0], {
+ startLine: 10,
+ endLine: 2,
+ });
+ if (variant === "backslash remote")
+ manifest["scan"].target.remote = "https://example.com/repository\\path";
+ await writeJson(findingsPath, findings);
+ await writeJson(manifestPath, manifest);
+ await reseal(scanDir);
+ const result = runPython(
+ process.env["PYTHON"] ?? Bun.which("python3") ?? "python",
+ [
+ "-c",
+ "import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); from finalize_scan_contract import _prepare_scan_finalization; _prepare_scan_finalization(Path(sys.argv[2]))",
+ join(PLUGIN_ROOT, "scripts"),
+ scanDir,
+ ],
+ );
+ expect(result.exitCode, new TextDecoder().decode(result.stderr)).not.toBe(
+ 0,
+ );
+ await expect(
+ loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
+ ).rejects.toBeInstanceOf(ContractValidationError);
+ });
+
test("rejects byte changes to any sealed binary artifact", async () => {
const scanDir = await copyExample();
const artifactPath = join(scanDir, "artifacts", "synthetic.bin");
@@ -517,6 +589,10 @@ describe("canonical scan contract", () => {
findings["findings"][0]["validation"] = legacyValidation;
findings["findings"][0]["attackPath"] = legacyAttackPath;
findings["findings"][0]["root_cause"] = null;
+ findings["findings"][0]["rootCause"] = {
+ summary: "Synthetic legacy details.",
+ evidenceRefs: [null, "evidence/source.md", 2],
+ };
findings["findings"][0]["code_evidence"] = [
{ id: "legacy-source", code: "legacy_source()" },
];
@@ -536,6 +612,10 @@ describe("canonical scan contract", () => {
).toEqual(["THE MITIGATION WAS CHECKED."]);
expect(loadedFinding?.attackPath?.steps).toBeUndefined();
expect(loadedFinding?.root_cause).toBeNull();
+ expect(loadedFinding?.rootCause).toEqual({
+ summary: "Synthetic legacy details.",
+ evidenceRefs: ["evidence/source.md"],
+ });
expect(await readJson(findingsPath)).toEqual(findings);
});
@@ -553,6 +633,28 @@ describe("canonical scan contract", () => {
expect(await readJson(findingsPath)).toEqual(findings);
});
+ test.each(["directory_snapshot", "git_worktree", "git_diff"])(
+ "both readers accept an empty unused revision for %s",
+ async (kind) => {
+ const scanDir = await copyExample();
+ const manifestPath = join(scanDir, "scan-manifest.json");
+ const manifest = await readJson(manifestPath);
+ manifest["scan"]["target"]["kind"] = kind;
+ manifest["scan"]["target"]["revision"] = "";
+ await writeJson(manifestPath, manifest);
+ const result = runPython(
+ process.env["PYTHON"] ?? Bun.which("python3") ?? "python",
+ [
+ join(PLUGIN_ROOT, "scripts", "finalize_scan_contract.py"),
+ "--scan-dir",
+ scanDir,
+ ],
+ );
+ expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
+ await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
+ },
+ );
+
test.each(["rootCause", "root_cause"])(
"reads legacy %s evidence references in both readers without rewriting the seal",
async (section) => {
@@ -603,6 +705,7 @@ describe("canonical scan contract", () => {
["taxonomy.category", " \t\n", false],
["provenance.source", " \t\n", false],
["severity.scoringSystem", " \t\n", false],
+ ["severity.scoringSystem", undefined, false],
["title", "\u0085\u001c", false],
["title", "\ufeff", true],
["title", " Synthetic required text. \n", true],
@@ -657,18 +760,32 @@ describe("canonical scan contract", () => {
},
);
- test("rejects noncanonical remote backslashes in both readers", async () => {
- const scanDir = await copyExample();
- const manifestPath = join(scanDir, "scan-manifest.json");
- const manifest = await readJson(manifestPath);
- manifest["scan"]["target"]["remote"] =
- "https://example.test/synthetic/repo\\name";
- await writeJson(manifestPath, manifest);
- expect(pythonExport(scanDir).exitCode).not.toBe(0);
- await expect(
- loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
- ).rejects.toThrow("canonical absolute URL");
- });
+ test.each([
+ "\\",
+ "\t",
+ "\n",
+ "\r",
+ "\u0000",
+ "\u001b",
+ "\u007f",
+ "\u0085",
+ "\u2028",
+ "\u2029",
+ ])(
+ "rejects noncanonical remote character %j in both readers",
+ async (character) => {
+ const scanDir = await copyExample();
+ const manifestPath = join(scanDir, "scan-manifest.json");
+ const manifest = await readJson(manifestPath);
+ manifest["scan"]["target"]["remote"] =
+ `https://example.test/synthetic/repo${character}name`;
+ await writeJson(manifestPath, manifest);
+ expect(pythonExport(scanDir).exitCode).not.toBe(0);
+ await expect(
+ loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
+ ).rejects.toThrow("canonical absolute URL");
+ },
+ );
test("loads an empty legacy root cause without changing the artifact", async () => {
const scanDir = await copyExample();
diff --git a/sdk/typescript/tests-ts/custom-validation.test.ts b/sdk/typescript/tests-ts/custom-validation.test.ts
index 050c691eb..afda2efae 100644
--- a/sdk/typescript/tests-ts/custom-validation.test.ts
+++ b/sdk/typescript/tests-ts/custom-validation.test.ts
@@ -559,6 +559,30 @@ describe("custom validation", () => {
});
});
+ test.each([{ artifacts: [] }, { artifacts: null }])(
+ "validates an unfinished draft with %j",
+ async ({ artifacts }) => {
+ const f = await fixture();
+ const manifest = await json<{ scan: Record<string, unknown> }>(
+ join(f.scanDir, "scan-manifest.json"),
+ );
+ manifest.scan["artifacts"] = artifacts;
+ manifest.scan["sealedAt"] = null;
+ await save(join(f.scanDir, "scan-manifest.json"), manifest);
+ const run = mock(async () => JSON.stringify(result("reportable")));
+ await runCustomValidation({ ...f, run });
+ expect(run).toHaveBeenCalledTimes(1);
+ const findings = await json<FindingsDocument>(
+ join(f.scanDir, "findings.json"),
+ );
+ expect(findings.findings).toHaveLength(1);
+ expect(findings.findings[0]).toMatchObject({
+ identity: f.findings.findings[0]!.identity,
+ validation: { disposition: "reportable" },
+ });
+ },
+ );
+
test.each([
"sealedAt",
"artifacts",
@@ -571,7 +595,14 @@ describe("custom validation", () => {
join(f.scanDir, "scan-manifest.json"),
);
if (kind === "sealedAt") manifest.scan.sealedAt = "2026-01-01T00:00:00Z";
- if (kind === "artifacts") manifest.scan.artifacts = [];
+ if (kind === "artifacts")
+ manifest.scan.artifacts = [
+ {
+ path: "findings.json",
+ sha256: "0".repeat(64),
+ mediaType: "application/json",
+ },
+ ];
if (kind === "manifest ID") manifest.scan.id = randomUUID();
if (kind === "findings ID" || kind === "coverage ID") {
const name = kind === "findings ID" ? "findings.json" : "coverage.json";
diff --git a/sdk/typescript/tests-ts/runtime.test.ts b/sdk/typescript/tests-ts/runtime.test.ts
index aa4b2399f..14db57e51 100644
--- a/sdk/typescript/tests-ts/runtime.test.ts
+++ b/sdk/typescript/tests-ts/runtime.test.ts
@@ -366,10 +366,20 @@ describe("plugin runtime preparation", () => {
/function buildFindings\(findings, mode\) \{[\s\S]*?\n\}/u.exec(
runtime,
)?.[0];
+ const candidateSource =
+ /function findingIdentityCandidate\(finding\) \{[\s\S]*?\n\}/u.exec(
+ runtime,
+ )?.[0];
+ const identitySource =
+ /function scanFindingIdentity\(finding\) \{[\s\S]*?\n\}/u.exec(
+ runtime,
+ )?.[0];
expect(source).toBeDefined();
+ expect(candidateSource).toBeDefined();
+ expect(identitySource).toBeDefined();
const buildFindings = new Function(
"semanticIdentifier",
- `${source}\nreturn buildFindings;`,
+ `${candidateSource}\n${identitySource}\n${source}\nreturn buildFindings;`,
)((value: string, fallback: string) => value || fallback) as (
findings: Array<{
title: string;
diff --git a/sdk/typescript/tests-ts/scan-resume.test.ts b/sdk/typescript/tests-ts/scan-resume.test.ts
index b1acbc7fa..f5ea9558f 100644
--- a/sdk/typescript/tests-ts/scan-resume.test.ts
+++ b/sdk/typescript/tests-ts/scan-resume.test.ts
@@ -1423,3 +1423,50 @@ test("resume requires an explicit scan ID", async () => {
expect(code).toBe(2);
expect(stderr.text()).toContain("scanId");
});
+
+test.each([false, true])(
+ "unfinished empty artifact list does not pin producer on resume (empty=%p)",
+ async (empty) => {
+ const f = await interruptedScan("deep");
+ await finishDiscovery(f);
+ const manifestPath = join(f.scanDir, "scan-manifest.json");
+ const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+ delete manifest.scan.sealedAt;
+ manifest.scan.producer.version = f.recipe.pluginVersion;
+ if (empty) manifest.scan.artifacts = [];
+ else delete manifest.scan.artifacts;
+ await writeFile(manifestPath, JSON.stringify(manifest));
+ const resume = await f.command([
+ "get-cli-scan-resume",
+ "--scan-id",
+ f.scanId,
+ ]);
+ expect(resume["sealedProducerVersion"]).toBeUndefined();
+ const { stderr, runCli } = createCliTest(main);
+ const code = await runCli(
+ ["scans", "resume", f.scanId, "--json"],
+ resumeDependencies(f, () => ({
+ startThread: () => fail("Unexpected new session"),
+ resumeThread(threadId) {
+ expect(threadId).toBe(f.threadId);
+ return {
+ id: threadId,
+ async runStreamed() {
+ return { events: completedEvents(threadId) };
+ },
+ };
+ },
+ })),
+ );
+ expect(code, stderr.text()).toBe(0);
+ expect(
+ (await f.command(["get-scan", "--scan-id", f.scanId]))["scan"],
+ ).toMatchObject({ progress: { status: "complete" } });
+ const sealed = JSON.parse(await readFile(manifestPath, "utf8"));
+ const plugin = JSON.parse(
+ await readFile(join(PLUGIN_ROOT, ".codex-plugin/plugin.json"), "utf8"),
+ );
+ expect(sealed.scan.producer.version).toBe(plugin.version);
+ expect(sealed.scan.artifacts.length).toBeGreaterThan(0);
+ },
+);
diff --git a/sdk/typescript/tests-ts/stopped-scan-results.test.ts b/sdk/typescript/tests-ts/stopped-scan-results.test.ts
index d88a841e9..a1ae586b4 100644
--- a/sdk/typescript/tests-ts/stopped-scan-results.test.ts
+++ b/sdk/typescript/tests-ts/stopped-scan-results.test.ts
@@ -48,13 +48,20 @@ const stoppedScanProbe = [
" checkpoint = {**payload, 'complete': False}",
" checkpoint_dir = artifact_dir / 'checkpoints'",
" checkpoint_dir.mkdir()",
- " if source == 'refined-checkpoint':",
+ " if source.startswith('refined-checkpoint'):",
" earlier = json.loads(json.dumps(checkpoint))",
" earlier['findings'][0]['locations'][0].update({'startLine': 21, 'endLine': 26})",
" later = json.loads(json.dumps(checkpoint))",
" later['findings'][0]['locations'][0].update({'startLine': 24, 'endLine': 26})",
" for document in (earlier, later):",
" encoded = json.dumps(document).encode()",
+ " if document is earlier:",
+ " earlier_digest = hashlib.sha256(encoded).hexdigest()",
+ " else:",
+ " # JSON whitespace controls hash order without changing either checkpoint.",
+ " earlier_first = source.endswith('earlier-first')",
+ " while (earlier_digest < hashlib.sha256(encoded).hexdigest()) != earlier_first:",
+ " encoded += b'\\n'",
" (checkpoint_dir / f'{hashlib.sha256(encoded).hexdigest()}.json').write_bytes(encoded)",
" result_path.write_text(json.dumps(later), encoding='utf-8')",
" else:",
@@ -140,7 +147,7 @@ const stoppedScanProbe = [
"findings = json.loads(findings_path.read_text(encoding='utf-8'))['findings'] if findings_path.exists() else []",
"if source == 'late-checkpoint':",
" print(json.dumps({'findingCount': stored['findingCount'], 'artifactFindingCount': len(findings), 'manifestUnchanged': manifest_before == (scan_dir / 'scan-manifest.json').read_bytes(), 'findingsUnchanged': findings_before == (scan_dir / 'findings.json').read_bytes()}))",
- "elif source == 'refined-checkpoint':",
+ "elif source.startswith('refined-checkpoint'):",
" histories = [item for finding in findings for item in finding.get('provenance', {}).get('previousFindings', [])]",
" print(json.dumps({'findingCount': stored['findingCount'], 'progressStatus': stored['progress']['status'], 'artifactFindingCount': len(findings), 'historyCount': len(histories), 'representedStartLines': sorted([finding['locations'][0]['startLine'] for finding in findings] + [finding['locations'][0]['startLine'] for finding in histories])}))",
"elif source == 'distinct-instances':",
@@ -185,19 +192,23 @@ test.each(["accepted", "checkpoint"] as const)(
30_000,
);
-test("keeps refined checkpoints as one finding with retained history", () => {
- const recovered = runStoppedScanProbe(
- "refined-checkpoint",
- "codex-security-refined-checkpoint-",
- );
- expect(recovered).toEqual({
- findingCount: 1,
- progressStatus: "failed",
- artifactFindingCount: 1,
- historyCount: 1,
- representedStartLines: [21, 24],
- });
-}, 30_000);
+test.each(["earlier-first", "later-first"] as const)(
+ "keeps refined checkpoints as one finding with retained history (%s)",
+ (order) => {
+ const recovered = runStoppedScanProbe(
+ `refined-checkpoint-${order}`,
+ "codex-security-refined-checkpoint-",
+ );
+ expect(recovered).toEqual({
+ findingCount: 1,
+ progressStatus: "failed",
+ artifactFindingCount: 1,
+ historyCount: 1,
+ representedStartLines: [21, 24],
+ });
+ },
+ 30_000,
+);
test.each(["failed", "interrupted"] as const)(
"keeps the first %s seal immutable when a worker writes late",