@clear-capabilities/agentic-security-scanner 0.74.0

package/src/dataflow/.agentic-security/streak.json

@@ -0,0 +1,24 @@
+{
+  "firstScanDate": "2026-05-18T18:08:52.292Z",
+  "lastScanDate": "2026-05-20T21:19:05.322Z",
+  "totalScans": 105,
+  "daysCleanCritical": 3,
+  "lastCleanDate": "2026-05-20",
+  "lastCriticalDate": null,
+  "hasEverHadCritical": false,
+  "bestDaysCleanCritical": 3,
+  "totalFindingsAtFirstScan": 0,
+  "totalFindingsAtLastScan": 17,
+  "totalFixesInferred": 0,
+  "lastGrade": "A",
+  "bestGrade": "A+",
+  "launchCheckPassedAt": null,
+  "achievements": [
+    "first-scan",
+    "grade-a",
+    "grade-a-plus",
+    "scan-veteran-100",
+    "scan-veteran-25"
+  ],
+  "previousGrade": "A"
+}

package/src/dataflow/CLAUDE.md

@@ -0,0 +1,38 @@
+# scanner/src/dataflow/
+
+Layer-2 taint engine. Walks the Layer-1 IR (`../ir/`) with field-sensitive forward taint, consults a 200+ entry sources/sinks/sanitizers catalog, and emits findings tagged `parser: 'IR-TAINT'`.
+
+## Scope — what we actually model
+
+- **Intra-procedural field-sensitive taint** with access-path lattice (`access-paths.js`). `user.email` is distinguishable from `user.password`.
+- **k=1 monovariant interprocedural return-taint.** `SummaryCache` (`summaries.js`) holds one summary per function under empty entry state. At an assign-from-call site, if the resolved callee's summary says `returnTainted`, the LHS becomes tainted. Premortem-derived; was previously dead code.
+- **Catalog-driven source/sink/sanitizer matching.** Add entries in `catalog.js`. Each entry: `kind` ∈ {source, sink, sanitizer}, plus language + framework + match shape. 200+ entries spanning Express/Flask/FastAPI/Django/Rails/PHP/Go-net-http/Gin/Echo.
+- **Path feasibility.** Constant-folds `if` conditions to prune unreachable branches.
+- **Per-flow source attribution.** Sources reported on a finding are the ones actually reaching the sink argument (via free-var matching in the sink expression), NOT the first source the worklist happened to see. Premortem-derived.
+
+## Scope — what we do NOT model (today)
+
+- **Arbitrary entry-taint-state context-sensitivity.** Each function gets ONE summary, computed under empty entry. A function that's pure when called with clean args but vulnerable when called with tainted args is modelled as the empty-state result. Track FR-SEM-2 to lift this.
+- **Mutated-parameter taint at call sites.** The `SummaryCache.applyAtCallSite` helper exists for it; the engine doesn't consult it yet. If you want a helper that mutates its argument (`Object.assign(target, tainted)`) to taint the caller's `target`, this is the modelling gap.
+- **Higher-order taint flow** — partial. `higher-order.js` propagates taint into `arr.map(fn)` / `promise.then(fn)` callbacks at the IR level, but the recorded `_higherOrderInvocations` aren't fed back into the worklist yet.
+- **Implicit flow.** `implicit-flow.js` exists for `if (tainted) { x = "yes" }` propagation but is conservative-by-default.
+
+## Entry points
+
+- `runTaintEngine(perFileIR, callGraph, opts)` — the public entry. Called from `engine.js` when `AGENTIC_SECURITY_DEEP=1` (or auto-enabled outside CI).
+- `applyPathFeasibility` — constant-fold pass that runs before the worklist.
+- `annotateBackwardSlices` — backward-slice annotation for already-emitted findings.
+
+## Configuration / opt-in
+
+- `AGENTIC_SECURITY_DEEP=1` — enable the deep engine.
+- `AGENTIC_SECURITY_DEEP_TIMEOUT_MS` — global walltime budget (default 300_000).
+- `AGENTIC_SECURITY_DEEP_FN_LIMIT` — function-count budget (default 5000).
+- `AGENTIC_SECURITY_DEEP_IN_CI=1` — also enable in CI (off by default; CI runs are time-bounded).
+
+## Gotchas
+
+- **Path attribution.** If you're adding a sink to the catalog, set `argIndex` carefully. `'all'` means "any tainted arg fires"; a numeric index pinpoints THE arg whose taint matters. Wrong here → noisy findings with confused traces.
+- **Cache invalidation.** `SummaryCache` is in-memory per-scan. Cross-scan persistence lives in `incremental.js` (FR-incremental) but it's behind a separate flag. Don't conflate the two.
+- **Recursion.** The cache returns a bottom summary (`_recursive: true`) when it hits a function already on the stack. The engine relies on fixed-point iteration to refine — but `runTaintEngine` does only ONE pass today. Recursive cycles will under-approximate.
+- **`AGENTIC_SECURITY_BLIND_BENCH=1` disables the deep engine** along with everything else bench-shape. If you're trying to bench taint quality, run with both `AGENTIC_SECURITY_DEEP=1` and `AGENTIC_SECURITY_BLIND_BENCH=0` (the default).

