Status Propagation Rules
========================

The PTT system implements automatic status propagation between related entities following a hierarchical relationship: Project → SBD → SBI → EB.

Entity Relationships
--------------------

The system maintains the following entity hierarchy:

- **Project**: Contains multiple SBDs (one-to-many)
- **SBD (Scheduling Block Definition)**: Contains multiple SBIs (one-to-many)  
- **SBI (Scheduling Block Instance)**: Contains multiple EBs (one-to-many)
- **EB (Execution Block)**: Leaf entity in the hierarchy

Top-Down Propagation
--------------------

Status changes propagate from parent to child entities:

Project Status Changes
~~~~~~~~~~~~~~~~~~~~~~

**Project → "Ready"**
  - All associated SBDs transition to "Ready" state
  - Ensures all scheduling blocks are prepared when project is approved

**Project → "Cancelled"**
  - Associated SBDs move to "Suspended" state
  - Associated SBIs move to "Failed" state  
  - Associated EBs move to "Failed" state
  - Cascades cancellation through entire project hierarchy

Bottom-Up Propagation
---------------------

Status changes propagate from child to parent entities:

EB Status Changes
~~~~~~~~~~~~~~~~~

**EB → "Fully Observed"**
  - Associated SBI transitions to "Observed"
  - Linked SBD transitions to "Observed" 
  - Project transitions to "Observed"
  - Indicates successful completion of observation

**EB → "Failed"**
  - Associated SBI transitions to "Failed"
  - Linked SBD transitions to "Suspended"
  - Project transitions to "Cancelled"
  - Propagates failure up the hierarchy

SBI Status Changes
~~~~~~~~~~~~~~~~~~

**SBI → "Executing"**
  - Associated SBD transitions to "In Progress"
  - Project transitions to "Ready"
  - Indicates active observation execution

Implementation Notes
--------------------

- Status propagation is automatic and immediate
- Changes are logged in the status history
- The system maintains referential integrity during propagation
- All status transitions are auditable through the status history API

Technical Implementation
------------------------

The status propagation system is implemented using PostgreSQL's Ltree extension for efficient hierarchical data management. This approach provides:

- **Hierarchical Path Representation**: Each entity maintains a path showing its position in the hierarchy
- **Efficient Tree Operations**: Fast ancestor/descendant queries using Ltree operators
- **Scalable Performance**: Optimized for large hierarchical datasets
- **ACID Compliance**: Ensures data consistency during propagation

For detailed technical implementation, see the `Status Toy Documentation <https://gitlab.com/bjmc/status-toy/-/blob/main/docs/how_it_works.md>`_ which demonstrates the Ltree-based approach used in this system.

API Endpoints
-------------

Status propagation can be monitored through:

- ``GET /entity/latest/status`` - View current entity statuses
- ``GET /entity/current/status`` - View current status view
- ``PUT /entity/{entity_id}/status`` - Update entity status
- ``GET /entity/history`` - View status change history
- ``GET /entity/status/get_entity`` - Get entity status dictionary
- ``GET /status/stream`` - Real-time status change notifications