@clear-capabilities/agentic-security-scanner 0.171.0 → 0.172.1

package/src/context-intelligence/graph-schema.js

@@ -0,0 +1,227 @@
+//
+// Versioned, typed declaration/reference graph (symbol-graph/1).
+//
+// This is an ADAPTER-FED CONTRACT, not a second analyzer: symbols and calls come from the shared IR (or, additively,
+// from imported compiler metadata). What this module adds is the part the context packer needs and the IR does not
+// carry: stable ids, hash-verifiable source spans, per-edge provenance and conditionality, and an explicit,
+// classified record of every call that could not be resolved. An unresolved call is data, never a leaf that looks
+// like fully analysed code.
+import { hashOf, sha256, sliceLines } from './canonical.js';
+import { spanFor } from './spans.js';
+import { buildImportMap, resolveViaImports } from './imports.js';
+
+export const GRAPH_SCHEMA_VERSION = 'symbol-graph/1';
+
+export const CONTINUATIONS = /^(?:next|done|cb|callback|resolve|reject|reply|fn_next)$/;
+
+/** Unresolved-call reasons that could be hiding first-party code (and so block a `complete` claim). */
+export const MATERIAL_REASONS = Object.freeze(new Set([
+  'name-matches-first-party-declaration', 'dynamic-callee', 'call-through-local-or-parameter',
+  'ambiguous-import-target', 'import-target-not-declared-in-module', 'unresolved-relative-import',
+]));
+
+export const EDGE_KINDS = Object.freeze(['call', 'dynamic_possible', 'external_unknown']);
+export const RESOLVERS = Object.freeze(['source-static', 'compiler-enriched']);
+
+/** Calls that cannot carry security meaning and are never first-party code. Classified, not dropped. */
+const INERT_CALL = /^(?:console\.\w+|Math\.\w+|JSON\.\w+|Object\.(?:keys|values|entries|assign|freeze)|Array\.\w+|Number\.\w+|String\.\w+|Promise\.\w+|parseInt|parseFloat|isNaN|String|Number|Boolean|next|require|print|len|str|int|float|bool|list|dict|tuple|range|isinstance|enumerate|zip|sorted|min|max|sum|abs|round|type|super|pure|fromMaybe|maybe|fmap|show|fst|snd|not|\w+\.(?:json|send|status|sendStatus|end|render|redirect|setHeader|header|then|catch|finally|push|pop|shift|unshift|slice|splice|join|split|map|filter|reduce|forEach|includes|indexOf|toString|trim|replace|toLowerCase|toUpperCase|keys|values|entries|startswith|endswith|lower|upper|items|strip))$/;
+const DYNAMIC_CALL = /(?:\[|\bapply\b|\bcall\b|\beval\b|\bFunction\b|__import__|getattr|dynamic|<dynamic>|\bsend\()/;
+
+function lastSegment(name) {
+  const s = String(name || '');
+  const parts = s.split(/[.:]|::/);
+  return parts[parts.length - 1] || s;
+}
+
+/** Largest CFG line of a function (0 when it has no CFG). Used only as a lower bound for a span end. */
+function cfgMaxLine(fn) {
+  let m = 0;
+  const nodes = fn && fn.cfg && fn.cfg.nodes;
+  if (nodes) for (const n of Object.values(nodes)) if (Number.isInteger(n.line) && n.line > m) m = n.line;
+  return m;
+}
+
+/** Names a function binds locally: its parameters and every assignment target in its CFG. */
+function localNamesOf(fn) {
+  const set = new Set((fn && Array.isArray(fn.params) ? fn.params : []).map(String));
+  const nodes = fn && fn.cfg && fn.cfg.nodes;
+  if (nodes) for (const n of Object.values(nodes)) if (n.kind === 'assign' && typeof n.target === 'string') set.add(n.target);
+  return set;
+}
+
+/**
+ * Is `nodeId` on every modelled path from entry to exit? (CFG dominance, by removal.) Bounded: a CFG larger than
+ * the cap reports 'unknown' rather than paying a quadratic cost on a generated file.
+ */
+export function conditionalityOf(fn, nodeId) {
+  const cfg = fn && fn.cfg;
+  if (!cfg || !cfg.nodes || !nodeId || !cfg.nodes[nodeId]) return 'unknown';
+  if (Object.keys(cfg.nodes).length > 600) return 'unknown';
+  if (nodeId === cfg.entry || nodeId === cfg.exit) return 'unconditional';
+  const seen = new Set([cfg.entry]);
+  const stack = [cfg.entry];
+  while (stack.length) {
+    const cur = stack.pop();
+    for (const s of cfg.nodes[cur]?.succ || []) {
+      if (s === nodeId || seen.has(s)) continue;
+      seen.add(s);
+      stack.push(s);
+    }
+  }
+  return seen.has(cfg.exit) ? 'conditional' : 'unconditional';
+}
+
+/**
+ * Build the graph from IR facts.
+ *   fileContents  { path: normalised text }
+ *   functions     Map<qid, fn>  (the IR call graph's `functions`)
+ *   edges         [{caller, callee|null, calleeName, line, site}]
+ *   provenance    'source-static' | 'compiler-enriched'
+ */
+export function buildSymbolGraph({ fileContents, functions, edges }) {
+  const linesOf = new Map();
+  const lines = (f) => {
+    if (!linesOf.has(f)) linesOf.set(f, (fileContents[f] || '').split('\n'));
+    return linesOf.get(f);
+  };
+
+  // Stable ids: file + declared name + ordinal among same-named declarations in that file, ordered by line. An edit
+  // ABOVE a function therefore does not rename it; only adding a same-named sibling above it does.
+  const rows = [...functions.values()]
+    .filter(fn => fn && fn.file && fileContents[fn.file] !== undefined)
+    .sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : (a.line - b.line) || (a.qid < b.qid ? -1 : 1));
+  const ordinal = new Map();
+  const idByQid = new Map();
+  const symbols = [];
+  for (const fn of rows) {
+    const anon = /^(?:anon|anonymous|<anonymous>|lambda)\b/.test(fn.name || '') || !fn.name;
+    const base = anon ? `${fn.file}::<anon>@${fn.line}` : `${fn.file}::${fn.name}`;
+    const k = ordinal.get(base) || 0;
+    ordinal.set(base, k + 1);
+    const id = !anon && k === 0 ? base : (anon ? base : `${base}#${k + 1}`);
+    idByQid.set(fn.qid, id);
+    const span = spanFor(fn.file, lines(fn.file), fn.line, cfgMaxLine(fn));
+    const text = sliceLines(fileContents[fn.file], span.startLine, span.endLine);
+    symbols.push({
+      id,
+      name: fn.name || '<anon>',
+      kind: fn.name === '<module>' ? 'module-top-level' : 'function',
+      file: fn.file,
+      startLine: span.startLine,
+      endLine: span.endLine,
+      declLine: fn.line,
+      spanPrecision: span.precision,
+      spanHash: sha256(text),
+      params: Array.isArray(fn.params) ? fn.params.map(String) : [],
+      resolver: 'source-static',
+    });
+  }
+  symbols.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+  const byLastName = new Map();
+  for (const s of symbols) {
+    if (s.kind !== 'function' || s.name.startsWith('<')) continue;
+    const key = lastSegment(s.name);
+    if (!byLastName.has(key)) byLastName.set(key, []);
+    byLastName.get(key).push(s.id);
+  }
+
+  const imports = buildImportMap(fileContents);
+  const symbolsByFileName = new Map();
+  for (const s of symbols) {
+    if (s.kind !== 'function' || s.id.includes('::<anon>@')) continue;
+    for (const key of new Set([s.name, lastSegment(s.name)])) {
+      const k = `${s.file}\0${key}`;
+      if (!symbolsByFileName.has(k)) symbolsByFileName.set(k, []);
+      symbolsByFileName.get(k).push(s.id);
+    }
+  }
+
+  const byFullName = new Map();
+  for (const s of symbols) {
+    if (s.kind !== 'function' || s.id.includes('::<anon>@')) continue;
+    if (!byFullName.has(s.name)) byFullName.set(s.name, []);
+    byFullName.get(s.name).push(s.id);
+  }
+
+  const graphEdges = [];
+  for (const e of edges || []) {
+    const from = idByQid.get(e.caller);
+    if (!from) continue;
+    const callerFn = functions.get(e.caller);
+    const callerFile = callerFn.file;
+    const base = {
+      from,
+      line: Number.isInteger(e.line) ? e.line : 0,
+      calleeName: String(e.calleeName || ''),
+      resolver: 'source-static',
+      conditionality: conditionalityOf(callerFn, e.site),
+      resolution: 'ir',
+    };
+    const to = e.callee ? idByQid.get(e.callee) : null;
+    if (to) {
+      graphEdges.push({ ...base, to, kind: 'call', confidence: 'high', unresolvedReason: null, candidates: [] });
+      continue;
+    }
+    const name = base.calleeName;
+    const push = (kind, confidence, unresolvedReason, candidates = [], extra = {}) => graphEdges.push({ ...base, ...extra, to: null, kind, confidence, unresolvedReason, candidates });
+
+    if (INERT_CALL.test(name) || CONTINUATIONS.test(name)) { push('external_unknown', 'high', 'inert-builtin'); continue; }
+
+    // a fully qualified name (`Auth.requireUser`, `Class.method`) that matches exactly one declaration IS that declaration
+    if (/[.:]/.test(name)) {
+      const q = (byFullName.get(name) || []).filter(id => id !== from);
+      if (q.length === 1) { graphEdges.push({ ...base, to: q[0], kind: 'call', confidence: 'high', unresolvedReason: null, candidates: [], resolution: 'qualified-name' }); continue; }
+    }
+
+    const imp = resolveViaImports(imports, callerFile, name);
+    if (imp && imp.kind === 'exact-import') {
+      const ids = (symbolsByFileName.get(`${imp.targetFile}\0${imp.member}`) || []).filter(id => id !== from);
+      if (ids.length === 1) { graphEdges.push({ ...base, to: ids[0], kind: 'call', confidence: 'high', unresolvedReason: null, candidates: [], resolution: 'import' }); continue; }
+      push('external_unknown', 'low', ids.length ? 'ambiguous-import-target' : 'import-target-not-declared-in-module', ids.slice(0, 5));
+      continue;
+    }
+    if (imp && imp.kind === 'third-party') { push('external_unknown', 'high', 'third-party-import'); continue; }
+    if (imp && imp.kind === 'unresolved-import') { push('external_unknown', 'low', 'unresolved-relative-import'); continue; }
+
+    // a bare identifier that is a parameter or a local assignment is a call through a value: the target is data
+    if (/^[A-Za-z_$][\w$]*$/.test(name) && !imp && localNamesOf(callerFn).has(name)) { push('dynamic_possible', 'low', 'call-through-local-or-parameter'); continue; }
+    if (DYNAMIC_CALL.test(name) || name === '') { push('dynamic_possible', 'low', 'dynamic-callee'); continue; }
+
+    const cand = (byLastName.get(lastSegment(name)) || []).filter(id => id !== from).slice(0, 5);
+    if (cand.length) push('external_unknown', 'low', 'name-matches-first-party-declaration', cand);
+    else push('external_unknown', 'high', 'external-boundary');
+  }
+  graphEdges.sort((a, b) =>
+    (a.from < b.from ? -1 : a.from > b.from ? 1 : 0) || (a.line - b.line) || (a.calleeName < b.calleeName ? -1 : a.calleeName > b.calleeName ? 1 : 0) || ((a.to || '') < (b.to || '') ? -1 : 1));
+
+  const snapshotHash = hashOf(Object.keys(fileContents).sort().map(f => [f, sha256(fileContents[f])]));
+  const body = { schemaVersion: GRAPH_SCHEMA_VERSION, snapshotHash, symbols, edges: graphEdges, imports: imports.map(i => ({ file: i.file, local: i.local, source: i.source, member: i.member, kind: i.kind, target: i.target })) };
+  return { ...body, hash: hashOf(body) };
+}
+
+/**
+ * Structural validation. Returns a list of problems (empty = valid): dangling ids, spans outside the file, a span
+ * hash that no longer matches the text, an edge that names a symbol that is not in the graph.
+ */
+export function validateGraph(graph, fileContents) {
+  const problems = [];
+  if (!graph || graph.schemaVersion !== GRAPH_SCHEMA_VERSION) return ['unsupported-schema-version'];
+  const ids = new Set(graph.symbols.map(s => s.id));
+  if (ids.size !== graph.symbols.length) problems.push('duplicate-symbol-id');
+  for (const s of graph.symbols) {
+    const text = fileContents[s.file];
+    if (typeof text !== 'string') { problems.push(`missing-file:${s.file}`); continue; }
+    const n = text.split('\n').length;
+    if (!(s.startLine >= 1 && s.endLine >= s.startLine && s.endLine <= n)) { problems.push(`span-out-of-range:${s.id}`); continue; }
+    if (sha256(sliceLines(text, s.startLine, s.endLine)) !== s.spanHash) problems.push(`stale-span-hash:${s.id}`);
+  }
+  for (const e of graph.edges) {
+    if (!ids.has(e.from)) problems.push(`dangling-from:${e.from}`);
+    if (e.to && !ids.has(e.to)) problems.push(`dangling-to:${e.to}`);
+    for (const c of e.candidates || []) if (!ids.has(c)) problems.push(`dangling-candidate:${c}`);
+  }
+  const { hash, ...rest } = graph;
+  if (hashOf(rest) !== hash) problems.push('graph-hash-mismatch');
+  return problems;
+}

package/src/context-intelligence/imports.js

@@ -0,0 +1,123 @@
+//
+// Import maps (JS/TS and Python): which local name in a file refers to which module, and which declaration in it.
+//
+// The shared IR resolves a call to a declaration only for the shapes it models; a destructured `require` or a named
+// ES import is not one of them, so a call such as `getReport(id)` arrives as an edge to nowhere. Left alone, nearly
+// every Express/Node route would be reported as having an unresolved call. This module recovers those edges from the
+// import statements themselves and records HOW each was resolved, so the result is still evidence and not a guess:
+//
+//   exact-import   the local name is bound by an import of a module in the repository, and that module declares a
+//                  function of that name (or, for a namespace, of the member name)
+//   third-party    the module is a package, not a repository file: a boundary, not first-party code
+//   unresolved     a relative import that no repository file satisfies
+//
+// Scope, stated plainly: this is statement-level pattern matching. Re-export chains, `import()` expressions,
+// computed `require` arguments and package-relative aliases (tsconfig paths) are not followed.
+import * as path from 'node:path';
+
+const JS_EXTS = ['', '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '/index.js', '/index.mjs', '/index.ts', '/index.tsx'];
+
+function resolveJsModule(fromFile, source, files) {
+  if (!source.startsWith('.')) return { kind: 'third-party', target: null };
+  const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), source));
+  for (const ext of JS_EXTS) if (files.has(base + ext)) return { kind: 'repo', target: base + ext };
+  return { kind: 'unresolved', target: null };
+}
+
+function resolvePyModule(fromFile, dotted, files) {
+  let dir = path.posix.dirname(fromFile);
+  let mod = dotted;
+  const lead = /^\.+/.exec(mod);
+  const candidatesBase = [];
+  if (lead) {
+    for (let i = 1; i < lead[0].length; i++) dir = path.posix.dirname(dir);
+    mod = mod.slice(lead[0].length);
+    candidatesBase.push(dir === '.' ? '' : dir);
+  } else {
+    candidatesBase.push('', path.posix.dirname(fromFile) === '.' ? '' : path.posix.dirname(fromFile));
+  }
+  for (const b of candidatesBase) {
+    const rel = mod.replace(/\./g, '/');
+    for (const cand of [rel ? `${rel}.py` : '__init__.py', rel ? `${rel}/__init__.py` : '__init__.py']) {
+      const full = b ? path.posix.join(b, cand) : cand;
+      if (files.has(full)) return { kind: 'repo', target: full };
+    }
+  }
+  return { kind: lead ? 'unresolved' : 'third-party', target: null };
+}
+
+function stripComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n]/g, ' ')).replace(/(^|[^:'"`\\])\/\/[^\n]*/g, (m, p1) => p1 + ' '.repeat(m.length - p1.length));
+}
+
+function names(list) {
+  return list.split(',').map(s => s.trim()).filter(Boolean).map(s => {
+    const m = /^(?:\w+\s+as\s+)?([\w$]+)$/.exec(s.replace(/^type\s+/, '').replace(/^([\w$]+)\s*:\s*([\w$]+)$/, '$1 as $2'));
+    const parts = s.replace(/^type\s+/, '').split(/\s+as\s+|\s*:\s*/).map(x => x.trim()).filter(Boolean);
+    void m;
+    if (parts.length === 2) return { imported: parts[0], local: parts[1] };
+    if (parts.length === 1) return { imported: parts[0], local: parts[0] };
+    return null;
+  }).filter(Boolean).filter(n => /^[\w$]+$/.test(n.imported) && /^[\w$]+$/.test(n.local));
+}
+
+/** Import entries for one JS/TS file. */
+function jsImports(file, text, files) {
+  const t = stripComments(text);
+  const out = [];
+  const add = (local, source, member) => out.push({ file, local, source, member, ...resolveJsModule(file, source, files) });
+  for (const m of t.matchAll(/\b(?:const|let|var)\s*\{([^}]*)\}\s*=\s*(?:await\s+)?require\(\s*['"]([^'"]+)['"]\s*\)/g)) for (const n of names(m[1])) add(n.local, m[2], n.imported);
+  for (const m of t.matchAll(/\b(?:const|let|var)\s+([\w$]+)\s*=\s*(?:await\s+)?require\(\s*['"]([^'"]+)['"]\s*\)/g)) add(m[1], m[2], '*');
+  for (const m of t.matchAll(/\bimport\s+(?:type\s+)?([\w$]+)?\s*,?\s*(?:\{([^}]*)\}|\*\s+as\s+([\w$]+))?\s*from\s*['"]([^'"]+)['"]/g)) {
+    if (m[1]) add(m[1], m[4], 'default');
+    if (m[2]) for (const n of names(m[2])) add(n.local, m[4], n.imported);
+    if (m[3]) add(m[3], m[4], '*');
+  }
+  return out;
+}
+
+function pyImports(file, text, files) {
+  const out = [];
+  const add = (local, source, member) => out.push({ file, local, source, member, ...resolvePyModule(file, source, files) });
+  // the unparenthesised form ends at the line end; only the parenthesised form may span lines
+  for (const m of text.matchAll(/^[ \t]*from[ \t]+([.\w]+)[ \t]+import[ \t]+(?:\(([\w\s,]+)\)|([\w \t,]+))/gm)) {
+    for (const n of (m[2] ?? m[3]).split(',').map(s => s.trim()).filter(Boolean)) {
+      const p = n.split(/\s+as\s+/);
+      add(p[1] || p[0], m[1], p[0]);
+    }
+  }
+  for (const m of text.matchAll(/^[ \t]*import\s+([.\w]+)(?:\s+as\s+(\w+))?\s*$/gm)) add(m[2] || m[1].split('.')[0], m[1], '*');
+  return out;
+}
+
+/** All import entries, deterministically ordered. */
+export function buildImportMap(fileContents) {
+  const files = new Set(Object.keys(fileContents));
+  const out = [];
+  for (const file of [...files].sort()) {
+    if (/\.(?:js|jsx|mjs|cjs|ts|tsx)$/i.test(file)) out.push(...jsImports(file, fileContents[file], files));
+    else if (/\.py$/i.test(file)) out.push(...pyImports(file, fileContents[file], files));
+  }
+  return out.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0) || (a.local < b.local ? -1 : a.local > b.local ? 1 : 0) || (a.source < b.source ? -1 : 1));
+}
+
+/**
+ * Resolve a callee name used in `file` against the import map.
+ * Returns { kind:'exact-import', targetFile, member } | { kind:'third-party' } | { kind:'unresolved-import' } | null.
+ */
+export function resolveViaImports(imports, file, calleeName) {
+  const parts = String(calleeName || '').split('.');
+  const head = parts[0];
+  const imp = imports.filter(i => i.file === file && i.local === head);
+  if (!imp.length) return null;
+  const i = imp[0];
+  if (i.kind === 'third-party') return { kind: 'third-party' };
+  if (i.kind === 'unresolved') return { kind: 'unresolved-import' };
+  if (parts.length === 1) {
+    const member = i.member === '*' || i.member === 'default' ? head : i.member;
+    return { kind: 'exact-import', targetFile: i.target, member, namespaceCall: i.member === '*' || i.member === 'default' };
+  }
+  if (i.member === '*' || i.member === 'default') return { kind: 'exact-import', targetFile: i.target, member: parts[parts.length - 1], namespaceCall: false };
+  // `db.query()` where `db` is a NAMED import: a method of an imported object, not a function of that module
+  return { kind: 'imported-object-method' };
+}

