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

package/src/posture/assurance/config.js

@@ -0,0 +1,299 @@
+// Unified configuration for the assurance features (CORE-004).
+//
+// Extends the configuration mechanism the scanner already has instead of adding
+// a second one:
+//   - environment variables, `AGENTIC_SECURITY_*` (docs/reference/configuration.md),
+//     including the existing `AGENTIC_SECURITY_NO_<NAME>=1` kill-switch shape;
+//   - a per-project YAML file under `.agentic-security/` read through
+//     posture/state-dir.js and util/yaml.js, exactly as egress-policy.yml is.
+//
+// Precedence, highest first. A higher level always wins over a lower one, and the
+// result says which level decided:
+//   1. kill switch   AGENTIC_SECURITY_NO_ASSURANCE=1 (all) or AGENTIC_SECURITY_NO_<FEATURE>=1
+//   2. overrides     explicit options from the caller (CLI flags)
+//   3. environment   AGENTIC_SECURITY_ASSURANCE_<FEATURE>=1|0
+//   4. project file  .agentic-security/assurance.yml
+//   5. default       every new feature defaults to OFF
+//
+// Two rules that follow from the trust model:
+//   - HIGH-RISK EXECUTION IS OPERATOR-ONLY. The project file lives inside the
+//     scanned repository, which is hostile input. A project file can never switch
+//     on a feature whose risk class is `high-risk-execution`; only the
+//     environment or an explicit override can. The refusal is disclosed, not silent.
+//   - INVALID CONFIGURATION FAILS CLOSED. An unknown feature, a non-boolean, or a
+//     limit that is not a finite number within its ceiling leaves that feature
+//     disabled and is reported in `errors`. It never falls through to a default
+//     that is more permissive than what the operator wrote.
+//
+// A disabled feature is inert: nothing in this module touches the scan or report
+// pipeline, so default behaviour is unchanged.
+
+import * as fs from 'node:fs';
+import { statePath } from '../state-dir.js';
+import { load as loadYaml } from '../../util/yaml.js';
+
+export const CONFIG_FILE = 'assurance.yml';
+export const CONFIG_VERSION = 1;
+
+export const RISK_CLASSES = Object.freeze(['passive', 'model-network', 'high-risk-execution']);
+
+// Every new feature. `platforms` is the set where the feature is supported at all;
+// off it the result is a typed `unsupported`, with the note disclosed.
+export const FEATURES = Object.freeze({
+  'verification-oracles': {
+    risk: 'high-risk-execution', platforms: ['linux', 'darwin'],
+    platformNote: 'runtime oracles run through the confinement sandbox; isolation-required checks are only advertised on Linux',
+  },
+  'patch-negative-verification': {
+    risk: 'high-risk-execution', platforms: ['linux', 'darwin'],
+    platformNote: 'replays the exploit against the original and the patched revision through the confinement sandbox, so it needs verification-oracles as well; an unproved isolation control blocks it',
+  },
+  'deployment-boundaries': { risk: 'passive', platforms: ['linux', 'darwin', 'win32'], platformNote: null },
+  'invariant-scenarios': {
+    risk: 'high-risk-execution', platforms: ['linux', 'darwin'],
+    platformNote: 'stateful scenarios execute target code and need the confinement sandbox',
+  },
+  'capability-enforcement': {
+    risk: 'high-risk-execution', platforms: ['linux'],
+    platformNote: 'runner-level filesystem, network and process enforcement is only advertised on Linux; macOS can supervise but not enforce',
+  },
+  'model-routing': { risk: 'model-network', platforms: ['linux', 'darwin', 'win32'], platformNote: null },
+  'portfolio-assurance': { risk: 'passive', platforms: ['linux', 'darwin', 'win32'], platformNote: null },
+});
+
+// Finite limits with hard ceilings. `enforcedBy` names the helper in THIS module
+// that actually enforces it; `null` means this layer only carries the number for
+// a runner to enforce, and the disclosure says so rather than claiming otherwise.
+export const LIMITS = Object.freeze({
+  timeoutMs: { default: 15_000, min: 1, max: 120_000, enforcedBy: 'withDeadline' },
+  retries: { default: 2, min: 0, max: 5, enforcedBy: 'retryBounded' },
+  maxOutputBytes: { default: 262_144, min: 1, max: 16 * 1024 * 1024, enforcedBy: 'capOutput' },
+  maxRequestBytes: { default: 262_144, min: 1, max: 16 * 1024 * 1024, enforcedBy: 'guardedModelCall' },
+  maxFileBytes: { default: 5 * 1024 * 1024, min: 1, max: 64 * 1024 * 1024, enforcedBy: 'readFileBounded' },
+  maxMemoryMiB: { default: 6144, min: 64, max: 65_536, enforcedBy: null },
+});
+
+const FEATURE_IDS = Object.keys(FEATURES);
+const envName = (id) => id.toUpperCase().replace(/-/g, '_');
+
+function parseBool(raw) {
+  if (raw === true || raw === '1' || raw === 'true') return true;
+  if (raw === false || raw === '0' || raw === 'false') return false;
+  return undefined;
+}
+
+function checkLimits(limits, where, errors) {
+  const out = {};
+  if (limits === undefined || limits === null) return out;
+  if (typeof limits !== 'object' || Array.isArray(limits)) { errors.push({ code: 'invalid-config', path: where, message: 'limits must be a mapping' }); return null; }
+  let bad = false;
+  for (const [k, v] of Object.entries(limits)) {
+    const spec = LIMITS[k];
+    if (!spec) { errors.push({ code: 'invalid-config', path: `${where}.${k}`, message: `unknown limit '${k}'` }); bad = true; continue; }
+    if (typeof v !== 'number' || !Number.isFinite(v) || !Number.isInteger(v)) { errors.push({ code: 'invalid-config', path: `${where}.${k}`, message: 'must be a finite integer' }); bad = true; continue; }
+    if (v < spec.min || v > spec.max) { errors.push({ code: 'invalid-config', path: `${where}.${k}`, message: `must be between ${spec.min} and ${spec.max}` }); bad = true; continue; }
+    out[k] = v;
+  }
+  return bad ? null : out;
+}
+
+function readProjectFile(scanRoot, readFile, errors) {
+  let fp;
+  try { fp = statePath(scanRoot, CONFIG_FILE); } catch { return null; }
+  let raw;
+  try { raw = readFile(fp); } catch { return null; } // absent file is the normal case
+  let doc;
+  try { doc = loadYaml(raw); } catch (e) {
+    errors.push({ code: 'invalid-config', path: CONFIG_FILE, message: `not valid YAML: ${String(e.message).split('\n')[0]}` });
+    return { broken: true };
+  }
+  if (doc === undefined) return { features: {}, limits: {} };
+  if (typeof doc !== 'object' || Array.isArray(doc)) { errors.push({ code: 'invalid-config', path: CONFIG_FILE, message: 'must be a mapping' }); return { broken: true }; }
+  for (const k of Object.keys(doc)) {
+    if (!['version', 'features', 'limits'].includes(k)) errors.push({ code: 'invalid-config', path: `${CONFIG_FILE}.${k}`, message: `unknown key '${k}'` });
+  }
+  if (doc.version !== undefined && doc.version !== CONFIG_VERSION) {
+    errors.push({ code: 'invalid-config', path: `${CONFIG_FILE}.version`, message: `unsupported version ${JSON.stringify(doc.version)} (supported: ${CONFIG_VERSION})` });
+    return { broken: true };
+  }
+  return doc;
+}
+
+/**
+ * Resolve the effective configuration.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.scanRoot]
+ * @param {object} [opts.env]       defaults to process.env
+ * @param {object} [opts.overrides] `{ features: {id: bool}, limits: {...} }` from explicit flags
+ * @param {string} [opts.platform]  defaults to process.platform
+ * @param {(p:string)=>string} [opts.readFile]
+ */
+export function resolveAssuranceConfig({ scanRoot, env = process.env, overrides = {}, platform = process.platform, readFile = (p) => fs.readFileSync(p, 'utf8') } = {}) {
+  const errors = [];
+  const file = readProjectFile(scanRoot, readFile, errors);
+  const fileOk = file && !file.broken ? file : null;
+  const globalKill = env.AGENTIC_SECURITY_NO_ASSURANCE === '1';
+
+  const fileFeatures = (fileOk && fileOk.features && typeof fileOk.features === 'object' && !Array.isArray(fileOk.features)) ? fileOk.features : {};
+  if (fileOk && fileOk.features !== undefined && fileFeatures !== fileOk.features) errors.push({ code: 'invalid-config', path: `${CONFIG_FILE}.features`, message: 'must be a mapping' });
+  for (const id of Object.keys(fileFeatures)) {
+    if (!FEATURES[id]) errors.push({ code: 'invalid-config', path: `${CONFIG_FILE}.features.${id}`, message: `unknown feature '${id}'` });
+  }
+
+  const features = {};
+  for (const id of FEATURE_IDS) {
+    const spec = FEATURES[id];
+    const entry = { id, risk: spec.risk, enabled: false, source: 'default', reason: 'default: off', killed: false, notes: [] };
+    let invalid = false;
+
+    // 5/4: project file
+    const fe = fileFeatures[id];
+    if (fe !== undefined) {
+      if (typeof fe !== 'object' || fe === null || Array.isArray(fe)) { errors.push({ code: 'invalid-config', path: `${CONFIG_FILE}.features.${id}`, message: 'must be a mapping' }); invalid = true; }
+      else {
+        for (const k of Object.keys(fe)) if (!['enabled', 'limits'].includes(k)) { errors.push({ code: 'invalid-config', path: `${CONFIG_FILE}.features.${id}.${k}`, message: `unknown key '${k}'` }); invalid = true; }
+        if (fe.enabled !== undefined) {
+          const b = parseBool(fe.enabled);
+          if (typeof fe.enabled !== 'boolean') { errors.push({ code: 'invalid-config', path: `${CONFIG_FILE}.features.${id}.enabled`, message: 'must be true or false' }); invalid = true; }
+          else if (b && spec.risk === 'high-risk-execution') {
+            entry.notes.push('project file requested enablement; refused: high-risk execution can only be enabled by the operator through the environment or an explicit option');
+            entry.source = 'project-file-refused'; entry.reason = 'high-risk execution cannot be enabled by a project file';
+          } else { entry.enabled = b; entry.source = 'project-file'; entry.reason = `project file sets enabled=${b}`; }
+        }
+      }
+    }
+    // 3: environment
+    const rawEnv = env[`AGENTIC_SECURITY_ASSURANCE_${envName(id)}`];
+    if (rawEnv !== undefined && rawEnv !== '') {
+      const b = parseBool(rawEnv);
+      if (b === undefined) { errors.push({ code: 'invalid-config', path: `AGENTIC_SECURITY_ASSURANCE_${envName(id)}`, message: `must be 1/true or 0/false, got ${JSON.stringify(rawEnv)}` }); invalid = true; }
+      else { entry.enabled = b; entry.source = 'env'; entry.reason = `environment sets enabled=${b}`; }
+    }
+    // 2: explicit overrides
+    const ov = overrides.features?.[id];
+    if (ov !== undefined) {
+      if (typeof ov !== 'boolean') { errors.push({ code: 'invalid-config', path: `overrides.features.${id}`, message: 'must be a boolean' }); invalid = true; }
+      else { entry.enabled = ov; entry.source = 'override'; entry.reason = `explicit option sets enabled=${ov}`; }
+    }
+    // invalid configuration fails closed
+    if (invalid) { entry.enabled = false; entry.source = 'invalid-config'; entry.reason = 'configuration for this feature is invalid; disabled'; }
+    // 1: kill switch
+    if (globalKill || env[`AGENTIC_SECURITY_NO_${envName(id)}`] === '1') {
+      entry.enabled = false; entry.killed = true; entry.source = 'kill-switch';
+      entry.reason = globalKill ? 'AGENTIC_SECURITY_NO_ASSURANCE=1' : `AGENTIC_SECURITY_NO_${envName(id)}=1`;
+    }
+    // platform disclosure
+    const supported = spec.platforms.includes(platform);
+    entry.platform = { supported, platform, note: spec.platformNote, supportedPlatforms: [...spec.platforms] };
+    features[id] = entry;
+  }
+
+  // limits: file -> overrides, each validated; a bad level is dropped whole
+  const limits = {};
+  for (const [k, spec] of Object.entries(LIMITS)) limits[k] = { value: spec.default, source: 'default', enforcedBy: spec.enforcedBy };
+  const apply = (obj, source, where) => {
+    const ok = checkLimits(obj, where, errors);
+    if (!ok) return;
+    for (const [k, v] of Object.entries(ok)) limits[k] = { value: v, source, enforcedBy: LIMITS[k].enforcedBy };
+  };
+  if (fileOk) apply(fileOk.limits, 'project-file', `${CONFIG_FILE}.limits`);
+  apply(overrides.limits, 'override', 'overrides.limits');
+
+  return { version: CONFIG_VERSION, features, limits, errors, killSwitch: globalKill };
+}
+
+/** Plain numeric limits for a caller that only wants the numbers. */
+export function limitValues(config) {
+  return Object.fromEntries(Object.entries(config.limits).map(([k, v]) => [k, v.value]));
+}
+
+// ---------------------------------------------------------------- typed results
+
+export const RESULT_STATUSES = Object.freeze(['ok', 'disabled', 'blocked', 'unsupported', 'degraded']);
+export const RESULT_CODES = Object.freeze([
+  'disabled', 'kill-switch', 'platform-unsupported', 'invalid-config', 'egress-denied', 'limit-exceeded', 'timeout',
+  'missing-provider', 'missing-credential', 'missing-collector', 'missing-execution-backend', 'missing-dependency',
+]);
+
+export function typed(status, code, reason, extra = {}) {
+  return { status, code, reason, ...extra };
+}
+
+/** The gate every new feature passes through. Never throws, never prompts, never reaches the network. */
+export function featureStatus(config, id) {
+  const f = config?.features?.[id];
+  if (!f) return typed('blocked', 'invalid-config', `unknown feature '${id}'`);
+  if (f.killed) return typed('blocked', 'kill-switch', f.reason, { feature: id });
+  if (f.source === 'invalid-config') return typed('blocked', 'invalid-config', f.reason, { feature: id });
+  if (!f.enabled) return typed('disabled', 'disabled', f.reason, { feature: id });
+  if (!f.platform.supported) {
+    return typed('unsupported', 'platform-unsupported', `${id} is not supported on ${f.platform.platform}${f.platform.note ? `: ${f.platform.note}` : ''}`, { feature: id, supportedPlatforms: f.platform.supportedPlatforms });
+  }
+  return typed('ok', null, f.reason, { feature: id });
+}
+
+const REQUIREMENT_KINDS = Object.freeze({
+  provider: 'missing-provider',
+  credential: 'missing-credential',
+  collector: 'missing-collector',
+  'execution-backend': 'missing-execution-backend',
+  dependency: 'missing-dependency',
+});
+
+/** A credential requirement that only checks that an environment variable is set. Never prompts, never reads its value into a result. */
+export function envPresent(name, env = process.env) {
+  return () => typeof env[name] === 'string' && env[name].length > 0;
+}
+
+/**
+ * Evaluate declared requirements. A missing REQUIRED one blocks; a missing
+ * OPTIONAL one degrades. A probe that throws counts as missing. No requirement is
+ * ever satisfied by a fallback, a prompt or a cloud default.
+ *
+ * requirements: [{ kind, name, optional?, present: () => boolean }]
+ */
+export function evaluateRequirements(requirements = []) {
+  const missingRequired = [];
+  const missingOptional = [];
+  for (const r of requirements) {
+    let present = false;
+    try { present = !!r.present(); } catch { present = false; }
+    if (present) continue;
+    const item = { kind: r.kind, name: r.name, code: REQUIREMENT_KINDS[r.kind] || 'missing-dependency' };
+    (r.optional ? missingOptional : missingRequired).push(item);
+  }
+  return { missingRequired, missingOptional };
+}
+
+/**
+ * Run `fn` only when the feature is enabled, supported here and its required
+ * dependencies are present. Returns a typed result either way; `fn` is never
+ * called otherwise. Optional gaps yield `degraded` and `fn` receives them so it
+ * can skip that part of its work.
+ */
+export async function runFeature(config, id, { requirements = [] } = {}, fn) {
+  const gate = featureStatus(config, id);
+  if (gate.status !== 'ok') return gate;
+  const { missingRequired, missingOptional } = evaluateRequirements(requirements);
+  if (missingRequired.length) {
+    const first = missingRequired[0];
+    return typed('blocked', first.code, `${id} needs ${first.kind} '${first.name}', which is not available`, { feature: id, missing: missingRequired });
+  }
+  const value = await fn({ limits: limitValues(config), missingOptional });
+  if (missingOptional.length) return typed('degraded', missingOptional[0].code, `${id} ran without optional ${missingOptional.map(m => `${m.kind} '${m.name}'`).join(', ')}`, { feature: id, missing: missingOptional, value });
+  return typed('ok', null, gate.reason, { feature: id, value });
+}
+
+/** Operator-readable disclosure of every feature, its state and its platform support. */
+export function describeAssuranceConfig(config) {
+  return {
+    killSwitch: config.killSwitch,
+    features: Object.values(config.features).map(f => ({
+      id: f.id, risk: f.risk, enabled: f.enabled, source: f.source, reason: f.reason,
+      platformSupported: f.platform.supported, platformNote: f.platform.supported ? null : f.platform.note, notes: f.notes,
+    })),
+    limits: Object.fromEntries(Object.entries(config.limits).map(([k, v]) => [k, { value: v.value, source: v.source, enforced: v.enforcedBy ? `by ${v.enforcedBy}` : 'not enforced by this layer (carried for the runner)' }])),
+    errors: config.errors,
+  };
+}

