quantred 2.4.0__py3-none-any.whl

quantred/execution/decision.py

@@ -0,0 +1,192 @@
+"""What execution decided, and why.
+
+A signal that produced no order used to leave a log line and nothing else. The engine
+saw ``None``, which is the same answer for "the market is closed", "we are halted",
+"you already hold this", "the size rounded to zero", and "the broker refused" - so
+the one question worth asking afterwards, *why did nothing happen on that bar*, could
+only be answered by reading logs, if they still existed.
+
+A :class:`Decision` makes the answer a value instead. It records the outcome, the
+reason in words, and - importantly - **which guards were consulted**, not merely which
+one fired. A veto list that only ever names the guard that tripped cannot distinguish
+a guard that passed from a guard that never ran, which is exactly how a check silently
+stops being applied and nobody notices.
+
+Trade-clock code: plain stdlib, no research imports, nothing that can block.
+"""
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Tuple
+
+from quantred.brokers.base import OrderResult
+
+# The guards, named once so a reason string and a consulted-list entry cannot drift.
+HOLD = "hold"
+MARKET_HOURS = "market_hours"
+HALT = "halt"
+EXISTING_POSITION = "existing_position"
+PENDING_ORDER = "pending_order"
+ACCOUNT = "account"
+SIZING = "sizing"
+MIN_NOTIONAL = "min_notional"
+BUYING_POWER = "buying_power"
+POSITION_LIMITS = "position_limits"
+BROKER = "broker"
+POSITION_MATCH = "position_match"
+
+# Why a refusal happened, as a stable family. The reason *message* embeds the numbers
+# that caused it - "gross exposure capped: $7,617.12 of $7,200.00" - so counting
+# messages turns sixteen refusals of one kind into sixteen rows of one, which hides a
+# throttle rather than showing it. The code groups; the message still explains.
+BOOK_FULL = "book_full"
+GROSS_EXPOSURE = "gross_exposure_capped"
+NET_EXPOSURE = "net_exposure_capped"
+RISK_BUDGET = "risk_budget_exhausted"
+EQUITY_UNREADABLE = "equity_unreadable"
+#: The two ways a book can be too small to express a position in a name at all. Coded
+#: rather than left as bare text because they are the signature of a book traded below
+#: the size it was validated at, and counting them is the only way that shows up as a
+#: number instead of as a strategy that mysteriously stopped trading the expensive
+#: names. The messages carry the amounts, so grouping by message would scatter one
+#: cause across as many rows as there were symbols.
+BELOW_MIN_NOTIONAL = "below_min_notional"
+ROUNDS_TO_ZERO = "size_rounds_to_zero"
+#: The kill switch refusing an entry. Distinct from the ``HALT`` guard name above: that
+#: says the check ran, this says it fired. Coded for the same reason the caps are — the
+#: message carries the halt's own reason, actor and *timestamp*, so re-halting for a new
+#: reason, or halting a second strategy, split one throttle into a row per halt. A
+#: reader counting refusal kinds would see several one-off families and no halt.
+HALTED = "halted"
+
+#: Message prefixes written before decisions carried a code, mapped to the family they
+#: belong to. A read-path concern only: rows written from here on carry a code and never
+#: consult this. It exists because an append-only ledger keeps its history, so a report
+#: that groups only new rows shows one throttle as two — some tidy families beside a
+#: scatter of one-off messages saying the same thing.
+#:
+#: Matched by prefix because the numbers follow the colon. A message not listed keeps
+#: its own text rather than being forced into a family it may not belong to.
+_LEGACY_REASON_PREFIXES = (
+    ("book is full", BOOK_FULL),
+    ("gross exposure capped", GROSS_EXPOSURE),
+    ("net exposure capped", NET_EXPOSURE),
+    ("risk budget exhausted", RISK_BUDGET),
+    ("cannot check portfolio limits", EQUITY_UNREADABLE),
+    # Every halted refusal already in a ledger was written without a code, and the words
+    # before the em dash are the only stable part of the message.
+    ("halted", HALTED),
+)
+
+
+def reason_family(record: Dict[str, Any]) -> str:
+    """The family a recorded decision belongs to, whenever it was written.
+
+    Prefers the code the decision carries. Falls back to recognising the message a
+    pre-code row was written with, and finally to the message itself — which is the
+    right answer for a fixed phrase like "market is closed" that has no numbers in it
+    and therefore never fragmented in the first place.
+    """
+    code = record.get("reason_code")
+    reason = str(record.get("reason") or "")
+    # A pre-code row has no `reason_code` at all; a coded row whose value equals its own
+    # message is one that never had a family, and both are worth normalising.
+    if code and code != reason:
+        return str(code)
+    for prefix, family in _LEGACY_REASON_PREFIXES:
+        if reason.startswith(prefix):
+            return family
+    return reason or "unknown"
+
+
+@dataclass(frozen=True)
+class OrderPlan:
+    """What execution intended to send, recorded whether or not the venue took it.
+
+    Separate from the :class:`~quantred.brokers.base.OrderResult` the broker returns,
+    because the interesting comparison is between the two. A result alone cannot say
+    what price the decision was made at, and so cannot say what the fill cost relative
+    to it.
+    """
+
+    side: str
+    qty: float
+    #: The price the signal fired at — the bar close execution decided on. Everything
+    #: called "slippage" downstream is measured against this and nothing else.
+    reference_price: float
+    order_type: str = "bracket"
+    time_in_force: str = "day"
+    stop_loss: Optional[float] = None
+    take_profit: Optional[float] = None
+    client_order_id: Optional[str] = None
+    #: What the cost model expected this to cost. Deliberately not stored in the same
+    #: field as a broker fee: a paper venue reports no fees, and collapsing the two
+    #: would make a modelled number look like an observed one.
+    cost_estimate: Optional[float] = None
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "side": self.side,
+            "qty": self.qty,
+            "reference_price": self.reference_price,
+            "order_type": self.order_type,
+            "time_in_force": self.time_in_force,
+            "stop_loss": self.stop_loss,
+            "take_profit": self.take_profit,
+            "client_order_id": self.client_order_id,
+            "cost_estimate": self.cost_estimate,
+        }
+
+
+@dataclass(frozen=True)
+class Decision:
+    """The outcome of handing one signal to execution."""
+
+    symbol: str
+    signal: str
+    allowed: bool
+    reason: str
+    guards_consulted: Tuple[str, ...] = field(default_factory=tuple)
+    order: Optional[OrderResult] = None
+    #: Joins this decision to the intent and the fills that follow it. Generated for
+    #: declines too — "why did nothing happen" is the question the audit trail exists
+    #: for, and a decline with no id cannot be referred to.
+    decision_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    plan: Optional[OrderPlan] = None
+    #: Stable family for this outcome, for grouping. ``None`` where the reason text is
+    #: already a fixed phrase with no numbers in it.
+    reason_code: Optional[str] = None
+
+    def __bool__(self) -> bool:
+        """Truthy when execution acted, so callers can read as `if decision:`."""
+        return self.allowed
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "symbol": self.symbol,
+            "signal": self.signal,
+            "allowed": self.allowed,
+            "reason": self.reason,
+            "guards_consulted": list(self.guards_consulted),
+            "order_id": self.order.id if self.order is not None else None,
+            "decision_id": self.decision_id,
+            "reason_code": self.reason_code or self.reason,
+            "plan": self.plan.as_dict() if self.plan is not None else None,
+        }
+
+    def __str__(self) -> str:
+        verdict = "acted" if self.allowed else "declined"
+        return f"{self.signal} {self.symbol}: {verdict} — {self.reason}"
+
+
+def allow(symbol, signal, reason, guards, order=None, plan: Optional[OrderPlan] = None) -> Decision:
+    return Decision(symbol, signal, True, reason, guards, order, plan=plan)
+
+
+def decline(symbol, signal, reason, guards, plan=None, code: Optional[str] = None) -> Decision:
+    """A refusal. ``plan`` is carried when there was one, so a declined entry still
+    records what it would have sent — otherwise the size a limit rejected is lost.
+
+    ``code`` groups refusals of the same kind whose messages differ only in numbers.
+    """
+    return Decision(symbol, signal, False, reason, guards, None, plan=plan, reason_code=code)

