infraweaver 0.1.0

package/src/mcp/terraform/registry.ts

@@ -0,0 +1,317 @@
+/**
+ * Registry module intelligence — look up a PUBLISHED module's interface and
+ * search the public registry for modules to reuse.
+ *
+ * Complements `./currency.ts` (which answers "is a newer VERSION available?"):
+ * this answers "what does this module EXPECT and EXPOSE?" (root inputs/outputs)
+ * and "what published modules exist for this need?". It exists so the agent can
+ * wire a `module {}` block against a real, published interface — an organisation's
+ * own published modules included — instead of guessing variable names.
+ *
+ * Read-only, public default registry only (private/TFE hosts are rejected, same
+ * scope as the currency check), and degrades green on every failure.
+ */
+
+import {
+  DEFAULT_REGISTRY_BASE_URL,
+  fetchRegistryJson,
+  isRecord,
+  type LookupStatus,
+} from "#app/mcp/terraform/currency";
+
+const SEARCH_LIMIT_DEFAULT = 10;
+const SEARCH_LIMIT_MAX = 25;
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function asNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+// --- module detail (interface lookup) ---------------------------------------
+
+export interface ModuleInput {
+  name: string;
+  type: string | null;
+  description: string | null;
+  default: string | null;
+  required: boolean;
+}
+
+export interface ModuleOutput {
+  name: string;
+  description: string | null;
+}
+
+export interface ModuleDetail {
+  source: string;
+  version: string | null;
+  description: string | null;
+  verified: boolean;
+  downloads: number | null;
+  published_at: string | null;
+  provider_dependencies: string[];
+  inputs: ModuleInput[];
+  outputs: ModuleOutput[];
+}
+
+function parseInputs(root: unknown): ModuleInput[] {
+  if (!isRecord(root) || !Array.isArray(root.inputs)) return [];
+  const out: ModuleInput[] = [];
+  for (const raw of root.inputs) {
+    if (!isRecord(raw) || typeof raw.name !== "string") continue;
+    const fallback = asString(raw.default);
+    out.push({
+      name: raw.name,
+      type: asString(raw.type),
+      description: asString(raw.description),
+      default: fallback,
+      // the registry sometimes carries an explicit `required` boolean; when it
+      // doesn't, a variable with no default is required.
+      required: typeof raw.required === "boolean" ? raw.required : fallback === null,
+    });
+  }
+  return out;
+}
+
+function parseOutputs(root: unknown): ModuleOutput[] {
+  if (!isRecord(root) || !Array.isArray(root.outputs)) return [];
+  const out: ModuleOutput[] = [];
+  for (const raw of root.outputs) {
+    if (!isRecord(raw) || typeof raw.name !== "string") continue;
+    out.push({ name: raw.name, description: asString(raw.description) });
+  }
+  return out;
+}
+
+function parseProviderDependencies(root: unknown): string[] {
+  if (!isRecord(root) || !Array.isArray(root.provider_dependencies)) return [];
+  const out: string[] = [];
+  for (const raw of root.provider_dependencies) {
+    if (!isRecord(raw)) continue;
+    const name = asString(raw.name);
+    if (name === null) continue;
+    const namespace = asString(raw.namespace);
+    out.push(namespace ? `${namespace}/${name}` : name);
+  }
+  return out;
+}
+
+function parseModuleDetail(body: unknown): ModuleDetail | null {
+  if (!isRecord(body)) return null;
+  const source = asString(body.source) ?? asString(body.id);
+  if (source === null) return null;
+  const root = body.root;
+  return {
+    source,
+    version: asString(body.version),
+    description: asString(body.description),
+    verified: body.verified === true,
+    downloads: asNumber(body.downloads),
+    published_at: asString(body.published_at),
+    provider_dependencies: parseProviderDependencies(root),
+    inputs: parseInputs(root),
+    outputs: parseOutputs(root),
+  };
+}
+
+// --- registry resolution (public vs private host) ---------------------------
+
+/** the default public registry host — a bare `namespace/name/provider` (or a
+ * `registry.terraform.io/`-prefixed source) resolves here with no auth. */
+export const PUBLIC_REGISTRY_HOST = "registry.terraform.io";
+
+/** a module lookup's outcome: the shared `LookupStatus` plus two private-registry
+ * policy outcomes the tool surfaces with their own message. */
+export type ModuleLookupStatus = LookupStatus | "host_not_allowed" | "auth_required";
+
+/**
+ * Split a module source into its optional registry `host` and the
+ * `namespace/name/provider` path. A host-prefixed source
+ * (`app.terraform.io/acme/vpc/aws`) targets a PRIVATE registry; a bare
+ * `namespace/name/provider` targets the public default registry (host === null).
+ * `path` is null when the source isn't a valid module address (the detected host,
+ * if any, is still returned for the caller's error message).
+ */
+export function splitModuleAddress(source: string): { host: string | null; path: string | null } {
+  const segments = source.split("/").filter(Boolean);
+  const first = segments[0];
+  const host = first?.includes(".") ? first.toLowerCase() : null;
+  if (segments.length === 4 && host !== null) {
+    return { host, path: segments.slice(1).join("/") };
+  }
+  if (segments.length === 3) return { host: null, path: segments.join("/") };
+  return { host, path: null };
+}
+
+export interface PrivateRegistryAuth {
+  /** the host(s) `token` authorises — a private source's host must be one of them.
+   * This is the security boundary: the agent names the source, but we only ever
+   * send the token to a host the operator allow-listed via `registry_host`. */
+  allowedHosts: string[];
+  /** the bearer token, or undefined when the run supplied no `registry_token`. */
+  token: string | undefined;
+}
+
+/** discovered `modules.v1` API base per private host (a run hits the same registry
+ * repeatedly). Successful resolutions only — a transient failure must not poison
+ * the run. Cleared between tests via `_clearModuleDiscoveryCache`. */
+const discoveryCache = new Map<string, string>();
+
+/** test seam: drop the per-host discovery cache. */
+export function _clearModuleDiscoveryCache(): void {
+  discoveryCache.clear();
+}
+
+/**
+ * Resolve a private registry's module API base via the standard service-discovery
+ * document (`GET https://<host>/.well-known/terraform.json` → its `modules.v1`
+ * entry). This is how Terraform itself finds the API, so it works for HCP Terraform,
+ * Terraform Enterprise, and any protocol-compliant registry regardless of the path
+ * they mount it at. Returns null when discovery fails or the host advertises no
+ * module API.
+ */
+async function discoverModulesV1Base(host: string, token: string): Promise<string | null> {
+  const cached = discoveryCache.get(host);
+  if (cached !== undefined) return cached;
+  const { status, body } = await fetchRegistryJson(`https://${host}/.well-known/terraform.json`, {
+    Authorization: `Bearer ${token}`,
+  });
+  if (status !== "ok" || !isRecord(body) || typeof body["modules.v1"] !== "string") return null;
+  const modulesPath = body["modules.v1"].replace(/\/$/, "");
+  const base = modulesPath.startsWith("http") ? modulesPath : `https://${host}${modulesPath}`;
+  discoveryCache.set(host, base);
+  return base;
+}
+
+/** fetch + parse a module's detail from an already-resolved API base
+ * (`…/v1/modules` for the public registry, the discovered `modules.v1` for a
+ * private one). `token`, when present, authenticates the private call. */
+async function fetchModuleDetailFrom(
+  base: string,
+  path: string,
+  opts: { version?: string | undefined; token?: string | undefined },
+): Promise<{ status: LookupStatus; module: ModuleDetail | null }> {
+  const suffix = opts.version ? `/${encodeURIComponent(opts.version)}` : "";
+  const headers = opts.token ? { Authorization: `Bearer ${opts.token}` } : undefined;
+  const { status, body } = await fetchRegistryJson(`${base}/${path}${suffix}`, headers);
+  if (status !== "ok") return { status, module: null };
+  const module = parseModuleDetail(body);
+  if (module === null) return { status: "error", module: null };
+  return { status: "ok", module };
+}
+
+/**
+ * Look up a published module's interface. A bare `namespace/name/provider` hits
+ * the public default registry (no auth). A host-prefixed `host/namespace/name/
+ * provider` targets a PRIVATE registry (HCP Terraform / Terraform Enterprise / any
+ * protocol-compliant registry): the host must be in `auth.allowedHosts` AND a token
+ * supplied, then the API base is resolved via service discovery and the detail
+ * fetched with `Authorization: Bearer …`. Pass `version` to pin the lookup; omit it
+ * for the latest.
+ */
+export async function fetchModuleDetail(
+  source: string,
+  opts: {
+    version?: string | undefined;
+    auth?: PrivateRegistryAuth | undefined;
+    /** public-base override (tests). */
+    baseUrl?: string;
+  } = {},
+): Promise<{ status: ModuleLookupStatus; module: ModuleDetail | null }> {
+  const { host, path } = splitModuleAddress(source);
+  if (path === null) return { status: "unsupported_source", module: null };
+
+  // public default registry — no auth.
+  if (host === null || host === PUBLIC_REGISTRY_HOST) {
+    const base = `${opts.baseUrl ?? DEFAULT_REGISTRY_BASE_URL}/v1/modules`;
+    return fetchModuleDetailFrom(base, path, { version: opts.version });
+  }
+
+  // private registry — the host must be operator-authorised AND a token supplied.
+  if (!opts.auth?.allowedHosts.includes(host)) {
+    return { status: "host_not_allowed", module: null };
+  }
+  if (!opts.auth.token) return { status: "auth_required", module: null };
+  const modulesBase = await discoverModulesV1Base(host, opts.auth.token);
+  if (modulesBase === null) return { status: "error", module: null };
+  return fetchModuleDetailFrom(modulesBase, path, {
+    version: opts.version,
+    token: opts.auth.token,
+  });
+}
+
+// --- module search (discovery) ----------------------------------------------
+
+export interface ModuleSearchResult {
+  address: string;
+  version: string | null;
+  description: string | null;
+  downloads: number | null;
+  verified: boolean;
+}
+
+export interface ModuleSearchQuery {
+  query: string;
+  namespace?: string | undefined;
+  provider?: string | undefined;
+  verified?: boolean | undefined;
+  limit?: number | undefined;
+}
+
+/** build the `namespace/name/provider` address callers feed back into
+ * fetchModuleDetail, falling back to the raw (version-suffixed) id. */
+function searchResultAddress(raw: Record<string, unknown>): string | null {
+  const namespace = asString(raw.namespace);
+  const name = asString(raw.name);
+  const provider = asString(raw.provider);
+  if (namespace && name && provider) return `${namespace}/${name}/${provider}`;
+  return asString(raw.id);
+}
+
+function parseSearchResults(body: unknown): ModuleSearchResult[] | null {
+  if (!isRecord(body) || !Array.isArray(body.modules)) return null;
+  const out: ModuleSearchResult[] = [];
+  for (const raw of body.modules) {
+    if (!isRecord(raw)) continue;
+    const address = searchResultAddress(raw);
+    if (address === null) continue;
+    out.push({
+      address,
+      version: asString(raw.version),
+      description: asString(raw.description),
+      downloads: asNumber(raw.downloads),
+      verified: raw.verified === true,
+    });
+  }
+  return out;
+}
+
+/**
+ * GET /v1/modules/search — discover published modules (the organisation's own
+ * namespace included) to REUSE instead of writing raw resources. Public default
+ * registry only. `limit` is clamped to a small range to keep the result tight.
+ */
+export async function searchRegistryModules(
+  params: ModuleSearchQuery,
+  opts: { baseUrl?: string } = {},
+): Promise<{ status: LookupStatus; modules: ModuleSearchResult[]; limit: number }> {
+  const base = opts.baseUrl ?? DEFAULT_REGISTRY_BASE_URL;
+  const limit = Math.min(
+    Math.max(1, Math.trunc(params.limit ?? SEARCH_LIMIT_DEFAULT)),
+    SEARCH_LIMIT_MAX,
+  );
+  const url = new URL(`${base}/v1/modules/search`);
+  url.searchParams.set("q", params.query);
+  url.searchParams.set("limit", String(limit));
+  if (params.namespace) url.searchParams.set("namespace", params.namespace);
+  if (params.provider) url.searchParams.set("provider", params.provider);
+  if (params.verified) url.searchParams.set("verified", "true");
+  const { status, body } = await fetchRegistryJson(url.toString());
+  if (status !== "ok") return { status, modules: [], limit };
+  const modules = parseSearchResults(body);
+  if (modules === null) return { status: "error", modules: [], limit };
+  return { status: "ok", modules, limit };
+}

