mirror of
https://github.com/ruvnet/RuView
synced 2026-06-09 10:13:17 +00:00
23fe8012e0e2f5c089df26ea381bd60438a11ac4
690 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 ruv
|
23fe8012e0 |
feat(adr-118/p5.3): RumqttPublisher behind mqtt feature gate (176/176 GREEN with mqtt)
Iter 23. Production Publish trait impl using rumqttc 0.24 (same crate
version + use-rustls feature pinning as wifi-densepose-sensing-server,
so both publishers can share broker connection posture).
Added:
- rumqttc = "0.24" optional dep (default-features = false, use-rustls)
- New `mqtt` cargo feature: ["std", "dep:rumqttc"]
- src/rumqttc_publisher.rs (gated on `feature = "mqtt"`):
* RumqttPublisher wrapping rumqttc::Client + QoS + retain flag
* RumqttPublisher::new(client, qos) const constructor
* with_retain(bool) builder for availability-style topics
* RumqttPublisher::connect(opts, capacity) -> (Self, Connection)
Returns the unpumped Connection — caller spawns a thread that
iterates connection.iter() to drive the MQTT protocol. Default
QoS is AtLeastOnce (HA-DISCO recommendation for state topics).
* impl Publish with Error = rumqttc::ClientError
- pub use RumqttPublisher from lib.rs
tests/rumqttc_publisher_smoke.rs (7 named tests, all green, gated on mqtt):
rumqttc_publisher_constructs_without_broker
(uses 127.0.0.1:1 — reserved port refuses immediately; no hang)
with_retain_builder_yields_a_publisher
publish_queues_message_without_blocking_on_broker_state
*** Critical property: rumqttc's sync Client::publish queues into
an unbounded channel; publish_event returns Ok without round-
tripping to the (offline) broker. The queued packet only sends
if a thread iterates Connection::iter(). ***
restricted_event_publishes_four_messages_through_rumqttc
(class 3 + no zone: presence/motion/count/confidence — 4 topics)
publisher_trait_object_is_constructible
(Box<dyn Publish<Error = rumqttc::ClientError>> works)
direct_publish_call_through_trait_object
default_qos_is_at_least_once_via_connect
ACs progressed:
- ADR-122 §2.2 broker integration — production publisher now wired,
matching the sensing-server's TLS / version posture. The two
crates can share a single broker connection if an operator wants
both publishers in the same process.
- ADR-122 AC4 still enforced — publish_event's class-gated routing
is upstream of rumqttc, so no broker-level config can leak Raw frames.
Test config:
- cargo test --no-default-features → 72 passed (mqtt feature off)
- cargo test → 169 passed (mqtt feature off)
- cargo test --features mqtt --test rumqttc_publisher_smoke → 7 passed
- With --features mqtt: 169 + 7 = 176 total
Out of scope (next iter target):
- mosquitto integration test (env-gated MQTT_BROKER=tcp://localhost:1883):
* spawn a thread iterating Connection::iter()
* publish a BfldEvent
* subscribe in the test, await SubAck per the workspace memory note
`feedback_mqtt_integration_test_patterns`
* assert the topics received match render_events output
- BfldPipelineHandle: Arc<Mutex<BfldPipeline>> with a thread that pumps
inbound (inputs, embedding) → process → publish_event(&rumqttc_pub, &event)
for a single-call "set up MQTT publisher and walk away" API.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
0cb037c007 |
feat(adr-118/p5.2): Publish trait + publish_event free function — 169/169 GREEN
Iter 22. Abstracts the MQTT publish boundary without pulling in tokio or
rumqttc yet. The trait is sync (callers can hold &mut self without an
async runtime); the production rumqttc-backed impl in iter 23 will drive
a tokio task internally and present the same sync surface here.
Added (in src/mqtt_topics.rs, gated on `feature = "std"`):
- Publish trait with associated Error type
- CapturePublisher (Vec-backed; default-constructible) for unit tests
- publish_event<P: Publish>(publisher, event) -> Result<usize, P::Error>
Iterates render_events(event) and forwards each TopicMessage to
publisher.publish(). Returns the count actually published, or the
publisher's error short-circuited on first failure.
- pub use Publish, CapturePublisher, publish_event from lib.rs
tests/mqtt_publish_loop.rs (7 named tests, all green):
capture_publisher_records_every_message
publish_returns_zero_for_raw_and_derived_events
(parameterized — class 0 and class 1 both produce zero publishes,
reinforcing the invariant I1 surface enforcement from iter 21)
published_topics_match_render_events_ordering
(stable per-event topic sequence for MQTT consumers)
restricted_class_publishes_no_identity_risk_topic
anonymous_without_zone_publishes_five_messages (5 = no zone_activity)
publisher_error_short_circuits_publish_event
(FailingPublisher fails on 3rd publish; publish_event surfaces the
error AND leaves the first two messages durably published)
capture_publisher_error_type_is_infallible
(compile-time witness that CapturePublisher cannot panic the loop)
ACs progressed:
- ADR-122 §2.2 publisher boundary — the broker-facing surface is now a
named trait operators can mock, swap, or wrap with retries.
- ADR-122 AC4 — publish_event respects the iter-21 class gating; Raw /
Derived events produce zero broker traffic by definition.
- ADR-118 invariant I1 — even if the broker connection somehow regressed,
the trait-level publish_event cannot exfiltrate a Raw frame because
render_events returns empty first.
Test config:
- cargo test --no-default-features → 72 passed (mqtt_publish_loop cfg-out)
- cargo test → 169 passed (162 + 7)
Out of scope (next iter target):
- New `mqtt` feature gate; tokio + rumqttc deps under it
- RumqttPublisher: impl Publish that holds an MqttClient + a small tokio
block_on or oneshot send to bridge sync trait to async client
- Optional: BfldPipelineHandle that owns Arc<Mutex<BfldPipeline>> + a
spawn-and-forget tokio task pumping inbound (inputs, embedding) →
process → publish_event(&rumqtt_pub, &event)
- mosquitto integration test following the patterns from
feedback_mqtt_integration_test_patterns memory note
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
f674efff9d |
feat(adr-118/p5.1): MQTT topic router (BfldEvent → Vec<TopicMessage>) — 162/162 GREEN
Iter 21. Lands ADR-122 §2.2 topic shape + class-gated routing as a pure
function. No broker dep yet — that lands in iter 22 with tokio + rumqttc
behind an `mqtt` feature. This iter is the routing policy, separated for
testability.
Added (gated on `feature = "std"`):
- src/mqtt_topics.rs:
* TopicMessage { topic: String, payload: String }
* TopicMessage::ruview_topic(node, entity) builds the canonical
`ruview/<node>/bfld/<entity>/state` shape
* render_events(&BfldEvent) -> Vec<TopicMessage>:
class < Anonymous (0/1): returns empty (raw/derived are local only)
class >= Anonymous (2/3): emits presence + motion + person_count +
confidence, plus zone_activity if zone_id set
class == Anonymous (2) ONLY: also emits identity_risk
class == Restricted (3): identity_risk is suppressed even with score
- pub use render_events, TopicMessage from lib.rs
Payload encoding:
- presence: "true" | "false"
- motion: "{:.6}" — fixed-precision decimal in [0.0, 1.0]
- person_count: bare integer string
- confidence: "{:.6}"
- zone_activity: JSON-string with quotes — "\"living_room\""
- identity_risk: "{:.6}"
tests/mqtt_topic_routing.rs (10 named tests, all green):
topic_format_is_ruview_node_bfld_entity_state
anonymous_class_publishes_six_topics_with_zone
(6 = presence/motion/count/conf/zone/identity_risk)
anonymous_class_without_zone_omits_zone_activity_topic (5 topics)
restricted_class_omits_identity_risk_topic (class 3 → 5 topics, no risk)
raw_and_derived_classes_publish_nothing
*** structural enforcement of "raw stays local" at the topic layer ***
presence_payload_is_lowercase_json_bool
motion_payload_is_fixed_precision_decimal
person_count_payload_is_bare_integer
zone_payload_is_json_string_with_quotes
identity_risk_payload_is_fixed_precision_decimal
ACs progressed:
- ADR-122 §2.2 topic shape now matches the documented format byte-for-byte.
- ADR-122 AC4 — per-class topic gating: classes 2 / 3 publish disjoint
sets, with identity_risk uniquely guarded.
- ADR-118 invariant I1 reaching the public surface — Raw frames produce
zero topic messages, so even a buggy publisher loop cannot leak them.
Test config:
- cargo test --no-default-features → 72 passed (mqtt_topics cfg-out)
- cargo test → 162 passed (152 + 10)
Out of scope (next iter target):
- tokio + rumqttc behind a new `mqtt` feature gate
- BfldPipelineHandle: Arc<Mutex<BfldPipeline>> + a tokio task that pumps
inbound SensingInputs, runs render_events on each emitted BfldEvent,
and calls client.publish() for each TopicMessage
- mosquitto integration test pattern (cf. feedback_mqtt_integration_test_patterns
memory: per-test client_id, pump until SubAck, wait for publisher discovery)
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
24f63466c1 |
feat(adr-118/p4.6): BfldPipeline::process_to_frame wire-bytes path (152/152 GREEN)
Iter 20. Adds the wire-bytes companion to BfldPipeline::process so
callers needing BfldFrame (for ESP-NOW, UDP, file dump, witness
bundles, etc.) don't have to drop down to BfldEmitter + manual
BfldFrame construction.
Added (in src/pipeline.rs):
- BfldPipeline::process_to_frame(
inputs: SensingInputs,
header_template: BfldFrameHeader,
payload: BfldPayload,
embedding: Option<IdentityEmbedding>,
) -> Option<BfldFrame>
Algorithm:
1. Cache timestamp_ns from inputs (consumed by the inner process()).
2. Call self.process(inputs, embedding) — gate logic decides drop/emit.
Returns None if the gate rejects, propagating to caller.
3. Clone header_template, override timestamp_ns and privacy_class from
the current pipeline state (privacy_mode-aware).
4. Build via BfldFrame::from_payload — CRC covers the section-prefixed
payload bytes per ADR-119 §2.2.
Separation of concerns: pipeline owns gate / ring / hasher state; caller
owns AP / STA / session identity (provided via header_template).
tests/pipeline_to_frame.rs (6 named tests, all green):
process_to_frame_emits_frame_under_low_risk
(timestamp_ns + privacy_class correctly propagated from pipeline)
process_to_frame_returns_none_under_sustained_high_risk
(gate Reject path: two consecutive high-risk calls → None)
process_to_frame_round_trips_through_bytes
(frame.to_bytes() → BfldFrame::from_bytes() → parse_payload() identity)
process_to_frame_overrides_class_in_privacy_mode
(enable_privacy_mode → frame.header.privacy_class = Restricted byte)
process_to_frame_preserves_header_template_identity_fields
(ap_hash, sta_hash, session_id, channel from template survive)
process_to_frame_uses_input_timestamp_not_template_timestamp
(template.timestamp_ns = 12345 is overridden by inputs.timestamp_ns)
ACs progressed:
- ADR-118 §2.1 wire-bytes consumer path now reachable from BfldPipeline,
not just from low-level BfldEmitter + manual frame construction.
- ADR-119 AC5/AC6 — round-trip-through-bytes test exercises the full
pipeline+frame stack, not just the frame in isolation.
- ADR-122 §2.2 prep — the BfldFrame is the wire format MQTT eventually
publishes via tokio loop (next iter pair); process_to_frame is the
per-frame producer that loop will call.
Test config:
- cargo test --no-default-features → 72 passed (pipeline_to_frame cfg-out)
- cargo test → 152 passed (146 + 6)
Out of scope (next iter target):
- BfldPipelineHandle: Arc<Mutex<BfldPipeline>> + tokio task that pumps
an inbound (SensingInputs, IdentityEmbedding) channel into MQTT
per-class topics (ADR-122 §2.2). Brings in tokio + rumqttc deps
behind a `mqtt` feature.
- Cargo benchmark: pipeline throughput target ≥ 40 frames/sec on a
Pi 5 core (ADR-118 §6 P2 effort estimate).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
ac461f94fc |
feat(adr-118/p4.5): BfldPipeline facade + BfldConfig (146/146 GREEN)
Iter 19. Public lib.rs entry point per ADR-118 §2.1. Thin facade over
BfldEmitter that adds a config-driven builder and a privacy_mode
toggle for emergency demote-to-Restricted without rebuilding the
gate/ring/hasher state.
Added (gated on `feature = "std"`):
- src/pipeline.rs:
* BfldConfig { node_id, default_zone_id, privacy_class, signature_hasher }
with new/with_zone/with_privacy_class/with_signature_hasher builder
* BfldPipeline { baseline_class, privacy_mode, emitter }
* BfldPipeline::new(config) — initializes the underlying emitter
* process(inputs, embedding) -> Option<BfldEvent>
Delegates to emitter.emit() then post-processes: if privacy_mode is
engaged, demotes the resulting event to Restricted and calls
apply_privacy_gating to strip identity fields
* enable_privacy_mode() / disable_privacy_mode() / is_privacy_mode_enabled()
* current_privacy_class() — returns Restricted when privacy_mode else baseline
* current_gate_action() — delegate diagnostic
- pub use BfldConfig, BfldPipeline from lib.rs
Design note: the privacy_mode override is applied post-emission, NOT by
rebuilding the emitter. This preserves gate state (current action,
pending transitions), ring contents, and hasher salt across the toggle —
critical for incident response where the operator needs to keep
detecting anomalies while temporarily redacting the public surface.
tests/pipeline_facade.rs (9 named tests, all green):
config_defaults_to_anonymous_no_zone_no_hasher
config_builder_methods_chain
fresh_pipeline_is_not_in_privacy_mode
pipeline_process_returns_anonymous_event_under_low_risk
enable_privacy_mode_demotes_published_events_to_restricted
(verifies BOTH identity_risk_score AND rf_signature_hash become None)
disable_privacy_mode_restores_baseline_class
(round-trip: enable → demoted → disable → restored to Anonymous)
privacy_mode_overrides_derived_baseline_too
(research-mode operator can still flip the emergency switch)
pipeline_with_hasher_emits_derived_rf_signature_hash
zone_is_threaded_from_config_to_event
ACs progressed:
- ADR-118 §2.1 — public entry point now matches the implementation
plan §1.2 sketch: BfldPipeline::new(config) → process() → BfldEvent.
Future iters add process_to_frame() and the tokio MQTT loop.
- ADR-118 §1.5 enable_privacy_mode requirement — operator can engage
Restricted-class redaction without restarting the pipeline or
losing in-flight detection state. First runtime witness of this.
Test config:
- cargo test --no-default-features → 72 passed (pipeline cfg-out)
- cargo test → 146 passed (137 + 9)
Out of scope (next iter target):
- process_to_frame(inputs, payload, embedding) -> Option<BfldFrame>
for callers that need wire-format bytes rather than JSON events.
- BfldPipelineHandle wrapping the pipeline in Arc<Mutex<...>> + a
tokio task that pumps an MQTT loop (ADR-122 §2.2 emitter half).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
ea98ceb335 |
feat(adr-118/p3.6): IdentityFeatures canonical-bytes encoder (137/137 GREEN)
Iter 18. Consolidates the embedding-vs-risk-factor hashing-input
selection behind a single typed API. Replaces the two ad-hoc paths
that lived in emitter.rs through iter 17:
* inline `emb.as_slice().iter().flat_map(|f| f.to_le_bytes())`
* private `canonical_risk_bytes(&inputs) -> [u8; 16]`
Added (gated on `feature = "std"`):
- src/identity_features.rs:
* IdentityFeatures<'a> enum: Embedding(&'a IdentityEmbedding) |
RiskFactors { sep, stab, consist, conf }
* from_embedding / from_risk_factors const constructors
* canonical_byte_len() const fn — no allocation, predicts wire length
* write_canonical_bytes(&mut Vec<u8>) — reusable-buffer path
* canonical_bytes() -> Vec<u8> — allocating convenience
* compute_hash(&SignatureHasher, day_epoch) -> [u8; 32]
* RISK_FACTOR_BYTES const (= 16)
- pub use IdentityFeatures, RISK_FACTOR_BYTES from lib.rs
Refactor:
- src/emitter.rs: derived_hash now uses
let features = match &embedding {
Some(emb) => IdentityFeatures::from_embedding(emb),
None => IdentityFeatures::from_risk_factors(sep, stab, consist, conf),
};
features.compute_hash(h, day_epoch)
Local canonical_risk_bytes helper removed (superseded).
tests/identity_features_encoder.rs (9 named tests, all green):
embedding_canonical_length_is_dim_times_four
risk_factor_canonical_length_is_sixteen_bytes
embedding_canonical_bytes_match_manual_flatten
risk_factor_canonical_bytes_match_explicit_le_layout
write_canonical_bytes_appends_to_existing_buffer
compute_hash_matches_direct_hasher_invocation
embedding_and_risk_factors_produce_different_hashes
iter_16_wire_compat_embedding_path *** backward-compat regression ***
iter_16_wire_compat_risk_factor_path *** backward-compat regression ***
These two tests assert that the refactored encoder produces
bit-identical hashes to iter 16's inline path. Existing deployed
nodes upgrading to iter 18 see no rf_signature_hash flip.
ACs progressed:
- ADR-120 §2.3 — features canonical-bytes representation now has a
single source of truth in the codebase; future feature additions
pass through one named encoder rather than scattered byte-fiddling.
- ADR-118 invariant I2 — IdentityFeatures borrows &IdentityEmbedding,
it doesn't take ownership. The embedding's Drop / no-Serialize
guarantees continue to hold across the canonical-bytes path.
Test config:
- cargo test --no-default-features → 72 passed (identity_features cfg-out)
- cargo test → 137 passed (128 + 9)
Out of scope (next iter target):
- Wire IdentityFeatures into a public emitter input path so callers
can supply pre-constructed IdentityFeatures rather than the bare
embedding + risk factors. (Soft refactor; current API is sufficient.)
- BfldPipeline facade — single struct combining BfldEmitter +
BfldFrame producer + MQTT publisher (ADR-118 §2.1 lib.rs entry point).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
29f23cb97e |
feat(adr-118/p4.4): rf_signature_hash JSON as "blake3:<hex>" (128/128 GREEN)
Iter 17. Lands the BFLD JSON wire spec format for rf_signature_hash —
a "blake3:" prefix followed by 64 lowercase hex chars. Replaces the
default serde array-of-integers encoding which was unusable for
downstream consumers (HA, Matter, MQTT).
Added (in src/event.rs):
- ser_rf_signature_hash<S>(hash: &Option<[u8;32]>, s) custom serializer
- Field attribute on BfldEvent.rf_signature_hash now uses
serialize_with = "ser_rf_signature_hash" alongside skip_serializing_if
- nibble_to_hex(u8) -> char private const fn (no `hex` crate dep needed
for 32 bytes; lowercase hex is trivial)
- Output format: "blake3:deadbeef..." exactly 71 ASCII chars
tests/json_hash_format.rs (5 named tests, all green):
rf_signature_hash_serializes_as_blake3_prefixed_lowercase_hex
(expected hex built programmatically via format!("{b:02x}"))
hex_string_is_always_64_chars_when_present
(parses the JSON, isolates the hash substring, asserts exact 64
chars and lowercase-only — catches case-folding regressions)
hash_field_omitted_entirely_when_none
end_to_end_emitter_hasher_to_json_emits_blake3_hex_hash
*** Cross-iter integration test: BfldEmitter::with_signature_hasher
→ SensingInputs.rf_signature_hash = None → emit derives via
BLAKE3 → BfldEvent::to_json → contains "blake3:" prefix.
Spans iters 13, 14, 15, 16, 17 in a single assertion. ***
end_to_end_restricted_class_omits_hash_even_with_hasher_set
(class 3: even with hasher installed, JSON omits the hash)
ACs progressed:
- BFLD wire spec §6 — rf_signature_hash JSON shape now matches the
documented format ("blake3:..."); HA / Matter consumers can parse
it without custom byte-array decoding.
- ADR-118 §1 invariant I3 — visibility: the JSON wire form now
cryptographically tags the hash with its algorithm prefix, so
consumers can verify they're not parsing a different (weaker)
hash that a future PR might accidentally substitute.
Test config:
- cargo test --no-default-features → 72 passed (json_hash_format cfg-out)
- cargo test → 128 passed (123 + 5)
Out of scope (next iter target):
- IdentityFeatures typed encoder so callers feeding BfldEmitter don't
need to know that embedding bytes serve as hasher input.
- Replace the manual hex push with `hex::encode` if/when the workspace
takes on the `hex` crate dep for other reasons; current path saves
the dep without sacrificing correctness.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
351af66084 |
feat(adr-118/p4.3): wire SignatureHasher into BfldEmitter (123/123 GREEN)
Iter 16. End-to-end ADR-120 §2.3 wiring: BfldEmitter now produces
rf_signature_hash derived from (site_salt, day_epoch, features), with
the IdentityEmbedding bytes as the preferred feature source. Closes
the gap from iter 15 — the hasher is now reachable from the pipeline.
Added (in src/emitter.rs):
- BfldEmitter.signature_hasher: Option<SignatureHasher> field
- BfldEmitter::with_signature_hasher(SignatureHasher) -> Self builder
- emit_with_oracle computes derived_hash BEFORE pushing embedding to ring:
1. unix_secs = inputs.timestamp_ns / NS_PER_SEC
2. feature bytes: embedding.as_slice() flattened to LE f32 bytes,
OR fallback canonical_risk_bytes(&inputs) (4-tuple of LE f32)
3. hasher.compute_at(unix_secs, &bytes)
- Derived hash overrides inputs.rf_signature_hash; when hasher absent
caller-supplied value passes through unchanged (backward compat)
- canonical_risk_bytes(&inputs) -> [u8; 16] private helper for fallback
tests/emitter_hasher.rs (6 named tests, all green):
no_hasher_passes_caller_supplied_hash_through
installed_hasher_overrides_caller_supplied_hash
same_emitter_same_inputs_produce_same_hash (determinism through emitter)
different_site_salts_produce_different_hashes_end_to_end
*** cross-site isolation proven via the BfldEmitter API, not just
via the SignatureHasher direct API (iter 15) ***
no_embedding_falls_back_to_risk_factor_bytes
fallback_hash_differs_from_embedding_hash
(embedding-based and fallback-based hashes are distinct paths)
ACs progressed:
- ADR-120 §2.7 AC2 — cross-site isolation now provable at the public
emitter surface, not just inside the hasher module.
- ADR-118 §2.1 pipeline integration — derived rf_signature_hash flows
through to the BfldEvent without caller participation. Operators
install the hasher once at boot; per-frame code never sees site_salt.
Test config:
- cargo test --no-default-features → 72 passed (emitter_hasher cfg-out)
- cargo test → 123 passed (117 + 6)
Out of scope (next iter target):
- IdentityFeatures struct — typed canonical-bytes encoder so callers
don't need to know that embedding bytes feed the hasher directly.
- Cross-iter integration test: BfldEmitter → BfldEvent::to_json with
derived hash, parsed back, hash field present and base64-encoded
(or hex-encoded) per the JSON wire spec.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
0ca8a38cbc |
feat(adr-118/p3.5): SignatureHasher (BLAKE3-keyed) — 117/117 GREEN
Iter 15. Lands ADR-120 §2.3 — the cryptographic foundation of invariant
I3 ("cross-site identity correlation is impossible"). rf_signature_hash
is now derived from a per-site secret and a daily epoch, so two nodes
observing the same physical person produce uncorrelated 256-bit digests.
Added (no_std-compatible):
- blake3 = "1.5", default-features = false (no_std, no SIMD by default)
- src/signature_hasher.rs:
* Constants SECONDS_PER_DAY (86_400), SITE_SALT_LEN (32), RF_SIGNATURE_LEN (32)
* SignatureHasher { site_salt: [u8; 32] } with new(salt) const ctor
* compute(day_epoch, &features) -> [u8; 32] (BLAKE3 keyed mode)
* compute_at(unix_secs, &features) -> [u8; 32] convenience
* day_epoch_from_unix_secs(unix_secs) -> u32 helper (floor(t / 86400))
- pub use SignatureHasher, RF_SIGNATURE_LEN, SITE_SALT_LEN from lib.rs
tests/signature_hasher.rs (8 named tests, all green):
deterministic_under_identical_inputs
different_site_salts_produce_different_hashes
different_day_epochs_rotate_the_hash
different_features_produce_different_hashes
output_length_is_32_bytes
day_epoch_from_unix_secs_matches_floor_division
(covers 0, 86_399, 86_400, and the 1.7e9 modern timestamp)
compute_at_matches_compute_with_derived_day
cross_site_hamming_distance_is_statistically_high
*** ADR-120 §2.7 AC2 acceptance test ***
Runs 100 trials with distinct (salt_a, salt_b) pairs observing
identical features, computes per-trial Hamming distance, asserts
mean >= 120 bits and min >= 80 bits. Empirically lands at ~128 bits
mean (the expected value for two independent 256-bit hashes), with
no trial below 80 bits — i.e., zero suspicious near-collisions.
ACs progressed:
- ADR-120 §2.7 AC2 — structurally enforced cross-site isolation, now
proven empirically by the Hamming-distance test. This is the
cryptographic half of invariant I3 in code, not just docs.
- ADR-118 invariant I3 — first runtime witness that two sites with
independent site_salts cannot correlate the same person's signature.
Test config:
- cargo test --no-default-features → 72 passed (64 + 8; signature_hasher is no_std)
- cargo test → 117 passed (109 + 8)
Out of scope (next iter target):
- Wire SignatureHasher into BfldEmitter: replace caller-supplied
rf_signature_hash with hasher.compute_at(ts, &features) so the
pipeline produces correct hashes end-to-end.
- IdentityFeatures canonical-bytes encoder so callers don't need to
hand-serialize per-feature representations.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
9c518f6e36 |
feat(adr-118/p4.2): BfldEmitter end-to-end pipeline (109/109 GREEN)
Iter 14. Wires every iter-1..13 primitive into a single ADR-118 §2.1
pipeline: per-frame sensing inputs go in, a privacy-gated BfldEvent
(or None) comes out. First time every constituent is exercised together.
Added (gated on `feature = "std"`):
- src/emitter.rs:
* SensingInputs struct — 11 fields: timestamp_ns, presence, motion,
person_count, sensing_confidence, sep, stab, consist, risk_conf,
rf_signature_hash (Option)
* BfldEmitter struct owning: node_id, default_zone_id, privacy_class,
CoherenceGate, EmbeddingRing
* Builder API: new(node_id) → with_zone(...) → with_privacy_class(...)
* current_action() / ring_len() diagnostic accessors
* emit(inputs, embedding) → Option<BfldEvent>
1. score = identity_risk::score(sep, stab, consist, risk_conf)
2. ring.push(embedding) if Some
3. action = gate.evaluate_with_oracle(score, ts, &NullOracle)
4. if action == Recalibrate { ring.drain() }
5. if action.drops_event() { return None }
6. else BfldEvent::with_privacy_gating(...) honoring privacy_class
* emit_with_oracle(...) variant for `--features soul-signature` callers
- pub use BfldEmitter, SensingInputs from lib.rs
tests/emitter_pipeline.rs (7 named tests, all green):
emitter_emits_event_under_low_risk
emitter_drops_event_under_sustained_high_risk (debounce honored)
emitter_drains_ring_on_recalibrate
(fills ring to 5, then Recalibrate-grade score → ring_len() == 0)
restricted_class_strips_identity_fields_in_emitted_event
(class 3: identity_risk_score AND rf_signature_hash both None)
with_zone_sets_default_zone_id_on_event
embedding_is_pushed_to_ring_even_when_event_dropped
(privacy gating drops the event but the ring still observes the
embedding so subsequent separability calculations remain valid)
ring_unchanged_when_no_embedding_supplied
ACs progressed:
- ADR-118 AC1 (BFLD core pipeline integration) — every component from
iter 1 (frame format) through iter 13 (event) is now traversed by a
single emit() call. This is the first end-to-end smoke proof.
- ADR-121 AC4 — Recalibrate-grade sustained score triggers ring drain
(verified by ring_len() going from 5 to 0).
- ADR-122 AC1 — privacy_class threaded through the pipeline so the
output event is correctly gated for HA/Matter consumption.
Test config:
- cargo test --no-default-features → 64 passed (emitter cfg-out)
- cargo test → 109 passed (102 + 7)
Out of scope (next iter target):
- Wiring rf_signature_hash computation from BLAKE3-keyed(site_salt,
features) per ADR-120 §2.3 — the SensingInputs.rf_signature_hash
is supplied by caller for now; needs a SignatureHasher with site_salt
initialization in a follow-up iter.
- Embedding ring → identity_separability_score derivation (currently
`sep` is caller-supplied; should be computed from ring contents).
- MQTT topic publisher wrapping BfldEmitter (ADR-122 §2.2) — depends
on a runtime (tokio).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
926c66f677 |
feat(adr-118/p4.1): BfldEvent privacy-gated output + JSON (102/102 GREEN)
Iter 13. Lands ADR-121 §2.1 (output event) + ADR-122 §2.1 (field-gating
policy). BfldEvent collapses the GateAction-driven sensing pipeline
into the canonical wire-format publishable on MQTT.
Added:
- serde (workspace, derive feature, optional) + serde_json (workspace, optional) deps
- New crate feature `serde-json` (default-on; requires `std`)
- src/event.rs (gated on `feature = "std"`):
* BfldEvent struct with all sensing + identity-derived fields
* with_privacy_gating(...) constructor that applies field-gating policy:
class < Restricted (3): identity_risk_score + rf_signature_hash kept
class >= Restricted (3): both nulled to None
* apply_privacy_gating() — idempotent in-place masking
* to_json() -> Result<String, serde_json::Error> (gated on serde-json)
* Custom ser_privacy_class serializer emits lowercase names
("anonymous", "restricted", etc.) per the BFLD JSON spec
* skip_serializing_if = "Option::is_none" on identity-derived fields so
privacy-gated events are observationally indistinguishable from
events that never had the field set
- pub use BfldEvent from lib.rs
tests/event_privacy_gating.rs (9 named tests, all green):
anonymous_event_retains_identity_risk_and_hash
restricted_event_strips_identity_fields (class 3 → None)
apply_privacy_gating_is_idempotent
event_type_is_always_bfld_update (parameterized over 3 classes)
json::json_round_trip_emits_type_field_first_or_last_but_present
json::anonymous_json_includes_identity_fields
json::restricted_json_omits_identity_fields_entirely
(asserts the JSON string does NOT contain identity_risk_score or
rf_signature_hash, verifying skip_serializing_if works as intended)
json::privacy_class_serializes_to_lowercase_name
json::zone_id_none_is_omitted_from_json
ACs progressed:
- ADR-121 AC6 (identity_risk score absent at class 3) — structurally
enforced by with_privacy_gating + skip_serializing_if combination.
- ADR-122 AC1 — JSON shape matches the HA-DISCO publishable event
contract; identity fields can be reliably stripped by privacy_class.
- ADR-118 AC5 — privacy_mode = engaged maps to PrivacyClass::Restricted
with no identity fields in the published event.
Test config:
- cargo test --no-default-features → 64 passed (unchanged; event cfg-out)
- cargo test → 102 passed (93 + 9)
Out of scope (next iter target):
- Emitter struct that wires GateAction + privacy class + sensing inputs
into BfldEvent construction (ADR-118 §2.1 pipeline diagram).
- MQTT topic publisher (ADR-122 §2.2) — depends on a runtime (tokio).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
ae6fd75095 |
feat(adr-118/p3.4): SoulMatchOracle + Recalibrate exemption (93/93 GREEN)
Iter 12. Wires the ADR-121 §2.6 Recalibrate exemption: when an enrolled
person_id matches the current high-separability cluster, the gate
downgrades the would-be Recalibrate to PredictOnly. The high score is
the *intended* outcome of a Soul Signature match, not an attacker-grade
sniffer arrival — so site_salt rotation is suppressed.
Added (no_std-compatible):
- src/coherence_gate.rs additions:
* MatchOutcome enum: Match { person_id: u64 } | NotEnrolled | Suppressed
* SoulMatchOracle trait with matches_enrolled() -> MatchOutcome
* NullOracle (default-constructible, always reports NotEnrolled)
* CoherenceGate::evaluate_with_oracle(score, ts, &O: SoulMatchOracle)
— same hysteresis/debounce as evaluate(), but downgrades Recalibrate
to PredictOnly when oracle returns Match { .. }
* Refactored evaluate(): extracted advance_state(target, ts) shared with
evaluate_with_oracle. evaluate is now a 4-line wrapper.
- pub use MatchOutcome, NullOracle, SoulMatchOracle from lib.rs
tests/soul_match_oracle.rs (8 named tests, all green):
null_oracle_matches_default_evaluate_behavior
(parameterized over 5 score points; oracle-aware and oracle-free
gates produce identical trajectories)
match_outcome_downgrades_recalibrate_to_predict_only
(score=0.95 pends PredictOnly instead of Recalibrate)
match_exemption_promotes_predict_only_after_debounce_not_recalibrate
(after DEBOUNCE_NS, current is PredictOnly — never Recalibrate)
match_outcome_does_not_affect_lower_actions
(Reject pending stays Reject; oracle only intercepts Recalibrate)
suppressed_outcome_does_not_exempt_recalibrate
(Suppressed is functionally equivalent to NotEnrolled at the gate)
not_enrolled_outcome_does_not_exempt_recalibrate
match_outcome_carries_person_id
null_oracle_default_constructor_works
ACs progressed:
- ADR-121 §2.6 fully covered as a stateless integration point — the
hook is in place for the `--features soul-signature` Soul Signature
crate (TBD) to plug in a real RaBitQ-backed oracle.
- ADR-118 §1.4 Soul Signature companion contract is now structurally
enforced at the gate boundary: enrolled subjects do not trigger
site_salt rotation; everyone else does.
Test config:
- cargo test --no-default-features → 64 passed (56 + 8)
- cargo test → 93 passed (85 + 8)
Out of scope (next iter target):
- BfldEvent struct (ADR-121 §2.1 output event JSON) — the downstream
consumer of GateAction. Pairs the gate decision with presence/motion/
person_count sensing fields.
- Optional: connect SoulMatchOracle into the actual `--features
soul-signature` build (compile-time gate around a re-export).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
8b79d951c1 |
feat(adr-118/p3.3): CoherenceGate hysteresis + 5s debounce — 85/85 GREEN
Iter 11. Wraps the stateless GateAction classifier from iter 10 with two
stabilizing mechanisms per ADR-121 §2.5:
* ±0.05 HYSTERESIS — a score must clear the current band's edge by
HYSTERESIS before the gate considers the next band.
* 5-second DEBOUNCE_NS — a different action must persist that long
before it becomes current; returning to the current band cancels it.
Added (no_std-compatible):
- src/coherence_gate.rs:
* HYSTERESIS const (0.05) + DEBOUNCE_NS const (5_000_000_000)
* CoherenceGate { current, pending: Option<(GateAction, u64)> }
* new() / Default / current() / pending() (diagnostic accessors)
* evaluate(score, timestamp_ns) -> GateAction
Algorithm: compute effective_target via per-direction hysteresis check,
promote pending after DEBOUNCE_NS elapsed, cancel pending on return to
current band, reset debounce clock if pending target changes
* Private helpers effective_target / action_idx / upper_edge_of / lower_edge_of
- pub use CoherenceGate from lib.rs
tests/coherence_gate.rs (13 named tests, all green):
fresh_gate_starts_in_accept_with_no_pending
low_score_stays_in_accept_with_no_pending
score_just_past_boundary_but_within_hysteresis_does_not_pend
(0.52: above 0.5 but inside hysteresis envelope — no pending)
score_clearly_past_hysteresis_starts_pending
(0.6: past 0.55 hysteresis edge — pending PredictOnly registered)
pending_action_promotes_after_full_debounce
pending_action_does_not_promote_before_debounce
(verified at DEBOUNCE_NS - 1)
returning_to_current_band_cancels_pending
changing_pending_target_resets_the_debounce_clock
(PredictOnly pending at t=0, then Recalibrate at t=1s — clock resets,
must wait until t=1s+DEBOUNCE_NS before Recalibrate is current)
downward_transitions_also_require_hysteresis
(from PredictOnly, 0.48 stays put; 0.44 pends Accept)
spike_to_one_then_back_to_zero_never_promotes_to_recalibrate
(transient spike + return to baseline produces no transition)
boundary_value_with_hysteresis_does_not_promote (0.5+0.05-epsilon)
boundary_value_at_hysteresis_exact_does_pend (0.5+0.05)
nan_score_stays_in_current_action_with_no_pending
ACs progressed:
- ADR-121 AC4 — Recalibrate fires when score >= 0.9 for >= DEBOUNCE_NS (5s).
The debounce test above directly exercises this.
- ADR-121 AC5 — hysteresis test confirms action does not oscillate across
± 0.05 of a threshold within a 5-second window.
Test config:
- cargo test --no-default-features → 56 passed (43 + 13)
- cargo test → 85 passed (72 + 13)
Out of scope (next iter target):
- SoulMatchOracle stub trait (ADR-121 §2.6) + Recalibrate exemption —
when --features soul-signature is enabled and the oracle reports a known
enrolled person_id match, the gate downgrades Recalibrate → PredictOnly.
- BfldEvent struct (ADR-121 §2.1 output event) — first downstream consumer
of the gate action.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
2e7f67c933 |
feat(adr-118/p3.2): identity_risk score + GateAction enum — 72/72 GREEN
Iter 10. Lands the stateless half of ADR-121 §2.2–§2.4: the
multiplicative risk-score formula and the 4-band gate classifier.
Hysteresis + 5s debounce (stateful CoherenceGate) land in iter 11.
Added (no_std-compatible):
- src/identity_risk.rs:
* score(sep, stab, consist, conf) -> f32
Each input clamped to [0,1]; NaN → 0 (conservative). Multiplicative
combination: any near-zero factor collapses the score → privacy-biased.
* Threshold constants: PREDICT_ONLY_THRESHOLD=0.5, REJECT_THRESHOLD=0.7,
RECALIBRATE_THRESHOLD=0.9
* GateAction enum: Accept | PredictOnly | Reject | Recalibrate
* GateAction::from_score(f32) -> Self — band-based classification with
inclusive lower edges (0.7 maps to Reject, 0.9 maps to Recalibrate)
* GateAction::allows_publish() / drops_event() / requires_recalibrate()
- pub use identity_risk_score (the function) and GateAction from lib.rs
tests/identity_risk_score.rs (12 named tests, all green):
all_ones_yields_one
any_zero_factor_collapses_score_to_zero (4 single-factor variants)
score_is_monotonic_non_decreasing_in_single_factor
out_of_range_inputs_are_clamped_to_unit_interval
nan_inputs_treated_as_zero (verifies privacy-conservative NaN handling)
known_score_matches_hand_calculation (0.8*0.9*0.85*0.95 to 1e-6)
from_score_classifies_each_band (8 boundary-condition checks)
threshold_constants_match_documented_values
nan_score_maps_to_accept_conservatively
allows_publish_partitions_actions_correctly
drops_event_inverts_allows_publish (parameterized over all 4 actions)
requires_recalibrate_is_unique_to_recalibrate
ACs progressed:
- ADR-121 AC2 partial — `score` formula structurally enforces non-negativity,
upper bound 1.0, and conservative behavior under uncertainty (NaN, negative
input, single near-zero factor).
- ADR-121 AC7 partial — score function is pure / deterministic; identical
inputs always produce identical outputs (asserted by the known-value test).
Test config:
- cargo test --no-default-features → 43 passed (31 + 12)
- cargo test → 72 passed (60 + 12)
Out of scope (next iter target):
- CoherenceGate stateful struct: ±0.05 hysteresis + 5-second debounce
(ADR-121 §2.5) so the gate doesn't oscillate near band boundaries.
- SoulMatchOracle stub trait (ADR-121 §2.6) — the Recalibrate exemption
hook for `--features soul-signature` deployments.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
4a6498fc2f |
feat(adr-118/p3.1): PrivacyGate::demote monotonic class transformer (60/60 GREEN)
Iter 9. Lands ADR-120 §2.4 — the only operation that can lower a frame's
information content. Demote is monotonic by construction (Result::Err
on non-monotone target), strips payload sections per the target class
table, and re-syncs header.privacy_class + CRC32.
Added:
- src/privacy_gate.rs (gated on `feature = "std"`):
* PrivacyGate unit struct (+ Default impl)
* PrivacyGate::demote(BfldFrame, target: PrivacyClass) -> Result<BfldFrame>
* Stripping policy:
target >= Anonymous (2): zeros + clears compressed_angle_matrix and
csi_delta; sets csi_delta = None so from_payload clears HAS_CSI_DELTA
target >= Restricted (3): also zeros + clears amplitude_proxy and phase_proxy
* zeroize_then_clear helper — overwrite with 0 then black_box then truncate
- BfldError::InvalidDemote { from: u8, to: u8 } variant
- pub use PrivacyGate from lib.rs
Note: demote does NOT zero the original Vec capacity that the heap allocator
may still hold — the buffers we own are zeroed and cleared, but the
intermediate Vec passed back to BfldFrame::from_payload reallocates anew.
For strict heap zeroization in regulated deployments, a follow-up iter can
substitute zeroize::Zeroizing<Vec<u8>>.
tests/privacy_gate_demote.rs (7 named tests, all green):
demote_to_same_class_is_identity
demote_derived_to_anonymous_strips_compressed_angle_matrix
(also asserts csi_delta dropped, snr_vector and amplitude_proxy preserved)
demote_derived_to_restricted_strips_amplitude_and_phase_too
(snr_vector and vendor_extension survive at class 3)
demote_anonymous_to_derived_is_rejected
(asserts InvalidDemote { from: 2, to: 1 })
demote_to_raw_is_rejected_from_any_higher_class
(parameterized over Derived, Anonymous, Restricted as sources)
demote_preserves_frame_crc_consistency_through_wire_roundtrip
(post-demote frame survives to_bytes -> from_bytes with no CRC error)
demote_clears_has_csi_delta_flag_bit
ACs progressed:
- AC5 ↑ — privacy_mode enforcement at the frame-class boundary now works
through PrivacyGate, not just the BfldEvent emitter (deferred). When the
active class is Anonymous (2) or Restricted (3), the angle matrix /
csi_delta / amplitude / phase sections that carry identity information
are zeroed before any downstream code sees them.
- AC4 ↑ — demoted frames retain valid CRC; the round-trip-through-bytes
test proves bit-correctness after the class transition.
Test config:
- cargo test --no-default-features → 31 passed (privacy_gate cfg-out)
- cargo test → 60 passed (53 + 7)
Out of scope (next iter target):
- SoulMatchOracle stub trait + no-op default impl (ADR-121 §2.6) so the
Recalibrate exemption hook is wireable from `--features soul-signature`.
- IdentityRiskEngine — multiplicative formula on (sep, stab, consist, conf)
with the coherence-gate GateAction enum (ADR-121 §2.2 + §2.4).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
60eaaa5af1 |
feat(adr-118/p2.2): EmbeddingRing 64-entry FIFO buffer — 53/53 GREEN
Iter 8. Lands the lifecycle half of ADR-120 §2.5: a bounded, in-place,
no_std-compatible ring of IdentityEmbeddings. Insertion is O(1); when
full, push evicts the oldest entry, whose Drop runs and zeroizes the
f32 storage. drain() clears the ring on the coherence-gate Recalibrate
action (ADR-121 §2.4).
Added:
- src/embedding_ring.rs (no_std-compatible; no heap):
* EmbeddingRing struct with [Option<IdentityEmbedding>; RING_CAPACITY=64]
backing array, head cursor, count
* EmbeddingRing::new() / Default impl
* push(emb) -> Option<IdentityEmbedding> (evicted oldest when full)
* len / is_empty / capacity / is_full / iter
* iter() returns occupied slots in insertion order (oldest first)
* drain() -> usize (empties the ring, returns count drained)
- pub use EmbeddingRing, RING_CAPACITY from lib.rs
Uses `[const { None }; RING_CAPACITY]` (stable since 1.79) to initialize
the slot array for a non-Copy element type.
tests/embedding_ring.rs (9 named tests, all green):
new_ring_is_empty
default_constructor_matches_new
push_below_capacity_returns_none
iter_yields_in_insertion_order
push_at_capacity_evicts_oldest_and_returns_it
(verifies eviction reports the FIRST pushed value, not the last)
push_beyond_capacity_keeps_last_n_entries
(after 74 pushes into a 64-slot ring, the surviving 64 are positions 10..74)
drain_empties_the_ring_and_returns_count
drain_on_empty_ring_returns_zero
ring_can_be_refilled_after_drain
(post-drain push lands cleanly at index 0; iter yields exactly that entry)
ACs progressed:
- I2 ↑ — ring eviction and explicit drain both drop IdentityEmbeddings,
which the iter-7 Drop impl zeroizes. The "in-RAM-only" lifecycle is now
end-to-end: bounded buffer in, FIFO out, drain on Recalibrate.
Test config:
- cargo test --no-default-features → 31 passed (22 + 9)
- cargo test → 53 passed (44 + 9)
Out of scope (next iter target):
- PrivacyGate::demote(frame, target_class) — ADR-120 §2.4 monotonic class
transition with field zeroization, refusing demote-to-Raw (compile-fail).
- SoulMatchOracle stub trait + no-op default impl (ADR-121 §2.6) so the
Recalibrate exemption hook is wireable from `--features soul-signature`.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
71ca2780bf |
feat(adr-118/p2.1): IdentityEmbedding newtype + zeroizing Drop — 44/44 GREEN
Iter 7. First structural enforcement of ADR-118 invariant I2 — the
identity embedding is in-RAM-only and cannot be serialized, cloned,
or copied. Lands the type itself; ring-buffer lifecycle is next.
Added:
- src/embedding.rs (no_std-compatible; lives in the lib regardless of features):
* IdentityEmbedding wrapping [f32; EMBEDDING_DIM=128]
* from_raw(values), as_slice() -> &[f32], l2_norm(), len(), is_empty()
* NO Serialize, NO Clone, NO Copy impl
* Custom Debug emits only dim + L2 norm + "<redacted>" — never raw values
* Drop overwrites storage with 0.0 then core::hint::black_box(...) to defeat
dead-store elimination (DSE would otherwise let the compiler skip the write)
- Compile-time structural guards via static_assertions:
assert_impl_all!(IdentityEmbedding: Drop)
assert_not_impl_any!(IdentityEmbedding: Copy, Clone)
- pub use IdentityEmbedding, EMBEDDING_DIM from lib.rs
tests/identity_embedding.rs (5 named tests, all green):
from_raw_preserves_values_through_as_slice
l2_norm_is_correct
debug_output_redacts_raw_values
(asserts the formatted output does NOT contain decimal text of values)
embedding_is_not_clonable
(runtime witness; compile-time assertion lives in src/embedding.rs)
drop_overwrites_storage_with_zeros
(Drop runs without panic; bit-level zeroization is asserted by the
black_box-guarded loop. Unsafe peek-after-free is intentionally avoided.)
ACs progressed:
- AC5 ↑ — even in `privacy_mode`, the IdentityEmbedding type can't be reached
from any serialization path because the type system rejects the impl.
- I2 ↑ — Drop, no Clone, no Copy, redacted Debug are all in place as
compile-time guarantees.
Test config:
- cargo test --no-default-features → 22 passed
- cargo test → 44 passed (3 + 6 + 7 + 8 + 8 + 7 + 5)
Out of scope (next iter target):
- EmbeddingRing — 64-entry FIFO ring buffer holding IdentityEmbeddings,
drained on coherence-gate Recalibrate (ADR-121 §2.4).
- PrivacyGate::demote(frame, target_class) transformer (ADR-120 §2.4).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
5312e3c4a1 |
feat(adr-118/p1.6): BfldFrame <-> BfldPayload wire integration (39/39 GREEN)
Iter 6. Connects the typed payload parser (iter 5) to the framed
wire format (iter 4): the CRC32 now covers the section-prefixed
payload bytes per ADR-119 §2.2 ("CRC32 covers all section bytes
including length prefixes").
Added:
- BfldFrame::from_payload(header, &BfldPayload) -> Self
Auto-syncs header.flags HAS_CSI_DELTA bit from payload.csi_delta.is_some(),
serializes payload via to_bytes(), feeds BfldFrame::new() which computes
payload_len + payload_crc32 over the section-prefixed bytes.
- BfldFrame::parse_payload(&self) -> Result<BfldPayload, BfldError>
Reads HAS_CSI_DELTA bit from header.flags and dispatches to
BfldPayload::from_bytes(&self.payload, expect_csi_delta).
tests/frame_payload_integration.rs (7 named tests, all green):
from_payload_then_parse_payload_is_identity
from_payload_autosets_has_csi_delta_flag
from_payload_clears_has_csi_delta_flag_when_csi_absent
(verifies the flag is cleared when csi_delta is None even if caller
pre-set the bit; other flag bits like PRIVACY_MODE are preserved)
frame_crc_covers_section_prefixed_bytes
(mutating a byte inside section body trips CRC, not magic/length)
frame_crc_covers_section_length_prefixes
(mutating a section length-prefix byte trips CRC before parser ever runs)
empty_typed_payload_roundtrips
end_to_end_wire_roundtrip_via_bytes
(BfldPayload -> from_payload -> to_bytes -> from_bytes -> parse_payload
is the identity function modulo flag auto-set)
ACs progressed:
- AC5 ↑ — full payload round-trip through the framed bytes (closes
the round-trip leg from BfldPayload through wire and back).
- AC6 ↑ — same input produces same bytes through both layers.
- AC4 ↑ — CRC mismatch on tampered section bodies and tampered section
length prefixes both surface as BfldError::Crc, not as silent acceptance
or as a deeper parser error.
Test config:
- cargo test --no-default-features → 17 passed (integration tests cfg-out)
- cargo test → 39 passed (3 + 6 + 7 + 8 + 8 + 7)
Out of scope (next iter target):
- PrivacyGate::demote(frame, target_class) — ADR-120 §2.4 class transition
transformer with subtle::Zeroize on dropped fields.
- IdentityEmbedding newtype with no Serialize impl (ADR-120 §2.5 / I2).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
73ba8d3b27 |
feat(adr-118/p1.5): payload section parser (BfldPayload) — 32/32 GREEN
Iter 5. Implements ADR-119 §2.2 payload layout: 4-byte LE length prefix
followed by section bytes, in this fixed order:
compressed_angle_matrix ‖ amplitude_proxy ‖ phase_proxy ‖ snr_vector
‖ csi_delta (iff flags.bit0)
‖ vendor_extension (length 0 allowed)
Added:
- src/payload.rs (gated on `feature = "std"`):
* BfldPayload struct with 6 fields (csi_delta: Option<Vec<u8>>)
* SECTION_PREFIX_LEN const (= 4)
* to_bytes(include_csi_delta: bool) -> Vec<u8>
* wire_len(include_csi_delta: bool) -> usize (predictive, no allocation)
* from_bytes(&[u8], expect_csi_delta: bool) -> Result<Self, BfldError>
* push_section / read_section helpers (private)
- BfldError::MalformedSection { offset, reason } variant
- pub use BfldPayload from lib.rs (cfg-gated mirror of BfldFrame)
tests/payload_sections.rs (8 named tests, all green):
payload_roundtrip_with_csi_delta
payload_roundtrip_without_csi_delta
wire_len_matches_to_bytes_length
empty_payload_has_five_zero_length_sections
parser_rejects_buffer_shorter_than_first_length_prefix
parser_rejects_section_body_running_past_buffer_end
parser_rejects_trailing_bytes_after_vendor_extension
csi_delta_flag_mismatch_with_payload_is_detectable_via_trailing_bytes
ACs progressed:
- AC5 ↑ — full section-level round-trip preservation (round-trip with and
without csi_delta both pass).
- AC6 ↑ — deterministic section encoding (length prefixes use to_le_bytes,
body is byte-stable).
- AC1 partial — section layout now parses with bounded errors; CBFR-specific
parsing (Phi/Psi Givens decoders) is a separate iter inside extractor.rs.
Test config:
- cargo test --no-default-features → 17 passed (payload module cfg-out)
- cargo test → 32 passed (3 + 6 + 7 + 8 + 8)
Out of scope (next iter target):
- Wire integration: feed BfldPayload bytes through BfldFrame::new so the
header.payload_crc32 covers the section-prefixed bytes per ADR-119 §2.2
("CRC32 covers all section bytes including length prefixes").
- A no_std-friendly BfldPayloadRef<'_> borrowing variant (ESP32-S3 path).
- Givens-rotation angle decoder (Phi/Psi extraction from compressed_angle_matrix).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
775661b2e8 |
feat(adr-118/p1.4): BfldFrame (header + payload + CRC32) — 24/24 GREEN
Iter 4. Lands the central wire-format primitive: complete frames with
header + arbitrary-length payload, protected by CRC-32/ISO-HDLC.
Added:
- crc = "3" dependency (CRC-32/ISO-HDLC, same poly as Ethernet / zlib)
- src/frame.rs: CRC32_ALG const and crc32_of_payload(&[u8]) -> u32
- src/frame.rs: BfldFrame { header, payload: Vec<u8> } (gated on `std`)
* BfldFrame::new(header, payload) — auto-syncs payload_len + payload_crc32
* BfldFrame::to_bytes() -> Vec<u8> — header LE bytes ‖ payload
* BfldFrame::from_bytes(&[u8]) -> Result<Self, BfldError>
- BfldError::TruncatedFrame { got, need } variant
- Doc strings on BfldError::Crc and BfldError::PrivacyViolation field names
- tests/frame_roundtrip.rs (7 named tests, gated on feature = "std"):
frame_roundtrip_preserves_header_and_payload
frame_new_syncs_payload_len_and_crc
frame_serialization_is_deterministic
frame_rejects_payload_crc_mismatch
frame_rejects_truncated_buffer_smaller_than_header
frame_rejects_truncated_buffer_smaller_than_payload
empty_payload_is_valid (CRC of empty payload is 0x00000000)
Test config:
- cargo test --no-default-features → 17 passed (frame_roundtrip cfg-out)
- cargo test (default features = std) → 24 passed (3+6+7+8)
ADR-119 ACs progressed:
- AC4 partial: bad-magic + bad-version + CRC-mismatch + truncation rejected
with typed errors; field-level masking lives in the privacy_gate iter.
- AC5: BfldFrame round-trip preserves header + payload + CRC.
- AC6: Identical inputs produce bit-identical bytes (asserted explicitly).
Out of scope (next iter):
- Payload section parser (compressed_angle_matrix, amplitude_proxy, ...)
— only the byte buffer is opaque so far; sections need length prefixes.
- BfldFrameRef<'_> for ESP32-S3 self-only mode (no-alloc, ADR-123 §2.5).
- PrivacyGate::demote(frame, target_class) transformer (ADR-120 §2.4).
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
eb996294fb |
feat(adr-118/p1.3): Sink marker traits + PrivacyClass::try_from (17/17 GREEN)
Iter 3. Lands the structural enforcement of ADR-118 invariant I1
("raw BFI never exits the node") and ADR-120 §2.2 ("Sink marker types").
Added:
- src/sink.rs:
* Sink trait with MIN_CLASS and KIND associated constants
* LocalSink (Raw OK), NetworkSink (Derived+ only), MatterSink (Anonymous+)
* Hierarchy: MatterSink: NetworkSink (every Matter sink is a NetworkSink)
* check_class<S>(class) runtime gate, returns PrivacyViolation{reason:KIND}
* Zero-sized kind tags: LocalKind / NetworkKind / MatterKind
- PrivacyClass::as_u8() const helper
- TryFrom<u8> for PrivacyClass (0..=3 valid; 4..=255 → InvalidPrivacyClass)
- BfldError::InvalidPrivacyClass(u8) variant
tests/sink_enforcement.rs adds 8 tests:
privacy_class_try_from_accepts_all_four_valid_bytes
privacy_class_try_from_rejects_out_of_range_bytes
privacy_class_byte_roundtrip_is_stable
local_sink_accepts_all_classes
network_sink_rejects_raw_frames
network_sink_accepts_derived_anonymous_restricted
matter_sink_rejects_raw_and_derived
matter_sink_accepts_anonymous_and_restricted
Out of scope (next iter):
- BfldFrame (header + payload + section length-prefixes + CRC32 over payload)
— needs the `crc` crate dependency.
- PrivacyGate::demote(frame, target_class) transformer (ADR-120 §2.4).
- compile-fail test that proves a sink-trait bound rejects Raw at compile
time — needs `trybuild` integration; deferred to a separate iter.
cargo test -p wifi-densepose-bfld --no-default-features → 17 passed, 0 failed
(3 frame_header_size + 6 header_roundtrip + 8 sink_enforcement)
Co-Authored-By: claude-flow <ruv@ruv.net>
v1260
v1261
v1259
|
||
|
ruv
|
be4dad6ede |
feat(adr-118/p1.2): header encode/decode + 6 round-trip tests (9/9 GREEN)
Iter 2 of the BFLD rollout. Adds the canonical little-endian wire form for
BfldFrameHeader with safe (no unsafe) encoders/decoders. Covers ADR-119 AC5
(round-trip preservation), AC6 (deterministic serialization), and partial
AC1 (constant wire size) / AC4 (rejects bad magic + bad version).
Added:
- BfldFrameHeader::empty() — convenience constructor with magic/version set
- BfldFrameHeader::to_le_bytes() -> [u8; 86]
- BfldFrameHeader::from_le_bytes(&[u8; 86]) -> Result<Self, BfldError>
- Field-level doc strings on every header field (clears all 21 missing-docs
warnings the iter 1 commit logged)
- tests/header_roundtrip.rs — 6 named tests:
header_roundtrip_preserves_all_fields
header_serialization_is_deterministic
header_magic_is_at_offset_zero_little_endian (LE byte order proof)
parsing_rejects_invalid_magic
parsing_rejects_unsupported_version
wire_size_is_constant
Implementation notes:
- Used #[derive(Default)] on BfldFrameHeader so empty() can build cleanly.
- to_le_bytes copies packed fields into locals first to dodge unaligned-
borrow lints; from_le_bytes uses try_into() on byte slices.
- All field reads/writes are #[forbid(unsafe_code)] compliant.
Out of scope (next iter targets):
- BfldFrame (header + payload sections + section-length prefixes + CRC32
computation over payload bytes only) — needs the `crc` crate dependency.
- PrivacyGate::demote(...) skeleton (ADR-120 §2.4).
- SinkMarker traits (LocalSink / NetworkSink / MatterSink) — ADR-120 §2.2.
cargo test -p wifi-densepose-bfld --no-default-features → 9 passed, 0 failed
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
c965e3e6c0 |
feat(adr-118/p1): scaffold wifi-densepose-bfld crate + frame header (3/3 tests GREEN)
Land P1 of the BFLD rollout — the wire-format primitives: - New workspace member: v2/crates/wifi-densepose-bfld - PrivacyClass enum (Raw/Derived/Anonymous/Restricted) with allows_network() and allows_matter() const helpers reflecting ADR-120 §2.2 and ADR-122 §2.4 - BfldFrameHeader (#[repr(C, packed)]) per ADR-119 §2.1 - BFLD_MAGIC = 0xBF1D_0001, BFLD_VERSION = 1 - BfldError variants for InvalidMagic / UnsupportedVersion / Crc / PrivacyViolation - soul-signature cargo feature (gated, default OFF) per ADR-118 §1.4 - Compile-time size assertion via static_assertions::const_assert_eq! - 3 acceptance tests in tests/frame_header_size.rs (all pass) Bug fix: - ADR-119 AC1 claimed BfldFrameHeader is 40 bytes. Actual packed layout sums to 86 bytes. Updated AC1 and §2.1 prose to match. const_assert in frame.rs pins the value structurally — a future field addition that breaks the size fails to compile. Out of scope for this iter (deferred to later P1 commits): - Field-level missing-docs warnings (21) — addressed alongside accessor helpers - Payload section parsing — needs the section-length prefix tests - Round-trip serialize/parse — covered by a fixture-based test in the next iter cargo test -p wifi-densepose-bfld --no-default-features → 3 passed, 0 failed Co-Authored-By: claude-flow <ruv@ruv.net> |
||
|
ruv
|
833ac84059 |
docs(adr-117): point README + user-guide at the live PyPI releases
Both packages are now live on PyPI; bring the in-repo docs up to match. Keep both updates brief — the canonical surface documentation lives on the PyPI project pages themselves. Root README (Option 4 block): - Switch the default `pip install` example to `ruview` (the brand name) and note `wifi-densepose` is equivalent. - Add live PyPI version badges for both packages. docs/user-guide.md (§Python wheel): - Replace the single-install example with a table showing both PyPI projects and their import names so users see the choice immediately. - Add three short usage snippets (vitals, live sensing-server WS, HA-MIND semantic-primitive MQTT listener) so the guide doubles as a "what does this thing do?" reference for someone landing via pip. - Note the cibuildwheel matrix for multi-arch wheels. - Add the `pytest tests/` + `pytest bench/` source-build verify steps. No code or test changes. Refs: docs/adr/ADR-117-pip-wifi-densepose-modernization.md Refs: #786 Co-Authored-By: claude-flow <ruv@ruv.net>v1258 |
||
|
rUv
|
0bffe27288 |
feat(adr-117): pip wifi-densepose modernization (PIP-PHOENIX) + ruview sibling release (#786)
* docs(adr-117): seed branch — ADR-117 pip-modernization spec + soul-signature research bundle
Two artifacts landing together on this new branch as the prerequisite
documentation for the v2.0.0 Python wheel modernization work:
1. **docs/adr/ADR-117-pip-wifi-densepose-modernization.md** (644 lines)
— Plan to bring the 2025-published `wifi-densepose` PyPI package
(last release v1.1.0, 2025-06-07, 11.5 months out of sync) up to
the current Rust v2/ workspace SOTA. Recommends PyO3 + maturin
with abi3-py310 (one binary covers Python 3.10–3.13 per OS/arch),
first-wheel scope = core + vitals + signal crates (~5 MB), v1.99.0
tombstone + 90-day un-yank window for v1.1.0, v2.0.0 hard break.
Open questions catalogued; phases P1–P6+ laid out with concrete
acceptance criteria.
2. **docs/research/soul/** (5 files, ~1,450 lines) — Soul Signature
research spec: 7-channel electromagnetic biometric fingerprint
(AETHER 128-dim + cardiac HR/HRV + cardiac waveform morphology +
respiratory pattern + gait timing + skeletal proportions +
subcarrier reflection profile), fused into one RVF graph file.
Includes 60s scanning protocol, 5-layer security model,
threat-model + mitigations, references to existing ADRs (014,
021, 024, 027, 030, 039, 079, 106, 108, 109, 110, 115). Marked
"Research Specification (Pre-Implementation)". Explicit "what
this is NOT" disclaimers preempt pseudoscience drift; every
discriminative-power claim either cites a measurement or is
marked "open research; baseline TBD".
Branch off main at HEAD; ready for /loop 10m implementation
iterations.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(adr-117/p1): scaffold python/ workspace — PyO3 + maturin + smoke tests (refs #785)
ADR-117 P1 — the python/ directory is now a working maturin-buildable
crate that produces the v2.x replacement for the legacy pure-Python
wifi-densepose==1.1.0 PyPI wheel.
## What lands
- `python/Cargo.toml` — PyO3 0.22 with `extension-module` + `abi3-py310`
(one binary covers Python 3.10–3.13 per OS/arch — keeps the
cibuildwheel matrix to 5 wheels per release, not 20). Depends on
`wifi-densepose-core` from the existing v2/ workspace via relative
path.
- `python/pyproject.toml` — maturin>=1.7 build backend with
`python-source = "python"` and `module-name = "wifi_densepose._native"`
so the compiled module loads as an internal underscore-private
submodule of the user-facing `wifi_densepose` package. PEP 621
metadata + classifiers + project URLs. Optional-deps:
`wifi-densepose[client]` for the P4 WS/MQTT pure-Python layer,
`wifi-densepose[dev]` for the test toolchain (pytest, ruff, mypy).
- `python/src/lib.rs` — minimal `#[pymodule] wifi_densepose_native`
exporting `__rust_version__`, `__rust_build_tag__`,
`__build_features__`, and a `hello()` smoke function. P2 will land
the core type bindings here.
- `python/wifi_densepose/__init__.py` — pure-Python facade re-exporting
the compiled module's symbols under their stable user-facing names.
Docstring teaches the v1→v2 migration story up-front.
- `python/wifi_densepose/py.typed` — PEP 561 marker so `mypy --strict`
in user code treats the wheel as fully typed (real stubs land in P2).
- `python/tests/test_smoke.py` — 6 P1 acceptance tests:
1. package imports without error
2. version string is PEP 440-compliant
3. `__rust_version__` is reachable from Python (the diagnostic
surface ADR-117 §5.2 promised)
4. `__build_features__` lists `p1-scaffold` marker
5. `wifi_densepose.hello()` returns "ok" (FFI round-trip)
6. `wifi_densepose._native` is reachable but the leading underscore
conveys "private; users should import the parent package"
- `python/README.md` — phase ledger, local build instructions
(`maturin develop`), layout diagram.
## What's deferred to P2+
- Core type bindings (`CsiFrame`, `Keypoint`, `PoseEstimate`) — P2
- Vitals + signal DSP bindings + witness v2 — P3
- Pure-Python WS/MQTT client layer (`wifi_densepose[client]`) — P4
- cibuildwheel + PyPI publish — P5
- v1.99.0 tombstone — concurrent with P5
The new `python/` crate is intentionally OUTSIDE the v2/ Cargo
workspace — it has its own Cargo.toml with `[package]` not
`[workspace.package]` inheritance — to keep maturin's `python-source`
+ `module-name` config self-contained and to avoid forcing every
`cargo test --workspace` invocation in v2/ to compile pyo3.
Refs ADR-117 §5 (Detailed design) and §6 (Phased migration).
Refs #785 (tracking issue).
Co-Authored-By: claude-flow <ruv@ruv.net>
* fix(adr-117/p1): standalone Cargo.toml + python-source=. + #[pyo3(name=_native)] (P1 GREEN)
Three fixes to make maturin develop actually work locally:
1. `python/Cargo.toml` removed `*.workspace = true` inheritance —
the python/ crate is intentionally outside the v2/ workspace
(ADR-117 §5.2) so it needs every `[package]` field local.
2. `python/pyproject.toml` `python-source = "python"` was wrong
because pyproject.toml lives at python/ — maturin was looking for
python/python/. Changed to `python-source = "."` so the
`wifi_densepose/` package directory sibling-to-pyproject is found.
3. `python/src/lib.rs` `#[pymodule] fn wifi_densepose_native` →
`#[pymodule] #[pyo3(name = "_native")] fn wifi_densepose_native`.
PyO3 generates `PyInit__native` from the pyo3-name attribute, which
must match the `module-name` in pyproject.toml's [tool.maturin]
block ("wifi_densepose._native"). Without this attribute the wheel
builds but `import wifi_densepose._native` fails with
ModuleNotFoundError.
## Local validation (P1 acceptance gate)
```
$ python -m venv .venv && .venv/Scripts/python -m pip install maturin pytest
$ VIRTUAL_ENV=… maturin develop --release
…
Finished `release` profile [optimized] target(s)
📦 Built wheel for abi3 Python ≥ 3.10
🛠 Installed wifi-densepose-2.0.0a1
$ .venv/Scripts/python -c 'import wifi_densepose; print(wifi_densepose.__version__, wifi_densepose.__rust_version__, wifi_densepose.hello())'
2.0.0a1 2.0.0-alpha.1 ok
$ .venv/Scripts/python -m pytest tests/ -v
tests/test_smoke.py::test_package_imports PASSED
tests/test_smoke.py::test_version_string_well_formed PASSED
tests/test_smoke.py::test_rust_version_surfaced PASSED
tests/test_smoke.py::test_build_features_listed PASSED
tests/test_smoke.py::test_hello_returns_ok PASSED
tests/test_smoke.py::test_native_module_private PASSED
======================== 6 passed in 0.05s =========================
```
P1 closed. Moving to P2 (core type bindings).
Refs #785, ADR-117 §6.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(adr-117/p2): Keypoint + KeypointType bindings — 23 new tests (29/29 GREEN)
Lands the first chunk of P2: PyO3 bindings for `Keypoint` and
`KeypointType` from `wifi_densepose_core`. Bound types surface to
Python as `wifi_densepose.Keypoint` / `wifi_densepose.KeypointType`.
## Design choices that affect the API surface
1. **`Confidence` is NOT bound as a separate class.** Users hate
wrapping a float in a constructor. Python-side, confidence is just
a `float in [0.0, 1.0]`; the binding validates on construction
(`ValueError` for out-of-range, matching the Rust core error).
2. **`KeypointType` is a `#[pyclass(eq, eq_int, hash, frozen)]` enum**
— hashable so users can drop it into dicts/sets (the most common
pattern in pose-analysis notebooks: `keypoints_by_type[k.type] = k`).
3. **`Keypoint.__init__` keyword-only `z`** so 2D users don't have to
write `None` and 3D users get a clear named arg:
`Keypoint(KeypointType.LeftWrist, 0.2, 0.4, 0.8, z=0.1)`.
4. **`Keypoint` is `#[pyclass(frozen)]`** — no in-place mutation. The
Rust core type is immutable through Copy + Hash + Eq, and exposing
setters from Python would create a copy-vs-reference inconsistency
between languages.
## Files
- `python/src/bindings/keypoint.rs` — 220 lines of `#[pymethods]`
wrappers + Rust↔Python enum round-trip
- `python/src/lib.rs` — `mod bindings { pub mod keypoint; }` +
`bindings::keypoint::register(m)?` call from `#[pymodule]`
- `python/wifi_densepose/__init__.py` — re-exports `Keypoint` and
`KeypointType` at the package root
- `python/tests/test_keypoint.py` — 23 tests covering:
- 17-element COCO ordering of `KeypointType.all()`
- index→type mapping for every variant
- snake_name matches COCO spec
- `is_face()` / `is_upper_body()` predicates
- hashability (the bug I caught when I added the set-based face
test — fixed by adding `hash` to the `#[pyclass]` attribute)
- 2D + 3D constructor variants
- position_2d / position_3d tuples
- is_visible threshold
- confidence validation (Err on out-of-range)
- distance_to (2D Euclidean, 3D Euclidean, fallback when one is 2D
and the other is 3D)
- __repr__ + __eq__
- the new `p2-keypoint-bindings` feature marker landed
## Local validation
\`\`\`
$ cd python && .venv/Scripts/python -m pytest tests/ -v
tests/test_smoke.py::test_package_imports PASSED
tests/test_smoke.py::test_version_string_well_formed PASSED
tests/test_smoke.py::test_rust_version_surfaced PASSED
tests/test_smoke.py::test_build_features_listed PASSED
tests/test_smoke.py::test_hello_returns_ok PASSED
tests/test_smoke.py::test_native_module_private PASSED
tests/test_keypoint.py::test_keypoint_type_all_returns_17 PASSED
…
======================== 29 passed in 0.06s =========================
\`\`\`
Wheel size after both bindings: still well under the 5 MB ADR §5.4
budget (release build with --strip on Windows: ~340 KB).
Also adds `python/.gitignore` to prevent the `.venv/` + `target/` +
`_native.abi3.pyd` artifacts from getting committed.
## What's left in P2
CsiFrame + PoseEstimate bindings land in the next iteration. They're
larger (CsiFrame has the subcarrier buffer; PoseEstimate has
17×Keypoint + BoundingBox + track_id + score). Pattern is now proven
so they go faster.
Refs #785, ADR-117 §6.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(adr-117/p2): BoundingBox + PersonPose + PoseEstimate — P2 COMPLETE (57/57 tests GREEN)
Lands the second + third chunks of P2: PyO3 bindings for `BoundingBox`,
`PersonPose`, `PoseEstimate` from `wifi_densepose_core`. Combined with
the prior Keypoint + KeypointType bindings (
v1256
|
||
|
ruv
|
753f0a23b7 |
docs(adr-118): integrate Soul Signature into BFLD ADRs 118/120/121/122
Wire the Soul Signature research (docs/research/soul/) into BFLD as a consent-based opt-in that runs at privacy_class = 1 (derived). BFLD becomes the policy-enforcement and compliance layer for Soul Signature; the two share the AETHER encoder, the witness chain, the RVF container, and cross_room.rs. ADR-118 §1.4 (new): comparison table of intents, consent models, ID spaces, and shared assets. Explains why the two systems are complementary, not antagonistic. ADR-120 §2.7 (new): dual-ID-space contract. - Default BFLD: class 2, daily-rotated rf_signature_hash for all. - Soul Signature opt-in: class 1, rotating hash for unenrolled + stable opaque person_id for enrolled. No collision. - Class 3 (restricted): Soul Signature disabled. Static enforcement via --features soul-signature feature gate. ADR-121 §2.6 (new): Soul Signature Recalibrate exemption + enrollment- quality gate. - SoulMatchOracle suppresses Recalibrate when high score traces to an enrolled person_id (matched outcome is intended, not an attack). - identity_risk_score doubles as enrollment-quality signal: Soul Signature enrollment requires score >= 0.65 sustained over the 60s window. - Exemption is asymmetric: unknown high-separability clusters still trigger Recalibrate. ADR-122 §2.7 (new): three Soul Signature HA entities exposed at class 1 only, structurally rejected at the Matter boundary. Fourth blueprint (enrolled-person arrival notification) ships under feature flag, default off, per-person opt-in. Co-Authored-By: claude-flow <ruv@ruv.net>v1251 |
||
|
ruv
|
2365f0c31b | Merge feat/adr-118-bfld into main: BFLD layer (6 ADRs + research bundle) v1.99.0-pip v1248 | ||
|
ruv
|
29233db6d5 |
docs(adr-118): BFLD — Beamforming Feedback Layer for Detection (6 ADRs + research bundle)
Introduce the Beamforming Feedback Layer for Detection: the RuView safety layer
that ingests WiFi BFI, measures identity-leakage risk, and structurally prevents
identity-correlated data from leaving the node by default.
ADRs (6):
- ADR-118: umbrella decision, crate scaffolding, 6-phase rollout (~10.5 wk)
- ADR-119: BfldFrame wire format, magic 0xBF1D_0001, deterministic serialization
- ADR-120: 4 privacy classes, BLAKE3 keyed-hash rotation, #[must_classify] default-deny
- ADR-121: 9-feature identity-risk scoring, coherence gate with hysteresis
- ADR-122: 6 HA entities, 3 Matter clusters, mosquitto ACL, cognitum-v0 federation
- ADR-123: Pi 5 / Nexmon production capture, AX210 dev path, ESP32-S3 self-only fallback
Research bundle (docs/research/BFLD/, 13,544 words):
- SOTA survey covering BFId (KIT, ACM CCS 2025) and LeakyBeam (NDSS 2025)
- Architectural soul: defensive sensing primitive, not surveillance lens
- Six-adversary threat model with attack trees and mitigations
- Privacy-gating mechanics with structural cross-site isolation proof
- Automation/integration surface (HA, Matter, MQTT, federation)
- Concrete implementation plan with reuse map
- Evaluation strategy with red-team protocol on KIT BFId dataset
- Draft ADR, GitHub issue, and public gist
Three structural invariants enforced by the type system, not policy:
I1 — Raw BFI never exits the node
I2 — Identity embedding is in-RAM-only (no Serialize impl)
I3 — Cross-site identity correlation is cryptographically impossible
(per-site BLAKE3 keyed-hash with daily epoch rotation)
References:
https://publikationen.bibliothek.kit.edu/1000185756 (BFId)
https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf (LeakyBeam)
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
be4efecbcd |
cog-ha-matter (ADR-116 P8): app-registry entry stub + release checklist
Two closing P8 deliverables that complete the local-side publishing
scaffolding. The remaining work is all credential-bearing user
action.
1. `cog/app-registry-entry.json` — the exact JSON payload to paste
into cognitum-one's `app-registry.json`. Schema discovered by
fetching the live registry (105 cogs, 11 categories) and
matching the existing `ruview-densepose` entry verbatim. Keys:
id, name, category, version, size_kb, difficulty, description,
featured, config[], sha256, binary_size
cog-ha-matter slots in under `category: "building"` (smart home
/ building automation — the natural HA / Matter category, vs
`network` which is more about transport bridges).
7 config[] entries mirror our CLI surface:
sensing_url, mqtt_host, mqtt_port, privacy_mode,
mdns_hostname, mdns_ipv4, no_mdns
Two post-build fields left as `<FILL_IN_...>` markers:
sha256 (paste from the workflow artifact's .sha256)
binary_size (wc -c < the binary)
Schema validated: all 10 required keys present, parses as JSON.
2. `cog/RELEASE-CHECKLIST.md` — one-page mechanical playbook with
four explicit "🔑 USER ACTION" gates. Each gate names exactly
what the user (or org admin) has to do that the pipeline cannot:
a) provision GCP_CREDENTIALS + HAS_GCP_CREDENTIALS org var
b) provision COGNITUM_OWNER_SIGNING_KEY GH secret
c) gcloud auth login (only if uploading locally)
d) PR app-registry.json into cognitum-one
Plus pre-release test gate, tag-push command, post-release
verification curl, and a rollback procedure using GCS object
versioning (per ADR-100 §"GCS misconfiguration risks").
Stop-condition check (cron's predicate: "ALL local-side publishing
scaffolding is complete and the only remaining work requires user
action"):
✅ cog/manifest.template.json
✅ cog/Makefile (build / sign / upload / verify / clean)
✅ cog/README.md
✅ cog/app-registry-entry.json (this commit)
✅ cog/RELEASE-CHECKLIST.md (this commit)
✅ .github/workflows/cog-ha-matter-release.yml (3 jobs, gated)
✅ dist/ handling (gitignored, created by make)
🔑 4 user-action gates explicitly enumerated in the checklist
The cron should STOP after this iter — the local-side scaffolding
is complete and the remaining work is the four named credential
gates that the pipeline cannot self-serve.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1235
v1234
|
||
|
ruv
|
3833929dcb |
cog-ha-matter (ADR-116 P8): CI release workflow + fix inherited filename bug
New `.github/workflows/cog-ha-matter-release.yml`:
* Triggers on `cog-ha-matter-v*` tag-push + manual dispatch
* Three jobs: build-x86_64, build-arm, publish-gcs
* x86_64: native ubuntu-latest cargo build
* arm: aarch64-unknown-linux-gnu via apt-installed gcc-aarch64-linux-gnu
linker (no `cross` dep needed — keeps workflow self-contained)
* Each build job runs make build-{arch} + make sign-{arch} +
gated Ed25519 sign step (skipped when COGNITUM_OWNER_SIGNING_KEY
secret is unset — workflow still produces unsigned artifacts so
we get build coverage now and signing later without re-merging)
* publish-gcs job gated on `vars.HAS_GCP_CREDENTIALS == 'true'`
so the workflow is safe to merge before credentials land —
no-op until the org admin sets the variable
* Uploads binary + sha256 + (optional) sig to
`gs://cognitum-apps/cogs/{arch}/cog-ha-matter-{arch}`
* Prints the app-registry.json snippet for the cognitum-one PR
(so the publish step's output is the exact JSON the user pastes)
Fixed a bug inherited from cog-pose-estimation's Makefile: the
precedent produces `dist/cog-cog-pose-estimation-arm` (double
`cog-` prefix because CRATE name already starts with `cog-`) but
the manifest URL has single prefix `cog-pose-estimation-arm`. The
upload path doesn't match the binary_url — a latent bug in the
pose cog's pipeline.
My copy now produces `dist/cog-ha-matter-arm` matching the
manifest URL `cog-ha-matter-{{ARCH}}`. Changed: Makefile (build /
sign / upload / verify / clean targets), workflow (artifact names
+ gsutil paths), README (local dry-run instructions). The
cog-pose-estimation precedent is unchanged — separate fix if/when
the user wants to align it.
What this iter does NOT do (P8 remaining):
* provision GCP_CREDENTIALS / COGNITUM_OWNER_SIGNING_KEY secrets
(user action — needs org admin access)
* actually run the workflow (needs a `cog-ha-matter-v0.1.0` tag
push, or workflow_dispatch from the Actions tab)
* append to app-registry.json in cognitum-one (separate repo PR)
Next iter: tag a v0.0.1-dev (so the workflow runs once + we see
any build-time errors on real CI runners) OR scaffold the
app-registry.json patch payload as a check-in doc.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
1e469aa336 |
cog-ha-matter (ADR-116 P8): scaffold cog/ publishing layout
Mirrors v2/crates/cog-pose-estimation/cog/ so the Seed runtime
treats cog-ha-matter identically — `cognitum cog install ha-matter`
behaves like `cognitum cog install pose-estimation`.
Files:
* cog/manifest.template.json — 9-field manifest with {{VERSION}}
+ {{ARCH}} slots, hand-edited by the Makefile signer
* cog/Makefile — same target set as cog-pose-estimation:
build / build-arm / build-x86_64
sign / sign-arm / sign-x86_64 (Ed25519 step is TODO,
blocked on COGNITUM_OWNER_SIGNING_KEY provisioning —
same blocker as cog-pose-estimation)
upload / upload-arm / upload-x86_64
manifest (delegates to `cargo run -- --print-manifest`)
release (= build + sign + upload + manifest)
verify (sha256sum vs sidecar)
clean
Adds `mkdir -p dist` to build steps so the gitignored dist/
folder is created on first build.
* cog/README.md — what this cog does, layout map, local dry-run
instructions, gcloud auth requirements, the JSON snippet to
paste into app-registry.json (in the separate cognitum-one
repo, not this one)
Local dist/ is intentionally not committed: top-level .gitignore
matches `dist/` globally, the Makefile creates it on demand.
What this commit does NOT do (P8 remaining):
* cross-compile build (needs `rustup target add
aarch64-unknown-linux-gnu x86_64-unknown-linux-gnu` + linker)
* sign the binaries (COGNITUM_OWNER_SIGNING_KEY not provisioned)
* gsutil cp to gs://cognitum-apps/ (needs user's gcloud auth)
* append to app-registry.json (lives in cognitum-one repo —
separate PR there)
Next iter: a CI workflow that runs `make build sign verify` on
tag-push, so the local-side pipeline is fully exercised even
without the production credentials.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1233
|
||
|
ruv
|
d4f0e12073 |
cog-ha-matter (ADR-116): P4 ✅ — mDNS wired into main, broker deferred
Two landings that flip P4 to shipped:
1. main.rs now actually registers the mDNS responder. New CLI:
--mdns-hostname (default: cog-ha-matter.local.)
--mdns-ipv4 (default: 127.0.0.1)
--no-mdns (skip for restrictive CI / multi-instance)
Responder boots after the publisher; failure logs WARN + falls
back to manual HA config instead of killing the cog. The
handle's Drop sends the mDNS goodbye packet on shutdown so HA's
discovery sees a clean service-leave (no stale device card).
2. Embedded rumqttd broker DEFERRED to v0.7 per dossier §8 ranking.
The dossier's prioritised v1 scope is:
1. --privacy-mode audit-only
2. cog manifest + Ed25519 signing + store listing
3. local SONA fine-tuning loop
4. HACS gold-tier integration
5. Matter Bridge (v0.8)
Embedded broker is not in that list. Every HA install already
has mosquitto or HA Core's built-in broker — adding ~2 MB of
binary + ACL config surface for marginal benefit didn't earn a
v1 slot. Documented as row 6 of §4 v1 scope table with explicit
v0.7 target.
P4 row updated to ✅: mDNS half complete (record-builder +
ServiceInfo + live responder + main.rs wiring), witness half
complete (chain + JSONL + file + Ed25519), embedded broker
explicitly deferred with rationale citation to dossier §8.
Stop-condition check:
* dossier has "Recommended scope" section ✅ (§8, folded into
ADR §4)
* P2 (cog scaffold) ✅
* P3 (MQTT publisher wrap) ✅
* P4 (Seed-native enhancements) ✅
Cron's stop predicate evaluates: P2-P4 shipped AND dossier has
the recommended-scope section → STOP. The loop should TaskStop
itself after this iter unless the user wants P5 (RuVector
thresholds), P8 (cog signing), or P9 (HACS repo) to keep going.
64/64 tests green.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1230
v1231
|
||
|
ruv
|
07b792715f |
cog-ha-matter (ADR-116 P4): live mDNS responder + handle
Closes the mDNS half of P4. `runtime::start_mdns_responder` binds
multicast via `mdns_sd::ServiceDaemon::new`, builds the
ServiceInfo from `MdnsService::to_service_info` (iter 9), and
registers — returning a typed handle that owns both daemon and
fullname.
Handle shape:
pub struct MdnsResponderHandle {
daemon: ServiceDaemon,
fullname: String,
}
impl MdnsResponderHandle {
pub fn fullname(&self) -> &str;
pub fn shutdown(self) -> Result<(), mdns_sd::Error>;
}
impl Drop for MdnsResponderHandle { /* best-effort */ }
Why explicit `shutdown` + best-effort `Drop`: a clean shutdown
sends a goodbye packet so HA's discovery integration sees the
service leave (good UX — no stale device card). `Drop` is the
fallback for panics / process termination but swallows errors
since panicking-in-Drop would mask the real failure.
1 new live-I/O test:
* mdns_responder_fullname_concatenates_instance_and_service_type
— actually binds multicast on the loopback adapter, registers,
asserts the fullname contains `_ruview-ha._tcp`, then
shutdown()s. Confirmed working on Windows; CI environments
where multicast bind is filtered will hit the gracefully-
skipping early return rather than failing the suite.
64/64 cog tests green (63 → 64).
ADR-116 P4: mDNS half ✅ (record-builder + ServiceInfo + live
responder), witness half ✅ (chain + JSONL + file + Ed25519).
Last piece is the embedded rumqttd broker so external mosquitto
becomes optional.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1229
|
||
|
ruv
|
34eced880f |
cog-ha-matter (ADR-116 P4): MdnsService -> mdns-sd ServiceInfo bridge
Pure conversion from our wire-format `MdnsService` to the
`mdns_sd::ServiceInfo` shape the responder daemon consumes. No
socket binding, no daemon registration yet — that lands next iter
as a `runtime::spawn_mdns_responder(info)` JoinHandle returning
helper, same shape as `runtime::spawn_publisher`.
* `MdnsService::to_service_info(hostname, ipv4) ->
Result<ServiceInfo, mdns_sd::Error>`
* `mdns-sd = "0.11"` added — aligned with the workspace pin from
wifi-densepose-desktop so the lockfile doesn't fork dalek-like
surfaces.
3 new tests:
* to_service_info_carries_service_type_and_port — locks that
`_ruview-ha._tcp` (with or without mdns-sd's trailing-dot
normalisation) and the control port round-trip through the
conversion
* to_service_info_propagates_txt_records — every locked TXT
key from iter 4 (cog_id, mqtt_port, privacy, proto, node_id,
cog_version) reachable via `get_property_val_str` on the
converted ServiceInfo
* to_service_info_does_not_silently_drop_caller_hostname —
locks the caller-side responsibility for the .local. suffix.
mdns-sd 0.11 accepts bare hostnames (verified empirically by
initial test expecting it to reject — it didn't), so the
wrapper layer must do the trailing-dot dance. Documenting
that via a named test catches future bumps where the lib
starts mutating the value.
63/63 cog tests green (60 → 63).
ADR-116 P4 now ⁶⁄₇: ✅ mDNS record-builder, ✅ chain, ✅ JSONL, ✅
file persistence, ✅ Ed25519 signing, ✅ ServiceInfo conversion;
⏳ daemon register + embedded broker.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1228
|
||
|
ruv
|
bb154d4e78 |
cog-ha-matter (ADR-116 P4): Ed25519 signing layer for witness chain
Closes the cryptographic-attestation gap in ADR-116 §2.2: every
witness event can now be signed by the Seed's Ed25519 key, with
verify available to any auditor holding the public key.
Module shape (`src/witness_signing.rs`, kept separate from
`witness::` so the hash chain stays usable without dalek linked
in — important for the wasm32 audit-verifier variant we'll ship
later):
* sign_event(event, &SigningKey) -> Signature
* verify_signature(event, &Signature, &VerifyingKey)
-> Result<(), SignatureVerifyError>
* signature_to_hex / signature_from_hex (128-char lowercase,
matches the witness hex convention)
* SignatureVerifyError::Invalid
* SignatureParseError::{Length, Hex}
Key design point: signature covers the SAME canonical bytes
witness::hash_event hashes. That means:
1. A signed event commits to the entire event content (kind,
payload, timestamp, seq, prev_hash) — no field can be
retroactively changed without invalidating both the hash AND
the signature.
2. The signature implicitly commits to the event's *chain
position* via prev_hash — splicing a signed event into a
different chain breaks verification.
Adds `ed25519-dalek = "2.1"` to cog-ha-matter (already in
workspace via ruv-neural, version kept aligned).
9 new tests:
* sign_and_verify_round_trip
* verify_rejects_signature_under_wrong_key
* verify_rejects_tampered_event (mutate payload after sign)
* verify_rejects_event_with_wrong_prev_hash (splice attack)
* signature_hex_round_trip
* signature_from_hex_rejects_wrong_length
* signature_from_hex_rejects_non_hex
* signature_is_deterministic_for_same_event_and_key
(locks Ed25519's determinism — catches future accidental
swap to a randomized scheme)
* different_events_produce_different_signatures
60/60 cog tests green (51 → 60). Key management is intentionally
out of scope here — the cog runtime reads the Seed's key from the
Cognitum control plane's secure store (separate concern).
ADR-116 P4 now ⁵⁄₆: ✅ mDNS record, ✅ chain, ✅ JSONL, ✅ file
persistence, ✅ Ed25519 signing; ⏳ responder + embedded broker.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1227
v1225
|
||
|
ruv
|
1f5b7b48c9 |
cog-ha-matter (ADR-116 P4): witness file persistence + chain-level verify
Closes the witness audit-bundle surface. The hash-chain primitive
+ JSONL serializer from earlier iters only handled one event at a
time; this lands the file-stream surface that operations actually
need:
* `WitnessChain::write_jsonl(&mut impl Write) -> io::Result<()>`
— streams every event as one line + `\n`, empty chain writes
zero bytes
* `WitnessChain::read_jsonl(impl BufRead) -> Result<WitnessChain,
WitnessReadError>` — parses event-by-event AND runs chain-level
`verify()` on the loaded chain, catching reordered or replayed
prefixes that per-event hashing alone misses
Critical security property: `read_jsonl` calls `WitnessChain::verify`
on the loaded chain BEFORE returning Ok. A forged bundle assembled
from two valid chains pasted together would slip past the
per-event hash check (each event's `this_hash` is internally
consistent) but the cross-event `prev_hash` linkage detects the
seam. Test `read_jsonl_chain_verify_catches_reordered_events`
locks this — swap two events in a 2-event bundle, see Verify error.
Error surface (new `WitnessReadError` enum):
* `Io { line_no, msg }` — read failure mid-stream
* `Parse { line_no, source }` — per-event from_jsonl_line failure
* `Verify { source }` — chain-level verify failure
`line_no` is 1-indexed so an auditor sees the same number their
text editor shows. Blank lines tolerated for hand-edited bundles.
7 new tests:
* empty chain writes zero bytes
* write→read round-trips a 3-event chain
* exactly N newlines for N events; trailing newline present
* blank lines / leading newline tolerated
* parse error surfaces with correct line_no
* reordered events caught by chain-level verify
* no-trailing-newline still loads the final event
51/51 cog tests green (44 → 51).
Co-Authored-By: claude-flow <ruv@ruv.net>
v1226
|
||
|
ruv
|
a3478ea3b5 |
cog-ha-matter (ADR-116 P4): witness JSONL persistence
Third P4 sub-unit: serialize/parse for the witness hash chain so
audit bundles can be written to disk and replayed.
Wire shape (one record per line, alphabetical field order locked):
{"kind":"...","payload_hex":"...","prev_hash":"...","seq":N,
"this_hash":"...","timestamp_unix_s":N}
Why alphabetical field order: auditors archive whole bundles and
hash them. A rebuild that reordered fields would silently
invalidate every archival hash — locking the order is what makes
the JSONL stable across compiler / serde-json upgrades.
Why hex everywhere: human-greppable, monospace-friendly, no base64
ambiguity, no Vec<u8> JSON-array ugliness. Same convention as
ADR-101's `binary_sha256`.
Critically, `from_jsonl_line` RE-VERIFIES `this_hash` against
the canonical bytes derived from the parsed fields. A tampered
bundle fires `WitnessParseError::HashMismatch` BEFORE the event
loads — the parser is itself an auditor.
New surfaces:
* `WitnessHash::from_hex` (with structured length/parse errors)
* `WitnessEvent::to_jsonl_line`, `from_jsonl_line`
* `WitnessParseError` enum: Json | MissingField | WrongType |
HashLength | HashHex | PayloadHex | PayloadLength | HashMismatch
* private `hex_encode` / `hex_decode` helpers (no `hex` crate dep)
10 new tests:
* jsonl round-trip preserves all fields
* jsonl line has no embedded \n / \r (one record per line)
* jsonl field order is alphabetical (byte-stable archival)
* parser rejects tampered payload via HashMismatch
* parser rejects non-hex characters in hash
* parser rejects missing field
* hex encode/decode round-trip across empty / single byte / 0xff /
UTF-8 / arbitrary bytes
* hex decode rejects odd-length input
* WitnessHash::from_hex round-trip
* WitnessHash::from_hex rejects wrong length
44/44 cog tests green (34 → 44).
ADR-116 P4 row enumerates 4 sub-units now: ✅ mDNS record-builder,
✅ witness chain primitive, ✅ witness JSONL persistence,
⏳ responder + embedded broker + Ed25519 signing.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1223
|
||
|
ruv
|
fe913b0ea7 |
cog-ha-matter (ADR-116 P4): pure witness hash-chain primitive
Second P4 unit: an append-only SHA-256 hash chain for tamper-evident
audit logging. ADR-116 §2.2 promised this for healthcare /
education / shared-housing deployments — this lands the primitive
with no key dependency so the next iter can layer Ed25519 signing
on top without touching the chain itself.
Module shape:
* `WitnessHash([u8; 32])` newtype + `WitnessHash::GENESIS` sentinel
* `WitnessEvent { seq, prev_hash, ts, kind, payload, this_hash }`
— once committed, every field is immutable
* `WitnessChain` — `append`, `tip`, `verify`, `events`
* `canonical_bytes` — length-prefixed serialization that prevents
the classic concatenation forgery
(`abc|def` ≠ `ab|cdef`)
* `WitnessVerifyError` — auditor-friendly error with `at: usize`
on every variant (SeqGap, PrevHashMismatch, HashMismatch)
13 new tests covering both happy path and active tampering:
* genesis hash all-zeros
* empty chain tip is genesis
* canonical bytes length-prefixed (anti-forgery)
* canonical bytes start with prev_hash (wire-format lock)
* append links to prev_hash
* seq monotonic from 0
* verify passes on clean chain
* verify catches tampered payload (fires HashMismatch)
* verify catches broken prev_hash link
* verify catches seq gap
* hash hex is 64 lowercase chars
* first event prev_hash == GENESIS (auditor anchor)
* different payloads → different hashes
Hash-chain over Merkle is the right tradeoff for the cog's event
rate (a few/min steady, dozens during a fall) — linear scan is
fine and we save the Merkle complexity for a future tier when
chains span days.
34/34 cog tests green (21 → 34).
ADR-116 P4 row updated to enumerate the three P4 sub-units shipped /
pending: (a) mDNS record-builder ✅, (b) witness hash-chain ✅, (c)
responder + embedded broker + Ed25519 signing pending.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1224
|
||
|
ruv
|
35722529bf |
cog-ha-matter (ADR-116 P4): pure mDNS service-record builder
Opens P4 with the smallest extractable unit: a pure builder that
produces the wire-format `MdnsService` the responder will publish
next iter. Splitting the record-builder from the responder lets
us:
* lock the TXT-record surface with named unit tests so drift
between the cog and the HA-side YAML auto-discovery binding
fires a test instead of silently breaking deployments,
* swap the responder library (mdns-sd / zeroconf / pnet) without
touching content,
* include the advertisement in `--print-manifest` for Seed
integration tests that can't boot tokio.
TXT surface (sorted, RFC 6763):
| cog_id | "ha-matter" |
| cog_version | CARGO_PKG_VERSION |
| node_id | identity.node_id |
| mqtt_port | u16 stringified |
| privacy | "1" | "0" |
| proto | "ruview-ha/1" |
9 new tests:
* service_type locked to `_ruview-ha._tcp`
* instance_name carries node_id
* control_port advertises the *control plane*, not MQTT
* privacy flag is "1"/"0" (HA config flow reads it byte-stable)
* proto version locked to ruview-ha/1 (bump is deliberate)
* cog_id in TXT matches crate constant
* txt_records sorted for byte-stable mDNS responses
* **PII leak guard**: TXT must NOT carry hr_bpm, br_bpm, pose_*,
keypoint, ssid, lat, lon, mac, rssi — broadcasts in cleartext
so a future "let's add hr_bpm for convenience" patch fires
here, not in a privacy incident.
* required-keys lock — adding is fine, removing/renaming breaks
every deployed Seed.
21/21 cog tests green (12 → 21).
ADR-116 P4 flipped pending → in progress, with the responder /
embedded broker / witness chain enumerated as the remaining P4
sub-units.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
c9f005c360 |
cog-ha-matter (ADR-116 P3): wire publisher::spawn into main.rs
P3 closes the publisher wiring loop. `main.rs` now:
1. builds `PublisherInputs` from CLI args via the pure helper
extracted last iter,
2. opens a `broadcast::channel::<VitalsSnapshot>(256)`,
3. calls `runtime::spawn_publisher(inputs, rx)` — a thin
wrapper around ADR-115's `publisher::spawn` that owns the
`Arc<MqttConfig>` wrap,
4. holds the tx side so the channel stays open until P3.5
wires the sensing-server bridge,
5. awaits Ctrl-C or unexpected publisher exit (logged at WARN).
Two new tests:
* `spawn_publisher_returns_live_handle_without_broker` — proves
the wiring compiles and the rumqttc event loop survives an
unreachable broker (it retries internally; we abort the handle
inside 100 ms). Catches breakage from a future refactor that
accidentally pre-validates host reachability.
* `default_state_channel_capacity_is_reasonable` — locks the
`DEFAULT_STATE_CHANNEL_CAPACITY = 256` default; a regression to
e.g. 1 would surface here instead of as a dropped frame in
production under bursty multi-Seed federation.
12/12 cog-ha-matter tests green (10 → 12).
ADR-116 phase table: P3 flipped from "in progress" to ✅ wiring done,
with the P3.5 follow-up (sensing-server `/v1/snapshot` WS bridge)
explicitly named.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1222
|
||
|
ruv
|
5723f505b7 |
cog-ha-matter (ADR-116 P3): extract pure publisher-input builder
Adds `runtime::build_publisher_inputs(host, port, privacy, identity)` —
the side-effect-free helper that turns the cog's CLI surface into the
`(MqttConfig, OwnedDiscoveryBuilder)` pair ADR-115's `publisher::spawn`
consumes. Keeps the tokio runtime wiring out of the pure unit so the
mDNS responder + Seed control plane (P4) can build the same inputs
from different sources without going through clap.
8 new tests lock the wire-format invariants:
* host/port round-trip into MqttConfig
* privacy_mode propagation (P1 dossier item 7, FDA Jan 2026)
* discovery_prefix defaults to "homeassistant"
* discovery carries node_id + sw_version + friendly_name
* via_device advertises COG_ID (ADR-101/102 device-registry shape)
* client_id includes node_id (lesson from ADR-115 iter 45-48 session
takeover post-mortem — two publishers sharing a client_id loop)
* tls defaults to Off for v1 LAN-only (lock against silent enablement)
* default_identity carries CARGO_PKG_VERSION + PID for uniqueness
Plus the existing 2 manifest tests → 10/10 green
(`cargo test -p cog-ha-matter --no-default-features --lib`).
Also lands the deep-researcher dossier (`docs/research/ADR-116-ha-...`)
that the ADR §3+§4 reference — it was produced last iter but only the
ADR was committed; this puts the source-of-truth into the tree so the
ADR's "8 sections, 30+ citations" claim is actually verifiable.
P3 status in the ADR phase table flipped from "pending" to "in progress"
with the helper named; next iter tokio::spawns publisher::run(...) in
main.rs and registers the mDNS responder.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|
ruv
|
56265023dc |
feat(cog-ha-matter): P2 scaffold + ADR-116 P1 research-dossier fold-in
cron iter 1. Three things landed atomically because they cross-cite:
P1 — research dossier complete
Deep-researcher agent (a4dd35950ffd) shipped
docs/research/ADR-116-ha-matter-cog-research.md: 8 sections,
30+ citations across Matter / HACS / cog arch / local-AI /
federation / competitors / regulatory / v1 scope. Key
findings folded into ADR-116 §3 and §4:
- Matter device class: OccupancySensor (0x0107) +
RFSensing feature on cluster 0x0406 (1.4 rev 5)
- ESP32-C6 Thread Border Router: one Kconfig flag away
(CONFIG_OPENTHREAD_BORDER_ROUTER=y)
- HACS quality tier: target Gold (repairs + diagnostics +
reconfiguration), start from hacs.integration_blueprint
- CSA cert: ~$30-42k/yr — skip for v1, "Works with HA"
positioning instead
- Cog RAM/CPU: 128 MB / 15% on the Seed; 10 KB INT8
semantic-primitive classifier fits without PSRAM
- SONA: <100 µs/query confirmed by ruvllm-esp32 v0.3.3
- FDA Jan 2026 wellness guidance covers HR / sleep / activity
anomaly when marketed as "anomaly notification" not "diagnosis"
- Competitor moat: Aqara FP300 / TOMMY / ESPectre all lack
HR + BR + pose + semantic + witness simultaneously
P2 — cog crate scaffold compiles
v2/crates/cog-ha-matter/ created with cog-pose-estimation as
precedent shape (ADR-101). Files:
- Cargo.toml: depends on wifi-densepose-sensing-server with
--features mqtt + wifi-densepose-hardware for the ADR-110
SyncPacket bridge.
- src/lib.rs: COG_ID = "ha-matter", MDNS_SERVICE_TYPE
"_ruview-ha._tcp", DEFAULT_CONTROL_PORT 9180.
- src/manifest.rs: typed CogManifest (8 fields) mirroring
cog-pose-estimation's manifest.template.json. Round-trip
test locks the JSON wire shape; id-constant test guards
against rename drift.
- src/main.rs: clap CLI with --sensing-url / --mqtt-host /
--mqtt-port / --privacy-mode / --print-manifest. The
--print-manifest flag emits the build-time template with
{{VERSION}} / {{ARCH}} placeholders for the signer.
- v2/Cargo.toml: cog-ha-matter added as workspace member.
Verification:
cargo check -p cog-ha-matter --no-default-features → green
cargo test -p cog-ha-matter --no-default-features --lib
→ 2/2 manifest tests pass
ADR-116 §3 + §4 + §5 (phases) updated to mark P1+P2 ✅ done and
seat the recommended v1 scope (privacy-mode audit-only → cog
signing → SONA loop → HACS gold → Matter Bridge as v0.8) ranked
by build cost × user impact per the dossier.
P3 (next iter): wrap the existing ADR-115 MQTT publisher as the
cog's main loop. The scaffold returns SUCCESS immediately today.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1221
|
||
|
ruv
|
f751740d3d |
docs(adr): ADR-116 — Home Assistant + Matter as a Cognitum Seed cog
Proposes `cog-ha-matter` as a Cognitum Seed cog packaging the
ADR-115 HA-DISCO + HA-MIND surfaces as a first-class Seed-installable
artifact, rather than configuration of an external sensing-server.
P1 — research dossier in progress (deep-researcher agent), output at
`docs/research/ADR-116-ha-matter-cog-research.md`.
Seed-native enhancements vs the ADR-115 sensing-server flag:
- Embedded mosquitto (optional, for Seeds without external broker)
- mDNS service advertisement (_ruview-ha._tcp)
- RuVector-backed semantic-primitive thresholds (SONA adaptation,
per-home learning rather than static YAML)
- Ed25519 witness chain for state transitions (regulated deployments)
- OTA firmware coordination for the mesh's ESP32-C6 nodes
- Multi-Seed federation via ADR-110 ESP-NOW substrate (≤100 µs
sync enables cross-Seed dedup of events like falls in shared rooms)
7 open questions tracked for the research dossier to answer:
Matter Bridge vs Matter Root, Thread Border Router feasibility,
HACS value-add, CSA cert cost/timeline, cog binary RAM budget,
ruvllm latency, HIPAA/FDA classification.
10 implementation phases scaffolded. Tracking issue to file once
research lands. PR for the cog binary in P2.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1220
|
||
|
ruv
|
db6df747b9 |
docs(ha): add cross-industry application examples to home-assistant.md
Add an 'Applications — what people actually do with this' section
above References, grouping real-world uses by category so prospective
users can pick what matches their space without having to invent
their own automations from the entity catalog.
Categories (7 tables, ~70 example use cases):
- Personal & home (goodnight routine, wake-up, meeting mode,
bathroom fan, forgotten stove, pet-only at home, sleep tracking,
toddler safety, pre-arrival lighting)
- Healthcare & assisted living (fall detection + escalation,
elderly inactivity anomaly, privacy-mode care, sleep apnea,
post-surgery, dementia wandering, bathroom timeout)
- Security & safety (auto-arm, intrusion, through-wall verification,
silent distress, garage / outbuilding, child safety zones)
- Commercial buildings & retail (office occupancy, demand-controlled
HVAC, meeting room truth, retail dwell + heat-map, queue length,
cleaning verification, lone-worker safety)
- Industrial & infrastructure (control rooms, restricted zones,
equipment rooms, hazardous area, construction after-hours,
maritime quarters)
- Education & public spaces (classroom occupancy, library, lecture
hall attendance, restroom signage, gym capacity, transit platforms)
- Energy & sustainability (per-room lighting, smart thermostat
zoning, vampire-load cut-off, solar / battery dispatch tuning,
cold-chain monitoring)
- Research, prototyping & developer use
Plus a 'Combining entities — recipe patterns' section that captures
5 reusable automation patterns (negative+duration trip wire, two-state
agreement guard, threshold+cooldown, calendar-vs-reality, privacy-mode
semantic-only) so users can build their own without reading the entity
reference cover-to-cover.
Plus a 'What about regulated environments?' subsection that names
the HIPAA / GDPR / CCPA properties of --privacy-mode + semantic-only
publishing — the architectural win for healthcare / education /
shared-housing deployments.
Co-Authored-By: claude-flow <ruv@ruv.net>
v1219
|
||
|
ruv
|
4bbb004f2d |
docs(readme): tighten ADR-079 caveat + drop What's-new callout
Tighten the ADR-079 camera-supervised limitation line and remove the prominent iter-50 'What's new (2026-05-23)' callout block — both preferred local edits. Co-Authored-By: claude-flow <ruv@ruv.net>v1218 |
||
|
ruv
|
62af91beb1 |
docs(readme): add 'What's new (2026-05-23)' callout for ADR-110 + ADR-115
Iter 50 — both ADRs merged today (PR #764 + PR #778). README's beta-software warning block was the natural location for a release callout above the main pitch; users hitting the README see today's shipped work first. Two-bullet block: - ADR-110 ESP32-C6 firmware substrate at v0.7.0-esp32 with the headline measured numbers (99.56 % match / 104 µs stdev / 3.95x EMA suppression) and the host-side surface (decoders + REST + Prometheus + WebSocket). - ADR-115 HA+Matter integration with the entity-count / blueprint / Lovelace count and the privacy-mode architectural win. Both link to their ADRs + PRs so reviewers can follow back. Co-Authored-By: claude-flow <ruv@ruv.net>v1216 v1217 |
||
|
rUv
|
249d6c327f |
ADR-115: Home Assistant + Matter integration (#778)
Closes ADR-115's MQTT track (HA-DISCO + HA-MIND + HA-FABRIC scaffolding). Headline: - 21 entity kinds per node (11 raw + 10 semantic primitives) - MQTT auto-discovery with HA conventions - Matter Bridge scaffolding (SDK wiring deferred to v0.7.1 per ADR §9.10) - Privacy mode strips biometrics at the wire, semantic primitives keep working - 420+ lib tests, mosquitto-backed integration tests, property-based fuzzing - 8 starter HA Blueprints + 3 Lovelace dashboards shipped Tracking issue: #776 |
||
|
rUv
|
00a234eda8 |
ADR-110: ESP32-C6 firmware extension (#764)
Closes the firmware-side ADR-110 design at v0.7.0-esp32 after a 38-iter /loop SOTA sprint. Headline (bench, COM9+COM12 ESP32-C6): - 99.56% cross-board RX, 104.1 µs smoothed offset stdev (≤100 µs §2.4 target met) - 3.95× EMA suppression, 1.4 ppm crystal skew preserved 4 firmware releases: v0.6.7 / v0.6.8 / v0.6.9 / v0.7.0-esp32. 42 ADR-110 unit tests, 1761 v2 workspace tests, full Firmware CI + QEMU green.v1201 |
||
|
rUv
|
5d544126ee |
fix(ui): unbreak viz.html — OrbitControls importmap, WS URL, toast NPE (#760) (#773)
* fix(ui): unbreak viz.html — OrbitControls importmap, WS URL, toast NPE (#760) Three independent bugs were stacking to make ui/viz.html unusable from `main`: 1. Three.js r160 removed `examples/js/OrbitControls.js`, so the script-tag load 404'd and `new THREE.OrbitControls(...)` threw. Switch to an importmap that pulls the ES module build, then re-expose `window.THREE` and `THREE.OrbitControls` so the existing component modules (scene.js, body-model.js, …) keep working without a wider refactor. 2. The WebSocket client was hardcoded to `ws://localhost:8000/ws/pose`, but the sensing-server listens on `--ws-port` (8765 default, 3001 in the Docker image) at `/ws/sensing`. Reuse the existing `buildSensingWsUrl()` helper from `sensing.service.js` so port pairings are handled centrally, and add a `?ws=…` query-string override for non-standard setups. The websocket-client.js default is also updated to derive from `window.location` instead of the dead `:8000/ws/pose` literal. 3. `ToastManager.show()` called `this.container.appendChild(...)` even when `init()` had never been called, throwing a TypeError that killed the rest of page initialization. Auto-init the container lazily on first show (patch from issue reporter). Closes #760. Co-Authored-By: claude-flow <ruv@ruv.net> * fix(ui): single module script + mutable THREE — OrbitControls validated Browser validation against the previous commit caught two stacked issues: 1. `import * as THREE from 'three'` returns a frozen Module Namespace Object — assignment `THREE.OrbitControls = OrbitControls` silently no-ops, so the global never gets the OrbitControls reference. 2. Two separate `<script type="module">` blocks (one installing the THREE global, one consuming it via Scene) are independently async-resolved. The second can finish dependency loading first and call `new THREE.OrbitControls(...)` before the first script has run. Fixed by spreading the namespace into a plain mutable object and merging all initialization into a single module script with `await import()` for component modules. Order is now strictly: import THREE → install window.THREE → import components → run init(). Validated via agent-browser: page logs `[VIZ] Initialization complete`, WebSocket targets the correct `ws://127.0.0.1:3001/ws/sensing` endpoint (derived from buildSensingWsUrl), toast lazy-init confirmed via eval. Co-Authored-By: claude-flow <ruv@ruv.net>v1160 |
||
|
rUv
|
004a63e82d |
fix(security): audit — fix RUSTSEC vulns, clippy warnings, dead code (#769)
- Upgrade openssl to 0.10.78 (CVE-2026-41676), jsonwebtoken to 9.4 - Suppress unmaintained-only/no-CVE advisories in .cargo/audit.toml with per-entry rationale - Fix all `cargo clippy --all-targets -- -D warnings` errors across 35 crates: derivable_impls, needless_range_loop, map_or→is_some_and/ is_none_or, await_holding_lock (drop MutexGuard before .await), ptr_arg (&mut Vec→&mut [T]), useless_conversion, approximate_constant (2.718→E, 3.14→PI), field_reassign_with_default, manual_inspect, useless_vec, lines_filter_map_ok, print_literal, dead_code - Apply `cargo fmt --all` - Pre-existing test failure in wifi-densepose-signal (test_estimate_occupancy_noise_only) is not introduced by this PRv1155 |