# mimirs-bridge

![mimirs-bridge concept](../docs/assets/mimirs_bridge_concept.png)


Bidirectional protocol bridge for Zenoh-NATS communication. The only binary crate in the workspace.

## What It Does

- `bridge_zenoh_to_nats()`: Async task that subscribes to Zenoh key expressions and forwards samples to NATS subjects.
- `bridge_nats_to_zenoh()`: Async task that subscribes to NATS subjects and forwards messages to Zenoh key expressions.
- `zenoh_key_to_nats_subject()`: Converts `mimirs/signal/agent1` to `MIMIRS.SIGNAL.AGENT1`.
- `nats_subject_to_zenoh_key()`: Converts `MIMIRS.SIGNAL.AGENT1` to `mimirs/signal/agent1`.
- `HilbertPulse`: High-frequency state vector transmission for real-time resonance sensing.
- `EigenstateFrame`: Privacy-preserving structural sync with epsilon-noise injected singular values.

## What It Does NOT Do

- No memory storage, no encoding, no reservoir computing, no OTOC.
- No identity management, no contradiction detection.

## Public API

```rust
/// CLI arguments (clap derive)
pub struct Args {
    pub zenoh_peer: String,           // default: "tcp/127.0.0.1:7447"
    pub nats_server: String,          // default: "nats://127.0.0.1:4222"
    pub zenoh_to_nats_prefix: String, // default: "mimirs/signal/**"
    pub nats_to_zenoh_subject: String, // default: "MIMIRS.SIGNAL.>"
}

pub fn zenoh_key_to_nats_subject(key: &str) -> String;
pub fn nats_subject_to_zenoh_key(subject: &str) -> String;

pub async fn bridge_zenoh_to_nats(
    zenoh: Arc<zenoh::Session>,
    nats: Arc<async_nats::Client>,
    prefix: String,
);

pub async fn bridge_nats_to_zenoh(
    zenoh: Arc<zenoh::Session>,
    nats: Arc<async_nats::Client>,
    subject: String,
);

pub struct HilbertPulse {
    pub agent_id: AgentId,
    pub psi: Vec<f64>,
    pub timestamp_ns: u64,
}

impl HilbertPulse {
    pub fn new(agent_id: AgentId, psi: Vec<f64>) -> Self;
}

pub struct EigenstateFrame {
    pub agent_id: AgentId,
    pub eigenvectors: Vec<Vec<f64>>,
    pub singular_values: Vec<f64>,
}

impl EigenstateFrame {
    pub fn new_with_privacy(
        agent_id: AgentId,
        eigenvectors: Vec<Vec<f64>>,
        singular_values: Vec<f64>,
        epsilon: f64,
    ) -> Self;

    pub fn resonance(&self, other: &Self) -> f64;
}
```

## Running the Bridge

```bash
cargo run -p mimirs-bridge -- \
  --zenoh-peer tcp/127.0.0.1:7447 \
  --nats-server nats://127.0.0.1:4222 \
  --zenoh-to-nats-prefix "mimirs/signal/**" \
  --nats-to-zenoh-subject "MIMIRS.SIGNAL.>"
```

## Dependencies

- `mimirs-core`: Foundation types
- `mimirs-ha`: `MemorySignal` for event types
- `zenoh`: Zenoh mesh networking
- `async-nats`: NATS client
- `clap`: CLI argument parsing
- `futures`: Async stream processing
- `rand`: Noise generation for EigenstateFrame
- `serde`, `serde_json`: Serialization
- `tracing`, `tracing-subscriber`: Logging
- `testcontainers`, `testcontainers-modules` (dev): Integration test infrastructure
- `mimirs-agent` (dev): Integration test dependency

## Known Limitations

- The bridge does not handle backpressure. If NATS is slower than Zenoh, messages accumulate in memory.
- Subject/key mapping is a simple string transformation (replace `/` with `.` and change case). It does not handle all edge cases.
- The bridge spawns two independent tokio tasks. If one fails, the other continues running until the process is shut down.
