Invariants Overview

An invariant is a claim about a property that should always hold in your system: “no public S3 buckets,” “every production database has deletion protection enabled,” “all IAM roles in the network boundary require MFA.” You write the intent in plain language; Forgecroft turns it into evidence checks and evaluates them against every run.

What an Invariant Is Not

Invariants are not policies, tests, or scanners — though they may use policy evaluation as one of their evidence sources.

	Invariant	Policy set	Test	Scanner
Authored as	Natural language	Rego code	Code	Config or rules
Evaluated by	Forgecroft (multi-source)	Policy engine	Test runner	Scanner engine
Verdict model	Four-mode with evidence	Pass/fail	Pass/fail	Finding list
Evidence surfaced	Yes — per entry	No	No	Partial
Gaps reported	Yes — honest gaps at authoring time	No	No	No

Policies, approval rules, and external checks operate as governance layers that gate individual runs. An invariant claims a property holds across your system and reports how that was established — or why it could not be.

The Four-Mode Verdict

Every (invariant × change) pair evaluates to one of four outcomes. Two of these are surfaced in the scorecard; one is implicit.

Customer label	What it means
Compliant	Forgecroft found evidence that the property holds for this change. The evidence references are included in the scorecard entry.
Needs evidence	The invariant intersects with this change, but the available evidence is insufficient to prove or disprove the claim. The scorecard entry explains what would resolve it.
Violation	Forgecroft found evidence that the property is violated. The run is flagged and remediation guidance is included.

A fourth outcome — when the invariant simply does not intersect with the change — is not surfaced in the scorecard at all. Absence means “not applicable to this change,” not “passed.”

The Authoring Flow

Write intent text
  → Preview: Forgecroft produces an evidence-check plan + surfaces honest gaps
  → Review preview (cost class, gaps, checks)
  → Accept: Create invariant (persisted, active immediately)
  → Forgecroft evaluates on every subsequent run

Preview first. POST /invariants/preview (or forgecroft invariants preview) processes the intent and returns the evidence checks and any honest gaps without persisting anything. Use it to understand what Forgecroft will evaluate and where evidence may be thin before committing.

Create is one-shot. POST /invariants (or forgecroft invariants create) processes and persists in a single call. There are no drafts. If you want to revise the intent later, use PATCH /invariants/{id} — it re-analyzes and bumps the intent version.

Honest Gaps

When Forgecroft processes an intent, it also reports honest gaps — aspects of your intent that the available evidence sources cannot fully prove. These are surfaced at authoring time, not at evaluation time.

An honest gap is a feature, not a failure. It means Forgecroft is being precise about what it can and cannot know. A gap might say “runtime configuration of this service is not observable from plan output alone” — which tells you that the Compliant verdict for that aspect will require a runtime observation source to be configured.

See Authoring Invariants for how to interpret and act on honest gaps.

Scope

Invariants are org-scoped. Every invariant belongs to exactly one organization and is evaluated against all runs within that org. Workspace or project-level scoping is expressed through the invariant’s scope_selector field.

How Invariants Relate to Governance

Governance layers (policy sets, approval rules, external checks) gate individual runs: they evaluate a plan and return pass/fail decisions that control whether a run proceeds. They are described in the Governance Overview.

Invariants work alongside governance, not instead of it:

• Governance answers “can this change proceed?” — a per-run gate.
• Invariants answer “does this property hold?” — a per-claim evaluation with evidence.

A claim like “no public S3 buckets” might be enforced by both a mandatory policy set (blocking violating plans) and an invariant (tracking evidence and surfacing gaps where policy alone cannot prove compliance). These are complementary, not redundant.

Related Guides

• Authoring Invariants — creating, previewing, and managing invariants
• Scorecard — reading per-run invariant evaluation results
• Governance Overview — policy sets, approval rules, and external checks