Explain monitored-system over-plan legitimacy

pkg/licensing/entitlement_payload.go

@@ -221,6 +221,11 @@ type MonitoredSystemCapacityStatus struct {
 	// is while existing monitoring continues.
 	Overage int64 `json:"overage"`
 
+	// Reason explains why the current monitored-system posture is legitimate.
+	// Values: "limit_reached", "preexisting_usage",
+	// "legacy_migration_capture_pending"
+	Reason string `json:"reason,omitempty"`
+
 	// BlocksNewSystems indicates that Pulse will reject net-new monitored
 	// systems until capacity is freed or the plan changes.
 	BlocksNewSystems bool `json:"blocks_new_systems"`
@@ -420,6 +425,7 @@ func BuildEntitlementPayloadWithUsage(
 	payload.MonitoredSystemCapacity = buildMonitoredSystemCapacityStatus(
 		int64(status.MaxMonitoredSystems),
 		usage,
+		status.MonitoredSystemContinuity,
 	)
 
 	if payload.Capabilities == nil {
@@ -525,6 +531,7 @@ func boolPointer(value bool) *bool {
 func buildMonitoredSystemCapacityStatus(
 	limit int64,
 	usage EntitlementUsageSnapshot,
+	continuity *MonitoredSystemContinuityStatus,
 ) *MonitoredSystemCapacityStatus {
 	currentAvailable := usage.monitoredSystemCountAvailable()
 	if !currentAvailable {
@@ -574,11 +581,17 @@ func buildMonitoredSystemCapacityStatus(
 		status.AvailableSlots = limit - current
 	case current == limit:
 		status.Mode = "at_limit_blocking_new"
+		status.Reason = "limit_reached"
 		status.BlocksNewSystems = true
 	case current > limit:
 		status.Mode = "over_limit_frozen"
 		status.BlocksNewSystems = true
 		status.Overage = current - limit
+		if continuity != nil && continuity.CapturePending {
+			status.Reason = "legacy_migration_capture_pending"
+		} else {
+			status.Reason = "preexisting_usage"
+		}
 	default:
 		status.Mode = "within_limit"
 	}

pkg/licensing/entitlement_payload_test.go

@@ -293,6 +293,9 @@ func TestBuildEntitlementPayloadWithUsage_CopiesMonitoredSystemContinuity(t *tes
 	if payload.MonitoredSystemCapacity.Mode != "at_limit_blocking_new" {
 		t.Fatalf("Mode=%q, want at_limit_blocking_new", payload.MonitoredSystemCapacity.Mode)
 	}
+	if payload.MonitoredSystemCapacity.Reason != "limit_reached" {
+		t.Fatalf("Reason=%q, want limit_reached", payload.MonitoredSystemCapacity.Reason)
+	}
 	if !payload.MonitoredSystemCapacity.BlocksNewSystems {
 		t.Fatal("expected at-limit posture to block new monitored systems")
 	}
@@ -462,6 +465,39 @@ func TestBuildCommercialPosturePayloadWithUsage_CurrentValues(t *testing.T) {
 	if payload.MonitoredSystemCapacity.Overage != 2 {
 		t.Fatalf("Overage=%d, want 2", payload.MonitoredSystemCapacity.Overage)
 	}
+	if payload.MonitoredSystemCapacity.Reason != "preexisting_usage" {
+		t.Fatalf("Reason=%q, want preexisting_usage", payload.MonitoredSystemCapacity.Reason)
+	}
+}
+
+func TestBuildEntitlementPayloadWithUsage_MarksLegacyContinuityCapturePendingOverage(t *testing.T) {
+	payload := BuildEntitlementPayloadWithUsage(&LicenseStatus{
+		Valid:               true,
+		Tier:                TierPro,
+		Features:            append([]string(nil), TierFeatures[TierPro]...),
+		MaxMonitoredSystems: 10,
+		MonitoredSystemContinuity: &MonitoredSystemContinuityStatus{
+			PlanLimit:      10,
+			EffectiveLimit: 10,
+			CapturePending: true,
+		},
+	}, string(SubStateActive), EntitlementUsageSnapshot{
+		MonitoredSystems:          23,
+		MonitoredSystemsAvailable: true,
+	}, nil)
+
+	if payload.MonitoredSystemCapacity == nil {
+		t.Fatal("expected monitored-system capacity posture")
+	}
+	if payload.MonitoredSystemCapacity.Mode != "over_limit_frozen" {
+		t.Fatalf("Mode=%q, want over_limit_frozen", payload.MonitoredSystemCapacity.Mode)
+	}
+	if payload.MonitoredSystemCapacity.Reason != "legacy_migration_capture_pending" {
+		t.Fatalf(
+			"Reason=%q, want legacy_migration_capture_pending",
+			payload.MonitoredSystemCapacity.Reason,
+		)
+	}
 }
 
 func TestCommercialPosturePayloadFromEntitlementPayload_StripsBillingIdentityFields(t *testing.T) {