@clear-capabilities/agentic-security-scanner 0.161.0 → 0.163.0

package/src/posture/routing/decide.js

@@ -0,0 +1,211 @@
+// Constrained routing decisions (X-604).
+//
+// A decision is made in two stages that never swap places:
+//
+//   1. CONSTRAINTS. A candidate model is acceptable only if it is available, has every capability the task requires, is allowed to
+//      receive the task's data (the egress policy, egress/policy.js, decides; the capability manifest's egress check is used when a
+//      manifest is supplied), has a context window that fits the task, and has RELIABLE calibrated quality evidence that is fresh,
+//      narrow enough and whose LOWER bound meets the policy's minimum quality, and fits the remaining budget.
+//   2. OPTIMIZATION. Only among acceptable candidates is cost (or latency) minimised, using MEASURED cost and latency from the
+//      calibration. A candidate with no measured cost is ranked behind every candidate that has one, on its catalog upper bound, and
+//      the explanation says so.
+//
+// Every candidate is evaluated against every constraint and ALL failures are recorded, so the explanation shows why each was
+// rejected, not only the first reason. When nothing is acceptable the outcome is one of:
+//
+//   fallback  the existing capability route (the baseline), but only if it passes the HARD constraints (capability, privacy, context,
+//             budget). Its quality is then `unverified`, and the decision says so. `fallbackMode: 'block'` refuses this entirely.
+//   blocked   with a code: `no-compliant-model`, `budget-exhausted`, `insufficient-quality-evidence`, `excessive-uncertainty`,
+//             `stale-evidence`, `invalid-policy`. A blocked decision selects nothing. A constraint is never relaxed to find a route.
+//
+// Pure given its inputs: the clock is a parameter (`now`), the egress evaluator is injectable, no network.
+
+import { digestOf } from '../assurance/identity.js';
+import { evaluateEgress } from '../../egress/policy.js';
+import { costOf } from './economics.js';
+
+export const DECISION_SCHEMA = 'agentic-security/routing-decision';
+const DECISION_VERSION = '1.0.0';
+export const CONSTRAINTS = Object.freeze(['availability', 'capability', 'privacy', 'context', 'quality', 'uncertainty', 'freshness', 'budget']);
+export const BLOCK_CODES = Object.freeze(['no-compliant-model', 'budget-exhausted', 'insufficient-quality-evidence', 'excessive-uncertainty', 'stale-evidence', 'invalid-policy', 'invalid-task']);
+const HARD = Object.freeze(['availability', 'capability', 'privacy', 'context']);
+const DAY = 86_400_000;
+
+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;
+}
+
+export function validateRoutingPolicy(p) {
+  const errors = [];
+  const bad = (path, message) => errors.push({ code: 'BAD_POLICY', path, message });
+  if (!p || typeof p !== 'object') return { ok: false, errors: [{ code: 'BAD_POLICY', path: '', message: 'not an object' }] };
+  if (typeof p.version !== 'string' || !p.version) bad('version', 'a policy is versioned');
+  const frac = (k, lo, hiOpen) => { if (!(typeof p[k] === 'number' && Number.isFinite(p[k]) && p[k] >= lo && p[k] <= 1)) bad(k, `must be a number in [${lo}, 1]`); else if (hiOpen && p[k] === lo) bad(k, 'must be above 0'); };
+  frac('minQualityLower', 0, false); frac('maxIntervalWidth', 0, true);
+  if (!(typeof p.maxEvidenceAgeDays === 'number' && p.maxEvidenceAgeDays > 0)) bad('maxEvidenceAgeDays', 'must be a positive number');
+  if (!['cost', 'latency'].includes(p.objective)) bad('objective', "must be 'cost' or 'latency'");
+  if (p.fallbackMode !== undefined && !['baseline-unverified', 'block'].includes(p.fallbackMode)) bad('fallbackMode', "must be 'baseline-unverified' or 'block'");
+  if (!p.budget || !(typeof p.budget.remainingUsd === 'number' && Number.isFinite(p.budget.remainingUsd))) bad('budget.remainingUsd', 'a finite remaining budget is required');
+  if (!(Number.isInteger(p.expectedOutputTokens) && p.expectedOutputTokens >= 0)) bad('expectedOutputTokens', 'a non-negative integer bound on output size is required');
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * A candidate from the provider catalog's price entry plus operator-supplied facts. The catalog carries prices and cache models but
+ * NOT capabilities or context windows, and this function does not invent them: a missing `maxContextTokens` stays null and the
+ * candidate is rejected on the context constraint as unknown.
+ */
+export function candidateFromCatalog({ id, provider, modelVersion = null, priceBook, capabilities = [], maxContextTokens = null, endpoint = null, local = false, available = true }) {
+  return { id, provider, modelVersion, capabilities: [...capabilities].sort(), maxContextTokens, endpoint, local, available, price: priceBook?.entries?.[id] ?? null };
+}
+
+const fresh = (artifact, est, now, maxDays) => {
+  const latest = est?.latestObservationAt || artifact?.latestObservationAt || null;
+  if (!latest || Number.isNaN(Date.parse(latest))) return { fresh: false, ageDays: null, latest };
+  const ageDays = (Date.parse(now) - Date.parse(latest)) / DAY;
+  return { fresh: ageDays >= 0 && ageDays <= maxDays, ageDays: Math.round(ageDays * 1000) / 1000, latest };
+};
+
+function expectedCost(c, task, policy, est) {
+  const priced = c.price && costOf({
+    usage: { inputTokens: task.contextTokens, outputTokens: policy.expectedOutputTokens, cachedInputTokens: 0, source: 'measured' },
+    model: c.id, priceBook: { version: 'candidate-price', currency: 'USD', billingBasis: 'list-price', entries: { [c.id]: c.price } },
+    toolExecutionUsd: 0, // the bound covers model tokens only; tool execution is priced by the caller's runner
+  });
+  // The upper bound is the catalog price on the full request with NO cache credit: a ceiling for the budget check, not a measurement.
+  const upperUsd = priced && priced.totalStatus !== 'unknown' ? priced.totalUpperUsd : null;
+  const measuredP50 = est && est.costUsd && est.costUsd.n > 0 ? est.costUsd.p50 : null;
+  return { measuredP50Usd: measuredP50, boundUpperUsd: upperUsd, basis: measuredP50 !== null ? 'measured-median' : upperUsd !== null ? 'catalog-upper-bound' : 'unknown' };
+}
+
+/**
+ * Decide a route for one task.
+ *
+ * @param {object} o
+ * @param {object} o.task          from buildRoutingTask
+ * @param {object[]} o.candidates  candidate descriptors (see candidateFromCatalog)
+ * @param {object|null} o.calibration  buildCalibration() artifact
+ * @param {object} o.policy        versioned routing policy (validateRoutingPolicy)
+ * @param {string} o.now           ISO timestamp; the only clock this function sees
+ * @param {{model:string, effort?:string, reason?:string}|null} o.baselineRoute  the existing capability route, used as the fallback
+ * @param {(ctx)=>object} [o.egress]  egress evaluator, default evaluateEgress
+ * @param {string} [o.scanRoot]
+ * @param {((egressCtx)=>object)|null} [o.manifestEgress]  optional capability-manifest egress check, used INSTEAD of `egress`; for example
+ *        `(ctx) => evaluateManifestEgress(bound, binding, ctx)` from capabilities/egress.js, which applies the task grant AND the operator policy
+ */
+export function routeConstrained({ task, candidates, calibration = null, policy, now, baselineRoute = null, egress = evaluateEgress, scanRoot = null, manifestEgress = null, allowSynthetic = false }) {
+  const header = { schema: DECISION_SCHEMA, schemaVersion: DECISION_VERSION, policyVersion: policy?.version ?? null, taskId: task?.taskId ?? null, stratum: task?.stratum ?? null };
+  const finish = (d) => { const out = { ...header, ...d }; out.decisionHash = digestOf({ ...out, decisionHash: undefined }); return deepFreeze(JSON.parse(JSON.stringify(out))); };
+  const pv = validateRoutingPolicy(policy);
+  if (!pv.ok) return finish({ status: 'blocked', code: 'invalid-policy', reason: pv.errors.map((e) => `${e.path}: ${e.message}`).join('; '), selected: null, candidates: [], alternatives: [], fallback: null });
+  if (!task || !task.stratum || !Array.isArray(task.requiredCapabilities) || Number.isNaN(Date.parse(now))) {
+    return finish({ status: 'blocked', code: 'invalid-task', reason: 'a valid task record and an ISO `now` are required', selected: null, candidates: [], alternatives: [], fallback: null });
+  }
+  const permitSynthetic = allowSynthetic === true || policy.allowSynthetic === true;
+  const remaining = policy.budget.remainingUsd;
+  const evalOne = (c) => {
+    const rejections = [];
+    const rej = (constraint, code, detail) => rejections.push({ constraint, code, detail });
+    if (c.available === false) rej('availability', 'unavailable', 'the model is not currently available');
+    const missing = task.requiredCapabilities.filter((cap) => !(c.capabilities || []).includes(cap));
+    if (missing.length) rej('capability', 'missing-capability', `lacks: ${missing.join(', ')}`);
+    // privacy: the egress policy decides whether this task's data class may go to this endpoint/model, and local endpoints are judged the same way
+    if (!c.endpoint) rej('privacy', 'no-endpoint', 'no endpoint is configured, so the egress policy cannot clear it');
+    else {
+      const ectx = { scanRoot, purpose: 'routing-decision', endpoint: c.endpoint, model: c.id, dataClass: task.dataClass, contextTokens: task.contextTokens };
+      let e;
+      try { e = manifestEgress ? manifestEgress(ectx) : egress(ectx); } catch { e = { allowed: false, code: 'egress-error' }; }
+      if (!e || e.allowed !== true) rej('privacy', 'egress-denied', (e && (e.reason || e.code || e.policy?.reason)) || 'egress policy denied');
+    }
+    if (c.maxContextTokens === null || c.maxContextTokens === undefined) rej('context', 'context-unknown', 'the model\'s context window is not known');
+    else if (c.maxContextTokens < task.contextTokens + policy.expectedOutputTokens) rej('context', 'context-too-small', `needs ${task.contextTokens + policy.expectedOutputTokens} tokens, window is ${c.maxContextTokens}`);
+
+    // quality evidence for exactly this model and version
+    const est = calibration ? calibration.estimates.find((x) => x.model === c.id && (x.modelVersion ?? null) === (c.modelVersion ?? null) && x.stratum === task.stratum) : null;
+    const anyVersion = calibration ? calibration.estimates.some((x) => x.model === c.id && x.stratum === task.stratum) : false;
+    let quality = null;
+    if (!est) rej('quality', anyVersion ? 'model-version-mismatch' : 'no-quality-evidence', anyVersion ? 'evidence exists only for another version of this model' : 'no calibration for this model and stratum');
+    else {
+      quality = { estimate: est.accuracy, low: est.interval.low, high: est.interval.high, n: est.n, label: est.label, shift: est.shift };
+      const reliable = est.label === 'reliable' || (est.label === 'reliable-synthetic' && permitSynthetic);
+      if (!reliable) rej('quality', est.label === 'reliable-synthetic' ? 'synthetic-evidence' : `not-reliable:${est.label}`, est.reasons.length ? est.reasons[0] : `calibration label is ${est.label}`);
+      else if (est.interval.low === null || est.interval.low < policy.minQualityLower) rej('quality', 'below-minimum-quality', `lower bound ${est.interval.low} is under the required ${policy.minQualityLower}`);
+      if (est.interval.low !== null && est.interval.high !== null && est.interval.high - est.interval.low > policy.maxIntervalWidth) rej('uncertainty', 'excessive-uncertainty', `interval width ${(est.interval.high - est.interval.low).toFixed(3)} exceeds ${policy.maxIntervalWidth}`);
+      else if (est.interval.low === null) rej('uncertainty', 'unmeasured-uncertainty', 'no uncertainty interval could be measured');
+    }
+    const fr = est ? fresh(calibration, est, now, policy.maxEvidenceAgeDays) : { fresh: null, ageDays: null, latest: null };
+    if (est && !fr.fresh) rej('freshness', 'stale-evidence', fr.latest ? `evidence is ${fr.ageDays} days old, over ${policy.maxEvidenceAgeDays}` : 'evidence has no observation time');
+
+    const cost = expectedCost(c, task, policy, est);
+    if (cost.boundUpperUsd === null && cost.measuredP50Usd === null) rej('budget', 'cost-unknown', 'no price and no measured cost: an unknown cost is never treated as free');
+    else {
+      // budget uses the LARGER of the catalog ceiling and the measured median, so neither can understate what a task may cost
+      const need = Math.max(cost.boundUpperUsd ?? 0, cost.measuredP50Usd ?? 0);
+      if (!(remaining > 0)) rej('budget', 'budget-exhausted', 'no budget remains');
+      else if (need > remaining) rej('budget', 'over-budget', `expected at most ${need} against ${remaining} remaining`);
+      if (typeof policy.budget.maxUsdPerTask === 'number' && need > policy.budget.maxUsdPerTask) rej('budget', 'over-task-cap', `expected at most ${need} against a per-task cap of ${policy.budget.maxUsdPerTask}`);
+    }
+    return {
+      model: c.id, provider: c.provider ?? null, modelVersion: c.modelVersion ?? null, accepted: rejections.length === 0, rejections,
+      quality, evidence: est ? { label: est.label, latestObservationAt: fr.latest, ageDays: fr.ageDays, fresh: fr.fresh, maxAgeDays: policy.maxEvidenceAgeDays, calibrationHash: calibration.calibrationHash } : null,
+      expectedCost: cost, latencyMs: est ? est.latencyMs : null, hardCompliant: rejections.every((r) => !HARD.includes(r.constraint)),
+      fitsBudget: rejections.every((r) => r.constraint !== 'budget'),
+    };
+  };
+  const evaluated = [...candidates].sort((a, b) => (a.id < b.id ? -1 : 1)).map(evalOne);
+  const accepted = evaluated.filter((e) => e.accepted);
+
+  const rank = (e) => {
+    if (policy.objective === 'latency') return [e.latencyMs && e.latencyMs.p50 !== null ? 0 : 1, e.latencyMs?.p50 ?? Infinity, e.expectedCost.measuredP50Usd ?? e.expectedCost.boundUpperUsd ?? Infinity, e.model];
+    return [e.expectedCost.measuredP50Usd !== null ? 0 : 1, e.expectedCost.measuredP50Usd ?? e.expectedCost.boundUpperUsd ?? Infinity, e.latencyMs?.p50 ?? Infinity, e.model];
+  };
+  const cmp = (a, b) => { const ra = rank(a); const rb = rank(b); for (let i = 0; i < ra.length; i++) if (ra[i] !== rb[i]) return ra[i] < rb[i] ? -1 : 1; return 0; };
+  const summary = (e) => ({ model: e.model, modelVersion: e.modelVersion, accepted: e.accepted, rejections: e.rejections, quality: e.quality, evidence: e.evidence, expectedCost: e.expectedCost, latencyMs: e.latencyMs });
+
+  if (accepted.length) {
+    const ordered = [...accepted].sort(cmp);
+    const sel = ordered[0];
+    return finish({
+      status: 'routed', code: null, reason: `selected ${sel.model}: every constraint met, lowest ${policy.objective === 'latency' ? 'p50 latency' : 'cost'} among ${accepted.length} acceptable candidate(s) (${sel.expectedCost.basis})`,
+      selected: { model: sel.model, provider: sel.provider, modelVersion: sel.modelVersion, via: 'optimized' },
+      candidates: evaluated.map(summary),
+      alternatives: ordered.slice(1).map((e) => ({ model: e.model, why: `acceptable, but ${policy.objective === 'latency' ? 'slower' : 'costlier'} than the selection` })),
+      expectedBounds: { quality: { low: sel.quality.low, high: sel.quality.high }, costUsd: { measuredMedian: sel.expectedCost.measuredP50Usd, upperBound: sel.expectedCost.boundUpperUsd, basis: sel.expectedCost.basis }, latencyMs: sel.latencyMs },
+      evidence: sel.evidence, fallback: { considered: false, used: false }, synthetic: calibration?.synthetic === true || sel.quality.label === 'reliable-synthetic',
+    });
+  }
+
+  // Nothing is acceptable. Classify why, then offer the bounded fallback or block.
+  const hard = evaluated.filter((e) => e.hardCompliant);
+  const anyRej = (code) => evaluated.some((e) => e.rejections.some((r) => r.code === code));
+  const budgetExhausted = !(remaining > 0) || (hard.length > 0 && hard.every((e) => !e.fitsBudget));
+  let code;
+  if (!hard.length) code = 'no-compliant-model';
+  else if (budgetExhausted) code = 'budget-exhausted';
+  else if (hard.every((e) => e.rejections.some((r) => r.code === 'stale-evidence'))) code = 'stale-evidence';
+  else if (hard.some((e) => e.rejections.some((r) => r.code === 'excessive-uncertainty')) && !anyRej('no-quality-evidence')) code = 'excessive-uncertainty';
+  else code = 'insufficient-quality-evidence';
+
+  const fb = baselineRoute && baselineRoute.model ? evaluated.find((e) => e.model === baselineRoute.model) : null;
+  const fallbackInfo = { considered: !!baselineRoute, model: baselineRoute?.model ?? null, mode: policy.fallbackMode ?? 'baseline-unverified', used: false, qualityVerified: false };
+  const base = { candidates: evaluated.map(summary), alternatives: [], expectedBounds: null, evidence: null, synthetic: calibration?.synthetic === true };
+  const canFallback = code !== 'no-compliant-model' && code !== 'budget-exhausted' && (policy.fallbackMode ?? 'baseline-unverified') === 'baseline-unverified'
+    && fb && fb.hardCompliant && fb.fitsBudget;
+  // A fallback that could not be taken because it breaks a hard constraint or the budget is blocked, never relaxed.
+  if (canFallback) {
+    return finish({
+      ...base, status: 'fallback', code, reason: `no model has reliable quality evidence that meets the policy (${code}); using the existing capability route ${fb.model}, which passes the capability, privacy, context and budget constraints. Its quality is UNVERIFIED.`,
+      selected: { model: fb.model, provider: fb.provider, modelVersion: fb.modelVersion, via: 'fallback' },
+      expectedBounds: { quality: null, costUsd: { measuredMedian: fb.expectedCost.measuredP50Usd, upperBound: fb.expectedCost.boundUpperUsd, basis: fb.expectedCost.basis }, latencyMs: fb.latencyMs },
+      fallback: { ...fallbackInfo, used: true },
+    });
+  }
+  return finish({
+    ...base, status: 'blocked', code,
+    reason: code === 'no-compliant-model' ? 'no candidate satisfies the capability, privacy and context constraints; no constraint was relaxed'
+      : code === 'budget-exhausted' ? 'the remaining budget cannot cover any compliant candidate; no constraint was relaxed'
+        : `${code}: no reliable evidence clears the policy and the baseline fallback ${fallbackInfo.mode === 'block' ? 'is disabled by policy' : 'does not satisfy the hard constraints or the budget'}`,
+    selected: null, fallback: fallbackInfo,
+  });
+}

package/src/posture/routing/drift.js

@@ -0,0 +1,137 @@
+// Drift detection and explicit invalidation (X-606.AC01).
+//
+// A calibration is evidence about one model version, one price book, one set of record schemas and one measured quality level. When
+// any of those moves, the estimates built on them no longer describe what the router would be choosing, and silently carrying them
+// forward is the failure this module exists to prevent.
+//
+//   snapshotRoutingBasis   what the policy was promoted on: calibration hash, per-model version, per-model price digest, schema versions
+//   assessDrift            compare a snapshot with the present, plus a window of recent decided outcomes
+//   applyInvalidations     a DERIVED calibration in which the affected estimates are labelled `invalidated` (quality, version, schema)
+//                          or have their measured cost removed (pricing), with the reason on the estimate and the artifact
+//
+// Kinds of drift and what each invalidates:
+//   model-version    the candidate's current version differs from the calibrated one (or is no longer reported): that model's estimates
+//   schema           a record or calibration schema version differs: every estimate
+//   pricing          the model's price entry changed: its measured COST (decisions fall back to the catalog upper bound); quality stands
+//   quality-shift    recent decided outcomes sit significantly below the calibrated lower bound: that model/stratum estimate
+//
+// State on any invalidation is the policy's documented choice: `fallback` (the existing capability route stands, because invalidated
+// estimates are refused by the constrained router) or `shadow` (proposals are recorded, production is untouched). It is never
+// `active`, and the assessment says which estimates were invalidated and why. No clock and no network: `now` is not even needed.
+
+import { digestOf } from '../assurance/identity.js';
+import { wilsonInterval } from '../evaluation/interval.js';
+import { CALIBRATION_SCHEMA } from './calibration.js';
+import { ROUTING_OUTCOME_SCHEMA } from './outcomes.js';
+import { DECISION_SCHEMA } from './decide.js';
+
+export const BASIS_SCHEMA = 'agentic-security/routing-basis-snapshot';
+export const DRIFT_KINDS = Object.freeze(['model-version', 'schema', 'pricing', 'quality-shift']);
+export const DRIFT_STATES = Object.freeze(['active', 'fallback', 'shadow']);
+export const DRIFT_DEFAULTS = Object.freeze({ onInvalidation: 'fallback', minRecentDecided: 30 });
+export const SCHEMA_VERSIONS = Object.freeze({ calibration: `${CALIBRATION_SCHEMA}@1.0.0`, outcome: ROUTING_OUTCOME_SCHEMA, decision: DECISION_SCHEMA });
+
+/**
+ * @param {object} o
+ * @param {object} o.calibration  buildCalibration() artifact
+ * @param {object} o.priceBook    priceBookFromCatalog() result
+ * @param {{id:string, modelVersion:string|null}[]} o.models  the candidates the policy was promoted on
+ */
+export function snapshotRoutingBasis({ calibration, priceBook, models, schemas = SCHEMA_VERSIONS }) {
+  const priceDigests = {};
+  for (const m of models) priceDigests[m.id] = priceBook?.entries?.[m.id] ? digestOf(priceBook.entries[m.id]) : null;
+  const quality = {};
+  for (const e of calibration?.estimates ?? []) {
+    if (e.level === 'stratum' && (e.label === 'reliable' || e.label === 'reliable-synthetic')) quality[`${e.model}|${e.modelVersion ?? ''}|${e.stratum}`] = { low: e.interval.low, accuracy: e.accuracy, n: e.n };
+  }
+  const snap = {
+    schema: BASIS_SCHEMA, calibrationHash: calibration?.calibrationHash ?? null, priceVersion: priceBook?.version ?? null,
+    models: Object.fromEntries(models.map((m) => [m.id, m.modelVersion ?? null])), priceDigests, schemas: { ...schemas }, quality,
+    synthetic: calibration?.synthetic === true,
+  };
+  snap.snapshotHash = digestOf({ ...snap, snapshotHash: undefined });
+  return Object.freeze(snap);
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.basis    snapshotRoutingBasis() result
+ * @param {object} o.current  { models: [{id, modelVersion}], priceBook, schemas }
+ * @param {object[]} [o.recentOutcomes]  decided outcomes observed since the snapshot
+ * @param {{onInvalidation?:'fallback'|'shadow', minRecentDecided?:number}} [o.policy]
+ */
+export function assessDrift({ basis, current, recentOutcomes = [], policy = {} }) {
+  const onInvalidation = policy.onInvalidation ?? DRIFT_DEFAULTS.onInvalidation;
+  const minRecent = policy.minRecentDecided ?? DRIFT_DEFAULTS.minRecentDecided;
+  const invalidations = [];
+  const add = (kind, model, modelVersion, stratum, reason) => invalidations.push({ kind, model, modelVersion, stratum, reason });
+  if (!basis || basis.schema !== BASIS_SCHEMA || digestOf({ ...basis, snapshotHash: undefined }) !== basis.snapshotHash) {
+    return { state: DRIFT_STATES.includes(onInvalidation) ? onInvalidation : 'fallback', invalidations: [{ kind: 'schema', model: null, modelVersion: null, stratum: null, reason: 'the basis snapshot is missing or does not match its own hash' }], documentedFallback: onInvalidation, unchanged: false };
+  }
+  const have = new Map((current?.models ?? []).map((m) => [m.id, m.modelVersion ?? null]));
+  for (const [id, version] of Object.entries(basis.models)) {
+    if (!have.has(id)) { add('model-version', id, version, null, `${id} is no longer offered (calibrated at version ${version ?? 'unversioned'})`); continue; }
+    if (have.get(id) !== version) add('model-version', id, version, null, `${id} moved from version ${version ?? 'unversioned'} to ${have.get(id) ?? 'unreported'}; estimates for the old version do not carry over`);
+    const priceNow = current?.priceBook?.entries?.[id] ? digestOf(current.priceBook.entries[id]) : null;
+    if (priceNow !== basis.priceDigests[id]) add('pricing', id, version, null, `the price entry for ${id} changed (price book ${basis.priceVersion} to ${current?.priceBook?.version ?? 'unknown'}); measured cost estimates are no longer valid`);
+  }
+  for (const [k, v] of Object.entries(basis.schemas)) {
+    const now = current?.schemas?.[k];
+    if (now !== v) add('schema', null, null, null, `the ${k} schema changed from ${v} to ${now ?? 'unreported'}`);
+  }
+  // measured quality: recent decided outcomes per (model, version, stratum) against the calibrated lower bound
+  const groups = new Map();
+  for (const o of recentOutcomes) {
+    if (o.outcome !== 'correct' && o.outcome !== 'incorrect') continue;
+    const k = `${o.model}|${o.modelVersion ?? ''}|${o.stratum}`;
+    if (!groups.has(k)) groups.set(k, { correct: 0, n: 0, model: o.model, modelVersion: o.modelVersion ?? null, stratum: o.stratum });
+    const g = groups.get(k); g.n += 1; if (o.outcome === 'correct') g.correct += 1;
+  }
+  for (const [k, g] of [...groups.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    const base = basis.quality[k];
+    if (!base || g.n < minRecent || base.low === null) continue;
+    const w = wilsonInterval(g.correct, g.n);
+    if (w.status === 'measured' && w.high < base.low) add('quality-shift', g.model, g.modelVersion, g.stratum, `recent quality ${g.correct}/${g.n} (95% upper ${w.high.toFixed(3)}) is below the calibrated lower bound ${base.low}`);
+  }
+  const state = invalidations.length ? (DRIFT_STATES.includes(onInvalidation) && onInvalidation !== 'active' ? onInvalidation : 'fallback') : 'active';
+  return {
+    state, invalidations, unchanged: invalidations.length === 0,
+    documentedFallback: invalidations.length ? (state === 'shadow' ? 'shadow: proposals are recorded and production selection is unchanged' : 'fallback: the existing capability route stands; invalidated estimates are refused by the constrained router') : null,
+    kinds: [...new Set(invalidations.map((i) => i.kind))].sort(),
+  };
+}
+
+/** A derived calibration with the assessed invalidations applied. The original artifact is not modified. */
+export function applyInvalidations(calibration, assessment) {
+  const list = assessment?.invalidations ?? [];
+  const schemaWide = list.find((i) => i.kind === 'schema');
+  const estimates = calibration.estimates.map((e) => {
+    const hits = list.filter((i) => {
+      if (i.kind === 'schema') return true;
+      if (i.model !== e.model) return false;
+      if (i.kind === 'model-version') return (i.modelVersion ?? null) === (e.modelVersion ?? null);
+      if (i.kind === 'pricing') return (i.modelVersion ?? null) === (e.modelVersion ?? null);
+      if (i.kind === 'quality-shift') return i.stratum === e.stratum && (i.modelVersion ?? null) === (e.modelVersion ?? null);
+      return false;
+    });
+    if (!hits.length) return e;
+    const qualityHits = hits.filter((h) => h.kind !== 'pricing');
+    const next = JSON.parse(JSON.stringify(e));
+    if (qualityHits.length) {
+      next.label = 'invalidated';
+      next.reasons = qualityHits.map((h) => `${h.kind}: ${h.reason}`);
+      next.fallback = { policy: 'baseline-model', model: calibration.pairing?.baselineModel ?? null, note: 'this estimate was invalidated; the baseline route stands' };
+    }
+    if (hits.some((h) => h.kind === 'pricing' || h.kind === 'schema')) {
+      next.costUsd = { n: 0, unknown: e.costUsd?.n ?? 0, p50: null, invalidated: true, reason: hits.filter((h) => h.kind === 'pricing' || h.kind === 'schema').map((h) => h.reason)[0] };
+    }
+    next.invalidatedBy = hits.map((h) => h.kind).sort();
+    return next;
+  });
+  const out = JSON.parse(JSON.stringify({ ...calibration, estimates }));
+  out.derivedFrom = calibration.calibrationHash;
+  out.invalidations = list;
+  out.invalidatedAll = !!schemaWide;
+  out.calibrationHash = digestOf({ ...out, calibrationHash: undefined });
+  return Object.freeze(out);
+}

package/src/posture/routing/economics.js

@@ -0,0 +1,185 @@
+// Auditable provider economics (X-602).
+//
+// Turns token usage into a cost that says how it was obtained. Extends the provider catalog (posture/provider-catalog.js, which
+// already carries the dated $/1M-token rates and each provider's cache model) rather than keeping a second price table, and sits
+// beside cache-economics.js, which prices Claude Code's own transcript. That module and the interactive cost advisor are unchanged.
+//
+// What "auditable" means here:
+//
+//   - A cost is split into input (uncached prompt tokens), cached input, output, retries and tool execution, and the result names the
+//     price book version, currency and billing basis it was computed against, so two costs are comparable only when those match.
+//   - UNKNOWN IS NOT ZERO. A missing price, a missing token count, an unknown cache split, a subscription whose marginal cost is not
+//     metered: each yields `unknown` (null) or a BOUNDED estimate with a lower and an upper value, never 0. A total with an unknown
+//     component is unknown; it does not quietly sum the parts that happened to be known.
+//   - MEASURED AND PREDICTED NEVER MIX. `measured` is computed only from usage the provider reported. A prediction (from a context
+//     size, say) goes in `predicted`, and the measured fields stay null when no measurement exists. A prediction never fills in for a
+//     measurement, and the budget path in decide.js uses the bounded upper estimate, labelled as such, not a "measured" number.
+//
+// Pure: no fs, no clock, no network. Money is a plain number of the book's currency; sums use the same order every time so a result
+// is reproducible.
+
+import { PROVIDERS, SOURCED_AT } from '../provider-catalog.js';
+import { digestOf } from '../assurance/identity.js';
+
+export const PRICE_BOOK_SCHEMA = 'agentic-security/routing-price-book';
+export const BILLING_BASES = Object.freeze(['list-price', 'contract', 'subscription', 'unknown']);
+/** A basis whose per-token price is not the whole story: a flat subscription has no metered marginal cost. */
+const UNMETERED_BASES = Object.freeze(['subscription', 'unknown']);
+export const COST_STATUS = Object.freeze({ measured: 'measured', bounded: 'bounded-estimate', unknown: 'unknown' });
+const PER = 1_000_000;
+
+/**
+ * The price book derived from the provider catalog. `version` pins the catalog snapshot date, so a price change is a new version, and
+ * the catalog's own warning stands: those rates are a dated snapshot, not live truth.
+ */
+export function priceBookFromCatalog({ providers = PROVIDERS, sourcedAt = SOURCED_AT, billingBasis = 'list-price', currency = 'USD' } = {}) {
+  const entries = {};
+  for (const [provider, p] of Object.entries(providers)) {
+    for (const m of p.models) {
+      entries[m.id] = {
+        provider, in: m.in ?? null, out: m.out ?? null, cached: m.cached ?? null,
+        cacheKind: p.cache?.kind ?? null, cacheMinPrefixTokens: p.cache?.minPrefixTokens ?? null,
+      };
+    }
+  }
+  const book = { schema: PRICE_BOOK_SCHEMA, version: `provider-catalog@${sourcedAt}`, currency, billingBasis, unit: 'per-1M-tokens', sourcedAt, entries };
+  book.digest = digestOf({ ...book, digest: undefined });
+  return book;
+}
+
+export function validatePriceBook(b) {
+  const errors = [];
+  const bad = (path, message) => errors.push({ code: 'BAD_PRICE_BOOK', path, message });
+  if (!b || typeof b !== 'object') return { ok: false, errors: [{ code: 'BAD_PRICE_BOOK', path: '', message: 'not an object' }] };
+  if (b.schema !== PRICE_BOOK_SCHEMA) bad('schema', `expected ${PRICE_BOOK_SCHEMA}`);
+  if (typeof b.version !== 'string' || !b.version) bad('version', 'a price book has a version');
+  if (typeof b.currency !== 'string' || !/^[A-Z]{3}$/.test(b.currency)) bad('currency', 'must be a three-letter code');
+  if (!BILLING_BASES.includes(b.billingBasis)) bad('billingBasis', `must be one of ${BILLING_BASES.join(', ')}`);
+  if (!b.entries || typeof b.entries !== 'object') bad('entries', 'missing');
+  else {
+    for (const [id, e] of Object.entries(b.entries)) {
+      for (const f of ['in', 'out', 'cached']) {
+        if (e[f] !== null && e[f] !== undefined && !(typeof e[f] === 'number' && Number.isFinite(e[f]) && e[f] >= 0)) bad(`entries.${id}.${f}`, 'a rate is a non-negative number, or null when unknown (never 0 for unknown)');
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+const pick = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const UNKNOWN = Object.freeze({ usd: null, lowerUsd: null, upperUsd: null, status: COST_STATUS.unknown });
+const unknown = (reason) => ({ ...UNKNOWN, reason });
+const exact = (usd) => ({ usd, lowerUsd: usd, upperUsd: usd, status: COST_STATUS.measured });
+const bounded = (lowerUsd, upperUsd, reason) => ({ usd: null, lowerUsd, upperUsd, status: COST_STATUS.bounded, reason });
+
+/**
+ * Can the prompt prefix be cached at all? `ineligible` is a fact (the provider's own minimum prefix is not met, or it has no cache);
+ * `unknown` is everything else, because eligible is not the same as hit.
+ */
+export function cacheEligibility(entry, inputTokens) {
+  if (!entry || entry.cacheKind === null || entry.cacheKind === undefined) return 'unknown';
+  if (Number.isInteger(inputTokens) && Number.isInteger(entry.cacheMinPrefixTokens) && inputTokens < entry.cacheMinPrefixTokens) return 'ineligible';
+  return 'unknown';
+}
+
+/** Cost of the token components of ONE attempt from MEASURED usage. */
+function attemptCost(usage, entry) {
+  const inTok = usage.inputTokens;
+  const outTok = usage.outputTokens;
+  const out = outTok === null || pick(entry?.out) === null ? unknown(outTok === null ? 'output tokens not reported' : 'no output price') : exact((outTok * entry.out) / PER);
+  let input; let cachedInput;
+  if (inTok === null || pick(entry?.in) === null) {
+    const why = inTok === null ? 'input tokens not reported' : 'no input price';
+    input = unknown(why); cachedInput = unknown(why);
+  } else if (usage.cachedInputTokens !== null && usage.cachedInputTokens !== undefined) {
+    const cached = usage.cachedInputTokens;
+    input = exact(((inTok - cached) * entry.in) / PER);
+    cachedInput = cached === 0 ? exact(0) : (pick(entry.cached) === null ? unknown('cached input tokens reported but no cached-input price') : exact((cached * entry.cached) / PER));
+  } else if (cacheEligibility(entry, inTok) === 'ineligible') {
+    // Below the provider's minimum cacheable prefix, so no token can have been served from cache: a fact, not a guess.
+    input = exact((inTok * entry.in) / PER); cachedInput = exact(0);
+  } else if (pick(entry.cached) === null) {
+    input = unknown('cache split not reported and no cached-input price to bound it'); cachedInput = unknown('cache split not reported');
+  } else {
+    // Cache split unknown: the cached share is somewhere in [0, inTok]. Bound the COMBINED prompt cost, and say so on both parts.
+    const lo = (inTok * Math.min(entry.in, entry.cached)) / PER;
+    const hi = (inTok * Math.max(entry.in, entry.cached)) / PER;
+    input = bounded(lo, hi, 'cache split not reported: the prompt cost lies between all-cached and all-uncached; the bound covers input and cached input together');
+    cachedInput = { ...input, combinedWithInput: true };
+  }
+  return { input, cachedInput, output: out };
+}
+
+const sumParts = (parts) => {
+  if (parts.some((p) => p.status === COST_STATUS.unknown)) return { ...UNKNOWN, reason: 'a component is unknown, so the total is unknown' };
+  const lowerUsd = parts.reduce((a, p) => a + p.lowerUsd, 0);
+  const upperUsd = parts.reduce((a, p) => a + p.upperUsd, 0);
+  if (parts.every((p) => p.status === COST_STATUS.measured)) return exact(lowerUsd);
+  return { usd: null, lowerUsd, upperUsd, status: COST_STATUS.bounded };
+};
+
+/**
+ * Price one task run.
+ *
+ * @param {object} o
+ * @param {{inputTokens:number|null, outputTokens:number|null, cachedInputTokens:number|null, source:string}} o.usage  the FINAL attempt's usage
+ * @param {string} o.model
+ * @param {object} o.priceBook
+ * @param {Array<{usage?:object, billable?:boolean}>} [o.retries]  earlier attempts. An attempt with no reported usage is bounded by
+ *        `estimatedRequestTokens` (a failed request may have been billed for its input), never priced at 0.
+ * @param {number|null} [o.estimatedRequestTokens]  request size estimate used ONLY to bound unreported retries
+ * @param {number|null} [o.toolExecutionUsd]  null/undefined means not measured (unknown), not free
+ * @param {number|null} [o.predictedTokens]   a prediction; reported under `predicted`, never under `measured`
+ * @returns the cost with `priceVersion`, `currency`, `billingBasis`, and separate `measured` / `predicted` sections
+ */
+export function costOf({ usage, model, priceBook, retries = [], estimatedRequestTokens = null, toolExecutionUsd = undefined, predictedTokens = null } = {}) {
+  const meta = {
+    priceVersion: priceBook?.version ?? null, currency: priceBook?.currency ?? null, billingBasis: priceBook?.billingBasis ?? 'unknown',
+    priceBookDigest: priceBook?.digest ?? null, model,
+  };
+  const entry = priceBook?.entries?.[model] ?? null;
+  const metered = priceBook && !UNMETERED_BASES.includes(priceBook.billingBasis);
+  const reason = !priceBook ? 'no price book' : !entry ? `no price for model '${model}'` : !metered ? `billing basis '${priceBook.billingBasis}' has no metered per-token cost` : null;
+  const usable = reason === null ? entry : null;
+
+  const u = usage || {};
+  const measuredUsage = u.source === 'measured';
+  const tokens = { inputTokens: pick(u.inputTokens) === null ? null : u.inputTokens, outputTokens: pick(u.outputTokens) === null ? null : u.outputTokens, cachedInputTokens: pick(u.cachedInputTokens) === null ? null : u.cachedInputTokens };
+  const unpriced = (why) => ({ input: unknown(why), cachedInput: unknown(why), output: unknown(why) });
+  let parts;
+  if (!usable) parts = unpriced(reason);
+  else if (!measuredUsage) parts = unpriced(`usage is '${u.source ?? 'unknown'}', not measured: a prediction is not substituted for a measurement`);
+  else parts = attemptCost(tokens, usable);
+
+  // retries: each earlier attempt, priced on its own reported usage, or bounded when it reported none
+  let retryParts;
+  if (!retries.length) retryParts = exact(0);
+  else {
+    const each = retries.map((r) => {
+      if (!usable) return unknown(reason);
+      if (r?.usage?.source === 'measured') { const c = attemptCost({ inputTokens: pick(r.usage.inputTokens) === null ? null : r.usage.inputTokens, outputTokens: pick(r.usage.outputTokens) === null ? null : r.usage.outputTokens, cachedInputTokens: pick(r.usage.cachedInputTokens) === null ? null : r.usage.cachedInputTokens }, usable); return sumParts([c.input, c.cachedInput.combinedWithInput ? exact(0) : c.cachedInput, c.output]); }
+      if (Number.isInteger(estimatedRequestTokens) && pick(usable.in) !== null) return bounded(0, (estimatedRequestTokens * usable.in) / PER, 'attempt reported no usage: bounded by its estimated input, never assumed free');
+      return unknown('attempt reported no usage and no request size estimate is available');
+    });
+    retryParts = sumParts(each);
+  }
+  const tool = toolExecutionUsd === undefined || toolExecutionUsd === null ? unknown('tool execution cost not measured') : (pick(toolExecutionUsd) !== null && toolExecutionUsd >= 0 ? exact(toolExecutionUsd) : unknown('invalid tool execution cost'));
+
+  const distinct = [parts.input, parts.cachedInput.combinedWithInput ? exact(0) : parts.cachedInput, parts.output, retryParts, tool];
+  const total = sumParts(distinct);
+  const measured = { ...parts, retries: retryParts, toolExecution: tool, total };
+  let predicted = null;
+  if (Number.isInteger(predictedTokens) && usable && pick(usable.in) !== null) {
+    predicted = { basis: 'prediction', upperUsd: (predictedTokens * usable.in) / PER, note: 'a prediction from a request-size estimate; it never replaces measured usage' };
+  }
+  // A cost on a metered basis from measured usage is "measured"; everything else is reported as it is.
+  return Object.freeze({ ...meta, measured, predicted, totalUsd: total.status === COST_STATUS.measured ? total.usd : null, totalStatus: total.status, totalLowerUsd: total.lowerUsd, totalUpperUsd: total.upperUsd });
+}
+
+/** Median of the known values; null (never 0) when there are none. */
+export function medianKnown(values) {
+  const v = values.filter((x) => typeof x === 'number' && Number.isFinite(x)).sort((a, b) => a - b);
+  if (!v.length) return null;
+  const m = v.length >> 1;
+  return v.length % 2 ? v[m] : (v[m - 1] + v[m]) / 2;
+}