Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

35.6 KB
Raw Blame
package unifiedresources

import (
	"crypto/sha256"
	"encoding/json"
	"fmt"
	"log"
	"sort"
	"strings"
	"sync"
	"time"

	"github.com/rcourtman/pulse-go-rewrite/internal/models"
)

// MonitorAdapter exposes a ResourceRegistry through the monitoring
// package's legacy resource-store contract.
type MonitorAdapter struct {
	registry *ResourceRegistry

	// mutationMu serializes complete registry generations with incremental
	// supplemental updates. Registry construction intentionally happens while
	// readers keep using the prior pointer, but two writers must never publish
	// out of order or mutate a registry after it has been replaced.
	mutationMu      sync.Mutex
	mu              sync.RWMutex
	activeAlerts    []models.Alert
	lastRebuiltAt   time.Time
	staleThresholds map[DataSource]time.Duration
	// registryStaleThresholds are the thresholds the current registry
	// generation was built and judged with. staleThresholds may already hold
	// newer ones, which reach the registry at the next rebuild.
	registryStaleThresholds map[DataSource]time.Duration
	legacyHistory           legacyHistoryBackfill

	overlays overlayReadStateCache

	// changeObserver hears each live change after the store accepted it.
	// Guarded by mu.
	changeObserver ResourceChangeObserver

	// restartBaseline maps each resource the change history recorded before
	// this process's first diff to its last recorded state. A resource's first
	// appearance in this run is compared with that state rather than with
	// nothing, so restarting or updating Pulse does not record the whole fleet
	// as new. Guarded by mutationMu.
	restartBaseline       map[string]string
	restartBaselineLoaded bool
}

// ResourceChangeObserver is told about a change the adapter just recorded,
// with its resource ID already resolved to the canonical identity it was
// stored under. It runs on the recording goroutine, so it must not block.
// Replayed or imported history never reaches it: only registry diffs and
// changes recorded through RecordLiveChange do.
type ResourceChangeObserver func(change ResourceChange)

// SetChangeObserver installs the observer for live changes; nil removes it.
func (a *MonitorAdapter) SetChangeObserver(observer ResourceChangeObserver) {
	if a == nil {
		return
	}
	a.mu.Lock()
	a.changeObserver = observer
	a.mu.Unlock()
}

func (a *MonitorAdapter) notifyChanges(changes []ResourceChange) {
	if a == nil || len(changes) == 0 {
		return
	}
	a.mu.RLock()
	observer := a.changeObserver
	a.mu.RUnlock()
	if observer == nil {
		return
	}
	for _, change := range changes {
		change.ResourceID = CanonicalResourceID(change.ResourceID)
		observer(change)
	}
}

// overlayReadStateMaxAge bounds how long an overlay built from one registry
// generation is reused. The overlay evaluates source staleness when it is
// built, so reuse stays within the staleness read paths already accept.
const overlayReadStateMaxAge = 2 * time.Second

// overlayReadStateCache holds the last overlay built from this adapter's
// registry. Host continuity overlays are requested on every canonical
// read-state lookup, which alert evaluation makes once per resource per poll;
// rebuilding the registry for each made polls quadratic while a standalone
// agent stayed offline across a restart.
type overlayReadStateCache struct {
	mu        sync.Mutex
	registry  *ResourceRegistry
	rebuiltAt time.Time
	key       [sha256.Size]byte
	builtAt   time.Time
	overlay   ReadState
}

// NewMonitorAdapter creates a monitor-facing adapter around a registry.
// If registry is nil, a new in-memory registry is created.
func NewMonitorAdapter(registry *ResourceRegistry) *MonitorAdapter {
	return NewMonitorAdapterWithStaleThresholds(registry, nil)
}

// NewMonitorAdapterWithStaleThresholds creates a monitor-facing adapter using
// caller-owned source freshness thresholds.
func NewMonitorAdapterWithStaleThresholds(registry *ResourceRegistry, staleThresholds map[DataSource]time.Duration) *MonitorAdapter {
	if registry == nil {
		registry = NewRegistry(nil)
	}

	return &MonitorAdapter{
		registry:                registry,
		staleThresholds:         cloneStaleThresholds(staleThresholds),
		registryStaleThresholds: cloneStaleThresholds(staleThresholds),
	}
}

// SetStaleThresholds updates the source freshness thresholds used on future
// snapshot rebuilds. Missing source entries keep the registry defaults.
func (a *MonitorAdapter) SetStaleThresholds(staleThresholds map[DataSource]time.Duration) {
	if a == nil {
		return
	}
	a.mu.Lock()
	a.staleThresholds = cloneStaleThresholds(staleThresholds)
	a.mu.Unlock()
}

