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

> Learn how to update OpenLogi's protocol_version and regenerate wire format tests. Follow these steps to bump the constant, run tests, and update assertions for seamless integration.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs), run the failing [`wire_format.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs) and serves as the authoritative version identifier for all IPC peers.

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

```

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

```rust
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs) and increment the constant:

```rust
// 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:

```bash
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:

```rust
// 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:

```rust
#[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:

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs) (version bump)
- [`crates/openlogi-ipc/tests/wire_format.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs) | Defines `PROTOCOL_VERSION` and core IPC types |
| [`crates/openlogi-ipc/tests/wire_format.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/tests/wire_format.rs) | Golden-bytes tests for binary serialization stability |
| [`crates/openlogi-ipc/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.