infraweaver 0.1.0

package/dist/mcp/terraform/transformPacks.d.ts

@@ -0,0 +1,267 @@
+import type { LocatedResource, ProviderRequirement } from "#app/mcp/terraform/scanners";
+/** Bumped when the pack SHAPE changes (not when an individual pack's content
+ *  does — each pack carries its own `version`). Mirrors `FixMemoryFile.version`. */
+export declare const TRANSFORM_PACK_SCHEMA: "infraweaver-transform-pack/v1";
+/**
+ * The built-in packs.
+ *
+ * Built in rather than fetched: a migration table pulled at runtime is a remote
+ * input that decides how live infrastructure gets edited, which is the last
+ * thing that should be mutable outside a reviewed release. Adding a pack is a
+ * code change with a diff, a review and a version — exactly like the crosswalk.
+ *
+ * These ship to everyone, OSS included, with no input to enable. The only
+ * Cloud-gated part of TC-2.2 is the fleet-wide *proven* counters.
+ */
+export declare const BUILTIN_TRANSFORM_PACKS: readonly TransformPack[];
+/**
+ * How a transform's state has to move.
+ *
+ * This is the field the whole feature turns on, because it — not the size of the
+ * diff — decides whether a human must look. `auto` is a pure config edit that
+ * `plan` should show as a no-op. `moved_block` needs a `moved {}` block authored
+ * (Terraform ≥ 1.8) but keeps the resource. `manual_import` means the state
+ * entry cannot be carried across: without `state rm` + `import`, applying the
+ * change DESTROYS and RECREATES the resource.
+ */
+export type StateMove = "auto" | "moved_block" | "manual_import";
+export type TransformKind = "resource_renamed" | "resource_removed" | "argument_renamed" | "argument_removed" | "argument_required" | "provider_setting";
+/** One codified breaking change. */
+export interface TransformEntry {
+    /** stable id, `<provider>.<from>-<to>.<slug>` — the fleet-sharing match key. */
+    id: string;
+    kind: TransformKind;
+    /** the resource type the change applies to; `null` for provider-block changes. */
+    resource_type: string | null;
+    /** what the config says today (old resource type, old argument name). */
+    from: string;
+    /** what it becomes; `null` when the thing was removed with no replacement. */
+    to: string | null;
+    state_move: StateMove;
+    /** true when applying this change is expected to force replacement even after
+     *  the config edit — the pre-plan signal that a human will be needed. */
+    forces_replacement: boolean;
+    /**
+     * Set when the VALUE must change too, not just the identifier.
+     *
+     * This exists because the most dangerous entry in any migration table is the
+     * one that looks like a pure rename and isn't: `disable_bgp_route_propagation`
+     * → `bgp_route_propagation_enabled` inverts the boolean, and a mechanical
+     * rename would silently flip the routing behaviour of a live network while
+     * `validate`, `plan` and every scanner stayed green. When this is set, the
+     * transform is never presented as a rename.
+     */
+    value_change?: string;
+    /** one line the agent can act on. */
+    note: string;
+}
+export interface TransformPack {
+    /** registry provider name, e.g. `azurerm`. */
+    provider: string;
+    from_major: number;
+    to_major: number;
+    /** pack content version — bump when entries change. */
+    version: string;
+    /** the upstream guide these entries were transcribed from. Every claim in this
+     *  file is someone else's documented breaking change, so it gets a citation. */
+    source: string;
+    /** ALWAYS false in practice, and stated rather than implied: no pack here is a
+     *  complete migration. `unknown_arguments` is the exhaustive check. */
+    exhaustive: boolean;
+    /** upstream's own migration tool, when one exists. Preferring it over our own
+     *  leads is "integrate upward, don't compete" applied to migrations. */
+    official_tool?: string;
+    entries: TransformEntry[];
+}
+/**
+ * Whether the installed provider schema CORROBORATES a pack entry.
+ *
+ * - `pre-upgrade`  — schema has `from`, not `to`. Consistent with the old major
+ *                    still being installed; the entry is a valid lead.
+ * - `post-upgrade` — schema has `to`, not `from`. The new major is installed, so
+ *                    any remaining use of `from` is a confirmed must-fix.
+ * - `unverified`   — schema has both, neither, or wasn't loadable. The pack is
+ *                    not believed; the entry is reported but never actionable.
+ */
+export type SchemaAgreement = "pre-upgrade" | "post-upgrade" | "unverified";
+/**
+ * How sure we are that this entry applies to a specific piece of the config.
+ *
+ * `absent` exists because one entry kind — `argument_required` — fires on the
+ * argument NOT being there. Reporting that as `confirmed` (which is documented
+ * as "the identifier was found") would tell the reader the exact opposite of
+ * what happened.
+ */
+export type MatchConfidence = "confirmed" | "nested" | "absent";
+export interface TransformMatch {
+    entry: TransformEntry;
+    /** the pack that produced it. Carried per-match rather than read from the
+     *  run's primary pack, because a repo can be mid-upgrade on two providers and
+     *  the fleet row's provider/major columns must describe the right one. */
+    provider: string;
+    from_major: number;
+    to_major: number;
+    /** where it was found. */
+    file: string;
+    /** the resource block's local name (`""` for provider-block matches). */
+    resource_name: string;
+    /**
+     * `confirmed` — the exact top-level identifier was found in the parsed config.
+     * `nested`    — the entry names a path inside a block (`a.b.c`) and the parser
+     *               only sees top-level argument names, so the resource TYPE
+     *               matched but the argument itself was not confirmed. Reported as
+     *               a lead to check by hand, never as a certainty.
+     */
+    confidence: MatchConfidence;
+    schema_agreement: SchemaAgreement;
+    /** true when this match must not be applied autonomously. */
+    needs_human: boolean;
+    /** why, when it does. */
+    needs_human_reason: string | null;
+}
+/**
+ * Does this transform need a human?
+ *
+ * Two independent triggers, both deliberately conservative:
+ *  1. `manual_import` — the state cannot be carried across automatically, so an
+ *     unattended apply destroys and recreates. Always human, every resource type.
+ *  2. `forces_replacement` on a STATEFUL resource type. Stateful-ness is read
+ *     from `plan.ts`'s `STATEFUL_RESOURCE_TYPES` — the exact set the push-time
+ *     `assertNoBlockedDestroy` guardrail uses — and NOT from `governance.ts`'s
+ *     regex heuristic, because the point of pre-declaring this is to predict
+ *     what the guard will actually block. Predicting it with a different
+ *     definition than the guard uses would be worse than not predicting it.
+ */
+export declare function transformNeedsHuman(entry: TransformEntry): {
+    needs: boolean;
+    reason: string | null;
+};
+/** Schema lookup seam. Returns the argument names known for a resource type, or
+ *  `null` when the schema could not be loaded / the type is unknown to it. */
+export type SchemaLookup = (resourceType: string) => ReadonlySet<string> | null;
+/**
+ * Check one entry against the installed provider schema.
+ *
+ * Only argument-level entries are checkable this way — a removed RESOURCE type
+ * cannot be corroborated by asking the schema about it (its absence is equally
+ * consistent with "removed in v4" and "this provider isn't installed"), so those
+ * return `unverified` and lean on the deterministic type match instead.
+ */
+export declare function verifyEntry(entry: TransformEntry, lookup: SchemaLookup): SchemaAgreement;
+/**
+ * Select the packs that apply to what this repo actually pins.
+ *
+ * A pack applies when the provider is required AND the pinned lower-bound major
+ * equals the pack's `from_major`. An unconstrained provider (`major: null`)
+ * matches nothing: guessing which major an unpinned provider resolves to is how
+ * you hand someone a migration they don't need.
+ */
+export declare function packsForRequirements(packs: readonly TransformPack[], requirements: readonly ProviderRequirement[]): TransformPack[];
+/**
+ * Match a pack's entries against the parsed configuration. Pure.
+ *
+ * `resources` comes from `parseResourceArguments`, which reports TOP-LEVEL
+ * argument names only. That bound is honoured rather than papered over: a
+ * dotted entry produces a `nested` match (resource type present, argument not
+ * confirmed) so the agent knows to look inside the block itself.
+ */
+export declare function matchTransforms(pack: TransformPack, resources: readonly LocatedResource[], lookup: SchemaLookup): TransformMatch[];
+/**
+ * Fleet reuse stats for a transform id — the §5.12-shaped half.
+ *
+ * Notice what is NOT here: no config, no snippet, no repo name. A transform is
+ * already fully described by the pack every engine ships; the only thing worth
+ * sharing across an org is *whether it has been proven to plan cleanly, and how
+ * widely*. That keeps the fleet payload a set of counters, so there is no path
+ * by which one repo's configuration reaches another.
+ */
+export interface ProvenTransform {
+    /** matches `TransformEntry.id`. */
+    transform_id: string;
+    provider: string;
+    from_major: number;
+    to_major: number;
+    /** how many times this transform's upgrade planned cleanly. */
+    times_proven?: number;
+    /** distinct repos it has been proven on. */
+    repos_count?: number;
+    last_proven?: string;
+    /** operator retired it in the dashboard — never offered as proven. */
+    disabled?: boolean;
+}
+export declare function isProvenTransform(value: unknown): value is ProvenTransform;
+/** Coerce the untrusted Cloud `provenTransforms` blob. Pure — the wire boundary
+ *  can't be typechecked across repos (same reasoning as `coerceLibrary`). */
+export declare function coerceProvenTransforms(raw: unknown): ProvenTransform[];
+/**
+ * What `terraform_provider_upgrade` detected this run, parked on the session so
+ * the evidence builder can bind it to the plan that came after.
+ */
+export interface UpgradeIntent {
+    provider: string;
+    from_major: number;
+    to_major: number;
+    pack_version: string;
+    pack_source: string;
+    pack_exhaustive: boolean;
+    /** ids of every transform matched in this config, deduped, sorted. */
+    transform_ids: string[];
+    /** how many of those must not be applied autonomously. */
+    needing_human: number;
+}
+/** The plan facts the proof rests on. Supplied by the caller from the session so
+ *  this stays pure and testable. */
+export interface UpgradePlanFacts {
+    to_add: number;
+    to_change: number;
+    to_destroy: number;
+    /** count of destroy/replace actions across all roots. */
+    destructive: number;
+    /** count of those that hit a data-bearing resource type. */
+    stateful_destructive: number;
+    /** false when a second plan disagreed with the first. */
+    idempotent: boolean;
+}
+/**
+ * The signed-evidence statement for a provider upgrade (TC-2.2's "carrying the
+ * passing plan as proof").
+ *
+ * The verdict is computed from the plan, never asserted by the agent, and — per
+ * §8 — the statement carries what it does NOT claim. A clean plan proves that
+ * Terraform intends no destructive change to the resources it can see. It does
+ * not prove the upgrade is behaviourally correct, and it says so.
+ */
+export interface UpgradeEvidenceStatement {
+    provider: string;
+    from_major: number;
+    to_major: number;
+    pack_version: string;
+    pack_source: string;
+    /** always false, carried into the signed bytes so a reader cannot mistake the
+     *  transform list for a complete migration. */
+    pack_exhaustive: boolean;
+    verdict: "plan-proven" | "plan-unclean" | "no-plan";
+    transforms_detected: number;
+    transforms_needing_human: number;
+    transform_ids: string[];
+    plan?: UpgradePlanFacts | undefined;
+    asserts: string;
+    does_not_assert: string;
+}
+/**
+ * Build the upgrade statement. Pure. `facts` is undefined when no plan ran —
+ * which is itself recorded as a verdict rather than omitted, because an upgrade
+ * shipped without a plan is precisely the case a reader must be able to spot.
+ */
+export declare function buildUpgradeStatement(intent: UpgradeIntent | undefined, facts: UpgradePlanFacts | undefined): UpgradeEvidenceStatement | undefined;
+/**
+ * The transforms this run may report to the org's fleet library as PROVEN.
+ *
+ * Only on a `plan-proven` verdict, and only transforms that did not need a
+ * human — a transform a person had to intervene on is not evidence that the
+ * transform is safe to apply unattended, which is the only claim the fleet
+ * counter is allowed to make.
+ */
+export declare function captureProvenTransforms(statement: UpgradeEvidenceStatement | undefined, matches: readonly TransformMatch[]): ProvenTransform[];
+/** Index a fleet library by transform id for O(1) lookup while rendering. */
+export declare function indexProvenTransforms(library: readonly ProvenTransform[]): Map<string, ProvenTransform>;