quantred/execution/flatten.py

@@ -0,0 +1,302 @@
+"""Flatten: stop, cancel everything, close everything.
+
+The most drastic thing this system can be asked to do, and the one most likely to be
+asked for by someone who does not trust it any more. Two properties follow from that.
+
+**It goes through the broker, not the engine.** Nothing here asks a running
+:class:`~quantred.engine.live.LiveEngine` to do anything, so it works when the engine
+is wedged, mid-restart, or holding state that is exactly what you no longer believe.
+
+**It halts first.** Cancelling and closing while an engine is still streaming bars is
+a race the engine can win - it re-enters on the next bar, and the account refills
+behind you. Recording the halt before touching anything closes that window, and is
+also the step most worth having if a later one fails.
+
+Every step is attempted even if an earlier one failed. A partial flatten is a bad
+outcome, but stopping halfway through because the cancel call errored - and leaving
+the positions open - is a worse one. What actually happened comes back in the report,
+and the exit code reflects it.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from quantred.brokers.base import Broker
+from quantred.brokers.errors import BrokerError
+from quantred.execution.halt import ALL, HaltState
+from quantred.settings import invocation
+
+logger = logging.getLogger(__name__)
+
+
+#: What a broker read afterwards actually established about the positions.
+#:
+#: Four values, not a boolean, because submitting a close and observing it is not the
+#: same fact and the gap between them is where an operator gets hurt. Closes queue
+#: outside market hours and fill piecemeal at the open: a real flatten reported every
+#: position closed and the account still held its whole book minutes later.
+CLOSED = "yes"  # a broker read came back with no positions
+PENDING = "pending"  # closes were submitted and positions are still open
+NOT_CLOSED = "no"  # the close request itself failed, and positions are still open
+UNKNOWN = "unknown"  # the confirming read failed; nothing here knows what is open
+
+
+@dataclass
+class FlattenReport:
+    """What each step of the flatten did, and what a broker read afterwards observed.
+
+    The distinction this type exists to keep is between a request that was *accepted*
+    and a state that was *observed*. ``close_submitted`` is the first; ``observed`` is
+    the second, and only the second can be called flat.
+    """
+
+    started_at: str
+    halted: bool = False
+    orders_cancelled: bool = False
+    close_submitted: bool = False
+    observed: str = UNKNOWN
+    checked_at: Optional[str] = None
+    remaining: List[str] = field(default_factory=list)
+    #: Resting orders the confirming read still saw. ``None`` means it could not be
+    #: asked — absent, not zero, in the field that decides whether the book can refill.
+    open_orders: Optional[int] = None
+    failures: List[str] = field(default_factory=list)
+    #: Symbols recorded in the ledger as closed by this flatten. ``None`` means no
+    #: ledger was given, which is different from an empty list: the first says nobody
+    #: was told, the second says there was nothing this ledger still expected.
+    recorded_closed: Optional[List[str]] = None
+
+    @property
+    def complete(self) -> bool:
+        """Flat, and known to be. Deliberately requires the *observation*.
+
+        This used to be satisfied by the close call returning, so a flatten whose orders
+        merely queued reported success and printed a reassuring next step. Submission is
+        not a terminal state; nothing may claim one without a read that saw it.
+
+        Both legs are held to that. ``open_orders == 0`` rather than ``orders_cancelled``
+        because the cancel is a submitted fact too, and a resting order the cancel missed
+        can refill the book after the instant the read was taken — so a verifiably empty
+        account with an unknown order book is not a terminal state either. ``None``
+        (unreadable) fails this, as it should.
+        """
+        return self.halted and self.observed == CLOSED and self.open_orders == 0
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "started_at": self.started_at,
+            "complete": self.complete,
+            "halted": self.halted,
+            "orders_cancelled": self.orders_cancelled,
+            "close_submitted": self.close_submitted,
+            "observed": self.observed,
+            "checked_at": self.checked_at,
+            "remaining": self.remaining,
+            "open_orders": self.open_orders,
+            "failures": self.failures,
+            "recorded_closed": self.recorded_closed,
+        }
+
+    def summary(self) -> str:
+        remaining = (
+            f"{len(self.remaining)} ({', '.join(sorted(self.remaining))})"
+            if self.remaining
+            else ("none" if self.observed == CLOSED else "unknown")
+        )
+        lines = [
+            "FLATTEN",
+            f"  halt set                  : {'yes' if self.halted else 'NO'}",
+            f"  orders cancelled          : {'yes' if self.orders_cancelled else 'NO'}",
+            f"  close orders submitted    : {'yes' if self.close_submitted else 'NO'}",
+            f"  positions observed closed : {self.observed}",
+            f"  last broker position check: {self.checked_at or 'never'}",
+            f"  remaining positions       : {remaining}",
+            f"  resting orders observed   : {'unknown' if self.open_orders is None else self.open_orders}",
+        ]
+        if self.recorded_closed is None:
+            lines.append("  recorded in the ledger    : no ledger given")
+        elif self.recorded_closed:
+            lines.append(
+                f"  recorded in the ledger    : {len(self.recorded_closed)} "
+                f"({', '.join(self.recorded_closed)}) closed by operator"
+            )
+        else:
+            lines.append("  recorded in the ledger    : nothing was expected there")
+        for failure in self.failures:
+            lines.append(f"  ! {failure}")
+
+        if self.complete:
+            lines.append("\nFlat, and confirmed by a broker read at the time above: no")
+            lines.append("positions and no resting orders. The engine cannot re-enter while")
+            lines.append(f"the halt stands; `{invocation('resume all')}` when you are ready.")
+        elif self.observed == PENDING:
+            # The case that used to read as success. Say what is true and no more. It
+            # must NOT promise a fill: a symbol refused for being halted, non-tradable
+            # or restricted never will, and this cannot tell that apart from a queued
+            # close, because the venue's per-symbol answer is not surfaced here.
+            lines.append("\nNOT FLAT — the close orders were accepted and these positions are")
+            lines.append("still open. A queued close fills at the next open; a *refused* one")
+            lines.append("never will, and this cannot tell them apart. Re-run to re-read, and")
+            lines.append("check the symbols above at the broker if they persist.")
+        elif self.observed == UNKNOWN:
+            lines.append("\nUNCONFIRMED — the position read failed, so nothing here knows what")
+            lines.append("is open. Check the broker directly.")
+        elif self.observed == CLOSED:
+            # Positions verifiably gone, but something else is unfinished. The old
+            # catch-all said "finish by hand" while pointing at the positions, which are
+            # the one thing that is done.
+            lines.append("\nPOSITIONS FLAT, BUT NOT FINISHED:")
+            unfinished = []
+            if not self.halted:
+                unfinished.append("the halt was not recorded, so the engine may re-enter")
+            if self.open_orders is None:
+                unfinished.append("the resting orders could not be read")
+            elif self.open_orders:
+                unfinished.append(f"{self.open_orders} order(s) still resting, which can refill the book")
+            for item in unfinished or ["something above did not complete"]:
+                lines.append(f"  - {item}")
+        else:
+            lines.append("\nNOT FLAT — the close request was not accepted and these positions")
+            lines.append("are still open. Check the broker directly and finish by hand.")
+        return "\n".join(lines)
+
+
+def flatten(
+    broker: Broker,
+    *,
+    reason: str,
+    actor: str = "cli",
+    halt_state: Optional[HaltState] = None,
+    ledger: Optional[Any] = None,
+) -> FlattenReport:
+    """Halt, cancel all open orders, and close all positions. Returns what happened.
+
+    ``ledger`` is optional and the flatten works without one, deliberately: this path
+    has to run when the engine is wedged, and a ledger that cannot be written must never
+    be the reason a book stays open. Given one, the positions it was still expecting are
+    recorded as closed by an operator — see :meth:`PositionLedger.record_flatten` — so a
+    reconciliation afterwards does not report every one of them as a dropped fill.
+    """
+    report = FlattenReport(started_at=datetime.now(timezone.utc).isoformat())
+    halts = halt_state or HaltState()
+
+    try:
+        halts.set(f"flatten: {reason}", actor=actor, scope=ALL)
+        report.halted = True
+    except OSError as exc:
+        # Keep going. An un-halted flatten is worth far more than no flatten, and the
+        # report says plainly that re-entry is not blocked.
+        report.failures.append(f"could not record the halt: {exc}")
+        logger.error("Could not record the halt; continuing to cancel and close", exc_info=True)
+
+    try:
+        broker.cancel_all_orders()
+        report.orders_cancelled = True
+    except BrokerError as exc:
+        report.failures.append(f"could not cancel open orders: {exc}")
+        logger.error("Could not cancel open orders; still attempting to close positions", exc_info=True)
+
+    try:
+        # Orders were cancelled above; asking again is harmless and covers the case
+        # where that call failed but the close path can still clear them.
+        # The return value is consulted, not discarded. A broker that answers False has
+        # said it did not take the request, and recording that as "submitted" would be
+        # the same lie this change exists to remove, one line above the fix.
+        report.close_submitted = bool(broker.close_all_positions(cancel_orders=True))
+        if not report.close_submitted:
+            report.failures.append("the broker did not accept the close request")
+    except BrokerError as exc:
+        report.failures.append(f"could not close positions: {exc}")
+        logger.error("Could not close positions", exc_info=True)
+
+    _confirm(broker, report)
+
+    # Only on an observed-flat book, and only for what this ledger was expecting.
+    # `pending` means the closes were accepted and nothing has confirmed they filled;
+    # recording a terminal fact there would assert an exit nobody has seen, which is
+    # the submitted-versus-observed confusion this module exists to end.
+    if ledger is not None and report.observed == CLOSED:
+        try:
+            report.recorded_closed = ledger.record_flatten(
+                sorted(ledger.expected_positions()),
+                reason=reason,
+                actor=actor,
+                checked_at=report.checked_at,
+            )
+        except Exception as exc:  # noqa: BLE001 - a bookkeeping failure must not fail the flatten
+            report.failures.append(f"could not record the flatten in the ledger: {exc}")
+            logger.error("Could not record the flatten in the ledger", exc_info=True)
+
+    if report.complete:
+        logger.warning("Flatten complete and confirmed flat: %s", reason)
+    elif report.observed == PENDING:
+        logger.error(
+            "Flatten submitted but NOT FLAT: %d position(s) still open at %s (%s)",
+            len(report.remaining),
+            report.checked_at,
+            ", ".join(sorted(report.remaining)),
+        )
+    else:
+        logger.error("Flatten INCOMPLETE: %s", report.failures)
+    return report
+
+
+def _confirm(broker: Broker, report: FlattenReport) -> None:
+    """Ask the broker what is actually open, and record it.
+
+    The step that makes the difference between "we asked" and "it happened". A close is
+    a *request*: outside market hours it queues, and at the open it fills piecemeal, so
+    the interval where the account still holds everything is minutes wide at best.
+
+    One read, and no waiting. This is the command someone runs when they have stopped
+    trusting the system, so it must answer now rather than block on a fill that may be
+    hours away — and it must never poll a broker in a loop. Reporting a truthful
+    ``pending`` is worth more than a confident answer arrived at late.
+
+    A read that fails leaves ``UNKNOWN``, never ``CLOSED``: this is exactly the place
+    where an absent answer must not be rendered as a clean one.
+    """
+    report.checked_at = datetime.now(timezone.utc).isoformat()
+    try:
+        positions = broker.list_positions()
+        if positions is None:
+            # A broker that answers "I don't know" must not be read as "nothing is
+            # open". `or []` did exactly that, in the one function whose whole purpose
+            # is refusing to call an unobserved book flat.
+            raise BrokerError("broker returned no position list")
+        # Inside the guard: a lazy or paged result raises while being consumed, not
+        # when it is returned.
+        report.remaining = [position.symbol for position in positions]
+    except Exception as exc:  # noqa: BLE001 - see below
+        # Deliberately bare, matching `PositionLedger.reconcile`. This is a *reporting*
+        # step running after the halt, the cancel and the closes have already happened,
+        # and a reporting step that raises destroys the report of the order path — the
+        # operator loses not just the confirmation but the fact that the halt was set
+        # and the closes were sent. Catching only `BrokerError` was a promise about
+        # brokers this module does not control: a `TimeoutError` from a socket, or an
+        # `AttributeError` from a partial implementation, escaped and left a traceback
+        # where the report should be. `UNKNOWN` already means precisely this.
+        report.failures.append(f"could not confirm positions: {exc}")
+        report.observed = UNKNOWN
+        logger.error("Could not confirm the flatten against the broker", exc_info=True)
+        return
+
+    if report.remaining:
+        report.observed = PENDING if report.close_submitted else NOT_CLOSED
+    else:
+        report.observed = CLOSED
+
+    # The same question asked of the other leg. `orders_cancelled` is a *submitted*
+    # fact, and this change exists because submitted is not observed — applying that to
+    # the positions and not to the orders would leave `complete` meaning "one observed
+    # fact and one hopeful one". A resting order the cancel missed can refill the book
+    # after the instant this read was taken.
+    try:
+        resting = broker.list_open_orders()
+        report.open_orders = len(resting or [])
+    except Exception as exc:  # noqa: BLE001 - as above; never break the report
+        report.failures.append(f"could not confirm open orders: {exc}")
+        report.open_orders = None
+        logger.error("Could not confirm resting orders against the broker", exc_info=True)

quantred/execution/halt.py

@@ -0,0 +1,165 @@
+"""The kill switch.
+
+There was previously no way to say "stop trading" and have it stick. Orders could be
+cancelled and positions closed, but nothing recorded the *decision*, so a running
+engine would open a new position on the next bar and an operator who had just
+flattened the account would watch it refill. Stopping needs durable state, not a
+one-off action.
+
+That state is a file, deliberately:
+
+**No database on the trade clock.** The order path holds no connection to anything
+that can be down. A file under the state root is readable by a hung engine, by the
+CLI, and by a human with `cat`, which is exactly the population that needs it during
+an incident.
+
+**A halt blocks entries, never exits.** A switch that also blocked closing orders
+would trap the book at precisely the moment someone had decided to stop - and would
+deadlock any flatten against its own gate. Getting out is always allowed.
+
+**It reports; it does not remediate.** Setting a halt places no orders and closes
+nothing. Flattening is a separate, explicit act (:mod:`quantred.execution.flatten`).
+
+**Absent is not halted.** A missing or unreadable file means "no halt recorded", so a
+corrupt state file cannot silently freeze trading. The reverse default would make an
+unrelated disk problem look like a deliberate stop.
+"""
+
+import json
+import logging
+import os
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+#: The scope that halts everything, whatever strategy is running.
+ALL = "all"
+
+_LOCK = threading.Lock()
+
+
+def default_halt_path() -> Path:
+    """Where halt state lives - beside the ledger, under the state root."""
+    from quantred.settings import state_path
+
+    return state_path("logs", "halts.json")
+
+
+@dataclass(frozen=True)
+class Halt:
+    """One recorded decision to stop trading."""
+
+    scope: str
+    reason: str
+    actor: str
+    set_at: str
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {"scope": self.scope, "reason": self.reason, "actor": self.actor, "set_at": self.set_at}
+
+    def __str__(self) -> str:
+        return f"[{self.scope}] {self.reason} (set by {self.actor} at {self.set_at})"
+
+
+class HaltState:
+    """Durable halt state, scoped globally or to a single strategy."""
+
+    def __init__(self, path: Optional[Any] = None):
+        self.path = Path(path) if path else default_halt_path()
+
+    # ------------------------------------------------------------------ #
+    # Reading
+    # ------------------------------------------------------------------ #
+    def active(self, scope: Optional[str] = None) -> Optional[Halt]:
+        """The halt in force for ``scope``, if any. A global halt covers every scope.
+
+        Returns the global halt in preference to a scoped one, since that is the more
+        severe of the two and the more useful thing to show an operator.
+        """
+        halts = self._read()
+        if ALL in halts:
+            return halts[ALL]
+        if scope is not None and scope in halts:
+            return halts[scope]
+        return None
+
+    def is_halted(self, scope: Optional[str] = None) -> bool:
+        return self.active(scope) is not None
+
+    def list(self) -> List[Halt]:
+        return sorted(self._read().values(), key=lambda h: h.set_at, reverse=True)
+
+    # ------------------------------------------------------------------ #
+    # Writing
+    # ------------------------------------------------------------------ #
+    def set(self, reason: str, *, actor: str, scope: str = ALL) -> Halt:
+        """Record a halt. Re-halting an already-halted scope replaces the reason."""
+        halt = Halt(
+            scope=scope,
+            reason=reason,
+            actor=actor,
+            set_at=datetime.now(timezone.utc).isoformat(),
+        )
+        halts = self._read()
+        halts[scope] = halt
+        self._write(halts)
+        logger.warning("HALT SET %s", halt)
+        return halt
+
+    def clear(self, scope: str = ALL) -> bool:
+        """Lift a halt. Returns True if one was actually in force."""
+        halts = self._read()
+        if scope not in halts:
+            return False
+        removed = halts.pop(scope)
+        self._write(halts)
+        logger.warning("Halt cleared: %s", removed)
+        return True
+
+    # ------------------------------------------------------------------ #
+    # Storage
+    # ------------------------------------------------------------------ #
+    def _read(self) -> Dict[str, Halt]:
+        if not self.path.exists():
+            return {}
+        try:
+            raw = json.loads(self.path.read_text() or "{}")
+        except (OSError, json.JSONDecodeError):
+            # Absent is not halted: an unreadable file must not look like a decision
+            # nobody made. Loud, because the switch is now not working.
+            logger.error("Halt state at %s is unreadable; treating as NO halt", self.path, exc_info=True)
+            return {}
+        if not isinstance(raw, dict):
+            # Valid JSON that is not an object - `null`, a list, a bare number. Only a
+            # hand edit produces one, which is exactly when this is read: during an
+            # incident. Without this the scope loop raises AttributeError straight out
+            # of the entry decision on the trade clock, which is the reverse of the
+            # default this module promises, arriving as a crash rather than a halt.
+            logger.error("Halt state at %s is not an object; treating as NO halt", self.path)
+            return {}
+        halts = {}
+        for scope, record in raw.items():
+            try:
+                halts[scope] = Halt(
+                    scope=scope,
+                    reason=record["reason"],
+                    actor=record.get("actor", "unknown"),
+                    set_at=record.get("set_at", ""),
+                )
+            except (TypeError, KeyError):
+                logger.error("Skipping malformed halt record for scope %r", scope)
+        return halts
+
+    def _write(self, halts: Dict[str, Halt]) -> None:
+        payload = json.dumps({scope: halt.as_dict() for scope, halt in halts.items()}, indent=2)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        # Write-then-rename: a process killed mid-write leaves the previous state
+        # intact rather than a truncated file that reads as "no halt".
+        temporary = self.path.with_suffix(".json.tmp")
+        with _LOCK:
+            temporary.write_text(payload)
+            os.replace(temporary, self.path)