Normalize Proxmox special ZFS groups

Refs #1413

docs/release-control/v6/internal/subsystems/monitoring.md

@@ -43,14 +43,15 @@ truth for live infrastructure data.
 19. `internal/dockeragent/swarm.go`
 20. `internal/dockeragent/collect.go`
 21. `pkg/proxmox/ceph.go`
-22. `internal/monitoring/guest_memory_sources.go`
-23. `internal/monitoring/guest_memory_stability.go`
-24. `internal/monitoring/monitor_polling_vm.go`
-25. `internal/monitoring/monitor_pve_guest_builders.go`
-26. `internal/monitoring/monitor_pve_guest_poll.go`
-27. `internal/monitoring/guest_disk_stability.go`
-28. `internal/monitoring/mock_metrics_history.go`
-29. `internal/monitoring/mock_chart_history.go`
+22. `pkg/proxmox/zfs.go`
+23. `internal/monitoring/guest_memory_sources.go`
+24. `internal/monitoring/guest_memory_stability.go`
+25. `internal/monitoring/monitor_polling_vm.go`
+26. `internal/monitoring/monitor_pve_guest_builders.go`
+27. `internal/monitoring/monitor_pve_guest_poll.go`
+28. `internal/monitoring/guest_disk_stability.go`
+29. `internal/monitoring/mock_metrics_history.go`
+30. `internal/monitoring/mock_chart_history.go`
 
 ## Shared Boundaries
 
@@ -66,7 +67,8 @@ truth for live infrastructure data.
 6. Add or change Docker Swarm manager task/service runtime collection through `internal/dockeragent/swarm.go`
 7. Add or change Docker or Podman container stats compatibility and runtime metric semantics through `internal/dockeragent/collect.go`
 8. Add or change Proxmox Ceph compatibility payload decoding through `pkg/proxmox/ceph.go`
-9. Add or change mock chart synthesis, seeded history continuity, or mock-owned
+9. Add or change Proxmox ZFS compatibility payload decoding and vdev-role normalization through `pkg/proxmox/zfs.go`
+10. Add or change mock chart synthesis, seeded history continuity, or mock-owned
    chart fallbacks through `internal/monitoring/mock_metrics_history.go` and
    `internal/monitoring/mock_chart_history.go`
 
@@ -80,7 +82,7 @@ truth for live infrastructure data.
 
 1. Update this contract when monitoring truth ownership changes
 2. Tighten guardrails when `GetState()`-centric paths are removed
-3. Keep discovery-provider, host-agent ingest, guest-memory trust, metrics-history, storage-risk, Docker/Podman container collection, Proxmox Ceph compatibility, Docker Swarm collection, and container bootstrap proof routes explicit in `registry.json`
+3. Keep discovery-provider, host-agent ingest, guest-memory trust, metrics-history, storage-risk, Docker/Podman container collection, Proxmox Ceph and ZFS compatibility, Docker Swarm collection, and container bootstrap proof routes explicit in `registry.json`
 4. Update related read-state or monitor tests when new collector paths land
 5. Keep platform ingestion semantics aligned with
    `docs/release-control/v6/internal/PLATFORM_SUPPORT_MODEL.md`: hybrid is a
@@ -92,6 +94,12 @@ truth for live infrastructure data.
    and the attached ZFS health model must carry the provider-reported `pool`
    field through to runtime storage snapshots and use it before name/path
    heuristics when matching ZFS pool health on multi-storage hosts.
+   That same Proxmox compatibility boundary also owns top-level ZFS vdev-role
+   normalization. Provider payload buckets such as `special`, `log`, `cache`,
+   and `spares` may omit a concrete health state; `pkg/proxmox/zfs.go` must
+   treat those blank-state grouping rows as role metadata rather than projecting
+   operator-visible `UNKNOWN` failures unless the bucket or one of its children
+   carries an actual degraded state or error count.
 
 ## Current State
 

docs/release-control/v6/internal/subsystems/registry.json

@@ -3200,7 +3200,8 @@
         "docker-entrypoint.sh",
         "internal/dockeragent/collect.go",
         "internal/dockeragent/swarm.go",
-        "pkg/proxmox/ceph.go"
+        "pkg/proxmox/ceph.go",
+        "pkg/proxmox/zfs.go"
       ],
       "verification": {
         "allow_same_subsystem_tests": true,
@@ -3365,6 +3366,20 @@
               "internal/dockeragent/swarm_test.go"
             ]
           },
