docs: describe fm-guard beacon-only predicate and its blind window - #865
Open
ManveerBhullar wants to merge 1 commit into
Open
docs: describe fm-guard beacon-only predicate and its blind window#865ManveerBhullar wants to merge 1 commit into
ManveerBhullar wants to merge 1 commit into
Conversation
docs/architecture.md overstated the pull-based guard as warning when the watcher 'stops running'; it actually keys off the beacon mtime and never inspects the watcher lock, so a dead watcher with a fresh beacon stays silent for up to FM_GUARD_GRACE. Restate the predicate precisely and note the bounded blind window, with the push-based turn-end guard as the identity-matched live-lock backstop. Add a regression test pinning the beacon-only predicate so the retained split cannot silently regress.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Corrects documentation that overstated the pull-based supervision guard's predicate, and adds a regression test pinning the retained behavior. No runtime change.
Why
docs/architecture.mdclaimedfm-guard.shwarns when "that watcher stops running". It does not:fm-guard.shkeys solely off the liveness beacon mtime (state/.last-watcher-beatwithinFM_GUARD_GRACE, 300s) and never inspects the watcher lock. So a watcher that has died while its beacon is still fresh stays silent for up toFM_GUARD_GRACE— a bounded blind window. The strict identity-matched live-lock backstop (fm-turnend-guard.sh) is what catches that case at the next turn end.This split is intentional and retained (per the supervision-tooling-contract-audit): the cheap pull-based beacon guard and the strict push-based turn-end guard are complementary. This change keeps the predicate exactly as-is and only makes the prose precise.
Changes
docs/architecture.md: restatefm-guard.sh's predicate as beacon-staleness, name the bounded blind window, and point to the push-based turn-end guard as the identity-matched live-lock backstop. The lib header (fm-supervision-lib.sh), script header, anddocs/turnend-guard.mdwere already accurate; only this architecture prose was loose.tests/fm-guard-stale-banner.test.sh: addtest_fresh_beacon_silent_with_dead_lock, pinning the beacon-only predicate —fm-guard.shstays silent on a fresh beacon even with a dead watcher lock present. If the guard is ever strengthened to callfm_watcher_healthy, this test fails, surfacing the divergence as intentional.Scope
No behavior, watcher timing, locks, runtime code, or unrelated docs are touched. The strict complementary behavior is already covered by
test_hook_blocks_when_dead_lock_has_fresh_beaconinfm-turnend-guard.test.sh.Verification
bin/fm-test-run.sh tests/fm-guard-stale-banner.test.sh— all pass (incl. new test)bin/fm-test-run.sh tests/fm-turnend-guard.test.sh— all passShipped via direct-PR (no-mistakes pipeline agent unavailable).