package/src/mcp/terraform/risk.ts

@@ -0,0 +1,99 @@
+import { classifyRefusal } from "#app/mcp/terraform/decisions";
+import {
+  applyNoisePenalty,
+  EMPTY_NOISE_PROFILE,
+  explainNoiseAdjustment,
+  type NoiseAdjustment,
+  type NoiseProfile,
+  noiseAdjustmentFor,
+} from "#app/mcp/terraform/noiseProfile";
+import { type Concern, cvssScoreForSeverity } from "#app/mcp/terraform/types";
+
+const EXPOSURE_SIGNAL =
+  /(0\.0\.0\.0\/0|::\/0|\bpublic(ly)?\b|\binternet\b|\bingress\b|\bunrestricted\b|world[-\s]?readable|\banonymous\b|\bexposed?\b)/i;
+
+export interface RiskFactors {
+  severity: number;
+  exposure: number;
+  fixability: number;
+  /** G7: the fleet-noise down-rank applied, as a NEGATIVE contribution. Present
+   *  only when one applied, so a reader can always reconstruct the score from
+   *  its parts and see that nothing was adjusted invisibly. */
+  noise?: number;
+}
+
+export interface RiskScore {
+  score: number;
+  factors: RiskFactors;
+  /** the dismissal history behind `factors.noise`, when there is one. */
+  noise?: NoiseAdjustment;
+}
+
+/**
+ * Score a concern for SURFACING order.
+ *
+ * `profile` is the org's fleet-wide dismissal record (G7). It can only ever
+ * lower a score, is bounded and floored, and never applies to critical/high —
+ * see `noiseProfile.ts` for why a ranking model in an evidence product is
+ * allowed to reorder and nothing else. Defaults to empty, so every existing
+ * caller keeps the exact scores it had.
+ */
+export function scoreConcern(concern: Concern, profile: NoiseProfile = EMPTY_NOISE_PROFILE): RiskScore {
+  const severity = cvssScoreForSeverity(concern.severity);
+  const exposed = EXPOSURE_SIGNAL.test(`${concern.rule_id} ${concern.evidence}`);
+  const exposure = concern.category === "security" && exposed ? 1.5 : 0;
+  const fixability = classifyRefusal(concern).refuse ? 0 : 0.5;
+  const raw = severity + exposure + fixability;
+  const base = Math.min(10, Math.round(raw * 10) / 10);
+
+  const adjustment = noiseAdjustmentFor(concern, profile);
+  if (!adjustment) return { score: base, factors: { severity, exposure, fixability } };
+  const score = applyNoisePenalty(base, adjustment);
+  return {
+    score,
+    // report the penalty ACTUALLY applied (the floor may have absorbed part of
+    // it), so `severity + exposure + fixability + noise` reconstructs `score`.
+    factors: { severity, exposure, fixability, noise: Math.round((score - base) * 10) / 10 },
+    noise: adjustment,
+  };
+}
+
+export function riskScore(concern: Concern, profile: NoiseProfile = EMPTY_NOISE_PROFILE): number {
+  return scoreConcern(concern, profile).score;
+}
+
+export interface RankedConcern {
+  concern_id: string;
+  rule_id: string;
+  severity: Concern["severity"];
+  category: Concern["category"];
+  location: Concern["location"];
+  risk_score: number;
+  risk_factors: RiskFactors;
+  /** G7: why this was ranked lower, in the org's own words. Present only when a
+   *  down-rank applied — an unexplained demotion is indistinguishable from a bug. */
+  noise_reason?: string;
+}
+
+export function topRisks(
+  concerns: Concern[],
+  n = 5,
+  profile: NoiseProfile = EMPTY_NOISE_PROFILE,
+): RankedConcern[] {
+  return concerns
+    .map((c) => ({ concern: c, risk: scoreConcern(c, profile) }))
+    .sort((a, b) => b.risk.score - a.risk.score || a.concern.id.localeCompare(b.concern.id))
+    .slice(0, n)
+    .map(({ concern, risk }) => ({
+      concern_id: concern.id,
+      rule_id: concern.rule_id,
+      severity: concern.severity,
+      category: concern.category,
+      location: concern.location,
+      risk_score: risk.score,
+      risk_factors: risk.factors,
+      // conditional spread, not `noise_reason: undefined` —
+      // `exactOptionalPropertyTypes` treats an explicit undefined as a value.
+      ...(risk.noise ? { noise_reason: explainNoiseAdjustment(risk.noise) } : {}),
+    }));
+}

