Iter 48. Ships the production-recommended operator example: full
lifecycle through the worker-thread handle. Companion to iter-47's
minimal example which uses BfldPipeline::process directly. The
handle example demonstrates the multi-thread pattern operators
actually deploy with HA + MQTT.
Lifecycle demonstrated in the example:
1. publish_availability_online (retained → HA marks device online)
2. publish_discovery (retained → HA auto-creates 6 BFLD entities)
3. BfldPipelineHandle::spawn (worker owns gate + ring + hasher)
4. handle.send(input) per BFI frame (worker process + publish)
5. handle.shutdown() (clean worker join)
6. publish_availability_offline (explicit graceful disconnect)
Example output (verified pre-commit):
bootstrap: 1 availability + 6 discovery payloads
total messages published: 33
first three topics:
ruview/seed-handle-demo/bfld/availability
homeassistant/binary_sensor/seed-handle-demo_bfld_presence/config
homeassistant/sensor/seed-handle-demo_bfld_motion/config
last three topics:
ruview/seed-handle-demo/bfld/confidence/state
ruview/seed-handle-demo/bfld/identity_risk/state
ruview/seed-handle-demo/bfld/availability
Added:
- v2/crates/wifi-densepose-bfld/examples/bfld_handle.rs (~110 LOC):
* Documents the 6-phase lifecycle with inline comments
* Pointer to RumqttPublisher::connect_with_lwt for prod use
* 5 sensing frames × 5 state topics = 25 per-frame messages
- v2/crates/wifi-densepose-bfld/tests/example_handle.rs (4 named tests):
handle_example_documents_full_lifecycle_phases
(doc drift guard: 8 operator-facing symbols must appear)
handle_example_carries_run_instructions_and_prod_pointer
(cargo run line + RumqttPublisher pointer present)
handle_example_lifecycle_produces_expected_message_counts
*** Re-executes full lifecycle inline; asserts total == 33,
first message payload == "online", last == "offline" ***
handle_example_returns_box_dyn_error_for_main_signature
- v2/crates/wifi-densepose-bfld/Cargo.toml:
[[example]] name = "bfld_handle", required-features = ["std"]
ADR-124 status (iter step 0 sibling check):
- docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md unchanged
at 431 lines. SENSE-BRIDGE scope remains orthogonal.
ACs progressed:
- ADR-118 §2.1 documentation surface — two runnable operator examples
now shipped (iter 47 minimal, iter 48 worker-thread). Together
they cover the two operator patterns: simple in-process consumer
(process + to_json) and the full HA-integration deployment
(handle + bootstrap + lifecycle).
- ADR-122 §2.1 + §2.2 + §2.6 — the worker example exercises every
layer of the HA-DISCO publish chain in one runnable file:
availability, discovery, state, graceful shutdown.
Test config:
- cargo test --no-default-features → 101 passed (example_handle cfg-out)
- cargo test → 319 passed (315 + 4)
Out of scope (next iter target):
- PR-readiness pivot still pending. External-resource-gated work
(KIT BFId, Pi5/Nexmon) still skipped.
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 47. Ships the operator-facing quickstart as doc-as-code. Three
goals:
1. New operators reading the crate get a 50-line working example
instead of having to assemble pipeline + config + hasher + inputs
+ embedding + JSON publish themselves.
2. CI proves the example COMPILES and RUNS end-to-end via a
separate test that re-executes the same flow inline.
3. The example output is the canonical BfldEvent JSON, demonstrating
every documented field (presence/motion/count/conf/zone/class/
identity_risk_score/rf_signature_hash) for a typical Anonymous
class publish.
Added:
- v2/crates/wifi-densepose-bfld/examples/bfld_minimal.rs (~70 LOC):
* Per-site secret salt
* BfldPipeline::new(BfldConfig::new(...).with_signature_hasher(...))
* SensingInputs with low-risk factors so the gate emits
* IdentityEmbedding from a deterministic ramp
* pipeline.process(...).ok_or(...) for the gate-drop case
* event.to_json() printed to stdout
* Run command in the doc comment:
cargo run -p wifi-densepose-bfld --example bfld_minimal
- v2/crates/wifi-densepose-bfld/tests/example_minimal.rs (4 tests):
minimal_example_documents_the_operator_quickstart_flow
(asserts file contains BfldPipeline, SignatureHasher,
SensingInputs, IdentityEmbedding, BfldConfig, .process(,
to_json — catches doc drift if the example removes a key
symbol)
minimal_example_carries_run_instructions_in_doc_comments
(the cargo run --example line must be present)
minimal_example_flow_produces_valid_json_with_documented_fields
*** Re-runs the example flow inline and asserts every
documented JSON field appears in the output ***
example_returns_box_dyn_error_for_main_signature
(canonical Rust-example main signature)
- v2/crates/wifi-densepose-bfld/Cargo.toml:
[[example]] name = "bfld_minimal", required-features = ["serde-json"]
so `cargo test --no-default-features` doesn't try to build the
example (which needs to_json gated on serde-json).
Example run output (sanity check before commit):
{"type":"bfld_update","node_id":"seed-example","timestamp_ns":...,
"presence":true,"motion":0.42,"person_count":1,"confidence":0.91,
"privacy_class":"anonymous","identity_risk_score":0.0016000001,
"rf_signature_hash":"blake3:cc3615c7aaab9d0867a0c15327444b8f...bf"}
ADR-124 status (iter step 0 sibling check):
- docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md unchanged
at 431 lines. SENSE-BRIDGE scope remains orthogonal.
ACs progressed:
- ADR-118 §2.1 documentation surface — first operator-facing example
shipped as part of the crate. Discoverable via
`cargo run --example bfld_minimal` and verified via cargo test.
Test config:
- cargo test --no-default-features → 101 passed (example_minimal cfg-out)
- cargo test → 315 passed (311 + 4 example_minimal)
Out of scope (next iter target):
- PR-readiness pivot still pending: CHANGELOG, witness bundle,
AC closeout table. External-resource-gated work still skipped.
Co-Authored-By: claude-flow <ruv@ruv.net>
ruv