anolis-protocol

Canonical protocol contracts for the Anolis ecosystem.

Quick Start

Consume a pinned release (recommended)

C++ (CMake FetchContent):

include(FetchContent)
FetchContent_Declare(
    anolis_protocol
    URL https://github.com/anolishq/anolis-protocol/releases/download/v1.10.0/anolis-protocol-1.10.0-source.tar.gz
    URL_HASH SHA256=77c8baf8b423682e2f1fda771540a24ff0cb0843a3d7540607991f662218419a
)
FetchContent_MakeAvailable(anolis_protocol)
# proto files are at ${anolis_protocol_SOURCE_DIR}/proto/

Replace the version and hash from the latest release SHA256SUMS file.

Python (wheel from the GitHub Release):

Each tagged release attaches a built wheel (generated protobuf bindings) to the GitHub Release (there is no PyPI publish). Pin it by URL:

pip install "anolis-protocol @ https://github.com/anolishq/anolis-protocol/releases/download/v1.10.0/anolis_protocol-1.10.0-py3-none-any.whl"

The cross-provider conformance harness (the [conformance] extra + the anolis-adpp-conformance script) ships in the wheel from v1.3.0 onward (releases up to and including v1.2.0 predate it):

pip install "anolis-protocol[conformance] @ https://github.com/anolishq/anolis-protocol/releases/download/v1.10.0/anolis_protocol-1.10.0-py3-none-any.whl"
# or, from a checkout with tags fetched, after generating gen/python and its
# package shims as in .github/workflows/ci.yml: pip install ".[conformance]"

buf BSR (code generation):

The module is not published to the Buf Schema Registry. Generate code from the proto/ directory of the release source tarball above.

Work with the schema directly (contributors)

Requires Buf CLI v1.x.

# Verify schema compiles
buf build

# Lint
buf lint

# Check breaking changes vs main
buf breaking --against "https://github.com/anolishq/anolis-protocol.git#branch=main"

# Generate Python bindings (outputs to gen/python, not committed)
buf generate

• Owns ADPP protobuf schema used by anolis and providers.
• Contains the protocol contract (schema + normative semantics/profile docs) plus the generic conformance harness that verifies any provider against it.
• Contains no provider/runtime implementation code — the harness is a generic verifier, and it ships no knowledge of any specific provider.

Layout

anolis-protocol/
├── buf.yaml              # Buf v2 module config (lint, breaking)
├── buf.gen.yaml          # Canonical generation config (Python)
├── buf.lock              # Pinned dependency hashes
├── proto/
│   └── anolis/
│       └── deviceprovider/
│           └── v1/
│               ├── envelope.proto    # Request / Response top-level envelopes
│               ├── status.proto      # Status and error codes
│               ├── handshake.proto   # Hello request/response
│               ├── inventory.proto   # ListDevices / DescribeDevice
│               ├── telemetry.proto   # ReadSignals / SignalValue
│               ├── call.proto        # CallRequest / CallResponse
│               ├── health.proto      # ProviderHealth / DeviceHealth
│               ├── readiness.proto   # WaitReady request/response
│               ├── types.proto       # Device, CapabilitySet, FunctionSpec, ArgSpec
│               └── value.proto       # Value, ValueType
├── conformance/            # generic ADPP conformance harness (shipped in the wheel)
│   ├── anolis_conformance/ # AdppClient, spec, checks, the three contract suites
│   └── ADPP-CONFORMANCE.md # how to run it (non-normative)
└── docs/
    ├── index.md
    ├── semantics.md        # core ADPP v1 (normative)
    ├── profiles/
    │   ├── framed-stdio-v1.md            # stdio transport binding (normative)
    │   └── anolis-executable-profile-v1.md  # Anolis executable conventions
    └── versioning.md

Development

Requires Buf CLI v1.x.

# Verify the schema compiles
buf build

# Check lint rules
buf lint

# Check formatting
buf format --diff

# Check for breaking changes vs main
buf breaking --against "https://github.com/anolishq/anolis-protocol.git#branch=main"

# Generate Python bindings (outputs to gen/python, not committed)
buf generate

Versioning

• Repository uses semantic versioning tags: vMAJOR.MINOR.PATCH (e.g. v1.8.0). Pushing a v* tag runs the release workflow.
• Breaking wire-contract changes require a major bump (buf breaking enforces this on every PR).
• Semantic tightening (stricter conformance, same wire) ships as an opt-in conformance level, not a silent minor — see docs/versioning.md (Conformance Changes).
• See docs/versioning.md.

Future Work

• long-term: add CMakeLists.txt + cmake config; cut consumers to find_package — defer until FetchContent causes pain

License

Apache-2.0. See LICENSE. This covers the schema, the generated bindings and the conformance harness, which ship together in one wheel. Contributions are accepted under the same licence (Apache-2.0 §5).

Releases up to and including v1.9.0 were published under AGPL-3.0-or-later and remain available under it. The Anolis runtime and Workbench stay AGPL-3.0; a provider is a separate process, so their licence does not extend to it.