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

package/src/pipeline/analyzer-worker.js

@@ -0,0 +1,26 @@
+// Worker-thread entry point for analyzer-supervisor.js (assurance-hardening
+// PRD FR-202, D-0046 phase 1).
+//
+// Generic by design: workerData names a module and an export to call with a
+// list of plain arguments, so this file has no knowledge of what analyzer it
+// is running. The supervisor is the only caller; this file is not meant to
+// be imported directly.
+
+import { parentPort, workerData } from 'node:worker_threads';
+
+async function run() {
+  try {
+    const { modulePath, exportName, args } = workerData;
+    const mod = await import(modulePath);
+    const fn = mod[exportName];
+    if (typeof fn !== 'function') {
+      throw new Error(`export "${exportName}" is not a function in ${modulePath}`);
+    }
+    const result = await fn(...(args || []));
+    parentPort.postMessage({ ok: true, result });
+  } catch (e) {
+    parentPort.postMessage({ ok: false, error: String((e && e.message) || e) });
+  }
+}
+
+run();

package/src/pipeline/annotator-runner.js

@@ -0,0 +1,33 @@
+// Annotator runner (assurance-hardening PRD, Milestone 0/1, FR-106).
+//
+// Extracted from engine.js's local `_runAnnotator` closure so the Promise-
+// aware error-capture contract can be fault-injection tested directly,
+// without needing a real annotator to actually throw (this codebase's
+// annotators are deliberately built never to — see posture/CLAUDE.md's "no
+// throwing" convention — which is good for production but means there was
+// no natural way to prove the capture path works end-to-end before this
+// module existed). engine.js's `_runAnnotator` is now a thin wrapper that
+// closes over its local `_annotatorErrors` array and delegates here; this
+// module has no engine.js-specific state, so it takes the errors array as a
+// parameter instead of a closure.
+//
+// Contract: a rejection or thrown error from `fn()` — sync or async — is
+// captured as a structured entry, never left to become an unhandled
+// rejection or to race ahead of the caller. The caller MUST `await` this
+// function for the second half of that contract (capture-before-return) to
+// hold; see engine.js's call sites, all of which now do.
+
+/**
+ * @param {Array<{phase:string, err:string}>} annotatorErrors - mutated in place (push only)
+ * @param {string} phase - name recorded on a captured error
+ * @param {() => any} fn - sync or async callback
+ * @returns {Promise<any>} fn()'s resolved value, or undefined if it threw/rejected
+ */
+export async function runAnnotatorAsync(annotatorErrors, phase, fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    annotatorErrors.push({ phase, err: String((e && e.message) || e) });
+    return undefined;
+  }
+}

package/src/pipeline/assurance-mode.js

