Core Concepts

StateAnchor is built on a small number of precise concepts. Understanding them makes the entire system predictable. This page defines each concept formally.

Desired-state control plane

StateAnchor is a desired-state control plane for APIs. You declare what your API should be in stateanchor.yaml. StateAnchor continuously reconciles reality against that declaration — detecting when code, runtime, or generated artifacts diverge from it.

This is the same pattern Kubernetes uses for infrastructure: you declare desired state, controllers reconcile toward it, and status reports the difference. StateAnchor applies this to APIs.

The three planes

StateAnchor separates concerns into three planes. They must never be conflated.

Desired-state plane

stateanchor.yaml → canonical IR. This is the only authoritative source. Nothing writes back to this plane automatically. Only human git commits modify it.

Observation plane

Source scanners, runtime probes, deployed-spec comparison. Observational only. Never authoritative. Observations surface warnings but never block without deterministic backing.

Derivation plane

SDKs, MCP servers, docs, OpenAPI specs. Derived from the desired-state plane only. Never become source of truth. If a derived artifact diverges, the system regenerates — it never modifies the spec to match the artifact.

Intermediate Representation (IR)

The IR is a canonical, structured JSON model of your API derived from stateanchor.yaml. It normalizes endpoints, models, auth, and metadata into a form that generators consume. The IR is the stable internal boundary — generators never read the raw YAML directly.

The IR is stored on every completed sync_run. This creates a timeline of your API's structural evolution. Diffs are computed between consecutive IRs, not between raw YAML files.

Artifact provenance

Every generated artifact carries a provenance record embedded as a comment header:

// @stateanchor-provenance: <base64-encoded JSON>

The provenance contains: source_ir_hash (SHA-256 of the IR that produced it), generator_version, spec_sha (commit that triggered generation), artifact_type, project_id, and generated_at timestamp.

Content-addressed storage

Artifacts are stored by content hash (SHA-256). If two different commits produce identical output, they resolve to the same storage object. This provides deduplication and guarantees that artifacts are immutable — the same hash always returns the same content.

Commit binding

Every sync run is bound to a specific git commit SHA. The commit_sha field on sync_runs records which commit triggered the sync. Artifacts generated from that sync are transitively bound to that commit. You can answer: "what commit produced this SDK version?" for any artifact.

Drift

Drift is a formal, measurable deviation between desired state and observed/derived state. It is NOT a heuristic or approximation. In StateAnchor, drift is a SHA mismatch: the IR hash of the current spec differs from the IR hash of the last completed sync. If they match, there is no drift. If they differ, the diff engine classifies every change.

Drift examples

• Endpoint removed from spec → endpoint_removed (score 40)
• Field type changed → type_changed (score 25)
• New optional field added → field_added_optional (score 0, no drift concern)
• Auth scheme changed → auth_changed (score 35)

Drift velocity

Drift velocity is the rate at which a project's spec changes produce breaking diffs. High drift velocity signals API design instability — endpoints that change frequently are the highest-value StateAnchor users AND the highest retention risk. StateAnchor tracks drift velocity per project for analytics.

Rollback

Rollback in StateAnchor is a pointer move, not a regeneration. Every sync run stores the complete IR and artifact references. Rolling back means pointing the current environment reference to a previous sync run's closure. The artifacts already exist in content-addressed storage — no regeneration needed. This makes rollback instant and deterministic.