Ship Tier A Week 1–2: posture glossary, delivery mode, freshness UI, canonical tokens.

Expose mission-control mode on home/bridge/analytics, quiet-chain freshness copy, and a canonical-first indexed token list with WETH9 metadata override and non-canonical warnings.

Co-authored-by: Cursor <cursoragent@cursor.com>

backend/api/track1/bridge_mode.go

@@ -0,0 +1,78 @@
+package track1
+
+import (
+	"strings"
+
+	"github.com/explorer/backend/api/freshness"
+)
+
+type bridgeDeliveryMode struct {
+	Kind   string
+	Reason any
+	Scope  any
+}
+
+func resolveBridgeDeliveryMode(hasRelays bool, diagnostics *freshness.Diagnostics, txFeed freshness.Completeness) bridgeDeliveryMode {
+	if !hasRelays {
+		if diagnostics != nil && isStaleTransactionVisibility(diagnostics) {
+			return bridgeDeliveryMode{
+				Kind:   "mixed",
+				Reason: "partial_observability_inputs",
+				Scope:  "homepage_summary_only",
+			}
+		}
+		return bridgeDeliveryMode{
+			Kind:   "live",
+			Reason: nil,
+			Scope:  nil,
+		}
+	}
+
+	if diagnostics != nil && isStaleTransactionVisibility(diagnostics) {
+		return bridgeDeliveryMode{
+			Kind:   "mixed",
+			Reason: "relay_snapshot_only_source",
+			Scope:  "bridge_monitoring_and_homepage",
+		}
+	}
+
+	if txFeed == freshness.CompletenessPartial || txFeed == freshness.CompletenessStale {
+		return bridgeDeliveryMode{
+			Kind:   "mixed",
+			Reason: "partial_observability_inputs",
+			Scope:  "bridge_monitoring_and_homepage",
+		}
+	}
+
+	return bridgeDeliveryMode{
+		Kind:   "snapshot",
+		Reason: "live_homepage_stream_not_attached",
+		Scope:  "relay_monitoring_homepage_card_only",
+	}
+}
+
+func isStaleTransactionVisibility(diagnostics *freshness.Diagnostics) bool {
+	if diagnostics == nil {
+		return false
+	}
+	state := strings.ToLower(strings.TrimSpace(diagnostics.ActivityState))
+	switch state {
+	case "fresh_head_stale_transaction_visibility", "lagging", "stale_transaction_visibility":
+		return true
+	default:
+		return strings.Contains(state, "stale") && strings.Contains(state, "transaction")
+	}
+}
+
+func buildBridgeModePayload(now string, resolved bridgeDeliveryMode) map[string]interface{} {
+	return map[string]interface{}{
+		"kind":        resolved.Kind,
+		"updated_at":  now,
+		"age_seconds": int64(0),
+		"reason":      resolved.Reason,
+		"scope":       resolved.Scope,
+		"source":      freshness.SourceReported,
+		"confidence":  freshness.ConfidenceHigh,
+		"provenance":  freshness.ProvenanceMissionFeed,
+	}
+}

backend/api/track1/bridge_mode_test.go

@@ -0,0 +1,36 @@
+package track1
+
+import (
+	"testing"
+
+	"github.com/explorer/backend/api/freshness"
+	"github.com/stretchr/testify/require"
+)
+
+func TestResolveBridgeDeliveryModeLiveWithoutRelays(t *testing.T) {
+	got := resolveBridgeDeliveryMode(false, nil, freshness.CompletenessComplete)
+	require.Equal(t, "live", got.Kind)
+	require.Nil(t, got.Reason)
+}
+
+func TestResolveBridgeDeliveryModeSnapshotWithRelays(t *testing.T) {
+	got := resolveBridgeDeliveryMode(true, nil, freshness.CompletenessComplete)
+	require.Equal(t, "snapshot", got.Kind)
+	require.Equal(t, "live_homepage_stream_not_attached", got.Reason)
+	require.Equal(t, "relay_monitoring_homepage_card_only", got.Scope)
+}
+
+func TestResolveBridgeDeliveryModeMixedWhenTransactionVisibilityStale(t *testing.T) {
+	diagnostics := &freshness.Diagnostics{
+		ActivityState: "fresh_head_stale_transaction_visibility",
+	}
+	got := resolveBridgeDeliveryMode(true, diagnostics, freshness.CompletenessPartial)
+	require.Equal(t, "mixed", got.Kind)
+	require.Equal(t, "relay_snapshot_only_source", got.Reason)
+	require.Equal(t, "bridge_monitoring_and_homepage", got.Scope)
+}
+
+func TestIsStaleTransactionVisibility(t *testing.T) {
+	require.True(t, isStaleTransactionVisibility(&freshness.Diagnostics{ActivityState: "fresh_head_stale_transaction_visibility"}))
+	require.False(t, isStaleTransactionVisibility(&freshness.Diagnostics{ActivityState: "healthy"}))
+}

backend/api/track1/bridge_status_data.go

