@clear-capabilities/agentic-security-scanner 0.162.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

@@ -23,7 +23,10 @@
 // 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)' },
@@ -357,4 +360,172 @@ finish({ results });
   },
 });
 
-export const ADAPTERS = Object.freeze([injection, authorization, stateTransition, sideEffect, parserResource, replayIdempotency, functionalRegression]);
+// ------------------------------------------------------------------ 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]);

package/src/posture/oracles/conformance.js

@@ -140,7 +140,8 @@ export function checkFixturePins(adapter, scannerRoot, pins = loadPins(scannerRo
 
 // ---------------------------------------------------------------- execution
 
-const enabledConfig = () => resolveAssuranceConfig({ env: {}, overrides: { features: { [FEATURE_ID]: true } } });
+// An adapter that declares `requiresFeature` (X-404) needs that feature enabled too; conformance enables exactly the ones the adapter names.
+const enabledConfig = (adapter) => resolveAssuranceConfig({ env: {}, overrides: { features: { [FEATURE_ID]: true, ...(adapter?.requiresFeature ? { [adapter.requiresFeature]: true } : {}) } } });
 
 function requestFor(adapter, scannerRoot, kind, over = {}) {
   const f = readFixture(scannerRoot, adapter, kind);
@@ -164,7 +165,7 @@ function requestFor(adapter, scannerRoot, kind, over = {}) {
 export async function runAdapterConformance(adapter, { scannerRoot, run = runOracle, runOptions = {}, harnessProcesses = null } = {}) {
   const checks = [];
   const registry = { getOracle: (id) => (id === adapter.id ? adapter : null) };
-  const go = (req, extra = {}) => run(req, { config: enabledConfig(), registry, ...runOptions, ...extra });
+  const go = (req, extra = {}) => run(req, { config: enabledConfig(adapter), registry, ...runOptions, ...extra });
   try {
     const pos = await go(requestFor(adapter, scannerRoot, 'positive'));
     if (pos.status === 'unsupported' || pos.status === 'blocked' || pos.status === 'disabled') {

package/src/posture/oracles/oracle.js

@@ -46,7 +46,7 @@ import path from 'node:path';
 import { runInBoundary } from '../../sandbox/trust-boundary.js';
 import { detectBackend } from '../../sandbox/capabilities.js';
 import { DOMAINS, settleVerification } from '../../sandbox/trust-domains.js';
-import { resolveAssuranceConfig, featureStatus } from '../assurance/config.js';
+import { resolveAssuranceConfig, featureStatus, FEATURES } from '../assurance/config.js';
 import { digestOf, digestOfBytes } from '../assurance/identity.js';
 import { isCommit, isPlainObject } from '../assurance/schema-kit.js';
 import { emitVerification } from '../verification/emit.js';
@@ -56,6 +56,8 @@ export const ORACLE_CLASSES = Object.freeze([
   'injection-execution', 'authorization-decision', 'state-transition', 'side-effect-reachability', 'parser-resource',
   // X-205 and X-204: a replayed request that repeats its effect, and a differential behaviour check for a patch.
   'replay-idempotency', 'functional-regression',
+  // X-404: durable business and tenant state judged over a bounded stateful scenario.
+  'business-state',
 ]);
 const PLATFORM_STATUSES = Object.freeze(['supported', 'unverified', 'unsupported']);
 export const FEATURE_ID = 'verification-oracles';
@@ -66,6 +68,7 @@ const RECEIPT_SCHEMA = 'agentic-security/oracle-receipt';
 const RESERVED_PREFIX = '__oracle_';
 const MAX_INPUT_BYTES = 64 * 1024;
 const MAX_OBSERVED_BYTES = 4 * 1024;
+const MAX_REPORT_BYTES = 32 * 1024;
 const REQUEST_KEYS = ['oracleId', 'hypothesisId', 'finding', 'commit', 'files', 'entry', 'inputs', 'attempt', 'budgets', 'detectorOrigin'];
 const BUDGET_KEYS = ['timeoutMs', 'graceMs', 'maxOutputBytes', 'maxFileBytes', 'maxFiles'];
 
@@ -129,6 +132,7 @@ export function validateOracleSpec(spec) {
   }
   if (!isPlainObject(spec.fixtures) || !['dir', 'positive', 'negative', 'inconclusive'].every((k) => typeof spec.fixtures[k] === 'string' && spec.fixtures[k])) errs.push('fixtures need dir, positive, negative and inconclusive');
   if (!Array.isArray(spec.limitations) || spec.limitations.length === 0) errs.push('limitations must be stated');
+  if (spec.requiresFeature !== undefined && !(typeof spec.requiresFeature === 'string' && FEATURES[spec.requiresFeature])) errs.push('requiresFeature must name a known feature');
   if (typeof spec.harnessSource !== 'string' || !spec.harnessSource.includes('__INPUT__')) errs.push('harnessSource (verifier-authored) is required');
   for (const fn of ['prepare', 'validateInputs', 'interpret']) if (typeof spec[fn] !== 'function') errs.push(`${fn} must be a function`);
   return errs;
@@ -335,6 +339,14 @@ export async function runOracle(request, o = {}) {
     return none(gate.status === 'unsupported' ? 'unsupported' : 'not-run', `${FEATURE_ID} is not available: ${gate.reason}`, gate.status === 'unsupported' ? 'unsupported' : 'disabled', { gate });
   }
 
+  // 1b. an adapter may require a second feature of its own (X-404: stateful invariant scenarios are separately opt-in)
+  if (oracle.requiresFeature) {
+    const g2 = featureStatus(config, oracle.requiresFeature);
+    if (g2.status !== 'ok') {
+      return none(g2.status === 'unsupported' ? 'unsupported' : 'not-run', `${oracle.requiresFeature} is not available: ${g2.reason}`, g2.status === 'unsupported' ? 'unsupported' : 'disabled', { gate: g2 });
+    }
+  }
+
   // 2. prerequisites: an unmet one is `unsupported`, never a pass, and nothing executes
   const env = o.probeEnv || probeEnvironment();
   const unmet = [];
@@ -413,14 +425,22 @@ export async function runOracle(request, o = {}) {
       // identical record id); it is bound into the receipt instead.
       digest: digestOf({ oracle: oracle.logicDigest, observed }), source: `oracle:${oracle.id}@${oracle.version}`,
     }];
+    // An adapter may add per-assertion evidence items (stable ids, derived from the observed log) and a bounded report (sanitized
+    // snapshots, event sequence, assertion results). Both come from verifier-side interpretation, never from the target.
+    if (Array.isArray(judged.evidenceItems)) {
+      for (const it of judged.evidenceItems.slice(0, 16)) {
+        if (it && typeof it.id === 'string' && typeof it.digest === 'string') evidence.push({ id: it.id, kind: 'observation', producer: 'trusted-runner', digest: it.digest, source: `oracle:${oracle.id}@${oracle.version}` });
+      }
+    }
+    const report = judged.report !== undefined && Buffer.byteLength(JSON.stringify(judged.report) ?? '') <= MAX_REPORT_BYTES ? JSON.parse(JSON.stringify(judged.report)) : undefined;
     const out = finishWithRecord(oracle, req, 'completed', outcomeFields(oracle, req, {
       outcome, reason, attempt: attemptNo, evidence, preconditionsValid: evidenceIn.preconditionsHeld, backend: boundary.backend,
-    }), { executed: true, run: runInfo, environment, targetOutput: boundary.targetOutput });
+    }), { executed: true, run: runInfo, environment, targetOutput: boundary.targetOutput, ...(report !== undefined ? { report } : {}) });
     out.receipt = issueReceipt({
       schema: RECEIPT_SCHEMA, issuedBy: 'verifier',
       oracle: { id: oracle.id, class: oracle.class, version: oracle.version, logicDigest: oracle.logicDigest },
       request: { hypothesisId: req.hypothesisId, commit: req.commit ?? null, entry: req.entry, inputsDigest: digestOf(req.inputs), filesDigest: digestOf(req.files), attempt: attemptNo },
-      environment, run: runInfo, observed, harnessDigest,
+      environment, run: runInfo, observed, harnessDigest, reportDigest: report !== undefined ? digestOf(report) : null,
       settled: { outcome, satisfied: judged.satisfied, preconditionsHeld: evidenceIn.preconditionsHeld }, recordId: out.record?.id ?? null,
     });
     return out;

package/src/posture/oracles/registry.js

@@ -33,7 +33,7 @@ export function manifestEntry(a) {
   return {
     id: a.id, class: a.class, version: a.version, logicDigest: a.logicDigest, description: a.description,
     prerequisites: a.prerequisites.map((id) => ({ id, description: PREREQUISITES[id].description })),
-    platforms: a.platforms, budgets: a.budgets,
+    platforms: a.platforms, budgets: a.budgets, requiresFeature: a.requiresFeature ?? null,
     negativeControls: a.negativeControls, fixtures: a.fixtures, limitations: a.limitations,
     receipts: 'issued by the verifier domain only (runOracle); a caller-supplied receipt is not valid',
   };

package/src/posture/portfolio/backend.js

@@ -0,0 +1,279 @@
+// Pluggable storage backends and offline operation for portfolios (X-708.AC02, X-708.AC03).
+//
+// Everything in the portfolio works with no hosted service: state is plain files, written atomically, readable with the standard
+// library. This module adds the one thing a single store file cannot give, a defined way to run it from SEVERAL workers or hosts that
+// share a directory, and a defined answer when that directory is not there.
+//
+// THE BACKEND INTERFACE (what a replacement implements)
+//   kind                       'local-fs' | 'shared-dir' (a label that appears in every report)
+//   describe()                 { kind, root, consistency } and what the backend does NOT claim
+//   probe()                    { ok: true } or { ok: false, state: 'blocked', code, reason }; never throws, never creates anything
+//   storeFile(name)            the path of a named document, for the portfolio store and ledger
+//   withExclusive(name, fn)    run `fn` while holding a cross-process lock; throws BACKEND_UNAVAILABLE if the backend went away
+//   acquireLease / renewLease / releaseLease / readLease
+//                              a named, expiring, FENCED lease (below)
+//
+// REFERENCE IMPLEMENTATION. `FileLockBackend` uses exclusive file creation (`open(..., 'wx')`) in a directory. `createLocalBackend`
+// makes the directory if needed (single user, durable restart). `createSharedBackend` will NOT: it requires a marker file written by
+// an explicit `initSharedBackend`, so an unmounted path, a mistyped path or an empty mount point is a typed `blocked`, never a quietly
+// fresh store.
+//
+// LEASE SEMANTICS (each tested, including two real processes contending):
+//   - mutual exclusion: at most one holder has an unexpired lease on a resource at a time;
+//   - fencing: every grant increments a `fence` number that never goes down (a release keeps it). A holder presents its fence on
+//     renew and release, so a holder that was replaced after its lease expired is refused and learns it lost the lease (`lost`);
+//   - expiry takeover: an expired lease can be taken by anyone; the previous holder's renew then fails;
+//   - release by anyone but the holder, or with a stale fence, is refused.
+//
+// WHAT IS NOT CLAIMED. These semantics were verified on one machine's local filesystem, with several processes. Exclusive file
+// creation is atomic on a local POSIX filesystem; whether it is atomic on a particular network filesystem depends on that filesystem
+// and its mount options, and this build has not tested any. A shared directory used from several HOSTS therefore needs the operator to
+// verify exclusive-create atomicity on that mount, and lease expiry compares wall clocks, so hosts' clocks must agree to well within a
+// lease. Stale-lock recovery (a holder that died inside a critical section) has a narrow window in which two recoverers can both
+// believe they broke the lock; critical sections here last milliseconds, and `lockStaleMs` is far above that. `networkFilesystem` is
+// reported `unverified` in `describe()`.
+//
+// UNAVAILABLE BACKEND. Selecting a shared backend that cannot be used returns `{ ok: false, state: 'blocked', code, reason }` from
+// `openBackend`, and there is no fallback argument: nothing here ever "degrades" to a local write. Callers must stop, not substitute.
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { digestOf } from '../assurance/identity.js';
+import { findSecret } from './bundle.js';
+import { verifyStore, typedError } from './work-units.js';
+import { ledgerPathFor, readLedger } from './scheduler.js';
+
+export const BACKEND_MARKER = '.agentic-security-backend.json';
+export const BACKEND_MARKER_SCHEMA = 'agentic-security/portfolio-backend-marker';
+export const STATE_EXPORT_SCHEMA = 'agentic-security/portfolio-state-export';
+export const BLOCK_CODES = Object.freeze(['backend-missing', 'backend-not-initialized', 'backend-not-a-directory', 'backend-symlink', 'backend-not-writable', 'backend-marker-invalid']);
+export const BACKEND_LIMITS = Object.freeze({ lockStaleMs: 30_000, lockWaitMs: 5000, maxLeaseMs: 6 * 60 * 60_000, maxExportBytes: 64 * 1024 * 1024 });
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+const unavailable = (probe) => typedError('BACKEND_UNAVAILABLE', `the portfolio backend is unavailable (${probe.code}): ${probe.reason}`, { state: 'blocked', probe });
+
+/** The reference backend: exclusive-create file locks in a directory. */
+export class FileLockBackend {
+  constructor({ kind, root, requireMarker, lockStaleMs = BACKEND_LIMITS.lockStaleMs, lockWaitMs = BACKEND_LIMITS.lockWaitMs, nodeId = null }) {
+    this.kind = kind; this.root = path.resolve(root); this.requireMarker = requireMarker;
+    this.lockStaleMs = lockStaleMs; this.lockWaitMs = lockWaitMs;
+    this.nodeId = nodeId ?? `${os.hostname()}:${process.pid}`;
+  }
+
+  describe() {
+    return {
+      kind: this.kind, root: this.root, requiresMarker: this.requireMarker,
+      consistency: {
+        mutualExclusion: 'verified for processes sharing one local filesystem (two-process contention test)',
+        fencing: 'monotonic per resource; a stale holder is refused on renew and release',
+        networkFilesystem: 'unverified',
+        clocks: 'lease expiry compares wall clocks; hosts sharing a directory must agree to well within a lease',
+        staleLockRecovery: `a lock file older than ${this.lockStaleMs} ms is treated as abandoned; the recovery has a narrow race and is not a substitute for short critical sections`,
+      },
+    };
+  }
+
+  probe() {
+    let st;
+    try { st = fs.lstatSync(this.root); } catch { return { ok: false, state: 'blocked', code: 'backend-missing', reason: `${this.kind} backend directory does not exist or cannot be read` }; }
+    if (st.isSymbolicLink()) return { ok: false, state: 'blocked', code: 'backend-symlink', reason: 'the backend directory is a symbolic link; it is not followed' };
+    if (!st.isDirectory()) return { ok: false, state: 'blocked', code: 'backend-not-a-directory', reason: 'the backend path is not a directory' };
+    if (this.requireMarker) {
+      let m;
+      try { m = JSON.parse(fs.readFileSync(path.join(this.root, BACKEND_MARKER), 'utf8')); } catch (e) {
+        return { ok: false, state: 'blocked', code: e.code === 'ENOENT' ? 'backend-not-initialized' : 'backend-marker-invalid', reason: e.code === 'ENOENT' ? 'the shared directory has no backend marker: it is not initialized (an unmounted or empty directory is not a store)' : 'the backend marker is unreadable' };
+      }
+      if (m?.schema !== BACKEND_MARKER_SCHEMA || m.kind !== this.kind) return { ok: false, state: 'blocked', code: 'backend-marker-invalid', reason: 'the backend marker does not describe this kind of backend' };
+    }
+    try {
+      const probeFile = path.join(this.root, `.probe-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+      fs.writeFileSync(probeFile, '', { flag: 'wx' }); fs.unlinkSync(probeFile);
+    } catch { return { ok: false, state: 'blocked', code: 'backend-not-writable', reason: 'the backend directory is not writable' }; }
+    return { ok: true };
+  }
+
+  storeFile(name = 'portfolio-store.json') {
+    if (!NAME_RE.test(name)) throw typedError('BAD_NAME', `'${name}' is not an allowed document name`);
+    return path.join(this.root, name);
+  }
+
+  _lockPath(name) {
+    if (!NAME_RE.test(name)) throw typedError('BAD_NAME', `'${name}' is not an allowed lock name`);
+    return path.join(this.root, '.locks', `${name}.lock`);
+  }
+
+  /** Run `fn` under the named cross-process lock. The backend is re-probed first: a backend that went away is an error, not an empty store. */
+  withExclusive(name, fn, { waitMs = this.lockWaitMs } = {}) {
+    const p = this.probe();
+    if (!p.ok) throw unavailable(p);
+    const lock = this._lockPath(name);
+    fs.mkdirSync(path.dirname(lock), { recursive: true });
+    const token = crypto.randomBytes(12).toString('hex');
+    const body = JSON.stringify({ token, node: this.nodeId, pid: process.pid });
+    const start = Date.now();
+    for (;;) {
+      try { fs.writeFileSync(lock, body, { flag: 'wx' }); break; } catch (e) {
+        if (e.code !== 'EEXIST') throw e;
+        this._breakIfStale(lock);
+        if (Date.now() - start > waitMs) throw typedError('LOCK_TIMEOUT', `could not take lock '${name}' within ${waitMs} ms`);
+        sleepSync(3);
+      }
+    }
+    try { return fn(); } finally {
+      // release only OUR lock: if it was recovered as stale and re-taken, the file belongs to someone else now
+      try { if (JSON.parse(fs.readFileSync(lock, 'utf8')).token === token) fs.unlinkSync(lock); } catch { /* already gone */ }
+    }
+  }
+
+  _breakIfStale(lock) {
+    let st; let seen;
+    try { st = fs.statSync(lock); seen = JSON.parse(fs.readFileSync(lock, 'utf8')).token; } catch { return; }
+    if (Date.now() - st.mtimeMs <= this.lockStaleMs) return;
+    const grave = `${lock}.broken-${process.pid}-${crypto.randomBytes(3).toString('hex')}`;
+    try { fs.renameSync(lock, grave); } catch { return; }
+    let got = null;
+    try { got = JSON.parse(fs.readFileSync(grave, 'utf8')).token; } catch { /* unreadable: treated as the stale one */ }
+    if (got !== null && got !== seen) { try { fs.linkSync(grave, lock); } catch { /* the lock was re-taken meanwhile: the documented narrow race */ } }
+    try { fs.unlinkSync(grave); } catch { /* ignore */ }
+  }
+
+  _leaseFile(resource) {
+    if (!NAME_RE.test(resource)) throw typedError('BAD_NAME', `'${resource}' is not an allowed lease name`);
+    return path.join(this.root, 'leases', `${resource}.json`);
+  }
+
+  _readLease(resource) {
+    try { return JSON.parse(fs.readFileSync(this._leaseFile(resource), 'utf8')); } catch (e) { if (e.code === 'ENOENT') return null; throw typedError('LEASE_CORRUPT', `lease '${resource}' is unreadable`); }
+  }
+
+  _writeLease(resource, doc) {
+    const file = this._leaseFile(resource);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(doc), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+  }
+
+  readLease(resource) { return this.withExclusive(`lease-${resource}`, () => this._readLease(resource)); }
+
+  acquireLease(resource, { holder, ttlMs, now }) {
+    if (typeof holder !== 'string' || !holder) throw typedError('BAD_HOLDER', 'a lease needs a holder');
+    if (!(Number.isFinite(ttlMs) && ttlMs >= 1) || !Number.isFinite(now)) throw typedError('BAD_LEASE', 'a lease needs a positive ttlMs and a now');
+    const ttl = Math.min(ttlMs, BACKEND_LIMITS.maxLeaseMs);
+    return this.withExclusive(`lease-${resource}`, () => {
+      const cur = this._readLease(resource);
+      if (cur && cur.holder && cur.expiresAt > now) return { ok: false, code: 'held', heldBy: cur.holder, expiresAt: cur.expiresAt, fence: cur.fence };
+      const fence = (cur?.fence ?? 0) + 1;
+      const doc = { resource, holder, fence, expiresAt: now + ttl, acquiredAt: now, node: this.nodeId };
+      this._writeLease(resource, doc);
+      return { ok: true, fence, expiresAt: doc.expiresAt, takenOver: !!(cur && cur.holder) };
+    });
+  }
+
+  renewLease(resource, { holder, fence, ttlMs, now }) {
+    const ttl = Math.min(ttlMs, BACKEND_LIMITS.maxLeaseMs);
+    return this.withExclusive(`lease-${resource}`, () => {
+      const cur = this._readLease(resource);
+      if (!cur || cur.holder !== holder || cur.fence !== fence) return { ok: false, code: 'lost', reason: 'the lease is held by another holder or generation' };
+      if (cur.expiresAt <= now) return { ok: false, code: 'expired', reason: 'the lease expired; it must be acquired again' };
+      cur.expiresAt = now + ttl;
+      this._writeLease(resource, cur);
+      return { ok: true, fence, expiresAt: cur.expiresAt };
+    });
+  }
+
+  releaseLease(resource, { holder, fence }) {
+    return this.withExclusive(`lease-${resource}`, () => {
+      const cur = this._readLease(resource);
+      if (!cur || cur.holder !== holder || cur.fence !== fence) return { ok: false, code: 'not-holder', reason: 'only the current holder, with its fence, can release' };
+      this._writeLease(resource, { resource, holder: null, fence: cur.fence, expiresAt: 0, node: this.nodeId });
+      return { ok: true };
+    });
+  }
+}
+
+/** Create the marker that makes a directory a shared backend. An explicit operator act; `openBackend` never does it. */
+export function initSharedBackend(dir, { id = crypto.randomBytes(8).toString('hex') } = {}) {
+  const root = path.resolve(dir);
+  fs.mkdirSync(root, { recursive: true });
+  const marker = path.join(root, BACKEND_MARKER);
+  if (fs.existsSync(marker)) return { ok: true, created: false };
+  fs.writeFileSync(marker, JSON.stringify({ schema: BACKEND_MARKER_SCHEMA, kind: 'shared-dir', id }), { flag: 'wx' });
+  return { ok: true, created: true };
+}
+
+export const createLocalBackend = (dir, o = {}) => { fs.mkdirSync(path.resolve(dir), { recursive: true }); return new FileLockBackend({ kind: 'local-fs', root: dir, requireMarker: false, ...o }); };
+export const createSharedBackend = (dir, o = {}) => new FileLockBackend({ kind: 'shared-dir', root: dir, requireMarker: true, ...o });
+
+/**
+ * Select a backend. `mode` is 'local' or 'shared'. A shared backend that is not usable returns `{ ok: false, state: 'blocked', ... }`;
+ * there is no fallback to the local backend, by design.
+ */
+export function openBackend({ mode, dir }) {
+  if (mode !== 'local' && mode !== 'shared') return { ok: false, state: 'blocked', code: 'invalid-mode', reason: "mode must be 'local' or 'shared'" };
+  if (typeof dir !== 'string' || !dir) return { ok: false, state: 'blocked', code: 'backend-missing', reason: 'a backend directory is required' };
+  const backend = mode === 'local' ? createLocalBackend(dir) : createSharedBackend(dir);
+  const p = backend.probe();
+  return p.ok ? { ok: true, backend } : p;
+}
+
+// ---------------------------------------------------------------- offline export and import
+
+/**
+ * A single self-checking file holding the portfolio store and ledger (and optionally the deletion log), for moving state to an
+ * air-gapped machine or archiving it. Reads nothing from the network. Refused if the store fails verification or any text in it has a
+ * secret shape.
+ */
+export function exportState({ storeFile, outFile, retentionLog = null, now }) {
+  const storeText = fs.readFileSync(storeFile, 'utf8');
+  if (storeText.length > BACKEND_LIMITS.maxExportBytes) throw typedError('EXPORT_TOO_LARGE', 'the store is larger than the export limit');
+  const store = JSON.parse(storeText);
+  const v = verifyStore(store);
+  if (!v.ok) throw typedError('STORE_CORRUPT', `refusing to export a store that fails verification: ${v.errors[0].code}`);
+  const ledger = readLedger(storeFile);
+  const log = retentionLog && fs.existsSync(retentionLog) ? fs.readFileSync(retentionLog, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)) : [];
+  const body = { schema: STATE_EXPORT_SCHEMA, version: 1, ...(store.synthetic ? { synthetic: true } : {}), exportedAtMs: now, store, ledger, retentionLog: log };
+  const secret = findSecret(JSON.stringify(body));
+  if (secret) throw typedError('SECRET_IN_EXPORT', `the state contains a secret-shaped string (${secret}); it was not exported`);
+  const doc = { ...body, digest: digestOf(body) };
+  fs.mkdirSync(path.dirname(path.resolve(outFile)), { recursive: true });
+  const tmp = `${outFile}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(doc), { mode: 0o600 });
+  fs.renameSync(tmp, outFile);
+  return { ok: true, digest: doc.digest, units: Object.keys(store.units).length };
+}
+
+/** Offline verification of an export: re-derives its digest and verifies the store inside. Executes nothing. */
+export function verifyStateExport(file) {
+  let doc;
+  try {
+    const st = fs.lstatSync(file);
+    if (st.isSymbolicLink() || !st.isFile() || st.size > BACKEND_LIMITS.maxExportBytes) return { ok: false, code: 'BAD_FILE', reason: 'not a regular file within the size limit' };
+    doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch { return { ok: false, code: 'BAD_FILE', reason: 'unreadable or not JSON' }; }
+  if (doc?.schema !== STATE_EXPORT_SCHEMA || doc.version !== 1) return { ok: false, code: 'BAD_SCHEMA', reason: 'not a portfolio state export of a supported version' };
+  const { digest, ...body } = doc;
+  if (digestOf(body) !== digest) return { ok: false, code: 'DIGEST_MISMATCH', reason: 'the export was modified after it was written' };
+  const v = verifyStore(doc.store);
+  if (!v.ok) return { ok: false, code: 'STORE_INVALID', reason: `the store inside fails verification: ${v.errors[0].code}` };
+  return { ok: true, doc };
+}
+
+/** Import into a backend that holds no portfolio store yet. Verifies first; never overwrites. */
+export function importState({ from, backend, name = 'portfolio-store.json' }) {
+  const p = backend.probe();
+  if (!p.ok) return p;
+  const v = verifyStateExport(from);
+  if (!v.ok) return { ok: false, state: 'rejected', code: v.code, reason: v.reason };
+  const file = backend.storeFile(name);
+  return backend.withExclusive('import', () => {
+    if (fs.existsSync(file)) return { ok: false, state: 'rejected', code: 'WOULD_OVERWRITE', reason: 'the backend already holds a portfolio store; import never overwrites' };
+    fs.writeFileSync(file, JSON.stringify(v.doc.store), { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(ledgerPathFor(file), JSON.stringify(v.doc.ledger), { flag: 'wx', mode: 0o600 });
+    return { ok: true, file, units: Object.keys(v.doc.store.units).length };
+  });
+}
+