# 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

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

## Python Model

### Basic Usage

```python
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

```python
# 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:

```sql
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

```json
{
  "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:

```bash
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