@clear-capabilities/agentic-security-scanner 0.160.0 → 0.162.0

package/src/posture/verification/emit.js

@@ -0,0 +1,257 @@
+// The single emit function for the one verification record (X-201).
+//
+// Every surface that verifies something (fix verification, the closed fix loop,
+// execution proof, the verifier verdicts, autopilot, hunt, the trusted oracle
+// adapters) calls `emitVerification(surface, source, ctx)` and gets back a
+// version-1 record from `assurance/verification-record.js`. The surface keeps
+// producing its own native fields; the record is ADDITIVE (callers attach it
+// under `verificationRecord`) so no existing consumer changes.
+//
+// The rule that governs every mapping here is the one CORE-002 states: evidence
+// can be lost in translation but never invented. Each surface's native result
+// lands on the strongest outcome its OWN evidence supports, and none of the
+// legacy surfaces ran under the trusted boundary, so none of them can reach
+// `confirmed` or `refuted` through this function:
+//   - a PoC that ran under the older sandbox path is `inconclusive` (the older
+//     path is not a trusted runner; re-verify under an oracle adapter to confirm);
+//   - a PoC that ran and did not fire is `inconclusive`, never `refuted`;
+//   - a model verdict is recorded as `inference` evidence and nothing more;
+//   - a surface that executed nothing (static legs only) is `not-run`;
+//   - a family or class with no oracle is `unsupported`, a harness failure `error`.
+// `confirmed`/`refuted` records come only from `oracle` emissions, whose caller
+// (`oracles/oracle.js`) supplies trusted-runner evidence produced by the
+// verifier domain. This function validates before it returns and never throws.
+import { spawnSync } from 'node:child_process';
+import { buildVerificationRecord, validateVerificationRecord } from '../assurance/verification-record.js';
+import { legacyVerificationOutcome, toLegacyVerificationView } from '../assurance/migrations.js';
+import { digestOf, hypothesisIdFromFinding } from '../assurance/identity.js';
+import { isCommit, isPlainObject } from '../assurance/schema-kit.js';
+import { judgeNonTaintHypothesis } from '../oracles/scenario-classes.js';
+
+export const SURFACES = Object.freeze([
+  'fix-verify', 'fix-verify-loop', 'execution-proof', 'verifier', 'autopilot', 'hunt', 'oracle',
+]);
+
+const POC_ORACLE = Object.freeze({ id: 'poc-marker-replay', kind: 'runtime-replay', version: '1' });
+const TAINT_ORACLE = Object.freeze({ id: 'taint-engine-confirmation', kind: 'static-proof', version: '1' });
+const SANITIZER_ORACLE = Object.freeze({ id: 'sanitizer-absence-window', kind: 'static-proof', version: '1' });
+
+/** HEAD of `root`, or null when it is not a git work tree. Bounded; never throws. */
+export function headCommit(root) {
+  if (!root || typeof root !== 'string') return null;
+  try {
+    const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', timeout: 2000 });
+    const out = String(r.stdout || '').trim();
+    return r.status === 0 && isCommit(out) ? out : null;
+  } catch { return null; }
+}
+
+function detectorOriginOf(finding, ctx) {
+  if (isPlainObject(ctx.detectorOrigin)) return ctx.detectorOrigin;
+  const f = finding || {};
+  const origin = { detector: String(f.ruleId || f.vuln || f.id || f.parser || 'unknown') };
+  if (typeof f.family === 'string' && f.family) origin.family = f.family;
+  if (typeof f.parser === 'string' && f.parser) origin.parser = f.parser;
+  return origin;
+}
+
+const observation = (id, source, value) => ({ id, kind: 'observation', producer: 'tool', digest: digestOf(value ?? null), source });
+const inference = (id, source, value) => ({ id, kind: 'inference', producer: 'model', digest: digestOf(value ?? null), source });
+
+function scopeOf(description, backend) {
+  const scope = { description, platform: process.platform };
+  if (backend && typeof backend === 'string') scope.backend = backend;
+  return scope;
+}
+
+// ------------------------------------------------------------ per-surface mappers
+
+function mapFixVerify(r, ctx) {
+  const files = ctx.files && typeof ctx.files === 'object' ? ctx.files : null;
+  const repair = files ? { status: 'proposed', patchDigest: digestOf(files) } : { status: 'none' };
+  const legs = {
+    rescan: { ok: r?.rescan?.ok ?? null, reason: r?.rescan?.reason ?? null },
+    lint: { ok: r?.lint?.ok ?? null, runner: r?.lint?.runner ?? null, skipped: !!r?.lint?.skipped },
+    tests: { passed: r?.tests?.passed ?? null, skipped: !!r?.tests?.skipped },
+    poc: { status: r?.poc?.status ?? 'not-requested', tier: r?.poc?.tier ?? null },
+  };
+  const evidence = [observation('legs', 'fix-verify legs', legs)];
+  const legText = `re-scan ${legs.rescan.ok ? 'passed' : 'failed'}, lint ${legs.lint.skipped ? 'skipped' : legs.lint.ok ? 'passed' : 'failed'}, tests ${legs.tests.skipped ? 'skipped' : legs.tests.passed ? 'passed' : 'failed'}`;
+  const base = { repair, evidence, scope: scopeOf('candidate patch re-verification (hypothesis: the vulnerability is still present on the patched tree)', r?.poc?.backend) };
+  if (!files || legs.rescan.reason === 'no-files-provided') {
+    return { ...base, outcome: 'not-run', reason: 'no candidate patch files were supplied, so nothing was verified', attempt: 0, oracle: null, preconditions: { valid: false } };
+  }
+  if (legs.rescan.reason === 'rescan-failed') {
+    return { ...base, outcome: 'error', reason: 'the verification re-scan failed to run', attempt: 1, oracle: null, preconditions: { valid: false } };
+  }
+  const p = legs.poc.status;
+  if (p === 'not-requested') {
+    return {
+      ...base, outcome: 'not-run', attempt: 0, oracle: null, preconditions: { valid: false },
+      reason: `no exploit oracle was executed against the patch; only detector-level and project-test legs ran (${legText})`,
+    };
+  }
+  // The leg's own free text (it can echo scanned source) is deliberately not copied into the record's reason.
+  if (p === 'inconclusive') {
+    return { ...base, outcome: 'inconclusive', attempt: 1, oracle: POC_ORACLE, preconditions: { valid: false },
+      reason: `the proof-of-concept leg did not complete, so nothing was established about the patch (${legText})` };
+  }
+  const mapped = legacyVerificationOutcome({ proofEvidence: { tier: p === 'still-exploitable' ? 'execution-proven' : 'proof-failed', ran: true } });
+  return {
+    ...base, outcome: mapped.outcome, attempt: 1, oracle: POC_ORACLE, preconditions: { valid: true },
+    // The leg's native status word ('fixed') is not echoed: it would read as a generic fixed label on a result that decided nothing.
+    reason: `proof-of-concept leg ${p === 'still-exploitable' ? 'reproduced the effect' : 'did not reproduce the effect'}: ${mapped.reason} (${legText})`,
+  };
+}
+
+function mapFixLoop(r, ctx) {
+  const files = ctx.files && typeof ctx.files === 'object' ? ctx.files : null;
+  const repair = files ? { status: 'proposed', patchDigest: digestOf(files) } : { status: 'none' };
+  const legs = r?.legs || {};
+  const evidence = [observation('legs', 'fix-verify-loop legs', {
+    scan: legs.scan?.ok ?? null, lint: legs.lint?.ok ?? null, tests: { ok: legs.tests?.ok ?? null, skipped: !!legs.tests?.skipped }, verdict: r?.verdict ?? null,
+  })];
+  const base = { repair, evidence, scope: scopeOf('closed-loop fix verification (scan, lint, project tests)', null), oracle: null, preconditions: { valid: false } };
+  if (!files) return { ...base, outcome: 'not-run', attempt: 0, reason: 'no candidate patch files were supplied, so nothing was verified' };
+  if (legs.scan?.detail?.reason === 'rescan-failed') return { ...base, outcome: 'error', attempt: 1, reason: 'the verification re-scan failed to run' };
+  return {
+    ...base, outcome: 'not-run', attempt: 0,
+    reason: `loop verdict '${r?.verdict ?? 'unknown'}': the loop runs the detector, linter and project tests; no exploit oracle ran against the patch`,
+  };
+}
+
+function mapExecutionProof(finding) {
+  const pe = isPlainObject(finding?.proofEvidence) ? finding.proofEvidence : null;
+  if (!pe) return { outcome: 'not-run', attempt: 0, reason: 'no execution-proof evidence is attached to this finding', oracle: null, evidence: [], preconditions: { valid: false }, scope: scopeOf('execution proof (no evidence attached)', null) };
+  const m = legacyVerificationOutcome({ proofEvidence: pe });
+  const ran = pe.ran === true;
+  return {
+    outcome: m.outcome, reason: m.reason, attempt: ['not-run', 'unsupported'].includes(m.outcome) ? 0 : 1,
+    oracle: ran ? POC_ORACLE : null,
+    evidence: ran ? [observation('proof-evidence', 'execution-proof sandbox run', { tier: pe.tier, backend: pe.backend ?? null, observed: pe.observed ?? null, exitCode: pe.exitCode ?? null })] : [],
+    preconditions: { valid: ran },
+    scope: scopeOf(`proof-of-concept execution (${pe.proofKind || 'in-process marker proof'})`, pe.backend),
+  };
+}
+
+// verifier.js verdicts. `cannot-verify` carries its cause in the reason string; the cause decides the state.
+function mapVerifierVerdict(finding) {
+  const verdict = finding?.verifier_verdict;
+  const reason = String(finding?.verifier_reason || '');
+  const scope = scopeOf(`verifier verdict '${verdict}'`, finding?.verifier_runner);
+  const none = { oracle: null, evidence: [], preconditions: { valid: false }, scope };
+  switch (verdict) {
+    case 'verified-exploit':
+      return { ...none, outcome: 'inconclusive', attempt: 1, oracle: POC_ORACLE, preconditions: { valid: true },
+        evidence: [observation('poc-exit', 'verifier live PoC run', { reason })],
+        reason: 'the PoC exited 0 against the caller-provided target under the older confined runner; an exit code is not trusted runtime proof, so this is not carried forward as confirmed' };
+    case 'verified-by-llm':
+      return { ...none, outcome: 'inconclusive', attempt: 1, evidence: [inference('llm-accept', 'layer-3 validator', { reason })],
+        reason: 'a model accepted the finding; a model verdict alone is an inference and never confirms' };
+    case 'verified-sanitizer-absence':
+      return { ...none, outcome: 'inconclusive', attempt: 1, oracle: SANITIZER_ORACLE, evidence: [observation('sanitizer-window', 'sanitizer-absence window scan', { reason })],
+        reason: `no sanitizer was found in the source window (${reason}); a static absence check does not execute anything` };
+    case 'unverified-by-design':
+      return { ...none, outcome: 'unsupported', attempt: 0, reason: `this vulnerability family has no verification oracle (${reason})` };
+    case 'cannot-verify': {
+      if (/^verifier-exception/.test(reason) || /^sandbox-error/.test(reason)) return { ...none, outcome: 'error', attempt: 1, reason };
+      if (/confinement primitive|disabled/.test(reason)) return { ...none, outcome: 'unsupported', attempt: 0, reason };
+      if (/^poc-timeout|^poc-exit/.test(reason)) return { ...none, outcome: 'inconclusive', attempt: 1, oracle: POC_ORACLE, preconditions: { valid: true }, reason: `${reason}: the PoC ran but did not demonstrate the effect; absence of proof is not refutation` };
+      if (/^no-poc-no-sanitizer-rule/.test(reason)) return { ...none, outcome: 'unsupported', attempt: 0, reason: 'neither a PoC nor a sanitizer rule exists for this finding, so no oracle applies' };
+      return { ...none, outcome: 'not-run', attempt: 0, reason: reason || 'the verifier did not run' };
+    }
+    default:
+      return { ...none, outcome: 'not-run', attempt: 0, reason: 'the finding carries no verifier verdict' };
+  }
+}
+
+function mapAutopilot(rec, ctx) {
+  const patch = ctx.patch && typeof ctx.patch === 'object' ? ctx.patch : null;
+  const repairStatus = rec?.applied === true ? 'applied' : patch ? 'proposed' : 'none';
+  const repair = patch ? { status: repairStatus, patchDigest: digestOf(patch) } : { status: 'none' };
+  const evidence = [observation('autopilot-stage', 'autopilot stage outcome', {
+    outcome: rec?.outcome ?? null, proofTier: rec?.proofTier ?? null, pocStillFires: rec?.pocStillFires ?? null, testsPass: rec?.testsPass ?? null, validation: rec?.validation ?? null,
+  })];
+  const scope = scopeOf('autopilot scan, prove, validate, fix, re-verify chain', null);
+  const base = { repair, evidence, scope, oracle: null, preconditions: { valid: false } };
+  if (rec?.validation === 'refuted') {
+    return { ...base, outcome: 'inconclusive', attempt: 1, evidence: [...evidence, inference('validator-refutation', 'autopilot validate stage', { validation: rec.validation })],
+      reason: 'a validator voted to refute the finding; a validator verdict is not an applicable oracle, so this is not a refutation' };
+  }
+  if (rec?.outcome === 'UNPROVEN') {
+    return rec.proofTier === 'proof-failed'
+      ? { ...base, outcome: 'inconclusive', attempt: 1, oracle: POC_ORACLE, preconditions: { valid: true }, reason: 'the proof-of-concept ran and did not demonstrate the effect; absence of proof is not refutation' }
+      : { ...base, outcome: 'not-run', attempt: 0, reason: String(rec.reason || 'no proof-of-concept ran for this finding') };
+  }
+  if (rec?.outcome === 'NO_FIX') return { ...base, outcome: 'inconclusive', attempt: 1, oracle: POC_ORACLE, preconditions: { valid: true }, reason: 'the finding was proved by the older runner but no patch was synthesised, so no re-verification ran' };
+  if (rec?.pocStillFires === true) return { ...base, outcome: 'inconclusive', attempt: 1, oracle: POC_ORACLE, preconditions: { valid: true }, reason: 'the proof-of-concept still fires against the patch under the older runner' };
+  if (rec?.outcome === 'VERIFIED_FIXED') return { ...base, outcome: 'inconclusive', attempt: 1, oracle: POC_ORACLE, preconditions: { valid: true }, reason: 'the proof-of-concept no longer fires against the patch under the older runner; that is not a trusted exploit-negative result' };
+  return { ...base, outcome: 'inconclusive', attempt: 1, reason: String(rec?.reason || 'the patch did not re-verify') };
+}
+
+function mapHunt(finding) {
+  const d = isPlainObject(finding?.discovery) ? finding.discovery : {};
+  const tier = d.confirmation?.tier || 'unconfirmed';
+  const scope = scopeOf(`hunt candidate from the ${d.lens || 'unknown'} lens (advisory)`, null);
+  const evidence = [];
+  if (d.refutation) evidence.push(inference('refutation-panel', 'refutation panel votes', d.refutation));
+  // X-205: a non-taint hypothesis (a tenant check, a privileged action, workflow order, replay, resource use) is not judged by
+  // a taint probe in EITHER direction. Without an executed oracle of its own class it is `not-run` (or `unsupported`).
+  const nonTaint = judgeNonTaintHypothesis({ finding, taint: { clean: !(tier === 'taint-confirmed' || tier === 'sink-adjacent') } });
+  if (nonTaint.nonTaint) {
+    return { outcome: nonTaint.outcome, attempt: 0, oracle: null, evidence, preconditions: { valid: false }, scope, reason: nonTaint.reason };
+  }
+  if (tier === 'taint-confirmed' || tier === 'sink-adjacent') {
+    evidence.unshift(observation('taint-probe', 'deterministic taint probe', d.confirmation));
+    return { outcome: 'inconclusive', attempt: 1, oracle: TAINT_ORACLE, evidence, preconditions: { valid: true }, scope,
+      reason: `the deterministic taint probe corroborated this candidate at tier '${tier}'; a static probe is corroboration, not execution` };
+  }
+  return { outcome: 'not-run', attempt: 0, oracle: null, evidence, preconditions: { valid: false }, scope,
+    reason: String(d.confirmation?.reason || 'the candidate was not corroborated by any deterministic probe; no oracle ran') };
+}
+
+const MAPPERS = Object.freeze({
+  'fix-verify': (s, ctx) => mapFixVerify(s, ctx),
+  'fix-verify-loop': (s, ctx) => mapFixLoop(s, ctx),
+  'execution-proof': (s) => mapExecutionProof(s),
+  verifier: (s) => mapVerifierVerdict(s),
+  autopilot: (s, ctx) => mapAutopilot(s, ctx),
+  hunt: (s) => mapHunt(s),
+});
+
+/**
+ * Emit the version-1 verification record for one surface result.
+ *
+ * @param {string} surface one of SURFACES
+ * @param {object} source  the surface's native result (see each mapper)
+ * @param {object} [ctx]   { finding, hypothesisId, commit, scanRoot, files, patch, detectorOrigin }
+ *   `oracle` emissions pass `ctx.fields`: the record fields the oracle runner
+ *   built (including trusted-runner evidence). Nothing else can supply them.
+ * @returns {{ ok: boolean, record: object|null, legacy: object|null, errors: object[] }} never throws
+ */
+export function emitVerification(surface, source, ctx = {}) {
+  try {
+    if (!SURFACES.includes(surface)) return fail('UNKNOWN_ENUM', `unknown verification surface '${surface}'`);
+    const finding = ctx.finding || (surface === 'execution-proof' || surface === 'verifier' || surface === 'hunt' ? source : null);
+    const hypothesisId = ctx.hypothesisId || ctx.originalFindingStableId || hypothesisIdFromFinding(finding);
+    if (!hypothesisId) return fail('MISSING_FIELD', 'a verification record needs a hypothesis id (a finding stableId); it is not guessed');
+    const commit = ctx.commit !== undefined ? (isCommit(ctx.commit) ? ctx.commit : null) : headCommit(ctx.scanRoot);
+    let fields;
+    if (surface === 'oracle') {
+      if (!isPlainObject(ctx.fields)) return fail('MISSING_FIELD', 'an oracle emission needs the fields built by the oracle runner');
+      fields = ctx.fields;
+    } else {
+      fields = MAPPERS[surface](source, ctx);
+    }
+    const record = buildVerificationRecord({
+      ...fields, hypothesisId, commit, detectorOrigin: detectorOriginOf(finding, ctx),
+    });
+    const v = validateVerificationRecord(record);
+    if (!v.ok) return { ok: false, record: null, legacy: null, errors: v.errors };
+    return { ok: true, record, legacy: toLegacyVerificationView(record), errors: [] };
+  } catch (e) {
+    return fail('RULE_VIOLATION', `verification record emission failed: ${String(e?.message || e).slice(0, 200)}`);
+  }
+}
+
+function fail(code, message) { return { ok: false, record: null, legacy: null, errors: [{ code, path: '', message }] }; }

