cleveragents-core/tools/controller/contracts/causes.py

"""Controlled vocabulary for ``controller_events.cause`` attribution.

The ``cause`` column on ``controller_events`` disambiguates events whose
``event_type`` alone could have multiple legitimate sources — e.g.
``label-pause`` can be emitted by reconciliation reacting to a human
pulling the opt-in label OR by defer performing a controller-driven
pause. Telemetry queries that need to separate these (cost attribution,
audit forensics) filter on ``cause``.

Events whose ``event_type`` already uniquely identifies the trigger
(e.g. ``estimator_done`` — only the estimator emits it) leave
``cause = NULL``.

This module is dependency-free (stdlib ``enum`` only). All insert sites
import this enum and pass enum members, not bare strings, so an
introduced typo fails at import time rather than as a silently-NULL
column in production.

See ``.drew/regressions-plan.md`` — "``cause`` enum" section and
decisions #23 and #32.
"""

from __future__ import annotations

from enum import StrEnum


class Cause(StrEnum):
    """Why a ``controller_events`` row was written.

    ``StrEnum`` (stdlib, 3.11+) makes each member a real ``str``
    instance whose ``__str__`` returns its value, so members serialise
    correctly through ``sqlite3`` parameter binding without an explicit
    ``.value`` access at every insert site — ``f"{Cause.GROOMING_DEFER}"``
    and ``str(Cause.GROOMING_DEFER)`` both yield ``"grooming_defer"``.
    """

    # Grooming gate (Phase 0/1) — defer vs close attribution on
    # events whose event_type doesn't uniquely identify the gate.
    GROOMING_DEFER = "grooming_defer"
    GROOMING_CLOSE = "grooming_close"

    # Estimator gate (Phase 2) — abandonment decided at ANALYZING.
    ESTIMATOR_ABANDON = "estimator_abandon"

    # Reviewer gate (Phase 3) — abandonment decided at REVIEWING.
    REVIEWER_ABANDON = "reviewer_abandon"

    # Operator manual action — used by the documented clear-deferral
    # SQL and any future operator-driven event insertions.
    OPERATOR = "operator"

    # Reactive detection of a human-initiated change via Forgejo UI
    # (e.g. a human pulls the opt-in label).
    HUMAN = "human"

    # State changes detected by reconciliation (e.g. PR closed
    # externally by someone other than the controller).
    EXTERNAL = "external"

    # Reserved for the Phase 6+ scope-evaluator pipeline that will
    # clear deferrals after re-evaluating deferred PRs.
    SCOPE_EVALUATOR = "scope_evaluator"


__all__ = ["Cause"]