worktree_env.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/worktree_env.py
 
# OCT-LINT: disable=tests_exist reason="Re-export shim plus the oct timing wiring; covered by test_245_engine_timing.py and test_257_dispatcher_seams.py"
"""
Per-worktree uv environments — moved to :mod:`oc_orchestrator.worktree_env`.
 
Purpose
-------
Plan 270 P4. This module's code now lives in the standalone
``oc_orchestrator`` package; this file keeps ``oc_chat.core.worktree_env``
working for every importer that has always spelled it that way, and it
carries the one piece of wiring oc_chat owns here: the ``oct`` timing
ledger.
 
It is a REBINDING, not a wrapper: the last statement replaces this
module's entry in :data:`sys.modules` with the moved module itself, so
``oc_chat.core.worktree_env`` and ``oc_orchestrator.worktree_env`` are
one object. That is what keeps every private name reachable, every
``monkeypatch`` effective across the seam, and every ``isinstance``
true — a wrapper that merely re-exported public names would break all
three quietly.
 
The oct timing hook (plan 270 P4)
---------------------------------
The moved module treats ``oct`` as absent by default, which is what
takes the toolchain out of the dispatcher package's import graph. oc_chat
HAS ``oct``, so importing this path registers the live hook and the
engine timing ledger fills exactly as it did before the split. The
import is a STATEMENT rather than an ``importlib.import_module`` call:
the plan-245 timing witness hides ``oct`` by patching
``builtins.__import__``, which ``import_module`` bypasses.
 
Responsibilities
----------------
- Register :func:`_oct_hook` as the moved module's default hook.
- Bind the moved module to this path.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events
    L3 - semantic details (an unknown hook target)
    L4 - deep tracing (the rebinding)
 
Contracts
---------
- Registering the hook is IDEMPOTENT and global to the process: the
  moved module holds one default and the last registration wins. Only
  this module and a test ever register one.
- The hook never catches: each call site keeps its own failure policy,
  and the timing edge's own ``except ImportError`` is what degrades a
  missing ``oct`` to a null context.
- Retirement rule (plan 270 P8): this path stays until an explicit
  retirement plan retargets its importers. New code names
  ``oc_orchestrator.worktree_env`` directly — and registers its own
  hook if it wants timings.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_orchestrator.worktree_env (the moved module this path binds)
- oct.timing.ledger (lazy; timed_stage, optional - resolved through the hook this module installs)
"""
 
from __future__ import annotations
 
import sys
from typing import Any
 
from oc_diagnostics import _dbg
 
from oc_orchestrator import worktree_env as _moved
 
 
def _oct_hook(target: str) -> Any:
    """Resolve one member of ``oct`` for the moved module.
 
    Byte-for-byte the pre-270 ``_default_oct_hook``, minus the
    ``"package"`` target that plan 270 P1 retired when the venv repair
    file moved into ``oc_diagnostics``. Nothing is caught here.
    """
    func = "_oct_hook"
    if target == "timed_stage":
        from oct.timing.ledger import timed_stage  # noqa: PLC0415
 
        return timed_stage
    _dbg("OC_CHAT.MAIN", func, f"VALIDATION_ERROR: unknown target {target!r}", 3)
    raise _moved.WorktreeEnvError(f"unknown oct hook target {target!r}")
 
 
_moved.use_oct_hook(_oct_hook)
 
_dbg("OC_CHAT.MAIN", "module", "worktree_env shim -> oc_orchestrator.worktree_env", 4)
 
sys.modules[__name__] = _moved