diff --git a/docs/consumers/README.md b/docs/consumers/README.md index 3474fcf..892aa77 100644 --- a/docs/consumers/README.md +++ b/docs/consumers/README.md @@ -6,6 +6,30 @@ applications. Consumers still own their configuration structs, defaults, semanti validation, schema-version policy, CLI parsing, runtime matching and conversion, resource checks, remote acquisition, and service initialization. +## Choosing a loading entry point + +- Use [`Load`](../../lifecycle.go) with one source for an ordinary configuration. + [`SearchConfig`](../../discovery.go) is also a source, so its explicit + discovery result can be passed to `Load` or used as the main input to + [`LoadLayered`](../../layered.go). +- Use `LoadLayered` when inputs must be composed in underlay groups before the + main source. Each [`Input`](../../layered.go) owns its source, filesystem, + destination, and import choice. The overlay filesystem context is selected + independently in [`LayeredOptions`](../../layered.go). +- Load-wide rules belong to [`Options`](../../lifecycle.go) or + [`LayeredOptions`](../../layered.go): the application definition (including + version policy), import defaults, and explicit overrides. These do not turn + on imports or discovery by themselves. See the + [configuration contract](../config.md#layered-loading) and + [discovery contract](../config.md#configuration-discovery) for exact rules. + +The root [README example](../../README.md) shows the small `Load` path. +[`layered.go`](../../examples/consumers/layered.go) demonstrates the bundled +file and layered cases. For import-focused adoption, see the +[prompt catalog](../../examples/consumers/prompt_catalog.go); for explicit +discovery composed with sequences, see the +[sequence catalog](../../examples/consumers/sequence_catalog.go). + The maintained [`examples/consumers`](../../examples/consumers) package demonstrates sanitized shapes using only ConfigKit and the Go standard library: diff --git a/docs/development.md b/docs/development.md index 277927e..1a7ba05 100644 --- a/docs/development.md +++ b/docs/development.md @@ -240,17 +240,17 @@ code changes. Use the component overview to find the corresponding implementatio | Task | Behavioral test owners | Focused command | | --- | --- | --- | | YAML syntax, diagnostics, parser limits | [Adapter tests](../internal/yaml/parse_test.go), [source translation](../internal/engine/parse_test.go) | `go test ./internal/yaml` and `go test ./internal/engine -run '^TestParseSource'` | -| File/reader access, imports, globs, containment | [Sources](../internal/engine/source_test.go), [FIFO](../internal/engine/source_fifo_test.go), [imports](../internal/engine/imports_test.go), [relative destinations](../internal/engine/destination_import_test.go), [globs](../internal/engine/glob_test.go) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` | +| File/reader access, imports, globs, containment | [Import internals](internal/imports.md), [source acquisition](../internal/engine/source_test.go), [FIFO](../internal/engine/source_fifo_test.go), [import traversal](../internal/engine/imports_test.go), [import evidence](../internal/engine/import_evidence_test.go), [relative destinations](../internal/engine/destination_import_test.go), [globs](../internal/engine/glob_test.go) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` | | Explicit main-file discovery and absent-input loading | [Candidate selection](../internal/engine/discovery_test.go), [load integration](../internal/engine/discovery_load_test.go), [public facade](../facade_discovery_test.go), and maintained [catalog](../examples/consumers/sequence_catalog_test.go) and [preset](../examples/consumers/discovery_test.go) examples | `go test ./internal/engine -run 'Discovery|Search'`, `go test . -run 'Search'`, and `go test ./examples/consumers -run 'WorkingDirectoryPreset|SequenceCatalog'` | | Import defaults, empty-selection evidence, and dependency-ready ordering | [Defaults and facade evidence](../facade_import_defaults_test.go), [engine import evidence](../internal/engine/import_evidence_test.go), [scheduler](../internal/engine/dependency_order_test.go), [scheduling integrations](../internal/engine/imports_test.go) | `go test ./internal/engine -run 'Import|ScheduleDependencies|Inheritance'`, `go test . -run 'ImportDefaults|FacadeImport'`, and `go test ./examples/consumers` | | Native filesystem and mapping sources | [Native acquisition](../internal/engine/native_filesystem_test.go), [filesystem facade](../facade_filesystem_test.go), [mapping facade](../facade_mapping_test.go) | `go test ./internal/engine -run 'NativeFilesystem'` and `go test . -run 'TestFacade'` | | Composition, selected overlays, CLI precedence | [Composition](../internal/engine/compose_test.go), [overlay](../internal/engine/overlay_test.go), [selected overlays](../internal/engine/selected_overlay_test.go), [overrides](../internal/engine/override_test.go) | `go test ./internal/engine -run 'Compose\|Overlay\|Override'` | | Sequence identity, declarations, and operations | [Identity](../internal/engine/sequence_identity_test.go), [registrations](../internal/engine/sequence_registration_test.go), [declarations](../internal/engine/sequence_declaration_test.go), [combination](../internal/engine/sequence_combine_test.go), [final facade validation](../facade_final_sequence_identity_test.go), and [consumer catalog](../examples/consumers/sequence_catalog_test.go) | `go test ./internal/engine -run 'Sequence\|Collection'`, `go test . -run 'SequenceIdentity\|SequenceRegistration'`, and `go test ./examples/consumers` | -| Sibling inheritance, provenance, history, sensitivity | [Expansion](../internal/engine/inheritance_test.go), [destination scopes](../internal/engine/inheritance_walk_test.go), [origins](../internal/engine/inheritance_origin_test.go), [history](../internal/engine/inheritance_history_test.go), [secrets](../internal/engine/inheritance_secret_test.go), [public loading](../facade_inheritance_test.go) | `go test ./internal/engine -run 'Inheritance\|Inherited'` and `go test . -run '^TestFacadeInheritance\|^TestFacadeInheritedSecrets'` | +| Sibling inheritance, provenance, history, sensitivity | [Implementation flow](internal/overview.md#implementation-flow), [expansion](../internal/engine/inheritance_test.go), [destination scopes](../internal/engine/inheritance_walk_test.go), [origins](../internal/engine/inheritance_origin_test.go), [history](../internal/engine/inheritance_history_test.go), [secrets](../internal/engine/inheritance_secret_test.go), [public loading](../facade_inheritance_test.go) | `go test ./internal/engine -run 'Inheritance\|Inherited'` and `go test . -run '^TestFacadeInheritance\|^TestFacadeInheritedSecrets'` | | Layered loading and source equivalence | [Grouped lifecycle](../internal/engine/load_request_test.go), [layered facade](../facade_layered_test.go), [equivalence](../facade_equivalence_test.go) | `go test ./internal/engine -run '^TestGrouped'`, `go test . -run '^TestFacadeLayered'`, and `go test . -run '^TestEquivalentSourceForms'` | | Input and relative-import destinations, mounted sources, and source ownership | [Destination engine tests](../internal/engine/destination_test.go), [tier tests](../internal/engine/destination_tiers_test.go), [import traversal and version tests](../internal/engine/destination_import_test.go), [accounting tests](../internal/engine/destination_accounting_test.go), [lifecycle inspection tests](../internal/engine/destination_import_lifecycle_test.go), [public source/error tests](../facade_destination_test.go), [resource contexts](../facade_resource_context_test.go), and [consumer examples](../examples/consumers/destinations_test.go) | `go test ./internal/engine -run 'Destination|Import|Glob|Mounted'`, `go test . -run 'Destination|Import|SourceContext|FacadeMounted'`, and `go test ./examples/consumers` | | Shared source-version modes and evidence | [Engine source-version tests](../internal/engine/source_version_test.go), [public facade tests](../facade_source_version_mode_test.go), and [consumer example tests](../examples/consumers/layered_test.go) | `go test ./internal/engine -run 'SourceVersion'`, `go test . -run 'SourceVersion'`, and `go test ./examples/consumers` | -| Schema, defaults, projection, cloning | [Schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` | +| Schema, defaults, projection, cloning | [Implementation flow](internal/overview.md#implementation-flow), [schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection and typed cloning](../internal/engine/projection_test.go), [deferred clone review](roadmap/future.md#4-clone-traversal-review) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` | | Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` | | Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` | | Passive resource contexts | [Engine contexts](../internal/engine/resource_context_test.go), [public contexts](../facade_resource_context_test.go) | `go test ./internal/engine -run 'Resource'` and `go test . -run 'SourceContext'` | diff --git a/docs/internal/imports.md b/docs/internal/imports.md index 8424c23..5f105f8 100644 --- a/docs/internal/imports.md +++ b/docs/internal/imports.md @@ -7,7 +7,10 @@ This note records implementation flow and private identities for maintainers. ## Discovery and acquisition Each source's root directive is parsed into presence-aware declarations and -resolved against load-wide defaults. Candidate selection preserves a normalized +resolved against load-wide defaults. `acquisition.go` owns shared acquisition +policy, load accounting, and per-tier accounting; `import_acquisition.go` owns +reading candidate bytes, declaration traversal, and import admission. Candidate +selection in `import_selection.go` preserves a normalized namespace path separately from canonical access identity: overlapping roots coalesce the same candidate spelling in that namespace, while aliases reached through distinct spellings retain separate inclusion routes for admission. @@ -20,10 +23,14 @@ Directory traversal tracks canonical directories on the active traversal path. It adds an identity when descending and removes it when the frame is popped, so only a back-edge to an active directory is a traversal cycle; a later alias is not mistaken for one. This is separate from import dependency-cycle detection. -For host sources, discovery uses rooted `Lstat` and canonical containment. Native -sources use `fs.ReadLinkFS` inspection when supplied; otherwise traversal follows -the capabilities and behavior of the provided `fs.FS`, without claiming a -general sandbox guarantee. +For host sources, discovery uses rooted `Lstat` and canonical containment. +`filesystem_context.go` owns resolved access facts and live access setup; the +acquisition operation closes its live handles before composition. Native sources +use `fs.ReadLinkFS` inspection when supplied; otherwise traversal follows the +capabilities and behavior of the provided `fs.FS`, without claiming a general +sandbox guarantee. `source_context.go` derives passive resource contexts from +resolved sources for later caller-owned reads; those records do not retain live +acquisition handles. Acquisition remains authored: declarations are visited in source order and each selected candidate set in namespace-path lexical order. This preserves source @@ -78,10 +85,14 @@ mapping order in its output. These scopes do not flatten into one global graph, and independent precedence tiers remain separate. -The main owners are [`import_selection.go`](../../internal/engine/import_selection.go), +The owners are [`acquisition.go`](../../internal/engine/acquisition.go), +[`import_selection.go`](../../internal/engine/import_selection.go), +[`import_acquisition.go`](../../internal/engine/import_acquisition.go), [`directory_walk.go`](../../internal/engine/directory_walk.go), [`import_graph.go`](../../internal/engine/import_graph.go), +[`import_projection.go`](../../internal/engine/import_projection.go), [`dependency_order.go`](../../internal/engine/dependency_order.go), and [`inheritance_schedule.go`](../../internal/engine/inheritance_schedule.go). -Their focused behavior is covered by import-selection, scheduler, and scheduling -integration tests under `internal/engine`. +Their focused behavior is covered by import-selection, acquisition, scheduler, +and scheduling integration tests under `internal/engine`; see the +[development test map](../development.md#task-to-test-map). diff --git a/docs/internal/overview.md b/docs/internal/overview.md index f0fdeb2..70395b6 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -87,3 +87,58 @@ operations and CLI ordering. [ADR 0019](../adr/0019-explicit-configuration-disco 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. The +ordinary and grouped entry points share a normalized `loadRequest`: 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 and load-wide and per-tier accounting 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). 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: 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. Typed clone extraction remains deferred in +[`future.md`](../roadmap/future.md#4-clone-traversal-review). diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 3108ab0..735e153 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # Consolidation Implementation Plan -Status: in progress. Stages 1 through 18 are complete; follow Stage 19 through Stage 20 in order. +Status: in progress. Stages 1 through 19 are complete; follow Stage 20. The target executor is a Luna coding agent working through one end-to-end sprint. ## Authority, Baseline, And Execution @@ -710,7 +710,7 @@ flattened fields and inline-map metadata. Validation group R passed. **Finish:** field discovery and descriptor assembly have explicit responsibilities without a new registration framework. Run R for both Stages 17–18. -## Stage 19 — Update Consumer And Internal Navigation +## Stage 19 — Update Consumer And Internal Navigation (Complete) **Owners:** `docs/consumers/README.md`, `docs/internal/overview.md`, `docs/internal/imports.md`, and affected links/test-owner entries in @@ -733,6 +733,12 @@ without a new registration framework. Run R for both Stages 17–18. clone work in `future.md`. No policy change or new ADR is needed for the selected private refactor. +Progress notes (2026-10-25): added a consumer entry-point and ownership guide, +linked the existing adoption examples, and documented normalized requests, +acquisition/context lifetimes, import owners, and inheritance/projection/schema +handoffs. Updated test navigation and retained clone review as deferred. +Documentation links and repository boundaries passed. + **Finish:** current documentation describes implemented structure, with the roadmap/plan retaining future work and progress until release cleanup.