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

package/src/posture/oracles/scenario-classes.js

@@ -0,0 +1,223 @@
+// Non-taint vulnerability classes and the rules for judging them (X-205).
+//
+// A taint engine answers "does attacker data reach a dangerous call". Several
+// defect classes have no such flow: a missing tenant check, a privileged action
+// open to a lower role, a workflow step that can be skipped, a request whose
+// effect repeats when it is delivered again, an unbounded work parameter. A
+// source-to-sink analysis finding nothing says NOTHING about them, so this module
+// states three things, each with a test:
+//
+//   1. WHICH classes are supported (`SCENARIO_CLASSES`), and for each one the
+//      adapter that executes it, what the requester must supply, the fixtures that
+//      prove it works in both directions, and the limitations a reader must see.
+//      Where an existing adapter already covers a class it is REUSED, and the
+//      entry says so (`adapterReuse`); only replay/idempotency needed a new one.
+//   2. That taint absence NEVER refutes one of these hypotheses
+//      (`judgeNonTaintHypothesis`): without an executed oracle of the class's own
+//      adapter the outcome is `not-run`, never `refuted`.
+//   3. Which results may count as a trusted negative (`trustedNegativeDenominator`):
+//      only a decided result from an executed oracle with proven preconditions.
+//      Unsupported, not-run, inconclusive, error, static-only and model-only results
+//      are listed explicitly and excluded; they cannot be counted as "checked and
+//      clean".
+//
+// This module is pure data and pure functions: it imports no adapter and runs
+// nothing, so `oracle.js` and `registry.js` can both depend on it.
+
+export const NON_TAINT_SCHEMA = 'agentic-security/non-taint-classes';
+
+const FIXTURE_ROOT = 'test/fixtures/non-taint';
+
+export const SCENARIO_CLASSES = Object.freeze([
+  Object.freeze({
+    id: 'tenant-authorization',
+    title: 'Tenant authorization',
+    adapterId: 'authorization-decision', adapterReuse: true,
+    claim: 'an actor from one tenant is allowed to read or change another tenant\'s resource',
+    cwes: ['CWE-639', 'CWE-566', 'CWE-863', 'CWE-862', 'CWE-285', 'CWE-284'],
+    families: ['idor', 'authz', 'missing-authz', 'broken-access-control', 'tenant-isolation'],
+    requires: ['an exported decision function taking the actor and the resource (or ids that resolve to them)', 'one control case the function must allow (the owner) and one attack case it must deny (another tenant)'],
+    limitations: ['asserts the decision function in isolation; a route or middleware that enforces the check elsewhere is not exercised', 'the scenario names which actors should be denied: the oracle does not infer tenancy rules', 'row-level checks inside a database query are not observed'],
+    fixtures: { dir: `${FIXTURE_ROOT}/tenant-authorization`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+  Object.freeze({
+    id: 'privileged-action',
+    title: 'Privileged action',
+    adapterId: 'authorization-decision', adapterReuse: true,
+    claim: 'a lower-privileged actor is allowed to perform an action reserved for a higher role',
+    cwes: ['CWE-269', 'CWE-250', 'CWE-266', 'CWE-267'],
+    families: ['privilege-escalation', 'privileged-action', 'missing-role-check'],
+    requires: ['an exported decision function taking the actor and the action', 'one control case with the privileged role (must be allowed) and one attack case with an ordinary role (must be denied)'],
+    limitations: ['asserts the decision function in isolation; role checks enforced only by a gateway or framework guard are not exercised', 'a thrown error is not read as a denial', 'role and permission grants stored outside the function are not observed'],
+    fixtures: { dir: `${FIXTURE_ROOT}/privileged-action`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+  Object.freeze({
+    id: 'workflow-order',
+    title: 'Workflow order',
+    adapterId: 'state-transition', adapterReuse: true,
+    claim: 'a step that must follow another can be performed first (for example a refund before approval)',
+    cwes: ['CWE-841', 'CWE-840', 'CWE-696'],
+    families: ['workflow', 'business-logic', 'state-machine', 'workflow-order'],
+    requires: ['an exported factory returning a machine with `send(event)` and a `state`', 'a legal event sequence with its expected final state, an attack sequence and the forbidden state'],
+    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: business rules are not inferred'],
+    fixtures: { dir: `${FIXTURE_ROOT}/workflow-order`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+  Object.freeze({
+    id: 'replay-idempotency',
+    title: 'Replay and idempotency',
+    adapterId: 'replay-idempotency', adapterReuse: false,
+    claim: 'delivering the same request again repeats its side effect (a double charge, a double credit)',
+    cwes: ['CWE-294', 'CWE-837', 'CWE-841'],
+    families: ['replay', 'idempotency', 'replay-attack', 'duplicate-submission'],
+    requires: ['an exported factory that receives a recording stand-in for the effect and returns a request handler', 'a request, a distinct request and a delivery count'],
+    limitations: ['deliveries are sequential: a race between concurrent deliveries is not exercised', 'deduplication kept in an external store is not observed, only the handler the factory returns', 'code that imports its effect directly instead of receiving it is not covered'],
+    fixtures: { dir: `${FIXTURE_ROOT}/replay-idempotency`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+  Object.freeze({
+    id: 'resource-exhaustion',
+    title: 'Bounded resource exhaustion',
+    adapterId: 'parser-resource', adapterReuse: true,
+    claim: 'a bounded hostile parameter makes the code exceed its time or output budget (an uncapped page size, an unbounded loop)',
+    cwes: ['CWE-400', 'CWE-770', 'CWE-789', 'CWE-405', 'CWE-834'],
+    families: ['resource-exhaustion', 'dos', 'denial-of-service', 'unbounded-loop'],
+    requires: ['an exported function taking one string', 'a benign input it must finish and a hostile input described as a unit repeated at most 65536 times'],
+    limitations: ['the hostile input is bounded and the run is cut at the supervisor deadline: this shows a budget was exceeded, not how large the blow-up is', 'memory is not measured', 'distributed or network-level exhaustion, and exhaustion that needs a populated datastore, are not exercised'],
+    fixtures: { dir: `${FIXTURE_ROOT}/resource-exhaustion`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+]);
+
+// Non-taint classes this build recognises and does NOT execute. A finding that maps here is `unsupported`,
+// stated by name, and never counted as checked.
+export const UNSUPPORTED_NON_TAINT = Object.freeze([
+  Object.freeze({ id: 'concurrent-race', cwes: ['CWE-362', 'CWE-367'], reason: 'a race needs concurrent scheduling; the adapters deliver sequentially, so no verdict about a race can be formed' }),
+  Object.freeze({ id: 'cross-site-request-forgery', cwes: ['CWE-352'], reason: 'needs a browser and a session; no adapter exercises one' }),
+  Object.freeze({ id: 'authentication-throttling', cwes: ['CWE-307', 'CWE-799'], reason: 'needs a stateful attempt counter over time and a populated store; the adapters bound a single input, not a campaign' }),
+]);
+
+const BY_ID = new Map(SCENARIO_CLASSES.map((c) => [c.id, c]));
+
+export function scenarioClassesForAdapter(adapterId) { return SCENARIO_CLASSES.filter((c) => c.adapterId === adapterId); }
+
+/**
+ * The lines a user reads about one class: what it asserts, what the requester must supply (prerequisites), the platform
+ * statement and every limitation. A report that shows a class shows these with it.
+ * @param {object} cls  a SCENARIO_CLASSES entry
+ * @param {object} [adapter] the executing adapter (prerequisites and platform statements are taken from it)
+ */
+export function scenarioClassReportLines(cls, adapter = null) {
+  const lines = [`${cls.title} (${cls.id}): ${cls.claim}.`];
+  lines.push(`  oracle: ${cls.adapterId}${cls.adapterReuse ? ' (an existing adapter, reused for this class)' : ' (added for this class)'}`);
+  lines.push(`  prerequisites: ${[...cls.requires, ...(adapter ? adapter.prerequisites.map((p) => `host: ${p}`) : [])].join('; ')}`);
+  if (adapter) lines.push(`  platforms: macOS ${adapter.platforms.darwin.status}, Linux ${adapter.platforms.linux.status}, Windows ${adapter.platforms.win32.status}`);
+  for (const l of cls.limitations) lines.push(`  limitation: ${l}`);
+  lines.push('  not established: a clean result covers only the declared scenario; it is not proof the class is absent from the code.');
+  return lines;
+}
+
+// ------------------------------------------------------------------ classification
+
+const cweOf = (f) => String(f?.cwe || '').toUpperCase().replace(/^CWE[-_ ]?/, 'CWE-');
+const familyOf = (f) => String(f?.family || '').toLowerCase();
+
+/**
+ * Which non-taint class, supported or not, does this finding belong to? `null` when it is not a recognised non-taint
+ * hypothesis (then nothing in this module applies). An explicit `finding.scenarioClass` wins over CWE and family.
+ * @returns {null | { classId: string, supported: boolean, title: string, reason?: string }}
+ */
+export function nonTaintClassOf(finding) {
+  if (!finding || typeof finding !== 'object') return null;
+  if (typeof finding.scenarioClass === 'string') {
+    const c = BY_ID.get(finding.scenarioClass);
+    if (c) return { classId: c.id, supported: true, title: c.title };
+  }
+  const cwe = cweOf(finding);
+  const fam = familyOf(finding);
+  for (const u of UNSUPPORTED_NON_TAINT) {
+    if (u.cwes.includes(cwe) || fam === u.id) return { classId: u.id, supported: false, title: u.id.replace(/-/g, ' '), reason: u.reason };
+  }
+  for (const c of SCENARIO_CLASSES) {
+    if (c.cwes.includes(cwe) || c.families.includes(fam)) return { classId: c.id, supported: true, title: c.title };
+  }
+  return null;
+}
+
+// ------------------------------------------------------------------ judging a non-taint hypothesis
+
+/**
+ * Judge a non-taint hypothesis from what is actually known about it.
+ *
+ * The rule: absence of a taint flow is not evidence about these classes, so it is never an input to a refutation. An
+ * outcome of `refuted` needs an EXECUTED oracle result from the class's own adapter with proven preconditions; anything
+ * else is `not-run` (a supported class nobody ran), `unsupported` (a class this build cannot execute) or the oracle's own
+ * `confirmed`/`inconclusive`/`error`.
+ *
+ * @param {object} args
+ * @param {object} args.finding
+ * @param {object} [args.taint]        static taint evidence, for example `{ clean: true }`; recorded, never used to refute
+ * @param {object} [args.oracleResult] `{ outcome, oracleId, preconditionsValid }` from a run of an oracle adapter
+ * @returns {{ nonTaint: boolean, classId?: string, supported?: boolean, outcome?: string, reason?: string, taintAbsenceUsed: false }}
+ */
+export function judgeNonTaintHypothesis({ finding, taint = null, oracleResult = null } = {}) {
+  const cls = nonTaintClassOf(finding);
+  if (!cls) return { nonTaint: false, taintAbsenceUsed: false };
+  const taintNote = taint && taint.clean === true
+    ? ' No source-to-sink flow was found, and that says nothing about this class: it is not a refutation.'
+    : '';
+  if (!cls.supported) {
+    return { nonTaint: true, classId: cls.classId, supported: false, outcome: 'unsupported', taintAbsenceUsed: false,
+      reason: `${cls.title} is a non-taint class this build does not execute: ${cls.reason}.${taintNote}` };
+  }
+  const own = BY_ID.get(cls.classId);
+  const r = oracleResult && typeof oracleResult === 'object' ? oracleResult : null;
+  const decisive = r && r.oracleId === own.adapterId && ['confirmed', 'refuted', 'inconclusive', 'error'].includes(r.outcome);
+  if (!decisive) {
+    return { nonTaint: true, classId: cls.classId, supported: true, outcome: 'not-run', taintAbsenceUsed: false,
+      reason: `no executed ${own.adapterId} oracle result exists for this ${cls.title.toLowerCase()} hypothesis, so it stays unrefuted.${taintNote}` };
+  }
+  if (r.outcome === 'refuted' && r.preconditionsValid !== true) {
+    return { nonTaint: true, classId: cls.classId, supported: true, outcome: 'inconclusive', taintAbsenceUsed: false,
+      reason: `the ${own.adapterId} oracle did not show its preconditions held, so its negative result is not a refutation.${taintNote}` };
+  }
+  return { nonTaint: true, classId: cls.classId, supported: true, outcome: r.outcome, taintAbsenceUsed: false,
+    reason: `decided by the executed ${own.adapterId} oracle.${taintNote}` };
+}
+
+// ------------------------------------------------------------------ the trusted-negative denominator
+
+const ORACLE_IDS = new Set(SCENARIO_CLASSES.map((c) => c.adapterId));
+
+function whyExcluded(rec) {
+  if (!rec || typeof rec !== 'object') return 'malformed';
+  if (rec.outcome === 'unsupported') return 'unsupported';
+  if (rec.outcome === 'not-run') return 'not-run';
+  if (rec.outcome === 'inconclusive') return 'inconclusive';
+  if (rec.outcome === 'error') return 'error';
+  if (rec.outcome !== 'confirmed' && rec.outcome !== 'refuted') return 'not-decided';
+  if (!rec.oracle || rec.oracle.kind !== 'runtime-replay') return 'no-executed-oracle';
+  if (!ORACLE_IDS.has(rec.oracle.id)) return 'oracle-not-in-supported-class-manifest';
+  if (!rec.preconditions || rec.preconditions.valid !== true) return 'preconditions-not-proved';
+  if (!Array.isArray(rec.evidence) || !rec.evidence.some((e) => e && e.kind === 'trusted-runtime-proof')) return 'no-trusted-runtime-proof';
+  return null;
+}
+
+/**
+ * The trusted-negative denominator over verification records: the decided results (`confirmed` or `refuted`) of an
+ * executed oracle of an advertised class with proven preconditions and trusted runtime proof. Everything else is listed
+ * with the reason it is excluded; an unsupported or unrun case can never be counted as a negative.
+ */
+export function trustedNegativeDenominator(records) {
+  const list = Array.isArray(records) ? records : [];
+  let trustedNegatives = 0;
+  let trustedPositives = 0;
+  const excluded = [];
+  for (const rec of list) {
+    const why = whyExcluded(rec);
+    if (why) { excluded.push({ id: rec && rec.id ? String(rec.id) : null, outcome: rec && rec.outcome ? String(rec.outcome) : null, reason: why }); continue; }
+    if (rec.outcome === 'refuted') trustedNegatives++; else trustedPositives++;
+  }
+  return {
+    denominator: trustedNegatives + trustedPositives, trustedNegatives, trustedPositives,
+    excluded, unsupported: excluded.filter((e) => e.reason === 'unsupported'),
+    total: list.length,
+  };
+}

package/src/posture/replay/replay.js

@@ -0,0 +1,249 @@
+// Replay manifests and environment identity (X-203).
+//
+// Extends the existing proof-of-concept sandbox path (a payload run under the
+// confinement backend, judged by an observed effect) with an identity for the run
+// and a way to repeat it. It is NOT a second sandbox or a second runner: a replay
+// is an oracle run (`oracles/oracle.js`), which goes through `runInBoundary` and
+// therefore through the supervised process tree, output cap and cleanup of
+// CORE-003. What this module adds is the pinned, validated description of the run.
+//
+// A manifest pins: the repository commit, the patch hash, the fixture hash, the
+// toolchain (and container digest when there is one), the oracle id, version and
+// logic digest, the inputs and the budgets. Replaying it on the same supported
+// environment reproduces the verdict, and the identical verification record id.
+//
+// Honesty rules, each with a test:
+//   - A manifest is REJECTED, and nothing executes, when a content hash does not
+//     match the content, when the oracle changed since the manifest was made, when
+//     its scope asks for more than the oracle's declared scope (network, another
+//     oracle, a write outside the workspace) or when a budget exceeds the oracle's
+//     ceiling. The manifest is closed-world, so a field such as a model verdict
+//     cannot ride along.
+//   - A missing toolchain, container image or container runtime, or a disabled
+//     feature, is a typed PREREQUISITE and the attempt is resumable. Nothing is
+//     substituted for the execution that did not happen: the outcome is `not-run`
+//     (or `unsupported` when this build can never meet it), with no evidence.
+//   - This build never fetches anything. A prerequisite whose acquisition would
+//     need the network is reported as such, with the network denied.
+//   - Container execution is not implemented. A manifest pinning a container
+//     digest is therefore `unsupported` here, never run outside the container it
+//     names.
+//   - Toolchain identity is exact (runtime version, platform, architecture). A
+//     different patch release is a different environment, reported as an unmet
+//     prerequisite rather than silently tolerated.
+import { digestOf, semanticId } from '../assurance/identity.js';
+import { SCHEMA_VERSION, isCommit, isDigest, isPlainObject } from '../assurance/schema-kit.js';
+import { detectBackend } from '../../sandbox/capabilities.js';
+import { runOracle, recordWithoutExecution, isSafeRelativePath, FEATURE_ID } from '../oracles/oracle.js';
+import * as registry from '../oracles/registry.js';
+
+export const REPLAY_SCHEMA = 'agentic-security/replay-manifest';
+export const ATTEMPT_SCHEMA = 'agentic-security/replay-attempt';
+export const MAX_ATTEMPTS = 10;
+
+const ALLOWED = ['schema', 'schemaVersion', 'id', 'hypothesisId', 'repository', 'patch', 'fixture', 'toolchain', 'oracle', 'entry', 'inputs', 'inputsDigest', 'budgets', 'scope', 'expected'];
+const REQUIRED = ['schema', 'schemaVersion', 'id', 'hypothesisId', 'repository', 'patch', 'fixture', 'toolchain', 'oracle', 'entry', 'inputs', 'inputsDigest', 'budgets', 'scope'];
+const ID_FIELDS = ALLOWED.filter((k) => k !== 'id');
+const REPLAY_BUDGET_KEYS = ['timeoutMs', 'graceMs', 'maxOutputBytes'];
+const EXPECTED_OUTCOMES = ['confirmed', 'refuted', 'inconclusive'];
+
+/** The pinned scope a replay may have: exactly the oracle it names, no network, workspace-only writes. */
+export function allowedScope(oracleId) {
+  return { executes: [oracleId], network: false, writes: 'workspace-only' };
+}
+
+/** Sanitized identity of the execution environment: facts about the toolchain, nothing about the host. */
+export function environmentIdentity(overrides = {}) {
+  const base = {
+    runtime: 'node', version: process.versions.node, platform: process.platform, arch: process.arch,
+    containerDigest: null, backend: detectBackend(),
+  };
+  const env = { ...base, ...overrides };
+  return { ...env, toolchainDigest: digestOf({ runtime: env.runtime, version: env.version, platform: env.platform, arch: env.arch, containerDigest: env.containerDigest }) };
+}
+
+/**
+ * Build a manifest from the pieces of a verification. The oracle identity and the
+ * environment come from this build, not from the caller.
+ */
+export function createReplayManifest({ hypothesisId, commit, fixtureFiles, patchFiles = null, oracleId, entry, inputs, budgets = {}, expected, environment }) {
+  const oracle = registry.getOracle(oracleId);
+  if (!oracle) throw new Error(`unknown oracle '${oracleId}'`);
+  const env = environment || environmentIdentity();
+  const m = {
+    schema: REPLAY_SCHEMA, schemaVersion: SCHEMA_VERSION, hypothesisId,
+    repository: { commit },
+    patch: patchFiles && Object.keys(patchFiles).length ? { digest: digestOf(patchFiles) } : null,
+    fixture: { digest: digestOf(fixtureFiles) },
+    toolchain: { runtime: env.runtime, version: env.version, platform: env.platform, arch: env.arch, containerDigest: env.containerDigest ?? null },
+    oracle: { id: oracle.id, version: oracle.version, logicDigest: oracle.logicDigest },
+    entry, inputs, inputsDigest: digestOf(inputs),
+    budgets: { timeoutMs: oracle.budgets.timeoutMs, graceMs: oracle.budgets.graceMs, maxOutputBytes: oracle.budgets.maxOutputBytes, ...budgets },
+    scope: allowedScope(oracle.id),
+  };
+  if (expected) m.expected = expected;
+  m.id = manifestId(m);
+  return m;
+}
+
+export function manifestId(m) { return semanticId('rpl', m, ID_FIELDS); }
+
+function err(errors, code, path, message) { errors.push({ code, path, message }); }
+
+/**
+ * Validate a manifest against the content it describes. Rejects, and the caller
+ * must not execute, on any error. Pure: reads no file and runs nothing.
+ */
+export function validateReplayManifest(m, { fixtureFiles, patchFiles = null } = {}) {
+  const errors = [];
+  if (!isPlainObject(m)) { err(errors, 'NOT_AN_OBJECT', '', 'manifest must be an object'); return { ok: false, errors }; }
+  if (m.schema !== REPLAY_SCHEMA) { err(errors, 'SCHEMA_MISMATCH', 'schema', `expected '${REPLAY_SCHEMA}'`); return { ok: false, errors }; }
+  if (typeof m.schemaVersion !== 'string' || m.schemaVersion.split('.')[0] !== '1') { err(errors, 'UNSUPPORTED_MAJOR', 'schemaVersion', 'only major version 1 is supported'); return { ok: false, errors }; }
+  for (const k of Object.keys(m)) if (!ALLOWED.includes(k)) err(errors, 'UNKNOWN_FIELD', k, `field '${k}' is not part of a replay manifest`);
+  for (const k of REQUIRED) if (m[k] === undefined) err(errors, 'MISSING_FIELD', k, `required field '${k}' is missing`);
+  if (errors.length) return { ok: false, errors };
+
+  if (typeof m.hypothesisId !== 'string' || !m.hypothesisId) err(errors, 'BAD_TYPE', 'hypothesisId', 'must be a non-empty string');
+  if (!isPlainObject(m.repository) || !isCommit(m.repository.commit)) err(errors, 'BAD_COMMIT', 'repository.commit', 'a replay pins an exact 40 or 64 character commit');
+  if (!isPlainObject(m.fixture) || !isDigest(m.fixture.digest)) err(errors, 'BAD_DIGEST', 'fixture.digest', 'must be sha256:<64 hex>');
+  else if (!isPlainObject(fixtureFiles) || digestOf(fixtureFiles) !== m.fixture.digest) err(errors, 'HASH_MISMATCH', 'fixture.digest', 'the fixture content does not match its pinned hash');
+  const havePatch = isPlainObject(patchFiles) && Object.keys(patchFiles).length > 0;
+  if (m.patch === null) {
+    if (havePatch) err(errors, 'HASH_MISMATCH', 'patch', 'patch content was supplied but the manifest pins no patch');
+  } else if (!isPlainObject(m.patch) || !isDigest(m.patch.digest)) err(errors, 'BAD_DIGEST', 'patch.digest', 'must be null or { digest: sha256:<64 hex> }');
+  else if (!havePatch || digestOf(patchFiles) !== m.patch.digest) err(errors, 'HASH_MISMATCH', 'patch.digest', 'the patch content does not match its pinned hash');
+  if (!isDigest(m.inputsDigest) || !isPlainObject(m.inputs) || digestOf(m.inputs) !== m.inputsDigest) err(errors, 'HASH_MISMATCH', 'inputsDigest', 'the inputs do not match their pinned hash');
+
+  // Paths are part of the allowed execution scope: a fixture or patch that names a file outside the workspace is refused here,
+  // before anything can run, even when its hash matches.
+  for (const [label, files] of [['fixture', fixtureFiles], ['patch', patchFiles]]) {
+    for (const rel of Object.keys(isPlainObject(files) ? files : {})) {
+      if (!isSafeRelativePath(rel)) err(errors, 'SCOPE_VIOLATION', `${label}.files`, `path ${JSON.stringify(String(rel).slice(0, 60))} is not a safe relative path inside the workspace`);
+    }
+  }
+  if (typeof m.entry === 'string' && isPlainObject(fixtureFiles) && !(m.entry in { ...fixtureFiles, ...(isPlainObject(patchFiles) ? patchFiles : {}) })) err(errors, 'SCOPE_VIOLATION', 'entry', 'the entry must be one of the pinned files');
+
+  const tc = m.toolchain;
+  if (!isPlainObject(tc) || tc.runtime !== 'node' || typeof tc.version !== 'string' || typeof tc.platform !== 'string' || typeof tc.arch !== 'string') err(errors, 'BAD_TYPE', 'toolchain', 'needs runtime node, version, platform and arch');
+  else if (tc.containerDigest !== null && !isDigest(tc.containerDigest)) err(errors, 'BAD_DIGEST', 'toolchain.containerDigest', 'must be null or sha256:<64 hex>');
+
+  const oracle = isPlainObject(m.oracle) ? registry.getOracle(m.oracle.id) : null;
+  if (!oracle) err(errors, 'UNKNOWN_ORACLE', 'oracle.id', 'the manifest names an oracle this build does not have');
+  else {
+    if (m.oracle.version !== oracle.version || m.oracle.logicDigest !== oracle.logicDigest) err(errors, 'ORACLE_MISMATCH', 'oracle', 'the oracle version or logic digest differs from the pinned one: this is not the oracle the manifest was made with');
+    const sc = m.scope;
+    const want = allowedScope(oracle.id);
+    if (!isPlainObject(sc) || Object.keys(sc).some((k) => !(k in want))) err(errors, 'SCOPE_VIOLATION', 'scope', 'unknown scope keys');
+    else {
+      if (JSON.stringify(sc.executes) !== JSON.stringify(want.executes)) err(errors, 'SCOPE_VIOLATION', 'scope.executes', 'a replay may execute only the oracle it names');
+      if (sc.network !== false) err(errors, 'SCOPE_VIOLATION', 'scope.network', 'replay grants no network access');
+      if (sc.writes !== 'workspace-only') err(errors, 'SCOPE_VIOLATION', 'scope.writes', 'replay writes only inside its workspace');
+    }
+    const b = m.budgets;
+    if (!isPlainObject(b)) err(errors, 'BAD_TYPE', 'budgets', 'must be an object');
+    else {
+      for (const k of Object.keys(b)) if (!REPLAY_BUDGET_KEYS.includes(k)) err(errors, 'UNKNOWN_FIELD', `budgets.${k}`, 'not a replay budget');
+      for (const k of REPLAY_BUDGET_KEYS) {
+        if (!Number.isInteger(b[k]) || b[k] < 1) err(errors, 'BAD_TYPE', `budgets.${k}`, 'must be a positive integer');
+        else if (b[k] > oracle.budgets[k]) err(errors, 'BUDGET_EXCEEDED', `budgets.${k}`, `exceeds the oracle ceiling of ${oracle.budgets[k]}`);
+      }
+    }
+  }
+  if (typeof m.entry !== 'string' || !m.entry) err(errors, 'BAD_TYPE', 'entry', 'must be a non-empty string');
+  if (m.expected !== undefined && (!isPlainObject(m.expected) || Object.keys(m.expected).some((k) => k !== 'outcome') || !EXPECTED_OUTCOMES.includes(m.expected.outcome))) err(errors, 'BAD_TYPE', 'expected', `must be { outcome: one of ${EXPECTED_OUTCOMES.join(', ')} }`);
+  if (m.id !== manifestId(m)) err(errors, 'ID_MISMATCH', 'id', 'the manifest id does not match its content');
+  return { ok: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------- prerequisites
+
+/**
+ * Typed prerequisites that are not met on this host. `resumable` is true when
+ * meeting it is something an operator can do (install a toolchain, enable the
+ * feature) and false when this build cannot meet it at all.
+ */
+export function unmetPrerequisites(m, host = environmentIdentity()) {
+  const out = [];
+  const tc = m.toolchain;
+  if (tc.containerDigest !== null) {
+    out.push({ kind: 'container-runtime', id: tc.containerDigest, state: 'unsupported', resumable: false, reason: 'container execution is not implemented in this build; the run is never executed outside the container the manifest names' });
+    out.push({ kind: 'container-image', id: tc.containerDigest, state: 'missing', resumable: false, reason: 'this build neither holds nor pulls container images' });
+    out.push({ kind: 'network', id: 'image-acquisition', state: 'denied', resumable: false, reason: 'acquiring a container image needs network access, which replay does not grant' });
+  }
+  if (tc.version !== host.version || tc.platform !== host.platform || tc.arch !== host.arch) {
+    out.push({
+      kind: 'toolchain', id: `${tc.runtime}@${tc.version} ${tc.platform}/${tc.arch}`, state: 'missing', resumable: true,
+      reason: `this host runs ${host.runtime}@${host.version} ${host.platform}/${host.arch}; the manifest pins an exact toolchain`,
+    });
+    out.push({ kind: 'network', id: 'toolchain-acquisition', state: 'denied', resumable: true, reason: 'installing the pinned toolchain needs network access, which replay does not grant; install it out of band and resume' });
+  }
+  return out;
+}
+
+function nextAttempt(resume, manifestId_) {
+  if (resume === undefined || resume === null) return { n: 1, history: [] };
+  if (!isPlainObject(resume) || resume.schema !== ATTEMPT_SCHEMA || resume.manifestId !== manifestId_) return { error: 'the attempt does not belong to this manifest' };
+  if (resume.status !== 'awaiting-prerequisites') return { error: `an attempt in status '${resume.status}' is not resumable` };
+  if (!Number.isInteger(resume.attempt) || resume.attempt < 1 || !Array.isArray(resume.history)) return { error: 'the attempt record is malformed' };
+  if (resume.attempt >= MAX_ATTEMPTS) return { error: `the attempt limit of ${MAX_ATTEMPTS} was reached` };
+  return { n: resume.attempt + 1, history: resume.history.slice(-MAX_ATTEMPTS) };
+}
+
+function attemptRecord(manifestId_, n, history, status, entry) {
+  return { schema: ATTEMPT_SCHEMA, manifestId: manifestId_, attempt: n, status, history: [...history, { attempt: n, ...entry }] };
+}
+
+/**
+ * Replay a manifest. Never throws.
+ *
+ * @param {object} bundle { manifest, fixtureFiles, patchFiles? }
+ * @param {object} [o]
+ * @param {object} [o.resume]  an attempt returned earlier with status 'awaiting-prerequisites'
+ * @param {object} [o.hostEnvironment] environment identity override (test seam)
+ * @param {object} [o.config]  assurance config (the verification-oracles feature is off by default)
+ * @param {object} [o.runOptions] passed to runOracle (test seams: deps, probeEnv, signal)
+ * @returns {Promise<object>} { status: 'completed'|'awaiting-prerequisites'|'rejected', executed, outcome, record, receipt, reproduced, prerequisites, attempt, errors }
+ */
+export async function replayManifest(bundle, o = {}) {
+  const { manifest, fixtureFiles, patchFiles = null } = bundle || {};
+  const valid = validateReplayManifest(manifest, { fixtureFiles, patchFiles });
+  if (!valid.ok) return { status: 'rejected', executed: false, outcome: null, record: null, receipt: null, reproduced: null, prerequisites: [], attempt: null, errors: valid.errors };
+
+  const step = nextAttempt(o.resume, manifest.id);
+  if (step.error) return { status: 'rejected', executed: false, outcome: null, record: null, receipt: null, reproduced: null, prerequisites: [], attempt: null, errors: [{ code: 'ATTEMPT_REJECTED', path: 'resume', message: step.error }] };
+
+  const request = {
+    oracleId: manifest.oracle.id, hypothesisId: manifest.hypothesisId, commit: manifest.repository.commit,
+    files: { ...fixtureFiles, ...(patchFiles || {}) }, entry: manifest.entry, inputs: manifest.inputs, attempt: step.n,
+    budgets: manifest.budgets,
+  };
+  const waiting = (prerequisites, outcome, reason) => {
+    const record = recordWithoutExecution(manifest.oracle.id, request, outcome, reason, registry);
+    return {
+      status: 'awaiting-prerequisites', executed: false, outcome, record, receipt: null, reproduced: null, prerequisites, errors: [],
+      attempt: attemptRecord(manifest.id, step.n, step.history, 'awaiting-prerequisites', { outcome, prerequisites: prerequisites.map((p) => `${p.kind}:${p.state}`) }),
+    };
+  };
+
+  const unmet = unmetPrerequisites(manifest, o.hostEnvironment || environmentIdentity());
+  if (unmet.length) {
+    const never = unmet.some((p) => !p.resumable);
+    return waiting(unmet, never ? 'unsupported' : 'not-run', `replay prerequisite(s) not met: ${unmet.map((p) => `${p.kind} ${p.id} (${p.state})`).join('; ')}; nothing was executed`);
+  }
+
+  const run = await runOracle(request, { config: o.config, ...(o.runOptions || {}) });
+  if (run.status === 'rejected') return { status: 'rejected', executed: false, outcome: null, record: null, receipt: null, reproduced: null, prerequisites: [], attempt: null, errors: (run.errors || []).map((m) => ({ code: 'REQUEST_REJECTED', path: '', message: m })) };
+  if (!run.executed) {
+    const feature = run.status === 'disabled';
+    const prereq = feature
+      ? [{ kind: 'feature', id: FEATURE_ID, state: 'disabled', resumable: true, reason: run.reason }]
+      : (run.prerequisites || [{ id: 'trust-boundary', reason: run.reason }]).map((p) => ({ kind: p.id === 'trust-boundary' ? 'trust-boundary' : 'oracle-prerequisite', id: p.id, state: 'unmet', resumable: false, reason: p.reason }));
+    return waiting(prereq, run.outcome === 'unsupported' ? 'unsupported' : 'not-run', run.reason);
+  }
+  const reproduced = manifest.expected ? run.outcome === manifest.expected.outcome : null;
+  return {
+    status: 'completed', executed: true, outcome: run.outcome, record: run.record, receipt: run.receipt, reproduced, disclosure: run.disclosure,
+    prerequisites: [], errors: [], run: run.run, environment: run.environment,
+    attempt: attemptRecord(manifest.id, step.n, step.history, 'completed', { outcome: run.outcome }),
+  };
+}

package/src/posture/verification/advisory-state.js

@@ -0,0 +1,71 @@
+// Advisory output can never reach authoritative state (X-207.AC01).
+//
+// Hunt (`discovery/`) is advisory: a model proposes candidates and the output is a hypothesis, never a finding that gates a
+// release. Two ways that separation could fail quietly are closed here, both by construction rather than by convention:
+//
+//   1. SHARED-FILE SIDE EFFECTS. Advisory code writes to exactly one file name from a closed allowlist, through
+//      `writeAdvisoryState`. The write goes to a fresh temporary file that is renamed over the target, so a target that is a
+//      symlink or a hard link to `last-scan.json` (planted by a hostile tree) is REPLACED, never written through. The state
+//      directory must resolve inside the project root. A name outside the allowlist, a path separator in a name, or the
+//      authoritative scan files are refused with a typed reason.
+//   2. SERIALIZATION. A hypothesis is recognisable (`isAdvisoryHypothesis`) from what the hunt pipeline stamps on it, and the
+//      report normalizer excludes it from every gating output. Promotion into a finding is the only way across, and it is a
+//      different shape (`hypothesis-promotion.js`), so a hypothesis cannot be turned into a blocker by being merged into a
+//      scan's finding list.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { isPlainObject } from '../assurance/schema-kit.js';
+import { STATE_DIR_NAME, stateWritesEnabled } from '../state-dir.js';
+
+/** The state file names advisory code may write. Everything else is refused. */
+export const ADVISORY_STATE_FILES = Object.freeze(['discovery-memory.json']);
+
+/** Files that decide a gate and that no advisory writer may name, even by mistake in the allowlist above. */
+const AUTHORITATIVE_STATE_FILES = Object.freeze(['last-scan.json', 'last-scan.json.sig', 'rules.yml', 'rules.yml.sig', 'scan-key']);
+
+const MAX_BYTES = 4 * 1024 * 1024;
+
+/** True for a hunt hypothesis: it carries the hunt stamp (`parser: DISCOVERY` and/or a `discovery` object). */
+export function isAdvisoryHypothesis(f) {
+  return isPlainObject(f) && (f.parser === 'DISCOVERY' || isPlainObject(f.discovery));
+}
+
+/**
+ * Write an advisory state file. Returns `{ ok: true, path }` or `{ ok: false, code, reason }`; never throws.
+ * `body` is a string. The write is atomic (temp file + rename) and never follows a link at the target.
+ */
+export function writeAdvisoryState(scanRoot, name, body) {
+  const refuse = (code, reason) => ({ ok: false, code, reason });
+  try {
+    if (typeof name !== 'string' || name.includes('/') || name.includes('\\') || name.includes('\0') || name === '' || name.startsWith('.')) {
+      return refuse('bad-name', 'an advisory state file name is a plain file name');
+    }
+    if (AUTHORITATIVE_STATE_FILES.includes(name) || /^last-scan/.test(name)) return refuse('authoritative', `'${name}' is authoritative scan state; advisory output never writes it`);
+    if (!ADVISORY_STATE_FILES.includes(name)) return refuse('not-allowlisted', `'${name}' is not an advisory state file`);
+    if (!stateWritesEnabled()) return refuse('state-writes-disabled', 'state writes are switched off for this process (read-only scan)');
+    if (typeof body !== 'string' || Buffer.byteLength(body) > MAX_BYTES) return refuse('bad-body', `advisory state is a string of at most ${MAX_BYTES} bytes`);
+    if (typeof scanRoot !== 'string' || !scanRoot) return refuse('no-root', 'no project root');
+    const rootReal = fs.realpathSync(scanRoot);
+    const dir = path.join(rootReal, STATE_DIR_NAME);
+    fs.mkdirSync(dir, { recursive: true });
+    const dirReal = fs.realpathSync(dir);
+    if (dirReal !== path.join(rootReal, STATE_DIR_NAME)) return refuse('state-dir-escapes', 'the state directory resolves outside the project root');
+    const target = path.join(dirReal, name);
+    const tmp = path.join(dirReal, `.${name}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+    let fd = null;
+    try {
+      fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o644);
+      fs.writeSync(fd, body);
+      fs.closeSync(fd); fd = null;
+      fs.renameSync(tmp, target);
+    } catch (e) {
+      if (fd !== null) { try { fs.closeSync(fd); } catch { /* best effort */ } }
+      try { fs.rmSync(tmp, { force: true }); } catch { /* best effort */ }
+      return refuse('write-failed', String(e?.message || e).slice(0, 160));
+    }
+    return { ok: true, path: target };
+  } catch (e) {
+    return refuse('write-failed', String(e?.message || e).slice(0, 160));
+  }
+}