Skip to main content

Status and state

This page summarizes the states users will most often encounter.

Session status​

The public session contract exposes these session statuses:

  • SESSION_STATUS_ACTIVE
  • SESSION_STATUS_ARCHIVING
  • SESSION_STATUS_ARCHIVED
  • SESSION_STATUS_HYDRATING
  • SESSION_STATUS_PENDING_REVIEW
  • SESSION_STATUS_CONFLICT
  • SESSION_STATUS_PENDING_APPROVAL

How to interpret session status​

SESSION_STATUS_ACTIVE​

The session is ready for normal work.

SESSION_STATUS_ARCHIVING​

The session is being moved out of its active state. Treat it as transitional.

SESSION_STATUS_ARCHIVED​

The session is no longer fully active and may need to be reactivated before interactive work continues.

SESSION_STATUS_HYDRATING​

The session is transitioning back into a ready state. Clients should expect a short wait rather than assuming permanent failure.

SESSION_STATUS_PENDING_REVIEW​

The workflow is waiting on review state. This is a strong signal that the next action should be inspection, not mutation.

SESSION_STATUS_CONFLICT​

The session cannot be treated as cleanly promotable without conflict handling. Clients should show this state prominently.

SESSION_STATUS_PENDING_APPROVAL​

The session is paused behind an explicit approval gate.

Health status​

The public health contract exposes:

  • STATUS_UNKNOWN
  • STATUS_PASSING
  • STATUS_FAILING

Interpretation:

  • unknown means no useful health report has been recorded yet
  • passing means the last reported test run succeeded
  • failing means the last reported test run had failures

Source status​

The public source contract exposes:

  • UNDERLAY_SOURCE_STATUS_CREATING
  • UNDERLAY_SOURCE_STATUS_READY
  • UNDERLAY_SOURCE_STATUS_FAILED
  • UNDERLAY_SOURCE_STATUS_DELETING

Treat READY as the only normal steady state for user-facing workflows.

Source job state​

Import and promotion workflows expose job states:

  • UNDERLAY_IMPORT_JOB_STATE_QUEUED
  • UNDERLAY_IMPORT_JOB_STATE_RUNNING
  • UNDERLAY_IMPORT_JOB_STATE_SUCCEEDED
  • UNDERLAY_IMPORT_JOB_STATE_FAILED

These states should be shown as asynchronous workflow progress, not as session health.

Design guidance​

Do not flatten all of these into one generic “status” label in a UI.

They belong to different layers:

  • session status describes workspace lifecycle
  • health status describes quality/test state
  • source status describes reusable baseline readiness
  • job state describes asynchronous operation progress