Lifecycle
Position Object lifecycle: states, transitions, events, and immutability.
Overview
Every Position Object progresses through a defined lifecycle. States represent the position's stage from creation to exit. Transitions are governed by rules and events. Understanding the lifecycle is essential for building workflows and interpreting position state.
All state transitions produce immutable events. You can replay a position's full history from its events array alone.
Lifecycle states
Stable draft — The position is being created or edited. Not yet registered. Draft positions are not queryable in the canonical Registry and do not participate in transfers.
Stable registered — The position has been registered in the Registry. It is now part of the authoritative record. May transition to active once all onboarding is complete.
Stable active — The position is fully active. The allocator holds beneficial ownership. Transfers and encumbrances are permitted subject to restrictions.
Stable encumbered — The position has one or more encumbrances (lien, pledge, hold). Transferability may be restricted. The position remains in active use but with constraints.
Stable transferred — The position has been transferred. The previous allocator no longer holds it; the new allocator does. The original position record is closed; a new position is created for the transferee.
Stable exited — The position has been exited (redemption, distribution, or other exit). The allocator no longer holds the position. The record is closed.
Stable voided — The position has been voided (error, cancellation, or invalidation). Voided positions are retained for audit but do not participate in operations.
Interactive lifecycle timeline
This timeline shows a real position progressing through its lifecycle. Expand each event to see the full payload.
Lifecycle Timeline
Position state transitions over time
State transitions
Valid transitions follow defined rules. Invalid transitions are rejected by the Registry.
| From | To | Trigger |
|---|---|---|
draft | registered | register — position passes validation |
draft | voided | void — position cancelled before registration |
registered | active | activate — onboarding complete, KYC cleared |
active | encumbered | place_lien — lien, pledge, or hold placed |
encumbered | active | release_lien — all encumbrances released |
active | transferred | execute_transfer — transfer completes |
active | exited | exit — redemption, distribution, or wind-down |
Gotcha: A position in encumbered state cannot be directly transferred. The encumbrance must first be released (transition back to active), then the transfer can execute. This is enforced by the Rights Engine.
Events
Events record lifecycle changes. Each event has:
event_id— Unique identifiertype— Event type (e.g.,position.registered,position.transferred)timestamp— ISO 8601 timestampactor— Who or what triggered the event (user ID, service name, orsystem)payload— Event-specific data (transition details, transfer context, etc.)
Events are immutable and append-only. They form the complete audit trail for regulatory compliance and dispute resolution.
Immutability
Past state is immutable. When a position transitions, the previous state is preserved. Mutations produce new event records; they never overwrite history. This design supports:
- Audit compliance — Full provenance chain from draft to exit
- Dispute resolution — Reconstruct state at any point in time
- Event sourcing — Rebuild current state from events alone
Related
- Position Object — Schema and structure
- Registry — Stores position state
- Event Schemas — Lifecycle event payloads