---
title: "State Registry — KYE Protocol™"
description: "State as a first-class primitive in KYE Protocol™: every entity carries a registered state machine; every transition is evidence-guarded and append-only"
url: https://kyeprotocol.com/state-registry/
lang: en
source: "KYE Protocol"
---

> State as a first-class primitive in KYE Protocol™: every entity carries a registered state machine; every transition is evidence-guarded and append-only

KYE Protocol™ · State Registry

# State is a first-class primitive in KYE™.

Every entity in KYE Protocol™ carries a `state` field driven by a registered state machine. You declare the machine once; KYE™ enforces it on every transition, guards it with evidence, logs it append-only, and checks it before every decision.

1 · The model

## One `state` field. One registered machine.

Each entity record carries three state-related fields. The machine is the source of truth for which transitions are valid and what evidence is required to make them.

### `state`

The current lifecycle value. A string from the machine's declared state set (e.g., `active`, `suspended`, `revoked`).

### `state_machine_id`

A `kye:sm:…` URN identifying the machine that governs this entity (e.g., `kye:sm:kyeprotocol.com:core.principal.v1`).

### `state_machine_version`

The semver of the machine at adoption time. Pinned — the entity continues to use that version even after the library publishes a newer one.

The machine itself declares states (with stability classes: `transient`, `stable`, `terminal`) and transitions (with source state, target state, and evidence class). A `terminal` state has no outbound transitions.

2 · State events

## Every transition appends a signed record.

State events are append-only. No record is ever updated or deleted. This makes the full lifecycle of any entity auditable at any point in time.

| Field | Description |
| --- | --- |
| `entity_id` | The entity that transitioned |
| `from_state` | State before the transition |
| `to_state` | State after the transition |
| `transition_id` | The declared transition in the registered machine |
| `triggered_by` | The principal or system that triggered the event |
| `evidence_ref` | Reference to the evidence pack that satisfied the transition guard |
| `recorded_at` | ISO 8601 timestamp (UTC) |

3 · Decision Engine check

## State preconditions are checked before every allow.

Before the Decision Engine issues an allow, it checks that the actor, subject, and resource are all in a state that permits the proposed action class. A suspended actor cannot act. A revoked resource cannot be accessed.

- **Actor check.** The Principal (or Model / Tool / External App) making the request must be in a state that the machine marks as action-eligible (typically `active` or `limited`).
- **Resource check.** The Resource being acted upon must be in a state that permits the requested action class.
- **Policy Bundle check.** The governing Policy Bundle must itself be in `active` state.
- **State mismatch = deny.** If any of the three checks fails, the Decision Engine emits a deny with reason code `state_precondition_not_met` and seals the Decision Map™.

The check and its outcome are recorded in the Decision Map™ and included in the Evidence Pack™. Auditors can replay the state snapshot at decision time.

4 · State Library

## Start from a reference machine, not from scratch.

The KYE™ State Library™ publishes 30 signed, open-source reference machines across 9 regulated industries. You adopt by reference and derive tighter variants where your regulator demands it.

- Adoption pins a library entry version to your entity class.
- Derivation lets you add states and tighten guards — you cannot loosen them.
- Derived machines record the parent entry ID and carry your tenant's signature.

[Explore the KYE™ State Library™ →](https://kyeprotocol.com/state-library/)

Canonical KYE™ surfaces referenced on this page: [Evidence Pack™](https://kyeprotocol.com/evidence-pack/) · [KYE Protocol™](https://kyeprotocol.com/).