state_observer.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_orchestrator/state_observer.py
 
# OCT-LINT: disable=tests_exist reason="Covered by tests/test_270_standalone_dispatch.py (no observers reached) and oc_chat's plan-257 registry-mirror witnesses"
"""
Plan-state observation seam for the dispatch layer.
 
Purpose
-------
Plan 257 P1 (A7, cut 1). The worker status tool used to reach into
``oc_chat.registry`` directly to mirror every ``.PLAN_STATUS.md``
lifecycle event into the orchestration registry. That coupling is the
single largest edge out of the dispatch layer, and it is the one the
orchestrator-extraction measurement keeps having to model as a cut.
 
This module inverts it. The dispatch layer now announces what happened
to a plan and knows nothing about who is listening; the registry side
supplies a listener that does the mirroring. Nothing observable
changes, because the status tool still registers that listener by
default.
 
Responsibilities
----------------
- :class:`StateObserver` -- the callback contract a listener implements.
  Two callbacks, derived from what the status tool actually emits: a
  plan was created, and a plan's status changed.
- :data:`NO_OBSERVERS` -- the empty default, for callers that want the
  dispatch layer to touch nothing but the status file.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events (module load)
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- A callback returns a process exit code: ``0`` when the observation was
  recorded or deliberately skipped, non-zero when the caller should
  abort with that code. This mirrors the pre-257 ``_mirror_*`` helpers
  byte for byte: a mirroring failure is reported and returns ``2``, it
  never raises into the status tool.
- Every argument is a plain string, integer or ``None``. The contract
  carries no dispatch-layer type, so an implementation on the registry
  side needs no import back into ``oc_chat.scripts``.
- This module imports nothing from ``oc_chat.registry`` and nothing
  from ``oc_chat.core`` -- it is a leaf of the dispatch layer.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
 
from __future__ import annotations
 
from typing import Protocol
 
from oc_diagnostics import _dbg
 
_dbg("OC_CHAT.MAIN", "module", "state_observer loaded", 4)
 
 
class StateObserver(Protocol):
    """A listener for the plan-state events the status tool emits."""
 
    def plan_created(
        self,
        *,
        plan_id: str,
        title: str,
        plan_type: str | None,
        body_path: str,
        body_sha256: str,
        body_observed_at: str | None,
        model: str,
        thinking: str,
        session: str,
        branch: str,
        worktree: str,
        target_status: str,
    ) -> int:
        """A ``.PLAN_STATUS.md`` was initialised for *plan_id*."""
 
    def status_changed(
        self,
        *,
        plan_id: str,
        from_status: str,
        to_status: str,
        note: str | None,
    ) -> int:
        """*plan_id* moved from *from_status* to *to_status*."""
 
 
#: The default when a caller wants no observation at all: the dispatch
#: layer writes the status file and reaches nothing else.
NO_OBSERVERS: tuple[StateObserver, ...] = ()
 
 
__all__ = ["NO_OBSERVERS", "StateObserver"]