defaults.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/defaults.py
 
"""
The fail-closed reader for the shipped, read-only defaults file (CONFIG-01).
 
Purpose
-------
OC Chat's configuration is two files: ``oc_chat/oc_chat.defaults.toml`` — shipped
as package data, hard-denied for writes BY NAME in :mod:`oc_chat.tools._sandbox`
(``_PROTECTED_WRITE_NAMES``), holding every default and every ceiling — and the
writable workspace settings file ``.oc_chat/oc_chat-settings.json`` (human-confirm
write tier), which may LOWER a ceiling and set a default but can never RAISE a
ceiling. The security property of a bound is WHERE the file lives and WHO may
write it, not that the value sits in a ``.py``: before plan 238 the ceilings were
uppercase module constants inside the importable tree, which a dogfooding agent
under the ``permissive`` profile can already write.
 
This module reads that file once at import, validates it against a key registry
— :data:`KEY_REGISTRY`, the one list of keys permitted to live in code — and
exposes the three accessors every call site uses. There is deliberately NO
permissive fallback anywhere in this module: "cannot read the defaults" is a
startup error, never a default.
 
Responsibilities
----------------
- :data:`KEY_REGISTRY` — every key, its expected value type, and its class.
- :func:`load_table` — parse + validate one defaults file; raise ``SystemExit``
  naming the file and the offending key on any fault.
- :func:`shipped` — the file's value, with no settings and no env consulted.
- :func:`default` — the shipped value, overridden by the workspace settings key
  the table declares (``setting``); absent that declaration the settings file
  cannot reach the value at all.
- :func:`authority` — the shipped value of an ``authority``-class key, REPLACED
  (never clamped, never merged) by the out-of-band variable the table names.
  The settings file cannot reach it in any spelling: an ``authority`` table may
  not declare a ``setting`` at all, and the class has no settings-consulting
  code path. Plan 253's trusted package index (SUPPLY-02 / M8 F78) is the first
  such value.
- :func:`ceiling` — the out-of-band environment variable named by the table
  (when set to a valid positive int) replaces the shipped value as the ceiling;
  an absent settings request preserves that value, while a present request may
  only LOWER it.
  One implementation of F33/§5.4 for every ceiling in the system.
- :func:`env_var` / :func:`setting_key` / :func:`doc` / :func:`keys` — the
  remaining table metadata, for diagnostics and tests.
 
Contracts
---------
- Import fails closed. A missing, unreadable, malformed, incomplete, over-full
  or mistyped defaults file raises ``SystemExit`` during import; nothing starts
  with a guessed value.
- A ``ceiling`` table MUST carry ``env``; the empty string declares "no
  out-of-band raise path exists for this ceiling". A non-empty name MUST be
  enrolled in ``_env_guard._AUTHORITY_EXACT`` (so a workspace ``.env`` cannot
  set it). A ``default`` table MUST NOT carry ``env``.
- An ``authority`` table MUST carry a NON-EMPTY enrolled ``env`` (out of band is
  its only replacement path) and MUST NOT carry ``setting``. Its value — and any
  value the out-of-band variable supplies — is validated as a trusted URL, and a
  fault refuses at load rather than degrading to the shipped one: an unusable
  trusted index is not a reason to fall back to a different one.
- :func:`ceiling` never returns a value above ``min`` of the shipped value and
  the out-of-band ceiling; a settings read that is unavailable, non-int or
  non-positive degrades to the bounded shipped value, never to "unbounded".
- The settings file is consulted only for a key whose table declares ``setting``.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat._env_guard (the out-of-band authority enrolment set)
- oc_chat.core.settings (lazy; workspace settings values for defaults and ceiling requests)
 
Diagnostics
-----------
Domain: OC_CHAT.CORE
Levels:
    L2 — the file was loaded; a ceiling was raised out-of-band
    L3 — per-key resolution detail
    L4 — deep tracing
"""
from __future__ import annotations
 
import os
import tomllib
from dataclasses import dataclass
from pathlib import Path
from typing import Any, NoReturn
from urllib.parse import urlsplit
 
from oc_diagnostics import _dbg
 
from oc_chat._env_guard import _AUTHORITY_EXACT
 
