eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Audit the public facade boundary

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-12 16:26:44 +00:00
parent 7f46c947dd
commit 5dc7e18d83
9 changed files with 216 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/adr/0006-public-facade.md
View File

@@ -2,7 +2,7 @@
## Status
Accepted. This records a design decision, not implementation completion.
Accepted and implemented on 2026-09-12.
## Date
@@ -10,32 +10,31 @@ Accepted. This records a design decision, not implementation completion.
## 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
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.
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.
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 may use a temporary internal candidate facade while the unchanged
root remains the only production entry point. That duplication is a bounded
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 removes the temporary candidate and old
root implementation together.
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 [public-facade roadmap](../roadmap/public.md)