ARCHITECTURE

How StateAnchor works

A deterministic desired-state compiler with observational drift detection and a conservative policy engine. Not a generator. Not a pipeline. Infrastructure.

THE THREE PLANES

Desired state in. Artifacts out. Nothing else.

DESIRED STATE

stateanchor.yaml

Lives in Git. Single authoritative source of truth for your API contract.

GATE ENGINE

ERR . WARN . INFO

Every change classified before anything deploys. Breaking changes blocked automatically.

DERIVED ARTIFACTS

SDKs . MCP . Docs

TypeScript, Python, Go SDKs. MCP server. OpenAPI 3.1. All regenerated on every push from the spec.

DESIRED-STATE PLANE

One authoritative source. Nothing more.

stateanchor.yaml lives in your repo. It is the only authoritative source. Nothing writes back to it automatically. Not scanners. Not runtime probes. Not the gate. The spec is declared. Everything else is derived.

# stateanchor.yaml -- single source of truth
version: "1.0"
api:
  name: acme-billing
  base_url: https://api.acme.dev/v2

endpoints:
  - path: /invoices
    method: GET
    auth: bearer
    response:
      - field: id
        type: string
        required: true
      - field: amount_cents
        type: integer
        required: true
      - field: status
        type: string
        enum: [draft, sent, paid]

  - path: /invoices/:id
    method: DELETE
    auth: bearer
    breaking: true

# OBSERVED STATE
# sa observe --source ./src/routes
scan complete -- 4 sources analysed

endpoints detected:
  GET  /invoices          match
  POST /invoices          match
  DEL  /invoices/:id      match
  GET  /invoices/:id/pdf  NOT IN SPEC

fields:
  invoice.amount_cents    match
  invoice.currency        NOT IN SPEC

warnings: 2
  endpoint not declared: GET /invoices/:id/pdf
  field not declared: invoice.currency

OBSERVATION PLANE

Observe. Never overwrite.

Source scanners and optional runtime probes detect what your live API actually does. This plane is observational only. It surfaces warnings. It informs the gate. It never overwrites the spec and never becomes authoritative.

DERIVATION PLANE

Everything else is an output.

SDKs, your MCP server, OpenAPI 3.1 docs -- all derived from the spec. Never the source of truth. When the spec changes, they rebuild. They are consequences, not causes.

// stateanchor-generated
// spec: 2.1.4 / commit: a3f92c1
// Generated: 2026-04-02T08:14:00Z

export interface Invoice {
  id: string;
  amount_cents: number;
  status: 'draft' | 'sent' | 'paid';
}

export async function listInvoices(
  token: string
): Promise<Invoice[]> {
  const res = await fetch(
    'https://api.acme.dev/v2/invoices',
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return res.json();
}

THE GATE

Conservative by design

Every change is sorted into one of three lanes. Each lane has a fixed behavior that never changes. ERR always blocks. WARN blocks above a configurable threshold. INFO always passes. No composite scores. No tuning until deploys stop breaking. The lane drives the decision.

ERR

Always blocks

Endpoint removed. Required field deleted. Type changed. Auth scheme changed. No threshold. No override without a scoped exception.

Examples: endpoint removed, required field deleted, type changed, auth scheme changed

WARN

Blocks above threshold

Optional field removed. Deprecation violated. Response shape changed. Configurable enforcement per team.

Examples: optional field removed, deprecation violated, response field made required

INFO

Always passes

New endpoint added. Optional field extended. Description changed. Additive changes never block your pipeline.

Examples: new endpoint added, optional field extended, description changed

Ready to anchor your API?

Connect a repo →

Desired state in. Artifacts out. Nothing else.

DESIRED STATE

stateanchor.yaml

Lives in Git. Single authoritative source of truth for your API contract.

GATE ENGINE

ERR . WARN . INFO

Every change classified before anything deploys. Breaking changes blocked automatically.

DERIVED ARTIFACTS

SDKs . MCP . Docs

TypeScript, Python, Go SDKs. MCP server. OpenAPI 3.1. All regenerated on every push from the spec.

# stateanchor.yaml -- single source of truth version: "1.0" api: name: acme-billing base_url: https://api.acme.dev/v2 endpoints: - path: /invoices method: GET auth: bearer response: - field: id type: string required: true - field: amount_cents type: integer required: true - field: status type: string enum: [draft, sent, paid] - path: /invoices/:id method: DELETE auth: bearer breaking: true

# OBSERVED STATE # sa observe --source ./src/routes scan complete -- 4 sources analysed endpoints detected: GET /invoices match POST /invoices match DEL /invoices/:id match GET /invoices/:id/pdf NOT IN SPEC fields: invoice.amount_cents match invoice.currency NOT IN SPEC warnings: 2 endpoint not declared: GET /invoices/:id/pdf field not declared: invoice.currency

// stateanchor-generated // spec: 2.1.4 / commit: a3f92c1 // Generated: 2026-04-02T08:14:00Z export interface Invoice { id: string; amount_cents: number; status: 'draft' | 'sent' | 'paid'; } export async function listInvoices( token: string ): Promise<Invoice[]> { const res = await fetch( 'https://api.acme.dev/v2/invoices', { headers: { Authorization: `Bearer ${token}` } } ); return res.json(); }

Conservative by design

ERR

Always blocks

Endpoint removed. Required field deleted. Type changed. Auth scheme changed. No threshold. No override without a scoped exception.

Examples: endpoint removed, required field deleted, type changed, auth scheme changed

WARN

Blocks above threshold

Optional field removed. Deprecation violated. Response shape changed. Configurable enforcement per team.

Examples: optional field removed, deprecation violated, response field made required

INFO

Always passes

New endpoint added. Optional field extended. Description changed. Additive changes never block your pipeline.

Examples: new endpoint added, optional field extended, description changed