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

package/src/posture/model-routing.js

@@ -1,4 +1,8 @@
 import { applyMeasuredTrust } from './model-trust.js';
+import { featureStatus } from './assurance/config.js';
+import { buildRoutingTask } from './routing/outcomes.js';
+import { routeConstrained } from './routing/decide.js';
+import { resolveRoutingControl } from './routing/control.js';
 // Capability-based model routing for cost-sensitive subagent dispatch.
 //
 // A declarative CWE/severity → model policy. When the orchestrator is about to
@@ -131,6 +135,42 @@ export function routeModelWithTrust(finding, ledger = null) {
   );
 }
 
+// X-604: constrained, calibrated routing, behind the `model-routing` feature (off by default).
+//
+// With the feature off (or no configuration given) this returns EXACTLY what `routeModelWithTrust` returns, the same object shape, so
+// nothing existing changes (test/routing/unchanged-when-off.test.js pins the outputs). With it on, the capability route above becomes
+// the BASELINE: capability, privacy, context, minimum-quality and budget constraints are applied first (routing/decide.js), cost or
+// latency is optimised only among compliant candidates, and the decision carries its explanation. A blocked decision selects nothing:
+// `model` is null and `blocked` is true, so a caller can never mistake it for a route.
+const EXT_LANGUAGE = { js: 'javascript', jsx: 'javascript', mjs: 'javascript', cjs: 'javascript', ts: 'typescript', tsx: 'typescript', py: 'python', java: 'java', kt: 'kotlin', go: 'go', rb: 'ruby', php: 'php', cs: 'csharp', rs: 'rust', hs: 'haskell', nix: 'nix' };
+function languageOfFinding(finding) {
+  const m = typeof finding?.file === 'string' ? finding.file.match(/\.([A-Za-z0-9]+)$/) : null;
+  return (m && EXT_LANGUAGE[m[1].toLowerCase()]) || 'unknown';
+}
+
+export function routeModelWithPolicy(finding, ctx = {}) {
+  const baseline = routeModelWithTrust(finding, ctx.ledger || null);
+  if (!ctx.config || featureStatus(ctx.config, 'model-routing').status !== 'ok') return baseline;
+  // X-608.AC03: the operator can pin or disable adaptive routing. Disabled leaves the capability route exactly as it was; a pin chooses
+  // that model without optimisation (sending a prompt still passes the egress policy in the guarded adapter). A bad value fails closed.
+  const control = ctx.routingControl || resolveRoutingControl({ env: ctx.env || process.env, options: ctx.routingOptions || {} });
+  if (control.mode === 'disabled') return { ...baseline, routingControl: control };
+  if (control.mode === 'pinned') return { model: control.pin, effort: baseline.effort, reason: control.reason, trust: baseline.trust, baseline, pinned: true, routingControl: control };
+  const built = buildRoutingTask({
+    taskId: ctx.taskId || finding?.stableId || finding?.id || 'unidentified-task', taskKind: ctx.taskKind || 'repair',
+    language: ctx.language || languageOfFinding(finding), vulnClass: parseCwe(finding?.cwe) || 'no-cwe',
+    contextTokens: ctx.contextTokens ?? 0, requiredCapabilities: ctx.requiredCapabilities || [], dataClass: ctx.dataClass || 'source-code',
+    synthetic: ctx.synthetic === true,
+  });
+  if (!built.ok) return { model: null, effort: null, blocked: true, reason: `routing task is invalid: ${built.errors.map((e) => e.path).join(', ')}`, trust: baseline.trust, baseline };
+  const decision = routeConstrained({
+    task: built.task, candidates: ctx.candidates || [], calibration: ctx.calibration || null, policy: ctx.policy, now: ctx.now,
+    baselineRoute: baseline, egress: ctx.egress, scanRoot: ctx.scanRoot || null, manifestEgress: ctx.manifestEgress || null, allowSynthetic: ctx.allowSynthetic === true,
+  });
+  if (decision.status === 'blocked') return { model: null, effort: null, blocked: true, reason: decision.reason, trust: baseline.trust, baseline, decision };
+  return { model: decision.selected.model, effort: baseline.effort, reason: decision.reason, trust: baseline.trust, baseline, decision, constrained: decision.status === 'routed' };
+}
+
 // Route a list of findings. Returns [{ finding, model, effort, reason }, …].
 export function routeModelForFindings(findings) {
   const list = Array.isArray(findings) ? findings : [];

package/src/posture/oracles/adapters.js

@@ -0,0 +1,531 @@
+// The five class-specific oracle adapters (X-202.AC01).
+//
+// Each adapter is data plus three small functions, all verifier-authored:
+//   harnessSource  the script the boundary runs. It imports the target, drives it
+//                  with a benign CONTROL input first and the hostile input second,
+//                  and writes a result document. It never decides a verdict.
+//   prepare        builds the harness input from the request inputs plus a
+//                  per-run token the target cannot know in advance.
+//   interpret      forms `{ satisfied, preconditionsHeld, observed, reason }` from
+//                  what the run left behind, read by the verifier after the whole
+//                  process tree is dead. `satisfied: true` means the hypothesised
+//                  effect was observed; `false` with `preconditionsHeld: true`
+//                  means it was not observed although the control proved the
+//                  target was exercised (a refutation); anything else leaves the
+//                  verdict open.
+//
+// Changing what an adapter asserts means bumping its `version`: the version and
+// the harness text feed `logicDigest`, which replay manifests pin.
+//
+// Platform statements are about what this repository's tests have executed. The
+// development host is macOS, so Linux is declared `unverified` everywhere: on
+// Linux the boundary currently refuses to run (read denial and supervised
+// tree termination are not implemented on the namespace backend), which the
+// runner reports as `unsupported`, and no Linux outcome is claimed.
+import { defineOracle } from './oracle.js';
+import crypto from 'node:crypto';
+import { digestOf } from '../assurance/identity.js';
+import { expressionProblems } from '../invariants/expressions.js';
+import { evaluateAssertions, sanitizeSnapshot, eventSequence, hasDurableEffect } from '../invariants/state-assertions.js';
+
+const PLATFORMS = Object.freeze({
+  darwin: { status: 'supported', note: 'executed by this repository\'s tests on the macOS development host (userspace confinement backend)' },
+  linux: { status: 'unverified', note: 'no Linux outcome is claimed: the boundary refuses to run on the namespace backend until read denial and supervised tree termination are implemented and executed there; the run reports unsupported' },
+  win32: { status: 'unsupported', note: 'no confinement backend exists for Windows' },
+});
+
+const COMMON_BUDGETS = Object.freeze({ timeoutMs: 8000, graceMs: 1000, maxOutputBytes: 65536, maxFileBytes: 262144, maxFiles: 32 });
+
+const PROLOGUE = `import fs from 'node:fs';
+const INPUT = __INPUT__;
+const ENTRY = __ENTRY__;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const text = (e) => String((e && e.message) || e).slice(0, 160);
+const out = {};
+function finish(extra) {
+  Object.assign(out, extra);
+  try { fs.writeFileSync('__oracle_result.json', JSON.stringify(out)); } catch {}
+  process.exit(0);
+}
+let mod;
+try { mod = await import('./' + ENTRY); } catch (e) { finish({ loadFailed: true }); }
+const fn = mod && mod[INPUT.export];
+if (typeof fn !== 'function') finish({ loadFailed: true });
+`;
+
+const isId = (s) => typeof s === 'string' && /^[A-Za-z_$][\w$]{0,63}$/.test(s);
+const isStr = (s, max = 2000) => typeof s === 'string' && s.length > 0 && s.length <= max;
+
+// ------------------------------------------------------------------ injection execution
+
+const injection = defineOracle({
+  id: 'injection-execution', class: 'injection-execution', version: '1',
+  description: 'Does attacker-controlled input reach a command interpreter and run? The harness calls the target with a benign control, then with a payload whose effect is a token-named file; the verifier looks for that file after the process tree is dead.',
+  prerequisites: ['node-runtime', 'confinement-backend', 'posix-shell'],
+  platforms: PLATFORMS, budgets: COMMON_BUDGETS,
+  negativeControls: [{ id: 'argv-array-call', description: 'the same handler passing the input as a separate argv element (no shell) must not produce the effect', expectedOutcome: 'refuted' }],
+  fixtures: { dir: 'test/fixtures/oracles/injection-execution', positive: 'positive', negative: 'negative', inconclusive: 'inconclusive' },
+  limitations: ['covers command injection through a shell only; SQL, template and code injection are not asserted here', 'the target is imported into the harness process, so it runs with the harness; a target written to recognise the payload and forge the effect file is not distinguishable from a real injection', 'asynchronous handlers that spawn without being awaited are given settleMs to finish, not guaranteed to'],
+  harnessSource: `${PROLOGUE}
+try { await Promise.resolve(fn(INPUT.benign)); out.controlOk = true; } catch (e) { out.controlOk = false; }
+if (out.controlOk) {
+  try { await Promise.resolve(fn(INPUT.attack)); out.attackReturned = true; } catch (e) { out.attackReturned = false; }
+  await sleep(INPUT.settleMs);
+}
+finish({});
+`,
+  validateInputs(i) {
+    if (!isId(i.export)) return 'export must be an identifier';
+    if (!isStr(i.benign, 500)) return 'benign must be a short string';
+    if (!isStr(i.attackTemplate, 500) || !i.attackTemplate.includes('{TOKEN}')) return 'attackTemplate must be a short string containing {TOKEN}';
+    if (i.settleMs !== undefined && !(Number.isInteger(i.settleMs) && i.settleMs >= 0 && i.settleMs <= 2000)) return 'settleMs must be 0 to 2000';
+    return null;
+  },
+  prepare: (i, token) => ({ export: i.export, benign: i.benign, attack: i.attackTemplate.split('{TOKEN}').join(token), settleMs: i.settleMs ?? 300 }),
+  interpret({ token, result, read }) {
+    const effect = read(`effect-${token}`, 256) === token;
+    const controlOk = result?.controlOk === true;
+    const observed = { effectObserved: effect, controlCompleted: controlOk, targetLoaded: result ? result.loadFailed !== true : null };
+    if (effect) return { satisfied: true, preconditionsHeld: true, observed, reason: 'the injected command ran: its token-named effect file exists' };
+    if (controlOk) return { satisfied: false, preconditionsHeld: true, observed, reason: 'the handler ran its benign control and the injected command left no effect' };
+    return { satisfied: null, preconditionsHeld: false, observed, reason: result?.loadFailed ? 'the target failed to load, so the payload was never delivered' : 'the benign control did not complete, so the payload was never delivered' };
+  },
+});
+
+// ------------------------------------------------------------------ authorization decision
+
+const DECISIONS = ['allow', 'deny', 'error', 'indeterminate'];
+
+const authorization = defineOracle({
+  id: 'authorization-decision', class: 'authorization-decision', version: '1',
+  description: 'Does an authorization function allow an actor it should deny? The harness evaluates declared control cases (the owner, expected allow) and attack cases (another tenant or a lower role, expected deny); the verifier recomputes the verdict from the raw decisions.',
+  prerequisites: ['node-runtime', 'confinement-backend'],
+  platforms: PLATFORMS, budgets: COMMON_BUDGETS,
+  negativeControls: [{ id: 'tenant-checked', description: 'the same function comparing tenant ids must deny the cross-tenant attack case', expectedOutcome: 'refuted' }],
+  fixtures: { dir: 'test/fixtures/oracles/authorization-decision', positive: 'positive', negative: 'negative', inconclusive: 'inconclusive' },
+  limitations: ['asserts the decision function in isolation; a route or middleware that enforces authorization elsewhere is not exercised', 'the cases describe the scenario; the oracle does not infer which actors should be denied', 'a thrown error is not read as a denial'],
+  harnessSource: `${PROLOGUE}
+const norm = (r) => (r === true || r === 'allow' || (r && r.allowed === true)) ? 'allow'
+  : (r === false || r === 'deny' || (r && r.allowed === false)) ? 'deny' : 'indeterminate';
+const decisions = {};
+for (const c of INPUT.cases) {
+  try { decisions[c.id] = norm(await Promise.resolve(fn(...c.args))); } catch (e) { decisions[c.id] = 'error'; }
+}
+finish({ decisions });
+`,
+  validateInputs(i) {
+    if (!isId(i.export)) return 'export must be an identifier';
+    if (!Array.isArray(i.cases) || i.cases.length < 2 || i.cases.length > 16) return 'cases must hold 2 to 16 entries';
+    const ids = new Set();
+    for (const c of i.cases) {
+      if (!c || !isId(String(c.id).replace(/-/g, '_')) || ids.has(c.id)) return 'every case needs a unique id';
+      ids.add(c.id);
+      if (!['control', 'attack'].includes(c.role)) return 'case role must be control or attack';
+      if (!Array.isArray(c.args) || c.args.length > 6) return 'case args must be an array of at most 6';
+    }
+    if (!i.cases.some((c) => c.role === 'control') || !i.cases.some((c) => c.role === 'attack')) return 'at least one control and one attack case are required';
+    return null;
+  },
+  prepare: (i) => ({ export: i.export, cases: i.cases.map((c) => ({ id: c.id, args: c.args })) }),
+  interpret({ inputs, result }) {
+    const got = result && result.decisions && typeof result.decisions === 'object' ? result.decisions : null;
+    if (!got || result.loadFailed) return { satisfied: null, preconditionsHeld: false, observed: { targetLoaded: false }, reason: 'the target did not report decisions' };
+    const decisions = {};
+    for (const c of inputs.cases) decisions[c.id] = DECISIONS.includes(got[c.id]) ? got[c.id] : 'indeterminate';
+    const controls = inputs.cases.filter((c) => c.role === 'control');
+    const attacks = inputs.cases.filter((c) => c.role === 'attack');
+    const controlsHeld = controls.every((c) => decisions[c.id] === 'allow');
+    const allowed = attacks.filter((c) => decisions[c.id] === 'allow').map((c) => c.id);
+    const allDenied = attacks.every((c) => decisions[c.id] === 'deny');
+    const observed = { decisions, controlsAllowed: controlsHeld, attackCasesAllowed: allowed };
+    if (allowed.length) return { satisfied: true, preconditionsHeld: controlsHeld, observed, reason: `the function allowed attack case(s): ${allowed.join(', ')}` };
+    if (allDenied && controlsHeld) return { satisfied: false, preconditionsHeld: true, observed, reason: 'every attack case was denied and every control case was allowed' };
+    return { satisfied: null, preconditionsHeld: false, observed, reason: controlsHeld ? 'an attack case returned neither allow nor deny' : 'a control case was not allowed, so the function was not shown to be deciding' };
+  },
+});
+
+// ------------------------------------------------------------------ state transition
+
+const stateTransition = defineOracle({
+  id: 'state-transition', class: 'state-transition', version: '1',
+  description: 'Does a state machine accept an event sequence that must be refused? The harness drives a fresh machine through the legal sequence (control) and a fresh one through the attack sequence; the verifier compares the final states.',
+  prerequisites: ['node-runtime', 'confinement-backend'],
+  platforms: PLATFORMS, budgets: COMMON_BUDGETS,
+  negativeControls: [{ id: 'payment-required', description: 'the same machine refusing shipment before payment must not reach the forbidden state', expectedOutcome: 'refuted' }],
+  fixtures: { dir: 'test/fixtures/oracles/state-transition', positive: 'positive', negative: 'negative', inconclusive: 'inconclusive' },
+  limitations: ['covers one factory and finite event lists; it is not a model checker', 'durable effects outside the machine object (a database row, a queued job) are not observed', 'the forbidden state is stated by the scenario; the oracle does not infer business rules'],
+  harnessSource: `${PROLOGUE}
+async function drive(events) {
+  const m = await Promise.resolve(fn());
+  const accepted = [];
+  for (const e of events) {
+    try { const r = await Promise.resolve(m.send(e)); accepted.push(r !== false); } catch (err) { accepted.push(false); }
+  }
+  return { state: String(m.state).slice(0, 80), accepted };
+}
+try { const c = await drive(INPUT.legal); out.controlState = c.state; } catch (e) { out.controlState = null; }
+try { const a = await drive(INPUT.attack); out.attackState = a.state; out.attackAccepted = a.accepted; } catch (e) { out.attackState = null; }
+finish({});
+`,
+  validateInputs(i) {
+    if (!isId(i.factory)) return 'factory must be an identifier';
+    const evs = (a) => Array.isArray(a) && a.length >= 1 && a.length <= 16 && a.every((e) => isStr(e, 64));
+    if (!evs(i.legal) || !evs(i.attack)) return 'legal and attack must be lists of 1 to 16 short event names';
+    if (!isStr(i.expectedFinal, 64) || !isStr(i.forbiddenState, 64)) return 'expectedFinal and forbiddenState are required';
+    return null;
+  },
+  prepare: (i) => ({ export: i.factory, legal: i.legal, attack: i.attack }),
+  interpret({ inputs, result }) {
+    if (!result || result.loadFailed) return { satisfied: null, preconditionsHeld: false, observed: { targetLoaded: false }, reason: 'the target failed to load' };
+    const controlHeld = result.controlState === inputs.expectedFinal;
+    const reached = result.attackState === inputs.forbiddenState;
+    const observed = { controlState: result.controlState ?? null, controlReachedExpected: controlHeld, attackState: result.attackState ?? null, attackAccepted: Array.isArray(result.attackAccepted) ? result.attackAccepted.slice(0, 16).map((b) => b === true) : [] };
+    if (reached) return { satisfied: true, preconditionsHeld: controlHeld, observed, reason: `the attack sequence reached the forbidden state '${inputs.forbiddenState}'` };
+    if (controlHeld) return { satisfied: false, preconditionsHeld: true, observed, reason: 'the legal sequence reached its expected state and the attack sequence did not reach the forbidden one' };
+    return { satisfied: null, preconditionsHeld: false, observed, reason: 'the legal sequence did not reach its expected state, so the machine was not shown to be working' };
+  },
+});
+
+// ------------------------------------------------------------------ side-effect reachability
+
+const sideEffect = defineOracle({
+  id: 'side-effect-reachability', class: 'side-effect-reachability', version: '1',
+  description: 'Does attacker-chosen input reach a privileged side-effecting operation? The harness injects a recording stand-in for the sink, calls the handler with a benign value (control) and an attacker value, and the verifier checks which values reached the sink.',
+  prerequisites: ['node-runtime', 'confinement-backend'],
+  platforms: PLATFORMS, budgets: COMMON_BUDGETS,
+  negativeControls: [{ id: 'allowlisted-target', description: 'the same handler with a destination allowlist must not pass the attacker value to the sink', expectedOutcome: 'refuted' }],
+  fixtures: { dir: 'test/fixtures/oracles/side-effect-reachability', positive: 'positive', negative: 'negative', inconclusive: 'inconclusive' },
+  limitations: ['the sink is a recording stand-in injected as the handler\'s second argument; handlers that import their sink directly are not covered', 'reaching the sink shows the operation would be invoked with the attacker value, not that the real operation would succeed', 'no network or privileged call is ever made'],
+  harnessSource: `${PROLOGUE}
+const calls = [];
+const deps = { [INPUT.sink]: (...args) => { try { calls.push(JSON.stringify(args).slice(0, 600)); } catch {} return Promise.resolve({ ok: true, status: 200, text: async () => '' }); } };
+const reached = (v) => calls.some((c) => c.includes(JSON.stringify(v).slice(1, -1)));
+try { await Promise.resolve(fn(INPUT.benignValue, deps)); } catch (e) {}
+out.benignReached = reached(INPUT.benignValue);
+calls.length = 0;
+try { await Promise.resolve(fn(INPUT.attackerValue, deps)); } catch (e) {}
+out.attackReached = reached(INPUT.attackerValue);
+finish({});
+`,
+  validateInputs(i) {
+    if (!isId(i.export) || !isId(i.sink)) return 'export and sink must be identifiers';
+    if (!isStr(i.benignValue, 500) || !isStr(i.attackerValue, 500) || i.benignValue === i.attackerValue) return 'benignValue and attackerValue must be distinct short strings';
+    return null;
+  },
+  prepare: (i) => ({ export: i.export, sink: i.sink, benignValue: i.benignValue, attackerValue: i.attackerValue }),
+  interpret({ result }) {
+    if (!result || result.loadFailed) return { satisfied: null, preconditionsHeld: false, observed: { targetLoaded: false }, reason: 'the target failed to load' };
+    const benign = result.benignReached === true;
+    const attack = result.attackReached === true;
+    const observed = { benignReachedSink: benign, attackerValueReachedSink: attack };
+    if (attack) return { satisfied: true, preconditionsHeld: benign, observed, reason: 'the attacker-chosen value reached the side-effecting sink' };
+    if (benign) return { satisfied: false, preconditionsHeld: true, observed, reason: 'the benign value reached the sink and the attacker value did not' };
+    return { satisfied: null, preconditionsHeld: false, observed, reason: 'even the benign value never reached the sink, so the handler was not shown to use it' };
+  },
+});
+
+// ------------------------------------------------------------------ parser / resource behaviour
+
+const parserResource = defineOracle({
+  id: 'parser-resource', class: 'parser-resource', version: '1',
+  description: 'Does a parser or matcher exhaust its budget on a bounded hostile input? The harness completes a benign control (marker file), then feeds the hostile input; the verifier\'s own supervisor deadline is the measurement, so no self-reported timing is trusted.',
+  prerequisites: ['node-runtime', 'confinement-backend'],
+  platforms: PLATFORMS, budgets: { ...COMMON_BUDGETS, timeoutMs: 5000 },
+  negativeControls: [{ id: 'linear-pattern', description: 'the same matcher written without nested quantifiers must finish the hostile input inside the budget', expectedOutcome: 'refuted' }],
+  fixtures: { dir: 'test/fixtures/oracles/parser-resource', positive: 'positive', negative: 'negative', inconclusive: 'inconclusive' },
+  limitations: ['the hostile input is bounded (at most 64 KiB) and the run is cut at the supervisor deadline; this shows a budget was exceeded, not how large the blow-up is', 'a hard crash without a deadline or output-cap hit is left inconclusive rather than called exhaustion', 'memory is not measured: address-space limits are not enforceable on the macOS backend'],
+  harnessSource: `${PROLOGUE}
+const mark = (name) => { try { fs.writeFileSync(name, INPUT.token); } catch {} };
+try { await Promise.resolve(fn(INPUT.benign)); mark('__oracle_benign_done'); } catch (e) { finish({ benignFailed: true }); }
+try { await Promise.resolve(fn(INPUT.hostile)); } catch (e) {}
+mark('__oracle_hostile_done');
+finish({});
+`,
+  validateInputs(i) {
+    if (!isId(i.export)) return 'export must be an identifier';
+    if (!isStr(i.benign, 500)) return 'benign must be a short string';
+    const h = i.hostile;
+    if (!h || !isStr(h.unit, 16) || !Number.isInteger(h.count) || h.count < 1 || h.count > 65536 || (h.suffix !== undefined && !isStr(h.suffix, 16))) return 'hostile needs unit (short), count (1 to 65536) and an optional short suffix';
+    return null;
+  },
+  prepare: (i, token) => ({ export: i.export, benign: i.benign, hostile: i.hostile.unit.repeat(i.hostile.count) + (i.hostile.suffix || ''), token }),
+  interpret({ token, run, read }) {
+    const benignDone = read('__oracle_benign_done', 128) === token;
+    const hostileDone = read('__oracle_hostile_done', 128) === token;
+    const observed = { benignCompleted: benignDone, hostileCompleted: hostileDone, deadlineHit: run.timedOut, outputCapHit: run.outputCapped };
+    if (!benignDone) return { satisfied: null, preconditionsHeld: false, observed, reason: 'the benign control did not complete, so the target was not shown to be working' };
+    if (hostileDone) return { satisfied: false, preconditionsHeld: true, observed, reason: 'the hostile input was handled inside the budget' };
+    if (run.timedOut || run.outputCapped) return { satisfied: true, preconditionsHeld: true, observed, reason: run.timedOut ? 'the hostile input exhausted the time budget (the supervisor deadline fired)' : 'the hostile input exhausted the output budget' };
+    return { satisfied: null, preconditionsHeld: true, observed, reason: 'the run ended without finishing the hostile input and without hitting a budget, so the cause is unknown' };
+  },
+});
+
+// ------------------------------------------------------------------ replay / idempotency (X-205)
+
+const replayIdempotency = defineOracle({
+  id: 'replay-idempotency', class: 'replay-idempotency', version: '1',
+  description: 'Does delivering the same request again repeat its side effect? The harness builds a fresh handler around a recording stand-in for the effect, delivers a request and then a DISTINCT request (control: one effect each), then on a second fresh handler delivers the same request repeatedly; the verifier counts the effects.',
+  prerequisites: ['node-runtime', 'confinement-backend'],
+  platforms: PLATFORMS, budgets: COMMON_BUDGETS,
+  negativeControls: [{ id: 'idempotency-key-honoured', description: 'the same handler remembering the idempotency key must produce exactly one effect for the repeated request', expectedOutcome: 'refuted' }],
+  fixtures: { dir: 'test/fixtures/oracles/replay-idempotency', positive: 'positive', negative: 'negative', inconclusive: 'inconclusive' },
+  limitations: ['the target is a factory that receives a recording stand-in for its effect and returns a handler; code that imports its effect directly is not covered', 'deliveries are sequential: a race between concurrent deliveries is not exercised', 'durable deduplication in an external store is not observed, only the handler instance the factory returns', 'reaching the effect twice shows the handler would repeat it, not that the real operation would succeed'],
+  harnessSource: `${PROLOGUE}
+const mk = () => { const calls = []; return { calls, deps: { [INPUT.sink]: (...a) => { calls.push(1); return Promise.resolve({ ok: true }); } } }; };
+async function build() { const m = mk(); const h = await Promise.resolve(fn(m.deps)); if (typeof h !== 'function') throw new Error('not a handler'); return { m, h }; }
+try {
+  const c = await build();
+  try { await Promise.resolve(c.h(INPUT.request)); } catch (e) {}
+  out.firstEffects = c.m.calls.length;
+  try { await Promise.resolve(c.h(INPUT.distinctRequest)); } catch (e) {}
+  out.distinctEffects = c.m.calls.length;
+} catch (e) { out.controlFailed = true; }
+try {
+  const a = await build();
+  for (let i = 0; i < INPUT.deliveries; i++) { try { await Promise.resolve(a.h(INPUT.request)); } catch (e) {} }
+  out.replayEffects = a.m.calls.length;
+} catch (e) { out.replayFailed = true; }
+finish({});
+`,
+  validateInputs(i) {
+    if (!isId(i.export) || !isId(i.sink)) return 'export and sink must be identifiers';
+    const small = (v) => { try { const s = JSON.stringify(v); return typeof s === 'string' && s.length <= 2000 && v !== null && typeof v === 'object' && !Array.isArray(v); } catch { return false; } };
+    if (!small(i.request) || !small(i.distinctRequest)) return 'request and distinctRequest must be small JSON objects';
+    if (digestOf(i.request) === digestOf(i.distinctRequest)) return 'distinctRequest must differ from request';
+    if (!(Number.isInteger(i.deliveries) && i.deliveries >= 2 && i.deliveries <= 6)) return 'deliveries must be 2 to 6';
+    return null;
+  },
+  prepare: (i) => ({ export: i.export, sink: i.sink, request: i.request, distinctRequest: i.distinctRequest, deliveries: i.deliveries }),
+  interpret({ result }) {
+    if (!result || result.loadFailed) return { satisfied: null, preconditionsHeld: false, observed: { targetLoaded: false }, reason: 'the target failed to load' };
+    const first = Number.isInteger(result.firstEffects) ? result.firstEffects : null;
+    const distinct = Number.isInteger(result.distinctEffects) ? result.distinctEffects : null;
+    const replay = Number.isInteger(result.replayEffects) ? result.replayEffects : null;
+    const controlHeld = first === 1 && distinct === 2;
+    const observed = { targetLoaded: true, firstDeliveryEffects: first, distinctDeliveryTotalEffects: distinct, repeatedDeliveryTotalEffects: replay, controlHeld };
+    if (replay !== null && replay > 1) return { satisfied: true, preconditionsHeld: controlHeld, observed, reason: `the same request delivered repeatedly produced ${replay} effects` };
+    if (controlHeld && replay === 1) return { satisfied: false, preconditionsHeld: true, observed, reason: 'a distinct request produced its own effect and the repeated request produced exactly one' };
+    return { satisfied: null, preconditionsHeld: false, observed, reason: controlHeld ? 'the repeated deliveries did not report' : 'the handler did not produce exactly one effect per first delivery, so it was not shown to be working' };
+  },
+});
+
+// ------------------------------------------------------------------ functional regression (X-204)
+
+const functionalRegression = defineOracle({
+  id: 'functional-regression', class: 'functional-regression', version: '1',
+  description: 'Does a revision still behave as intended? The harness calls the exported function with declared cases and records each result; the verifier compares them with the declared expectations. The hypothesis is that the behaviour REGRESSED, so a patch is clean when this is refuted.',
+  prerequisites: ['node-runtime', 'confinement-backend'],
+  platforms: PLATFORMS, budgets: COMMON_BUDGETS,
+  negativeControls: [{ id: 'behaviour-preserved', description: 'a revision that returns the expected value for every declared case must show no regression', expectedOutcome: 'refuted' }],
+  fixtures: { dir: 'test/fixtures/oracles/functional-regression', positive: 'positive', negative: 'negative', inconclusive: 'inconclusive' },
+  limitations: ['only the declared cases are checked: behaviour outside them is not observed, and a patch that breaks an undeclared path is not detected', 'results are compared as JSON values, so identity, ordering of unordered data and timing are not compared', 'the expectations are supplied by the requester and are not inferred; expectations that are wrong for the ORIGINAL revision are reported by the baseline check, not hidden'],
+  harnessSource: `${PROLOGUE}
+const results = {};
+for (const c of INPUT.cases) {
+  try { const v = await Promise.resolve(fn(...c.args)); results[c.id] = { ok: true, value: v === undefined ? null : JSON.parse(JSON.stringify(v)) }; }
+  catch (e) { results[c.id] = { ok: false }; }
+}
+finish({ results });
+`,
+  validateInputs(i) {
+    if (!isId(i.export)) return 'export must be an identifier';
+    if (!Array.isArray(i.cases) || i.cases.length < 1 || i.cases.length > 16) return 'cases must hold 1 to 16 entries';
+    const ids = new Set();
+    for (const c of i.cases) {
+      if (!c || typeof c.id !== 'string' || !/^[a-z0-9-]{1,40}$/.test(c.id) || ids.has(c.id)) return 'every case needs a unique slug id';
+      ids.add(c.id);
+      if (!Array.isArray(c.args) || c.args.length > 6) return 'case args must be an array of at most 6';
+      if (!('expected' in c)) return 'every case needs an expected value';
+      try { if (JSON.stringify(c.expected) === undefined) return 'expected must be JSON'; } catch { return 'expected must be JSON'; }
+    }
+    return null;
+  },
+  prepare: (i) => ({ export: i.export, cases: i.cases.map((c) => ({ id: c.id, args: c.args })) }),
+  interpret({ inputs, result }) {
+    const got = result && result.results && typeof result.results === 'object' ? result.results : null;
+    if (!got || result.loadFailed) return { satisfied: null, preconditionsHeld: false, observed: { targetLoaded: false }, reason: 'the target did not report results' };
+    const regressions = [];
+    let reported = 0;
+    for (const c of inputs.cases) {
+      const r = got[c.id];
+      if (!r || typeof r !== 'object') continue;
+      reported++;
+      if (r.ok !== true || digestOf(r.value) !== digestOf(c.expected)) regressions.push(c.id);
+    }
+    const complete = reported === inputs.cases.length;
+    const observed = { targetLoaded: true, casesDeclared: inputs.cases.length, casesReported: reported, regressedCases: regressions };
+    if (regressions.length) return { satisfied: true, preconditionsHeld: complete, observed, reason: `behaviour differs from the declared expectation in case(s): ${regressions.join(', ')}` };
+    if (complete) return { satisfied: false, preconditionsHeld: true, observed, reason: 'every declared case returned its expected value' };
+    return { satisfied: null, preconditionsHeld: false, observed, reason: 'not every declared case reported a result' };
+  },
+});
+
+// ------------------------------------------------------------------ business state (X-404)
+
+const BS_MAX_OPS = 16;
+const BS_MAX_ITEMS = 12;
+
+function bsStepProblem(step, actorIds) {
+  if (!step || typeof step !== 'object' || Array.isArray(step)) return 'a step must be an object';
+  if (!actorIds.has(step.actor)) return 'a step actor must be a declared actor';
+  if (!isId(step.action)) return 'a step action must be an identifier';
+  if (step.args !== undefined) {
+    if (!Array.isArray(step.args) || step.args.length > 4) return 'step args must be an array of at most 4';
+    try { if (Buffer.byteLength(JSON.stringify(step.args)) > 400) return 'step args are too large'; } catch { return 'step args must be JSON'; }
+  }
+  return null;
+}
+
+/** Problems with one sequence of items (steps or deterministic parallel groups), counting operations toward the shared ceiling. */
+function bsSequenceProblem(items, actorIds, label) {
+  if (!Array.isArray(items) || items.length < 1 || items.length > BS_MAX_ITEMS) return `${label} must hold 1 to ${BS_MAX_ITEMS} items`;
+  let ops = 0;
+  for (const it of items) {
+    if (it && Array.isArray(it.parallel)) {
+      if (it.parallel.length < 2 || it.parallel.length > 4) return 'a parallel group holds 2 to 4 steps';
+      const sched = it.schedule;
+      if (!Array.isArray(sched) || sched.length !== it.parallel.length || [...sched].sort().join() !== it.parallel.map((_, i) => i).join()) return 'a parallel group needs a schedule that is a permutation of its steps';
+      for (const s of it.parallel) { const why = bsStepProblem(s, actorIds); if (why) return why; }
+      ops += it.parallel.length;
+    } else {
+      const why = bsStepProblem(it, actorIds);
+      if (why) return why;
+      ops += 1;
+    }
+  }
+  return ops > BS_MAX_OPS ? `${label} exceeds ${BS_MAX_OPS} operations` : null;
+}
+
+const sha256hex = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+const businessState = defineOracle({
+  id: 'business-state', class: 'business-state', version: '1',
+  requiresFeature: 'invariant-scenarios',
+  description: 'Does a bounded stateful scenario drive an application into a state its invariant forbids? The harness gives the application a durable store and an effect recorder, plays a control sequence and an adversarial sequence (twice, to detect nondeterministic scheduling), and logs every durable write and emitted effect. The verifier evaluates the invariant\'s forbidden outcomes over that log; the response status is recorded but never decides.',
+  prerequisites: ['node-runtime', 'confinement-backend'],
+  platforms: PLATFORMS, budgets: COMMON_BUDGETS,
+  negativeControls: [{ id: 'tenant-scoped-writes', description: 'the same application scoping every write to the caller\'s tenant must leave the forbidden state unreached while its control flow still changes durable state', expectedOutcome: 'refuted' }],
+  fixtures: { dir: 'test/fixtures/oracles/business-state', positive: 'positive', negative: 'negative', inconclusive: 'inconclusive' },
+  limitations: [
+    'the application is a factory taking no arguments that returns action functions (ctx, ...args); ctx.store and ctx.emit are in-memory stand-ins, so durable state held anywhere else (a real database, a queue, the file system) is not observed',
+    'concurrency is cooperative scheduling inside one process with a fixed start order: it exercises interleavings at await points, not parallel execution, and a scenario whose two runs disagree is reported inconclusive rather than guessed',
+    'only the declared forbidden outcomes are checked, over the declared actors, tenants and steps; a clean result is a statement about this bounded scenario, not about the application',
+    'a target that recognises the oracle and forges its own log entries is not distinguishable from a real violation (the same limit every adapter states)',
+  ],
+  harnessSource: `${PROLOGUE}
+import crypto from 'node:crypto';
+const clone = (v) => (v === undefined ? null : JSON.parse(JSON.stringify(v)));
+const actorOf = (id) => INPUT.actors.find((a) => a.id === id);
+async function play(items, phase) {
+  const data = new Map();
+  for (const s of INPUT.seed) data.set(s.key, clone(s.value));
+  const initial = Object.fromEntries(data);
+  const log = [];
+  const api = await Promise.resolve(fn());
+  async function runOp(opIndex, itemIndex, step) {
+    const a = actorOf(step.actor);
+    const entry = { item: itemIndex, op: opIndex, phase, actor: step.actor, action: step.action, ok: false, status: null, response: null, writes: [], events: [] };
+    log.push(entry);
+    const raw = [];
+    const ctx = {
+      id: a.id, tenant: a.tenant, role: a.role,
+      store: {
+        read: (k) => (data.has(String(k)) ? clone(data.get(String(k))) : null),
+        list: (p) => [...data.keys()].filter((k) => k.startsWith(String(p))).sort(),
+        write: (k, v) => { k = String(k); raw.push({ key: k, before: data.has(k) ? clone(data.get(k)) : null, after: clone(v) }); data.set(k, clone(v)); },
+        remove: (k) => { k = String(k); if (!data.has(k)) return; raw.push({ key: k, before: clone(data.get(k)), after: null }); data.delete(k); },
+      },
+      emit: (name, payload) => { entry.events.push({ name: String(name).slice(0, 64), key: payload && payload.key !== undefined ? String(payload.key).slice(0, 64) : null }); },
+    };
+    try {
+      const f = api && api[step.action];
+      if (typeof f !== 'function') throw new Error('no such action');
+      const r = await Promise.resolve(f.call(api, ctx, ...(step.args || [])));
+      entry.ok = true;
+      entry.status = r && typeof r.status === 'number' ? r.status : null;
+      try { entry.response = JSON.stringify(r === undefined ? null : r).slice(0, 300); } catch (e) { entry.response = null; }
+    } catch (e) { entry.error = text(e).slice(0, 80); }
+    const net = new Map();
+    for (const w of raw) { const p = net.get(w.key); net.set(w.key, p ? { key: w.key, before: p.before, after: w.after } : w); }
+    entry.writes = [...net.values()].filter((w) => JSON.stringify(w.before) !== JSON.stringify(w.after));
+  }
+  let i = 0;
+  for (const item of items) {
+    if (item.parallel) await Promise.allSettled(item.schedule.map((idx) => runOp(idx, i, item.parallel[idx])));
+    else await runOp(0, i, item);
+    i++;
+  }
+  const final = Object.fromEntries(data);
+  data.clear();
+  return { initial, steps: log, final, cleaned: data.size === 0 };
+}
+let c = null; let a1 = null; let a2 = null;
+try { c = await play(INPUT.control, 'control'); } catch (e) { out.controlFailed = true; }
+try { a1 = await play(INPUT.attack, 'attack'); a2 = await play(INPUT.attack, 'attack'); } catch (e) { out.attackFailed = true; }
+out.control = c; out.attack = a1;
+if (a1 && a2) out.replayDigest = crypto.createHash('sha256').update(JSON.stringify(a2)).digest('hex');
+if (JSON.stringify(out).length > 15000) { delete out.control; delete out.attack; out.oversize = true; }
+finish({});
+`,
+  validateInputs(i) {
+    if (!isId(i.export)) return 'export must be an identifier';
+    const inv = i.invariant;
+    if (!inv || typeof inv.id !== 'string' || !inv.id.startsWith('inv:') || !isStr(inv.key, 64) || !Number.isInteger(inv.revision) || !isStr(inv.class, 64)) return 'invariant needs id, key, revision and class';
+    if (!Array.isArray(i.actors) || i.actors.length < 1 || i.actors.length > 8 || !i.actors.every((a) => a && isStr(a.id, 64) && isStr(a.tenant, 64) && isStr(a.role, 64))) return 'actors must hold 1 to 8 entries with id, tenant and role';
+    const actorIds = new Set(i.actors.map((a) => a.id));
+    if (actorIds.size !== i.actors.length) return 'actor ids must be unique';
+    if (i.markers !== undefined && (!Array.isArray(i.markers) || i.markers.length > 16 || !i.markers.every((m) => m && isStr(m.tenant, 64) && isStr(m.marker, 64)))) return 'markers must be at most 16 entries of tenant and marker';
+    if (!Array.isArray(i.seed) || i.seed.length > 16) return 'seed must hold at most 16 records';
+    for (const s of i.seed) {
+      if (!s || !isStr(s.key, 64) || !s.value || typeof s.value !== 'object' || Array.isArray(s.value)) return 'every seed record needs a key and an object value';
+      try { if (Buffer.byteLength(JSON.stringify(s.value)) > 400) return 'a seed record is too large'; } catch { return 'seed values must be JSON'; }
+    }
+    const c = bsSequenceProblem(i.control, actorIds, 'control'); if (c) return c;
+    const a = bsSequenceProblem(i.attack, actorIds, 'attack'); if (a) return a;
+    if (!Array.isArray(i.forbidden) || i.forbidden.length < 1 || i.forbidden.length > 8) return 'forbidden must hold 1 to 8 expressions';
+    for (const f of i.forbidden) { const p = expressionProblems(f); if (p.length) return `forbidden: ${p[0]}`; }
+    if (!Array.isArray(i.cleanup) || i.cleanup.length !== 1 || i.cleanup[0]?.action !== 'discard-world') return 'cleanup must be exactly [{ action: "discard-world" }]';
+    return null;
+  },
+  prepare: (i) => ({ export: i.export, actors: i.actors.map((a) => ({ id: a.id, tenant: a.tenant, role: a.role })), seed: i.seed, control: i.control, attack: i.attack }),
+  interpret({ inputs, result }) {
+    if (!result || result.loadFailed) return { satisfied: null, preconditionsHeld: false, observed: { targetLoaded: false }, reason: 'the target failed to load' };
+    if (result.oversize) return { satisfied: null, preconditionsHeld: false, observed: { logWithinCap: false }, reason: 'the scenario log exceeded the size cap, so no assertion was evaluated' };
+    if (result.controlFailed || result.attackFailed || !result.control || !result.attack) return { satisfied: null, preconditionsHeld: false, observed: { applicationStarted: false }, reason: 'the application factory failed to start for the scenario' };
+    const actors = Object.fromEntries(inputs.actors.map((a) => [a.id, { tenant: a.tenant, role: a.role }]));
+    const common = { invariantId: inputs.invariant.id, forbidden: inputs.forbidden, actors, markers: inputs.markers || [] };
+    const controlResults = evaluateAssertions({ ...common, phaseLog: result.control });
+    const attackResults = evaluateAssertions({ ...common, phaseLog: result.attack });
+    const deterministic = typeof result.replayDigest === 'string' && result.replayDigest === sha256hex(JSON.stringify(result.attack));
+    const preconditions = {
+      controlRan: result.control.steps.length > 0 && result.control.steps.every((s) => s.ok === true),
+      controlDurableEffect: hasDurableEffect(result.control),
+      controlClean: controlResults.every((r) => !r.violated),
+      cleanedUp: result.control.cleaned === true && result.attack.cleaned === true,
+      deterministic,
+    };
+    const controlHeld = preconditions.controlRan && preconditions.controlDurableEffect && preconditions.controlClean && preconditions.cleanedUp;
+    // A forbidden outcome reached by the CONTROL flow is a violation too (the legitimate path itself breaks the contract); it is
+    // reported under its own phase and cannot be mistaken for an adversarial finding.
+    const assertionsAll = [...attackResults.map((r) => ({ ...r, phase: 'attack' })), ...controlResults.filter((r) => r.violated).map((r) => ({ ...r, phase: 'control' }))];
+    const violated = assertionsAll.filter((r) => r.violated);
+    const report = {
+      schema: 'agentic-security/business-state-report', invariant: { id: inputs.invariant.id, key: inputs.invariant.key, revision: inputs.invariant.revision, class: inputs.invariant.class },
+      preconditions, snapshots: { initial: sanitizeSnapshot(result.attack.initial), final: sanitizeSnapshot(result.attack.final) },
+      events: eventSequence(result.attack),
+      assertions: assertionsAll.map((r) => ({ id: r.id, phase: r.phase, op: r.op, violated: r.violated, ops: r.ops, detail: r.detail, evidenceId: r.evidenceId })),
+    };
+    const observed = {
+      preconditions, violatedAssertions: violated.map((r) => r.id), assertions: assertionsAll.length,
+      evidenceIds: assertionsAll.map((r) => r.evidenceId), reportDigest: digestOf(report),
+    };
+    const evidenceItems = assertionsAll.map((r) => ({ id: r.evidenceId, digest: digestOf({ id: r.id, phase: r.phase, op: r.op, violated: r.violated, ops: r.ops }) }));
+    const base = { observed, report, evidenceItems };
+    if (!deterministic) return { ...base, satisfied: null, preconditionsHeld: false, reason: 'the adversarial sequence did not reproduce itself across two fresh runs (nondeterministic scheduling), so no verdict is formed' };
+    if (violated.length) return { ...base, satisfied: true, preconditionsHeld: controlHeld, reason: `forbidden durable state reached: ${violated.map((r) => `${r.id} in the ${r.phase} sequence (${r.detail})`).join('; ').slice(0, 300)}` };
+    if (controlHeld) return { ...base, satisfied: false, preconditionsHeld: true, reason: 'the control flow changed durable state as intended and no forbidden outcome was observed in the adversarial sequence' };
+    return { ...base, satisfied: null, preconditionsHeld: false, reason: 'the control flow did not show the application working (no durable effect, an error, or a violation in the legitimate flow), so the absence of a violation proves nothing' };
+  },
+});
+
+export const ADAPTERS = Object.freeze([injection, authorization, stateTransition, sideEffect, parserResource, replayIdempotency, functionalRegression, businessState]);