How to Update the IPC Protocol Version in OpenLogi

To update the IPC protocol version in OpenLogi, increment the PROTOCOL_VERSION constant in crates/openlogi-ipc/src/ipc.rs, update the hard-coded assertion in crates/openlogi-ipc/tests/wire_format.rs, and run the wire-format test suite to regenerate golden fixtures and verify compatibility.

OpenLogi's inter-process communication (IPC) protocol is versioned by a single source-of-truth constant that ensures the GUI, overlay, agent, CLI, and other components share a compatible wire format. When you need to update the IPC protocol version in OpenLogi—whether for breaking schema changes or routine version increments—you only need to modify the central definition and its corresponding test assertion. The openlogi-ipc crate re-exports this constant, so downstream components automatically detect the new version without requiring individual code changes.

Locating the PROTOCOL_VERSION Definition

The canonical version number lives in the openlogi-ipc crate. In crates/openlogi-ipc/src/ipc.rs, the PROTOCOL_VERSION constant declares the current u32 value used across the entire system.

// crates/openlogi-ipc/src/ipc.rs
/// Current IPC protocol version. Increment when the wire format changes.
pub const PROTOCOL_VERSION: u32 = 29; // Current value

Any change to the wire format—such as reordering enum variants, adding fields, or modifying struct layouts—requires bumping this integer. The repository's lint rules mark such changes with explicit comments reminding contributors that a PROTOCOL_VERSION bump is mandatory.

Step-by-Step Protocol Version Update

Bump the PROTOCOL_VERSION Constant

Open crates/openlogi-ipc/src/ipc.rs and increment the constant to the new version number. For example, changing from version 29 to 30:

// crates/openlogi-ipc/src/ipc.rs
pub const PROTOCOL_VERSION: u32 = 30; // ← Updated from 29

This is the only definition you must edit. Because the constant is re-exported from the openlogi_ipc crate, the overlay, agent, desktop services, and CLI modules automatically reference the new value when compiled.

Sync the Version-Pin Test

The test suite enforces that the constant matches a hard-coded expectation to prevent accidental drift. Edit crates/openlogi-ipc/tests/wire_format.rs and update the assertion:

// crates/openlogi-ipc/tests/wire_format.rs
#[test]
fn protocol_version_is_pinned() {
    // The test ensures the constant stays in sync with the expected value.
    assert_eq!(PROTOCOL_VERSION, 30); // ← Updated expected value
}

This test acts as a safety lock, ensuring that developers intentionally change the version rather than letting it drift through refactoring.

Regenerate Golden Fixtures and Verify

Run the IPC wire-format test to regenerate any golden fixture files and confirm that serialization remains stable:

# From the repository root

cargo test -p openlogi-ipc --test wire_format

Successful execution indicates that all components agree on the new protocol version and that no unintentional wire-format changes slipped into the build.

Components That Consume the Version

Because PROTOCOL_VERSION is re-exported from the openlogi_ipc crate, several components automatically pick up the new version without manual edits:

• Overlay (crates/openlogi-overlay/src/agent.rs) – Validates the protocol version during the overlay-agent handshake
• Agent (crates/openlogi-agent/src/server.rs) – Embeds the version when constructing the agent's identity
• CLI (crates/openlogi-cli/src/cmd/list.rs) – Verifies CLI compatibility against the running agent's version
• Desktop GUI (crates/openlogi-desktop/src/services/ipc.rs) – Handles version negotiation on the GUI side

Handling Breaking Wire Format Changes

If your update includes actual modifications to the serialization schema—such as adding new message fields or changing enum discriminant values—you must perform additional steps beyond bumping the version constant:

1. Update the serialization/deserialization logic in the relevant IPC modules
2. Bump PROTOCOL_VERSION to signal the breaking change to peers
3. Update the wire-format tests to reflect the new schema
4. Regenerate golden files to capture the new byte-level representation

The version bump alone does not alter wire behavior; it merely labels the current format. Always pair version increments with the corresponding schema changes and documentation updates in docs/README.md or CHANGELOG.md to communicate impact to downstream developers.

Summary

• Single source of truth: The PROTOCOL_VERSION constant in crates/openlogi-ipc/src/ipc.rs defines the canonical version for all OpenLogi components.
• Two-file change: Update the constant definition and the matching assertion in crates/openlogi-ipc/tests/wire_format.rs.
• Automatic propagation: The overlay, agent, CLI, and desktop services automatically detect the new version through the openlogi_ipc crate re-export.
• Verification: Run cargo test -p openlogi-ipc --test wire_format to validate the bump and regenerate golden fixtures.
• Breaking changes: Pair version bumps with explicit schema updates and documentation to alert users of wire-format incompatibilities.

Frequently Asked Questions

Where is the IPC protocol version defined in OpenLogi?

The protocol version is defined as a pub const PROTOCOL_VERSION: u32 in crates/openlogi-ipc/src/ipc.rs within the openlogi-ipc crate. This file serves as the single source of truth for all IPC versioning across the OpenLogi ecosystem.

Do I need to update every crate when bumping the protocol version?

No. Only two locations require explicit edits: the constant definition in crates/openlogi-ipc/src/ipc.rs and the test assertion in crates/openlogi-ipc/tests/wire_format.rs. All other crates—including the overlay, agent, CLI, and desktop GUI—import PROTOCOL_VERSION from the openlogi_ipc crate and automatically receive the new value at compile time.

What happens if I forget to update the version-pin test?

The test suite will fail with an assertion error in crates/openlogi-ipc/tests/wire_format.rs. This intentional failure prevents accidental version drift, forcing developers to explicitly synchronize the expected value with the new constant before the build passes.

When must I regenerate golden wire-format fixtures?

You must regenerate golden fixtures whenever you run the wire-format tests after bumping the version. Execute cargo test -p openlogi-ipc --test wire_format from the repository root; the test suite automatically rebuilds fixture files if the serialization layout has changed, ensuring that the stored "known good" bytes match the current protocol schema.

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