Item 4: one declared order, walked by both modes

src/ctrlrun/authority.py

@@ -943,6 +943,44 @@ def unmatched_shape(grant: Grant, action: Action) -> str | None:
     return None
 
 
+def narrowed_dimensions(parent: Grant, child: Grant) -> tuple[str, ...]:
+    """Which of §5.4's rows `child` makes strictly stricter than `parent` (SPEC-v0.10 §6.2).
+
+    **A reporting helper. It decides nothing**, and that is the line that keeps §2.2's
+    one-relation rule intact: `contained_dimension` stays the only thing any decision calls, and a
+    build where this disagreed with it would be wrong about a rendering rather than about an
+    authorization.
+
+    It exists because `contained_dimension` computes the **complement**: the first row a child
+    *violates*, or `None` where it is contained. An operator reading a refused action's chain needs
+    the other question, *which link took the resource away*, and no name in the tree answered it.
+
+    Plural, in `DIMENSIONS` order. A hop narrowed on every dimension narrows on several at once
+    (T470), so a singular answer has no definition.
+    """
+    narrowed: list[str] = []
+    if parent.subject != child.subject:
+        narrowed.append("subject")
+    if set(parent.actions) != set(child.actions):
+        narrowed.append("actions")
+    if parent.resources != child.resources and child.resources is not None:
+        narrowed.append("resources")
+    if dict(parent.constraints) != dict(child.constraints):
+        narrowed.append("constraints")
+    if parent.environments != child.environments and child.environments is not None:
+        narrowed.append("environments")
+    if child.expires_at is not None and (
+        parent.expires_at is None or child.expires_at < parent.expires_at
+    ):
+        narrowed.append("expires_at")
+    if parent.tasks != child.tasks and child.tasks is not None:
+        narrowed.append("tasks")
+    if parent.budgets != child.budgets and child.budgets is not None:
+        narrowed.append("budgets")
+    order = {name: index for index, name in enumerate(DIMENSIONS)}
+    return tuple(sorted(narrowed, key=lambda name: order[name]))
+
+
 def contained_dimension(parent: Grant, child: Grant) -> str | None:
     """The first §5.4 row `child` violates, or `None` where it is contained on every one.
 
@@ -2342,6 +2380,7 @@ def _reject_unknown_keys(mapping: Mapping[Any, Any], allowed: Iterable[str], whe
     "grant_from_yaml",
     "grant_to_json",
     "matches",
+    "narrowed_dimensions",
     "new_delegation_id",
     "unmatched_shape",
     "validate_pattern",

src/ctrlrun/cli/main.py

@@ -44,6 +44,8 @@
 from ..reporting import (
     budget_document,
     budget_lines,
+    hop_document,
+    hop_lines,
     inspection_for,
     ledger_rows,
     since_boundary,
@@ -621,10 +623,19 @@ def resolve(effect_key: str, committed: bool, failed: bool, store_url: str | Non
     "grant_id",
     help="Show this grant's budgets instead: consumed, held, and what holds it.",
 )
+@click.option(
+    "--hop",
+    "hop_id",
+    help="Show this hop or delegation instead: who issued it, and what each link narrowed.",
+)
 @click.option("--json", "as_json", is_flag=True, help="Emit one JSON object instead.")
 @STORE_URL_OPTION
 def inspect(
-    action_id: str | None, grant_id: str | None, as_json: bool, store_url: str | None
+    action_id: str | None,
+    grant_id: str | None,
+    hop_id: str | None,
+    as_json: bool,
+    store_url: str | None,
 ) -> None:
     """Show one action's whole history: proposal, decision, approval, effect, receipt.
 
