2.8 KiB
ADR 0006: Keep the public facade root-owned
Status
Accepted and implemented on 2026-09-12.
Date
2026-09-12
Context
The root configkit package formerly combined the supported consumer API with
loading, decoding, inspection, and rendering machinery. That made ordinary
consumer navigation harder and risked exposing implementation details through
future public declarations. Moving files alone would not preserve the identity,
method sets, callbacks, ownership rules, or reflection-sensitive behavior of the
root's public types.
Decision
Keep configkit as the sole supported consumer import path and keep all public
named types defined there. Lifecycle machinery lives in a cohesive
internal/engine; the root facade holds private engine state and forwards
deliberately selected methods. The dependency direction is root to engine and
its supporting internal packages. Internal production packages do not import the
root package.
The facade will use root-owned wrappers and explicit private conversions. It will not use public aliases to engine types, anonymous embedding that promotes engine methods, public engine types in signatures or fields, or public bridge methods. Existing document and YAML boundaries remain intact.
The migration used a temporary internal candidate facade while the unchanged root remained the only production entry point. That duplication was a bounded relocation mechanism, not a second supported package, feature path, or runtime selection mechanism; the final cutover removed it and the old root implementation.
The architecture policy owns the binding boundary. The component overview describes the implemented layout; the development guide locates the completed roadmap and implementation history.
Alternatives considered
- Alias root types to engine types: reduces forwarding, but makes the engine's exported method set and type ownership part of the consumer API.
- Keep all machinery in the root package: avoids migration work, but leaves the public boundary difficult to navigate and easy to expand accidentally.
- Introduce a generic adapter or registration framework: could reduce some handwritten conversions, but adds machinery and obscures the ownership rules this boundary needs to preserve.
Consequences
The refactor carries explicit forwarding and conversion work, especially for callbacks, detached records, source ownership, frozen inspection, and the exact-type secret bridge. Public compatibility must be verified by behavior and external-package evidence rather than inferred from package names. Internal exports remain implementation surfaces, and the completed architecture will have one engine and one root facade.