AgentStateGuard: verify agent state before commit

New in v5.1.0

AgentStateGuard verifies proposed agent state payloads deterministically before any side effects occur. It enforces strict JSON parsing, schema validation, and configurable transition rules to prevent agents from corrupting their own state.

When to use AgentStateGuard

Use AgentStateGuard when your AI agents maintain structured state (such as task lists, workflow progress, or configuration) and you need guarantees that:

State payloads conform to a strict schema before they are persisted
State transitions follow monotonic, immutable, or ordered-enum constraints
Writes to disk are atomic — either fully committed or not written at all

AgentStateGuard was introduced in v5.1.0. It operates entirely in-process, requires no network access or API key, and all verification is deterministic and fail-closed.

How it works

AgentStateGuard uses a three-phase approach:

Structural verification (Phase 1) — Validates that a proposed JSON state payload conforms to a strict schema. Rejects duplicate keys, non-standard JSON constants (NaN, Infinity), and unexpected fields. Numbers are parsed as Decimal to preserve deterministic numeric semantics.
Semantic transition verification (Phase 2) — Verifies that a proposed state transition satisfies configured rules. Immutable paths cannot change, integer paths must increase monotonically, enum paths must advance forward, and keyed arrays must preserve order.
Governed atomic commit (Phase 3) — After verification passes, writes the normalized state to disk atomically using tempfile + os.replace. The write target must be within configured allowed roots and must end in .json.

All three phases are fail-closed — if any check fails, no side effects occur.

Canonicalization and Unicode normalization

Before validation, AgentStateGuard canonicalizes every parsed payload: dict keys are sorted and all string keys and values are normalized to Unicode Normalization Form C (NFC). Precomposed and decomposed spellings of the same text (for example "\u00C9" vs "E\u0301") therefore reduce to the same canonical bytes.

Equivalent Unicode text produces identical verification results. The same payload written with precomposed or decomposed characters yields the same normalized_state and the same proof_ref.

Schema property names, required lists, and enum values are canonicalized the same way at construction time, so a payload key spelled "café" matches a schema property spelled "cafe\u0301". If two distinct keys in the same object collide under NFC, construction (or verification) is rejected with QWED-AGENT-STATE-102 rather than silently dropping data.

Proof references

Every VERIFIED result includes a proof_ref — the SHA-256 hex digest of the canonical evidence payload produced during verification. Because the digest is computed from the canonicalized (NFC-normalized, key-sorted) form, it is stable across equivalent inputs and reproducible by any consumer that recanonicalizes the same data.

verify_state_payload — proof_ref covers {"normalized_state": ...}.
verify_state_transition — proof_ref covers {"normalized_previous_state": ..., "normalized_state": ...}.
verify_transition_and_commit_state — proof_ref is bound to the exact bytes written to disk (the canonical serialization of normalized_state), so it can be recomputed from the committed file. The separate transition_proof_ref covers the transition evidence.

The human-readable sentence that older releases returned as proof now lives in developer_fields.proof_reason and is intended for logs and dashboards. The verified boolean and all method signatures are unchanged.

Usage

Phase 1: structural verification

import json
from qwed_new.guards.agent_state_guard import AgentStateGuard

schema = {
    "type": "object",
    "properties": {
        "agent_id": {"type": "string"},
        "status": {"type": "string", "enum": ["pending", "running", "completed"]},
        "step_count": {"type": "integer"},
        "tasks": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {"type": "string"},
                    "done": {"type": "boolean"},
                },
                "required": ["id", "done"],
                "additionalProperties": False,
            },
        },
    },
    "required": ["agent_id", "status", "step_count", "tasks"],
    "additionalProperties": False,
}

guard = AgentStateGuard(required_schema=schema)

result = guard.verify_state_payload(json.dumps({
    "agent_id": "a1",
    "status": "pending",
    "step_count": 1,
    "tasks": [{"id": "task-1", "done": False}]
}))

print(result["verified"])                       # True
print(result["status"])                         # "VERIFIED"
print(result["proof_ref"])                      # "3f8c…" sha256 of canonical evidence
print(result["developer_fields"]["proof_reason"])  # Human-readable summary
print(result["normalized_state"])               # Keys sorted, strings NFC-normalized

Phase 2: transition verification

guard = AgentStateGuard(
    required_schema=schema,
    transition_rules={
        "immutable_paths": ["$.agent_id"],
        "monotonic_integer_paths": ["$.step_count"],
        "ordered_enum_paths": {
            "$.status": ["pending", "running", "completed"],
        },
        "keyed_object_array_paths": {
            "$.tasks": {
                "key": "id",
                "monotonic_boolean_fields": ["done"],
                "allow_new_items": True,
            }
        },
    },
)

current = json.dumps({
    "agent_id": "a1",
    "status": "pending",
    "step_count": 1,
    "tasks": [{"id": "task-1", "done": False}]
})

proposed = json.dumps({
    "agent_id": "a1",
    "status": "running",
    "step_count": 2,
    "tasks": [
        {"id": "task-1", "done": True},
        {"id": "task-2", "done": False}
    ]
})

