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

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 };
+}

package/src/pipeline/finding-schema.js

@@ -0,0 +1,108 @@
+// Finding schema (assurance-hardening PRD, Milestone 0, FR-105).
+//
+// The PRD's §10.1 envelope (schemaVersion/stableId/producerId/... in ten
+// named groups) describes an IDEAL shape. This engine's actual canonical
+// shape already exists — it is report/index.js's `normalizeFindings()`,
+// which every JSON/SARIF/HTML/CSV/JUnit/OSCAL output format calls (verified
+// by grepping every call site in report/index.js, oscal.js, and
+// bin/agentic-security.js before writing this module — see
+// docs/implementation/assurance-hardening-decisions.md D-0003's rule: read
+// the existing mechanism before building a parallel one). `normalizeFindings`
+// already enforces an explicit allowlist with an honest `null` default for
+// every optional field, which is most of what FR-105 asks for; it was simply
+// never versioned or independently callable as "does this finding satisfy
+// the contract".
+//
+// This module does two things, both additive (Milestone 0 scope — no gate
+// wiring, no new required fields, nothing gets rejected):
+//   1. Names FINDING_SCHEMA_VERSION so future breaking changes to the
+//      normalizeFindings shape have something to bump (FR-105 acceptance:
+//      "select a supported output contract during migration" per §12.1's
+//      `--schema-version` flag, not yet wired to a CLI flag in this cycle).
+//   2. Provides describeFindingCompleteness(), a pure, non-throwing function
+//      that reports which of the CURRENT canonical fields a given finding
+//      actually has non-null values for — observability, not enforcement.
+//      Full enforcement (every producer's output must pass validation before
+//      it can reach a reporter) is Milestone 1's FR-103/FR-104, which
+//      requires producer isolation (FR-201) to exist first so a rejected
+//      finding can be attributed to the producer that emitted it.
+//
+// One MCP correctness bug was found and fixed alongside this (not scope
+// creep — it's the exact FR-105 acceptance criterion "...and MCP outputs
+// derive from the same validated object"): mcp/tools.js's scan_diff hand-
+// rolled a 3-of-4-channel finding merge instead of calling
+// normalizeFindings(), which both risked field-mapping drift and silently
+// excluded the supplyChain channel. Fixed in mcp/tools.js; see that file's
+// comment for the residual limitation (scan_diff still never populates
+// depFileContents, so supply-chain detection does not reach it today for an
+// unrelated, deeper reason this schema module does not address).
+
+export const FINDING_SCHEMA_VERSION = 1;
+
+// Field groups mirror the PRD's §10.1 structure, using the CURRENT field
+// names normalizeFindings() actually produces (see decision D-0003: extend
+// what exists, don't invent a parallel vocabulary no real finding uses).
+// `required` fields are ones every finding channel (sast/secret/logic/sca)
+// sets to a real (non-null) value today; `optional` fields are legitimately
+// null on many findings (e.g. a finding no annotator has enriched yet).
+export const FINDING_FIELD_GROUPS = {
+  // `findingProvenance` is REQUIRED, not optional, and that is deliberate:
+  // posture/provenance/coordinator.js guarantees every finding it sees leaves
+  // with a TERMINAL provenance object, expressing every failure mode as a
+  // status ('not_available', 'uncommitted', 'budget_exhausted', 'error')
+  // rather than as an absent field. So a missing findingProvenance never means
+  // "provenance didn't apply here" — it means the finding escaped annotation
+  // entirely, which is exactly the condition this group exists to surface.
+  identity: { required: ['id', 'kind', 'vuln', 'findingProvenance'], optional: ['stableId'] },
+  location: { required: ['file', 'line'], optional: ['snippet'] },
+  classification: { required: ['severity'], optional: ['cwe', 'owaspLlm', 'family', 'parser', 'tags', 'description'] },
+  confidence: { required: [], optional: ['confidence', 'confidenceTier', 'calibrated_confidence', 'calibration_reason'] },
+  evidence: { required: [], optional: ['proof', 'falsification', 'verification', 'chain', 'sources', 'corroboration'] },
+  privacy: { required: [], optional: ['dataClasses'] },
+  compliance: { required: [], optional: [] }, // no per-finding controlRefs today — compliance mapping is scan-level (FR-501/E5)
+  remediation: { required: [], optional: ['fix', 'remediation'] },
+  risk: { required: [], optional: ['exploitability', 'exploitabilityTier', 'compositeRisk', 'compositeRiskTier', 'crownJewelScore', 'riskDollars'] },
+  lifecycle: { required: [], optional: ['triage', 'quarantined', 'unreachable'] },
+};
+
+/**
+ * Reports, for one normalized finding (i.e. an item from
+ * report/index.js#normalizeFindings' output — this function does NOT accept
+ * a raw pre-normalization finding), which canonical groups have their
+ * required fields present and which optional fields are populated.
+ *
+ * Pure, non-throwing, additive-only: does not mutate the finding, does not
+ * gate anything, and is not called from engine.js's default pipeline. It
+ * exists to be run over a real scan's output for observability (a future
+ * `--explain-health`-style report, per PRD §12.1) — see this module's
+ * header comment for what is deliberately NOT yet true of it.
+ *
+ * @param {object} finding - one entry from normalizeFindings(scan)
+ * @returns {{schemaVersion:number, missingRequiredFields:string[], populatedOptionalFields:string[], missingOptionalFields:string[], isComplete:boolean}}
+ */
+export function describeFindingCompleteness(finding) {
+  const f = finding && typeof finding === 'object' ? finding : {};
+  const missingRequiredFields = [];
+  const populatedOptionalFields = [];
+  const missingOptionalFields = [];
+
+  const isPopulated = (v) => v !== null && v !== undefined && !(Array.isArray(v) && v.length === 0);
+
+  for (const group of Object.values(FINDING_FIELD_GROUPS)) {
+    for (const field of group.required) {
+      if (!isPopulated(f[field])) missingRequiredFields.push(field);
+    }
+    for (const field of group.optional) {
+      if (isPopulated(f[field])) populatedOptionalFields.push(field);
+      else missingOptionalFields.push(field);
+    }
+  }
+
+  return {
+    schemaVersion: FINDING_SCHEMA_VERSION,
+    missingRequiredFields,
+    populatedOptionalFields,
+    missingOptionalFields,
+    isComplete: missingRequiredFields.length === 0,
+  };
+}