_dbg("OC_CHAT.CORE", "module", "loaded", 4)
 
 
#: The shipped file's basename. Distinctive on purpose: it is hard-denied by
#: NAME everywhere, and a generic ``defaults.toml`` would over-block unrelated
#: files. Keep this in step with ``_sandbox._PROTECTED_WRITE_NAMES``.
DEFAULTS_FILENAME = "oc_chat.defaults.toml"
 
#: The shipped file's location: the package directory, one level above ``core/``.
DEFAULTS_PATH = Path(__file__).resolve().parent.parent / DEFAULTS_FILENAME
 
#: Value classes. A ceiling may only be LOWERED by the settings file; a default
#: may be replaced by it (when the table declares a ``setting``); an authority
#: value is out of the settings file's reach entirely — only the operator's
#: out-of-band variable replaces it (plan 253, SUPPLY-02 / M8 F78).
CLASS_CEILING = "ceiling"
CLASS_DEFAULT = "default"
CLASS_AUTHORITY = "authority"
 
#: Fields a table may carry. Anything else is a fault (fail-closed).
_KNOWN_FIELDS = frozenset({"value", "class", "doc", "env", "setting"})
 
#: Value-type names the registry may pin, and their strict predicates. ``bool``
#: is NOT accepted for ``int`` (Python's ``isinstance(True, int)`` would let a
#: boolean masquerade as a ceiling).
_TYPE_CHECKS = {
    "int": lambda v: isinstance(v, int) and not isinstance(v, bool),
    "float": lambda v: isinstance(v, float),
    "bool": lambda v: isinstance(v, bool),
    "str": lambda v: isinstance(v, str),
    # Plan 237 (CAPS-01): a non-empty list of positive floats — the cost
    # checkpoint ladder. Deliberately as strict as the scalar ``float`` row:
    # ``[2, 5]`` (TOML integers) REFUSES, exactly as ``0.70`` written as ``0``
    # would, so the shipped ladder cannot silently change type. Emptiness is a
    # fault too — "no checkpoints at all" must be written as a deliberate change
    # to the resolver, never as an easily-overlooked empty list in the file.
    "floatlist": lambda v: (
        isinstance(v, list) and bool(v)
        and all(isinstance(x, float) and x > 0 for x in v)
    ),
}
 
 
#: The ONE list of keys permitted to live in code: key name, expected value
#: type, class. Everything else about a value — the value itself, its doc, its
#: out-of-band env knob, the settings key allowed to influence it — lives in the
#: shipped file. A key here but not in the file, or in the file but not here,
#: refuses to start.
KEY_REGISTRY: tuple[tuple[str, str, str], ...] = (
    # Appendix B resource ceilings.
    ("tool_calls_per_turn", "int", CLASS_CEILING),
    ("stall_repeat_calls", "int", CLASS_CEILING),
    ("stall_error_streak", "int", CLASS_CEILING),
    ("stall_no_progress_iterations", "int", CLASS_CEILING),
    ("parallel_workers", "int", CLASS_CEILING),
    ("timeout_seconds", "int", CLASS_CEILING),
    ("byte_budget", "int", CLASS_CEILING),
    ("search_results", "int", CLASS_CEILING),
    ("dir_depth", "int", CLASS_CEILING),
    # Session cost bounds (CAPS-01, plan 237).
    ("session_cost_thresholds_usd", "floatlist", CLASS_DEFAULT),
    ("session_cost_hard_cap_usd", "int", CLASS_CEILING),
    ("checkpoint_top_tools", "int", CLASS_DEFAULT),
    ("session_alert_notify_timeout_s", "int", CLASS_DEFAULT),
    ("settings_session_cost_hard_cap_usd", "int", CLASS_DEFAULT),
    # Completion (output) token budget.
    ("output_tokens", "int", CLASS_CEILING),
    ("undeclared_output_tokens", "int", CLASS_DEFAULT),
    # Context window and compression.
    ("model_max_tokens", "int", CLASS_DEFAULT),
    ("context_window_size", "int", CLASS_DEFAULT),
    ("context_compress_threshold", "float", CLASS_DEFAULT),
    ("context_keep_recent", "int", CLASS_DEFAULT),
    ("context_keep_recent_turns", "int", CLASS_DEFAULT),
    # ReAct loop.
    ("max_react_iterations", "int", CLASS_DEFAULT),
    ("reasoning_effort", "str", CLASS_DEFAULT),
    # Settings-file schema defaults.
    ("settings_verbose", "bool", CLASS_DEFAULT),
    ("settings_max_output_tokens", "int", CLASS_DEFAULT),
    ("mode_standard_include_persona", "bool", CLASS_DEFAULT),
    ("mode_standard_include_tools", "bool", CLASS_DEFAULT),
    ("mode_standard_include_env", "bool", CLASS_DEFAULT),
    ("mode_standard_include_project_tree", "bool", CLASS_DEFAULT),
    ("mode_option_c_include_persona", "bool", CLASS_DEFAULT),
    ("mode_option_c_include_tools", "bool", CLASS_DEFAULT),
    ("mode_option_c_include_env", "bool", CLASS_DEFAULT),
    ("mode_option_c_include_project_tree", "bool", CLASS_DEFAULT),
    ("project_tree_max_depth", "int", CLASS_DEFAULT),
    ("project_tree_honor_gitignore", "bool", CLASS_DEFAULT),
    # Verification backpressure.
    ("verification_enabled", "bool", CLASS_DEFAULT),
    ("verification_lint", "bool", CLASS_DEFAULT),
    ("verification_typecheck", "bool", CLASS_DEFAULT),
    ("verification_tests", "bool", CLASS_DEFAULT),
    ("verification_timeout_s", "int", CLASS_DEFAULT),
    ("verification_max_files", "int", CLASS_DEFAULT),
    ("verification_max_findings", "int", CLASS_DEFAULT),
    ("verification_jobs", "int", CLASS_DEFAULT),
    ("verification_max_runs_per_turn", "int", CLASS_DEFAULT),
    ("verification_baseline", "bool", CLASS_DEFAULT),
    ("verification_baseline_timeout_s", "int", CLASS_DEFAULT),
    # Per-step output-budget shares.
    ("bucket_share_planning", "float", CLASS_DEFAULT),
    ("bucket_share_thinking", "float", CLASS_DEFAULT),
    ("bucket_share_thinking_write", "float", CLASS_DEFAULT),
    ("bucket_share_simple_thinking", "float", CLASS_DEFAULT),
    ("bucket_share_simple", "float", CLASS_DEFAULT),
    ("min_bucket_output_tokens", "int", CLASS_DEFAULT),
    # API-context tool-result caps.
    ("tool_result_cap", "int", CLASS_DEFAULT),
    ("big_context_tool_result_cap", "int", CLASS_DEFAULT),
    # Lane-picker table widths.
    ("lane_picker_name_width", "int", CLASS_DEFAULT),
    ("lane_picker_label_width", "int", CLASS_DEFAULT),
    # Terminal UI.
    ("ui_reasoning_tail", "int", CLASS_DEFAULT),
    # The operator-trusted package index (SUPPLY-02, plan 253; M8 F78).
    ("pip_index_url", "str", CLASS_AUTHORITY),
)
 
