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.

Keep Proxmox update recovery zeros explicit on the wire

pulse-triage[bot]592bfdd10150
diff --git a/docs/release-control/v6/internal/subsystems/monitoring.md b/docs/release-control/v6/internal/subsystems/monitoring.md
index dc0b253639..0badb88278 100644
--- a/docs/release-control/v6/internal/subsystems/monitoring.md
+++ b/docs/release-control/v6/internal/subsystems/monitoring.md
@@ -8131,6 +8131,11 @@ non-403 failures keep their ordinary OS-specific cadence. Denial is not a memory
sample or a new successful origin. The same instance/node/VM key, read ownership,
lifecycle invalidation, cancellation and uncertainty fences remain effective.
+The unified wire serializer keeps an explicit update verdict atomic: measured
+zero, cleared reason and absent origin must replace their stale predecessors
+in the consuming node drawer. Its registered JSON and desktop/narrow consuming
+proof is owned by the unified-resources contract, not a new collection policy.
+
Both paths use `proxmox.APIErrorStatus`, including wrapped client/cluster errors,
not a quoted status in a provider body. A known non-403 HTTP error cannot be
labelled permission-denied from its text. No token permission, guest operation,
diff --git a/docs/release-control/v6/internal/subsystems/registry.json b/docs/release-control/v6/internal/subsystems/registry.json
index fb9a4ecd35..bd63a4b7f1 100644
--- a/docs/release-control/v6/internal/subsystems/registry.json
+++ b/docs/release-control/v6/internal/subsystems/registry.json
@@ -8667,6 +8667,19 @@
"exact_files": [],
"require_explicit_path_policy_coverage": true,
"path_policies": [
+ {
+ "id": "proxmox-update-evidence-json",
+ "label": "authoritative Proxmox update JSON clearing proof",
+ "match_prefixes": [],
+ "match_files": [
+ "internal/unifiedresources/proxmox_update_evidence_json.go"
+ ],
+ "allow_same_subsystem_tests": false,
+ "test_prefixes": [],
+ "exact_files": [
+ "internal/unifiedresources/proxmox_update_evidence_test.go"
+ ]
+ },
{
"id": "identity-canonicalization",
"label": "canonical identity proof",
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index 825235c090..628a5f7cc3 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -23,6 +23,26 @@ and sort the complete canonical change table while startup and ingestion wait.
## Purpose
+### Explicit Proxmox update verdicts carry their complete wire observation
+
+`internal/unifiedresources/proxmox_update_evidence_json.go` serializes a PVE
+node's explicit pending-update status with its count, successful origin and
+fixed reason together. It includes a measured zero, an empty cleared reason
+and a null absent origin. Generic canonical facet merges otherwise retain
+omitted keys: after a stale seven-package observation, a successful empty
+response must show checked zero without inherited access-denial help. Losing
+the successful origin must likewise clear it, not retain an older date.
+
+The canonical API resource and realtime/broadcast projection use the same
+Proxmox metadata serializer. Guests and legacy sources without an explicit
+update verdict retain their previous payload exactly, including omitted zero
+fields; no new observation, permission, identity, polling or UI policy is added.
+`proxmox_update_evidence_test.go` covers checked/stale zero, unavailable/offline
+clears, generic merge behaviour, API/realtime parity and unchanged guest/legacy/
+nil payloads. Consuming browser proof must exercise the actual producer frames
+through the existing canonical merger and open node drawer at desktop/narrow
+widths, not replace an omitted zero with a fixture-supplied value.
+
### Restore-point inspection states what its evidence cannot confirm
The existing By date record detail places a visible, wrapping evidence-limits
diff --git a/internal/unifiedresources/proxmox_update_evidence_json.go b/internal/unifiedresources/proxmox_update_evidence_json.go
new file mode 100644
index 0000000000..d7a1dd69c0
--- /dev/null
+++ b/internal/unifiedresources/proxmox_update_evidence_json.go
@@ -0,0 +1,28 @@
+package unifiedresources
+
+import (
+ "encoding/json"
+ "time"
+)
+
+// MarshalJSON keeps an explicit update verdict atomic on incremental readers.
+// Omitting a measured zero, a cleared reason or an absent origin would let a
+// generic facet merge retain the preceding positive/stale observation instead.
+// Guests and legacy sources without a verdict retain their existing payload.
+func (p *ProxmoxData) MarshalJSON() ([]byte, error) {
+ type plain ProxmoxData
+ if p == nil || p.PendingUpdatesStatus == "" {
+ return json.Marshal((*plain)(p))
+ }
+ return json.Marshal(struct {
+ *plain
+ PendingUpdates int `json:"pendingUpdates"`
+ PendingUpdatesCheckedAt *time.Time `json:"pendingUpdatesCheckedAt"`
+ PendingUpdatesReason string `json:"pendingUpdatesReason"`
+ }{
+ plain: (*plain)(p),
+ PendingUpdates: p.PendingUpdates,
+ PendingUpdatesCheckedAt: p.PendingUpdatesCheckedAt,
+ PendingUpdatesReason: p.PendingUpdatesReason,
+ })
+}
diff --git a/internal/unifiedresources/proxmox_update_evidence_test.go b/internal/unifiedresources/proxmox_update_evidence_test.go
index 1ae905d14a..5326292d09 100644
--- a/internal/unifiedresources/proxmox_update_evidence_test.go
+++ b/internal/unifiedresources/proxmox_update_evidence_test.go
@@ -1,10 +1,80 @@
package unifiedresources
import (
+ "encoding/json"
"testing"
"time"
+
+ "github.com/rcourtman/pulse-go-rewrite/internal/models"
)
+func TestProxmoxUpdateEvidenceJSONCarriesAuthoritativeClears(t *testing.T) {
+ at := time.Date(2026, 10, 30, 5, 0, 0, 0, time.UTC)
+ for _, tc := range []struct {
+ name string
+ data *ProxmoxData
+ }{
+ {"checked zero", &ProxmoxData{PendingUpdatesStatus: "checked", PendingUpdatesCheckedAt: &at}},
+ {"stale zero", &ProxmoxData{PendingUpdatesStatus: "stale", PendingUpdatesCheckedAt: &at, PendingUpdatesReason: "permission_denied"}},
+ {"unavailable", &ProxmoxData{PendingUpdatesStatus: "unavailable", PendingUpdatesReason: "permission_denied"}},
+ {"offline", &ProxmoxData{PendingUpdatesStatus: "not_checked", PendingUpdatesReason: "node_offline"}},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ wire, err := json.Marshal(tc.data)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var fields map[string]json.RawMessage
+ if err := json.Unmarshal(wire, &fields); err != nil {
+ t.Fatal(err)
+ }
+ for _, field := range []string{"pendingUpdates", "pendingUpdatesCheckedAt", "pendingUpdatesStatus", "pendingUpdatesReason"} {
+ if _, present := fields[field]; !present {
+ t.Errorf("authoritative observation omitted %s: %s", field, wire)
+ }
+ }
+ // The consuming snapshot merger retains omitted keys. Exercise that
+ // real wire behaviour rather than merely round-tripping a fresh zero.
+ merged := map[string]any{"pendingUpdates": float64(7), "pendingUpdatesReason": "permission_denied", "pendingUpdatesCheckedAt": "old"}
+ if err := json.Unmarshal(wire, &merged); err != nil {
+ t.Fatal(err)
+ }
+ if merged["pendingUpdates"] != float64(0) || merged["pendingUpdatesReason"] != tc.data.PendingUpdatesReason ||
+ (tc.data.PendingUpdatesCheckedAt == nil && merged["pendingUpdatesCheckedAt"] != nil) {
+ t.Fatalf("JSON retained an obsolete count/reason/origin: %+v", merged)
+ }
+ // The same metadata is exposed in API resources and realtime
+ // projections. Both must invoke the authoritative serializer.
+ resourceWire, err := json.Marshal(&Resource{Proxmox: tc.data})
+ if err != nil {
+ t.Fatal(err)
+ }
+ var resource struct{ Proxmox json.RawMessage }
+ if err := json.Unmarshal(resourceWire, &resource); err != nil || string(resource.Proxmox) != string(wire) {
+ t.Fatalf("resource API changed update metadata: %s / %v", resourceWire, err)
+ }
+ front := models.ConvertResourceToFrontend(models.ResourceConvertInput{Proxmox: wire})
+ if string(front.Proxmox) != string(wire) {
+ t.Fatal("realtime projection dropped authoritative clears")
+ }
+ })
+ }
+}
+
+func TestProxmoxUpdateEvidenceJSONPreservesGuestsLegacyAndNil(t *testing.T) {
+ for _, p := range []*ProxmoxData{nil, {}, {VMID: 105, OSName: "Linux"}, {PendingUpdates: 7}} {
+ wire, err := json.Marshal(p)
+ if err != nil {
+ t.Fatal(err)
+ }
+ type plain ProxmoxData
+ original, err := json.Marshal((*plain)(p))
+ if err != nil || string(wire) != string(original) {
+ t.Fatalf("unrelated payload changed: %s, want %s / %v", wire, original, err)
+ }
+ }
+}
+
func TestMergeProxmoxDataTreatsUpdateEvidenceAsAuthoritative(t *testing.T) {
oldCheckedAt := time.Date(2026, 8, 29, 10, 0, 0, 0, time.UTC)
newCheckedAt := oldCheckedAt.Add(time.Hour)
diff --git a/scripts/release_control/subsystem_lookup_test.py b/scripts/release_control/subsystem_lookup_test.py
index 63fd4d6444..26054ba843 100644
--- a/scripts/release_control/subsystem_lookup_test.py
+++ b/scripts/release_control/subsystem_lookup_test.py
@@ -97,6 +97,16 @@ def _contract_reference(contract_path: str, needle: str, runtime_path: str) -> d
class SubsystemLookupTest(unittest.TestCase):
+ def test_proxmox_update_json_uses_authoritative_wire_proof(self) -> None:
+ result = lookup_paths(["internal/unifiedresources/proxmox_update_evidence_json.go"])
+ self.assertEqual(result["unowned_runtime_files"], [])
+ matches = result["files"][0]["matches"]
+ self.assertEqual(len(matches), 1)
+ self.assertEqual(matches[0]["subsystem"], "unified-resources")
+ proof = matches[0]["verification_requirement"]
+ self.assertEqual(proof["id"], "proxmox-update-evidence-json")
+ self.assertEqual(proof["exact_files"], ["internal/unifiedresources/proxmox_update_evidence_test.go"])
+
def test_release_presentation_proofs_do_not_widen_promotion_metadata(self):
paths = [
".github/PULL_REQUEST_TEMPLATE.md",