package/src/mcp/terraform/scanSession.ts

@@ -0,0 +1,242 @@
+import type { ProvenFixPattern } from "#app/mcp/terraform/fixMemory";
+import type { IdleFloorReport } from "#app/mcp/terraform/idleFloor";
+import type { NoiseProfile } from "#app/mcp/terraform/noiseProfile";
+import type { DriftEvidenceStatement } from "#app/mcp/terraform/planDrift";
+import {
+  buildUpgradeStatement,
+  type ProvenTransform,
+  type TransformMatch,
+  type UpgradeEvidenceStatement,
+  type UpgradeIntent,
+} from "#app/mcp/terraform/transformPacks";
+import type { Concern } from "#app/mcp/terraform/types";
+
+/**
+ * The terraform tool-to-tool session: the explicit, typed channel the terraform
+ * MCP tools use to hand results to one another (and to end-of-run reporting)
+ * across separate, agent-mediated invocations.
+ *
+ * This used to be ~11 loose fields on the 69-field `ToolState` god-bag, where
+ * the coupling was invisible in every signature and the ordering was silently
+ * load-bearing. Naming the channel makes the contract greppable and testable:
+ *
+ *   - `terraform_scan` / `terraform_assess` / `read_findings` POPULATE the
+ *     baseline (`baselineConcernIds` / `baselineConcernKeys` /
+ *     `baselineFmtDriftFiles`) and the acted-on set (`lastScanConcerns`).
+ *   - `terraform_plan` POPULATES `plannedDestroy` + the confidence signals
+ *     (`lastBlastTier`, `lastIdempotent`); `infracost_diff` populates
+ *     `lastCostDirection`; `terraform_emit_sarif` sets `emittedSarifPath`;
+ *     the refactor equivalence check sets `refactorEquivalence` and
+ *     `terraform_emit_evidence` sets `refactorProposedUnproven`.
+ *   - `terraform_verify_remediation` CONSUMES the baseline + confidence signals;
+ *     `terraform_validate` consumes `baselineFmtDriftFiles`; the push guardrails
+ *     consume `plannedDestroy` / `refactorEquivalence`; end-of-run reporting
+ *     (`runLifecycle`, `cloudReport`) consumes `lastScanConcerns` /
+ *     `emittedSarifPath` / the refactor markers.
+ *
+ * Every field is still LITERAL (records a thing that happened) and every
+ * consumer degrades gracefully when its producer didn't run this session
+ * (`undefined`), so the ordering is documented here rather than assumed.
+ * Reach it through {@link scanSessionOf} so a partially-constructed `ToolState`
+ * (chiefly in tests) lazily gets a session rather than throwing.
+ */
+export interface ScanSession {
+  // full pre-fix scan id set (the deduped union of every scanner's concern ids,
+  // unfiltered by severity), captured by terraform_scan. read by
+  // terraform_verify_remediation to compute regressions = current −
+  // baseline (concern ids the fix INTRODUCED). undefined until the first scan.
+  baselineConcernIds?: string[];
+  // enterprise-integrity — the LINE-INDEPENDENT keys (concernKeyOf) of the
+  // same full pre-fix baseline. terraform_verify_remediation diffs on these, not
+  // raw ids, so a fix that SHIFTS lines (almost every fix) can't make an unfixed
+  // concern look resolved nor a pre-existing one look like a regression. Set
+  // alongside baselineConcernIds by terraform_scan / read_findings.
+  baselineConcernKeys?: string[];
+  // files that already failed `terraform fmt -check` at the pre-fix baseline
+  // scan (before any edit). read by terraform_validate so PRE-EXISTING style
+  // drift the run didn't introduce never gates `passed` — a scoped remediation
+  // must not reformat unrelated lines just to clear drift the file already had.
+  // Set alongside baselineConcernIds by terraform_scan / read_findings;
+  // undefined until the first scan (validate then falls back to gating on all
+  // drift, preserving pre-change behaviour outside the remediation flow).
+  baselineFmtDriftFiles?: string[];
+  // the most recent terraform_scan's reported concern set (post scope/severity
+  // filtering — what the run acted on). read at end-of-run by
+  // finalizeSuccessRun to emit the SARIF artifact + findings-count output, and
+  // by cloudReport to build the dashboard report. undefined until a scan ran;
+  // [] means the scan came back clean.
+  lastScanConcerns?: Concern[];
+  // destructive resources the most recent terraform_plan reported, partitioned
+  // into stateful (data-bearing, high-risk) and ephemeral. set by
+  // terraform_plan; read by the destroy-block guardrail (mcp/guardrails.ts) at
+  // push time so a fix that would delete/replace a datastore is blocked on the
+  // plan's evidence rather than the agent's self-report.
+  plannedDestroy?: {
+    stateful: { address: string; action: string; type: string }[];
+    ephemeral: { address: string; action: string; type: string }[];
+  };
+  // verification signals the confidence label aggregates, each recorded
+  // by the tool that produced it: terraform_plan sets blastTier + idempotent
+  // (undefined when no plan ran), infracost_diff sets costDirection. read by
+  // terraform_verify_remediation's computeConfidence so the PR's confidence is
+  // computed from real evidence, not the agent's word.
+  lastBlastTier?: "low" | "medium" | "high";
+  lastIdempotent?: boolean;
+  lastCostDirection?: "increase" | "decrease" | "no-change" | "unknown";
+  // the credential-free idle-floor report from terraform_emit_cost (§5.19). set
+  // by that tool; read by the evidence builder so the signed bundle carries the
+  // SAME numbers the cost.md artifact shows, computed once.
+  lastIdleFloor?: IdleFloorReport | undefined;
+  // the drift statement from the most recent detect_plan_drift (TC-2.1). set by
+  // that tool; read by terraform_emit_evidence so drift — including the
+  // `forgotten` blind-spot list and every coverage gap — enters the SIGNED
+  // bundle instead of dying as a run verdict. undefined until drift ran.
+  lastDrift?: DriftEvidenceStatement | undefined;
+  // absolute path of a SARIF file the agent wrote via terraform_emit_sarif.
+  // set by that tool on a successful write. read by finalizeSuccessRun's
+  // findings-output step so the end-of-run safety-net emit does NOT clobber an
+  // agent-emitted report (which may use a lower threshold / custom path) — it
+  // points findings-sarif-path at this file instead of rewriting.
+  emittedSarifPath?: string;
+  // the most recent terraform_equivalence_check verdict (the keys-free refactor
+  // EQUIVALENCE proof). set by that tool; read by the assertRefactorEquivalence
+  // push guardrail (mcp/guardrails.ts) so a refactor whose equivalence couldn't
+  // be proven — most dangerously, an UNCOVERED `moved {}` block, which would
+  // silently destroy/recreate live resources — is hard-blocked at push time on
+  // the proof's evidence, never the agent's self-report. undefined until the
+  // equivalence check runs, so it only ever gates an actual refactor flow.
+  refactorEquivalence?: {
+    equivalent: boolean;
+    // the keys-free sub-results, recorded so terraform_emit_evidence can render
+    // the equivalence statement with the proof that backs each claim (§8).
+    resource_set_equivalent: boolean;
+    arg_names_equivalent: boolean;
+    moves_exhaustive: boolean;
+    moves_detected: number;
+    validate_passed: boolean;
+    fmt_clean: boolean;
+    uncovered_moves: { from: string; to: string }[];
+    reasons: string[];
+  };
+  // set by terraform_emit_evidence when it records a b.4 third-party-module
+  // adoption shipped WITHOUT a plan (the `proposed — unproven` marker). read by
+  // the Cloud report (cloudReport.ts) so the dashboard shows that unmissable
+  // marker rather than implying a proof. An actual equivalence proof
+  // (refactorEquivalence) always takes precedence over this flag.
+  refactorProposedUnproven?: boolean;
+  // §5.12 proven-fix memory — the library of proven-fix patterns loaded at run
+  // start (local `.infraweaver.fix-memory.json` ∪ the org's Cloud library), read by
+  // the terraform_fix_memory tool to offer the fixer a proven prior for the
+  // finding-types in the current scan. undefined until loaded; [] = none known.
+  fixMemoryLibrary?: ProvenFixPattern[];
+  // G7 the org's fleet-wide dismissal record, coerced at run start from the Cloud
+  // run-context. Read by `terraform_scan` to DOWN-RANK finding types this org has
+  // repeatedly waived. Surfacing only — it can never suppress a finding, change a
+  // severity or verdict, or touch the signed evidence (see `noiseProfile`).
+  // undefined until loaded; an empty map = nothing learned.
+  noiseProfile?: NoiseProfile;
+  // §5.12 — patterns CAPTURED this run: each is a finding-type that went ✗→✓ via
+  // terraform_verify_remediation (only on a clean proof — verified, a real
+  // regression baseline, no regressions). read at end-of-run by cloudReport, which
+  // reports them to the org library (the fleet store). Accumulated across verify
+  // calls; deduped on use. (The committed local `.infraweaver.fix-memory.json` is
+  // produced out-of-band — it's a READ source here, not written during a run.)
+  provenFixCaptures?: ProvenFixPattern[];
+  // TC-2.2 — the org's fleet-wide record of which provider-upgrade transforms
+  // have already planned cleanly elsewhere, coerced at run start from the Cloud
+  // run-context. Read by terraform_provider_upgrade to annotate a transform with
+  // its fleet reuse. Counters only: no repo names, no configuration.
+  provenTransformLibrary?: ProvenTransform[];
+  // TC-2.2 — what terraform_provider_upgrade matched this run. Kept so the
+  // end-of-run capture can report the transforms the plan actually proved,
+  // rather than every transform the pack knows about.
+  transformMatches?: TransformMatch[];
+  // TC-2.2 — the detected upgrade, bound at evidence time to the plan that
+  // followed it. undefined unless terraform_provider_upgrade ran and a pack
+  // applied, so a run that never touched a provider major emits no upgrade block.
+  upgradeIntent?: UpgradeIntent;
+  // TC-2.2 — the aggregate plan counts, recorded by terraform_plan. The session
+  // already carries blast tier, idempotency and the destroy classification; only
+  // the raw add/change/destroy totals were missing, and the upgrade evidence
+  // statement needs them to state what the plan actually showed.
+  lastPlanTotals?: {
+    to_add: number;
+    to_change: number;
+    to_destroy: number;
+    destructive: number;
+  };
+  // TC-2.2 — was the upgrade ALREADY detected when this plan ran? Set by
+  // terraform_plan from whether `upgradeIntent` existed at that moment.
+  //
+  // Without it, a run that planned for some other reason and only later called
+  // terraform_provider_upgrade would emit a `plan-proven` verdict off a plan
+  // produced BEFORE the upgrade was even considered — a signed claim that a
+  // migration planned cleanly, backed by a plan of the pre-migration config.
+  // The ordering is the whole proof, so it is recorded rather than assumed.
+  planFollowedUpgradeDetection?: boolean;
+}
+
+/**
+ * The TC-2.2 upgrade statement for this session, or undefined when no provider
+ * pack applied.
+ *
+ * Deliberately computed in ONE place. Two consumers need it — the signed
+ * evidence bundle and the fleet report — and if each assembled the plan facts
+ * itself they could disagree, which would mean telling an org that a transform
+ * planned cleanly while the signed artefact for that same run said otherwise.
+ */
+export function upgradeStatementOf(
+  session: ScanSession,
+): UpgradeEvidenceStatement | undefined {
+  // Only a plan that ran AFTER the upgrade was detected can back it. A plan from
+  // earlier in the run describes the pre-migration configuration, so it is
+  // discarded here and the statement degrades to `no-plan` — visibly unproven,
+  // which is the honest outcome, rather than silently proven by the wrong plan.
+  const totals = session.planFollowedUpgradeDetection
+    ? session.lastPlanTotals
+    : undefined;
+  return buildUpgradeStatement(
+    session.upgradeIntent,
+    totals
+      ? {
+          ...totals,
+          stateful_destructive: session.plannedDestroy?.stateful.length ?? 0,
+          // A plan whose idempotency was never recorded is treated as unstable
+          // rather than stable — the conservative direction for a proof.
+          idempotent: session.lastIdempotent ?? false,
+        }
+      : undefined,
+  );
+}
+
+/** A fresh, empty terraform session. */
+export function createScanSession(): ScanSession {
+  return {};
+}
+
+/**
+ * The single entry point to the terraform session on a `ToolState`. Lazily
+ * initializes it, so a partially-constructed `ToolState` (chiefly test fixtures
+ * that cast `{}`) still reads and writes safely rather than dereferencing
+ * `undefined`. In production `initToolState` seeds it, so this only ever
+ * lazy-creates for such fixtures.
+ */
+export function scanSessionOf(toolState: {
+  scanSession?: ScanSession;
+}): ScanSession {
+  toolState.scanSession ??= {};
+  return toolState.scanSession;
+}
+
+/**
+ * true once terraform_scan / read_findings captured a pre-fix baseline this
+ * session. terraform_verify_remediation key-maps requested ids against the
+ * baseline when this holds, and reports regressions on that basis; otherwise it
+ * falls back to raw-id matching and marks regressions as unchecked.
+ */
+export function hasBaseline(session: ScanSession): boolean {
+  return (
+    session.baselineConcernKeys !== undefined ||
+    session.baselineConcernIds !== undefined
+  );
+}