@clear-capabilities/agentic-security-scanner 0.184.0 → 0.186.1

package/src/lineage/scc-solver.js

@@ -0,0 +1,186 @@
+// Recursive-component solver for the lineage driver (DAG-01, R01.3 to R01.5).
+//
+// Pure: no I/O, no clock of its own (a budget is an injected callback), and
+// no import of any analysis engine. `driver.js` supplies the per-function
+// analysis; tests supply synthetic transfer functions.
+//
+// ## Fact domain (R01.4)
+//
+// A function summary is a finite set of facts:
+//   - `ret:<dataElementId>`                 the return value carries the id
+//   - `mut:<paramPath>:<dataElementId>`     the parameter access path
+//                                           `paramPath` is mutated to carry
+//                                           the id
+// The id universe is the set of data-element ids that appear in the entry
+// states of the analyzed contexts and the program text (finite per run). The
+// path universe is the set of syntactic parameter access paths, additionally
+// BOUNDED by `maxPathDepth` (default 6 segments): a deeper path is folded to
+// its depth-bounded prefix, which only adds the id to a coarser path (an
+// over-approximation) and is recorded as the widening reason
+// `path-depth-cap`.
+//
+// ## Join and monotonicity
+//
+// The join is set union per fact family. The solver stores
+// `next = join(previous, analyze(previous))`, so the per-function summary
+// sequence is an ascending chain in a finite lattice whether or not the
+// underlying analysis is itself monotone. An ascending chain over a finite
+// lattice stabilizes, so the iteration terminates; `maxRounds` is a second,
+// independent safety bound. A fixed point reached here is the least fixed
+// point of the joined transfer function, which is exactly what a naive
+// exhaustive iteration to stability computes (the reference solver in the
+// tests).
+//
+// ## What converged means
+//
+// `converged: true` means a full round changed no member summary AND at least
+// two rounds ran (round one is compared with the bottom seed, which is not an
+// analysis result). It does not mean the program is safe: summaries
+// under-approximate whatever the analysis does not model. If a budget stops
+// the iteration, a round cap is hit, or a member is never analyzed, the
+// result is `converged: false` with the remaining frontier listed, and the
+// last iterate must be treated as partial, never as a conservative proof.
+
+function cmp(a, b) { return a < b ? -1 : a > b ? 1 : 0; }
+
+export const DEFAULT_MAX_PATH_DEPTH = 6;
+export const DEFAULT_MAX_ROUNDS = 32;
+export const DEFAULT_MAX_CHANGED_FACTS = 1000;
+
+function foldPath(path, maxDepth) {
+  const segs = String(path).split('.');
+  if (segs.length <= maxDepth) return null;
+  return segs.slice(0, maxDepth).join('.');
+}
+
+// Joins two field-identity summaries. Returns `{ summary, reasons }`.
+// `reasons` lists widening reasons applied by this join (deterministic order).
+export function joinFieldSummaries(prev, next, opts = {}) {
+  const maxDepth = opts.maxPathDepth ?? DEFAULT_MAX_PATH_DEPTH;
+  const reasons = new Set();
+  const returnFlat = new Set(prev ? prev.returnFlat : []);
+  for (const id of next.returnFlat) returnFlat.add(id);
+
+  const mutatedParams = new Map();
+  const addMut = (path, ids) => {
+    const folded = foldPath(path, maxDepth);
+    const key = folded ?? path;
+    if (folded !== null) reasons.add('path-depth-cap');
+    let set = mutatedParams.get(key);
+    if (!set) { set = new Set(); mutatedParams.set(key, set); }
+    for (const id of ids) set.add(id);
+  };
+  if (prev) for (const [p, ids] of prev.mutatedParams) addMut(p, ids);
+  for (const [p, ids] of next.mutatedParams) addMut(p, ids);
+
+  const returnByPath = new Map();
+  for (const src of [prev && prev.returnByPath, next.returnByPath]) {
+    if (!src) continue;
+    for (const [p, ids] of src) {
+      const set = returnByPath.get(p) ?? new Set();
+      for (const id of ids) set.add(id);
+      returnByPath.set(p, set);
+    }
+  }
+  const summary = { returnFlat, returnByPath, mutatedParams, widenings: next.widenings ?? [] };
+  if (next.degradedReason) summary.degradedReason = next.degradedReason;
+  return { summary, reasons: [...reasons].sort(cmp) };
+}
+
+export function fieldFacts(summary) {
+  const out = [];
+  if (!summary) return out;
+  for (const id of summary.returnFlat) out.push(`ret:${id}`);
+  for (const [p, ids] of summary.mutatedParams) for (const id of ids) out.push(`mut:${p}:${id}`);
+  return out.sort(cmp);
+}
+
+export function bottomFieldSummary() {
+  return { returnFlat: new Set(), returnByPath: new Map(), mutatedParams: new Map(), widenings: [] };
+}
+
+function factsEqual(a, b) {
+  const fa = fieldFacts(a);
+  const fb = fieldFacts(b);
+  if (fa.length !== fb.length) return false;
+  for (let i = 0; i < fa.length; i++) if (fa[i] !== fb[i]) return false;
+  return true;
+}
+
+// Solves one recursive component.
+//
+//   members            sorted qids in the component
+//   analyze(qid)       runs one analysis of `qid` against the currently
+//                      published summaries and returns a RAW summary
+//   publish(qid, s)    makes `s` the summary other members will read
+//   bottom(qid)        initial summary (default: empty)
+//   beforeRound(round) hook, called before each round
+//   shouldStop()       returns a reason string to stop, or a falsy value
+//   maxRounds, maxPathDepth, maxChangedFacts   bounds
+//
+// Returns { converged, rounds, changedFacts, changedFactsTotal,
+//           changedFactsTruncated, wideningReasons, stoppedBy,
+//           remainingFrontier, summaries }.
+export function solveRecursiveComponent(args) {
+  const members = [...args.members].sort(cmp);
+  const maxRounds = args.maxRounds ?? DEFAULT_MAX_ROUNDS;
+  const maxChanged = args.maxChangedFacts ?? DEFAULT_MAX_CHANGED_FACTS;
+  const bottom = args.bottom || (() => bottomFieldSummary());
+  const current = new Map();
+  for (const q of members) {
+    const b = bottom(q);
+    current.set(q, b);
+    args.publish(q, b);
+  }
+  const reasons = new Set();
+  const changedFacts = [];
+  let changedTotal = 0;
+  let rounds = 0;
+  let converged = false;
+  let stoppedBy = null;
+  let analyzedThisRound = new Set();
+
+  while (rounds < maxRounds) {
+    rounds++;
+    if (args.beforeRound) args.beforeRound(rounds);
+    let changedInRound = false;
+    analyzedThisRound = new Set();
+    for (const q of members) {
+      const stop = args.shouldStop ? args.shouldStop() : null;
+      if (stop) { stoppedBy = stop; break; }
+      const prev = current.get(q);
+      const raw = args.analyze(q);
+      analyzedThisRound.add(q);
+      const { summary: joined, reasons: rs } = joinFieldSummaries(prev, raw, { maxPathDepth: args.maxPathDepth });
+      for (const r of rs) reasons.add(r);
+      if (!factsEqual(prev, joined)) {
+        changedInRound = true;
+        const before = new Set(fieldFacts(prev));
+        for (const f of fieldFacts(joined)) {
+          if (before.has(f)) continue;
+          changedTotal++;
+          if (changedFacts.length < maxChanged) changedFacts.push({ round: rounds, qid: q, fact: f });
+        }
+      }
+      current.set(q, joined);
+      args.publish(q, joined);
+    }
+    if (stoppedBy) { rounds = analyzedThisRound.size === 0 && rounds > 0 ? rounds - 1 : rounds; break; }
+    if (!changedInRound && rounds >= 2) { converged = true; break; }
+  }
+  if (!converged && !stoppedBy && rounds >= maxRounds) {
+    reasons.add('round-cap');
+    stoppedBy = 'round-cap';
+  }
+  return {
+    converged,
+    rounds,
+    changedFacts,
+    changedFactsTotal: changedTotal,
+    changedFactsTruncated: changedTotal > changedFacts.length,
+    wideningReasons: [...reasons].sort(cmp),
+    stoppedBy,
+    remainingFrontier: converged ? [] : members.slice(),
+    summaries: current,
+  };
+}

