termverify 0.1.0__py3-none-any.whl

termverify/_conpty.py

@@ -0,0 +1,586 @@
+"""Minimal Windows ConPTY binding boundary for the terminal adapter plan.
+
+This module is the only place that touches ``pywinpty``. It owns the native
+``winpty._winpty.PTY`` object directly instead of ``winpty.PtyProcess``: the
+``PtyProcess`` wrapper routes output through an internal socket-relay reader
+thread that swallows the native end-of-stream signal and can drop buffered
+output once the child exits, and the accepted verification plan rejects
+reader-thread state as evidence. Driving the native object keeps every
+observable — output bytes, end-of-stream, liveness, exit status — a direct
+native signal.
+
+Process-tree containment uses a Windows job object created per spawn with
+``JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`` and neither breakaway limit, so every
+descendant the child starts inherits membership and cannot leave. Forced
+close terminates the whole tree atomically with ``TerminateJobObject``;
+releasing the binding closes the job handle, which makes the OS sweep any
+survivors even if this process dies abruptly. Disclosed boundary: the child
+is assigned to the job immediately after ``CreateProcess`` returns, so a
+process the child manages to start within that microseconds-wide window
+would fall outside the job; the binding does not claim pre-start assignment.
+
+I/O is single-flight by contract: at most one native read or write may be in
+flight, and overlap fails fast with ``ConptyConcurrentIOError``. The native
+layer is not thread-safe for overlapped calls on one pseudoconsole —
+concurrent ``pty.write`` against a blocked ``pty.read`` intermittently
+crashes the interpreter with a native access violation — and the transcript
+protocol is single-flight anyway, so the binding refuses the overlap rather
+than risking the crash. ``close`` is the one concurrent-safe operation; it
+cancels in-flight I/O and waits it out before releasing the native object,
+because releasing during a native call is the same crash.
+
+The binding stays deliberately thin: every future adapter behavior above it
+must be testable cross-platform against an injected fake binding, so this
+native boundary is excluded from the coverage ratchet with recorded rationale
+in the developer guide. Cancellation and recovery are evidenced at this
+binding level only — startup failure fails closed for both a missing command
+and a command the OS refuses to start, forced close recovers from hostile
+children (output flood, busy spin, in-flight write) without leaking threads,
+with handle release proven by the release-only close evidence, and conin
+writes showed no backpressure on the verified matrix. Classification into
+the structured failure/abort taxonomy is adapter behavior and remains
+unclaimed here.
+
+``write`` intentionally returns ``None``: the ConPTY write return value is not
+a reliable byte-count receipt, and exposing it would fabricate evidence.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from collections.abc import Mapping, Sequence
+from typing import Any, Final
+
+_CHILD_EXIT_WAIT_MS = 30_000
+_READ_CANCEL_TIMEOUT_SECONDS = 30.0
+_READ_CANCEL_RETRY_SECONDS = 0.01
+
+#: Exit code set on every process in the tree by a forced close. The value
+#: keeps parity with the previous single-process termination convention.
+FORCED_TERMINATION_EXIT_CODE: Final = 15
+
+
+class ConptyUnsupportedError(RuntimeError):
+    """Raised when the ConPTY binding is used on a host without ConPTY."""
+
+
+def is_supported() -> bool:
+    """Report whether this host can create ConPTY pseudoconsoles.
+
+    This is the explicit support probe the adapter consults during
+    negotiation, answering the same precondition :meth:`ConptyChild.spawn`
+    checks so platform support is decidable before any spawn is attempted.
+    It inspects no session state and creates nothing.
+    """
+    return os.name == "nt"
+
+
+class ConptyClosedError(RuntimeError):
+    """Raised when an operation is attempted after the binding was closed."""
+
+
+class ConptyConcurrentIOError(RuntimeError):
+    """Raised when a read or write is attempted while another is in flight.
+
+    The native layer is not thread-safe for overlapped calls on one
+    pseudoconsole: concurrent ``pty.write`` against a blocked ``pty.read``
+    intermittently dies with a native access violation. The transcript
+    protocol is single-flight, so the binding forbids overlap outright and
+    fails fast instead of risking the crash or deadlocking behind an
+    indefinitely blocked read. ``close`` is the one concurrent-safe
+    operation; it cancels in-flight I/O.
+    """
+
+
+class ConptyEndOfStreamError(Exception):
+    """Raised by ``read`` when the native output pipe reports end-of-stream.
+
+    Only raised while the binding is open: a read interrupted by ``close``
+    raises :class:`ConptyClosedError` instead, because close may abandon
+    buffered output. On this genuine end-of-stream path Windows pipe
+    semantics deliver all buffered output before the read side observes the
+    broken pipe, so every byte the pseudoconsole emitted has been returned by
+    earlier ``read`` calls when this is raised.
+    """
+
+
+if sys.platform == "win32":
+    import ctypes
+    from ctypes import wintypes
+
+    _SYNCHRONIZE = 0x0010_0000
+    _PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+    _PROCESS_SET_QUOTA = 0x0100
+    _PROCESS_TERMINATE = 0x0001
+    _WAIT_OBJECT_0 = 0
+    _WAIT_TIMEOUT = 0x102
+    _JOB_OBJECT_EXTENDED_LIMIT_INFORMATION = 9
+    _JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x2000
+
+    class _IoCounters(ctypes.Structure):
+        _fields_ = [
+            ("ReadOperationCount", ctypes.c_uint64),
+            ("WriteOperationCount", ctypes.c_uint64),
+            ("OtherOperationCount", ctypes.c_uint64),
+            ("ReadTransferCount", ctypes.c_uint64),
+            ("WriteTransferCount", ctypes.c_uint64),
+            ("OtherTransferCount", ctypes.c_uint64),
+        ]
+
+    class _JobBasicLimits(ctypes.Structure):
+        _fields_ = [
+            ("PerProcessUserTimeLimit", ctypes.c_int64),
+            ("PerJobUserTimeLimit", ctypes.c_int64),
+            ("LimitFlags", wintypes.DWORD),
+            ("MinimumWorkingSetSize", ctypes.c_size_t),
+            ("MaximumWorkingSetSize", ctypes.c_size_t),
+            ("ActiveProcessLimit", wintypes.DWORD),
+            ("Affinity", ctypes.c_size_t),
+            ("PriorityClass", wintypes.DWORD),
+            ("SchedulingClass", wintypes.DWORD),
+        ]
+
+    class _JobExtendedLimits(ctypes.Structure):
+        _fields_ = [
+            ("BasicLimitInformation", _JobBasicLimits),
+            ("IoInfo", _IoCounters),
+            ("ProcessMemoryLimit", ctypes.c_size_t),
+            ("JobMemoryLimit", ctypes.c_size_t),
+            ("PeakProcessMemoryUsed", ctypes.c_size_t),
+            ("PeakJobMemoryUsed", ctypes.c_size_t),
+        ]
+
+    _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    _kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    _kernel32.OpenProcess.restype = wintypes.HANDLE
+    _kernel32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+    _kernel32.WaitForSingleObject.restype = wintypes.DWORD
+    _kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    _kernel32.CloseHandle.restype = wintypes.BOOL
+    _kernel32.CreateJobObjectW.argtypes = [ctypes.c_void_p, wintypes.LPCWSTR]
+    _kernel32.CreateJobObjectW.restype = wintypes.HANDLE
+    _kernel32.SetInformationJobObject.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_int,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+    ]
+    _kernel32.SetInformationJobObject.restype = wintypes.BOOL
+    _kernel32.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
+    _kernel32.AssignProcessToJobObject.restype = wintypes.BOOL
+    _kernel32.TerminateJobObject.argtypes = [wintypes.HANDLE, wintypes.UINT]
+    _kernel32.TerminateJobObject.restype = wintypes.BOOL
+    _kernel32.TerminateProcess.argtypes = [wintypes.HANDLE, wintypes.UINT]
+    _kernel32.TerminateProcess.restype = wintypes.BOOL
+
+    def _create_containment_job() -> int:
+        """Create a kill-on-close job object for one pseudoconsole child."""
+        job = _kernel32.CreateJobObjectW(None, None)
+        if not job:
+            raise OSError(f"CreateJobObject failed: {ctypes.get_last_error()}")
+        limits = _JobExtendedLimits()
+        limits.BasicLimitInformation.LimitFlags = _JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+        if not _kernel32.SetInformationJobObject(
+            job,
+            _JOB_OBJECT_EXTENDED_LIMIT_INFORMATION,
+            ctypes.byref(limits),
+            ctypes.sizeof(limits),
+        ):
+            error = ctypes.get_last_error()
+            _kernel32.CloseHandle(job)
+            raise OSError(f"SetInformationJobObject failed: {error}")
+        return int(job)
+
+    def _open_containment_handle(pid: int) -> int:
+        """Open the child's real process handle for assignment and waits."""
+        handle = _kernel32.OpenProcess(
+            _SYNCHRONIZE
+            | _PROCESS_QUERY_LIMITED_INFORMATION
+            | _PROCESS_SET_QUOTA
+            | _PROCESS_TERMINATE,
+            False,
+            pid,
+        )
+        if not handle:
+            raise OSError(f"OpenProcess({pid}) failed: {ctypes.get_last_error()}")
+        return int(handle)
+
+    def _assign_to_job(job: int, process_handle: int) -> None:
+        if not _kernel32.AssignProcessToJobObject(job, process_handle):
+            raise OSError(f"AssignProcessToJobObject failed: {ctypes.get_last_error()}")
+
+    def _terminate_job(job: int, exit_code: int) -> None:
+        if not _kernel32.TerminateJobObject(job, exit_code):
+            raise OSError(f"TerminateJobObject failed: {ctypes.get_last_error()}")
+
+    def _terminate_process(process_handle: int, exit_code: int) -> None:
+        _kernel32.TerminateProcess(process_handle, exit_code)
+
+    def _wait_for_handle(handle: int, timeout_ms: int) -> bool:
+        """OS wait on a real handle; True once it is signaled, never a sleep.
+
+        A wait failure is a real error, not a timeout, and is raised as such
+        so it cannot masquerade as "the process did not terminate".
+        """
+        result = int(_kernel32.WaitForSingleObject(handle, timeout_ms))
+        if result == _WAIT_OBJECT_0:
+            return True
+        if result == _WAIT_TIMEOUT:
+            return False
+        raise OSError(
+            f"WaitForSingleObject failed ({result:#x}): {ctypes.get_last_error()}"
+        )
+
+    def _close_handle(handle: int) -> None:
+        _kernel32.CloseHandle(handle)
+
+else:
+
+    def _unsupported() -> ConptyUnsupportedError:
+        return ConptyUnsupportedError(
+            "the ConPTY binding requires Windows; this host has no ConPTY"
+        )
+
+    def _create_containment_job() -> int:
+        raise _unsupported()
+
+    def _open_containment_handle(pid: int) -> int:
+        raise _unsupported()
+
+    def _assign_to_job(job: int, process_handle: int) -> None:
+        raise _unsupported()
+
+    def _terminate_job(job: int, exit_code: int) -> None:
+        raise _unsupported()
+
+    def _terminate_process(process_handle: int, exit_code: int) -> None:
+        raise _unsupported()
+
+    def _wait_for_handle(handle: int, timeout_ms: int) -> bool:
+        raise _unsupported()
+
+    def _close_handle(handle: int) -> None:
+        raise _unsupported()
+
+
+class ConptyChild:
+    """Thin ownership wrapper around one native ConPTY pseudoconsole child."""
+
+    def __init__(self, pty: Any, pid: int, job: int, process_handle: int) -> None:
+        self._pty: Any | None = pty
+        self._pid = pid
+        self._job: int | None = job
+        self._process_handle: int | None = process_handle
+        self._exit_status: int | None = None
+        self._lock = threading.Lock()
+        self._pending_io = 0
+
+    @classmethod
+    def spawn(
+        cls,
+        argv: Sequence[str],
+        *,
+        rows: int,
+        columns: int,
+        env_overlay: Mapping[str, str] | None = None,
+        cwd: str | None = None,
+    ) -> ConptyChild:
+        """Spawn a contained child on a ConPTY pseudoconsole.
+
+        The child is assigned to a fresh kill-on-close job object before the
+        binding is returned. If containment cannot be established, the child
+        is terminated and the spawn fails closed: no uncontained session is
+        ever handed out.
+
+        ``env_overlay`` variables are overlaid onto this process's ambient
+        environment at spawn time; an overlay variable always wins over an
+        ambient variable of the same name. Disclosed: the child inherits the
+        ambient environment underneath the overlay — ambient contents are
+        not evidence and are not recorded, only the overlay is. ``cwd``
+        selects the child's working directory; without it, the child starts
+        in this process's current directory.
+        """
+        if os.name != "nt":
+            raise ConptyUnsupportedError(
+                "the ConPTY binding requires Windows; this host has no ConPTY"
+            )
+        from winpty import Backend
+        from winpty._winpty import PTY
+
+        arguments = list(argv)
+        command = shutil.which(arguments[0])
+        if command is None:
+            raise FileNotFoundError(
+                f"the command was not found or was not executable: {arguments[0]}"
+            )
+        merged = dict(os.environ)
+        if env_overlay is not None:
+            merged.update(env_overlay)
+        pty = PTY(columns, rows, backend=Backend.ConPTY)
+        environment = (
+            "\0".join(f"{name}={value}" for name, value in merged.items()) + "\0"
+        )
+        cmdline = (
+            " " + subprocess.list2cmdline(arguments[1:]) if len(arguments) > 1 else None
+        )
+        working_directory = cwd if cwd is not None else os.getcwd()
+        try:
+            spawned = pty.spawn(
+                command, cmdline=cmdline, cwd=working_directory, env=environment
+            )
+        except Exception as error:
+            # Drop the native reference before raising so the held exception's
+            # traceback cannot pin the freshly created pseudoconsole.
+            del pty
+            raise OSError(f"ConPTY spawn failed for {command}") from error
+        if not spawned:
+            del pty
+            raise OSError(f"ConPTY spawn reported failure for {command}")
+        pid = int(pty.pid)
+        job: int | None = None
+        process_handle: int | None = None
+        try:
+            job = _create_containment_job()
+            process_handle = _open_containment_handle(pid)
+            _assign_to_job(job, process_handle)
+        except OSError as error:
+            if process_handle is not None:
+                _terminate_process(process_handle, FORCED_TERMINATION_EXIT_CODE)
+                _close_handle(process_handle)
+            if job is not None:
+                _close_handle(job)
+            # Drop the native reference before raising so the exception
+            # traceback cannot pin the pseudoconsole handles.
+            del pty
+            raise OSError(
+                f"failed to contain ConPTY child {pid} in a job object"
+            ) from error
+        return cls(pty, pid, job, process_handle)
+
+    @property
+    def pid(self) -> int:
+        """Return the child's OS process id."""
+        return self._pid
+
+    def read(self) -> str:
+        """Block until pseudoconsole output is available and return it.
+
+        Raises :class:`ConptyEndOfStreamError` when the binding is still open
+        and the native output pipe reports end-of-stream after the child has
+        exited; the native exit status has been captured by then. Raises
+        :class:`ConptyClosedError` when the binding is closed before or while
+        the read is in flight, and :class:`ConptyConcurrentIOError` when
+        another read or write is already in flight. Any other native read
+        failure — the binding open, the child alive — is re-raised unchanged.
+        """
+        pty = self._begin_io()
+        try:
+            return str(pty.read(blocking=True))
+        except Exception as error:
+            replacement = self._classify_io_failure(pty, end_of_stream=True)
+            # Drop the frame-local native reference before raising: the
+            # exception's traceback keeps this frame alive, and a pinned
+            # native object would defer the handle release indefinitely.
+            del pty
+            if replacement is None:
+                raise
+            raise replacement from error
+        finally:
+            self._end_io()
+
+    def write(self, text: str) -> None:
+        """Write ``text`` to the child without claiming a byte-count receipt.
+
+        Raises :class:`ConptyClosedError` when the binding is closed before
+        or while the write is in flight, and
+        :class:`ConptyConcurrentIOError` when another read or write is
+        already in flight; other native write failures are re-raised
+        unchanged.
+        """
+        pty = self._begin_io()
+        try:
+            pty.write(text)
+        except Exception as error:
+            replacement = self._classify_io_failure(pty, end_of_stream=False)
+            del pty
+            if replacement is None:
+                raise
+            raise replacement from error
+        finally:
+            self._end_io()
+
+    def resize(self, *, rows: int, columns: int) -> None:
+        """Resize the pseudoconsole explicitly."""
+        self._require_open().set_size(columns, rows)
+
+    def is_alive(self) -> bool:
+        """Report whether the child process is still alive.
+
+        A closed binding reports ``False``: it no longer owns a live native
+        session through which liveness could be observed.
+        """
+        pty = self._pty
+        return False if pty is None else bool(pty.isalive())
+
+    def close(self, *, force: bool) -> None:
+        """Release native ownership; with ``force``, terminate the child's tree.
+
+        The forced path terminates the entire job — the child and every
+        descendant — atomically with ``TerminateJobObject`` (uniform exit
+        code :data:`FORCED_TERMINATION_EXIT_CODE`), waits on the child's real
+        process handle, and captures the native exit record before releasing
+        the handles.
+
+        A release-only close (``force=False``) of a live child records no
+        exit status — the binding never observed a native exit record — while
+        the pseudoconsole handle release itself makes ConPTY terminate the
+        attached client, which callers can observe at the OS level. The close
+        waits for that termination on the child's process handle and then
+        closes the job handle, whose kill-on-close limit sweeps any remaining
+        descendants; the no-kill path therefore cannot leak a process tree
+        either.
+
+        Close first unpublishes the native object so no new I/O can start,
+        then cancels pending native I/O until every in-flight read and write
+        has returned. Interrupted I/O surfaces :class:`ConptyClosedError` with
+        its frame-local native reference dropped, so a held exception cannot
+        pin the native object and the handles are released as soon as the
+        last frame still holding it unwinds.
+        """
+        with self._lock:
+            pty = self._pty
+            if pty is None:
+                return
+            self._pty = None
+            job = self._job
+            process_handle = self._process_handle
+            self._job = None
+            self._process_handle = None
+        child_exited = True
+        try:
+            try:
+                if force and pty.isalive():
+                    if job is None:
+                        # Defensive: unreachable on the only construction
+                        # path; failing fast beats waiting on a live child.
+                        raise OSError("no containment job to terminate")
+                    _terminate_job(job, FORCED_TERMINATION_EXIT_CODE)
+                    if process_handle is not None and not _wait_for_handle(
+                        process_handle, _CHILD_EXIT_WAIT_MS
+                    ):
+                        raise OSError(
+                            f"child process {self._pid} did not terminate on"
+                            " forced close"
+                        )
+                if not pty.isalive():
+                    self._capture_exit_status(pty)
+            finally:
+                try:
+                    self._cancel_pending_io(pty)
+                finally:
+                    # Release the binding's native reference even when the
+                    # cancel loop raises: the propagating exception's
+                    # traceback must never pin the native object. The
+                    # destructor closes the pseudoconsole once the last
+                    # in-flight frame unwinds.
+                    del pty
+            if not force and process_handle is not None:
+                child_exited = _wait_for_handle(process_handle, _CHILD_EXIT_WAIT_MS)
+        finally:
+            if job is not None:
+                # Kill-on-close sweeps every remaining job member, so even a
+                # failed graceful path cannot leak the tree.
+                _close_handle(job)
+            if not child_exited and process_handle is not None:
+                child_exited = _wait_for_handle(process_handle, _CHILD_EXIT_WAIT_MS)
+            if process_handle is not None:
+                _close_handle(process_handle)
+        if not child_exited:
+            raise OSError(
+                f"child process {self._pid} did not terminate after handle release"
+            )
+
+    def _cancel_pending_io(self, pty: Any) -> None:
+        """Cancel native I/O until no read or write frame can block on ``pty``."""
+        deadline = time.monotonic() + _READ_CANCEL_TIMEOUT_SECONDS
+        while True:
+            with self._lock:
+                pending = self._pending_io
+            if pending == 0:
+                return
+            with contextlib.suppress(Exception):
+                pty.cancel_io()
+            if time.monotonic() >= deadline:
+                raise OSError("pending native ConPTY I/O did not cancel during close")
+            time.sleep(_READ_CANCEL_RETRY_SECONDS)
+
+    @property
+    def exit_status(self) -> int | None:
+        """Return the natively observed exit status, else ``None``."""
+        pty = self._pty
+        if self._exit_status is None and pty is not None:
+            self._capture_exit_status(pty)
+        return self._exit_status
+
+    def _require_open(self) -> Any:
+        pty = self._pty
+        if pty is None:
+            raise ConptyClosedError("the ConPTY binding is closed")
+        return pty
+
+    def _begin_io(self) -> Any:
+        """Atomically take the native object and count the in-flight call.
+
+        At most one read or write may be in flight: overlapped native calls
+        on one pseudoconsole can crash the interpreter, and blocking a write
+        behind an indefinitely blocked read would deadlock, so overlap fails
+        fast as :class:`ConptyConcurrentIOError`.
+        """
+        with self._lock:
+            pty = self._pty
+            if pty is None:
+                raise ConptyClosedError("the ConPTY binding is closed")
+            if self._pending_io > 0:
+                raise ConptyConcurrentIOError(
+                    "another native read or write is already in flight; the"
+                    " binding is single-flight by contract"
+                )
+            self._pending_io += 1
+            return pty
+
+    def _end_io(self) -> None:
+        with self._lock:
+            self._pending_io -= 1
+
+    def _classify_io_failure(
+        self, pty: Any, *, end_of_stream: bool
+    ) -> Exception | None:
+        """Map a native I/O failure to the binding's honest exception, if any.
+
+        A failure observed after ``close`` unpublished the native object is
+        the close's own cancellation (or indistinguishable from it) and
+        becomes :class:`ConptyClosedError` — never an end-of-stream claim,
+        because close may have abandoned buffered output. A read failure on
+        an open binding with a dead child is the native end-of-stream signal.
+        Anything else is the caller's to see unchanged (``None``).
+        """
+        if not pty.isalive():
+            self._capture_exit_status(pty)
+        if self._pty is None:
+            return ConptyClosedError("the ConPTY binding was closed during native I/O")
+        if end_of_stream and not pty.isalive():
+            return ConptyEndOfStreamError(
+                "the native ConPTY output pipe reported end-of-stream"
+            )
+        return None
+
+    def _capture_exit_status(self, pty: Any) -> None:
+        status = pty.get_exitstatus()
+        if status is not None:
+            self._exit_status = int(status)