result = guard.verify_state_transition(current, proposed)

print(result["verified"])  # True
print(result["normalized_previous_state"]["status"])  # "pending"
print(result["normalized_state"]["status"])            # "running"

Phase 3: atomic commit

guard = AgentStateGuard(
    required_schema=schema,
    transition_rules={
        "immutable_paths": ["$.agent_id"],
        "monotonic_integer_paths": ["$.step_count"],
        "ordered_enum_paths": {
            "$.status": ["pending", "running", "completed"],
        },
        "keyed_object_array_paths": {
            "$.tasks": {
                "key": "id",
                "monotonic_boolean_fields": ["done"],
                "allow_new_items": True,
            }
        },
    },
    allowed_commit_roots=["/var/agent-state"],
)

result = guard.verify_transition_and_commit_state(
    current_state_json=current,
    proposed_state_json=proposed,
    target_path="/var/agent-state/agent_a1.json",
)

if result["verified"]:
    print(result["committed_path"])       # "/var/agent-state/agent_a1.json"
    print(result["committed_bytes"])      # Number of bytes written
    print(result["proof_ref"])            # sha256 of the bytes on disk
    print(result["transition_proof_ref"]) # sha256 covering the transition evidence

The target_path must be an absolute path ending in .json, and its parent directory must already exist. The path must fall within one of the configured allowed_commit_roots.

API reference

`AgentStateGuard(required_schema, transition_rules, allowed_commit_roots)`

Creates a new AgentStateGuard instance. The schema and transition rules are frozen on construction — later mutations to the original dicts have no effect.

dict

required

A strict JSON schema definition. Must include a type field (object, array, string, integer, number, boolean, or null). Object schemas must define properties and may include required and additionalProperties (boolean). Array schemas must define items. Enum constraints use the enum key with a non-empty list.

dict | None

default:"None"

Semantic transition rules. At least one rule must have a non-empty value for transition verification to be enabled. Supported keys are described in the transition rules section.

list[str] | None

default:"None"

List of absolute directory paths where atomic commits are permitted. Required for verify_transition_and_commit_state. Each entry must be an absolute path string.

`verify_state_payload(proposed_state_json)`

Validates a proposed state payload against the configured schema.

str

required

A JSON string representing the proposed agent state. Must be a non-empty string containing valid JSON.

Returns a decision object:

Key	Type	Description
`verified`	`bool`	`True` if the payload passed all structural checks
`status`	`str`	`"VERIFIED"` or `"BLOCKED"`
`proof_ref`	`str`	SHA-256 hex digest of the canonical evidence payload (on success)
`developer_fields`	`dict`	Human-readable diagnostics (`proof_reason`) intended for logs and dashboards (on success)
`normalized_state`	`dict`	The canonicalized payload — dict keys sorted, string keys and values NFC-normalized (on success)
`error_code`	`str`	Error code (on failure)
`message`	`str`	Human-readable error description (on failure)

`verify_state_transition(current_state_json, proposed_state_json)`

Validates a state transition against both structural and semantic rules.

str

required

JSON string representing the current agent state.

str

required

JSON string representing the proposed new agent state.

Returns a decision object with the same fields as verify_state_payload, plus:

Key	Type	Description
`normalized_previous_state`	`dict`	The canonicalized current state (on success)

`verify_transition_and_commit_state(current_state_json, proposed_state_json, target_path)`

Verifies the transition and atomically writes the normalized state to disk if verification passes.

str

required

JSON string representing the current agent state.

str

required

JSON string representing the proposed new agent state.

str

required

Absolute path to the target .json file. The parent directory must exist, and the path must fall within a configured allowed_commit_roots directory.

Returns a decision object with the same fields as verify_state_transition, plus:

Key	Type	Description
`committed_path`	`str`	Absolute path where the state was written (on success)
`committed_bytes`	`int`	Number of bytes written (on success)
`transition_proof_ref`	`str`	SHA-256 hex digest covering the transition evidence (`normalized_previous_state` + `normalized_state`) (on success)

The top-level proof_ref on this method is bound to the exact bytes written to disk — the SHA-256 of the canonical serialization of normalized_state. Any consumer with access to the committed file can recompute and verify it without replaying the transition.

Transition rules

Transition rules define semantic constraints that must hold between the current and proposed state. All paths use dot-style JSON path notation starting with $..

`immutable_paths`

A list of paths whose values must not change between states.

"immutable_paths": ["$.agent_id", "$.created_at"]

`monotonic_integer_paths`

A list of paths whose integer values must never decrease.

"monotonic_integer_paths": ["$.step_count", "$.version"]

`ordered_enum_paths`

A dictionary mapping paths to ordered lists of allowed values. The value at each path must advance forward (or stay the same) in the list — it cannot move backward.

"ordered_enum_paths": {
    "$.status": ["pending", "running", "completed"]
}

`keyed_object_array_paths`

A dictionary mapping array paths to rules for keyed object arrays. Each rule specifies:

