# 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.