@clear-capabilities/agentic-security-scanner 0.74.0

package/src/dataflow/incremental.js

@@ -0,0 +1,229 @@
+// Differential / incremental taint (P4.3).
+//
+// Today every scan re-analyzes every file. On a 100k-LoC monorepo the
+// deep-engine pass takes 4-8 minutes. PR-scoped re-analysis should be
+// 10-50× faster.
+//
+// Strategy:
+//   1. Persist a SHA-256 of each file's POST-COMMENT-STRIP source under
+//      `.agentic-security/incremental/files.json`.
+//   2. Persist each function's SUMMARY (returnTainted / mutatedParams /
+//      taintedGlobals) keyed by `qid` under
+//      `.agentic-security/incremental/summaries.json`.
+//   3. On the next scan, diff the file-hash map. For unchanged files,
+//      seed the SummaryCache with the persisted summaries.
+//   4. For CHANGED files, invalidate their qids' summaries AND the
+//      summaries of any function that previously called into them
+//      (back-pointer set persisted alongside summaries).
+//
+// Safety:
+//   - The cache invalidates on rule-pack version change (any change to
+//     `catalog.js` bumps the rules.lock.json digest).
+//   - The cache invalidates on scanner version change.
+//   - On any inconsistency (truncated file, JSON parse error), the cache
+//     is dropped and we fall back to a full scan.
+//
+// This module is purely the persistence + invalidation layer. The engine
+// is responsible for calling `seedSummaryCache` / `recordSummary` /
+// `commitIncrementalState`.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+
+const STATE_DIR = '.agentic-security/incremental';
+const FILES_PATH = 'files.json';
+const SUMMARIES_PATH = 'summaries.json';
+const VERSION_PATH = 'version.json';
+const MAX_PERSISTED_SUMMARIES = 50000;
+
+/** Compute the content hash used for file-equality detection. */
+export function hashFileContent(stripped) {
+  return crypto.createHash('sha256').update(stripped || '').digest('hex');
+}
+
+/** Read the persisted state. Returns a fresh empty state on any error. */
+export function readIncrementalState(projectRoot) {
+  const dir = path.join(projectRoot, STATE_DIR);
+  try {
+    const versionFp = path.join(dir, VERSION_PATH);
+    if (!fs.existsSync(versionFp)) return _emptyState();
+    const v = JSON.parse(fs.readFileSync(versionFp, 'utf8'));
+    return {
+      version: v,
+      files: _readJsonOrEmpty(path.join(dir, FILES_PATH), {}),
+      summaries: _readJsonOrEmpty(path.join(dir, SUMMARIES_PATH), {}),
+    };
+  } catch (_e) {
+    return _emptyState();
+  }
+}
+
+function _emptyState() {
+  return { version: null, files: {}, summaries: {} };
+}
+
+function _readJsonOrEmpty(fp, fallback) {
+  try {
+    if (!fs.existsSync(fp)) return fallback;
+    return JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch (_e) {
+    return fallback;
+  }
+}
+
+/**
+ * Validate persisted state against the current rule-pack + scanner version.
+ * Returns `{ valid: boolean, reason?: string }`.
+ */
+export function validateIncrementalState(state, currentVersion) {
+  if (!state || !state.version) return { valid: false, reason: 'no prior state' };
+  if (!currentVersion) return { valid: false, reason: 'no current version' };
+  if (state.version.scanner !== currentVersion.scanner) return { valid: false, reason: 'scanner version changed' };
+  if (state.version.rules  !== currentVersion.rules)   return { valid: false, reason: 'rule-pack changed' };
+  return { valid: true };
+}
+
+/**
+ * Diff the previous file-hash map against the current scan's hashes.
+ * Returns:
+ *   { unchanged: [filePath, ...], changed: [filePath, ...], added: [...], removed: [...] }
+ */
+export function diffFileHashes(prevFiles, currentHashes) {
+  const unchanged = [];
+  const changed = [];
+  const added = [];
+  const removed = [];
+  for (const [fp, h] of Object.entries(currentHashes)) {
+    if (!(fp in prevFiles)) added.push(fp);
+    else if (prevFiles[fp] === h) unchanged.push(fp);
+    else changed.push(fp);
+  }
+  for (const fp of Object.keys(prevFiles)) {
+    if (!(fp in currentHashes)) removed.push(fp);
+  }
+  return { unchanged, changed, added, removed };
+}
+
+/**
+ * Decide which previously-persisted summaries are still safe to reuse.
+ *
+ *   summaries: persisted summary map { qid: summary }
+ *   callerOfQid: persisted reverse-call-graph { qid: [callerQid, ...] }
+ *   changedQids: Set of qids whose source files changed
+ *
+ * Returns: { reusable: Set<qid>, invalidated: Set<qid> }
+ */
+export function pickReusableSummaries(summaries, callerOfQid, changedQids) {
+  const invalidated = new Set();
+  // Seed with directly-changed qids.
+  for (const q of changedQids) invalidated.add(q);
+  // BFS via reverse call graph — invalidate every transitive caller.
+  const stack = [...changedQids];
+  while (stack.length) {
+    const q = stack.pop();
+    const callers = callerOfQid?.[q] || [];
+    for (const c of callers) {
+      if (!invalidated.has(c)) {
+        invalidated.add(c);
+        stack.push(c);
+      }
+    }
+  }
+  const reusable = new Set();
+  for (const q of Object.keys(summaries || {})) {
+    if (!invalidated.has(q)) reusable.add(q);
+  }
+  return { reusable, invalidated };
+}
+
+/** Seed a SummaryCache instance from persisted summaries. */
+export function seedSummaryCache(summaryCache, persisted, reusableQids) {
+  if (!summaryCache || !persisted) return 0;
+  let n = 0;
+  for (const qid of reusableQids) {
+    const s = persisted[qid];
+    if (!s) continue;
+    // Reconstitute Set fields (JSON dropped them).
+    const summary = {
+      returnTainted: !!s.returnTainted,
+      mutatedParams: new Set(s.mutatedParams || []),
+      taintedGlobals: new Set(s.taintedGlobals || []),
+      findings: Array.isArray(s.findings) ? s.findings : [],
+    };
+    // Use the bottom taint-state key — these are summaries that DON'T depend
+    // on entry taint state (e.g., pure functions). Higher-fidelity reuse
+    // would require persisting the entry-state hash too; deferred.
+    summaryCache.set(qid, new Set(), summary, null);
+    n++;
+  }
+  return n;
+}
+
+/**
+ * Serialize a SummaryCache for persistence. Only persists summaries with
+ * `_persistable: true` (set by the engine when the summary is independent
+ * of an entry taint-state — typically pure functions or terminal sinks).
+ *
+ * Returns a plain object `{ qid: summary }` safe for JSON.stringify.
+ */
+export function serializeSummaries(summaryCache) {
+  const out = {};
+  if (!summaryCache || !summaryCache._cache) return out;
+  let count = 0;
+  for (const [key, summary] of summaryCache._cache) {
+    if (count >= MAX_PERSISTED_SUMMARIES) break;
+    if (!summary || summary._budgetExceeded || summary._recursive) continue;
+    const qid = key.split('::')[0];
+    if (!qid) continue;
+    out[qid] = {
+      returnTainted: !!summary.returnTainted,
+      mutatedParams: [...(summary.mutatedParams || [])],
+      taintedGlobals: [...(summary.taintedGlobals || [])],
+      findings: Array.isArray(summary.findings) ? summary.findings.slice(0, 50) : [],
+    };
+    count++;
+  }
+  return out;
+}
+
+/**
+ * Commit incremental state to disk. Idempotent — safe to call from anywhere.
+ *
+ *   state.files       { filepath: sha256 }
+ *   state.summaries   { qid: summary }      (output of serializeSummaries)
+ *   state.callers     { qid: [callerQid] }  (reverse call-graph)
+ *   currentVersion    { scanner, rules }
+ */
+export function commitIncrementalState(projectRoot, state, currentVersion) {
+  if (!projectRoot) return false;
+  const dir = path.join(projectRoot, STATE_DIR);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, VERSION_PATH), JSON.stringify(currentVersion, null, 2));
+    fs.writeFileSync(path.join(dir, FILES_PATH), JSON.stringify(state.files || {}, null, 2));
+    const payload = {
+      summaries: state.summaries || {},
+      callers: state.callers || {},
+    };
+    fs.writeFileSync(path.join(dir, SUMMARIES_PATH), JSON.stringify(payload));
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+/** Drop persisted state — used when a version mismatch is detected. */
+export function dropIncrementalState(projectRoot) {
+  const dir = path.join(projectRoot, STATE_DIR);
+  try {
+    if (!fs.existsSync(dir)) return true;
+    for (const fn of [VERSION_PATH, FILES_PATH, SUMMARIES_PATH]) {
+      const fp = path.join(dir, fn);
+      if (fs.existsSync(fp)) fs.unlinkSync(fp);
+    }
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}

package/src/dataflow/index.js

@@ -0,0 +1,181 @@
+// Layer 2 entry point.
+import { runTaintEngine } from './engine.js';
+import { CATALOG, matchSource, matchSinkOrSanitizer, _catalogSize } from './catalog.js';
+import { applyPathFeasibility } from './path-feasibility.js';
+import { SummaryCache, entryStateFromCall } from './summaries.js';
+import { rhsReachableFunctions, shouldAnalyzeUnderRhs } from './tabulation.js';
+import { annotateBackwardSlices } from './backward.js';
+import {
+  readIncrementalState, validateIncrementalState, diffFileHashes,
+  hashFileContent, pickReusableSummaries, seedSummaryCache,
+  serializeSummaries, commitIncrementalState,
+} from './incremental.js';
+import { buildPointsTo } from './points-to.js';
+import { annotateSoftTaint } from './soft-taint.js';
+import { runIfdsTaintEngine } from './ifds.js';
+import { proveExploits } from './exploit-prover.js';
+import { applyStubAwareFilter } from './stub-aware-filter.js';
+import { loadProjectStubs } from '../ir/type-stubs.js';
+
+export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
+  // Path-feasibility pass over every function before the taint walk.
+  let totalPruned = 0;
+  for (const fn of callGraph.functions.values()) {
+    const r = applyPathFeasibility(fn);
+    totalPruned += r.pruned;
+  }
+  // P2.1 — RHS-lite reachability slice. When AGENTIC_SECURITY_RHS=1 the
+  // engine narrows analysis to sink-reachable functions. Default OFF
+  // because it changes the finding-set composition.
+  if (process.env.AGENTIC_SECURITY_RHS === '1') {
+    const ctx = rhsReachableFunctions(perFileIR, callGraph);
+    if (ctx.reachable) {
+      opts = { ...opts, _rhsReachable: ctx.reachable, _rhsCheck: shouldAnalyzeUnderRhs };
+    }
+  }
+  // v0.69 — cross-scan incremental cache (AGENTIC_SECURITY_INCREMENTAL=1).
+  // Read persisted state, seed the SummaryCache with summaries from files
+  // whose content hasn't changed, then hand it to runTaintEngine. After,
+  // serialize the cache and commit to disk.
+  const incrementalEnabled = process.env.AGENTIC_SECURITY_INCREMENTAL === '1';
+  let preSeededCache = null;
+  let priorState = null;
+  let currentFileHashes = null;
+  if (incrementalEnabled && opts.scanRoot && opts.fileContents) {
+    priorState = readIncrementalState(opts.scanRoot);
+    const currentVersion = {
+      scanner: opts.scannerVersion || 'unknown',
+      rules: opts.rulesDigest || `catalog:${_catalogSize()}`,
+    };
+    const valid = validateIncrementalState(priorState, currentVersion);
+    if (valid.valid) {
+      currentFileHashes = {};
+      for (const [fp, content] of Object.entries(opts.fileContents)) {
+        currentFileHashes[fp] = hashFileContent(content);
+      }
+      const diff = diffFileHashes(priorState.files || {}, currentFileHashes);
+      const changedQids = new Set();
+      // Map a changed file to the qids it owns. perFileIR exposes file→fns.
+      for (const fp of [...diff.changed, ...diff.added, ...diff.removed]) {
+        const ir = perFileIR[fp];
+        if (!ir) continue;
+        for (const fn of (ir.functions || [])) changedQids.add(fn.qid);
+      }
+      const persistedPayload = (priorState.summaries && priorState.summaries.summaries) || priorState.summaries || {};
+      const callerOfQid = (priorState.summaries && priorState.summaries.callers) || {};
+      const { reusable } = pickReusableSummaries(persistedPayload, callerOfQid, changedQids);
+      preSeededCache = new SummaryCache();
+      const seededN = seedSummaryCache(preSeededCache, persistedPayload, reusable);
+      preSeededCache._incrementalSeeded = seededN;
+      preSeededCache._incrementalReusable = reusable.size;
+    } else {
+      // Stale → caller should drop; we just don't seed.
+      priorState = null;
+    }
+  }
+  // v0.70 #2 — Steensgaard points-to / alias analysis. Built once before
+  // the worklist, passed via opts so the engine can resolve aliased
+  // mutations (`let a = obj; a.x = tainted; sink(obj.x)`).
+  let pointsToGraph = null;
+  if (process.env.AGENTIC_SECURITY_POINTS_TO === '1') {
+    try { pointsToGraph = buildPointsTo(perFileIR, callGraph); }
+    catch { pointsToGraph = null; }
+  }
+  // v0.71 #3 — IFDS alternative analyzer (AGENTIC_SECURITY_IFDS=1).
+  // Runs the formal Reps-Horwitz-Sagiv tabulation in parallel with the
+  // worklist engine. We MERGE findings — the IFDS solver may catch
+  // context-sensitive flows the k=2 cache joined out. Deduped by sink+line.
+  let findings = runTaintEngine(perFileIR, callGraph, {
+    ...opts,
+    summaryCache: preSeededCache || undefined,
+    _pointsTo: pointsToGraph || undefined,
+  });
+  if (process.env.AGENTIC_SECURITY_IFDS === '1') {
+    try {
+      const ifdsFindings = runIfdsTaintEngine(perFileIR, callGraph, opts);
+      const existing = new Set(findings.map(f => `${f.file}:${f.line}:${f.sink?.label || ''}`));
+      for (const f of ifdsFindings) {
+        const key = `${f.file}:${f.line}:${f.sink?.label || ''}`;
+        if (!existing.has(key)) findings.push(f);
+      }
+    } catch { /* IFDS failure should not fail the scan */ }
+  }
+  for (const f of findings) f._pathFeasibilityPruned = totalPruned;
+  if (preSeededCache) {
+    Object.defineProperty(findings, '_incrementalStats', {
+      value: {
+        seeded: preSeededCache._incrementalSeeded || 0,
+        reusable: preSeededCache._incrementalReusable || 0,
+      },
+      enumerable: false,
+    });
+  }
+  // P1.4 — backward slice (opt-in via AGENTIC_SECURITY_BACKWARD_SLICE=1).
+  if (process.env.AGENTIC_SECURITY_BACKWARD_SLICE === '1') {
+    findings = annotateBackwardSlices(findings, perFileIR, callGraph);
+  }
+  // v0.70 #6 — probabilistic / soft taint. Walks each finding's trace +
+  // chain, multiplies (1 - effectiveness) across sanitizers, demotes
+  // below-threshold findings to lower severity (never drops).
+  if (process.env.AGENTIC_SECURITY_SOFT_TAINT === '1') {
+    findings = annotateSoftTaint(findings);
+  }
+  // v0.73 — type-stub-aware filter. Consults the project's TS/.pyi/JAR
+  // stub signatures (loaded by ir/type-stubs.js when AGENTIC_SECURITY_TYPE_STUBS=1).
+  // If a finding's source type is provably non-stringy (number, boolean,
+  // Date, RegExp) AND the sink class can't be triggered by that type,
+  // demote the finding's severity.
+  if (process.env.AGENTIC_SECURITY_TYPE_STUBS === '1' && opts.scanRoot) {
+    try {
+      const stubs = loadProjectStubs(opts.scanRoot);
+      findings = applyStubAwareFilter(findings, stubs);
+    } catch { /* stub load failure must not fail the scan */ }
+  }
+  // v0.71 #9 — symbolic exploit proof. For each finding, run the SMT-lite
+  // infeasibility check (and optionally Z3 when AGENTIC_SECURITY_SYMEXEC_Z3=1
+  // AND z3-solver is installed). Attach _exploitInput / _provenUnreachable.
+  if (process.env.AGENTIC_SECURITY_SYMEXEC === '1') {
+    try {
+      const useZ3 = process.env.AGENTIC_SECURITY_SYMEXEC_Z3 === '1';
+      // proveExploits returns a Promise; we keep the deep pass synchronous
+      // by not awaiting — the prover runs eagerly with z3=null (sync path).
+      // For Z3 path, callers should use the async runDeepAnalysisAsync (TBD).
+      if (!useZ3) {
+        // Synchronous SMT-lite branch.
+        // proveExploits awaits z3 only when opts.useZ3=true; otherwise it
+        // returns synchronously through the same async function (Promise of
+        // sync result). We tolerate the Promise here since findings are
+        // mutated in place.
+        const p = proveExploits(findings, { useZ3: false });
+        if (p && typeof p.then === 'function') p.catch(() => {});
+      }
+    } catch { /* prover failure should not fail the scan */ }
+  }
+  // v0.69 — commit incremental state after a successful scan.
+  if (incrementalEnabled && opts.scanRoot && currentFileHashes) {
+    const cache = findings._summaryCache;
+    const summaries = cache ? serializeSummaries(cache) : {};
+    // Reverse call-graph (qid → callers) — derive from callGraph.
+    const callers = {};
+    if (callGraph && callGraph.functions) {
+      for (const fn of callGraph.functions.values()) {
+        if (!Array.isArray(fn.calls)) continue;
+        for (const callee of fn.calls) {
+          if (!callers[callee]) callers[callee] = [];
+          callers[callee].push(fn.qid);
+        }
+      }
+    }
+    commitIncrementalState(opts.scanRoot, {
+      files: currentFileHashes,
+      summaries,
+      callers,
+    }, {
+      scanner: opts.scannerVersion || 'unknown',
+      rules: opts.rulesDigest || `catalog:${_catalogSize()}`,
+    });
+  }
+  return findings;
+}
+
+export { runTaintEngine, CATALOG, matchSource, matchSinkOrSanitizer, _catalogSize, applyPathFeasibility, SummaryCache, entryStateFromCall, rhsReachableFunctions, shouldAnalyzeUnderRhs, annotateBackwardSlices };

