electra-archon/docs/state-schema.md

SEED State Schema Documentation

Overview

The State Schema defines the structure for persisting and managing state within the SEED (State-Event-Entity-Domain) architecture. Each state record represents a snapshot of an entity at a specific point in time.

Schema Design

Core Fields

Field	Type	Required	Description
id	UUID	Yes	Unique identifier for this state record
entity_id	UUID	Yes	Reference to the entity this state belongs to
state_type	Enum	Yes	Classification: active, inactive, pending, archived, deleted
payload	Object	Yes	Flexible JSON containing state-specific data
timestamp	ISO 8601	Yes	When this state was recorded
version	Integer	Yes	Version number for optimistic locking (>= 1)
metadata	Object	No	Additional metadata (source, provenance, tags)
previous_state_id	UUID	No	Reference to previous state (for history chain)
ttl	Integer	No	Time-to-live in seconds

State Types

• active: Entity is currently active and operational
• inactive: Entity is temporarily inactive
• pending: Entity is in a pending/waiting state
• archived: Entity has been archived
• deleted: Entity has been marked for deletion

Metadata Structure

{
  "source": "service-name",
  "provenance": "trace-id",
  "created_by": "user-or-service",
  "tags": ["tag1", "tag2"]
}

Python Model

Basic Usage

from models.state import State, StateType, StateMetadata
import uuid

# Create a new state
state = State.create(
    entity_id=str(uuid.uuid4()),
    state_type=StateType.ACTIVE,
    payload={"status": "running", "progress": 75},
    metadata=StateMetadata(
        source="electra-archon",
        created_by="electra",
        tags=["seed", "priority"]
    )
)

# Serialize to JSON
json_str = state.to_json(indent=2)

# Deserialize from JSON
restored_state = State.from_json(json_str)

Versioning

# Create next version of a state
next_state = state.next_version({"status": "running", "progress": 90})
print(next_state.version)  # 2
print(next_state.previous_state_id)  # Original state ID

Validation

The model validates:

• UUID format for all ID fields
• Version is >= 1
• TTL is non-negative if specified
• State type is valid enum value

Indexes

For optimal performance, the following indexes are recommended:

CREATE INDEX idx_state_entity_id ON states(entity_id);
CREATE INDEX idx_state_timestamp ON states(timestamp);
CREATE INDEX idx_state_type ON states(state_type);
CREATE INDEX idx_state_entity_version ON states(entity_id, version);

JSON Schema

The full JSON Schema is available at schemas/state.json. It can be used for:

• API request/response validation
• Documentation generation
• Client code generation

Example State Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "state_type": "active",
  "payload": {
    "status": "running",
    "progress": 75,
    "details": {
      "last_action": "processing",
      "queue_position": 3
    }
  },
  "timestamp": "2026-04-02T19:30:00Z",
  "version": 3,
  "metadata": {
    "source": "electra-archon",
    "provenance": "trace-abc123",
    "created_by": "electra",
    "tags": ["seed", "priority"]
  },
  "previous_state_id": "550e8400-e29b-41d4-a716-446655440001",
  "ttl": null
}

Testing

Run the test suite:

pytest tests/test_state.py -v

Integration with SEED Architecture

The State component works with:

• Entity: States reference entities via entity_id
• Event: State changes can emit events
• Domain: Business logic determines state transitions

Future Enhancements

• Compression for large payloads
• Encryption for sensitive data
• State transition validation rules
• Bulk state operations
• State snapshot/restore functionality