What Is PROTOCOL_VERSION in OpenLogi and When Should It Be Bumped?

The PROTOCOL_VERSION constant in OpenLogi is a u32 wire-protocol version defined in crates/openlogi-ipc/src/ipc.rs that must be incremented only when breaking changes to the IPC data structures occur, ensuring binary compatibility between the GUI client and background agent.

OpenLogi uses inter-process communication (IPC) to coordinate between its graphical interface and background system agent. Because the transport layer relies on bincode for serialization—where field order, enum variants, and types are encoded verbatim—a strict versioning scheme is required to prevent data corruption when the two processes communicate.

What Is PROTOCOL_VERSION?

PROTOCOL_VERSION is a compile-time constant that defines the wire-protocol revision for OpenLogi’s IPC layer. According to the source code in [crates/openlogi-ipc/src/ipc.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-ipc/src/ipc.rs#L65), the current value is:

pub const PROTOCOL_VERSION: u32 = 30;

This constant lives in the IPC contract module and serves as the authoritative version identifier for both the client (GUI) and server (agent). When the two processes establish a connection, they exchange this value to verify compatibility before exchanging operational data.

When Should You Bump PROTOCOL_VERSION?

You must increment PROTOCOL_VERSION only when making a breaking change to any type that crosses the IPC boundary. Because bincode serializes data structures in declaration order with no field identifiers, structural modifications that alter the binary layout will cause deserialization failures if both sides do not agree on the format.

The following scenarios require a version bump:

Enum Variant Order Changes

Adding, removing, or reordering variants in IPC-exposed enums breaks compatibility because bincode encodes enum variants using their discriminant indices. For example, AgentRequest::ProtocolVersion is explicitly designated as variant 0 in [crates/openlogi-ipc/tests/wire_format.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-ipc/tests/wire_format.rs#L16-L18). If you insert a new variant before existing ones, the indices shift and the agent will misinterpret requests.

Struct Field Modifications

Changing the order or type of fields in structs like AgentStatus or AgentSnapshot alters the binary layout. Since bincode serializes fields in declaration order, inserting a field in the middle of a struct shifts all subsequent data, causing the receiving side to read garbage values.

Appending New Fields

While appending fields to the end of a struct is safer, it still requires a version bump if the new data is mandatory or changes the expected frame size. The existing comment history in ipc.rs documents such additions, noting that each expansion necessitates a protocol revision even when backward-reading might technically work.

Enum Discriminant Changes

Core enums such as PairingPhase and InventoryHealth carry explicit comments stating that modifications require a PROTOCOL_VERSION bump. Adding new states to these workflows changes the variant indices, which breaks the wire format.

Transport Configuration Changes

The IPC layer uses bincode's DefaultOptions for serialization. If you alter these options—for example, by enabling Fixint encoding or changing the byte order—you must bump the version because the binary representation changes entirely.

How Runtime Version Checking Works

When the OpenLogi GUI client connects to the background agent, it performs a handshake to validate compatibility. The implementation in [crates/openlogi-overlay/src/agent.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-overlay/src/agent.rs#L90-L95) retrieves the agent’s reported version and compares it against the client’s local PROTOCOL_VERSION:

// Runtime version validation during connection establishment
let connection = openlogi_ipc::client::connect().await?;
if connection.version != PROTOCOL_VERSION {
    eprintln!(
        "Incompatible IPC version: agent={}, client={}",
        connection.version, PROTOCOL_VERSION
    );
    // Abort or trigger a fallback to compatible binaries
    std::process::exit(1);
}

If the values differ, the client aborts immediately to prevent protocol errors. The CLI command in [crates/openlogi-cli/src/cmd/list.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-cli/src/cmd/list.rs) implements similar validation logic.

Testing Protocol Compatibility

OpenLogi guards against accidental wire-format changes using the protocol_version_is_pinned test located in [crates/openlogi-ipc/tests/wire_format.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-ipc/tests/wire_format.rs#L105). This test asserts the current value of PROTOCOL_VERSION against golden-byte snapshots.

When you deliberately modify IPC structures:

1. Update the golden test data to reflect the new binary format
2. Increment PROTOCOL_VERSION in ipc.rs
3. Run the test suite to verify the assertion passes

If you modify structures without bumping the version, the test suite will fail, reminding you to synchronize the constant with the structural changes.

Practical Example: Adding a New Field

When extending the AgentStatus struct with a new capability flag, you must append the field and increment the version:

#[derive(Serialize, Deserialize)]
pub struct AgentStatus {
    pub accessibility_granted: bool,
    // Existing fields...
    
    // NEW FIELD: Must be appended, not inserted
    pub new_feature_enabled: bool,
    pub protocol_version: u32,
}

After modifying the struct, update PROTOCOL_VERSION from 30 to 31 and regenerate the golden-byte tests to capture the new layout.

Summary

• PROTOCOL_VERSION is defined in crates/openlogi-ipc/src/ipc.rs as a u32 constant (currently 30) that locks the IPC wire format.
• Bump the version only when changing enum variants, struct fields, or transport settings that alter the binary serialization layout.
• Runtime checks in agent.rs and list.rs abort connections when version mismatches are detected.
• The test suite enforces manual version updates via protocol_version_is_pinned in wire_format.rs, preventing accidental format drift.

Frequently Asked Questions

What is the current value of PROTOCOL_VERSION in OpenLogi?

As implemented in the source code, the current value is 30, defined in crates/openlogi-ipc/src/ipc.rs at line 65. This value represents the 30th revision of the wire protocol since the project began tracking binary compatibility.

What happens if the client and agent have different PROTOCOL_VERSION values?

The connection will abort immediately. The GUI client queries the agent for its version during the handshake phase, and if the values do not match exactly, the client prints an incompatibility error and terminates. This prevents data corruption from mismatched serialization layouts.

Do I need to bump PROTOCOL_VERSION when adding non-breaking fields?

If the change is truly non-breaking—such as adding an optional field at the end of a struct that older clients can safely ignore—you might technically maintain compatibility. However, the OpenLogi project convention is to increment the version anyway to signal a format change. The golden-byte tests will force you to update the version constant when the binary representation changes, regardless of semantic compatibility.

Where is the PROTOCOL_VERSION validated during development?

The canonical validation occurs in crates/openlogi-ipc/tests/wire_format.rs via the protocol_version_is_pinned test. This test compares the current constant against serialized golden-byte snapshots. If you modify IPC structures without updating the version, this test fails, acting as a safety net against accidental protocol breaks.

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