docs: record why admin revert refuses REJECTED inbound ballots

REJECTED is a quorum asserting the observation is invalid, not a stuck
deposit, so refunding it would pay out against a deposit the validator set
said never happened. Adds an alarm if the unreachable state ever occurs.

Author: 0xNilesh

test/integration/uexecutor/revert_stuck_inbound_test.go

@@ -297,3 +297,42 @@ func TestRevertStuckInbound_RecomputeThenRevert_E2E(t *testing.T) {
 	require.Len(t, utx.OutboundTx, 1)
 	require.Equal(t, uexecutortypes.TxType_INBOUND_REVERT, utx.OutboundTx[0].TxType)
 }
+
+// TestRevertStuckInbound_RejectedBallot_RefusedDeliberately pins the refusal
+// documented for F-2026-18801.
+//
+// The terminal-routing hook files BOTH terminal-failure statuses into
+// ExpiredInbounds, but the admin hatch accepts only EXPIRED. That asymmetry is
+// intentional, and this test exists so a future change cannot quietly relax it:
+//
+//   - EXPIRED is uncertainty. Quorum never formed, the deposit may be real, the
+//     funds may be stuck in the source gateway. Refunding is correct.
+//   - REJECTED is a supermajority asserting the observation is invalid. A revert
+//     outbound there would pay out of the TSS vault against a deposit the
+//     validator set concluded never happened.
+//
+// Note this state is unreachable for inbounds today (VoteOnInboundBallot
+// hardcodes VOTE_RESULT_SUCCESS, so threshold-FAILURE never fires); the ballot is
+// seeded directly here precisely because no vote path can produce it. If inbound
+// negative voting is ever added, this test is the place the design decision has
+// to be re-made rather than inherited.
+func TestRevertStuckInbound_RejectedBallot_RefusedDeliberately(t *testing.T) {
+	chainApp, ctx, inbound, admin := setupRevertStuckInbound(t)
+	seedBallot(t, chainApp, ctx, inbound, uvalidatortypes.BallotStatus_BALLOT_STATUS_REJECTED)
+
+	ms := uexecutorkeeper.NewMsgServerImpl(chainApp.UexecutorKeeper)
+	_, err := ms.RevertStuckInbound(sdk.WrapSDKContext(ctx), &uexecutortypes.MsgRevertStuckInbound{
+		Signer:  admin,
+		Inbound: inbound,
+	})
+	require.Error(t, err, "admin revert must refuse a REJECTED ballot")
+	require.Contains(t, err.Error(), "admin revert requires EXPIRED",
+		"the refusal must name the required status so an operator knows why")
+
+	// The refusal must be total: no UTX, and therefore no revert outbound that
+	// could later be signed and broadcast.
+	utxKey := uexecutortypes.GetInboundUniversalTxKey(*inbound)
+	has, hErr := chainApp.UexecutorKeeper.HasUniversalTx(ctx, utxKey)
+	require.NoError(t, hErr)
+	require.False(t, has, "a refused revert must not leave a UniversalTx behind")
+}

x/uexecutor/keeper/admin_revert.go

@@ -22,6 +22,27 @@ import (
 // to EXPIRED if it isn't already (recompute auto-expires when no eligible
 // voters remain).
 //
+// REJECTED is refused deliberately, not by omission (F-2026-18801). The two
+// terminal-failure statuses mean opposite things:
+//
+//   - EXPIRED is uncertainty. Quorum never formed, so we do not know whether the
+//     deposit happened; the funds may genuinely be sitting in the source-chain
+//     gateway. Refunding is the right instinct.
+//   - REJECTED is a supermajority of universal validators affirmatively voting
+//     that the observation is invalid. Building a revert outbound for that would
+//     pay real funds out of the TSS-controlled vault against a deposit the
+//     validator set concluded never occurred.
+//
+// It is also unreachable for inbounds today: REJECTED is only produced by
+// Ballot.IsFinalizingVote's threshold-FAILURE branch, and VoteOnInboundBallot
+// hardcodes VOTE_RESULT_SUCCESS - an inbound observer either votes for what it
+// saw or stays silent, there is no "I assert this did not happen" vote. So an
+// inbound ballot terminates PASSED or EXPIRED, never REJECTED.
+//
+// If a negative-vote path for inbounds is ever added, this refusal must be
+// revisited as a design decision rather than silently inherited; see the
+// unreachable-status warning in BallotHooks.afterInboundBallotTerminal.
+//
 // Returns the new UTX ID and revert outbound ID for telemetry.
 func (k Keeper) RevertStuckInbound(ctx context.Context, inbound types.Inbound) (utxId, outboundId string, err error) {
 	sdkCtx := sdk.UnwrapSDKContext(ctx)

x/uexecutor/keeper/ballot_hooks.go

@@ -134,6 +134,30 @@ func (h BallotHooks) afterInboundBallotTerminal(
 	// All variants are terminal-failure (EXPIRED or REJECTED). Preserve
 	// the full audit trail in ExpiredInbounds for the future escape-hatch
 	// refund flow.
+	//
+	// Only EXPIRED is reachable here for inbounds: REJECTED comes solely from
+	// Ballot.IsFinalizingVote's threshold-FAILURE branch, and VoteOnInboundBallot
+	// hardcodes VOTE_RESULT_SUCCESS. An inbound observer votes for what it saw or
+	// stays silent; disagreement forks the ballot key into a separate variant
+	// rather than voting against one. The admin hatch (RevertStuckInbound)
+	// therefore accepts EXPIRED only, and refuses REJECTED deliberately - see the
+	// reasoning there.
+	//
+	// Shout if that ever stops being true. A REJECTED inbound reaching this point
+	// means someone added a negative-vote path and silently reopened a terminal
+	// state with no refund route (F-2026-18801).
+	for _, v := range entry.Variants {
+		if v.TerminalStatus == uvalidatortypes.BallotStatus_BALLOT_STATUS_REJECTED {
+			h.k.Logger().Error(
+				"REJECTED inbound ballot variant reached terminal routing - this should be unreachable; "+
+					"inbound votes are SUCCESS-only. RevertStuckInbound will refuse this entry, leaving it "+
+					"with no shipped refund path. Revisit F-2026-18801 before shipping inbound negative voting.",
+				"utx_key", utxKey,
+				"ballot_id", v.BallotId,
+			)
+		}
+	}
+
 	sdkCtx := sdk.UnwrapSDKContext(ctx)
 	return h.k.ExpiredInbounds.Set(ctx, utxKey, types.ExpiredInboundEntry{
 		UtxKey:          utxKey,