@@ -0,0 +1,91 @@
+// Assurance modes (assurance-hardening PRD FR-204).
+//
+// "Add assurance modes: advisory, standard, and strict | Strict mode fails
+// when a required analyzer fails, times out, is unavailable, or is
+// silently skipped." Section 12.1 names the CLI surface:
+// `--assurance advisory|standard|strict`.
+//
+// Built directly on FR-203's coverage ledger (pipeline/coverage-ledger.js)
+// and FR-206's scan-health.js -- this module adds no new signal collection
+// of its own, only a POLICY over signals that already exist. That is
+// deliberate: assurance modes decide how strict to be about incomplete
+// analysis; they must never be the thing that DEFINES what "incomplete"
+// means, or the two concepts would drift out of sync.
+//
+// THREE MODES:
+//   advisory — never fails the gate over scan health, regardless of what
+//     scanHealth reports. Purely informational (surfaced in scanHealth /
+//     toShipVerdict / `ci`'s stderr, per FR-206's fix -- this mode does not
+//     suppress that, it just does not ADD a build-failing consequence).
+//   standard (the DEFAULT, matching this codebase's behavior before and
+//     after FR-204) — same as advisory for gate purposes: an incomplete
+//     scan is surfaced, never silently hidden, but does not itself fail a
+//     build independent of the ordinary --fail-on severity threshold. The
+//     distinction from advisory is one of INTENT/reporting emphasis, not
+//     mechanism -- see the module-level note below on why this codebase
+//     does not invent a mechanical difference the PRD text does not ask
+//     for.
+//   strict — an incomplete scan (any analyzer failed, timed out, or was
+//     skipped by policy -- the ledger's own three non-"completed" outcomes)
+//     is a HARD FAILURE, independent of and IN ADDITION TO --fail-on,
+//     mirroring cmdCi's own existing precedent for its --policy gate
+//     ("Policy runs ALONGSIDE the --fail-on threshold; either gate can
+//     fail the build").
+//
+// WHY ADVISORY AND STANDARD ARE MECHANICALLY IDENTICAL HERE: the PRD's own
+// one-line acceptance criterion only specifies STRICT mode's behavior in
+// full ("fails when..."); it does not name a distinct mechanical
+// consequence for standard beyond "the default, not strict." Inventing an
+// intermediate failure condition neither named in the PRD nor requested
+// would be exactly the kind of unrequested scope-widening this codebase's
+// own conventions warn against. If a future requirement needs standard
+// mode to behave differently from advisory, that is a deliberate, separate
+// decision -- not something to guess at here.
+
+export const ASSURANCE_MODES = Object.freeze(['advisory', 'standard', 'strict']);
+export const DEFAULT_ASSURANCE_MODE = 'standard';
+
+function _isValidMode(mode) {
+  return ASSURANCE_MODES.includes(mode);
+}
+
+/**
+ * @param {string} mode - one of ASSURANCE_MODES; invalid/missing degrades to the default.
+ * @param {object|null} scanHealth - the engine's computed scan.scanHealth (FR-206).
+ * @returns {{ok: boolean, mode: string, reason: string|null, conditions: string[]}}
+ *   ok:false only ever happens in strict mode; advisory/standard always ok:true
+ *   (they report, they do not gate).
+ */
+export function evaluateAssuranceMode(mode, scanHealth) {
+  const effectiveMode = _isValidMode(mode) ? mode : DEFAULT_ASSURANCE_MODE;
+  const conditions = Array.isArray(scanHealth?.conditions) ? scanHealth.conditions : [];
+
+  if (effectiveMode !== 'strict') {
+    return { ok: true, mode: effectiveMode, reason: null, conditions };
+  }
+
+  // Strict: any of the ledger's three non-"completed" analyzer outcomes,
+  // OR an annotator error / deep-mode failure (scanHealth's OTHER,
+  // non-analyzer conditions) -- "a required analyzer... is unavailable, or
+  // is silently skipped" covers more than just coverage-ledger.js's own
+  // per-detector accounting; a scan whose ANY known-good signal degraded
+  // is not "complete" under strict's own definition.
+  const status = scanHealth?.status;
+  if (!scanHealth || status !== 'complete') {
+    const a = scanHealth?.analyzers;
+    const parts = [];
+    if (a?.failed > 0) parts.push(`${a.failed} analyzer(s) failed`);
+    if (a?.timedOut > 0) parts.push(`${a.timedOut} analyzer(s) timed out`);
+    if (a?.skippedByPolicy > 0) parts.push(`${a.skippedByPolicy} analyzer(s) silently skipped by policy`);
+    const analyzerSummary = parts.length ? ` (${parts.join(', ')})` : '';
+    return {
+      ok: false,
+      mode: 'strict',
+      reason: `strict mode requires a fully complete scan; scanHealth.status is '${status ?? 'unknown'}'${analyzerSummary}`,
+      conditions,
+    };
+  }
+  return { ok: true, mode: 'strict', reason: null, conditions };
+}
+
+export const _internals = { _isValidMode };

package/src/pipeline/cascade-worker-pool.js

