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

package/src/posture/evaluation/protocol.js

@@ -0,0 +1,308 @@
+// Frozen current-engine evaluation protocol (QA-001).
+//
+// A protocol is the thing registered BEFORE any result is looked at: dataset
+// scope, thresholds, matching rules, budgets and split membership. Its hash is
+// computed over every semantic field, so a changed threshold or a moved target
+// is a different protocol, never an edit of the old one.
+//
+// What this module does NOT do: it creates no population, no labels and no
+// results. A protocol marked `synthetic` can exercise the machinery and can
+// never satisfy a real-code gate (gates.js enforces that).
+//
+// Pure: no fs, no clock, no network. Validators return `{ ok, errors }` with the
+// same error shape the assurance schema kit uses.
+
+import {
+  SCHEMA_VERSION, makeCtx, result, guardObject, checkHeader, checkFields, checkDigest, checkCommit, checkString,
+  isPlainObject, isDigest,
+} from '../assurance/schema-kit.js';
+import { digestOf } from '../assurance/identity.js';
+import { groupTargets, splitStraddles } from './grouping.js';
+
+const PROTOCOL_SCHEMA = 'agentic-security/evaluation-protocol';
+
+// The nine advertised core languages (docs/POSITIONING.md, PRD section 3).
+export const CORE_LANGUAGES = Object.freeze([
+  'javascript', 'python', 'java', 'kotlin', 'go', 'ruby', 'php', 'csharp', 'rust',
+]);
+
+// PRD section 5. These are release TARGETS registered in advance, not claims
+// about current performance. They live in code so a protocol that omits or
+// loosens one is detectable (`validateProtocol` compares against this floor).
+export const PREREGISTERED_THRESHOLDS = Object.freeze({
+  perLanguageF1: 0.80,
+  overallMicroF1: 0.80,
+  overallMacroF1: 0.80,
+  pooledPrecision: 0.90,
+  pooledRecall: 0.75,
+  perLanguageF1LowerBound: 0.70,
+  completion: 0.95,
+  minPositivesPerCoreLanguage: 100,
+  minNegativesPerCoreLanguage: 100,
+  minPositivesPerFamily: 30,
+  intervalMethod: 'grouped-bootstrap-95',
+});
+
+export const DEFAULT_MATCHING = Object.freeze({
+  policy: 'root-cause-location',
+  lineWindow: 3,
+  requireFamilyOrCwe: true,
+  cweAloneSufficient: false,
+  lineLessFindingsMatch: false,
+});
+
+const FIELDS = [
+  'schema', 'schemaVersion', 'protocolVersion', 'supersedes', 'synthetic', 'engine', 'measurement', 'tools', 'models',
+  'datasetLicenses', 'scope', 'matching', 'limits', 'thresholds', 'targets', 'originalTargetIds', 'retired', 'splits',
+  'grouping', 'comparability', 'protocolHash', 'createdAt',
+];
+const REQUIRED = [
+  'schema', 'schemaVersion', 'protocolVersion', 'synthetic', 'engine', 'measurement', 'tools', 'models', 'datasetLicenses',
+  'scope', 'matching', 'limits', 'thresholds', 'targets', 'originalTargetIds', 'splits', 'protocolHash',
+];
+// Everything except the hash itself and the informational clock.
+const HASHED = FIELDS.filter((f) => f !== 'protocolHash' && f !== 'createdAt');
+
+export function protocolHashOf(p) {
+  const material = {};
+  for (const f of HASHED) material[f] = p?.[f] === undefined ? null : p[f];
+  return digestOf({ kind: 'evaluation-protocol', material });
+}
+
+function deepFreeze(v) {
+  if (v && typeof v === 'object' && !Object.isFrozen(v)) {
+    Object.freeze(v);
+    for (const k of Object.keys(v)) deepFreeze(v[k]);
+  }
+  return v;
+}
+
+const clone = (v) => JSON.parse(JSON.stringify(v));
+
+/**
+ * Validate a protocol, frozen or not. A protocol whose hash does not match its
+ * content fails with HASH_MISMATCH: that is what "immutable" means here.
+ */
+export function validateProtocol(p) {
+  const g = guardObject(p);
+  const ctx = g.ctx;
+  if (!g.ok) return result(ctx);
+  if (!checkHeader(ctx, p, PROTOCOL_SCHEMA)) return result(ctx);
+  checkFields(ctx, p, FIELDS, REQUIRED);
+
+  if (!Number.isInteger(p.protocolVersion) || p.protocolVersion < 1) ctx.err('BAD_TYPE', 'protocolVersion', 'must be a positive integer');
+  if (typeof p.synthetic !== 'boolean') ctx.err('BAD_TYPE', 'synthetic', 'must be a boolean');
+
+  // AC01: pinned versions, digests and a clean measurement tree.
+  if (!isPlainObject(p.engine)) ctx.err('BAD_TYPE', 'engine', 'must be an object');
+  else { checkString(ctx, 'engine.version', p.engine.version); checkDigest(ctx, 'engine.bundleDigest', p.engine.bundleDigest); }
+  if (!isPlainObject(p.measurement)) ctx.err('BAD_TYPE', 'measurement', 'must be an object');
+  else {
+    checkCommit(ctx, 'measurement.commit', p.measurement.commit, { nullable: false });
+    if (p.measurement.cleanTree !== true) ctx.err('RULE_VIOLATION', 'measurement.cleanTree', 'the measurement tree must be clean; a dirty tree cannot be pinned');
+  }
+  if (!isPlainObject(p.tools) || Object.keys(p.tools).length === 0) ctx.err('MISSING_FIELD', 'tools', 'tool versions must be pinned');
+  if (!Array.isArray(p.models)) ctx.err('BAD_TYPE', 'models', 'must be an array (empty when no model is used)');
+  else p.models.forEach((m, i) => { if (!isPlainObject(m) || !m.provider || !m.model || !m.version) ctx.err('BAD_TYPE', `models[${i}]`, 'must name provider, model and version'); });
+  if (!isPlainObject(p.datasetLicenses) || Object.keys(p.datasetLicenses).length === 0) ctx.err('MISSING_FIELD', 'datasetLicenses', 'dataset licenses must be declared');
+
+  if (!isPlainObject(p.scope) || !Array.isArray(p.scope.languages) || !p.scope.languages.length || !Array.isArray(p.scope.families) || !p.scope.families.length) {
+    ctx.err('MISSING_FIELD', 'scope', 'scope must declare languages[] and families[]');
+  }
+  if (!isPlainObject(p.matching)) ctx.err('BAD_TYPE', 'matching', 'must be an object');
+  else if (p.matching.cweAloneSufficient !== false) ctx.err('RULE_VIOLATION', 'matching.cweAloneSufficient', 'CWE agreement alone can never make a true positive');
+  if (!isPlainObject(p.limits)) ctx.err('BAD_TYPE', 'limits', 'must be an object');
+  else {
+    for (const k of ['perTargetTimeoutMs', 'spendCeilingUsd', 'replicates']) {
+      if (typeof p.limits[k] !== 'number' || !(p.limits[k] >= 0)) ctx.err('BAD_TYPE', `limits.${k}`, 'must be a non-negative number');
+    }
+  }
+
+  // Thresholds may be stricter than the floor, never looser or missing.
+  if (!isPlainObject(p.thresholds)) ctx.err('BAD_TYPE', 'thresholds', 'must be an object');
+  else {
+    for (const [k, floor] of Object.entries(PREREGISTERED_THRESHOLDS)) {
+      const v = p.thresholds[k];
+      if (typeof floor === 'string') { if (v !== floor) ctx.err('RULE_VIOLATION', `thresholds.${k}`, `must be '${floor}'`); continue; }
+      if (typeof v !== 'number') { ctx.err('MISSING_FIELD', `thresholds.${k}`, 'preregistered threshold is missing'); continue; }
+      if (v < floor) ctx.err('RULE_VIOLATION', `thresholds.${k}`, `${v} is looser than the preregistered ${floor}`);
+    }
+  }
+
+  // Targets: pairs, licenses, commits, digests.
+  const ids = new Set();
+  if (!Array.isArray(p.targets) || p.targets.length === 0) ctx.err('MISSING_FIELD', 'targets', 'a protocol needs at least one target');
+  else {
+    p.targets.forEach((t, i) => {
+      const at = `targets[${i}]`;
+      if (!isPlainObject(t)) { ctx.err('BAD_TYPE', at, 'must be an object'); return; }
+      if (!checkString(ctx, `${at}.id`, t.id)) return;
+      if (ids.has(t.id)) ctx.err('DUPLICATE_ID', `${at}.id`, `duplicate target id ${t.id}`);
+      ids.add(t.id);
+      checkString(ctx, `${at}.language`, t.language);
+      checkString(ctx, `${at}.license`, t.license);
+      checkCommit(ctx, `${at}.preCommit`, t.preCommit, { nullable: false });
+      checkCommit(ctx, `${at}.postCommit`, t.postCommit, { nullable: true });
+      checkDigest(ctx, `${at}.digest`, t.digest);
+      if (isPlainObject(p.datasetLicenses) && t.license && !(t.license in p.datasetLicenses)) ctx.err('RULE_VIOLATION', `${at}.license`, `license ${t.license} is not declared in datasetLicenses`);
+      if (isPlainObject(p.scope) && Array.isArray(p.scope.languages) && t.language && !p.scope.languages.includes(t.language)) ctx.err('RULE_VIOLATION', `${at}.language`, `${t.language} is outside the declared scope`);
+    });
+  }
+
+  // AC03: nothing silently disappears from the original denominator.
+  const retired = Array.isArray(p.retired) ? p.retired : [];
+  const retiredIds = new Set();
+  retired.forEach((r, i) => {
+    if (!isPlainObject(r) || !r.id || !r.reason) ctx.err('BAD_TYPE', `retired[${i}]`, 'a retired target must name id and reason');
+    else retiredIds.add(r.id);
+  });
+  if (!Array.isArray(p.originalTargetIds)) ctx.err('BAD_TYPE', 'originalTargetIds', 'must be an array');
+  else {
+    for (const id of p.originalTargetIds) {
+      if (!ids.has(id) && !retiredIds.has(id)) ctx.err('RULE_VIOLATION', 'originalTargetIds', `target ${id} left the population without a disclosed retirement`);
+    }
+  }
+
+  // Splits: immutable membership, a partition of the targets, no group straddling it.
+  if (!isPlainObject(p.splits) || !Array.isArray(p.splits.dev) || !Array.isArray(p.splits.sealed)) ctx.err('BAD_TYPE', 'splits', 'must be {dev[], sealed[]}');
+  else {
+    const dev = new Set(p.splits.dev); const sealed = new Set(p.splits.sealed);
+    for (const id of dev) if (sealed.has(id)) ctx.err('RULE_VIOLATION', 'splits', `target ${id} is in both development and sealed`);
+    for (const id of ids) if (!dev.has(id) && !sealed.has(id)) ctx.err('RULE_VIOLATION', 'splits', `target ${id} is in no split`);
+    for (const id of [...dev, ...sealed]) if (!ids.has(id)) ctx.err('DANGLING_REF', 'splits', `split names unknown target ${id}`);
+    if (Array.isArray(p.targets) && ctx.errors.length === 0) {
+      for (const grp of splitStraddles(groupTargets(p.targets).groups, p.splits)) {
+        ctx.err('RULE_VIOLATION', 'splits', `related samples ${grp.members.join(', ')} (${grp.reasons.join('; ')}) straddle development and sealed`);
+      }
+    }
+  }
+
+  if (typeof p.protocolHash !== 'string' || !isDigest(p.protocolHash)) ctx.err('BAD_DIGEST', 'protocolHash', 'must be a sha256 digest');
+  else if (ctx.errors.length === 0 && p.protocolHash !== protocolHashOf(p)) {
+    ctx.err('HASH_MISMATCH', 'protocolHash', 'content does not match protocolHash: the protocol was changed after it was frozen');
+  }
+  return result(ctx);
+}
+
+/**
+ * Freeze a draft. The draft must already carry its splits; use `assignSplits`
+ * (grouping.js) to produce them. Returns `{ ok, errors, protocol }`; on success
+ * the protocol is deeply frozen and carries its hash.
+ */
+export function freezeProtocol(draft) {
+  const p = clone(draft || {});
+  p.schema = PROTOCOL_SCHEMA;
+  p.schemaVersion = SCHEMA_VERSION;
+  p.protocolVersion = Number.isInteger(p.protocolVersion) ? p.protocolVersion : 1;
+  if (p.supersedes === undefined) p.supersedes = null;
+  if (p.thresholds === undefined) p.thresholds = { ...PREREGISTERED_THRESHOLDS };
+  if (p.matching === undefined) p.matching = { ...DEFAULT_MATCHING };
+  if (!Array.isArray(p.originalTargetIds)) p.originalTargetIds = (p.targets || []).map((t) => t.id).sort();
+  if (!Array.isArray(p.retired)) p.retired = [];
+  if (p.comparability === undefined) p.comparability = { comparableWith: [] };
+  p.protocolHash = protocolHashOf(p);
+  const v = validateProtocol(p);
+  if (!v.ok) return { ok: false, errors: v.errors, protocol: null };
+  return { ok: true, errors: [], protocol: deepFreeze(p) };
+}
+
+// ---------------------------------------------------------------- versioned diff
+
+function flatten(v, prefix, out) {
+  if (Array.isArray(v) || !isPlainObject(v)) { out[prefix] = digestOf(v === undefined ? null : v) + ':' + JSON.stringify(v ?? null).slice(0, 200); return; }
+  for (const k of Object.keys(v).sort()) flatten(v[k], prefix ? `${prefix}.${k}` : k, out);
+}
+
+/** Field-level diff of two protocols' hashed content. Empty `changes` means identical content. */
+export function diffProtocols(a, b) {
+  const fa = {}; const fb = {};
+  for (const f of HASHED) { flatten(a?.[f], f, fa); flatten(b?.[f], f, fb); }
+  const paths = [...new Set([...Object.keys(fa), ...Object.keys(fb)])].sort();
+  const changes = [];
+  for (const path of paths) if (fa[path] !== fb[path]) changes.push({ path, change: !(path in fa) ? 'added' : !(path in fb) ? 'removed' : 'modified' });
+  return { from: a?.protocolHash || null, to: b?.protocolHash || null, changes, identical: changes.length === 0 };
+}
+
+// Fields that define the measurement. Once a result exists they can never be
+// edited in place, only superseded by a new protocol and a new measurement.
+const MEASUREMENT_DEFINING = ['thresholds', 'matching', 'scope', 'limits', 'targets', 'originalTargetIds', 'retired', 'splits', 'engine', 'measurement', 'tools', 'models', 'datasetLicenses', 'grouping'];
+
+/**
+ * Amend a frozen protocol BEFORE any result was observed for it. The result is a
+ * new versioned protocol that names what it supersedes, carries the field diff,
+ * and is comparable with nothing earlier. A removed target must be disclosed as
+ * retired with a reason; it stays in `originalTargetIds`.
+ *
+ * `observedResults` is the list of result records known to the caller. If any is
+ * bound to this protocol's hash the amendment is refused with POST_RESULT_CHANGE:
+ * a threshold, matching rule or denominator cannot move once results exist. The
+ * only route forward is `deriveSuccessorProtocol`, which needs a fresh sealed set.
+ */
+export function amendProtocol(frozen, patch, { observedResults = [], reason } = {}) {
+  const base = validateProtocol(frozen);
+  if (!base.ok) return { ok: false, errors: base.errors, protocol: null, diff: null };
+  const bound = (observedResults || []).filter((r) => r && r.protocolHash === frozen.protocolHash);
+  if (bound.length > 0) {
+    return {
+      ok: false, protocol: null, diff: null,
+      errors: [{ code: 'POST_RESULT_CHANGE', path: '', message: `${bound.length} result(s) already exist for protocol ${frozen.protocolHash}; its thresholds, matching rules, scope and denominator cannot change in place` }],
+    };
+  }
+  if (!reason || typeof reason !== 'string') return { ok: false, protocol: null, diff: null, errors: [{ code: 'MISSING_FIELD', path: 'reason', message: 'an amendment must state its reason' }] };
+  const next = clone(frozen);
+  for (const [k, v] of Object.entries(patch || {})) {
+    if (!MEASUREMENT_DEFINING.includes(k)) return { ok: false, protocol: null, diff: null, errors: [{ code: 'UNKNOWN_FIELD', path: k, message: `'${k}' is not an amendable protocol field` }] };
+    next[k] = clone(v);
+  }
+  // Removed targets are retired, never dropped.
+  const keep = new Set((next.targets || []).map((t) => t.id));
+  const retired = Array.isArray(next.retired) ? next.retired : [];
+  const known = new Set(retired.map((r) => r.id));
+  for (const t of frozen.targets) if (!keep.has(t.id) && !known.has(t.id)) retired.push({ id: t.id, reason: `removed by amendment: ${reason}`, retiredInVersion: frozen.protocolVersion + 1 });
+  next.retired = retired;
+  next.protocolVersion = frozen.protocolVersion + 1;
+  next.supersedes = frozen.protocolHash;
+  next.comparability = { comparableWith: [], invalidates: [frozen.protocolHash], reason };
+  next.protocolHash = protocolHashOf(next);
+  const v = validateProtocol(next);
+  if (!v.ok) return { ok: false, errors: v.errors, protocol: null, diff: null };
+  return { ok: true, errors: [], protocol: deepFreeze(next), diff: diffProtocols(frozen, next) };
+}
+
+/**
+ * After results exist, the only legal change is a SUCCESSOR protocol with a new
+ * measurement. Its sealed set must not overlap any sealed target already
+ * consumed by an observed result, so a consumed holdout is never reused.
+ */
+export function deriveSuccessorProtocol(frozen, draft, { observedResults = [], consumedSealedIds = [] } = {}) {
+  const consumed = new Set(consumedSealedIds);
+  for (const r of observedResults || []) for (const id of r?.sealedTargetIds || []) consumed.add(id);
+  if (consumed.size === 0 && (observedResults || []).some((r) => r?.protocolHash === frozen?.protocolHash)) {
+    for (const id of frozen.splits.sealed) consumed.add(id);
+  }
+  const reused = (draft?.splits?.sealed || []).filter((id) => consumed.has(id));
+  if (reused.length) {
+    return { ok: false, protocol: null, errors: [{ code: 'SEALED_REUSE', path: 'splits.sealed', message: `sealed target(s) ${reused.join(', ')} were already consumed by an observed result; a successor needs a fresh sealed population` }] };
+  }
+  const r = freezeProtocol({
+    ...draft,
+    protocolVersion: (frozen?.protocolVersion || 0) + 1,
+    supersedes: frozen?.protocolHash || null,
+    comparability: { comparableWith: [], invalidates: [frozen?.protocolHash].filter(Boolean), reason: 'successor protocol with a new measurement' },
+  });
+  return { ...r, diff: r.ok ? diffProtocols(frozen, r.protocol) : null };
+}
+
+/**
+ * Does a result or run record belong to this exact protocol? A record produced
+ * under any other hash (or under a hash that no longer matches the protocol's
+ * content) is rejected: it cannot be re-scored under changed rules.
+ */
+export function assertBoundToProtocol(record, protocol) {
+  const v = validateProtocol(protocol);
+  if (!v.ok) return { ok: false, errors: v.errors };
+  if (!record || record.protocolHash !== protocol.protocolHash) {
+    return { ok: false, errors: [{ code: 'PROTOCOL_MISMATCH', path: 'protocolHash', message: `record is bound to ${record?.protocolHash || 'no protocol'}, not ${protocol.protocolHash}` }] };
+  }
+  return { ok: true, errors: [] };
+}

