eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify implementation discipline and provenance feature scope

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-12 13:05:00 +00:00
parent 381430a24b
commit 818d36f836
3 changed files with 108 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/roadmap/source-origins-during-resolution.md
View File

@@ -107,7 +107,9 @@ source still supplies no directory, and the application must choose its fallback
Multiple locations do not imply one declaring file. Consumers needing a single
file must inspect the exact value's origin and source records and handle ambiguity
explicitly. No new `DeclaringFile` shortcut should silently discard contributors.
according to application policy. ConfigKit does not require rejection: an
application may choose an explicit fallback, retain a relative value, warn, or
report an error. No new `DeclaringFile` shortcut should silently discard contributors.
### Lifetime and detachment
@@ -150,18 +152,20 @@ overlay history before calling `runResolution`. Pass a read-only entry-state
provenance view and the load's acquired source records into the private resolution
state. No public parser types or new external dependencies are needed.
The view must have complete effective semantic-path indexing when the callback
The view must support complete effective semantic-path lookup when the callback
starts. Current result metadata indexes are finalized later; exposing an unfinished
`Metadata` value would make legitimate lookups fail. Reuse or factor existing
effective-path traversal and shape matching so entry queries and final queries
cannot acquire different path semantics. A full historical index or public
`Metadata.History` interface during resolution is not required by this feature.
Keep the view independent of metadata updates performed after resolution.
Implementations may share immutable backing data privately while returning detached
records; do not copy an entire configuration tree per query. Source lookup should
use a per-load index or equivalent bounded existing mechanism, rather than requiring
each consumer to rebuild source bookkeeping.
Keep queries stable across consumer normalization and return detached records.
Private copying, immutable sharing, or ownership transfer may satisfy that contract;
no particular backing representation or eager-copy strategy is required. Prefer
existing traversal/indexing machinery and proportionate allocation. A per-load
source index is a recommended mechanism, not a public complexity guarantee or a
prohibition on scanning the bounded existing source collection. Consumers should
not need to rebuild source bookkeeping themselves.
The source and input views remain bounded by existing load limits. They contain
provenance records, not configuration values or resolved credentials. Do not read
@@ -207,14 +211,22 @@ behavioral owners rather than duplicate every mechanism at every layer. Acceptan
does not require a live Notarius checkout, external credentials, or target-file
existence checks.
## Explicit exclusions
## Scope and existing boundaries
Do not add automatic path-string recognition, filesystem path normalization,
existence checks, path confinement, default/CLI base selection, source discovery,
new import/profile composition rules, historical value access during resolution,
automatic move tracking, post-load mutability, or a general provenance service.
Application responsibilities remain application responsibilities: interpreting
path-valued strings, normalizing filesystem paths, choosing default/CLI bases,
and deciding whether to check existence, impose confinement, or use fallbacks.
This feature neither performs those operations nor prohibits consumers from doing so.
Actual Notarius integration remains downstream work.
Existing contracts, including import/profile composition and frozen post-load
inspection, remain unchanged. Their authority comes from the current contracts,
not from this roadmap's exclusions.
Source discovery, historical value access during resolution, automatic move
tracking, and a general provenance service are not included in this feature.
That scope choice is not a repository-wide prohibition on future proposals.
## Compatibility and canonical ownership
This is an additive public capability; existing callbacks, loading order, and