@clear-capabilities/agentic-security-scanner 0.143.0 → 0.144.0

package/src/posture/state-dir.js

@@ -16,7 +16,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const STATE_DIR_NAME = '.agentic-security';
+// Exported so a caller that needs the state dir NAME for display purposes
+// (e.g. a human-readable "this file lives at X/Y" string, not an actual
+// path construction) can go through the seam too, rather than hardcoding
+// the literal — see test/no-stray-state.test.js's own detector, which
+// flags a quoted '.agentic-security' literal anywhere else in the tree.
+export const STATE_DIR_NAME = '.agentic-security';
 
 const PROJECT_MARKERS = [
   '.git',
@@ -143,6 +148,36 @@ export function stateWritesEnabled() {
   return _stateWritesEnabled;
 }
 
+/**
+ * Run `fn` with state writes forced off, restoring the PRIOR flag value
+ * afterward — for a caller (assurance-hardening PRD FR-704) that must
+ * guarantee ITS scan does not mutate the tree, without having to remember
+ * to call setStateWritesEnabled(true) again itself. A caller that disables
+ * writes and forgets to re-enable them silently breaks every LATER write in
+ * the same process — exactly `apply_fix`'s failure mode this wrapper exists
+ * to prevent, via `finally` rather than caller discipline.
+ *
+ * KNOWN LIMITATION: `_stateWritesEnabled` is process-global, not per-call.
+ * Two overlapping calls to this function (or one overlapping a direct
+ * setStateWritesEnabled() call) can race and leave the flag in the wrong
+ * state for one of them once both finish. mcp/CLAUDE.md already documents
+ * an accepted concurrency limitation of the same shape for fix-history.js
+ * ("concurrent apply_fix calls can race... today benign... a future
+ * stateful tool needs serialization") — this is the same class of risk, not
+ * a new one, and this wrapper is still a strict improvement over the
+ * alternative it replaces (a caller that writes state UNCONDITIONALLY on
+ * every call, with no opt-out at all).
+ */
+export async function withStateWritesDisabled(fn) {
+  const prior = _stateWritesEnabled;
+  _stateWritesEnabled = false;
+  try {
+    return await fn();
+  } finally {
+    _stateWritesEnabled = prior;
+  }
+}
+
 // Safe mkdir: only creates .agentic-security/ if the parent has a project marker.
 // Returns the dir on success, null if refused. Logs a warning when refused.
 export function ensureStateDir(scanRoot) {

package/src/posture/state-lifecycle-report.js

@@ -0,0 +1,77 @@
+// FR-706 (assurance-hardening PRD): manifest-based export and deletion
+// reports — "Operators can prove what was exported, deleted, retained, or
+// failed."
+//
+// Two report kinds, one shared per-item shape ({name, status, ...}), each
+// written by its one real caller in bin/agentic-security.js:
+//   - `cmdReset` builds a deletion report from the SAME target/preserved
+//     data it already computes for its console output (see FR-702/FR-703),
+//     reshaped into a durable, structured artifact instead of only ever
+//     printed and lost. Written on BOTH a dry run (items carry status
+//     'planned') and a real run (status 'deleted'/'failed'), so an operator
+//     can prove either "what would happen" or "what did happen" depending
+//     on which they asked for — `dryRun` on the report says which.
+//   - `cmdExport` (new) builds an export report after copying every
+//     currently-present registered artifact to an operator-chosen
+//     destination, naming what was copied (with a hash) and what failed.
+//
+// Each report is a SINGLE OVERWRITTEN file per kind — the same "last
+// action" precedent as last-scan.json, not an ever-growing log. An
+// operator who needs a persistent audit trail across many runs should
+// retain these externally (commit them, forward to their own SIEM); this
+// module's job is only to make the LAST action's outcome durable and
+// provable, not to be the audit log itself.
+
+import { statePath, safeWriteState } from './state-dir.js';
+
+export const DELETION_REPORT_FILE = 'deletion-report.json';
+export const EXPORT_REPORT_FILE = 'export-report.json';
+
+export function buildDeletionReport({ mode, dryRun, root, items, preserved }) {
+  const list = Array.isArray(items) ? items : [];
+  const preservedList = Array.isArray(preserved) ? preserved : [];
+  return {
+    schema: 'agentic-security/deletion-report@1',
+    generatedAt: new Date().toISOString(),
+    mode: mode || 'reset',
+    dryRun: !!dryRun,
+    root: root || null,
+    items: list,
+    preserved: preservedList,
+    summary: {
+      planned: list.filter(i => i.status === 'planned').length,
+      deleted: list.filter(i => i.status === 'deleted').length,
+      failed: list.filter(i => i.status === 'failed').length,
+      preserved: preservedList.length,
+    },
+  };
+}
+
+export function writeDeletionReport(scanRoot, report) {
+  try {
+    const fp = statePath(scanRoot, DELETION_REPORT_FILE);
+    return safeWriteState(fp, JSON.stringify(report, null, 2) + '\n') ? fp : null;
+  } catch { return null; }
+}
+
+export function buildExportReport({ root, outDir, items }) {
+  const list = Array.isArray(items) ? items : [];
+  return {
+    schema: 'agentic-security/export-report@1',
+    generatedAt: new Date().toISOString(),
+    root: root || null,
+    outDir: outDir || null,
+    items: list,
+    summary: {
+      exported: list.filter(i => i.status === 'exported').length,
+      failed: list.filter(i => i.status === 'failed').length,
+    },
+  };
+}
+
+export function writeExportReport(scanRoot, report) {
+  try {
+    const fp = statePath(scanRoot, EXPORT_REPORT_FILE);
+    return safeWriteState(fp, JSON.stringify(report, null, 2) + '\n') ? fp : null;
+  } catch { return null; }
+}

package/src/posture/suppressions.js

@@ -4,11 +4,41 @@
 //                  reviewer + expiry + rule-version pin)
 // One function `applySuppressions(findings, scanRoot, profile)` filters in
 // place. Loaders accept malformed input gracefully (skip bad entries, log).
+//
+// FR-1004 (assurance-hardening PRD): "exception owner, reason, scope,
+// compensating control, and expiry." The pro schema already had reason
+// (`reason`) and expiry (`expires_at`); `owner`, `scope`, and
+// `compensating_control` are added here as required fields on the SAME
+// entry, validated by the SAME `validateProSuppression` gate that already
+// enforces the two-person rule. This is a deliberate tightening: an
+// existing suppressions.yml entry written before this field set was
+// required will now fail validation and REOPEN its finding, same as any
+// other invalid pro suppression already does — an operator must add the
+// three new fields to keep the exception honored. `owner` is who is
+// accountable for eventually resolving or renewing the exception (may or
+// may not be the same person as `reviewer`); `scope` is a short,
+// human-readable statement of what the exception covers (this module's
+// matching remains per-finding — `scope` documents intent, it does not
+// widen what gets suppressed); `compensating_control` is the specific
+// alternative mitigation that justifies leaving the underlying finding
+// unfixed (a required field, not inferred from `reason` — "we'll fix it
+// later" is a reason, not a compensating control, and conflating the two
+// was the actual gap this PRD item exists to close).
+//
+// "Expired exceptions automatically reopen findings or fail the gate":
+// `applySuppressions` already returns an expired suppression's finding to
+// the KEPT (open) set rather than the suppressed set (see the `exp < now`
+// branch below) — an expired exception was always self-reopening by
+// construction, this was just never covered by a test until FR-1004.
+// Reopening feeds the existing severity-based CI gate (`--fail-on`)
+// exactly like any other open finding; no second, parallel expiry-gate
+// mechanism is needed or built here.
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 import { statePath, safeWriteState } from './state-dir.js';
+import { loadApproverRegistry, verifyApprover, requiredRolesFor } from '../fix/approver-registry.js';
 
 const MS_PER_DAY = 86400000;
 const SOFT_TTL_DAYS = 30;
@@ -59,14 +89,31 @@ export function loadProSuppressions(scanRoot) {
 }
 
 // Validate one entry. Returns { ok, errors }.
-export function validateProSuppression(entry) {
+//
+// FR-1002: "bind approvals, EXCEPTIONS, AND SUPPRESSIONS to verified
+// identities and roles... anonymous or unauthorized high-risk exceptions
+// fail policy." A pro suppression's `justification_signed_by` is exactly
+// such an exception-approval identity, but until this fix it was pure
+// self-reported free text -- FR-307/FR-1002's registry existed and was
+// wired into apply_fix, but never consulted here. `opts.registry` is
+// optional and NO-OP when absent (loadApproverRegistry(scanRoot) returns
+// null until an operator opts in, matching every other gate in this
+// registry), so an existing project with no registry file sees zero
+// behavior change. `opts.requiredRoles` lets the caller scope role
+// requirements to the SUPPRESSED FINDING's own family/category, the same
+// way FR-307 scopes them to a change's material-change category.
+export function validateProSuppression(entry, opts = {}) {
   const errors = [];
-  for (const k of ['finding_id', 'file', 'reason', 'justification_signed_by', 'reviewer', 'expires_at']) {
+  for (const k of ['finding_id', 'file', 'reason', 'justification_signed_by', 'reviewer', 'expires_at', 'owner', 'scope', 'compensating_control']) {
     if (!entry[k] || (typeof entry[k] === 'string' && !entry[k].trim())) errors.push(`missing: ${k}`);
   }
   if (entry.justification_signed_by && entry.reviewer && entry.justification_signed_by === entry.reviewer) {
     errors.push('justification_signed_by must differ from reviewer (two-person rule)');
   }
+  if (entry.justification_signed_by && opts.registry !== undefined) {
+    const v = verifyApprover(opts.registry, entry.justification_signed_by, opts.requiredRoles || []);
+    if (!v.verified) errors.push(`justification_signed_by not authorized: ${v.reason}`);
+  }
   if (entry.expires_at) {
     const t = _dateOnly(entry.expires_at);
     if (!Number.isFinite(t)) errors.push('expires_at must be ISO date');
@@ -84,6 +131,11 @@ export function applySuppressions(findings, scanRoot, profile) {
   const items = isPro ? loadProSuppressions(scanRoot) : loadSoftAccepted(scanRoot);
   if (!items.length) return findings;
 
+  // FR-1002: loaded once per call, not per entry — a missing registry file
+  // (the common, not-opted-in case) makes verifyApprover() a no-op below,
+  // exactly like every other gate built on this registry.
+  const approverRegistry = isPro ? loadApproverRegistry(scanRoot) : null;
+
   const now = _now();
   const kept = [];
   const suppressed = [];
@@ -106,7 +158,11 @@ export function applySuppressions(findings, scanRoot, profile) {
       }
       // Pro: validate the entry still passes
       if (isPro) {
-        const v = validateProSuppression({ ...matched, severity: f.severity });
+        // Same registry/category shape FR-307 already uses for high-impact
+        // fixes: an operator opts a finding family into role-gating via
+        // requiredRolesByCategory, keyed by that family's name.
+        const requiredRoles = requiredRolesFor(approverRegistry, [f.family].filter(Boolean));
+        const v = validateProSuppression({ ...matched, severity: f.severity }, { registry: approverRegistry, requiredRoles });
         if (!v.ok) { kept.push({ ...f, _suppressionInvalid: v.errors }); continue; }
       }
       suppressed.push({ ...f, _suppressed: matched });

package/src/privacy/ir-adapter.js

@@ -0,0 +1,380 @@
+// Privacy IR adapter (assurance-hardening PRD, Milestone 2, FR-401).
+//
+// dataflow/privacy-taint.js's annotatePrivacyTaint() expects a per-file map
+// of `{ _content, decls: [{name, line, type}], calls: [{line, fullPath|callee,
+// args: [{text}]}] }` — a FLAT, per-file shape. The real Layer-1 IR
+// (ir/index.js#buildProjectIR) does not produce that shape at all: it is
+// per-FUNCTION (`functions: [{params, cfg: {nodes: {...}}}]`), and CFG node
+// arguments are structured expression trees (`{kind:'ident', name}`,
+// `{kind:'member', object, prop}`, ...), not `{text: string}` objects. This
+// was the actual reason privacy analysis was wired with hardcoded
+// `decls:[], calls:[]` (A-06) — there was no adapter reconciling the two
+// shapes, not a missing capability in the underlying IR/taint engine (see
+// docs/implementation/assurance-hardening-decisions.md D-0003's pattern:
+// verify before assuming something is unbuilt).
+//
+// This module is that adapter. It does NOT reimplement privacy analysis —
+// it only reshapes the real IR into exactly what annotatePrivacyTaint()
+// already knows how to consume.
+//
+// Declarations: sourced from every function's `params` (a parameter is a
+// declaration) and every `assign`-kind CFG node's `target` (an assignment
+// declares/rebinds a name). Both are what a real codebase would call PII
+// "at the point it enters a function or gets bound to a local".
+//
+// Calls: sourced from every `call`-kind CFG node, AND from `assign`-kind
+// nodes whose `source` is itself a call expression (`const x = fetch(...)`)
+// — privacy-taint.js only walks a flat `ir.calls` list, so a call used as
+// an assignment's right-hand side needs to be surfaced there too or it's
+// invisible to the sink-matching pass entirely.
+//
+// Argument "text": privacy-taint.js's sink-matching does a literal
+// \b<name>\b regex test against the joined text of a call's argument
+// expressions — it does not need faithful re-rendered source code, only
+// text that CONTAINS every identifier name referenced (directly or nested)
+// in that argument, so a tainted variable's name is found wherever it
+// appears. `_identifiersIn` recursively collects identifier names (and
+// literal values, for completeness) rather than attempting full expression
+// pretty-printing, which is simpler and sufficient for this consumer's
+// actual matching logic.
+//
+// Storage: this codebase already has a separate stored-taint subsystem
+// (engine.js's STORED_TAINT_FIELD_PATTERNS / buildStoredTaintRegistry) that
+// tracks which ORM/model fields are written with unsanitized request input,
+// for its own cross-file write-then-render correlation (crossStoredTaint).
+// `_storageForFile` reindexes that ALREADY-COMPUTED, whole-project registry
+// down to one file's writes rather than recomputing anything — the engine
+// builds it once per scan regardless of whether privacy analysis runs at all.
+//
+// Types: the underlying Layer-1 IR (ir/index.js#buildProjectIR) tracks no
+// type-annotation/inference data for any language — genuine cross-language
+// type inference would mean extending every language parser, a separate,
+// substantially larger project deliberately out of scope here. What IS in
+// scope, and implemented below, is a narrow, honest, TypeScript-only sliver:
+// `_extractTsTypes` does a SEPARATE, read-only `@babel/core` `parseSync` pass
+// over `.ts`/`.tsx` source (never touching ir/parser-js.js's own transform
+// pipeline or its shared, heavily-relied-on visitor plugin) and walks the
+// resulting AST for `TSTypeAnnotation` nodes on function parameters and
+// `let`/`const`/`var` declarators. Babel's `parseSync` only PARSES — it never
+// runs `@babel/preset-typescript`'s stripping transform, so a `.ts` file's
+// type annotations are fully intact on the AST it returns, no plugin-ordering
+// trick required. Matching this SEPARATE parse's declarations back to the
+// real IR's decls is done by `(line, name)` — the same real source line and
+// identifier name a given parameter or declarator sits on in both parses,
+// since both parse the identical source text. A `.js` file, a type Babel
+// cannot express as a plain name (destructured/computed types, deeply
+// generic types past a small recursion depth), or any parse/traverse failure
+// all degrade to `type: null` — never a guess, matching every other
+// optional field in this module.
+
+import { parseSync as babelParseSync, traverse as babelTraverse } from '@babel/core';
+import presetTypescript from '@babel/preset-typescript';
+
+const MAX_EXPR_DEPTH = 40;
+const MAX_TS_TYPE_DEPTH = 6;
+
+function _calleeToString(callee, depth = 0) {
+  if (typeof callee === 'string') return callee;
+  if (!callee || typeof callee !== 'object' || depth > MAX_EXPR_DEPTH) return '';
+  switch (callee.kind) {
+    case 'ident': return callee.name || '';
+    case 'member': {
+      const obj = _calleeToString(callee.object, depth + 1);
+      return obj ? `${obj}.${callee.prop || ''}` : String(callee.prop || '');
+    }
+    case 'call': return _calleeToString(callee.callee, depth + 1);
+    default: return '';
+  }
+}
+
+function _identifiersIn(expr, out, depth = 0) {
+  if (!expr || typeof expr !== 'object' || depth > MAX_EXPR_DEPTH) return;
+  switch (expr.kind) {
+    case 'ident':
+      if (expr.name) out.push(expr.name);
+      return;
+    case 'literal':
+      if (expr.value != null) out.push(String(expr.value));
+      return;
+    case 'member':
+      _identifiersIn(expr.object, out, depth + 1);
+      if (expr.prop) out.push(String(expr.prop));
+      return;
+    case 'binary':
+    case 'logical':
+      _identifiersIn(expr.left, out, depth + 1);
+      _identifiersIn(expr.right, out, depth + 1);
+      return;
+    case 'tpl':
+      for (const p of expr.parts || []) _identifiersIn(p, out, depth + 1);
+      return;
+    case 'call':
+      _identifiersIn(expr.callee, out, depth + 1);
+      for (const a of expr.args || []) _identifiersIn(a, out, depth + 1);
+      return;
+    case 'array':
+      for (const e of expr.elements || []) _identifiersIn(e, out, depth + 1);
+      return;
+    case 'object':
+      for (const p of expr.props || []) _identifiersIn(p.value, out, depth + 1);
+      return;
+    case 'union':
+      for (const b of expr.branches || []) _identifiersIn(b, out, depth + 1);
+      return;
+    default:
+      return;
+  }
+}
+
+function _argsToTextArgs(args) {
+  return (args || []).map(a => {
+    const names = [];
+    _identifiersIn(a, names);
+    return { text: names.join(' ') };
+  });
+}
+
+// A TSQualifiedName is `A.B.C` (e.g. `Foo.Bar`) — dot-join it the same way
+// _calleeToString dot-joins a member expression above.
+function _qualifiedTypeName(node, depth = 0) {
+  if (!node || depth > MAX_TS_TYPE_DEPTH) return null;
+  if (node.type === 'Identifier') return node.name || null;
+  if (node.type === 'TSQualifiedName') {
+    const left = _qualifiedTypeName(node.left, depth + 1);
+    const right = node.right?.name || null;
+    if (!left || !right) return left || right;
+    return `${left}.${right}`;
+  }
+  return null;
+}
+
+/**
+ * Renders a TSType AST node to a short, human-readable string — never a
+ * best-effort re-render of the whole type, just enough to be a real,
+ * non-fabricated signal. Anything not recognized (mapped types, conditional
+ * types, indexed access, deeply nested generics past the depth guard) is
+ * `null`, exactly like every other "don't know" in this module — no type
+ * string is ever invented for a shape this doesn't genuinely understand.
+ */
+function _tsTypeToString(node, depth = 0) {
+  if (!node || depth > MAX_TS_TYPE_DEPTH) return null;
+  switch (node.type) {
+    case 'TSStringKeyword': return 'string';
+    case 'TSNumberKeyword': return 'number';
+    case 'TSBooleanKeyword': return 'boolean';
+    case 'TSAnyKeyword': return 'any';
+    case 'TSUnknownKeyword': return 'unknown';
+    case 'TSVoidKeyword': return 'void';
+    case 'TSNullKeyword': return 'null';
+    case 'TSUndefinedKeyword': return 'undefined';
+    case 'TSNeverKeyword': return 'never';
+    case 'TSObjectKeyword': return 'object';
+    case 'TSBigIntKeyword': return 'bigint';
+    case 'TSSymbolKeyword': return 'symbol';
+    case 'TSTypeReference': {
+      const name = node.typeName?.type === 'Identifier'
+        ? node.typeName.name
+        : _qualifiedTypeName(node.typeName, depth + 1);
+      if (!name) return null;
+      // Babel's current AST names this `typeArguments`; `typeParameters` was
+      // the property on older @babel/parser versions for the same node —
+      // checking both means this doesn't silently go generic-blind on a
+      // dependency bump either direction.
+      const paramNodes = (node.typeArguments || node.typeParameters)?.params || [];
+      const args = paramNodes.map(p => _tsTypeToString(p, depth + 1)).filter(Boolean);
+      return (args.length && args.length === paramNodes.length) ? `${name}<${args.join(', ')}>` : name;
+    }
+    case 'TSArrayType': {
+      const el = _tsTypeToString(node.elementType, depth + 1);
+      return el ? `${el}[]` : null;
+    }
+    case 'TSUnionType': {
+      const parts = (node.types || []).map(t => _tsTypeToString(t, depth + 1)).filter(Boolean);
+      return parts.length === (node.types || []).length ? parts.join(' | ') : null;
+    }
+    case 'TSLiteralType': {
+      const lit = node.literal;
+      if (lit?.type === 'StringLiteral') return JSON.stringify(lit.value);
+      if (lit?.type === 'NumericLiteral') return String(lit.value);
+      if (lit?.type === 'BooleanLiteral') return String(lit.value);
+      return null;
+    }
+    default: return null;
+  }
+}
+
+/**
+ * FR-401's "types" element, TypeScript-only. A separate, read-only parse of
+ * the real source — never the transformed AST ir/parser-js.js builds its IR
+ * from, and never a mutation of anything that module owns. `parseSync` only
+ * parses; `@babel/preset-typescript`'s stripping transform never runs, so
+ * `.ts`/`.tsx` type annotations are fully intact on the returned AST.
+ *
+ * Keyed by the real source line a parameter or declarator's IDENTIFIER sits
+ * on (matching how ir/parser-js.js's own IR already records a parameter's
+ * line as its enclosing function's start line, and an assignment's line as
+ * its own CFG node's line) so `_adaptFile` can look a type up by the exact
+ * (line, name) pair it already has, without needing any cross-parse node
+ * identity.
+ *
+ * @returns {Map<number, Map<string,string>>} line -> (name -> type string)
+ */
+function _extractTsTypes(file, content) {
+  const out = new Map();
+  if (!/\.tsx?$/i.test(file) || typeof content !== 'string' || content.length > 500_000) return out;
+  const record = (name, line, typeAnnotationNode) => {
+    if (!name || !line || !typeAnnotationNode) return;
+    const t = _tsTypeToString(typeAnnotationNode.typeAnnotation);
+    if (!t) return;
+    if (!out.has(line)) out.set(line, new Map());
+    out.get(line).set(name, t);
+  };
+  let ast;
+  try {
+    ast = babelParseSync(content, {
+      filename: file,
+      presets: [[presetTypescript, { ignoreExtensions: true }]],
+      // Mirrors ir/parser-js.js's own parserOpts exactly — accepting the same
+      // decorator syntax it accepts, so this separate parse does not reject
+      // (and silently lose types from) a file the real IR parser accepts.
+      parserOpts: { plugins: ['decorators-legacy', 'decoratorAutoAccessors'] },
+      babelrc: false, configFile: false, ast: true, code: false,
+    });
+  } catch { return out; }
+  if (!ast) return out;
+  try {
+    babelTraverse(ast, {
+      Function(path) {
+        for (const p of path.node.params || []) {
+          const resolved = p.type === 'AssignmentPattern' ? p.left : p;
+          if (resolved?.type === 'Identifier' && resolved.typeAnnotation) {
+            record(resolved.name, path.node.loc?.start?.line, resolved.typeAnnotation);
+          }
+        }
+      },
+      VariableDeclarator(path) {
+        const id = path.node.id;
+        if (id?.type === 'Identifier' && id.typeAnnotation) {
+          record(id.name, path.node.loc?.start?.line, id.typeAnnotation);
+        }
+      },
+    });
+  } catch { /* degrade to whatever was recorded before the failure */ }
+  return out;
+}
+
+/**
+ * FR-401's "storage" element. Reindexes the whole-project, field-name-keyed
+ * stored-taint registry (engine.js#buildStoredTaintRegistry — already
+ * computed once per scan for crossStoredTaint's own cross-file correlation,
+ * not recomputed here) down to just the writes that happened in THIS file.
+ * `storedRegistry` is `{ [fieldName]: [{file, line, snippet, named}, ...] }`;
+ * this returns the flattened, per-file subset as
+ * `[{field, line, snippet, named}, ...]`.
+ */
+function _storageForFile(file, storedRegistry) {
+  const out = [];
+  if (!storedRegistry || typeof storedRegistry !== 'object') return out;
+  for (const [field, writes] of Object.entries(storedRegistry)) {
+    for (const w of writes || []) {
+      if (w && w.file === file) out.push({ field, line: w.line ?? 0, snippet: w.snippet || '', named: !!w.named });
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {object} fileIR - one entry from ir/index.js#buildProjectIR's `perFile` map: {file, functions, topLevel}
+ * @param {Map<number, Map<string,string>>|null} [tsTypes] - `_extractTsTypes`'s
+ *   output for this same file. Optional: omitted (or no match at a given
+ *   (line, name)) leaves `type: null`, exactly as before this existed.
+ * @returns {{decls: Array, calls: Array}}
+ */
+function _adaptFile(fileIR, tsTypes) {
+  const decls = [];
+  const calls = [];
+  const returns = [];
+  const typeAt = (line, name) => tsTypes?.get(line)?.get(name) ?? null;
+  for (const fn of fileIR?.functions || []) {
+    for (const paramName of fn.params || []) {
+      if (typeof paramName === 'string' && paramName) {
+        // `kind` genuinely distinguishes a parameter from a later
+        // assignment (FR-401's "parameters" vs "assignments" elements) —
+        // annotatePrivacyTaint() ignores unknown fields, so this is purely
+        // additive for that consumer.
+        decls.push({ name: paramName, line: fn.line ?? 0, type: typeAt(fn.line ?? 0, paramName), kind: 'parameter' });
+      }
+    }
+    const nodes = fn.cfg?.nodes || {};
+    for (const node of Object.values(nodes)) {
+      if (!node) continue;
+      if (node.kind === 'assign' && node.target) {
+        const line = node.line ?? fn.line ?? 0;
+        decls.push({ name: node.target, line, type: typeAt(line, node.target), kind: 'assignment' });
+      }
+      if (node.kind === 'call') {
+        calls.push({
+          line: node.line ?? fn.line ?? 0,
+          fullPath: _calleeToString(node.callee),
+          args: _argsToTextArgs(node.args),
+        });
+      } else if (node.kind === 'assign' && node.source && node.source.kind === 'call') {
+        calls.push({
+          line: node.line ?? fn.line ?? 0,
+          fullPath: _calleeToString(node.source.callee),
+          args: _argsToTextArgs(node.source.args),
+        });
+      } else if (node.kind === 'return' && node.value) {
+        // FR-401's "returns" element: every CFG language parser genuinely
+        // emits return-kind nodes (confirmed across parser-js/py/java/go/
+        // rb/php/cs/kt/cpp), so this is real IR data, not a stub — surfaced
+        // here even though annotatePrivacyTaint() (the shallow walker) does
+        // not consume it today, matching the adapter's stated job of
+        // supplying what the real IR has, not just what today's one
+        // consumer happens to read (see D-0052's evidence for the honest
+        // caveat: no current caller reads this field yet).
+        const names = [];
+        _identifiersIn(node.value, names);
+        returns.push({ line: node.line ?? fn.line ?? 0, names });
+      }
+    }
+  }
+  return { decls, calls, returns };
+}
+
+/**
+ * Build the flat, per-file map annotatePrivacyTaint() expects, from the real
+ * Layer-1 IR plus the raw file contents (for the `_content` field it uses
+ * for snippet extraction — the IR itself carries no raw source text).
+ *
+ * @param {Record<string,object>} perFileIR - ir/index.js#buildProjectIR's `perFile` (or buildProjectIRAsync's)
+ * @param {Record<string,string>} fileContents
+ * @param {object|null} [storedRegistry] - engine.js#buildStoredTaintRegistry's
+ *   output, for FR-401's "storage" element. Optional and additive: omitted
+ *   (or not an object) yields `storage: []` for every file, same
+ *   degrade-gracefully convention as every other field here — this is not a
+ *   second copy of the registry's own computation, just a per-file view of
+ *   the one the engine already builds once per scan.
+ * @returns {Map<string, {_content:string, decls:Array, calls:Array, returns:Array, storage:Array}>}
+ */
+export function adaptIRForPrivacyTaint(perFileIR, fileContents, storedRegistry) {
+  const out = new Map();
+  const fc = fileContents || {};
+  for (const [file, content] of Object.entries(fc)) {
+    if (typeof content !== 'string') continue;
+    const fileIR = perFileIR ? perFileIR[file] : null;
+    // FR-401's "types" element: a real, TypeScript-only signal via a
+    // separate parse (see _extractTsTypes's own header) — a no-op Map for
+    // every non-.ts/.tsx file, so this costs nothing on the common path.
+    const tsTypes = _extractTsTypes(file, content);
+    const { decls, calls, returns } = fileIR ? _adaptFile(fileIR, tsTypes) : { decls: [], calls: [], returns: [] };
+    const storage = _storageForFile(file, storedRegistry);
+    out.set(file, { _content: content, decls, calls, returns, storage });
+  }
+  return out;
+}
+
+export const _internals = {
+  _calleeToString, _identifiersIn, _argsToTextArgs, _adaptFile, _storageForFile,
+  _tsTypeToString, _qualifiedTypeName, _extractTsTypes,
+};