Keep guest-memory provenance bound to its original observation

Expose current, last-known and unavailable memory through raw guest and selected unified metrics without renewing QGA evidence during repeated backup deferrals. Preserve independent PVE/linked-agent source times, numeric selection, History and alert policy. Annotate selected metrics as well as raw facets so cross-source fallback cannot inherit another source freshness. Add connected observation, source ownership, clone and wire controls and update the shared subsystem contracts.

Change-source: pulse-maintainer
This commit is contained in:
pulse-triage[bot]
2026-10-04 17:00:24 +01:00
parent c50b8340fd
commit 43ccc6c39a
21 changed files with 434 additions and 31 deletions
@@ -15,6 +15,18 @@
## Purpose
### Memory annotation is not agent admission
The shared Memory model's optional guest `observation` records selected metric
state/source/original known time. Missing annotation is legacy/unknown. It
changes neither numeric validity nor enrollment, identity, removal, token scope
or guest-command authority. Canonical agent metric annotations use server-owned
report/source receipt time rather than a client-supplied annotation, and a
PVE-refreshed guest row cannot renew the correlated agent observation.
`TestGuestMemoryObservationWireContract` pins omission, round-trip preservation
and unchanged numeric validity; linked-agent/source-selection controls pin
receipt ownership and offline exclusion. No native liveness/thaw is asserted.
### TrueNAS probes are not fleet or inventory liveness
A separate settings connection probe does not establish runtime provider
@@ -17,6 +17,28 @@
## Purpose
### Guest memory observations are source-owned
QEMU and LXC memory carry an optional `observation` with `state` (`current`,
`last-known`, `unavailable`), canonical `source`, and original RFC3339
`observedAt` when known. Normal TTL cache hits keep the original read time.
Repeated QGA/backup deferrals are last-known, never renewed by a poll or
diagnostic RetrievedAt; expired/missing usage and powered-off guests expose
unavailability without inventing a read time. Legacy unannotated values make
no freshness assertion. Independently selected PVE status/listing or linked
Pulse-agent memory remains distinct from disk or QGA collection state. Agent
receipt time belongs to its source status, not a guest row refreshed by PVE.
Annotation preserves numeric selection, capacity, retention, guest identity,
agent admission, alert thresholds and existing History recording. It grants
no live-check authority or proof of thaw. Existing legacy state, raw Proxmox
facets and selected canonical memory metrics preserve the discriminator;
selected metric provenance must not be borrowed from another merged facet.
`TestGuestMemoryObservationContract` exercises poll/cache/deferral/expiry/
resumption through unified and served conversions; wire and source-selection
controls cover omission, cloning and independent live agent data. These are
synthetic source proofs, not native QGA/HAOS acceptance or delivered relief.
### Unavailable backup-age evaluation is not silent recovery
PVE, PBS and mock backup checks share one failure-preserving evaluator. The
@@ -21,6 +21,17 @@
## Purpose
### Memory provenance does not imply recoverability
Canonical metric values may carry optional selected guest memory observation
state/source/original known time. The facet follows that numeric source through
cloning and frontend conversion; last-known or unavailable memory is not fresh
backup evidence, a storage-health verdict or confirmation of thaw. This
annotation changes no backup identity, retention, rollup selection, restore
policy or snapshot data. The connected monitoring observation and metric
source-selection controls verify the shared type without weakening recovery
evidence requirements.
### Latest provider observations do not scan retained evidence payloads
The protection-posture reader enumerates provider/scope keys through the existing
@@ -23,6 +23,23 @@ and sort the complete canonical change table while startup and ingestion wait.
## Purpose
### Guest memory provenance follows metric selection
Raw Proxmox `memory.observation` preserves the guest builder's state, source
and original known observation time. Canonical memory metrics carry their own
optional `observation` through clones, merges and served frontend conversion.
A retained platform facet cannot supply provenance for a different selected
agent metric. Agent memory annotations are authored from server-owned source
receipt/freshness, never agent-supplied annotation or merged guest LastSeen.
Linked-agent views retain that source time after host/guest correlation.
Absent annotations are unknown/legacy; absent observation times stay absent.
Numeric preference, unavailable same-source withdrawal, cross-source fallback,
identity and freshness policy remain unchanged. Guest memory and disk-read
provenance are independent. Adapter/source-selection and linked-view controls
exercise these boundaries, with the connected monitoring contract pinning the
actual served projection; this does not prove native recovery or publication.
### PBS capacity consumers preserve explicit read failure
`ResourcePBSDatastore.error` describes existing provider read-failure evidence,