@@ -0,0 +1,172 @@
+// FR-202 phase 3b (D-0050): a pool of long-lived workers, each running engine.js's
+// _runFileCascade for many files over its lifetime, instead of the one-shot-per-call
+// model runWithDeadline/analyzer-supervisor.js uses (which is correct for FR-202's
+// primitive-level proof but would force whole-project setup — _buildProjectIndex,
+// _buildGlobalJavaTaintedMethodIndex, _loadCustomRules — to redo per FILE, an O(n^2)
+// cost across a scan). Each worker performs that setup ONCE at creation via
+// _initCascadeWorkerState, then answers task messages over its lifetime.
+//
+// A task that exceeds its deadline+grace gets its OWN worker terminated (genuinely
+// preemptive, mirroring analyzer-supervisor.js's worker.terminate() precedent) and a
+// fresh replacement worker is spawned to keep the pool at full size for later files —
+// one hung file costs one worker restart, not the whole scan.
+import { Worker } from 'node:worker_threads';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// `new Worker()` needs a REAL file on disk -- once ncc bundles this module's code
+// into a dist/ chunk, `import.meta.url` resolves to that chunk's location (dist/),
+// not to src/pipeline/, so a naive path.join(HERE, 'cascade-worker.js') would look
+// for a file that was never copied there. src/ always ships as a sibling of dist/
+// (see package.json's "files"), in both a dev checkout and the published npm
+// package, so fall back to the real, unbundled worker script in that case.
+function _resolveDefaultWorkerScript() {
+  const hereDir = path.dirname(fileURLToPath(import.meta.url));
+  if (path.basename(hereDir) === 'pipeline') return path.join(hereDir, 'cascade-worker.js');
+  return path.join(hereDir, '..', 'src', 'pipeline', 'cascade-worker.js');
+}
+const DEFAULT_WORKER_SCRIPT = _resolveDefaultWorkerScript();
+export const DEFAULT_GRACE_MS = 500;
+
+function spawnReadyWorker({ workerScript, modulePath, fileContents, scanRoot }) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const worker = new Worker(workerScript, { workerData: { modulePath, fileContents, scanRoot } });
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      worker.off('message', onMessage);
+      worker.off('error', onError);
+      fn(value);
+    };
+    const onMessage = (msg) => {
+      if (!msg) return;
+      if (msg.type === 'ready') finish(resolve, worker);
+      else if (msg.type === 'init-error') { worker.terminate().catch(() => {}); finish(reject, new Error(msg.error)); }
+    };
+    const onError = (err) => { worker.terminate().catch(() => {}); finish(reject, err); };
+    worker.on('message', onMessage);
+    worker.on('error', onError);
+  });
+}
+
+/**
+ * @param {object} opts
+ * @param {Record<string,string>} opts.fileContents - broadcast once to every worker at creation.
+ * @param {string|null} opts.scanRoot
+ * @param {number} [opts.poolSize=4]
+ * @param {string} opts.modulePath - absolute path to the engine.js each worker imports.
+ * @param {string} [opts.workerScript] - defaults to cascade-worker.js next to this file.
+ * @param {number} [opts.graceMs]
+ */
+export function createCascadePool(opts = {}) {
+  const {
+    fileContents = {},
+    scanRoot = null,
+    poolSize = 4,
+    workerScript = DEFAULT_WORKER_SCRIPT,
+    modulePath,
+    graceMs = DEFAULT_GRACE_MS,
+  } = opts;
+  if (!modulePath) throw new Error('createCascadePool requires opts.modulePath');
+  if (!(Number.isInteger(poolSize) && poolSize > 0)) throw new Error('createCascadePool requires opts.poolSize to be a positive integer');
+
+  const idle = [];
+  const pendingIdle = [];
+  const allWorkers = new Set();
+  let nextTaskId = 1;
+  let closed = false;
+  let spawnFailureCount = 0;
+  let lastSpawnError = null;
+
+  function spawnAndRegister() {
+    return spawnReadyWorker({ workerScript, modulePath, fileContents, scanRoot }).then((w) => {
+      allWorkers.add(w);
+      return w;
+    });
+  }
+
+  // Background respawn after a killed worker (see runFile's timeout branch)
+  // is deliberately fire-and-forget -- the timed-out task has already
+  // resolved and nothing is waiting on this promise -- but a swallowed
+  // failure here would otherwise shrink the pool invisibly (e.g. thread
+  // exhaustion making every future respawn fail silently forever). Track
+  // it instead of a bare `.catch(() => {})`.
+  function respawnInBackground() {
+    spawnAndRegister().then(releaseWorker).catch((err) => {
+      spawnFailureCount += 1;
+      lastSpawnError = err;
+    });
+  }
+
+  function releaseWorker(w) {
+    if (closed) { allWorkers.delete(w); w.terminate().catch(() => {}); return; }
+    if (pendingIdle.length) pendingIdle.shift()(w);
+    else idle.push(w);
+  }
+
+  function acquireWorker() {
+    if (idle.length) return Promise.resolve(idle.pop());
+    return new Promise((resolve) => pendingIdle.push(resolve));
+  }
+
+  const ready = Promise.all(
+    Array.from({ length: poolSize }, () => spawnAndRegister().then(releaseWorker))
+  );
+
+  /**
+   * Run one file's cascade on a pooled worker. Resolves with
+   * {ok:true, result} | {ok:false, error} | {ok:false, timedOut:true, timeoutMs, graceMs}.
+   * Never rejects.
+   */
+  async function runFile(p, c, taskScanRoot, detectorErrors, taskOpts = {}) {
+    await ready;
+    if (closed) return { ok: false, error: 'pool is closed' };
+    const timeoutMs = taskOpts.timeoutMs;
+    const worker = await acquireWorker();
+    const id = nextTaskId++;
+    return new Promise((resolve) => {
+      let settled = false;
+      let killTimer = null;
+      const onMessage = (msg) => {
+        if (settled || !msg || msg.id !== id) return;
+        settled = true;
+        if (killTimer) clearTimeout(killTimer);
+        worker.off('message', onMessage);
+        releaseWorker(worker);
+        resolve(msg.ok ? { ok: true, result: msg.result } : { ok: false, error: msg.error });
+      };
+      worker.on('message', onMessage);
+      if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+        killTimer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          worker.off('message', onMessage);
+          allWorkers.delete(worker);
+          worker.terminate().catch(() => {});
+          if (!closed) respawnInBackground();
+          resolve({ ok: false, timedOut: true, timeoutMs, graceMs });
+        }, timeoutMs + graceMs);
+        killTimer.unref?.();
+      }
+      worker.postMessage({ type: 'task', id, p, c, scanRoot: taskScanRoot, detectorErrors });
+    });
+  }
+
+  async function shutdown() {
+    closed = true;
+    await ready.catch(() => {});
+    for (const w of allWorkers) await w.terminate().catch(() => {});
+    allWorkers.clear();
+    idle.length = 0;
+  }
+
+  return {
+    runFile,
+    shutdown,
+    ready,
+    DEFAULT_GRACE_MS: graceMs,
+    getSpawnFailureCount: () => spawnFailureCount,
+    getLastSpawnError: () => lastSpawnError,
+  };
+}