#: Plan 246 adds positive-only semantics for its three new thresholds without
#: changing the validation contract of pre-existing ceiling entries.
_POSITIVE_CEILING_KEYS = frozenset({
    "stall_repeat_calls",
    "stall_error_streak",
    "stall_no_progress_iterations",
})
 
 
@dataclass(frozen=True)
class Entry:
    """One validated table from the shipped defaults file."""
 
    key: str
    value: Any
    value_class: str
    doc: str
    env: str = ""
    setting: str = ""
 
 
def _refuse(path: Path, message: str) -> NoReturn:
    """Refuse to start: raise ``SystemExit`` naming *path* and the fault.
 
    SECURITY_ERROR (L1). No caller may recover from this — a defaults file that
    does not validate means the ceilings are unknown, and an unknown ceiling is
    not a default (CONFIG-01, F33/§5.4). The text is ASCII-only: it is printed
    to a console whose encoding may be cp1252."""
    func = "_refuse"
    text = f"oc_chat: refusing to start - {path}: {message}"
    _dbg("OC_CHAT.CORE", func, f"SECURITY_ERROR: {message}", 1)
    raise SystemExit(text)
 
 
def _refuse_env(env_name: str, key: str, message: str) -> NoReturn:
    """Refuse to start: the out-of-band value for *key* does not validate.
 
    SECURITY_ERROR (L1). The same fail-closed rule the shipped file gets, applied
    to the one channel allowed to replace an authority value: an operator
    variable that does not validate leaves the trusted destination UNKNOWN, and
    an unknown trusted destination is not a reason to silently use a different
    one (M8 F78). ASCII-only text: it prints to a cp1252 console."""
    func = "_refuse_env"
    text = f"oc_chat: refusing to start - {env_name} (authority value for {key!r}): {message}"
    _dbg("OC_CHAT.CORE", func, f"SECURITY_ERROR: {message}", 1)
    raise SystemExit(text)
 
 
