62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# 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](../policy/architecture.md#public-api-and-dependency-direction)
|
|
owns the binding boundary. The [component overview](../internal/overview.md)
|
|
describes the implemented layout; the [development guide](../development.md)
|
|
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.
|