package/src/pipeline/cascade-worker.js

@@ -0,0 +1,43 @@
+// FR-202 phase 3b (D-0050): the long-lived worker thread spawned by cascade-worker-pool.js.
+// Unlike analyzer-worker.js (one-shot: single call, single reply, then terminated by its
+// caller), this worker performs one-time setup ONCE at startup, then services many per-file
+// _runFileCascade task messages for the lifetime of the pool. See D-0050 for why per-file
+// setup (rebuilding the whole-project index for every single file) would be O(N^2) and was
+// rejected.
+import { parentPort, workerData } from 'node:worker_threads';
+
+const { modulePath, fileContents, scanRoot } = workerData;
+
+let mod = null;
+let initError = null;
+
+async function init() {
+  try {
+    mod = await import(modulePath);
+    if (typeof mod._initCascadeWorkerState !== 'function' || typeof mod._runFileCascade !== 'function') {
+      throw new Error(`module at ${modulePath} does not export _initCascadeWorkerState/_runFileCascade`);
+    }
+    await mod._initCascadeWorkerState(fileContents, scanRoot);
+    parentPort.postMessage({ type: 'ready' });
+  } catch (err) {
+    initError = String((err && err.stack) || err);
+    parentPort.postMessage({ type: 'init-error', error: initError });
+  }
+}
+
+parentPort.on('message', (msg) => {
+  if (!msg || msg.type !== 'task') return;
+  const { id, p, c, scanRoot: taskScanRoot, detectorErrors } = msg;
+  if (!mod) {
+    parentPort.postMessage({ id, ok: false, error: initError || 'worker not initialized' });
+    return;
+  }
+  try {
+    const result = mod._runFileCascade(p, c, taskScanRoot, detectorErrors || []);
+    parentPort.postMessage({ id, ok: true, result });
+  } catch (err) {
+    parentPort.postMessage({ id, ok: false, error: String((err && err.message) || err) });
+  }
+});
+
+init();

