feat: checkpoint device agent runtime milestones

2026-07-06 17:24:03 +08:00
parent 2d4251e98e
commit 5658735bca
153 changed files with 8060 additions and 65 deletions
@@ -0,0 +1,53 @@
+# 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.