package/src/lineage/smt-orchestrator.js

@@ -0,0 +1,174 @@
+//
+// smt-orchestrator.js: the optional solver path for witness conditions (DAG-04, R04.3 / R04.4).
+//
+// The bounded abstract domains in path-predicates.js decide first. A solver is consulted only when they
+// say `unknown`, and only through this module, which makes the call:
+//   * awaited: the caller gets one settled result, never a dangling promise;
+//   * time-bounded: a deadline races the solver, and a solver that ignores it is still released;
+//   * cancellable: an AbortSignal from the caller and the module's own deadline both abort the solver's
+//     signal, and a late settlement from an abandoned solver is swallowed;
+//   * honest: no solver reports `unsupported`, a deadline reports `timeout`, a malformed or failing solver
+//     reports `unknown`. None of these ever drops or downgrades the finding. The abstract result is kept.
+//
+// `noSolver` is the default stub. The real backend is smt-z3-backend.js (optional `z3-solver`, lazy, used only
+// when a solver is passed in or AGENTIC_SECURITY_LINEAGE_SMT=z3 is set). A solver is an
+// object with `{ name, version?, available?, check(problem, { signal }) -> Promise<{ result }> }` where
+// `result` is 'sat' | 'unsat' | 'unknown'. `problem` is the solver-neutral view from `toSolverProblem`.
+// Satisfiability never implies exploitability.
+
+import { evaluateWitnessConditions, toSolverProblem, PATH_PREDICATE_VERSION, SATISFIABILITY_NOTE } from './path-predicates.js';
+import { sharedZ3Solver, smtBackendEnabled } from './smt-z3-backend.js';
+
+export const SOLVER_DEFAULT_TIMEOUT_MS = 1000;
+export const SOLVER_TIMEOUT_MAX_MS = 60_000;
+
+/** The default: a solver that is not there. */
+export const noSolver = Object.freeze({
+  name: 'none', version: null, available: false,
+  async check() { return { result: 'unsupported' }; },
+});
+
+const MAP = Object.freeze({ sat: 'feasible-model', unsat: 'infeasible-under-model', unknown: 'unknown', timeout: 'timeout' });
+
+/**
+ * The solver a call uses. An explicit `solver` always wins. Otherwise the real z3 backend is used only when
+ * AGENTIC_SECURITY_LINEAGE_SMT=z3 is set (it loads lazily and reports `unsupported` if the optional package
+ * is missing); with nothing set the default is `noSolver`, so a default run never loads a solver.
+ */
+export function resolveSolver(solver, env = process.env) {
+  if (solver !== undefined) return solver;
+  return smtBackendEnabled(env) ? sharedZ3Solver() : noSolver;
+}
+
+/** Render the problem as SMT-LIB 2 text for a solver adapter that wants text. Opaque predicates become comments. */
+export function toSmtLib(problem) {
+  const lines = ['(set-logic ALL)'];
+  const sym = (s) => `|${String(s).replace(/\|/g, '_')}|`;
+  const num = (side) => (side.var ? sym(side.var) : String(side.const));
+  for (const v of problem.vars) lines.push(`(declare-const ${sym(v)} Int)`);
+  for (const a of problem.assertions) {
+    const alts = a.alternatives.map((alt) => {
+      const parts = alt.map((l) => {
+        if (l.t === 'num') {
+          const op = { '<': '<', '<=': '<=', '>': '>', '>=': '>=', '==': '=', '===': '=', '!=': 'distinct', '!==': 'distinct' }[l.op];
+          return `(${op} ${num(l.left)} ${num(l.right)})`;
+        }
+        if (l.t === 'eq') return `(${l.equal ? '=' : 'distinct'} ${sym(l.var)} ${JSON.stringify(l.value)})`;
+        if (l.t === 'bool') return l.truth ? 'true' : 'false';
+        return 'true';
+      });
+      return parts.length === 1 ? parts[0] : `(and ${parts.join(' ') || 'true'})`;
+    });
+    lines.push(`; ${a.ref}`);
+    lines.push(`(assert ${alts.length === 0 ? 'false' : alts.length === 1 ? alts[0] : `(or ${alts.join(' ')})`})`);
+  }
+  lines.push('(check-sat)');
+  return lines.join('\n');
+}
+
+function boundedTimeout(ms) {
+  if (ms === undefined) return SOLVER_DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(ms) || ms < 0 || ms > SOLVER_TIMEOUT_MAX_MS) return null;
+  return Math.floor(ms);
+}
+
+/**
+ * Ask a solver about the collected conditions. Always resolves; never throws.
+ *
+ * @returns {Promise<{status:string, reasons:string[], solver:object, elapsedMs:number, semanticsVersion:string, limitations:string[]}>}
+ */
+export async function checkWithSolver(collected, { solver: solverOpt, timeoutMs, signal, now = Date.now } = {}) {
+  const solver = resolveSolver(solverOpt);
+  const started = now();
+  const info = { name: solver?.name ?? 'unknown', version: solver?.version ?? null };
+  const out = (status, reasons, extra = {}) => ({
+    status, reasons, solver: info, elapsedMs: now() - started, semanticsVersion: PATH_PREDICATE_VERSION,
+    satisfiabilityNote: SATISFIABILITY_NOTE,
+    limitations: ['A solver result is relative to the encoded conditions, not to the running program.', ...(extra.limitations ?? [])],
+    ...(extra.model ? { model: extra.model } : {}),
+  });
+  const tmo = boundedTimeout(timeoutMs);
+  if (tmo === null) return out('unknown', ['invalid-timeout']);
+  if (!solver || solver.available === false || typeof solver.check !== 'function') return out('unsupported', ['no-solver']);
+  if (signal?.aborted) return out('unknown', ['cancelled']);
+
+  const ac = new AbortController();
+  let timer; let onAbort;
+  const timeoutP = new Promise((resolve) => { timer = setTimeout(() => resolve({ __timeout: true }), tmo); });
+  const cancelP = new Promise((resolve) => {
+    if (!signal) return;
+    onAbort = () => resolve({ __cancelled: true });
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+  let solverP;
+  try {
+    solverP = Promise.resolve(solver.check(toSolverProblem(collected), { signal: ac.signal }));
+  } catch {
+    clearTimeout(timer);
+    return out('unknown', ['solver-error']);
+  }
+  // A solver that settles after we gave up must not become an unhandled rejection.
+  solverP.catch(() => {});
+  try {
+    const r = await Promise.race([solverP, timeoutP, cancelP]);
+    if (r && r.__timeout) { ac.abort(); return out('timeout', ['solver-deadline']); }
+    if (r && r.__cancelled) { ac.abort(); return out('unknown', ['cancelled']); }
+    const status = isObjectWithResult(r) ? MAP[r.result] : undefined;
+    if (r?.result === 'unsupported') return out('unsupported', ['solver-declined', ...(typeof r.reason === 'string' ? [r.reason] : [])]);
+    if (!status) return out('unknown', ['solver-malformed']);
+    const why = typeof r.reason === 'string' ? [r.reason] : [];
+    return out(status, [`solver-${r.result}`, ...why], r.result === 'sat' && r.model && typeof r.model === 'object' ? { model: r.model } : {});
+  } catch {
+    return out('unknown', ['solver-error']);
+  } finally {
+    clearTimeout(timer);
+    if (signal && onAbort) signal.removeEventListener('abort', onAbort);
+  }
+}
+
+function isObjectWithResult(r) { return typeof r === 'object' && r !== null && typeof r.result === 'string'; }
+
+/**
+ * The full decision: abstract domains first, then the solver only when the abstract answer is `unknown`.
+ * The abstract answer stays on the result, so a timeout or an unsupported solver never erases what the
+ * cheap model already established, and the finding stays visible as unknown/partial.
+ */
+export async function evaluateWitnessConditionsAsync(collected, o = {}) {
+  const abstract = evaluateWitnessConditions(collected, o);
+  const consultFeasible = o.consultOnFeasible ?? smtBackendEnabled();
+  const refine = abstract.status === 'feasible-model' && consultFeasible && abstract.clauseRefs.length > 0;
+  if (abstract.status !== 'unknown' && !refine) return { ...abstract, abstractStatus: abstract.status, solverConsulted: false };
+  const s = await checkWithSolver(collected, o);
+  const kept = { ...abstract, abstractStatus: abstract.status };
+  // Branch arms of one branch inside a loop may belong to different iterations. The solver's problem carries no
+  // iteration structure, so its `unsat` there is not evidence of infeasibility: the answer stays `unknown`.
+  const loopArms = abstract.reasons.includes('branch-arms-in-loop');
+  if (refine) {
+    // On a feasible-model answer ONLY a solver unsat changes anything; every other outcome keeps the abstract result.
+    if (s.status === 'infeasible-under-model' && !loopArms) return unsatResult(abstract, s);
+    return { ...kept, solverConsulted: s.status !== 'unsupported', solver: s.solver, solverStatus: s.status, elapsedMs: s.elapsedMs };
+  }
+  if (s.status === 'unsupported') return { ...kept, solverConsulted: false, solver: s.solver, solverStatus: 'unsupported' };
+  if (s.status === 'timeout') {
+    return { ...kept, status: 'timeout', reasons: [...abstract.reasons, 'solver-deadline'], solverConsulted: true, solver: s.solver, solverStatus: 'timeout', elapsedMs: s.elapsedMs };
+  }
+  if (s.status === 'infeasible-under-model' && loopArms) {
+    return { ...kept, solverConsulted: true, solver: s.solver, solverStatus: 'unknown', reasons: [...abstract.reasons, 'solver-unsat-not-trusted-in-loop'], elapsedMs: s.elapsedMs };
+  }
+  if (s.status === 'unknown') {
+    return { ...kept, solverConsulted: true, solver: s.solver, solverStatus: 'unknown', reasons: [...abstract.reasons, ...s.reasons], elapsedMs: s.elapsedMs };
+  }
+  if (s.status === 'infeasible-under-model') return unsatResult(abstract, s);
+  return {
+    ...kept, status: s.status, reasons: s.reasons, solverConsulted: true, solver: s.solver, solverStatus: s.status,
+    limitations: [...abstract.limitations, ...s.limitations], elapsedMs: s.elapsedMs, contradiction: null,
+  };
+}
+
+function unsatResult(abstract, s) {
+  return {
+    ...abstract, status: 'infeasible-under-model', reasons: s.reasons, abstractStatus: abstract.status, solverConsulted: true, solver: s.solver, solverStatus: s.status,
+    limitations: [...abstract.limitations, ...s.limitations], elapsedMs: s.elapsedMs,
+    contradiction: { kind: 'solver-unsat', refs: abstract.clauseRefs },
+  };
+}

package/src/lineage/smt-z3-backend.js

@@ -0,0 +1,294 @@
+//
+// smt-z3-backend.js: a real solver for the SMT orchestrator (DAG-04, R04.3 / R04.4).
+//
+// The orchestrator (smt-orchestrator.js) is built against an injectable backend object
+//   { name, version?, available?, check(problem, { signal }) -> Promise<{ result, reason? }> }.
+// This module is that backend, on top of the optional `z3-solver` package. Rules it keeps:
+//
+//   * LAZY and OPTIONAL. `z3-solver` is imported on the first query, never at module load, and never by a
+//     default scan (the whole path is behind `pathEvidence` and `AGENTIC_SECURITY_LINEAGE_SMT=z3`). A package
+//     that is not installed, fails to load or fails to initialise makes the backend `unsupported`
+//     (`available === false`): never a crash and never an `unsat`.
+//   * ONLY A VERIFIED ENCODING MAY SAY `unsat`. `encodeProblem` refuses (result `unknown`, with a reason) any
+//     problem it cannot translate faithfully: a variable used with two sorts, a number SMT-LIB cannot write
+//     exactly, an unknown literal or operator. An opaque (unmodeled) predicate is encoded as `true`, which can
+//     only make the formula LARGER, so `unsat` stays sound; for the same reason a `sat` that leaned on an opaque
+//     predicate is reported `unknown`, not as a model.
+//   * Numbers are Real, not Int, so a comparison such as `0.5 < x < 1` is not wrongly called infeasible.
+//   * BOUNDED. A per-query timeout (`timeoutMs`), a process memory cap (`memoryMb`, Z3's `memory_max_size`),
+//     and the orchestrator's own deadline racing the query. A timeout is `timeout`, memory exhaustion and any
+//     other solver failure is `unknown`. None of them ever reduces anything.
+//   * DETERMINISTIC. Variables are renamed v0..vN in sorted order, assertions keep their order, the solver
+//     random seed is fixed, and the SMT-LIB text is the cache key. Only definitive answers (`sat`, `unsat`)
+//     are cached; a timeout depends on the machine and is not.
+//
+// `unsat` here means "the encoded conditions cannot hold together", relative to the model stated in
+// path-predicates.js. It is not a proof about the running program, and `sat` never implies exploitability.
+
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const Z3_BACKEND_VERSION = 'smt-z3/1';
+export const Z3_DEFAULT_TIMEOUT_MS = 1000;
+export const Z3_DEFAULT_MEMORY_MB = 256;
+const CACHE_MAX = 256;
+const HARD_GRACE_MS = 500;
+// 1e21 and 1e-7 are where String(number) switches to exponent form, which SMT-LIB has no literal for.
+const MAX_PLAIN = 1e15;
+
+// ---- encoding ------------------------------------------------------------------------------------------
+
+const OPS = { '<': '<', '<=': '<=', '>': '>', '>=': '>=', '==': '=', '===': '=', '!=': 'distinct', '!==': 'distinct' };
+
+/** A finite JS number as an SMT-LIB Real literal, or null when it cannot be written exactly in plain decimal. */
+function realLiteral(n) {
+  if (typeof n !== 'number' || !Number.isFinite(n) || Math.abs(n) >= MAX_PLAIN) return null;
+  const s = String(n);
+  if (/e/i.test(s)) return null;
+  const abs = Math.abs(n);
+  const body = Number.isInteger(abs) ? `${abs}.0` : String(abs);
+  return n < 0 ? `(- ${body})` : body;
+}
+
+/** A JS string as an SMT-LIB 2.6 string literal: only printable ASCII is written raw. */
+function stringLiteral(s) {
+  let out = '';
+  for (const ch of String(s)) {
+    const cp = ch.codePointAt(0);
+    if (ch === '"') out += '""';
+    else if (cp >= 0x20 && cp <= 0x7e && ch !== '\\') out += ch;
+    else out += `\\u{${cp.toString(16)}}`;
+  }
+  return `"${out}"`;
+}
+
+/**
+ * Translate the solver-neutral problem (path-predicates.js `toSolverProblem`) into SMT-LIB 2 text.
+ *
+ * @returns {{ok:true, text:string, digest:string, unmodeled:number, sorts:object, literals:number, assertions:number}
+ *   | {ok:false, reason:string}}
+ */
+export function encodeProblem(problem) {
+  if (!problem || typeof problem !== 'object' || !Array.isArray(problem.assertions) || !Array.isArray(problem.vars)) {
+    return { ok: false, reason: 'encoding-unverified:malformed-problem' };
+  }
+  const sorts = new Map();
+  const claim = (v, sort) => {
+    if (typeof v !== 'string') return false;
+    if (sorts.has(v) && sorts.get(v) !== sort) return false;
+    sorts.set(v, sort);
+    return true;
+  };
+  const constants = problem.constants && typeof problem.constants === 'object' ? problem.constants : {};
+  let literals = 0; let unmodeled = 0;
+  const alt = [];
+  for (const a of problem.assertions) {
+    if (!a || !Array.isArray(a.alternatives)) return { ok: false, reason: 'encoding-unverified:malformed-assertion' };
+    for (const conj of a.alternatives) {
+      if (!Array.isArray(conj)) return { ok: false, reason: 'encoding-unverified:malformed-assertion' };
+      for (const l of conj) {
+        literals += 1;
+        if (!l || typeof l !== 'object') return { ok: false, reason: 'encoding-unverified:malformed-literal' };
+        if (l.t === 'num') {
+          if (!OPS[l.op]) return { ok: false, reason: 'encoding-unverified:unknown-operator' };
+          for (const s of [l.left, l.right]) {
+            if (!s || typeof s !== 'object') return { ok: false, reason: 'encoding-unverified:malformed-literal' };
+            if ('var' in s) { if (!claim(s.var, 'Real')) return { ok: false, reason: 'encoding-unverified:sort-conflict' }; }
+            else if (realLiteral(s.const) === null) return { ok: false, reason: 'encoding-unverified:number-not-encodable' };
+          }
+        } else if (l.t === 'eq') {
+          if (typeof l.value !== 'string') return { ok: false, reason: 'encoding-unverified:non-string-equality' };
+          if (!claim(l.var, 'String')) return { ok: false, reason: 'encoding-unverified:sort-conflict' };
+        } else if (l.t === 'bool') {
+          if (!claim(l.var, 'Bool')) return { ok: false, reason: 'encoding-unverified:sort-conflict' };
+        } else if (l.t === 'opaque') {
+          unmodeled += 1;
+        } else {
+          return { ok: false, reason: 'encoding-unverified:unknown-literal' };
+        }
+      }
+    }
+  }
+  const constEntries = [];
+  for (const [k, v] of Object.entries(constants)) {
+    if (!sorts.has(k)) continue; // a constant for a variable no condition reads constrains nothing
+    if (typeof v === 'number') {
+      if (!claim(k, 'Real')) return { ok: false, reason: 'encoding-unverified:sort-conflict' };
+      if (realLiteral(v) === null) return { ok: false, reason: 'encoding-unverified:number-not-encodable' };
+    } else if (typeof v === 'string') {
+      if (!claim(k, 'String')) return { ok: false, reason: 'encoding-unverified:sort-conflict' };
+    } else return { ok: false, reason: 'encoding-unverified:constant-type' };
+    constEntries.push([k, v]);
+  }
+  // Rename to v0..vN in sorted order: no escaping hazard, and two distinct names can never merge.
+  const names = [...sorts.keys()].sort();
+  const id = new Map(names.map((n, i) => [n, `v${i}`]));
+  const lines = ['(set-logic ALL)'];
+  for (const n of names) lines.push(`(declare-const ${id.get(n)} ${sorts.get(n)})`);
+  const side = (s) => ('var' in s ? id.get(s.var) : realLiteral(s.const));
+  let asserted = 0;
+  for (const a of problem.assertions) {
+    const alts = a.alternatives.map((conj) => {
+      const parts = conj.map((l) => {
+        if (l.t === 'num') return `(${OPS[l.op]} ${side(l.left)} ${side(l.right)})`;
+        if (l.t === 'eq') return l.equal ? `(= ${id.get(l.var)} ${stringLiteral(l.value)})` : `(distinct ${id.get(l.var)} ${stringLiteral(l.value)})`;
+        if (l.t === 'bool') return l.truth ? id.get(l.var) : `(not ${id.get(l.var)})`;
+        return 'true'; // opaque: no constraint
+      });
+      return parts.length === 0 ? 'true' : parts.length === 1 ? parts[0] : `(and ${parts.join(' ')})`;
+    });
+    lines.push(`(assert ${alts.length === 0 ? 'false' : alts.length === 1 ? alts[0] : `(or ${alts.join(' ')})`})`);
+    asserted += 1;
+  }
+  for (const [k, v] of constEntries.sort((x, y) => (x[0] < y[0] ? -1 : 1))) {
+    lines.push(`(assert (= ${id.get(k)} ${typeof v === 'number' ? realLiteral(v) : stringLiteral(v)}))`);
+    asserted += 1;
+  }
+  lines.push('(check-sat)');
+  const text = lines.join('\n');
+  // Structural self-check of the translation: every assertion of the problem became exactly one assert.
+  const emitted = lines.filter((l) => l.startsWith('(assert ')).length;
+  if (emitted !== problem.assertions.length + constEntries.length || asserted !== emitted) {
+    return { ok: false, reason: 'encoding-unverified:assertion-count' };
+  }
+  return {
+    ok: true, text, unmodeled, literals, assertions: emitted,
+    sorts: Object.fromEntries(names.map((n) => [n, sorts.get(n)])),
+    digest: crypto.createHash('sha256').update(text).digest('hex').slice(0, 16),
+  };
+}
+
+// ---- the backend ---------------------------------------------------------------------------------------
+
+/**
+ * The default loader. Loaded through a createRequire call at first use, the way the optional tree-sitter
+ * runtime is: a bundler keeps it external, and a build without the package fails here (reported as
+ * unsupported by the caller), never at start-up.
+ */
+async function defaultLoader() {
+  return require('z3-solver');
+}
+
+/**
+ * Build a z3 backend.
+ *
+ * @param {object} [o]
+ * @param {number} [o.timeoutMs]   per-query solver timeout (Z3 `timeout`)
+ * @param {number} [o.memoryMb]    process memory cap handed to Z3 (`memory_max_size`)
+ * @param {()=>Promise<object>} [o.loader]  returns the `z3-solver` module; injected by tests
+ */
+export function createZ3Solver({ timeoutMs = Z3_DEFAULT_TIMEOUT_MS, memoryMb = Z3_DEFAULT_MEMORY_MB, loader = defaultLoader } = {}) {
+  const state = { initP: null, failed: null, api: null, ctx: null, version: null, queue: Promise.resolve() };
+  const cache = new Map();
+  const stats = { queries: 0, cacheHits: 0, loads: 0 };
+
+  function init() {
+    if (state.initP) return state.initP;
+    state.initP = (async () => {
+      stats.loads += 1;
+      const mod = await loader();
+      const initFn = mod?.init ?? mod?.default?.init;
+      if (typeof initFn !== 'function') throw new Error('z3-solver has no init()');
+      const api = await initFn();
+      try { api.Z3.global_param_set('memory_max_size', String(memoryMb)); } catch { /* an older build without the knob */ }
+      state.api = api;
+      state.ctx = api.Context('lineage-smt');
+      try { state.version = api.getVersionString?.() ?? null; } catch { state.version = null; }
+      return state;
+    })().catch((e) => {
+      state.failed = String(e?.code || e?.name || 'load-error');
+      state.initP = null;
+      return null;
+    });
+    return state.initP;
+  }
+
+  async function run(enc, signal) {
+    const ctx = state.ctx;
+    const solver = new ctx.Solver();
+    let abortHook;
+    try {
+      solver.set('timeout', timeoutMs);
+      try { solver.set('random_seed', 0); } catch { /* not a parameter of this build */ }
+      solver.fromString(enc.text);
+      if (signal) {
+        abortHook = () => { try { state.api.Z3.interrupt(ctx.ptr); } catch { /* best effort */ } };
+        signal.addEventListener('abort', abortHook, { once: true });
+      }
+      // Z3 honours `timeout`, but a wedged wasm call must not hold the queue forever: past a grace period the
+      // backend gives up on this context and reports itself unavailable from then on.
+      let hardTimer;
+      const hung = new Promise((resolve) => { hardTimer = setTimeout(() => resolve('hung'), timeoutMs + HARD_GRACE_MS); });
+      const verdict = await Promise.race([solver.check(), hung]).finally(() => clearTimeout(hardTimer));
+      if (verdict === 'hung') {
+        try { state.api.Z3.interrupt(ctx.ptr); } catch { /* best effort */ }
+        state.failed = 'hung';
+        return { result: 'timeout', reason: 'z3-hung' };
+      }
+      if (verdict === 'unsat') return { result: 'unsat' };
+      if (verdict === 'sat') return { result: 'sat' };
+      const why = String(solver.reasonUnknown?.() ?? '');
+      if (/timeout/i.test(why)) return { result: 'timeout', reason: 'z3-timeout' };
+      if (/memout|memory/i.test(why)) return { result: 'unknown', reason: 'z3-memory' };
+      if (/cancel/i.test(why)) return { result: 'unknown', reason: 'z3-cancelled' };
+      return { result: 'unknown', reason: 'z3-unknown' };
+    } finally {
+      if (abortHook && signal) signal.removeEventListener('abort', abortHook);
+    }
+  }
+
+  const backend = {
+    name: 'z3',
+    get version() { return state.version ? `${state.version}+${Z3_BACKEND_VERSION}` : Z3_BACKEND_VERSION; },
+    /** False only after a load/initialisation failure; true (unknown yet) before the first query. */
+    get available() { return state.failed === null; },
+    get loadFailure() { return state.failed; },
+    stats() { return { ...stats, cacheSize: cache.size }; },
+    /** Never throws. `unsupported` when z3 is missing, `unknown` when the encoding cannot be verified. */
+    async check(problem, { signal } = {}) {
+      stats.queries += 1;
+      const enc = encodeProblem(problem);
+      if (!enc.ok) return { result: 'unknown', reason: enc.reason };
+      const key = `${timeoutMs}|${enc.text}`;
+      const hit = cache.get(key);
+      if (hit) { stats.cacheHits += 1; cache.delete(key); cache.set(key, hit); return finish(hit, enc, true); }
+      const ready = await init();
+      if (!ready || state.failed) return { result: 'unsupported', reason: `z3-unavailable:${state.failed}` };
+      // One query at a time: the wasm context is single-threaded.
+      const turn = state.queue.then(() => run(enc, signal)).catch(() => ({ result: 'unknown', reason: 'z3-error' }));
+      state.queue = turn.then(() => {}, () => {});
+      const raw = await turn;
+      if (raw.result === 'sat' || raw.result === 'unsat') {
+        cache.set(key, raw);
+        if (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value);
+      }
+      return finish(raw, enc, false);
+    },
+    /** Release the wasm worker threads. The next query re-initialises. */
+    async shutdown() {
+      const api = state.api;
+      state.initP = null; state.api = null; state.ctx = null;
+      if (!api) return;
+      try { const kt = (await loader())?.killThreads ?? null; if (kt && api.em) kt(api.em); } catch { /* nothing to release */ }
+    },
+  };
+  return backend;
+}
+
+function finish(raw, enc, cached) {
+  // A model that leaned on an unmodeled predicate says nothing about the real conditions.
+  if (raw.result === 'sat' && enc.unmodeled > 0) return { result: 'unknown', reason: 'sat-with-unmodeled-predicates', encodingDigest: enc.digest, cached };
+  return { ...raw, encodingDigest: enc.digest, cached };
+}
+
+let _shared = null;
+/** The process-wide backend used when AGENTIC_SECURITY_LINEAGE_SMT=z3. */
+export function sharedZ3Solver() {
+  if (!_shared) _shared = createZ3Solver();
+  return _shared;
+}
+export function smtBackendEnabled(env = process.env) {
+  return env.AGENTIC_SECURITY_LINEAGE_SMT === 'z3';
+}