package/src/pipeline/detector-runner.js

@@ -0,0 +1,51 @@
+// Detector runner (assurance-hardening PRD, E2 decomposition — D-0028 step
+// (a): "build a small `_runDetector(errs, file, name, thunk)` isolation
+// helper first (low-risk, no call sites touched yet)").
+//
+// FR-201: "Execute detectors in isolated units with per-analyzer error
+// capture | One detector exception does not prevent subsequent independent
+// analyzers from running."
+//
+// Modeled directly on `annotator-runner.js`'s own runAnnotatorAsync (FR-106,
+// already shipped) — same isolation contract, same "extract into its own
+// file so the capture path can be fault-injection tested directly" rationale
+// (this codebase's own detectors are built never to throw in practice, so
+// there is no natural way to prove the isolation works end-to-end without
+// synthetic throwing callbacks). The one real difference: every one of
+// `engine.js`'s ~128 per-file detector call sites is SYNCHRONOUS — none
+// return a Promise — so this helper is deliberately sync-only, not a
+// generic sync-or-async wrapper. Wrapping ~128 calls per file in an async
+// function across every scanned file would add real Promise-microtask
+// overhead to the hottest loop in the engine for no benefit any detector
+// actually needs.
+//
+// THIS MODULE HAS NO CALLER YET, BY DESIGN. D-0028's own decomposition is
+// explicit that step (a) — this helper — must exist and be proven correct
+// BEFORE step (b) (migrating the ~128 heterogeneous call sites in small,
+// git-diffable, gate-verified batches) begins. Wiring it into engine.js
+// is intentionally out of scope for this step.
+
+/**
+ * Run one detector (`fn`), isolating any exception it throws so it cannot
+ * abort the caller's per-file loop. On success, returns `fn()`'s value
+ * unchanged. On a thrown exception, appends a structured entry to
+ * `detectorErrors` and returns `undefined` — the SAME "undefined means it
+ * failed, check the errors array" contract `runAnnotatorAsync` already
+ * establishes, so a caller spreading the result into an array must guard
+ * with `...(runDetector(...) || [])`, exactly as existing `_runAnnotator`
+ * call sites already do for their own non-array return values.
+ *
+ * @param {Array<{file:string, analyzer:string, err:string}>} detectorErrors - mutated in place (push only)
+ * @param {string} file - the file being analyzed when `fn` was invoked
+ * @param {string} analyzer - the detector's name, for FR-203's future per-analyzer coverage ledger
+ * @param {() => any} fn - the detector call itself, e.g. `() => scanXxx(file, cc)`
+ * @returns {any} fn()'s return value, or undefined if it threw
+ */
+export function runDetector(detectorErrors, file, analyzer, fn) {
+  try {
+    return fn();
+  } catch (e) {
+    detectorErrors.push({ file, analyzer, err: String((e && e.message) || e) });
+    return undefined;
+  }
+}

package/src/pipeline/enrichment-completion.js