package/src/context-intelligence/manifest.js

@@ -0,0 +1,99 @@
+//
+// context-manifest/1: the inspectable record behind every bundle.
+//
+// A manifest answers, without any model: which entry point, which exact source spans (with hashes), which controls
+// were seen and how they were established, what could not be resolved, what was left out and why, and how complete
+// the bundle is. `validateManifest` enforces the contract's hard rules, so a manifest that over-claims is an error,
+// not a warning.
+import { hashOf, safeRelPath, sha256, sliceLines } from './canonical.js';
+import { evaluateProtection } from './reachability.js';
+
+export const MANIFEST_SCHEMA_VERSION = 'context-manifest/1';
+export const INTEGRITY_VALUES = Object.freeze(['complete', 'partial', 'unavailable']);
+
+/** Content-addressed key of a bundle set. Depends on what the model would see and how it was built, never on the commit. */
+export function contextHashOf({ entrypoint, pack, graphSchema }) {
+  return hashOf({
+    algorithm: 'context-hash/1',
+    graphSchema,
+    entrypoint: { kind: entrypoint.kind, method: entrypoint.method, path: entrypoint.pathTemplate, handler: entrypoint.handlerSymbol },
+    profile: pack.profile, maxTokens: pack.maxTokens, prune: pack.pruneLowValue,
+    packages: pack.packages.map(p => p.sha256),
+    integrity: pack.integrity,
+  });
+}
+
+export function buildManifest({ entrypoint, reach, pack, graph, fileContents, repository, semanticSource = ['static-ir'] }) {
+  const omittedWithControls = pack.omissions.some(o => o.reason === 'omitted_due_to_budget' && o.symbolId && reach.facts.some(f => f.symbolId === o.symbolId));
+  const protection = evaluateProtection({ facts: reach.facts, unknowns: reach.unknowns, omittedWithControls, capped: reach.capped });
+  const byId = new Map(graph.symbols.map(s => [s.id, s]));
+
+  const reachableSymbols = reach.visited.map(v => {
+    const s = byId.get(v.symbolId);
+    return { symbolId: v.symbolId, file: s.file, start: { line: s.startLine, column: 1 }, end: { line: s.endLine, column: 1 }, spanHash: s.spanHash, spanPrecision: s.spanPrecision, reason: v.reason, depth: v.depth, pathFromRoot: v.path, confidence: v.confidence };
+  });
+  const includedSymbols = new Set(pack.packages.flatMap(p => p.segments.flatMap(s => s.symbolIds)));
+  for (const r of reachableSymbols) r.included = includedSymbols.has(r.symbolId) || (reach.root && reach.root.kind === 'inline-block' && r.reason === 'handler');
+
+  const manifest = {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    entrypointId: entrypoint.id,
+    entrypoint: {
+      kind: entrypoint.kind, method: entrypoint.method, path: entrypoint.pathTemplate, framework: entrypoint.framework, language: entrypoint.language,
+      handlerSymbol: entrypoint.handlerSymbol, handlerKind: entrypoint.handlerKind, handlerConfidence: entrypoint.handlerConfidence,
+      registrationSite: entrypoint.registrationSite, authScheme: entrypoint.authScheme, middleware: entrypoint.middleware,
+    },
+    repository,
+    graph: { schemaVersion: graph.schemaVersion, hash: graph.hash, source: semanticSource },
+    context: {
+      profile: pack.profile, maxTokens: pack.maxTokens, integrity: pack.integrity, integrityReasons: [...pack.integrityReasons].sort(),
+      tokenizer: pack.tokenizer, pruneLowValue: pack.pruneLowValue,
+      packages: pack.packages.map(p => ({ index: p.index, total: p.total, setId: p.setId, sha256: p.sha256, tokensEstimated: p.tokensEstimated, standalone: p.standalone, integrity: p.integrity, segments: p.segments })),
+    },
+    reachableSymbols,
+    // observed and inferred are kept apart on purpose: a name is not an observation
+    controls: reach.facts.filter(f => f.category === 'control').map(f => ({ symbolId: f.symbolId, file: f.file, line: f.line, kind: f.kind, evidence: f.evidence, basis: f.basis, rejectionSeen: f.rejectionSeen, order: f.effLine === -1 ? 'before-handler' : null, status: 'included' })),
+    sensitiveOperations: reach.facts.filter(f => f.category === 'sensitive').map(f => ({ symbolId: f.symbolId, file: f.file, line: f.line, kind: f.kind, basis: f.basis })),
+    protection,
+    unknowns: reach.unknowns.map(u => ({ type: u.type, site: u.site, calleeName: u.calleeName || null, reason: u.reason, material: u.material, candidates: u.candidates || [] })),
+    boundaries: reach.boundaries,
+    omissions: pack.omissions,
+    traversal: { capped: reach.capped, cycles: reach.cycles, limits: reach.limits, unvisited: reach.unvisited },
+    status: { entrypoint: entrypoint.disposition, reachability: reach.capped || reach.unknowns.some(u => u.material) ? 'partial' : (reach.root ? 'complete' : 'unavailable'), bundle: pack.integrity },
+    resolutionReasons: entrypoint.resolutionReasons,
+  };
+  manifest.contextHash = contextHashOf({ entrypoint, pack, graphSchema: graph.schemaVersion });
+  manifest.manifestHash = hashOf({ ...manifest, repository: undefined });
+  return manifest;
+}
+
+/**
+ * Contract validation. Returns problems (empty = valid). With `fileContents` it also verifies every span hash against
+ * the current source, which is what turns a stale manifest into an error instead of a quiet mismatch.
+ */
+export function validateManifest(m, { fileContents = null } = {}) {
+  const p = [];
+  if (!m || m.schemaVersion !== MANIFEST_SCHEMA_VERSION) return ['unsupported-schema-version'];
+  if (!INTEGRITY_VALUES.includes(m.context?.integrity)) p.push('bad-integrity-value');
+  const materialUnknowns = (m.unknowns || []).some(u => u.material);
+  const budgetOmissions = (m.omissions || []).some(o => o.reason === 'omitted_due_to_budget');
+  if (m.context?.integrity === 'complete' && (materialUnknowns || budgetOmissions || m.traversal?.capped)) p.push('complete-with-material-gaps');
+  if (m.context?.integrity === 'complete' && m.status?.entrypoint && m.status.entrypoint !== 'resolved') p.push('complete-with-unresolved-entrypoint');
+  for (const pk of m.context?.packages || []) {
+    if (pk.total > 1 && pk.integrity === 'complete') p.push(`standalone-complete-in-split-set:${pk.index}`);
+    for (const s of pk.segments || []) {
+      if (!safeRelPath(s.file) || s.file !== safeRelPath(s.file)) p.push(`unsafe-path:${s.file}`);
+      if (fileContents) {
+        const t = fileContents[s.file];
+        if (typeof t !== 'string') { p.push(`missing-file:${s.file}`); continue; }
+        if (s.startLine < 1 || s.endLine > t.split('\n').length || s.endLine < s.startLine) { p.push(`span-out-of-range:${s.file}:${s.startLine}`); continue; }
+        if (sha256(sliceLines(t, s.startLine, s.endLine)) !== s.spanHash) p.push(`stale-span:${s.file}:${s.startLine}-${s.endLine}`);
+      }
+    }
+  }
+  const probe = { ...m };
+  delete probe.manifestHash;
+  if (hashOf({ ...probe, repository: undefined }) !== m.manifestHash) p.push('manifest-hash-mismatch');
+  if (JSON.stringify(m).match(/"(?:file|site)":"(?:\/|[A-Za-z]:)/)) p.push('absolute-host-path');
+  return p;
+}