// StaleThresholds returns the source freshness thresholds the current
// registry generation was judged by; nil means the registry defaults.
// Thresholds set since that rebuild are not reported until the next one
// judges a generation by them.
func (a *MonitorAdapter) StaleThresholds() map[DataSource]time.Duration {
	if a == nil {
		return nil
	}
	a.mu.RLock()
	thresholds := cloneStaleThresholds(a.registryStaleThresholds)
	a.mu.RUnlock()
	return thresholds
}

func (a *MonitorAdapter) currentStaleThresholds() map[DataSource]time.Duration {
	if a == nil {
		return nil
	}
	a.mu.RLock()
	thresholds := cloneStaleThresholds(a.staleThresholds)
	a.mu.RUnlock()
	return thresholds
}

// ReadStateWithRecords clones a supported read state and overlays additional
// source-native records without mutating the original live view.
func ReadStateWithRecords(
	readState ReadState,
	source DataSource,
	records []IngestRecord,
) ReadState {
	return readStateWithRecords(readState, source, records, false)
}

// ReadStateWithHostContinuity fills absent machines from saved enrollments.
// A saved enrollment is not a current observation: if canonical correlation
// finds an existing resource, retain that resource's identity and telemetry.
func ReadStateWithHostContinuity(readState ReadState, records []IngestRecord) ReadState {
	return readStateWithRecords(readState, SourceAgent, records, true)
}

func readStateWithRecords(readState ReadState, source DataSource, records []IngestRecord, onlyMissing bool) ReadState {
	if readState == nil || len(records) == 0 || strings.TrimSpace(string(source)) == "" {
		return readState
	}

	adapter, ok := readState.(*MonitorAdapter)
	if !ok || adapter == nil {
		return readState
	}

	// The overlay re-judges the generation's listing, so it takes the
	// thresholds that generation was judged by, not ones set since: those
	// cannot clear a stale verdict the listing already carries.
	registry, thresholds := adapter.currentRegistryAndStaleThresholds()
	if registry == nil {
		return readState
	}
	// Capture the generation before reading it, so a mutation during the build
	// leaves the cached overlay keyed to the older generation.
	rebuiltAt := adapter.LastRebuiltAt()
	key, keyed := overlayRecordsKey(source, records, onlyMissing)
	now := time.Now()
	if keyed {
		if overlay := adapter.overlays.lookup(registry, rebuiltAt, key, now); overlay != nil {
			return overlay
		}
	}

	cloned := newRegistryFrom(registry)
	cloned.IngestResourcesWithStaleThresholds(registry.List(), thresholds)
	cloned.ingestRecords(source, records, onlyMissing, thresholds)
	overlay := NewMonitorAdapterWithStaleThresholds(cloned, thresholds)
	if keyed {
		adapter.overlays.store(registry, rebuiltAt, key, now, overlay)
	}
	return overlay
}

// overlayRecordsKey fingerprints an overlay request. Resource.UpdatedAt is
// stamped when a record is built, not observed, so it is left out.
func overlayRecordsKey(source DataSource, records []IngestRecord, onlyMissing bool) ([sha256.Size]byte, bool) {
	stable := make([]IngestRecord, len(records))
	for i, record := range records {
		record.Resource.UpdatedAt = time.Time{}
		stable[i] = record
	}
	payload, err := json.Marshal(struct {
		Source      DataSource
		OnlyMissing bool
		Records     []IngestRecord
	}{source, onlyMissing, stable})
	if err != nil {
		return [sha256.Size]byte{}, false
	}
	return sha256.Sum256(payload), true
}

func (c *overlayReadStateCache) lookup(registry *ResourceRegistry, rebuiltAt time.Time, key [sha256.Size]byte, now time.Time) ReadState {
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.overlay == nil || c.registry != registry || !c.rebuiltAt.Equal(rebuiltAt) || c.key != key {
		return nil
	}
	if age := now.Sub(c.builtAt); age < 0 || age >= overlayReadStateMaxAge {
		return nil
	}
	return c.overlay
}

func (c *overlayReadStateCache) store(registry *ResourceRegistry, rebuiltAt time.Time, key [sha256.Size]byte, now time.Time, overlay ReadState) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.registry = registry
	c.rebuiltAt = rebuiltAt
	c.key = key
	c.builtAt = now
	c.overlay = overlay
}

// currentRegistryAndStaleThresholds reads the current registry generation
// together with the thresholds it was judged by.
func (a *MonitorAdapter) currentRegistryAndStaleThresholds() (*ResourceRegistry, map[DataSource]time.Duration) {
	if a == nil {
		return nil, nil
	}
	a.mu.RLock()
	registry := a.registry
	thresholds := cloneStaleThresholds(a.registryStaleThresholds)
	a.mu.RUnlock()
	return registry, thresholds
}