def _authority_url_fault(value: Any) -> str:
    """Why *value* is not a usable authority URL, or ``""`` when it is.
 
    An authority URL is the operator's declared destination for a child process
    that reaches the network (F78), so it is checked as strictly as a ceiling's
    type is: a non-empty ``str`` of printable ASCII (no embedded newline can
    smuggle a second argument), the ``https`` scheme alone (no ``http``
    downgrade and no ``file``/``ftp`` substitution), a named host, no
    ``user:pass@`` userinfo (a credential does not belong in a config value or
    in an argv the operator reads at a confirm prompt) and no query string."""
    if not isinstance(value, str) or not value:
        return "an authority value must be a non-empty string"
    if any(ch < "!" or ch > "~" for ch in value):
        return "an authority URL must be printable ASCII with no whitespace"
    try:
        parts = urlsplit(value)
        scheme, host, user, password, query = (
            parts.scheme, parts.hostname, parts.username, parts.password, parts.query)
        _ = parts.port          # a malformed port raises here, not at the point of use
    except ValueError as exc:
        return f"an authority URL is malformed ({type(exc).__name__}: {exc})"
    if scheme != "https":
        return f"an authority URL must use the https scheme, found {scheme!r}"
    if not host:
        return "an authority URL must name a host"
    if user is not None or password is not None:
        return "an authority URL must carry no userinfo (credentials do not belong in it)"
    if query:
        return "an authority URL must carry no query string"
    return ""
 
 
def _validate_entry(path: Path, key: str, type_name: str, want_class: str, raw: Any) -> Entry:
    """Validate one table against its registry row and return its :class:`Entry`."""
    if not isinstance(raw, dict):
        _refuse(path, f"key {key!r}: expected a table, found {type(raw).__name__}")
    unknown = sorted(set(raw) - _KNOWN_FIELDS)
    if unknown:
        _refuse(path, f"key {key!r}: unknown field(s) {unknown}")
    for field_name in ("value", "class", "doc"):
        if field_name not in raw:
            _refuse(path, f"key {key!r}: missing required field {field_name!r}")
    if raw["class"] != want_class:
        _refuse(path, f"key {key!r}: class is {raw['class']!r}, the registry pins {want_class!r}")
    if not _TYPE_CHECKS[type_name](raw["value"]):
        _refuse(path, f"key {key!r}: value {raw['value']!r} is not of the registered type {type_name!r}")
    if key in _POSITIVE_CEILING_KEYS and raw["value"] <= 0:
        _refuse(path, f"key {key!r}: value must be a positive integer")
    if want_class == CLASS_AUTHORITY:
        fault = _authority_url_fault(raw["value"])
        if fault:
            _refuse(path, f"key {key!r}: {fault}")
    if not isinstance(raw["doc"], str) or not raw["doc"].strip():
        _refuse(path, f"key {key!r}: doc must be a non-empty string")
 
    env = raw.get("env")
    if want_class in (CLASS_CEILING, CLASS_AUTHORITY):
        if env is None:
            if want_class == CLASS_CEILING:
                _refuse(path, f"key {key!r}: a ceiling must declare env (use \"\" for no out-of-band raise path)")
            _refuse(path, f"key {key!r}: an authority value must declare env")
        if not isinstance(env, str):
            _refuse(path, f"key {key!r}: env must be a string")
        if want_class == CLASS_AUTHORITY and not env:
            _refuse(path, f"key {key!r}: an authority value must declare a NON-EMPTY env "
                          "- out of band is its only replacement path")
        if env and env not in _AUTHORITY_EXACT:
            # OCT-LINT: disable=no_hardcoded_secrets reason="Refusal message naming _env_guard._AUTHORITY_EXACT trips Shannon entropy (4.51 bits/char); prose, no secret (operator ruling 2026-09-05)"
            _refuse(path, f"key {key!r}: env {env!r} is not enrolled in _env_guard._AUTHORITY_EXACT")
    elif env is not None:
        _refuse(path, f"key {key!r}: env is permitted on a ceiling only, not on a default")
 
    setting = raw.get("setting")
    if want_class == CLASS_AUTHORITY and setting is not None:
        _refuse(path, f"key {key!r}: an authority value may not declare a setting "
                      "- the settings file may never set it or lower it")
    if setting is not None and (not isinstance(setting, str) or not setting.strip()):
        _refuse(path, f"key {key!r}: setting must be a non-empty string when present")
 
    return Entry(
        key=key,
        value=raw["value"],
        value_class=want_class,
        doc=raw["doc"],
        env=env or "",
        setting=setting or "",
    )
 
 