package/dist/mcp/terraform/types.d.ts

@@ -0,0 +1,226 @@
+import type { IacLanguage } from "#app/mcp/terraform/iacLanguages";
+/**
+ * A degrade-green skip result carrying the structured envelope
+ * (`ok: false` + machine `code` + human `detail`) PLUS the legacy alias the tool
+ * returned before it converged on the envelope — `ran`/`found` and
+ * `skipped_reason`/`reason` — so existing prompt + test contracts keep working.
+ * Additive, never breaking. `extra` folds in any tool-specific fields (e.g.
+ * read_findings' empty `concerns`/`groups`).
+ */
+export declare function skipResult(code: string, detail: string, opts?: {
+    key?: "ran" | "found";
+    reasonKey?: "skipped_reason" | "reason";
+    extra?: Record<string, any>;
+}): Record<string, any>;
+/**
+ * Internal "concern" model — the Remediator's ground truth for "what is not
+ * best practice". Produced by `terraform_scan` from the fork's own deterministic
+ * Terraform check tools (fmt / validate / tflint / trivy / checkov).
+ *
+ * This is a deliberate SUBSET of the reviewer's `findings.schema.json` v1.0
+ * (../terraform-reviewer/schemas/findings.schema.json). The reviewer's findings
+ * add `lens` / `standard` / `control_id` / `state` on top. Keeping the shape a
+ * subset means a future reviewer integration (read_findings) can emit the same
+ * Concern[] with no change to the modes or the rest of the tools — only the
+ * SOURCE of concerns swaps.
+ */
+export interface Concern {
+    /** stable content id: sha1(source|rule_id|file|line). idempotency key for branch/PR naming. */
+    id: string;
+    /** producing tool. `infraweaver` is the NATIVE rule pack ([[nativeRules]]) — the
+     * findings no upstream scanner can produce, re-derived on every scan so they stay
+     * ✗→✓ verifiable. `reviewer` marks a concern loaded from a terraform-reviewer
+     * findings.json whose original tool isn't one Infraweaver re-runs (tfsec / infracost
+     * / llm) — its provenance lives in `rule_id`. */
+    source: "terraform-fmt" | "terraform-validate" | "tflint" | "trivy" | "checkov" | "infraweaver" | "reviewer";
+    /** original namespaced rule, e.g. "trivy:AVD-AWS-0088" */
+    rule_id: string;
+    severity: Severity;
+    category: "security" | "style" | "correctness" | "cost";
+    /** the scanner message — what is wrong */
+    evidence: string;
+    location: {
+        file: string;
+        line: number | null;
+    };
+    /** the IaC language the flagged file is written in (from the scanner's own
+     * classification — trivy `Type` / checkov `check_type`). Absent on the
+     * Terraform-only scanners (fmt/validate/tflint) and reviewer-loaded concerns;
+     * scope filtering falls back to a path classification then terraform.
+     * NOT part of the content `id` — purely descriptive, additive. */
+    language?: IacLanguage;
+    /** the offending source line(s) the scanner flagged (trivy cause lines /
+     *  checkov code block), so a reader sees the exact code, not just file:line.
+     *  Absent when the scanner doesn't attach source context. */
+    code_snippet?: string | null;
+    remediation_hint: string | null;
+    suppression?: ConcernSuppression;
+    /** 2c taxonomy: the canonical resource+misconfig class this rule maps to (e.g.
+     *  "aws-s3-encryption"), set when cross-scanner normalisation recognises it. */
+    canonical_class?: string;
+    /** 2c taxonomy: the scanner(s) that flagged this canonical issue, after a
+     *  cross-scanner merge (e.g. ["checkov", "trivy"]). */
+    flagged_by?: string[];
+}
+export interface ConcernSuppression {
+    source: "inline" | "policy";
+    reason: string;
+    expires: string | null;
+}
+export declare const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
+export type Severity = (typeof SEVERITIES)[number];
+export declare const SEVERITY_RANK: Record<Severity, number>;
+export declare const SEVERITY_CVSS_SCORE: Record<Severity, number>;
+export declare const CVSS_SEVERITY_BANDS: ReadonlyArray<{
+    min: number;
+    severity: Severity;
+}>;
+export declare function severityFromCvss(score: number): Severity;
+export declare function cvssScoreForSeverity(severity: Severity): number;
+export declare function concernId(source: string, ruleId: string, file: string, line: number | null): string;
+/**
+ * The single constructor every scanner parser uses to turn a raw finding into a
+ * `Concern`. It owns the one coupling that must never drift: the content `id`
+ * (`sha1(source|rule|file|line)`) and the namespaced `rule_id` (`source:rule`)
+ * are BOTH derived from the same bare `rule` here, so a parser can't accidentally
+ * hash one rule string while labelling the concern with another — which would
+ * silently break `remediate/<id>` branch naming and the ✗→✓ re-scan match.
+ *
+ * The per-scanner bits that genuinely differ (severity map, category, evidence
+ * text, remediation hint, whether a source snippet is attached) stay explicit at
+ * the call site — they're not uniform enough to hide behind a config object
+ * without obscuring each parser. `code_snippet` is only set when provided, so
+ * fmt/validate/tflint concerns keep their exact prior shape (no `code_snippet`
+ * key) and trivy/checkov keep theirs (`code_snippet` before `remediation_hint`).
+ */
+export declare function buildConcern(input: {
+    source: Concern["source"];
+    /** the BARE rule (e.g. `unformatted`, `AVD-AWS-0088`), NOT `source:rule`. */
+    rule: string;
+    file: string;
+    line: number | null;
+    severity: Severity;
+    category: Concern["category"];
+    evidence: string;
+    remediation_hint: string | null;
+    code_snippet?: string | null;
+    /** the scanner-reported IaC language (trivy `Type` / checkov `check_type`);
+     * omit for the Terraform-only scanners — descriptive only, never hashed. */
+    language?: IacLanguage | null;
+}): Concern;
+/**
+ * A LINE-INDEPENDENT identity for a concern — which rule fires in which file,
+ * ignoring the exact line. Two instances of the same rule in the same file at
+ * different lines share a key.
+ *
+ * The full content `id` keys on the line so it's unique per instance (right for
+ * SARIF alerts + branch naming), but that makes it UNSTABLE under a fix: almost
+ * every fix adds or removes lines, shifting every concern below it to a new line
+ * → a new id. If ✗→✓ verification compared raw ids, a shifted-but-unfixed concern
+ * would look RESOLVED (old id gone) and simultaneously look like a REGRESSION
+ * (new id appeared) — a false attestation either way. `terraform_verify_remediation`
+ * compares on this key instead, so a line shift can't fabricate a resolution or a
+ * regression. Derived identically to `id` minus the line (same bare-rule
+ * normalization) so keys match across the original scan and the re-scan.
+ */
+/** Strip a rule id's own `<source>:` namespace prefix, if present — the
+ *  normalization shared by `concernKeyOf` (per-file key) and the fix-memory
+ *  finding-TYPE key (`source|bareRule`, file-independent). One helper so the two
+ *  can never disagree on what "the same rule" means. */
+export declare function bareRuleOf(source: string, ruleId: string): string;
+export declare function concernKeyOf(c: Pick<Concern, "source" | "rule_id" | "location">): string;
+export type ScannerOutcome = {
+    source: Concern["source"];
+    ran: boolean;
+    skipped_reason?: string;
+    concerns: Concern[];
+    /**
+     * For `terraform validate` only: count of roots where terraform RAN but its
+     * `-json` output could not be parsed (a real CLI-level failure, not a missing
+     * binary). Lets the validate tool report `passed` as fail-closed instead of
+     * silently treating an un-validated root as clean. Undefined/0 elsewhere.
+     */
+    unvalidated?: number;
+    /**
+     * A scanner that RAN but whose coverage was incomplete — one named check inside
+     * it could not execute. Distinct from `ran: false` (nothing ran) and from an
+     * empty `concerns` (everything ran and found nothing), which is exactly the
+     * distinction that stops a partially-blind scan reading as a clean one. Folded
+     * into the verification summary's INCONCLUSIVE list, never dropped.
+     */
+    partial?: {
+        check: string;
+        reason: string;
+    };
+    /**
+     * Set when this scanner executed under egress denial (supply-chain 0.2).
+     * Always the honest word "partial": the control is an env-level proxy
+     * contract, not a kernel boundary — a malicious binary can ignore it. The
+     * run summary records it so an assessor can see WHICH findings were produced
+     * under bounded egress; absence means the tool ran with open egress.
+     */
+    egress_isolation?: "partial";
+};
+export declare function skipped(source: Concern["source"], reason: string): ScannerOutcome;
+/**
+ * Re-base a concern produced by a per-root command (its file is relative to the
+ * root dir) onto the scan `cwd` by prefixing the root's `relDir`, and recompute
+ * the content id so it stays consistent with the cwd-relative scanners (✗→✓).
+ * A no-op when `relDir` is "" (the root IS cwd).
+ */
+export declare function rebaseConcern(c: Concern, relDir: string): Concern;
+/** true when a path is a Terraform source file Infraweaver may remediate. */
+export declare function isTerraformFile(file: string): boolean;
+/**
+ * The FIX-LOOP filter: Remediate is Terraform-first. A concern in a
+ * non-`.tf`/`.tfvars` file can never be remediated (the `allowed_paths` push
+ * guardrail blocks the edit, and the `✗→✓` proof machinery is Terraform-specific).
+ * The single chokepoint that enforces this is `buildConcernResult`
+ * (concernResult.ts), through which EVERY fixer-feeding surface routes —
+ * `terraform_scan`, `read_findings`, `detect_plan_drift` and
+ * `ingest_external_findings` — so a non-Terraform concern can never reach grouping,
+ * a PR branch, or the verifier no matter which tool produced it.
+ * The READ-ONLY surfaces (Assess / SARIF / evidence) deliberately do NOT use this
+ * filter: they scope by detected IaC language instead (`inLanguageScope`), which is
+ * how multi-language Assess widens breadth without ever faking a fix proof for a
+ * format the machinery can't verify.
+ */
+export declare function isTerraformConcern(c: Concern): boolean;
+export declare function dedupe(concerns: Concern[]): Concern[];
+export declare function sortConcerns(concerns: Concern[]): Concern[];
+export declare function lowerSeverity(s: string | undefined): Severity;
+/**
+ * A scoped unit of work = all concerns in one file. Different scanners flag the
+ * same underlying defect under different rule ids (trivy ∩ checkov overlap
+ * heavily on e.g. S3 buckets), so per-concern PRs would spam many PRs for one
+ * bad file. Remediate acts on ONE group per PR (branch `remediate/<group.id>`),
+ * fixing every concern in the file together and proving them all cleared (✗→✓).
+ */
+export interface ConcernGroup {
+    /** stable id — the remediation branch/PR key (`remediate/<id>`). Derived from
+     * the file (by-file grouping) or the rule (by-rule grouping). */
+    id: string;
+    /** the group's primary file (by-file) or a human label like "3 files"
+     * (by-rule); `files` carries the full list for by-rule groups. */
+    file: string;
+    /** every file the group spans. one entry for a by-file group; the
+     * full set for a by-rule group (the agent must fix the rule in all of them). */
+    files?: string[];
+    /** how the group was formed — `file` (default) or `rule`. */
+    grouping?: "file" | "rule";
+    /** highest severity among the group's concerns. */
+    severity: Severity;
+    concern_count: number;
+    /** distinct rule ids in the group, for the PR body. */
+    rule_ids: string[];
+    /** the concern ids the re-scan must confirm are gone to call this ✓. */
+    concern_ids: string[];
+    /** `auto` (open a normal PR) or `needs-human` (escalate). attached by
+     * the scan tool from the group's concerns, not by `groupConcerns` (which has
+     * no autonomy threshold). undefined until the scan tool annotates it. */
+    autonomy?: Autonomy;
+    /** why the group was escalated (empty/absent for `auto`). */
+    autonomy_reasons?: string[];
+}
+export type Autonomy = "auto" | "needs-human";
+export type BlastTier = "low" | "medium" | "high";