package/src/dataflow/access-paths.js

@@ -0,0 +1,172 @@
+// Field-sensitive access-path lattice (P1.1).
+//
+// Replaces the engine's flat Set<varName> with Set<accessPath>, where an
+// access path is a string of the shape "base.prop.prop.prop" (any depth).
+// The lattice operations are:
+//
+//   - prefixCovers(haveSet, query)
+//       True iff some path in haveSet is a prefix of `query` (e.g. "x" covers
+//       "x.y.z"). Models the "if x is tainted, x.y and x.y.z are tainted too"
+//       contamination rule we already use today.
+//
+//   - longestCommonPrefixJoin(a, b)
+//       At a branch-join point, given two access-path sets, compute the LCP
+//       of every pair (a_path, b_path) that share a common prefix. The join
+//       keeps:
+//         (i)  paths present in BOTH a and b unchanged
+//         (ii) for paths present in only ONE branch, KEEP them (over-
+//              approximate — the path may have been mutated in that branch
+//              and stayed clean in the other; we treat the union as the
+//              conservative state).
+//       This is the canonical lattice for forward dataflow over a powerset.
+//
+// The path string format is intentionally simple — dot-separated, with no
+// support for [i] / [*] / function-call notation. Index sensitivity is a
+// follow-on (P3 work).
+//
+// Public API:
+//   accessPathOf(expr)             → string | null
+//   isCoveredBy(set, path)         → bool — is `path` covered by some path in `set`?
+//   joinSets(a, b)                 → new Set
+//   addPath(set, path)             → new Set (returns a new set with `path` added,
+//                                            collapsing redundant longer paths)
+//   removePathAndDescendants(set, path) → new Set
+//   canonicalize(set)              → new Set (removes paths covered by shorter prefixes)
+
+/**
+ * Convert an exprDesc (member / ident) into a dot-separated access path.
+ * Returns null when the expression is not a pure ident/member chain (e.g.
+ * has a call, binary, etc. — those are not access paths).
+ */
+export function accessPathOf(expr) {
+  if (!expr) return null;
+  if (expr.kind === 'ident') return expr.name;
+  if (expr.kind === 'member') {
+    if (!expr.object || typeof expr.prop !== 'string') return null;
+    const base = accessPathOf(expr.object);
+    if (!base) return null;
+    return `${base}.${expr.prop}`;
+  }
+  return null;
+}
+
+/**
+ * Returns true iff `path` is `prefix` or starts with `prefix + '.'`.
+ */
+export function pathIsCoveredByPrefix(path, prefix) {
+  if (typeof path !== 'string' || typeof prefix !== 'string') return false;
+  if (path === prefix) return true;
+  return path.length > prefix.length && path[prefix.length] === '.' && path.startsWith(prefix);
+}
+
+/**
+ * Returns true iff some entry in `set` is a prefix of `path` (or equals it).
+ * This is the "covers" relation that determines whether `path` is tainted:
+ * - `set = {"x"}` covers "x.y.z"  ✓
+ * - `set = {"x.y"}` covers "x.y.z"  ✓
+ * - `set = {"x.z"}` does NOT cover "x.y"  ✗
+ * - `set = {"x.y.z"}` does NOT cover "x.y"  ✗ (we don't propagate UP)
+ */
+export function isCoveredBy(set, path) {
+  if (!set || typeof path !== 'string') return false;
+  if (set.has(path)) return true;
+  let idx = path.lastIndexOf('.');
+  while (idx > 0) {
+    const prefix = path.slice(0, idx);
+    if (set.has(prefix)) return true;
+    idx = prefix.lastIndexOf('.');
+  }
+  return false;
+}
+
+/**
+ * Add `path` to the set. If a strictly-shorter prefix already covers `path`,
+ * the set is unchanged. If `path` covers existing longer descendants, they
+ * are removed (they're now redundant — taint at the shorter prefix subsumes
+ * taint at the longer descendant).
+ */
+export function addPath(set, path) {
+  if (typeof path !== 'string' || !path) return set;
+  const out = new Set(set);
+  // Strict-prefix already in set? Nothing to add.
+  let idx = path.lastIndexOf('.');
+  while (idx > 0) {
+    const prefix = path.slice(0, idx);
+    if (out.has(prefix)) return out;
+    idx = prefix.lastIndexOf('.');
+  }
+  // Remove redundant longer descendants.
+  for (const existing of [...out]) {
+    if (existing !== path && pathIsCoveredByPrefix(existing, path)) out.delete(existing);
+  }
+  out.add(path);
+  return out;
+}
+
+/**
+ * Remove `path` AND every descendant from the set (re-assignment of `x`
+ * clears `x.y`, `x.y.z`, etc.).
+ */
+export function removePathAndDescendants(set, path) {
+  if (!set || typeof path !== 'string' || !path) return set;
+  const out = new Set();
+  for (const existing of set) {
+    if (existing === path) continue;
+    if (pathIsCoveredByPrefix(existing, path)) continue;
+    out.add(existing);
+  }
+  return out;
+}
+
+/**
+ * Branch-join: the conservative union of two access-path sets, with
+ * redundant longer paths collapsed under their shorter-prefix parents.
+ */
+export function joinSets(a, b) {
+  if (!a && !b) return new Set();
+  if (!a) return canonicalize(b);
+  if (!b) return canonicalize(a);
+  // Union both, then canonicalize.
+  const all = new Set();
+  for (const p of a) all.add(p);
+  for (const p of b) all.add(p);
+  return canonicalize(all);
+}
+
+/**
+ * Remove any path that is covered by some strictly-shorter prefix in the
+ * same set. Idempotent.
+ */
+export function canonicalize(set) {
+  if (!set || set.size <= 1) return new Set(set || []);
+  const sorted = [...set].sort((a, b) => a.length - b.length || (a < b ? -1 : 1));
+  const out = new Set();
+  for (const path of sorted) {
+    let covered = false;
+    for (const existing of out) {
+      if (pathIsCoveredByPrefix(path, existing)) { covered = true; break; }
+    }
+    if (!covered) out.add(path);
+  }
+  return out;
+}
+
+/**
+ * Hash a set for cache keying — sorted canonical paths joined by '|'.
+ */
+export function hashSet(set) {
+  if (!set || set.size === 0) return 'empty';
+  return [...canonicalize(set)].sort().join('|');
+}
+
+/**
+ * Two access-path sets equal under canonicalization?
+ */
+export function setsEqual(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  const ca = canonicalize(a), cb = canonicalize(b);
+  if (ca.size !== cb.size) return false;
+  for (const x of ca) if (!cb.has(x)) return false;
+  return true;
+}

