ALX Protocol v1 defines the shared contract for solve request and response flows, session inspection, run events, protocol negotiation, and response envelopes. The specification is structured around two layers: the wire contract (what messages look like) and the semantic invariants (what must remain true over time). This page summarizes the most important rules for clients and implementers. The normative type source isDocumentation Index
Fetch the complete documentation index at: https://docs.xandrlabs.ai/llms.txt
Use this file to discover all available pages before exploring further.
packages/protocol/src/index.ts, and the full document is docs/protocol/PROTOCOL-SPEC.md.
The current shared protocol version constant is exported from @alx/protocol:
"1.1").
Wire-level guarantees
All compatible implementations must satisfy the following wire-level rules.| Rule | Requirement |
|---|---|
| WG-01 | Shared protocol-owned wire shapes must live in @alx/protocol. |
| WG-02 | Major protocol surfaces must expose stable envelope metadata: ok, correlationId, and protocol. |
| WG-03 | Session timeline events must use the closed SessionTimelineEventType vocabulary. |
| WG-04 | Run events must use the closed RunEventType vocabulary. |
| WG-05 | error.code must be machine-readable and stable across compatible releases. |
| WG-06 | Canonical wire fields must remain semantically stable across minor releases. |
| WG-07 | Implementations must tolerate unknown optional fields and unsupported capabilities. |
| WG-08 | A failed request must not report ok: true. |
| WG-09 | If run.failed is emitted, it must carry ok: false. |
| WG-10 | If run.completed is emitted, it must carry ok: true. |
Solve response canonical fields
These fields carry compatibility guarantees and must not be renamed or removed in a minor release.| Field | Description |
|---|---|
ok | true on success, false on failure. |
correlationId | Opaque trace identifier. Preserve for operator observability. |
protocol | Negotiation envelope: protocol_version and capabilities. |
success | Whether the solve operation succeeded. |
executionId | Stable identifier for the execution. |
artifact | The selected Knowledge Block artifact, if any. |
result | The natural-language result payload. |
confidence | Numeric confidence score for the selected artifact. |
execution | Execution metadata. |
steps | Ordered list of execution steps. |
learning | Feedback and learning metadata. |
error | Error detail (present when ok: false). |
Session response canonical fields
| Field | Description |
|---|---|
ok | true on success, false on failure. |
correlationId | Opaque trace identifier. |
protocol | Protocol negotiation envelope. |
sessionId | Stable session identifier. |
userId | Identifier of the session owner. |
intent | Original user intent string. |
status | Current session lifecycle status. |
progress | Completion progress indicator. |
nextStep | Suggested next action for the client. |
summary | Human-readable session summary. |
timeline | Ordered list of session timeline events. |
sessions | Session list (for list endpoints). |
error | Error detail (present when ok: false). |
Determinism boundaries
Not every surface is required to be deterministic. Clients must not depend on server behavior outside the deterministic surfaces.Deterministic surfaces
Deterministic surfaces
- Protocol type shapes
- Field names and their meanings
- Event vocabulary names (run and session timeline types)
- Response envelope structure
- Negotiation field semantics
kbHashderivation for identical inputs- Settlement and attribution math for identical inputs
Not required to be deterministic
Not required to be deterministic
- Artifact selection strategy
- Retrieval ranking order
- Natural-language response text
- Runtime optimization heuristics
Versioning rules
See versioning and compatibility for the complete compatibility policy. The summary:- Clients should ignore unknown optional fields.
- Clients should ignore unknown capabilities.
- Servers may add optional fields in minor releases.
- Servers must not change the meaning of an existing canonical field without a major version bump.
- New union members are allowed in minor releases only when old clients can safely ignore them.
- Ergonomic alias fields may be added but do not override canonical wire fields.
Canonical vs ergonomic fields
Canonical fields are the compatibility contract. Ergonomic alias fields are convenience additions that may be present alongside canonical fields for SDK or CLI consumers, but are not the authoritative wire representation. Current solve alias fields (not part of the stability contract):improvement, confidenceScore, reason, cached, fallbackUsed, idempotencyKey, selectMeta.
Current error alias field: top-level code (the canonical location is error.code).
Knowledge Block identity fields
| Field | Included in kbHash derivation | Notes |
|---|---|---|
top-level kbHash | No | Removed before canonical hashing. |
| canonical KB content | Yes | Hashed through canonical serialization. |
sources / lineage references | Yes (when present in canonical content) | Affect derived identity. |
kbId (implementation label) | No | Must not alter canonical identity. |
| transport metadata | No | Does not change KB identity. |