@quantakrypto/core 0.2.2 → 0.4.0

package/src/index.ts

@@ -18,6 +18,41 @@ export type { SarifLog } from "./report.js";
 // Core orchestration + built-in detector set.
 export { scan, detectors, detectFile, compareFindings } from "./scan.js";
 
+// Snippet-level fix verification (shared by MCP verify_fix + remediation).
+export { verifyFix, languageToExtension } from "./verify.js";
+export type { VerifyResult } from "./verify.js";
+
+// Agent-plane shared types + the context redactor (offline; reused by MCP).
+export type {
+  ContextLevel,
+  RedactedContext,
+  TriageVerdict,
+  Patch,
+  FixProposal,
+} from "./agent-types.js";
+export { buildContext, renderPreflight } from "./redact.js";
+export { TRIAGE_RUBRIC, TRIAGE_VERDICT_SCHEMA, buildTriageRequest } from "./triage.js";
+export type { TriageRequest } from "./triage.js";
+export {
+  REMEDIATE_RUBRIC,
+  FIX_REQUEST_SCHEMA,
+  buildRemediateRequest,
+} from "./remediate-request.js";
+export type { RemediateRequest } from "./remediate-request.js";
+export { checkPatchPolicy } from "./patch-policy.js";
+export type { PolicyContext, PolicyDecision } from "./patch-policy.js";
+export { withWorktree } from "./worktree.js";
+export { codemodRegistry, codemodFor } from "./codemods/registry.js";
+export type { Codemod } from "./codemods/registry.js";
+export { configToggleCodemod } from "./codemods/config-toggle.js";
+export { remediateFindings } from "./remediate-pipeline.js";
+export type {
+  RemediateOptions,
+  RemediationResult,
+  VerifiedPatch,
+  RejectedPatch,
+} from "./remediate-pipeline.js";
+
 // Scan cancellation / work-budget errors.
 export { AbortError, BudgetExceededError } from "./errors.js";
 
@@ -25,8 +60,9 @@ export { AbortError, BudgetExceededError } from "./errors.js";
 export { scanParallel, mergeChunkResults, chunkByBytes } from "./parallel.js";
 export type { ScanChunk, ChunkResult, SizedFile } from "./parallel.js";
 
-// Detector registry (plugin point) + helpers.
+// Detector registry (plugin point) + helpers + the rule catalog.
 export { DetectorRegistry, defaultRegistry, detectorScope } from "./registry.js";
