docs: calibration guide + trust/engine-error diagnostics (closes #1456) - #1457
Merged
Conversation
Closes the two documentation gaps from #1456 (follow-up to #1401): - docs/calibration-guide.md: what calibrate/enroll/train-room actually enforce, grounded in v2/crates/wifi-densepose-calibration and wifi-densepose-cli source (not just ADR-135/151 aspirational prose). Covers the hard 600-frame baseline minimum, per-anchor quality gate thresholds, the unsolved pet/small-motion presence-detection gap, and what the empty-room baseline capture actually needs (steady vs silent). Flags that ADR-135's drift_score/BaselineDrift staleness system is not implemented in code — only bank.rs's baseline_id STALE check is real. - docs/trust-and-engine-errors.md: exact trigger conditions for engine_error_count vs the separate, non-sticky `demoted` privacy-class flag, where both are exposed (/health/ready and /api/v1/status share a handler), the real diagnostic gap (no per-cause breakdown, log line is the closest thing), the WDP_GUARD_INTERVAL_US recovery path for persistent clock-drift demotion, and an honest "no code path found" answer on whether a converted HuggingFace model explains engine errors. Also adds both docs to the README documentation table. No code changes.
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
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
Closes #1456 (follow-up documentation gap tracked from #1401). Two new operator-facing docs, both grounded in the actual Rust source (not ADR aspirational prose) — every specific number/threshold below is cited with a file:line and was spot-checked against source before this PR was opened.
docs/calibration-guide.mdDEFAULT_MIN_FRAMES,wifi-densepose-signal/src/ruvsense/calibration.rs:48) —calibratefails outright below it, it doesn't degrade silently.enroll(AnchorQualityGate), and thattrain-roomonly requires a non-empty anchor list — a partial anchor set silently produces a bank missing whichever specialists lacked their prerequisite anchors.PresenceSpecialisthas no size/species discrimination at all, purely amplitude-variance/mean-shift thresholding. Documented as an open limitation, not glossed over.drift_score/BaselineDriftstaleness system does not exist in the actual code — only a cruderbaseline_id-mismatch check inbank.rsis real.docs/trust-and-engine-errors.mdengine_error_countand the separate, non-stickydemotedflag to their exact trigger conditions inengine_bridge.rs/wifi-densepose-engine./health/readyand/api/v1/statusshare a handler and expose atrustblock, but plainly states the real diagnostic gap: no per-cause error breakdown is exposed over the API — the rate-limited log line is the closest thing today.WDP_GUARD_INTERVAL_US, from issue Make multistatic guard_interval_us configurable (hardcoded 5000 µs causes permanent trust demotion with 2 ESP32-S3 nodes) #1049) and thatengine_error_counthas no reset besides a process restart.--convert-modeland the engine/trust cycle are separate code paths with no call-through found — no invented causal link.Both docs are added to the README documentation table.
Test plan
git status/diff that nothing outsidedocs/andREADME.mdwas touched.DEFAULT_MIN_FRAMES = 600,engine_error_countincrement/no-reset,WDP_GUARD_INTERVAL_US,demote_one/self.demoted = trust.demoted) directly against source before opening this PR.🤖 Generated with Claude Code
Co-Authored-By: claude-flow ruv@ruv.net