package/src/posture/assurance/contracts.js

@@ -0,0 +1,315 @@
+// Observation bindings, capability decisions, routing labels and release
+// evidence (CORE-002), plus cross-record validation (duplicate ids, dangling
+// references). Verification records live in verification-record.js.
+//
+// Lineage separation: an observation binding refers to a lineage runtime
+// observation BY ID ONLY. It never embeds, imports or mutates lineage state;
+// lineage owns the graph and this package owns the vulnerability-evidence claim
+// that a given observation bears on a given hypothesis.
+
+import {
+  SCHEMA_VERSION, makeCtx, result, guardObject, checkHeader, checkFields, checkEnum, checkDigest, checkCommit,
+  checkString, checkId, isPlainObject, isDigest,
+} from './schema-kit.js';
+import { semanticId, ID_PREFIXES } from './identity.js';
+import { validateVerificationRecord, verificationClaimKey } from './verification-record.js';
+
+// ---------------------------------------------------------------- observation binding
+
+export const OBSERVATION_BINDING_SCHEMA = 'agentic-security/observation-binding';
+export const BINDING_PROVENANCE = Object.freeze(['static-config', 'runtime-observation', 'inferred']);
+export const PATH_STATES = Object.freeze(['possible', 'blocked', 'unresolved', 'runtime-supported']);
+export const OBSERVATION_COMPLETENESS = Object.freeze(['complete', 'sampled', 'unknown']);
+
+const OB_ALLOWED = [
+  'schema', 'schemaVersion', 'id', 'hypothesisId', 'observationRef', 'boundaryRef', 'provenance', 'pathState',
+  'completeness', 'window', 'eventDiscriminator', 'migration', 'createdAt',
+];
+const OB_REQUIRED = ['schema', 'schemaVersion', 'id', 'hypothesisId', 'observationRef', 'provenance', 'pathState', 'completeness'];
+
+// The semantic identity of a binding excludes the event discriminator.
+export const OBSERVATION_BINDING_KEY_FIELDS = Object.freeze([
+  'hypothesisId', 'observationRef', 'boundaryRef', 'provenance', 'pathState', 'completeness', 'window',
+]);
+
+/** Identity of WHAT the binding says, independent of which event delivered it. */
+export function observationBindingKey(b) {
+  return semanticId('obkey', b, OBSERVATION_BINDING_KEY_FIELDS);
+}
+
+/** Id of this binding instance: the key plus the optional explicit event discriminator. */
+export function observationBindingId(b) {
+  return semanticId(ID_PREFIXES.observationBinding, b, [...OBSERVATION_BINDING_KEY_FIELDS, 'eventDiscriminator']);
+}
+
+export function validateObservationBinding(b) {
+  const g = guardObject(b);
+  const ctx = g.ctx;
+  if (!g.ok) return result(ctx);
+  if (!checkHeader(ctx, b, OBSERVATION_BINDING_SCHEMA)) return result(ctx);
+  checkFields(ctx, b, OB_ALLOWED, OB_REQUIRED);
+  checkString(ctx, 'hypothesisId', b.hypothesisId);
+  if (!isPlainObject(b.observationRef)) ctx.err('BAD_TYPE', 'observationRef', 'must be an object');
+  else {
+    for (const k of Object.keys(b.observationRef)) if (!['observationId', 'adapter'].includes(k)) ctx.err('UNKNOWN_FIELD', `observationRef.${k}`, 'not part of observationRef');
+    checkString(ctx, 'observationRef.observationId', b.observationRef.observationId);
+  }
+  if (b.boundaryRef !== undefined && b.boundaryRef !== null) checkString(ctx, 'boundaryRef', b.boundaryRef);
+  const provOk = checkEnum(ctx, 'provenance', b.provenance, BINDING_PROVENANCE);
+  const stateOk = checkEnum(ctx, 'pathState', b.pathState, PATH_STATES);
+  const compOk = checkEnum(ctx, 'completeness', b.completeness, OBSERVATION_COMPLETENESS);
+  if (b.window !== undefined && b.window !== null) {
+    if (!isPlainObject(b.window) || !Object.keys(b.window).every(k => ['start', 'end'].includes(k))) ctx.err('BAD_TYPE', 'window', 'must be {start, end}');
+    else { checkString(ctx, 'window.start', b.window.start); checkString(ctx, 'window.end', b.window.end); }
+  }
+  if (b.eventDiscriminator !== undefined && b.eventDiscriminator !== null) checkString(ctx, 'eventDiscriminator', b.eventDiscriminator);
+  if (provOk && stateOk && compOk) {
+    if (b.pathState === 'runtime-supported' && b.provenance !== 'runtime-observation') {
+      ctx.err('RULE_VIOLATION', 'pathState', `'runtime-supported' requires provenance 'runtime-observation'`);
+    }
+    if (b.pathState === 'blocked' && b.provenance === 'runtime-observation' && b.completeness !== 'complete') {
+      ctx.err('RULE_VIOLATION', 'pathState', `absence in a ${b.completeness} observation cannot establish 'blocked'`);
+    }
+    if (b.provenance === 'runtime-observation' && !(isPlainObject(b.window) && b.window.start && b.window.end)) {
+      ctx.err('RULE_VIOLATION', 'window', `a runtime observation binding must state its observation window`);
+    }
+  }
+  checkId(ctx, b, observationBindingId(b));
+  return result(ctx);
+}
+
+// ---------------------------------------------------------------- capability decision
+
+export const CAPABILITY_DECISION_SCHEMA = 'agentic-security/capability-decision';
+export const CAPABILITY_KINDS = Object.freeze(['filesystem-read', 'filesystem-write', 'command', 'network', 'tool', 'delegation']);
+export const CAPABILITY_DECISIONS = Object.freeze(['allow', 'deny', 'blocked', 'unsupported']);
+export const CAPABILITY_MEDIATIONS = Object.freeze(['runner', 'proxy', 'in-process-policy', 'hook-advisory', 'none']);
+
+const CD_ALLOWED = [
+  'schema', 'schemaVersion', 'id', 'taskId', 'capability', 'subject', 'decision', 'mediation', 'enforced', 'backend',
+  'probeDigest', 'reason', 'migration', 'createdAt',
+];
+const CD_REQUIRED = ['schema', 'schemaVersion', 'id', 'taskId', 'capability', 'subject', 'decision', 'mediation', 'enforced', 'backend', 'reason'];
+
+export const CAPABILITY_DECISION_ID_FIELDS = Object.freeze([
+  'taskId', 'capability', 'subject', 'decision', 'mediation', 'enforced', 'backend', 'probeDigest', 'reason',
+]);
+
+export function capabilityDecisionId(d) {
+  return semanticId(ID_PREFIXES.capabilityDecision, d, CAPABILITY_DECISION_ID_FIELDS);
+}
+
+export function validateCapabilityDecision(d) {
+  const g = guardObject(d);
+  const ctx = g.ctx;
+  if (!g.ok) return result(ctx);
+  if (!checkHeader(ctx, d, CAPABILITY_DECISION_SCHEMA)) return result(ctx);
+  checkFields(ctx, d, CD_ALLOWED, CD_REQUIRED);
+  checkString(ctx, 'taskId', d.taskId);
+  checkEnum(ctx, 'capability', d.capability, CAPABILITY_KINDS);
+  checkString(ctx, 'subject', d.subject);
+  const decOk = checkEnum(ctx, 'decision', d.decision, CAPABILITY_DECISIONS);
+  const medOk = checkEnum(ctx, 'mediation', d.mediation, CAPABILITY_MEDIATIONS);
+  if (typeof d.enforced !== 'boolean') ctx.err('BAD_TYPE', 'enforced', 'must be a boolean');
+  if (d.backend !== null && d.backend !== undefined) checkString(ctx, 'backend', d.backend);
+  if (d.probeDigest !== undefined && d.probeDigest !== null) checkDigest(ctx, 'probeDigest', d.probeDigest);
+  checkString(ctx, 'reason', d.reason);
+  if (decOk && medOk && d.enforced === true) {
+    // A hook response or an in-process check explains a decision; it does not
+    // prove isolation. Only the runner or a proxy, with a named backend and an
+    // active probe, may claim enforcement.
+    if (!['runner', 'proxy'].includes(d.mediation)) ctx.err('RULE_VIOLATION', 'enforced', `mediation '${d.mediation}' cannot claim enforcement`);
+    if (!(typeof d.backend === 'string' && d.backend)) ctx.err('RULE_VIOLATION', 'backend', 'an enforced decision must name its backend');
+    if (!isDigest(d.probeDigest)) ctx.err('RULE_VIOLATION', 'probeDigest', 'an enforced decision must carry the digest of its active probe evidence');
+    if (!['allow', 'deny'].includes(d.decision)) ctx.err('RULE_VIOLATION', 'enforced', `decision '${d.decision}' cannot be enforced`);
+  }
+  checkId(ctx, d, capabilityDecisionId(d));
+  return result(ctx);
+}
+
+// ---------------------------------------------------------------- routing label
+
+export const ROUTING_LABEL_SCHEMA = 'agentic-security/routing-label';
+export const ROUTING_TASK_KINDS = Object.freeze(['discovery', 'triage', 'verification-planning', 'repair']);
+export const ROUTING_OUTCOMES = Object.freeze(['correct', 'incorrect', 'unknown', 'delayed']);
+export const ROUTING_LABEL_SOURCES = Object.freeze(['adjudication', 'trusted-execution', 'none']);
+
+const RL_ALLOWED = [
+  'schema', 'schemaVersion', 'id', 'taskId', 'taskKind', 'stratum', 'model', 'outcome', 'labelSource', 'verificationRecordId', 'migration', 'createdAt',
+];
+const RL_REQUIRED = ['schema', 'schemaVersion', 'id', 'taskId', 'taskKind', 'stratum', 'model', 'outcome', 'labelSource'];
+export const ROUTING_LABEL_ID_FIELDS = Object.freeze(['taskId', 'taskKind', 'stratum', 'model', 'outcome', 'labelSource', 'verificationRecordId']);
+
+export function routingLabelId(l) {
+  return semanticId(ID_PREFIXES.routingLabel, l, ROUTING_LABEL_ID_FIELDS);
+}
+
+export function validateRoutingLabel(l) {
+  const g = guardObject(l);
+  const ctx = g.ctx;
+  if (!g.ok) return result(ctx);
+  if (!checkHeader(ctx, l, ROUTING_LABEL_SCHEMA)) return result(ctx);
+  checkFields(ctx, l, RL_ALLOWED, RL_REQUIRED);
+  checkString(ctx, 'taskId', l.taskId);
+  checkEnum(ctx, 'taskKind', l.taskKind, ROUTING_TASK_KINDS);
+  checkString(ctx, 'stratum', l.stratum);
+  checkString(ctx, 'model', l.model);
+  const outOk = checkEnum(ctx, 'outcome', l.outcome, ROUTING_OUTCOMES);
+  const srcOk = checkEnum(ctx, 'labelSource', l.labelSource, ROUTING_LABEL_SOURCES);
+  if (l.verificationRecordId !== undefined && l.verificationRecordId !== null) {
+    if (typeof l.verificationRecordId !== 'string' || !l.verificationRecordId.startsWith('vrec:')) ctx.err('BAD_ID', 'verificationRecordId', `must be a verification record id ('vrec:...')`);
+  }
+  if (outOk && srcOk) {
+    // Delayed and unknown outcomes are retained, but they cannot carry a source
+    // that implies they were adjudicated; a decided label must name its source.
+    if (['correct', 'incorrect'].includes(l.outcome) && l.labelSource === 'none') {
+      ctx.err('RULE_VIOLATION', 'labelSource', `a '${l.outcome}' label needs an adjudication or trusted-execution source`);
+    }
+    if (['unknown', 'delayed'].includes(l.outcome) && l.labelSource !== 'none') {
+      ctx.err('RULE_VIOLATION', 'labelSource', `an '${l.outcome}' label has no decided source`);
+    }
+  }
+  checkId(ctx, l, routingLabelId(l));
+  return result(ctx);
+}
+
+// ---------------------------------------------------------------- release evidence
+
+export const RELEASE_EVIDENCE_SCHEMA = 'agentic-security/release-evidence';
+export const CLAIM_STATUSES = Object.freeze(['verified', 'failed', 'skipped', 'incomplete', 'unverified']);
+
+const RE_ALLOWED = ['schema', 'schemaVersion', 'id', 'subject', 'claims', 'complete', 'migration', 'createdAt'];
+const RE_REQUIRED = ['schema', 'schemaVersion', 'id', 'subject', 'claims', 'complete'];
+export const RELEASE_EVIDENCE_ID_FIELDS = Object.freeze(['subject', 'claims', 'complete']);
+
+export function releaseEvidenceId(r) {
+  return semanticId(ID_PREFIXES.releaseEvidence, r, RELEASE_EVIDENCE_ID_FIELDS);
+}
+
+/** `complete` as the claims support it: every claim verified, no gaps, exact commit and bundle bound. */
+export function deriveReleaseComplete(r) {
+  if (!isPlainObject(r?.subject) || !r.subject.commit || !r.subject.bundleDigest) return false;
+  if (!Array.isArray(r.claims) || r.claims.length === 0) return false;
+  return r.claims.every(c => isPlainObject(c) && c.status === 'verified' && (!Array.isArray(c.gaps) || c.gaps.length === 0));
+}
+
+export function validateReleaseEvidence(r) {
+  const g = guardObject(r);
+  const ctx = g.ctx;
+  if (!g.ok) return result(ctx);
+  if (!checkHeader(ctx, r, RELEASE_EVIDENCE_SCHEMA)) return result(ctx);
+  checkFields(ctx, r, RE_ALLOWED, RE_REQUIRED);
+  if (!isPlainObject(r.subject)) ctx.err('BAD_TYPE', 'subject', 'must be an object');
+  else {
+    for (const k of Object.keys(r.subject)) if (!['commit', 'bundleDigest', 'policyDigest'].includes(k)) ctx.err('UNKNOWN_FIELD', `subject.${k}`, 'not part of subject');
+    checkCommit(ctx, 'subject.commit', r.subject.commit ?? null);
+    checkDigest(ctx, 'subject.bundleDigest', r.subject.bundleDigest ?? null, { nullable: true });
+    if (r.subject.policyDigest !== undefined && r.subject.policyDigest !== null) checkDigest(ctx, 'subject.policyDigest', r.subject.policyDigest);
+  }
+  if (typeof r.complete !== 'boolean') ctx.err('BAD_TYPE', 'complete', 'must be a boolean');
+  if (!Array.isArray(r.claims)) ctx.err('BAD_TYPE', 'claims', 'must be an array');
+  else {
+    const seen = new Set();
+    r.claims.forEach((c, i) => {
+      const p = `claims[${i}]`;
+      if (!isPlainObject(c)) { ctx.err('BAD_TYPE', p, 'claim must be an object'); return; }
+      for (const k of Object.keys(c)) if (!['id', 'statement', 'status', 'evidenceRefs', 'gaps'].includes(k)) ctx.err('UNKNOWN_FIELD', `${p}.${k}`, 'not part of a claim');
+      if (checkString(ctx, `${p}.id`, c.id)) {
+        if (seen.has(c.id)) ctx.err('DUPLICATE_ID', `${p}.id`, `duplicate claim id '${c.id}'`);
+        seen.add(c.id);
+      }
+      checkString(ctx, `${p}.statement`, c.statement);
+      const stOk = checkEnum(ctx, `${p}.status`, c.status, CLAIM_STATUSES);
+      if (!Array.isArray(c.evidenceRefs)) ctx.err('BAD_TYPE', `${p}.evidenceRefs`, 'must be an array');
+      else c.evidenceRefs.forEach((ref, j) => {
+        if (typeof ref !== 'string' || !(ref.startsWith('vrec:') || isDigest(ref))) ctx.err('BAD_ID', `${p}.evidenceRefs[${j}]`, `must be a verification record id or a sha256 digest`);
+      });
+      if (!Array.isArray(c.gaps) || !c.gaps.every(x => typeof x === 'string' && x.trim())) ctx.err('BAD_TYPE', `${p}.gaps`, 'must be an array of non-empty strings');
+      if (stOk && Array.isArray(c.evidenceRefs) && Array.isArray(c.gaps)) {
+        if (c.status === 'verified' && c.evidenceRefs.length === 0) ctx.err('RULE_VIOLATION', `${p}.evidenceRefs`, `a 'verified' claim must cite evidence`);
+        if (c.status === 'verified' && c.gaps.length > 0) ctx.err('RULE_VIOLATION', `${p}.gaps`, `a 'verified' claim cannot list gaps`);
+        if (c.status !== 'verified' && c.gaps.length === 0) ctx.err('RULE_VIOLATION', `${p}.gaps`, `a '${c.status}' claim must say what is missing`);
+      }
+    });
+    if (typeof r.complete === 'boolean' && r.complete !== deriveReleaseComplete(r)) {
+      ctx.err('RULE_VIOLATION', 'complete', `claimed complete=${r.complete} but the claims and subject support complete=${deriveReleaseComplete(r)}`);
+    }
+  }
+  checkId(ctx, r, releaseEvidenceId(r));
+  return result(ctx);
+}
+
+// ---------------------------------------------------------------- record set
+
+const VALIDATORS = Object.freeze({
+  verificationRecords: validateVerificationRecord,
+  observationBindings: validateObservationBinding,
+  capabilityDecisions: validateCapabilityDecision,
+  routingLabels: validateRoutingLabel,
+  releaseEvidence: validateReleaseEvidence,
+});
+
+/**
+ * Validate a whole set: every record individually, then duplicate ids within and
+ * across types, dangling references, and the cross-record honesty rules.
+ * Input is `{ verificationRecords, observationBindings, capabilityDecisions, routingLabels, releaseEvidence }`,
+ * each an optional array.
+ */
+export function validateRecordSet(set) {
+  const ctx = makeCtx();
+  if (!isPlainObject(set)) { ctx.err('NOT_AN_OBJECT', '', 'record set must be an object'); return result(ctx); }
+  for (const k of Object.keys(set)) if (!VALIDATORS[k]) ctx.err('UNKNOWN_FIELD', k, `'${k}' is not a record collection`);
+  const allIds = new Map();
+  for (const [name, validate] of Object.entries(VALIDATORS)) {
+    const list = set[name];
+    if (list === undefined) continue;
+    if (!Array.isArray(list)) { ctx.err('BAD_TYPE', name, 'must be an array'); continue; }
+    list.forEach((rec, i) => {
+      const r = validate(rec);
+      for (const e of r.errors) ctx.err(e.code, `${name}[${i}]${e.path ? '.' + e.path : ''}`, e.message);
+      if (isPlainObject(rec) && typeof rec.id === 'string') {
+        if (allIds.has(rec.id)) ctx.err('DUPLICATE_ID', `${name}[${i}].id`, `id '${rec.id}' is already used by ${allIds.get(rec.id)}`);
+        else allIds.set(rec.id, `${name}[${i}]`);
+      }
+    });
+  }
+
+  const vrecs = new Map((Array.isArray(set.verificationRecords) ? set.verificationRecords : []).filter(isPlainObject).map(r => [r.id, r]));
+
+  // two records with the same claim key but different outcomes are a conflict, not two facts
+  const byClaim = new Map();
+  for (const [id, r] of vrecs) {
+    const key = verificationClaimKey(r);
+    const prior = byClaim.get(key);
+    if (prior && prior.outcome !== r.outcome) ctx.err('RULE_VIOLATION', `verificationRecords`, `records '${prior.id}' and '${id}' make the same claim with different outcomes ('${prior.outcome}' vs '${r.outcome}')`);
+    byClaim.set(key, r);
+  }
+
+  for (const [id, r] of vrecs) {
+    const rid = r.repair?.replayRecordId;
+    if (rid && !vrecs.has(rid)) ctx.err('DANGLING_REF', `verificationRecords.${id}.repair.replayRecordId`, `replay record '${rid}' is not in the set`);
+  }
+  (Array.isArray(set.observationBindings) ? set.observationBindings : []).filter(isPlainObject).forEach((b, i) => {
+    // hypothesis ids are findings' stable ids, not record ids; a binding is dangling only against explicit vrec refs
+    if (typeof b.hypothesisId === 'string' && b.hypothesisId.startsWith('vrec:') && !vrecs.has(b.hypothesisId)) {
+      ctx.err('DANGLING_REF', `observationBindings[${i}].hypothesisId`, `'${b.hypothesisId}' is not in the set`);
+    }
+  });
+  (Array.isArray(set.routingLabels) ? set.routingLabels : []).filter(isPlainObject).forEach((l, i) => {
+    if (l.verificationRecordId && !vrecs.has(l.verificationRecordId)) ctx.err('DANGLING_REF', `routingLabels[${i}].verificationRecordId`, `'${l.verificationRecordId}' is not in the set`);
+  });
+  (Array.isArray(set.releaseEvidence) ? set.releaseEvidence : []).filter(isPlainObject).forEach((rev, ri) => {
+    (Array.isArray(rev.claims) ? rev.claims : []).filter(isPlainObject).forEach((c, ci) => {
+      for (const ref of Array.isArray(c.evidenceRefs) ? c.evidenceRefs : []) {
+        if (typeof ref === 'string' && ref.startsWith('vrec:')) {
+          const v = vrecs.get(ref);
+          if (!v) ctx.err('DANGLING_REF', `releaseEvidence[${ri}].claims[${ci}].evidenceRefs`, `'${ref}' is not in the set`);
+          else if (c.status === 'verified' && !['confirmed', 'refuted'].includes(v.outcome)) {
+            ctx.err('RULE_VIOLATION', `releaseEvidence[${ri}].claims[${ci}]`, `claim is 'verified' but cites '${ref}' whose outcome is '${v.outcome}'`);
+          }
+        }
+      }
+    });
+  });
+  return result(ctx);
+}