# ADR 0002: Own YAML Semantics Behind a Private Parser Boundary

## Status

Accepted. This records a design decision, not implementation completion.

## Date

2026-09-06

## Context

A shared library cannot provide consistent configuration semantics if each
consumer inherits parser conversions, node types, and extension behavior.
Exposing parser types also makes dependency changes part of the public API.

## Decision

ConfigKit defines its supported YAML policy and keeps parser integration private.
Application types and diagnostics must not require parser-specific public types.
Use a small internal boundary rather than a general parser/provider framework.
The [architecture policy](../policy/architecture.md) owns this constraint; the
[target design](../roadmap/initial.md#yaml-and-scalar-policy) owns planned syntax.

## Alternatives considered

- Expose parser nodes and hooks: easy integration but couples consumers to parser
  behavior and permits bypassing library policy.
- Adopt the parser's entire YAML behavior: reduces initial code but leaves core
  semantics outside ConfigKit's control.
- Abstract many configuration languages immediately: adds unsupported scope.

## Consequences

Parser changes require behavior-level compatibility verification. ConfigKit must
translate errors safely and enforce its own supported subset. Some existing
consumer custom decoders will need replacement with library-supported mechanisms
or application resolution. No particular parser dependency is selected here.