frank/ruvnet--RuView
1
0
Fork 0
mirror of https://github.com/ruvnet/RuView synced 2026-08-07 20:01:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(adr-118/p3.6): IdentityFeatures canonical-bytes encoder (137/137 GREEN)

Browse Source 
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>
This commit is contained in:
ruv
2026-05-24 16:18:33 -04:00
parent 29f23cb97e
commit ea98ceb335
4 changed files with 278 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
v2/crates/wifi-densepose-bfld/src/emitter.rs
+19 -23
View File
@@ -19,6 +19,7 @@
use crate::coherence_gate::{CoherenceGate, NullOracle, SoulMatchOracle};
use crate::embedding_ring::EmbeddingRing;
use crate::identity_features::IdentityFeatures;
use crate::identity_risk::{score, GateAction};
use crate::signature_hasher::SignatureHasher;
use crate::{BfldEvent, IdentityEmbedding, PrivacyClass};
@@ -142,21 +143,23 @@ impl BfldEmitter {
) -> Option<BfldEvent> {
let risk = score(inputs.sep, inputs.stab, inputs.consist, inputs.risk_conf);
// Compute the derived rf_signature_hash BEFORE moving `embedding` into
// the ring. Derived hash uses the embedding bytes when present and
// falls back to the canonical risk-factor bytes otherwise.
// Compute the derived rf_signature_hash BEFORE moving `embedding`
// into the ring. The IdentityFeatures encoder (iter 18) consolidates
// the embedding vs risk-factor selection behind a single canonical-
// bytes path; same wire bytes as the iter-16 inline encoding.
let derived_hash: Option<[u8; 32]> = self.signature_hasher.as_ref().map(|h| {
let unix_secs = inputs.timestamp_ns / NS_PER_SEC;
if let Some(emb) = &embedding {
let bytes: Vec<u8> = emb
.as_slice()
.iter()
.flat_map(|f| f.to_le_bytes())
.collect();
h.compute_at(unix_secs, &bytes)
} else {
h.compute_at(unix_secs, &canonical_risk_bytes(&inputs))
}
let day_epoch = SignatureHasher::day_epoch_from_unix_secs(unix_secs);
let features = match &embedding {
Some(emb) => IdentityFeatures::from_embedding(emb),
None => IdentityFeatures::from_risk_factors(
inputs.sep,
inputs.stab,
inputs.consist,
inputs.risk_conf,
),
};
features.compute_hash(h, day_epoch)
});
if let Some(emb) = embedding {
@@ -204,13 +207,6 @@ impl BfldEmitter {
}
}
/// Canonical byte layout for the risk-factor tuple. Used by the hasher
/// fallback when no embedding is supplied.
fn canonical_risk_bytes(inputs: &SensingInputs) -> [u8; 16] {
let mut buf = [0u8; 16];
buf[0..4].copy_from_slice(&inputs.sep.to_le_bytes());
buf[4..8].copy_from_slice(&inputs.stab.to_le_bytes());
buf[8..12].copy_from_slice(&inputs.consist.to_le_bytes());
buf[12..16].copy_from_slice(&inputs.risk_conf.to_le_bytes());
buf
}
// canonical_risk_bytes removed in iter 18 — superseded by
// IdentityFeatures::from_risk_factors().canonical_bytes() which uses the
// same little-endian f32 layout.
v2/crates/wifi-densepose-bfld/src/identity_features.rs
+116
View File
@@ -0,0 +1,116 @@
//! `IdentityFeatures` — typed canonical-bytes encoder for `SignatureHasher`.
//!
//! Wraps the two possible feature sources (a borrowed [`IdentityEmbedding`] or
//! the four-tuple of risk factors) behind a single API so callers don't need
//! to know which one ultimately feeds the BLAKE3 keyed hash. Replaces the
//! ad-hoc `canonical_risk_bytes` + inline embedding-flatten paths that lived
//! in `emitter.rs` through iter 17.
//!
//! Borrowing semantics:
//! - `IdentityFeatures::Embedding(&IdentityEmbedding)` is the **preferred**
//! source — it carries the AETHER cluster identity directly.
//! - `IdentityFeatures::RiskFactors { .. }` is the fallback used when the
//! per-frame embedding is unavailable.
//!
//! Both variants emit canonical little-endian f32 bytes. Embedding produces
//! `EMBEDDING_DIM * 4` bytes (512 by default); risk factors produce
//! [`RISK_FACTOR_BYTES`] bytes (16).
#![cfg(feature = "std")]
use crate::signature_hasher::{SignatureHasher, RF_SIGNATURE_LEN};
use crate::{IdentityEmbedding, EMBEDDING_DIM};
/// Wire-form length for the `RiskFactors` variant (4 × f32 little-endian).
pub const RISK_FACTOR_BYTES: usize = 16;
/// Borrowed feature source for the signature hasher.
#[derive(Debug)]
pub enum IdentityFeatures<'a> {
/// Preferred: a borrowed identity embedding. The embedding stays in-RAM
/// (invariant I2) — this enum holds only a reference.
Embedding(&'a IdentityEmbedding),
/// Fallback: the four risk-score factors. Less identity-stable than the
/// embedding, but always available even when the encoder is offline.
RiskFactors {
/// `identity_separability_score`.
sep: f32,
/// `temporal_stability`.
stab: f32,
/// `cross_perspective_consistency`.
consist: f32,
/// Risk-score sample confidence factor.
conf: f32,
},
}
impl<'a> IdentityFeatures<'a> {
/// Build from a borrowed embedding (preferred path).
#[must_use]
pub const fn from_embedding(emb: &'a IdentityEmbedding) -> Self {
Self::Embedding(emb)
}
/// Build from the risk-factor four-tuple (fallback path).
#[must_use]
pub const fn from_risk_factors(sep: f32, stab: f32, consist: f32, conf: f32) -> Self {
Self::RiskFactors {
sep,
stab,
consist,
conf,
}
}
/// Predicted wire length without allocating.
#[must_use]
pub const fn canonical_byte_len(&self) -> usize {
match self {
Self::Embedding(_) => EMBEDDING_DIM * 4,
Self::RiskFactors { .. } => RISK_FACTOR_BYTES,
}
}
/// Append canonical little-endian bytes to `out`. Useful for callers that
/// already own a buffer (avoids the `canonical_bytes` allocation).
pub fn write_canonical_bytes(&self, out: &mut Vec<u8>) {
out.reserve(self.canonical_byte_len());
match self {
Self::Embedding(emb) => {
for f in emb.as_slice() {
out.extend_from_slice(&f.to_le_bytes());
}
}
Self::RiskFactors {
sep,
stab,
consist,
conf,
} => {
out.extend_from_slice(&sep.to_le_bytes());
out.extend_from_slice(&stab.to_le_bytes());
out.extend_from_slice(&consist.to_le_bytes());
out.extend_from_slice(&conf.to_le_bytes());
}
}
}
/// Allocating convenience wrapper around [`Self::write_canonical_bytes`].
#[must_use]
pub fn canonical_bytes(&self) -> Vec<u8> {
let mut v = Vec::with_capacity(self.canonical_byte_len());
self.write_canonical_bytes(&mut v);
v
}
/// Drive `hasher` with this feature source at the given `day_epoch`. The
/// returned hash is what the emitter publishes as `rf_signature_hash`.
#[must_use]
pub fn compute_hash(
&self,
hasher: &SignatureHasher,
day_epoch: u32,
) -> [u8; RF_SIGNATURE_LEN] {
hasher.compute(day_epoch, &self.canonical_bytes())
}
}
v2/crates/wifi-densepose-bfld/src/lib.rs
+4
View File
@@ -21,6 +21,8 @@ pub mod emitter;
#[cfg(feature = "std")]
pub mod event;
pub mod frame;
#[cfg(feature = "std")]
pub mod identity_features;
pub mod identity_risk;
#[cfg(feature = "std")]
pub mod payload;
@@ -36,6 +38,8 @@ pub use emitter::{BfldEmitter, SensingInputs};
pub use event::BfldEvent;
pub use embedding::{IdentityEmbedding, EMBEDDING_DIM};
pub use embedding_ring::{EmbeddingRing, RING_CAPACITY};
#[cfg(feature = "std")]
pub use identity_features::{IdentityFeatures, RISK_FACTOR_BYTES};
pub use identity_risk::{score as identity_risk_score, GateAction};
pub use frame::{BfldFrameHeader, BFLD_MAGIC, BFLD_VERSION, BFLD_HEADER_SIZE};
#[cfg(feature = "std")]