ConfigKit/docs/internal/overview.md

Internal Component Overview

ConfigKit exposes one supported root configkit package. The root owns public named types, declaration comments, constructors, and explicit conversion/wrapper code. It delegates loading and frozen inspection to internal/engine through private state; public signatures and fields do not expose engine types.

Implemented component owners:

• internal/engine owns host and native-filesystem source acquisition, grouped strict composition, recursive precedence assembly, per-input mapping and sequence-item placement, definition-registered distinct-ID sequence composition within strict tiers, and immediate-parent-relative import placement within that assembly. Higher-priority sequences replace lower sequences as whole values. The engine also owns dependency-ready, destination-local sibling inheritance before typed decoding, plus shared source-version checking with sanitized declaration evidence. Explicit import discovery supports declared paths, directory searches, and globs; load-wide defaults and source-local empty-selection evidence cross the root facade without changing acquisition order. Import and inheritance resolution share dependency-ready scheduling within their composition scopes. It retains each source's effective placement alongside physical source identity and owns schema inspection, lifecycle coordination, callback auditing, provenance/history, passive source-context retention, secret resolution and bootstrap, safe inspection rendering, and effective-value comparison over frozen inspection snapshots. It never imports the root package.
• Root Source, Filesystem, Input, Underlay, Path, Secret, records, lifecycle callbacks, results, and bootstrap reports are root-defined wrappers or records. Callback wrappers pass only live engine context during a callback; Result.Config is detached and its private inspection remains frozen independently.
• Root conversion files explicitly cross the path, record, callback, secret, and error boundaries. There are no public aliases, anonymous engine embeddings, or public engine bridge methods.
• Root Diff and Difference provide the public comparison boundary and convert detached engine records to root-owned paths and snapshots; consumer examples own presentation of the safe changed regions.
• internal/document owns the parser-independent ordered tree and cloning. internal/yaml is the sole upstream YAML adapter and parser/dumper boundary.
• Engine mechanism tests own source, composition, inheritance, decoding, callback, provenance, source-context, secret, history, rendering, and bootstrap behavior. Root tests own public API compatibility, facade integration, documentation links, and dependency/public boundary checks. Consumer examples remain under examples/consumers.

Dependency direction is root to engine to document/YAML support. The root may import only internal/engine among project internal production packages; engine and its supporting packages do not import root. The root boundary test enforces these constraints and rejects exported aliases, fields, or signatures involving internal types.

The configuration contract owns implemented YAML and lifecycle semantics, including input destinations, shared source-version checks, and effective configuration diffs. The strict composition contract owns sequence placement, registration, replacement, and history behavior; the consumer guide shows the maintained example. The consumer adoption guide owns application guidance. The architecture policy owns contributor boundaries; ADR 0006 records the facade decision and ADR 0010 records the diff decision; ADR 0011 records the placement decision. See the development guide for validation commands and release procedure for source-candidate gates. ADR 0009 records why inheritance is a built-in post-assembly structural operation. ADR 0012 records the relative-import extension; ADR 0013 records the source-version decision. ADR 0014 records explicit sequence placement and composition. ADR 0015 records the shared dependency-ready ordering decision; ADR 0016 records the independent selection controls. The import internals document candidate and namespace identities, discovery and scheduling, and the bounded algorithms.