Di Result

1"""The structured result returned by instrumentation-config / status operations.
2
3WHY THIS EXISTS
4The CRUD and status operation functions (in ``di_crud_tools`` / ``di_status_tools``)
5return a human-readable string for both success and failure and never raise. That
6text is what the agent reads. But the entry script (``di_instrumentation.py``) also
7needs to derive a process exit code from each operation, and historically it did so
8by *string-matching* the rendered prose ("Failed to ...", "DELETE ERRORS:", etc.) —
9wording owned by several other modules. Rewording any renderer could silently flip a
10real failure to exit 0.
11
12``OpResult`` separates the two concerns that the bare string conflated:
13
14* ``ok``   — the STATUS channel. Drives the process exit code (``0`` if ``ok`` else
15             ``1``). Set by each operation at the point where success vs. failure is
16             actually known (the ``except GatewayError`` site, the early ``ERROR:``
17             return, the success render).
18* ``text`` — the PRESENTATION channel. The rendered human string, unchanged from
19             before; the entry script prints it verbatim.
20
21``ok`` is about whether the *operation* succeeded, NOT about the AWS instrumentation
22lifecycle state. A ``check-status`` call that successfully reports a breakpoint in the
23ERROR state is ``OpResult(ok=True, ...)`` — the query succeeded; the breakpoint's
24status being ERROR is content in ``text``.
25
26This module imports nothing so the entry script and both tools modules can import it
27without any risk of an import cycle.
28"""
29
30from dataclasses import dataclass
31
32
33@dataclass(frozen=True)
34class OpResult:
35    """The (status, presentation) pair an operation returns.
36
37    Attributes:
38        ok: True when the operation succeeded; False for any input/validation/AWS
39            failure. Maps to exit code ``0``/``1`` in the entry script.
40        text: The rendered human-readable message the agent reads (printed verbatim).
41    """
42
43    ok: bool
44    text: str