@@ -0,0 +1,58 @@
+// Enrichment completion pass (assurance-hardening PRD, Milestone 1, FR-103).
+//
+// engine.js's primary enrichment chain (stableId -> defaults -> confidence
+// -> calibration -> exploitability -> proof-gate -> ...) runs once, early,
+// over whatever is in `finalFindings` at that moment. At least 19 separate
+// call sites append MORE findings after that chain already ran (A-03) —
+// cross-language taint, IAM/container/business-logic/spec-drift/concurrency
+// producers, privacy-taint, plus several opt-in "world-class artifact"
+// emitters (API contract, SBOM diff, license graph, multi-sink synthesis).
+// Moving all 19 call sites earlier in that ~900-line function was
+// considered and rejected as the fix here: several depend on state (aR,
+// annotatedComponents, supplyChain dedup results) not yet computed at an
+// earlier point, and relocating them carries real regression risk against
+// this project's own 500+-entry accuracy corpus for a single engineering
+// cycle's blast radius.
+//
+// Instead: this is a GAP-FILLING pass, run once, late, right before the
+// finding collection is frozen (FR-104). It finds every finding still
+// missing a stableId — the reliable marker of "never went through the
+// primary chain," since annotateStableIds is the first stage in that chain
+// and runs unconditionally — and runs the same core stages on exactly that
+// subset. This covers every late producer's output equally, whether or not
+// that producer has been converted to go through producer-collector.js
+// (see that module's header for which ones have).
+//
+// Two of the four stages (backfillFindingDefaults, annotateConfidence)
+// already skip a finding that has the field set, so calling them here is
+// pure gap-filling by construction. The other two (annotateCalibratedConfidence,
+// annotateExploitability) always recompute unconditionally, which is why
+// this scopes to the late subset rather than the whole array — cheap and
+// correct, not "cheap because deduped by luck."
+
+import { annotateStableIds } from '../posture/stable-id.js';
+import { backfillFindingDefaults } from '../posture/finding-defaults.js';
+import { annotateConfidence } from '../posture/confidence.js';
+import { annotateCalibratedConfidence } from '../posture/calibration.js';
+import { annotateExploitability } from '../posture/exploitability.js';
+
+/**
+ * @param {object[]} finalFindings
+ * @param {object} ctx
+ * @param {string} ctx.scanRoot
+ * @param {object} ctx.projectCtx - same shape engine.js's own annotateExploitability call already builds
+ * @returns {{gapFilledCount:number}}
+ */
+export function completeEnrichment(finalFindings, { scanRoot, projectCtx } = {}) {
+  if (!Array.isArray(finalFindings)) return { gapFilledCount: 0 };
+  const late = finalFindings.filter(f => f && typeof f === 'object' && !f.stableId);
+  if (!late.length) return { gapFilledCount: 0 };
+
+  annotateStableIds(late);
+  backfillFindingDefaults(late);
+  annotateConfidence(late);
+  try { annotateCalibratedConfidence(late, { scanRoot }); } catch { /* calibration table load is best-effort */ }
+  try { annotateExploitability(late, projectCtx || {}); } catch { /* scoring is best-effort */ }
+
+  return { gapFilledCount: late.length };
+}

package/src/pipeline/evidence-provenance.js

