ConfigKit/docs/internal/overview.md

Internal Component Overview

ConfigKit currently contains the root configkit package, which establishes the module and package documentation boundary. Its implemented public primitives are:

• immutable semantic Path construction and strict JSON Pointer parsing;
• detached provenance and diagnostic record types with empty Metadata queries;
• canonical, control-safe diagnostic rendering and structured LoadError access;
• opaque file, byte, reader, and no-input source construction and bounded reads;
• a parser-independent ordered tree in internal/document;
• the sole upstream YAML integration in internal/yaml, which translates validated input into that owned tree and exposes no parser types outside its boundary;
• a per-operation private reflection descriptor graph in schema.go for supported types, YAML field binding, inlining, secret tags, recursion, and semantic paths;
• descriptor-driven canonical projection, detached typed cloning, cycle/limit enforcement, and structural comparison in projection.go; and
• strict schema-driven decoding over detached defaults in decode.go, including mapping/sequence semantics, null and numeric policy, safe codec errors, presence, baseline/final trees, and initial default/input origins; and
• public single-source lifecycle coordination in load.go, version-report contexts in validation.go, and detached base/default metadata assembly in load_metadata.go; and
• recorded application defaulting and normalization in resolution.go, including explicitness queries, helper verification, structural mutation audit, coalesced intent, private before/after snapshots, and resolution metadata integration.

The configuration contract owns implemented input, schema, decoding, single-source lifecycle, version checking, recorded resolution, metadata, and ownership behavior.

The source-extraction inventory records the application foundations assigned to future implementation work:

• Extraction inventory

This document will inventory additional components and link to their current contracts and focused internal documentation as they are introduced.

The architecture policy owns binding boundaries and invariants. The initial target design describes planned behavior; it is not an inventory of implemented features. See the development guide for contributor orientation and validation.