func (a *MonitorAdapter) currentRegistry() *ResourceRegistry {
	if a == nil {
		return nil
	}

	a.mu.RLock()
	registry := a.registry
	a.mu.RUnlock()
	return registry
}

// GetByReference delegates identity and alias resolution to the current registry.
func (a *MonitorAdapter) GetByReference(reference string) (*Resource, string, bool) {
	registry := a.currentRegistry()
	if registry == nil {
		return nil, "", false
	}
	return registry.GetByReference(reference)
}

// RecordChange forwards canonical resource-history events into the underlying
// resource store when monitoring has a durable store attached. Alert lifecycle
// events carry source-native references (Proxmox node and guest IDs, agent
// IDs, Docker host and Swarm service IDs, sub-resource references); they
// resolve here so history reads by canonical ID include them. PVE disk alert
// rows are owned row by row instead (proxmoxDiskAlertOwner).
func (a *MonitorAdapter) RecordChange(change ResourceChange) error {
	_, _, err := a.recordChange(change)
	return err
}

// RecordLiveChange records a change that is happening now, as RecordChange
// does, then tells the change observer. Callers replaying or importing history
// use RecordChange so old events are not announced as new.
func (a *MonitorAdapter) RecordLiveChange(change ResourceChange) error {
	recorded, ok, err := a.recordChange(change)
	if err != nil || !ok {
		return err
	}
	a.notifyChanges([]ResourceChange{recorded})
	return nil
}

// recordChange persists the change and returns it as stored, with the
// resource ID it resolved to. ok is false when no durable store is attached.
func (a *MonitorAdapter) recordChange(change ResourceChange) (ResourceChange, bool, error) {
	registry := a.currentRegistry()
	if registry == nil || registry.store == nil {
		return change, false, nil
	}
	sourceRef := change.ResourceID
	if ref, ok := proxmoxDiskAlertRowReference(change); ok {
		// A PVE disk alert reference never binds: the row goes to the disk its
		// own hardware identity names, or stays under the reference.
		if owner := registry.proxmoxDiskAlertOwner(ref, change.Metadata); owner != "" && owner != ref {
			change.Metadata = cloneChangeMetadata(change.Metadata)
			change.Metadata[MetadataAlertResourceID] = ref
			change.ResourceID = owner
		}
		err := registry.store.RecordChange(change)
		return change, err == nil, err
	}
	history, hasHistory := registry.store.(resourceHistoryIdentityWriter)
	unbound := false
	if sourceID, derivedID, ok := legacyDockerHistoryIdentity(sourceRef); ok {
		// Use exact source identity when inventory is present, including any
		// canonical identity merge. Full Docker IDs remain derivable after removal.
		registry.mu.RLock()
		resolvedID := registry.bySource[SourceDocker][sourceID]
		registry.mu.RUnlock()
		if resolvedID != "" {
			change.ResourceID = resolvedID
		} else {
			change.ResourceID = derivedID
			if hasHistory {
				id, found, err := history.ResolveHistorySourceIdentity(sourceRef)
				if err != nil {
					return change, false, err
				}
				if found {
					change.ResourceID = id
				}
			}
		}
	} else if resolvedID, claimed := registry.resolveHistoryReference(sourceRef); resolvedID != "" {
		change.ResourceID = resolvedID
	} else if hasHistory && !isDockerNameHistoryReference(sourceRef) {
		// A later generation may name the resource or settle a conflict.
		unbound = true
		if !claimed {
			// No resource answers to it: keep the binding an earlier event recorded.
			id, found, err := history.ResolveHistorySourceIdentity(CanonicalResourceID(sourceRef))
			if err != nil {
				return change, false, err
			}
			if found {
				change.ResourceID = id
				unbound = false
			}
		}
	}
	if hasHistory && CanonicalResourceID(sourceRef) != CanonicalResourceID(change.ResourceID) {
		err := history.RecordChangeWithSourceIdentity(change, sourceRef)
		return change, err == nil, err
	}
	if err := registry.store.RecordChange(change); err != nil {
		return change, false, err
	}
	// Inventory may name the resource in a later generation; bind the row then.
	if _, ok := registry.store.(legacyHistoryBinder); unbound && ok {
		a.legacyHistory.add(CanonicalResourceID(sourceRef), time.Now())
	}
	return change, true, nil
}