package/src/dataflow/async-sequencing.js

@@ -0,0 +1,177 @@
+// Async / Promise sequencing (P3.3).
+//
+// Today's engine treats every await/then/catch as a synchronous call. That's
+// CORRECT for most flows — taint propagates through resolved values just
+// like return values. But several real patterns break:
+//
+//   const data = await fetch(url).then(r => r.json());
+//                                       ^^^^^^^^^^^^^^   ← need first-arg taint
+//   p.then(onFulfilled).catch(onRejected)
+//                              ^^^^^^^^^^^^   ← rejected branch carries error taint
+//   Promise.all([fetchA(req.body), fetchB(req.body)])
+//          .then(([a, b]) => use(a, b))         ← destructured array elements
+//   for await (const chunk of req)              ← async iter — body chunks are sources
+//   const stream = req.body                     ← Node 18+ web streams
+//
+// This module captures the SHAPES of these chains and tells the engine
+// which callbacks to walk and how the result of the chain inherits taint.
+// It's a structural helper consumed by the IR-driven dataflow engine.
+//
+// Public API:
+//   describeChain(callExpr)
+//     → returns a normalized AsyncChain descriptor:
+//       { ops: [{ kind, callback?, argIndex? }], rootCallee, isPromise }
+//   resultTaintFor(chain, sourceTainted)
+//     → returns true iff the chain's resolved value is tainted given the
+//       root callee returned a tainted promise.
+//   awaitedTaint(state, varName)
+//     → adapts the engine's taint state at `await x` (no-op for typed
+//       values; for `await req.body.text()` we lift the call's result).
+//
+// Identification heuristic (no types in JS): a callee is considered
+// "promise-shaped" iff its name matches a known async source/sink in the
+// catalog, OR it's awaited at least once in the analyzed function. The
+// engine threads `isPromise` based on the catalog hit.
+
+const PROMISE_CHAIN_METHODS = new Set([
+  'then', 'catch', 'finally', 'allSettled',
+]);
+
+const PROMISE_STATIC_METHODS = new Set([
+  'all', 'allSettled', 'race', 'any',
+]);
+
+const ASYNC_ITER_BODY_SOURCES = new Set([
+  // req.body (Node 18+ / Fetch API web streams) — `for await` over it yields
+  // raw user-controlled chunks.
+  'body', 'stream',
+]);
+
+/**
+ * Describe a Promise-chain AST tail. Input is the OUTERMOST call expression
+ * of the chain (e.g., for `fetch(url).then(r).catch(e)`, pass the .catch call).
+ * Returns a normalized list of operations plus the root callee.
+ *
+ * AST shape expected (parser-js.js neutral):
+ *   { kind: 'call', callee: { kind: 'member', object: <expr>, prop: <string> }, args: [...] }
+ */
+export function describeChain(callExpr) {
+  if (!callExpr || callExpr.kind !== 'call') return null;
+  const ops = [];
+  let cur = callExpr;
+  // Walk leftward through .then/.catch/.finally chain.
+  while (cur && cur.kind === 'call' && cur.callee && cur.callee.kind === 'member' && PROMISE_CHAIN_METHODS.has(cur.callee.prop)) {
+    const arg = (cur.args || [])[0];
+    ops.unshift({
+      kind: cur.callee.prop,           // 'then' | 'catch' | 'finally'
+      callback: arg && (arg.kind === 'ident' || arg.kind === 'arrow' || arg.kind === 'function') ? arg : null,
+      argIndex: 0,
+    });
+    cur = cur.callee.object;
+  }
+  // `cur` should be the root call (e.g., `fetch(url)` or `Promise.all([...])`).
+  const isPromise = isPromiseRoot(cur);
+  return { ops, rootCallee: cur, isPromise };
+}
+
+function isPromiseRoot(expr) {
+  if (!expr) return false;
+  if (expr.kind !== 'call') return false;
+  const c = expr.callee;
+  if (!c) return false;
+  if (c.kind === 'ident') {
+    return /^(fetch|axios|request|got)$/.test(c.name);
+  }
+  if (c.kind === 'member') {
+    if (c.object && c.object.kind === 'ident' && c.object.name === 'Promise' && PROMISE_STATIC_METHODS.has(c.prop)) return true;
+    // any .xxxAsync() pattern, or .then-chainable: too noisy to assume; require
+    // an explicit await elsewhere or a known callee.
+    return /Async$/.test(c.prop) || /^(fetch|json|text|blob|formData)$/.test(c.prop);
+  }
+  return false;
+}
+
+/**
+ * Given a chain descriptor + a `sourceTainted` boolean indicating whether
+ * the root callee's resolved value is tainted, return whether each callback
+ * in the chain receives tainted input and whether the final resolved value
+ * is tainted.
+ *
+ * Semantics:
+ *   - `.then(fn)`     — fn(resolved) — fn receives taint iff source tainted
+ *   - `.catch(fn)`    — fn(error)   — fn receives ERROR taint; treated as
+ *                        tainted iff `assumeRejectionTainted` (default true:
+ *                        error.message can include user input via thrown
+ *                        new Error(req.body)).
+ *   - `.finally(fn)`  — fn() — no input; passes through previous taint
+ *   - chain result is tainted iff the LAST .then's callback returns a
+ *     tainted value (we approximate: any `.then` after a tainted input
+ *     keeps result tainted unless its callback is a known sanitizer).
+ *
+ * Returns:
+ *   { callbacks: [{ callback, taintedInput }], finalTainted }
+ */
+export function resultTaintFor(chain, sourceTainted, opts = {}) {
+  const assumeRejectionTainted = opts.assumeRejectionTainted !== false;
+  if (!chain) return { callbacks: [], finalTainted: !!sourceTainted };
+  let cur = !!sourceTainted;
+  const callbacks = [];
+  for (const op of chain.ops) {
+    if (op.kind === 'then') {
+      callbacks.push({ callback: op.callback, taintedInput: cur });
+      // result remains tainted until a sanitizer-known .then callback
+      // proves otherwise. We can't analyze the callback body here — that's
+      // the engine's job. Conservative default: tainted-in → tainted-out.
+    } else if (op.kind === 'catch') {
+      const errTainted = assumeRejectionTainted;
+      callbacks.push({ callback: op.callback, taintedInput: errTainted });
+      // catch can sanitize OR propagate. Conservative: keep current value.
+    } else if (op.kind === 'finally') {
+      callbacks.push({ callback: op.callback, taintedInput: false });
+      // finally callback gets no input.
+    }
+  }
+  return { callbacks, finalTainted: cur };
+}
+
+/**
+ * For `for await (const x of obj)` — return whether x should inherit taint
+ * given the object's name/property shape. The check is name-based since
+ * we don't have types.
+ *
+ *   `for await (const chunk of req.body)`           → chunk tainted
+ *   `for await (const chunk of req)`                → chunk tainted
+ *   `for await (const item of someInternal)`        → not tainted
+ */
+export function asyncIterYieldsTaint(iterableExpr, knownTaintedVars) {
+  if (!iterableExpr) return false;
+  if (iterableExpr.kind === 'ident') {
+    return knownTaintedVars && knownTaintedVars.has(iterableExpr.name);
+  }
+  if (iterableExpr.kind === 'member' && iterableExpr.object && iterableExpr.object.kind === 'ident') {
+    if (iterableExpr.object.name === 'req' || iterableExpr.object.name === 'request') {
+      // req.body / req.stream → tainted
+      if (ASYNC_ITER_BODY_SOURCES.has(iterableExpr.prop)) return true;
+    }
+    // user-tainted object's any property is tainted too (field-collapsing
+    // approximation matching engine.js's pre-P1.1 behavior).
+    if (knownTaintedVars && knownTaintedVars.has(iterableExpr.object.name)) return true;
+  }
+  return false;
+}
+
+/**
+ * Promise.all / Promise.race / Promise.any aggregate flow.
+ *
+ *   Promise.all([p1, p2, p3]).then(([a, b, c]) => …)
+ *
+ * Returns: an array of booleans indicating which destructured names
+ * inherit taint.
+ *
+ *   args:         the array literal passed to Promise.all (AST node or null)
+ *   eachTaintedFn: (argExpr) => boolean    — engine's per-expr predicate
+ */
+export function promiseAggregateTaint(args, eachTaintedFn) {
+  if (!args || !Array.isArray(args.elements)) return [];
+  return args.elements.map(eachTaintedFn || (() => false));
+}

