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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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