Conformance in ALX Protocol means that identical inputs must produce identical outputs — across runs, across machines, and across independent implementations. The protocol defines correctness through invariants, not through any single implementation. An implementation is conformant if it satisfies all applicable invariants for the surfaces it ships, and if it passes the canonical test vectors. ALX Protocol maintains conformant implementations in TypeScript (the primary SDK), Python, and Rust. All three are validated against the same set of canonical test vectors.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 supports TypeScript, Python, and Rust conformant implementations. The TypeScript
@alx/protocol package is the primary SDK and reference executable surface. The Python and Rust implementations are for conformance verification.What conformance covers
Conformance is defined at two levels: wire conformance and semantic conformance. Wire conformance covers the shape of messages: solve requests and responses, session status and list responses, timeline and run events, and error envelopes. Wire-conformant implementations pass the protocol fixture tests and produce envelopes that match the documented shapes. Semantic conformance covers behavior: given the same inputs, the implementation must produce the same canonical bytes, Knowledge Block identifiers, settlement amounts, and attribution results. Semantic conformance is deeper than wire shape — it requires that the implementation’s logic is equivalent to the reference, not just that its output fields are present.Semantic conformance requirements
At minimum, a semantically conformant implementation must:- Produce identical canonical bytes for identical Knowledge Block content (INV-01)
- Derive identical
kbHashvalues for identical canonical bytes (INV-02) - Produce identical results as all other conformant implementations for the same input (INV-03)
- Pass
kbHashreplay against all published canonical vectors - Pass
artifactHashreplay against all published canonical vectors - Reject cycles in the Knowledge Block derivation graph (INV-07)
- Produce deterministic settlement results for identical economic inputs (INV-10)
- Produce consistent, independently verifiable proofs and receipts (INV-11)
Verification commands
If you are building a conformant implementation of ALX Protocol, use the following commands from the alx-protocol repository to verify your implementation against the reference:| Command | What it verifies |
|---|---|
pnpm --filter @alx/protocol run typecheck | TypeScript SDK type surface |
pnpm test:protocol | Protocol and property tests |
pnpm test:spec | Semantic specification tests including canonical vector replay |
pnpm --filter @alx/protocol test | On-chain registry contract tests |
python implementations/python/verify_vectors.py | Python cross-implementation vector replay |
cargo test --manifest-path implementations/rust/Cargo.toml | Rust cross-implementation vector replay |
Proof surface
| Surface | Verification command | Status |
|---|---|---|
| Protocol and property tests | pnpm test:protocol | Implemented |
| Canonicalization and identity replay | pnpm test:spec | Implemented |
| Proofs and Merkle vectors | pnpm test:spec | Implemented |
| Virtual registry and lineage | pnpm test:spec | Implemented |
| Economic settlement and attribution | pnpm test:spec | Implemented |
| Contract-backed registry | pnpm --filter @alx/protocol test | Implemented |
| Shared protocol package surface | pnpm --filter @alx/protocol run typecheck | Implemented |
| Python conformance core | python implementations/python/verify_vectors.py | Implemented |
| Rust conformance core | cargo test --manifest-path implementations/rust/Cargo.toml | Prepared |
Canonical test vectors
The canonical test vectors are published intest-vectors/canonical/. Each vector is a directory containing two files:
envelope.json— the input Knowledge Block envelopeexpected.json— the expectedkbHash(and related fields)
| Category | Contents |
|---|---|
types/ | One vector per canonical KB type: practice, pattern, prompt, synthesis, adaptation, compliance, enhancement, state-machine |
edge-cases/ | Unicode content, large payloads, maximum number of sources, empty payload fields |
derivation/ | Single-parent and multi-parent lineage, source sort stability (sorted and unsorted inputs must produce the same hash) |
verify_vectors.py script, and the Rust cargo test suite all load and replay these same files. Adding a new vector to test-vectors/canonical/ is the standard way to expand cross-implementation coverage.
Invariant mapping
The detailed invariant-to-proof mapping is indocs/protocol/INVARIANTS.md. A summary:
INV-01throughINV-07have executable proof in the specification and protocol tests.INV-08throughINV-10have executable proof through economic invariant tests, property tests, and derived-envelope coverage.INV-11is covered by proof and Merkle vector tests and canonical signing helpers in@alx/protocol.INV-12(forward compatibility) is partially covered by protocol tests and shared types.
Known gaps
The following areas are tracked as active protocol-hardening work rather than fully proven guarantees:- Richer attribution graph proofs beyond current normalization and deterministic distribution vectors
- Broader receipt verification for non-happy-path and tampered payloads
- Downgrade abuse resistance beyond documented compatibility rules