package/src/dataflow/backward.js

@@ -0,0 +1,201 @@
+// Backward taint slicing (P1.4).
+//
+// Forward analysis answers: "given these sources, what flows reach the sinks?"
+// Backward slicing answers: "given this sink, walk back along def-use to
+// find the source(s)." The two combined give precise source→sink paths for
+// every emitted finding — the "show me the work" explainability layer.
+//
+// Algorithm (intraprocedural for v1):
+//
+//   slice(fn, sinkNode, sinkArgPath):
+//     work = [{ node: sinkNode, path: sinkArgPath }]
+//     visited = set
+//     trail = []
+//     while work non-empty:
+//       n = work.pop()
+//       if visited.has(n.node + ':' + n.path): continue
+//       visited.add(...)
+//       if n.node is 'assign' and target subsumes n.path:
+//         trail.push(n)
+//         enqueue every read in n.node.source as a new query
+//       follow CFG predecessor edges and continue
+//     return trail (oldest first)
+//
+// We use the IR CFG's `succ` arrays — predecessors are not directly stored
+// but we precompute the reverse edges for each function on demand.
+//
+// Interprocedural: when the sink's argument is bound to a function parameter,
+// we ascend to caller(s) by consulting the call graph. v1 visits up to 5
+// callers (BFS-bounded) to keep the slicer fast.
+
+import { accessPathOf, pathIsCoveredByPrefix } from './access-paths.js';
+
+const SLICE_BUDGET_NODES = 200;
+const SLICE_BUDGET_CALLERS = 5;
+
+function _reverseEdges(cfg) {
+  const rev = new Map();
+  if (!cfg || !cfg.nodes) return rev;
+  for (const id of Object.keys(cfg.nodes)) {
+    const node = cfg.nodes[id];
+    for (const s of (node?.succ || [])) {
+      if (!rev.has(s)) rev.set(s, []);
+      rev.get(s).push(id);
+    }
+  }
+  return rev;
+}
+
+/**
+ * Build a backward slice from a finding's sink site to its source(s).
+ *
+ *   fn:        the function the sink lives in
+ *   sinkNode:  the IR node where the sink fires
+ *   sinkArgPath: the access path of the tainted argument (string)
+ *
+ * Returns an ordered list of trace steps (source-first):
+ *   [
+ *     { line, kind: 'source', label, varName, path },
+ *     { line, kind: 'assign', from, to, path },
+ *     { line, kind: 'call',   callee, argPath, path },
+ *     { line, kind: 'sink',   callee, argIndex, path },
+ *   ]
+ */
+export function sliceBackward(fn, sinkNode, sinkArgPath) {
+  const out = [];
+  if (!fn || !sinkNode) return out;
+  const cfg = fn.cfg;
+  if (!cfg || !cfg.nodes) return out;
+  const rev = _reverseEdges(cfg);
+
+  // Map node-id to itself lookup for nodes in this CFG.
+  const nodes = cfg.nodes;
+
+  // We don't directly know the node-id of `sinkNode`; the caller passes
+  // a reference. Recover it by linear search (CFGs are small per fn).
+  let sinkNid = null;
+  for (const id of Object.keys(nodes)) {
+    if (nodes[id] === sinkNode) { sinkNid = id; break; }
+  }
+  if (!sinkNid) return out;
+
+  out.push({
+    line: sinkNode.line || 0,
+    kind: 'sink',
+    callee: sinkNode.callee || null,
+    path: sinkArgPath,
+  });
+
+  const work = [{ nid: sinkNid, queryPath: sinkArgPath }];
+  const visited = new Set();
+  let visitedCount = 0;
+
+  while (work.length) {
+    if (++visitedCount > SLICE_BUDGET_NODES) break;
+    const { nid, queryPath } = work.shift();
+    const key = `${nid}::${queryPath}`;
+    if (visited.has(key)) continue;
+    visited.add(key);
+
+    const node = nodes[nid];
+    if (!node) continue;
+
+    // The query path matches an assignment target? Record the def + chase RHS.
+    if (node.kind === 'assign' && typeof node.target === 'string' && pathIsCoveredByPrefix(queryPath, node.target)) {
+      const srcAp = accessPathOf(node.source);
+      out.push({
+        line: node.line || 0,
+        kind: 'assign',
+        to: node.target,
+        from: srcAp,
+        path: queryPath,
+      });
+      // Switch the query to the RHS access path (if any). If the source
+      // itself is a catalog source (req.body, etc.), mark it as the
+      // origin step.
+      if (srcAp) {
+        // Heuristic source detection without re-importing catalog —
+        // anything that starts with a common source prefix.
+        if (/^req\.(?:body|query|params|headers|cookies)|process\.env|window\.location|document\.URL/.test(srcAp)) {
+          out.push({
+            line: node.line || 0,
+            kind: 'source',
+            label: srcAp,
+            path: queryPath,
+          });
+          continue;
+        }
+        // Otherwise, follow the def of the new query path upstream.
+        work.push({ nid, queryPath: srcAp });
+      }
+    }
+
+    // Walk predecessors regardless — defs can be on prior nodes.
+    for (const p of (rev.get(nid) || [])) {
+      work.push({ nid: p, queryPath });
+    }
+  }
+
+  // Reverse so the trace reads source-first.
+  return out.reverse();
+}
+
+/**
+ * Helper: annotate every finding in a list with its backward slice.
+ *
+ *   findings: produced by the engine, expected to carry `_funcQid` and `line`.
+ *   perFileIR / callGraph: same shape the dataflow engine consumes.
+ *
+ * Walltime-bounded: total annotation work is capped by
+ * AGENTIC_SECURITY_BACKWARD_SLICE_BUDGET_MS (default 30_000). When the
+ * budget is exhausted, remaining findings are left without slices —
+ * earlier findings keep their annotations.
+ *
+ * Returns the (mutated) findings array, with an `_annotateBackwardSlicesStats`
+ * scratch property on the array containing { annotated, skipped, exhausted }.
+ */
+export function annotateBackwardSlices(findings, perFileIR, callGraph) {
+  if (!Array.isArray(findings)) return findings;
+  const budgetMs = Number(process.env.AGENTIC_SECURITY_BACKWARD_SLICE_BUDGET_MS) || 30_000;
+  const deadline = Date.now() + budgetMs;
+  // Build a qid → fn map for O(1) lookup.
+  const fnByQid = new Map();
+  if (callGraph && callGraph.functions) {
+    for (const fn of callGraph.functions.values()) fnByQid.set(fn.qid, fn);
+  }
+  let annotated = 0, skipped = 0, exhausted = false;
+  for (const f of findings) {
+    if (Date.now() > deadline) { exhausted = true; skipped++; continue; }
+    if (!f || !f._funcQid) { skipped++; continue; }
+    const fn = fnByQid.get(f._funcQid);
+    if (!fn) { skipped++; continue; }
+    // Find the sink node in fn by line + callee match.
+    let sinkNode = null;
+    for (const nid of Object.keys(fn.cfg?.nodes || {})) {
+      const n = fn.cfg.nodes[nid];
+      if (!n || n.kind !== 'call') continue;
+      if (n.line === f.line && n.callee === f.callee) { sinkNode = n; break; }
+    }
+    if (!sinkNode) { skipped++; continue; }
+    // The tainted arg path — derive from the tainted argument's expression.
+    const taintedArg = (sinkNode.args || [])[f.argIndex];
+    const argPath = accessPathOf(taintedArg) || `arg[${f.argIndex}]`;
+    const slice = sliceBackward(fn, sinkNode, argPath);
+    if (slice && slice.length) {
+      f.backwardSlice = slice;
+      f.pathSteps = (f.pathSteps || []).concat(slice.map(s => ({
+        type: s.kind,
+        label: s.label || s.callee || s.path || '',
+        line: s.line,
+      })));
+      annotated++;
+    } else {
+      skipped++;
+    }
+  }
+  Object.defineProperty(findings, '_annotateBackwardSlicesStats', {
+    value: { annotated, skipped, exhausted, budgetMs },
+    enumerable: false,
+  });
+  return findings;
+}