@lornatang/dsh-codex-security 0.1.7 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/CHANGELOG.md +118 -103
  2. package/README.md +196 -189
  3. package/README.zh.md +196 -189
  4. package/docs/ARCHITECTURE.md +59 -53
  5. package/docs/ARTIFACTS.md +49 -46
  6. package/docs/CODEX-COMPATIBILITY.md +17 -0
  7. package/docs/SPEC.md +43 -43
  8. package/docs/TOOLS.md +364 -341
  9. package/docs/VALIDATION.md +33 -31
  10. package/docs/superpowers/plans/2026-11-16-deep-scan.md +71 -0
  11. package/docs/superpowers/specs/2026-11-16-deep-scan-design.md +31 -0
  12. package/lib/constants.js +3 -3
  13. package/lib/contracts.js +114 -34
  14. package/lib/deep-coordinator.js +599 -0
  15. package/lib/deep-host.js +36 -0
  16. package/lib/deep-worker.js +254 -0
  17. package/lib/git.js +24 -22
  18. package/lib/index.js +23 -1
  19. package/lib/secure-read.js +229 -0
  20. package/lib/service.js +403 -62
  21. package/lib/state-lock.js +71 -0
  22. package/lib/store.js +33 -15
  23. package/lib/target.js +33 -13
  24. package/lib/tools.js +54 -19
  25. package/lib/types/constants.d.ts +1 -1
  26. package/lib/types/contracts.d.ts +5 -2
  27. package/lib/types/deep-coordinator.d.ts +70 -0
  28. package/lib/types/deep-host.d.ts +32 -0
  29. package/lib/types/deep-worker.d.ts +110 -0
  30. package/lib/types/git.d.ts +10 -10
  31. package/lib/types/index.d.ts +1 -1
  32. package/lib/types/secure-read.d.ts +15 -0
  33. package/lib/types/service.d.ts +20 -4
  34. package/lib/types/state-lock.d.ts +9 -0
  35. package/lib/types/store.d.ts +5 -2
  36. package/lib/types/target.d.ts +1 -0
  37. package/lib/types/tools.d.ts +3 -2
  38. package/lib/types/types.d.ts +42 -7
  39. package/lib/types/util.d.ts +4 -0
  40. package/lib/types/worker-preset.d.ts +18 -0
  41. package/lib/util.js +27 -4
  42. package/lib/worker-preset.js +8 -0
  43. package/package.json +131 -123
  44. package/schemas/coverage.schema.json +136 -134
  45. package/skills/README.md +122 -116
  46. package/skills/assess-patch-risk/SKILL.md +10 -0
  47. package/skills/attack-path-analysis/SKILL.md +10 -0
  48. package/skills/deep-security-scan/SKILL.md +15 -116
  49. package/skills/define-security-policy/SKILL.md +10 -0
  50. package/skills/finding-discovery/SKILL.md +10 -0
  51. package/skills/fix-finding/SKILL.md +14 -112
  52. package/skills/propose-security-hardening/SKILL.md +10 -0
  53. package/skills/track-findings/SKILL.md +12 -113
  54. package/skills/validation/SKILL.md +10 -0
  55. package/skills/verify-fix/SKILL.md +14 -108
package/lib/service.js CHANGED
@@ -2,14 +2,17 @@ import { lstat, readFile } from 'node:fs/promises';
2
2
  import { dirname, join, resolve as resolvePath } from 'node:path';
3
3
  import { DEFAULT_CONFIG } from './config.js';
4
4
  import { PACKAGE_NAME, PLUGIN_NAME, PRODUCER, SKILL_NAMES, VERSION } from './constants.js';
5
- import { buildCoverage, buildFindingsDocument, normalizeAnchor, normalizeRuleId, normalizeFinding, policyGate, renderReport, severityCounts, sortedFindings, toCsv, toSarif, validateDraft, } from './contracts.js';
5
+ import { buildCoverage, buildFindingsDocument, fingerprintFor, normalizeAnchor, normalizeRuleId, normalizeFinding, policyGate, renderReport, severityCounts, sortedFindings, toCsv, toSarif, validateDraft, validateFindingEvidence, } from './contracts.js';
6
6
  import { gitString } from './git.js';
7
7
  import { FINDING_STATUSES, SEVERITIES } from './types.js';
8
8
  import { ScanStore, defaultStateDir } from './store.js';
9
9
  import { readEvidenceLine, resolveTarget } from './target.js';
10
10
  import { assertArtifactContract } from './schema.js';
11
- import { canonicalProspectivePath, ensureDir, joinWithin, newId, nowIso, readFullText, readJson, sanitizeRelative, sha256, truncate, writeFileAtomic, writeJsonAtomic } from './util.js';
11
+ import { canonicalProspectivePath, ensureDir, joinWithin, newId, normalizeLine, nowIso, readFullText, readJson, sanitizeRelative, sha256, truncate, writeFileAtomic, writeJsonAtomic } from './util.js';
12
12
  import { createExportValidator, writeSecureExport } from './secure-export.js';
13
+ import { acquireStateLock } from './state-lock.js';
14
+ import { WorkerRegistry } from './deep-worker.js';
15
+ import { sourceRootIdentity } from './secure-read.js';
13
16
  export const FORMATS = ['sarif', 'json', 'csv', 'markdown'];
