Allegro
bcf8c31270
- 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
154 lines
3.9 KiB
Markdown
154 lines
3.9 KiB
Markdown
# 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
|