Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(models): canonical status vocabulary + RunLifecycleMixin (plan 77 D1/D2)

Juan Denis1b49352f2764
diff --git a/backend/app/models/mixins.py b/backend/app/models/mixins.py
index 4b0410ab..5f066a38 100644
--- a/backend/app/models/mixins.py
+++ b/backend/app/models/mixins.py
@@ -31,6 +31,7 @@ import uuid
from datetime import datetime
from app import db
+from app.models import status as _status
logger = logging.getLogger(__name__)
@@ -196,3 +197,61 @@ class TimestampMixin:
def updated_at(cls): # noqa: N805
return db.Column(db.DateTime, default=datetime.utcnow,
onupdate=datetime.utcnow)
+
+
+class RunLifecycleMixin:
+ """State transitions for run-shaped models (plan 77 D2).
+
+ Ten run models hand-write ``status`` + ``started_at``/``completed_at``
+ (+ duration) transitions today; this mixin is the one place they happen::
+
+ job.mark_running()
+ job.mark_succeeded() # or mark_failed(error=...), mark_cancelled()
+
+ Status spellings come from models/status.py. A domain still storing a
+ legacy spelling (e.g. deployment jobs' 'succeeded') overrides the class
+ attributes below until its per-domain data migration lands — adoption
+ must NOT silently change stored strings.
+
+ Column-name variance is absorbed, not forced: completed-at goes to
+ ``__completed_at_attr__`` (default 'completed_at'; set 'finished_at'
+ where that is the column), and a duration is stored only when the model
+ actually has a 'duration_seconds' or 'duration' COLUMN (properties are
+ left alone).
+ """
+
+ __status_running__ = _status.RUNNING
+ __status_success__ = _status.SUCCESS
+ __status_failed__ = _status.FAILED
+ __status_cancelled__ = _status.CANCELLED
+ __completed_at_attr__ = 'completed_at'
+
+ def mark_running(self, when=None):
+ self.status = self.__status_running__
+ self.started_at = when or datetime.utcnow()
+ return self
+
+ def mark_succeeded(self, when=None):
+ return self._finish(self.__status_success__, when)
+
+ def mark_failed(self, error=None, when=None):
+ self._finish(self.__status_failed__, when)
+ if error is not None and 'error' in self.__table__.columns:
+ self.error = str(error)
+ return self
+
+ def mark_cancelled(self, when=None):
+ return self._finish(self.__status_cancelled__, when)
+
+ def _finish(self, status, when=None):
+ when = when or datetime.utcnow()
+ self.status = status
+ if self.__completed_at_attr__ in self.__table__.columns:
+ setattr(self, self.__completed_at_attr__, when)
+ started = getattr(self, 'started_at', None)
+ if started is not None:
+ for dattr in ('duration_seconds', 'duration'):
+ if dattr in self.__table__.columns:
+ setattr(self, dattr, (when - started).total_seconds())
+ break
+ return self
diff --git a/backend/app/models/status.py b/backend/app/models/status.py
new file mode 100644
index 00000000..222ffe27
--- /dev/null
+++ b/backend/app/models/status.py
@@ -0,0 +1,59 @@
+"""The ONE status vocabulary for run-shaped models (plan 77 D1).
+
+The same terminal state has historically been spelled four ways across run
+models (``success`` in cron_run/backup_run, ``completed`` in db_snapshot and
+environment_activity, ``done`` in sandbox runs, ``succeeded`` in deployment
+jobs). New columns and API filters import these constants; existing domains
+keep their stored spelling until their own per-domain data migration lands
+(changing stored strings wholesale is explicitly out of scope — each domain
+migrates deliberately, smallest tables first) and normalize at the read edge
+via :func:`normalize`.
+
+RunLifecycleMixin (models/mixins.py) writes these constants for adopters,
+with per-model overrides for domains still on a legacy spelling.
+"""
+
+PENDING = 'pending'
+QUEUED = 'queued'
+RUNNING = 'running'
+SUCCESS = 'success'
+FAILED = 'failed'
+CANCELLED = 'cancelled'
+
+#: States a run can never leave.
+TERMINAL = frozenset({SUCCESS, FAILED, CANCELLED})
+
+#: States describing a run that has not finished.
+ACTIVE = frozenset({PENDING, QUEUED, RUNNING})
+
+ALL = frozenset({PENDING, QUEUED, RUNNING, SUCCESS, FAILED, CANCELLED})
+
+#: Every legacy spelling measured in the 2026-08-18 audit, mapped to its
+#: canonical constant. Domain-specific *phase* states (``analyzing``,
+#: ``verifying``, ``rolled_back``, …) are not lifecycle spellings and pass
+#: through :func:`normalize` unchanged.
+LEGACY_ALIASES = {
+ 'succeeded': SUCCESS,
+ 'completed': SUCCESS,
+ 'done': SUCCESS,
+ 'failure': FAILED,
+ 'error': FAILED,
+ 'canceled': CANCELLED,
+ 'scheduled': QUEUED,
+}
+
+
+def normalize(value):
+ """Map a stored status string to its canonical spelling.
+
+ Canonical values and unknown domain-specific states return unchanged;
+ only known legacy aliases are rewritten. ``None`` stays ``None``.
+ """
+ if not value:
+ return value
+ return LEGACY_ALIASES.get(value, value)
+
+
+def is_terminal(value) -> bool:
+ """True when the (possibly legacy-spelled) status is a terminal state."""
+ return normalize(value) in TERMINAL
diff --git a/backend/tests/test_status_vocabulary.py b/backend/tests/test_status_vocabulary.py
new file mode 100644
index 00000000..5246d7dc
--- /dev/null
+++ b/backend/tests/test_status_vocabulary.py
@@ -0,0 +1,90 @@
+"""Plan 77 D1/D2 — canonical status vocabulary + run lifecycle transitions.
+
+Parity gate: every status spelling a run model writes today is either a
+canonical constant or a known legacy alias that normalize() maps home.
+"""
+import pytest
+
+from app.models import status as st
+
+
+MEASURED_LIFECYCLE_SPELLINGS = {
+ # canonical
+ 'pending', 'queued', 'running', 'success', 'failed', 'cancelled',
+ # legacy terminal spellings measured across run models (2026-08-18 audit)
+ 'succeeded', 'completed', 'done', 'failure', 'error', 'canceled',
+ 'scheduled',
+}
+
+
+def test_every_measured_lifecycle_spelling_normalizes_to_canonical():
+ for spelling in MEASURED_LIFECYCLE_SPELLINGS:
+ assert st.normalize(spelling) in st.ALL, spelling
+
+
+def test_terminal_set_and_aliases():
+ assert st.is_terminal('succeeded')
+ assert st.is_terminal('done')
+ assert st.is_terminal('failure')
+ assert not st.is_terminal('running')
+ assert not st.is_terminal('analyzing') # domain phase, passes through
+
+
+def test_normalize_passes_domain_states_through():
+ assert st.normalize('rolled_back') == 'rolled_back'
+ assert st.normalize(None) is None
+ assert st.normalize('') == ''
+
+
+def test_run_lifecycle_mixin_transitions(app):
+ from app import db
+ from app.models.mixins import RunLifecycleMixin
+
+ class _FakeRun(RunLifecycleMixin):
+ # stand-in with the standard columns; __table__ faked via a dict
+ class _T:
+ columns = {'status': None, 'started_at': None,
+ 'completed_at': None, 'duration_seconds': None,
+ 'error': None}
+ __table__ = _T()
+ status = None
+ started_at = None
+ completed_at = None
+ duration_seconds = None
+ error = None
+
+ run = _FakeRun()
+ run.mark_running()
+ assert run.status == st.RUNNING and run.started_at is not None
+
+ run.mark_succeeded()
+ assert run.status == st.SUCCESS
+ assert run.completed_at is not None
+ assert run.duration_seconds is not None and run.duration_seconds >= 0
+
+ run2 = _FakeRun()
+ run2.mark_running()
+ run2.mark_failed(error='boom')
+ assert run2.status == st.FAILED and run2.error == 'boom'
+
+ run3 = _FakeRun()
+ run3.mark_cancelled()
+ assert run3.status == st.CANCELLED
+
+
+def test_legacy_spelling_override(app):
+ from app.models.mixins import RunLifecycleMixin
+
+ class _LegacyRun(RunLifecycleMixin):
+ __status_success__ = 'succeeded' # domain not yet data-migrated
+ class _T:
+ columns = {'status': None, 'completed_at': None}
+ __table__ = _T()
+ status = None
+ started_at = None
+ completed_at = None
+
+ run = _LegacyRun()
+ run.mark_succeeded()
+ assert run.status == 'succeeded'
+ assert st.normalize(run.status) == st.SUCCESS