Lifecycle

Entity types can be assigned a lifecycle map via has_lc_map, governing the valid states and transitions of their instances. The lifecycle system controls which entities are considered released, which are read-only, and which state changes are permitted.

Lifecycle Map (lc_map)

A lifecycle map groups a set of lc_status entries and defines the allowed transitions between them.

Field	Description
name	System identifier (key)
label	Localized display name
has_lc_status	The statuses belonging to this lifecycle

Assigning a Lifecycle to an Entity Type

Use has_lc_map on the entity type definition:

"has_lc_map": [
    { "target": "lc_map/EP_Default" }
]

Entities of a type without a lifecycle map have no @status field and are always writable.

Lifecycle Status (lc_status)

A lifecycle status defines a state an entity can be in.

Field	Type	Description
name	string	System identifier (key)
label	localized map	Display name
number	int	Ordering number (used for status transitions via the API)
is_released	bool	Whether entities in this status are considered "released"
is_read_only	bool	Whether new versions of entities in this status may be created
color	string	Hex color for UI display
has_lc_transition	relationships	Valid transitions to other statuses

Transitions (has_lc_transition)

A transition is a relationship instance between two lc_status entities with an optional label edge property. Only transitions explicitly defined via has_lc_transition are permitted -- the engine rejects any status change that does not follow a declared transition path.

The Default Lifecycle: EP_Default

The system provides one built-in lifecycle: lc_map/EP_Default.

Statuses

Status	Number	Released	Read-Only	Color
lc_status/new	0	no	no	#FF0000
lc_status/review	100	no	yes	#FFBB00
lc_status/released	200	yes	yes	#00FF00
lc_status/obsolete	300	no	yes	#DDDDDD

Transition Diagram

stateDiagram-v2
    [*] --> new
    new --> review
    review --> released
    review --> new
    released --> obsolete

Valid transitions: new -> review -> released -> obsolete, and review -> new.

warning

Once an entity reaches the review, released, or obsolete status, it becomes read-only (is_read_only: true). The only status that allows creating new versions is new. To make changes to an entity in review, transition it back to new first.

API Interaction

Reading the Current Status

GET /api/v1/by-key/<type>/<key>/@status

Returns the full entity object for the current lc_status.

Response 200: Status entity object.

Response 404: No lifecycle available for this entity.

Transitioning to a New Status

PUT /api/v1/by-key/<type>/<key>/@status

or

POST /api/v1/by-key/<type>/<key>/@status

The request body is either the status name as a string or the status number:

"review"

or

100

A successful transition creates a new entity version with the updated status.

Response 200: Updated entity object.

Response 400: Invalid status or illegal transition.

Status in Entity Responses

When an entity has a lifecycle map assigned, its response includes the @status field:

{
    "@status": { "name": "new", "number": 0 }
}

If no lifecycle map is assigned, the @status field is absent.

Custom Lifecycle Maps

You can define custom lifecycle maps by creating lc_map and lc_status entities with your own statuses and transitions. The process is:

1. Create lc_status entities for each state.
2. Define has_lc_transition relationships between the statuses.
3. Create a lc_map entity with has_lc_status relationships pointing to the statuses.
4. Assign the lifecycle map to entity types via has_lc_map.