# DDR-0012: Normalization Rules for Domain and Command Names

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

## Context

On-wire domain and command names come from the E27 API and must remain stable.
Python module filenames and handler function names must be valid identifiers.
A consistent normalization strategy prevents import/name conflicts.

## Decision

Normalization rules:

- On-wire identifiers:
  - Domain and command names are taken exactly from inventory.json for dispatch keys.
  - Domain modules must declare DOMAIN = "<on-wire-domain>".

- Python module filenames:
  - Use a python-safe module name derived from on-wire domain:
    - lowercase
    - non [a-z0-9_] characters converted to underscore
    - collapse multiple underscores
  - Example: "bus-io-dev" -> "bus_io_dev.py"

- Handler function names:
  - handle_<command> where <command> uses the same normalization rules as above.
  - Example: "get-status" -> handle_get_status

- Registry mapping:
  - registry.py maintains an explicit mapping from on-wire domain -> module name when
    normalization changes the spelling, to avoid ambiguity.

## Rationale

- Prevents invalid python identifiers from breaking imports
- Keeps on-wire semantics explicit and separate from file naming concerns
- Enables stable dispatch keys regardless of code organization

## Consequences

- Domain modules must export HANDLERS keyed by on-wire command strings
- Registry must normalize names only for module/function resolution, not for dispatch keys
- Any normalization collisions must be detected and rejected with clear errors
