ADR-0005: A shared kb-hal-common repository¶
- Status: Accepted
- Date: 2026-11-03
Context¶
Board HALs that start as copies of each other drift: in the review, six managers were near-copies, the facades
were near-clones, the platform binds used different shapes and verbs, each HAL's lint missed the other's rules,
and their ManagerError enums differed in values, width and namespace. Keeping copies aligned by hand was the
alternative; the drift shows it does not hold.
Board HALs are also product code: their pin tables, chip lists and board-specific managers belong to one product.
Decision¶
kb-hal-commoninkokeb-labs(namespacekb::hal) holdsManagerBase,FacadeBasewith ordered, fail-closed start-up and oneCollectDiagnostics(), the six common managers (NVS, LED, GPIO, ADC, temperature, comms), onePlatformBindinterface, the lints, and an example board HAL.- Board HALs live in the product's organization or repository. A board HAL keeps only its board config, its pin
table (written with the generic
pincfgframework), its bind and its board-specific managers. kb-hal-commonis a submodule of each board HAL, pinned to a release tag.kokeb-labs/board-hal-templatewill carry the board HAL shell; until it exists, new board HALs start from the example inkb-hal-common.
Consequences¶
- A fix to a common manager lands once.
- A new board starts from
kb-hal-commonand the new-board checklist instead of a copy. - One more repository to release, between kb-core and the board HALs in the release order.
- The common managers take everything board-specific as configuration and never name a board.