def load_table(path: Path) -> dict[str, Entry]:
    """Read and validate the defaults file at *path*; ``SystemExit`` on any fault.
 
    Refuses on a missing file, an unreadable file, malformed TOML, an unknown
    key, a missing key, a wrong value type, a ceiling without ``env``, and an
    ``env`` that is not enrolled in ``_env_guard._AUTHORITY_EXACT``. There is no
    fallback: every refusal names the file, and every key-scoped refusal names
    the key."""
    func = "load_table"
    try:
        raw_bytes = path.read_bytes()
    except FileNotFoundError:
        _refuse(path, "the shipped defaults file is missing")
    except OSError as exc:
        # EXTERNAL_ERROR (L2) at the seam; fail closed regardless.
        _refuse(path, f"the shipped defaults file is unreadable ({type(exc).__name__}: {exc})")
    try:
        data = tomllib.loads(raw_bytes.decode("utf-8"))
    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
        _refuse(path, f"malformed TOML ({type(exc).__name__}: {exc})")
 
    registered = {key for key, _type, _cls in KEY_REGISTRY}
    for key in sorted(set(data) - registered):
        _refuse(path, f"key {key!r}: unknown key — it is not in defaults.KEY_REGISTRY")
 
    table: dict[str, Entry] = {}
    for key, type_name, want_class in KEY_REGISTRY:
        if key not in data:
            _refuse(path, f"key {key!r}: missing from the shipped defaults file")
        table[key] = _validate_entry(path, key, type_name, want_class, data[key])
 
    _dbg("OC_CHAT.CORE", func, f"loaded {len(table)} keys from {path.name}", 2)
    return table
 
 
def _validate_authority_env(table: dict[str, Entry]) -> None:
    """Refuse at import when an out-of-band authority value does not validate.
 
    The shipped file is checked by :func:`load_table`; this is the same check
    applied to the ONE channel allowed to replace an authority value. Doing it
    at import means a malformed operator variable stops the process at startup,
    where the operator is looking, rather than on the first granted install."""
    for key, entry in table.items():
        if entry.value_class != CLASS_AUTHORITY or not entry.env:
            continue
        raw = os.environ.get(entry.env)
        if raw is None:
            continue
        fault = _authority_url_fault(raw)
        if fault:
            _refuse_env(entry.env, key, fault)
 
 
#: The validated table, read once at import. Import fails closed (SystemExit).
_TABLE: dict[str, Entry] = load_table(DEFAULTS_PATH)
_validate_authority_env(_TABLE)
 
 
def _entry(key: str) -> Entry:
    """The validated :class:`Entry` for *key*; ``KeyError`` names an unregistered key."""
    try:
        return _TABLE[key]
    except KeyError:
        raise KeyError(f"{key!r} is not a key in {DEFAULTS_FILENAME}") from None
 
 
def keys() -> tuple[str, ...]:
    """Every registered key, in registry order."""
    return tuple(key for key, _type, _cls in KEY_REGISTRY)
 
 
def doc(key: str) -> str:
    """The shipped documentation string for *key*."""
    return _entry(key).doc
 
 
def env_var(key: str) -> str:
    """The out-of-band env variable that raises *key*'s ceiling, or ``""``."""
    return _entry(key).env
 
 
def setting_key(key: str) -> str:
    """The settings-file key permitted to influence *key*, or ``""`` for none."""
    return _entry(key).setting
 
 
def shipped(key: str) -> Any:
    """The shipped value for *key*: no settings file, no env, no resolution.
 
    This is the built-in default a settings-file merge starts from, and the code
    default every ceiling degrades to."""
    return _entry(key).value
 
 
