policy

def authorize_transition(
    self,
    transition: TransitionRequest,
    invocation_state: Mapping[str, Any],
    *,
    now: datetime | None = None,
) -> PolicyVerdict:
    """Return the final allow/deny verdict for ``transition`` (AC-3-1, AC-3-6).

    Runs the gate stack in order and short-circuits on the first failure. When
    every gate passes for a non-human-gated transition, returns
    ``allowed=True`` (AC-3-6). Reads all state from ``invocation_state`` by
    reference and does not mutate it (AC-3-7).

    Args:
        transition: The proposed transition to judge.
        invocation_state: The run state (grants/approvals/findings/revision
            hashes) read by reference.
        now: Clock override for expiry checks (defaults to real UTC now).

    Returns:
        A :class:`PolicyVerdict`; on a ``human_required`` deny it also carries
        the pending :class:`HumanDecision` to suspend on (AC-4-1).
    """
    grants: Mapping[str, AuthorityGrant] = invocation_state.get(STATE_GRANTS, {})
    approvals: Mapping[str, ApprovalToken] = invocation_state.get(STATE_APPROVALS, {})
    findings: Sequence[Finding] = invocation_state.get(STATE_FINDINGS, [])
    revision_hashes: Mapping[str, str] = invocation_state.get(STATE_REVISION_HASHES, {})

    # Gate 1: capability (AC-3-2)
    grant = grants.get(transition.actor)
    if grant is None or not getattr(grant, transition.required_capability, False):
        return PolicyVerdict(
            allowed=False,
            failed_gate="capability",
            reason=(
                f"Actor '{transition.actor}' lacks required capability "
                f"'{transition.required_capability}' for transition '{transition.kind}'."
            ),
        )

    presented = [approvals[t] for t in transition.presented_tokens if t in approvals]

    # Gate 2: separation of duties (AC-3-3) — actor cannot be sole approver.
    if presented and all(tok.approver == transition.actor for tok in presented):
        return PolicyVerdict(
            allowed=False,
            failed_gate="separation_of_duties",
            reason=(
                f"Actor '{transition.actor}' is the sole approver of the transition they requested; "
                "separation of duties requires an independent approver."
            ),
        )

    # Gate 3: human-required (AC-4-1) — emit a pending gate, do not self-approve.
    if transition.kind in self.human_gated_kinds:
        pending = HumanDecision(
            transition=transition,
            prompt=(
                f"Human approval required for '{transition.kind}' transition "
                f"on revision '{transition.target_revision_id}' requested by '{transition.actor}'."
            ),
            options=["approve", "reject"],
        )
        return PolicyVerdict(
            allowed=False,
            failed_gate="human_required",
            reason=f"Transition kind '{transition.kind}' is human-gated; a human must resolve the decision.",
            pending_human_decision=pending,
        )

    # Gate 4: required approvals (AC-3-4, AC-5-1, AC-5-4) — count only VALID tokens.
    if transition.consequential or self.required_approvals > 0:
        valid = [tok for tok in presented if self._approval_is_valid(tok, transition, revision_hashes, now)]
        if len(valid) < max(self.required_approvals, 1 if transition.consequential else 0):
            return PolicyVerdict(
                allowed=False,
                failed_gate="required_approvals",
                reason=(
                    f"Transition '{transition.kind}' has {len(valid)} valid revision-bound approval(s); "
                    f"{self.required_approvals} required (stale/expired/forged tokens do not count)."
                ),
            )

    # Gate 5: open blocking finding (AC-3-5, AC-6-3).
    if self._has_open_blocking_finding(findings, transition):
        return PolicyVerdict(
            allowed=False,
            failed_gate="open_blocking_finding",
            reason=(
                f"An open blocking finding affects the target of transition '{transition.kind}'; "
                "it must be resolved before the transition is authorized."
            ),
        )

    return PolicyVerdict(
        allowed=True,
        reason=f"All gates passed for transition '{transition.kind}'.",
    )