docs(self-deploy): document the rpc-health canary gate probe (#4646) - #4651
Open
rysweet wants to merge 2 commits into
Open
docs(self-deploy): document the rpc-health canary gate probe (#4646)#4651rysweet wants to merge 2 commits into
rysweet wants to merge 2 commits into
Conversation
The rpc-health self-relaunch canary gate previously ran the non-dispatched `probe rpc` subcommand, which `dispatch_operator_cli` rejects as `unsupported command 'probe'`. It therefore reddened *every* self-deploy candidate regardless of daemon health, wedging the self-deploy loop behind a stuck target SHA (#4646). The code fix (#4639) repointed the probe at the real, read-only, dispatched `simard memory stats` subcommand (`RPC_HEALTH_PROBE_ARGS`), guarded by a socket-liveness pre-flight and fail-closed timeout/spawn/exit handling. This change records that resolution in the docs so the runbook and reference tree reflect current reality: - Add reference/rpc-health-canary-gate-probe.md — the probe contract, socket resolution (SIMARD_STATE_ROOT-driven), the liveness pre-flight that refuses to green a dead daemon, the fail-closed disposition table, and the regression guards that keep the argv pointed at a dispatched subcommand. - howto/converge-a-stuck-red-canary-self-deploy.md — add the "rpc-health reddens every candidate identically" special case pointing at the new ref. - reference/canary-gate-convergence.md + index.md — cross-link the new ref. - mkdocs.yml — add the new page to the nav (docs-integrity nav gate). Docs-only; PRD preserved; no Bridge naming; the gate path remains tracing/OTel-only with no print-family sinks. Verified: `cargo test --test docs_integrity` (nav + dead-link gates) and the full `self_relaunch::gates` suite are green, including the #4646 reproduction guard `rpc_health_probe_args_resolve_to_a_dispatched_subcommand`. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
) Refactor pass: collapse the run-on frontmatter `description` (a single 400+ char sentence) into a crisp summary. The body already carries the full probe contract, so no information is lost. Nav and cross-links are untouched; `cargo test --test docs_integrity` (nav + dead-link gates) stays green. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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.
Summary
Resolves #4646 (documentation of the fix). The
rpc-healthself-relaunch canary gate previously ran the non-dispatchedprobe rpcsubcommand, whichdispatch_operator_clirejects asunsupported command 'probe'. It therefore reddened every self-deploy candidate regardless of daemon health, wedging the self-deploy loop behind a stuck target SHA and lettingDeployDriftclimb.The code fix landed in #4639: the probe now runs the real, read-only, dispatched
simard memory statssubcommand (RPC_HEALTH_PROBE_ARGS), guarded by a socket-liveness pre-flight and fail-closed timeout/spawn/exit handling — a healthy relaunch passes while a dead or unreachable daemon still reddens. This PR records that resolution in the docs tree so the runbook and reference reflect current reality.Changes (docs-only)
docs/reference/rpc-health-canary-gate-probe.md— probe contract,SIMARD_STATE_ROOT-driven socket resolution, the liveness pre-flight that refuses to green a dead daemon, the fail-closed disposition table, and the regression guards that keep the argv pointed at a dispatched subcommand.docs/howto/converge-a-stuck-red-canary-self-deploy.md— adds the "rpc-healthreddens every candidate identically" special case pointing at the new reference.docs/reference/canary-gate-convergence.md+docs/index.md— cross-link the new reference.mkdocs.yml— adds the new page to nav (satisfies the docs-integrity nav gate).Constraints honored
Specs/ProductArchitecture.mduntouched).Bridgenaming; gate path remainstracing/OTel-only with noprint!/println!sinks.Verification
cargo test --test docs_integrity— nav-resolution + dead-link gates green.self_relaunch::gatessuite green (38 tests), including the Fix the self-relaunch rpc-health canary gate that deterministically refuses every Simard self-deploy. Root cause: the rpc-health canary gate invokes aprobesubcommand that the freshly-built candida #4646 reproduction guardrpc_health_probe_args_resolve_to_a_dispatched_subcommand.clippy --all-targets --all-features --locked) gates passed.Closes #4646
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com