Skip to content

docs: match the entity count, presence claim and capture tier to the code - #2536

Open
rudycelekli wants to merge 1 commit into
ruvnet:mainfrom
rudycelekli:docs/claims-match-the-tree
Open

rudycelekli wants to merge 1 commit into
ruvnet:mainfrom
rudycelekli:docs/claims-match-the-tree

Conversation

@rudycelekli

Copy link
Copy Markdown

Three headline claims disagree with the tree. All three are the shape AGENTS.md already legislates for — "do not copy volatile counts into documentation", and the MEASURED / CLAIMED / SYNTHETIC vocabulary — so this extends the existing honest-labelling discipline (ADR-187) rather than introducing a new one.

1. Entity count: 21 → 15

README.md:39 said "Ships 21 entities per node (11 raw signals + 10 inferred semantic states: … meeting-in-progress, bathroom-occupied, … bed-exit, … multi-room-transition)".

DiscoveryBuilder::enabled_entities declares 21 kinds and then filters out every kind without a server source. The crate's own tests pin the result:

  • mqtt/discovery.rs:606 — assert_eq!(entities.len(), 15);
  • unsourced_entities_are_never_announced — asserts ZoneOccupancy, BathroomOccupied, BedExit, MultiRoomTransition, MeetingInProgress, PoseKeypoints are never announced, with the comment "HA discovery announces entities that never receive state #2085: announcing these left them 'unknown' in HA forever."

Four of those six were in the README's list of ten. docs/integrations/home-assistant.md already says 15 entities (9 raw + 6 semantic) and even explains the gap at :406 ("not announced yet (zones, bathroom, bed exit, meeting)"). So the README was the only place still carrying 21.

Now 15 (9 raw + 6 semantic), with the four unsourced entries removed. README, discovery.rs and the HA doc agree.

2. Presence: separate the encoder metric from the head's status

README.md:338 filed presence under Real & validated / MEASURED / published with "Presence = 82.3% held-out temporal-triplet accuracy … the pose/presence numbers the project stands behind today", and docs/user-guide.md:1465 carried ✅ with the same number.

Two things are conflated there. The 82.3% is heldout_triplet_acc — an embedding-quality metric, not a presence decision rate. And the published head on top of that encoder is degenerate: bias 8.19 exceeds weight norm 3.67, so on L2-normalised embeddings every logit lands in [4.52, 11.86], p(present) ≥ 0.989 for every input, and absent is unreachable (#1521).

This is not a new assertion — the repo already states it. v2/crates/wifi-densepose-train/src/model_gates.rs:9 documents "logit positive (8.19 − 3.67 = 4.52 > 0), so predicted presence probability is ≥ ~0.989 for every valid input", ADR-298 is Accepted, and the gate's tests are named for the issue. I ran them at ce8d296c:

cargo test -p wifi-densepose-train --no-default-features model_gates
test model_gates::tests::issue_1521_norm_and_bias_match_the_review ... ok
test model_gates::tests::issue_1521_fails_unreachable_boundary ... ok
test model_gates::tests::issue_1521_fails_constant_output ... ok
test model_gates::tests::issue_1521_aggregate_fails_boundary_and_constant ... ok
test result: ok. 13 passed; 0 failed

So the encoder number stays and is labelled as what it measures; the head's status is stated. The artifact itself lives in the HF repo and is not changed here.

3. Capture tier

docs/user-guide.md prescribes --edge-tier 2 in the provisioning example with no note that tier 2 replaces raw CSI with on-node derived values, while the room-learning CLI requires tier 0:

  • v2/crates/wifi-densepose-cli/src/room.rs:4 — "requires edge_tier=0 raw CSI"
  • room.rs:73 — "raw CSI; provision with --edge-tier 0"
  • ADR-061 lists edge_tier=0 as "Raw CSI passthrough (no DSP)"

Added a short note saying which tier to provision for capture/training versus on-node vitals. (The NVS table's documented default of 0 is correct and unchanged — the gap was only in the worked example.)

Validation

Docs only; no code paths touched. I verified every cited path and ADR resolves, and that the three entity figures now agree. No markdown gate exists in .github/workflows/, so there is nothing further to run — I am not claiming a test proves a documentation change.

Happy to split this into three PRs if you would rather review them separately.

…code

Three headline claims disagree with the tree.

Entity count. README said 21 entities per node and listed
meeting-in-progress, bathroom-occupied, bed-exit and multi-room-transition
among them. DiscoveryBuilder::enabled_entities filters out every kind
without a server source, and mqtt/discovery.rs asserts the result is 15;
the sibling test unsourced_entities_are_never_announced asserts those
four are never announced (ruvnet#2085 — announcing them left them "unknown" in
HA forever). docs/integrations/home-assistant.md already says 15 (9 raw
+ 6 semantic). Use 15 and drop the four unsourced entries.

Presence. The 82.3% figure is held-out temporal-triplet accuracy, an
embedding-quality metric, and was filed as the presence number under
"Real & validated / MEASURED". The published head on top of that encoder
is degenerate: bias 8.19 exceeds weight norm 3.67, so on L2-normalised
embeddings every logit lands in [4.52, 11.86] and `absent` is
unreachable (ruvnet#1521). model_gates.rs documents the same arithmetic and
the ADR-298 gate rejects the head. Keep the encoder number, label it as
embedding quality, and state the head's status.

Capture tier. The provisioning example prescribes --edge-tier 2 with no
note that tier 2 replaces raw CSI with on-node derived values, while the
room-learning CLI requires edge_tier=0 (room.rs:4, :73; ADR-061 lists
tier 0 as raw CSI passthrough). Say which tier to use for capture.

Docs only.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant