Core Concepts

Intent, Evidence and Decisions

Understand how desired intent, independent observations and policy-driven decisions form a reconciliation loop without becoming one source of truth.

Edit this page on GitHub

Intent, Evidence and Decisions

The desired graph answers “What do we want?” It does not, by itself, answer “What is running?” or “What should we do about the difference?”

Observed state extends rescile beyond describing intent. Independent collectors provide evidence about the environment; action-owned comparisons evaluate that evidence against selected intent under each action’s explicit policy. The build pipeline remains the owner of desired configuration. It does not become a continuously overwritten mirror of the provider.

Three things that flow

Intent, evidence and decisions: two independent inputs, one explicit reconciliation loop Workspace inputs build the desired graph. Separately, independent collectors read the environment into an observation store. Intent and usable evidence meet in reconciliation, together with workspace policy. Decisions can remain reports or proposals. Only authorized actions change the environment, which collectors read again. Observations never overwrite intent, and a successful action is not proof of its outcome. INTENT Desired Configuration Workspace Inputs Assets, models, rules (TOML & CSV) Authoritative source of what should exist Build Desired Graph Compiled topology & declared properties CPU: 8 vCPUs INTENDED • Stable between builds • Never overwritten by provider state EVIDENCE Observed Reality Live Environment Actual infrastructure & cloud resources Mutated only by authorized actions Independent collection Observation Store Collected telemetry, provenance & time CPU: 4 vCPUs OBSERVED • Source authority · read time · coverage • Updated continuously without a build Two inputs · neither overwrites the other DECISIONS Reconciliation & Workspace Policy Compares intent against usable evidence, evaluates freshness, and applies policy Drift Finding Audit Report Plan Proposal Human Approval Findings identify conditions — they never silently rewrite desired intent Only if authorized Action Execution Queue FROZEN INTENT Protected execution by sandboxed runner with exact scoped inputs Mutates provider environment only — never alters graph records directly Change environment · collect again Verify with fresh evidence: Do not infer convergence or success from exit status

Open the diagram at full size.

Flow Question Where it comes from How it changes
Intent What should exist? Workspace assets, models, compliance rules and rendered configuration Rebuilt when workspace inputs change; stable between builds
Evidence What did a source observe? Independent provider reads and collector reports Recorded independently of builds; retains provenance and ages over time
Decisions What does the difference mean, and may we act? Intent + usable evidence + workspace policy Findings are recomputed as inputs change; proposals, approvals and execution records preserve the exact context of a decision

Intent and evidence have different owners and update cycles. Decisions derive from both; they are not a new source of truth for either. A read-only query can show desired and observed values together without merging their authoritative stores.

Observed state is not actual state

Actual state is what exists in the environment. Observed state is the evidence available to the controller.

A provider API can return an old value. A collector can lack permission to read a disk. A paginated inventory can fail halfway through. Two sources can report different CPU counts because one measures allocated vCPUs and another measures online guest CPUs.

Each observation therefore needs identity, source, scope, read time and coverage. Freshness and source authority determine whether it can support a comparison. Unknown, unreadable, unsupported, stale and absent are different conditions—not interchangeable values.

For example, four reported servers against five desired servers do not necessarily mean that one server is missing. Only a complete authoritative inventory of the relevant boundary can establish absence. A failed or partial scan cannot.

A difference is not yet permission to act

Consider a desired server with eight allocated vCPUs:

  1. The workspace build publishes desired CPU 8.
  2. An independent provider read reports CPU 4, with its identity, source and read time.
  3. Reconciliation checks that the resource and field are managed, the meanings match, and the evidence is authoritative and fresh.
  4. A finding explains the mismatch. Workspace and deployment policy determine whether to report it or offer an approval workflow.
  5. An approved correction uses frozen configuration and exact inputs through the existing action queue.
  6. A new independent read checks the outcome. The action’s requested value or successful exit is not proof of convergence.

If the evidence becomes stale or the resource identity is uncertain, the next result may be “not enough evidence”, not “resize the server.” A finding identifies a condition; an approval authorizes a specific response. Neither silently rewrites intent.

Close the loop without mixing the records

Collection continues independently of execution. A correction changes the environment; it does not manufacture a successful observation. A matching fresh observation can establish that the compared property now agrees with intent, but it does not by itself establish that all work has stopped.

Possible scoped execution remains held until a qualifying independent read supplies state plus both provider and runner terminal assertions. Runner terminality covers the root process, descendants and resumable work. This distinguishes convergence, execution finality and successful execution: a terminal failed job can be finished without having achieved the desired result.

The loop does not adopt provider values into CSV assets, infer permission to delete unexpected resources, or retry uncertain mutations. Changing intent remains an explicit workspace change.

Put the model to work