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;
• detached parser-neutral CLI override validation and synthetic-source application in override.go, sharing overlay, source, byte, node, and depth policies;
• 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;
• opaque typed environment references and per-load name resolution in secret_reference.go, including credential-free projection/cloning and private validator-state auditing;
• explicit bounded startup environment bootstrap and safe partial reporting in secrets.go;
• fixed-point tag/predicate/dependency sensitivity classification in secret.go; and
• frozen-snapshot redaction and canonical effective output in render.go;
• bounded immutable input applications, safe historical replay, detached explanation records, and deterministic human rendering in explain.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/CLI overlay, version checking, recorded resolution, typed secret references/bootstrap, semantic validation, metadata, secret classification, redacted effective rendering, historical explanation, 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.