package/src/posture/evaluation/release-gate.js

@@ -0,0 +1,209 @@
+// Release evaluation gates, signed by the custodian, with a sealed-population ledger (QA-007).
+//
+// gates.js decides each gate; this module turns those decisions into a RELEASE verdict that a person can rely on and a tampering
+// person cannot quietly improve:
+//
+//   1. The verdict is an aggregate. The custodian signs `{ overall, gates, population }` and nothing per-case: a development
+//      worker iterating on a detector sees the aggregate gate states, never which sealed case failed.
+//   2. It is a verdict about ONE detector revision. Every sealed evaluation is appended to a hash-chained ledger together with a
+//      digest of the detector source it was run against and the sealed targets it consumed. A detector edit after that evaluation
+//      means the sealed population has been seen by the people who made the edit, so a new release accuracy claim needs a FRESH
+//      sealed population (`assessReleaseClaim`). The old result stays in the ledger as an evaluation-only artifact: retained,
+//      never deleted, never usable for a new claim.
+//   3. Insufficient data is `blocked`, never a pass on a smaller sample. gates.js already refuses to pass a short or synthetic
+//      population; here a non-pass verdict also blocks the claim, whatever the reason.
+//   4. A lower-quality engine, a failed-target spike, a changed denominator, an answer-key leak, a threshold weakened after
+//      freezing, and a baseline edited downward each produce a failing or rejected verdict (gates.js plus `verifyLedger`).
+//
+// Trust: the signature is Ed25519 over the canonical bytes with a custodian key the caller supplies. It is a SELF-ISSUED local
+// signature (trustBasis `self-issued-local-key`, `independentlyCertified: false`), tamper evidence for whoever holds the public
+// key, not independent certification. Verifying needs only the public key.
+//
+// Pure apart from `detectorDigestOf` (reads a source tree) and the key handling the caller does. No clock: ordering is the chain.
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { canonicalJson } from '../evidence-bundle.js';
+import { digestOf } from '../assurance/identity.js';
+import { STATE_DIR_NAME } from '../state-dir.js';
+import { evaluateGates } from './gates.js';
+
+const GATE_REPORT_SCHEMA = 'agentic-security/evaluation-release-gate';
+const LEDGER_SCHEMA = 'agentic-security/sealed-evaluation-ledger';
+const TRUST_BASIS = 'self-issued-local-key';
+
+// ---------------------------------------------------------------- detector identity
+
+const DETECTOR_SKIP_DIRS = new Set(['node_modules', '.git', STATE_DIR_NAME, 'vendor', 'dist']);
+
+/**
+ * Digest of the detector source: every file under `srcRoot` EXCEPT the evaluation tooling itself (editing the measuring instrument
+ * is not editing the detector, and it is covered by the protocol hash). Paths are hashed relative and sorted, so the digest
+ * depends on content and layout only.
+ */
+export function detectorDigestOf(srcRoot, { exclude = ['posture/evaluation'] } = {}) {
+  const h = crypto.createHash('sha256');
+  const skip = exclude.map((e) => e.replace(/\\/g, '/'));
+  const walk = (dir, rel) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (skip.includes(r)) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!DETECTOR_SKIP_DIRS.has(e.name)) walk(full, r); continue; }
+      if (!e.isFile()) continue;
+      h.update(`F:${r}\n`); h.update(fs.readFileSync(full));
+    }
+  };
+  walk(srcRoot, '');
+  return `sha256:${h.digest('hex')}`;
+}
+
+// ---------------------------------------------------------------- the ledger
+
+const entryHashOf = (e) => digestOf({ kind: 'sealed-ledger-entry', e: { ...e, entryHash: undefined } });
+
+export const emptyLedger = () => ({ schema: LEDGER_SCHEMA, entries: [] });
+
+/**
+ * Append one sealed evaluation. Returns a NEW ledger; the input is not modified. An entry records the detector digest, the sealed
+ * targets consumed and the aggregate outcome, and chains to the previous entry by hash.
+ */
+export function appendSealedEvaluation(ledger, { protocolHash, detectorDigest, sealedTargetIds, overall, gateStatuses = {}, score = null, label = null }) {
+  if (!detectorDigest) throw new Error('a sealed evaluation is recorded against a detector digest');
+  const prev = ledger.entries.length ? ledger.entries[ledger.entries.length - 1].entryHash : null;
+  const entry = {
+    sequence: ledger.entries.length, prev, protocolHash, detectorDigest,
+    sealedTargetIds: [...sealedTargetIds].sort(), overall, gateStatuses,
+    // The aggregate only: this is what a later no-regression comparison reads. Per-case outcomes are never stored here.
+    baseline: score ? { endToEnd: { micro: { f1: score.endToEnd?.micro?.f1 ?? null, precision: score.endToEnd?.micro?.precision ?? null, recall: score.endToEnd?.micro?.recall ?? null }, byLanguage: Object.fromEntries(Object.entries(score.endToEnd?.byLanguage || {}).map(([l, c]) => [l, { f1: c.f1 ?? null }])) } } : null,
+    usage: 'evaluation-only', label,
+  };
+  entry.entryHash = entryHashOf(entry);
+  return { ...ledger, entries: [...ledger.entries, entry] };
+}
+
+/** The chain must be intact: a recomputed hash that disagrees, a broken link or a gap means an entry (a baseline, say) was edited. */
+export function verifyLedger(ledger) {
+  const errors = [];
+  if (!ledger || ledger.schema !== LEDGER_SCHEMA || !Array.isArray(ledger.entries)) return { ok: false, errors: [{ code: 'BAD_LEDGER', message: 'not a sealed evaluation ledger' }] };
+  let prev = null;
+  ledger.entries.forEach((e, i) => {
+    if (e.sequence !== i) errors.push({ code: 'GAP', index: i, message: `entry ${i} claims sequence ${e.sequence}` });
+    if (e.prev !== prev) errors.push({ code: 'BROKEN_CHAIN', index: i, message: `entry ${i} does not chain to the entry before it` });
+    if (entryHashOf(e) !== e.entryHash) errors.push({ code: 'ENTRY_EDITED', index: i, message: `entry ${i} no longer matches its recorded hash` });
+    prev = e.entryHash;
+  });
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * May a NEW release accuracy claim be made on this sealed evaluation of this detector?
+ *   - the ledger must verify;
+ *   - the evaluation must have been run against the CURRENT detector digest (an old result describes an old detector);
+ *   - none of the sealed targets it used may have been consumed by an earlier evaluation of a DIFFERENT detector digest: those
+ *     targets have been seen, so a claim on them is a claim on a holdout that was tuned against. A fresh sealed population is needed.
+ * Historical results stay in `retained`, flagged evaluation-only.
+ */
+export function assessReleaseClaim({ ledger, detectorDigest, sealedTargetIds, overall }) {
+  const v = verifyLedger(ledger);
+  if (!v.ok) return { allowed: false, status: 'blocked', reasons: ['ledger-tampered'], errors: v.errors, retained: [] };
+  const sealed = new Set(sealedTargetIds);
+  const retained = ledger.entries.map((e) => ({ sequence: e.sequence, detectorDigest: e.detectorDigest, overall: e.overall, usage: 'evaluation-only', usableForNewClaim: false }));
+  const reasons = [];
+  const consumed = new Set();
+  const priorOtherDetector = ledger.entries.filter((e) => e.detectorDigest !== detectorDigest);
+  for (const e of priorOtherDetector) for (const t of e.sealedTargetIds) if (sealed.has(t)) consumed.add(t);
+  if (consumed.size) reasons.push('fresh-sealed-population-required');
+  if (!ledger.entries.some((e) => e.detectorDigest === detectorDigest)) reasons.push('no-sealed-evaluation-of-this-detector');
+  if (overall !== 'pass') reasons.push(overall === 'insufficient-population' || overall === 'unmeasured' ? `gate-${overall}` : 'gates-not-passing');
+  return {
+    allowed: reasons.length === 0, status: reasons.length === 0 ? 'claim-allowed' : 'blocked', reasons,
+    consumedSealedTargets: [...consumed].sort(), retained,
+    note: 'historical sealed results are retained as evaluation-only artifacts; they never support a new claim for a different detector revision',
+  };
+}
+
+/**
+ * The chain alone is not tamper-proof: hashes are unkeyed, so someone who edits a baseline can recompute every later hash. The
+ * custodian therefore signs the chain HEAD, and a ledger is trusted only through `verifySignedLedger`.
+ */
+export function signLedger(ledger, privateKeyPem) {
+  const v = verifyLedger(ledger);
+  if (!v.ok) throw new Error('refusing to sign a ledger that does not verify');
+  const head = ledger.entries.length ? ledger.entries[ledger.entries.length - 1].entryHash : null;
+  const body = { ledger, head, length: ledger.entries.length };
+  return { ...body, signature: { algorithm: 'ed25519', value: crypto.sign(null, Buffer.from(canonicalJson({ head, length: body.length })), privateKeyPem).toString('base64') } };
+}
+
+export function verifySignedLedger(signed, publicKeyPem) {
+  if (!signed?.ledger || !signed.signature) return { ok: false, reason: 'not a signed ledger' };
+  const v = verifyLedger(signed.ledger);
+  if (!v.ok) return { ok: false, reason: 'the chain does not verify', errors: v.errors };
+  const entries = signed.ledger.entries;
+  const head = entries.length ? entries[entries.length - 1].entryHash : null;
+  if (head !== signed.head || entries.length !== signed.length) return { ok: false, reason: 'the ledger head or length differs from the signed one' };
+  let good = false;
+  try { good = crypto.verify(null, Buffer.from(canonicalJson({ head, length: entries.length })), publicKeyPem, Buffer.from(signed.signature.value, 'base64')); } catch { good = false; }
+  return good ? { ok: true, ledger: signed.ledger } : { ok: false, reason: 'the head signature does not verify under the custodian key' };
+}
+
+// ---------------------------------------------------------------- the release verdict
+
+/**
+ * Evaluate the release gates for one sealed-split run and decide whether a new accuracy claim is allowed.
+ * `run` is required: the integrity gates (leaks, denominator) read it, and a verdict that cannot count leaks is not a release verdict.
+ */
+export function evaluateReleaseGates({ protocol, score, run, defects = [], negatives = [], ledger = emptyLedger(), detectorDigest }) {
+  if (!run) return { ok: false, rejected: true, overall: 'rejected', errors: [{ code: 'RUN_REQUIRED', message: 'a release verdict needs the run record: leakage and the denominator are checked against it' }], gates: [] };
+  const lv = verifyLedger(ledger);
+  if (!lv.ok) return { ok: false, rejected: true, overall: 'rejected', errors: [{ code: 'LEDGER_TAMPERED', message: 'the sealed evaluation ledger does not verify, so no baseline can be trusted', detail: lv.errors }], gates: [] };
+  // The baseline is the last PASSING evaluation of any detector in the verified ledger; it cannot be supplied by the caller.
+  const lastPass = [...ledger.entries].reverse().find((e) => e.overall === 'pass' && e.baseline);
+  const g = evaluateGates({ protocol, score, defects, negatives, run, baseline: lastPass ? lastPass.baseline : null });
+  if (g.rejected) return g;
+  const sealedIds = protocol.splits.sealed;
+  const claim = assessReleaseClaim({ ledger, detectorDigest, sealedTargetIds: sealedIds, overall: g.overall });
+  // A first evaluation of this detector has no ledger entry yet; the entry the caller will append is what makes later claims checkable.
+  const firstEvaluation = !ledger.entries.some((e) => e.detectorDigest === detectorDigest);
+  const verdict = {
+    schema: GATE_REPORT_SCHEMA, ok: true, rejected: false,
+    protocolHash: protocol.protocolHash, synthetic: !!protocol.synthetic, detectorDigest,
+    overall: g.overall,
+    gates: g.gates.map((x) => ({ id: x.id, status: x.status, threshold: x.threshold ?? null, measured: x.measured ?? null, ...(x.reason ? { reason: x.reason } : {}) })),
+    population: { realSealedPositives: g.population.realSealedPositives, realSealedNegatives: g.population.realSealedNegatives, reason: g.population.reason },
+    claim: firstEvaluation && claim.reasons.every((r) => r === 'no-sealed-evaluation-of-this-detector')
+      ? { ...claim, reasons: claim.reasons.filter((r) => r !== 'no-sealed-evaluation-of-this-detector'), allowed: g.overall === 'pass', status: g.overall === 'pass' ? 'claim-allowed' : 'blocked' }
+      : claim,
+    aggregateOnly: 'no per-case sealed outcome appears in this report',
+  };
+  verdict.reportHash = digestOf({ ...verdict, reportHash: undefined });
+  return verdict;
+}
+
+// ---------------------------------------------------------------- signing
+
+/** Custodian signature over the aggregate verdict. `privateKeyPem` is the custodian's Ed25519 key. */
+export function signGateReport(report, privateKeyPem, { issuerId = 'evaluation-custodian' } = {}) {
+  if (!report || report.rejected) throw new Error('only an accepted gate report is signed');
+  const publicKeyPem = crypto.createPublicKey(privateKeyPem).export({ type: 'spki', format: 'pem' });
+  const fingerprint = crypto.createHash('sha256').update(publicKeyPem).digest('hex');
+  const issuance = { issuerId, keyFingerprint: fingerprint, trustBasis: TRUST_BASIS, independentlyCertified: false, statement: 'signed by a local custodian key; tamper evidence, not independent certification' };
+  const body = { report, issuance };
+  const signature = crypto.sign(null, Buffer.from(canonicalJson(body)), privateKeyPem).toString('base64');
+  return { ...body, signature: { algorithm: 'ed25519', value: signature } };
+}
+
+/** Verify with only the public key. A report that claims independent certification, or whose fingerprint is not this key, is rejected. */
+export function verifyGateReport(signed, publicKeyPem) {
+  if (!signed || !signed.report || !signed.signature || !signed.issuance) return { ok: false, reason: 'not a signed gate report' };
+  if (signed.signature.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${signed.signature.algorithm}` };
+  if (signed.issuance.independentlyCertified !== false || signed.issuance.trustBasis !== TRUST_BASIS) return { ok: false, reason: 'the only verifiable trust basis is a self-issued local key' };
+  const fp = crypto.createHash('sha256').update(crypto.createPublicKey(publicKeyPem).export({ type: 'spki', format: 'pem' })).digest('hex');
+  if (signed.issuance.keyFingerprint !== fp) return { ok: false, reason: 'the issuer fingerprint is not the verifying key' };
+  let good = false;
+  try { good = crypto.verify(null, Buffer.from(canonicalJson({ report: signed.report, issuance: signed.issuance })), publicKeyPem, Buffer.from(signed.signature.value, 'base64')); } catch { good = false; }
+  if (!good) return { ok: false, reason: 'signature does not match the report' };
+  if (digestOf({ ...signed.report, reportHash: undefined }) !== signed.report.reportHash) return { ok: false, reason: 'report content does not match its recorded hash' };
+  return { ok: true, overall: signed.report.overall, claimAllowed: !!signed.report.claim?.allowed, trustBasis: TRUST_BASIS };
+}