62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# 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](../policy/architecture.md#public-api-and-dependency-direction)
|
|
owns the binding boundary. The [public-facade roadmap](../roadmap/public.md)
|
|
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.
|