14
17
  async function possibleGitMetadata(root) {
15
18
  if (process.env['GIT_DIR'] !== undefined || process.env['GIT_COMMON_DIR'] !== undefined)
@@ -78,34 +81,90 @@ function samePaths(left, right) {
78
81
  function renderThreatModel(value) {
79
82
  if (typeof value === 'string')
80
83
  return value;
84
+ if (value['format'] === 'markdown' && typeof value['content'] === 'string')
85
+ return value['content'];
81
86
  return '# Threat model\n\n```json\n' + JSON.stringify(value, null, 2) + '\n```\n';
82
87
  }
88
+ function manifestThreatModel(value) {
89
+ if (typeof value === 'string')
90
+ return { format: 'markdown', content: value };
91
+ if ((value['format'] === 'markdown' && typeof value['content'] === 'string') || typeof value['summary'] === 'string')
92
+ return value;
93
+ return { format: 'markdown', content: renderThreatModel(value) };
94
+ }
95
+ function validateThreatModel(value) {
96
+ if ((typeof value === 'string' && value.trim()) || asObject(value))
97
+ return;
98
+ throw new Error('codex-security: threatModel must be a non-empty string or an object');
99
+ }
83
100
  export class SecurityService {
84
101
  store;
85
102
  config;
86
103
  ctx;
87
104
  scanLocks = new Map();
105
+ managedInvocations = new WeakSet();
88
106
  constructor(ctx, options = {}) {
89
107
  this.ctx = ctx;
90
108
  this.config = { ...DEFAULT_CONFIG, ...(options.config ?? {}) };
91
- const patchPath = options.patchPath ?? ctx.profileContext?.patchPath;
109
+ const profile = ctx.get?.('profileContext') ?? (Object.hasOwn(ctx, 'profileContext') ? ctx.profileContext : undefined);
110
+ const patchPath = options.patchPath ?? profile?.patchPath;
92
111
  this.store = new ScanStore(defaultStateDir(patchPath, this.config.stateDir));
93
112
  }
94
- /** Serialize complete read-modify-write operations for each scan within this process. */
95
- async withScanLock(scanId, operation) {
113
+ /** Serialize complete read-modify-write operations across instances and processes. */
114
+ async withScanLock(scanId, operation, args, signal) {
115
+ if (!/^cs_[a-f0-9]{24}$/.test(scanId))
116
+ throw new Error('codex-security: scan not found: ' + scanId);
96
117
  const previous = this.scanLocks.get(scanId) ?? Promise.resolve();
97
118
  let release;
98
119
  const held = new Promise((resolve) => { release = resolve; });
99
120
  const tail = previous.then(() => held);
100
121
  this.scanLocks.set(scanId, tail);
101
- await previous;
122
+ let releaseState;
123
+ try {
124
+ signal?.throwIfAborted();
125
+ if (signal) {
126
+ let onAbort;
127
+ const aborted = new Promise((_, reject) => {
128
+ onAbort = () => reject(signal.reason);
129
+ signal.addEventListener('abort', onAbort, { once: true });
130
+ });
131
+ try {
132
+ await Promise.race([previous, aborted]);
133
+ }
134
+ finally {
135
+ signal.removeEventListener('abort', onAbort);
136
+ }
137
+ }
138
+ else
139
+ await previous;
140
+ signal?.throwIfAborted();
141
+ await this.ready();
142
+ releaseState = await acquireStateLock(join(this.store.stateDir, '.locks', 'scan-' + scanId + '.sqlite'), { signal });
143
+ const current = await this.store.get(scanId);
144
+ if (current?.record.managedParent && !this.managedInvocations.has(args)) {
145
+ throw new Error('codex-security: managed scans can only be modified by their coordinator');
146
+ }
147
+ return await operation();
148
+ }
149
+ finally {
150
+ try {
151
+ releaseState?.();
152
+ }
153
+ finally {
154
+ release();
155
+ if (this.scanLocks.get(scanId) === tail)
156
+ this.scanLocks.delete(scanId);
157
+ }
158
+ }
159
+ }
160
+ /** Internal capability: tool-provided JSON cannot grant access to a managed scan. */
161
+ async withManagedAccess(args, operation) {
162
+ this.managedInvocations.add(args);
102
163
  try {
103
164
  return await operation();
104
165
  }
105
166
  finally {
106
- release();
107
- if (this.scanLocks.get(scanId) === tail)
108
- this.scanLocks.delete(scanId);
167
+ this.managedInvocations.delete(args);
109
168
  }
110
169
  }
111
170
  async requireRunningScan(scanId) {
@@ -226,7 +285,8 @@ export class SecurityService {
226
285
  throw new Error('codex-security: invalid scan mode: ' + requested);
227
286
  return this.startScan(args, requested);
228
287
  }
229
- async startScan(args, kind) {
288
+ async startScan(args, kind, options = {}) {
289
+ options.signal?.throwIfAborted();
230
290
  await this.ready();
231
291
  const resolved = await resolveTarget({
232
292
  targetPath: str(args['targetPath']),
@@ -236,7 +296,9 @@ export class SecurityService {
236
296
  workingTree: bool(args['workingTree']) === true,
237
297
  maxFiles: this.config.maxFiles,
238
298
  maxFileBytes: this.config.maxFileBytes,
299
+ signal: options.signal,
239
300
  });
301
+ options.signal?.throwIfAborted();
240
302
  const mode = kind === 'prompt-only' ? 'prompt-only' : kind;
241
303
  const deep = kind === 'deep';
242
304
  const budget = deep
@@ -247,9 +309,15 @@ export class SecurityService {
247
309
  maxTimeMinutes: Math.min(24 * 60, Math.max(1, num(args['maxTimeMinutes']) ?? 360)),
248
310
  }
249
311
  : undefined;
250
- const scanId = newId('cs_', 24);
312
+ const scanId = options.scanId ?? newId('cs_', 24);
313
+ if (!/^cs_[a-f0-9]{24}$/.test(scanId) || (options.managedParent && !/^cs_[a-f0-9]{24}$/.test(options.managedParent))) {
314
+ throw new Error('codex-security: invalid managed scan identifier');
315
+ }
316
+ const boundRoot = options.managedParent ? sourceRootIdentity(resolved.target.rootPath).identity : undefined;
251
317
  const record = await this.store.create({
252
318
  scanId,
319
+ ...(options.managedParent ? { managedParent: options.managedParent } : {}),
320
+ ...(boundRoot ? { managedRootIdentity: { dev: String(boundRoot.dev), ino: String(boundRoot.ino) } } : {}),
253
321
  mode,
254
322
  promptOnly: kind === 'prompt-only',
255
323
  target: resolved.target,
@@ -261,7 +329,7 @@ export class SecurityService {
261
329
  ...(args['threatModel'] !== undefined ? { threatModel: args['threatModel'] } : {}),
262
330
  ...(str(args['previousScanId']) ? { previousScanId: str(args['previousScanId']) } : {}),
263
331
  warnings: resolved.warnings,
264
- });
332
+ }, { signal: options.signal });
265
333
  const skill = kind === 'deep' ? 'deep-security-scan' : resolved.target.kind === 'git_diff' ? 'security-diff-scan' : 'security-scan';
266
334
  const instructions = this.scanInstructions(record, skill, kind === 'prompt-only');
267
335
  return {
@@ -332,15 +400,17 @@ export class SecurityService {
332
400
  return counts;
333
401
  }
334
402
  async updateScanContext(args) {
335
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.updateScanContextUnlocked(args));
403
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.updateScanContextUnlocked(args), args);
336
404
  }
337
405
  async updateScanContextUnlocked(args) {
338
406
  const scanId = requiredStr(args, 'scanId');
339
- await this.requireRunningScan(scanId);
407
+ const { dir } = await this.requireRunningScan(scanId);
340
408
  const includePaths = strArray(args['includePaths']);
341
409
  const excludePaths = strArray(args['excludePaths']);
342
410
  const notes = str(args['notes']);
343
411
  const threatModel = args['threatModel'];
412
+ if (threatModel !== undefined)
413
+ validateThreatModel(threatModel);
344
414
  const record = await this.store.update(scanId, (current) => {
345
415
  if (notes)
346
416
  current.notes = (current.notes ? current.notes + '\n' : '') + notes;
@@ -350,10 +420,37 @@ export class SecurityService {
350
420
  throw new Error('codex-security: scan scope is bound; start a new scan to change it');
351
421
  }
352
422
  });
423
+ if (threatModel !== undefined) {
424
+ const model = threatModel;
425
+ const draft = await readJson(join(dir, 'checkpoints', 'scan-draft.json'));
426
+ if (draft) {
427
+ draft.input.threatModel = model;
428
+ await writeJsonAtomic(join(dir, 'checkpoints', 'scan-draft.json'), draft);
429
+ }
430
+ await writeFileAtomic(join(dir, 'threatmodel.md'), renderThreatModel(model));
431
+ }
353
432
  return { ok: true, scan: record };
354
433
  }
355
434
  async updateScanProgress(args) {
356
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.updateScanProgressUnlocked(args));
435
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.updateScanProgressUnlocked(args), args);
436
+ }
437
+ /** Set an absolute count from the durable coordinator journal after a restart. */
438
+ async setManagedProgress(args) {
439
+ if (!this.managedInvocations.has(args))
440
+ throw new Error('codex-security: coordinator capability is required');
441
+ const scanId = requiredStr(args, 'scanId');
442
+ const count = args['discoveryRuns'];
443
+ if (typeof count !== 'number' || !Number.isSafeInteger(count) || count < 0)
444
+ throw new Error('codex-security: invalid Deep run count');
445
+ await this.withScanLock(scanId, async () => {
446
+ const scan = await this.requireRunningScan(scanId);
447
+ if (!scan.record.managedParent)
448
+ throw new Error('codex-security: scan is not managed');
449
+ await this.store.update(scanId, (current) => {
450
+ current.progress.discoveryRuns = count;
451
+ current.progress.phase = typeof args['phase'] === 'string' ? args['phase'] : 'deep-discovery';
452
+ });
453
+ }, args);
357
454
  }
358
455
  async updateScanProgressUnlocked(args) {
359
456
  const scanId = requiredStr(args, 'scanId');
@@ -371,27 +468,41 @@ export class SecurityService {
371
468
  });
372
469
  return { ok: true, scanId, progress: record.progress };
373
470
  }
374
- async recordScanDraft(args) {
375
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.recordScanDraftUnlocked(args));
471
+ async recordScanDraft(args, options) {
472
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.recordScanDraftUnlocked(args, options), args, options?.signal);
376
473
  }
377
- async recordScanDraftUnlocked(args) {
474
+ async recordScanDraftUnlocked(args, options) {
475
+ options?.signal?.throwIfAborted();
378
476
  const scanId = requiredStr(args, 'scanId');
379
477
  const { record, dir } = await this.requireRunningScan(scanId);
380
478
  const draft = validateDraft(args['draft'] ?? args);
479
+ if (draft.threatModel !== undefined)
480
+ validateThreatModel(draft.threatModel);
381
481
  if ((draft.scope?.includePaths && !samePaths(draft.scope.includePaths, record.scope.includePaths)) ||
382
482
  (draft.scope?.excludePaths && !samePaths(draft.scope.excludePaths, record.scope.excludePaths))) {
383
483
  throw new Error('codex-security: draft scope differs from the bound scan scope');
384
484
  }
385
- const evidence = await this.collectEvidenceLines(record, draft.findings);
386
- const findings = draft.findings.map((input) => normalizeFinding(scanId, input, { rootPath: record.target.rootPath, evidenceLines: evidence }));
485
+ const submitted = asObject(args['draft'] ?? args);
486
+ const coverageInput = asObject(submitted?.['coverage']);
487
+ if ((coverageInput?.['includePaths'] && (!Array.isArray(coverageInput['includePaths']) || !samePaths(coverageInput['includePaths'], record.scope.includePaths))) ||
488
+ (coverageInput?.['excludePaths'] && (!Array.isArray(coverageInput['excludePaths']) || !samePaths(coverageInput['excludePaths'], record.scope.excludePaths)))) {
489
+ throw new Error('codex-security: coverage scope differs from the bound scan scope');
490
+ }
491
+ if (coverageInput?.['mode'] !== undefined && coverageInput['mode'] !== buildCoverage(record, draft.reviewState).mode)
492
+ throw new Error('codex-security: coverage mode differs from the bound scan mode');
493
+ const evidence = options?.workerSnapshot
494
+ ? await this.collectBoundEvidenceLines(options.workerSnapshot, draft.findings)
495
+ : await this.collectEvidenceLines(record, draft.findings);
496
+ const findings = draft.findings.map((input) => normalizeFinding(scanId, input, { rootPath: record.target.rootPath, targetId: record.target.targetId, evidenceLines: evidence }));
387
497
  const deduped = [];
388
498
  const seen = new Set();
389
499
  for (const finding of findings) {
390
500
  if (seen.has(finding.fingerprints.primary))
391
- continue;
501
+ throw new Error('codex-security: duplicate finding identity; use identity.instance to distinguish findings');
392
502
  seen.add(finding.fingerprints.primary);
393
503
  deduped.push(finding);
394
504
  }
505
+ validateFindingEvidence(deduped);
395
506
  assertArtifactContract('findings', buildFindingsDocument(scanId, deduped));
396
507
  const stored = {
397
508
  scanId,
@@ -402,6 +513,9 @@ export class SecurityService {
402
513
  };
403
514
  await ensureDir(join(dir, 'checkpoints'));
404
515
  await writeJsonAtomic(join(dir, 'checkpoints', 'scan-draft.json'), stored);
516
+ const threatModel = draft.threatModel ?? record.threatModel;
517
+ if (threatModel !== undefined)
518
+ await writeFileAtomic(join(dir, 'threatmodel.md'), renderThreatModel(threatModel));
405
519
  const counts = severityCounts(stored.findings);
406
520
  const updated = await this.store.update(scanId, (current) => {
407
521
  current.findingsCount = stored.findings.length;
@@ -462,20 +576,106 @@ export class SecurityService {
462
576
  }
463
577
  return evidence;
464
578
  }
579
+ async collectBoundEvidenceLines(snapshot, findings) {
580
+ const registry = new WorkerRegistry();
581
+ registry.reserve('verified-draft', snapshot);
582
+ const files = new Map();
583
+ const evidence = new Map();
584
+ const read = async (path) => {
585
+ let content = files.get(path);
586
+ if (content === undefined) {
587
+ content = await registry.read('verified-draft', path);
588
+ files.set(path, content);
589
+ }
590
+ return content;
591
+ };
592
+ try {
593
+ for (const finding of findings) {
594
+ if (!Array.isArray(finding.locations))
595
+ throw new Error('codex-security: finding locations are required');
596
+ for (const location of finding.locations) {
597
+ const content = await read(location.path);
598
+ const lines = content.split('\n');
599
+ if (!Number.isInteger(location.startLine) || location.startLine < 1 || location.startLine > lines.length || (location.endLine !== undefined && location.endLine > lines.length))
600
+ throw new Error('codex-security: finding location is outside the bound source');
601
+ evidence.set(location.path + ':' + location.startLine, truncate(normalizeLine(lines[location.startLine - 1] ?? ''), 400));
602
+ }
603
+ for (const raw of [...(finding.codeEvidence ?? []), ...(finding.code_evidence ?? [])]) {
604
+ const item = asObject(raw);
605
+ if (!item || typeof item['path'] !== 'string' || typeof item['code'] !== 'string' || !item['code'])
606
+ throw new Error('codex-security: worker code evidence requires a bound source path and code');
607
+ const content = await read(item['path']);
608
+ const start = item['startLine'] ?? item['start_line'];
609
+ const end = item['endLine'] ?? item['end_line'] ?? start;
610
+ let excerpt = content;
611
+ if (start !== undefined) {
612
+ const lines = content.split('\n');
613
+ if (typeof start !== 'number' || typeof end !== 'number' || !Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start || end > lines.length)
614
+ throw new Error('codex-security: code evidence location is outside the bound source');
615
+ excerpt = lines.slice(start - 1, end).join('\n');
616
+ }
617
+ if (!excerpt.includes(item['code']))
618
+ throw new Error('codex-security: code evidence does not match the bound source');
619
+ }
620
+ }
621
+ return evidence;
622
+ }
623
+ finally {
624
+ registry.release('verified-draft');
625
+ }
626
+ }
465
627
  async recordDiscoveryCandidates(args) {
466
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.recordDiscoveryCandidatesUnlocked(args));
628
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.recordDiscoveryCandidatesUnlocked(args), args);
467
629
  }
468
630
  async recordDiscoveryCandidatesUnlocked(args) {
469
631
  const scanId = requiredStr(args, 'scanId');
470
632
  const { record, dir } = await this.requireRunningScan(scanId);
471
633
  const inputs = requiredArray(args, 'candidates');
472
634
  const document = (await readJson(join(dir, 'candidates.json'))) ?? { scanId, updatedAt: nowIso(), candidates: [] };
473
- const existing = new Map(document.candidates.map((candidate) => [candidate.ruleId + '\u0000' + candidate.anchor + '\u0000' + (candidate.instance ?? ''), candidate]));
635
+ const existing = new Map(document.candidates.map((candidate) => [candidate.candidateId, candidate]));
474
636
  let added = 0;
475
637
  for (const raw of inputs) {
476
638
  const input = asObject(raw);
477
639
  if (!input)
640
+ throw new Error('codex-security: each discovery candidate must be an object');
641
+ if (input['ruleId'] === undefined && Array.isArray(input['locations'])) {
642
+ const summary = requiredStr(input, 'summary');
643
+ const evidence = requiredStr(input, 'evidence');
644
+ if (!Array.isArray(input['cwe_ids']) || input['cwe_ids'].some((value) => typeof value !== 'string'))
645
+ throw new Error('codex-security: candidate cwe_ids must be an array of strings');
646
+ const locations = input['locations'].map((rawLocation) => {
647
+ const location = asObject(rawLocation);
648
+ if (!location)
649
+ throw new Error('codex-security: candidate location must be an object');
650
+ const path = sanitizeRelative(requiredStr(location, 'path'));
651
+ const start = location['start_line'];
652
+ const end = location['end_line'];
653
+ if (!Number.isInteger(start) || start < 1 || (end !== undefined && (!Number.isInteger(end) || end < start)))
654
+ throw new Error('codex-security: invalid candidate location lines');
655
+ const role = requiredStr(location, 'role');
656
+ if (!['entrypoint', 'entrypoint/wrapper', 'source', 'root_control', 'sink', 'concrete_implementation', 'evidence'].includes(role))
657
+ throw new Error('codex-security: invalid candidate location role');
658
+ return { path, start_line: start, ...(end === undefined ? {} : { end_line: end }), role };
659
+ });
660
+ const first = locations[0];
661
+ if (!first)
662
+ throw new Error('codex-security: candidate locations must not be empty');
663
+ const instance = str(input['instance']);
664
+ const key = JSON.stringify([summary, evidence, locations, instance ?? '', input['cwe_ids']]);
665
+ const candidateId = 'cand_' + sha256(key).slice(0, 16);
666
+ if (existing.has(candidateId))
667
+ continue;
668
+ const candidate = {
669
+ candidateId, title: truncate(summary, 300), path: first.path, startLine: first.start_line,
670
+ anchor: normalizeAnchor('codex-security.candidate', first.path, summary + ' ' + evidence, instance),
671
+ ...(instance ? { instance } : {}), summary: truncate(summary, 4000), status: 'discovered', createdAt: nowIso(),
672
+ discovery: { ...input, locations },
673
+ };
674
+ document.candidates.push(candidate);
675
+ existing.set(candidateId, candidate);
676
+ added += 1;
478
677
  continue;
678
+ }
479
679
  const ruleId = normalizeRuleId(requiredStr(input, 'ruleId'));
480
680
  const title = requiredStr(input, 'title');
481
681
  const severity = this.severityOf(requiredStr(input, 'severity'));
@@ -484,10 +684,11 @@ export class SecurityService {
484
684
  const anchor = str(input['anchor']) ?? normalizeAnchor(ruleId, path, await readEvidenceLine(record.target.rootPath, path, startLine, this.config.maxFileBytes), str(input['instance']));
485
685
  const instance = str(input['instance']);
486
686
  const key = ruleId + '\u0000' + anchor + '\u0000' + (instance ?? '');
487
- if (existing.has(key))
687
+ const candidateId = 'cand_' + sha256(key).slice(0, 16);
688
+ if (existing.has(candidateId))
488
689
  continue;
489
690
  const candidate = {
490
- candidateId: 'cand_' + sha256(key).slice(0, 16),
691
+ candidateId,
491
692
  ruleId,
492
693
  title: truncate(title, 300),
493
694
  severity,
@@ -500,7 +701,7 @@ export class SecurityService {
500
701
  createdAt: nowIso(),
501
702
  };
502
703
  document.candidates.push(candidate);
503
- existing.set(key, candidate);
704
+ existing.set(candidateId, candidate);
504
705
  added += 1;
505
706
  }
506
707
  document.updatedAt = nowIso();
@@ -523,7 +724,7 @@ export class SecurityService {
523
724
  return { ok: true, scanId, total: candidates.length, candidates };
524
725
  }
525
726
  async recordCandidateValidations(args) {
526
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.recordCandidateValidationsUnlocked(args));
727
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.recordCandidateValidationsUnlocked(args), args);
527
728
  }
528
729
  async recordCandidateValidationsUnlocked(args) {
529
730
  const scanId = requiredStr(args, 'scanId');
@@ -535,21 +736,44 @@ export class SecurityService {
535
736
  for (const raw of inputs) {
536
737
  const input = asObject(raw);
537
738
  if (!input)
538
- continue;
739
+ throw new Error('codex-security: each validation must be an object');
539
740
  const candidateId = requiredStr(input, 'candidateId');
540
741
  const candidate = byId.get(candidateId);
541
742
  if (!candidate)
542
743
  throw new Error('codex-security: unknown candidateId: ' + candidateId);
543
- const status = requiredStr(input, 'status');
744
+ const nested = asObject(input['validation']);
745
+ if (input['validation'] !== undefined && !nested)
746
+ throw new Error('codex-security: candidate validation must be an object');
747
+ if (nested && (input['status'] !== undefined || input['summary'] !== undefined))
748
+ throw new Error('codex-security: do not mix nested and flat candidate validation fields');
749
+ const status = nested ? requiredStr(nested, 'disposition') : requiredStr(input, 'status');
544
750
  if (!['reportable', 'validated', 'deferred', 'rejected', 'suppressed', 'not_applicable'].includes(status))
545
751
  throw new Error('codex-security: invalid candidate validation status: ' + status);
546
- const summary = requiredStr(input, 'summary');
752
+ let summary;
753
+ if (nested) {
754
+ const confidence = requiredStr(nested, 'confidence');
755
+ if (!['high', 'medium', 'low'].includes(confidence))
756
+ throw new Error('codex-security: invalid candidate confidence');
757
+ for (const field of ['confidence_rationale', 'counterevidence_or_proof_gap', 'method', 'remaining_uncertainty'])
758
+ requiredStr(nested, field);
759
+ const evidence = nested['evidence'];
760
+ if (!(typeof evidence === 'string' && evidence.trim()) && !(Array.isArray(evidence) && evidence.length > 0 && evidence.every((value) => typeof value === 'string' && value.trim())))
761
+ throw new Error('codex-security: nested validation evidence is required');
762
+ if (nested['rubric'] === undefined || nested['rubric'] === null)
763
+ throw new Error('codex-security: nested validation rubric is required');
764
+ summary = typeof evidence === 'string' ? evidence : evidence.join('\n');
765
+ candidate.validation = nested;
766
+ }
767
+ else {
768
+ summary = requiredStr(input, 'summary');
769
+ delete candidate.validation;
770
+ }
547
771
  document.validations.push({
548
772
  candidateId,
549
773
  status,
550
774
  summary: truncate(summary, 8000),
551
- ...(str(input['method']) ? { method: str(input['method']) } : {}),
552
- ...(Array.isArray(input['evidence']) ? { evidence: input['evidence'] } : {}),
775
+ ...(str(nested?.['method'] ?? input['method']) ? { method: str(nested?.['method'] ?? input['method']) } : {}),
776
+ ...(nested ? { validation: nested, evidence: Array.isArray(nested['evidence']) ? nested['evidence'] : [nested['evidence']] } : Array.isArray(input['evidence']) ? { evidence: input['evidence'] } : {}),
553
777
  ...(strArray(input['limitations']) ? { limitations: strArray(input['limitations']) } : {}),
554
778
  recordedAt: nowIso(),
555
779
  });
@@ -565,7 +789,7 @@ export class SecurityService {
565
789
  return { ok: true, scanId, recorded: inputs.length, validations: document.validations.length, candidates };
566
790
  }
567
791
  async recordCandidateAttackPaths(args) {
568
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.recordCandidateAttackPathsUnlocked(args));
792
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.recordCandidateAttackPathsUnlocked(args), args);
569
793
  }
570
794
  async recordCandidateAttackPathsUnlocked(args) {
571
795
  const scanId = requiredStr(args, 'scanId');
@@ -577,27 +801,51 @@ export class SecurityService {
577
801
  for (const raw of inputs) {
578
802
  const input = asObject(raw);
579
803
  if (!input)
580
- continue;
804
+ throw new Error('codex-security: each attack path must be an object');
581
805
  const candidateId = requiredStr(input, 'candidateId');
582
- if (!byId.has(candidateId))
806
+ const candidate = byId.get(candidateId);
807
+ if (!candidate)
583
808
  throw new Error('codex-security: unknown candidateId: ' + candidateId);
809
+ const nested = asObject(input['attackPath']);
810
+ if (input['attackPath'] !== undefined && !nested)
811
+ throw new Error('codex-security: candidate attackPath must be an object');
812
+ if (nested && input['summary'] !== undefined)
813
+ throw new Error('codex-security: do not mix nested and flat attack path fields');
814
+ if (nested) {
815
+ const decision = requiredStr(nested, 'decision');
816
+ const severity = requiredStr(nested, 'severity');
817
+ if (!['reportable', 'ignore', 'deferred'].includes(decision) || (decision === 'ignore' ? severity !== 'ignore' : !['critical', 'high', 'medium', 'low', ...(decision === 'deferred' ? ['unknown'] : [])].includes(severity)))
818
+ throw new Error('codex-security: invalid attack path decision or severity');
819
+ for (const field of ['change_conditions', 'counterevidence', 'dataflow', 'reachability', 'severity_rationale'])
820
+ requiredStr(nested, field);
821
+ for (const field of ['impact', 'likelihood'])
822
+ if (!['high', 'medium', 'low', 'ignore', 'unknown'].includes(requiredStr(nested, field)))
823
+ throw new Error('codex-security: invalid attack path ' + field);
824
+ if (decision === 'deferred')
825
+ requiredStr(nested, 'proof_gap');
826
+ candidate.attackPath = nested;
827
+ }
828
+ else
829
+ delete candidate.attackPath;
584
830
  document.attackPaths.push({
585
831
  candidateId,
586
- summary: truncate(requiredStr(input, 'summary'), 8000),
832
+ summary: truncate(nested ? requiredStr(nested, 'dataflow') : requiredStr(input, 'summary'), 8000),
587
833
  ...(strArray(input['steps']) ? { steps: strArray(input['steps']) } : {}),
588
- ...(str(input['impact']) ? { impact: str(input['impact']) } : {}),
589
- ...(str(input['likelihood']) ? { likelihood: str(input['likelihood']) } : {}),
834
+ ...(str(nested?.['impact'] ?? input['impact']) ? { impact: str(nested?.['impact'] ?? input['impact']) } : {}),
835
+ ...(str(nested?.['likelihood'] ?? input['likelihood']) ? { likelihood: str(nested?.['likelihood'] ?? input['likelihood']) } : {}),
590
836
  ...(strArray(input['preconditions']) ? { preconditions: strArray(input['preconditions']) } : {}),
591
837
  ...(strArray(input['controls']) ? { controls: strArray(input['controls']) } : {}),
838
+ ...(nested ? { attackPath: nested } : {}),
592
839
  recordedAt: nowIso(),
593
840
  });
594
841
  }
595
842
  document.updatedAt = nowIso();
596
843
  await writeJsonAtomic(join(dir, 'attack-paths.json'), document);
844
+ await writeJsonAtomic(join(dir, 'candidates.json'), { scanId, updatedAt: nowIso(), candidates });
597
845
  return { ok: true, scanId, recorded: inputs.length, attackPaths: document.attackPaths.length };
598
846
  }
599
847
  async saveArtifact(args) {
600
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.saveArtifactUnlocked(args));
848
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.saveArtifactUnlocked(args), args);
601
849
  }
602
850
  async saveArtifactUnlocked(args) {
603
851
  const scanId = requiredStr(args, 'scanId');
@@ -620,10 +868,11 @@ export class SecurityService {
620
868
  const artifact = await this.store.readArtifact(scanId, path, limit);
621
869
  return { ok: true, scanId, ...artifact };
622
870
  }
623
- async completeScan(args) {
624
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.completeScanUnlocked(args));
871
+ async completeScan(args, options) {
872
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.completeScanUnlocked(args, options), args, options?.signal);
625
873
  }
626
- async completeScanUnlocked(args) {
874
+ async completeScanUnlocked(args, options) {
875
+ options?.signal?.throwIfAborted();
627
876
  const scanId = requiredStr(args, 'scanId');
628
877
  const { record, dir } = await this.requireScan(scanId);
629
878
  if (record.status === 'completed')
@@ -643,12 +892,34 @@ export class SecurityService {
643
892
  workingTree: record.target.workingTree === true,
644
893
  maxFiles: this.config.maxFiles,
645
894
  maxFileBytes: this.config.maxFileBytes,
895
+ signal: options?.signal,
646
896
  });
897
+ options?.signal?.throwIfAborted();
898
+ if (record.managedRootIdentity) {
899
+ const current = sourceRootIdentity(record.target.rootPath).identity;
900
+ if (String(current.dev) !== record.managedRootIdentity.dev || String(current.ino) !== record.managedRootIdentity.ino)
901
+ throw new Error('codex-security: managed target directory changed after scan binding');
902
+ }
647
903
  if (currentTarget.target.snapshotDigest !== record.target.snapshotDigest)
648
904
  throw new Error('codex-security: target changed after scan binding; start a new scan');
649
- const findings = sortedFindings(draft.findings ?? []);
905
+ let findings = sortedFindings(draft.findings ?? []);
650
906
  const reviewState = draft.input.reviewState ?? { surfaces: [] };
651
907
  const warnings = [...record.warnings];
908
+ let migratedDraftIds;
909
+ if (findings.some((finding) => finding.fingerprints.primary !== fingerprintFor(record.target.targetId, finding.ruleId, finding.identity.anchor, finding.identity.instance))) {
910
+ // Only unsealed checkpoints are migrated. Sealed historical artifacts
911
+ // remain byte-for-byte immutable and use the legacy comparison path.
912
+ const evidenceLines = await this.collectEvidenceLines(record, draft.input.findings);
913
+ const migrated = draft.input.findings.map((input) => normalizeFinding(scanId, input, { rootPath: record.target.rootPath, targetId: record.target.targetId, evidenceLines }));
914
+ if (new Set(migrated.map((finding) => finding.fingerprints.primary)).size !== migrated.length)
915
+ throw new Error('codex-security: legacy draft has duplicate finding identities; record a corrected draft');
916
+ const byIdentity = new Map(migrated.map((finding) => [JSON.stringify([finding.ruleId, finding.identity.anchor, finding.identity.instance ?? '', finding.locations[0]?.path]), finding]));
917
+ migratedDraftIds = findings.map((finding) => ({ previous: finding.findingId, current: byIdentity.get(JSON.stringify([finding.ruleId, finding.identity.anchor, finding.identity.instance ?? '', finding.locations[0]?.path]))?.findingId ?? '' }));
918
+ if (migratedDraftIds.some((entry) => !entry.current))
919
+ throw new Error('codex-security: legacy draft identities changed; record a corrected draft');
920
+ findings = sortedFindings(migrated);
921
+ warnings.push('unsealed legacy draft finding IDs were migrated to the Codex-compatible identity contract');
922
+ }
652
923
  if (reviewState.surfaces.length === 0)
653
924
  throw new Error('codex-security: at least one coverage surface is required before sealing');
654
925
  const candidates = (await readJson(join(dir, 'candidates.json')))?.candidates ?? [];
@@ -667,19 +938,48 @@ export class SecurityService {
667
938
  }
668
939
  }
669
940
  const coverage = buildCoverage(record, reviewState);
941
+ const submittedScope = draft.input.scope ?? {};
942
+ for (const field of ['summary', 'runtimeStatus', 'validationMode', 'context']) {
943
+ if (submittedScope[field] !== undefined && (typeof submittedScope[field] !== 'string' || !submittedScope[field].trim()))
944
+ throw new Error('codex-security: scope ' + field + ' must be a non-empty string');
945
+ }
946
+ for (const field of ['limitations', 'artifactsReviewed']) {
947
+ const values = submittedScope[field];
948
+ if (values !== undefined && (!Array.isArray(values) || values.some((value) => typeof value !== 'string' || !value)))
949
+ throw new Error('codex-security: scope ' + field + ' must contain non-empty strings');
950
+ }
951
+ const scopeLimitations = submittedScope.limitations ?? [];
952
+ for (const surface of coverage.surfaces) {
953
+ for (const ref of surface.receiptRefs) {
954
+ if (!record.artifacts.some((artifact) => artifact.path === ref))
955
+ throw new Error('codex-security: coverage receipt is not a saved artifact: ' + ref);
956
+ let current = dir;
957
+ const components = ref.split('/');
958
+ for (let index = 0; index < components.length; index++) {
959
+ current = join(current, components[index]);
960
+ const info = await lstat(current).catch(() => undefined);
961
+ if (!info || info.isSymbolicLink() || (index === components.length - 1 ? !info.isFile() : !info.isDirectory())) {
962
+ throw new Error('codex-security: coverage receipt must be a scan-local regular file: ' + ref);
963
+ }
964
+ }
965
+ }
966
+ }
670
967
  const threatModel = draft.input.threatModel ?? record.threatModel;
671
968
  const sealedAt = nowIso();
672
969
  const findingsDocument = buildFindingsDocument(scanId, findings);
673
970
  const sarif = toSarif(record, findings);
674
971
  const report = renderReport(record, findings, coverage, { sealedAt, threatModel });
972
+ validateFindingEvidence(findings);
675
973
  assertArtifactContract('findings', findingsDocument);
676
974
  assertArtifactContract('coverage', coverage);
677
975
  await writeJsonAtomic(join(dir, 'findings.json'), findingsDocument);
678
976
  await writeJsonAtomic(join(dir, 'coverage.json'), coverage);
679
977
  await writeJsonAtomic(join(dir, 'sarif.json'), sarif);
680
978
  await writeFileAtomic(join(dir, 'report.md'), report);
681
- if (threatModel !== undefined)
979
+ if (threatModel !== undefined) {
682
980
  await writeFileAtomic(join(dir, 'threat-model.md'), renderThreatModel(threatModel));
981
+ await writeFileAtomic(join(dir, 'threatmodel.md'), renderThreatModel(threatModel));
982
+ }
683
983
  const sealFiles = [
684
984
  { path: 'findings.json', mediaType: 'application/json' },
685
985
  { path: 'coverage.json', mediaType: 'application/json' },
@@ -687,13 +987,15 @@ export class SecurityService {
687
987
  { path: 'report.md', mediaType: 'text/markdown' },
688
988
  ];
689
989
  if (threatModel !== undefined)
690
- sealFiles.push({ path: 'threat-model.md', mediaType: 'text/markdown' });
990
+ sealFiles.push({ path: 'threat-model.md', mediaType: 'text/markdown' }, { path: 'threatmodel.md', mediaType: 'text/markdown' });
691
991
  const artifacts = [];
692
992
  for (const file of sealFiles) {
993
+ options?.signal?.throwIfAborted();
693
994
  const data = await readFile(joinWithin(dir, file.path));
694
995
  artifacts.push({ path: file.path, sha256: sha256(data), mediaType: file.mediaType });
695
996
  }
696
997
  for (const artifact of record.artifacts) {
998
+ options?.signal?.throwIfAborted();
697
999
  const data = await readFile(joinWithin(dir, artifact.path));
698
1000
  artifacts.push({ path: artifact.path, sha256: sha256(data), mediaType: artifact.mediaType || 'application/octet-stream' });
699
1001
  }
@@ -720,15 +1022,18 @@ export class SecurityService {
720
1022
  snapshotDigest: record.target.snapshotDigest,
721
1023
  },
722
1024
  scope: {
1025
+ ...submittedScope,
723
1026
  includePaths: record.scope.includePaths,
724
1027
  excludePaths: record.scope.excludePaths,
725
1028
  ...(record.scope.summary ? { summary: record.scope.summary } : {}),
726
- runtimeStatus: 'not_executed',
727
- validationMode: 'static_source_review',
728
- ...(record.notes ? { context: record.notes } : {}),
729
- limitations: warnings,
1029
+ runtimeStatus: submittedScope.runtimeStatus ?? 'unknown',
1030
+ validationMode: submittedScope.validationMode ?? 'unspecified',
1031
+ ...(submittedScope.context ? { context: submittedScope.context } : record.notes ? { context: record.notes } : {}),
1032
+ limitations: [...new Set([...scopeLimitations, ...warnings])],
730
1033
  },
731
1034
  findingsRef: 'findings.json',
1035
+ coverageRef: 'coverage.json',
1036
+ ...(threatModel !== undefined ? { threatModel: manifestThreatModel(threatModel) } : {}),
732
1037
  artifacts,
733
1038
  mode: coverage.mode,
734
1039
  warnings,
@@ -738,6 +1043,7 @@ export class SecurityService {
738
1043
  assertArtifactContract('scan-manifest', manifest);
739
1044
  await writeJsonAtomic(join(dir, 'scan-manifest.json'), manifest);
740
1045
  const counts = severityCounts(findings);
1046
+ options?.signal?.throwIfAborted();
741
1047
  const updated = await this.store.update(scanId, (current) => {
742
1048
  current.status = 'completed';
743
1049
  current.completedAt = sealedAt;
@@ -754,6 +1060,7 @@ export class SecurityService {
754
1060
  scanId,
755
1061
  status: 'completed',
756
1062
  sealedAt,
1063
+ ...(migratedDraftIds ? { migratedDraftIds } : {}),
757
1064
  findingsCount: findings.length,
758
1065
  severityCounts: counts,
759
1066
  policy,
@@ -769,7 +1076,7 @@ export class SecurityService {
769
1076
  };
770
1077
  }
771
1078
  async failScan(args) {
772
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.failScanUnlocked(args));
1079
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.failScanUnlocked(args), args);
773
1080
  }
774
1081
  async failScanUnlocked(args) {
775
1082
  const scanId = requiredStr(args, 'scanId');
@@ -785,7 +1092,7 @@ export class SecurityService {
785
1092
  return { ok: true, scanId, status: record.status, error: record.error };
786
1093
  }
787
1094
  async cancelScan(args) {
788
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.cancelScanUnlocked(args));
1095
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.cancelScanUnlocked(args), args);
789
1096
  }
790
1097
  async cancelScanUnlocked(args) {
791
1098
  const scanId = requiredStr(args, 'scanId');
@@ -874,7 +1181,7 @@ export class SecurityService {
874
1181
  return { ok: true, total: all.length, limit, offset, findings: all.slice(offset, offset + limit) };
875
1182
  }
876
1183
  async setFindingTriage(args) {
877
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.setFindingTriageUnlocked(args));
1184
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.setFindingTriageUnlocked(args), args);
878
1185
  }
879
1186
  async setFindingTriageUnlocked(args) {
880
1187
  const scanId = requiredStr(args, 'scanId');
@@ -897,19 +1204,19 @@ export class SecurityService {
897
1204
  return { ok: true, scanId, triage };
898
1205
  }
899
1206
  async setFindingRemediation(args) {
900
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.setFindingRemediationUnlocked(args));
1207
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.setFindingRemediationUnlocked(args), args);
901
1208
  }
902
1209
  async setFindingRemediationUnlocked(args) {
903
1210
  const scanId = requiredStr(args, 'scanId');
904
1211
  const findingId = requiredStr(args, 'findingId');
905
1212
  const remediation = requiredStr(args, 'remediation');
906
- const status = str(args['status']) ?? 'triaged';
907
- if (!FINDING_STATUSES.includes(status))
908
- throw new Error('codex-security: status must be one of ' + FINDING_STATUSES.join(', '));
909
1213
  const findings = await this.store.readFindings(scanId);
910
1214
  if (!findings.some((finding) => finding.findingId === findingId))
911
1215
  throw new Error('codex-security: unknown findingId: ' + findingId);
912
1216
  const existing = (await this.store.readTriage(scanId))[findingId];
1217
+ const status = str(args['status']) ?? existing?.status ?? 'triaged';
1218
+ if (!FINDING_STATUSES.includes(status))
1219
+ throw new Error('codex-security: status must be one of ' + FINDING_STATUSES.join(', '));
913
1220
  const entry = {
914
1221
  findingId,
915
1222
  status: status,
@@ -977,7 +1284,7 @@ export class SecurityService {
977
1284
  return { ok: true, scanId, format, path: output, bytes: Buffer.byteLength(exported.content, 'utf8'), findingsCount: exported.count, policy: exported.policy ?? null };
978
1285
  }
979
1286
  async prepareReviewItems(args) {
980
- return this.withScanLock(requiredStr(args, 'scanId'), () => this.prepareReviewItemsUnlocked(args));
1287
+ return this.withScanLock(requiredStr(args, 'scanId'), () => this.prepareReviewItemsUnlocked(args), args);
981
1288
  }
982
1289
  async prepareReviewItemsUnlocked(args) {
983
1290
  const scanId = requiredStr(args, 'scanId');
@@ -1045,7 +1352,7 @@ export class SecurityService {
1045
1352
  item.updatedAt = nowIso();
1046
1353
  await writeJsonAtomic(join(dir, 'review-items.json'), document);
1047
1354
  return { ok: true, scanId, item };
1048
- });
1355
+ }, args);
1049
1356
  }
1050
1357
  async compareScans(args) {
1051
1358
  const baseScanId = requiredStr(args, 'baseScanId');
@@ -1066,6 +1373,7 @@ export class SecurityService {
1066
1373
  const document = await readJson(join(scan.dir, 'findings.json'));
1067
1374
  const review = scan.record.target.kind === 'git_diff' ? await readJson(join(scan.dir, 'review-items.json')) : undefined;
1068
1375
  if (!document || !Array.isArray(document.findings) || !coverage || !coverage.surfaces?.length ||
1376
+ (coverage.completeness !== undefined && coverage.completeness !== 'complete') ||
1069
1377
  coverage.deferred?.length || coverage.surfaces.some((surface) => surface.disposition === 'needs_follow_up') ||
1070
1378
  (scan.record.target.kind === 'git_diff' && (!review || review.items.some((item) => item.status === 'pending' || item.status === 'needs_follow_up'))) ||
1071
1379
  scan.record.inventory.truncated || scan.record.warnings.some((warning) => warning.startsWith('snapshot could not hash file:'))) {
@@ -1074,11 +1382,44 @@ export class SecurityService {
1074
1382
  }
1075
1383
  const base = await this.store.readFindings(baseScanId);
1076
1384
  const head = await this.store.readFindings(headScanId);
1077
- const baseMap = new Map(base.map((finding) => [finding.fingerprints.primary, finding]));
1078
1385
  const headMap = new Map(head.map((finding) => [finding.fingerprints.primary, finding]));
1079
- const closed = base.filter((finding) => !headMap.has(finding.fingerprints.primary));
1080
- const added = head.filter((finding) => !baseMap.has(finding.fingerprints.primary));
1081
- const open = head.filter((finding) => baseMap.has(finding.fingerprints.primary));
1386
+ const matchedBase = new Set();
1387
+ const matchedHead = new Set();
1388
+ for (const finding of base) {
1389
+ const match = headMap.get(finding.fingerprints.primary);
1390
+ if (match) {
1391
+ matchedBase.add(finding);
1392
+ matchedHead.add(match);
1393
+ }
1394
+ }
1395
+ // Pre-parity releases used path-based fingerprints. Match old records only
1396
+ // on a unique semantic identity; ambiguity must not close findings.
1397
+ const legacy = (finding, targetId) => finding.fingerprints.primary !== fingerprintFor(targetId, finding.ruleId, finding.identity.anchor, finding.identity.instance);
1398
+ const key = (finding) => JSON.stringify([finding.ruleId, finding.identity.anchor, finding.identity.instance ?? '']);
1399
+ const groups = (values) => {
1400
+ const result = new Map();
1401
+ for (const finding of values) {
1402
+ const identity = key(finding);
1403
+ const list = result.get(identity) ?? [];
1404
+ list.push(finding);
1405
+ result.set(identity, list);
1406
+ }
1407
+ return result;
1408
+ };
1409
+ const baseGroups = groups(base.filter((finding) => !matchedBase.has(finding)));
1410
+ const headGroups = groups(head.filter((finding) => !matchedHead.has(finding)));
1411
+ for (const [identity, left] of baseGroups) {
1412
+ const right = headGroups.get(identity) ?? [];
1413
+ if (!right.length || !left.some((finding) => legacy(finding, baseRecord.target.targetId)) && !right.some((finding) => legacy(finding, headRecord.target.targetId)))
1414
+ continue;
1415
+ if (left.length !== 1 || right.length !== 1)
1416
+ throw new Error('codex-security: ambiguous legacy finding identity prevents comparison');
1417
+ matchedBase.add(left[0]);
1418
+ matchedHead.add(right[0]);
1419
+ }
1420
+ const closed = base.filter((finding) => !matchedBase.has(finding));
1421
+ const added = head.filter((finding) => !matchedHead.has(finding));
1422
+ const open = head.filter((finding) => matchedHead.has(finding));
1082
1423
  const brief = (finding) => ({
1083
1424
  findingId: finding.findingId,
1084
1425
  title: finding.title,