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

package/dist/agentic-security.mjs.sha256

@@ -1 +1 @@
-40d5efd2eaa9410528e168bd5055148ac0de203d57c44b68abc12c25618db762  agentic-security.mjs
+edcc9e08f076b2bc50946c512557c15038e337fa568bc490586fc882ca1c11bc  agentic-security.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clear-capabilities/agentic-security-scanner",
-  "version": "0.171.0",
+  "version": "0.172.0",
   "description": "Scanner engine for the agentic-security Claude Code plugin: SAST, SCA with reachability and CISA KEV, secrets, IaC, Haskell and Nix/NixOS, prompt-injection, MCP/agent-tool audit, authZ analysis, SBOM, compliance attestation, and more.",
   "type": "module",
   "main": "src/index.js",
@@ -49,7 +49,7 @@
   "optionalDependencies": {
     "tree-sitter-wasms": "0.1.13",
     "web-tree-sitter": "0.20.8",
-    "z3-solver": "^5.2.0"
+    "z3-solver": "^5.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",
@@ -121,7 +121,7 @@
     "verification:replay-example": "node ../scripts/verification-replay-example.mjs",
     "test:lifecycle": "node --test test/ci-hang-protection.test.js test/ci-test-shards.test.js test/pre-bash-guard.test.js test/lsp-protocol-smoke.test.js test/ide-surfaces.test.js test/detector-liveness.test.js test/bench-watchdog.test.js test/ci-parity.test.js test/dead-code.test.js test/no-dead-modules.test.js test/no-orphan-scripts.test.js test/no-stray-state.test.js test/tree-integrity.test.js test/stop-hook.test.js test/plugin-self-check.test.js test/skills-registry.test.js test/bodyguard.test.js test/cache-invalidator-guard.test.js test/dispatch-pre-tool.test.js test/dispatch-user-prompt.test.js test/session-start-model-capture.test.js test/sandbox.test.js test/sandbox-escape.test.js test/trust-boundary.test.js test/ci-templates.test.js test/agent-mcp-tools.test.js test/triage-command.test.js test/no-orphan-tests.test.js test/supply-command.test.js test/posture-command.test.js test/labs-command.test.js test/compliance-command.test.js test/check-doc-drift.test.js test/dist-chunks-tracked.test.js && node ../scripts/lint-command-descriptions.mjs test/workflow-confinement.test.js test/check-bundle-source.test.js test/ship.test.js",
     "test:eval": "node --test test/independent-eval.test.js test/realworld-recall.test.js",
-    "test:discovery": "node --test test/discovery-partition.test.js test/discovery-lenses.test.js test/discovery-hunter.test.js test/discovery-confirm.test.js test/discovery-disprove.test.js test/discovery-judge.test.js test/discovery-run.test.js test/discovery-wiring.test.js test/discovery-llm-invoke.test.js test/local-only-mode.test.js",
+    "test:discovery": "node --test test/discovery-partition.test.js test/discovery-lenses.test.js test/discovery-hunter.test.js test/discovery-confirm.test.js test/discovery-disprove.test.js test/discovery-judge.test.js test/discovery-run.test.js test/discovery-wiring.test.js test/discovery-llm-invoke.test.js test/local-only-mode.test.js test/context-intelligence/build-js.test.js test/context-intelligence/build-python-haskell.test.js test/context-intelligence/hie-adapter.test.js test/context-intelligence/store.test.js test/context-intelligence/review-queue.test.js test/context-intelligence/packer-egress.test.js test/context-intelligence/evaluation.test.js test/context-intelligence/queue-diff.test.js test/context-intelligence/cli.test.js test/context-intelligence/resilience.test.js test/context-intelligence/frameworks.test.js test/context-intelligence/skew-git-rls.test.js test/context-intelligence/git-diff-candidates.test.js",
     "eval:independent": "node ../bench/independent-eval/runner.mjs",
     "eval:independent:gate": "node ../bench/independent-eval/runner.mjs --gate default",
     "smoke": "node bin/agentic-security.js scan test/fixtures/vulnerable-js",

package/src/context-intelligence/CLAUDE.md

@@ -0,0 +1,21 @@
+# context-intelligence/
+
+Deterministic Context Intelligence (the `context` command). Opt-in and additive: nothing in the default scan imports this directory. Guide: `docs/guides/context-intelligence.md`; architecture: `docs/architecture/context-intelligence.md`.
+
+## Invariants (break one and a test fails)
+
+- `build` is deterministic and makes no model or network call. Same snapshot and config give byte-identical manifests.
+- Unresolved is never dropped. A material unresolved edge, a budget omission, a cap or a split prevents `complete`.
+- A control that runs after the sensitive operation is `evaluated_and_ineffective`, never protection.
+- Model output cannot set severity. A citation outside the bundle invalidates the review. Severity comes from the existing confirmation tier.
+- Store writes are atomic and refuse links and unsafe paths. Stored packages are re-checked against their hashes.
+- A job with no verified result is missing coverage, never a clean result.
+- Evaluation is synthetic. Scorecards must say so and must not state an accuracy claim. Holdout use is ledgered.
+
+## Where things are
+
+See the module table in the architecture doc. Tests: `test/context-intelligence/` (in the `test:discovery` scope). The capability matrix in `capabilities.js` cites test files; `build-js.test.js` checks they exist.
+
+## Reuse, do not fork
+
+Model calls go through `discovery/llm-invoke.js` and the egress policy. Confirmation, refutation and judging are `discovery/{confirm,disprove,judge}.js`. Grouped intervals come from `posture/evaluation/interval.js`. State paths come from `posture/state-dir.js`.

package/src/context-intelligence/adapters/existing-ir.js

@@ -0,0 +1,14 @@
+//
+// Adapter: shared IR (`buildProjectIR`) -> symbol-graph/1.
+//
+// The IR is REUSED, not copied. All languages the IR lowers (JS/TS, Python, Java, C#, Kotlin, Go, PHP, Ruby, Rust,
+// C/C++, and Haskell through the shared call graph) arrive through the one call graph, so this adapter has no
+// per-language logic; per-language capability is a matter for the capability matrix, not for branching here.
+import { buildProjectIR } from '../../ir/index.js';
+import { buildSymbolGraph } from '../graph-schema.js';
+
+export function graphFromSource(fileContents) {
+  const { perFile, callGraph } = buildProjectIR(fileContents);
+  const graph = buildSymbolGraph({ fileContents, functions: callGraph.functions, edges: callGraph.edges });
+  return { graph, perFile, callGraph };
+}

package/src/context-intelligence/adapters/haskell-hie.js

@@ -0,0 +1,138 @@
+//
+// Optional compiler-semantic metadata: a READ-ONLY importer for a Haskell declaration/reference export (`hie-export/1`).
+//
+// What this is and is not:
+//   * It imports an export that already exists. It never runs GHC, `hiedb`, Cabal or Stack, never builds, and never
+//     executes anything from the repository (no Template Haskell, no custom Setup, no plugins). A later explicit
+//     metadata-build command would need a sandbox proof that does not exist in this build, so there is none.
+//   * `hie-export/1` is the interchange format DCI defines for the data GHC's `-fwrite-ide-info` / `hiedb` hold
+//     (declarations with exact spans, and references between them). Producing it from `.hie` files is a separate,
+//     explicit, operator step documented in docs/guides/context-intelligence.md; the binary `.hie` files themselves
+//     are not parsed here.
+//   * The export is untrusted input. It must name the compiler and tool, and it must carry the SHA-256 of every source
+//     file it describes; a file whose current hash differs makes the whole adapter DEGRADE (the static graph is kept and
+//     the mismatch is reported). Paths must be repository-relative and may not escape; sizes are capped.
+//   * Compiler facts are merged as additional, provenance-tagged evidence. A static edge is never silently overwritten:
+//     an unresolved static call that the compiler resolves is marked superseded (and counted as closed by the compiler);
+//     a static edge that DISAGREES with the compiler stays, and both are flagged as a conflict, which keeps the bundle
+//     partial.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { hashOf, safeRelPath, sha256 } from '../canonical.js';
+
+export const HIE_EXPORT_SCHEMA = 'hie-export/1';
+export const HIE_EXPORT_FILE = 'hie-export.json';
+const LIMITS = Object.freeze({ maxBytes: 16 * 1024 * 1024, maxDecls: 200000, maxRefs: 1000000, maxName: 300 });
+const SUPPORTED_COMPILER = /^ghc$/i;
+
+function degrade(reason, detail) { return { status: 'degraded', reason, detail: detail || null, declarations: [], references: [] }; }
+
+/**
+ * Load and validate an export. Returns { status: 'ok'|'degraded'|'off', ... }. Never throws, never reads outside the
+ * repository, and treats ANY validation failure as a degradation of the adapter, not of the scan.
+ */
+export function loadHieMetadata(rootReal, hieDir, { fileContents }) {
+  if (!hieDir) return { status: 'off', reason: 'no-directory-configured', declarations: [], references: [] };
+  const dirRel = safeRelPath(hieDir);
+  if (!dirRel) return degrade('unsafe-directory');
+  const abs = path.join(rootReal, dirRel, HIE_EXPORT_FILE);
+  let text;
+  try {
+    const st = fs.lstatSync(abs);
+    if (st.isSymbolicLink() || !st.isFile()) return degrade('not-a-regular-file');
+    if (st.size > LIMITS.maxBytes) return degrade('too-large');
+    const real = fs.realpathSync(abs);
+    if (real !== rootReal && !real.startsWith(rootReal + path.sep)) return degrade('escapes-root');
+    text = fs.readFileSync(abs, 'utf8');
+  } catch (e) {
+    return degrade(e && e.code === 'ENOENT' ? 'export-not-found' : 'unreadable');
+  }
+  let doc;
+  try { doc = JSON.parse(text); } catch { return degrade('invalid-json'); }
+  if (!doc || doc.schemaVersion !== HIE_EXPORT_SCHEMA) return degrade('unsupported-schema-version', String(doc && doc.schemaVersion));
+  if (!doc.compiler || !SUPPORTED_COMPILER.test(String(doc.compiler.name || '')) || typeof doc.compiler.version !== 'string') return degrade('compiler-not-identified');
+  if (!doc.tool || typeof doc.tool.name !== 'string' || typeof doc.tool.version !== 'string') return degrade('tool-not-identified');
+  if (!Array.isArray(doc.files) || !Array.isArray(doc.declarations) || !Array.isArray(doc.references)) return degrade('malformed');
+  if (doc.declarations.length > LIMITS.maxDecls || doc.references.length > LIMITS.maxRefs) return degrade('over-size-limit');
+
+  // source snapshot match: every file the export describes must be byte-identical to what is being analysed
+  const stale = [];
+  const described = new Set();
+  for (const f of doc.files) {
+    const rel = safeRelPath(String(f && f.path));
+    if (!rel || rel !== f.path) return degrade('unsafe-path-in-export', String(f && f.path).slice(0, 80));
+    described.add(rel);
+    if (typeof fileContents[rel] !== 'string') { stale.push(`${rel}:missing`); continue; }
+    if (sha256(fileContents[rel]) !== f.sha256) stale.push(`${rel}:hash-differs`);
+  }
+  if (stale.length) return degrade('source-snapshot-mismatch', stale.slice(0, 10).join(', '));
+
+  const declarations = [];
+  for (const d of doc.declarations) {
+    const rel = safeRelPath(String(d && d.file));
+    if (!rel || !described.has(rel) || typeof d.name !== 'string' || d.name.length > LIMITS.maxName) return degrade('malformed-declaration');
+    const total = fileContents[rel].split('\n').length;
+    if (![d.startLine, d.endLine].every(Number.isInteger) || d.startLine < 1 || d.endLine < d.startLine || d.endLine > total) return degrade('declaration-span-out-of-range', `${rel}:${d.name}`);
+    declarations.push({ name: d.name, file: rel, startLine: d.startLine, endLine: d.endLine });
+  }
+  const references = [];
+  for (const r of doc.references) {
+    if (!r || typeof r.from !== 'string' || typeof r.to !== 'string' || r.from.length > LIMITS.maxName || r.to.length > LIMITS.maxName || !Number.isInteger(r.line)) return degrade('malformed-reference');
+    references.push({ from: r.from, to: r.to, line: r.line });
+  }
+  declarations.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0) || a.startLine - b.startLine || (a.name < b.name ? -1 : 1));
+  references.sort((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : 0) || a.line - b.line || (a.to < b.to ? -1 : 1));
+  return { status: 'ok', tool: doc.tool, compiler: doc.compiler, declarations, references, exportHash: hashOf({ declarations, references }) };
+}
+
+/**
+ * Merge an imported export into the static graph. Returns { graph, semantic } where `semantic` carries the provenance
+ * and the static-versus-compiler difference report.
+ */
+export function mergeHieIntoGraph(graph, meta, fileContents) {
+  void fileContents;
+  if (meta.status !== 'ok') {
+    return { graph, semantic: { source: ['static-ir'], status: meta.status, reason: meta.reason || null, detail: meta.detail || null, diff: null } };
+  }
+  const idsByName = new Map();
+  for (const s of graph.symbols) {
+    if (s.kind !== 'function' || s.id.includes('::<anon>@')) continue;
+    if (!idsByName.has(s.name)) idsByName.set(s.name, []);
+    idsByName.get(s.name).push(s.id);
+  }
+  const edges = graph.edges.map(e => ({ ...e }));
+  const diff = { newSymbols: [], newEdges: 0, resolvedUnknowns: 0, conflicts: [], remainingMaterialUnknowns: 0, unmatchedReferences: 0 };
+
+  // declarations the static pass never saw are reported (not added: DCI has no source-hash-verified span for them
+  // beyond what the export says, and an export-only symbol would be an unverified span)
+  const known = new Set(graph.symbols.map(s => `${s.file}\0${s.name}`));
+  for (const d of meta.declarations) if (!known.has(`${d.file}\0${d.name}`)) diff.newSymbols.push(`${d.file}::${d.name}`);
+
+  for (const r of meta.references) {
+    const from = (idsByName.get(r.from) || [])[0];
+    const to = (idsByName.get(r.to) || [])[0];
+    if (!from || !to || (idsByName.get(r.from) || []).length !== 1 || (idsByName.get(r.to) || []).length !== 1) { diff.unmatchedReferences++; continue; }
+    const same = edges.filter(e => e.from === from && e.line === r.line);
+    const agree = same.find(e => e.to === to);
+    if (agree) continue; // static already has it: nothing to add
+    const conflicting = same.find(e => e.to && e.to !== to && e.calleeName.split(/[.:]/).pop() === r.to.split(/[.:]/).pop());
+    if (conflicting) {
+      conflicting.conflict = true;
+      diff.conflicts.push({ from, line: r.line, static: conflicting.to, compiler: to });
+      edges.push({ from, to, line: r.line, calleeName: r.to, kind: 'call', resolver: 'compiler-enriched', conditionality: 'unknown', resolution: 'compiler', confidence: 'high', unresolvedReason: null, candidates: [], conflict: true });
+      diff.newEdges++;
+      continue;
+    }
+    const unresolved = same.find(e => !e.to && (e.calleeName.split(/[.:]/).pop() === r.to.split(/[.:]/).pop()));
+    if (unresolved) { unresolved.superseded = true; diff.resolvedUnknowns++; }
+    edges.push({ from, to, line: r.line, calleeName: r.to, kind: 'call', resolver: 'compiler-enriched', conditionality: unresolved ? unresolved.conditionality : 'unknown', resolution: 'compiler', confidence: 'high', unresolvedReason: null, candidates: [], conflict: false });
+    diff.newEdges++;
+  }
+  edges.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));
+  diff.remainingMaterialUnknowns = edges.filter(e => !e.to && !e.superseded && e.confidence === 'low').length;
+  const body = { schemaVersion: graph.schemaVersion, snapshotHash: graph.snapshotHash, symbols: graph.symbols, edges, imports: graph.imports, semantic: { exportHash: meta.exportHash, compiler: meta.compiler, tool: meta.tool } };
+  return {
+    graph: { ...body, hash: hashOf(body) },
+    semantic: { source: ['static-ir', 'hie-import'], status: 'ok', compiler: meta.compiler, tool: meta.tool, exportHash: meta.exportHash, diff },
+  };
+}

