From 6192479e96f2ddfb07c01581bb8c2f423cf1f4cd Mon Sep 17 00:00:00 2001 From: Clovis Muneza Date: Mon, 3 Aug 2026 23:11:46 -0400 Subject: [PATCH] docs(design): define current failure supersession --- DESIGN.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/DESIGN.md b/DESIGN.md index f3eb70fe..31714666 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1355,6 +1355,20 @@ The status output should include daemon state, Gateway state, DNS resolver state `pv status` derives aggregate health from existing current state in v1: PV-owned files, LaunchAgent registration, socket health, SQLite state, runtime observed state, Project env observed state, recent jobs, installed Managed Resource tracks, port assignments, DNS, `pf`, CA, and read-only platform inspectors. PV does not need separate persisted aggregate system-health or Project-health subjects for the first status implementation. +### Current Failures and Job History + +Aggregate health uses current unresolved failures, not every retained failed job. Daemon jobs remain immutable historical records for `pv jobs`; a later success never deletes, rewrites, or changes the status of an earlier failure. PV instead treats each failure as an episode for a diagnostic subject. A diagnostic subject identifies both the affected component and the condition that was verified, such as Gateway runtime readiness, one Project's env rendering, or one Managed Resource track's runtime health. Outcomes for unrelated subjects do not supersede each other. + +A failed outcome remains current until PV records newer successful verification for the same subject. Successful verification may come from a completed job whose recorded reconciliation coverage contains that subject or from a newer healthy runtime observation that directly verifies the same condition. A generic healthy process observation does not clear a config, env-rendering, allocation, or privileged-integration failure that it did not verify. Timestamp ordering is evaluated within a subject; unrelated newer work has no effect. + +Job supersession uses job kind plus recorded work coverage, not the requested scope string alone. Scope remains useful request and history metadata, but it is not proof that a component was reconciled. A successful `reconcile system` covers the global Gateway, linked Projects, and demanded Managed Resources actually included in that run. A successful Project reconciliation covers the selected Project and the global Gateway because the Project path invokes Gateway reconciliation. Gateway-runtime reconciliation covers the Gateway. Backing Managed Resource reconciliation covers the resource track and the Project state actually refreshed by that operation. Only completed successful coverage clears failures; partial work from a failed job does not clear an earlier failure unless a newer healthy observed-state record independently verifies the subject. + +An `update system` job that finds no installed updates or no changed artifacts verifies only the update assessment. It does not cover reconciliation and cannot clear a reconciliation or runtime failure. When an update changes artifacts and subsequently performs reconciliation successfully, its recorded coverage includes the subjects actually reconciled in addition to the update assessment. This distinction prevents a no-op update from hiding an unverified system failure. + +Failure deduplication applies only within one continuous unresolved episode. A repeated background error for the same subject and equivalent error may be coalesced while no newer success exists. Once newer successful coverage or a matching healthy observation resolves the episode, the same error recurring later starts a new current failure and is recorded again. Searching retained history for any matching error string is never sufficient deduplication. + +`pv status` and `pv doctor` select repair advice from the current failure's typed subject and condition. They prefer the narrowest command that can repair and then verify that subject, such as `pv daemon:restart`, `pv dns:install`, `pv ports:install`, `pv ca:trust`, or an applicable Managed Resource command. They use broader `pv restart` or `pv setup` guidance only when no focused command covers the failure. Historical failures remain visible through `pv jobs` but do not make aggregate status fail after their subjects have newer successful verification. + `pv status` shows the log directory and a summary of the most recent daemon or reconciliation errors without dumping full logs by default. `pv status` may show Managed Resource health and ports, but it must not print credentials or secrets.