// GetRecentChanges forwards canonical resource-history reads into the
// underlying resource store when monitoring has a durable store attached.
func (a *MonitorAdapter) GetRecentChanges(canonicalID string, since time.Time, limit int) ([]ResourceChange, error) {
	registry := a.currentRegistry()
	if registry == nil || registry.store == nil {
		return nil, nil
	}
	return registry.store.GetRecentChanges(canonicalID, since, limit)
}

// GetRecentChangesFiltered preserves the canonical query predicates used by
// incident projections, including alert identity before the evidence limit.
func (a *MonitorAdapter) GetRecentChangesFiltered(resourceID string, since time.Time, limit int, filters ResourceChangeFilters) ([]ResourceChange, error) {
	registry := a.currentRegistry()
	if registry == nil || registry.store == nil {
		return nil, fmt.Errorf("canonical resource history unavailable")
	}
	return registry.store.GetRecentChangesFiltered(resourceID, since, limit, filters)
}

func (a *MonitorAdapter) ResourceHistoryIDs(resourceID string) ([]string, error) {
	registry := a.currentRegistry()
	if registry == nil || registry.store == nil {
		return nil, fmt.Errorf("canonical resource history unavailable")
	}
	reader, ok := registry.store.(interface {
		ResourceHistoryIDs(string) ([]string, error)
	})
	if !ok {
		return nil, fmt.Errorf("canonical history identities unavailable")
	}
	return reader.ResourceHistoryIDs(resourceID)
}

// GetResourceOperatorState exposes the durable operator-intent record through
// the monitor adapter without widening monitoring's core resource-store
// interface. Alert policy resolution discovers this capability optionally.
func (a *MonitorAdapter) GetResourceOperatorState(canonicalID string) (ResourceOperatorState, bool, error) {
	registry := a.currentRegistry()
	if registry == nil || registry.store == nil {
		return ResourceOperatorState{}, false, nil
	}
	return registry.store.GetResourceOperatorState(canonicalID)
}

// ResolveCanonicalResourceID bridges source-native alert identifiers to the
// canonical resource identity used by durable operator state and policy UI.
func (a *MonitorAdapter) ResolveCanonicalResourceID(ref string) (string, bool) {
	registry := a.currentRegistry()
	if registry == nil {
		return "", false
	}
	return registry.ResolveReferenceID(ref)
}

// ResolveCanonicalResourceAncestors returns the live canonical parent chain,
// nearest parent first. It is used by policy consumers that deliberately opt
// into inherited intent; ordinary per-resource state remains exact-match.
func (a *MonitorAdapter) ResolveCanonicalResourceAncestors(ref string) []string {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	canonicalID, ok := registry.ResolveReferenceID(ref)
	if !ok {
		canonicalID = CanonicalResourceID(ref)
	}
	seen := map[string]struct{}{canonicalID: {}}
	ancestors := make([]string, 0, 4)
	for canonicalID != "" {
		resource, found := registry.Get(canonicalID)
		if !found || resource.ParentID == nil {
			break
		}
		parentRef := CanonicalResourceID(*resource.ParentID)
		parentID := parentRef
		if resolvedParentID, resolved := registry.ResolveReferenceID(parentRef); resolved {
			parentID = resolvedParentID
		}
		if parentID == "" {
			break
		}
		if _, cycle := seen[parentID]; cycle {
			break
		}
		seen[parentID] = struct{}{}
		ancestors = append(ancestors, parentID)
		canonicalID = parentID
	}
	return ancestors
}

// LastRebuiltAt returns when the registry last published a generation. Zero
// when no snapshot or supplemental ingest has completed yet.
func (a *MonitorAdapter) LastRebuiltAt() time.Time {
	if a == nil {
		return time.Time{}
	}
	a.mu.RLock()
	defer a.mu.RUnlock()
	return a.lastRebuiltAt
}

// RegistryGeneration identifies one generation a MonitorAdapter published:
// the registry it serves and when that registry last changed. LastRebuiltAt
// alone does not, since two rebuilds of a snapshot stamped in the future
// share its time; a rebuild swaps the registry and an incremental update
// restamps it.
type RegistryGeneration struct {
	registry  *ResourceRegistry
	rebuiltAt int64
}

// Generation returns the generation the adapter currently publishes.
func (a *MonitorAdapter) Generation() RegistryGeneration {
	if a == nil {
		return RegistryGeneration{}
	}
	a.mu.RLock()
	defer a.mu.RUnlock()
	generation := RegistryGeneration{registry: a.registry}
	if !a.lastRebuiltAt.IsZero() {
		generation.rebuiltAt = a.lastRebuiltAt.UnixNano()
	}
	return generation
}

