79 lines
5.0 KiB
Markdown
79 lines
5.0 KiB
Markdown
# 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](../config.md) owns implemented YAML and lifecycle
|
|
semantics, including [input destinations](../config.md#input-destinations),
|
|
[shared source-version checks](../config.md#shared-source-version-checks), and
|
|
[effective configuration diffs](../config.md#effective-configuration-diffs).
|
|
The [strict composition contract](../config.md#strict-document-composition)
|
|
owns sequence placement, registration, replacement, and history behavior; the
|
|
[consumer guide](../consumers/README.md#identified-prompt-sequences) shows the
|
|
maintained example.
|
|
The [consumer adoption guide](../consumers/README.md) owns application guidance.
|
|
The [architecture policy](../policy/architecture.md) owns contributor
|
|
boundaries; [ADR 0006](../adr/0006-public-facade.md) records the facade decision
|
|
and [ADR 0010](../adr/0010-effective-configuration-diff.md) records the diff
|
|
decision; [ADR 0011](../adr/0011-input-destinations.md) records the placement
|
|
decision. See the [development guide](../development.md) for validation commands
|
|
and [release procedure](../release.md) for source-candidate gates. [ADR
|
|
0009](../adr/0009-sibling-inheritance.md) records why inheritance is a built-in
|
|
post-assembly structural operation. [ADR 0012](../adr/0012-relative-import-destinations.md)
|
|
records the relative-import extension; [ADR 0013](../adr/0013-shared-source-version-checks.md)
|
|
records the source-version decision.
|
|
[ADR 0014](../adr/0014-sequence-placement-and-composition.md) records explicit
|
|
sequence placement and composition. [ADR 0015](../adr/0015-shared-dependency-ready-ordering.md)
|
|
records the shared dependency-ready ordering decision; [ADR
|
|
0016](../adr/0016-independent-import-controls.md) records the independent
|
|
selection controls. The [import internals](imports.md) document candidate and
|
|
namespace identities, discovery and scheduling, and the bounded algorithms.
|