@clear-capabilities/agentic-security-scanner 0.175.0 → 0.177.0

package/src/posture/rule-compiler/cli.js

@@ -1,4 +1,4 @@
-// CLI surface: `agentic-security rules synthesize|evaluate|promote|status|rollback`.
+// CLI surface: `agentic-security rules synthesize|evaluate|promote|status|rollback|cost|regress`.
 //
 // Distinct from the pre-existing `labs synthesize-rule` (posture/rule-synthesis.js), which proposes SUPPRESSION
 // rules from repeated false-positive triage verdicts — a different input, a different output and a different
@@ -9,12 +9,17 @@
 // it never decides promotion).
 import fs from 'node:fs';
 import { statePath } from '../state-dir.js';
+import { packTrust, signPublishedRule } from './store.js';
+import { sharedFalsePositiveCorpus, falsePositiveHits, regressRules } from './regression.js';
 import { draftRuleIR, validateRuleIR, ruleIRDigest } from './ir.js';
 import { checkEligibility } from './eligibility.js';
 import { buildCorpus } from './corpus.js';
 import { gatePromotion, checkLeakage, PROMOTION_DEFAULTS } from './promotion.js';
 import { recordTransition, stateOf, historyFor } from './lifecycle.js';
-import { loadLedger, saveLedger, saveIR, loadIR, saveEvaluation, writeFixtures, publishCustomRule, unpublishCustomRule } from './store.js';
+import { loadLedger, saveLedger, saveIR, loadIR, saveEvaluation, writeFixtures, publishCustomRule, unpublishCustomRule, saveCorpus, loadCorpus, saveSynthesis, loadSynthesis, loadProvenance, saveProvenance } from './store.js';
+import { synthesizeCandidate } from './proposal.js';
+import { mutatorCoverage } from './mutation.js';
+import { sha256 } from '../proof-fabric/reproducer.js';
 
 function loadFinding(root, id) {
   const p = statePath(root, 'last-scan.json');
@@ -35,7 +40,9 @@ export async function cmdRules(args, root) {
   if (sub === 'promote') return cmdPromote(args, root);
   if (sub === 'status') return cmdStatus(args, root);
   if (sub === 'rollback') return cmdRollback(args, root);
-  console.error('usage: rules synthesize <finding-id> --spec <file.json> | evaluate <rule-id> | promote <rule-id> | status [rule-id] | rollback <rule-id>');
+  if (sub === 'cost') return cmdCost(args, root);
+  if (sub === 'regress') return cmdRegress(args, root);
+  console.error('usage: rules synthesize <finding-id> --spec <file.json> [--auto] [--max-attempts N] | evaluate <rule-id> | promote <rule-id> | status [rule-id] | rollback <rule-id> | cost <rule-id>');
   return 4;
 }
 
@@ -51,7 +58,22 @@ async function cmdSynthesize(args, root) {
   const elig = checkEligibility(finding, { proofState: args.flags['proof-state'] || null });
   if (!elig.eligible) { console.error(`Not eligible for rule synthesis: ${elig.reasons.join('; ')}`); return 4; }
 
-  const ir = draftRuleIR({ ...spec, originatingFindingId: finding.stableId ?? finding.id, originatingCommit: spec.originatingCommit ?? null, evidenceState: elig.evidenceState });
+  // The candidate pattern is the model's or the person's, when they gave one. Without one, or with --auto, the synthesis loop proposes
+  // from the vulnerable and patched code, scores each attempt on the real corpus and its mutations, and revises (see proposal.js).
+  let finalSpec = spec; let synthesis = null;
+  const corpusSpec = { originalCode: spec.originalCode, patchedCode: spec.patchedCode ?? null, nearbyCleanCode: spec.nearbyCleanCode ?? [], protectedVariantsCode: spec.protectedVariantsCode ?? [] };
+  const leak = checkLeakage(JSON.stringify(corpusSpec), { benchmarkNames: args.flags['benchmark-names'] ? String(args.flags['benchmark-names']).split(',') : [], fileNames: spec.fileNames ?? [] });
+  if (!leak.ok) { console.error(`Refusing: the material for this rule shows benchmark or answer-key signals (${leak.offendingTerms.join('; ')}). Nothing was written.`); return 4; }
+  if (args.flags.auto || (!spec.match && !spec.sink)) {
+    if (!isStr(spec.originalCode)) { console.error('Automatic proposal needs originalCode (the vulnerable snippet) in the spec.'); return 4; }
+    const { id, title, severity, cwe, family, languages, remediation } = spec;
+    synthesis = synthesizeCandidate({ base: { id, title, severity, cwe, family, languages, remediation, originatingFindingId: finding.stableId ?? finding.id, evidenceState: elig.evidenceState }, corpusSpec, proposed: spec.match ?? null, maxAttempts: Number(args.flags['max-attempts']) || 6, leakageOk: true });
+    for (const a of synthesis.attempts) console.log(`  attempt ${a.n}: ${a.strategy.padEnd(34)} ${a.valid ? `precision ${fmtPct(a.score.precision)}  recall ${fmtPct(a.score.recall)}  protected-failures ${a.score.protectedFailures}${a.pass ? '  PASS' : ''}` : `invalid (${a.errors[0]})`}`);
+    if (!synthesis.best) { console.error('No valid candidate could be proposed from this material.'); return 1; }
+    finalSpec = { ...spec, ...(synthesis.best.match ? { match: synthesis.best.match } : {}), ...(synthesis.best.structure ?? {}) };
+    console.log(synthesis.best.pass ? `  candidate meets the promotion gate on this corpus (not yet recorded as VALIDATED).` : `  no attempt met the gate; the best is kept as a CANDIDATE only: ${synthesis.best.reasons.join('; ')}`);
+  }
+  const ir = draftRuleIR({ ...finalSpec, originatingFindingId: finding.stableId ?? finding.id, originatingCommit: spec.originatingCommit ?? null, evidenceState: elig.evidenceState });
   const errs = validateRuleIR(ir);
   if (errs.length) { console.error(`Invalid rule: ${errs.join('; ')}`); return 4; }
 
@@ -61,6 +83,8 @@ async function cmdSynthesize(args, root) {
   const cand = recordTransition(ledger, { ruleId: ir.id, from: 'DRAFT', to: 'CANDIDATE', reason: 'eligibility passed', evidence: { eligibility: elig }, actor: args.flags.actor || 'agent' });
   saveLedger(root, ledger);
   saveIR(root, { ...ir, state: 'CANDIDATE' });
+  saveCorpus(root, ir.id, { ...corpusSpec, fileNames: spec.fileNames ?? [], discoveryCost: spec.discoveryCost ?? (args.flags['discovery-cost-usd'] ? { usd: Number(args.flags['discovery-cost-usd']), tokens: Number(args.flags['discovery-tokens']) || null, model: spec.model ?? null } : null) });
+  if (synthesis) saveSynthesis(root, ir.id, { attempts: synthesis.attempts, best: synthesis.best });
   console.log(`Rule ${ir.id}: DRAFT -> CANDIDATE (digest ${ruleIRDigest(ir).slice(0, 12)})`);
   if (!cand.ok) console.error(cand.reason);
   return 0;
@@ -71,17 +95,35 @@ async function cmdEvaluate(args, root) {
   if (!id) { console.error('usage: rules evaluate <rule-id> --corpus <file.json>'); return 4; }
   const ir = loadIR(root, id);
   if (!ir) { console.error(`No rule IR found for ${id}. Run rules synthesize first.`); return 4; }
-  const corpusSpec = readJsonArg(args.flags.corpus);
+  const corpusSpec = readJsonArg(args.flags.corpus) ?? loadCorpus(root, id);
   if (!corpusSpec) { console.error('No corpus supplied. Pass --corpus <file.json> with originalCode (and optionally patchedCode/nearbyCleanCode/protectedVariantsCode).'); return 4; }
   const corpus = buildCorpus(ir, corpusSpec);
-  const leakage = checkLeakage(JSON.stringify(corpusSpec), { benchmarkNames: args.flags['benchmark-names'] ? String(args.flags['benchmark-names']).split(',') : [] });
+  // the corpus a rule is evaluated on is the evidence for it: keep it, so `rules regress` and the shared false-positive corpus use the SAME code
+  if (args.flags.corpus) saveCorpus(root, id, { ...(loadCorpus(root, id) ?? {}), ...corpusSpec });
+  const leakage = checkLeakage(JSON.stringify({ ...corpusSpec, fileNames: undefined, discoveryCost: undefined }), { benchmarkNames: args.flags['benchmark-names'] ? String(args.flags['benchmark-names']).split(',') : [], fileNames: corpusSpec.fileNames ?? [] });
   const gate = gatePromotion({ ir, corpus, leakageCheck: leakage, thresholds: args.flags.thresholds ? readJsonArg(args.flags.thresholds) : PROMOTION_DEFAULTS });
 
   const ledger = loadLedger(root);
+  // the shared false-positive corpus: the safe code of every other promoted rule, plus the operator's own files. Part of the gate.
+  const fpItems = sharedFalsePositiveCorpus(root, ledger, id);
+  const fpHits = falsePositiveHits(ir, fpItems);
+  gate.fpCorpus = { items: fpItems.length, hits: fpHits.map((h) => h.label) };
+  if (fpHits.length) { gate.pass = false; gate.reasons.push(`fires on ${fpHits.length} of ${fpItems.length} item(s) in the shared false-positive corpus: ${fpHits.slice(0, 3).map((h) => h.label).join(', ')}${fpHits.length > 3 ? ', ...' : ''}`); }
   const cur = stateOf(ledger, id);
   if (gate.pass && cur === 'CANDIDATE') recordTransition(ledger, { ruleId: id, from: 'CANDIDATE', to: 'VALIDATED', reason: 'promotion gate passed', evidence: { score: gate.evaluation.score }, actor: args.flags.actor || 'agent' });
   saveLedger(root, ledger);
   saveEvaluation(root, id, gate);
+  const corpusHash = (list) => sha256(JSON.stringify(list.map((x) => [x.label, x.code]).sort()));
+  const prev = loadProvenance(root, id);
+  saveProvenance(root, id, {
+    schema: 'agentic-security/rule-provenance', version: 1, ruleId: id, ruleVersion: 1, ruleHash: ruleIRDigest(ir),
+    originatingFinding: ir.provenance.originatingFindingId, originatingCommit: ir.provenance.originatingCommit, evidenceState: ir.provenance.evidenceState,
+    generatingModel: ir.provenance.model, promptConfigVersion: ir.provenance.promptConfigVersion,
+    positiveCorpusHash: corpusHash(corpus.positives), negativeCorpusHash: corpusHash(corpus.negatives),
+    benchmarkResults: { precision: gate.evaluation.score.precision, recall: gate.evaluation.score.recall, tp: gate.evaluation.score.tp, fp: gate.evaluation.score.fp, fn: gate.evaluation.score.fn, tn: gate.evaluation.score.tn, protectedFailures: gate.evaluation.score.protectedFailures, thresholds: gate.evaluation.thresholds, gate: gate.pass ? 'passed' : 'failed', reasons: gate.reasons },
+    leakageCheck: leakage, mutatorCoverage: mutatorCoverage(corpusSpec.originalCode), discoveryCost: corpusSpec.discoveryCost ?? prev?.discoveryCost ?? null,
+    promotionEvent: prev?.promotionEvent ?? null, evaluatedAt: new Date().toISOString(),
+  });
   if (args.flags.json) console.log(JSON.stringify(gate, null, 2));
   else {
     console.log(`Rule ${id}: ${gate.pass ? 'VALIDATED' : 'gate FAILED'}`);
@@ -91,6 +133,7 @@ async function cmdEvaluate(args, root) {
   if (gate.pass) { const f = writeFixtures(root, ir, corpus); if (f.ok) console.log(`  regression fixtures written: ${f.written.length} file(s) under .agentic-security/rule-compiler/${id}/fixtures/`); }
   return gate.pass ? 0 : 1;
 }
+function isStr(v) { return typeof v === 'string' && v.length > 0; }
 const fmtPct = (n) => (n == null ? 'unmeasured' : `${(n * 100).toFixed(1)}%`);
 
 async function cmdPromote(args, root) {
@@ -101,15 +144,39 @@ async function cmdPromote(args, root) {
   if (stateOf(ledger, id) !== 'VALIDATED') { console.error(`Rule ${id} is not VALIDATED (run rules evaluate first); refusing to promote.`); return 4; }
   const ir = loadIR(root, id);
   if (!ir) { console.error(`No rule IR found for ${id}.`); return 4; }
+  // other rules may have been promoted since this one was evaluated: hold it to the false-positive corpus as it is NOW
+  const fpNow = falsePositiveHits(ir, sharedFalsePositiveCorpus(root, ledger, id));
+  if (fpNow.length) { console.error(`Promotion refused: ${id} fires on ${fpNow.length} item(s) of the shared false-positive corpus (${fpNow.slice(0, 3).map((h) => h.label).join(', ')}). Re-evaluate or narrow the rule.`); return 1; }
   const pub = publishCustomRule(root, ir);
   if (!pub.ok) { console.error(`Promotion refused: ${pub.reason}`); return 4; }
   const t = recordTransition(ledger, { ruleId: id, from: 'VALIDATED', to: 'PROMOTED', reason: args.flags.reason || 'promoted', actor: args.flags.actor || 'operator' });
   saveLedger(root, ledger);
+  const prov = loadProvenance(root, id);
+  if (prov) saveProvenance(root, id, { ...prov, promotionEvent: { at: new Date().toISOString(), actor: args.flags.actor || 'operator', reason: args.flags.reason || 'promoted', ruleHash: ruleIRDigest(ir) } });
   console.log(`Rule ${id}: VALIDATED -> PROMOTED. Published to ${pub.file}.`);
+  // Publishing is not trusting. Rule packs are signature-checked so a rule dropped into a repository cannot run in someone's CI; sign this
+  // one with the operator's key when there is one, and say plainly whether the scanner will load it.
+  const key = args.flags['sign-key'] ?? process.env.AGENTIC_SECURITY_PRIVATE_KEY;
+  if (key) { const sg = signPublishedRule(pub.file, key); console.log(sg.ok ? `  signed: ${pub.file}.sig` : `  could not sign (${sg.reason}); the rule is published unsigned`); }
+  const trust = packTrust(root, id);
+  console.log(trust.live ? `  The scanner will load it (${trust.via}).` : `  NOT LIVE YET: the scanner will refuse this rule (${trust.reason}). To make it live: ${trust.remediation}.`);
   if (!t.ok) console.error(t.reason);
   return 0;
 }
 
+/** `rules regress [rule-id]`: re-score every PROMOTED rule against its own corpus and the shared false-positive corpus. Exit 1 on any regression. */
+async function cmdRegress(args, root) {
+  const ledger = loadLedger(root);
+  if (ledger.tampered) { console.error(`Refusing: rule lifecycle ledger failed its integrity check (${ledger.tamperReason}).`); return 4; }
+  const only = args._[2] ?? null;
+  const results = regressRules(root, ledger, { only, thresholds: args.flags.thresholds ? readJsonArg(args.flags.thresholds) : undefined });
+  if (args.flags.json) console.log(JSON.stringify({ results }, null, 2));
+  else if (!results.length) console.log(only ? `No promoted rule ${only}.` : 'No rule is PROMOTED; nothing to regress.');
+  else for (const r of results) { console.log(`${r.id}: ${r.status.toUpperCase()}${r.precision != null ? `  precision ${fmtPct(r.precision)}  recall ${fmtPct(r.recall)}  false-positive corpus hits ${r.fpCorpusHits}` : ''}`); for (const m of r.reasons) console.log(`  - ${m}`); }
+  if (only && !results.length) return 4;
+  return results.every((r) => r.status === 'ok') ? 0 : 1;
+}
+
 async function cmdRollback(args, root) {
   const id = args._[2];
   if (!id) { console.error('usage: rules rollback <rule-id> [--reason text]'); return 4; }
@@ -130,12 +197,37 @@ async function cmdStatus(args, root) {
     const h = historyFor(ledger, id);
     if (!h.length) { console.error(`No history for rule ${id}.`); return 4; }
     if (args.flags.json) console.log(JSON.stringify(h, null, 2));
-    else { console.log(`Rule ${id}: ${stateOf(ledger, id)}`); for (const e of h) console.log(`  ${e.at}  ${e.from ?? '(new)'} -> ${e.to}  (${e.reason || ''})`); }
+    else { console.log(`Rule ${id}: ${stateOf(ledger, id)}`);
+      if (stateOf(ledger, id) === 'PROMOTED') { const tr = packTrust(root, id); console.log(tr.live ? `  live: yes (${tr.via})` : `  live: NO, the scanner refuses it (${tr.reason}). ${tr.remediation}.`); }
+      for (const e of h) console.log(`  ${e.at}  ${e.from ?? '(new)'} -> ${e.to}  (${e.reason || ''})`); 
+      const syn = loadSynthesis(root, id);
+      if (syn?.attempts?.length) { console.log(`  synthesis: ${syn.attempts.length} attempt(s), best ${syn.best ? `${syn.best.strategy}${syn.best.pass ? ' (met the gate)' : ' (did not meet the gate)'}` : 'none'}`); }
+    }
     return 0;
   }
   const ids = [...new Set(ledger.entries.map((e) => e.ruleId))];
-  if (args.flags.json) { console.log(JSON.stringify(ids.map((rid) => ({ id: rid, state: stateOf(ledger, rid) })), null, 2)); return 0; }
+  if (args.flags.json) { console.log(JSON.stringify(ids.map((rid) => ({ id: rid, state: stateOf(ledger, rid), ...(stateOf(ledger, rid) === 'PROMOTED' ? { live: packTrust(root, rid).live } : {}) })), null, 2)); return 0; }
   if (!ids.length) { console.log('No rules in the lifecycle ledger yet.'); return 0; }
-  for (const rid of ids) console.log(`  ${rid.padEnd(40)} ${stateOf(ledger, rid)}`);
+  for (const rid of ids) console.log(`  ${rid.padEnd(40)} ${stateOf(ledger, rid)}${stateOf(ledger, rid) === 'PROMOTED' && !packTrust(root, rid).live ? '  (NOT LIVE: the scanner refuses it)' : ''}`);
+  return 0;
+}
+
+// PRD 3 business metric: what the first, model-assisted discovery cost, against what every later deterministic detection costs.
+// The discovery cost is whatever the agent run reported for it (recorded at synthesis); a deterministic detection makes no model
+// call and is $0 of model spend. The count of later detections is read from the LAST scan only, so it is a floor, not a history.
+async function cmdCost(args, root) {
+  const id = args._[2];
+  if (!id) { console.error('usage: rules cost <rule-id>'); return 4; }
+  const prov = loadProvenance(root, id);
+  if (!prov) { console.error(`No provenance for ${id}. Run rules evaluate first.`); return 4; }
+  let detections = null;
+  try { const last = JSON.parse(fs.readFileSync(statePath(root, 'last-scan.json'), 'utf8')); detections = (last.findings || []).filter((f) => String(f.id || '').startsWith(`custom:rule-compiler/${id}:`)).length; } catch { /* no scan */ }
+  const first = prov.discoveryCost;
+  const out = { ruleId: id, firstDiscovery: first ? { usd: first.usd ?? null, tokens: first.tokens ?? null, model: first.model ?? null } : null, laterDeterministicDetections: detections, laterDeterministicModelUsd: 0, state: prov.promotionEvent ? 'promoted' : 'not promoted' };
+  if (args.flags.json) { console.log(JSON.stringify(out, null, 2)); return 0; }
+  console.log(`Rule ${id} (${out.state})`);
+  console.log(first ? `  first discovery: ${first.usd != null ? `$${first.usd}` : 'cost not recorded'}${first.tokens ? `, ${first.tokens} tokens` : ''}${first.model ? `, ${first.model}` : ''}` : '  first discovery: cost was not recorded for this rule');
+  console.log(`  later detections by this rule in the last scan: ${detections ?? 'no scan available'}, each at $0 of model spend`);
+  if (first?.usd != null && detections) console.log(`  discovery cost spread over ${detections + 1} detection(s): $${(first.usd / (detections + 1)).toFixed(4)} each, falling with every further one`);
   return 0;
 }

package/src/posture/rule-compiler/corpus.js

@@ -9,17 +9,13 @@
 // the score a rule gets here is the score it will actually produce once promoted.
 import { generateVariants } from './mutation.js';
 import { compileToCustomRule } from './ir.js';
-import { runRule } from '../custom-rules.js';
+import { runRule, normalizeCustomRule } from '../custom-rules.js';
 
+/** The rule exactly as the scanner would load it: through the loader's own normalizer, not a second implementation. */
 function toRuntimeRule(ir) {
   const { ok, doc, errs } = compileToCustomRule(ir);
   if (!ok) throw new Error(`cannot build corpus for an invalid rule IR: ${errs.join('; ')}`);
-  const regexes = doc.match.allOf ? doc.match.allOf.map((p) => new RegExp(p, 'g')) : [new RegExp(doc.match.pattern, 'g')];
-  return {
-    id: doc.id, title: doc.title, severity: doc.severity, cwe: doc.cwe, languages: doc.languages, message: doc.message,
-    regexes, requireAll: !!doc.match.allOf, windowLines: doc.match.window ?? 5,
-    notMatch: doc.match.notMatch ? new RegExp(doc.match.notMatch) : null,
-  };
+  return normalizeCustomRule(doc);
 }
 
 const EXT = { javascript: 'x.js', typescript: 'x.ts', python: 'x.py', go: 'x.go', ruby: 'x.rb', java: 'x.java', rust: 'x.rs', csharp: 'x.cs', php: 'x.php', any: 'x.txt' };
@@ -33,8 +29,16 @@ export function buildCorpus(ir, { originalCode, patchedCode = null, nearbyCleanC
     negatives.push({ label: 'patched', code: patchedCode });
     for (const v of generateVariants(patchedCode)) negatives.push({ label: `patched-sibling:${v.mutator}`, code: v.code });
   }
-  nearbyCleanCode.forEach((code, i) => negatives.push({ label: `nearby-clean-${i}`, code }));
-  protectedVariantsCode.forEach((code, i) => negatives.push({ label: `protected-${i}`, code }));
+  // The safe side is mutated too (rename, wrapper, equivalent API, ALTERNATE SANITIZER, framework variant, ...): a rule keyed to one
+  // sanitizer's name or one framework's accessor fires on the sibling that uses another, and that is a protected-negative failure.
+  nearbyCleanCode.forEach((code, i) => {
+    negatives.push({ label: `nearby-clean-${i}`, code });
+    for (const v of generateVariants(code)) negatives.push({ label: `nearby-clean-${i}-sibling:${v.mutator}`, code: v.code });
+  });
+  protectedVariantsCode.forEach((code, i) => {
+    negatives.push({ label: `protected-${i}`, code });
+    for (const v of generateVariants(code)) negatives.push({ label: `protected-${i}-sibling:${v.mutator}`, code: v.code });
+  });
 
   return { positives, negatives };
 }

package/src/posture/rule-compiler/ir.js

@@ -4,9 +4,20 @@
 // regex/allOf/notMatch/window engine; this module only adds PROVENANCE metadata around it.
 //
 // A rule's match semantics are deliberately the same closed vocabulary custom-rules.js
-// already supports (pattern | allOf+window | notMatch) — no new matching primitive is
-// introduced, so a promoted rule is exactly as auditable as a hand-written one.
+// already supports (pattern | allOf+window | notMatch, plus the structural fields below): no
+// separate matching engine is introduced, so a promoted rule is exactly as auditable as a hand-written one.
+//
+// The structural fields are REAL, not annotations: each is a regular expression and each compiles to a constraint the
+// runtime matcher enforces.
+//   source, propagator, sink   together they become a windowed co-occurrence (allOf) anchored on the SINK; a sink alone is the pattern
+//   sanitizer, dominatingGuard a hit is dropped when either matches within `guardWindow` lines before (or on) it
+//   frameworkConstraint        a file-level precondition (the file must contain it, wherever it is)
+//   exclusions                 a hit is dropped when its own line matches one
+//   languages                  the rule only runs on files of those languages
+// An explicit `match` always wins over a derived one. An AST pattern is NOT a field: the existing engine has no AST matcher for rules to
+// compile to, and a field the matcher ignored would be the old mistake (an annotation that looks like a constraint).
 import { sha256 } from '../proof-fabric/reproducer.js';
+import { normalizeCustomRule } from '../custom-rules.js';
 
 const RULE_IR_SCHEMA = 'agentic-security/rule-ir';
 const RULE_IR_VERSION = 1;
@@ -28,8 +39,9 @@ export function validateRuleIR(ir) {
   if (!isStr(ir.family)) errs.push('family required');
   if (!Array.isArray(ir.languages) || !ir.languages.length || !ir.languages.every((l) => VALID_LANGS.has(l))) errs.push('languages must be a non-empty array from the supported set');
   const m = ir.match;
-  if (!m || typeof m !== 'object') errs.push('match required');
-  else {
+  if (m == null && !isStr(ir.sink)) errs.push('match required (or at least a sink, from which one is derived)');
+  else if (m != null && typeof m !== 'object') errs.push('match must be an object');
+  else if (m) {
     const hasPattern = isStr(m.pattern);
     const hasAllOf = Array.isArray(m.allOf) && m.allOf.length > 0 && m.allOf.every(isStr);
     if (!hasPattern && !hasAllOf) errs.push('match needs a pattern or a non-empty allOf');
@@ -39,12 +51,20 @@ export function validateRuleIR(ir) {
       try { new RegExp(re); } catch { errs.push(`invalid regex: ${re}`); }
     }
   }
-  // Declarative-only hint fields (sink/source/propagator/sanitizer/dominatingGuard/frameworkConstraint): free text,
-  // never executable, carried for provenance/review only and NOT consulted by the matcher.
+  // Structural fields: each is a regular expression the matcher enforces (see the header). Free text is rejected, so a field can
+  // never look like a constraint while being ignored.
   for (const k of ['sink', 'source', 'propagator', 'sanitizer', 'dominatingGuard', 'frameworkConstraint']) {
-    if (ir[k] != null && !isStr(ir[k])) errs.push(`${k} must be a string when present`);
+    if (ir[k] == null) continue;
+    if (!isStr(ir[k])) { errs.push(`${k} must be a regular-expression string when present`); continue; }
+    try { new RegExp(ir[k]); } catch { errs.push(`${k} is not a valid regular expression`); }
+  }
+  if ((ir.source || ir.propagator) && !ir.sink && !ir.match) errs.push('a source or propagator needs a sink');
+  if (ir.window != null && !(Number.isInteger(ir.window) && ir.window > 0 && ir.window <= 200)) errs.push('window must be an integer in 1..200');
+  if (ir.guardWindow != null && !(Number.isInteger(ir.guardWindow) && ir.guardWindow > 0 && ir.guardWindow <= 200)) errs.push('guardWindow must be an integer in 1..200');
+  if (ir.exclusions != null) {
+    if (!(Array.isArray(ir.exclusions) && ir.exclusions.every(isStr))) errs.push('exclusions must be an array of regular-expression strings');
+    else for (const re of ir.exclusions) { try { new RegExp(re); } catch { errs.push(`invalid exclusion regex: ${re}`); } }
   }
-  if (ir.exclusions != null && !(Array.isArray(ir.exclusions) && ir.exclusions.every(isStr))) errs.push('exclusions must be an array of strings');
   if (!ir.provenance || typeof ir.provenance !== 'object') errs.push('provenance required');
   else {
     if (!isStr(ir.provenance.originatingFindingId)) errs.push('provenance.originatingFindingId required');
@@ -74,14 +94,37 @@ export function draftRuleIR({ id, title, severity, cwe, family, languages, match
 export function compileToCustomRule(ir) {
   const errs = validateRuleIR(ir);
   if (errs.length) return { ok: false, errs };
+  const alt = (...parts) => { const p = parts.filter(isStr); return p.length ? p.map((x) => `(?:${x})`).join('|') : null; };
+  // the base match: explicit wins; otherwise source -> propagator -> sink as a windowed co-occurrence, or a sink alone
+  let base = ir.match;
+  if (!base) {
+    // the SINK leads: the matcher anchors on the first pattern, and the finding, the guard window and the line exclusions all belong at
+    // the sink, where the flaw manifests. The window is symmetric, so the order of the others does not affect co-occurrence.
+    const chain = [ir.sink, ir.propagator, ir.source].filter(isStr);
+    base = chain.length > 1 ? { allOf: chain, window: ir.window ?? 8 } : { pattern: ir.sink };
+  }
+  const guard = alt(ir.sanitizer, ir.dominatingGuard);
   const doc = {
     id: `rule-compiler/${ir.id}`,
     title: ir.title,
     severity: ir.severity,
     cwe: ir.cwe,
     languages: ir.languages,
-    match: { ...(ir.match.pattern ? { pattern: ir.match.pattern } : {}), ...(ir.match.allOf ? { allOf: ir.match.allOf, window: ir.match.window ?? 5 } : {}), ...(ir.match.notMatch ? { notMatch: ir.match.notMatch } : {}) },
+    match: {
+      ...(base.pattern ? { pattern: base.pattern } : {}),
+      ...(base.allOf ? { allOf: base.allOf, window: base.window ?? 5 } : {}),
+      ...(base.notMatch ? { notMatch: base.notMatch } : {}),
+      ...(isStr(ir.frameworkConstraint) ? { fileRequires: [ir.frameworkConstraint] } : {}),
+      ...(guard ? { guardedBy: guard, guardWindow: ir.guardWindow ?? base.window ?? 5 } : {}),
+      ...(Array.isArray(ir.exclusions) && ir.exclusions.length ? { excludeLine: ir.exclusions } : {}),
+    },
     message: ir.remediation || `${ir.title} (${ir.cwe}, compiled from ${ir.provenance.originatingFindingId})`,
   };
+  // The loader has its own safety checks (nested quantifiers and so on). A rule it would refuse must not be reported as compiled,
+  // or it would score well here and silently never fire in a scan.
+  const origError = console.error; let loaderSaid = '';
+  console.error = (...a) => { loaderSaid = a.join(' '); };
+  let normalized; try { normalized = normalizeCustomRule(doc); } finally { console.error = origError; }
+  if (!normalized) return { ok: false, errs: [`the scanner's rule loader would reject this rule${loaderSaid ? `: ${loaderSaid.replace(/^agentic-security:\s*/, '').slice(0, 160)}` : ''}`] };
   return { ok: true, doc };
 }

package/src/posture/rule-compiler/mutation.js

@@ -29,6 +29,7 @@ export function variableRename(code, { suffix = '_v2' } = {}) {
 }
 
 export function wrapInFunction(code, { name = 'wrapped_v2' } = {}) {
+  if (!String(code).trim()) return null;
   const indented = code.split('\n').map((l) => (l ? `  ${l}` : l)).join('\n');
   return `function ${name}() {\n${indented}\n}\n${name}();\n`;
 }
@@ -46,7 +47,71 @@ function insertIndirection(code) {
 
 function _hash(s) { let h = 0; for (const c of s) h = (h * 31 + c.charCodeAt(0)) | 0; return h; }
 
-const MUTATORS = Object.freeze({ 'variable-rename': variableRename, 'wrap-in-function': wrapInFunction, 'insert-indirection': insertIndirection });
+// ---- the four mutators the PRD lists beyond rename / wrapper / indirection --------------------------------------------------
+// Each is a deterministic, table-driven textual rewrite that returns null when it does not apply. Tables are deliberately
+// small and conservative: an entry is here only when both sides are the same API family used the same way, so the claim "same
+// vulnerability, different shape" stays true. They are applied to the vulnerable side (does the rule still fire?) and to the safe
+// side (does it still decline?); the safe side is where a rule keyed to ONE sanitizer's name is caught.
+
+// equivalent APIs: the same operation through a sibling entry point
+const EQUIVALENT_APIS = Object.freeze([
+  [/\bchild_process\.exec\(/, 'child_process.execSync('], [/\bexecSync\(/, 'exec('], [/\bos\.system\(/, 'os.popen('],
+  [/\bdb\.query\(/, 'db.execute('], [/\bconnection\.query\(/, 'connection.execute('], [/\bcursor\.execute\(/, 'cursor.executemany('],
+  [/\bfs\.readFile\(/, 'fs.readFileSync('], [/\bfs\.readFileSync\(/, 'fs.readFile('], [/\bfs\.writeFile\(/, 'fs.writeFileSync('],
+  [/\bhttp\.get\(/, 'https.get('], [/\baxios\.get\(/, 'axios.request('], [/\bres\.send\(/, 'res.end('],
+  [/\bos\.Open\(/, 'os.OpenFile('], [/\bsubprocess\.call\(/, 'subprocess.run('], [/\bsubprocess\.run\(/, 'subprocess.call('],
+]);
+export function equivalentApi(code) {
+  for (const [from, to] of EQUIVALENT_APIS) if (from.test(code)) return code.replace(from, to);
+  return null;
+}
+
+// alternate sanitizers: a different, equally valid way to neutralize the same input
+const ALTERNATE_SANITIZERS = Object.freeze([
+  [/\bescapeHtml\(/, 'validator.escape('], [/\bvalidator\.escape\(/, 'escapeHtml('], [/\bDOMPurify\.sanitize\(/, 'sanitizeHtml('], [/\bsanitizeHtml\(/, 'DOMPurify.sanitize('],
+  [/\bshlex\.quote\(/, 'pipes.quote('], [/\bhtml\.escape\(/, 'markupsafe.escape('], [/\bhtml\.EscapeString\(/, 'template.HTMLEscapeString('],
+  [/\bencodeURIComponent\(/, 'encodeURI('], [/\bpath\.basename\(/, 'path.parse('], [/\bparseInt\(/, 'Number('], [/\bNumber\(/, 'parseInt('],
+  [/\bstrconv\.Atoi\(/, 'strconv.ParseInt('], [/\bint\(/, 'abs('],
+]);
+export function alternateSanitizer(code) {
+  for (const [from, to] of ALTERNATE_SANITIZERS) if (from.test(code)) return code.replace(from, to);
+  return null;
+}
+
+// framework variants: the same untrusted input reached through another framework's accessor
+const FRAMEWORK_VARIANTS = Object.freeze([
+  [/\breq\.body\./g, 'ctx.request.body.'], [/\breq\.query\./g, 'ctx.query.'], [/\breq\.params\./g, 'ctx.params.'],
+  [/\brequest\.args\.get\(/g, 'request.form.get('], [/\brequest\.form\.get\(/g, 'request.args.get('], [/\$_GET\[/g, '$_REQUEST['], [/\$_POST\[/g, '$_REQUEST['],
+  [/\br\.URL\.Query\(\)\.Get\(/g, 'r.FormValue('], [/\brequest\.getParameter\(/g, 'request.getHeader('],
+]);
+export function frameworkVariant(code) {
+  for (const [from, to] of FRAMEWORK_VARIANTS) if (from.test(code)) { from.lastIndex = 0; return code.replace(from, to); }
+  return null;
+}
+
+// reordering: swap the first pair of ADJACENT simple statements that share no identifier, so neither feeds the other. This is a
+// syntactic independence test, not a data-flow proof; it is applied to rule-corpus snippets, where a swap of two unrelated
+// statements is what a different author's version of the same code would plausibly look like.
+const CONTROL = /^\s*(?:if|else|for|while|switch|case|return|try|catch|finally|do|break|continue|throw|function|def|class|import|from|package|\}|\{|@|\/\/|#)\b|^\s*[}{]\s*$/;
+export function reorderStatements(code) {
+  const lines = code.split('\n');
+  const simple = (l) => l.trim() && !CONTROL.test(l) && /[;)]\s*$|^[^=]*=[^=].*[^{]$/.test(l.trim()) && !/[{]\s*$/.test(l);
+  const ids = (l) => new Set([...l.matchAll(/\b[A-Za-z_][A-Za-z0-9_]*\b/g)].map((m) => m[0]).filter((x) => !RESERVED.has(x)));
+  for (let i = 0; i + 1 < lines.length; i++) {
+    if (!simple(lines[i]) || !simple(lines[i + 1])) continue;
+    const a = ids(lines[i]); const b = ids(lines[i + 1]);
+    if ([...a].some((x) => b.has(x))) continue;
+    const out = [...lines]; [out[i], out[i + 1]] = [out[i + 1], out[i]];
+    return out.join('\n');
+  }
+  return null;
+}
+
+const MUTATORS = Object.freeze({
+  'variable-rename': variableRename, 'wrap-in-function': wrapInFunction, 'insert-indirection': insertIndirection,
+  'equivalent-api': equivalentApi, 'reorder-statements': reorderStatements, 'alternate-sanitizer': alternateSanitizer, 'framework-variant': frameworkVariant,
+});
+export const MUTATOR_NAMES = Object.freeze(Object.keys(MUTATORS));
 
 /** Every mutator applied to `code`; mutators that don't apply (return null) are omitted, never silently skipped without saying so. */
 export function generateVariants(code) {
@@ -58,3 +123,9 @@ export function generateVariants(code) {
   }
   return out;
 }
+
+/** Which of the seven mutators produced a variant for this code, and which did not (so a report can say what was not exercised). */
+export function mutatorCoverage(code) {
+  const applied = new Set(generateVariants(code).map((v) => v.mutator));
+  return { applied: MUTATOR_NAMES.filter((n) => applied.has(n)), notApplicable: MUTATOR_NAMES.filter((n) => !applied.has(n)) };
+}

package/src/posture/rule-compiler/promotion.js

@@ -13,14 +13,30 @@ export const PROMOTION_DEFAULTS = Object.freeze({ minPrecision: 0.95, minRecall:
 // checker rather than reaching across that isolation boundary.
 const ADVISORY_ID = /\b(?:CVE|GHSA|CWE)-[A-Za-z0-9-]+\b/i;
 
-/** Anti-cheating: the synthesis agent must never see benchmark answer keys, hidden labels, CWE-bearing hidden
- * filenames or vulnerability-comment metadata. */
-export function checkLeakage(promptText, { benchmarkNames = [] } = {}) {
+// What a synthesis agent must never see (PRD 3, anti-cheating): benchmark answer keys, hidden test labels, CWE-bearing hidden file
+// names, vulnerability comments and protected test metadata. These defaults are always applied; a caller adds its own benchmark names.
+const DEFAULT_BENCHMARK_NAMES = Object.freeze(['owasp benchmark', 'juliet', 'sard test', 'cve-replay', 'corpus-baseline', 'answer key', 'ground truth', 'adjudicated', 'hidden test', 'expectedresults']);
+const CWE_FILENAME = /(^|[\\/])[^\\/]*cwe[-_]?\d+[^\\/]*$/i;
+const ANSWER_KEY_FILENAME = /(^|[\\/])(?:labels?|answers?|expected|ground[-_]?truth|answer[-_]?key|oracle|result)[^\\/]*\.(?:json|jsonl|ya?ml|csv|txt)$/i;
+const VULNERABILITY_COMMENT = /(?:\/\/|#|\/\*|^\s*\*)\s*(?:POTENTIAL FLAW|FLAW\b|INCIDENTAL|BAD\b|GOOD\b|vulnerab\w*|insecure|exploit\w*)/im;
+
+/**
+ * Anti-cheating gate. Fails closed: any hit makes `ok` false, and the synthesis loop will not report a pass.
+ * @param {string} promptText everything the synthesis agent would be shown (corpus code, spec text)
+ * @param {{benchmarkNames?: string[], fileNames?: string[]}} opts
+ */
+export function checkLeakage(promptText, { benchmarkNames = [], fileNames = [] } = {}) {
   const hay = String(promptText ?? '');
+  const lower = hay.toLowerCase();
   const offending = [];
-  for (const name of benchmarkNames) if (name && hay.toLowerCase().includes(String(name).toLowerCase())) offending.push(name);
+  for (const name of [...DEFAULT_BENCHMARK_NAMES, ...benchmarkNames]) if (name && lower.includes(String(name).toLowerCase())) offending.push(`benchmark name: ${name}`);
   const m = ADVISORY_ID.exec(hay);
-  if (m) offending.push(m[0]);
+  if (m) offending.push(`identifier: ${m[0]}`);
+  if (VULNERABILITY_COMMENT.test(hay)) offending.push('a comment that describes the vulnerability');
+  for (const f of fileNames) {
+    if (CWE_FILENAME.test(String(f))) offending.push(`weakness-bearing file name: ${f}`);
+    if (ANSWER_KEY_FILENAME.test(String(f))) offending.push(`answer-key file name: ${f}`);
+  }
   return { ok: offending.length === 0, offendingTerms: offending };
 }
 

package/src/posture/rule-compiler/proposal.js

@@ -0,0 +1,137 @@
+// The synthesis loop for the rule compiler (PRD 3, requirement 5): propose, compile, test positives, test negatives, mutation test,
+// score, revise, repeat with bounded attempts, emit a candidate.
+//
+// "Models propose rules. Evidence promotes rules." A model's proposal (a `match` in the spec) is tried first when there is one.
+// When there is none, or it fails, this module proposes deterministically from the two pieces of evidence it has: the vulnerable
+// code and its patched twin. The lines that exist only in the vulnerable version say what the flaw looks like; the calls that exist
+// only in the patched version say what a safe version looks like (and become the `notMatch` that keeps the rule quiet on safe files).
+// No model is consulted here and nothing here promotes a rule: the loop returns attempts and a best candidate, and promotion stays
+// with the gate and the lifecycle ledger.
+//
+// Every attempt is scored against the real corpus (positives with their mutations, negatives with theirs) by the same matcher the
+// rule will run on once promoted. An attempt that does not clear the gate is revised from WHY it failed: low recall generalizes,
+// a negative that fires adds the safe version's names to `notMatch`.
+import { draftRuleIR, validateRuleIR } from './ir.js';
+import { buildCorpus } from './corpus.js';
+import { evaluateRule } from './promotion.js';
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\\/]/g, '\\$&');
+const KEYWORDS = new Set(['if', 'else', 'for', 'while', 'return', 'function', 'const', 'let', 'var', 'new', 'await', 'async', 'try', 'catch', 'throw', 'typeof', 'def', 'class', 'import', 'from', 'with', 'in', 'of', 'and', 'or', 'not', 'is', 'func', 'fn', 'public', 'private', 'static', 'void', 'int', 'string']);
+const SOURCES = [
+  String.raw`req(?:uest)?\.(?:body|query|params|headers|cookies)\b`, String.raw`ctx\.(?:query|params|request\.body)\b`, String.raw`request\.(?:args|form|values|json|GET|POST)\b`,
+  String.raw`\$_(?:GET|POST|REQUEST|COOKIE)\b`, String.raw`process\.argv\b`, String.raw`os\.Args\b`, String.raw`\bgetParameter\s*\(`, String.raw`r\.(?:URL\.Query\(\)|FormValue)\b`,
+];
+
+const meaningful = (l) => { const t = l.trim(); return t.length >= 8 && !/^(?:\/\/|#|\/\*|\*|[{}()\];,]+$)/.test(t); };
+
+/** Lines (trimmed) present only in `a`. */
+function onlyIn(a, b) {
+  const bs = new Set(String(b ?? '').split('\n').map((l) => l.trim()));
+  return String(a ?? '').split('\n').filter((l) => meaningful(l) && !bs.has(l.trim())).map((l) => l.trim());
+}
+
+/** Call names (a.b.c) in some code, in order of appearance, without keywords. */
+function callNames(code) {
+  const out = [];
+  for (const m of String(code).matchAll(/\b([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\(/g)) if (!KEYWORDS.has(m[1]) && !out.includes(m[1])) out.push(m[1]);
+  return out;
+}
+
+/** A regular expression for one source line: the call names stay, strings and the other identifiers become classes. */
+export function generalizeLine(line) {
+  const keep = new Set(callNames(line));
+  let out = ''; let i = 0;
+  while (i < line.length) {
+    const c = line[i];
+    if (/\s/.test(c)) { const before = line[i - 1] ?? ''; while (/\s/.test(line[i] ?? '')) i++; out += /[\w$]/.test(before) && /[\w$]/.test(line[i] ?? '') ? String.raw`\s+` : String.raw`\s*`; continue; }
+    if (c === '"' || c === "'" || c === '`') { const q = c; let j = i + 1; while (j < line.length && line[j] !== q) j += line[j] === '\\' ? 2 : 1; out += q === '`' ? '`[^`]*`' : `(?:'[^']*'|"[^"]*")`; i = j + 1; continue; }
+    const id = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*/.exec(line.slice(i));
+    if (id) { const tok = id[0]; const isCall = line[i + tok.length] === '(' || keep.has(tok); out += isCall || KEYWORDS.has(tok) ? esc(tok) : String.raw`[A-Za-z_$][\w$.]*`; i += tok.length; continue; }
+    const num = /^\d+(?:\.\d+)?/.exec(line.slice(i));
+    if (num) { out += String.raw`\d+(?:\.\d+)?`; i += num[0].length; continue; }
+    out += esc(c); i++;
+  }
+  return out;
+}
+
+const sinkOf = (line) => callNames(line).filter((n) => !/^(?:console|logger|log)\b/.test(n))[0] ?? null;
+const interpolation = String.raw`(?:\+|\$\{|%s|%d|\.format\s*\(|\bf["']|\|\|)`;
+
+/** Ordered proposals, most specific first. Each is {strategy, match}; `match.notMatch` is added by `withSafeNames`. */
+export function proposeCandidates({ vulnerableCode, patchedCode = null }) {
+  const vuln = onlyIn(vulnerableCode, patchedCode);
+  const lines = vuln.length ? vuln : String(vulnerableCode).split('\n').filter(meaningful).map((l) => l.trim()).filter((l) => callNames(l).length);
+  const out = []; const seen = new Set();
+  const add = (strategy, match, structure = null) => { const k = JSON.stringify([match, structure]); if (!seen.has(k)) { seen.add(k); out.push({ strategy, ...(match ? { match } : {}), ...(structure ? { structure } : {}) }); } };
+  for (const l of lines.slice(0, 3)) add('line-shape', { pattern: generalizeLine(l) });
+  for (const l of lines.slice(0, 3)) {
+    const sink = sinkOf(l);
+    if (sink) add('sink-with-interpolation', { pattern: `${esc(sink)}\\s*\\([^)\\n]*${interpolation}` });
+  }
+  const sink = lines.map(sinkOf).find(Boolean);
+  const src = SOURCES.find((s) => new RegExp(s).test(vulnerableCode));
+  if (sink && src) add('source-and-sink', { allOf: [`${esc(sink)}\\s*\\(`, src], window: 6 });
+  // the same evidence as an explicit structure: a source and a sink the matcher enforces, so a sanitizer found in the patched code can
+  // later be added as a LOCAL guard (dropping one hit) instead of a file-level exclusion (silencing the whole file)
+  if (sink && src) add('structural', null, { source: src, sink: `${esc(sink)}\\s*\\(`, window: 6 });
+  if (sink) add('sink-call', { pattern: `${esc(sink)}\\s*\\(` });
+  return out;
+}
+
+/** Names that appear in the patched code and not in the vulnerable code: the safe version's vocabulary. */
+export function safeNames({ vulnerableCode, patchedCode }) {
+  if (!patchedCode) return [];
+  const v = new Set(callNames(vulnerableCode));
+  const names = callNames(patchedCode).filter((n) => !v.has(n));
+  if (/\?['"`]?\s*[,)]/.test(patchedCode) && !/\?['"`]?\s*[,)]/.test(vulnerableCode)) names.push('?');
+  return names;
+}
+
+const PLACEHOLDER_RE = '\\?[\'"`]?\\s*[,)]';
+const safeRegex = (names) => (names.length ? names.map((n) => (n === '?' ? PLACEHOLDER_RE : esc(n))).join('|') : null);
+
+const summary = (score) => ({ precision: score.precision, recall: score.recall, tp: score.tp, fp: score.fp, fn: score.fn, tn: score.tn, protectedFailures: score.protectedFailures });
+const quality = (e) => (e.pass ? 10 : 0) + (e.score.precision ?? 0) * (e.score.recall ?? 0) - e.score.protectedFailures * 0.5;
+
+/**
+ * @param {object} o
+ * @param {object} o.base      the IR fields that are not the match: id, title, severity, cwe, family, languages, remediation, evidence
+ * @param {object} o.corpusSpec  { originalCode, patchedCode?, nearbyCleanCode?, protectedVariantsCode? }
+ * @param {object|null} o.proposed  a match supplied by a model or a person, tried first
+ * @returns {{attempts: object[], best: object|null, exhausted: boolean}}
+ */
+export function synthesizeCandidate({ base, corpusSpec, proposed = null, maxAttempts = 6, thresholds, leakageOk = true }) {
+  const cap = Math.max(1, Math.min(12, maxAttempts));
+  const queue = [];
+  if (proposed) queue.push({ strategy: 'proposed', match: proposed });
+  for (const p of proposeCandidates({ vulnerableCode: corpusSpec.originalCode, patchedCode: corpusSpec.patchedCode })) queue.push(p);
+  const names = safeNames({ vulnerableCode: corpusSpec.originalCode, patchedCode: corpusSpec.patchedCode });
+  const attempts = []; const tried = new Set();
+  const tryOne = (strategy, match, structure = null) => {
+    const key = JSON.stringify([match, structure]);
+    if (tried.has(key) || attempts.length >= cap) return null;
+    tried.add(key);
+    const ir = draftRuleIR({ ...base, ...(match ? { match } : {}), ...(structure ?? {}) });
+    const errs = validateRuleIR(ir);
+    if (errs.length) { attempts.push({ n: attempts.length + 1, strategy, match: match ?? null, structure, valid: false, errors: errs, pass: false, reasons: errs }); return null; }
+    const corpus = buildCorpus(ir, corpusSpec);
+    const ev = evaluateRule(ir, corpus, thresholds);
+    const rec = { n: attempts.length + 1, strategy, match: match ?? null, structure, valid: true, pass: ev.pass && leakageOk, reasons: ev.reasons, score: summary(ev.score), ir, corpusSizes: { positives: corpus.positives.length, negatives: corpus.negatives.length } };
+    attempts.push(rec);
+    return { rec, ev };
+  };
+  for (let qi = 0; qi < queue.length && attempts.length < cap; qi++) {
+    const q = queue[qi];
+    const first = tryOne(q.strategy, q.match, q.structure);
+    if (!first) continue;
+    if (first.rec.pass) break;
+    // revise from the failure: a negative that fired means the safe version is not excluded yet
+    const fired = first.ev.score.negatives.filter((n) => n.fired);
+    const rx = safeRegex(names);
+    if (fired.length && rx && q.structure && !q.structure.sanitizer) { const r = tryOne(`${q.strategy}+sanitizer`, null, { ...q.structure, sanitizer: rx }); if (r?.rec.pass) break; }
+    else if (fired.length && rx && q.match && !q.match.notMatch) { const r = tryOne(`${q.strategy}+exclude-safe`, { ...q.match, notMatch: rx }); if (r?.rec.pass) break; }
+  }
+  const valid = attempts.filter((a) => a.valid);
+  const best = valid.length ? [...valid].sort((a, b) => quality({ pass: b.pass, score: b.score }) - quality({ pass: a.pass, score: a.score }))[0] : null;
+  return { attempts: attempts.map(({ ir, ...rest }) => rest), best: best ? { strategy: best.strategy, match: best.match, structure: best.structure, pass: best.pass, score: best.score, reasons: best.reasons } : null, exhausted: !attempts.some((a) => a.pass) };
+}