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

package/src/posture/invariants/coverage.js

@@ -0,0 +1,164 @@
+// Bounded business-logic coverage (X-407).
+//
+// "We ran scenarios" is not "the business logic is covered". This turns the contracts a project has and the runs it made into a
+// report that says what was exercised AND what was not, and keeps every gap explicit:
+//
+//   inventory    approved versus proposed (and rejected, superseded, unrecorded) contracts, judged by the VERIFIED approval ledger:
+//                a document that merely claims approval is listed as proposed-by-ledger with the claim noted;
+//   exercised    which actors, states and declared transitions the executed scenarios actually drove, against what each contract
+//                declares;
+//   gaps         untested transitions, actors and states; the sequence depth the scenarios were bounded to; races a contract
+//                class cannot model (and the cooperative-scheduling limit where one was run); scenarios that could not be built
+//                or did not settle; and absent contracts (a class with no contract at all, or no contracts whatsoever).
+//
+// It never claims exhaustive correctness: the report states, in a field and in the text, that it describes a bounded sample.
+// A run that did not execute contributes nothing to "exercised": an unsupported or inconclusive scenario is a gap, never
+// coverage.
+//
+// Additive output. `invariantCoverageFields` is the one place a surface (the JSON/CLI report) asks for the fields: it returns
+// `{}` unless the `invariant-scenarios` feature is on AND a coverage object was supplied, so a default scan's report is
+// byte-identical to what it was (pinned in `test/fixtures/invariant-compat/`). The key is `invariantCoverage`.
+import { SCHEMA_VERSION, isPlainObject } from '../assurance/schema-kit.js';
+import { featureStatus, resolveAssuranceConfig } from '../assurance/config.js';
+import { INVARIANT_CLASSES } from './schema.js';
+import { verifyLedger } from './lifecycle.js';
+import { FEATURE, HARD_BOUNDS, KINDS_BY_CLASS } from './scenarios.js';
+import { NOT_EXHAUSTIVE } from './export.js';
+
+export const COVERAGE_SCHEMA = 'agentic-security/business-coverage';
+export const GAP_CODES = Object.freeze([
+  'absent-contract', 'unapproved-contract', 'not-executed', 'untested-transition', 'untested-actor', 'untested-state',
+  'bounded-depth', 'unsupported-scenario', 'unsettled-scenario', 'unsupported-race', 'cooperative-scheduling',
+]);
+
+const sorted = (set) => [...set].sort();
+
+function declaredStates(inv) {
+  const wf = inv.forbidden.find((f) => f.op === 'transition-outside');
+  if (wf) return sorted(new Set(wf.allowed.flatMap((t) => [t.from, t.to])));
+  return sorted(new Set(inv.resources.map((r) => r.id)));
+}
+
+function exercisedStates(inv, steps) {
+  const wf = inv.forbidden.find((f) => f.op === 'transition-outside');
+  const keyToId = new Map(inv.resources.map((r) => [r.key, r.id]));
+  const out = new Set();
+  if (wf) {
+    const declared = new Set(declaredStates(inv));
+    const reached = steps.filter((s) => s.to && declared.has(s.to));
+    if (reached.length) out.add(wf.allowed[0].from); // the seeded initial state is where a workflow starts
+    for (const s of reached) out.add(s.to);
+  } else {
+    for (const s of steps) if (s.key && keyToId.has(s.key)) out.add(keyToId.get(s.key));
+  }
+  return sorted(out);
+}
+
+/**
+ * @param {object} p
+ * @param {Array<{ invariant: object, result?: object }>} p.entries  each contract, with the `verifyInvariant` result of its run (or none)
+ * @param {object} [p.ledger]   the approval ledger; without a verifying one no contract is approved
+ * @param {object} [p.signer]   ledger signer (test seam)
+ * @returns {object} the coverage report (plain data, deterministic: no clock)
+ */
+export function businessCoverage({ entries, ledger, signer } = {}) {
+  const list = (Array.isArray(entries) ? entries : []).filter((e) => isPlainObject(e) && isPlainObject(e.invariant) && Array.isArray(e.invariant.actors));
+  const verified = verifyLedger(ledger, { signer });
+  const stateOf = (inv) => (verified.ok ? (verified.states[inv.id] ?? 'unrecorded') : 'unrecorded');
+  const gaps = [];
+  const gap = (code, detail, extra = {}) => gaps.push({ code, detail, ...extra });
+  const invariants = [];
+  const inventory = { approved: [], proposed: [], rejected: [], superseded: [], unrecorded: [] };
+  let maxDepth = 0; let maxRequests = 0; let truncated = 0;
+  const totals = { actors: { declared: 0, exercised: 0 }, transitions: { declared: 0, exercised: 0 }, states: { declared: 0, exercised: 0 } };
+
+  for (const { invariant: inv, result } of list) {
+    const state = stateOf(inv);
+    const ref = { id: inv.id, key: inv.key, revision: inv.revision, class: inv.class };
+    inventory[state === 'approved' ? 'approved' : state === 'proposed' ? 'proposed' : state === 'rejected' ? 'rejected' : state === 'superseded' ? 'superseded' : 'unrecorded'].push(ref);
+    const claimsApproval = inv.review?.state === 'approved' && state !== 'approved';
+
+    const runs = Array.isArray(result?.results) ? result.results : [];
+    const executed = runs.filter((r) => r.status === 'completed');
+    const decided = executed.filter((r) => r.outcome === 'confirmed' || r.outcome === 'refuted');
+    const steps = executed.flatMap((r) => [...(r.exercise?.control || []), ...(r.exercise?.attack || [])]);
+    for (const r of executed) {
+      maxDepth = Math.max(maxDepth, r.limits?.depth ?? 0); maxRequests = Math.max(maxRequests, r.limits?.requests ?? 0);
+      if (r.limits?.truncated) truncated++;
+    }
+
+    const actorsDeclared = sorted(new Set(inv.actors.map((a) => a.id)));
+    const actorsExercised = sorted(new Set(steps.map((s) => s.actor).filter((a) => actorsDeclared.includes(a))));
+    const keyOf = new Map(inv.resources.map((r) => [r.id, r.key]));
+    const transitionsDeclared = inv.transitions.map((t) => t.id);
+    const transitionsExercised = inv.transitions.filter((t) => steps.some((s) => t.actors.includes(s.actor) && s.action === t.action && s.key === keyOf.get(t.resource))).map((t) => t.id);
+    const statesDeclared = declaredStates(inv);
+    const statesExercised = exercisedStates(inv, steps);
+
+    const mine = { id: inv.id, key: inv.key };
+    if (!executed.length) {
+      gap('not-executed', `no scenario for '${inv.key}' was executed${result?.status && result.status !== 'ok' ? ` (${result.status}: ${result.reason ?? 'no reason given'})` : ''}`, mine);
+    } else {
+      for (const t of transitionsDeclared.filter((x) => !transitionsExercised.includes(x))) gap('untested-transition', `declared transition '${t}' of '${inv.key}' was not exercised by any executed scenario`, { ...mine, transition: t });
+      for (const a of actorsDeclared.filter((x) => !actorsExercised.includes(x))) gap('untested-actor', `declared actor '${a}' of '${inv.key}' performed no step in any executed scenario`, { ...mine, actor: a });
+      for (const s of statesDeclared.filter((x) => !statesExercised.includes(x))) gap('untested-state', `declared state '${s}' of '${inv.key}' was not reached by any executed scenario`, { ...mine, state: s });
+    }
+    for (const u of result?.unsupported || []) gap('unsupported-scenario', `${u.kind ?? 'scenario'} for '${inv.key}' could not be built: ${u.reason}`, { ...mine, kind: u.kind ?? null });
+    for (const r of runs.filter((x) => x.status !== 'completed' || !['confirmed', 'refuted'].includes(x.outcome))) {
+      gap('unsettled-scenario', `${r.kind} for '${inv.key}' did not settle (${r.status === 'completed' ? `outcome '${r.outcome}'` : `status '${r.status}'`})${r.reason ? `: ${String(r.reason).slice(0, 160)}` : ''}`, { ...mine, kind: r.kind });
+    }
+    // races: a class with no concurrent family cannot be race-tested here; one that has it needs an executed, settled run
+    const hasRaceFamily = (KINDS_BY_CLASS[inv.class] || []).includes('concurrent-operations');
+    const raceRuns = decided.filter((r) => r.kind === 'concurrent-operations');
+    if (!hasRaceFamily) gap('unsupported-race', `no concurrent-operations scenario exists for the '${inv.class}' class, so races against '${inv.key}' are not tested`, mine);
+    else if (!raceRuns.length) gap('unsupported-race', `no concurrent-operations scenario for '${inv.key}' settled, so races against it are not tested`, mine);
+    else gap('cooperative-scheduling', `races against '${inv.key}' were exercised under cooperative scheduling in one process with a fixed start order; parallel execution and other interleavings are not covered`, mine);
+    if (state !== 'approved') gap('unapproved-contract', `'${inv.key}' is ${state}${claimsApproval ? ' (its document claims approval; only the verified ledger counts)' : ''}: a violation of it would be an advisory candidate, not a failure of a requirement`, mine);
+
+    totals.actors.declared += actorsDeclared.length; totals.actors.exercised += actorsExercised.length;
+    totals.transitions.declared += transitionsDeclared.length; totals.transitions.exercised += transitionsExercised.length;
+    totals.states.declared += statesDeclared.length; totals.states.exercised += statesExercised.length;
+    invariants.push({
+      ...ref, name: inv.name, state, claimsApproval,
+      declared: { actors: actorsDeclared, transitions: transitionsDeclared, states: statesDeclared },
+      exercised: { actors: actorsExercised, transitions: transitionsExercised, states: statesExercised },
+      scenarios: { total: runs.length, executed: executed.length, decided: decided.length, unsupported: (result?.unsupported || []).length },
+      violations: { approved: runs.filter((r) => r.classification?.kind === 'approved-violation').length, candidate: runs.filter((r) => r.classification?.kind === 'candidate-violation').length },
+    });
+  }
+
+  // contracts that do not exist are gaps too
+  if (!list.length) gap('absent-contract', 'no contract was supplied: no business-logic behaviour is covered');
+  else for (const cls of INVARIANT_CLASSES) {
+    if (!list.some((e) => e.invariant.class === cls)) gap('absent-contract', `no contract exists for the '${cls}' class: that kind of behaviour is not covered at all`, { class: cls });
+  }
+  const executedAny = invariants.some((i) => i.scenarios.executed > 0);
+  if (executedAny) gap('bounded-depth', `scenarios were bounded to at most ${maxDepth} attack step(s) and ${maxRequests} request(s) (hard ceilings: depth ${HARD_BOUNDS.depth}, requests ${HARD_BOUNDS.requests})${truncated ? `; ${truncated} scenario(s) were truncated to fit` : ''}; longer sequences are not explored`, { maxDepth, maxRequests, truncated });
+
+  const counts = Object.fromEntries(Object.entries(inventory).map(([k, v]) => [k, v.length]));
+  const lines = [
+    `Business-logic coverage (bounded sample, not exhaustive): ${counts.approved} approved, ${counts.proposed} proposed, ${counts.rejected + counts.superseded + counts.unrecorded} other contract(s)`,
+    `  Exercised: ${totals.actors.exercised}/${totals.actors.declared} actors, ${totals.states.exercised}/${totals.states.declared} states, ${totals.transitions.exercised}/${totals.transitions.declared} transitions`,
+    `  Gaps: ${gaps.length}${gaps.length ? ` (${[...new Set(gaps.map((g) => g.code))].sort().join(', ')})` : ''}`,
+    `  ${NOT_EXHAUSTIVE}`,
+  ];
+  return {
+    schema: COVERAGE_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    ledger: { verified: verified.ok, note: verified.ok ? 'approval state comes from the verified ledger' : 'no verifying approval ledger: no contract counts as approved' },
+    inventory, counts, invariants, totals, gaps,
+    bounds: { maxDepth, maxRequests, truncatedScenarios: truncated, hard: HARD_BOUNDS },
+    claims: { exhaustive: false, statement: NOT_EXHAUSTIVE },
+    lines,
+  };
+}
+
+/**
+ * The fields a report adds for business coverage: `{ invariantCoverage }`, or `{}` when the feature is off or there is nothing to
+ * report. ADDITIVE: with the feature off (the default) a report is byte-identical to what it was.
+ */
+export function invariantCoverageFields(coverage, { config } = {}) {
+  if (!isPlainObject(coverage) || coverage.schema !== COVERAGE_SCHEMA) return {};
+  const cfg = config || resolveAssuranceConfig({ env: process.env });
+  if (featureStatus(cfg, FEATURE).status !== 'ok') return {};
+  return { invariantCoverage: coverage };
+}