@@ -133,6 +133,8 @@ func (s *Server) BuildBridgeStatusData(ctx context.Context) map[string]interface
 	}
 	if s.freshnessLoader != nil {
 		if snapshot, completeness, sampling, diagnostics, err := s.freshnessLoader(ctx); err == nil && snapshot != nil {
+			txFeed := completeness.TransactionsFeed
+			resolvedMode := resolveBridgeDeliveryMode(false, diagnostics, txFeed)
 			subsystems := map[string]interface{}{
 				"rpc_head": map[string]interface{}{
 					"status":       chainStatusFromProbe(p138),
@@ -174,39 +176,13 @@ func (s *Server) BuildBridgeStatusData(ctx context.Context) map[string]interface
 					"issues":       sampling.Issues,
 				}
 			}
-			modeKind := "live"
-			modeReason := any(nil)
-			modeScope := any(nil)
-			if relays, ok := data["ccip_relays"].(map[string]interface{}); ok && len(relays) > 0 {
-				modeKind = "snapshot"
-				modeReason = "live_homepage_stream_not_attached"
-				modeScope = "relay_monitoring_homepage_card_only"
-				subsystems["bridge_relay_monitoring"] = map[string]interface{}{
-					"status":       overall,
-					"updated_at":   now,
-					"age_seconds":  int64(0),
-					"source":       freshness.SourceReported,
-					"confidence":   freshness.ConfidenceHigh,
-					"provenance":   freshness.ProvenanceMissionFeed,
-					"completeness": freshness.CompletenessComplete,
-				}
-			}
 			data["freshness"] = snapshot
 			data["subsystems"] = subsystems
 			data["sampling"] = sampling
 			if diagnostics != nil {
 				data["diagnostics"] = diagnostics
 			}
-			data["mode"] = map[string]interface{}{
-				"kind":        modeKind,
-				"updated_at":  now,
-				"age_seconds": int64(0),
-				"reason":      modeReason,
-				"scope":       modeScope,
-				"source":      freshness.SourceReported,
-				"confidence":  freshness.ConfidenceHigh,
-				"provenance":  freshness.ProvenanceMissionFeed,
-			}
+			data["mode"] = buildBridgeModePayload(now, resolvedMode)
 		}
 	}
 	if relays := FetchCCIPRelayHealths(ctx); relays != nil {
@@ -224,9 +200,22 @@ func (s *Server) BuildBridgeStatusData(ctx context.Context) map[string]interface
 	}
 	if mode, ok := data["mode"].(map[string]interface{}); ok {
 		if relays, ok := data["ccip_relays"].(map[string]interface{}); ok && len(relays) > 0 {
-			mode["kind"] = "snapshot"
-			mode["reason"] = "live_homepage_stream_not_attached"
-			mode["scope"] = "relay_monitoring_homepage_card_only"
+			var diagnostics *freshness.Diagnostics
+			if diag, ok := data["diagnostics"].(*freshness.Diagnostics); ok {
+				diagnostics = diag
+			}
+			txFeed := freshness.CompletenessUnavailable
+			if subsystems, ok := data["subsystems"].(map[string]interface{}); ok {
+				if txIndex, ok := subsystems["tx_index"].(map[string]interface{}); ok {
+					if feed, ok := txIndex["completeness"].(freshness.Completeness); ok {
+						txFeed = feed
+					}
+				}
+			}
+			resolved := resolveBridgeDeliveryMode(true, diagnostics, txFeed)
+			mode["kind"] = resolved.Kind
+			mode["reason"] = resolved.Reason
+			mode["scope"] = resolved.Scope
 			if subsystems, ok := data["subsystems"].(map[string]interface{}); ok {
 				subsystems["bridge_relay_monitoring"] = map[string]interface{}{
 					"status":       data["status"],
@@ -239,6 +228,9 @@ func (s *Server) BuildBridgeStatusData(ctx context.Context) map[string]interface
 				}
 			}
 		}
+	} else if relays, ok := data["ccip_relays"].(map[string]interface{}); ok && len(relays) > 0 {
+		resolved := resolveBridgeDeliveryMode(true, nil, freshness.CompletenessUnavailable)
+		data["mode"] = buildBridgeModePayload(now, resolved)
 	}
 	return data
 }

backend/api/track1/ccip_health_test.go

@@ -212,6 +212,11 @@ func TestBuildBridgeStatusDataIncludesCCIPRelay(t *testing.T) {
 	require.Contains(t, got, "diagnostics")
 	require.Contains(t, got, "subsystems")
 	require.Contains(t, got, "mode")
+	mode, ok := got["mode"].(map[string]interface{})
+	require.True(t, ok)
+	require.Equal(t, "mixed", mode["kind"])
+	require.Equal(t, "relay_snapshot_only_source", mode["reason"])
+	require.Equal(t, "bridge_monitoring_and_homepage", mode["scope"])
 }
 
 func TestBuildBridgeStatusDataDegradesWhenNamedRelayFails(t *testing.T) {