2.8 KiB
ADR 0006: Keep the public facade root-owned
Status
Accepted. This records a design decision, not implementation completion.
Date
2026-09-12
Context
The root configkit package currently combines the supported consumer API with
the loading, decoding, inspection, and rendering machinery. That makes ordinary
consumer navigation harder and risks 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. When lifecycle machinery is extracted, it will live
in a cohesive internal/engine; the root facade may hold private engine state
and forward 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 may use a temporary internal candidate facade while the unchanged root remains the only production entry point. That duplication is a bounded relocation mechanism, not a second supported package, feature path, or runtime selection mechanism. The final cutover removes the temporary candidate and old root implementation together.
The architecture policy owns the binding boundary. The public-facade roadmap owns the intended end state and its implementation plan owns progress.
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.