# DDR-0003: inventory.json Is the Authoritative Implemented E27 API Surface

Status: Accepted  
Date: 2025-12-22  
Related ADRs: ADR-0010 (Authoritative API reference)
              ADR-0012 (inventory-driven API surface)

## Context

The E27 Dealer API documentation exists in PDF/CHM formats whose structure and
formatting may change over time. Directly generating code from documentation
creates instability and makes diffs noisy.

A stable representation of supported domains and commands is needed.

## Decision

A committed JSON file is the authoritative source of inventory.json is the authoritative
implemented API surface/registry input, derived from HelpDealerAPI_UL (the source of truth)
for E27 API domains and commands:

elkm1/elke27_lib/messages/inventory.json

This file defines:
- All supported domains
- The list of commands per domain

Registry and dispatch logic must rely on this file, not on documentation parsing.

## Rationale

- Decouples code from documentation formatting changes
- Makes API surface changes explicit and reviewable
- Enables generation of stub handlers without re-reading docs
- Acts as a contract for Home Assistant integration

## Consequences

- Adding or removing API support requires updating inventory.json
- Registry must validate domains/commands against inventory
- Documentation updates alone must not affect runtime behavior
- inventory.json is authoritative for what the code claims to support / dispatch / generate
- HelpDealerAPI_UL is authoritative for the meaning/shape of those APIs

NOTE: if inventory.json ever diverges from HelpDealerAPI_UL, the doc wins and
      inventory must be updated following API change approval