package/src/posture/invariants/export.js

@@ -0,0 +1,178 @@
+// Reproducible scenario export, without tenant secrets (X-407.AC03).
+//
+// A reviewer or another tool should be able to take a bounded scenario away, replay it on the same pinned fixture, and get the
+// same verdict. This builds that package from generated scenarios, and keeps three promises:
+//
+//   - It carries no tenant secret. The fixture SOURCE is never exported (only its digest: the recipient already holds the
+//     fixture, or cannot reproduce anyway); the scenario inputs are scanned for secret-looking keys and token shapes, and a
+//     scenario that holds one is WITHHELD with the paths named (never the values), not exported with a hole in it, because a
+//     scenario with a value removed is a different scenario and would not replay to the same digest.
+//   - It is self-checking. Every scenario carries its content digest and its pinned fixture digest; `verifyScenarioExport`
+//     recomputes them (and the replay manifest ids, when a commit was supplied) so an edited export is detected.
+//   - It never claims more than it did. The package states that it is a bounded sample of one contract's behaviour, lists the
+//     bounds that applied, the scenario families that could not be built, and says plainly that it is not a proof of
+//     business-logic correctness.
+//
+// Gate: the `invariant-scenarios` feature, off by default. With it off nothing is built.
+//
+// `findSecrets` is shared with the regression artifact (`repair.js`), which embeds the fixture and the patch and therefore
+// must refuse to embed a credential. It reports WHERE (file and kind), never WHAT. Pattern checks over text: a paraphrased or
+// encoded secret is not caught, and the export is only as clean as the synthetic fixture it was generated from.
+import { digestOf, semanticId } from '../assurance/identity.js';
+import { SCHEMA_VERSION, isPlainObject } from '../assurance/schema-kit.js';
+import { featureStatus, resolveAssuranceConfig } from '../assurance/config.js';
+import { createReplayManifest } from '../replay/replay.js';
+import { generateScenarios, HARD_BOUNDS, FEATURE } from './scenarios.js';
+import { verifyLedger } from './lifecycle.js';
+import { readJsonFile, readFixtureDir } from './project-input.js';
+
+export const EXPORT_SCHEMA = 'agentic-security/invariant-scenario-export';
+export const NOT_EXHAUSTIVE = 'This is a bounded sample of one contract on one disposable fixture. A clean result covers only the scenarios listed here; it is not a proof of business-logic correctness.';
+
+const SECRET_KEY = /secret|token|passw|api[_-]?key|authorization|cookie|credential|private[_-]?key|ssn/i;
+const SECRET_SHAPES = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, 'private key block'],
+  [/\bAKIA[0-9A-Z]{16}\b/, 'cloud access key id'],
+  [/\bgh[pousr]_[A-Za-z0-9]{30,}\b/, 'source host token'],
+  [/\bsk-[A-Za-z0-9_-]{10,}/, 'secret key token'],
+  [/\bxox[abprs]-[A-Za-z0-9-]{10,}/, 'chat token'],
+  [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}/, 'signed web token'],
+  [/\b(?:password|passwd|secret|api[_-]?key|token|authorization|bearer)\b["']?\s*[:=]\s*["'][^"'\s]{6,}["']/i, 'credential assignment'],
+];
+
+/** Secret-looking content in a map of file name to text. Names the file and the kind; never returns the matched text. */
+export function findSecrets(files) {
+  const out = [];
+  for (const [file, text] of Object.entries(isPlainObject(files) ? files : {})) {
+    if (typeof text !== 'string') continue;
+    for (const [re, kind] of SECRET_SHAPES) if (re.test(text)) out.push({ where: file, kind });
+  }
+  return out;
+}
+
+/** Secret-looking keys or values anywhere in a JSON-able value. Returns paths and kinds, never the values. */
+export function findSecretsIn(value, path = '$', out = []) {
+  if (typeof value === 'string') {
+    for (const [re, kind] of SECRET_SHAPES) if (re.test(value)) { out.push({ where: path, kind }); break; }
+  } else if (Array.isArray(value)) {
+    value.forEach((v, i) => findSecretsIn(v, `${path}[${i}]`, out));
+  } else if (isPlainObject(value)) {
+    for (const [k, v] of Object.entries(value)) {
+      if (SECRET_KEY.test(k) && v !== null && v !== undefined && v !== '' && typeof v !== 'boolean') out.push({ where: `${path}.${k}`, kind: 'secret-looking field' });
+      else findSecretsIn(v, `${path}.${k}`, out);
+    }
+  }
+  return out;
+}
+
+const copy = (v) => JSON.parse(JSON.stringify(v));
+
+/**
+ * Build the export for one invariant. Never throws.
+ *
+ * @param {object} p
+ * @param {object} p.invariant  a valid invariant document
+ * @param {object} p.fixture    { files } of the disposable fixture (used for its digest and the entry check only; never exported)
+ * @param {object} [p.ledger]   the approval ledger: only a ledger that verifies can say a contract is approved
+ * @param {string} [p.commit]   exact commit; with it the replay manifests are included, without it they are listed as needed
+ * @param {number} [p.seed]
+ * @param {object} [p.bounds]
+ * @param {object} [p.config]   assurance config
+ * @param {object} [p.signer]   ledger signer (test seam)
+ * @returns {{ status: 'ok'|'disabled'|'unsupported'|'rejected'|'blocked', reason?: string, export?: object, withheld?: object[] }}
+ */
+export function exportScenarios(p = {}) {
+  const config = p.config || resolveAssuranceConfig({ env: process.env });
+  const gate = featureStatus(config, FEATURE);
+  if (gate.status !== 'ok') return { status: 'disabled', reason: `${FEATURE} is not available: ${gate.reason}` };
+  const gen = generateScenarios(p.invariant, { fixture: p.fixture, seed: p.seed, bounds: p.bounds, config });
+  if (gen.status !== 'ok') return { status: gen.status, reason: gen.reason, errors: gen.errors };
+
+  // the identifying text that travels with the export is checked too: a credential pasted into a contract's name must not leave
+  const meta = findSecretsIn({ name: p.invariant.name, key: p.invariant.key, application: p.invariant.scope.application }, 'invariant');
+  if (meta.length) return { status: 'blocked', reason: 'secret-looking content in the contract\'s name, key or application', withheld: [{ scenarioId: null, kind: null, reason: 'secret-looking content in the contract metadata', where: meta }] };
+
+  const withheld = [];
+  const scenarios = [];
+  for (const s of gen.scenarios) {
+    const hits = findSecretsIn(s.inputs, 'inputs');
+    if (hits.length) { withheld.push({ scenarioId: s.id, kind: s.kind, reason: 'secret-looking content in the scenario inputs', where: hits }); continue; }
+    const doc = copy(s);
+    const entry = { scenario: doc, digest: digestOf(doc) };
+    if (p.commit) {
+      try { entry.manifest = createReplayManifest({ hypothesisId: s.id, commit: p.commit, fixtureFiles: p.fixture.files, oracleId: 'business-state', entry: s.entry, inputs: s.inputs, budgets: { timeoutMs: s.limits.timeBudgetMs } }); } catch { entry.manifest = null; }
+    }
+    scenarios.push(entry);
+  }
+  if (!scenarios.length && withheld.length) return { status: 'blocked', reason: 'every scenario was withheld because it held secret-looking content', withheld };
+
+  let approval = { state: 'unrecorded', source: 'no ledger supplied' };
+  if (p.ledger) {
+    const v = verifyLedger(p.ledger, { signer: p.signer });
+    approval = v.ok ? { state: v.states[p.invariant.id] || 'unrecorded', source: 'verified approval ledger' } : { state: 'unverified', source: 'the approval ledger does not verify' };
+  }
+  const body = {
+    schema: EXPORT_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    invariant: { id: p.invariant.id, key: p.invariant.key, revision: p.invariant.revision, class: p.invariant.class, name: p.invariant.name },
+    approval: { ...approval, documentClaims: p.invariant.review?.state ?? null },
+    fixture: { digest: gen.scenarios[0]?.fixtureDigest ?? digestOf(p.fixture.files), entry: p.invariant.scope.entry, included: false, note: 'the fixture source is not exported: replay needs the fixture whose digest is listed' },
+    oracle: { id: 'business-state', version: '1' },
+    bounds: { applied: gen.bounds, hard: HARD_BOUNDS },
+    scenarios,
+    notBuilt: gen.unsupported,
+    withheld,
+    secretsExported: false,
+    claims: { exhaustive: false, statement: NOT_EXHAUSTIVE },
+    reproduce: p.commit
+      ? 'replay each manifest against the fixture with the listed digest (replayManifest), then compare the outcome with an executed run'
+      : 'supply an exact commit to obtain replay manifests; the scenario documents alone pin the fixture digest, the seed and the inputs',
+  };
+  body.id = semanticId('sexp', { ...body, scenarioDigests: scenarios.map((e) => e.digest) }, ['invariant', 'fixture', 'scenarioDigests', 'bounds']);
+  return { status: 'ok', export: body, withheld };
+}
+
+/**
+ * Check an export: every scenario digest, content-addressed id and fixture pin recomputes, no secret-looking content is present,
+ * and (given the fixture files) the pinned digest matches. Never throws.
+ */
+export function verifyScenarioExport(doc, { fixtureFiles } = {}) {
+  const errors = [];
+  const fail = (code, message) => errors.push({ code, message });
+  try {
+    if (!isPlainObject(doc) || doc.schema !== EXPORT_SCHEMA) return { ok: false, errors: [{ code: 'malformed', message: 'not a scenario export' }] };
+    if (doc.claims?.exhaustive !== false || typeof doc.claims?.statement !== 'string') fail('overclaim', 'an export must state that it is not exhaustive');
+    if (doc.secretsExported !== false) fail('secrets-flag', 'the export must record that no secret was exported');
+    for (const e of doc.scenarios || []) {
+      if (digestOf(e.scenario) !== e.digest) fail('scenario-tampered', `scenario ${e.scenario?.id} does not match its digest`);
+      if (e.scenario?.fixtureDigest !== doc.fixture?.digest) fail('fixture-pin-mismatch', `scenario ${e.scenario?.id} pins a different fixture than the export`);
+      if (e.manifest && e.manifest.fixture?.digest !== doc.fixture?.digest) fail('manifest-fixture-mismatch', `the manifest for ${e.scenario?.id} pins a different fixture`);
+      const leaked = findSecretsIn(e.scenario?.inputs, 'inputs');
+      if (leaked.length) fail('secret-in-export', `scenario ${e.scenario?.id} holds secret-looking content at ${leaked.map((l) => l.where).join(', ')}`);
+    }
+    if (fixtureFiles !== undefined && digestOf(fixtureFiles) !== doc.fixture?.digest) fail('fixture-mismatch', 'the supplied fixture does not match the digest the export pins');
+    if (doc.fixture?.included !== false) fail('fixture-included', 'the export must not include the fixture source');
+  } catch (e) {
+    fail('malformed', `the check could not complete: ${String(e?.message || e).slice(0, 120)}`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * The CLI and MCP entry: build an export from files already resolved (and confined) to absolute paths by the caller.
+ * Reads the contract, the fixture directory and, optionally, the ledger through the bounded readers in `project-input.js`.
+ * Never throws; every failure is a typed status with its reason.
+ */
+export function exportFromFiles({ invariantPath, fixturePath, ledgerPath, commit, seed, bounds, config, signer } = {}) {
+  const inv = readJsonFile(invariantPath);
+  if (!inv.ok) return { status: 'rejected', reason: `the invariant file: ${inv.reason}` };
+  const fx = readFixtureDir(fixturePath);
+  if (!fx.ok) return { status: 'rejected', reason: `the fixture directory: ${fx.errors.join('; ')}` };
+  let ledger;
+  if (ledgerPath) {
+    const l = readJsonFile(ledgerPath);
+    if (!l.ok) return { status: 'rejected', reason: `the ledger file: ${l.reason}` };
+    ledger = l.value;
+  }
+  if (commit !== undefined && !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(String(commit))) return { status: 'rejected', reason: 'commit must be an exact 40 or 64 character hex id' };
+  return exportScenarios({ invariant: inv.value, fixture: { files: fx.files }, ledger, commit, seed, bounds, config, signer });
+}

package/src/posture/invariants/expressions.js

@@ -0,0 +1,46 @@
+// The closed grammar of forbidden outcomes (X-401).
+//
+// Kept apart from `schema.js` so the oracle adapter can validate the expressions it is handed without importing the schema
+// (the schema imports the oracle registry, which imports the adapters). Every expression is data: an `op` from the table below
+// plus parameters whose strings are restricted to a conservative charset, so no declarative field can carry executable content.
+// An op that is not in the table is an unsupported expression and is rejected, never interpreted.
+const LIST_LIMIT = 8;
+
+// Letters, digits and a few separators. No spaces, quotes, braces, parentheses, operators or template syntax.
+const SAFE_TEXT = /^[A-Za-z0-9_.:/-]{1,64}$/;
+export const isSafeText = (v) => typeof v === 'string' && SAFE_TEXT.test(v);
+const safeList = (v, max = LIST_LIMIT) => Array.isArray(v) && v.length >= 1 && v.length <= max && v.every(isSafeText);
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+export const EXPRESSIONS = Object.freeze({
+  'cross-tenant-write': { classes: ['tenant-isolation'], keys: ['op', 'bind', 'id', 'prefix'], check: (e) => (e.prefix === undefined || isSafeText(e.prefix) ? null : 'prefix must be a short safe string') },
+  'cross-tenant-read': { classes: ['tenant-isolation'], keys: ['op', 'bind', 'id'], check: () => null },
+  'unauthorized-role-change': {
+    classes: ['privilege-constraint'], keys: ['op', 'bind', 'id', 'actions', 'allowedRoles'],
+    check: (e) => (safeList(e.actions) && safeList(e.allowedRoles) ? null : 'actions and allowedRoles must be short lists of safe strings'),
+  },
+  'sum-not-conserved': {
+    classes: ['value-conservation'], keys: ['op', 'bind', 'id', 'prefix', 'field', 'allowedActions'],
+    check: (e) => (isSafeText(e.prefix) && isSafeText(e.field) && (e.allowedActions === undefined || (Array.isArray(e.allowedActions) && e.allowedActions.length <= LIST_LIMIT && e.allowedActions.every(isSafeText))) ? null : 'prefix and field are required safe strings; allowedActions is a short list'),
+  },
+  'transition-outside': {
+    classes: ['workflow-order'], keys: ['op', 'bind', 'id', 'prefix', 'field', 'allowed'],
+    check: (e) => (isSafeText(e.prefix) && isSafeText(e.field) && Array.isArray(e.allowed) && e.allowed.length >= 1 && e.allowed.length <= 16
+      && e.allowed.every((t) => isObj(t) && Object.keys(t).every((k) => k === 'from' || k === 'to') && isSafeText(t.from) && isSafeText(t.to)) ? null : 'prefix, field and a list of { from, to } transitions are required'),
+  },
+  'duplicate-effect': {
+    classes: ['idempotency'], keys: ['op', 'bind', 'id', 'event', 'max'],
+    check: (e) => (isSafeText(e.event) && (e.max === undefined || (Number.isInteger(e.max) && e.max >= 1 && e.max <= 5)) ? null : 'event must be a safe string and max an integer 1 to 5'),
+  },
+});
+
+/** Problems with one expression (empty list when it is supported and well formed). Does not check class or oracle binding. */
+export function expressionProblems(expr) {
+  if (!isObj(expr) || !isSafeText(expr.id)) return ['a forbidden outcome needs a safe id'];
+  const spec = EXPRESSIONS[expr.op];
+  if (!spec) return [`'${String(expr.op).slice(0, 40)}' is not a supported expression (supported: ${Object.keys(EXPRESSIONS).join(', ')})`];
+  const out = Object.keys(expr).filter((k) => !spec.keys.includes(k)).map((k) => `'${k}' is not a parameter of ${expr.op}`);
+  const why = spec.check(expr);
+  if (why) out.push(why);
+  return out;
+}