errors.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/registry/source_migrations/errors.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/test_source_migrate_runner.py"
"""
The migrate refusal exception class (Plan 142m).
 
Purpose
-------
Carry every migrate-specific §8 refusal code on ONE exception type that
subclasses ``SourceError`` **directly** — never ``SourceScanError`` /
``SourceValidationError`` — so ``exit_code_for``'s exit-1 short-circuit
(``isinstance(error, (SourceScanError, SourceValidationError))``, ``envelope.py``)
does NOT fire, and the ten migrate codes route through the ``code in
_EXIT_BY_CODE`` branch to **exit 2**. A plain ``Exception`` subclass would escape
the pinned ``(SourceError, RegenerateError)`` handler catch as an uncaught
traceback, so ``SourceError`` is the load-bearing base.
 
Beyond the base ``code``/``records``/``hint`` the class carries the migrate
recovery/hash channel the handler passes EXPLICITLY to ``build_envelope`` (the
recovery keys are never ``getattr``-read inside ``build_envelope``): the per-phase
``raw_source_tree_hash``/``source_hash`` basis (the failure-stage table) and the
post-write ``rollback``/``journal_path``/``remaining_paths``/``journal_unresolved``
fields.
 
Responsibilities
----------------
- Define ``MigrateError`` carrying the §8 code + the per-phase hash basis + the
  post-write recovery channel.
 
Contracts
---------
- Subclasses ``SourceError`` DIRECTLY (never the two exit-1 leaf classes).
- Recovery fields are set by the runner and passed EXPLICITLY to ``build_envelope``.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - refusal construction lifecycle
    L3 - refusal code context
    L4 - module load
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.source.errors (the SourceError base)
"""
from __future__ import annotations
 
from typing import Optional, Sequence
 
from oc_diagnostics import _dbg
 
from oc_chat.registry.source.errors import SourceError
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
 
class MigrateError(SourceError):
    """A ``roadmap source migrate`` refusal (§8) — subclasses ``SourceError``
    DIRECTLY so ``exit_code_for`` routes its ``SRC_*`` code via ``_EXIT_BY_CODE``
    to exit 2 (never the SourceScan/SourceValidation exit-1 short-circuit).
 
    ``raw_source_tree_hash``/``source_hash`` carry the failure-stage hash basis;
    ``rollback``/``journal_path``/``remaining_paths``/``journal_unresolved`` carry
    the post-write recovery state — all read by the handler and passed EXPLICITLY
    to ``build_envelope`` (never getattr'd inside it).
    """
 
    def __init__(
        self,
        message: str,
        *,
        code: str,
        records: Optional[Sequence[str]] = None,
        hint: Optional[str] = None,
        raw_source_tree_hash: Optional[str] = None,
        source_hash: Optional[str] = None,
        rollback: Optional[str] = None,
        journal_path: Optional[str] = None,
        remaining_paths: Optional[Sequence[str]] = None,
        journal_unresolved: Optional[bool] = None,
    ) -> None:
        func = "MigrateError.__init__"
        super().__init__(message, code=code, records=records, hint=hint)
        self.raw_source_tree_hash = raw_source_tree_hash
        self.source_hash = source_hash
        self.rollback = rollback
        self.journal_path = journal_path
        self.remaining_paths: Optional[list[str]] = (
            list(remaining_paths) if remaining_paths is not None else None
        )
        self.journal_unresolved = journal_unresolved
        _dbg("OC_CHAT.MAIN", func, f"migrate refusal {code}", 3)
 
 
__all__ = ["MigrateError"]