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

package/src/context-intelligence/queue.js

@@ -0,0 +1,355 @@
+//
+// Durable, bounded review queue.
+//
+// Every job ends in exactly one terminal state, with a reason, and the run reports both how many jobs were ELIGIBLE and
+// how many were ATTEMPTED, so a run that stopped early can never read as a clean one:
+//
+//   succeeded          a verified answer was obtained
+//   partial            the job ran but the answer was declined (bad citation, malformed, context unavailable)
+//   failed             the model call failed and retries were exhausted or the failure is not retryable
+//   timed_out          the job-level deadline passed
+//   skipped_by_policy  egress policy, redaction, a size limit or an exhausted budget stopped it BEFORE any call
+//   cancelled          the run was cancelled before the job finished
+//
+// Nothing here talks to a provider: the invoker comes from `review.resolveInvoker`, which goes through the governed
+// discovery caller. Local-only policy therefore holds by construction, and there is no fallback to a different provider.
+//
+// Bounds are absolute: jobs, concurrency, model calls (retries count), tokens per job, estimated dollars (only when a
+// price is supplied), and wall time. No unbounded queue growth, no infinite retry.
+import { hashOf, canonicalJson, sha256 } from './canonical.js';
+import { packRef, REVIEW_SCHEMA_VERSION } from './prompts/packs.js';
+import { runReviewOnce, verifyReview } from './review.js';
+import { readStoreJson, writeStoreJson, writeStoreFile } from './store.js';
+
+export const TERMINAL_STATES = Object.freeze(['succeeded', 'partial', 'failed', 'timed_out', 'skipped_by_policy', 'cancelled']);
+export const QUEUE_SCHEMA_VERSION = 'review-queue/1';
+export const HARD_LIMITS = Object.freeze({ maxJobs: 20000, maxConcurrency: 16, maxCalls: 5000, maxRetries: 3, maxWallSeconds: 86400 });
+const MAX_GROUP = 6;
+
+/** Group entry points that operate on the same kind of object (the static segment before the last path parameter). */
+export function resourceKeyOf(pathTemplate) {
+  const segs = String(pathTemplate || '').split('/').filter(Boolean);
+  let lastParam = -1;
+  segs.forEach((s, i) => { if (/^[:{<]/.test(s) || /[}>]$/.test(s)) lastParam = i; });
+  for (let i = lastParam - 1; i >= 0; i--) if (!/^[:{<]/.test(segs[i])) return segs[i];
+  return null;
+}
+
+export function jobKeyOf({ entrypointIds, contextHashes, packageIndex, pack, model }) {
+  return hashOf({
+    schema: REVIEW_SCHEMA_VERSION,
+    entrypoints: entrypointIds,
+    contexts: contextHashes,
+    packageIndex,
+    pack: packRef(pack),
+    model: { provider: model.provider || null, model: model.model || null },
+    settings: {},
+  });
+}
+
+/**
+ * Plan jobs. `bundles` are build results (`{entrypoint, manifest}`). Excluded entry points get no job; they are counted
+ * by the caller from the entry-point dispositions.
+ */
+export function planJobs({ bundles, packs, model, maxJobs = HARD_LIMITS.maxJobs }) {
+  const live = bundles.filter(b => b.manifest);
+  const jobs = [];
+  for (const pack of packs) {
+    if (pack.multiBundle) {
+      const groups = new Map();
+      for (const b of live) {
+        if (b.manifest.context.integrity === 'unavailable') continue;
+        const k = resourceKeyOf(b.entrypoint.pathTemplate);
+        if (!k) continue;
+        if (!groups.has(k)) groups.set(k, []);
+        groups.get(k).push(b);
+      }
+      for (const [k, members] of [...groups.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+        if (members.length < 2) continue;
+        const sorted = members.sort((a, b) => (a.entrypoint.id < b.entrypoint.id ? -1 : 1));
+        const used = sorted.slice(0, MAX_GROUP);
+        jobs.push({
+          key: jobKeyOf({ entrypointIds: used.map(m => m.entrypoint.id), contextHashes: used.map(m => m.manifest.contextHash), packageIndex: 1, pack, model }),
+          packId: pack.id, packRef: packRef(pack), label: `${pack.id}: ${k} (${used.length} routes)`, entrypointIds: used.map(m => m.entrypoint.id),
+          contextHashes: used.map(m => m.manifest.contextHash), packageIndexes: used.map(() => 1), groupTruncated: sorted.length > used.length ? sorted.length - used.length : 0,
+        });
+      }
+    } else {
+      for (const b of live) {
+        for (const pk of b.manifest.context.packages.length ? b.manifest.context.packages : [{ index: 1 }]) {
+          jobs.push({
+            key: jobKeyOf({ entrypointIds: [b.entrypoint.id], contextHashes: [b.manifest.contextHash], packageIndex: pk.index, pack, model }),
+            packId: pack.id, packRef: packRef(pack), label: `${pack.id}: ${b.entrypoint.label}${b.manifest.context.packages.length > 1 ? ` [package ${pk.index}/${pk.total}]` : ''}`,
+            entrypointIds: [b.entrypoint.id], contextHashes: [b.manifest.contextHash], packageIndexes: [pk.index], groupTruncated: 0,
+          });
+        }
+      }
+    }
+  }
+  jobs.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  const dropped = Math.max(0, jobs.length - maxJobs);
+  return { jobs: jobs.slice(0, maxJobs), droppedByJobLimit: dropped };
+}
+
+// ---- queue state ----------------------------------------------------------------------------------------------
+
+export function runIdOf(jobs, limits) { return hashOf({ jobs: jobs.map(j => j.key), limits: { calls: limits.maxCalls } }).slice(0, 24); }
+
+function sealState(state) {
+  const body = { ...state };
+  delete body.stateHash;
+  return { ...body, stateHash: sha256(canonicalJson(body)) };
+}
+
+function loadState(root, runId) {
+  const r = readStoreJson(root, `queues/${runId}.json`);
+  if (!r.ok) return { ok: false, corrupt: r.code === 'corrupt-json' };
+  const { stateHash, ...body } = r.value;
+  if (r.value.schemaVersion !== QUEUE_SCHEMA_VERSION || sha256(canonicalJson(body)) !== stateHash) return { ok: false, corrupt: true };
+  return { ok: true, state: r.value };
+}
+
+function reviewPath(key) { return `reviews/${key}.json`; }
+
+/** A stored review is reusable only if it still verifies as a review of exactly this job. */
+function loadCachedReview(root, job) {
+  const r = readStoreJson(root, reviewPath(job.key));
+  if (!r.ok) return null;
+  const v = r.value;
+  if (!v || v.jobKey !== job.key || !v.review || v.review.schemaVersion !== REVIEW_SCHEMA_VERSION) return null;
+  if (sha256(canonicalJson(v.review)) !== v.reviewHash) return null;
+  return v;
+}
+
+// ---- run --------------------------------------------------------------------------------------------------------
+
+const defaultSleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+/**
+ * Run a planned job list.
+ *   ctx.root, ctx.loadJob(job) -> { pack, entrypoints, manifests, packageTexts } | { error }
+ *   ctx.fileContents, ctx.invoker ({ok,invoke}|{ok:false,reason,denied}), ctx.model
+ *   ctx.limits { concurrency, maxCalls, maxWallSeconds, maxTokensPerJob, maxRetries, jobTimeoutMs, maxCostUsd, costPerCallUsd }
+ *   ctx.signal (AbortSignal), ctx.sleep, ctx.random, ctx.now  -- injected so tests are deterministic
+ *   ctx.retryFailed (re-run jobs that ended failed/timed_out), ctx.onEvent
+ */
+export async function runQueue(jobs, ctx) {
+  const now = ctx.now || (() => Date.now());
+  const sleep = ctx.sleep || defaultSleep;
+  const random = ctx.random || Math.random;
+  const emit = typeof ctx.onEvent === 'function' ? ctx.onEvent : () => {};
+  const L = {
+    concurrency: Math.min(HARD_LIMITS.maxConcurrency, Math.max(1, ctx.limits.concurrency || 1)),
+    maxCalls: Math.min(HARD_LIMITS.maxCalls, Math.max(1, ctx.limits.maxCalls || 100)),
+    maxWallMs: Math.min(HARD_LIMITS.maxWallSeconds, Math.max(1, ctx.limits.maxWallSeconds || 900)) * 1000,
+    maxTokensPerJob: ctx.limits.maxTokensPerJob || 40000,
+    maxRetries: Math.min(HARD_LIMITS.maxRetries, Math.max(0, ctx.limits.maxRetries ?? 3)),
+    jobTimeoutMs: ctx.limits.jobTimeoutMs || 120000,
+    maxCostUsd: Number.isFinite(ctx.limits.maxCostUsd) ? ctx.limits.maxCostUsd : null,
+    costPerCallUsd: Number.isFinite(ctx.limits.costPerCallUsd) ? ctx.limits.costPerCallUsd : null,
+  };
+  const runId = runIdOf(jobs, L);
+  const started = now();
+  const loaded = loadState(ctx.root, runId);
+  const prior = loaded.ok ? loaded.state.jobs : {};
+  const state = { schemaVersion: QUEUE_SCHEMA_VERSION, runId, jobs: {} };
+  const results = new Map();
+  let calls = 0;
+  let estCost = 0;
+  let cooldownUntil = 0;
+  let budgetStop = null;
+  let persistChain = Promise.resolve();
+  const persist = () => {
+    persistChain = persistChain.then(() => { writeStoreJson(ctx.root, `queues/${runId}.json`, sealState(state)); });
+    return persistChain;
+  };
+
+  const settle = async (job, outcome) => {
+    state.jobs[job.key] = { state: outcome.state, reason: outcome.reason || null, attempts: outcome.attempts || 0, label: job.label };
+    results.set(job.key, { job, ...outcome });
+    if (outcome.review) {
+      const reviewRecord = { schemaVersion: 'review-result/1', jobKey: job.key, questionPack: job.packRef, entrypointIds: job.entrypointIds, contextHashes: job.contextHashes, state: outcome.state, review: outcome.review, reviewHash: sha256(canonicalJson(outcome.review)) };
+      writeStoreJson(ctx.root, reviewPath(job.key), reviewRecord);
+    }
+    await persist();
+    emit({ event: 'job', key: job.key, state: outcome.state, reason: outcome.reason || null });
+  };
+
+  // classify jobs: cached / settled-before / to run
+  const todo = [];
+  for (const job of jobs) {
+    const p = prior[job.key];
+    const cached = loadCachedReview(ctx.root, job);
+    if (cached && cached.state === 'succeeded') {
+      results.set(job.key, { job, state: 'succeeded', reason: null, review: cached.review, cached: true, attempts: 0 });
+      state.jobs[job.key] = { state: 'succeeded', reason: null, attempts: 0, label: job.label, cached: true };
+      continue;
+    }
+    // A policy skip, a cancellation and an interrupted job say nothing about the model, so they are always re-evaluated:
+    // the policy or the endpoint may be different now. Answers (even declined ones) and real failures are kept so a
+    // resume does not pay twice, unless the operator asks to retry them.
+    const resettable = !p || p.state === 'skipped_by_policy' || p.state === 'cancelled' || p.state === 'running' || p.state === 'pending' || (ctx.retryFailed && (p.state === 'failed' || p.state === 'timed_out'));
+    if (!resettable && ['partial', 'failed', 'timed_out', 'succeeded'].includes(p.state)) {
+      state.jobs[job.key] = { ...p, resumed: true };
+      results.set(job.key, { job, state: p.state, reason: p.reason, attempts: p.attempts, resumed: true, review: cached ? cached.review : undefined });
+      continue;
+    }
+    state.jobs[job.key] = { state: 'pending', reason: null, attempts: 0, label: job.label };
+    todo.push(job);
+  }
+  await persist();
+
+  const gate = async () => { const wait = cooldownUntil - now(); if (wait > 0) await sleep(wait); };
+
+  const budgetReason = () => {
+    if (ctx.signal && ctx.signal.aborted) return 'cancelled';
+    if (now() - started >= L.maxWallMs) return 'budget-exhausted:wall-time';
+    if (calls >= L.maxCalls) return 'budget-exhausted:max-calls';
+    if (L.maxCostUsd !== null && L.costPerCallUsd !== null && estCost + L.costPerCallUsd > L.maxCostUsd) return 'budget-exhausted:max-cost';
+    return null;
+  };
+
+  const runOne = async (job) => {
+    const stop = budgetReason();
+    if (stop) { return settle(job, stop === 'cancelled' ? { state: 'cancelled', reason: 'run cancelled before this job started' } : { state: 'skipped_by_policy', reason: stop }); }
+    if (!ctx.invoker || !ctx.invoker.ok) return settle(job, { state: 'skipped_by_policy', reason: (ctx.invoker && ctx.invoker.reason) || 'no model endpoint is configured' });
+
+    const loadedJob = ctx.loadJob(job);
+    if (loadedJob.error) return settle(job, { state: 'failed', reason: loadedJob.error, attempts: 0 });
+
+    let attempts = 0;
+    for (;;) {
+      const s2 = budgetReason();
+      if (s2) return settle(job, s2 === 'cancelled' ? { state: 'cancelled', reason: 'run cancelled', attempts } : { state: 'skipped_by_policy', reason: s2, attempts });
+      await gate();
+      attempts++;
+      calls++;
+      if (L.costPerCallUsd !== null) estCost += L.costPerCallUsd;
+      state.jobs[job.key] = { state: 'running', reason: null, attempts, label: job.label };
+      const out = await runReviewOnce({
+        pack: loadedJob.pack, entrypoints: loadedJob.entrypoints, manifests: loadedJob.manifests, packageIndexes: job.packageIndexes, packageTexts: loadedJob.packageTexts,
+        fileContents: ctx.fileContents, scanRoot: ctx.root, invoker: ctx.invoker, model: ctx.model, limits: { maxTokensPerJob: L.maxTokensPerJob, jobTimeoutMs: L.jobTimeoutMs },
+      });
+      if (out.state === 'skipped_by_policy') calls--; // nothing was sent
+      if (out.state === 'failed' && out.retryable && attempts <= L.maxRetries) {
+        // exponential backoff with jitter; the shared cooldown slows every worker, which is what a 429 storm needs
+        const backoff = Math.min(30000, 500 * 2 ** (attempts - 1)) + Math.floor(random() * 250);
+        cooldownUntil = Math.max(cooldownUntil, now() + backoff);
+        emit({ event: 'retry', key: job.key, attempt: attempts, backoffMs: backoff, reason: out.reason });
+        continue;
+      }
+      return settle(job, { ...out, attempts });
+    }
+  };
+
+  let next = 0;
+  const worker = async () => {
+    for (;;) {
+      const idx = next++;
+      if (idx >= todo.length) return;
+      try { await runOne(todo[idx]); } catch (err) { await settle(todo[idx], { state: 'failed', reason: `internal error: ${String((err && err.message) || err).slice(0, 120)}` }); }
+    }
+  };
+  const poolSize = Math.min(L.concurrency, Math.max(1, todo.length));
+  await Promise.all(Array.from({ length: poolSize }, worker));
+  await persistChain;
+
+  // anything still pending/running was never finished: it is cancelled, not clean
+  for (const job of todo) {
+    const s = state.jobs[job.key];
+    if (s && (s.state === 'pending' || s.state === 'running')) await settle(job, { state: 'cancelled', reason: 'run ended before this job finished', attempts: s.attempts });
+  }
+  budgetStop = budgetReason();
+  return { runId, results, coverage: coverageOf(jobs, results, { calls, estCost: L.costPerCallUsd !== null ? estCost : null, costBasis: L.costPerCallUsd !== null ? 'estimate: operator-supplied per-call price' : 'unknown: no price supplied, dollar cap not enforceable', limits: L, wallMs: now() - started, budgetStop, queueStateCorrupt: loaded.corrupt === true }) };
+}
+
+export function coverageOf(jobs, results, extra = {}) {
+  const c = { eligible: jobs.length, attempted: 0, succeeded: 0, partial: 0, failed: 0, timed_out: 0, skipped_by_policy: 0, cancelled: 0, cached: 0, resumed: 0, modelCalls: extra.calls || 0, estimatedCostUsd: extra.estCost ?? null, costBasis: extra.costBasis || null, wallMs: extra.wallMs || 0, budgetStop: extra.budgetStop || null, queueStateCorrupt: !!extra.queueStateCorrupt, reasons: {} };
+  for (const job of jobs) {
+    const r = results.get(job.key);
+    if (!r) { c.cancelled++; continue; }
+    c[r.state] = (c[r.state] || 0) + 1;
+    if (r.cached) c.cached++;
+    if (r.resumed) c.resumed++;
+    if (r.state !== 'skipped_by_policy' && r.state !== 'cancelled') c.attempted++;
+    if (r.reason) c.reasons[r.reason] = (c.reasons[r.reason] || 0) + 1;
+  }
+  // only a succeeded job with a conclusion is a reviewed route; everything else is missing coverage, never a clean pass
+  c.reviewed = c.succeeded;
+  c.missingCoverage = c.eligible - c.succeeded;
+  return c;
+}
+
+// ---- offline batch: export a request file, import a result file --------------------------------------------------
+
+export function batchIdOf(jobs) { return hashOf(jobs.map(j => j.key)).slice(0, 24); }
+
+/**
+ * Write a provider-agnostic batch: a request file (one JSON line per job, with the redacted prompt) and a manifest that
+ * binds every request to its job key, context hash and prompt hash. No provider API is called: uploading the file and
+ * downloading results is the operator's step, and the contract of any particular provider's batch API is NOT assumed.
+ */
+export function exportBatch(root, jobs, loadJob, ctx) {
+  const { buildReviewPrompt, redactPackageText, checkEgressForFiles } = ctx.review;
+  const lines = [];
+  const entries = [];
+  const skipped = [];
+  for (const job of jobs) {
+    const lj = loadJob(job);
+    if (lj.error) { skipped.push({ key: job.key, reason: lj.error }); continue; }
+    const files = [...new Set(lj.manifests.flatMap((m, i) => (m.context.packages.find(p => p.index === job.packageIndexes[i]) || { segments: [] }).segments.map(s => s.file)))];
+    const eg = checkEgressForFiles(files, { scanRoot: root, model: ctx.model });
+    if (!eg.allowed) { skipped.push({ key: job.key, reason: `egress policy denied ${eg.file}: ${eg.reason}` }); continue; }
+    const red = lj.packageTexts.map(t => redactPackageText(t, { scanRoot: root }));
+    const bad = red.find(r => !r.ok);
+    if (bad) { skipped.push({ key: job.key, reason: `redaction refused: ${bad.reason}` }); continue; }
+    const { prompt, promptHash } = buildReviewPrompt({ pack: lj.pack, entrypoints: lj.entrypoints, packageTexts: red.map(r => r.text), contextHash: lj.manifests[0].contextHash });
+    lines.push(JSON.stringify({ custom_id: job.key, prompt }));
+    entries.push({ key: job.key, packRef: job.packRef, entrypointIds: job.entrypointIds, contextHashes: job.contextHashes, packageIndexes: job.packageIndexes, promptHash });
+  }
+  const batchId = batchIdOf(jobs);
+  const manifest = { schemaVersion: 'review-batch/1', batchId, jobs: entries, skipped, note: 'Provider batch upload and download are performed by the operator. Results are imported with `context review --import-batch`.' };
+  const w1 = writeStoreFile(root, `batches/${batchId}/requests.jsonl`, lines.join('\n') + (lines.length ? '\n' : ''));
+  if (!w1.ok) return w1;
+  const w2 = writeStoreJson(root, `batches/${batchId}/manifest.json`, manifest);
+  if (!w2.ok) return w2;
+  return { ok: true, batchId, requests: entries.length, skipped, requestsFile: w1.path };
+}
+
+/**
+ * Import results for a batch. Each result line is `{ custom_id, response }` where `response` is the model text.
+ * A result is REJECTED when it names an unknown job, repeats a job already settled (first wins), or was produced for a
+ * context that is no longer the current one (stale or out-of-order). Import is idempotent.
+ */
+export function importBatch(root, batchId, resultsText, ctx) {
+  const m = readStoreJson(root, `batches/${batchId}/manifest.json`);
+  if (!m.ok) return { ok: false, reason: `batch manifest ${m.code}` };
+  const byKey = new Map(m.value.jobs.map(j => [j.key, j]));
+  const seen = new Set();
+  const report = { accepted: 0, declined: 0, rejected: [], duplicates: 0 };
+  for (const lineRaw of String(resultsText).split('\n')) {
+    const line = lineRaw.trim();
+    if (!line) continue;
+    let rec;
+    try { rec = JSON.parse(line); } catch { report.rejected.push({ reason: 'not-json' }); continue; }
+    const key = rec && rec.custom_id;
+    const entry = byKey.get(key);
+    if (!entry) { report.rejected.push({ key: key || null, reason: 'unknown-job' }); continue; }
+    const settled = loadCachedReview(root, { key });
+    if (seen.has(key) || (settled && settled.state === 'succeeded')) { report.duplicates++; continue; }
+    seen.add(key);
+    const job = ctx.jobs.find(j => j.key === key);
+    if (!job) { report.rejected.push({ key, reason: 'job-not-in-current-plan' }); continue; }
+    const lj = ctx.loadJob(job);
+    if (lj.error) { report.rejected.push({ key, reason: lj.error }); continue; }
+    if (lj.manifests.some((mm, i) => mm.contextHash !== entry.contextHashes[i])) { report.rejected.push({ key, reason: 'stale-context' }); continue; }
+    const promptHash = entry.promptHash;
+    const review = verifyReview({ raw: typeof rec.response === 'string' ? rec.response : '', pack: lj.pack, entrypoints: lj.entrypoints, manifests: lj.manifests, packageIndexes: job.packageIndexes, fileContents: ctx.fileContents, promptHash });
+    const state = review.status === 'completed' ? 'succeeded' : 'partial';
+    const record = { schemaVersion: 'review-result/1', jobKey: key, questionPack: job.packRef, entrypointIds: job.entrypointIds, contextHashes: job.contextHashes, state, review, reviewHash: sha256(canonicalJson(review)), via: 'batch-import' };
+    writeStoreJson(root, reviewPath(key), record);
+    if (state === 'succeeded') report.accepted++; else report.declined++;
+  }
+  return { ok: true, ...report };
+}
+

package/src/context-intelligence/reachability.js

@@ -0,0 +1,188 @@
+//
+// Deterministic, bounded reachability from an entry point's handler.
+//
+// Breadth-first, with a stable tie-break (call line, then callee name, then target id), so the same graph always
+// yields the same visit order and therefore the same bundle bytes. Three things this module refuses to do:
+//
+//   * claim exhaustiveness. A call that could not be resolved to a declaration is recorded as an explicit unknown.
+//     Only the ones that COULD hide first-party code (the callee's name matches a first-party declaration, or the
+//     callee is dynamic) are `material`; a call into a library or a response helper is a boundary, listed but not
+//     blocking, because nothing first-party can be hiding behind it.
+//   * hide a limit. Hitting the symbol or depth cap marks the walk `capped` and lists what was left unvisited.
+//   * lose a control. Middleware and every callee are walked, and each visited symbol's controls are collected by the
+//     same classifier the packer uses to refuse pruning.
+import { analyzeSymbolText } from './controls.js';
+import { cmpCodeUnit } from './canonical.js';
+import { MATERIAL_REASONS } from './graph-schema.js';
+
+export const DEFAULT_LIMITS = Object.freeze({ maxSymbols: 60, maxDepth: 12 });
+
+function indexGraph(graph) {
+  const byId = new Map();
+  const edgesFrom = new Map();
+  for (const s of graph.symbols) byId.set(s.id, s);
+  for (const e of graph.edges) {
+    if (!edgesFrom.has(e.from)) edgesFrom.set(e.from, []);
+    edgesFrom.get(e.from).push(e);
+  }
+  return { byId, edgesFrom };
+}
+
+/**
+ * Walk the graph from an entry point.
+ * Returns { root, visited, facts, unknowns, boundaries, capped, unvisited, cycles, limits }.
+ */
+export function reachFrom({ graph, fileContents, entrypoint, limits = {} }) {
+  const lim = { ...DEFAULT_LIMITS, ...limits };
+  const { byId, edgesFrom } = indexGraph(graph);
+  const linesCache = new Map();
+  const linesOf = (f) => { if (!linesCache.has(f)) linesCache.set(f, (fileContents[f] || '').split('\n')); return linesCache.get(f); };
+
+  const visited = [];
+  const seen = new Set();
+  const unknowns = [];
+  const boundaryMap = new Map();
+  let cycles = 0;
+  let capped = false;
+  const queue = [];
+
+  const inlineRoot = entrypoint.handlerKind === 'inline' && entrypoint.rootSpan && entrypoint.language === 'haskell';
+  const rootSymbol = entrypoint.handlerSymbol ? byId.get(entrypoint.handlerSymbol) : null;
+
+  // the "root view": either the handler declaration or, for an inline handler inside a larger declaration, only the
+  // registration block's lines
+  let root = null;
+  if (inlineRoot && rootSymbol) {
+    root = { kind: 'inline-block', symbolId: rootSymbol.id, file: entrypoint.rootSpan.file, startLine: entrypoint.rootSpan.startLine, endLine: entrypoint.rootSpan.endLine, declLine: entrypoint.rootSpan.startLine, spanPrecision: entrypoint.rootSpan.precision };
+  } else if (rootSymbol) {
+    root = { kind: 'declaration', symbolId: rootSymbol.id, file: rootSymbol.file, startLine: rootSymbol.startLine, endLine: rootSymbol.endLine, declLine: rootSymbol.declLine, spanPrecision: rootSymbol.spanPrecision };
+  } else if (entrypoint.rootSpan) {
+    root = { kind: 'registration-only', symbolId: null, file: entrypoint.rootSpan.file, startLine: entrypoint.rootSpan.startLine, endLine: entrypoint.rootSpan.endLine, declLine: entrypoint.rootSpan.startLine, spanPrecision: entrypoint.rootSpan.precision };
+  }
+
+  const enqueue = (symbolId, depth, reason, viaLine, path, confidence) => {
+    if (seen.has(symbolId)) { cycles++; return; }
+    seen.add(symbolId);
+    queue.push({ symbolId, depth, reason, viaLine, path, confidence });
+  };
+
+  if (!root) {
+    return { root: null, visited: [], facts: [], unknowns: [{ type: 'no-handler', site: `${entrypoint.registrationSite.file}:${entrypoint.registrationSite.line}`, reason: 'entry point has no resolvable handler or registration block', material: true }], boundaries: [], capped: false, unvisited: [], cycles: 0, limits: lim };
+  }
+
+  // middleware runs before the handler: it is enqueued first and ordered at line -1
+  for (const mw of [...entrypoint.middleware].sort((a, b) => (a.line - b.line) || cmpCodeUnit(a.name, b.name))) {
+    if (mw.symbolId && byId.has(mw.symbolId)) enqueue(mw.symbolId, 0, mw.inherited ? 'inherited-middleware' : 'middleware', -1, [mw.symbolId], mw.resolution === 'resolved' ? 'exact' : 'name-match');
+  }
+  if (root.symbolId) {
+    if (!seen.has(root.symbolId)) { seen.add(root.symbolId); }
+    queue.unshift({ symbolId: root.symbolId, depth: 0, reason: 'handler', viaLine: null, path: [root.symbolId], confidence: entrypoint.handlerConfidence, isRoot: true });
+  }
+
+  const emitted = [];
+  while (queue.length) {
+    const cur = queue.shift();
+    const sym = byId.get(cur.symbolId);
+    if (!sym) continue;
+    if (emitted.length >= lim.maxSymbols) { capped = true; queue.unshift(cur); break; }
+    emitted.push(cur);
+    visited.push({ symbolId: cur.symbolId, depth: cur.depth, reason: cur.reason, viaLine: cur.viaLine, path: cur.path, confidence: cur.confidence });
+
+    const restrictTo = cur.isRoot && root.kind === 'inline-block' ? [root.startLine, root.endLine] : null;
+    const out = (edgesFrom.get(cur.symbolId) || [])
+      .filter(e => !e.superseded)
+      .filter(e => !restrictTo || (e.line >= restrictTo[0] && e.line <= restrictTo[1]))
+      .sort((a, b) => (a.line - b.line) || (a.calleeName < b.calleeName ? -1 : a.calleeName > b.calleeName ? 1 : 0) || ((a.to || '') < (b.to || '') ? -1 : 1));
+    for (const e of out) {
+      // The root-level line a chain started on: callees of the handler are ordered by the line of the call that led to them.
+      const via = cur.isRoot ? e.line : cur.viaLine;
+      if (e.conflict) {
+        // the compiler and the static pass disagree about this call: follow both, and say the bundle is not settled
+        unknowns.push({ type: 'compiler-static-conflict', site: `${sym.file}:${e.line}`, from: cur.symbolId, calleeName: e.calleeName, reason: 'compiler-and-static-analysis-disagree', material: true, candidates: [] });
+      }
+      if (e.to) {
+        if (cur.depth + 1 > lim.maxDepth) { capped = true; continue; }
+        enqueue(e.to, cur.depth + 1, 'callee', via, [...cur.path, e.to], 'exact');
+      } else if (MATERIAL_REASONS.has(e.unresolvedReason)) {
+        unknowns.push({ type: e.kind, site: `${sym.file}:${e.line}`, from: cur.symbolId, calleeName: e.calleeName, reason: e.unresolvedReason, material: true, candidates: e.candidates });
+        // Candidates are shown to the model as CANDIDATES (low confidence); the unknown stays material regardless.
+        if (e.candidates.length && e.candidates.length <= 3 && cur.depth + 1 <= lim.maxDepth) {
+          for (const c of e.candidates) enqueue(c, cur.depth + 1, 'name-match-candidate', via, [...cur.path, c], 'name-match');
+        }
+      } else {
+        const key = `${e.calleeName}|${e.unresolvedReason}`;
+        const b = boundaryMap.get(key) || { calleeName: e.calleeName, reason: e.unresolvedReason, count: 0, firstSite: `${sym.file}:${e.line}` };
+        b.count++;
+        boundaryMap.set(key, b);
+      }
+    }
+  }
+  const unvisited = queue.map(q => q.symbolId).sort();
+
+  // facts: classified once per visited symbol, with the effective ordering line attached
+  const facts = [];
+  for (const v of visited) {
+    const sym = byId.get(v.symbolId);
+    const isInlineRoot = v.reason === 'handler' && root.kind === 'inline-block';
+    const view = isInlineRoot ? { ...sym, startLine: root.startLine, endLine: root.endLine, declLine: root.startLine } : sym;
+    const hs = /\.l?hs$/i.test(sym.file);
+    for (const f of analyzeSymbolText(view, linesOf(sym.file), { haskell: hs })) {
+      let effLine;
+      if (v.reason === 'handler') effLine = f.line;
+      else if (v.reason === 'middleware' || v.reason === 'inherited-middleware') effLine = -1;
+      else effLine = v.viaLine === null || v.viaLine === undefined ? f.line : v.viaLine;
+      facts.push({ ...f, file: sym.file, effLine, via: v.reason });
+    }
+  }
+  // registration-only roots have no symbol: still classify the registration block itself
+  if (!root.symbolId) {
+    const view = { id: `${root.file}::<registration>@${root.startLine}`, file: root.file, startLine: root.startLine, endLine: root.endLine, declLine: root.startLine };
+    for (const f of analyzeSymbolText(view, linesOf(root.file), { haskell: /\.l?hs$/i.test(root.file) })) facts.push({ ...f, file: root.file, effLine: f.line, via: 'handler' });
+  }
+
+  unknowns.sort((a, b) => (a.site < b.site ? -1 : a.site > b.site ? 1 : 0) || (a.calleeName < b.calleeName ? -1 : 1));
+  const boundaries = [...boundaryMap.values()].sort((a, b) => (a.calleeName < b.calleeName ? -1 : a.calleeName > b.calleeName ? 1 : 0));
+  return { root, visited, facts, unknowns, boundaries, capped, unvisited, cycles, limits: lim };
+}
+
+/**
+ * Protection state per dimension. The five non-present states are deliberately distinct, because collapsing them is
+ * how "I did not see a check" turns into "there is no check":
+ *   present                     an observed or named control precedes the first sensitive operation
+ *   evaluated_and_ineffective   a control exists but runs AFTER the first sensitive operation (a late guard)
+ *   not_present                 the context is complete and no control of this kind is in it
+ *   not_resolved                a material unknown edge could hide one
+ *   omitted_due_to_budget       a symbol that holds a control was left out for size
+ *   not_seen                    no sensitive operation was seen, so there was nothing for a control to protect
+ */
+export const PROTECTION_DIMENSIONS = Object.freeze(['authentication', 'authorization-role', 'ownership']);
+
+export function evaluateProtection({ facts, unknowns, omittedWithControls = false, capped = false }) {
+  const sens = facts.filter(f => f.category === 'sensitive');
+  const firstSens = sens.length ? Math.min(...sens.map(f => f.effLine)) : null;
+  const dims = {};
+  for (const dim of PROTECTION_DIMENSIONS) {
+    const kinds = dim === 'ownership' ? ['ownership', 'tenant-scope'] : [dim];
+    const ctl = facts.filter(f => f.category === 'control' && kinds.includes(f.kind));
+    // A control whose answer is visibly thrown away (a predicate called as a bare statement) guards nothing.
+    const effective = (f) => f.rejectionSeen !== false;
+    const before = ctl.filter(f => effective(f) && (firstSens === null || f.effLine < firstSens || (f.basis === 'query-filter' && f.effLine <= firstSens)));
+    const after = ctl.filter(f => firstSens !== null && f.effLine > firstSens);
+    let state; let why;
+    if (before.length) { state = 'present'; why = 'a control precedes the first sensitive operation'; }
+    else if (after.length) { state = 'evaluated_and_ineffective'; why = 'every control of this kind runs after the first sensitive operation'; }
+    else if (ctl.length && ctl.every(f => !effective(f))) { state = 'evaluated_and_ineffective'; why = 'a check is called but nothing in view acts on its answer'; }
+    else if (ctl.length) { state = 'evaluated_and_ineffective'; why = 'a control is present but is not ordered before the sensitive operation'; }
+    else if (omittedWithControls) { state = 'omitted_due_to_budget'; why = 'a symbol holding a control was left out for size'; }
+    else if (unknowns.some(u => u.material) || capped) { state = 'not_resolved'; why = 'an unresolved call or a traversal limit could hide a control'; }
+    else if (firstSens === null) { state = 'not_seen'; why = 'no sensitive operation was seen in the resolved context'; }
+    else { state = 'not_present'; why = 'the resolved context is complete and contains no control of this kind'; }
+    dims[dim] = {
+      state, why, firstSensitiveLine: firstSens,
+      // How the control was established: 'observed' = the text shows it, 'inferred' = only a name suggests it. Only meaningful for `present`.
+      strength: state === 'present' ? (before.some(f => f.evidence === 'observed') ? 'observed' : 'inferred') : null,
+      evidence: ctl.slice(0, 6).map(f => ({ file: f.file, line: f.line, kind: f.kind, evidence: f.evidence, basis: f.basis, order: firstSens === null ? 'no-sensitive-op' : f.effLine < firstSens ? 'before-sensitive' : f.effLine > firstSens ? 'after-sensitive' : 'same-step', rejectionSeen: f.rejectionSeen })),
+    };
+  }
+  return dims;
+}

package/src/context-intelligence/repo-info.js

@@ -0,0 +1,16 @@
+//
+// Best-effort git identity of the checkout. Absent git is not an error: the fields are null and the snapshot hash
+// (content-based) still identifies the analysed bytes exactly.
+import { execFileSync } from 'node:child_process';
+
+function git(root, args) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 1024 }).trim();
+  } catch { return null; }
+}
+
+export function repositoryInfo(root, snapshotHash) {
+  const commit = git(root, ['rev-parse', 'HEAD']);
+  const status = commit ? git(root, ['status', '--porcelain']) : null;
+  return { commit: commit || null, dirty: status === null ? null : status.length > 0, snapshotHash };
+}