+          {
+            "id": "proxmox-zfs-runtime",
+            "label": "proxmox zfs compatibility proof",
+            "match_prefixes": [],
+            "match_files": [
+              "pkg/proxmox/zfs.go"
+            ],
+            "allow_same_subsystem_tests": false,
+            "test_prefixes": [],
+            "exact_files": [
+              "pkg/proxmox/zfs_details_test.go",
+              "pkg/proxmox/zfs_test.go"
+            ]
+          },
           {
             "id": "proxmox-ceph-runtime",
             "label": "proxmox ceph compatibility proof",

internal/models/models.go

@@ -1122,7 +1122,7 @@ func (p ZFSPool) NormalizeCollections() ZFSPool {
 // ZFSDevice represents a device in a ZFS pool
 type ZFSDevice struct {
 	Name           string `json:"name"`
-	Type           string `json:"type"`  // disk, mirror, raidz, raidz2, raidz3, spare, log, cache
+	Type           string `json:"type"`  // disk, mirror, raidz, raidz2, raidz3, spare, log, cache, special, special-group
 	State          string `json:"state"` // ONLINE, DEGRADED, FAULTED, OFFLINE, REMOVED, UNAVAIL
 	ReadErrors     int64  `json:"readErrors"`
 	WriteErrors    int64  `json:"writeErrors"`

pkg/proxmox/zfs.go

@@ -151,6 +151,8 @@ func convertDeviceRecursive(dev ZFSPoolDevice, parentRole string) []ZFSDevice {
 			role = "cache"
 		case lowerName == "spares" || strings.HasPrefix(lowerName, "spare"):
 			role = "spare"
+		case lowerName == "special":
+			role = "special"
 		}
 	}
 
@@ -177,10 +179,14 @@ func convertDeviceRecursive(dev ZFSPoolDevice, parentRole string) []ZFSDevice {
 		deviceType = "cache"
 	case isVdev && role == "spare":
 		deviceType = "spare"
+	case isVdev && role == "special":
+		deviceType = "special-group"
 	case role == "log" && dev.Leaf == 1:
 		deviceType = "log"
 	case role == "cache" && dev.Leaf == 1:
 		deviceType = "cache"
+	case role == "special" && dev.Leaf == 1:
+		deviceType = "special"
 	}
 
 	isSpare := lowerName == "spares" || strings.HasPrefix(lowerName, "spare")
@@ -200,7 +206,7 @@ func convertDeviceRecursive(dev ZFSPoolDevice, parentRole string) []ZFSDevice {
 	}
 
 	if state == "UNKNOWN" {
-		if role == "log" || role == "cache" || role == "spare" || isSpare {
+		if role == "log" || role == "cache" || role == "spare" || role == "special" || isSpare {
 			healthyStates[state] = true
 		}
 	}

pkg/proxmox/zfs_test.go

@@ -186,6 +186,46 @@ func TestConvertDeviceRecursive_SpareWithErrors(t *testing.T) {
 	}
 }
 
+func TestConvertDeviceRecursive_SpecialDevices(t *testing.T) {
+	specialVdev := ZFSPoolDevice{
+		Name:  "special",
+		State: "",
+		Leaf:  0,
+		Children: []ZFSPoolDevice{
+			{Name: "nvme0n1", State: "ONLINE", Leaf: 1, Read: 1},
+		},
+	}
+
+	devices := convertDeviceRecursive(specialVdev, "")
+
+	if len(devices) != 1 {
+		t.Fatalf("expected 1 device, got %d", len(devices))
+	}
+	if devices[0].Type != "special" {
+		t.Errorf("Type = %q, want special", devices[0].Type)
+	}
+	if devices[0].State != "ONLINE" {
+		t.Errorf("State = %q, want ONLINE", devices[0].State)
+	}
+}
+
+func TestConvertDeviceRecursive_SkipsHealthySpecialGroupWithBlankState(t *testing.T) {
+	specialVdev := ZFSPoolDevice{
+		Name:  "special",
+		State: "",
+		Leaf:  0,
+		Children: []ZFSPoolDevice{
+			{Name: "nvme0n1", State: "ONLINE", Leaf: 1},
+		},
+	}
+
+	devices := convertDeviceRecursive(specialVdev, "")
+
+	if len(devices) != 0 {
+		t.Fatalf("expected 0 devices for healthy special group, got %d", len(devices))
+	}
+}
+
 func TestConvertDeviceRecursive_NestedMirror(t *testing.T) {
 	// Nested structure: mirror with healthy children
 	mirror := ZFSPoolDevice{
@@ -265,6 +305,33 @@ func TestConvertDeviceRecursive_L2arcDevice(t *testing.T) {
 	}
 }
 
+func TestConvertToModelZFSPool_OmitsHealthySpecialGroupingRows(t *testing.T) {
+	info := &ZFSPoolInfo{
+		Name:   "tank",
+		Health: "ONLINE",
+		State:  "ONLINE",
+		Status: "ok",
+		Devices: []ZFSPoolDevice{
+			{
+				Name:  "special",
+				State: "",
+				Leaf:  0,
+				Children: []ZFSPoolDevice{
+					{Name: "nvme0n1", State: "ONLINE", Leaf: 1},
+				},
+			},
+		},
+	}
+
+	pool := info.ConvertToModelZFSPool()
+	if pool == nil {
+		t.Fatal("expected pool")
+	}
+	if len(pool.Devices) != 0 {
+		t.Fatalf("expected healthy special grouping row to be omitted, got %+v", pool.Devices)
+	}
+}
+
 func TestConvertDeviceRecursive_InUseSpare(t *testing.T) {
 	spare := ZFSPoolDevice{
 		Name:  "spare-0",

scripts/release_control/canonical_completion_guard_test.py

@@ -216,6 +216,7 @@ class CanonicalCompletionGuardTest(unittest.TestCase):
                 "memory-source-runtime",
                 "docker-collect-runtime",
                 "docker-swarm-runtime",
+                "proxmox-zfs-runtime",
                 "proxmox-ceph-runtime",
                 "container-entrypoint-runtime",
                 "monitoring-runtime",