# ADR 0002: Layered Hexagonal Architecture

## Status

Accepted

## Context

Upcoming milestones add semantic understanding, world state, skill retrieval,
workflow orchestration, multi-agent behavior, and cloud scheduling. Those
features introduce LLM, embedding, HTTP, MCP, storage, and plugin concerns that
must not leak into the device and domain contracts.

The `device-agent-runtime-foundation` design decision D7 records the governing
architecture: Hexagonal / Ports-and-Adapters with DDD-style domain boundaries.

## Decision

Use this dependency direction:

1. `core`: domain models and errors. No framework, LLM, HTTP, MCP, or external
   device SDK dependencies.
2. `driver`: adapters over external device SDKs, implementing the `Driver`
   contract.
3. `device`: device lifecycle management and active driver ownership.
4. `tools`: capability layer called by the runtime. Tools use device/driver
   capabilities and do not import concrete drivers.
5. `perception`: produces `Scene` behind `PerceptionProvider`.
6. `storage`: persists timeline, task metadata, artifacts, and device config.
7. `runtime`: application layer. Planner and Executor orchestrate tools,
   perception, storage, retries, and task state. LLM-backed planning first
   enters here.
8. `api`: outermost transport adapter for REST, MCP, and future platform APIs.

Future milestones must build bottom-up through these boundaries. LLM and
transport dependencies may not be introduced into `core`, `driver`, `device`,
or `tools`.

## Alternatives Considered

Leaving the layering implicit was rejected because upcoming AI-heavy milestones
will otherwise tend to call LLM or transport APIs from convenient lower layers.

Adding lint enforcement now was deferred. The written architecture is the
current source of truth; mechanical enforcement can be added when a concrete
boundary violation or second-driver pressure appears.

## Consequences

The runtime can add smarter planning and richer perception without changing the
device capability contract. API and cloud concerns stay outside domain and
adapter layers. Future OpenSpec designs must state how they uphold this
dependency direction.