@@ -635,15 +646,24 @@ def inspect(
     The third number is the one that matters at 3am. A budget that refuses while it looks
     nowhere near its limit is almost always one unresolved effect: `ctrlrun resolve` clears it.
     """
-    if (action_id is None) == (grant_id is None):
-        # §7.1 keeps both behind one command, which makes "which of the two did you mean" this
-        # command's own question. Neither names a subject; both name two.
+    given = [
+        name
+        for name, value in (("ACTION_ID", action_id), ("--grant", grant_id), ("--hop", hop_id))
+        if value
+    ]
+    if len(given) != 1:
+        # `v0.9 §7.1` keeps them behind one command, which makes "which of these did you mean"
+        # this command's own question. None names a subject; each names two.
         raise click.UsageError(
-            "give an ACTION_ID, or --grant GRANT_ID, and not both: they inspect different things"
+            "give exactly one of ACTION_ID, --grant GRANT_ID or --hop DELEGATION_ID: they "
+            "inspect different things"
         )
     if grant_id is not None:
         _inspect_grant(grant_id, as_json, store_url)
         return
+    if hop_id is not None:
+        _inspect_hop(hop_id, as_json, store_url)
+        return
     assert action_id is not None
     store = _store(store_url)
     try:
@@ -672,6 +692,35 @@ def inspect(
         click.echo(line)
 
 
+def _inspect_hop(hop_id: str, as_json: bool, store_url: str | None) -> None:
+    """SPEC-v0.10 §6.2, behind `ctrlrun inspect --hop`.
+
+    Answers about a **hop or an ordinary delegation alike**, because an operator paged about a
+    refusal does not yet know which kind they have: `created_via` is rendered rather than filtered
+    on.
+    """
+    try:
+        control = _control_on(store_url)
+        authority = control._authority
+        if authority is None:
+            raise click.ClickException(
+                "this configuration has no 'authority:' section, so it holds no hops "
+                "(SPEC-v0.3 §4.1)"
+            )
+        document = hop_document(hop_id, authority, control._store)
+        if document is None:
+            # Exits non-zero with nothing on stdout, as `inspect` does for an unknown action, so
+            # a script cannot mistake "no such hop" for "a hop with no chain".
+            raise click.ClickException(f"no hop {hop_id}")
+    except CTRLRunError as exc:
+        raise _fail(exc) from exc
+    if as_json:
+        click.echo(json.dumps(document, ensure_ascii=False, indent=2))
+        return
+    for line in hop_lines(document):
+        click.echo(line)
+
+
 def _inspect_grant(grant_id: str, as_json: bool, store_url: str | None) -> None:
     """SPEC-v0.9 §7.2, behind `ctrlrun inspect --grant`.
 

src/ctrlrun/control.py

@@ -50,6 +50,8 @@
     unsatisfied,
 )
 from .authority import (
+    NO_AUTHORITY,
+    REASON_PRECEDENCE,
     RESOURCE_SEPARATOR,
     Authority,
     AuthorityResult,
@@ -101,6 +103,7 @@
     OBSERVE,
     POLICY_CHANGE_ACTION,
     POLICY_UNAPPROVED,
+    UPSTREAM_MISMATCH,
     UPSTREAM_UNVERIFIED,
     Decision,
     Evaluation,
@@ -110,6 +113,8 @@
 )
 from .receipt import (
     BLOCKED_AMBIGUOUS,
+    BLOCKED_APPROVAL_MISMATCH,
+    BLOCKED_APPROVAL_REASONS,
     BLOCKED_APPROVAL_REQUIRED,
     BLOCKED_ATTEMPT_CEILING,
     BLOCKED_DUPLICATE,
@@ -408,9 +413,18 @@
     `_observe_secure` and `_outcome`, and threading four extra values through all three would
     put the same fact in three signatures.
 
-    `block()` keeps the **first** reason, because the checks run in the order enforce mode
-    runs them and enforce mode stops at the first: a later refusal is one enforce mode would
-    never have reached.
+    **`block()` keeps the reason earliest in `DECISION_ORDER`, not the first one it is handed**
+    (SPEC-v0.10 §5). The docstring here used to say the opposite, and say it for a reason that was
+    not true: "the checks run in the order enforce mode runs them". They do not, which is what
+    `v0.9 §4.2.1b` records, and keeping the first is how observe mode came to name a refusal
+    enforce mode would not raise.
+
+    **What this does not do is move a check**, and that is the point. v0.9 aligned three cases by
+    reordering and the three reorderings produced four regressions between them (`v0.9 §13.8`).
+    The information was never missing: a probe over §4.2.1b's own second case shows observe mode
+    is handed `['no_authority', 'policy_unapproved']` and reports the first, while enforce mode
+    raises the second. Ordering the **selection** is enough, and it cannot regress a check's
+    position because it changes none.
     """
 
     __slots__ = ("blocked_reason", "decision", "reason")
@@ -425,7 +439,13 @@
         self.reason = evaluation.reason
 
     def block(self, reason: str) -> None:
-        if self.blocked_reason is None:
+        """Record a refusal enforce mode would have raised, keeping the one it would raise FIRST.
+
+        A reason `DECISION_ORDER` does not name sorts last among itself and still loses to any
+        reason it does name, which is the fail-safe direction for a reason somebody adds without
+        listing it: the report stays a refusal and names something the order knows.
+        """
+        if self.blocked_reason is None or _rank(reason) < _rank(self.blocked_reason):
             self.blocked_reason = reason
 
     def frozen(self) -> _WouldHave:
@@ -666,6 +686,93 @@
 SCOPE_UNAVAILABLE: Final = "scope_unavailable"
 OUT_OF_SCOPE: Final = "out_of_scope"
 
+#: SPEC-v0.10 §5 — **the order enforce mode decides in, declared once, as data.**
+#:
+#: `control.py` has carried this sequence as a comment since v0.3 (`principal_expired ->
+#: authority -> policy -> approval -> reservation -> execution`). Making it a value is the whole
+#: of item 4: observe mode's checks do not run in this order, `_Observation.block` used to keep
+#: whichever it was handed first, and `v0.9 §4.2.1b` is the record of what that cost.
+#:
+#: **The list starts at `Control.execute`'s entry, not at `_secure`.** `policy_unapproved` is
+#: decided by `_require_approved` above authority, while `_observe_secure` is not called until
+#: several hundred lines later; an ordering beginning at `_secure` could not have covered it.
+#:
+#: **Groups, and every group that has a source is read from it.** `receipt.py`'s own comment
+#: records this set being missed twice, and says why
+#: `test_every_approval_refusal_reason_is_counted_by_stats` enumerates from `approval.py` rather
+#: than restating: *a set maintained by hand is a set the next reason is missed from.* This list
+#: was hand-written once and `attempt_ceiling` was missing from it within the hour, caught by
+#: T250. So the authority group is `REASON_PRECEDENCE` and the approval group is
+#: `BLOCKED_APPROVAL_REASONS`, both imported, and neither can drift from its owner.
+_ORDERED_GROUPS: Final[tuple[tuple[str, ...], ...]] = (
+    (PRINCIPAL_EXPIRED,),
+    # Above authority: `v0.8 §8.4`, a policy nobody approved decides nothing, checked before
+    # anything else is decided because what follows would be decided *by* it. It is also a
+    # member of `BLOCKED_APPROVAL_REASONS`, and this explicit position is what puts it here
+    # rather than with the approval gate.
+    (POLICY_UNAPPROVED,),
+    # `v0.3 §4.3`: authority before policy, so a denial leaves no pending approval behind.
+    REASON_PRECEDENCE,
+    # SPEC-v0.10 §4.3's check 2, and `v0.9 §2.3`/§2.4.1's budget refusals: all three are above
+    # the approval gate on T446's argument, that they depend on nothing a human says.
+    (UPSTREAM_MISMATCH, UPSTREAM_UNVERIFIED),
+    (BUDGET_UNMEASURABLE, BUDGET_EXHAUSTED),
+    # SPEC-v0.7 §5.5 — and T250 asserts by name that the ceiling is recorded **before** the
+    # approval gate, which is how the hand-written version of this list was caught.
+    (BLOCKED_ATTEMPT_CEILING,),
+    (BLOCKED_APPROVAL_REQUIRED, BLOCKED_APPROVAL_MISMATCH, *sorted(BLOCKED_APPROVAL_REASONS)),
+    (SCOPE_UNAVAILABLE, OUT_OF_SCOPE),
+    (BLOCKED_DUPLICATE, BLOCKED_IN_PROGRESS, BLOCKED_AMBIGUOUS),
+)
+
+DECISION_ORDER: Final = tuple(reason for group in _ORDERED_GROUPS for reason in group)
+
+_RANKS: Final[dict[str, int]] = {}
+for _index, _group in enumerate(_ORDERED_GROUPS):
+    for _reason in _group:
+        _RANKS.setdefault(_reason, _index)
+
+#: Where a reason this list does not name sits. **The policy axis, because that is the one open
+#: vocabulary**: `v0.1 §3.2` lets a decision reason be `rule[N]` for any N, and no fixed tuple can
+#: enumerate those. Ranking them with the policy decision they are is correct rather than a
+#: fallback; every other vocabulary in the kernel is closed and belongs in a group above.
+_UNLISTED_RANK: Final = _RANKS[NO_AUTHORITY] + 1
+
+
+def _where_to_look(result: AuthorityResult) -> str:
+    """SPEC-v0.10 §6.3 — the command, with its argument filled in, never a placeholder.
+
+    **The argument is always the PRESENTED hop**, with whatever the refusal knows about the chain
+    named in the prose beside it. An earlier draft of §6.3 had `missing_parent_id` print the id it
+    names; that id is by construction the record the store could **not** read, so
+    `inspect --hop <it>` is the unknown-id path and exits non-zero. A refusal whose one suggested
+    command is guaranteed to fail is worse than no suggestion: it sends an operator to a dead end
+    and teaches them the line is noise.
+
+    `authority_revoked` gets the same treatment for the same reason, measured: `_check_chain`
+    returns no id for the revoked node, so the only id in hand is the leaf.
+
+    Nothing is suggested where there is no id, which is a principal that presented no hop and
+    holds no delegation: `inspect --hop` has no argument there and the operator's question is a
+    different one.
+    """
+    hop = result.hop or result.delegation_id
+    if hop is None:
+        return ""
+    detail = ""
+    if result.missing_parent_id is not None:
+        detail = f"; {result.missing_parent_id} in its chain could not be read"
+    elif result.expired_parent_id is not None:
+        detail = f"; {result.expired_parent_id} above it has expired"
+    return f"{detail}. ctrlrun inspect --hop {hop}"
+
+
+def _rank(reason: str) -> int:
+    """Where `reason` sits in the declared order (SPEC-v0.10 §5)."""
+    rank: int = _RANKS.get(reason, _UNLISTED_RANK)
+    return rank
+
+
 #: SPEC-v0.9 §5.5 — its own domain tag, so a scope hash can never equal a precondition
 #: fingerprint over the same mapping. That matters precisely because §5.7 permits both.
 _SCOPE_SCHEMA: Final = "ctrlrun.scope/v1"
@@ -1100,7 +1207,7 @@
             effect_key=effect_key,
         )
         raise AuthorityDenied(
-            f"{action.name} denied: {result.reason}",
+            f"{action.name} denied: {result.reason}{_where_to_look(result)}",
             reason=result.reason,
             action_id=action.action_id,
             grant_id=result.grant_id,