package/src/pipeline/legacy-compat.js

@@ -0,0 +1,101 @@
+// Legacy field compatibility adapter (assurance-hardening PRD, Milestone 1,
+// FR-108: "Publish a compatibility adapter for legacy finding consumers.
+// Existing integrations receive a deprecation warning and equivalent legacy
+// fields for one documented transition period.")
+//
+// This codebase's own stated convention (repeated three times across
+// CHANGELOG.md: "No breaking changes. All new capabilities are additive")
+// means a finding field should almost never be renamed or removed out from
+// under an existing consumer. But it can happen for a good reason — this
+// same session's FR-804 renamed `riskDollars.confidenceFloor` to
+// `confidenceWeight` because the old name was actively misleading (the
+// field stopped being a floor once the bug it named was fixed) — and when
+// it does, a consumer reading the old field name should not silently start
+// getting `undefined`. That rename is the concrete, real case this adapter
+// exists for, not a hypothetical one.
+//
+// LEGACY_FIELD_ALIASES names every known rename. applyLegacyCompat(finding)
+// backfills the OLD dotted path from the NEW one's current value whenever
+// the new value is present and nothing already occupies the old path — an
+// existing integration reading the deprecated name keeps working, unchanged,
+// for the documented transition period. legacyFieldDeprecationNotice()
+// turns that into the single, honest, report-level notice FR-108 asks for,
+// rather than silently reintroducing the old shape forever with no signal
+// that it is scheduled for removal.
+
+export const LEGACY_FIELD_ALIASES = Object.freeze([
+  Object.freeze({
+    oldPath: 'riskDollars.confidenceFloor',
+    newPath: 'riskDollars.confidenceWeight',
+    deprecatedInVersion: '0.143.0', // FR-804, same session as this adapter
+    sunsetAfter: '2027-02-24', // ~6 months from this adapter's introduction
+    reason: "renamed because the field stopped being a floor — Math.max(0.4, f.confidence || 0.8)'s unconditional floor and 0-as-falsy inflation were removed as part of FR-804's fix",
+  }),
+]);
+
+function _getPath(obj, dottedPath) {
+  return dottedPath.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), obj);
+}
+
+function _setPath(obj, dottedPath, value) {
+  const parts = dottedPath.split('.');
+  let o = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    // Only backfill onto a parent object that already exists — if
+    // riskDollars itself is null/absent, there is nothing to attach a
+    // legacy alias to, and creating a fake `{confidenceFloor: ...}` shell
+    // would be actively misleading (it would look like a real annotation
+    // that never ran).
+    if (o[parts[i]] == null || typeof o[parts[i]] !== 'object') return false;
+    o = o[parts[i]];
+  }
+  o[parts[parts.length - 1]] = value;
+  return true;
+}
+
+/**
+ * Backfill deprecated field names on ONE finding from their current
+ * replacements. Mutates the finding in place (matches every other
+ * annotator's convention in this codebase). Additive only — never
+ * overwrites a value already present at the old path, so a caller that set
+ * the legacy field explicitly (e.g. a hand-built test fixture) is never
+ * clobbered.
+ *
+ * @returns {string[]} which legacy field paths were actually backfilled —
+ *   empty for the common, eventual steady state where nothing legacy fired.
+ */
+export function applyLegacyCompat(finding) {
+  if (!finding || typeof finding !== 'object') return [];
+  const applied = [];
+  for (const alias of LEGACY_FIELD_ALIASES) {
+    const newValue = _getPath(finding, alias.newPath);
+    if (newValue === undefined) continue; // nothing to backfill from
+    if (_getPath(finding, alias.oldPath) !== undefined) continue; // already set — don't clobber
+    if (_setPath(finding, alias.oldPath, newValue)) applied.push(alias.oldPath);
+  }
+  if (applied.length) finding._legacyFields = applied;
+  return applied;
+}
+
+/**
+ * A single, report-level deprecation notice summarizing every legacy alias
+ * actually used across a finding set. Returns null when none fired.
+ */
+export function legacyFieldDeprecationNotice(findings) {
+  if (!Array.isArray(findings)) return null;
+  const used = new Set();
+  for (const f of findings) {
+    if (Array.isArray(f?._legacyFields)) for (const p of f._legacyFields) used.add(p);
+  }
+  if (used.size === 0) return null;
+  const fields = [...used].sort().map(oldPath => {
+    const alias = LEGACY_FIELD_ALIASES.find(a => a.oldPath === oldPath);
+    return alias
+      ? { oldPath, newPath: alias.newPath, deprecatedInVersion: alias.deprecatedInVersion, sunsetAfter: alias.sunsetAfter, reason: alias.reason }
+      : { oldPath, newPath: null, deprecatedInVersion: null, sunsetAfter: null, reason: null };
+  });
+  return {
+    message: 'This report includes deprecated legacy field name(s), backfilled from their current replacements for backward compatibility. Update integrations to read the new field name(s) before the documented sunset date.',
+    fields,
+  };
+}