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

feat(dedupe): attribute records reviews to participating observations (#1145)

Kyle Brown9329e47098ff
diff --git a/sdk/typescript/docs/dedupe-records.md b/sdk/typescript/docs/dedupe-records.md
index f7fd5de12..c04778475 100644
--- a/sdk/typescript/docs/dedupe-records.md
+++ b/sdk/typescript/docs/dedupe-records.md
@@ -95,6 +95,11 @@ The CLI sends one review at a time:
"method": "review.run",
"params": {
"requestId": "<same review UUID>",
+ "attribution": {
+ "version": 1,
+ "beneficiaryObservationIds": ["observation-1"],
+ "contextObservationIds": ["observation-2"]
+ },
"stage": "screening",
"model": "gpt-5.6-luna",
"effort": "xhigh",
@@ -106,6 +111,25 @@ The CLI sends one review at a time:
}
```
+Every records review includes `attribution.version: 1`. The two ID arrays name
+the exact original host observations participating in that screening or pair
+review, using the structured assignment rather than the prompt or final groups.
+`beneficiaryObservationIds` contains participants that have an anchor entry in
+this invocation's `candidateRelationships`; `contextObservationIds` contains
+the remaining participants. Both arrays are sorted, distinct, and disjoint,
+and beneficiaries are nonempty. Candidate-only observations never become
+beneficiaries, even when selected as the final representative. An incoming
+observation participating in several reviews appears in each review's metadata.
+
+This is additive metadata: JSON-RPC remains 2.0 and input/result versions remain 1.
+Older hosts may ignore it; hosts that require attribution must validate it
+and reject missing or unknown identities before executing a review. Persist the
+request UUID and attribution before provisioning remote execution. The host owns
+accounting and any partitioning of invocation anchors by origin scan; the CLI
+preserves the supplied batch and does not assign costs or infer scan ownership.
+The `model` field remains the configured review model. A new invocation produces
+new request UUIDs; this metadata does not introduce cross-invocation replay.
+
`stage` is `screening` or `pair-review`. Screening uses `gpt-5.6-luna`/`xhigh`;
independent pair validation uses `gpt-5.6-sol`/`high`. Execute each request in a
fresh review context: pair reviews must not inherit screening answers or prior
diff --git a/sdk/typescript/src/deduplication/codex-review.ts b/sdk/typescript/src/deduplication/codex-review.ts
index 4ba30f9aa..719877893 100644
--- a/sdk/typescript/src/deduplication/codex-review.ts
+++ b/sdk/typescript/src/deduplication/codex-review.ts
@@ -50,6 +50,8 @@ export interface CodexReview<T> extends Pick<
DeduplicationReviewRequest,
"stage" | "model" | "effort" | "prompt" | "schema"
> {
+ /** Exact comparison participants, supplied by the structured reviewer. */
+ findingIds?: readonly string[];
validate(value: unknown): T;
}
diff --git a/sdk/typescript/src/deduplication/deduplication-reviewer.ts b/sdk/typescript/src/deduplication/deduplication-reviewer.ts
index df1af9055..62b3a04a9 100644
--- a/sdk/typescript/src/deduplication/deduplication-reviewer.ts
+++ b/sdk/typescript/src/deduplication/deduplication-reviewer.ts
@@ -130,6 +130,7 @@ export class CodexDeduplicationReviewer implements DeduplicationReviewer {
async screen(findings: readonly Finding[]): Promise<ScreeningResult> {
return await this.runner.run({
stage: "screening",
+ findingIds: findings.map((finding) => finding.findingId),
model: "gpt-5.6-luna",
effort: "xhigh",
prompt: screeningPrompt(findings),
@@ -141,6 +142,7 @@ export class CodexDeduplicationReviewer implements DeduplicationReviewer {
async reviewPair(findings: readonly Finding[]): Promise<DuplicateDecision> {
return await this.runner.run({
stage: "pair-review",
+ findingIds: findings.map((finding) => finding.findingId),
model: "gpt-5.6-sol",
effort: "high",
prompt: pairReviewPrompt(findings),
diff --git a/sdk/typescript/src/deduplication/records.ts b/sdk/typescript/src/deduplication/records.ts
index 5a5d86b7d..a45cd1f38 100644
--- a/sdk/typescript/src/deduplication/records.ts
+++ b/sdk/typescript/src/deduplication/records.ts
@@ -14,7 +14,39 @@ import {
screeningFindingFormatInstructions,
pairFindingFormatInstructions,
} from "./deduplication-prompts.js";
-import type { DeduplicationReviewRunner } from "./review.js";
+import type {
+ DeduplicationReviewAttribution,
+ DeduplicationReviewRunner,
+} from "./review.js";
+
+export function recordsReviewAttribution(
+ findingIds: readonly string[] | undefined,
+ references: ReadonlyMap<string, string>,
+ anchors: ReadonlyMap<string, readonly string[]>,
+): DeduplicationReviewAttribution {
+ if (!findingIds?.length)
+ throw new Error("Records review is missing its comparison participants.");
+ const participants = new Set(
+ findingIds.map((findingId) => {
+ const observationId = references.get(findingId);
+ if (observationId === undefined)
+ throw new Error(`Unknown records review finding ID: ${findingId}`);
+ return observationId;
+ }),
+ );
+ const beneficiaryObservationIds = [...participants]
+ .filter((id) => anchors.has(id))
+ .sort();
+ if (beneficiaryObservationIds.length === 0)
+ throw new Error("Records review has no incoming observation participants.");
+ return {
+ version: 1,
+ beneficiaryObservationIds,
+ contextObservationIds: [...participants]
+ .filter((id) => !anchors.has(id))
+ .sort(),
+ };
+}
const id = z.string().min(1);
const record = z
@@ -117,7 +149,11 @@ export async function deduplicateRecords(
observations.get(id)!,
);
const reviewer = new CodexDeduplicationReviewer({
- async run<T>({ validate, ...review }: CodexReview<T>): Promise<T> {
+ async run<T>({
+ validate,
+ findingIds,
+ ...review
+ }: CodexReview<T>): Promise<T> {
try {
return await abortable(async () => {
options.signal?.throwIfAborted();
@@ -126,6 +162,11 @@ export async function deduplicateRecords(
{
...review,
requestId: randomUUID(),
+ attribution: recordsReviewAttribution(
+ findingIds,
+ references,
+ relationships,
+ ),
trustedInstructions: [
sourceReviewInstructions,
review.stage === "screening"
diff --git a/sdk/typescript/src/deduplication/review.ts b/sdk/typescript/src/deduplication/review.ts
index c2bd66240..25d21be22 100644
--- a/sdk/typescript/src/deduplication/review.ts
+++ b/sdk/typescript/src/deduplication/review.ts
@@ -1,8 +1,16 @@
import type { DeduplicationReviewStage } from "../errors.js";
+export interface DeduplicationReviewAttribution {
+ version: 1;
+ beneficiaryObservationIds: string[];
+ contextObservationIds: string[];
+}
+
/** Serializable review contract shared by local and host-provided execution. */
export interface DeduplicationReviewRequest {
requestId: string;
+ /** Present in records mode; IDs identify this review's host observations. */
+ attribution?: DeduplicationReviewAttribution;
stage: DeduplicationReviewStage;
model: string;
effort: string;
diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts
index 13a01255e..982ea0c60 100644
--- a/sdk/typescript/src/index.ts
+++ b/sdk/typescript/src/index.ts
@@ -137,6 +137,7 @@ export type {
} from "./deduplication/records.js";
export type {
DeduplicationReviewRequest,
+ DeduplicationReviewAttribution,
DeduplicationReviewRunner,
} from "./deduplication/review.js";
export {
diff --git a/sdk/typescript/tests-ts/dedupe-records.test.ts b/sdk/typescript/tests-ts/dedupe-records.test.ts
index 1e957a6f1..edfa1031a 100644
--- a/sdk/typescript/tests-ts/dedupe-records.test.ts
+++ b/sdk/typescript/tests-ts/dedupe-records.test.ts
@@ -10,6 +10,7 @@ import { PassThrough, Writable } from "node:stream";
import type { Finding, FindingsDocument } from "../src/models.js";
import {
deduplicateRecords,
+ recordsReviewAttribution,
type DeduplicateRecordsInput,
} from "../src/deduplication/records.js";
import type { DeduplicationReviewRequest } from "../src/deduplication/review.js";
@@ -17,6 +18,41 @@ import { runRecordsProtocol } from "../src/deduplication/records-protocol.js";
import { main } from "../src/cli.js";
import { capture, dependencies, FakeSignals } from "./cli-fixtures.js";
import { PLUGIN_ROOT } from "./plugin-root.js";
+import attributionFixtures from "./fixtures/records-review-attribution.json";
+
+test("attribution maps exact structured participants to sorted host identities", () => {
+ const references = new Map(
+ ["A", "B", "C", "D"].map((id) => [`finding-${id}`, id]),
+ );
+ for (const fixture of attributionFixtures) {
+ const participants = fixture.participants.map((id) => `finding-${id}`);
+ expect(
+ recordsReviewAttribution(
+ [...participants].reverse().concat(participants),
+ references,
+ new Map(fixture.anchors.map((id) => [id, []])),
+ ),
+ ).toEqual({ ...fixture.attribution, version: 1 });
+ }
+});
+
+test("attribution rejects absent, unknown, and context-only participants", () => {
+ const references = new Map([
+ ["finding-A", "A"],
+ ["finding-C", "C"],
+ ]);
+ const anchors = new Map([["A", ["C"]]]);
+ for (const participants of [
+ undefined,
+ [],
+ ["unknown"],
+ ["finding-C"],
+ ["finding-A", "unknown"],
+ ])
+ expect(() =>
+ recordsReviewAttribution(participants, references, anchors),
+ ).toThrow();
+});
const document: FindingsDocument = JSON.parse(
await readFile(
@@ -93,6 +129,7 @@ test("records groups original observations and retrieved neighbors with unique r
expect(review.trustedInstructions).toContain("approved repository");
expect(review.findingSchema).toHaveProperty("required");
expect(review).not.toHaveProperty("validate");
+ expect(review).not.toHaveProperty("findingIds");
for (const finding of assigned(review))
expect(finding.provenance).toHaveProperty(
"revision",
@@ -116,6 +153,20 @@ test("records groups original observations and retrieved neighbors with unique r
2,
);
expect(original).toEqual(input());
+ for (const request of requests) {
+ const participants = assigned(request).map((finding) =>
+ finding.provenance!.source!.slice("synthetic/".length),
+ );
+ expect(request.attribution).toEqual({
+ version: 1,
+ beneficiaryObservationIds: participants
+ .filter((id) => id !== "neighbor")
+ .sort(),
+ contextObservationIds: participants
+ .filter((id) => id === "neighbor")
+ .sort(),
+ });
+ }
});
test("records honors explicit observation neighborhoods and handles empty/isolated inputs without reviews", async () => {
@@ -171,6 +222,52 @@ test("candidate-only observations are grouped without becoming additional anchor
"screening",
"pair-review",
]);
+ for (const request of requests)
+ expect(request.attribution).toEqual({
+ version: 1,
+ beneficiaryObservationIds: ["a"],
+ contextObservationIds: ["b"],
+ });
+});
+
+test("records retries in a new invocation preserve membership with fresh review UUIDs", async () => {
+ const requests: DeduplicationReviewRequest[] = [];
+ const data: DeduplicateRecordsInput = {
+ version: 1,
+ observations: [record("A", "same"), record("D", "same")],
+ candidateRelationships: [
+ { observationId: "A", candidateObservationIds: ["D"] },
+ ],
+ };
+ const failed = await deduplicateRecords(data, {
+ reviewRunner: {
+ async run(review) {
+ requests.push(review);
+ throw new Error("Remote acceptance unknown");
+ },
+ },
+ });
+ expect(failed.status).toBe("unresolved");
+ const completed = await deduplicateRecords(data, {
+ reviewRunner: {
+ async run(review) {
+ requests.push(review);
+ return answer(review);
+ },
+ },
+ });
+ expect(completed.status).toBe("completed");
+ expect(requests).toHaveLength(3);
+ expect(new Set(requests.map((request) => request.requestId)).size).toBe(3);
+ for (const request of requests) {
+ expect(request.requestId).toMatch(
+ /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+ );
+ expect(request.attribution).toEqual({
+ ...attributionFixtures[3]!.attribution,
+ version: 1,
+ });
+ }
});
test.each([
@@ -327,9 +424,26 @@ function fakeHost(
const run = { jsonrpc: "2.0", id: "run-1", method: "run", params: input() };
test("CLI records mode uses only the fake host, bypassing saved scans, persistence, auth, and updates", async () => {
- const host = fakeHost((message, send) =>
- send({ jsonrpc: "2.0", id: message.id, result: answer(message.params) }),
- );
+ const host = fakeHost((message, send) => {
+ expect(message.jsonrpc).toBe("2.0");
+ expect(message.id).toBe(message.params.requestId);
+ expect(message.params.attribution?.version).toBe(1);
+ const participants = assigned(message.params).map((finding) =>
+ finding.provenance!.source!.slice("synthetic/".length),
+ );
+ expect(message.params.attribution).toEqual({
+ version: 1,
+ beneficiaryObservationIds: participants
+ .filter((id) => id !== "neighbor")
+ .sort(),
+ contextObservationIds: participants
+ .filter((id) => id === "neighbor")
+ .sort(),
+ });
+ // An older host can ignore additive metadata and use the original request.
+ const { attribution: _attribution, ...legacyRequest } = message.params;
+ send({ jsonrpc: "2.0", id: message.id, result: answer(legacyRequest) });
+ });
const deps = dependencies();
for (const key of Object.keys(deps)) {
if (typeof deps[key as keyof typeof deps] === "function")
@@ -482,14 +596,36 @@ test("real CLI pipes exit after a fake-host run without local Codex or state wri
try {
child.stdin.write(`${JSON.stringify(run)}\n`);
let final: Message | undefined;
+ const reviews: DeduplicationReviewRequest[] = [];
for await (const line of createInterface({ input: child.stdout })) {
const message = JSON.parse(line) as Message;
- if (message.method === "review.run")
+ if (message.method === "review.run") {
+ reviews.push(message.params);
+ expect(message.jsonrpc).toBe("2.0");
+ expect(message.id).toBe(message.params.requestId);
+ const participants = assigned(message.params).map((finding) =>
+ finding.provenance!.source!.slice("synthetic/".length),
+ );
+ expect(message.params.attribution).toEqual({
+ version: 1,
+ beneficiaryObservationIds: participants
+ .filter((id) => id !== "neighbor")
+ .sort(),
+ contextObservationIds: participants
+ .filter((id) => id === "neighbor")
+ .sort(),
+ });
child.stdin.write(
`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result: answer(message.params) })}\n`,
);
- else final = message;
+ } else final = message;
}
+ expect(
+ reviews.filter((review) => review.stage === "screening"),
+ ).toHaveLength(4);
+ expect(
+ reviews.filter((review) => review.stage === "pair-review"),
+ ).toHaveLength(2);
expect(await closed).toBe(0);
expect(stderr).toBe("");
expect(final).toMatchObject({
diff --git a/sdk/typescript/tests-ts/fixtures/records-review-attribution.json b/sdk/typescript/tests-ts/fixtures/records-review-attribution.json
new file mode 100644
index 000000000..89b52fe88
--- /dev/null
+++ b/sdk/typescript/tests-ts/fixtures/records-review-attribution.json
@@ -0,0 +1,38 @@
+[
+ {
+ "anchors": ["A", "B", "D"],
+ "participants": ["A", "B", "C"],
+ "attribution": {
+ "version": 1,
+ "beneficiaryObservationIds": ["A", "B"],
+ "contextObservationIds": ["C"]
+ }
+ },
+ {
+ "anchors": ["A", "B", "D"],
+ "participants": ["A", "C"],
+ "attribution": {
+ "version": 1,
+ "beneficiaryObservationIds": ["A"],
+ "contextObservationIds": ["C"]
+ }
+ },
+ {
+ "anchors": ["A", "B", "D"],
+ "participants": ["A", "B"],
+ "attribution": {
+ "version": 1,
+ "beneficiaryObservationIds": ["A", "B"],
+ "contextObservationIds": []
+ }
+ },
+ {
+ "anchors": ["A"],
+ "participants": ["A", "D"],
+ "attribution": {
+ "version": 1,
+ "beneficiaryObservationIds": ["A"],
+ "contextObservationIds": ["D"]
+ }
+ }
+]