Client Server Build Compatibility

A client and server can each start successfully while still being unsafe to run together. A reliable delivery path makes compatibility an explicit release contract: what must agree, what may differ, who evaluates it, and how a mismatch fails.

Define the compatibility contract#

Create one compatibility identifier from a canonical set of declared inputs. It is a release identity, not a human-friendly build label. Store it with each artifact and expose it before session admission.

Each immutable manifest should identify source and build-definition revisions, target and configuration, the generated identifier, and every compatibility dimension. Promotion must read that manifest rather than infer compatibility from a branch, timestamp, or filename.

Protocol#

Protocol compatibility covers message names, field encoding, ordering assumptions, handshake behavior, and error handling. Increase or otherwise change the protocol identity whenever either side would decode the same bytes differently. A connection gate should compare this value before accepting gameplay traffic, not after state has begun to replicate.

Content#

Content compatibility covers cooked data that affects shared simulation, identifiers, map availability, or asset lookup. Define whether the contract uses a content-set version, a deterministic content manifest, or another stable identity. Cosmetic-only content may be outside the contract only when it cannot affect loading, simulation, or a referenced identifier.

Schema#

Schema compatibility covers persisted state, replicated structures, service payloads, and migration expectations. Record both the active schema identity and the supported migration path. A newer schema is not automatically compatible with an older server or client; compatibility exists only when the declared reader, writer, and migration behavior support the pairing.

Feature flags#

A feature flag belongs in the compatibility contract when it changes protocol behavior, content interpretation, schema handling, authority, or session rules. Record the required flag set and allowed values in the manifest. Flags used only for local presentation can remain outside the identifier, but that distinction should be written down and reviewed when the flag changes.

Gate promotion on the manifest#

Generate the compatibility manifest as part of packaging, then validate it before promotion. The gate should retrieve the exact candidate manifests, confirm their integrity, compare every required dimension, and produce a clear reason when it rejects a pairing. Missing, malformed, or unknown manifests should block promotion just as a mismatch does.

The gate needs a policy owner and versioned implementation, not a release operator's visual comparison. A successful gate records the selected artifacts, manifest identities, policy revision, and check evidence.

Set a deliberate skew policy#

Use exact identifier matching as the default. It gives a simple rule: a client may join only a server with the same declared contract. If a rolling update requires temporary skew, express the allowed pairings in a bounded policy rather than treating any nearby version as acceptable.

A skew policy should name the compatible predecessor or successor manifests, the dimensions allowed to differ, the reason for the exception, its expiration condition, and its rollback behavior. It must be tested with the same handshake gate used in normal delivery. Reject pairs outside that list with an actionable incompatibility response; do not allow partial admission and hope later state will reconcile.

Roll back a paired release#

A rollback unit is a known client and server artifact pair plus its approved compatibility manifest and configuration reference. Select that immutable unit directly. Do not rebuild an older source revision during an incident, because a rebuilt artifact creates new evidence to prove.

Before an incident, identify the prior compatible pair, retain its manifests, and test its startup path. If a rollback changes a skew window, treat that policy change as a separate gated release. The safe recovery path is a previously proven pairing, not a widened compatibility rule.

Exercise the test matrix#

Test the gate and runtime handshake independently, retaining evidence with the policy revision.

Implementation sequence#

1. List every protocol, content, schema, and feature-flag decision that can change shared behavior.
2. Define canonical values for those decisions and generate one compatibility identifier from them.
3. Publish immutable manifests with both client and server artifacts.
4. Add manifest comparison to packaging and promotion before distribution depends on it.
5. Enforce the same rule during the runtime handshake.
6. Document the default exact-match policy, any bounded skew exception, and the paired rollback unit.
7. Run the mismatch and recovery cases whenever the contract or gate changes.

Practical checklist#

• Client and server artifacts carry immutable compatibility manifests.
• The identifier is derived from declared canonical inputs.
• Protocol, content, schema, and compatibility-relevant flags have explicit identities.
• Promotion reads exact manifests and blocks missing or mismatched values.
• Runtime admission applies the same compatibility policy.
• Any skew policy names allowed pairs, boundaries, expiration, and owner.
• Incompatible pairs fail before shared gameplay state is accepted.
• A rollback selects a retained compatible artifact pair rather than rebuilding.
• The test matrix includes each mismatch class and the rollback path.
• Compatibility evidence is retained with the promoted pairing.

Compatibility should be declared during packaging, checked during promotion, enforced during admission, and recoverable through a proven pair.