feat(state): Implement State Schema for SEED Architecture (Issue #3)
- Add JSON schema at schemas/state.json with full validation rules - Implement State, StateType, StateMetadata dataclasses in models/state.py - Support immutable state objects with versioning and TTL - Include serialization/deserialization (JSON and dict) - Add next_version() for state history chaining - Comprehensive test suite with 19 tests (100% pass) - Full documentation at docs/state-schema.md Features: - UUID validation for all ID fields - Optimistic locking via version numbers - Flexible payload structure - Metadata support (source, provenance, tags) - Expiration checking via TTL - Complete type hints Closes Issue #3
This commit is contained in:
153
docs/state-schema.md
Normal file
153
docs/state-schema.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user