infraweaver 0.1.0

package/src/mcp/terraform/findings.ts

@@ -0,0 +1,383 @@
+import { type } from "arktype";
+import { TOOL_NAME } from "#app/brand";
+import { ruleDocUrl } from "#app/mcp/terraform/decisions";
+import { NATIVE_SOURCE, nativeRuleOf } from "#app/mcp/terraform/nativeRules";
+import { toRepoRelative } from "#app/mcp/terraform/paths";
+import { parseScannerJson } from "#app/mcp/terraform/scannerJson";
+import {
+  type Concern,
+  concernId,
+  cvssScoreForSeverity,
+  isTerraformFile,
+  lowerSeverity,
+  type Severity,
+  severityFromCvss,
+} from "#app/mcp/terraform/types";
+import { redactSecrets } from "#app/utils/redact";
+
+// --- reviewer findings (read_findings) ------------------------------------
+
+/**
+ * The subset of a terraform-reviewer (Assessor) `findings.json` finding that
+ * Infraweaver consumes. The reviewer's contract is a deliberate SUPERSET of the
+ * Concern model (same content-id formula, same severity enum) — see
+ * ../terraform-reviewer/schemas/findings.schema.json. Extra fields
+ * (lens/standard/control_id/confidence/state) are ignored except `state`.
+ */
+const ReviewerFinding = type({
+  "category?": "string",
+  "source?": "string",
+  "rule_id?": "string",
+  // verified (deterministic) | evidence (confirm manually) | human_only (out of scope).
+  "state?": "string",
+  "severity?": "string",
+  "evidence?": "string",
+  "location?": { "file?": "string", "line?": "number | null" },
+  "remediation_hint?": "string | null",
+});
+
+const ReviewerFindingsReport = type({
+  "schema_version?": "string",
+  "findings?": ReviewerFinding.array().or("null"),
+});
+
+/**
+ * Map a reviewer `source` to a Concern source. The scanners Infraweaver also runs
+ * (checkov / tflint / trivy / terraform-fmt / terraform-validate) keep their
+ * name, so re-running them reproduces the identical content id — those concerns
+ * are ✗→✓ verifiable. Everything else (tfsec — whose rule ids differ from
+ * trivy's — plus infracost, llm, …) collapses to `reviewer`: the original tool
+ * stays visible in `rule_id`, but Infraweaver can't reproduce the id, so
+ * `terraform_verify_remediation` will honestly report it unresolved.
+ *
+ * NB: trivy ✗→✓ verifiability assumes the reviewer's trivy `rule_id` equals
+ * Infraweaver's (both `trivy:<AVDID>`). That holds today (the reviewer's SARIF
+ * `ruleId` is the AVD id); if a future Trivy diverges SARIF ruleId from the
+ * JSON AVDID, trivy-source findings would stop matching on re-scan.
+ */
+function mapReviewerSource(source: string | undefined): Concern["source"] {
+  switch (source) {
+    case "checkov":
+    case "tflint":
+    case "trivy":
+    case "terraform-fmt":
+    case "terraform-validate":
+    // our own native pack: re-running a scan reproduces the identical id, so a
+    // findings.json that carries it back to us stays ✗→✓ verifiable.
+    case NATIVE_SOURCE:
+      return source;
+    default:
+      return "reviewer";
+  }
+}
+
+function mapReviewerCategory(
+  category: string | undefined,
+): Concern["category"] {
+  switch (category) {
+    case "security":
+      return "security";
+    case "style":
+      return "style";
+    case "cost":
+      return "cost";
+    default:
+      return "correctness";
+  }
+}
+
+/**
+ * Map a reviewer `findings.json` body into Concern[]. Drops `human_only`
+ * findings (out of scope — not auto-remediable). Paths are normalized to
+ * repo-relative POSIX (same as the scanners) so ids and grouping stay portable.
+ */
+export function parseReviewerFindings(json: string, cwd = ""): Concern[] {
+  const parsed = parseScannerJson(
+    ReviewerFindingsReport,
+    json,
+    "reviewer findings",
+  );
+  const out: Concern[] = [];
+  for (const f of parsed.findings ?? []) {
+    if (f.state === "human_only") continue;
+    const file = toRepoRelative(f.location?.file, cwd);
+    // Skip findings that don't point at a Terraform file — they aren't per-file
+    // remediable. In particular the reviewer's infracost/cost findings are keyed
+    // to a project *directory* (not a `.tf`), so they land here; cost is surfaced
+    // during remediation by `infracost_diff` (E1), not by editing a directory.
+    if (!isTerraformFile(file)) continue;
+    const line = f.location?.line ?? null;
+    const source = mapReviewerSource(f.source);
+    const ruleId = f.rule_id || "finding";
+    // Infraweaver's own parsers store `rule_id` namespaced (`${source}:${rule}`)
+    // but hash only the bare rule into the content id. Strip a matching
+    // `${source}:` prefix so a checkov/tflint/trivy/fmt finding from the reviewer
+    // reproduces the SAME id Infraweaver's own scan would — keeping it ✗→✓
+    // verifiable. `reviewer`-source findings keep the full rule_id in the hash
+    // (they aren't reproducible anyway). Both namespaced and bare inputs work.
+    const bareRule =
+      source !== "reviewer" && ruleId.startsWith(`${source}:`)
+        ? ruleId.slice(source.length + 1)
+        : ruleId;
+    out.push({
+      id: concernId(source, bareRule, file, line),
+      source,
+      rule_id: ruleId,
+      severity: lowerSeverity(f.severity),
+      category: mapReviewerCategory(f.category),
+      evidence: f.evidence || ruleId,
+      location: { file, line },
+      remediation_hint: f.remediation_hint ?? null,
+    });
+  }
+  return out;
+}
+
+// --- SARIF ingestion (read_findings) --------------------------------------
+
+const SarifLocation = type({
+  "physicalLocation?": {
+    "artifactLocation?": { "uri?": "string" },
+    "region?": { "startLine?": "number" },
+  },
+});
+const SarifSuppression = type({
+  kind: "'inSource' | 'external'",
+  "justification?": "string",
+});
+const SarifResult = type({
+  "ruleId?": "string",
+  "level?": "string",
+  "message?": { "text?": "string" },
+  "locations?": SarifLocation.array(),
+  "properties?": { "security-severity?": "string" },
+  "suppressions?": SarifSuppression.array(),
+});
+const SarifRule = type({
+  "id?": "string",
+  "helpUri?": "string",
+  "shortDescription?": { "text?": "string" },
+});
+const SarifRun = type({
+  "tool?": { "driver?": { "name?": "string", "rules?": SarifRule.array() } },
+  "results?": SarifResult.array(),
+});
+const SarifReport = type({
+  "version?": "string",
+  "$schema?": "string",
+  "runs?": SarifRun.array(),
+});
+// the same shapes serve the emit side (buildSarifReport) as plain types.
+type SarifReport = typeof SarifReport.infer;
+type SarifRule = typeof SarifRule.infer;
+type SarifResult = typeof SarifResult.infer;
+
+/** true when a parsed JSON object looks like a SARIF report (the standard
+ * scanner-output format) rather than a terraform-reviewer findings.json. */
+export function isSarif(parsed: unknown): boolean {
+  if (!parsed || typeof parsed !== "object") return false;
+  const o = parsed as Record<string, unknown>;
+  const schema = typeof o.$schema === "string" ? o.$schema.toLowerCase() : "";
+  return (
+    Array.isArray(o.runs) &&
+    (schema.includes("sarif") || typeof o.version === "string")
+  );
+}
+
+/** map a SARIF driver name to a Concern source (so a re-run reproduces the id
+ * for the scanners Infraweaver also runs; everything else → `reviewer`). */
+function mapSarifDriver(name: string | undefined): Concern["source"] {
+  switch ((name ?? "").toLowerCase()) {
+    case "trivy":
+      return "trivy";
+    case "checkov":
+      return "checkov";
+    case "tflint":
+      return "tflint";
+    // a SARIF report we emitted ourselves — the driver name IS the native source,
+    // so it round-trips as native rather than collapsing to `reviewer`.
+    case NATIVE_SOURCE:
+      return NATIVE_SOURCE;
+    default:
+      return "reviewer";
+  }
+}
+
+/** SARIF `level` → severity (a `security-severity` property refines it). */
+function sarifSeverity(
+  level: string | undefined,
+  securitySeverity: string | undefined,
+): Severity {
+  const score = securitySeverity
+    ? Number.parseFloat(securitySeverity)
+    : Number.NaN;
+  if (Number.isFinite(score) && score > 0) return severityFromCvss(score);
+  switch ((level ?? "").toLowerCase()) {
+    case "error":
+      return "high";
+    case "warning":
+      return "medium";
+    case "note":
+      return "low";
+    default:
+      return "info";
+  }
+}
+
+/**
+ * Parse a SARIF 2.1.0 report (the standard scanner-output format Trivy /
+ * Checkov / tflint all emit) into Concern[]. The driver name picks the source so
+ * a finding from a scanner Infraweaver re-runs reproduces the SAME content id
+ * (✗→✓ verifiable); other tools collapse to `reviewer`. Rule docs come from the
+ * matching `tool.driver.rules[].helpUri`. Non-Terraform files are dropped.
+ */
+export function parseSarifFindings(json: string, cwd = ""): Concern[] {
+  let report: SarifReport;
+  try {
+    report = parseScannerJson(SarifReport, json, "SARIF");
+  } catch {
+    return [];
+  }
+  const out: Concern[] = [];
+  for (const run of report.runs ?? []) {
+    const source = mapSarifDriver(run.tool?.driver?.name);
+    const ruleDocs = new Map<string, string>();
+    for (const rule of run.tool?.driver?.rules ?? []) {
+      if (rule.id && rule.helpUri) ruleDocs.set(rule.id, rule.helpUri);
+    }
+    for (const result of run.results ?? []) {
+      const loc = result.locations?.[0]?.physicalLocation;
+      const file = toRepoRelative(loc?.artifactLocation?.uri, cwd);
+      if (!isTerraformFile(file)) continue;
+      const start = loc?.region?.startLine;
+      const line = typeof start === "number" && start > 0 ? start : null;
+      const rawRule = result.ruleId || "finding";
+      // strip a `${source}:` prefix if a tool already namespaced it, so the
+      // content id matches Infraweaver's own scan of the same rule.
+      const bareRule =
+        source !== "reviewer" && rawRule.startsWith(`${source}:`)
+          ? rawRule.slice(source.length + 1)
+          : rawRule;
+      const ruleId = source === "reviewer" ? rawRule : `${source}:${bareRule}`;
+      out.push({
+        id: concernId(source, bareRule, file, line),
+        source,
+        rule_id: ruleId,
+        severity: sarifSeverity(
+          result.level,
+          result.properties?.["security-severity"],
+        ),
+        // a native rule declares its own category (the governance rules are
+        // `correctness`, not security) — keep it on the round-trip.
+        category:
+          source === "tflint"
+            ? "style"
+            : (nativeRuleOf(ruleId)?.category ?? "security"),
+        evidence: result.message?.text || ruleId,
+        location: { file, line },
+        remediation_hint: ruleDocs.get(rawRule) ?? null,
+      });
+    }
+  }
+  return out;
+}
+
+/** dispatch a findings file to the right parser: SARIF (standard scanner
+ * output) or a terraform-reviewer findings.json. */
+export function parseFindingsFile(json: string, cwd = ""): Concern[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json || "{}");
+  } catch {
+    return [];
+  }
+  return isSarif(parsed)
+    ? parseSarifFindings(json, cwd)
+    : parseReviewerFindings(json, cwd);
+}
+
+// --- SARIF emit (GitHub code-scanning) ------------------------------------
+
+/** Concern severity → SARIF `level`. SARIF has only error/warning/note, so
+ * critical+high collapse to `error`, medium → `warning`, low+info → `note`. The
+ * finer grade survives in the `security-severity` property below. */
+function severityToSarifLevel(s: Severity): "error" | "warning" | "note" {
+  switch (s) {
+    case "critical":
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    default:
+      return "note";
+  }
+}
+
+/** Concern severity → the numeric `security-severity` GitHub reads to colour the
+ * alert (0–10 CVSS-like scale). */
+function securitySeverityScore(s: Severity): string {
+  return cvssScoreForSeverity(s).toFixed(1);
+}
+
+/**
+ * Emit a set of concerns as a SARIF 2.1.0 report for GitHub code-scanning (the
+ * inverse of `parseSarifFindings` — close the loop so a Infraweaver scan can
+ * populate the repo's Security tab via `github/codeql-action/upload-sarif`). One
+ * `run` with the `infraweaver` driver, a deduped `rules` array (each rule's
+ * `helpUri` from `ruleDocUrl`), and one `result` per concern carrying its
+ * `level`, `security-severity`, message, and `file:line`. Pure + deterministic
+ * (rules sorted, stable partialFingerprints from the content id) so re-emitting
+ * an unchanged scan yields a byte-identical report.
+ */
+export function buildSarifReport(concerns: Concern[]): SarifReport {
+  // deduped rule metadata, keyed by the namespaced rule_id (the SARIF ruleId).
+  const rulesById = new Map<string, SarifRule>();
+  for (const c of concerns) {
+    if (rulesById.has(c.rule_id)) continue;
+    const helpUri = ruleDocUrl(c);
+    rulesById.set(c.rule_id, {
+      id: c.rule_id,
+      ...(helpUri ? { helpUri } : {}),
+      // LLM02: evidence is repo-derived and can carry a secret — redact before it
+      // reaches SARIF (uploaded to GitHub Code Scanning, a durable artifact).
+      shortDescription: { text: redactSecrets(c.evidence).slice(0, 200) },
+    });
+  }
+  const rules = [...rulesById.values()].sort((a, b) =>
+    (a.id ?? "").localeCompare(b.id ?? ""),
+  );
+  const results: SarifResult[] = concerns.map((c) => ({
+    ruleId: c.rule_id,
+    level: severityToSarifLevel(c.severity),
+    message: { text: redactSecrets(c.evidence) },
+    properties: { "security-severity": securitySeverityScore(c.severity) },
+    ...(c.suppression
+      ? {
+          suppressions: [
+            {
+              kind:
+                c.suppression.source === "inline"
+                  ? ("inSource" as const)
+                  : ("external" as const),
+              justification: redactSecrets(c.suppression.reason),
+            },
+          ],
+        }
+      : {}),
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: c.location.file },
+          ...(c.location.line
+            ? { region: { startLine: c.location.line } }
+            : {}),
+        },
+      },
+    ],
+  }));
+  return {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [{ tool: { driver: { name: TOOL_NAME, rules } }, results }],
+  };
+}

