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 in source.go, with shared regular-file checks and bounded read mechanics in source_file.go;
• a parser-independent ordered tree in internal/document, with root-private semantic lookup, indexing, and value traversal in document_walk.go;
• the sole upstream YAML integration in internal/yaml, which translates validated input into that owned tree and exposes no parser types outside its boundary; parse.go owns shared translation into detached, ordered public diagnostics;
• 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; overlay records retain origins, while value explanation uses separate history applications;
• CLI override validation/preparation in override.go, parser-neutral values in override_value.go, and synthetic-source application in override_apply.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 in projection.go, detached typed cloning with explicit secret-state modes in clone.go, shared reflection and cycle/limit state in value_operation.go, and configuration-value comparison in document_compare.go; validation separately audits sensitivity and secrets;
• 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;
• public lifecycle coordination in load.go, option selection in options.go, input assembly in load_input.go, typed phases/publication in load_result.go, bounded canonical import DFS in imports.go, filesystem context/containment in filesystem.go, directive parsing/restrictions in directives.go, pattern-directed glob expansion in glob.go, version-report contexts in validation.go, and detached layered metadata/history assembly in load_metadata.go;
• 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;
• 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;
• frozen-snapshot redaction and canonical effective output in render.go;
• detached public explanation records and coordination in explain.go, immutable input applications/replay and retained-node budgeting in history.go, shared safe snapshot projection in snapshot.go, and deterministic human output in explain_render.go; the only upstream dumper integration remains isolated in internal/yaml/write.go;
• a separate maintained examples/consumers package with four sanitized consumer shapes, fixtures, domain validators, and runtime-boundary functions; and
• a fail-fast source-candidate checker in scripts/release-check.sh, with local documentation-link and public import-boundary gates owned by root-package tests.

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 consumer adoption guide owns current application-fit and migration guidance.

The source-extraction inventory records the application foundations used by the implementation:

• Extraction inventory

The architecture policy owns binding boundaries and invariants. The initial target record links current feature owners and preserves deferred scope; it is not an implementation inventory. See the development guide for contributor orientation and validation and the release procedure for source-candidate gates.