package/src/posture/verification/hypothesis-promotion.js

@@ -0,0 +1,211 @@
+// Promoting an advisory hypothesis into a finding (X-207.AC02, AC03).
+//
+// A hunt hypothesis is advisory. It becomes a FINDING only through `promoteHypothesis`, which needs all three of:
+//
+//   1. a trusted verifier receipt, VERIFIED here (not merely present): issued by `runOracle` in this process
+//      (`isIssuedReceipt`: a copy, a JSON round trip or a hand-built object is not), bound to this hypothesis and one exact
+//      commit, carrying a valid version-1 record whose id is the receipt's `recordId`, settled `confirmed` at the
+//      `runtime-confirmed` level with trusted-runtime-proof evidence from the trusted runner;
+//   2. an explicit policy evaluation. The caller passes a policy; the result carries every rule that was evaluated with its
+//      outcome and a digest of the policy. The mandatory rules cannot be removed by a policy, and a policy key this module does
+//      not know is refused (fail closed);
+//   3. an audit record, returned for EVERY decision (promoted or not), that links the source hypothesis to the promoted finding
+//      (or to none) and names the receipt, the record and the policy evaluation. It carries no clock, so identical inputs give
+//      an identical record.
+//
+// What can never satisfy the policy: a confidence score, a repeated or unanimous model agreement, a refutation panel's votes,
+// a taint-probe tier, or a severity. None of them is an input to any rule except the optional `minConfidence` / `minAgreement`
+// rules, which can only ADD a requirement: the receipt rules are always evaluated, so a hypothesis with perfect confidence and
+// no receipt is rejected, and a policy made only of those rules still rejects it.
+//
+// The producer of a hunt hypothesis and the verifier that confirms it must be different parties (`verification-separation.js`
+// is reused for that check). The audit record is returned, not persisted: persisting an audit trail needs an artifact-registry
+// classification and a signing domain, which are not decided here.
+import { isIssuedReceipt, ORACLE_CLASSES } from '../oracles/oracle.js';
+import { validateVerificationRecord } from '../assurance/verification-record.js';
+import { digestOf, hypothesisIdFromFinding, semanticId } from '../assurance/identity.js';
+import { isPlainObject } from '../assurance/schema-kit.js';
+import { recordProducer, assertSeparation } from '../verification-separation.js';
+import { isAdvisoryHypothesis } from './advisory-state.js';
+
+export const AUDIT_SCHEMA = 'agentic-security/promotion-audit';
+const AUDIT_VERSION = '1.0.0';
+export const POLICY_SCHEMA = 'agentic-security/promotion-policy';
+
+export const DECISIONS = Object.freeze(['promoted', 'rejected', 'unsupported', 'inconclusive']);
+const SEVERITY_ORDER = ['info', 'low', 'medium', 'high', 'critical'];
+
+/** The default policy: runtime-confirmed by a class oracle other than the functional-regression one, severity capped at high. */
+export const DEFAULT_PROMOTION_POLICY = Object.freeze({
+  schema: POLICY_SCHEMA, id: 'default', version: '1',
+  allowedOracleClasses: Object.freeze(ORACLE_CLASSES.filter((c) => c !== 'functional-regression')),
+  maxSeverity: 'high',
+});
+
+const POLICY_KEYS = ['schema', 'id', 'version', 'allowedOracleClasses', 'maxSeverity', 'expectedCommit', 'minConfidence', 'minAgreement'];
+
+const PROMOTED = new WeakSet();
+/** True only for a finding `promoteHypothesis` itself returned. */
+export function isPromotedFinding(f) { return isPlainObject(f) && PROMOTED.has(f); }
+
+function validatePolicy(policy) {
+  if (!isPlainObject(policy)) return ['no policy was supplied: promotion needs an explicit policy evaluation'];
+  const errs = [];
+  for (const k of Object.keys(policy)) if (!POLICY_KEYS.includes(k)) errs.push(`unknown policy key '${k}'`);
+  if (policy.schema !== POLICY_SCHEMA) errs.push(`policy.schema must be '${POLICY_SCHEMA}'`);
+  if (typeof policy.id !== 'string' || !policy.id) errs.push('policy.id is required');
+  if (typeof policy.version !== 'string' || !policy.version) errs.push('policy.version is required');
+  if (!Array.isArray(policy.allowedOracleClasses) || policy.allowedOracleClasses.length === 0 || !policy.allowedOracleClasses.every((c) => ORACLE_CLASSES.includes(c))) errs.push('policy.allowedOracleClasses must list known oracle classes');
+  if (!SEVERITY_ORDER.includes(policy.maxSeverity)) errs.push('policy.maxSeverity must be a severity');
+  if (policy.expectedCommit !== undefined && !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(String(policy.expectedCommit))) errs.push('policy.expectedCommit must be an exact commit');
+  for (const k of ['minConfidence', 'minAgreement']) if (policy[k] !== undefined && !(typeof policy[k] === 'number' && policy[k] >= 0 && policy[k] <= 1)) errs.push(`policy.${k} must be a number between 0 and 1`);
+  return errs;
+}
+
+function agreementOf(h) {
+  const votes = h?.discovery?.refutation?.votes;
+  if (!Array.isArray(votes) || votes.length === 0) return null;
+  const upheld = votes.filter((v) => v && (v.verdict === 'upheld' || v.upheld === true)).length;
+  return upheld / votes.length;
+}
+
+/**
+ * Evaluate the policy for one hypothesis and one oracle result. Every rule is evaluated and listed.
+ * @returns {{ ok: boolean, rules: {id: string, pass: boolean, detail: string}[], status: string, policyDigest: string|null, record: object|null }}
+ */
+export function evaluatePromotionPolicy({ hypothesis, result, policy } = {}) {
+  const rules = [];
+  const rule = (id, pass, detail) => rules.push({ id, pass: !!pass, detail });
+  const bad = validatePolicy(policy);
+  if (bad.length) {
+    rule('policy-valid', false, bad.join('; '));
+    return { ok: false, rules, status: 'rejected', policyDigest: null, record: null };
+  }
+  rule('policy-valid', true, `policy '${policy.id}' v${policy.version}`);
+  const policyDigest = digestOf(policy);
+
+  const receipt = result?.receipt ?? null;
+  const record = result?.record ?? null;
+  const hypothesisId = isPlainObject(hypothesis) ? hypothesisIdFromFinding(hypothesis) : null;
+
+  rule('hypothesis-advisory', isAdvisoryHypothesis(hypothesis) && !!hypothesisId, 'the source must be an unpromoted hunt hypothesis with a stable id');
+  const issued = isIssuedReceipt(receipt) && receipt.issuedBy === 'verifier' && receipt.schema === 'agentic-security/oracle-receipt';
+  rule('receipt-issued', issued, issued ? 'the receipt was issued by the verifier domain in this process' : 'no receipt issued by the verifier domain was supplied (a copy, a parsed file or a constructed object is not valid)');
+
+  const recordOk = isPlainObject(record) && validateVerificationRecord(record).ok;
+  rule('record-valid', recordOk, recordOk ? 'the verification record validates' : 'the verification record is missing or invalid');
+  const bound = issued && recordOk && receipt.recordId === record.id && receipt.request.hypothesisId === hypothesisId && record.hypothesisId === hypothesisId;
+  rule('receipt-binds-hypothesis', bound, bound ? 'the receipt, the record and the hypothesis name one another' : 'the receipt or record is for a different hypothesis, or they do not reference each other');
+  const commit = issued ? receipt.request.commit : null;
+  rule('commit-bound', !!commit && (!policy.expectedCommit || policy.expectedCommit === commit) && recordOk && record.commit === commit,
+    commit ? (policy.expectedCommit && policy.expectedCommit !== commit ? `the receipt is for a different commit than the policy expects` : 'the receipt is bound to one exact commit') : 'the receipt is not bound to an exact commit');
+
+  const outcome = bound ? receipt.settled.outcome : null;
+  rule('outcome-confirmed', outcome === 'confirmed', `the verifier settled '${outcome ?? 'nothing'}'`);
+  const runtime = bound && record.confirmationLevel === 'runtime-confirmed'
+    && record.evidence.some((e) => e.kind === 'trusted-runtime-proof' && e.producer === 'trusted-runner' && record.evidenceRefs.includes(e.id));
+  rule('runtime-confirmed', runtime, runtime ? 'trusted runtime proof from the trusted runner is referenced' : 'no referenced trusted runtime proof at the runtime-confirmed level');
+  const classOk = bound && policy.allowedOracleClasses.includes(receipt.oracle.class);
+  rule('class-allowed', classOk, classOk ? `oracle class '${receipt.oracle.class}' is allowed` : 'the oracle class is not allowed by the policy');
+
+  // producer and verifier must be different parties
+  const probe = { ...hypothesis };
+  let sep = { ok: false, reason: 'no receipt' };
+  if (bound) {
+    const stamped = recordProducer(probe, `hunter:${hypothesis?.discovery?.lens ?? 'unknown'}`);
+    sep = stamped.ok ? assertSeparation(probe, `verifier:oracle:${receipt.oracle.id}`) : stamped;
+  }
+  rule('producer-verifier-separation', sep.ok, sep.ok ? 'the hunter and the verifying oracle are different parties' : String(sep.reason));
+
+  // additive-only rules: they can add a requirement, never satisfy one
+  if (policy.minConfidence !== undefined) {
+    const c = typeof hypothesis?.confidence === 'number' ? hypothesis.confidence : null;
+    rule('min-confidence', c !== null && c >= policy.minConfidence, `an additional requirement only: confidence ${c ?? 'absent'} against ${policy.minConfidence}`);
+  }
+  if (policy.minAgreement !== undefined) {
+    const a = agreementOf(hypothesis);
+    rule('min-agreement', a !== null && a >= policy.minAgreement, `an additional requirement only: panel agreement ${a ?? 'absent'} against ${policy.minAgreement}`);
+  }
+
+  const ok = rules.every((r) => r.pass);
+  let status = 'promoted';
+  if (!ok) {
+    const settled = bound ? outcome : (isPlainObject(record) && typeof record.outcome === 'string' ? record.outcome : null);
+    if (settled === 'unsupported') status = 'unsupported';
+    else if (['inconclusive', 'not-run', 'error'].includes(settled)) status = 'inconclusive';
+    else status = 'rejected';
+  }
+  return { ok, rules, status, policyDigest, record: recordOk ? record : null };
+}
+
+const capSeverity = (sev, max) => (SEVERITY_ORDER.indexOf(sev) > SEVERITY_ORDER.indexOf(max) ? max : (SEVERITY_ORDER.includes(sev) ? sev : max));
+
+/**
+ * Promote one hypothesis, or decline to. Never throws.
+ *
+ * @param {object} args
+ * @param {object} args.hypothesis  a hunt finding (`discovery/judge.js` shape)
+ * @param {object} args.result      the `runOracle` result for it (`{ record, receipt, outcome }`)
+ * @param {object} args.policy      an explicit policy (see DEFAULT_PROMOTION_POLICY)
+ * @returns {{ ok: boolean, decision: string, finding: object|null, audit: object, evaluation: object }}
+ */
+export function promoteHypothesis({ hypothesis, result, policy } = {}) {
+  let evaluation;
+  try { evaluation = evaluatePromotionPolicy({ hypothesis, result, policy }); }
+  catch (e) { evaluation = { ok: false, status: 'rejected', policyDigest: null, record: null, rules: [{ id: 'evaluation', pass: false, detail: `the policy evaluation failed: ${String(e?.message || e).slice(0, 120)}` }] }; }
+  const hypothesisId = isPlainObject(hypothesis) ? hypothesisIdFromFinding(hypothesis) : null;
+  const decision = evaluation.ok ? 'promoted' : evaluation.status;
+
+  let finding = null;
+  if (evaluation.ok) {
+    const h = hypothesis;
+    const base = {
+      id: `promoted-${hypothesisId}`, stableId: hypothesisId,
+      severity: capSeverity(h.severity, policy.maxSeverity),
+      file: h.file, line: h.line, vuln: h.vuln, cwe: h.cwe, description: h.description, remediation: h.remediation,
+      // A promoted finding is no longer a hunt hypothesis: it carries neither the hunt parser nor the `discovery` stamp, so the
+      // advisory exclusion does not apply to it, and its origin lives in `promotedFrom`.
+      parser: 'PROMOTED-HYPOTHESIS', family: h.family ?? 'other', ruleId: h.ruleId ?? 'promoted-hypothesis', snippet: h.snippet ?? '',
+    };
+    finding = { ...base, verificationRecord: JSON.parse(JSON.stringify(evaluation.record)) };
+  }
+
+  const audit = {
+    schema: AUDIT_SCHEMA, schemaVersion: AUDIT_VERSION, decision,
+    sourceHypothesis: {
+      id: hypothesisId, digest: digestOf(isPlainObject(hypothesis) ? hypothesis : null),
+      origin: { lens: hypothesis?.discovery?.lens ?? null, parser: hypothesis?.parser ?? null, family: hypothesis?.family ?? null },
+    },
+    promotedFinding: finding ? { stableId: finding.stableId, id: finding.id } : null,
+    verification: {
+      recordId: evaluation.record?.id ?? null, receiptDigest: isIssuedReceipt(result?.receipt) ? result.receipt.receiptDigest : null,
+      oracle: evaluation.record?.oracle ?? null, outcome: evaluation.record?.outcome ?? null,
+      confirmationLevel: evaluation.record?.confirmationLevel ?? null, commit: evaluation.record?.commit ?? null,
+    },
+    policy: { id: isPlainObject(policy) ? policy.id ?? null : null, version: isPlainObject(policy) ? policy.version ?? null : null, digest: evaluation.policyDigest, rules: evaluation.rules },
+  };
+  audit.id = semanticId('padt', audit, ['decision', 'sourceHypothesis', 'promotedFinding', 'verification', 'policy']);
+  deepFreeze(audit);
+  if (finding) {
+    finding.promotedFrom = { hypothesisId, auditId: audit.id, lens: hypothesis?.discovery?.lens ?? null };
+    deepFreeze(finding);
+    PROMOTED.add(finding);
+  }
+  return { ok: !!finding, decision, finding, audit, evaluation };
+}
+
+/** Do an audit record, the hypothesis it names and the promoted finding it names agree? (The link, checked from both ends.) */
+export function auditLinksHold({ audit, hypothesis, finding }) {
+  if (!isPlainObject(audit) || audit.schema !== AUDIT_SCHEMA) return false;
+  const hid = isPlainObject(hypothesis) ? hypothesisIdFromFinding(hypothesis) : null;
+  if (!hid || audit.sourceHypothesis?.id !== hid || audit.sourceHypothesis?.digest !== digestOf(hypothesis)) return false;
+  if (audit.id !== semanticId('padt', audit, ['decision', 'sourceHypothesis', 'promotedFinding', 'verification', 'policy'])) return false;
+  if (audit.decision !== 'promoted') return finding == null && audit.promotedFinding === null;
+  return isPromotedFinding(finding) && finding.promotedFrom?.auditId === audit.id && finding.promotedFrom?.hypothesisId === hid
+    && audit.promotedFinding?.stableId === finding.stableId && finding.verificationRecord?.id === audit.verification.recordId;
+}
+
+function deepFreeze(o) {
+  for (const v of Object.values(o)) if (v && typeof v === 'object' && !Object.isFrozen(v)) deepFreeze(v);
+  return Object.freeze(o);
+}