// TryReplaceRegistryForRead rebuilds the registry on behalf of a read path
// (/api/state, websocket hydrate). Unlike the ingest-driven populate methods
// it never queues behind an in-flight rebuild and skips entirely while the
// current generation is younger than maxAge, so serving state cannot stall
// on registry persistence (change records and identity pins write to SQLite,
// which can take seconds per transaction on slow volumes — #1665). The
// supplemental payload is only materialized via supply() once a rebuild is
// committed, keeping consume-once providers undrained on skipped refreshes.
// The one exception is a cold start: before the first generation exists a
// read path must block and build it, or first loads would render empty.
// Returns true when a rebuild ran.
func (a *MonitorAdapter) TryReplaceRegistryForRead(snapshot models.StateSnapshot, maxAge time.Duration, supply func() map[DataSource][]IngestRecord) bool {
	if a == nil {
		return false
	}
	if last := a.LastRebuiltAt(); !last.IsZero() {
		if maxAge > 0 && time.Since(last) < maxAge {
			return false
		}
		if !a.mutationMu.TryLock() {
			// An ingest rebuild is already publishing a generation at least
			// as fresh as this snapshot; serve the current one instead.
			return false
		}
	} else {
		a.mutationMu.Lock()
	}
	defer a.mutationMu.Unlock()
	// Re-check under the lock: another rebuild may have published while this
	// caller was acquiring it.
	if last := a.LastRebuiltAt(); !last.IsZero() && maxAge > 0 && time.Since(last) < maxAge {
		return false
	}
	var recordsBySource map[DataSource][]IngestRecord
	if supply != nil {
		recordsBySource = supply()
	}
	a.replaceRegistryLocked(snapshot, recordsBySource)
	return true
}

func (a *MonitorAdapter) replaceRegistry(snapshot models.StateSnapshot, recordsBySource map[DataSource][]IngestRecord) {
	if a == nil {
		return
	}
	a.mutationMu.Lock()
	defer a.mutationMu.Unlock()
	a.replaceRegistryLocked(snapshot, recordsBySource)
}

// replaceRegistryLocked is the rebuild body; callers must hold mutationMu.
func (a *MonitorAdapter) replaceRegistryLocked(snapshot models.StateSnapshot, recordsBySource map[DataSource][]IngestRecord) {
	registry := a.currentRegistry()
	if registry == nil {
		return
	}

	rebuilt := newRegistryFrom(registry)
	staleThresholds := a.currentStaleThresholds()
	// Operator links apply once the snapshot and every record source are in,
	// so a chain is judged over the whole estate rather than folded as its
	// members' sources arrive: a fold cannot be undone when a later source
	// brings a member that outranks the earlier choice. Availability checks
	// still come after the links, so a check linked to a folded resource
	// projects onto its primary.
	rebuilt.deferManualLinks = true
	rebuilt.IngestSnapshotWithStaleThresholds(snapshot, staleThresholds)
	sources := make([]DataSource, 0, len(recordsBySource))
	for source := range recordsBySource {
		sources = append(sources, source)
	}
	sort.Slice(sources, func(i, j int) bool {
		if sources[i] == SourceAvailability {
			return false
		}
		if sources[j] == SourceAvailability {
			return true
		}
		return string(sources[i]) < string(sources[j])
	})
	for _, source := range sources {
		if source == SourceAvailability {
			rebuilt.applyDeferredManualLinks(staleThresholds)
		}
		records := recordsBySource[source]
		if len(records) == 0 || strings.TrimSpace(string(source)) == "" {
			continue
		}
		rebuilt.IngestRecordsWithStaleThresholds(source, records, staleThresholds)
	}
	rebuilt.applyDeferredManualLinks(staleThresholds)
	// IngestSnapshot runs its stale pass before the record sources above are
	// ingested, so record-sourced resources would otherwise keep their
	// ingest-time "online" stamp regardless of how old their data is.
	// Re-evaluate staleness over the fully assembled registry.
	rebuilt.MarkStale(time.Now().UTC(), staleThresholds)
	rebuiltAt := time.Now().UTC()
	if !snapshot.LastUpdate.IsZero() && snapshot.LastUpdate.After(rebuiltAt) {
		rebuiltAt = snapshot.LastUpdate
	}

	var occurredAt *time.Time
	if !snapshot.LastUpdate.IsZero() {
		occ := snapshot.LastUpdate
		occurredAt = &occ
	}
	recorded := recordRegistryChangesBetweenGenerationsSkipping(registry, rebuilt, rebuiltAt, occurredAt, SourcePulseDiff, "", a.restartRediscoveryFilterLocked(registry.store))
	rebuilt.PersistIdentityPins()

	a.mu.Lock()
	a.registry = rebuilt
	a.registryStaleThresholds = staleThresholds
	a.activeAlerts = append([]models.Alert(nil), snapshot.ActiveAlerts...)
	a.lastRebuiltAt = rebuiltAt
	a.mu.Unlock()
	a.bindLegacyHistory(rebuilt, time.Now())
	// After the swap, so an observer reading the adapter sees the generation
	// that produced the change.
	a.notifyChanges(recorded)
}

