# Which Crates Are Affected by Changes to the OpenLogi Wire Format: A Complete Guide

> Discover the seven crates affected by OpenLogi wire format changes. This guide details synchronization needs from core IPC to client interfaces like CLI and GUI.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: deep-dive
- Published: 2026-09-11

---

**Seven crates across the OpenLogi workspace require synchronization when the wire format changes, ranging from the core `openlogi-ipc` crate that defines `PROTOCOL_VERSION` to the HID++ abstraction layer in `openlogi-core` and all client interfaces including CLI, desktop GUI, and overlay components.**

Changes to the OpenLogi wire format impact nearly every component in the AprilNEA/OpenLogi repository. When the binary protocol evolves, the `PROTOCOL_VERSION` constant must increment, and developers must update serialization logic across the entire workspace to maintain compatibility between the agent, desktop clients, and command-line tools.

## The Canonical Definition in openlogi-ipc

The `openlogi-ipc` crate serves as the single source of truth for the OpenLogi wire format. In [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs), the `PROTOCOL_VERSION` constant defines the current protocol revision, while this crate also houses the serialization and deserialization logic for all inter-process communication (IPC) messages. Any modification to message structures, field ordering, or encoding rules originates here and cascades to dependent crates.

## Downstream Crates Requiring Version Synchronization

When `PROTOCOL_VERSION` increments, the following six crates must update their IPC-handling code to remain compatible with the new wire format.

### openlogi-overlay

The overlay agent relies on the protocol version during the initial handshake process. In [`crates/openlogi-overlay/src/session.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/session.rs), the code constructs an `Identity` using `Identity::new(..., PROTOCOL_VERSION)` to advertise its compatibility level to peers attempting to establish a session.

### openlogi-desktop

The desktop GUI validates the agent's protocol version before establishing communication channels. The version check in [`crates/openlogi-desktop/src/services/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/services/ipc.rs) compares the remote agent's advertised version against the local `PROTOCOL_VERSION` constant, implementing logic to handle downgrade scenarios or reject incompatible connections.

### openlogi-cli

The command-line interface verifies agent compatibility before executing administrative commands. In [`crates/openlogi-cli/src/cmd/list.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/cmd/list.rs), the CLI performs explicit version comparisons to ensure the connected agent speaks a compatible protocol dialect, preventing undefined behavior against newer or older agent versions.

### openlogi-agent

The agent process advertises its protocol version and validates takeover holders attempting to assume control. In [`crates/openlogi-agent/src/server.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/server.rs), the server constructs its identity using `Identity::mine(..., PROTOCOL_VERSION)` and validates the version of any peer requesting a takeover to ensure protocol alignment.

### openlogi-agent-core

Core observable state includes the protocol version in IPC snapshots transmitted to clients. The snapshot formation code in [`crates/openlogi-agent-core/src/observable.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent-core/src/observable.rs) embeds `protocol_version: PROTOCOL_VERSION` into state data, allowing clients to verify compatibility when processing agent status updates.

### openlogi-core

Low-level HID++ data structures encode directly onto the wire without additional transformation. Files such as [`crates/openlogi-core/src/hid/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/hid/smartshift.rs) contain explicit documentation warnings stating that "variant order is wire format and changes require a `PROTOCOL_VERSION` bump." Similar architectural constraints exist in [`src/hid/route.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/hid/route.rs), [`src/hid/pairing.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/hid/pairing.rs), [`src/hid/error.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/hid/error.rs), [`src/hid/dpi.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/hid/dpi.rs), [`src/hid/backlight.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/hid/backlight.rs), [`src/device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/device.rs), and [`src/config/settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/config/settings.rs), meaning modifications to any of these structures necessitate a protocol version increment.

## Implementing Version Checks in Practice

Runtime version validation ensures compatibility between distributed OpenLogi components. When establishing an IPC session, code constructs an `Identity` that encapsulates the current protocol revision:

```rust
use openlogi_ipc::{Identity, PROTOCOL_VERSION, Compat};

let identity = Identity::new(serving, Compat::from(PROTOCOL_VERSION));

```

The desktop client implements defensive version checking to handle protocol drift between distributed components:

```rust
match version {
    v if v == PROTOCOL_VERSION => { /* compatible */ }
    v if v < PROTOCOL_VERSION => { /* older agent – downgrade */ }
    _ => { /* newer agent – reject */ }
}

```

## Summary

- **Seven crates** require updates when the OpenLogi wire format changes: `openlogi-ipc`, `openlogi-overlay`, `openlogi-desktop`, `openlogi-cli`, `openlogi-agent`, `openlogi-agent-core`, and `openlogi-core`.
- The `PROTOCOL_VERSION` constant defined in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs) serves as the single source of truth for protocol compatibility across the workspace.
- Runtime version checks occur in `openlogi-desktop` and `openlogi-cli` to prevent communication with incompatible agent versions.
- Binary layout changes in `openlogi-core` HID++ structures automatically necessitate protocol version bumps due to direct wire encoding without abstraction layers.

## Frequently Asked Questions

### Where is the OpenLogi wire format version defined?

The canonical definition resides in the `openlogi-ipc` crate within [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs), where the `PROTOCOL_VERSION` constant specifies the current protocol revision. This crate also contains the serialization logic for all IPC messages exchanged between agents and clients according to the AprilNEA/OpenLogi source code.

### Why does openlogi-core affect the wire format?

The `openlogi-core` crate implements low-level HID++ protocol structures that serialize directly to binary for transmission over USB or IPC channels. Files like [`crates/openlogi-core/src/hid/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/hid/smartshift.rs) explicitly document that variant ordering constitutes wire format, meaning any change to these data structures requires a `PROTOCOL_VERSION` increment to prevent deserialization errors in distributed components.

### How do OpenLogi clients validate protocol compatibility?

Client crates such as `openlogi-desktop` and `openlogi-cli` import `PROTOCOL_VERSION` from `openlogi-ipc` and compare it against the version advertised by the agent during connection establishment. In [`crates/openlogi-desktop/src/services/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/services/ipc.rs), the client handles three scenarios: exact version matches proceed normally, older agent versions trigger downgrade logic, and newer agent versions are rejected to prevent undefined behavior in the communication protocol.

### What happens if PROTOCOL_VERSION is not bumped after wire format changes?

Failure to increment `PROTOCOL_VERSION` after modifying wire-format structures results in runtime deserialization errors, connection failures, or silent data corruption between mismatched OpenLogi components. The agent and clients rely on this constant to negotiate compatible communication channels, and version mismatches cause immediate session termination or parsing failures.