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 private strict composer in compose.go that joins only disjoint document-tree definitions, retains ordered claims and composite mapping origins, reports every conflicting location, and never aliases an input tree;
• fixed selected-profile loading in profile.go and recursive, non-aliasing overlay with displacement records in overlay.go;
• 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 lifecycle coordination in load.go, bounded canonical import DFS in imports.go, pattern-directed glob expansion in glob.go, version-report contexts in validation.go, and detached layered metadata/history 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; and
• post-resolution schema-aware report collection and validator mutation detection in validation.go, completing the public callback lifecycle after composed input;
• fixed-point tag/predicate/dependency sensitivity classification in secret.go; and
• frozen-snapshot redaction and canonical effective output in render.go, with the only upstream dumper integration isolated in internal/yaml/write.go.

The configuration contract owns implemented input, schema, decoding, loading lifecycle, path imports, composition, profile overlay, version checking, recorded resolution, semantic validation, metadata, secret classification, redacted effective rendering, 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.