// restartRediscoveryFilterLocked returns the skip filter for a registry diff.
// A resource's first appearance in this run is a "resource discovered" change
// built against an empty generation; for a resource the history already knew
// it becomes:
//   - nothing, when its last recorded state matches (or none was recorded);
//   - a transition from its last recorded state, when that state changed while
//     Pulse was stopped;
//   - the discovery unchanged, when it was last recorded as removed.
//
// The resource then leaves the baseline, so later changes record normally.
// The baseline is read from store on the first diff. Callers must hold
// mutationMu.
func (a *MonitorAdapter) restartRediscoveryFilterLocked(store ResourceStore) func(*ResourceChange) bool {
	if !a.restartBaselineLoaded {
		a.restartBaselineLoaded = true
		if reader, ok := store.(lastResourceStateReader); ok {
			states, err := reader.LastResourceStates()
			if err != nil {
				log.Printf("unifiedresources: cannot read change history before the first diff; this run may record known resources as discovered: %v", err)
			}
			if len(states) > 0 {
				a.restartBaseline = states
			}
		}
	}
	if len(a.restartBaseline) == 0 {
		return nil
	}
	return func(change *ResourceChange) bool {
		id := CanonicalResourceID(change.ResourceID)
		last, known := a.restartBaseline[id]
		if !known {
			return false
		}
		delete(a.restartBaseline, id)
		if change.Kind != ChangeStateTransition || change.From != "absent" || last == "absent" {
			return false
		}
		if last == "" || last == change.To {
			return true
		}
		change.From = last
		change.OccurredAt = nil
		change.Reason = "resource state changed while Pulse was stopped"
		change.Metadata = map[string]any{"changeType": "state_changed_while_stopped", "changedFields": []string{"status"}}
		return false
	}
}

// ShouldSkipAPIPolling returns true when agent coverage indicates API
// polling for the hostname should be skipped entirely.
func (a *MonitorAdapter) ShouldSkipAPIPolling(hostname string) bool {
	hostname = strings.ToLower(strings.TrimSpace(hostname))
	if hostname == "" {
		return false
	}

	multiplier, ok := a.GetPollingRecommendations()[hostname]
	if !ok {
		return false
	}
	return multiplier == 0
}

// GetPollingRecommendations returns hostname -> polling multiplier.
// 0 means skip API polling; 0.5 means reduced frequency.
func (a *MonitorAdapter) GetPollingRecommendations() map[string]float64 {
	recommendations := make(map[string]float64)

	for _, resource := range a.GetAll() {
		sourceType := monitorSourceType(resource.Sources)
		if sourceType != "agent" && sourceType != "hybrid" {
			continue
		}

		hostname := monitorHostname(resource)
		if hostname == "" {
			hostname = strings.TrimSpace(resource.Name)
		}
		if hostname == "" {
			continue
		}

		key := strings.ToLower(hostname)
		if sourceType == "hybrid" {
			if existing, exists := recommendations[key]; !exists || existing != 0 {
				recommendations[key] = 0.5
			}
			continue
		}
		recommendations[key] = 0
	}

	return recommendations
}

// GetAll returns all unified resources for monitor broadcast usage.
func (a *MonitorAdapter) GetAll() []Resource {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}

	return registry.List()
}

// GetAllWithMetricsTargets materializes one complete broadcast read, binding
// its detached target map to the same registry as its detached resource list.
// The adapter may publish a replacement immediately after this capture; neither
// half of the returned read then consults that newer generation.
func (a *MonitorAdapter) GetAllWithMetricsTargets() ([]Resource, map[string]MetricsTarget) {
	registry := a.currentRegistry()
	if registry == nil {
		return nil, nil
	}
	return registry.ListWithMetricsTargets()
}

// GetAllWithMetricsTargetsAndStaleThresholds is GetAllWithMetricsTargets
// plus the stale thresholds the listed registry generation was judged by,
// read with the registry pointer, so a rebuild publishing meanwhile cannot
// pair one generation's listing with another's thresholds.
func (a *MonitorAdapter) GetAllWithMetricsTargetsAndStaleThresholds() ([]Resource, map[string]MetricsTarget, map[DataSource]time.Duration) {
	registry, thresholds := a.currentRegistryAndStaleThresholds()
	if registry == nil {
		return nil, nil, nil
	}
	resources, targets := registry.ListWithMetricsTargets()
	return resources, targets, thresholds
}

