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

package/src/posture/routing/promotion.js

@@ -0,0 +1,291 @@
+// Paired replay and the routing-promotion gate (X-605.AC02, X-605.AC03).
+//
+// The PRD section 5 routing row, in full:
+//   >= 200 paired adjudicated tasks overall and >= 30 per promoted stratum;
+//   lower 95% bound on the quality difference (proposed minus baseline) above -0.02;
+//   measured median cost >= 20% lower, OR quality >= +0.05 at no higher median cost;
+//   p95 latency <= 1.2x baseline; full failure reporting; retries, cache and tools accounted for.
+//
+// The comparison is over a FROZEN task set (`freezeTaskSet`): a hash of the task ids and strata fixed before any outcome is looked at.
+// `replayPaired` pairs, for every frozen task, the baseline arm (the model production used) with the proposed arm (the model the
+// shadow decision picked) from recorded outcomes. It issues no provider call unless the caller supplies BOTH an `invoke` function and a
+// bounded authorization (a finite call count, a finite spend, a per-call ceiling for unknown costs); without both it is offline, and
+// an `invoke` without a valid authorization is refused (`UNBOUNDED_REPLAY`). A replay that stops at its bound leaves tasks unpaired.
+//
+// What invalidates the gate (status `invalid`, whatever the figures say):
+//   cherry-picked    the paired task set differs from the frozen set (an extra task, or a task not in the frozen set)
+//   dropped          a frozen task has no pair: no shadow record, a missing or ambiguous outcome, or a replay that ran out of bound
+//   unbounded        a replay that ran unauthorized, over its bounds, or was truncated
+//   edited           the replay or frozen set no longer matches its own hash
+// A FAILED arm is never dropped: a failure status, a timeout, a blocked proposal or a task the proposed policy left unserved counts as
+// not-correct in the quality comparison and is reported. A pair where correctness is still unknown for either arm is counted
+// (`unadjudicated`) and kept out of the quality statistic, never imputed.
+//
+// Synthetic data can never pass: the verdict is `unmeasured`. Nothing here claims an improvement.
+
+import { groupedBootstrap } from '../evaluation/interval.js';
+import { digestOf } from '../assurance/identity.js';
+import { ROUTING_MINIMUMS, ROUTING_PROMOTION_TARGETS } from './calibration.js';
+import { FAILURE_STATUSES, validateRoutingOutcome } from './outcomes.js';
+
+export const FROZEN_SET_SCHEMA = 'agentic-security/routing-frozen-task-set';
+export const REPLAY_SCHEMA = 'agentic-security/routing-paired-replay';
+export const PROMOTION_SCHEMA = 'agentic-security/routing-promotion-verdict';
+export const REPLAY_LIMITS = Object.freeze({ maxCalls: 1000, maxUsd: 1000 });
+export const INVALIDATION_CODES = Object.freeze(['frozen-set-edited', 'replay-edited', 'cherry-picked', 'dropped-tasks', 'unbounded-replay', 'truncated-replay']);
+
+const keyOf = (taskId, model) => `${taskId}\u0000${model}`;
+
+/** Fix the evaluation tasks before any outcome is examined. `tasks` are routing task records (outcomes.js). */
+export function freezeTaskSet(tasks) {
+  const list = Array.isArray(tasks) ? tasks : [];
+  const seen = new Set();
+  const rows = [];
+  for (const t of list) {
+    if (!t || typeof t.taskId !== 'string' || typeof t.stratum !== 'string') return { ok: false, code: 'BAD_TASK', reason: 'every frozen task needs a taskId and a stratum' };
+    if (seen.has(t.taskId)) return { ok: false, code: 'DUPLICATE_TASK', reason: `task ${t.taskId} appears twice` };
+    seen.add(t.taskId);
+    rows.push({ taskId: t.taskId, stratum: t.stratum, synthetic: t.synthetic === true });
+  }
+  rows.sort((a, b) => (a.taskId < b.taskId ? -1 : 1));
+  const strata = {};
+  for (const r of rows) strata[r.stratum] = (strata[r.stratum] || 0) + 1;
+  const frozen = { schema: FROZEN_SET_SCHEMA, count: rows.length, tasks: rows, strata, synthetic: rows.some((r) => r.synthetic) };
+  frozen.hash = digestOf({ tasks: rows });
+  return { ok: true, frozen: Object.freeze(frozen) };
+}
+
+const frozenIntact = (f) => !!f && Array.isArray(f.tasks) && digestOf({ tasks: f.tasks }) === f.hash;
+
+function validAuthorization(a) {
+  const finite = (v, hi) => typeof v === 'number' && Number.isFinite(v) && v > 0 && v <= hi;
+  return !!a && typeof a.authorizedBy === 'string' && a.authorizedBy.length > 0
+    && Number.isInteger(a.maxCalls) && a.maxCalls >= 1 && a.maxCalls <= REPLAY_LIMITS.maxCalls
+    && finite(a.maxUsd, REPLAY_LIMITS.maxUsd) && finite(a.perCallUsdCeiling, REPLAY_LIMITS.maxUsd);
+}
+
+function qualityOf(outcome, served) {
+  if (!served) return { quality: 0, kind: 'unserved' };
+  if (outcome.outcome === 'correct') return { quality: 1, kind: 'correct' };
+  if (outcome.outcome === 'incorrect') return { quality: 0, kind: 'incorrect' };
+  if (FAILURE_STATUSES.includes(outcome.status)) return { quality: 0, kind: 'failed' };
+  return { quality: null, kind: 'undecided' };
+}
+
+function armOf(model, outcome, served) {
+  if (!served) return { model: null, modelVersion: null, served: false, outcomeId: null, status: 'unserved', quality: 0, kind: 'unserved', costUsd: 0, costStatus: 'measured', latencyMs: null, retries: 0, cacheState: 'unknown', synthetic: false, group: null };
+  const q = qualityOf(outcome, true);
+  return {
+    model, modelVersion: outcome.modelVersion ?? null, served: true, outcomeId: outcome.id, status: outcome.status, quality: q.quality, kind: q.kind,
+    costUsd: outcome.costUsd, costStatus: outcome.costStatus, latencyMs: outcome.latencyMs, retries: outcome.usage?.retries ?? 0, cacheState: outcome.cacheState,
+    synthetic: outcome.synthetic === true, group: outcome.group ?? null,
+  };
+}
+
+/**
+ * Pair every frozen task's baseline arm with its proposed arm.
+ *
+ * @param {object} o
+ * @param {object} o.frozen          freezeTaskSet().frozen
+ * @param {object[]} o.shadowRecords shadow.js records (the latest per task is used)
+ * @param {object[]} o.outcomes      recorded routing outcomes (outcomes.js)
+ * @param {object} [o.authorization] { authorizedBy, maxCalls, maxUsd, perCallUsdCeiling }; only used with `invoke`
+ * @param {(req:{task:object, model:string})=>Promise<object>} [o.invoke] injected paid replay; absent means offline
+ * @param {object} [o.log]           receipt log
+ */
+export async function replayPaired({ frozen, shadowRecords, outcomes, authorization = null, invoke = null, log = null }) {
+  if (!frozenIntact(frozen)) return { ok: false, code: 'FROZEN_SET_EDITED', reason: 'the frozen task set does not match its own hash' };
+  if (invoke && !validAuthorization(authorization)) {
+    return { ok: false, code: 'UNBOUNDED_REPLAY', reason: `a paid replay needs an authorization naming who approved it and finite maxCalls (<= ${REPLAY_LIMITS.maxCalls}), maxUsd (<= ${REPLAY_LIMITS.maxUsd}) and perCallUsdCeiling` };
+  }
+  const latest = new Map();
+  for (const r of Array.isArray(shadowRecords) ? shadowRecords : []) latest.set(r.taskId, r);
+  const pool = new Map();
+  for (const o of Array.isArray(outcomes) ? outcomes : []) {
+    if (!validateRoutingOutcome(o).ok) continue;
+    const k = keyOf(o.taskId, o.model);
+    if (!pool.has(k)) pool.set(k, []);
+    pool.get(k).push(o);
+  }
+  const replay = { authorized: !!invoke, authorizedBy: invoke ? authorization.authorizedBy : null, bounds: invoke ? { maxCalls: authorization.maxCalls, maxUsd: authorization.maxUsd, perCallUsdCeiling: authorization.perCallUsdCeiling } : null, calls: 0, spentUsd: 0, truncated: false, offline: !invoke };
+  const fetched = new Map(); // calls already made this replay, by (task, model)
+
+  async function obtain(task, model) {
+    const k = keyOf(task.taskId, model);
+    const have = pool.get(k) || [];
+    if (have.length > 1) return { problem: 'ambiguous-outcomes' };
+    if (have.length === 1) return { outcome: have[0] };
+    if (fetched.has(k)) return fetched.get(k);
+    if (!invoke) return { problem: 'missing-outcome' };
+    if (replay.calls >= authorization.maxCalls || replay.spentUsd + authorization.perCallUsdCeiling > authorization.maxUsd) {
+      replay.truncated = true;
+      return { problem: 'replay-bound-reached' };
+    }
+    replay.calls += 1;
+    let out;
+    try { out = await invoke({ task, model }); } catch { out = null; }
+    let res;
+    if (!out || !validateRoutingOutcome(out).ok || out.taskId !== task.taskId || out.model !== model) {
+      replay.spentUsd += authorization.perCallUsdCeiling; // a failed or malformed replay is charged at the ceiling, never at zero
+      res = { problem: 'invalid-replay-outcome' };
+    } else {
+      replay.spentUsd += typeof out.costUsd === 'number' ? out.costUsd : authorization.perCallUsdCeiling;
+      res = { outcome: out };
+    }
+    fetched.set(k, res);
+    return res;
+  }
+
+  const pairs = [];
+  for (const t of frozen.tasks) {
+    const rec = latest.get(t.taskId);
+    if (!rec) { pairs.push({ taskId: t.taskId, stratum: t.stratum, status: 'dropped', dropReason: 'no-shadow-record' }); continue; }
+    const taskLike = { taskId: t.taskId, stratum: t.stratum };
+    const base = await obtain(taskLike, rec.production.model);
+    const servedProposed = rec.proposed.model !== null && rec.proposed.model !== undefined;
+    const prop = servedProposed ? await obtain(taskLike, rec.proposed.model) : { unserved: true };
+    if (base.problem || prop.problem) {
+      pairs.push({ taskId: t.taskId, stratum: t.stratum, status: 'dropped', dropReason: base.problem || prop.problem, side: base.problem ? 'baseline' : 'proposed' });
+      continue;
+    }
+    const a = armOf(rec.production.model, base.outcome, true);
+    const b = servedProposed ? armOf(rec.proposed.model, prop.outcome, true) : armOf(null, null, false);
+    pairs.push({
+      taskId: t.taskId, stratum: t.stratum, status: 'paired', group: a.group || b.group || t.taskId,
+      proposedStatus: rec.proposed.status, proposedCode: rec.proposed.code, baseline: a, proposed: b,
+    });
+  }
+  const out = { schema: REPLAY_SCHEMA, ok: true, frozenHash: frozen.hash, pairs, replay, paidCalls: replay.calls };
+  out.replayHash = digestOf({ ...out, replayHash: undefined });
+  if (log) log.append('replay', { frozenHash: frozen.hash, replayHash: out.replayHash, paired: pairs.filter((p) => p.status === 'paired').length, dropped: pairs.filter((p) => p.status === 'dropped').length, replay });
+  return out;
+}
+
+// ---------------------------------------------------------------- statistics
+
+const sortedNums = (xs) => xs.filter((x) => typeof x === 'number' && Number.isFinite(x)).sort((x, y) => x - y);
+function median(xs) {
+  const s = sortedNums(xs);
+  if (!s.length) return null;
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+function nearestRank(xs, q) {
+  const s = sortedNums(xs);
+  return s.length ? s[Math.min(s.length - 1, Math.max(0, Math.ceil(q * s.length) - 1))] : null;
+}
+const round = (x) => (x === null || x === undefined ? null : Math.round(x * 1e9) / 1e9);
+const tally = (arms, key, vocab) => { const o = Object.fromEntries(vocab.map((v) => [v, 0])); for (const a of arms) o[a[key]] = (o[a[key]] || 0) + 1; return o; };
+
+/** One slice of pairs (overall or one stratum) against the section 5 criteria. */
+function analyse(pairs, { replicates, protocolHash, name }) {
+  const paired = pairs.filter((p) => p.status === 'paired');
+  const adjudicated = paired.filter((p) => p.baseline.quality !== null && p.proposed.quality !== null);
+  const n = adjudicated.length;
+  const mean = (arm) => (n ? adjudicated.reduce((s, p) => s + p[arm].quality, 0) / n : null);
+  const units = adjudicated.map((p) => {
+    const pq = p.proposed.quality; const bq = p.baseline.quality;
+    return { id: p.taskId, language: 'all', tp: pq === 1 && bq === 0 ? 1 : 0, fn: pq === 0 && bq === 1 ? 1 : 0, fp: 0, tn: pq === bq ? 1 : 0 };
+  });
+  const groupOf = Object.fromEntries(adjudicated.map((p) => [p.taskId, p.group]));
+  const diffStat = (a) => { const t = a.total; const d = t.tp + t.fn + t.fp + t.tn; return d ? (t.tp - t.fn) / d : null; };
+  const interval = n === 0 ? { status: 'unmeasured', low: null, high: null, point: null, reason: 'no paired adjudicated task' }
+    : groupedBootstrap({ units, groupOf, statistic: diffStat, name, protocolHash, replicates });
+  const diffPoint = n ? units.reduce((s, u) => s + u.tp - u.fn, 0) / n : null;
+
+  const arms = (k) => adjudicated.map((p) => p[k]);
+  const costKnown = adjudicated.every((p) => p.baseline.costStatus === 'measured' && typeof p.baseline.costUsd === 'number' && p.proposed.costStatus === 'measured' && typeof p.proposed.costUsd === 'number');
+  const medBase = costKnown ? median(arms('baseline').map((a) => a.costUsd)) : null;
+  const medProp = costKnown ? median(arms('proposed').map((a) => a.costUsd)) : null;
+  const reduction = costKnown && medBase !== null && medBase > 0 ? 1 - medProp / medBase : null;
+  const served = (k) => arms(k).filter((a) => a.served);
+  const latencyKnown = n > 0 && ['baseline', 'proposed'].every((k) => served(k).every((a) => typeof a.latencyMs === 'number'));
+  const p95Base = latencyKnown ? nearestRank(served('baseline').map((a) => a.latencyMs), 0.95) : null;
+  const p95Prop = latencyKnown ? nearestRank(served('proposed').map((a) => a.latencyMs), 0.95) : null;
+  const p95Ratio = latencyKnown && p95Base > 0 ? p95Prop / p95Base : null;
+
+  const T = ROUTING_PROMOTION_TARGETS;
+  const qualityLowerMet = interval.status === 'measured' ? interval.low > T.qualityDifferenceLowerBound : null;
+  const costPath = reduction === null ? null : reduction >= T.medianCostReduction;
+  // The quality path is stricter than the PRD wording: the lower bound must also clear zero, so a gain cannot rest on a point estimate.
+  const qualityPath = interval.status === 'measured' && costKnown && medBase !== null ? (diffPoint >= T.qualityGain && interval.low > 0 && medProp <= medBase) : null;
+  const advantageMet = costPath === true || qualityPath === true ? true : (costPath === null && qualityPath === null ? null : false);
+  const latencyMet = p95Ratio === null ? null : p95Ratio <= T.p95LatencyRatio;
+  const all = qualityLowerMet === true && advantageMet === true && latencyMet === true;
+  const failuresOf = (k) => tally(paired.map((p) => p[k]), 'kind', ['correct', 'incorrect', 'failed', 'unserved', 'undecided']);
+
+  return {
+    pairedTasks: paired.length, adjudicated: n, unadjudicated: paired.length - n,
+    quality: { baseline: round(mean('baseline')), proposed: round(mean('proposed')), difference: round(diffPoint), interval: { method: interval.method ?? 'grouped-bootstrap-95', status: interval.status, low: round(interval.low), high: round(interval.high), groups: interval.groups ?? 0, ...(interval.reason ? { reason: interval.reason } : {}) } },
+    cost: { complete: costKnown, medianBaselineUsd: round(medBase), medianProposedUsd: round(medProp), medianReduction: round(reduction), totalBaselineUsd: costKnown ? round(arms('baseline').reduce((s, a) => s + a.costUsd, 0)) : null, totalProposedUsd: costKnown ? round(arms('proposed').reduce((s, a) => s + a.costUsd, 0)) : null, retriesBaseline: arms('baseline').reduce((s, a) => s + a.retries, 0), retriesProposed: arms('proposed').reduce((s, a) => s + a.retries, 0), basis: 'outcome cost covers input, output, cached input, retries and tool execution as measured by the adapter; an unknown cost makes the cost criterion unmet, never zero' },
+    cache: { baseline: tally(arms('baseline'), 'cacheState', ['hit', 'partial', 'miss', 'ineligible', 'unknown']), proposed: tally(arms('proposed').filter((a) => a.served), 'cacheState', ['hit', 'partial', 'miss', 'ineligible', 'unknown']) },
+    latencyMs: { complete: latencyKnown, baselineP50: latencyKnown ? nearestRank(served('baseline').map((a) => a.latencyMs), 0.5) : null, baselineP95: p95Base, proposedP50: latencyKnown ? nearestRank(served('proposed').map((a) => a.latencyMs), 0.5) : null, proposedP95: p95Prop, p95Ratio: round(p95Ratio) },
+    failures: { baseline: failuresOf('baseline'), proposed: failuresOf('proposed') },
+    criteria: { qualityLowerBound: { met: qualityLowerMet, need: `> ${T.qualityDifferenceLowerBound}`, value: round(interval.low) }, advantage: { met: advantageMet, costPath, qualityPath, needMedianCostReduction: T.medianCostReduction, needQualityGain: T.qualityGain }, p95Latency: { met: latencyMet, need: `<= ${T.p95LatencyRatio}x baseline`, value: round(p95Ratio) }, all },
+  };
+}
+
+/**
+ * Judge a paired replay against the section 5 routing-promotion row.
+ * `status`: `invalid` | `unmeasured` | `insufficient-population` | `fail` | `pass`, in that precedence. Never throws.
+ */
+export function evaluatePromotion({ frozen, replay, replicates = 1000, log = null } = {}) {
+  const invalidations = [];
+  const inval = (code, detail) => invalidations.push({ code, detail });
+  if (!frozenIntact(frozen)) inval('frozen-set-edited', 'the frozen task set does not match its own hash');
+  if (!replay || replay.schema !== REPLAY_SCHEMA || digestOf({ ...replay, replayHash: undefined }) !== replay.replayHash) inval('replay-edited', 'the replay does not match its own hash');
+  const pairs = Array.isArray(replay?.pairs) ? replay.pairs : [];
+  if (frozenIntact(frozen) && replay) {
+    if (replay.frozenHash !== frozen.hash) inval('cherry-picked', 'the replay was built against a different task set than the frozen one');
+    const frozenIds = new Set(frozen.tasks.map((t) => t.taskId));
+    const seen = new Map();
+    for (const p of pairs) seen.set(p.taskId, (seen.get(p.taskId) || 0) + 1);
+    const extras = [...seen.keys()].filter((id) => !frozenIds.has(id));
+    const repeated = [...seen.entries()].filter(([, c]) => c > 1).map(([id]) => id);
+    const absent = [...frozenIds].filter((id) => !seen.has(id));
+    if (extras.length || repeated.length) inval('cherry-picked', `${extras.length} task(s) outside the frozen set, ${repeated.length} repeated`);
+    if (absent.length) inval('dropped-tasks', `${absent.length} frozen task(s) are missing from the replay`);
+  }
+  const dropped = pairs.filter((p) => p.status === 'dropped');
+  if (dropped.length) {
+    const byReason = {};
+    for (const d of dropped) byReason[d.dropReason] = (byReason[d.dropReason] || 0) + 1;
+    inval('dropped-tasks', `${dropped.length} frozen task(s) could not be paired: ${Object.entries(byReason).map(([k, v]) => `${k} x${v}`).join(', ')}`);
+  }
+  const rp = replay?.replay;
+  if (rp) {
+    if (rp.truncated) inval('truncated-replay', 'the replay stopped at its bound, so tasks were left unpaired');
+    if (rp.calls > 0 && (!rp.authorized || !rp.bounds || rp.calls > rp.bounds.maxCalls || rp.spentUsd > rp.bounds.maxUsd)) inval('unbounded-replay', 'paid calls were made without a valid authorization or beyond its bounds');
+  }
+
+  const protocolHash = frozen?.hash ?? 'no-frozen-set';
+  const overall = analyse(pairs, { replicates, protocolHash, name: 'routing-promotion|overall' });
+  const strata = {};
+  for (const s of Object.keys(frozen?.strata ?? {}).sort()) {
+    const sub = analyse(pairs.filter((p) => p.stratum === s), { replicates, protocolHash, name: `routing-promotion|${s}` });
+    const enough = sub.adjudicated >= ROUTING_MINIMUMS.pairedTasksPerStratum;
+    strata[s] = { ...sub, frozenTasks: frozen.strata[s], promoted: enough && sub.criteria.all, reason: !enough ? `${sub.adjudicated} paired adjudicated task(s); ${ROUTING_MINIMUMS.pairedTasksPerStratum} are required` : sub.criteria.all ? 'criteria met' : 'criteria not met' };
+  }
+  const promotedStrata = Object.entries(strata).filter(([, v]) => v.promoted).map(([k]) => k);
+  const synthetic = (frozen?.synthetic === true) || pairs.some((p) => p.status === 'paired' && (p.baseline.synthetic || p.proposed.synthetic));
+
+  let status; let reason;
+  if (invalidations.length) { status = 'invalid'; reason = `the gate is invalidated: ${invalidations.map((i) => i.code).join(', ')}`; }
+  else if (synthetic) { status = 'unmeasured'; reason = 'the population is synthetic: it exercises the machinery and measures nothing about real routing'; }
+  else if (overall.adjudicated < ROUTING_MINIMUMS.pairedTasksOverall) { status = 'insufficient-population'; reason = `${overall.adjudicated} paired adjudicated task(s); ${ROUTING_MINIMUMS.pairedTasksOverall} are required`; }
+  else if (!Object.values(strata).some((v) => v.adjudicated >= ROUTING_MINIMUMS.pairedTasksPerStratum)) { status = 'insufficient-population'; reason = `no stratum has ${ROUTING_MINIMUMS.pairedTasksPerStratum} paired adjudicated tasks`; }
+  else if (!overall.criteria.all) { status = 'fail'; reason = 'the overall quality, cost or latency criteria are not met'; }
+  else if (!promotedStrata.length) { status = 'fail'; reason = 'no stratum meets the criteria on its own sample'; }
+  else { status = 'pass'; reason = `criteria met overall and in ${promotedStrata.length} stratum/strata`; }
+
+  const versions = [...new Set(pairs.filter((p) => p.status === 'paired').flatMap((p) => [p.baseline, p.proposed]).filter((a) => a.served).map((a) => `${a.model}@${a.modelVersion ?? 'unversioned'}`))].sort();
+  const verdict = {
+    schema: PROMOTION_SCHEMA, status, reason, invalidations, synthetic, frozenHash: frozen?.hash ?? null, replayHash: replay?.replayHash ?? null,
+    thresholds: { ...ROUTING_MINIMUMS, ...ROUTING_PROMOTION_TARGETS }, replicates,
+    overall, strata, promotedStrata, testedModelVersions: versions,
+    claim: status === 'pass' ? { allowed: true, scope: promotedStrata, modelVersions: versions, note: 'applies to the listed strata and model versions only' } : { allowed: false, note: 'no routing advantage is claimed' },
+  };
+  verdict.verdictHash = digestOf({ ...verdict, verdictHash: undefined });
+  if (log) log.append('promotion', { status, reason, invalidations, verdictHash: verdict.verdictHash, frozenHash: verdict.frozenHash, replayHash: verdict.replayHash });
+  return verdict;
+}

package/src/posture/routing/receipts.js

@@ -0,0 +1,59 @@
+// Routing decision receipts (X-605, X-606, X-608): an append-only, hash-chained log of every shadow decision, replay, drift
+// assessment, canary event, rollback, promotion verdict and operator control change.
+//
+// Why a chain. A rollback must not lose the evidence of the decisions that led to it, and an exported log must be checkable by
+// someone with only the file. Each receipt carries the hash of the previous one, so a missing, reordered or edited receipt breaks
+// `verifyReceiptChain`. This is tamper EVIDENCE for whoever holds the export, not a signature and not independent certification.
+//
+// A receipt body is JSON-cloned on the way in (no live references, no functions), and callers pass sanitized decision metadata only:
+// never a prompt, a response or source text. The clock is a parameter, so a reproduction can fix it.
+
+import { digestOf } from '../assurance/identity.js';
+
+export const ROUTING_RECEIPT_SCHEMA = 'agentic-security/routing-receipt-chain';
+export const ROUTING_RECEIPT_KINDS = Object.freeze(['shadow-decision', 'replay', 'promotion', 'drift', 'canary', 'rollback', 'control', 'feedback']);
+const MAX_RECEIPTS = 100_000;
+const GENESIS = 'sha256:genesis';
+
+export function createReceiptLog({ now = () => new Date().toISOString() } = {}) {
+  const receipts = [];
+  return {
+    append(kind, body) {
+      if (!ROUTING_RECEIPT_KINDS.includes(kind)) throw new Error(`unknown routing receipt kind '${kind}'`);
+      if (receipts.length >= MAX_RECEIPTS) throw new Error('routing receipt log is full');
+      const r = { seq: receipts.length, kind, at: now(), body: JSON.parse(JSON.stringify(body ?? null)), prev: receipts.length ? receipts[receipts.length - 1].hash : GENESIS };
+      r.hash = digestOf({ ...r, hash: undefined });
+      receipts.push(Object.freeze(r));
+      return r;
+    },
+    entries() { return receipts.slice(); },
+    head() { return receipts.length ? receipts[receipts.length - 1].hash : GENESIS; },
+    get length() { return receipts.length; },
+  };
+}
+
+/** Recompute every hash and link. Fails closed on any gap, reorder, edit or unknown kind. */
+export function verifyReceiptChain(receipts) {
+  if (!Array.isArray(receipts)) return { ok: false, reason: 'not a list of receipts', brokenAt: null };
+  let prev = GENESIS;
+  for (let i = 0; i < receipts.length; i++) {
+    const r = receipts[i];
+    if (!r || typeof r !== 'object') return { ok: false, reason: `receipt ${i} is not an object`, brokenAt: i };
+    if (r.seq !== i) return { ok: false, reason: `receipt ${i} has sequence ${r.seq} (a receipt is missing or reordered)`, brokenAt: i };
+    if (!ROUTING_RECEIPT_KINDS.includes(r.kind)) return { ok: false, reason: `receipt ${i} has an unknown kind`, brokenAt: i };
+    if (r.prev !== prev) return { ok: false, reason: `receipt ${i} does not link to the one before it`, brokenAt: i };
+    if (digestOf({ ...r, hash: undefined }) !== r.hash) return { ok: false, reason: `receipt ${i} was modified after it was written`, brokenAt: i };
+    prev = r.hash;
+  }
+  return { ok: true, reason: 'chain verified', brokenAt: null };
+}
+
+/** The portable export: the chain plus its head, checkable offline with `verifyReceiptChain`. */
+export function exportReceipts(log) {
+  const receipts = log.entries();
+  const byKind = Object.fromEntries(ROUTING_RECEIPT_KINDS.map((k) => [k, receipts.filter((r) => r.kind === k).length]));
+  return JSON.parse(JSON.stringify({
+    schema: ROUTING_RECEIPT_SCHEMA, schemaVersion: '1.0.0', count: receipts.length, byKind, headHash: log.head(), receipts,
+    disclosure: 'a hash-linked log: tamper evidence for the holder of the export, not a signature and not independent certification',
+  }));
+}

package/src/posture/routing/report.js

@@ -0,0 +1,142 @@
+// Routing replay report and policy card (X-608.AC01, X-608.AC02).
+//
+// The report restates a promotion verdict (promotion.js) with exact denominators, so nobody has to rerun the arithmetic to see how
+// many tasks stand behind a figure. It never adds a claim the verdict did not earn:
+//
+//   - a quality difference always appears with its interval, or with the reason it could not be measured;
+//   - cost is the MEASURED median and total (retries and tool execution included), or `incomplete`; never a prediction;
+//   - cache conditions and latency percentiles for both arms sit beside the cost figure they qualify;
+//   - claims are restricted to the strata and model versions the gate actually passed. Unsupported strata and every unmet
+//     criterion stay listed, whatever the overall status.
+//
+// A synthetic population reads `unmeasured` and the report says no advantage is claimed. The output is deterministic: no clock (the
+// caller passes `generatedAt` or nothing) and a content hash, so a rerun from the same manifests is checkable byte for byte.
+
+import { digestOf } from '../assurance/identity.js';
+import { DRIFT_KINDS } from './drift.js';
+import { ROUTING_MODES } from './control.js';
+
+export const REPORT_SCHEMA = 'agentic-security/routing-replay-report';
+export const POLICY_CARD_SCHEMA = 'agentic-security/routing-policy-card';
+
+const NOT_CLAIMED = Object.freeze([
+  'no routing cost or quality advantage is claimed outside the strata and model versions listed under claims.scope',
+  'no claim is made about task kinds, languages, vulnerability classes or context sizes that were not tested',
+  'no claim is made for a provider model version other than those tested, or for different prices or cache conditions',
+]);
+
+function unmetCriteria(verdict) {
+  const out = [];
+  const c = verdict.overall?.criteria;
+  if (verdict.status !== 'pass') out.push({ gate: 'routing-promotion', status: verdict.status, reason: verdict.reason });
+  if (c) {
+    if (c.qualityLowerBound.met !== true) out.push({ gate: 'quality-lower-bound', met: c.qualityLowerBound.met, need: c.qualityLowerBound.need, value: c.qualityLowerBound.value });
+    if (c.advantage.met !== true) out.push({ gate: 'cost-or-quality-advantage', met: c.advantage.met, needMedianCostReduction: c.advantage.needMedianCostReduction, needQualityGain: c.advantage.needQualityGain });
+    if (c.p95Latency.met !== true) out.push({ gate: 'p95-latency', met: c.p95Latency.met, need: c.p95Latency.need, value: c.p95Latency.value });
+  }
+  for (const i of verdict.invalidations || []) out.push({ gate: 'invalidation', code: i.code, detail: i.detail });
+  return out;
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.frozen    freezeTaskSet().frozen
+ * @param {object} o.replay    replayPaired() result
+ * @param {object} o.verdict   evaluatePromotion() result
+ * @param {object} [o.receipts] exportReceipts() result, for its head hash
+ * @param {string|null} [o.generatedAt]
+ */
+export function buildRoutingReplayReport({ frozen, replay, verdict, receipts = null, generatedAt = null }) {
+  const pairs = replay?.pairs ?? [];
+  const byStratum = {};
+  const passed = verdict.status === 'pass';
+  for (const [s, v] of Object.entries(verdict.strata || {})) {
+    // a stratum is SUPPORTED only when the whole gate passed; meeting the criteria on its own sample is not enough while the gate reads
+    // unmeasured, invalid, insufficient-population or fail
+    byStratum[s] = {
+      frozenTasks: v.frozenTasks, pairedTasks: v.pairedTasks, adjudicated: v.adjudicated, unadjudicated: v.unadjudicated, supported: passed && v.promoted,
+      criteriaMetOnSample: v.promoted, reason: passed ? v.reason : (v.promoted ? `criteria met on this sample, but the gate reads '${verdict.status}'` : v.reason),
+      quality: v.quality, cost: v.cost, latencyMs: v.latencyMs, criteria: v.criteria,
+    };
+  }
+  const supported = Object.entries(byStratum).filter(([, v]) => v.supported).map(([k]) => k);
+  const unsupported = Object.entries(byStratum).filter(([, v]) => !v.supported).map(([k, v]) => ({ stratum: k, reason: v.reason, adjudicated: v.adjudicated }));
+  const o = verdict.overall;
+  const claims = verdict.claim.allowed
+    ? {
+      allowed: true, scope: verdict.claim.scope, modelVersions: verdict.claim.modelVersions,
+      statements: verdict.claim.scope.map((s) => `Stratum ${s}: the proposed policy met the routing-promotion criteria on ${byStratum[s].adjudicated} paired adjudicated task(s), for model versions ${verdict.claim.modelVersions.join(', ')}, under the cache conditions shown.`),
+    }
+    : { allowed: false, scope: [], modelVersions: [], statements: [] };
+  const report = {
+    schema: REPORT_SCHEMA, schemaVersion: '1.0.0', generatedAt, synthetic: verdict.synthetic,
+    status: verdict.status, reason: verdict.reason,
+    denominators: {
+      frozenTasks: frozen.count, pairedTasks: o.pairedTasks, droppedTasks: pairs.filter((p) => p.status === 'dropped').length,
+      adjudicated: o.adjudicated, unadjudicated: o.unadjudicated,
+      replay: { offline: replay.replay.offline, paidCalls: replay.paidCalls, spentUsd: replay.replay.spentUsd, truncated: replay.replay.truncated, bounds: replay.replay.bounds },
+    },
+    comparison: { quality: o.quality, cost: o.cost, cache: o.cache, latencyMs: o.latencyMs, failures: o.failures },
+    strata: byStratum, supportedStrata: supported, unsupportedStrata: unsupported,
+    gate: { thresholds: verdict.thresholds, criteria: o.criteria, invalidations: verdict.invalidations },
+    unmetGates: unmetCriteria(verdict),
+    claims, notClaimed: NOT_CLAIMED.slice(),
+    reproduce: { frozenHash: frozen.hash, replayHash: verdict.replayHash, verdictHash: verdict.verdictHash, receiptsHead: receipts ? receipts.headHash : null, command: 'npm run reproduce:routing' },
+    disclosure: verdict.synthetic ? 'SYNTHETIC population: this exercises the machinery and measures nothing about real routing' : 'the figures describe the tested strata and model versions only',
+  };
+  report.reportHash = digestOf({ ...report, reportHash: undefined });
+  return report;
+}
+
+const pct = (x) => (x === null || x === undefined ? 'n/a' : `${(x * 100).toFixed(1)}%`);
+const num = (x) => (x === null || x === undefined ? 'n/a' : String(x));
+
+/** Plain-text rendering of the report. Same content as the object; nothing is added or softened. */
+export function renderRoutingReport(r) {
+  const q = r.comparison.quality; const c = r.comparison.cost; const l = r.comparison.latencyMs;
+  const lines = [];
+  lines.push(`Routing replay report (${r.synthetic ? 'SYNTHETIC' : 'measured'}): ${r.status}`);
+  lines.push(r.reason);
+  lines.push('');
+  lines.push(`Denominators: ${r.denominators.frozenTasks} frozen task(s), ${r.denominators.pairedTasks} paired, ${r.denominators.droppedTasks} dropped, ${r.denominators.adjudicated} paired adjudicated, ${r.denominators.unadjudicated} unadjudicated.`);
+  lines.push(`Replay: ${r.denominators.replay.offline ? 'offline (recorded outcomes)' : 'authorized and bounded'}, ${r.denominators.replay.paidCalls} paid call(s), $${r.denominators.replay.spentUsd}${r.denominators.replay.truncated ? ', TRUNCATED' : ''}.`);
+  lines.push(`Quality: baseline ${pct(q.baseline)}, proposed ${pct(q.proposed)}, difference ${num(q.difference)}, 95% interval ${q.interval.status === 'measured' ? `[${num(q.interval.low)}, ${num(q.interval.high)}]` : `unmeasured (${q.interval.reason || q.interval.status})`}.`);
+  lines.push(`Measured cost: median baseline $${num(c.medianBaselineUsd)}, proposed $${num(c.medianProposedUsd)}, reduction ${pct(c.medianReduction)}${c.complete ? '' : ' (INCOMPLETE: a cost was unknown)'}; retries ${c.retriesBaseline} vs ${c.retriesProposed}.`);
+  lines.push(`Cache (baseline): ${JSON.stringify(r.comparison.cache.baseline)}; (proposed): ${JSON.stringify(r.comparison.cache.proposed)}.`);
+  lines.push(`Latency ms: p50 ${num(l.baselineP50)} vs ${num(l.proposedP50)}, p95 ${num(l.baselineP95)} vs ${num(l.proposedP95)}, ratio ${num(l.p95Ratio)}${l.complete ? '' : ' (INCOMPLETE)'}.`);
+  lines.push(`Failures (baseline): ${JSON.stringify(r.comparison.failures.baseline)}; (proposed): ${JSON.stringify(r.comparison.failures.proposed)}.`);
+  lines.push('');
+  lines.push(`Supported strata: ${r.supportedStrata.length ? r.supportedStrata.join(', ') : 'none'}.`);
+  for (const u of r.unsupportedStrata) lines.push(`  unsupported: ${u.stratum} (${u.reason})`);
+  lines.push('Unmet gates:');
+  if (!r.unmetGates.length) lines.push('  none'); else for (const g of r.unmetGates) lines.push(`  ${g.gate}: ${JSON.stringify(g)}`);
+  lines.push('Claims:');
+  if (!r.claims.allowed) lines.push('  none. No routing advantage is claimed.'); else for (const s of r.claims.statements) lines.push(`  ${s}`);
+  for (const n of r.notClaimed) lines.push(`  not claimed: ${n}`);
+  lines.push(`Reproduce: ${r.reproduce.command} (frozen ${r.reproduce.frozenHash}, verdict ${r.reproduce.verdictHash}).`);
+  return lines.join('\n');
+}
+
+/** The policy card: what the policy is, what it was tested on, what is not claimed, and how an operator controls it. */
+export function buildPolicyCard({ policy, report, control, canaryLimits = null, driftPolicy = null }) {
+  const card = {
+    schema: POLICY_CARD_SCHEMA, schemaVersion: '1.0.0', synthetic: report.synthetic,
+    policy: { version: policy.version, objective: policy.objective, minQualityLower: policy.minQualityLower, maxIntervalWidth: policy.maxIntervalWidth, maxEvidenceAgeDays: policy.maxEvidenceAgeDays, fallbackMode: policy.fallbackMode ?? 'baseline-unverified', budget: policy.budget },
+    constraintOrder: ['availability', 'capability', 'privacy', 'context', 'quality', 'uncertainty', 'freshness', 'budget'],
+    evidence: { gateStatus: report.status, reason: report.reason, testedStrata: report.supportedStrata, untestedOrUnsupportedStrata: report.unsupportedStrata, testedModelVersions: report.claims.modelVersions },
+    claims: report.claims, notClaimed: report.notClaimed, unmetGates: report.unmetGates,
+    controls: {
+      modes: ROUTING_MODES.slice(), current: control ? { mode: control.mode, pin: control.pin, source: control.source } : null,
+      howTo: ['AGENTIC_SECURITY_ROUTING=disabled', 'AGENTIC_SECURITY_ROUTING=pin:<model>', 'AGENTIC_SECURITY_ROUTING=adaptive', 'AGENTIC_SECURITY_NO_MODEL_ROUTING=1 (kill switch)'],
+      receipts: 'every shadow decision, replay, drift assessment, canary event and rollback is in an exportable hash-linked receipt log',
+    },
+    safety: {
+      driftTriggers: DRIFT_KINDS.slice(), onInvalidation: driftPolicy?.onInvalidation ?? 'fallback',
+      canary: canaryLimits ? { maxTasks: canaryLimits.maxTasks, budgetUsd: canaryLimits.budgetUsd, maxErrorRate: canaryLimits.maxErrorRate, maxConsecutiveErrors: canaryLimits.maxConsecutiveErrors, maxIncorrectRate: canaryLimits.maxIncorrectRate } : null,
+    },
+    dataHandling: 'feedback keeps an allowlist of metadata; source code and evidence reach a provider only when the task policy and the egress policy both allow it',
+    reproduce: report.reproduce,
+  };
+  card.cardHash = digestOf({ ...card, cardHash: undefined });
+  return card;
+}

package/src/posture/routing/shadow.js

@@ -0,0 +1,53 @@
+// Shadow mode (X-605.AC01): record the route the constrained policy WOULD pick, and change nothing.
+//
+// The recorder has no transport, no adapter and no client: it cannot issue a provider call, paid or otherwise, so "no extra paid
+// calls by default" holds by construction rather than by a flag. `shadow()` returns the production route it was given, the same object
+// and untouched; the proposal is only written to the record list (and the receipt log, when one is supplied). Whether a proposal is
+// ever acted on is the promotion gate's decision (promotion.js), not this module's.
+//
+// If the operator disabled adaptive routing (control.js) nothing is decided or recorded.
+
+import { routeConstrained } from './decide.js';
+
+export const SHADOW_SCHEMA = 'agentic-security/routing-shadow-record';
+
+export function createShadowRecorder({ log = null, control = null } = {}) {
+  const records = [];
+  return {
+    /**
+     * @param {object} o
+     * @param {object} o.task             from buildRoutingTask
+     * @param {{model:string, effort?:string}} o.productionRoute  the route production will use; returned unchanged
+     * @param {...object} o.rest          the remaining routeConstrained inputs (candidates, calibration, policy, now, egress, ...)
+     */
+    shadow({ task, productionRoute, ...decideArgs }) {
+      if (!productionRoute || typeof productionRoute.model !== 'string' || !productionRoute.model) {
+        throw new Error('shadow mode needs the production route it is shadowing');
+      }
+      if (control && control.mode === 'disabled') {
+        return { route: productionRoute, shadow: null, recorded: false, paidCalls: 0, reason: 'adaptive routing is disabled by the operator' };
+      }
+      const decision = routeConstrained({ ...decideArgs, task, baselineRoute: productionRoute });
+      const record = Object.freeze({
+        schema: SHADOW_SCHEMA, taskId: task?.taskId ?? null, stratum: task?.stratum ?? null,
+        production: Object.freeze({ model: productionRoute.model }),
+        proposed: Object.freeze({
+          status: decision.status, code: decision.code, model: decision.selected ? decision.selected.model : null,
+          modelVersion: decision.selected ? decision.selected.modelVersion : null, via: decision.selected ? decision.selected.via : null,
+          policyVersion: decision.policyVersion, decisionHash: decision.decisionHash,
+        }),
+        synthetic: decision.synthetic === true || task?.synthetic === true, paidCalls: 0,
+      });
+      records.push(record);
+      if (log) log.append('shadow-decision', record);
+      return { route: productionRoute, shadow: record, recorded: true, paidCalls: 0 };
+    },
+    records() { return records.slice(); },
+    /** The latest record for each task. A re-decision replaces the earlier one in this view; the earlier record stays in `records()`. */
+    latestByTask() {
+      const m = new Map();
+      for (const r of records) m.set(r.taskId, r);
+      return [...m.values()];
+    },
+  };
+}

package/src/posture/specification-mining.js

@@ -27,6 +27,8 @@
 //   isAdmin / requireAdmin             → references admin role check
 //   requireAuth / mustBeLoggedIn       → references auth middleware / login flag
 
+import { inferredInvariant } from './invariants/lifecycle.js';
+
 const NAME_FAMILIES = [
   {
     label: 'ownership-check',
@@ -168,3 +170,27 @@ export function scanSpecificationDrift(fileContents) {
   }
   return findings;
 }
+
+// X-402: the same name families, read as INTENT instead of as drift. A function named `validateOwnership` implies a tenant
+// isolation contract whether or not its body satisfies it; a function named `requireAdmin` implies a privilege constraint. Each
+// becomes a PROPOSED invariant (inferred, with its source and an uncertainty), a skeleton for a reviewer to revise. Nothing here
+// approves anything: a mined contract is a hypothesis and is advisory until a reviewer approves it in the signed ledger.
+const INVARIANT_CLASS_BY_FAMILY = Object.freeze({ 'ownership-check': 'tenant-isolation', 'authorization-check': 'privilege-constraint', 'admin-gate': 'privilege-constraint' });
+
+export function mineInvariantProposals(fileContents) {
+  const out = [];
+  if (!fileContents || typeof fileContents !== 'object') return out;
+  for (const [fp, text] of Object.entries(fileContents)) {
+    const lang = inferLang(fp);
+    if (!lang) continue;
+    for (const fn of extractFunctionBodies(text, lang)) {
+      for (const fam of NAME_FAMILIES) {
+        const cls = INVARIANT_CLASS_BY_FAMILY[fam.label];
+        if (!cls || !fam.nameRe.test(fn.name)) continue;
+        const inv = inferredInvariant({ class: cls, source: 'specification-mining', evidence: { file: fp, line: fn.startLine, function: fn.name, family: fam.label }, uncertainty: 0.65, action: fn.name });
+        if (inv) out.push(inv);
+      }
+    }
+  }
+  return out;
+}