package/src/context-intelligence/build.js

@@ -0,0 +1,68 @@
+//
+// Orchestration: source snapshot -> symbol graph -> entry points -> per-entry-point reachability -> bundles + manifests.
+// Pure with respect to the repository (read-only); persistence is store.js's job. No model, no network.
+import { graphFromSource } from './adapters/existing-ir.js';
+import { validateGraph } from './graph-schema.js';
+import { collectEntrypoints, countDispositions } from './entrypoints.js';
+import { reachFrom } from './reachability.js';
+import { packContext } from './packer.js';
+import { buildManifest } from './manifest.js';
+import { readSnapshot } from './files.js';
+import { repositoryInfo } from './repo-info.js';
+import { loadHieMetadata, mergeHieIntoGraph } from './adapters/haskell-hie.js';
+
+/**
+ * Build every bundle for a project.
+ *   opts.config   normalised DCI config
+ *   opts.route    optional filter: a label substring or an entrypoint id
+ *   opts.onEvent  optional progress callback (JSON-serialisable events)
+ */
+export async function buildContext(root, opts = {}) {
+  const config = opts.config;
+  const emit = typeof opts.onEvent === 'function' ? opts.onEvent : () => {};
+  const snap = opts.snapshot || await readSnapshot(root, { maxFiles: config.maxFiles });
+  if (!snap.ok) return { ok: false, reason: snap.reason, detail: snap };
+  const { fileContents } = snap;
+  emit({ event: 'snapshot', files: Object.keys(fileContents).length, skipped: snap.skipped.length });
+
+  let { graph, perFile, callGraph } = graphFromSource(fileContents);
+  let semantic = { source: ['static-ir'], status: 'off', diff: null };
+  if (config.semanticMetadata.mode === 'import') {
+    const meta = loadHieMetadata(snap.rootReal, config.semanticMetadata.haskellHieDir, { fileContents });
+    const merged = mergeHieIntoGraph(graph, meta, fileContents);
+    graph = merged.graph;
+    semantic = merged.semantic;
+  }
+  const problems = validateGraph(graph, fileContents);
+  if (problems.length) return { ok: false, reason: 'graph-invalid', detail: problems.slice(0, 20) };
+  emit({ event: 'graph', symbols: graph.symbols.length, edges: graph.edges.length, hash: graph.hash });
+
+  let entrypoints = await collectEntrypoints({ fileContents, graph, config });
+  const counts = countDispositions(entrypoints);
+  emit({ event: 'entrypoints', ...counts });
+  if (opts.route) entrypoints = entrypoints.filter(e => e.id === opts.route || e.label.includes(opts.route));
+
+  const repository = snap.commit ? { commit: snap.commit, dirty: false, snapshotHash: snap.snapshotHash } : repositoryInfo(snap.rootReal, snap.snapshotHash);
+  const bundles = [];
+  for (const ep of entrypoints) {
+    if (ep.disposition === 'excluded_by_policy') { bundles.push({ entrypoint: ep, manifest: null, pack: null, reach: null }); continue; }
+    const reach = reachFrom({ graph, fileContents, entrypoint: ep, limits: { maxSymbols: config.context.maxSymbols, maxDepth: config.context.maxDepth } });
+    const pack = packContext({ entrypoint: ep, reach, graph, fileContents, config: { profile: config.context.profile, maxTokens: config.context.maxTokens, pruneLowValue: config.context.pruneLowValue, tokenizer: opts.tokenizer } });
+    const manifest = buildManifest({ entrypoint: ep, reach, pack, graph, fileContents, repository, semanticSource: semantic.source });
+    bundles.push({ entrypoint: ep, manifest, pack, reach });
+    emit({ event: 'bundle', entrypoint: ep.id, integrity: pack.integrity, packages: pack.packages.length });
+  }
+  const built = bundles.filter(b => b.manifest);
+  return {
+    ok: true, root: snap.rootReal, repository, graph, semantic, ir: { perFile, callGraph }, snapshotHash: snap.snapshotHash, entrypoints, bundles, fileContents, skipped: snap.skipped,
+    summary: {
+      entrypointsFound: counts.total, resolved: counts.resolved, partial: counts.partially_resolved, unresolved: counts.unresolved, excluded: counts.excluded_by_policy,
+      bundlesBuilt: built.length,
+      complete: built.filter(b => b.manifest.context.integrity === 'complete').length,
+      partialBundles: built.filter(b => b.manifest.context.integrity === 'partial').length,
+      unavailable: built.filter(b => b.manifest.context.integrity === 'unavailable').length,
+      unresolvedEdges: built.reduce((n, b) => n + b.manifest.unknowns.filter(u => u.material).length, 0),
+      tokens: built.reduce((n, b) => n + b.pack.packages.reduce((m, p) => m + p.tokensEstimated, 0), 0),
+    },
+  };
+}