def _settings_int(setting: str, fallback: "int | None") -> "int | None":
    """The workspace settings value for *setting* as an int, or ``None`` when the
    settings subsystem is unavailable or the value is unparseable (either way the
    caller degrades to the bounded shipped value, never to unbounded)."""
    func = "_settings_int"
    try:
        from oc_chat.core.settings import runtime_settings
        return int(getattr(runtime_settings(), setting, fallback))
    except Exception as exc:  # noqa: BLE001 — settings unavailable ⇒ bounded default
        _dbg("OC_CHAT.CORE", func, f"VALIDATION_ERROR: {type(exc).__name__}: {exc}", 3)
        return None
 
 
def default(key: str) -> Any:
    """The effective value for a ``default``-class *key*.
 
    The shipped value, overridden by the workspace settings key the table
    declares in ``setting``. A key that declares no ``setting`` cannot be reached
    from the settings file at all, so the shipped value stands."""
    func = "default"
    entry = _entry(key)
    if entry.value_class == CLASS_AUTHORITY:
        raise KeyError(f"{key!r} is an authority value - use defaults.authority(); "
                       "default() would answer with a value the operator's "
                       "out-of-band variable has already replaced")
    if not entry.setting:
        return entry.value
    try:
        from oc_chat.core.settings import runtime_settings
        found = getattr(runtime_settings(), entry.setting, None)
    except Exception as exc:  # noqa: BLE001 — settings unavailable ⇒ shipped value
        _dbg("OC_CHAT.CORE", func, f"VALIDATION_ERROR: {type(exc).__name__}: {exc}", 3)
        return entry.value
    return entry.value if found is None else found
 
 
def ceiling(key: str) -> int:
    """The effective ceiling for a ``ceiling``-class *key* — the ONE implementation
    of "settings may LOWER, never RAISE; the operator's out-of-band env raises".
 
    The env variable the table names replaces the shipped value as the absolute
    ceiling when set to a positive int (it is ``_env_guard``-enrolled, so a
    workspace ``.env`` cannot set it). The settings key is a REQUEST clamped by
    that ceiling. An unset, non-int or unavailable setting leaves the absolute
    ceiling in force. A non-positive legacy request degrades to the shipped
    value (F33/§5.4, F52)."""
    func = "ceiling"
    entry = _entry(key)
    if entry.value_class == CLASS_AUTHORITY:
        raise KeyError(f"{key!r} is an authority value - use defaults.authority(); "
                       "an authority value is replaced out of band, never clamped")
    shipped_value = int(entry.value)
 
    absolute = shipped_value
    if entry.env:
        raw = os.environ.get(entry.env)
        if raw is not None:
            try:
                candidate = int(raw)
            except (TypeError, ValueError):
                candidate = 0
            if candidate > 0:
                absolute = candidate
                _dbg("OC_CHAT.CORE", func, f"{key}: OOB ceiling {entry.env}={candidate}", 2)
 
    if not entry.setting:
        return absolute
 
    value = _settings_int(entry.setting, None)
    if value is None:
        return absolute
    requested = value if value > 0 else shipped_value
    return min(requested, absolute)
 
 
def authority(key: str) -> str:
    """The effective value for an ``authority``-class *key* (plan 253, F78).
 
    The shipped value, REPLACED outright by the out-of-band variable the table
    names when that variable is set. There is no settings path and no clamping:
    an authority value is a posture decision the operator makes out of band or
    not at all. An out-of-band value that does not validate refuses
    (``SystemExit``) rather than degrading to the shipped one — degrading would
    let a planted variable turn the operator's pin back into the default without
    anybody noticing."""
    func = "authority"
    entry = _entry(key)
    if entry.value_class != CLASS_AUTHORITY:
        raise KeyError(f"{key!r} is a {entry.value_class} value, not an authority value")
    raw = os.environ.get(entry.env) if entry.env else None
    if raw is None:
        return str(entry.value)
    fault = _authority_url_fault(raw)
    if fault:
        _refuse_env(entry.env, key, fault)
    _dbg("OC_CHAT.CORE", func, f"{key}: OOB authority value from {entry.env}", 2)
    return raw
 
 
__all__ = [
    "CLASS_AUTHORITY",
    "CLASS_CEILING",
    "CLASS_DEFAULT",
    "DEFAULTS_FILENAME",
    "DEFAULTS_PATH",
    "Entry",
    "KEY_REGISTRY",
    "authority",
    "ceiling",
    "default",
    "doc",
    "env_var",
    "keys",
    "load_table",
    "setting_key",
    "shipped",
]