Key	Type	Required	Default	Description
`key`	`str`	Yes	—	The field used to identify each object in the array
`monotonic_boolean_fields`	`list[str]`	No	`[]`	Boolean fields that can transition from `false` to `true` but never back
`allow_new_items`	`bool`	No	`true`	Whether new items can be appended to the array

Existing items must preserve their order and cannot be removed. All non-boolean fields on existing items are immutable.

"keyed_object_array_paths": {
    "$.tasks": {
        "key": "id",
        "monotonic_boolean_fields": ["done"],
        "allow_new_items": True,
    }
}

Error codes

Code	Phase	Description
`QWED-AGENT-STATE-101`	1	Input is not a non-empty JSON string
`QWED-AGENT-STATE-102`	1	Invalid JSON (syntax error, duplicate keys, non-standard constants, or two keys that collide under Unicode NFC normalization)
`QWED-AGENT-STATE-103`	1	Schema validation failed (missing keys, wrong types, unexpected fields)
`QWED-AGENT-STATE-104`	2	Transition rules not configured or all rules are empty
`QWED-AGENT-STATE-105`	2	Current state failed structural verification
`QWED-AGENT-STATE-106`	2	Transition rule violation (immutable path changed, value regressed, etc.)
`QWED-AGENT-STATE-107`	3	Commit target validation failed (no allowed roots, invalid path, outside roots)
`QWED-AGENT-STATE-108`	3	Atomic file write failed

Security considerations

Strict JSON parsing: Duplicate keys and non-standard constants (NaN, Infinity, -Infinity) are rejected. Numbers are parsed as Decimal to avoid floating-point non-determinism.
Unicode canonicalization: All string keys and values are normalized to NFC before validation, so precomposed and decomposed spellings of the same text cannot smuggle divergent hashes past the guard. Objects containing two keys that collide under NFC are rejected rather than silently merged.
Reproducible proof references: proof_ref is a SHA-256 over the canonical evidence payload, so any consumer can independently recompute and verify it. For committed state, proof_ref is bound to the exact bytes on disk.
Frozen configuration: Schemas and transition rules are deeply frozen on construction using MappingProxyType and tuples. Callers cannot mutate the guard’s configuration after initialization.
Fail-closed design: Every method returns a BLOCKED decision object on failure — no exceptions leak past the public API unless the constructor arguments themselves are invalid.
Path traversal prevention: Commit targets are resolved to absolute paths and validated against the allowed_commit_roots allowlist. Only .json file extensions are permitted.
Atomic writes: State files are written via tempfile.NamedTemporaryFile followed by os.replace, which is atomic on POSIX systems. The temporary file is cleaned up even if the rename fails.
Depth limit: Schema validation enforces a maximum recursion depth of 64 to prevent stack overflow from deeply nested payloads.

Next steps

StateGuard

Workspace rollback using shadow git snapshots

Agent verification

Pre-execution verification for AI agents

SDK guards

All available security guards

Attestations

Cryptographic proof of verification

Production path

Deployment

CI/CD

Security & Compliance

AgentStateGuard: verify agent state before commit

When to use AgentStateGuard

How it works

Canonicalization and Unicode normalization

Proof references

Usage

Phase 1: structural verification

Phase 2: transition verification

Phase 3: atomic commit

API reference

`AgentStateGuard(required_schema, transition_rules, allowed_commit_roots)`

`verify_state_payload(proposed_state_json)`

`verify_state_transition(current_state_json, proposed_state_json)`

`verify_transition_and_commit_state(current_state_json, proposed_state_json, target_path)`

Transition rules

`immutable_paths`

`monotonic_integer_paths`

`ordered_enum_paths`

`keyed_object_array_paths`

Error codes

Security considerations

Next steps

StateGuard

Agent verification

SDK guards

Attestations

​When to use AgentStateGuard

​How it works

​Canonicalization and Unicode normalization

​Proof references

​Usage

​Phase 1: structural verification

​Phase 2: transition verification

​Phase 3: atomic commit

​API reference

​AgentStateGuard(required_schema, transition_rules, allowed_commit_roots)

​verify_state_payload(proposed_state_json)

​verify_state_transition(current_state_json, proposed_state_json)

​verify_transition_and_commit_state(current_state_json, proposed_state_json, target_path)

​Transition rules

​immutable_paths

​monotonic_integer_paths

​ordered_enum_paths

​keyed_object_array_paths

​Error codes

​Security considerations

​Next steps

StateGuard

Agent verification

SDK guards

Attestations

When to use AgentStateGuard

How it works

Canonicalization and Unicode normalization

Proof references

Usage

Phase 1: structural verification

Phase 2: transition verification

Phase 3: atomic commit

API reference

`AgentStateGuard(required_schema, transition_rules, allowed_commit_roots)`

`verify_state_payload(proposed_state_json)`

`verify_state_transition(current_state_json, proposed_state_json)`

`verify_transition_and_commit_state(current_state_json, proposed_state_json, target_path)`

Transition rules

`immutable_paths`

`monotonic_integer_paths`

`ordered_enum_paths`

`keyed_object_array_paths`

Error codes

Security considerations

Next steps