package/src/context-intelligence/candidates.js

@@ -0,0 +1,115 @@
+//
+// Review results -> existing discovery candidates -> existing adjudication.
+//
+// A DCI review is a hypothesis. This module normalises an accepted `potential_issue` into the SAME candidate schema the
+// `hunt` pipeline uses, so the existing machinery decides what happens next and nothing about it is reimplemented here:
+//
+//   confirm.js   routes the candidate back through the taint engine. A novel authorization or business-logic
+//                hypothesis the taint engine cannot prove stays `unconfirmed`; it is neither rejected nor promoted.
+//   disprove.js  the only stage that may remove a candidate, and only by an argued majority.
+//   judge.js     shapes the finding. Severity comes from the CONFIRMATION TIER (taint-confirmed high, sink-adjacent
+//                medium, unconfirmed low). A model's confidence, likelihood or adjectives are never an input, and
+//                nothing here can produce `critical`.
+//
+// One shared defect reached through many routes is ONE candidate with many witnesses, not many top-level findings.
+import { sha256 } from './canonical.js';
+import { confirmAll } from '../discovery/confirm.js';
+import { disprovePanel } from '../discovery/disprove.js';
+import { judgeCandidates } from '../discovery/judge.js';
+
+const SINK_ROLES = ['data-access', 'database-read', 'database-write', 'state-change', 'sink', 'side-effect'];
+
+function normalizeInvariant(s) { return String(s || '').toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').replace(/\s+/g, ' ').trim(); }
+
+function primaryEvidence(evidence) {
+  for (const role of SINK_ROLES) {
+    const hit = evidence.find(e => e.role === role);
+    if (hit) return hit;
+  }
+  return evidence[0];
+}
+
+/**
+ * Build candidates from verified reviews.
+ *   records   [{ review, entrypoints: [{id,label}], pack }]  (only status 'completed' + 'potential_issue' qualifies)
+ */
+export function reviewsToCandidates(records) {
+  const groups = new Map();
+  for (const r of records) {
+    const rv = r.review;
+    if (!rv || rv.status !== 'completed' || rv.conclusion !== 'potential_issue' || !rv.evidence.length) continue;
+    const ev = primaryEvidence(rv.evidence);
+    const key = sha256(`${r.pack.id}|${ev.file}|${ev.startLine}|${normalizeInvariant(rv.invariant)}`).slice(0, 12);
+    if (!groups.has(key)) {
+      groups.set(key, {
+        id: key,
+        focusAreaId: String(rv.contextHash).slice(0, 12),
+        lens: r.pack.lens,
+        title: `${r.pack.title}: ${r.entrypoints[0].label}`,
+        file: ev.file,
+        line: ev.startLine,
+        family: r.pack.family,
+        cwe: r.pack.cwe,
+        rationale: rv.narrative || rv.invariant,
+        entryPoint: r.entrypoints.map(e => e.label).join('; '),
+        sink: ev.claim || ev.role,
+        origin: 'context-intelligence',
+        questionPack: rv.questionPack,
+        advisoryOnly: rv.advisoryOnly === true,
+        witnesses: [],
+        sourceSpanEvidence: rv.evidence.map(e => ({ role: e.role, file: e.file, startLine: e.startLine, endLine: e.endLine })),
+        scopeIntegrity: { contextIntegrity: rv.contextIntegrity, standalone: rv.standalone, deterministicAgreement: rv.deterministicAgreement, deterministicProtection: rv.deterministicProtection || null },
+        reviewStatus: rv.status,
+        uncertainties: rv.uncertainties,
+        recommendedValidation: rv.recommendedValidation,
+      });
+    }
+    const g = groups.get(key);
+    for (const e of r.entrypoints) {
+      if (!g.witnesses.some(w => w.entrypointId === e.id)) g.witnesses.push({ entrypointId: e.id, label: e.label, contextHash: rv.contextHash, questionPack: rv.questionPack });
+    }
+  }
+  return [...groups.values()].sort((a, b) => (a.id < b.id ? -1 : 1));
+}
+
+/**
+ * Run the existing adjudication. All stages are optional and injected:
+ *   taintProbe   -> confirm.js     refute -> disprove.js (needs a governed invoker: `{ llmInvoke | endpoint policy }`)
+ * Returns { findings, duplicates, suppressed, refuted, advisory }. `findings` carry a `contextIntelligence` block and
+ * `parser: 'DISCOVERY'`, so the report layer keeps them advisory exactly as it does for `hunt`.
+ */
+export async function adjudicate(candidates, opts = {}) {
+  const advisory = candidates.filter(c => c.advisoryOnly);
+  const real = candidates.filter(c => !c.advisoryOnly);
+  const confirmed = await confirmAll(real, { taintProbe: opts.taintProbe });
+  let survivors = confirmed;
+  let refuted = [];
+  if (opts.refute) {
+    const panel = await disprovePanel(confirmed, { ...opts.refute, scanRoot: opts.scanRoot });
+    survivors = panel.survivors;
+    refuted = panel.refuted;
+  }
+  const byId = new Map(candidates.map(c => [c.id, c]));
+  const judged = judgeCandidates(survivors, opts.priorScan, opts.triageFeedback);
+  const decorate = (f) => {
+    const id = String(f.id).split('-').pop();
+    const c = byId.get(id) || survivors.find(s => f.id.endsWith(s.id)) || null;
+    if (!c) return f;
+    return {
+      ...f,
+      contextIntelligence: {
+        origin: 'context-intelligence', questionPack: c.questionPack, witnesses: c.witnesses, witnessCount: c.witnesses.length,
+        sourceSpanEvidence: c.sourceSpanEvidence, scopeIntegrity: c.scopeIntegrity, reviewStatus: c.reviewStatus,
+        uncertainties: c.uncertainties, recommendedValidation: c.recommendedValidation,
+        note: 'A model hypothesis checked for citations, not a proof. Severity comes from the confirmation tier only.',
+      },
+    };
+  };
+  return {
+    findings: judged.fresh.map(decorate),
+    duplicates: judged.duplicates.map(decorate),
+    suppressed: judged.suppressed.map(decorate),
+    refuted: refuted.map(c => ({ id: c.id, title: c.title, file: c.file, line: c.line, refutation: c.refutation })),
+    advisory: advisory.map(c => ({ id: c.id, title: c.title, file: c.file, line: c.line, questionPack: c.questionPack, witnesses: c.witnesses, rationale: c.rationale })),
+  };
+}

package/src/context-intelligence/canonical.js

@@ -0,0 +1,95 @@
+//
+// Canonical serialization, hashing and path/snapshot safety for Deterministic Context Intelligence.
+//
+// Everything DCI stores or compares goes through this module so that "same checkout + same config => same bytes" is
+// a property of one place. No clock, no randomness, no host path ever enters a hashed value.
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Bump when the canonical encoding below changes; it is mixed into every hash. */
+export const HASH_ALGORITHM = 'sha256/canon-1';
+
+export function sha256(text) {
+  return crypto.createHash('sha256').update(text).digest('hex');
+}
+
+/** CRLF/CR -> LF so a Windows checkout and a Unix one produce the same spans and hashes. */
+export function normalizeText(text) {
+  return String(text).replace(/\r\n?/g, '\n');
+}
+
+/**
+ * JSON with object keys sorted at every depth. Arrays keep their order (callers sort them where order is not
+ * meaningful). `undefined` members are dropped, exactly as JSON.stringify does, so a missing and an undefined field hash alike.
+ */
+export function canonicalJson(value) {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(v) {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) {
+      if (v[k] !== undefined) out[k] = sortKeys(v[k]);
+    }
+    return out;
+  }
+  return v;
+}
+
+export function hashOf(value) {
+  return sha256(`${HASH_ALGORITHM}\n${canonicalJson(value)}`);
+}
+
+/**
+ * A repository-relative path in canonical form, or null. Rejects absolute paths, drive letters, NUL, backslash
+ * tricks and any `..` segment: a manifest can never name a file outside the repository.
+ */
+export function safeRelPath(p) {
+  if (typeof p !== 'string' || p === '' || p.includes('\0')) return null;
+  const n = p.replace(/\\/g, '/');
+  if (n.startsWith('/') || /^[A-Za-z]:/.test(n)) return null;
+  const parts = n.split('/');
+  const out = [];
+  for (const seg of parts) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..') return null;
+    out.push(seg);
+  }
+  return out.length ? out.join('/') : null;
+}
+
+/**
+ * Read one repository file for analysis. Refuses a symlink and anything whose real path leaves the repository root,
+ * and refuses non-regular files. Returns { ok, text } or { ok:false, reason }; never throws.
+ */
+export function readRepoFile(rootReal, rel, { maxBytes = 2 * 1024 * 1024 } = {}) {
+  const safe = safeRelPath(rel);
+  if (!safe) return { ok: false, reason: 'unsafe-path' };
+  const abs = path.join(rootReal, safe);
+  try {
+    const st = fs.lstatSync(abs);
+    if (st.isSymbolicLink()) return { ok: false, reason: 'symlink' };
+    if (!st.isFile()) return { ok: false, reason: 'not-a-regular-file' };
+    if (st.size > maxBytes) return { ok: false, reason: 'too-large' };
+    const real = fs.realpathSync(abs);
+    if (real !== rootReal && !real.startsWith(rootReal + path.sep)) return { ok: false, reason: 'escapes-root' };
+    return { ok: true, text: normalizeText(fs.readFileSync(abs, 'utf8')) };
+  } catch (err) {
+    return { ok: false, reason: err && err.code ? String(err.code) : 'unreadable' };
+  }
+}
+
+/** Hash of the analysed file set: sorted [path, content hash] pairs. Order of discovery never matters. */
+export function snapshotHashOf(fileContents) {
+  const rows = Object.keys(fileContents).sort().map(f => [f, sha256(fileContents[f])]);
+  return hashOf(rows);
+}
+
+/** 1-based inclusive line slice of already-normalised text. */
+export function sliceLines(text, startLine, endLine) {
+  const lines = text.split('\n');
+  return lines.slice(Math.max(0, startLine - 1), Math.max(0, endLine)).join('\n');
+}