@@ -0,0 +1,91 @@
+// Evidence provenance (assurance-hardening PRD, Milestone 1, FR-107).
+//
+// A real scanned finding carries ~90 flat fields (verified against a live
+// scan of test/fixtures/vulnerable-js before writing this) — a mix of what
+// the detector directly OBSERVED (file, line, matched snippet, rule id) and
+// what LATER ANNOTATORS INFERRED from it (confidence, calibrated_confidence,
+// severity adjustments, exploitability, compositeRisk, crownJewelScore,
+// riskDollars, toxicity, blastRadius, and dozens more). Nothing about the
+// flat shape tells a reviewer which is which — that distinction exists only
+// as tribal knowledge of which field name means what. FR-107's acceptance
+// criterion is exactly this: "A reviewer can distinguish observed facts from
+// inferred confidence, severity, and risk."
+//
+// `posture/why-fired.js` ALREADY captures genuine raw evidence — sink/source
+// snippets, path steps, sanitizers considered — nested under
+// `finding.whyFired.evidence`, and is already wired into engine.js's default
+// pipeline (confirmed: `annotateWhyFired` runs on every scan). That module
+// solves "what did the detector see" for the detection step itself. This
+// module does the complementary, coarser-grained job FR-107 actually asks
+// for: given ANY finding, cleanly partition its top-level fields into
+// observed vs. derived, so a reviewer (or a report) can ask the question
+// without already knowing which of ~90 field names is which.
+//
+// DESIGN: an explicit ALLOWLIST of observed fields, not a blocklist of
+// derived ones. A blocklist enumerating ~80 derived field names would need
+// updating every time a new annotator ships a new field — exactly the kind
+// of drift this session has repeatedly found and fixed elsewhere (producer
+// registry, artifact registry, egress completeness guard). An allowlist of
+// the small, stable set of fields a DETECTOR sets before any annotator runs
+// is self-maintaining: anything not on it is derived by construction, so a
+// new annotator's new field is correctly classified `derived` automatically,
+// with zero maintenance here.
+//
+// Additive, non-throwing, Milestone-1 observability — like FR-105's
+// describeFindingCompleteness, this does not mutate findings, gate anything,
+// or run from engine.js's default pipeline.
+
+import { FINDING_SCHEMA_VERSION } from './finding-schema.js';
+
+// The fields a detector sets to describe WHAT it found and WHERE, before any
+// annotator has touched the finding. Matches report/index.js's
+// normalizeFindings() identity/location field names (not invented — read
+// from the actual canonical shape, per this session's D-0003 discipline).
+export const RAW_OBSERVED_FIELDS = Object.freeze([
+  'id', 'stableId', 'kind', 'vuln', 'cwe', 'owaspLlm', 'stride', 'family', 'parser',
+  'file', 'line', 'snippet',
+]);
+
+/**
+ * Split one finding's fields into what was directly observed by a detector
+ * vs. what was inferred by a later annotator.
+ *
+ * @param {object} finding - one entry from report/index.js#normalizeFindings()'s
+ *   output (the same contract describeFindingCompleteness uses) — NOT a raw
+ *   pre-normalization engine finding. Some detector families only set `line`/
+ *   `snippet` nested under `f.source`/`f.sink` internally; normalizeFindings()
+ *   is what guarantees they land as flat top-level keys, which is what this
+ *   function's field partition depends on.
+ * @returns {{schemaVersion:number, observed:object, derived:object}}
+ *   `observed` — RAW_OBSERVED_FIELDS present on the finding, plus
+ *   `detectorEvidence` (finding.whyFired.evidence, when annotateWhyFired has
+ *   run) — the snippets/path/sanitizers a detector directly saw.
+ *   `derived` — every OTHER non-null field: confidence, severity,
+ *   exploitability, compositeRisk, riskDollars, and everything else any
+ *   annotator computed. Named `derived` rather than enumerated because the
+ *   set of annotator-added fields grows over time and enumerating it here
+ *   would silently go stale (see module header).
+ */
+export function describeEvidenceProvenance(finding) {
+  const f = finding && typeof finding === 'object' ? finding : {};
+  const observedSet = new Set(RAW_OBSERVED_FIELDS);
+  const observed = {};
+  const derived = {};
+
+  for (const [key, value] of Object.entries(f)) {
+    if (value === null || value === undefined) continue;
+    if (observedSet.has(key)) observed[key] = value;
+    else derived[key] = value;
+  }
+
+  // whyFired.evidence is itself raw (what the detector saw); whyFired as a
+  // whole still lands in `derived` above since it also carries `considered`
+  // (pipeline-processing outcomes) and `scanner` (ruleset provenance) —
+  // neither is "what the detector observed", so only the evidence slice is
+  // promoted into `observed`, not the whole wrapper object.
+  if (f.whyFired && typeof f.whyFired === 'object' && f.whyFired.evidence) {
+    observed.detectorEvidence = f.whyFired.evidence;
+  }
+
+  return { schemaVersion: FINDING_SCHEMA_VERSION, observed, derived };
+}