package/dist/mcp/terraform/verification.d.ts

@@ -0,0 +1,81 @@
+import type { Concern, ScannerOutcome } from "#app/mcp/terraform/types";
+/**
+ * Five-status verification taxonomy (the auditor-credibility win the evidence
+ * pack + crosswalk both lean on). The point is HONESTY: never let "no finding"
+ * read as "compliant", and never claim the engine proved something it cannot see
+ * from code. Every assessment statement carries exactly one of these:
+ *
+ *   - `pass`                — a check ran and code-verified compliance.
+ *   - `fail`                — a check ran and code-verified a violation.
+ *   - `not-applicable`      — the control does not apply to the resources present.
+ *   - `inconclusive`        — a relevant check did NOT run (gated / not installed /
+ *                             unparseable). A coverage gap, never silently a pass.
+ *   - `not-code-verifiable` — the control needs human / process evidence
+ *                             (governance, training, a key-policy decision); IaC
+ *                             scanning structurally cannot prove it either way.
+ *
+ * What this engine asserts today: `fail` and `not-code-verifiable` per concern,
+ * and `inconclusive` per scanner that didn't run. It deliberately does NOT
+ * fabricate `pass` / `not-applicable` for controls nothing fired on — absence of
+ * a finding is not proof, and over-claiming is exactly what costs credibility
+ * with an assessor. The two reserved statuses are part of the shared vocabulary
+ * for the evidence consumer (and a future full-framework crosswalk). Pure.
+ */
+export declare const VERIFICATION_STATUSES: readonly ["pass", "fail", "not-applicable", "inconclusive", "not-code-verifiable"];
+export type VerificationStatus = (typeof VERIFICATION_STATUSES)[number];
+/** one-line legend per status — for the report / evidence bundle. */
+export declare const VERIFICATION_STATUS_LABEL: Record<VerificationStatus, string>;
+/** the statuses the engine asserts per concern (a concern is always one or the
+ * other — it fired, the only question is whether code can prove the fix). */
+export type ConcernVerificationStatus = Extract<VerificationStatus, "fail" | "not-code-verifiable">;
+/**
+ * Classify one concern: a code-verified violation (`fail`) — UNLESS its
+ * remediation is a human decision the engine can flag but not prove from code
+ * (IAM least-privilege, a KMS key policy, a real CIDR — the refusal set), in
+ * which case it is `not-code-verifiable`. Pure.
+ *
+ * A NATIVE rule ([[nativeRules]]) is decided by its declared band FIRST, and the
+ * band is checked before the keyword-matching refusal set on purpose: a
+ * governance rule's own text (which names what it deliberately does not assert)
+ * must never be able to trip a refusal regex into a different reason, and a
+ * `verified` native rule must never be downgraded because its evidence happens
+ * to contain a word like "policy".
+ */
+export declare function concernVerificationStatus(concern: Pick<Concern, "rule_id" | "evidence">): {
+    status: ConcernVerificationStatus;
+    reason?: string;
+};
+export interface VerifiedConcern {
+    id: string;
+    status: ConcernVerificationStatus;
+    reason?: string;
+}
+export interface VerificationSummary {
+    /** per-concern verification status. */
+    concerns: VerifiedConcern[];
+    counts: {
+        fail: number;
+        not_code_verifiable: number;
+        /** scanners that did not run (each is a coverage gap). */
+        inconclusive: number;
+    };
+    coverage: {
+        /** scanners that ran — their checks are code-verified for what they cover. */
+        verified: string[];
+        /** scanners that did NOT run — their checks are INCONCLUSIVE, never a pass. */
+        inconclusive: {
+            source: string;
+            reason: string;
+        }[];
+    };
+    /** the honesty caveat an assessor should read alongside the statuses. */
+    note: string;
+}
+/**
+ * Roll a scan up into a verification summary: every concern classified
+ * (fail / not-code-verifiable) and every scanner partitioned into verified (ran)
+ * vs inconclusive (skipped — gated, not installed, or unparseable). Pure;
+ * `outcomes` is the raw `runScanners` result, `concerns` the deduped,
+ * Terraform-only set the assessment reports on.
+ */
+export declare function buildVerificationSummary(concerns: Pick<Concern, "id" | "rule_id" | "evidence">[], outcomes: ScannerOutcome[]): VerificationSummary;