package/src/mcp/terraform/fixMemory.ts

@@ -0,0 +1,253 @@
+/**
+ * Reusable proven-fix memory (§5.12) — "deterministic where safe, proven every time".
+ *
+ * When a remediation passes the `✗→✓` proof (`terraform_verify_remediation`), the
+ * finding-TYPE that was fixed (its `source|bareRule` shape, plus the cross-scanner
+ * `canonical_class`) and the guidance that fixed it are captured as a *pattern*.
+ * On a later run — the SAME repo, or any repo in the fleet via Cloud — when a
+ * finding of that type appears, the pattern is offered to the fixer as a proven
+ * starting point.
+ *
+ * The moat is untouched: a pattern is a PRIOR, never an action. The fixer still
+ * edits this repo's own resources and the run STILL re-scans `✗→✓` per target
+ * before any PR — a pattern is never blind-applied. This module is the pure core
+ * (identity, capture, merge, match, (de)serialize); the file read lives in
+ * `loadFixMemory` and everything else is unit-testable.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { FIX_MEMORY_FILE } from "#app/brand";
+import { bareRuleOf, type Concern } from "#app/mcp/terraform/types";
+
+export const FIX_MEMORY_FILENAME = FIX_MEMORY_FILE;
+
+/** Keep the wire + local file bounded — a pattern is a hint, not the whole file. */
+const MAX_DESCRIPTION = 400;
+const MAX_BEFORE_EXAMPLE = 1200;
+
+/**
+ * A proven-fix pattern. Freshly CAPTURED patterns carry only the identity +
+ * guidance (no stats); LIBRARY entries (loaded from Cloud / a local file) also
+ * carry the reuse stats and the operator `disabled` flag. The finding-TYPE key
+ * (`finding_type`) is file-independent on purpose — the whole point is to reuse
+ * across files and repos.
+ */
+export interface ProvenFixPattern {
+  /** the finding-TYPE shape: `source|bareRule` (file-independent). The match key. */
+  finding_type: string;
+  /** producing scanner, when known (null for reviewer-loaded concerns). */
+  source: string | null;
+  /** cross-scanner canonical class (e.g. "aws-s3-encryption"), when recognised. */
+  canonical_class: string | null;
+  category: string;
+  /** human label — the namespaced rule id (e.g. "trivy:AVD-AWS-0088"). */
+  title: string;
+  /** the scanner's "what is wrong" message, trimmed + capped. */
+  description: string | null;
+  /** the remediation guidance that proved out (trivy Resolution / fmt hint / …). */
+  remediation_hint: string | null;
+  /** a representative BEFORE snippet from the repo the pattern was proven on —
+   *  a concrete example for the fixer to adapt, never a patch to apply verbatim. */
+  before_example: string | null;
+  // ── stats (library entries only; absent on fresh captures) ──
+  /** how many times this type went `✗→✓` (across the fleet, from Cloud). */
+  times_proven?: number;
+  /** distinct repos it's been proven on. */
+  repos_count?: number;
+  /** ISO timestamp of the most recent proof. */
+  last_proven?: string;
+  /** operator retired this pattern in the dashboard — never offered to the fixer. */
+  disabled?: boolean;
+}
+
+/** The finding-TYPE identity: `source|bareRule`, file-independent (unlike
+ *  `concernKeyOf`, which folds in the file). Two instances of the same rule in
+ *  different files/repos share this key — the reuse unit. */
+export function findingTypeOf(c: Pick<Concern, "source" | "rule_id">): string {
+  return `${c.source}|${bareRuleOf(c.source, c.rule_id)}`;
+}
+
+function cap(text: string | null | undefined, max: number): string | null {
+  const trimmed = text?.trim();
+  if (!trimmed) return null;
+  return trimmed.length > max ? `${trimmed.slice(0, max - 1)}…` : trimmed;
+}
+
+/** Re-apply the size caps to a pattern from an UNTRUSTED source (a committed
+ *  local file or the Cloud library blob) — captures are already capped, but a
+ *  hand-edited/garbage file must not bloat the fixer prompt with an unbounded
+ *  before-example. Pure. */
+function capPattern(p: ProvenFixPattern): ProvenFixPattern {
+  return {
+    ...p,
+    description: cap(p.description, MAX_DESCRIPTION),
+    remediation_hint: cap(p.remediation_hint, MAX_DESCRIPTION),
+    before_example: cap(p.before_example, MAX_BEFORE_EXAMPLE),
+  };
+}
+
+/** Build a fresh pattern from a concern that just proved out `✗→✓`. Pure. */
+export function captureProvenFix(c: Concern): ProvenFixPattern {
+  return {
+    finding_type: findingTypeOf(c),
+    source: c.source,
+    canonical_class: c.canonical_class ?? null,
+    category: c.category,
+    title: c.rule_id,
+    description: cap(c.evidence, MAX_DESCRIPTION),
+    remediation_hint: cap(c.remediation_hint, MAX_DESCRIPTION),
+    before_example: cap(c.code_snippet, MAX_BEFORE_EXAMPLE),
+  };
+}
+
+/**
+ * De-duplicate a run's captures to one pattern per finding-type. When the same
+ * type is proven on several concerns this run, keep the FIRST that carries a
+ * before-example (a concrete example beats none), else the first seen — the
+ * order is otherwise stable so the wire is deterministic.
+ */
+export function dedupeCaptures(
+  captures: ProvenFixPattern[],
+): ProvenFixPattern[] {
+  const byType = new Map<string, ProvenFixPattern>();
+  for (const p of captures) {
+    const existing = byType.get(p.finding_type);
+    if (!existing) {
+      byType.set(p.finding_type, p);
+    } else if (!existing.before_example && p.before_example) {
+      byType.set(p.finding_type, p);
+    }
+  }
+  return [...byType.values()];
+}
+
+/**
+ * Match a loaded library against the CURRENT scan's concerns: return the patterns
+ * whose finding-type is present in this scan (deduped, `disabled` excluded),
+ * newest-proven first, capped. This is what the fixer is offered — a proven prior
+ * for the exact finding-types it's about to fix. Pure.
+ */
+export function matchPatternsForConcerns(
+  library: ProvenFixPattern[],
+  concerns: Pick<Concern, "source" | "rule_id">[],
+  max = 25,
+): ProvenFixPattern[] {
+  const present = new Set(concerns.map(findingTypeOf));
+  const seen = new Set<string>();
+  const matched = library.filter((p) => {
+    if (p.disabled) return false;
+    if (!present.has(p.finding_type)) return false;
+    if (seen.has(p.finding_type)) return false;
+    seen.add(p.finding_type);
+    return true;
+  });
+  matched.sort((a, b) =>
+    (b.last_proven ?? "").localeCompare(a.last_proven ?? ""),
+  );
+  return matched.slice(0, max);
+}
+
+export interface FixMemoryFile {
+  version: 1;
+  /** ISO timestamp of the last write (informational). */
+  updated?: string;
+  patterns: ProvenFixPattern[];
+}
+
+/**
+ * Merge freshly-captured patterns into a local library, keyed by finding-type:
+ * bump `times_proven`, advance `last_proven`, and prefer a non-empty
+ * before-example/hint over an empty one. The local file is single-repo memory
+ * (the fleet count lives in Cloud), so `repos_count` stays 1 here. Pure.
+ */
+export function mergeFixMemory(
+  existing: ProvenFixPattern[],
+  captured: ProvenFixPattern[],
+  provenAt: string,
+): ProvenFixPattern[] {
+  const byType = new Map<string, ProvenFixPattern>();
+  for (const p of existing) byType.set(p.finding_type, { ...p });
+  for (const cap of dedupeCaptures(captured)) {
+    const prior = byType.get(cap.finding_type);
+    if (!prior) {
+      byType.set(cap.finding_type, {
+        ...cap,
+        times_proven: 1,
+        repos_count: 1,
+        last_proven: provenAt,
+      });
+      continue;
+    }
+    byType.set(cap.finding_type, {
+      ...prior,
+      // refresh the guidance/example from the newest proof when it has richer content.
+      description: cap.description ?? prior.description,
+      remediation_hint: cap.remediation_hint ?? prior.remediation_hint,
+      before_example: cap.before_example ?? prior.before_example,
+      canonical_class: cap.canonical_class ?? prior.canonical_class,
+      times_proven: (prior.times_proven ?? 0) + 1,
+      repos_count: prior.repos_count ?? 1,
+      last_proven: provenAt,
+      // a locally-retired pattern stays retired even after a fresh local proof.
+      ...(prior.disabled ? { disabled: true } : {}),
+    });
+  }
+  return [...byType.values()].sort((a, b) =>
+    (b.last_proven ?? "").localeCompare(a.last_proven ?? ""),
+  );
+}
+
+export function serializeFixMemory(
+  patterns: ProvenFixPattern[],
+  updated: string,
+): FixMemoryFile {
+  return { version: 1, updated, patterns };
+}
+
+/** Parse fix-memory JSON into a pattern list; tolerant of a malformed/old file (→ null). */
+export function parseFixMemory(raw: string): ProvenFixPattern[] | null {
+  let doc: unknown;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object") return null;
+  const patterns = (doc as { patterns?: unknown }).patterns;
+  if (!Array.isArray(patterns)) return null;
+  return patterns.filter(isProvenFixPattern).map(capPattern);
+}
+
+/** Structural guard for one untrusted pattern (from a file or the Cloud library). */
+export function isProvenFixPattern(value: unknown): value is ProvenFixPattern {
+  if (!value || typeof value !== "object") return false;
+  const p = value as Record<string, unknown>;
+  return (
+    typeof p.finding_type === "string" &&
+    p.finding_type.length > 0 &&
+    typeof p.title === "string" &&
+    typeof p.category === "string"
+  );
+}
+
+/** Load `.infraweaver.fix-memory.json` under `cwd`; [] when absent/unreadable/malformed. */
+export function loadFixMemory(cwd: string | undefined): ProvenFixPattern[] {
+  const root = cwd ?? process.cwd();
+  let raw: string;
+  try {
+    raw = readFileSync(join(root, FIX_MEMORY_FILENAME), "utf-8");
+  } catch {
+    return [];
+  }
+  return parseFixMemory(raw) ?? [];
+}
+
+/**
+ * Coerce an untrusted library payload (the Cloud run-context `provenFixes` blob)
+ * into typed patterns, keeping only structurally-valid, non-disabled entries.
+ * Pure — the wire boundary can't be typechecked across repos.
+ */
+export function coerceLibrary(raw: unknown): ProvenFixPattern[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(isProvenFixPattern).map(capPattern);
+}