How to Update OpenLogi's Protocol Version and Regenerate Wire Format Tests

To update OpenLogi's protocol_version and regenerate wire format tests, you must bump the PROTOCOL_VERSION constant in crates/openlogi-ipc/src/ipc.rs, run the failing wire_format.rs test, copy the new hex output into the golden assertions, and verify the version is pinned in protocol_version_is_pinned().

OpenLogi's inter-process communication (IPC) uses a strictly versioned binary protocol. Any change affecting types that cross the IPC boundary—such as adding methods, adding enum variants, or reordering fields—requires a coordinated update to the protocol version and its corresponding golden-byte tests. This article walks through the exact workflow prescribed in the openlogi-ipc crate.

Understanding the Protocol Version Constant

The PROTOCOL_VERSION constant lives in crates/openlogi-ipc/src/ipc.rs and serves as the authoritative version identifier for all IPC peers.

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

This value is embedded in the Identity handshake sent at connection initialization:

Identity::new(..., Compat::from(PROTOCOL_VERSION))

The runtime checks for strict equality—a mismatch immediately aborts the handshake. This prevents version skew between the host and spawned agent processes.

Why Wire Format Changes Require Version Bumps

OpenLogi's wire format is append-only: method indices and enum variant orders are serialized directly into the binary payload. This design means:

• Existing method indices cannot be reordered or removed
• New methods must append to the end of the interface
• Enum variants must maintain stable disciminant values

When any of these invariants change, the serialized bytes shift. The golden tests in crates/openlogi-ipc/tests/wire_format.rs capture expected hex encodings for every IPC type. These tests fail when the actual encoding diverges, signaling that a version bump and regeneration are required.

Step-by-Step Workflow

Step 1: Update PROTOCOL_VERSION in ipc.rs

Edit crates/openlogi-ipc/src/ipc.rs and increment the constant:

// Before
pub const PROTOCOL_VERSION: u32 = 29;

// After
pub const PROTOCOL_VERSION: u32 = 30;

This change signals to all IPC clients that a wire-format change occurred.

Step 2: Run the Wire Format Test

Execute the golden-bytes test to expose the changed encodings:

cargo test -p openlogi-ipc --test wire_format

The test will fail with output showing the hex diff:

thread 'test::request_variant_order' panicked at 'wire encoding changed —
if intentional, bump PROTOCOL_VERSION and regenerate this golden
left: 00 01 02 ...', crates/openlogi-ipc/tests/wire_format.rs:74

The left side of the diff contains the new, correct hex encoding.

Step 3: Copy the New Hex into Wire Format Assertions

For each failing assert_wire! macro, replace the old literal with the hex from the failure message:

// Before regeneration
assert_wire(&AgentRequest::ProtocolVersion {}, "00");

// After regeneration (example—actual hex depends on your change)
assert_wire(&AgentRequest::ProtocolVersion {}, "00");

Repeat for every assertion that fails. The rest of the test file structure remains unchanged.

Step 4: Verify the Version Pin Test

Ensure protocol_version_is_pinned() asserts the updated constant:

#[test]
fn protocol_version_is_pinned() {
    assert_eq!(PROTOCOL_VERSION, 30);
}

This guarantees the version bump and golden regeneration occur in the same commit.

Step 5: Run the Full Test Suite

Validate no additional regressions:

cargo test -p openlogi-ipc

Or run the full workspace test suite for comprehensive coverage.

Step 6: Commit the Changes

Stage and commit:

• crates/openlogi-ipc/src/ipc.rs (version bump)
• crates/openlogi-ipc/tests/wire_format.rs (regenerated goldens)
• Any relevant documentation updates

The CI pipeline will re-run the golden tests, confirming correctness.

Key Files in the OpenLogi IPC System

File	Purpose
crates/openlogi-ipc/src/ipc.rs	Defines PROTOCOL_VERSION and core IPC types
crates/openlogi-ipc/tests/wire_format.rs	Golden-bytes tests for binary serialization stability
crates/openlogi-ipc/AGENTS.md	Official developer guide for IPC contract maintenance

Common Pitfalls

• Forgetting strict equality: The runtime does not negotiate versions—it requires exact matches.
• Partial regeneration: Update every failing golden assertion, not just the first one.
• Skipping the version pin test: protocol_version_is_pinned() must reflect the new constant or the commit is incomplete.

Summary

• Bump PROTOCOL_VERSION in crates/openlogi-ipc/src/ipc.rs for any IPC-affecting change
• Run cargo test -p openlogi-ipc --test wire_format to generate new golden hex values
• Copy the left-side hex from failure messages into assert_wire! calls
• Verify protocol_version_is_pinned() asserts the updated version
• Commit version bump, regenerated tests, and documentation together

Frequently Asked Questions

What happens if I forget to bump PROTOCOL_VERSION?

The host and agent processes will fail their handshake at runtime with a version mismatch error. The golden tests may pass locally, but cross-version communication will break in production.

Can I reorder methods or enum variants without bumping the version?

No. Method indices and enum discriminants serialize directly into the wire format. Reordering changes the binary encoding and requires a full version bump and regeneration cycle.

Where is the official documentation for this process?

The openlogi-ipc crate maintains the authoritative guide in crates/openlogi-ipc/AGENTS.md, which covers the bump-and-regenerate workflow and append-only design constraints.

What does "append-only" mean for the IPC contract?

It means you can only add new methods at the end of interfaces and new variants at the end of enums. Never remove, rename, or reorder existing entries—these operations break backward compatibility and require protocol version increments.

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