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

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, 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, 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 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, 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, 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 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 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, src/hid/pairing.rs, src/hid/error.rs, src/hid/dpi.rs, src/hid/backlight.rs, src/device.rs, and 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:

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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}