From 255096f20b0b6d9700d473c5155638dc73015d7a Mon Sep 17 00:00:00 2001 From: Grant Date: Mon, 13 Jul 2026 18:02:42 +0200 Subject: [PATCH] docs(dir): correct inverted DIR-7 in-mission-recovery intent to count-based fault-persistence model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 11 Jul DIR-7 addendum "In-mission recovery is mode-dependent" stated that AUV gate mode commits to recovery ON CONDITION-CLEAR. That was inverted and wrong — it produced a contradictory GREEN-while-in- RETURN_TO_SAFE state observed live. Corrected intent (v1.4, 13 Jul 2026, attributed to Grant): - GREEN is unconditionally a working state. A cleared fault returns the vehicle to GREEN and the mission continues/resumes; a cleared condition must never trigger or commit a recovery. Committed recovery is triggered by a fault PERSISTING or RECURRING, never by it clearing. - Three-tier fault model: (1) uncontrollable — power loss / anything that disables the safety logic itself, out of scope for the FSM, adjacent to shelved DIR-6; (2) transient/self-resetting — system attempts restore, returns to GREEN and resumes on success, each failure increments a raw count (deliberately no time window/duration), commits to RETURN_TO_SAFE only once the count exceeds a configured acceptable number; (3) hard/persistent — a RED that doesn't clear, commits immediately without waiting on a count. - All thresholds (acceptable count, transient-vs-hard classification) are configuration-driven via the resolved mode profile, same as health_role, never hardcoded. - Survives, correct: health_role mode-awareness (2a3e577); the safe-zone-reached arrival-exit mechanism (bf815cc) — its role (completing a committed recovery) is unchanged. Retired, known-wrong: 2a3e577's condition-clear entry logic, which bf815cc built its exit on top of — pending next-session rework into the count-based model. Only the ENTRY into committed recovery was wrong, not the exit. New Parked Design Item: adaptive restart-timing — monitor own restore count/duration per fault, log it, weigh future restart attempts against observed history rather than a fixed time. Deliberately holds all time/duration sophistication kept out of the count-based correction; depends on the count-based retry machinery existing first. Design-captured, not yet specified for build. Changelog and known-implementation-drift callout updated accordingly — failsafe_monitor's current condition-clear logic is now flagged as a known implementation gap pending rework, not merely an unimplemented addendum. Documentation only — no code or widget files touched. Not uploaded to Claude project knowledge; that remains a manual step. --- docs/design_intent_register.md | 169 ++++++++++++++++++++++++++------- 1 file changed, 133 insertions(+), 36 deletions(-) diff --git a/docs/design_intent_register.md b/docs/design_intent_register.md index 18d9850..06658e5 100644 --- a/docs/design_intent_register.md +++ b/docs/design_intent_register.md @@ -1,6 +1,6 @@ # Design Intent Register — Argonaut 3 -**Version:** 1.3 +**Version:** 1.4 **Date:** 13 July 2026 **File:** `docs/design_intent_register.md` (repo-tracked, no version number in filename) @@ -12,6 +12,7 @@ | Version | Date | Change | |---|---|---| +| 1.4 | 13 Jul 2026 | **CORRECTION: DIR-7 "in-mission recovery is mode-dependent" addendum was inverted — fixed.** The 11 Jul wording had AUV gate mode commit to recovery ON CONDITION-CLEAR; that produced a contradictory GREEN-while-in-`RETURN_TO_SAFE` state observed live. Corrected model: GREEN is unconditionally a working state; committed recovery is triggered by fault PERSISTENCE or RECURRENCE, never by clearing. Records a three-tier fault model (uncontrollable/out-of-scope for the FSM; transient/self-resetting with a raw failure-count trigger, deliberately no time window; hard/persistent, a RED that doesn't clear) with all thresholds configuration-driven via the resolved mode profile, same as `health_role`. Records what survives (health_role mode-awareness from `2a3e577`; the safe-zone-reached arrival-exit mechanism from `bf815cc`, unchanged in role) vs what's retired (the condition-clear entry logic in `2a3e577`, which `bf815cc` built its exit on top of) — pending next-session rework into the count-based model. **New Parked Design Item:** adaptive restart-timing (monitor own restore count/duration, weigh future attempts against observed history rather than a fixed time) — depends on the count-based retry machinery above existing first; design-captured, not build-specified. | | 1.3 | 13 Jul 2026 | **New Parked Design Item:** mode-aware safe-zone-reached arrival event (relates to the DIR-7 "in-mission recovery is mode-dependent" addendum) — the permanent `/rov/nav/safe_zone_reached` interface, mode-aware/sensor-derived arrival judgement (GPS at surface + EKF/dead-reckoning underwater), GPS recorded as first-class across mission types (not a hull/jacket-specific surface concern), gate-only scope, and the temporary W1-button bench-scaffolding publisher pending navigation. Implemented same day in `failsafe_monitor` (`bf815cc`) — see `docs/handover.md` §15f for the fix narrative; this entry records the design intent, not the commit detail. DIR-7 addendum's Implementation note updated: the mode-dependent recovery mechanism is no longer mode-blind (`2a3e577`, 13 Jul 2026). | | 1.2 | 11 Jul 2026 | **DIR-7's FC-connectivity MUST — RESOLVED**, four commits 11 Jul 2026 (full detail in `docs/handover.md` Changelog); open-flag callout updated accordingly. **DIR-7 gains two addenda:** in-mission recovery is mode-dependent (AUV commits to recovery on condition-clear, does not auto-resume; ROV holds and hands the continue-or-recover decision to the operator); and in-mission AMBER runtime-response (AMBER means action-required, not just informational, once a mission is underway — response branches by mode, AUV's autonomous curtailment logic left unspecified pending further design). **New "Parked Design Items" section** — auto-recovery (failsafe_monitor should attempt to re-establish the FC link itself before escalating) and a dedicated `string cause` field in `FailsafeStatus.msg` (replacing the `cockpit_bridge` message-substring shortcut) — both tracked as open implementation gaps against existing DIR-7/12 intent, not new decisions. Filename de-versioned as part of the 11 Jul doc restructure — this file moved into the repo `docs/` folder. | | 1.1 | 9 Jul 2026 | **DIR-1 corrected** — the *tether/HILT link*, not the power source, determines operating mode. A tethered vehicle may run on battery or topside supply. **DIR-7 expanded** — AUV `gate` vs ROV `advisory` health semantics; and a MUST that health assessment include flight-controller connectivity (a monitor with no FC input must never report GREEN). **DIR-9 superseded by DIR-9a** — recording is a single ARM-bounded black-box tier, not continuous-from-boot. **DIR-12 added** — vehicle health is distinct from autonomy health. | @@ -20,12 +21,16 @@ > ⚠ **Known implementation drift (updated 13 Jul 2026):** `recording_manager.py` still implements > the superseded DIR-9 (continuous-from-boot) model, NOT the governing DIR-9a — **still open.** > `failsafe_monitor`'s DIR-7 FC-connectivity MUST is **resolved** (11 Jul 2026, see DIR-7 below). -> The DIR-7 addendum "in-mission recovery is mode-dependent" is **essentially implemented** (13 -> Jul 2026 — `failsafe_monitor` now reads `health_role` and branches recovery accordingly, -> including the gate-mode arrival exit via the new `/rov/nav/safe_zone_reached` interface); -> remaining gap is the event's real publisher (navigation not yet built) — see the new "Parked -> Design Items" entry below. The AMBER runtime-response addendum, auto-recovery, and the -> dedicated `string cause` field remain **intent recorded, not implemented**. DIR-12's broader +> The DIR-7 "in-mission recovery is mode-dependent" addendum's **core trigger logic was corrected +> 13 Jul 2026** — the previous condition-clear-commits-to-recovery model was inverted and wrong +> (it produced a contradictory GREEN-while-in-`RETURN_TO_SAFE` state observed live); see the +> addendum below for the corrected count-based tier model. **`failsafe_monitor`'s current code +> (`2a3e577`) still implements the RETIRED, known-wrong condition-clear entry logic** — this is +> now a known implementation gap needing rework, not merely an unimplemented addendum, pending a +> dedicated next session. The safe-zone-reached arrival EXIT mechanism (`bf815cc`) remains +> correct and unaffected by this correction — only entry into committed recovery was wrong. The +> AMBER runtime-response addendum, auto-recovery, the dedicated `string cause` field, and the new +> adaptive restart-timing item all remain **intent recorded, not implemented**. DIR-12's broader > vehicle-health framing remains open beyond the FC-link piece (FD-headroom check on > `ardupilot_manager` not built). @@ -208,46 +213,111 @@ the state without opening another tool. --- -### DIR-7 addendum — In-mission recovery is mode-dependent (11 Jul 2026) +### DIR-7 addendum — In-mission recovery is mode-dependent (11 Jul 2026, **CORRECTED 13 Jul 2026**) **Source:** Grant, 11 Jul 2026 session. Extends the advisory-vs-gate framing above from the -pre-dive gate to the in-mission runtime case. +pre-dive gate to the in-mission runtime case. **Core trigger logic corrected 13 Jul 2026 (Grant) +— see callout immediately below.** -**Intent:** When a RED (or AMBER, see next addendum) condition triggers a return-to-safe / -hold-and-recover response **during a mission**, and the underlying condition later clears, -what happens next is mode-dependent — recovery is not one behaviour: +> ⚠ **CORRECTED 13 Jul 2026 (Grant).** The original text of this addendum stated that AUV gate +> mode **commits to the recovery action ON CONDITION-CLEAR.** That is inverted and wrong. It +> produced a contradictory state observed live: the failsafe assessment reporting GREEN (the +> fault cleared) while the FSM sat in `RETURN_TO_SAFE` (committed recovery) — a "green light, +> still returning to safe" state that should not be possible. **The corrected intent:** GREEN is +> unconditionally a **working state** — a fault that clears returns the vehicle to GREEN and the +> mission continues or resumes; a cleared condition must **never** trigger or commit a recovery. +> Committed recovery is triggered by a fault **persisting or recurring**, never by it clearing. +> The rewrite below is the corrected model, replacing the retired condition-clear wording — see +> "What survives / what is retired" near the end of this addendum for the implementation impact. -- **AUV (`gate`)** — commits to the recovery action on condition-clear. It does **not** - auto-resume the interrupted mission. Recovery, once committed, runs to completion (the - vehicle returns to / holds at the designated safe place per DIR-3); resuming the survey - itself is a fresh, deliberate mission start (DIR-10), never an automatic side-effect of - the condition going away. There is no operator to ask, so the vehicle must not guess that - "condition cleared" means "carry on as if nothing happened." -- **ROV (`advisory`)** — holds at AMBER/RED and hands the continue-or-recover decision to the - operator. The operator decides whether to accept recovery or override and continue, per - DIR-5's existing tethered intervention model. Matches DIR-5b: an operator override - continues the mission; it does not force a recovery the operator didn't ask for. +**Intent (corrected 13 Jul 2026):** Recovery response is governed by a **three-tier fault +model**, not by whether a condition has cleared: + +1. **Uncontrollable tier — out of scope for the FSM.** Loss of power, or any failure that + disables the safety logic itself, cannot be governed by a parameter inside the very system + that has just been disabled — there is no FSM response to "the thing running the FSM is + gone." This tier is adjacent to, and does not duplicate, the shelved DIR-6 Emergency Surface + last-resort concern above; it is noted here only so it is not mistaken for a gap in tiers 2/3 + below. +2. **Transient / self-resetting tier.** E.g. a comms blip, or a critical-sensor re-sync that can + restore on its own. The system **attempts to restore**; on success, it returns to **GREEN** + and the mission **continues or resumes** — a successful restore is not itself a reason to + recover. Each failure **increments a count**. Only once the failure count **exceeds a + configured acceptable number** does the FSM commit to `RETURN_TO_SAFE`. The count is a **raw + count of failures for the mission** — deliberately **no time window, no fixed duration** — + because time-window/duration-based logic will not survive changing startup periods and + mission lengths. (Time/duration-aware sophistication is parked separately — see "Adaptive + restart-timing" in Parked Design Items below — and depends on this raw-count mechanism + existing first.) +3. **Hard / persistent tier.** A RED condition that does **not** clear. Commits to + `RETURN_TO_SAFE` immediately, without waiting on a count — there is nothing to count against; + the fault is already known to be hard. + +**Mode-dependent role, same shape as the original addendum, now operating on the tier model +above rather than on condition-clear:** +- **AUV (`gate`)** — commits to `RETURN_TO_SAFE` when a fault crosses into tier 3 + (hard/persistent) or tier 2's failure count is exceeded — **never** merely because a condition + cleared. Once committed, recovery runs to completion (the vehicle returns to / holds at the + designated safe place per DIR-3); resuming the survey itself is a fresh, deliberate mission + start (DIR-10), never an automatic side-effect of anything clearing. There is no operator to + ask, so the vehicle must not guess that a transient success means "carry on as if nothing + happened" — tier 2 already handles that correctly, by returning to GREEN and resuming on a + *successful restore*, not on the fault merely being absent this instant. +- **ROV (`advisory`)** — holds during an active AMBER/RED condition and hands the + continue-or-recover decision to the operator. The operator decides whether to accept recovery + or override and continue, per DIR-5's existing tethered intervention model. Matches DIR-5b: an + operator override continues the mission; it does not force a recovery the operator didn't ask + for. + +**All thresholds are configuration-driven, not hardcoded:** the acceptable failure count (tier +2), and the classification of which specific faults are transient (tier 2) versus hard (tier 3), +are set in the setup wizard and read from the resolved mode profile the same way `health_role` +is — never hardcoded in `failsafe_monitor`. **Must:** - Derive the post-recovery behaviour from `health_role` (`gate`/`advisory`), never assume the - same generic "return to NORMAL" response is correct for both modes. -- AUV: treat mission resumption as a separate, deliberate action (DIR-10), never implicit in - condition-clear. + same generic response is correct for both modes. +- Trigger committed recovery on fault **persistence or recurrence** (tier 2 count exceeded, or + tier 3 hard fault) — **never** on condition-clear. +- On a successful transient restore (tier 2), return to GREEN and continue/resume the mission — + a successful restore is not a reason to recover. +- AUV: treat mission resumption as a separate, deliberate action (DIR-10), never implicit in a + restore or in reaching NORMAL. - ROV: surface the continue-or-recover choice explicitly; do not auto-decide on the operator's behalf. +- Keep all thresholds (acceptable failure count, transient-vs-hard fault classification) + configuration-driven via the mode profile, never hardcoded. -**Implementation note:** the FSM-level fix landed 11 Jul 2026 (commit `1b0050d`) made -`RETURN_TO_SAFE` and `HOLD_AND_RECOVER` both able to return to `NORMAL` on condition-clear — the -**mechanism**. It was initially **mode-blind** (`failsafe_monitor` did not yet read the mode -profile), so at that point it behaved the same way in both AUV and ROV. +**Must not:** +- Commit to, or remain committed to, recovery because a condition cleared. A cleared condition + is evidence the vehicle is fine, not evidence it needs recovering. +- Use a time window or fixed duration to decide whether a fault is "still happening" for the + purpose of this trigger — use the raw failure count (tier 2). Time/duration awareness is a + separate, later piece of sophistication (see "Adaptive restart-timing" Parked Design Item). -> ✅ **Made mode-aware 13 Jul 2026** (commit `2a3e577`): `failsafe_monitor` now subscribes to -> `/rov/mode/profile` and branches on `health_role` per this addendum — gate commits -> `HOLD_AND_RECOVER`→`RETURN_TO_SAFE` instead of returning to NORMAL; advisory holds for an -> explicit operator resume (placeholder topic). This surfaced a further gap — gate-mode -> `RETURN_TO_SAFE` had no exit — closed by the new mode-aware safe-zone-reached arrival event, -> commit `bf815cc`. See the new Parked Design Item below for the arrival-event design detail, -> and `docs/handover.md` §15f for the full fix narrative. +**What survives from the 11 Jul / 13 Jul implementation work, and what is retired (13 Jul +2026):** +- **Survives, correct:** `failsafe_monitor` subscribing to the resolved mode profile and reading + `health_role` (commit `2a3e577`'s mode-awareness mechanism) — this is the right way to know + which branch above applies, unchanged by this correction. +- **Survives, correct:** the safe-zone-reached arrival event and its permanent + `/rov/nav/safe_zone_reached` topic interface (commit `bf815cc`) — this remains the correct + means by which a **committed** `RETURN_TO_SAFE` recovery runs to completion and exits back to + `NORMAL` on arrival. Its role is **unchanged** by this correction: it completes a committed + recovery. Only the trigger for **entering** committed recovery was wrong — how a committed + recovery **exits**, once genuinely entered, is untouched and still correct. +- **Retired, known-wrong, pending rework:** the **condition-clear-commits-to-recovery entry + logic** — specifically, `2a3e577`'s gate-mode `HOLD_AND_RECOVER` → `RETURN_TO_SAFE` transition + on condition-clear (the `health_role == HEALTH_GATE` branch in + `failsafe_monitor._apply_failsafe_priority`'s "all clear" block), which `bf815cc` then built + its (correct) arrival exit on top of. The entry logic is now known-wrong per the correction + above and will be reworked next session into the tier-2 count-based persistence model + described here. Until reworked, treat that entry code path as implementing the retired + (wrong) intent, not this corrected one. + +> **Status:** Corrected 13 Jul 2026 (Grant). Design intent corrected; implementation rework +> (count-based tier-2 persistence trigger, config-driven thresholds) is a next-session task — +> `failsafe_monitor`'s current condition-clear entry logic is known-wrong in the meantime. --- @@ -488,6 +558,33 @@ one cut when navigation takes over publishing to the same permanent topic. > publisher (W1 button + `rov_api` endpoint) and the real navigation-raised event are both still > to come. +### Adaptive restart-timing (relates to the DIR-7 addendum's corrected tier-2 model; depends on the count-based retry machinery existing first) + +**Source:** Grant, 13 Jul 2026. + +Rather than a fixed restart timeout, the system should **monitor its own restore behaviour** — +capturing **restore count and restore duration** each time a fault is recovered — log it, and +**weigh future restart attempts against that observed history** rather than against a fixed +time. + +**Worked example:** On a failure, the system attempts a restart. If the restart succeeds, it +returns to GREEN and resumes (per the tier-2 model above), while in the background it **logs the +restore**, including count and duration. If the failure **recurs**, it may attempt restart +again — now **comparing against the previous attempt** — and logs the second failure. +Subsequent failures are then subject to the configured acceptable-count parameter (tier 2 +above). + +This item deliberately holds **all** the time-and-duration-based sophistication (rolling +windows, learned durations, weighing attempts against history) that was **kept out of** the +count-based correction above — the corrected DIR-7 addendum trigger is a raw count, on purpose, +precisely so it does not depend on this not-yet-built machinery. This item **depends on** the +count-based retry machinery existing first; it is not a substitute for it and cannot be built +ahead of it. + +> **Status:** Design-captured intent for a dedicated future session. **Not yet specified for +> build** — no algorithm, thresholds, or storage format decided here, only the shape of the +> problem and its dependency ordering. + --- ## Proposed build staging (REVISED to align with research)