deployment_shape.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/deployment_shape.py
 
"""
The `guarded` deployment-shape invariant (M8.0 WU-7; Appendix C G-1/G-7).
 
Purpose
-------
Under the ``guarded`` / ``isolated`` profiles the harness must **fail closed at
startup and on every effective-root change** if the agent's write sandbox overlaps
any of the harness's *importable roots*: a ``write_file`` into an importable tree
followed by an ``import`` is an in-process code-execution path (F57), and the
contract packages are additionally the ``canonical_json`` MAC preimage (F74). The
invariant closes both **by topology** — if the importable tree is outside the write
sandbox, a write can never become an in-process import. This is what makes the T2
(untrusted *target* project) posture safe without the cross-process broker; it is
the keystone of the ``guarded`` profile.
 
``permissive`` is a no-op: in-tree monorepo dogfooding intentionally keeps the
harness and the sandbox in one tree, accepting the in-process-ACE residual (§6).
 
Responsibilities
----------------
- :func:`enumerate_importable_roots` — the resolved importable-root set, derived
  from **loaded** ``sys.modules`` (the harness + contract packages) plus the active
  site-packages / per-user site and a hardcoded repo-root fallback — never a literal
  list (AC-G-1).
- :func:`check_deployment_shape` — under ``guarded`` / ``isolated``, raise
  :class:`DeploymentShapeError` if any importable root is equal / ancestor /
  descendant of the sandbox (compared on real ``resolve()``-d paths).
 
Contracts
---------
- ``permissive`` ⇒ no-op; ``guarded`` / ``isolated`` ⇒ enforced.
- Overlap is symmetric: equal, sandbox-inside-root, and root-inside-sandbox all
  fail closed. Paths are resolved (``..`` / symlinks / editable finders) first.
- The importable-root set reflects ``sys.modules`` at call time, so an unloaded
  package contributes nothing and the set follows the real deployment.
- G-7 follows by topology: a sandbox disjoint from every importable root is not
  importable, so a target ``conftest.py`` cannot be collected in this process.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
 
Diagnostics
-----------
Domain: OC_CHAT.CORE
Levels:
    L1 — fail-closed refusal (a startup/root-change block)
    L2 — lifecycle (check entry / outcome)
    L3 — the enumerated roots / per-root comparison
    L4 — deep tracing
"""
from __future__ import annotations
 
import site
import sys
from pathlib import Path
 
from oc_diagnostics import _dbg
 
#: The harness + contract importable packages. Only those actually present in
#: ``sys.modules`` contribute a root (the set is module-derived, not a literal list).
_IMPORTABLE_PACKAGES: tuple[str, ...] = (
    "oc_chat", "oc_ui", "providers", "oc_diagnostics", "oct",
    "option_c_agent_contracts", "option_c_registry_contracts",
)
 
#: Profiles for which the invariant is enforced (permissive is in-tree dogfooding).
_ENFORCING_PROFILES: frozenset[str] = frozenset({"guarded", "isolated"})
 
 
class DeploymentShapeError(RuntimeError):
    """Raised when the write sandbox overlaps a harness importable root (G-1)."""
 
 
def _module_dirs(module: object) -> list[Path]:
    """Resolved directories a module is importable from (``__file__`` parent +
    every ``__path__`` entry, for regular and namespace packages)."""
    dirs: list[Path] = []
    f = getattr(module, "__file__", None)
    if f:
        try:
            dirs.append(Path(f).resolve(strict=False).parent)
        except (OSError, ValueError):
            pass
    for entry in getattr(module, "__path__", None) or []:
        try:
            dirs.append(Path(entry).resolve(strict=False))
        except (OSError, ValueError, TypeError):
            pass
    return dirs
 
 
def _ensure_packages_loaded() -> None:
    """Import the importable packages so a namespace/contract package that would
    otherwise load *lazily during agent construction* is in ``sys.modules`` at
    enumeration time.
 
    Without this, a PEP-420 namespace contract package (``option_c_agent_contracts``
    / ``option_c_registry_contracts`` — in-tree, not under site-packages) is absent
    from ``sys.modules`` at the startup check, so a sandbox overlapping it would pass
    and the package would load afterward (AC-V11-3). Already-loaded names are a fast
    no-op; an unavailable one is ignored (the set still follows the real deployment).
    """
    import importlib
    for name in _IMPORTABLE_PACKAGES:
        if name in sys.modules:
            continue
        try:
            importlib.import_module(name)
        except Exception:
            pass  # optional / not present in this deployment
 
 
