Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xandrlabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

ALX Protocol uses a versioned wire contract to let the protocol evolve without breaking existing clients. The version is exported as a constant from the primary SDK and reported in every protocol envelope, so clients and servers can negotiate capabilities without a separate handshake. The compatibility policy distinguishes between changes that are safe in a minor release and those that require a major version bump.

​
The protocol version constant

The current protocol version is exported from @alx/protocol: 
import { ALX_PROTOCOL_VERSION } from "@alx/protocol";
The protocol envelope in every request and response reports the same version string. The current format is "1.1" (major.minor). Clients should treat the version string as opaque and compare it only for the purposes defined by the compatibility rules below.

​
Client compatibility rules

When consuming ALX Protocol responses, follow these rules to remain forward-compatible:
  • Ignore unknown optional fields. A newer server may include fields that an older client does not know about. Clients must not fail when encountering them.
  • Ignore unknown capabilities. Capability arrays are informational advertisements, not contract requirements. An unknown capability must be silently skipped.
  • Tolerate unknown error codes. New error codes may be added to an existing stable error type in a minor release. Default to conservative retry behavior for any unrecognized code.
  • Do not depend on alias fields as a stability contract. Ergonomic alias fields may change more freely than canonical wire fields.

​
Server compatibility rules

When implementing or operating an ALX Protocol server:
  • Servers may add optional fields in minor releases without breaking existing clients.
  • Servers must not change the meaning of an existing canonical field without a major version bump.
  • Servers must not remove a canonical field in a minor release.
  • Servers must not rename a canonical field in a minor release.
  • Servers must not make an optional canonical field required in a minor release.
  • Servers must not change a stable event name incompatibly in a minor release.
  • New event union members may be added in a minor release only if existing clients can safely ignore them.

​
Minor-safe changes

The following changes are safe in a minor release:
Change typeExample
New optional fieldAdding artifact.metadata to the solve response
New capabilityAdding "streaming" to a capabilities array
New event union memberAdding a new RunEventType value clients can ignore
New ergonomic alias fieldAdding a top-level shorthand for a nested canonical field
New error code within a stable typeAdding RATE_LIMITED to the execution error type

​
Major-version changes

The following changes require a major version bump:
Change typeExample
Remove a canonical fieldDropping correlationId from the envelope
Rename a canonical fieldRenaming executionId to runId
Change canonical field semanticsChanging confidence from 0–1 to 0–100
Make an optional field requiredRequiring learning in all solve responses
Incompatible event name changeRedefining what run.completed means
Incompatible envelope semanticsChanging what ok: true guarantees

​
Canonical vs ergonomic fields

Canonical wire fields are the compatibility contract. Ergonomic alias fields are convenience additions that sit alongside canonical fields for SDK or CLI consumers. Canonical fields must remain semantically stable across minor releases. If you are writing a parser or client, build on canonical fields. Ergonomic alias fields may be added, reordered, or replaced in minor releases, as long as the canonical field they mirror remains correct and available. Examples of current alias fields include the top-level code on error responses (canonical location: error.code) and confidenceScore on solve responses (canonical location: confidence).

​
The KB_V1 domain tag and Knowledge Block identity

The string "KB_V1" is prepended to canonicalized envelope bytes before hashing to produce kbHash. This domain tag scopes the hash to the Knowledge Block domain and version. Exported from both the TypeScript and Rust implementations as DOMAIN_TAGS.KB / KB_DOMAIN_PREFIX: 
import { DOMAIN_TAGS } from "@alx/protocol";
// DOMAIN_TAGS.KB === "KB_V1"
A new domain tag — for example, "KB_V2" — would be required if the hashing algorithm or canonical field set changes in a way that would produce different hashes for the same logical KB content. Such a change would constitute a major protocol version bump and would require new canonical test vectors covering both old and new tag behaviors. The current KB_V1 tag and its hash algorithm are stable for the lifetime of ALX Protocol v1.

​
How to handle unknown fields and codes

When consuming ALX Protocol responses in production:
  • Unknown fields: Deserialize but ignore. Do not fail because a field is present that your version of the protocol does not define.
  • Unknown capabilities: Skip silently. Capability arrays advertise support; they are not required.
  • Unknown error codes: Default to conservative retry behavior. See Error codes and retry guidance.
  • Unknown event types: Log and skip. Do not abort an event stream on an unrecognized RunEventType or SessionTimelineEventType.
Building forward-compatible clients on these rules means your integration will continue to work as ALX Protocol evolves through minor releases.