func (a *MonitorAdapter) unifiedAIAdapter() *UnifiedAIAdapter {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return &UnifiedAIAdapter{registry: registry}
}

// GetInfrastructure returns infrastructure resources for unified AI context.
func (a *MonitorAdapter) GetInfrastructure() []Resource {
	adapter := a.unifiedAIAdapter()
	if adapter == nil {
		return nil
	}
	return adapter.GetInfrastructure()
}

// GetWorkloads returns workload resources for unified AI context.
func (a *MonitorAdapter) GetWorkloads() []Resource {
	adapter := a.unifiedAIAdapter()
	if adapter == nil {
		return nil
	}
	return adapter.GetWorkloads()
}

// GetByType returns resources filtered by type for MCP tools.
func (a *MonitorAdapter) GetByType(t ResourceType) []Resource {
	adapter := a.unifiedAIAdapter()
	if adapter == nil {
		return nil
	}
	return adapter.GetByType(t)
}

// GetStats returns aggregate stats for unified AI context.
func (a *MonitorAdapter) GetStats() ResourceStats {
	adapter := a.unifiedAIAdapter()
	if adapter == nil {
		return ResourceStats{
			ByType:   make(map[ResourceType]int),
			ByStatus: make(map[ResourceStatus]int),
			BySource: make(map[DataSource]int),
		}
	}
	return adapter.GetStats()
}

// GetTopByCPU returns top CPU resources for unified AI context.
func (a *MonitorAdapter) GetTopByCPU(limit int, types []ResourceType) []Resource {
	adapter := a.unifiedAIAdapter()
	if adapter == nil {
		return nil
	}
	return adapter.GetTopByCPU(limit, types)
}

// GetTopByMemory returns top memory resources for unified AI context.
func (a *MonitorAdapter) GetTopByMemory(limit int, types []ResourceType) []Resource {
	adapter := a.unifiedAIAdapter()
	if adapter == nil {
		return nil
	}
	return adapter.GetTopByMemory(limit, types)
}

// GetTopByDisk returns top disk resources for unified AI context.
func (a *MonitorAdapter) GetTopByDisk(limit int, types []ResourceType) []Resource {
	adapter := a.unifiedAIAdapter()
	if adapter == nil {
		return nil
	}
	return adapter.GetTopByDisk(limit, types)
}

// GetRelated returns related resources for unified AI context.
func (a *MonitorAdapter) GetRelated(resourceID string) map[string][]Resource {
	adapter := a.unifiedAIAdapter()
	if adapter == nil {
		return map[string][]Resource{}
	}
	return adapter.GetRelated(resourceID)
}

// FindContainerHost resolves a container host for unified AI context.
func (a *MonitorAdapter) FindContainerHost(containerNameOrID string) string {
	adapter := a.unifiedAIAdapter()
	if adapter == nil {
		return ""
	}
	return adapter.FindContainerHost(containerNameOrID)
}

// PopulateFromSnapshot ingests a fresh state snapshot into the registry.
func (a *MonitorAdapter) PopulateFromSnapshot(snapshot models.StateSnapshot) {
	a.replaceRegistry(snapshot, nil)
}

// PopulateSnapshotAndSupplemental atomically rebuilds the registry from a
// snapshot plus source-native supplemental records before exposing the result.
func (a *MonitorAdapter) PopulateSnapshotAndSupplemental(snapshot models.StateSnapshot, recordsBySource map[DataSource][]IngestRecord) {
	a.replaceRegistry(snapshot, recordsBySource)
}

// PopulateSupplementalRecords ingests source-native records emitted outside the
// legacy state snapshot pipeline.
func (a *MonitorAdapter) PopulateSupplementalRecords(source DataSource, records []IngestRecord) {
	if a == nil {
		return
	}
	a.mutationMu.Lock()
	defer a.mutationMu.Unlock()

	// Records merge into the current generation, so they are judged by the
	// thresholds it was; thresholds set since wait for the next rebuild.
	registry, thresholds := a.currentRegistryAndStaleThresholds()
	if registry == nil || len(records) == 0 || strings.TrimSpace(string(source)) == "" {
		return
	}
	before := registry.List()
	registry.IngestRecordsWithStaleThresholds(source, records, thresholds)
	rebuiltAt := time.Now().UTC()
	recorded := recordRegistryChangesSkipping(registry.store, before, registry.List(), rebuiltAt, nil, SourcePlatformEvent, changeSourceAdapterForDataSource(source), a.restartRediscoveryFilterLocked(registry.store))
	registry.PersistIdentityPins()
	a.mu.Lock()
	a.lastRebuiltAt = rebuiltAt
	a.mu.Unlock()
	a.notifyChanges(recorded)
}