def enumerate_importable_roots() -> set[Path]:
    """Return the resolved importable roots derived from loaded ``sys.modules``.
 
    For each harness/contract package (force-loaded if not yet imported), its package
    directory(ies); plus the active ``site-packages`` / per-user site; plus a
    hardcoded repo-root fallback (``oc_chat``'s parent) in case an editable finder hid
    the sys.path entry.
    """
    _ensure_packages_loaded()
    roots: set[Path] = set()
    for name in _IMPORTABLE_PACKAGES:
        module = sys.modules.get(name)
        if module is not None:
            roots.update(_module_dirs(module))
    # Site dirs: a write landing here would also be importable.
    site_dirs: list[str] = []
    try:
        site_dirs.extend(site.getsitepackages())
    except Exception:  # virtualenv variants may lack getsitepackages
        pass
    try:
        user_site = site.getusersitepackages()
        if user_site:
            site_dirs.append(user_site)
    except (AttributeError, Exception):
        pass
    for d in site_dirs:
        try:
            roots.add(Path(d).resolve(strict=False))
        except (OSError, ValueError):
            pass
    # Hardcoded fallback: the harness repo root (oc_chat's parent).
    oc_chat_mod = sys.modules.get("oc_chat")
    f = getattr(oc_chat_mod, "__file__", None)
    if f:
        try:
            roots.add(Path(f).resolve(strict=False).parent.parent)
        except (OSError, ValueError):
            pass
    return roots
 
 
def _overlaps(a: Path, b: Path) -> bool:
    """True if *a* and *b* are equal, or one is an ancestor of the other (resolved)."""
    a = a.resolve(strict=False)
    b = b.resolve(strict=False)
    return a == b or a.is_relative_to(b) or b.is_relative_to(a)
 
 
def check_deployment_shape(
    sandbox_root: str | Path,
    profile: str,
    *,
    importable_roots: "set[Path] | None" = None,
) -> None:
    """Enforce the G-1 invariant for *profile*; raise on overlap (no-op otherwise).
 
    Under ``guarded`` / ``isolated``, raise :class:`DeploymentShapeError` if any
    importable root is equal / ancestor / descendant of *sandbox_root*. Under any
    other profile (``permissive``), return without checking.
    """
    func = "check_deployment_shape"
    if profile == "permissive":
        return  # in-tree dogfooding is the only no-op (§6)
    if profile not in _ENFORCING_PROFILES:
        # An unexpected / unrecognized profile is enforced, never silently skipped
        # (fail-closed). Real callers pass a resolve_risk_profile() value.
        _dbg("OC_CHAT.CORE", func,
             f"unexpected profile {profile!r}; enforcing deployment-shape fail-closed",
             1, override=True)
    sandbox = Path(sandbox_root).resolve(strict=False)
    roots = importable_roots if importable_roots is not None else enumerate_importable_roots()
    overlapping = sorted({str(r.resolve(strict=False)) for r in roots if _overlaps(r, sandbox)})
    if overlapping:
        _dbg("OC_CHAT.CORE", func,
             f"{profile} deployment-shape REFUSED: sandbox {sandbox} overlaps "
             f"importable root(s) {overlapping}", 1, override=True)
        raise DeploymentShapeError(
            f"the '{profile}' profile refuses this deployment shape: the write "
            f"sandbox '{sandbox}' overlaps harness importable root(s) "
            f"{', '.join(overlapping)} — a write-then-import would be an in-process "
            f"code-execution path. Move the sandbox outside the harness install tree, "
            f"or use the 'permissive' profile for in-tree dogfooding."
        )
    _dbg("OC_CHAT.CORE", func, f"{profile} deployment-shape OK for sandbox {sandbox}", 2)
 
 
__all__ = [
    "DeploymentShapeError",
    "enumerate_importable_roots",
    "check_deployment_shape",
]