package/src/context-intelligence/capabilities.js

@@ -0,0 +1,33 @@
+//
+// Capability matrix: what DCI supports, per language, entry-point kind and question pack, with the evidence behind each
+// claim and its known limits. The words are used strictly:
+//
+//   verified      covered by reproducible fixture tests in this repository, for the BUILD half (resolution, bundling,
+//                 integrity). It says nothing about how good a model's review is.
+//   experimental  works on fixtures, narrow or unmeasured; no accuracy claim
+//   unsupported   not implemented
+//   blocked       cannot be done here, for a stated reason
+//
+// Review quality is `experimental` everywhere: there is no real-world adjudicated holdout in this repository, so no
+// accuracy statement is made (see evaluation/ and docs/guides/context-intelligence.md).
+const T = (f) => `test/context-intelligence/${f}`;
+
+const BUILD = [
+  { language: 'javascript/typescript', kind: 'http', frameworks: 'Express-style call registration (get/post/put/patch/delete/all, router.use, app.use)', status: 'verified', evidence: [T('build-js.test.js')], limits: 'Router mounts in another file and middleware factories are not followed (reported as router-mount-not-resolved); destructured and named imports are followed, re-exports and tsconfig path aliases are not.' },
+  { language: 'python', kind: 'http', frameworks: 'decorator registration (Flask/FastAPI-style @app.route / @router.get), FastAPI Depends()/Security() guards', status: 'experimental', evidence: [T('build-python-haskell.test.js'), T('frameworks.test.js')], limits: 'Decorator guards are read from the decorator lines and Depends() guards from the signature (only dependencies named like an auth or user provider bind the principal); framework-level before_request hooks and Django URL conf are not modelled.' },
+  { language: 'haskell', kind: 'http', frameworks: 'Scotty, WAI, Servant, Yesod (through the existing web model)', status: 'verified', evidence: [T('build-python-haskell.test.js'), T('frameworks.test.js')], limits: 'Static source analysis; the existing web model decides what a route is. Dynamic routes are reported unresolved.' },
+  { language: 'java/kotlin/c#/go/php/ruby/rust', kind: 'http', frameworks: 'whatever the engine route scan recognises', status: 'unsupported', evidence: [], limits: 'No fixture proves this, so it is listed as unsupported even though some routes may resolve: Handlers are resolved only for decorator/annotation-style registration; no dedicated fixtures here.' },
+  { language: 'any with a recognised surface', kind: 'webhook/queue/cron/upload/cli', frameworks: 'existing entry-point inventory', status: 'experimental', evidence: [T('build-js.test.js')], limits: 'Handler is the enclosing declaration of the surface; no framework wiring beyond that.' },
+  { language: 'haskell', kind: 'compiler metadata import', frameworks: 'hie-export/1 JSON export of GHC declarations and references', status: 'experimental', evidence: [T('hie-adapter.test.js')], limits: 'Reads an export; never runs GHC or hiedb. The export is validated against the source snapshot. No export produced by a real GHC run is checked in.' },
+  { language: 'any', kind: 'compiler metadata build', frameworks: 'automatic metadata generation', status: 'blocked', evidence: [], limits: 'Running a compiler on untrusted source needs a sandbox proof this build does not have (Template Haskell, custom Setup and plugins run code).' },
+  { language: 'other semantic sources (TypeScript compiler API, Roslyn, go/packages, language servers)', kind: 'compiler metadata import', frameworks: '-', status: 'unsupported', evidence: [], limits: 'Extension point only: the graph schema carries a resolver field (source-static | compiler-enriched).' },
+  { language: 'any', kind: 'provider batch API', frameworks: 'provider-hosted batch submission', status: 'blocked', evidence: [], limits: 'No provider batch contract is verified on this checkout. The offline batch files (request export, result import with hash checks) are implemented and tested.' },
+];
+
+export function capabilityMatrix() {
+  const reviews = ['authz-idor', 'authz-function', 'cross-route-consistency', 'transaction-integrity', 'external-failure', 'sensitive-audit', 'business-invariant'].map(p => ({
+    language: 'any bundle that builds', kind: `review: ${p}`, frameworks: 'governed single-turn model call over a frozen bundle', status: 'experimental',
+    evidence: [T('review-queue.test.js'), T('queue-diff.test.js')], limits: 'Mechanics are tested with a fake provider; no accuracy measurement exists. The synthetic evaluation suite is a mechanism check, not an estimate.',
+  }));
+  return [...BUILD, ...reviews];
+}