From a0482ad7faf8bc6b3a800accf7f39c22715085ac Mon Sep 17 00:00:00 2001 From: Ruixiang Du Date: Tue, 7 Jul 2026 12:54:16 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20ADR=200005=20=E2=80=94=20dependency=20c?= =?UTF-8?q?lasses=20clarification=20(runtime=20vs=20development-support)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The xmBase-only rule constrains the deployment closure; family development-support components (xmViewer first) may be gated dev dependencies. Resolves the tension surfaced by xmNavigation's visualization tier: the support component's purpose is precisely to be used by domain components during development. --- docs/adr/0005-application-level-composition.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/adr/0005-application-level-composition.md b/docs/adr/0005-application-level-composition.md index 2cae00d..6334115 100644 --- a/docs/adr/0005-application-level-composition.md +++ b/docs/adr/0005-application-level-composition.md @@ -22,6 +22,15 @@ Meanwhile the planning core (~48k LOC), the estimators, the control laws, and th This mirrors ADR 0004 one level up: there, components instrument against a stateless API and applications choose the machinery; here, components implement algorithms or hardware against the shared foundation, and applications choose the combination. +### Dependency classes (clarification, 2026-07) + +The rule above constrains the **deployment closure** — what a robot links at runtime. Its rationale (consumers paying for stacks they don't use; behavior-critical layers entangling release cycles) applies to runtime dependencies only. Two classes are therefore distinguished: + +1. **Runtime dependencies**: the deployment closure of an algorithm or hardware component is **xmBase plus mathematical libraries, nothing else**. Unchanged, strict, CI-enforced. +2. **Development-support dependencies**: components *may* depend on family components whose purpose is supporting development — visualization, simulation tooling, test infrastructure — provided the dependency is **always optional (build-gated) and provably absent from the deployment closure**. These support components exist so that domain components can see themselves during development; forbidding the dependency would invert their purpose. + +**xmViewer** (quickviz) is the first registered development-support component: xmNavigation consumes its rendering primitives in the visualization-gated modules and demos. The division of labor is deliberate: the *drawers of a component's types live with that component* (they evolve with the algorithms); the support component stays domain-agnostic (canvases, windows, GUI primitives). Deployment builds are verified render-free the same way they are verified hardware-free. + ## Alternatives considered - **Keep the composition layer in xmNavigation** (status quo) — rejected: hardware dependencies in the algorithms component, coupled release cycles, and consumers paying for stacks they never use.