161 lines
10 KiB
Markdown
161 lines
10 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 and
|
|
explicitly selected configuration discovery. A search resolves once during
|
|
shared acquisition; the selected concrete file or absent-input state then
|
|
follows the existing composition, metadata, and resource-context lifecycle.
|
|
It also owns grouped strict composition, recursive precedence assembly,
|
|
per-input mapping and sequence-item placement, YAML collection declarations
|
|
and operations for identified sequences, and application identity registrations for strict
|
|
composition, inheritance, and final validation. It applies the selected
|
|
collection operation at precedence boundaries and owns dependency-ready,
|
|
destination-local inheritance before typed decoding. CLI assignment follows
|
|
inheritance and decoding, before application resolution. The engine also owns
|
|
shared source-version checking with sanitized declaration evidence.
|
|
Explicit import discovery supports declared paths, directory searches, and
|
|
globs; root-owned defaults are converted to the engine's single defaults input
|
|
and snapshotted during load preflight before acquisition, while source-local
|
|
empty-selection evidence crosses the facade without changing acquisition
|
|
order. The root constructs placement directly on engine options and inputs
|
|
using explicit enum conversion; public types and fields remain root-owned.
|
|
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, operation-local secret failure-location attribution, 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,
|
|
search-description, 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
|
|
[configuration discovery](../config.md#configuration-discovery),
|
|
[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 declarations, identity, operations, ownership, and final
|
|
validation; [CLI overrides](../config.md#explicit-cli-overrides) own override
|
|
ordering. The [consumer guide](../consumers/README.md#identified-prompt-sequences)
|
|
links maintained workflow examples.
|
|
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. [ADR 0017](../adr/0017-collection-sequence-policy.md) and
|
|
[ADR 0018](../adr/0018-cli-after-structural-resolution.md) record collection
|
|
operations and CLI ordering. [ADR 0019](../adr/0019-explicit-configuration-discovery.md)
|
|
records explicit main-file discovery. The [import internals](imports.md)
|
|
document candidate and namespace identities, discovery and scheduling, and the
|
|
bounded algorithms.
|
|
|
|
## Implementation flow
|
|
|
|
The root facade converts caller-owned values into engine-owned requests. Its
|
|
`ImportDefaults` conversion maps fields without taking ownership; engine load
|
|
preflight snapshots the defaults once before source acquisition or callbacks.
|
|
Ordinary and grouped loading then carry that read-only value through their
|
|
normalized `loadRequest` and acquisition policy, while declaration resolution
|
|
copies values needed by its independently owned effective policy. Placement is
|
|
constructed directly on the engine's options and input records after explicit
|
|
root-to-engine enum conversion. See
|
|
[`lifecycle.go`](../../lifecycle.go), [`layered.go`](../../layered.go), and
|
|
[`load_request.go`](../../internal/engine/load_request.go). Load-wide definition,
|
|
version, default-import, and override policy stays distinct from each input's
|
|
source, filesystem, destination, and import settings.
|
|
|
|
[`acquisition.go`](../../internal/engine/acquisition.go) defines acquisition
|
|
policy, load-wide accounting, and tier-scoped repetition/namespace state. Each
|
|
input is acquired under that policy; grouped requests retain acquired underlay
|
|
scopes until their tier is composed in
|
|
[`load_request.go`](../../internal/engine/load_request.go). Completed tiers then
|
|
share one assembly handoff that applies collection declarations and projects
|
|
only that tier's source/version evidence; the caller keeps main-version
|
|
protection and its projection explicit. Live
|
|
filesystem access handles are confined to acquisition and closed there. Resolved
|
|
filesystem facts used to authorize access are separate from passively retained
|
|
resource contexts. Non-import validation retains those facts on `assembledInput`
|
|
for passive-context construction and ordinary-overlay handling: see
|
|
[`filesystem_context.go`](../../internal/engine/filesystem_context.go) and
|
|
[`source_context.go`](../../internal/engine/source_context.go).
|
|
|
|
Import responsibilities are split across candidate selection and path
|
|
normalization in [`import_selection.go`](../../internal/engine/import_selection.go),
|
|
source reading and traversal admission in
|
|
[`import_acquisition.go`](../../internal/engine/import_acquisition.go),
|
|
directory walking in [`directory_walk.go`](../../internal/engine/directory_walk.go),
|
|
dependency graph scheduling in [`import_graph.go`](../../internal/engine/import_graph.go),
|
|
and projection of acquired evidence into final source coordinates in
|
|
[`import_projection.go`](../../internal/engine/import_projection.go). The
|
|
[import internals](imports.md) page describes the boundaries and identities.
|
|
|
|
After acquisition handles are closed, grouped composition and inheritance run on
|
|
the retained ordered documents. `inheritance.go` coordinates traversal and
|
|
[`inheritance_schedule.go`](../../internal/engine/inheritance_schedule.go) applies
|
|
dependency-ready templates;
|
|
[`inheritance_prepare.go`](../../internal/engine/inheritance_prepare.go)
|
|
prepares child and parent inputs,
|
|
[`inheritance_combine.go`](../../internal/engine/inheritance_combine.go)
|
|
returns the combined value with its origin, policy, sequence, and diagnostic
|
|
evidence, and [`inheritance_finalize.go`](../../internal/engine/inheritance_finalize.go)
|
|
accounts for and finalizes the result. Projection and schema work have separate
|
|
operation owners: [`value_operation.go`](../../internal/engine/value_operation.go)
|
|
holds per-operation state, [`projection.go`](../../internal/engine/projection.go)
|
|
builds projected values, [`schema.go`](../../internal/engine/schema.go) owns
|
|
descriptor caching and type policy, and
|
|
[`schema_fields.go`](../../internal/engine/schema_fields.go) owns ordinary and
|
|
inline field assembly. [`decode.go`](../../internal/engine/decode.go) consumes
|
|
those descriptors for typed decoding.
|
|
|
|
Behavioral ownership follows the same handoffs: imports and grouped lifetimes are
|
|
covered by `imports_test.go`, `load_request_test.go`, and focused source,
|
|
discovery, and destination tests; inheritance by the inheritance test files;
|
|
reflection behavior by `schema_test.go`, `projection_test.go`, and
|
|
`decode_test.go`. The [development test map](../development.md#task-to-test-map)
|
|
links focused commands. [`clone.go`](../../internal/engine/clone.go) owns typed
|
|
copying, using the shared descriptors and per-operation traversal helpers.
|