+export type { RuleCatalogEntry } from "./registry.js";
 
 // Canonical baseline (shared by qScan + the Action).
 export {
@@ -49,11 +85,20 @@ export type { QuantakryptoFileConfig, LoadConfigResult } from "./config.js";
 // Filesystem walker (relative POSIX paths, default ignores, size/binary filters).
 export { walkFiles, isBinaryPath, isGeneratedPath, looksMinified } from "./walk.js";
 
+// Analyzable-language coverage (which source languages the scanner inspects).
+export {
+  isAnalyzableSource,
+  ANALYZABLE_SOURCE_EXTENSIONS,
+  ANALYZABLE_LANGUAGES_LABEL,
+} from "./detect-utils.js";
+
 // Inventory + readiness score.
 export { buildInventory } from "./inventory.js";
 
 // Vulnerable-dependency database (the manifest scanner is used internally by scan()).
-export { vulnerableDependencies } from "./dependencies.js";
+// `DEP_VULNERABLE_RULE` is the generic catalog entry for dependency findings
+// (which don't come from a Detector, so aren't in the registry's rule catalog).
+export { vulnerableDependencies, DEP_VULNERABLE_RULE, isManifestFile } from "./dependencies.js";
 
 // Severity utilities (ordering, threshold, SARIF level) — shared across tools.
 export { SEVERITY_ORDER, severityRank, meetsThreshold, sarifLevel } from "./severity.js";

package/src/parallel.ts

@@ -18,8 +18,10 @@ import type { Worker as NodeWorker } from "node:worker_threads";
 
 import type { Finding, ParallelScanOptions, ScanResult } from "./types.js";
 import { walkFiles } from "./walk.js";
+import { isAnalyzableSource } from "./detect-utils.js";
 import { buildInventory } from "./inventory.js";
 import { compareFindings, filterExplicitFileList, scan } from "./scan.js";
+import { AbortError, BudgetExceededError } from "./errors.js";
 import { VERSION } from "./version.js";
 
 /** One unit of work dispatched to a worker. */
@@ -31,6 +33,10 @@ export interface ScanChunk {
 export interface ChunkResult {
   findings: Finding[];
   filesScanned: number;
+  /** Files that couldn't be read in this chunk (optional; older workers omit it). */
+  unreadable?: number;
+  /** Files skipped as minified in this chunk (optional; older workers omit it). */
+  skippedMinified?: number;
 }
 
 const DEFAULT_PARALLEL_THRESHOLD_BYTES = 2 * 1024 * 1024;
@@ -74,12 +80,16 @@ export function chunkByBytes(files: readonly SizedFile[], chunkBytes: number): S
 export function mergeChunkResults(results: readonly ChunkResult[]): ChunkResult {
   const findings: Finding[] = [];
   let filesScanned = 0;
+  let unreadable = 0;
+  let skippedMinified = 0;
   for (const r of results) {
     for (const f of r.findings) findings.push(f);
     filesScanned += r.filesScanned;
+    unreadable += r.unreadable ?? 0;
+    skippedMinified += r.skippedMinified ?? 0;
   }
   findings.sort(compareFindings);
-  return { findings, filesScanned };
+  return { findings, filesScanned, unreadable, skippedMinified };
 }
 
 /** Resolve the worker count (>= 1). */
@@ -162,14 +172,29 @@ export async function scanParallel(options: ParallelScanOptions): Promise<ScanRe
   const rootStat = await stat(options.root);
   const baseDir = rootStat.isFile() ? path.dirname(options.root) : options.root;
 
-  // Single-file roots and the override-detectors path always run serially:
-  // detectors may not be structured-cloneable across the worker boundary.
-  if (rootStat.isFile() || options.detectors) {
+  // Single-file roots, the override-detectors path, and the scan cache always
+  // run serially: detectors may not be structured-cloneable across the worker
+  // boundary, and the cache read/write is owned by the in-process `scan()`.
+  if (rootStat.isFile() || options.detectors || options.cacheFile) {
     return scan(options);
   }
 
   const files = await enumerateFiles(options, baseDir);
 
+  // Budget + cancellation parity with the serial path. The parallel path
+  // enumerates upfront, so budgets are enforced against the whole file set
+  // before any worker is dispatched.
+  if (options.signal?.aborted) throw new AbortError();
+  if (typeof options.maxFiles === "number" && files.length > options.maxFiles) {
+    throw new BudgetExceededError(`maxFiles budget exceeded (limit: ${options.maxFiles}).`);
+  }
+  if (typeof options.maxBytes === "number") {
+    const totalBytes = files.reduce((n, f) => n + f.size, 0);
+    if (totalBytes > options.maxBytes) {
+      throw new BudgetExceededError(`maxBytes budget exceeded (limit: ${options.maxBytes}).`);
+    }
+  }
+
   if (!shouldParallelize(options, files)) {
     // In-process: reuse the exact serial path over the same file list.
     return scan({ ...options, files: files.map((f) => f.rel) });
@@ -191,6 +216,8 @@ export async function scanParallel(options: ParallelScanOptions): Promise<ScanRe
     config: options.config !== false,
     deps: options.dependencies !== false,
     scanMinified: options.scanMinified === true,
+    // Plain string array — structured-cloneable, so it crosses the worker boundary.
+    disabledRules: options.disabledRules,
   };
 
   let results: ChunkResult[];
@@ -204,9 +231,12 @@ export async function scanParallel(options: ParallelScanOptions): Promise<ScanRe
       chunks,
       concurrency,
       options.onFile,
+      options.signal,
     );
-  } catch {
-    // Any worker failure → safe fallback to the serial path.
+  } catch (err) {
+    // Cancellation / budget overflow must propagate, not silently degrade.
+    if (err instanceof AbortError || err instanceof BudgetExceededError) throw err;
+    // Any other worker failure → safe fallback to the serial path.
     return scan({ ...options, files: files.map((f) => f.rel) });
   }
 
@@ -214,10 +244,21 @@ export async function scanParallel(options: ParallelScanOptions): Promise<ScanRe
   const inventory = buildInventory(merged.findings);
   const finishedAt = new Date();
 
+  // Coverage: count analyzable-source files in the enumerated set. Computed from
+  // the file list (not per-worker) to avoid worker-boundary plumbing; on the
+  // parallel path this can include a minified analyzable file the workers
+  // skipped, but that is vanishingly rare and never under-reports coverage.
+  const analyzedFiles = files.reduce((n, f) => (isAnalyzableSource(f.rel) ? n + 1 : n), 0);
+
   return {
     root: options.root,
     findings: merged.findings,
     filesScanned: merged.filesScanned,
+    analyzedFiles,
+    diagnostics: {
+      unreadable: merged.unreadable ?? 0,
+      skippedMinified: merged.skippedMinified ?? 0,
+    },
     inventory,
     startedAt: startedAt.toISOString(),
     finishedAt: finishedAt.toISOString(),
@@ -231,10 +272,17 @@ function runPool(
   entry: string,
   execArgv: string[] | undefined,
   baseDir: string,
-  toggles: { source: boolean; config: boolean; deps: boolean; scanMinified: boolean },
+  toggles: {
+    source: boolean;
+    config: boolean;
+    deps: boolean;
+    scanMinified: boolean;
+    disabledRules?: string[];
+  },
   chunks: ScanChunk[],
   concurrency: number,
   onFile?: (file: string) => void,
+  signal?: AbortSignal,
 ): Promise<ChunkResult[]> {
   return new Promise((resolve, reject) => {
     const results: ChunkResult[] = new Array(chunks.length);
@@ -243,10 +291,27 @@ function runPool(
     let failed = false;
     const workers: Array<NodeWorker> = [];
 
+    const onAbort = (): void => {
+      if (failed) return;
+      failed = true;
+      cleanup();
+      reject(new AbortError());
+    };
+
     const cleanup = () => {
+      if (signal) signal.removeEventListener("abort", onAbort);
       for (const w of workers) void w.terminate();
     };
 
+    // Cooperative cancellation: stop dispatching and tear down on abort.
+    if (signal) {
+      if (signal.aborted) {
+        reject(new AbortError());
+        return;
+      }
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+
     const dispatch = (w: NodeWorker): void => {
       if (failed) return;
       if (next >= chunks.length) {

package/src/patch-policy.ts

@@ -0,0 +1,42 @@
+/**
+ * Patch-policy allowlist. A remediation patch may only edit a file that already
+ * has a finding, or add dependencies to a manifest. Everything else — CI config,
+ * lockfiles, env/secret files, unrelated source — is denied. This is the second
+ * safety gate (the first is `verify_fix`): even a "verified" patch is dropped if
+ * it strays outside the sanctioned surface.
+ */
+import type { Patch } from "./agent-types.js";
+
+/** Files a remediation may write to. */
+export interface PolicyContext {
+  /** Relative paths (posix) that contain at least one finding. */
+  findingFiles: Set<string>;
+  /** Relative manifest paths (package.json, requirements.txt, …). */
+  manifestFiles: Set<string>;
+}
+
+/**
+ * Paths a patch may NEVER touch, regardless of anything else: version control,
+ * CI, dependency lockfiles, and anything that looks like a secret/env file.
+ */
+const DENY_RE =
+  /(^|\/)(\.github|\.git|node_modules)\/|(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|Gemfile\.lock|poetry\.lock)$|(^|\/)\.env(\.[^/]*)?$|\.(pem|key|p12|pfx)$/i;
+
+export interface PolicyDecision {
+  allowed: boolean;
+  reason?: string;
+}
+
+/** Decide whether `patch` may be applied under `ctx`. */
+export function checkPatchPolicy(patch: Patch, ctx: PolicyContext): PolicyDecision {
+  const p = patch.path.replace(/\\/g, "/");
+  if (DENY_RE.test(p)) {
+    return { allowed: false, reason: `patch touches a protected path (${p})` };
+  }
+  if (ctx.findingFiles.has(p)) return { allowed: true };
+  if (ctx.manifestFiles.has(p)) return { allowed: true };
+  return {
+    allowed: false,
+    reason: `patch edits ${p}, which has no finding and is not a dependency manifest`,
+  };
+}

package/src/redact.ts

@@ -0,0 +1,92 @@
+/**
+ * Context redactor: turn a finding + its file into the payload the LLM sees,
+ * bounded to a chosen {@link ContextLevel} and with secrets ALWAYS stripped.
+ *
+ * This is a hard privacy boundary and lives in `@quantakrypto/core` (offline) so
+ * the deterministic MCP plane redacts identically to the networked CLI. A
+ * `sensitive` finding (the match IS key material) never emits code at any level.
+ */
+import type { Finding } from "./types.js";
+import type { ContextLevel, RedactedContext } from "./agent-types.js";
+
+/** Lines of context on each side of the match at `snippet` level. */
+const SNIPPET_RADIUS = 8;
+
+/**
+ * PEM blocks and long unbroken base64 runs (≥120 chars) are treated as secret
+ * material and masked, even inside otherwise-shareable code.
+ */
+const SECRET_RE =
+  /-----BEGIN [A-Z0-9 ]+-----[\s\S]*?-----END [A-Z0-9 ]+-----|[A-Za-z0-9+/]{120,}={0,2}/g;
+
+function stripSecrets(text: string): { text: string; redacted: boolean } {
+  let redacted = false;
+  const out = text.replace(SECRET_RE, () => {
+    redacted = true;
+    return "«redacted-secret»";
+  });
+  return { text: out, redacted };
+}
+
+/** Best-effort enclosing brace/colon block around a 0-based line index. */
+function enclosingBlock(lines: string[], idx: number): string {
+  let start = idx;
+  while (start > 0 && !/[{:]\s*$/.test(lines[start - 1] ?? "")) start--;
+  let end = idx;
+  let depth = 0;
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    depth += (line.match(/{/g) ?? []).length - (line.match(/}/g) ?? []).length;
+    end = i;
+    if (i > idx && depth <= 0) break;
+  }
+  return lines.slice(start, end + 1).join("\n");
+}
+
+/**
+ * Build the redacted context for `finding` at `level`. `fileContent` is the full
+ * text of the file the finding lives in (unused at `metadata` level). Secrets
+ * are always removed; a `sensitive` finding yields `code: null`.
+ */
+export function buildContext(
+  finding: Finding,
+  level: ContextLevel,
+  fileContent: string,
+): RedactedContext {
+  const meta = {
+    ruleId: finding.ruleId,
+    algorithm: finding.algorithm,
+    severity: finding.severity,
+    hndl: finding.hndl,
+    file: finding.location.file,
+    line: finding.location.line,
+    message: finding.message,
+  };
+  // Sensitive findings never emit code, at any level.
+  if (finding.sensitive) return { level, meta, code: null, redactedSecret: true };
+  if (level === "metadata") return { level, meta, code: null, redactedSecret: false };
+
+  const lines = fileContent.split("\n");
+  let code: string;
+  if (level === "file") {
+    code = fileContent;
+  } else if (level === "function") {
+    code = enclosingBlock(lines, finding.location.line - 1);
+  } else {
+    const i = finding.location.line - 1;
+    code = lines.slice(Math.max(0, i - SNIPPET_RADIUS), i + SNIPPET_RADIUS + 1).join("\n");
+  }
+  const { text, redacted } = stripSecrets(code);
+  return { level, meta, code: text, redactedSecret: redacted };
+}
+
+/** Render the exact payload text a `--dry-run` preflight would send. */
+export function renderPreflight(contexts: RedactedContext[]): string {
+  return contexts
+    .map((c) => {
+      const flags = `level=${c.level}${c.redactedSecret ? ", secret-redacted" : ""}`;
+      const head = `[${c.meta.severity}] ${c.meta.ruleId} ${c.meta.file}:${c.meta.line} (${flags})`;
+      return c.code ? `${head}\n${c.code}` : head;
+    })
+    .join("\n\n---\n\n");
+}

package/src/registry.ts

@@ -10,8 +10,15 @@
  * To add a language or detector, see the "Adding a detector / language" section
  * of the package README.
  */
-import type { Detector, DetectorScope } from "./types.js";
+import type { Detector, DetectorScope, RuleMeta } from "./types.js";
 import { sourceDetectors } from "./detectors/source.js";
+import { pythonDetector } from "./detectors/python.js";
+import { goDetector } from "./detectors/go.js";
+import { javaDetector } from "./detectors/java.js";
+import { csharpDetector } from "./detectors/csharp.js";
+import { rustDetector } from "./detectors/rust.js";
+import { rubyDetector } from "./detectors/ruby.js";
+import { cDetector } from "./detectors/c.js";
 import { pemDetector } from "./detectors/pem.js";
 
 /** Normalised scope of a detector (defaults to "source" when undeclared). */
@@ -19,6 +26,12 @@ export function detectorScope(d: Detector): DetectorScope {
   return d.scope ?? "source";
 }
 
+/** A rule plus the detector that emits it — the result of {@link DetectorRegistry.forRule}. */
+export interface RuleCatalogEntry {
+  rule: RuleMeta;
+  detector: Detector;
+}
+
 /**
  * An ordered, id-indexed collection of detectors. Registration order is
  * preserved by {@link all} for deterministic scan output. Ids must be unique.
@@ -57,6 +70,38 @@ export class DetectorRegistry {
     return this.order.map((id) => this.byId.get(id)!);
   }
 
+  /**
+   * The flattened rule catalog: every {@link RuleMeta} declared by every
+   * registered detector, in detector-registration then in-detector order. This
+   * is the single source of truth for rule metadata consumed by SARIF
+   * `rules[]`, the MCP `explain_finding` resolver, and per-rule enable/disable.
+   * Duplicate rule ids across detectors throw (ids are globally unique).
+   */
+  ruleCatalog(): RuleMeta[] {
+    const out: RuleMeta[] = [];
+    const seen = new Set<string>();
+    for (const det of this.all()) {
+      for (const rule of det.rules ?? []) {
+        if (seen.has(rule.id)) {
+          throw new Error(`duplicate rule id in catalog: ${rule.id}`);
+        }
+        seen.add(rule.id);
+        out.push(rule);
+      }
+    }
+    return out;
+  }
+
+  /** Resolve a rule id to its {@link RuleMeta} and the detector that emits it. */
+  forRule(ruleId: string): RuleCatalogEntry | undefined {
+    for (const det of this.all()) {
+      for (const rule of det.rules ?? []) {
+        if (rule.id === ruleId) return { rule, detector: det };
+      }
+    }
+    return undefined;
+  }
+
   /** A shallow copy of this registry (useful to extend the defaults). */
   clone(): DetectorRegistry {
     return new DetectorRegistry(this.all());
@@ -64,8 +109,29 @@ export class DetectorRegistry {
 }
 
 /**
- * The default registry, preloaded with the built-in detectors in run order:
- * the JS/TS source + config detectors, then the language-agnostic PEM detector.
- * The manifest (dependency) scanner is handled separately by `scan()`.
+ * The built-in detectors, in run order: the JS/TS source + config detectors,
+ * then the per-language detectors (Python, Go, Java, C#, Rust, Ruby, C/C++),
+ * then the language-agnostic PEM detector. The manifest (dependency) scanner is
+ * handled separately by `scan()`.
+ *
+ * This is the single source of truth for the default detector set: both
+ * {@link defaultRegistry} and the public `detectors` export (re-exported from
+ * `scan.ts`) are built from it, so the two can never drift out of sync.
+ */
+export const builtinDetectors: Detector[] = [
+  ...sourceDetectors,
+  pythonDetector,
+  goDetector,
+  javaDetector,
+  csharpDetector,
+  rustDetector,
+  rubyDetector,
+  cDetector,
+  pemDetector,
+];
+
+/**
+ * The default registry, preloaded with {@link builtinDetectors}. Used by
+ * `scan()` whenever `options.detectors` is not supplied.
  */
-export const defaultRegistry = new DetectorRegistry([...sourceDetectors, pemDetector]);
+export const defaultRegistry = new DetectorRegistry(builtinDetectors);

package/src/remediate-pipeline.ts

@@ -0,0 +1,81 @@
+/**
+ * The remediation pipeline: turn candidate patches (from codemods or the LLM)
+ * into VERIFIED, in-policy patches. Pure and deterministic — the verify gate
+ * runs `verifyFix` on the patched content in memory, so this needs no
+ * filesystem or git. Callers (the `qremediate` CLI) decide what to DO with the
+ * verified patches (print a diff, write them, or open a PR in a worktree).
+ *
+ * Two gates, both must pass:
+ *   1. patch-policy   — the patch may only touch sanctioned files.
+ *   2. verify_fix     — the patched content clears the target finding, adds no
+ *                       new finding type, and nets fewer findings than before.
+ */
+import type { Finding } from "./types.js";
+import type { Patch } from "./agent-types.js";
+import { checkPatchPolicy } from "./patch-policy.js";
+import type { PolicyContext } from "./patch-policy.js";
+import { verifyFix } from "./verify.js";
+
+export interface VerifiedPatch {
+  finding: Finding;
+  patch: Patch;
+}
+export interface RejectedPatch {
+  finding: Finding;
+  reason: string;
+}
+export interface RemediationResult {
+  applied: VerifiedPatch[];
+  rejected: RejectedPatch[];
+}
+
+export interface RemediateOptions {
+  /** Current content of the file a finding lives in. */
+  readContent: (finding: Finding) => Promise<string> | string;
+  /** Produce a candidate patch for a finding (codemod or LLM), or null. */
+  patchSource: (finding: Finding, content: string) => Promise<Patch | null> | Patch | null;
+  /** Which files a patch is allowed to touch. */
+  policy: PolicyContext;
+}
+
+/** True when `after` is a strict improvement over `before` for `finding`. */
+function passesVerify(before: Finding[], after: Finding[], finding: Finding): boolean {
+  const targetGone = !after.some((x) => x.ruleId === finding.ruleId);
+  const noNewRuleTypes = after.every((x) => before.some((b) => b.ruleId === x.ruleId));
+  return targetGone && noNewRuleTypes && after.length < before.length;
+}
+
+/**
+ * Run each finding through patchSource → policy → verify, collecting the patches
+ * that survive both gates and the reasons the rest were dropped.
+ */
+export async function remediateFindings(
+  findings: readonly Finding[],
+  opts: RemediateOptions,
+): Promise<RemediationResult> {
+  const applied: VerifiedPatch[] = [];
+  const rejected: RejectedPatch[] = [];
+
+  for (const finding of findings) {
+    const content = await opts.readContent(finding);
+    const patch = await opts.patchSource(finding, content);
+    if (!patch) {
+      rejected.push({ finding, reason: "no deterministic fix available" });
+      continue;
+    }
+    const decision = checkPatchPolicy(patch, opts.policy);
+    if (!decision.allowed) {
+      rejected.push({ finding, reason: decision.reason ?? "rejected by patch policy" });
+      continue;
+    }
+    const before = verifyFix(content, { filename: finding.location.file }).findings;
+    const after = verifyFix(patch.newContent, { filename: patch.path }).findings;
+    if (!passesVerify(before, after, finding)) {
+      rejected.push({ finding, reason: "patch did not pass the verify_fix gate" });
+      continue;
+    }
+    applied.push({ finding, patch });
+  }
+
+  return { applied, rejected };
+}

package/src/remediate-request.ts

@@ -0,0 +1,52 @@
+/**
+ * Remediation rubric, fix schema, and request-bundle builder — offline and
+ * deterministic, shared by `@quantakrypto/agent` (which prompts a model with
+ * them) and the MCP `remediate_findings` tool (which hands the bundle to the
+ * host agent). Keeping them here means the MCP server stays offline/key-free.
+ */
+import type { Finding } from "./types.js";
+import type { ContextLevel, RedactedContext } from "./agent-types.js";
+import { buildContext } from "./redact.js";
+
+/** The system rubric for a fix proposal. */
+export const REMEDIATE_RUBRIC =
+  "You are a post-quantum cryptography migration engineer. Given the FULL content " +
+  "of one source file plus a finding describing classical (quantum-vulnerable) " +
+  "cryptography in it, return the FULL corrected file content that removes the " +
+  "flagged usage, migrating to a post-quantum or hybrid construction " +
+  "(ML-KEM-768 / ML-DSA-65, hybrid X25519MLKEM768) where a safe replacement " +
+  "exists. Change as little as possible; preserve all other code and formatting " +
+  "exactly. If you cannot safely fix it, return newContent identical to the " +
+  "input. NEVER invent or alter secrets/keys. After proposing, VERIFY with the " +
+  "verify_fix tool and keep only fixes that clear the finding.";
+
+/** JSON Schema every fix proposal must satisfy. */
+export const FIX_REQUEST_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  required: ["path", "newContent", "explanation"],
+  properties: {
+    path: { type: "string" },
+    newContent: { type: "string" },
+    explanation: { type: "string" },
+  },
+};
+
+/** A remediation request bundle for the host agent. */
+export interface RemediateRequest {
+  instructions: string;
+  schema: Record<string, unknown>;
+  contexts: RedactedContext[];
+}
+
+/** Build a remediation request bundle (offline; metadata level unless `readContent`). */
+export function buildRemediateRequest(
+  findings: readonly Finding[],
+  level: ContextLevel = "metadata",
+  readContent?: (finding: Finding) => string,
+): RemediateRequest {
+  const effectiveLevel: ContextLevel = readContent ? level : "metadata";
+  const contexts = findings.map((f) =>
+    buildContext(f, effectiveLevel, readContent ? readContent(f) : ""),
+  );
+  return { instructions: REMEDIATE_RUBRIC, schema: FIX_REQUEST_SCHEMA, contexts };
+}

package/src/remediation.ts

@@ -96,6 +96,31 @@ export function remediationText(algorithm: AlgorithmFamily): string {
   return REMEDIATIONS[algorithm].recommendation;
 }
 
+/**
+ * True when a family's PQC replacement is a KEM — i.e. it's used for
+ * confidentiality / key-agreement (and is therefore harvest-now-decrypt-later
+ * exposed). RSA is in both this set and {@link isSignatureFamily}. Single
+ * source of truth for the family→target taxonomy used by tier guidance and the
+ * multi-family remediation composer.
+ */
+export function isConfidentialityFamily(algorithm: AlgorithmFamily): boolean {
+  return (
+    algorithm === "RSA" ||
+    algorithm === "ECDH" ||
+    algorithm === "DH" ||
+    algorithm === "X25519" ||
+    algorithm === "X448" ||
+    algorithm === "ECIES"
+  );
+}
+
+/** True when a family's PQC replacement is a signature scheme (ML-DSA / SLH-DSA). */
+export function isSignatureFamily(algorithm: AlgorithmFamily): boolean {
+  return (
+    algorithm === "RSA" || algorithm === "ECDSA" || algorithm === "EdDSA" || algorithm === "DSA"
+  );
+}
+
 /* -------------------------------------------------------------------------- */
 /* Security-tier guidance (CNSA 2.0 Category 5) + stateful HBS (SP 800-208)     */
 /* -------------------------------------------------------------------------- */
@@ -135,14 +160,7 @@ export function remediationForTier(
   const base = REMEDIATIONS[algorithm];
   const params = TIER_PARAMS[tier];
   // Confidentiality families lean on the KEM; signature families on the signer.
-  const isConfidentiality =
-    algorithm === "RSA" ||
-    algorithm === "ECDH" ||
-    algorithm === "DH" ||
-    algorithm === "X25519" ||
-    algorithm === "X448" ||
-    algorithm === "ECIES";
-  const primary = isConfidentiality ? params.kem : params.signature;
+  const primary = isConfidentialityFamily(algorithm) ? params.kem : params.signature;
   return {
     algorithm,
     recommendation: `${base.recommendation} — ${tier}: ${primary}`,
@@ -167,7 +185,5 @@ export const STATEFUL_HBS_NOTE =
 /** True when stateful HBS (SP 800-208) is a reasonable alternative for a family. */
 export function statefulHbsApplies(algorithm: AlgorithmFamily): boolean {
   // Signature families only — LMS/XMSS are signatures, not KEMs.
-  return (
-    algorithm === "RSA" || algorithm === "ECDSA" || algorithm === "EdDSA" || algorithm === "DSA"
-  );
+  return isSignatureFamily(algorithm);
 }