package/src/dataflow/numeric-domain.js

@@ -0,0 +1,192 @@
+// Numeric range / abstract integer domain (P3.2).
+//
+// Today's path-feasibility module (`path-feasibility.js`) prunes branches
+// only when the condition folds to a literal constant. This module adds an
+// abstract domain over INTEGER VALUES so we can reason about ranges:
+//
+//   const idx = 5;
+//   if (idx < 0) return;                  // ← provably dead
+//   if (idx >= arr.length) return;        // ← provably dead if arr.length ≥ 6
+//   arr[idx]                              // ← bounds-check-safe
+//
+//   const idx = parseInt(req.query.i);
+//   if (idx < 0 || idx >= 100) return;
+//   table[idx]                            // ← idx narrowed to [0,99]
+//
+// The abstract domain is the classical interval lattice with TOP / BOTTOM:
+//
+//   TOP   ≡ (-∞, +∞)   — no information
+//   range(lo, hi)      — closed interval; lo ≤ hi; lo,hi ∈ ℤ ∪ {-∞, +∞}
+//   BOTTOM             — unreachable (use after a contradiction)
+//
+// Operations: join (∪), meet (∩), narrow-after-conditional, arithmetic
+// (+, -, *, /), and a `decide` predicate over a relational test
+// (lhs op rhs) returning 'true' | 'false' | 'maybe'.
+//
+// This is intentionally light-weight: no widening, no congruences, no
+// strided intervals — just the things you need to prune ~30% of false-
+// positive bounds-related paths in real code.
+
+const NEG_INF = -Infinity;
+const POS_INF = +Infinity;
+
+export const TOP = Object.freeze({ kind: 'range', lo: NEG_INF, hi: POS_INF });
+export const BOTTOM = Object.freeze({ kind: 'bottom' });
+
+/** Build a closed interval [lo, hi]. Order is normalized. */
+export function range(lo, hi) {
+  if (lo === undefined || lo === null) lo = NEG_INF;
+  if (hi === undefined || hi === null) hi = POS_INF;
+  if (lo > hi) return BOTTOM;
+  return { kind: 'range', lo, hi };
+}
+
+/** Convenience constructor for a single literal value. */
+export function constant(n) {
+  if (typeof n !== 'number' || Number.isNaN(n)) return TOP;
+  if (!Number.isFinite(n)) return TOP;
+  return range(n, n);
+}
+
+function isBottom(a) { return a && a.kind === 'bottom'; }
+function isTop(a)    { return a && a.kind === 'range' && a.lo === NEG_INF && a.hi === POS_INF; }
+
+/** Lattice join (least upper bound) — used at if/loop joins. */
+export function join(a, b) {
+  if (!a || isBottom(a)) return b;
+  if (!b || isBottom(b)) return a;
+  return range(Math.min(a.lo, b.lo), Math.max(a.hi, b.hi));
+}
+
+/** Lattice meet (greatest lower bound) — used to narrow after a guard. */
+export function meet(a, b) {
+  if (!a || !b) return BOTTOM;
+  if (isBottom(a) || isBottom(b)) return BOTTOM;
+  const lo = Math.max(a.lo, b.lo);
+  const hi = Math.min(a.hi, b.hi);
+  if (lo > hi) return BOTTOM;
+  return range(lo, hi);
+}
+
+/** Arithmetic. */
+export function add(a, b) {
+  if (!a || !b || isBottom(a) || isBottom(b)) return BOTTOM;
+  return range(a.lo + b.lo, a.hi + b.hi);
+}
+export function sub(a, b) {
+  if (!a || !b || isBottom(a) || isBottom(b)) return BOTTOM;
+  return range(a.lo - b.hi, a.hi - b.lo);
+}
+export function mul(a, b) {
+  if (!a || !b || isBottom(a) || isBottom(b)) return BOTTOM;
+  const candidates = [a.lo * b.lo, a.lo * b.hi, a.hi * b.lo, a.hi * b.hi];
+  return range(Math.min(...candidates), Math.max(...candidates));
+}
+
+/**
+ * Decide a relational test `a op b` where a, b are ranges.
+ *   Returns 'true' iff every concrete pair in a×b satisfies the test.
+ *   Returns 'false' iff every concrete pair fails it.
+ *   Returns 'maybe' otherwise (overlap → undecidable).
+ *
+ * Supported ops: '<', '<=', '>', '>=', '==', '!=', '===', '!=='.
+ */
+export function decide(a, op, b) {
+  if (!a || !b || isBottom(a) || isBottom(b)) return 'maybe';
+  switch (op) {
+    case '<':   return a.hi <  b.lo ? 'true' : a.lo >= b.hi ? 'false' : 'maybe';
+    case '<=':  return a.hi <= b.lo ? 'true' : a.lo >  b.hi ? 'false' : 'maybe';
+    case '>':   return a.lo >  b.hi ? 'true' : a.hi <= b.lo ? 'false' : 'maybe';
+    case '>=':  return a.lo >= b.hi ? 'true' : a.hi <  b.lo ? 'false' : 'maybe';
+    case '==':
+    case '===': {
+      // True iff intervals reduce to the same singleton.
+      if (a.lo === a.hi && b.lo === b.hi && a.lo === b.lo) return 'true';
+      // False iff disjoint.
+      if (a.hi < b.lo || b.hi < a.lo) return 'false';
+      return 'maybe';
+    }
+    case '!=':
+    case '!==': {
+      if (a.hi < b.lo || b.hi < a.lo) return 'true';
+      if (a.lo === a.hi && b.lo === b.hi && a.lo === b.lo) return 'false';
+      return 'maybe';
+    }
+    default: return 'maybe';
+  }
+}
+
+/**
+ * Narrow `a` by the assertion `a op b` having been observed as true.
+ *   e.g.  narrow(TOP, '>=', constant(0))  →  range(0, +∞)
+ *         narrow(TOP, '<',  constant(10)) →  range(-∞, 9)
+ *
+ * Returns a refined range; BOTTOM if the assertion is incompatible.
+ */
+export function narrow(a, op, b) {
+  if (!a || !b) return a || TOP;
+  if (isBottom(a) || isBottom(b)) return BOTTOM;
+  switch (op) {
+    case '<':  return meet(a, range(NEG_INF, b.hi - 1));
+    case '<=': return meet(a, range(NEG_INF, b.hi));
+    case '>':  return meet(a, range(b.lo + 1, POS_INF));
+    case '>=': return meet(a, range(b.lo, POS_INF));
+    case '==':
+    case '===': return meet(a, b);
+    case '!=':
+    case '!==': {
+      // Only refine when b is a singleton matching a boundary of a.
+      if (b.lo === b.hi) {
+        if (a.lo === b.lo) return range(a.lo + 1, a.hi);
+        if (a.hi === b.lo) return range(a.lo, a.hi - 1);
+      }
+      return a;
+    }
+    default: return a;
+  }
+}
+
+/**
+ * Abstract an AST-ish expression into a range. Returns TOP for anything
+ * we can't fold. The parser shape mirrors what `path-feasibility.js`
+ * consumes: { kind: 'literal'|'ident'|'bin', ... }
+ *
+ *   env: Map<varName, range>  — the abstract store
+ */
+export function abstractEval(expr, env) {
+  if (!expr) return TOP;
+  if (expr.kind === 'literal' && typeof expr.value === 'number' && Number.isFinite(expr.value)) {
+    return constant(expr.value);
+  }
+  if (expr.kind === 'ident' && env instanceof Map) {
+    return env.get(expr.name) || TOP;
+  }
+  if (expr.kind === 'bin') {
+    const l = abstractEval(expr.left, env);
+    const r = abstractEval(expr.right, env);
+    switch (expr.op) {
+      case '+': return add(l, r);
+      case '-': return sub(l, r);
+      case '*': return mul(l, r);
+      default:  return TOP;
+    }
+  }
+  return TOP;
+}
+
+/** Render an interval for debugging / finding evidence. */
+export function render(a) {
+  if (!a) return '⊤';
+  if (isBottom(a)) return '⊥';
+  if (isTop(a))    return '(-∞, +∞)';
+  const lo = a.lo === NEG_INF ? '-∞' : a.lo;
+  const hi = a.hi === POS_INF ? '+∞' : a.hi;
+  return `[${lo}, ${hi}]`;
+}
+
+/** True iff `a ⊑ b` (a is at least as precise as b). */
+export function leq(a, b) {
+  if (isBottom(a)) return true;
+  if (isBottom(b)) return false;
+  return a.lo >= b.lo && a.hi <= b.hi;
+}