termverify/_enforcement_tier_v1.py

@@ -0,0 +1,30 @@
+"""Protocol-owned enforcement-tier vocabulary `termverify.enforcement-tier/v1`.
+
+A closed, versioned vocabulary owned by the protocol exactly like the
+timezone and key registries: exact case-sensitive membership, no aliases or
+normalization, runtime validation authoritative. Post-freeze membership or
+meaning changes require a new vocabulary version. Membership is not evidence
+that an emitter exists; each tier's authorized emitting path is fixed by the
+accepted cooperation-tier design
+(`docs/agent/design/cooperation-tier-constraint-ports.md`) and enforced
+fail-closed during receipt-binding validation.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypeGuard
+
+type EnforcementTier = Literal["os", "constructive", "delivered"]
+
+#: The closed v1 membership, in disclosure-strength order: ``os`` (applied by
+#: an operating-system mechanism at the subject boundary), ``constructive``
+#: (applied by construction of the controlled in-process runtime),
+#: ``delivered`` (placed into the subject's spawn environment; honoring it is
+#: subject cooperation — nothing is enforced).
+ENFORCEMENT_TIERS: tuple[EnforcementTier, ...] = ("os", "constructive", "delivered")
+_ENFORCEMENT_TIER_SET = frozenset(ENFORCEMENT_TIERS)
+
+
+def is_enforcement_tier(value: object) -> TypeGuard[EnforcementTier]:
+    """Return whether *value* is an exact v1 enforcement-tier member."""
+    return type(value) is str and value in _ENFORCEMENT_TIER_SET

termverify/_json.py

@@ -0,0 +1,7 @@
+"""Mutable JSON value shape used by v1 protocol boundaries."""
+
+from __future__ import annotations
+
+type JsonValue = (
+    None | bool | int | float | str | list["JsonValue"] | dict[str, "JsonValue"]
+)