# DDR-0010: Unknown and Unimplemented Command Behavior

Status: Accepted  
Date: 2025-12-22  
Related ADRs: ADR-0012 (Inventory-Driven API Surface)

## Context

inventory.json may include commands that are not fully implemented yet, and the panel
may also send unknown/unsupported commands (e.g., firmware differences). A consistent
behavior is needed for:
- unknown domain/command (not in inventory)
- known domain/command (in inventory) but no handler implemented yet

## Decision

Dispatcher behavior is defined as follows:

1) Unknown domain (not in inventory):
- Return an error DispatchResult:
  ok=False, error_message="Unknown domain '<domain>'", include raw message for debugging.

2) Unknown command (domain known, command not in inventory):
- Return an error DispatchResult:
  ok=False, error_message="Unknown command '<command>' for domain '<domain>'", include
  available commands.

3) Unimplemented handler (domain/command present in inventory but handler missing):
- Registry must install a default stub handler.
- Stub handler returns a single event:
  type="<domain>.<command>", note="unimplemented", data=<cmd_payload>
- Stub does not raise, and does not crash dispatch.

## Rationale

- Distinguishes “unexpected wire input” from “known but not yet implemented”
- Allows incremental implementation without breaking dispatch
- Provides predictable logging/HA behavior without noisy exceptions

## Consequences

- Registry must guarantee a callable handler exists for every (domain, command) in inventory
- Tests must verify stub behavior is stable
- Unknown domain/command remains a hard error to surface protocol mismatches
