risk_profile.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/risk_profile.py
 
"""
Risk-level runtime profile (M8.0 WU-8; §6, F66 / F33).
 
Purpose
-------
The M8 enforcement posture is one of three operator-selected runtime profiles,
named for the *risk level* the operator accepts (never the deployment context):
 
* ``permissive`` — L1 hardened in-process; importable-tree writes allowed;
  external-content fetch confirm-gated; provider egress governed. The in-process
  ACE residual is *accepted* (T1; no determined in-process adversary).
* ``guarded``    — ``permissive`` + the deployment-shape invariant enforced
  (WU-7 / Appendix C G-1): refuses to start if a harness importable root is
  inside the sandbox, closing write→import by topology (T2).
* ``isolated``   — L3 cross-process broker; the agent holds no sink and no key
  (M8.6b). The first real boundary (T3).
 
**OOB-only (F33):** the profile is selected *operator-out-of-band only* — read
from the ``OC_CHAT_PROFILE`` process environment variable set at launch, NEVER
from a settings file / prompt / resume / model output (any of which an injected
agent could influence). An unset / unrecognized value falls to the M8.0 default
``permissive`` (the dogfooding posture, §6: "monorepo dogfooding is permissive");
released / T2 deployments select ``guarded`` out-of-band (the installer / docs
guide this, F69). The resolved profile is logged at resolution.
 
This module establishes the profile *contract*; the profile-scoped behaviors
(the external-content confirmation gate F67, the ``permissive`` importable-write
human-confirm tier F70, and the ``guarded`` deployment-shape invariant) hook into
it in their own work-units (WU-8 follow-ups / WU-7).
 
Responsibilities
----------------
- :data:`RiskProfile` / :data:`VALID_PROFILES` — the three profile names, as a
  type and as the validation set.
- :data:`PROFILE_ENV_VAR` / :data:`DEFAULT_PROFILE` — the out-of-band selection
  variable and the M8.0 default profile.
- :func:`resolve_risk_profile` — read the active profile from the process
  environment and log the resolved value.
 
Contracts
---------
- The profile is read from the ``OC_CHAT_PROFILE`` process environment variable
  only; no settings file, prompt, resume payload or model output is consulted.
- Matching is case-insensitive and whitespace-tolerant, and the returned value is
  always a member of :data:`VALID_PROFILES`.
- An unset, empty or unrecognized value resolves to :data:`DEFAULT_PROFILE`
  (``permissive``); resolution never raises.
 
Diagnostics
-----------
Domain: OC_CHAT.CORE
Levels:
    L2 — the resolved active profile, and an unrecognized ``OC_CHAT_PROFILE``
         value falling to the default
    L3 — (none) resolution has no per-call detail beyond the L2 records
    L4 — deep tracing
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
import os
from typing import Literal
 
from oc_diagnostics import _dbg
 
RiskProfile = Literal["permissive", "guarded", "isolated"]
 
#: The valid profile names.
VALID_PROFILES: frozenset[str] = frozenset({"permissive", "guarded", "isolated"})
 
#: The out-of-band selection variable (process env only; never settings/model).
PROFILE_ENV_VAR = "OC_CHAT_PROFILE"
 
#: M8.0 default (the dogfooding posture). Released/T2 deployments set "guarded".
DEFAULT_PROFILE: RiskProfile = "permissive"
 
 
def resolve_risk_profile() -> RiskProfile:
    """Return the active risk profile, selected out-of-band only (F33).
 
    Reads ``OC_CHAT_PROFILE`` from the process environment (case-insensitive,
    whitespace-tolerant). Never consults a settings file, prompt, resume payload,
    or model output. An unset value uses :data:`DEFAULT_PROFILE`; an explicitly
    set but unrecognized value is logged and also falls to the default.
    """
    func = "resolve_risk_profile"
    raw = os.environ.get(PROFILE_ENV_VAR, "").strip().lower()
    if raw in VALID_PROFILES:
        profile: RiskProfile = raw  # type: ignore[assignment]
    else:
        if raw:
            _dbg("OC_CHAT.CORE", func,
                 f"unrecognized {PROFILE_ENV_VAR}={raw!r}; falling to {DEFAULT_PROFILE!r}", 2)
        profile = DEFAULT_PROFILE
    _dbg("OC_CHAT.CORE", func, f"active risk profile: {profile}", 2)
    return profile
 
 
__all__ = ["RiskProfile", "VALID_PROFILES", "PROFILE_ENV_VAR", "DEFAULT_PROFILE", "resolve_risk_profile"]