Anolis Docs

Appearance

ADR-0001: Provider Scope and Shared-Bus Safety Model ​

  • Status: Accepted
  • Date: 2026-03-27

Context ​

anolis-provider-ezo is being introduced alongside anolis-provider-bread, with both potentially sharing one Linux I2C adapter (/dev/i2c-X).

The design needs to stay simple, avoid hidden coupling between providers, and remain safe under concurrent runtime behavior.

Decision ​

  1. Provider boundaries are strict:
    • anolis-provider-bread remains BREAD-over-CRUMBS only.
    • anolis-provider-ezo handles EZO devices only.
  2. v1 transport scope is I2C only.
  3. v1 discovery mode is manual config only.
  4. v1 startup behavior is strict identity verification + partial-ready startup:
    • type mismatch or unreachable devices are excluded with diagnostics.
    • healthy devices remain available.
  5. v1 function surface is limited to safe controls:
    • find
    • set_led
    • sleep
  6. Shared-bus safety is layered:
    • each provider must serialize its own bus operations through a single internal executor.
    • runtime must reject duplicate (bus_path, i2c_address) ownership across providers at startup.
  7. Cross-process advisory lock is optional hardening and not baseline for v1.

Consequences ​

  1. Clear ownership and maintainable provider code boundaries.
  2. Reduced race risk inside each provider.
  3. Deterministic startup failure for ambiguous topology.
  4. Lower initial complexity than a global broker model.

Non-goals for v1 ​

  1. UART transport support.
  2. Auto discovery.
  3. High-risk control/calibration command surface.
  4. Runtime-global lock manager or broker process.

Amendment (2026-10-09) ​

Decision 6's runtime check now runs over opaque claims (anolishq/anolis#318). Providers publish an anolis.claim tag built with the provider SDK's i2c::claim_key, and the runtime rejects duplicate keys without parsing them, so it no longer knows about I2C. The rest of this ADR stands. See runtime-ownership-validation-inputs.md.