Audit the public facade boundary

This commit is contained in:
2026-09-12 16:26:44 +00:00
parent 7f46c947dd
commit 5dc7e18d83
9 changed files with 216 additions and 136 deletions

View File

@@ -1,8 +1,8 @@
# Public facade and internal implementation
Status: agreed direction; not implemented. This roadmap defines the desired end
state and user intent. The [implementation plan](implementation.md) owns the
ordered work, concrete adapter design, validation commands, and handoffs.
Status: implemented on 2026-09-12. This roadmap records the intended architecture
and user intent; the completed [implementation plan](implementation.md) records
the ordered work, validation, and handoffs.
## Intent
@@ -31,13 +31,13 @@ design. Existing [configuration contracts](../config.md) and exported Go
declaration comments remain authoritative. The user-approved wrapper boundary is
a contributor design choice, not a strengthening of consumer behavior contracts.
## Current architecture
## Implemented architecture
The root currently owns both public declarations and most private implementation:
source acquisition, imports, composition and overlays, reflection descriptors,
decoding, resolution and validation coordination, provenance, history, secret
handling, and rendering. The [component overview](../internal/overview.md) owns
the detailed inventory.
The root owns public declarations, records, wrappers, and deliberate forwarding.
`internal/engine` owns source acquisition, imports, composition and overlays,
reflection descriptors, decoding, resolution and validation coordination,
provenance, history, secret handling, and rendering. The
[component overview](../internal/overview.md) owns the detailed inventory.
Two established internal boundaries already exist: `internal/document` owns the
parser-independent tree, and `internal/yaml` owns upstream YAML integration.
@@ -49,7 +49,7 @@ callback state; `Path` holds semantic segments; and `Secret` holds private
reference and resolved-value state. Moving implementation requires deliberate
type ownership, not just file relocation.
## Target architecture
## Architecture
### Public root package
@@ -140,7 +140,7 @@ need to change an established contract requires a separate explicit decision.
Version selection and publication remain governed by the
[release policy](../policy/release.md), not by this roadmap.
## Completion criteria
## Completion evidence
Completion means the root is a legible public surface, substantive plumbing is
internally owned, consumers require no migration, and representative