// MetricsTargetForResource resolves the history/metrics target for a canonical
// resource currently held by the adapter.
func (a *MonitorAdapter) MetricsTargetForResource(resourceID string) *MetricsTarget {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.MetricsTarget(resourceID)
}

// UnifiedResourceFreshness returns the most recent point at which the adapter
// replaced or mutated its canonical registry contents.
func (a *MonitorAdapter) UnifiedResourceFreshness() time.Time {
	if a == nil {
		return time.Time{}
	}

	a.mu.RLock()
	defer a.mu.RUnlock()
	return a.lastRebuiltAt
}

// VMs returns cached VM views for AI/read-state consumers.
func (a *MonitorAdapter) VMs() []*VMView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.VMs()
}

// Containers returns cached LXC container views for AI/read-state consumers.
func (a *MonitorAdapter) Containers() []*ContainerView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.Containers()
}

// Nodes returns cached Proxmox node views for AI/read-state consumers.
func (a *MonitorAdapter) Nodes() []*NodeView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.Nodes()
}

// Hosts returns cached agent-host views for AI/read-state consumers.
func (a *MonitorAdapter) Hosts() []*HostView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.Hosts()
}

// DockerHosts returns cached Docker host views for AI/read-state consumers.
func (a *MonitorAdapter) DockerHosts() []*DockerHostView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.DockerHosts()
}

// DockerContainers returns cached Docker container views for AI/read-state consumers.
func (a *MonitorAdapter) DockerContainers() []*DockerContainerView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.DockerContainers()
}

// StoragePools returns cached storage pool views for AI/read-state consumers.
func (a *MonitorAdapter) StoragePools() []*StoragePoolView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.StoragePools()
}

// PhysicalDisks returns cached physical disk views for AI/read-state consumers.
func (a *MonitorAdapter) PhysicalDisks() []*PhysicalDiskView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.PhysicalDisks()
}

// PBSInstances returns cached PBS instance views for AI/read-state consumers.
func (a *MonitorAdapter) PBSInstances() []*PBSInstanceView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.PBSInstances()
}

// PMGInstances returns cached PMG instance views for AI/read-state consumers.
func (a *MonitorAdapter) PMGInstances() []*PMGInstanceView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.PMGInstances()
}

// K8sClusters returns cached Kubernetes cluster views for AI/read-state consumers.
func (a *MonitorAdapter) K8sClusters() []*K8sClusterView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.K8sClusters()
}

// K8sNodes returns cached Kubernetes node views for AI/read-state consumers.
func (a *MonitorAdapter) K8sNodes() []*K8sNodeView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.K8sNodes()
}

// Pods returns cached pod views for AI/read-state consumers.
func (a *MonitorAdapter) Pods() []*PodView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.Pods()
}

// K8sDeployments returns cached deployment views for AI/read-state consumers.
func (a *MonitorAdapter) K8sDeployments() []*K8sDeploymentView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.K8sDeployments()
}

// Workloads returns cached polymorphic workload views for AI/read-state consumers.
func (a *MonitorAdapter) Workloads() []*WorkloadView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.Workloads()
}

// Infrastructure returns cached polymorphic infrastructure views for AI/read-state consumers.
func (a *MonitorAdapter) Infrastructure() []*InfrastructureView {
	registry := a.currentRegistry()
	if registry == nil {
		return nil
	}
	return registry.Infrastructure()
}

func monitorSourceType(sources []DataSource) string {
	if len(sources) > 1 {
		return "hybrid"
	}
	if len(sources) == 1 {
		switch sources[0] {
		case SourceAgent, SourceDocker, SourceK8s:
			return "agent"
		default:
			return "api"
		}
	}
	return "api"
}

func monitorHostname(resource Resource) string {
	if resource.Agent != nil {
		if hostname := strings.TrimSpace(resource.Agent.Hostname); hostname != "" {
			return hostname
		}
	}
	if resource.Docker != nil {
		if hostname := strings.TrimSpace(resource.Docker.Hostname); hostname != "" {
			return hostname
		}
	}
	if resource.Proxmox != nil {
		if hostname := strings.TrimSpace(resource.Proxmox.NodeName); hostname != "" {
			return hostname
		}
	}
	for _, hostname := range resource.Identity.Hostnames {
		if trimmed := strings.TrimSpace(hostname); trimmed != "" {
			return trimmed
		}
	}
	return ""
}