Prepare ConfigKit v0.1.0

README.md

@@ -33,9 +33,7 @@ func ReadConfig(path string) (Config, error) {
 The [configuration contract](docs/config.md) describes implemented behavior. The
 [consumer adoption guide](docs/consumers/README.md) provides maintained Narratio-,
 Notarius-, WeatherReporter-, and Seriatim-shaped examples and migration guidance.
-The [initial target record](docs/roadmap/initial.md) links implemented feature owners
-and preserves deliberately deferred scope. The [implementation plan](docs/roadmap/implementation.md)
-records completion evidence until release-candidate preparation retires it. See the
+The [deferred scope](docs/roadmap/deferred.md) records deliberate exclusions. See the
 [development guide](docs/development.md) for repository orientation and the
 [release procedure](docs/release.md) for maintainer-only candidate and publication
 steps.

clone.go

@@ -0,0 +1,159 @@
+package configkit
+
+import (
+	"encoding"
+	"math"
+	"reflect"
+)
+
+// secretCloneMode distinguishes fresh unresolved references from publication of
+// already validated private state, which must not trigger another lookup.
+type secretCloneMode uint8
+
+const (
+	cloneUnresolvedSecrets secretCloneMode = iota
+	cloneValidatedSecrets
+)
+
+func cloneConfiguration(schema *schemaDescriptor, value reflect.Value, limits projectionLimits) (reflect.Value, *projectionIssue) {
+	return cloneConfigurationWithMode(schema, value, limits, cloneUnresolvedSecrets)
+}
+
+func cloneConfigurationWithMode(schema *schemaDescriptor, value reflect.Value, limits projectionLimits, mode secretCloneMode) (reflect.Value, *projectionIssue) {
+	if schema == nil || schema.root == nil || !value.IsValid() || value.Type() != schema.root.typeOf {
+		return reflect.Value{}, &projectionIssue{code: CodeSchemaUnsupportedType, message: "configuration value does not match its schema"}
+	}
+	operation := valueOperation{schema: schema, limits: limits, active: make(map[valueVisit]bool), cloneMode: mode}
+	return operation.clone(value, schema.root, Path{}, 0)
+}
+
+func (o *valueOperation) clone(value reflect.Value, descriptor *typeDescriptor, path Path, depth int) (reflect.Value, *projectionIssue) {
+	if issue := o.checkDepth(path, depth); issue != nil {
+		return reflect.Value{}, issue
+	}
+	if descriptor.kind == descriptorPointer {
+		if value.IsNil() {
+			return reflect.Zero(value.Type()), nil
+		}
+		leave, issue := o.enter(value, path)
+		if issue != nil {
+			return reflect.Value{}, issue
+		}
+		defer leave()
+		child, issue := o.clone(value.Elem(), descriptor.element, path, depth)
+		if issue != nil {
+			return reflect.Value{}, issue
+		}
+		result := reflect.New(value.Type().Elem())
+		result.Elem().Set(child)
+		return result, nil
+	}
+
+	switch descriptor.kind {
+	case descriptorStruct:
+		result := reflect.New(value.Type()).Elem()
+		for _, member := range descriptor.members {
+			memberPath, memberDepth := path, depth
+			if !member.inline {
+				memberPath, memberDepth = path.Key(member.name), depth+1
+			}
+			cloned, issue := o.clone(value.Field(member.index), member.descriptor, memberPath, memberDepth)
+			if issue != nil {
+				return reflect.Value{}, issue
+			}
+			result.Field(member.index).Set(cloned)
+		}
+		return result, nil
+	case descriptorMap:
+		if value.IsNil() {
+			return reflect.Zero(value.Type()), nil
+		}
+		leave, issue := o.enter(value, path)
+		if issue != nil {
+			return reflect.Value{}, issue
+		}
+		defer leave()
+		result := reflect.MakeMapWithSize(value.Type(), value.Len())
+		for _, key := range value.MapKeys() {
+			cloned, issue := o.clone(value.MapIndex(key), descriptor.element, path.Key(key.String()), depth+1)
+			if issue != nil {
+				return reflect.Value{}, issue
+			}
+			result.SetMapIndex(key, cloned)
+		}
+		return result, nil
+	case descriptorSlice:
+		if value.IsNil() {
+			return reflect.Zero(value.Type()), nil
+		}
+		leave, issue := o.enter(value, path)
+		if issue != nil {
+			return reflect.Value{}, issue
+		}
+		defer leave()
+		result := reflect.MakeSlice(value.Type(), value.Len(), value.Len())
+		for i := 0; i < value.Len(); i++ {
+			cloned, issue := o.clone(value.Index(i), descriptor.element, path.Index(i), depth+1)
+			if issue != nil {
+				return reflect.Value{}, issue
+			}
+			result.Index(i).Set(cloned)
+		}
+		return result, nil
+	case descriptorArray:
+		result := reflect.New(value.Type()).Elem()
+		for i := 0; i < value.Len(); i++ {
+			cloned, issue := o.clone(value.Index(i), descriptor.element, path.Index(i), depth+1)
+			if issue != nil {
+				return reflect.Value{}, issue
+			}
+			result.Index(i).Set(cloned)
+		}
+		return result, nil
+	case descriptorDynamic:
+		if value.IsNil() {
+			return reflect.Zero(value.Type()), nil
+		}
+		concrete := value.Elem()
+		dynamic, issue := o.dynamicDescriptor(concrete.Type(), path)
+		if issue != nil {
+			return reflect.Value{}, issue
+		}
+		cloned, issue := o.clone(concrete, dynamic, path, depth)
+		if issue != nil {
+			return reflect.Value{}, issue
+		}
+		result := reflect.New(value.Type()).Elem()
+		result.Set(cloned)
+		return result, nil
+	case descriptorSecret:
+		result := reflect.New(value.Type()).Elem()
+		reference := value.Interface().(Secret)
+		if o.cloneMode == cloneValidatedSecrets {
+			result.Set(value)
+		} else if reference.specified {
+			result.Set(reflect.ValueOf(SecretEnv(reference.EnvName())))
+		}
+		return result, nil
+	case descriptorText:
+		text, issue := marshalCanonicalText(value, path)
+		if issue != nil {
+			return reflect.Value{}, issue
+		}
+		result := reflect.New(value.Type()).Elem()
+		unmarshaler := result.Addr().Interface().(encoding.TextUnmarshaler)
+		if err := unmarshaler.UnmarshalText([]byte(text)); err != nil {
+			return reflect.Value{}, &projectionIssue{code: CodeSchemaCodec, path: path.clone(), message: "custom text scalar could not be reconstructed"}
+		}
+		return result, nil
+	case descriptorFloat:
+		if math.IsNaN(value.Float()) || math.IsInf(value.Float(), 0) {
+			return reflect.Value{}, &projectionIssue{code: CodeSchemaNonFinite, path: path.clone(), message: "configuration float must be finite"}
+		}
+		fallthrough
+	default:
+		result := reflect.New(value.Type()).Elem()
+		result.Set(value)
+		return result, nil
+	}
+}

compose.go

@@ -15,6 +15,17 @@ type composedDocument struct {
 	inputNodes   int
 }
 
+// cloneComposedDocument detaches mutable composition and provenance state;
+// history application trees are immutable and retain their existing sharing.
+func cloneComposedDocument(base *composedDocument) *composedDocument {
+	return &composedDocument{
+		root: document.Clone(base.root), claims: cloneCompositionClaims(base.claims),
+		origins: cloneOriginIndex(base.origins), overlays: cloneOverlayRecords(base.overlays),
+		applications: cloneHistoryApplications(base.applications),
+		inputBytes:   base.inputBytes, inputNodes: base.inputNodes,
+	}
+}
+
 type compositionClaim struct {
 	path     Path
 	kind     document.Kind

compose_test.go

@@ -56,7 +56,7 @@ values: [one, two]
 	if len(reversedDiagnostics) != 0 {
 		t.Fatalf("reversed composeDocuments() diagnostics = %#v", reversedDiagnostics)
 	}
-	if deltas := compareDocumentTrees(composed.root, reversed.root); len(deltas) != 0 {
+	if deltas := compareConfigurationValues(composed.root, reversed.root); len(deltas) != 0 {
 		t.Fatalf("input order changed effective values: %#v", deltas)
 	}
 

composition_fuzz_test.go

@@ -40,7 +40,7 @@ func FuzzCompositionAndOverlay(f *testing.F) {
 			if len(reversedDiagnostics) != 0 {
 				t.Fatalf("reversed composition failed: %#v", reversedDiagnostics)
 			}
-			if differences := compareDocumentTrees(composed.root, reversed.root); len(differences) != 0 {
+			if differences := compareConfigurationValues(composed.root, reversed.root); len(differences) != 0 {
 				t.Fatalf("composition order changed effective values: %#v", differences)
 			}
 			composed.root.Mapping = append(composed.root.Mapping, document.Entry{Key: "fuzz-detachment"})

diagnostic.go

@@ -237,3 +237,12 @@ func escapeControls(value string) string {
 	}
 	return b.String()
 }
+
+func hasErrors(diagnostics []Diagnostic) bool {
+	for _, diagnostic := range diagnostics {
+		if diagnostic.Severity == SeverityError {
+			return true
+		}
+	}
+	return false
+}

directives.go

@@ -0,0 +1,227 @@
+package configkit
+
+import (
+	"path"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+type importDeclaration struct {
+	path     string
+	glob     string
+	optional bool
+	location Location
+}
+
+func splitImportDirectives(root *document.Node) (*document.Node, []importDeclaration, []Diagnostic) {
+	body := document.Clone(root)
+	var declarations []importDeclaration
+	directiveIndex := -1
+	for index, entry := range body.Mapping {
+		if entry.Key != "_configkit" {
+			continue
+		}
+		directiveIndex = index
+		parsed, diagnostics := parseImportDirective(entry.Value, Keys("_configkit"))
+		if len(diagnostics) != 0 {
+			return nil, nil, diagnostics
+		}
+		declarations = parsed
+		break
+	}
+	if directiveIndex >= 0 {
+		body.Mapping = append(body.Mapping[:directiveIndex], body.Mapping[directiveIndex+1:]...)
+	}
+	if diagnostics := nestedDirectiveDiagnostics(body, Path{}); len(diagnostics) != 0 {
+		return nil, nil, diagnostics
+	}
+	return body, declarations, nil
+}
+
+func parseImportDirective(node *document.Node, directivePath Path) ([]importDeclaration, []Diagnostic) {
+	if node.Kind != document.Mapping {
+		return nil, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, directivePath, "configuration directive must be a mapping", node)}
+	}
+	var declarations []importDeclaration
+	for _, entry := range node.Mapping {
+		fieldPath := directivePath.Key(entry.Key)
+		if entry.Key != "imports" {
+			return nil, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "configuration directive field is not recognized", entry.Value)}
+		}
+		if entry.Value.Kind != document.Sequence {
+			return nil, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "imports must be a sequence", entry.Value)}
+		}
+		for index, item := range entry.Value.Sequence {
+			declaration, diagnostics := parseImportDeclaration(item, fieldPath.Index(index))
+			if len(diagnostics) != 0 {
+				return nil, diagnostics
+			}
+			declarations = append(declarations, declaration)
+		}
+	}
+	return declarations, nil
+}
+
+func parseImportDeclaration(node *document.Node, declarationPath Path) (importDeclaration, []Diagnostic) {
+	if node.Kind != document.Mapping {
+		return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, declarationPath, "import declaration must be a mapping", node)}
+	}
+	declaration := importDeclaration{location: publicLocation(node.Location)}
+	seenTarget := false
+	for _, entry := range node.Mapping {
+		fieldPath := declarationPath.Key(entry.Key)
+		switch entry.Key {
+		case "path", "glob":
+			if seenTarget || entry.Value.Kind != document.String || entry.Value.Text == "" || strings.TrimSpace(entry.Value.Text) != entry.Value.Text {
+				return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "import declaration requires exactly one nonempty path or glob string", entry.Value)}
+			}
+			seenTarget = true
+			declaration.location = publicLocation(entry.Value.Location)
+			if entry.Key == "path" {
+				declaration.path = entry.Value.Text
+			} else {
+				declaration.glob = entry.Value.Text
+			}
+		case "optional":
+			if entry.Value.Kind != document.Boolean {
+				return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "optional must be a boolean", entry.Value)}
+			}
+			declaration.optional = entry.Value.Text == "true"
+		default:
+			return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "import declaration field is not recognized", entry.Value)}
+		}
+	}
+	if !seenTarget {
+		return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, declarationPath, "import declaration requires exactly one path or glob", node)}
+	}
+	return declaration, nil
+}
+
+func nestedDirectiveDiagnostics(node *document.Node, current Path) []Diagnostic {
+	if node.Kind == document.Mapping {
+		for _, entry := range node.Mapping {
+			childPath := current.Key(entry.Key)
+			if entry.Key == "_configkit" {
+				location := publicLocation(entry.KeyLocation)
+				return []Diagnostic{{Code: CodeImportInvalid, Severity: SeverityError, Path: childPath, Message: "configuration directives are permitted only at the document root", Primary: &location}}
+			}
+			if diagnostics := nestedDirectiveDiagnostics(entry.Value, childPath); len(diagnostics) != 0 {
+				return diagnostics
+			}
+		}
+	} else if node.Kind == document.Sequence {
+		for index, child := range node.Sequence {
+			if diagnostics := nestedDirectiveDiagnostics(child, current.Index(index)); len(diagnostics) != 0 {
+				return diagnostics
+			}
+		}
+	}
+	return nil
+}
+
+func fragmentVersionClaim(root *document.Node, rule *VersionRule) *document.Node {
+	if rule == nil {
+		return nil
+	}
+	current := root
+	if len(rule.Path.segments) == 0 {
+		return current
+	}
+	for _, segment := range rule.Path.segments {
+		if current.Kind != document.Mapping {
+			return current
+		}
+		if segment.kind == pathSegmentIndex {
+			return nil
+		}
+		key := segment.key
+		index := documentEntryIndex(current.Mapping, key)
+		if index < 0 {
+			return nil
+		}
+		current = current.Mapping[index].Value
+	}
+	return current
+}
+
+func validImportPath(value string) bool {
+	if value == "" || strings.TrimSpace(value) != value || path.IsAbs(value) || strings.HasPrefix(value, "//") {
+		return false
+	}
+	return !hasImportScheme(value)
+}
+
+func hasImportScheme(value string) bool {
+	colon := strings.IndexByte(value, ':')
+	slash := strings.IndexByte(value, '/')
+	if colon <= 0 || (slash >= 0 && slash < colon) {
+		return false
+	}
+	for index := 0; index < colon; index++ {
+		character := value[index]
+		if index == 0 {
+			if (character < 'a' || character > 'z') && (character < 'A' || character > 'Z') {
+				return false
+			}
+			continue
+		}
+		if (character < 'a' || character > 'z') && (character < 'A' || character > 'Z') &&
+			(character < '0' || character > '9') && character != '+' && character != '-' && character != '.' {
+			return false
+		}
+	}
+	return true
+}
+
+func nodeImportDiagnostic(code Code, path Path, message string, node *document.Node) Diagnostic {
+	location := publicLocation(node.Location)
+	return Diagnostic{Code: code, Severity: SeverityError, Path: path, Message: message, Primary: &location}
+}
+
+func profileDirectiveDiagnostics(node *document.Node, current Path) []Diagnostic {
+	if node.Kind == document.Mapping {
+		for _, entry := range node.Mapping {
+			childPath := current.Key(entry.Key)
+			if entry.Key == "_configkit" {
+				location := publicLocation(entry.KeyLocation)
+				return []Diagnostic{{
+					Code: CodeProfileDirective, Severity: SeverityError, Path: childPath,
+					Message: "profiles cannot contain configuration directives", Primary: &location,
+				}}
+			}
+			if diagnostics := profileDirectiveDiagnostics(entry.Value, childPath); len(diagnostics) != 0 {
+				return diagnostics
+			}
+		}
+	} else if node.Kind == document.Sequence {
+		for index, child := range node.Sequence {
+			if diagnostics := profileDirectiveDiagnostics(child, current.Index(index)); len(diagnostics) != 0 {
+				return diagnostics
+			}
+		}
+	}
+	return nil
+}
+
+func disabledDirectiveDiagnostics(node *document.Node, path Path) []Diagnostic {
+	var diagnostics []Diagnostic
+	if node.Kind == document.Mapping {
+		for _, entry := range node.Mapping {
+			childPath := path.Key(entry.Key)
+			if entry.Key == "_configkit" {
+				location := Location{SourceID: entry.KeyLocation.SourceID, Line: entry.KeyLocation.Line, Column: entry.KeyLocation.Column}
+				diagnostics = append(diagnostics, Diagnostic{
+					Code: CodeImportDisabled, Severity: SeverityError, Path: childPath,
+					Message: "configuration directives require imports to be enabled", Primary: &location,
+				})
+			}
+			diagnostics = append(diagnostics, disabledDirectiveDiagnostics(entry.Value, childPath)...)
+		}
+	} else if node.Kind == document.Sequence {
+		for index, child := range node.Sequence {
+			diagnostics = append(diagnostics, disabledDirectiveDiagnostics(child, path.Index(index))...)
+		}
+	}
+	return diagnostics
+}

docs/development.md

@@ -1,21 +1,16 @@
 # Development
 
-This is the contributor entry point for ConfigKit. Read the task-specific owners
-below before making changes. Its public
-loader currently covers strict selected sources, explicit path/glob import graphs,
-composition, selected profile overlays, typed defaults, schema-version checks,
-explicit CLI overrides, recorded application resolution, semantic validation,
-layered metadata, secret
-classification, typed environment references, explicit secrets bootstrap, and
-redacted effective rendering and historical value explanation. The
-[component overview](internal/overview.md) owns the implementation inventory.
+Start here when contributing to ConfigKit. Read the task-specific owners below
+before making changes. The [component overview](internal/overview.md) maps
+implementation responsibilities; the [configuration contract](config.md) owns
+public behavior.
 
 ## Initial orientation
 
 1. Inspect the working tree and preserve unrelated changes.
 2. Read the architecture policy for code or design work.
 3. Read the policy, contract, and internal documents applicable to the task.
-4. Inspect relevant implementation and tests where they exist before changing them.
+4. Inspect the relevant implementation and behavioral tests before changing them.
 
 ## Task-specific reading guide
 
@@ -23,23 +18,29 @@ redacted effective rendering and historical value explanation. The
 | --- | --- |
 | Repository orientation or component responsibility | [Architecture policy](policy/architecture.md) and [component overview](internal/overview.md) |
 | Documentation changes | [Documentation policy](policy/documentation.md) and the owning document |
-| Architecture decisions or future work | [Documentation policy](policy/documentation.md), [initial target record](roadmap/initial.md), and relevant ADRs listed below |
-| Code and test changes | [Architecture policy](policy/architecture.md), [testing policy](policy/testing.md), and owning contracts/tests as they are introduced |
+| Architecture decisions or future work | [Documentation policy](policy/documentation.md), [deferred scope](roadmap/deferred.md), and relevant ADRs listed below |
+| Code and test changes | [Architecture policy](policy/architecture.md), [testing policy](policy/testing.md), and the owning contract and tests from the map below |
 | Examples or copyable assets | The owning implemented contract and [consumer adoption guide](consumers/README.md) |
-| Release preparation | [Release policy](policy/release.md), [release procedure](release.md), and [release-readiness evidence](roadmap/release-readiness.md) |
+| Release preparation | [Release policy](policy/release.md) and [release procedure](release.md) |
 
 Accepted decisions:
 
 - [Separate composition and overlay](adr/0001-separate-composition-and-overlay.md)
 - [Own YAML semantics behind a private parser boundary](adr/0002-own-yaml-semantics.md)
 - [Preserve presence and record application resolution](adr/0003-preserve-presence-and-resolution-history.md)
-
 - [Secret references and explicit bootstrap](adr/0004-secret-references-and-explicit-bootstrap.md)
 - [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
 
-For cross-cutting changes, follow every applicable row. The
-[implementation plan](roadmap/implementation.md) owns the ordered stages and their
-acceptance checks and recorded implementation evidence.
+For cross-cutting changes, follow every applicable row. Completed implementation
+and remediation plans are preserved in Git history at `cb5b435`; use current
+contracts and the component overview for ongoing work. For example:
+
+```sh
+git show cb5b435:docs/roadmap/remediation.md
+```
+
+Release-candidate, publication, and verification work follows the operational
+[release procedure](release.md).
 
 ## Baseline validation
 
@@ -51,27 +52,51 @@ environment:
 go mod download
 ```
 
-Run the library baseline from the repository root:
+Run the everyday check with Bash 3.2 or newer and Git:
 
 ```sh
-go test ./...
-go vet ./...
-go build ./...
-git diff --check
+./scripts/check.sh
 ```
 
-The default tests must remain deterministic and runnable without network access or
-credentials after dependency acquisition. Also inspect new untracked files, verify
-changed local links and heading fragments, and review paths, examples, ownership,
-and current-versus-planned claims. The commands above do not check links or
-untracked content. Do not use an application binary build as the library baseline.
-Add executable-example and other checks when those artifacts are introduced; do
-not document nonexistent tools as operational.
+[The script](../scripts/check.sh) runs from the repository root regardless of the
+invocation directory. It checks Go formatting without rewriting files, checks
+staged/unstaged and untracked whitespace, then runs `go test ./...`,
+`go vet ./...`, and `go build ./...`, stopping on the first failure. It uses the
+installed Go toolchain by default, honors an explicit `GOTOOLCHAIN`, and disables
+dependency downloads. Acquire dependencies and any selected toolchain beforehand.
+Format reported Go files with `gofmt -w <files>`.
 
-Once code exists, use focused checks while iterating and validation proportionate
-to the change under the testing policy. Documentation-only work does not require
-Go checks unless it changes behavior-bearing examples or commands they validate.
-Release validation is a separate, stricter gate governed by release policy.
+The default suite includes executable examples, maintained consumer fixtures,
+local documentation-link checks, and the dependency import-boundary check.
+It must stay deterministic and runnable without network access or credentials.
+Still inspect new/untracked content and review paths, examples, ownership, and
+current-versus-planned claims; automated checks do not replace content review.
+
+Use focused checks while iterating, with validation proportionate to the change
+under the testing policy. Documentation-only work normally needs the local-link
+check below and whitespace review; behavior-bearing examples and commands also
+need execution. Use `go test -race ./...` for ownership or concurrency changes.
+The separate [release checker](release.md#4-validate-the-source-candidate) adds
+two-toolchain, module-hygiene, race, and cross-build gates.
+
+## Task-to-test map
+
+Commands run from the repository root after dependency acquisition. These are
+starting points for focused iteration; run the everyday check before handing off
+code changes. Use the component overview to find the corresponding implementation.
+
+| Task | Behavioral test owners | Focused command |
+| --- | --- | --- |
+| YAML syntax, diagnostics, parser limits | [Adapter tests](../internal/yaml/parse_test.go), [source translation](../parse_test.go) | `go test ./internal/yaml` and `go test . -run '^TestParseSource'` |
+| File/reader access, imports, globs, containment | [Sources](../source_test.go), [FIFO](../source_fifo_test.go), [imports](../imports_test.go), [globs](../glob_test.go) | `go test . -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
+| Composition, profiles, CLI precedence | [Composition](../compose_test.go), [overlay](../overlay_test.go), [profiles](../profile_test.go), [overrides](../override_test.go) | `go test . -run 'Compose\|Overlay\|Profile\|Override'` |
+| Schema, defaults, projection, cloning | [Schema](../schema_test.go), [decoding](../decode_test.go), [projection](../projection_test.go) | `go test . -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
+| Lifecycle, resolution, validation, callback ownership | [Loading](../load_test.go), [resolution](../resolution_test.go), [validation](../validation_test.go), [ownership](../callback_ownership_test.go), [independence](../independence_test.go) | `go test . -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
+| Paths, metadata, provenance | [Paths](../path_test.go), [metadata](../metadata_test.go), [provenance](../provenance_test.go) | `go test . -run 'Path\|Metadata\|Provenance\|Queries'` |
+| Secrets, bootstrap, redaction, explanation | [References](../secret_reference_test.go), [bootstrap](../secrets_test.go), [rendering](../render_test.go), [explanation](../explain_test.go) | `go test . -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'` |
+| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
+| Documentation links and dependency isolation | [Link checks](../documentation_test.go), [import boundary](../import_boundary_test.go) | `go test . -run '^(TestLocalDocumentationLinks\|TestDependencyImportBoundary)$'` |
+| Check-command behavior | [Shell regression](../release_check_test.go) | `go test . -run '^TestCheckScripts'` |
 
 ## Fuzz validation
 

docs/internal/extraction.md

@@ -115,8 +115,9 @@ Assigned to explicit import traversal and glob handling:
   Canonical paths—not `os.SameFile`—define identity, so hard links remain distinct.
 
 Path-import implementation record (2026-09-06): `splitImportDirectives`,
-`parseImportDeclaration`, `importFilesystem`, `importTraversal.visitPath`, and
-`loadImportedDocuments` in `imports.go` adapt the assigned envelope, loading, source,
+`parseImportDeclaration` (now in `directives.go`), `importFilesystem` (now in
+`filesystem.go`), and `importTraversal.visitPath`/`loadImportedDocuments` in
+`imports.go` adapt the assigned envelope, loading, source,
 and failure mechanics. The corresponding ConfigKit tests adapt the assigned
 declaration-order, disjoint composition, keyed-entry, all-source conflict, unsafe
 target, alias, imported parse/schema, and relative-resolution cases. ConfigKit adds

docs/internal/overview.md

@@ -1,32 +1,43 @@
 # Internal Component Overview
 
-ConfigKit currently contains the root `configkit` package, which establishes the
-module and package documentation boundary. Its implemented public primitives are:
+ConfigKit exposes the root `configkit` package and keeps its document and YAML
+representations private. The implemented components and their owners are:
 
 - immutable semantic `Path` construction and strict JSON Pointer parsing;
-- detached provenance and diagnostic record types with empty `Metadata` queries;
+- detached effective presence/origin and chronological history queries in
+  `metadata.go`, with provenance and diagnostic record types;
 - canonical, control-safe diagnostic rendering and structured `LoadError` access;
-- opaque file, byte, reader, and no-input source construction and bounded reads;
-- a parser-independent ordered tree in `internal/document`;
+- opaque file, byte, reader, and no-input source construction in `source.go`,
+  with shared regular-file checks and bounded read mechanics in `source_file.go`;
+- a parser-independent ordered tree in `internal/document`, with root-private
+  semantic lookup, indexing, and value traversal in `document_walk.go`;
 - the sole upstream YAML integration in `internal/yaml`, which translates validated
   input into that owned tree and exposes no parser types outside its boundary;
+  `parse.go` owns shared translation into detached, ordered public diagnostics;
 - a private strict composer in `compose.go` that joins only disjoint document-tree
   definitions, retains ordered claims and composite mapping origins, reports every
   conflicting location, and never aliases an input tree;
 - fixed selected-profile loading in `profile.go` and recursive, non-aliasing overlay
-  with displacement records in `overlay.go`;
-- detached parser-neutral CLI override validation and synthetic-source application
-  in `override.go`, sharing overlay, source, byte, node, and depth policies;
+  with displacement records in `overlay.go`; overlay records retain origins,
+  while value explanation uses separate history applications;
+- CLI override validation/preparation in `override.go`, parser-neutral values in
+  `override_value.go`, and synthetic-source application in `override_apply.go`,
+  sharing overlay, source, byte, node, and depth policies;
 - a per-operation private reflection descriptor graph in `schema.go` for supported
   types, YAML field binding, inlining, secret tags, recursion, and semantic paths;
-- descriptor-driven canonical projection, detached typed cloning, cycle/limit
-  enforcement, and structural comparison in `projection.go`;
+- descriptor-driven canonical projection in `projection.go`, detached typed
+  cloning with explicit secret-state modes in `clone.go`, shared reflection and
+  cycle/limit state in `value_operation.go`, and configuration-value comparison
+  in `document_compare.go`; validation separately audits sensitivity and secrets;
 - strict schema-driven decoding over detached defaults in `decode.go`, including
   mapping/sequence semantics, null and numeric policy, safe codec errors, presence,
   baseline/final trees, and initial default/input origins;
-- public lifecycle coordination in `load.go`, bounded canonical import DFS in
-  `imports.go`, pattern-directed glob expansion in `glob.go`, version-report contexts
-  in `validation.go`, and detached layered metadata/history assembly in
+- public lifecycle coordination in `load.go`, option selection in `options.go`,
+  input assembly in `load_input.go`, typed phases/publication in `load_result.go`,
+  bounded canonical import DFS in `imports.go`, filesystem context/containment in
+  `filesystem.go`, directive parsing/restrictions in `directives.go`,
+  pattern-directed glob expansion in `glob.go`, schema-version checking and report
+  contexts in `validation.go`, and layered metadata/history assembly in
   `load_metadata.go`;
 - recorded application defaulting and normalization in `resolution.go`, including
   explicitness queries, helper verification, structural mutation audit, coalesced
@@ -39,15 +50,25 @@ module and package documentation boundary. Its implemented public primitives are
 - explicit bounded startup environment bootstrap and safe partial reporting in
   `secrets.go`;
 - fixed-point tag/predicate/dependency sensitivity classification in `secret.go`;
-- frozen-snapshot redaction and canonical effective output in `render.go`;
-- bounded immutable input applications, safe historical replay, detached explanation
-  records, and deterministic human rendering in `explain.go`, with the
-  only upstream dumper integration isolated in `internal/yaml/write.go`;
+- canonical effective output in `render.go`, using frozen-snapshot redaction
+  shared with explanation in `snapshot.go`;
+- detached public explanation records and coordination in `explain.go`, immutable
+  input applications/replay and retained-node budgeting in `history.go`, shared
+  safe snapshot projection in `snapshot.go`, and deterministic human output in
+  `explain_render.go`; the only upstream dumper integration remains isolated in
+  `internal/yaml/write.go`;
 - a separate maintained `examples/consumers` package with four sanitized consumer
   shapes, fixtures, domain validators, and runtime-boundary functions; and
-- a fail-fast source-candidate checker in `scripts/release-check.sh`, with local
+- an everyday single-toolchain check in `scripts/check.sh` and a stricter
+  source-candidate checker in `scripts/release-check.sh`, with local
   documentation-link and public import-boundary gates owned by root-package tests.
 
+Dependency direction remains inward: the public lifecycle coordinates private
+source, document, schema, and inspection helpers. Semantic paths stay in the root
+package; `internal/document` owns only representation and cloning and never imports
+the root package. Only `internal/yaml` imports the upstream YAML package. Maintained
+consumer examples use the public package and standard library.
+
 The [configuration contract](../config.md) owns implemented input, schema, decoding,
 loading lifecycle, path imports, composition, profile/CLI overlay, version checking,
 recorded resolution, typed secret references/bootstrap, semantic validation,
@@ -62,7 +83,7 @@ implementation:
 - [Extraction inventory](extraction.md)
 
 The [architecture policy](../policy/architecture.md) owns binding boundaries and
-invariants. The [initial target record](../roadmap/initial.md) links current feature
-owners and preserves deferred scope; it is not an implementation inventory. See the
+invariants. The [deferred scope](../roadmap/deferred.md) records deliberate
+exclusions. See the
 [development guide](../development.md) for contributor orientation and validation
 and the [release procedure](../release.md) for source-candidate gates.

docs/policy/architecture.md

@@ -10,7 +10,7 @@ ConfigKit is an opinionated Go library for consistent YAML configuration loading
 and resolution across consuming applications. This policy governs contributions.
 The [component overview](../internal/overview.md) owns implementation inventory, the
 [configuration contract](../config.md) owns implemented behavior, and the
-[initial target record](../roadmap/initial.md) preserves deferred scope.
+[deferred scope](../roadmap/deferred.md) preserves deferred scope.
 
 ## Success criteria
 
@@ -136,7 +136,7 @@ for safe messages supplied by their hooks.
 Do not introduce automatic directory discovery, network providers, arbitrary
 merge strategies, additional configuration languages, or application runtime
 management without concrete consumer evidence and an explicit design decision.
-The [initial target record](../roadmap/initial.md#explicit-non-goals-and-deferred-scope)
+The [deferred scope](../roadmap/deferred.md#explicit-non-goals-and-deferred-scope)
 owns the deferred-feature inventory. Significant boundary
 changes require an ADR and corresponding policy/contract updates; implementation
 convenience alone is not a reason to broaden the public API.

docs/policy/documentation.md

@@ -28,8 +28,8 @@ semantics, defaults, paths, diagnostics, or compatibility guarantees.
   implementation; execution status belongs in roadmaps.
 - Roadmaps own unimplemented targets, deferred work, and execution status.
 
-The initial target and implementation plan have separate owners. Do not put
-staged steps or progress in `docs/roadmap/initial.md`. `docs/roadmap/implementation.md` owns those details.
+Future implementation plans own their task order, acceptance gates, and progress;
+`docs/roadmap/deferred.md` owns deliberate exclusions, not execution instructions.
 As behavior lands, move its normative definition into the current contract and
 replace the roadmap definition with a link. Retire completed roadmap material
 as part of release preparation; ADRs preserve significant decision history.
@@ -56,7 +56,7 @@ handling, not secret values.
 
 | Topic | Owner | Boundary |
 | --- | --- | --- |
-| Product orientation | `README.md` | Current status, purpose, navigation, and a minimal working example once available |
+| Product orientation | `README.md` | Current status, purpose, navigation, and a minimal working example |
 | Contributor entry point | `docs/development.md` | Reading guide and actual baseline validation commands |
 | Architecture rules | `docs/policy/architecture.md` | Responsibilities, dependency constraints, invariants, and scope boundaries |
 | Documentation rules | `docs/policy/documentation.md` | Ownership and document lifecycle |
@@ -64,14 +64,13 @@ handling, not secret values.
 | Release rules | `docs/policy/release.md` | Compatibility, integrity, gates, immutability, and exceptions |
 | Release procedure | `docs/release.md` | Exact maintainer commands, prerequisites, supported targets, and verification |
 | Exported Go API | Go documentation beside declarations | Symbol contracts, errors, ownership, and lifecycle API behavior |
-| YAML and resolution semantics | `docs/config.md`, as behavior lands | Syntax, composition, precedence, conversion, secret references/bootstrap, and explanation semantics; Go reference docs link here for shared rules |
+| YAML and resolution semantics | `docs/config.md` | Syntax, composition, precedence, conversion, secret references/bootstrap, and explanation semantics; Go reference docs link here for shared rules |
 | Consumer walkthroughs | `docs/consumers/`, when useful | Task-oriented usage and consumer responsibilities, not duplicate API reference |
 | Component inventory | `docs/internal/overview.md` | Implemented components and links to their owners |
 | Component mechanics | Other `docs/internal/` files, when needed | Detailed implementation behavior and change recipes |
 | Architectural decisions | `docs/adr/` | Context, decisions, alternatives, consequences, and supersession history |
-| Initial target record | `docs/roadmap/initial.md` | Implemented-feature owner links and deferred feature scope until roadmap retirement |
-| Implementation plan | `docs/roadmap/implementation.md` | Stages, dependencies, acceptance gates, and progress |
-| Release readiness evidence | `docs/roadmap/release-readiness.md` | Closed preparation gaps and outstanding candidate/publication evidence until roadmap retirement |
+| Deferred scope | `docs/roadmap/deferred.md` | Deliberate exclusions and the conditions for reconsidering them |
+| Future implementation plans | Task-specific files under `docs/roadmap/` | Unfinished work, task order, acceptance gates, and progress; completed plans retire to Git history |
 | Historical release notes | `docs/releases/` | Version-specific historical summaries required by release policy |
 | Complete examples | `examples/` and executable Go examples | Maintained artifacts; prose links instead of duplicating full examples |
 

docs/policy/release.md

@@ -220,23 +220,5 @@ restating or redefining its requirements.
 
 ## Policy Exceptions
 
-### Temporary bootstrap deferral
-
-The release procedure and automated source-candidate checker now exist, but no exact
-release candidate, version-matched release note, native macOS execution evidence, or
-post-publication module retrieval has been validated. Initial implementation may be
-completed without fabricating those later facts. This exception does not authorize
-publication or waive any candidate, platform, remote, or consumer-verification gate.
-
-Compensating controls: the [release procedure](../release.md) keeps every unvalidated
-step as an explicit maintainer gate, and the
-[release-readiness evidence](../roadmap/release-readiness.md) records what is closed
-and outstanding. No release may be published until an exact committed candidate has
-the required release note, passes all applicable automated and native-platform gates,
-is verified against `origin/main`, and completes guarded tag publication and clean
-consumer retrieval. The maintainer preparing the first release owns closure. Remove
-this temporary exception when that evidence is recorded and obsolete roadmap files
-are retired. Any other exception requires a documented repository constraint, rationale,
-compensating controls, scope, and closure condition here; none is currently
-adopted. Do not silently weaken the base integrity, validation, documentation,
-verification, or immutability guarantees.
+None. Candidate selection, publication, and post-publication verification remain
+mandatory steps in the [release procedure](../release.md), not policy exceptions.

docs/releases/v0.1.0.md

@@ -0,0 +1,72 @@
+# ConfigKit v0.1.0
+
+This is the first source release of ConfigKit, an opinionated Go library for strict,
+explainable YAML configuration loading.
+
+## Summary
+
+ConfigKit provides one typed loading lifecycle for file, byte, reader, and
+defaults-only inputs. It supports bounded explicit imports, strict composition,
+selected profiles, explicit CLI overrides, application-owned defaults and recorded
+resolution, semantic validation, provenance, redacted effective output, and safe
+historical explanation.
+
+Typed environment-name secret references and an explicit secrets-directory bootstrap
+keep credential acquisition separate from ordinary loading. Maintained consumer
+examples demonstrate simple and composed application shapes without exposing the
+private YAML parser dependency.
+
+See the [configuration contract](../config.md) and
+[consumer adoption guide](../consumers/README.md) for current behavior and examples.
+
+## Compatibility
+
+This is the initial public release, so there is no earlier ConfigKit release to
+upgrade from. The module requires Go 1.25 or newer and supports Linux and macOS on
+amd64 and arm64. Candidate validation uses patched Go 1.25 and Go 1.26 toolchains;
+native Linux and macOS evidence is required in addition to cross-builds.
+
+Configuration intentionally uses a strict YAML subset. Duplicate keys, aliases,
+anchors, merge keys, unsupported tags and scalar forms, trailing documents, and
+unknown typed fields are rejected. Composition rejects overlapping non-mapping
+definitions; replacement occurs only through selected profiles, explicit CLI
+overrides, or recorded application resolution.
+
+The private parser dependency remains explicitly pinned to
+`go.yaml.in/yaml/v4 v4.0.0-rc.6`, which was still the newest available v4 release when
+the candidate was prepared. No upstream YAML declarations are part of ConfigKit's
+public API.
+
+## Upgrade
+
+No action is required for an earlier ConfigKit version because this is the first
+release. New consumers can add the module with:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.1.0
+```
+
+The authoritative host may require its normal private-module credentials. Consumers
+adapting existing application configuration should review the intentional migration
+differences in the [consumer adoption guide](../consumers/README.md), particularly
+strict YAML, string schema versions, explicit empty/null behavior, canonical module
+objects, `int64` dynamic integers, explicit CLI records, and typed secret references.
+
+## Changes
+
+- Added opaque file, byte, reader, and defaults-only sources with fixed resource
+  limits and safe structured diagnostics.
+- Added an owned strict YAML model, typed schema binding, detached defaults and
+  results, canonical projection, and private parser isolation.
+- Added explicit path/glob imports, deterministic strict composition, canonical
+  source identity and containment, and selected profile overlays.
+- Added layered presence, origins, chronological history, version checks, recorded
+  defaulting and normalization, and read-only semantic validation.
+- Added secret classification, deterministic redacted effective YAML, typed
+  environment references, and bounded explicit secrets-directory bootstrap reports.
+- Added parser-neutral explicit CLI overrides and safe structured/human historical
+  value explanations, including removed and superseded values.
+- Added maintained Narratio-, Notarius-, WeatherReporter-, and Seriatim-shaped
+  examples and migration coverage using only ConfigKit and the standard library.
+- Added race and bounded fuzz coverage plus a two-toolchain, offline, cross-platform
+  source-release checker and maintainer runbook.

docs/roadmap/deferred.md

@@ -0,0 +1,28 @@
+# Deferred Scope
+
+This document owns intentionally excluded features, not a committed delivery plan.
+The [architecture policy](../policy/architecture.md) governs changes to these
+boundaries. Implemented behavior belongs in the [configuration contract](../config.md)
+and consumer adoption in the [consumer guide](../consumers/README.md).
+
+## Explicit non-goals and deferred scope
+
+General environment-variable configuration overlays are not supported. Typed secret
+references and explicit directory bootstrap are the environment convention. Literal
+credential configuration and implicit secret-directory discovery are unsupported.
+
+The initial release deliberately excludes:
+
+- automatic `conf.d` discovery;
+- remote imports, arbitrary providers, and additional configuration formats;
+- custom merge strategies, sequence merging, reset operators, and profile inheritance;
+- parser-specific or custom structural-decoding extension APIs;
+- generic dynamic-subtree conversion and module-registry APIs;
+- automatic schema migrations;
+- hot reload, runtime resource replacement, and remote resource validation;
+- a bundled CLI framework or application commands; and
+- configuration diffs and fingerprints.
+
+Applications may build their own validate, effective-value, source, bootstrap, and
+explanation commands around the library. Broadening these boundaries requires
+concrete consumer evidence, compatibility review, and an explicit design change.

docs/roadmap/initial.md

@@ -1,83 +0,0 @@
-# ConfigKit Initial Target Record
-
-## Status and ownership
-
-The initial feature target is implemented. This document now records the intended
-outcome, source foundations, and deliberately deferred scope without duplicating the
-current configuration contract or Go API reference. Ordered implementation history
-and acceptance evidence remain in the [implementation plan](implementation.md) until
-the maintainer retires completed roadmaps while preparing a release candidate.
-
-The [architecture policy](../policy/architecture.md) owns responsibilities,
-dependency direction, confidentiality, and the two success criteria. The
-[configuration contract](../config.md) and Go declarations own implemented behavior.
-The [consumer adoption guide](../consumers/README.md) owns consumer fit and migration
-guidance. Accepted rationale remains in the [ADRs](../development.md#task-specific-reading-guide).
-
-## Initial outcome
-
-ConfigKit is one opinionated Go library for strict YAML configuration loading. It
-removes source handling, parsing, explicit import/profile traversal, composition,
-precedence, presence tracking, provenance, secret lookup/bootstrap, diagnostics, and
-safe inspection plumbing from applications. Applications retain their types,
-defaults, schema-version policy, recorded normalization, semantic validation, CLI
-parsing, remote acquisition, domain algorithms, resource checks, and runtime setup.
-
-The maintained Narratio-, Notarius-, WeatherReporter-, and Seriatim-shaped examples
-demonstrate both architecture success criteria: simple consumers avoid optional
-composition machinery, complex consumers use the same conventions, and domain logic
-remains recognizable application code. These examples are migration evidence, not a
-claim that any sibling application has migrated.
-
-## Implementation foundations
-
-The implementation was generalized from maintainer-authorized application code and
-tests at fixed clean revisions. The [extraction inventory](../internal/extraction.md)
-records exact revisions, symbols, adapted cases, intentional semantic differences,
-and the boundary that keeps sibling checkouts out of builds and tests. Links from
-that inventory or historical implementation evidence to sibling source are optional
-in isolated clones; immutable revision references remain authoritative evidence.
-
-The module uses `go.yaml.in/yaml/v4` only behind `internal/yaml`. ConfigKit owns the
-document model, field binding, scalar grammar, errors, limits, and output behavior.
-No upstream type, option, plugin, error chain, hidden parser value, or generic
-constraint crosses the public API. The package-level import-boundary test enforces
-this isolation for production, tests, and maintained examples.
-
-## Current feature owners
-
-| Initial feature area | Current owner |
-| --- | --- |
-| Sources, lifecycle, limits, YAML/scalars, decoding, and ownership | [Configuration contract](../config.md) and Go reference comments |
-| Paths, presence, origins, sources, and definition history | [Layered metadata](../config.md#layered-metadata), [`path.go`](../../path.go), and [`metadata.go`](../../metadata.go) |
-| Strict composition, imports, globs, source identity, and profiles | [Strict composition](../config.md#strict-document-composition), [explicit imports](../config.md#explicit-imports), and [selected profiles](../config.md#selected-profiles) |
-| Static defaults, null, types, projection, and custom text scalars | [Defaults and typed decoding](../config.md#defaults-and-typed-decoding), [schema binding](../config.md#application-schema-binding), and [typed projection](../config.md#typed-projection-and-ownership) |
-| Schema versions, recorded resolution, and semantic validation | [Version contract](../config.md#application-schema-versions), [resolution](../config.md#recorded-application-resolution), and [validation](../config.md#semantic-validation) |
-| Secret classification, typed references, and directory bootstrap | [Redaction](../config.md#secret-classification-and-effective-rendering), [references](../config.md#typed-secret-references), and [bootstrap](../config.md#explicit-secrets-directory-bootstrap) |
-| Explicit CLI overrides and complete precedence | [CLI override contract](../config.md#explicit-cli-overrides) |
-| Effective rendering and safe historical explanation | [Effective rendering](../config.md#secret-classification-and-effective-rendering) and [historical explanation](../config.md#historical-value-explanation) |
-| Canonical module options and downstream adoption | [Module options](../config.md#canonical-module-options) and [consumer guide](../consumers/README.md) |
-| Diagnostics and structured errors | [`records.go`](../../records.go), [`diagnostic.go`](../../diagnostic.go), and relevant configuration-contract sections |
-| Internal components and dependency placement | [Component overview](../internal/overview.md) and [architecture policy](../policy/architecture.md) |
-
-## Explicit non-goals and deferred scope
-
-General environment-variable configuration overlays are not supported. Typed secret
-references and explicit directory bootstrap are the environment convention. Literal
-credential configuration and implicit secret-directory discovery are unsupported.
-
-The initial release deliberately excludes:
-
-- automatic `conf.d` discovery;
-- remote imports, arbitrary providers, and additional configuration formats;
-- custom merge strategies, sequence merging, reset operators, and profile inheritance;
-- parser-specific or custom structural-decoding extension APIs;
-- generic dynamic-subtree conversion and module-registry APIs;
-- automatic schema migrations;
-- hot reload, runtime resource replacement, and remote resource validation;
-- a bundled CLI framework or application commands; and
-- configuration diffs and fingerprints.
-
-Applications may build their own validate, effective-value, source, bootstrap, and
-explanation commands around the library. Broadening these boundaries requires
-concrete consumer evidence, compatibility review, and an explicit design change.

docs/roadmap/release-readiness.md

@@ -1,37 +0,0 @@
-# Release Readiness
-
-## Status and ownership
-
-ConfigKit's implementation is prepared for release-candidate validation, but no
-release candidate has been selected or publication authorized. The maintainer
-preparing the first release owns the remaining gates under the
-[temporary bootstrap exception](../policy/release.md#temporary-bootstrap-deferral).
-This evidence record remains until candidate preparation retires completed roadmap
-material in favor of the operational [release procedure](../release.md) and normal
-release notes.
-
-## Preparation evidence
-
-| Preparation item | Status and evidence |
-| --- | --- |
-| Module and support matrix | Closed: the runbook records module `gitea.maximumdirect.net/eric/ConfigKit`, minimum Go 1.25 with a patched 1.25 plus newer supported toolchain, and Linux/macOS on amd64/arm64. |
-| Maintainer release procedure | Closed: `docs/release.md` owns access prerequisites, candidate recording, complete validation, exact remote/commit/tag guards, source-only publication, consumer retrieval, and correction. |
-| Automated source checker | Closed for current-source preparation: `scripts/release-check.sh` passed on 2026-09-06 with Go 1.25.5 and Go 1.26.7 on linux/amd64. It performs disposable-copy module hygiene, cached/offline tests, race, vet, native and four-target cross-builds, formatting/whitespace, examples, import isolation, and local-link gates. The exact candidate must rerun it. |
-| Consumer verification procedure | Closed as procedure: the runbook retrieves an exact published version into a clean temporary module with no local replacement and tests/builds it. Actual retrieval remains a post-publication gate. |
-| Secret/precedence/explanation evidence | Closed locally: current contracts and deterministic tests cover bootstrap skip/partial failure, credential isolation, defaults/base/profile/CLI precedence, historical redaction, and maintained consumer startup examples. |
-| Parser dependency reassessment | Closed for preparation: on 2026-09-06, `go list -m -versions go.yaml.in/yaml/v4` and `go list -m -json go.yaml.in/yaml/v4@latest` both showed `v4.0.0-rc.6` as the newest available release. The explicit pin is retained; a candidate compatibility review must reassess and record it again. |
-
-## Outstanding release gates
-
-| Gate | Owner and closure evidence |
-| --- | --- |
-| Exact candidate and release note | Maintainer selects an unused stable version, writes `docs/releases/<version>.md`, commits all release changes, runs the checker against that exact clean commit, pushes it to `origin/main`, and records the commit. |
-| Native platform execution | Maintainer records applicable checker, race, symlink, and permission-fixture results on native Linux and macOS. Current local evidence is Linux/amd64 only; cross-builds do not close macOS execution. |
-| Compatibility, migration, and content review | Maintainer records public API/configuration/diagnostic review, downstream migration impact, release-note approval, and inspection for credentials, private data, generated output, unintended files, and unrelated changes. |
-| Roadmap retirement | Maintainer removes obsolete completed files under `docs/roadmap/`, repairs inbound links, and reruns the checker as part of the candidate. This record and the implementation plan intentionally remain while no candidate exists. |
-| Remote publication guards | Maintainer fetches authoritative `origin/main` and tags immediately before publication and proves branch, clean worktree/index, candidate commit, remote commit, release note, approvals, and unused version all agree. |
-| Tag and retrieval verification | After authorization, maintainer pushes only the exact immutable source tag, verifies its peeled remote commit, and retrieves/tests/builds the exact version in a clean consumer module without `replace`. |
-
-No tag, push, downstream migration, release note, or release publication was
-performed during implementation. A green local checker does not close the exact
-candidate, native macOS, remote, or post-publication gates.

docs/roadmap/remediation.md

@@ -1,355 +0,0 @@
-# Pre-release Maintainability Remediation
-
-## Status and scope
-
-Status: planned; no stages have been implemented under this roadmap.
-Audit baseline: `9b147bfd96aec25e0125dcae66e136e56dc7a670`.
-
-This roadmap owns the agreed maintainability cleanup before v0.1.0. It replaces
-the completed implementation-defect remediation record, whose findings, fixes,
-and validation evidence remain available in Git history. It does not reopen
-those defects or replace the original [implementation plan](implementation.md).
-
-The audit found worthwhile consolidation and ownership improvements, rather than
-a need to redesign ConfigKit. The offline default suite and vet passed at the
-audit baseline. That evidence is not validation of future changes or a release
-candidate.
-
-Read the [development guide](../development.md),
-[architecture policy](../policy/architecture.md),
-[testing policy](../policy/testing.md), and
-[documentation policy](../policy/documentation.md) before implementation.
-The [configuration contract](../config.md) owns current semantics; the
-[component overview](../internal/overview.md) owns implementation inventory.
-Release preparation remains governed by the [release policy](../policy/release.md)
-and [maintainer procedure](../release.md).
-
-## Execution rules and invariants
-
-Implement the numbered stages in order. Each stage is one reviewable unit of
-work: inspect its current owners and tests, make the change, validate it, update
-its status and evidence here, and commit the nonempty unit with a short plain
-English message. Do not create empty commits. Record any discovered behavioral
-defect separately with a reproduction rather than silently changing semantics
-under a refactoring stage.
-
-Keep the root public package and the existing `internal/document` and
-`internal/yaml` packages. Do not introduce dependencies, public API changes,
-provider interfaces, configurable merge policies, or a generic visitor framework.
-Private file splits do not require new packages or ADRs. Parser-specific types
-must remain behind the existing YAML adapter boundary.
-
-Preserve the implemented contracts, particularly:
-
-- Strict composition remains distinct from intentional profile/CLI overlay.
-- Input precedence, final-only typed decoding, retained defaults, canonical
-  decoding explanation events, and recorded domain resolution remain unchanged.
-- Source identity, containment, optional-import rules, limits, diagnostic codes,
-  source coordinates, ordering, and early callback termination remain intact.
-- Semantic paths retain explicit key/index distinctions and historical shapes.
-- Returned values and inspection snapshots remain detached; secret values remain
-  absent from history, rendering, and library-generated diagnostics.
-- Resolution runs before secret lookup and validation; ordinary loading never
-  bootstraps environment variables implicitly.
-
-Use focused existing behavioral tests during each stage and the baseline checks
-from the development guide before committing production changes. Add tests only
-for meaningful gaps exposed by extraction, not to enforce file locations or
-private call choreography. Update current owning documentation alongside each
-move. Planned filenames below are private implementation destinations, not new
-consumer contracts.
-
-## Stage 1 — Remove unused overlay value snapshots
-
-Status: pending.
-
-Evidence: `overlayRecord` in [overlay.go](../../overlay.go) retains `before` and
-`after` trees; profile and CLI processing construct them and
-`cloneOverlayRecords` clones them. Production consumers use the record's change
-and displaced origins, while explanation uses `historyApplication` instead.
-
-Work:
-
-1. Reconfirm all field reads before removal. Remove only the unused overlay
-   snapshot fields and their construction/cloning in `overlay.go` and
-   [override.go](../../override.go).
-2. Preserve `change`, `displaced`, input applications, and their ownership rules.
-   Do not remove resolution snapshots or retained decoded trees: those have
-   separate consumers and budget semantics.
-3. Remove locals and imports made unnecessary by the deletion. Do not replace
-   the removed state with a new cache or history representation.
-
-Acceptance: profile/CLI provenance, explanation replay, composition independence,
-and redaction tests pass unchanged in observable behavior. Source inspection
-confirms no unused overlay snapshot construction remains. An allocation benchmark
-is not required to justify removing provably unread clones.
-
-## Stage 2 — Centralize parser issue translation
-
-Status: pending.
-
-Evidence: [parse.go](../../parse.go) translates adapter issues inline, while
-`importParseDiagnostics` in [imports.go](../../imports.go) repeats the translation
-for imports and profiles.
-
-Work:
-
-1. Define one private `parserDiagnostics` helper in `parse.go` that maps adapter
-   issues to detached public diagnostics, including related locations.
-2. Route selected-source, import, and profile parsing through it. Remove the
-   import-specific translator and keep upstream parser errors private.
-3. Return canonically ordered diagnostics from the shared translation boundary.
-   Preserve existing codes, messages, primary/related coordinates, and source IDs.
-   Keep per-source parsing budgets and graph accounting at their current owners.
-
-Acceptance: malformed selected/imported/profile input retains safe, correctly
-attributed diagnostics. Use existing parser and import diagnostic tests; add a
-small cross-entry regression only if a source path lacks equivalent coverage.
-
-## Stage 3 — Share bounded regular-file read mechanics
-
-Status: pending.
-
-Evidence: `readSource`, `importTraversal.readImport`, and `readProfileFile` repeat
-preflight stat, open, post-open stat, regular-file checks, size checks, and bounded
-reads in [source.go](../../source.go), [imports.go](../../imports.go), and
-[profile.go](../../profile.go).
-
-Work:
-
-1. Introduce private helpers in `source_file.go` for regular-file opening and
-   bounded reading. Use narrow function parameters for stat/open operations so
-   callers can supply `os.Stat`/`os.Open` or root-bound methods. Do not introduce
-   an exported filesystem interface or substitute unrestricted opening for
-   `os.Root` access.
-2. Keep preflight before open and post-open verification. Close every opened
-   file on all paths. Preserve the existing treatment of read-only file close
-   errors; root-directory close diagnostics are a separate responsibility.
-3. Return private classified failures with enough distinction for callers to
-   map errors safely. Optional imports may suppress only the currently allowed
-   missing-target failures at stat/open, not later read failures. Do not expose
-   filesystem errors downstream through wrapping.
-4. Keep source metadata, canonicalization, containment, per-source/aggregate
-   budgets, byte accounting, and caller-specific limit diagnostics outside the
-   shared mechanics. Pass the computed byte limit into the reader and retain
-   both the size precheck and limit-plus-one read enforcement.
-5. Reuse bounded read mechanics for reader/byte sources only where it simplifies
-   existing code without changing single-use or ownership behavior. Keep secrets
-   bootstrap independent: its symlink, environment, and reporting policies differ.
-
-Acceptance: source, import, profile, FIFO, containment, symlink, optional-missing,
-exact-budget, and reader-ownership tests pass. Retain the deadline-isolated FIFO
-regression. Cover private failure classification only where public tests cannot
-reliably induce an important filesystem failure. Run race tests for this unit.
-
-## Stage 4 — Establish shared document traversal ownership
-
-Status: pending.
-
-Evidence: `indexDocument`, `walkDocumentPaths`, and `projectedSensitivity` repeat
-semantic tree traversal in [load_metadata.go](../../load_metadata.go),
-[metadata.go](../../metadata.go), and [secret.go](../../secret.go). General document
-lookup currently lives in [load.go](../../load.go).
-
-Work:
-
-1. Create root-private `document_walk.go` with a nil-safe preorder walker taking
-   a starting `Path` and a callback receiving both path and node. Visit mappings
-   in stored order and sequences in index order; construct explicit Key/Index
-   segments. It visits value nodes, not synthetic mapping-key nodes.
-2. Move `indexDocument` and `documentAtPath` to this owner. Implement indexing,
-   metadata shape collection, and projected sensitivity collection using the
-   walker where their traversal semantics match.
-3. Document callback borrowing: callers must clone paths or nodes when retaining
-   mutable state. Preserve existing defensive copies and avoid sharing mutable
-   metadata across results.
-4. Keep path-bearing helpers in the root package so `internal/document` does not
-   depend on the public package. Pure node representation and cloning stay in
-   `internal/document`.
-5. Leave specialized traversals explicit where they need inherited origins,
-   pruning, node identity deduplication, or different counting. In particular,
-   input limits count mapping keys and retained-history limits count shared nodes
-   once; do not implement either using the new walker without those semantics.
-
-Acceptance: numeric map keys versus sequence indices, escaped paths, unknown
-paths, historical shape changes, deleted descendants, dynamic secret tags, and
-metadata detachment remain protected by existing tests. No public path behavior
-or predicate coverage changes. Do not add tests that assert walker call counts.
-
-## Stage 5 — Separate typed projection, cloning, and comparison
-
-Status: pending.
-
-Evidence: [projection.go](../../projection.go) combines roughly 622 lines of
-projection, detached cloning, dynamic schema handling, cycle/limit enforcement,
-and structural comparison. Value equality deliberately ignores sensitivity,
-which validation must check separately.
-
-Work:
-
-1. Keep canonical typed projection in `projection.go`; move cloning into
-   `clone.go`, shared reflection operation state and cycle helpers into
-   `value_operation.go`, and value-tree comparison into `document_compare.go`.
-   Preserve the descriptor-driven approach and per-operation schema cache.
-2. Rename the private equality/comparison entry points to make configuration-value
-   semantics explicit. Document that location and sensitivity metadata are
-   excluded, mapping order is immaterial, and sequences are compared atomically
-   for change reporting. Update all callers without changing their semantics.
-3. Give validator mutation comparison a named private owner in `validation.go`.
-   It must combine projected value changes and sensitivity changes, while
-   retaining private resolved-secret-state auditing as an additional check.
-   Do not make resolver value comparison start treating sensitivity as a value.
-4. Preserve the distinction between cloning unresolved public secret references
-   and publication cloning of already validated private state. Name/document
-   the clone mode explicitly rather than leaving an unexplained boolean at
-   sensitive call sites.
-5. Replace custom `cmpString` calls with the standard library comparator and
-   remove that helper. Do not perform unrelated test-style rewrites.
-
-Acceptance: projection/cloning tests cover nil versus empty, custom text codecs,
-inline fields, dynamic types, cycles, and limits. Validator mutation regressions
-must still reject equal-text sensitivity changes and secret-state changes.
-Callback ownership and secret lookup tests must prove publication does not share
-borrowed values or reread the environment. Run race tests for this unit.
-
-## Stage 6 — Clarify source assembly and override ownership
-
-Status: pending.
-
-Evidence: [imports.go](../../imports.go) mixes filesystem context, directives,
-graph traversal, and diagnostics; [override.go](../../override.go) combines value
-construction/validation and application. Shared composition cloning is located
-inside the override feature, while profile overlay repeats it.
-
-Work:
-
-1. Keep import traversal and route diagnostics in `imports.go`. Move filesystem
-   context validation/canonicalization/containment to `filesystem.go`, and
-   directive structures/parsing/fragment restrictions to `directives.go`.
-   Give source-independent node counting an appropriate shared document owner,
-   with its mapping-key accounting documented.
-2. Keep override validation and preparation in `override.go`, move parser-neutral
-   value building to `override_value.go`, and application/displacement mechanics
-   to `override_apply.go`.
-3. Move `cloneComposedDocument` next to `composedDocument` in `compose.go`; use it
-   for both profile overlay and overrides. Ensure every retained field is copied
-   according to its existing ownership contract.
-4. Keep strict composition, overlay, and history replay separate. Share small
-   mechanics when identical; do not introduce merge strategy flags or one general
-   merge engine. Preserve the existing profile-versus-CLI recording behavior.
-5. Simplify profile root cleanup using deferred failure-path cleanup plus an
-   explicit checked success-path close. Preserve primary failure diagnostics and
-   the existing successful-read root-close error diagnostic; avoid double-close
-   effects. Import traversal cleanup may remain explicit where already clear.
-
-Acceptance: imports/globs, directive restrictions, source ordering, profiles,
-overrides, version restrictions, limits, and composition independence tests pass.
-No new cross-package dependencies appear. Root handles close on every path and
-profile/CLI provenance remains identical.
-
-## Stage 7 — Extract explicit loader lifecycle phases
-
-Status: pending.
-
-Evidence: `loadWithSecretLookup` in [load.go](../../load.go) coordinates roughly
-200 lines of source assembly, decoding, callbacks, history, secrets, and result
-publication, including repeated creation of a composition handoff.
-
-Work:
-
-1. Keep the exported entry point and a readable linear coordinator in `load.go`.
-   Move option selection to `options.go`, input assembly to `load_input.go`, and
-   typed lifecycle/result publication to `load_result.go`. Move version checking
-   beside the validation machinery rather than keeping it among document helpers.
-2. Use small private handoff structs for assembled input and necessary phase
-   outputs, not a mutable all-purpose loader object or a long list of output
-   parameters. Reuse one composition initialization helper for profile and CLI
-   processing, including NoSource override handling and source byte/node totals.
-3. Preserve the exact existing order of option validation, parsing/import checks,
-   schema validation, version checking, profile/CLI application, defaults factory,
-   typed decoding, resolution, retained-history limit enforcement, secret lookup,
-   validation, metadata/classification, and result publication.
-4. Keep diagnostic/source accumulation explicit. Warnings survive successful
-   phases; errors stop dependent work and never return a usable partial Result.
-5. Preserve both ownership barriers: detach resolver-borrowed values before secret
-   resolution and validation, then detach equal-valued validator replacements
-   before publication while preserving validated secret state. Do not remove
-   either clone as apparently redundant work.
-6. Group Result's frozen inspection state only if it clarifies this handoff; do
-   not add an additional history copy or change caller ownership of Config.
-
-Acceptance: lifecycle ordering/early-stop tests, defaults-only loading, all input
-combinations, callback ownership, secrets, warning retention, and complete
-provenance agreement pass. Keep orchestration visible enough to verify phase
-ordering by reading the coordinator. Run the complete race suite.
-
-## Stage 8 — Separate explanation replay, snapshots, and rendering
-
-Status: pending.
-
-Evidence: [explain.go](../../explain.go) combines approximately 576 lines of public
-records, replay algorithms, snapshot redaction, retained-history accounting, and
-human-readable output.
-
-Work:
-
-1. Keep public explanation records and Explain coordination in `explain.go`.
-   Move application/snapshot replay and history budgeting to `history.go`, safe
-   snapshot projection to `snapshot.go`, and WriteExplanation with its formatting
-   helpers to `explain_render.go`.
-2. Make effective rendering and explanation snapshots use the existing shared
-   redaction implementation; do not create separate sensitivity rules.
-3. Retain the canonical decoding reconciliation event between input replay and
-   domain resolution, overlapping resolution intent coalescing, added/deleted
-   paths, effective source attribution, and historical secret classification.
-4. Document the differences between metadata origin records and value replay:
-   they serve different query contracts but must agree on effective results.
-   Do not replace them with a new event-store abstraction in this cleanup.
-5. Preserve writer failure behavior and ownership of retained trees. Do not cache
-   explanations or optimize full-tree replay without measured need.
-
-Acceptance: explanation, effective rendering, history budget, provenance, secret
-redaction, and writer-failure tests pass without output changes. Container and
-leaf histories still reconcile with the frozen effective typed configuration.
-
-## Stage 9 — Complete ownership documentation and integration validation
-
-Status: pending.
-
-Work:
-
-1. Review the final code for obsolete helpers, duplicate traversal/translation,
-   unread retained state, stale comments, and imports left by earlier stages.
-   Confirm file splits reflect discrete responsibilities rather than line quotas.
-2. Update the component overview to describe the actual owners and fix its stale
-   claim that metadata queries are empty. Keep detailed consumer semantics in
-   their existing contract; repair navigation and moved-file links throughout
-   documentation, including this roadmap's evidence links if necessary.
-3. State the retained dependency direction clearly: public lifecycle coordination
-   uses private source/document/schema/inspection helpers; the owned document
-   representation has no dependency on the root package; only the private YAML
-   adapter imports the upstream YAML package.
-4. Run the full baseline and race suites, local documentation and dependency
-   boundary checks, and the complete source-candidate checker described in the
-   release procedure with available qualifying toolchains. Record exact versions,
-   host platform, results, and any unavailable platform evidence. Cross-builds
-   are not native execution evidence.
-5. Review the accumulated diff for public API/configuration/diagnostic changes.
-   Expected outcome: no consumer migration or dependency change. If any contract
-   change is discovered, resolve it explicitly before closing this roadmap.
-6. Record completion evidence and commit this final nonempty unit. Release
-   preparation must subsequently retire completed roadmap material and validate
-   the exact committed candidate under release policy. Completing this roadmap
-   does not create a tag, push refs, or authorize publication.
-
-Acceptance: all stages are complete with recorded validation, existing behavioral
-regressions remain protected, documentation matches the new ownership layout,
-and the worktree is clean after commits. Required release gates remain visible
-in the release procedure rather than being declared satisfied by this refactor.
-
-## Open Questions
-
-None required to begin implementation. The package boundaries, compatibility
-constraints, ordered units, and acceptance criteria above are decided. Routine
-private naming adjustments are acceptable when they preserve those decisions;
-new behavioral discoveries require explicit evidence and disposition.

document_compare.go

@@ -0,0 +1,110 @@
+package configkit
+
+import (
+	"cmp"
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+	"slices"
+)
+
+type documentDeltaKind uint8
+
+const (
+	documentAdded documentDeltaKind = iota + 1
+	documentRemoved
+	documentReplaced
+)
+
+type documentDelta struct {
+	path Path
+	kind documentDeltaKind
+}
+
+// compareConfigurationValues ignores locations and sensitivity metadata. Mapping
+// order is immaterial; sequences are atomic for change reporting.
+func compareConfigurationValues(before, after *document.Node) []documentDelta {
+	var deltas []documentDelta
+	compareConfigurationValue(before, after, Path{}, &deltas)
+	slices.SortFunc(deltas, func(left, right documentDelta) int {
+		if order := cmp.Compare(left.path.String(), right.path.String()); order != 0 {
+			return order
+		}
+		return int(left.kind) - int(right.kind)
+	})
+	return deltas
+}
+
+func compareConfigurationValue(before, after *document.Node, path Path, deltas *[]documentDelta) {
+	if before == nil && after == nil {
+		return
+	}
+	if before == nil {
+		*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentAdded})
+		return
+	}
+	if after == nil {
+		*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentRemoved})
+		return
+	}
+	if before.Kind != after.Kind {
+		*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentReplaced})
+		return
+	}
+	switch before.Kind {
+	case document.Mapping:
+		beforeEntries := make(map[string]*document.Node, len(before.Mapping))
+		afterEntries := make(map[string]*document.Node, len(after.Mapping))
+		keys := make(map[string]bool, len(before.Mapping)+len(after.Mapping))
+		for _, entry := range before.Mapping {
+			beforeEntries[entry.Key] = entry.Value
+			keys[entry.Key] = true
+		}
+		for _, entry := range after.Mapping {
+			afterEntries[entry.Key] = entry.Value
+			keys[entry.Key] = true
+		}
+		ordered := make([]string, 0, len(keys))
+		for key := range keys {
+			ordered = append(ordered, key)
+		}
+		slices.Sort(ordered)
+		for _, key := range ordered {
+			compareConfigurationValue(beforeEntries[key], afterEntries[key], path.Key(key), deltas)
+		}
+	case document.Sequence:
+		if !configurationValuesEqual(before, after) {
+			*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentReplaced})
+		}
+	default:
+		if before.Text != after.Text {
+			*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentReplaced})
+		}
+	}
+}
+
+// configurationValuesEqual compares only configuration values, not provenance or
+// sensitivity. Callers auditing validation must check sensitivity separately.
+func configurationValuesEqual(left, right *document.Node) bool {
+	if left == nil || right == nil {
+		return left == right
+	}
+	if left.Kind != right.Kind || left.Text != right.Text || len(left.Mapping) != len(right.Mapping) || len(left.Sequence) != len(right.Sequence) {
+		return false
+	}
+	if left.Kind == document.Mapping {
+		leftMap := make(map[string]*document.Node, len(left.Mapping))
+		for _, entry := range left.Mapping {
+			leftMap[entry.Key] = entry.Value
+		}
+		for _, entry := range right.Mapping {
+			if !configurationValuesEqual(leftMap[entry.Key], entry.Value) {
+				return false
+			}
+		}
+	}
+	for i := range left.Sequence {
+		if !configurationValuesEqual(left.Sequence[i], right.Sequence[i]) {
+			return false
+		}
+	}
+	return true
+}

document_walk.go

@@ -0,0 +1,86 @@
+package configkit
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+// walkDocument visits value nodes in preorder, preserving stored mapping order
+// and sequence index order. Mapping keys are not separate nodes in this walk.
+// The callback borrows paths and nodes; clone any mutable state it retains.
+// Specialized origin, pruning, and budget traversals retain their own semantics.
+func walkDocument(node *document.Node, path Path, visit func(Path, *document.Node)) {
+	if node == nil {
+		return
+	}
+	visit(path, node)
+	switch node.Kind {
+	case document.Mapping:
+		for _, entry := range node.Mapping {
+			walkDocument(entry.Value, path.Key(entry.Key), visit)
+		}
+	case document.Sequence:
+		for index, child := range node.Sequence {
+			walkDocument(child, path.Index(index), visit)
+		}
+	}
+}
+
+// indexDocument borrows nodes from its caller-owned tree.
+func indexDocument(node *document.Node, path Path, index map[string]*document.Node) {
+	walkDocument(node, path, func(path Path, node *document.Node) {
+		index[path.String()] = node
+	})
+}
+
+func documentAtPath(root *document.Node, path Path) (*document.Node, bool) {
+	if root == nil || !path.valid() {
+		return nil, false
+	}
+	current := root
+	for _, segment := range path.segments {
+		switch current.Kind {
+		case document.Mapping:
+			if segment.kind == pathSegmentIndex {
+				return nil, false
+			}
+			found := false
+			for _, entry := range current.Mapping {
+				if entry.Key == segment.key {
+					current = entry.Value
+					found = true
+					break
+				}
+			}
+			if !found {
+				return nil, false
+			}
+		case document.Sequence:
+			index, ok := schemaIndex(segment)
+			if !ok || index >= len(current.Sequence) {
+				return nil, false
+			}
+			current = current.Sequence[index]
+		default:
+			return nil, false
+		}
+	}
+	return current, true
+}
+
+// countInputNodes includes mapping-key nodes, unlike walkDocument's value-only
+// traversal. Aggregate source budgets charge every input occurrence.
+func countInputNodes(node *document.Node) int {
+	if node == nil {
+		return 0
+	}
+	count := 1
+	if node.Kind == document.Mapping {
+		count += len(node.Mapping)
+		for _, entry := range node.Mapping {
+			count += countInputNodes(entry.Value)
+		}
+	} else if node.Kind == document.Sequence {
+		for _, child := range node.Sequence {
+			count += countInputNodes(child)
+		}
+	}
+	return count
+}

explain.go

@@ -1,23 +1,6 @@
 package configkit
 
-import (
-	"bytes"
-	"errors"
-	"io"
-	"slices"
-	"strconv"
-	"strings"
-
-	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
-	yamladapter "gitea.maximumdirect.net/eric/ConfigKit/internal/yaml"
-)
-
-const historyNodeLimit = 4_000_000
-
-var (
-	errExplanationUnavailable = errors.New("configkit: configuration explanation is unavailable")
-	errExplanationUnknownPath = errors.New("configkit: configuration explanation path is unknown")
-)
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
 
 // ValueSnapshot is a detached, deterministic YAML representation of one value.
 // Present distinguishes absence or deletion from an explicit null value.
@@ -51,38 +34,6 @@ type Explanation struct {
 	SecretReference *SecretReferenceInfo
 }
 
-type historyApplication struct {
-	layer  Layer
-	path   Path
-	value  *document.Node
-	origin Origin
-}
-
-func cloneHistoryApplications(values []historyApplication) []historyApplication {
-	if values == nil {
-		return nil
-	}
-	cloned := make([]historyApplication, len(values))
-	for index, value := range values {
-		cloned[index] = historyApplication{
-			layer: value.layer, path: value.path.clone(), value: value.value,
-			origin: cloneOrigin(value.origin),
-		}
-	}
-	return cloned
-}
-
-func cloneSecretReferences(values map[string]string) map[string]string {
-	if values == nil {
-		return nil
-	}
-	cloned := make(map[string]string, len(values))
-	for path, name := range values {
-		cloned[path] = name
-	}
-	return cloned
-}
-
 // Explain returns safe effective and chronological values for a known final or
 // historical path. Unknown and malformed paths return false.
 func (r *Result[T]) Explain(path Path) (Explanation, bool) {
@@ -126,7 +77,7 @@ func (r *Result[T]) Explain(path Path) (Explanation, bool) {
 	// explicitly, including canonical scalar conversions, before domain changes.
 	replayed, _ := documentAtPath(working, path)
 	decoded, _ := documentAtPath(r.input, path)
-	if !documentNodesEqual(replayed, decoded) {
+	if !configurationValuesEqual(replayed, decoded) {
 		origin := cloneOrigin(r.inputOrigins[path.String()])
 		origin.Operation = ChangeDecoding
 		explanation.History = append(explanation.History, ValueChange{
@@ -169,408 +120,3 @@ func (r *Result[T]) Explain(path Path) (Explanation, bool) {
 	}
 	return explanation, true
 }
-
-func applicationOperationPath(application historyApplication, query Path) (Path, bool) {
-	if !application.path.valid() || application.value == nil {
-		return Path{}, false
-	}
-	if application.path.String() != "" {
-		if pathsIntersect(application.path, query) {
-			return application.path.clone(), true
-		}
-		return Path{}, false
-	}
-	if len(query.segments) == 0 {
-		return Path{}, true
-	}
-	for length := 1; length <= len(query.segments); length++ {
-		prefix := Path{segments: clonePathSegments(query.segments[:length], 0)}
-		node, present := documentAtPath(application.value, prefix)
-		if !present {
-			return Path{}, false
-		}
-		if length == len(query.segments) || node.Kind != document.Mapping {
-			return prefix, true
-		}
-	}
-	return Path{}, false
-}
-
-func historyApplicationOrigin(application historyApplication, operationPath Path) Origin {
-	if application.origin.Layer != "" {
-		return cloneOrigin(application.origin)
-	}
-	origin := Origin{Layer: application.layer}
-	relative, ok := relativeHistoryPath(application.path, operationPath)
-	if !ok {
-		return origin
-	}
-	if node, present := documentAtPath(application.value, relative); present {
-		origin.Locations = []Location{publicLocation(node.Location)}
-	}
-	return origin
-}
-
-func relativeHistoryPath(root, path Path) (Path, bool) {
-	if !pathContains(root, path) {
-		return Path{}, false
-	}
-	return Path{segments: clonePathSegments(path.segments[len(root.segments):], 0)}, true
-}
-
-func pathsIntersect(left, right Path) bool {
-	return pathContains(left, right) || pathContains(right, left)
-}
-
-func applyHistoryApplication(root **document.Node, application historyApplication) {
-	if application.path.String() == "" {
-		mergeHistoryDocument(root, application.value)
-		return
-	}
-	mergeHistoryAtPath(root, application.path, application.value)
-}
-
-func mergeHistoryDocument(target **document.Node, incoming *document.Node) {
-	if incoming == nil {
-		return
-	}
-	if *target == nil || (*target).Kind != document.Mapping || incoming.Kind != document.Mapping {
-		*target = document.Clone(incoming)
-		return
-	}
-	for _, entry := range incoming.Mapping {
-		position := documentEntryIndex((*target).Mapping, entry.Key)
-		if position < 0 {
-			cloned := entry
-			cloned.Value = document.Clone(entry.Value)
-			(*target).Mapping = append((*target).Mapping, cloned)
-			continue
-		}
-		mergeHistoryDocument(&(*target).Mapping[position].Value, entry.Value)
-	}
-}
-
-func mergeHistoryAtPath(root **document.Node, path Path, incoming *document.Node) {
-	if root == nil || *root == nil || len(path.segments) == 0 {
-		mergeHistoryDocument(root, incoming)
-		return
-	}
-	current := *root
-	for index, segment := range path.segments {
-		if current.Kind != document.Mapping || segment.kind == pathSegmentIndex {
-			return
-		}
-		position := documentEntryIndex(current.Mapping, segment.key)
-		if index == len(path.segments)-1 {
-			if position < 0 {
-				current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, Value: document.Clone(incoming)})
-			} else {
-				mergeHistoryDocument(&current.Mapping[position].Value, incoming)
-			}
-			return
-		}
-		if position < 0 {
-			child := &document.Node{Kind: document.Mapping}
-			current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, Value: child})
-			current = child
-		} else {
-			current = current.Mapping[position].Value
-		}
-	}
-}
-
-// Resolution records describe one before/final transformation, not assignment
-// order. A parent already carries its descendants' final values; merge overlapping
-// intent into that event rather than replay a child assignment a second time.
-func coalescedResolutionSnapshots(snapshots []resolutionSnapshot) []resolutionSnapshot {
-	groups := make([]resolutionSnapshot, 0, len(snapshots))
-	for _, snapshot := range snapshots {
-		merged := false
-		for i := range groups {
-			if !pathContains(groups[i].change.Path, snapshot.change.Path) {
-				continue
-			}
-			for _, reason := range snapshot.change.Reasons {
-				groups[i].change.Reasons = appendUniqueString(groups[i].change.Reasons, reason)
-			}
-			for _, dependency := range snapshot.change.Dependencies {
-				groups[i].change.Dependencies = appendUniquePath(groups[i].change.Dependencies, dependency)
-			}
-			if snapshot.change.Origin.Operation == ChangeNormalization {
-				groups[i].change.Origin.Operation = ChangeNormalization
-			}
-			merged = true
-			break
-		}
-		if !merged {
-			snapshot.change = cloneChange(snapshot.change)
-			groups = append(groups, snapshot)
-		}
-	}
-	return groups
-}
-
-func replaceHistoryPath(root **document.Node, path Path, replacement *document.Node) {
-	if root == nil || *root == nil {
-		return
-	}
-	if len(path.segments) == 0 {
-		*root = document.Clone(replacement)
-		return
-	}
-	current := *root
-	for index, segment := range path.segments {
-		last := index == len(path.segments)-1
-		switch current.Kind {
-		case document.Mapping:
-			if segment.kind == pathSegmentIndex {
-				return
-			}
-			position := documentEntryIndex(current.Mapping, segment.key)
-			if position < 0 {
-				if replacement == nil {
-					return
-				}
-				child := &document.Node{Kind: document.Mapping}
-				if last {
-					child = document.Clone(replacement)
-				}
-				current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, Value: child})
-				if last {
-					return
-				}
-				current = child
-				continue
-			}
-			if last {
-				if replacement == nil {
-					current.Mapping = append(current.Mapping[:position], current.Mapping[position+1:]...)
-				} else {
-					current.Mapping[position].Value = document.Clone(replacement)
-				}
-				return
-			}
-			current = current.Mapping[position].Value
-		case document.Sequence:
-			position, ok := schemaIndex(segment)
-			if !ok || position >= len(current.Sequence) {
-				return
-			}
-			if last {
-				if replacement != nil {
-					current.Sequence[position] = document.Clone(replacement)
-				}
-				return
-			}
-			current = current.Sequence[position]
-		default:
-			return
-		}
-	}
-}
-
-func valueSnapshot(root *document.Node, path Path, secrets map[string]bool) ValueSnapshot {
-	node, present := documentAtPath(root, path)
-	if !present {
-		return ValueSnapshot{}
-	}
-	safe, redacted := safeSnapshotDocument(node, secrets, path)
-	var output bytes.Buffer
-	if err := yamladapter.Write(&output, safe); err != nil {
-		return ValueSnapshot{Present: true, Redacted: true, YAML: "'[REDACTED]'\n"}
-	}
-	return ValueSnapshot{Present: true, Redacted: redacted, YAML: output.String()}
-}
-
-func safeSnapshotDocument(node *document.Node, secrets map[string]bool, path Path) (*document.Node, bool) {
-	if node == nil {
-		return nil, false
-	}
-	if pathIsSecret(secrets, path) {
-		return &document.Node{Kind: document.String, Text: "[REDACTED]"}, true
-	}
-	result := *node
-	redacted := false
-	switch node.Kind {
-	case document.Mapping:
-		result.Mapping = make([]document.Entry, len(node.Mapping))
-		copy(result.Mapping, node.Mapping)
-		sortDocumentMapping(result.Mapping)
-		for index := range result.Mapping {
-			entry := &result.Mapping[index]
-			entry.Value, redacted = safeSnapshotChild(entry.Value, secrets, path.Key(entry.Key), redacted)
-		}
-	case document.Sequence:
-		result.Sequence = make([]*document.Node, len(node.Sequence))
-		for index, child := range node.Sequence {
-			result.Sequence[index], redacted = safeSnapshotChild(child, secrets, path.Index(index), redacted)
-		}
-	}
-	return &result, redacted
-}
-
-func safeSnapshotChild(node *document.Node, secrets map[string]bool, path Path, prior bool) (*document.Node, bool) {
-	safe, redacted := safeSnapshotDocument(node, secrets, path)
-	return safe, prior || redacted
-}
-
-func sortDocumentMapping(entries []document.Entry) {
-	slices.SortFunc(entries, func(left, right document.Entry) int {
-		return strings.Compare(left.Key, right.Key)
-	})
-}
-
-func historyNodesWithinLimit(baseline, input, final *document.Node, applications []historyApplication, resolutions []resolutionSnapshot) bool {
-	return historyNodesWithin(historyNodeLimit, baseline, input, final, applications, resolutions)
-}
-
-func historyNodesWithin(limit int, baseline, input, final *document.Node, applications []historyApplication, resolutions []resolutionSnapshot) bool {
-	seen := make(map[*document.Node]bool)
-	count := 0
-	var visit func(*document.Node) bool
-	visit = func(node *document.Node) bool {
-		if node == nil || seen[node] {
-			return true
-		}
-		seen[node] = true
-		count++
-		if count > limit {
-			return false
-		}
-		for _, entry := range node.Mapping {
-			if !visit(entry.Value) {
-				return false
-			}
-		}
-		for _, child := range node.Sequence {
-			if !visit(child) {
-				return false
-			}
-		}
-		return true
-	}
-	if !visit(baseline) || !visit(input) || !visit(final) {
-		return false
-	}
-	for _, application := range applications {
-		if !visit(application.value) {
-			return false
-		}
-	}
-	for _, resolution := range resolutions {
-		if !visit(resolution.before) || !visit(resolution.after) {
-			return false
-		}
-	}
-	return true
-}
-
-// WriteExplanation writes a deterministic human-readable rendering of Explain.
-// Unknown paths produce no output. Writer failures may leave partial output.
-func (r *Result[T]) WriteExplanation(output io.Writer, path Path) error {
-	if r == nil || output == nil {
-		return errExplanationUnavailable
-	}
-	explanation, ok := r.Explain(path)
-	if !ok {
-		return errExplanationUnknownPath
-	}
-	var rendered strings.Builder
-	rendered.WriteString("path: ")
-	rendered.WriteString(strconv.Quote(explanation.Path.String()))
-	rendered.WriteByte('\n')
-	writeExplanationOrigin(&rendered, "effective source", explanation.Origin, r.sources)
-	writeExplanationSnapshot(&rendered, "effective (canonical typed)", explanation.Effective, 0)
-	if explanation.SecretReference != nil {
-		rendered.WriteString("secret reference: ")
-		rendered.WriteString(strconv.Quote(explanation.SecretReference.Name))
-		rendered.WriteString(" (resolved from process environment)\n")
-	}
-	rendered.WriteString("history:\n")
-	for _, change := range explanation.History {
-		rendered.WriteString("  - representation: ")
-		if change.Origin.Operation == ChangeDecoding {
-			rendered.WriteString("input to canonical typed\n")
-		} else if change.Origin.Layer == LayerBase || change.Origin.Layer == LayerProfile || change.Origin.Layer == LayerCLI {
-			rendered.WriteString("policy-validated input\n")
-		} else {
-			rendered.WriteString("canonical typed\n")
-		}
-		writeExplanationOrigin(&rendered, "    source", change.Origin, r.sources)
-		writeExplanationSnapshot(&rendered, "    before", change.Before, 4)
-		writeExplanationSnapshot(&rendered, "    after", change.After, 4)
-		for _, reason := range change.Reasons {
-			rendered.WriteString("    reason: ")
-			rendered.WriteString(strconv.Quote(reason))
-			rendered.WriteByte('\n')
-		}
-		for _, dependency := range change.Dependencies {
-			rendered.WriteString("    dependency: ")
-			rendered.WriteString(strconv.Quote(dependency.String()))
-			rendered.WriteByte('\n')
-		}
-	}
-	data := []byte(rendered.String())
-	written, err := output.Write(data)
-	if err == nil && written != len(data) {
-		return io.ErrShortWrite
-	}
-	return err
-}
-
-func writeExplanationOrigin(output *strings.Builder, label string, origin Origin, sources []SourceInfo) {
-	output.WriteString(label)
-	output.WriteString(": layer=")
-	output.WriteString(strconv.Quote(string(origin.Layer)))
-	if origin.Operation != "" {
-		output.WriteString(" operation=")
-		output.WriteString(strconv.Quote(string(origin.Operation)))
-	}
-	output.WriteByte('\n')
-	for _, location := range origin.Locations {
-		output.WriteString("      location: source=")
-		output.WriteString(strconv.Quote(location.SourceID))
-		if label := sourceLabel(sources, location.SourceID); label != "" {
-			output.WriteString(" label=")
-			output.WriteString(strconv.Quote(label))
-		}
-		output.WriteString(" line=")
-		output.WriteString(strconv.Itoa(location.Line))
-		output.WriteString(" column=")
-		output.WriteString(strconv.Itoa(location.Column))
-		output.WriteByte('\n')
-	}
-}
-
-func sourceLabel(sources []SourceInfo, sourceID string) string {
-	for _, source := range sources {
-		if source.ID == sourceID {
-			return source.Label
-		}
-	}
-	return ""
-}
-
-func writeExplanationSnapshot(output *strings.Builder, label string, snapshot ValueSnapshot, indent int) {
-	if !snapshot.Present {
-		output.WriteString(label)
-		output.WriteString(": absent\n")
-		return
-	}
-	output.WriteString(label)
-	if snapshot.Redacted {
-		output.WriteString(" (redacted)")
-	}
-	output.WriteString(":\n")
-	prefix := strings.Repeat(" ", indent+2)
-	for _, line := range strings.SplitAfter(snapshot.YAML, "\n") {
-		if line == "" {
-			continue
-		}
-		output.WriteString(prefix)
-		output.WriteString(line)
-		if !strings.HasSuffix(line, "\n") {
-			output.WriteByte('\n')
-		}
-	}
-}

explain_render.go

@@ -0,0 +1,123 @@
+package configkit
+
+import (
+	"errors"
+	"io"
+	"strconv"
+	"strings"
+)
+
+var (
+	errExplanationUnavailable = errors.New("configkit: configuration explanation is unavailable")
+	errExplanationUnknownPath = errors.New("configkit: configuration explanation path is unknown")
+)
+
+// WriteExplanation writes a deterministic human-readable rendering of Explain.
+// Unknown paths produce no output. Writer failures may leave partial output.
+func (r *Result[T]) WriteExplanation(output io.Writer, path Path) error {
+	if r == nil || output == nil {
+		return errExplanationUnavailable
+	}
+	explanation, ok := r.Explain(path)
+	if !ok {
+		return errExplanationUnknownPath
+	}
+	var rendered strings.Builder
+	rendered.WriteString("path: ")
+	rendered.WriteString(strconv.Quote(explanation.Path.String()))
+	rendered.WriteByte('\n')
+	writeExplanationOrigin(&rendered, "effective source", explanation.Origin, r.sources)
+	writeExplanationSnapshot(&rendered, "effective (canonical typed)", explanation.Effective, 0)
+	if explanation.SecretReference != nil {
+		rendered.WriteString("secret reference: ")
+		rendered.WriteString(strconv.Quote(explanation.SecretReference.Name))
+		rendered.WriteString(" (resolved from process environment)\n")
+	}
+	rendered.WriteString("history:\n")
+	for _, change := range explanation.History {
+		rendered.WriteString("  - representation: ")
+		if change.Origin.Operation == ChangeDecoding {
+			rendered.WriteString("input to canonical typed\n")
+		} else if change.Origin.Layer == LayerBase || change.Origin.Layer == LayerProfile || change.Origin.Layer == LayerCLI {
+			rendered.WriteString("policy-validated input\n")
+		} else {
+			rendered.WriteString("canonical typed\n")
+		}
+		writeExplanationOrigin(&rendered, "    source", change.Origin, r.sources)
+		writeExplanationSnapshot(&rendered, "    before", change.Before, 4)
+		writeExplanationSnapshot(&rendered, "    after", change.After, 4)
+		for _, reason := range change.Reasons {
+			rendered.WriteString("    reason: ")
+			rendered.WriteString(strconv.Quote(reason))
+			rendered.WriteByte('\n')
+		}
+		for _, dependency := range change.Dependencies {
+			rendered.WriteString("    dependency: ")
+			rendered.WriteString(strconv.Quote(dependency.String()))
+			rendered.WriteByte('\n')
+		}
+	}
+	data := []byte(rendered.String())
+	written, err := output.Write(data)
+	if err == nil && written != len(data) {
+		return io.ErrShortWrite
+	}
+	return err
+}
+
+func writeExplanationOrigin(output *strings.Builder, label string, origin Origin, sources []SourceInfo) {
+	output.WriteString(label)
+	output.WriteString(": layer=")
+	output.WriteString(strconv.Quote(string(origin.Layer)))
+	if origin.Operation != "" {
+		output.WriteString(" operation=")
+		output.WriteString(strconv.Quote(string(origin.Operation)))
+	}
+	output.WriteByte('\n')
+	for _, location := range origin.Locations {
+		output.WriteString("      location: source=")
+		output.WriteString(strconv.Quote(location.SourceID))
+		if label := sourceLabel(sources, location.SourceID); label != "" {
+			output.WriteString(" label=")
+			output.WriteString(strconv.Quote(label))
+		}
+		output.WriteString(" line=")
+		output.WriteString(strconv.Itoa(location.Line))
+		output.WriteString(" column=")
+		output.WriteString(strconv.Itoa(location.Column))
+		output.WriteByte('\n')
+	}
+}
+
+func sourceLabel(sources []SourceInfo, sourceID string) string {
+	for _, source := range sources {
+		if source.ID == sourceID {
+			return source.Label
+		}
+	}
+	return ""
+}
+
+func writeExplanationSnapshot(output *strings.Builder, label string, snapshot ValueSnapshot, indent int) {
+	if !snapshot.Present {
+		output.WriteString(label)
+		output.WriteString(": absent\n")
+		return
+	}
+	output.WriteString(label)
+	if snapshot.Redacted {
+		output.WriteString(" (redacted)")
+	}
+	output.WriteString(":\n")
+	prefix := strings.Repeat(" ", indent+2)
+	for _, line := range strings.SplitAfter(snapshot.YAML, "\n") {
+		if line == "" {
+			continue
+		}
+		output.WriteString(prefix)
+		output.WriteString(line)
+		if !strings.HasSuffix(line, "\n") {
+			output.WriteByte('\n')
+		}
+	}
+}

filesystem.go

@@ -0,0 +1,121 @@
+package configkit
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func validateFilesystemContext(source Source, context *FilesystemContext, main parsedSource) *Diagnostic {
+	rootPath, _, _, diagnostic := importFilesystem(source, context, main)
+	if diagnostic != nil {
+		return diagnostic
+	}
+	root, err := os.OpenRoot(rootPath)
+	if err != nil {
+		value := globFilesystemDiagnostic(err, "configuration root could not be opened", Location{})
+		value.Primary = nil
+		return &value
+	}
+	if err := root.Close(); err != nil {
+		value := importDiagnostic(CodeImportRead, "configuration root could not be closed", nil)
+		return &value
+	}
+	return nil
+}
+
+func filesystemOptionDiagnostics(source Source, context *FilesystemContext) []Diagnostic {
+	switch source.kind {
+	case sourceNone:
+		return []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "NoSource cannot use filesystem context")}
+	case sourceFile:
+		if context.BaseDir != "" {
+			return []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "file sources determine their own import base directory")}
+		}
+	case sourceBytes, sourceReader:
+		if context.BaseDir == "" || context.Root == "" {
+			return []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "byte and reader filesystem context requires base and root directories")}
+		}
+		if !filepath.IsAbs(context.BaseDir) || !filepath.IsAbs(context.Root) {
+			return []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "byte and reader filesystem base and root directories must be absolute")}
+		}
+	}
+	return nil
+}
+
+func importFilesystem(source Source, context *FilesystemContext, main parsedSource) (rootPath, basePath, mainPath string, diagnostic *Diagnostic) {
+	if main.source == nil || main.document == nil {
+		value := importDiagnostic(CodeImportInvalid, "imports require a selected configuration source", nil)
+		return "", "", "", &value
+	}
+
+	if source.kind == sourceFile {
+		if context != nil && context.BaseDir != "" {
+			value := optionDiagnostic(CodeOptionsInvalid, "file sources determine their own import base directory")
+			return "", "", "", &value
+		}
+		canonical, err := canonicalExistingPath(source.path)
+		if err != nil {
+			value := importDiagnostic(CodeImportInvalid, "selected source path could not be canonicalized", nil)
+			return "", "", "", &value
+		}
+		mainPath = canonical
+		basePath = filepath.Dir(canonical)
+		rootPath = basePath
+		if context != nil && context.Root != "" {
+			rootPath, err = canonicalExistingPath(context.Root)
+			if err != nil {
+				value := importDiagnostic(CodeImportInvalid, "configuration root could not be canonicalized", nil)
+				return "", "", "", &value
+			}
+		}
+	} else {
+		if context == nil || context.BaseDir == "" || context.Root == "" {
+			value := optionDiagnostic(CodeOptionsInvalid, "byte and reader imports require absolute base and root directories")
+			return "", "", "", &value
+		}
+		if !filepath.IsAbs(context.BaseDir) || !filepath.IsAbs(context.Root) {
+			value := optionDiagnostic(CodeOptionsInvalid, "byte and reader import base and root directories must be absolute")
+			return "", "", "", &value
+		}
+		var err error
+		basePath, err = canonicalExistingPath(context.BaseDir)
+		if err != nil {
+			value := importDiagnostic(CodeImportInvalid, "import base directory could not be canonicalized", nil)
+			return "", "", "", &value
+		}
+		rootPath, err = canonicalExistingPath(context.Root)
+		if err != nil {
+			value := importDiagnostic(CodeImportInvalid, "configuration root could not be canonicalized", nil)
+			return "", "", "", &value
+		}
+	}
+	if !containedPath(rootPath, basePath) || (mainPath != "" && !containedPath(rootPath, mainPath)) {
+		value := importDiagnostic(CodeImportOutsideRoot, "selected source and import base must stay inside the configuration root", nil)
+		return "", "", "", &value
+	}
+	for _, candidate := range []string{rootPath, basePath} {
+		info, err := os.Stat(candidate)
+		if err != nil || !info.IsDir() {
+			value := importDiagnostic(CodeImportInvalid, "configuration root and import base must be directories", nil)
+			return "", "", "", &value
+		}
+	}
+	return rootPath, basePath, mainPath, nil
+}
+
+func canonicalExistingPath(name string) (string, error) {
+	absolute, err := filepath.Abs(name)
+	if err != nil {
+		return "", err
+	}
+	return filepath.EvalSymlinks(filepath.Clean(absolute))
+}
+
+func containedPath(root, target string) bool {
+	relative, err := filepath.Rel(root, target)
+	if err != nil || filepath.IsAbs(relative) {
+		return false
+	}
+	return relative != ".." && !strings.HasPrefix(relative, ".."+string(filepath.Separator))
+}

history.go

@@ -0,0 +1,276 @@
+package configkit
+
+import (
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+const historyNodeLimit = 4_000_000
+
+// History applications borrow immutable policy-validated input trees. Metadata
+// records answer presence and origin queries; replay reconstructs value changes.
+// Replay reconciles with canonical decoding before domain resolution so both
+// contracts agree on the effective result without retaining a tree per field.
+type historyApplication struct {
+	layer  Layer
+	path   Path
+	value  *document.Node
+	origin Origin
+}
+
+func cloneHistoryApplications(values []historyApplication) []historyApplication {
+	if values == nil {
+		return nil
+	}
+	cloned := make([]historyApplication, len(values))
+	for index, value := range values {
+		cloned[index] = historyApplication{
+			layer: value.layer, path: value.path.clone(), value: value.value,
+			origin: cloneOrigin(value.origin),
+		}
+	}
+	return cloned
+}
+
+func applicationOperationPath(application historyApplication, query Path) (Path, bool) {
+	if !application.path.valid() || application.value == nil {
+		return Path{}, false
+	}
+	if application.path.String() != "" {
+		if pathsIntersect(application.path, query) {
+			return application.path.clone(), true
+		}
+		return Path{}, false
+	}
+	if len(query.segments) == 0 {
+		return Path{}, true
+	}
+	for length := 1; length <= len(query.segments); length++ {
+		prefix := Path{segments: clonePathSegments(query.segments[:length], 0)}
+		node, present := documentAtPath(application.value, prefix)
+		if !present {
+			return Path{}, false
+		}
+		if length == len(query.segments) || node.Kind != document.Mapping {
+			return prefix, true
+		}
+	}
+	return Path{}, false
+}
+
+func historyApplicationOrigin(application historyApplication, operationPath Path) Origin {
+	if application.origin.Layer != "" {
+		return cloneOrigin(application.origin)
+	}
+	origin := Origin{Layer: application.layer}
+	relative, ok := relativeHistoryPath(application.path, operationPath)
+	if !ok {
+		return origin
+	}
+	if node, present := documentAtPath(application.value, relative); present {
+		origin.Locations = []Location{publicLocation(node.Location)}
+	}
+	return origin
+}
+
+func relativeHistoryPath(root, path Path) (Path, bool) {
+	if !pathContains(root, path) {
+		return Path{}, false
+	}
+	return Path{segments: clonePathSegments(path.segments[len(root.segments):], 0)}, true
+}
+
+func pathsIntersect(left, right Path) bool {
+	return pathContains(left, right) || pathContains(right, left)
+}
+
+func applyHistoryApplication(root **document.Node, application historyApplication) {
+	if application.path.String() == "" {
+		mergeHistoryDocument(root, application.value)
+		return
+	}
+	mergeHistoryAtPath(root, application.path, application.value)
+}
+
+func mergeHistoryDocument(target **document.Node, incoming *document.Node) {
+	if incoming == nil {
+		return
+	}
+	if *target == nil || (*target).Kind != document.Mapping || incoming.Kind != document.Mapping {
+		*target = document.Clone(incoming)
+		return
+	}
+	for _, entry := range incoming.Mapping {
+		position := documentEntryIndex((*target).Mapping, entry.Key)
+		if position < 0 {
+			cloned := entry
+			cloned.Value = document.Clone(entry.Value)
+			(*target).Mapping = append((*target).Mapping, cloned)
+			continue
+		}
+		mergeHistoryDocument(&(*target).Mapping[position].Value, entry.Value)
+	}
+}
+
+func mergeHistoryAtPath(root **document.Node, path Path, incoming *document.Node) {
+	if root == nil || *root == nil || len(path.segments) == 0 {
+		mergeHistoryDocument(root, incoming)
+		return
+	}
+	current := *root
+	for index, segment := range path.segments {
+		if current.Kind != document.Mapping || segment.kind == pathSegmentIndex {
+			return
+		}
+		position := documentEntryIndex(current.Mapping, segment.key)
+		if index == len(path.segments)-1 {
+			if position < 0 {
+				current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, Value: document.Clone(incoming)})
+			} else {
+				mergeHistoryDocument(&current.Mapping[position].Value, incoming)
+			}
+			return
+		}
+		if position < 0 {
+			child := &document.Node{Kind: document.Mapping}
+			current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, Value: child})
+			current = child
+		} else {
+			current = current.Mapping[position].Value
+		}
+	}
+}
+
+// Resolution records describe one before/final transformation, not assignment
+// order. A parent already carries its descendants' final values; merge overlapping
+// intent into that event rather than replay a child assignment a second time.
+func coalescedResolutionSnapshots(snapshots []resolutionSnapshot) []resolutionSnapshot {
+	groups := make([]resolutionSnapshot, 0, len(snapshots))
+	for _, snapshot := range snapshots {
+		merged := false
+		for i := range groups {
+			if !pathContains(groups[i].change.Path, snapshot.change.Path) {
+				continue
+			}
+			for _, reason := range snapshot.change.Reasons {
+				groups[i].change.Reasons = appendUniqueString(groups[i].change.Reasons, reason)
+			}
+			for _, dependency := range snapshot.change.Dependencies {
+				groups[i].change.Dependencies = appendUniquePath(groups[i].change.Dependencies, dependency)
+			}
+			if snapshot.change.Origin.Operation == ChangeNormalization {
+				groups[i].change.Origin.Operation = ChangeNormalization
+			}
+			merged = true
+			break
+		}
+		if !merged {
+			snapshot.change = cloneChange(snapshot.change)
+			groups = append(groups, snapshot)
+		}
+	}
+	return groups
+}
+
+func replaceHistoryPath(root **document.Node, path Path, replacement *document.Node) {
+	if root == nil || *root == nil {
+		return
+	}
+	if len(path.segments) == 0 {
+		*root = document.Clone(replacement)
+		return
+	}
+	current := *root
+	for index, segment := range path.segments {
+		last := index == len(path.segments)-1
+		switch current.Kind {
+		case document.Mapping:
+			if segment.kind == pathSegmentIndex {
+				return
+			}
+			position := documentEntryIndex(current.Mapping, segment.key)
+			if position < 0 {
+				if replacement == nil {
+					return
+				}
+				child := &document.Node{Kind: document.Mapping}
+				if last {
+					child = document.Clone(replacement)
+				}
+				current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, Value: child})
+				if last {
+					return
+				}
+				current = child
+				continue
+			}
+			if last {
+				if replacement == nil {
+					current.Mapping = append(current.Mapping[:position], current.Mapping[position+1:]...)
+				} else {
+					current.Mapping[position].Value = document.Clone(replacement)
+				}
+				return
+			}
+			current = current.Mapping[position].Value
+		case document.Sequence:
+			position, ok := schemaIndex(segment)
+			if !ok || position >= len(current.Sequence) {
+				return
+			}
+			if last {
+				if replacement != nil {
+					current.Sequence[position] = document.Clone(replacement)
+				}
+				return
+			}
+			current = current.Sequence[position]
+		default:
+			return
+		}
+	}
+}
+
+func historyNodesWithinLimit(baseline, input, final *document.Node, applications []historyApplication, resolutions []resolutionSnapshot) bool {
+	return historyNodesWithin(historyNodeLimit, baseline, input, final, applications, resolutions)
+}
+
+func historyNodesWithin(limit int, baseline, input, final *document.Node, applications []historyApplication, resolutions []resolutionSnapshot) bool {
+	seen := make(map[*document.Node]bool)
+	count := 0
+	var visit func(*document.Node) bool
+	visit = func(node *document.Node) bool {
+		if node == nil || seen[node] {
+			return true
+		}
+		seen[node] = true
+		count++
+		if count > limit {
+			return false
+		}
+		for _, entry := range node.Mapping {
+			if !visit(entry.Value) {
+				return false
+			}
+		}
+		for _, child := range node.Sequence {
+			if !visit(child) {
+				return false
+			}
+		}
+		return true
+	}
+	if !visit(baseline) || !visit(input) || !visit(final) {
+		return false
+	}
+	for _, application := range applications {
+		if !visit(application.value) {
+			return false
+		}
+	}
+	for _, resolution := range resolutions {
+		if !visit(resolution.before) || !visit(resolution.after) {
+			return false
+		}
+	}
+	return true
+}

imports.go

@@ -3,7 +3,6 @@ package configkit
 import (
 	"bytes"
 	"errors"
-	"io"
 	"io/fs"
 	"os"
 	"path"
@@ -36,13 +35,6 @@ func defaultImportLimits() importLimits {
 	}
 }
 
-type importDeclaration struct {
-	path     string
-	glob     string
-	optional bool
-	location Location
-}
-
 type importRoute struct {
 	canonical string
 	locations []Location
@@ -121,120 +113,6 @@ func loadImportedDocuments(source Source, context *FilesystemContext, main parse
 	return composed, cloneSourceInfos(state.sources), diagnostics
 }
 
-func validateFilesystemContext(source Source, context *FilesystemContext, main parsedSource) *Diagnostic {
-	rootPath, _, _, diagnostic := importFilesystem(source, context, main)
-	if diagnostic != nil {
-		return diagnostic
-	}
-	root, err := os.OpenRoot(rootPath)
-	if err != nil {
-		value := globFilesystemDiagnostic(err, "configuration root could not be opened", Location{})
-		value.Primary = nil
-		return &value
-	}
-	if err := root.Close(); err != nil {
-		value := importDiagnostic(CodeImportRead, "configuration root could not be closed", nil)
-		return &value
-	}
-	return nil
-}
-
-func filesystemOptionDiagnostics(source Source, context *FilesystemContext) []Diagnostic {
-	switch source.kind {
-	case sourceNone:
-		return []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "NoSource cannot use filesystem context")}
-	case sourceFile:
-		if context.BaseDir != "" {
-			return []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "file sources determine their own import base directory")}
-		}
-	case sourceBytes, sourceReader:
-		if context.BaseDir == "" || context.Root == "" {
-			return []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "byte and reader filesystem context requires base and root directories")}
-		}
-		if !filepath.IsAbs(context.BaseDir) || !filepath.IsAbs(context.Root) {
-			return []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "byte and reader filesystem base and root directories must be absolute")}
-		}
-	}
-	return nil
-}
-
-func importFilesystem(source Source, context *FilesystemContext, main parsedSource) (rootPath, basePath, mainPath string, diagnostic *Diagnostic) {
-	if main.source == nil || main.document == nil {
-		value := importDiagnostic(CodeImportInvalid, "imports require a selected configuration source", nil)
-		return "", "", "", &value
-	}
-
-	if source.kind == sourceFile {
-		if context != nil && context.BaseDir != "" {
-			value := optionDiagnostic(CodeOptionsInvalid, "file sources determine their own import base directory")
-			return "", "", "", &value
-		}
-		canonical, err := canonicalExistingPath(source.path)
-		if err != nil {
-			value := importDiagnostic(CodeImportInvalid, "selected source path could not be canonicalized", nil)
-			return "", "", "", &value
-		}
-		mainPath = canonical
-		basePath = filepath.Dir(canonical)
-		rootPath = basePath
-		if context != nil && context.Root != "" {
-			rootPath, err = canonicalExistingPath(context.Root)
-			if err != nil {
-				value := importDiagnostic(CodeImportInvalid, "configuration root could not be canonicalized", nil)
-				return "", "", "", &value
-			}
-		}
-	} else {
-		if context == nil || context.BaseDir == "" || context.Root == "" {
-			value := optionDiagnostic(CodeOptionsInvalid, "byte and reader imports require absolute base and root directories")
-			return "", "", "", &value
-		}
-		if !filepath.IsAbs(context.BaseDir) || !filepath.IsAbs(context.Root) {
-			value := optionDiagnostic(CodeOptionsInvalid, "byte and reader import base and root directories must be absolute")
-			return "", "", "", &value
-		}
-		var err error
-		basePath, err = canonicalExistingPath(context.BaseDir)
-		if err != nil {
-			value := importDiagnostic(CodeImportInvalid, "import base directory could not be canonicalized", nil)
-			return "", "", "", &value
-		}
-		rootPath, err = canonicalExistingPath(context.Root)
-		if err != nil {
-			value := importDiagnostic(CodeImportInvalid, "configuration root could not be canonicalized", nil)
-			return "", "", "", &value
-		}
-	}
-	if !containedPath(rootPath, basePath) || (mainPath != "" && !containedPath(rootPath, mainPath)) {
-		value := importDiagnostic(CodeImportOutsideRoot, "selected source and import base must stay inside the configuration root", nil)
-		return "", "", "", &value
-	}
-	for _, candidate := range []string{rootPath, basePath} {
-		info, err := os.Stat(candidate)
-		if err != nil || !info.IsDir() {
-			value := importDiagnostic(CodeImportInvalid, "configuration root and import base must be directories", nil)
-			return "", "", "", &value
-		}
-	}
-	return rootPath, basePath, mainPath, nil
-}
-
-func canonicalExistingPath(name string) (string, error) {
-	absolute, err := filepath.Abs(name)
-	if err != nil {
-		return "", err
-	}
-	return filepath.EvalSymlinks(filepath.Clean(absolute))
-}
-
-func containedPath(root, target string) bool {
-	relative, err := filepath.Rel(root, target)
-	if err != nil || filepath.IsAbs(relative) {
-		return false
-	}
-	return relative != ".." && !strings.HasPrefix(relative, ".."+string(filepath.Separator))
-}
-
 func (s *importTraversal) checkInitialLimits() *Diagnostic {
 	if s.limits.sources < 1 {
 		value := importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the source-count limit", nil)
@@ -345,7 +223,7 @@ func (s *importTraversal) visitPath(basePath string, declaration importDeclarati
 		Depth: maxDocumentDepth, Nodes: maxDocumentNodes,
 	})
 	if len(issues) != 0 {
-		return importParseDiagnostics(sourceID, issues)
+		return parserDiagnostics(sourceID, issues)
 	}
 	nodeCount := countInputNodes(root)
 	if s.usedNodes+nodeCount > s.limits.nodes {
@@ -382,47 +260,12 @@ func (s *importTraversal) readImport(relative, sourceID string, optional bool) (
 	if limit < 0 {
 		limit = 0
 	}
-	preflight, err := s.root.Stat(relative)
-	if err != nil {
-		if optional && errors.Is(err, fs.ErrNotExist) {
+	data, failure := readRegularFile(relative, s.root.Stat, s.root.Open, limit)
+	if failure != nil {
+		if optional && failure.missingTarget {
 			return nil, true, nil
 		}
-		value := classifySourceError(err, sourceID)
-		return nil, false, &value
-	}
-	if !preflight.Mode().IsRegular() {
-		value := sourceDiagnostic(CodeSourceNotRegular, sourceID, "source is not a regular file")
-		return nil, false, &value
-	}
-	file, err := s.root.Open(relative)
-	if err != nil {
-		if optional && errors.Is(err, fs.ErrNotExist) {
-			return nil, true, nil
-		}
-		value := classifySourceError(err, sourceID)
-		return nil, false, &value
-	}
-	defer func() { _ = file.Close() }()
-	info, err := file.Stat()
-	if err != nil {
-		value := classifySourceError(err, sourceID)
-		return nil, false, &value
-	}
-	if !info.Mode().IsRegular() {
-		value := sourceDiagnostic(CodeSourceNotRegular, sourceID, "source is not a regular file")
-		return nil, false, &value
-	}
-	if info.Size() > limit {
-		value := importDiagnostic(CodeImportLimitExceeded, "configuration exceeds a source or aggregate byte limit", &Location{SourceID: sourceID})
-		return nil, false, &value
-	}
-	data, err := io.ReadAll(io.LimitReader(file, limit+1))
-	if err != nil {
-		value := classifySourceError(err, sourceID)
-		return nil, false, &value
-	}
-	if int64(len(data)) > limit {
-		value := importDiagnostic(CodeImportLimitExceeded, "configuration exceeds a source or aggregate byte limit", &Location{SourceID: sourceID})
+		value := sourceReadDiagnostic(failure, sourceID, CodeImportLimitExceeded, "configuration exceeds a source or aggregate byte limit")
 		return nil, false, &value
 	}
 	s.usedBytes += int64(len(data))
@@ -440,184 +283,6 @@ func (s *importTraversal) currentRoute(location Location) importRoute {
 	return importRoute{locations: locations}
 }
 
-func splitImportDirectives(root *document.Node) (*document.Node, []importDeclaration, []Diagnostic) {
-	body := document.Clone(root)
-	var declarations []importDeclaration
-	directiveIndex := -1
-	for index, entry := range body.Mapping {
-		if entry.Key != "_configkit" {
-			continue
-		}
-		directiveIndex = index
-		parsed, diagnostics := parseImportDirective(entry.Value, Keys("_configkit"))
-		if len(diagnostics) != 0 {
-			return nil, nil, diagnostics
-		}
-		declarations = parsed
-		break
-	}
-	if directiveIndex >= 0 {
-		body.Mapping = append(body.Mapping[:directiveIndex], body.Mapping[directiveIndex+1:]...)
-	}
-	if diagnostics := nestedDirectiveDiagnostics(body, Path{}); len(diagnostics) != 0 {
-		return nil, nil, diagnostics
-	}
-	return body, declarations, nil
-}
-
-func parseImportDirective(node *document.Node, directivePath Path) ([]importDeclaration, []Diagnostic) {
-	if node.Kind != document.Mapping {
-		return nil, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, directivePath, "configuration directive must be a mapping", node)}
-	}
-	var declarations []importDeclaration
-	for _, entry := range node.Mapping {
-		fieldPath := directivePath.Key(entry.Key)
-		if entry.Key != "imports" {
-			return nil, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "configuration directive field is not recognized", entry.Value)}
-		}
-		if entry.Value.Kind != document.Sequence {
-			return nil, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "imports must be a sequence", entry.Value)}
-		}
-		for index, item := range entry.Value.Sequence {
-			declaration, diagnostics := parseImportDeclaration(item, fieldPath.Index(index))
-			if len(diagnostics) != 0 {
-				return nil, diagnostics
-			}
-			declarations = append(declarations, declaration)
-		}
-	}
-	return declarations, nil
-}
-
-func parseImportDeclaration(node *document.Node, declarationPath Path) (importDeclaration, []Diagnostic) {
-	if node.Kind != document.Mapping {
-		return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, declarationPath, "import declaration must be a mapping", node)}
-	}
-	declaration := importDeclaration{location: publicLocation(node.Location)}
-	seenTarget := false
-	for _, entry := range node.Mapping {
-		fieldPath := declarationPath.Key(entry.Key)
-		switch entry.Key {
-		case "path", "glob":
-			if seenTarget || entry.Value.Kind != document.String || entry.Value.Text == "" || strings.TrimSpace(entry.Value.Text) != entry.Value.Text {
-				return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "import declaration requires exactly one nonempty path or glob string", entry.Value)}
-			}
-			seenTarget = true
-			declaration.location = publicLocation(entry.Value.Location)
-			if entry.Key == "path" {
-				declaration.path = entry.Value.Text
-			} else {
-				declaration.glob = entry.Value.Text
-			}
-		case "optional":
-			if entry.Value.Kind != document.Boolean {
-				return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "optional must be a boolean", entry.Value)}
-			}
-			declaration.optional = entry.Value.Text == "true"
-		default:
-			return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "import declaration field is not recognized", entry.Value)}
-		}
-	}
-	if !seenTarget {
-		return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, declarationPath, "import declaration requires exactly one path or glob", node)}
-	}
-	return declaration, nil
-}
-
-func nestedDirectiveDiagnostics(node *document.Node, current Path) []Diagnostic {
-	if node.Kind == document.Mapping {
-		for _, entry := range node.Mapping {
-			childPath := current.Key(entry.Key)
-			if entry.Key == "_configkit" {
-				location := publicLocation(entry.KeyLocation)
-				return []Diagnostic{{Code: CodeImportInvalid, Severity: SeverityError, Path: childPath, Message: "configuration directives are permitted only at the document root", Primary: &location}}
-			}
-			if diagnostics := nestedDirectiveDiagnostics(entry.Value, childPath); len(diagnostics) != 0 {
-				return diagnostics
-			}
-		}
-	} else if node.Kind == document.Sequence {
-		for index, child := range node.Sequence {
-			if diagnostics := nestedDirectiveDiagnostics(child, current.Index(index)); len(diagnostics) != 0 {
-				return diagnostics
-			}
-		}
-	}
-	return nil
-}
-
-func fragmentVersionClaim(root *document.Node, rule *VersionRule) *document.Node {
-	if rule == nil {
-		return nil
-	}
-	current := root
-	if len(rule.Path.segments) == 0 {
-		return current
-	}
-	for _, segment := range rule.Path.segments {
-		if current.Kind != document.Mapping {
-			return current
-		}
-		if segment.kind == pathSegmentIndex {
-			return nil
-		}
-		key := segment.key
-		index := documentEntryIndex(current.Mapping, key)
-		if index < 0 {
-			return nil
-		}
-		current = current.Mapping[index].Value
-	}
-	return current
-}
-
-func countInputNodes(node *document.Node) int {
-	if node == nil {
-		return 0
-	}
-	count := 1
-	if node.Kind == document.Mapping {
-		count += len(node.Mapping)
-		for _, entry := range node.Mapping {
-			count += countInputNodes(entry.Value)
-		}
-	} else if node.Kind == document.Sequence {
-		for _, child := range node.Sequence {
-			count += countInputNodes(child)
-		}
-	}
-	return count
-}
-
-func validImportPath(value string) bool {
-	if value == "" || strings.TrimSpace(value) != value || path.IsAbs(value) || strings.HasPrefix(value, "//") {
-		return false
-	}
-	return !hasImportScheme(value)
-}
-
-func hasImportScheme(value string) bool {
-	colon := strings.IndexByte(value, ':')
-	slash := strings.IndexByte(value, '/')
-	if colon <= 0 || (slash >= 0 && slash < colon) {
-		return false
-	}
-	for index := 0; index < colon; index++ {
-		character := value[index]
-		if index == 0 {
-			if (character < 'a' || character > 'z') && (character < 'A' || character > 'Z') {
-				return false
-			}
-			continue
-		}
-		if (character < 'a' || character > 'z') && (character < 'A' || character > 'Z') &&
-			(character < '0' || character > '9') && character != '+' && character != '-' && character != '.' {
-			return false
-		}
-	}
-	return true
-}
-
 func sourceInfos(source *SourceInfo) []SourceInfo {
 	if source == nil {
 		return nil
@@ -625,29 +290,10 @@ func sourceInfos(source *SourceInfo) []SourceInfo {
 	return []SourceInfo{cloneSourceInfo(*source)}
 }
 
-func importParseDiagnostics(sourceID string, issues []yamladapter.Issue) []Diagnostic {
-	diagnostics := make([]Diagnostic, len(issues))
-	for index, issue := range issues {
-		diagnostics[index] = Diagnostic{
-			Code: Code(issue.Code), Severity: SeverityError, Message: issue.Message,
-			Primary: &Location{SourceID: sourceID, Line: issue.Line, Column: issue.Column},
-		}
-		for _, related := range issue.Related {
-			diagnostics[index].Related = append(diagnostics[index].Related, publicLocation(related))
-		}
-	}
-	return diagnostics
-}
-
 func importDiagnostic(code Code, message string, location *Location) Diagnostic {
 	return Diagnostic{Code: code, Severity: SeverityError, Message: message, Primary: cloneLocation(location)}
 }
 
-func nodeImportDiagnostic(code Code, path Path, message string, node *document.Node) Diagnostic {
-	location := publicLocation(node.Location)
-	return Diagnostic{Code: code, Severity: SeverityError, Path: path, Message: message, Primary: &location}
-}
-
 func importCycleDiagnostic(target string, location Location, cycle []importRoute) Diagnostic {
 	paths := make([]string, 0, len(cycle)+1)
 	related := make([]Location, 0, len(cycle))

load.go

@@ -114,350 +114,69 @@ func Load[T any](source Source, supplied ...Options[T]) (*Result[T], error) {
 func loadWithSecretLookup[T any](source Source, lookup secretLookup, supplied ...Options[T]) (*Result[T], error) {
 	accumulator := diagnosticAccumulator{}
 	options, diagnostics := selectOptions(source, supplied)
+	accumulator.add(diagnostics...)
 	if len(diagnostics) != 0 {
-		accumulator.add(diagnostics...)
 		return nil, accumulator.loadError()
 	}
 
-	parsed, diagnostics := parseSource(source, "source-1", defaultParseLimits())
+	input, diagnostics := assembleBaseInput(source, options)
+	accumulator.sources = input.sources
+	accumulator.add(diagnostics...)
 	if len(diagnostics) != 0 {
-		if parsed.source != nil {
-			accumulator.sources = append(accumulator.sources, *parsed.source)
-		}
-		accumulator.add(diagnostics...)
 		return nil, accumulator.loadError()
 	}
-
-	inputDocument := parsed.document
-	var composition *composedDocument
-	if options.Imports {
-		composition, accumulator.sources, diagnostics = loadImportedDocuments(source, options.Filesystem, parsed, options.Definition.Version, defaultImportLimits())
-		if len(diagnostics) != 0 {
-			accumulator.add(diagnostics...)
-			return nil, accumulator.loadError()
-		}
-		inputDocument = composition.root
-	} else {
-		if parsed.source != nil {
-			accumulator.sources = append(accumulator.sources, *parsed.source)
-		}
-		if options.Filesystem != nil && !activeProfile(options.Profile) {
-			if diagnostic := validateFilesystemContext(source, options.Filesystem, parsed); diagnostic != nil {
-				accumulator.add(*diagnostic)
-				return nil, accumulator.loadError()
-			}
-		}
-	}
-	if !options.Imports && inputDocument != nil {
-		directiveDiagnostics := disabledDirectiveDiagnostics(inputDocument, Path{})
-		if len(directiveDiagnostics) != 0 {
-			accumulator.add(directiveDiagnostics...)
-			return nil, accumulator.loadError()
-		}
-	}
-
 	schema, schemaIssue := buildSchema(reflect.TypeFor[T]())
 	if schemaIssue != nil {
 		accumulator.add(diagnosticFromSchemaIssue(schemaIssue))
 		return nil, accumulator.loadError()
 	}
-
-	versionDiagnostics := checkVersion(options.Definition.Version, inputDocument)
+	versionDiagnostics := checkVersion(options.Definition.Version, input.document)
 	accumulator.add(versionDiagnostics...)
 	if hasErrors(versionDiagnostics) {
 		return nil, accumulator.loadError()
 	}
-	if activeProfile(options.Profile) {
-		if composition == nil {
-			composition, diagnostics = composeDocuments(inputDocument)
-			if len(diagnostics) != 0 {
-				accumulator.add(diagnostics...)
-				return nil, accumulator.loadError()
-			}
-			composition.inputBytes = parsed.bytes
-			composition.inputNodes = countInputNodes(parsed.document)
-		}
-		composition, accumulator.sources, diagnostics = loadProfileDocument(
-			source, options.Filesystem, parsed, composition, accumulator.sources,
-			options.Profile, options.Definition.Version, defaultImportLimits(),
-		)
-		if len(diagnostics) != 0 {
-			accumulator.add(diagnostics...)
-			return nil, accumulator.loadError()
-		}
-		inputDocument = composition.root
-	}
-	if len(options.Overrides) != 0 {
-		if composition == nil {
-			if inputDocument == nil {
-				composition = &composedDocument{root: &document.Node{Kind: document.Mapping}, origins: make(map[string]Origin)}
-			} else {
-				composition, diagnostics = composeDocuments(inputDocument)
-				if len(diagnostics) != 0 {
-					accumulator.add(diagnostics...)
-					return nil, accumulator.loadError()
-				}
-				composition.inputBytes = parsed.bytes
-				composition.inputNodes = countInputNodes(inputDocument)
-			}
-		}
-		composition, accumulator.sources, diagnostics = applyOverrides(
-			composition, accumulator.sources, options.Overrides, options.Definition.Version, defaultImportLimits(),
-		)
-		if len(diagnostics) != 0 {
-			accumulator.add(diagnostics...)
-			return nil, accumulator.loadError()
-		}
-		inputDocument = composition.root
-	}
-
-	defaults := reflect.Zero(reflect.TypeFor[T]())
-	if options.Definition.Defaults != nil {
-		defaults = reflect.ValueOf(options.Definition.Defaults())
-	}
-	decoded, decodeIssues := decodeConfiguration(schema, defaults, inputDocument)
-	if len(decodeIssues) != 0 {
-		for _, issue := range decodeIssues {
-			accumulator.add(diagnosticFromDecodeIssue(issue))
-		}
+	input, diagnostics = applyInputLayers(source, options, input)
+	accumulator.sources = input.sources
+	accumulator.add(diagnostics...)
+	if len(diagnostics) != 0 {
 		return nil, accumulator.loadError()
 	}
-	if composition != nil {
-		applyCompositionOrigins(&decoded, composition.origins)
-	}
 
-	configuration := decoded.value.Interface().(T)
-	metadata := metadataFromDecoded(decoded)
-	if composition != nil {
-		applyOverlayMetadata(&metadata, composition.overlays)
+	decoded, diagnostics := decodeLoadInput(schema, options.Definition, input)
+	accumulator.add(diagnostics...)
+	if len(diagnostics) != 0 {
+		return nil, accumulator.loadError()
 	}
-	final := decoded.final
-	var resolutionSnapshots []resolutionSnapshot
-	if options.Definition.Resolve != nil {
-		resolved := runResolution(&configuration, options.Definition.Resolve, schema, decoded, inputDocument)
-		accumulator.add(resolved.diagnostics...)
-		if hasErrors(resolved.diagnostics) {
-			return nil, accumulator.loadError()
-		}
-		final = resolved.final
-		resolutionSnapshots = resolved.snapshots
-		applyResolutionMetadata(&metadata, resolved)
+	resolved, diagnostics := resolveLoadInput(schema, options.Definition, input, decoded)
+	accumulator.add(diagnostics...)
+	if hasErrors(diagnostics) {
+		return nil, accumulator.loadError()
 	}
-	applications := []historyApplication(nil)
-	if composition != nil {
-		applications = cloneHistoryApplications(composition.applications)
-	} else if inputDocument != nil {
-		applications = []historyApplication{{layer: LayerBase, value: inputDocument}}
-	}
-	if !historyNodesWithinLimit(decoded.baseline, decoded.final, final, applications, resolutionSnapshots) {
+	if !historyNodesWithinLimit(decoded.baseline, decoded.final, resolved.final, resolved.applications, resolved.snapshots) {
 		accumulator.add(Diagnostic{Code: CodeExplainLimitExceeded, Severity: SeverityError, Message: "retained configuration history exceeds the node limit"})
 		return nil, accumulator.loadError()
 	}
-	// Resolver assignments may borrow application-owned mutable values. Detach
-	// before secret resolution mutates reference fields or validation sees them.
-	detached, ownershipIssue := cloneConfiguration(schema, reflect.ValueOf(configuration), defaultProjectionLimits())
+
+	// Detach resolver-borrowed values before reference mutation or validation.
+	configuration, ownershipIssue := detachLoadConfiguration(schema, resolved.configuration, cloneUnresolvedSecrets)
 	if ownershipIssue != nil {
-		accumulator.add(diagnosticFromDecodeIssue(decodeIssueFromProjection(ownershipIssue)))
+		accumulator.add(*ownershipIssue)
 		return nil, accumulator.loadError()
 	}
-	configuration = detached.Interface().(T)
-	secretResolution := resolveSecretReferences(reflect.ValueOf(&configuration).Elem(), schema, inputDocument, lookup)
+	secretResolution := resolveSecretReferences(reflect.ValueOf(&configuration).Elem(), schema, input.document, lookup)
 	accumulator.add(secretResolution.diagnostics...)
 	if hasErrors(secretResolution.diagnostics) {
 		return nil, accumulator.loadError()
 	}
 	if options.Definition.Validate != nil {
-		validationDiagnostics := runValidation(&configuration, options.Definition.Validate, schema, final, inputDocument, secretResolution.lookups)
-		accumulator.add(validationDiagnostics...)
-		if hasErrors(validationDiagnostics) {
+		diagnostics = runValidation(&configuration, options.Definition.Validate, schema, resolved.final, input.document, secretResolution.lookups)
+		accumulator.add(diagnostics...)
+		if hasErrors(diagnostics) {
 			return nil, accumulator.loadError()
 		}
 	}
-	// A read-only validator can replace a value with an equal borrowed object.
-	// Projected mutation checks cannot detect that alias, so detach at publication.
-	published, ownershipIssue := cloneConfigurationState(schema, reflect.ValueOf(configuration), defaultProjectionLimits(), true)
-	if ownershipIssue != nil {
-		accumulator.add(diagnosticFromDecodeIssue(decodeIssueFromProjection(ownershipIssue)))
-		return nil, accumulator.loadError()
-	}
-	configuration = published.Interface().(T)
-	finalizeMetadataPaths(&metadata, final, applications, decoded.baseline, decoded.final)
-	secrets := classifySecretPaths(schema, options.Definition.Secret, metadata, final, applications, decoded.baseline, decoded.final)
-	return &Result[T]{
-		Config:           configuration,
-		metadata:         metadata,
-		sources:          cloneSourceInfos(accumulator.sources),
-		diagnostics:      canonicalDiagnostics(accumulator.diagnostics),
-		baseline:         decoded.baseline,
-		input:            decoded.final,
-		inputOrigins:     cloneOriginIndex(decoded.origins),
-		final:            final,
-		resolution:       resolutionSnapshots,
-		applications:     applications,
-		secrets:          secrets,
-		secretReferences: cloneSecretReferences(secretResolution.references),
-	}, nil
-}
-
-func selectOptions[T any](source Source, supplied []Options[T]) (Options[T], []Diagnostic) {
-	if len(supplied) > 1 {
-		return Options[T]{}, []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "Load accepts at most one options value")}
-	}
-	var options Options[T]
-	if len(supplied) == 1 {
-		options = supplied[0]
-	}
-	var diagnostics []Diagnostic
-	definition := options.Definition
-	if !validProfileName(options.Profile) {
-		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "profile name must contain only ASCII letters, digits, underscore, or hyphen"))
-	}
-	if options.Filesystem != nil {
-		diagnostics = append(diagnostics, filesystemOptionDiagnostics(source, options.Filesystem)...)
-	}
-	if source.kind == sourceNone && options.Imports {
-		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "NoSource cannot enable imports"))
-	}
-	if source.kind == sourceNone && options.Profile != "" && options.Profile != "default" {
-		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "NoSource cannot select an active profile"))
-	}
-	if options.Filesystem == nil && (source.kind == sourceBytes || source.kind == sourceReader) && (options.Imports || activeProfile(options.Profile)) {
-		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "byte and reader imports or profiles require filesystem context"))
-	}
-	if definition.Version != nil {
-		if !definition.Version.Path.valid() {
-			diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "schema-version path is invalid"))
-		}
-		if definition.Version.Check == nil {
-			diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "schema-version rule requires a checker"))
-		}
-	}
-	return options, canonicalDiagnostics(diagnostics)
-}
-
-func optionDiagnostic(code Code, message string) Diagnostic {
-	return Diagnostic{Code: code, Severity: SeverityError, Message: message}
-}
-
-func disabledDirectiveDiagnostics(node *document.Node, path Path) []Diagnostic {
-	var diagnostics []Diagnostic
-	if node.Kind == document.Mapping {
-		for _, entry := range node.Mapping {
-			childPath := path.Key(entry.Key)
-			if entry.Key == "_configkit" {
-				location := Location{SourceID: entry.KeyLocation.SourceID, Line: entry.KeyLocation.Line, Column: entry.KeyLocation.Column}
-				diagnostics = append(diagnostics, Diagnostic{
-					Code: CodeImportDisabled, Severity: SeverityError, Path: childPath,
-					Message: "configuration directives require imports to be enabled", Primary: &location,
-				})
-			}
-			diagnostics = append(diagnostics, disabledDirectiveDiagnostics(entry.Value, childPath)...)
-		}
-	} else if node.Kind == document.Sequence {
-		for index, child := range node.Sequence {
-			diagnostics = append(diagnostics, disabledDirectiveDiagnostics(child, path.Index(index))...)
-		}
-	}
-	return diagnostics
-}
-
-func checkVersion(rule *VersionRule, root *document.Node) []Diagnostic {
-	if rule == nil {
-		return nil
-	}
-	version := Version{}
-	node, present := documentAtPath(root, rule.Path)
-	if present {
-		version.Present = true
-		switch node.Kind {
-		case document.Null:
-			version.Null = true
-		case document.String:
-			version.Text = node.Text
-		default:
-			location, _ := nearestDocumentLocation(root, rule.Path)
-			primary := documentLocationPointer(location)
-			return []Diagnostic{{
-				Code: CodeVersionType, Severity: SeverityError, Path: rule.Path.clone(),
-				Message: "schema version must be a string or null", Primary: primary,
-			}}
-		}
-	}
-	state := &validationState{
-		active: true, errorCode: CodeVersionError, warningCode: CodeVersionWarning,
-		invalidPath: CodeVersionError, document: root,
-	}
-	validation := &Validation{state: state}
-	err := rule.Check(version, validation)
-	state.active = false
-	if err != nil && !hasErrors(state.diagnostics) {
-		location, _ := nearestDocumentLocation(root, rule.Path)
-		state.diagnostics = append(state.diagnostics, Diagnostic{
-			Code: CodeVersionHookFailed, Severity: SeverityError, Path: rule.Path.clone(),
-			Message: "schema-version check failed", Primary: documentLocationPointer(location),
-		})
-	}
-	return canonicalDiagnostics(state.diagnostics)
-}
-
-func documentAtPath(root *document.Node, path Path) (*document.Node, bool) {
-	if root == nil || !path.valid() {
-		return nil, false
-	}
-	current := root
-	for _, segment := range path.segments {
-		switch current.Kind {
-		case document.Mapping:
-			if segment.kind == pathSegmentIndex {
-				return nil, false
-			}
-			found := false
-			for _, entry := range current.Mapping {
-				if entry.Key == segment.key {
-					current = entry.Value
-					found = true
-					break
-				}
-			}
-			if !found {
-				return nil, false
-			}
-		case document.Sequence:
-			index, ok := schemaIndex(segment)
-			if !ok || index >= len(current.Sequence) {
-				return nil, false
-			}
-			current = current.Sequence[index]
-		default:
-			return nil, false
-		}
-	}
-	return current, true
-}
-
-func documentLocationPointer(location document.Location) *Location {
-	if !locationKnown(location) {
-		return nil
-	}
-	return &Location{SourceID: location.SourceID, Line: location.Line, Column: location.Column}
-}
-
-func diagnosticFromSchemaIssue(issue *schemaIssue) Diagnostic {
-	return Diagnostic{Code: issue.code, Severity: SeverityError, Path: issue.path.clone(), Message: issue.message}
-}
-
-func diagnosticFromDecodeIssue(issue decodeIssue) Diagnostic {
-	return Diagnostic{
-		Code: issue.code, Severity: SeverityError, Path: issue.path.clone(), Message: issue.message,
-		Primary: documentLocationPointer(issue.location),
-	}
-}
-
-func hasErrors(diagnostics []Diagnostic) bool {
-	for _, diagnostic := range diagnostics {
-		if diagnostic.Severity == SeverityError {
-			return true
-		}
-	}
-	return false
+	resolved.configuration = configuration
+	// Publication detaches equal-valued validator replacements, preserving the
+	// validated secret state, then finalizes metadata and sensitivity.
+	return publishLoadResult(schema, options.Definition, resolved, secretResolution.references, &accumulator)
 }

load_input.go

@@ -0,0 +1,88 @@
+package configkit
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+// assembledInput is the source/document handoff across schema and version checks.
+type assembledInput struct {
+	parsed      parsedSource
+	document    *document.Node
+	composition *composedDocument
+	sources     []SourceInfo
+}
+
+func assembleBaseInput[T any](source Source, options Options[T]) (assembledInput, []Diagnostic) {
+	parsed, diagnostics := parseSource(source, "source-1", defaultParseLimits())
+	input := assembledInput{parsed: parsed, document: parsed.document}
+	if len(diagnostics) != 0 {
+		input.sources = sourceInfos(parsed.source)
+		return input, diagnostics
+	}
+	if options.Imports {
+		input.composition, input.sources, diagnostics = loadImportedDocuments(source, options.Filesystem, parsed, options.Definition.Version, defaultImportLimits())
+		if len(diagnostics) != 0 {
+			return input, diagnostics
+		}
+		input.document = input.composition.root
+	} else {
+		input.sources = sourceInfos(parsed.source)
+		if options.Filesystem != nil && !activeProfile(options.Profile) {
+			if diagnostic := validateFilesystemContext(source, options.Filesystem, parsed); diagnostic != nil {
+				return input, []Diagnostic{*diagnostic}
+			}
+		}
+	}
+	if !options.Imports && input.document != nil {
+		if diagnostics := disabledDirectiveDiagnostics(input.document, Path{}); len(diagnostics) != 0 {
+			return input, diagnostics
+		}
+	}
+	return input, nil
+}
+
+func applyInputLayers[T any](source Source, options Options[T], input assembledInput) (assembledInput, []Diagnostic) {
+	if !activeProfile(options.Profile) && len(options.Overrides) == 0 {
+		return input, nil
+	}
+	composition, diagnostics := compositionForInput(input)
+	if len(diagnostics) != 0 {
+		return input, diagnostics
+	}
+	if activeProfile(options.Profile) {
+		composition, input.sources, diagnostics = loadProfileDocument(
+			source, options.Filesystem, input.parsed, composition, input.sources,
+			options.Profile, options.Definition.Version, defaultImportLimits(),
+		)
+		if len(diagnostics) != 0 {
+			return input, diagnostics
+		}
+	}
+	if len(options.Overrides) != 0 {
+		composition, input.sources, diagnostics = applyOverrides(
+			composition, input.sources, options.Overrides, options.Definition.Version, defaultImportLimits(),
+		)
+		if len(diagnostics) != 0 {
+			return input, diagnostics
+		}
+	}
+	input.composition = composition
+	input.document = composition.root
+	return input, nil
+}
+
+// compositionForInput initializes one handoff for profiles and CLI, including
+// defaults-only CLI input. Raw source bytes and mapping keys retain their budgets.
+func compositionForInput(input assembledInput) (*composedDocument, []Diagnostic) {
+	if input.composition != nil {
+		return input.composition, nil
+	}
+	if input.document == nil {
+		return &composedDocument{root: &document.Node{Kind: document.Mapping}, origins: make(map[string]Origin)}, nil
+	}
+	composition, diagnostics := composeDocuments(input.document)
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+	composition.inputBytes = input.parsed.bytes
+	composition.inputNodes = countInputNodes(input.document)
+	return composition, nil
+}

load_metadata.go

@@ -159,23 +159,6 @@ func collectFieldInfo(node *document.Node, path Path, decoded decodedConfigurati
 	}
 }
 
-func indexDocument(node *document.Node, path Path, index map[string]*document.Node) {
-	if node == nil {
-		return
-	}
-	index[path.String()] = node
-	switch node.Kind {
-	case document.Mapping:
-		for _, entry := range node.Mapping {
-			indexDocument(entry.Value, path.Key(entry.Key), index)
-		}
-	case document.Sequence:
-		for position, child := range node.Sequence {
-			indexDocument(child, path.Index(position), index)
-		}
-	}
-}
-
 func cloneMetadata(metadata Metadata) Metadata {
 	if metadata.fields == nil && metadata.history == nil {
 		return Metadata{}

load_result.go

@@ -0,0 +1,115 @@
+package configkit
+
+import (
+	"reflect"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+// resolvedLoad carries typed phase outputs needed for validation and publication;
+// it owns no source access, options, or long-lived schema state.
+type resolvedLoad[T any] struct {
+	configuration T
+	decoded       decodedConfiguration
+	metadata      Metadata
+	final         *document.Node
+	snapshots     []resolutionSnapshot
+	applications  []historyApplication
+}
+
+func decodeLoadInput[T any](schema *schemaDescriptor, definition Definition[T], input assembledInput) (decodedConfiguration, []Diagnostic) {
+	defaults := reflect.Zero(reflect.TypeFor[T]())
+	if definition.Defaults != nil {
+		defaults = reflect.ValueOf(definition.Defaults())
+	}
+	decoded, decodeIssues := decodeConfiguration(schema, defaults, input.document)
+	if len(decodeIssues) != 0 {
+		diagnostics := make([]Diagnostic, len(decodeIssues))
+		for i, issue := range decodeIssues {
+			diagnostics[i] = diagnosticFromDecodeIssue(issue)
+		}
+		return decodedConfiguration{}, diagnostics
+	}
+	if input.composition != nil {
+		applyCompositionOrigins(&decoded, input.composition.origins)
+	}
+
+	return decoded, nil
+}
+
+func resolveLoadInput[T any](schema *schemaDescriptor, definition Definition[T], input assembledInput, decoded decodedConfiguration) (resolvedLoad[T], []Diagnostic) {
+	var diagnostics []Diagnostic
+	configuration := decoded.value.Interface().(T)
+	metadata := metadataFromDecoded(decoded)
+	if input.composition != nil {
+		applyOverlayMetadata(&metadata, input.composition.overlays)
+	}
+	final := decoded.final
+	var resolutionSnapshots []resolutionSnapshot
+	if definition.Resolve != nil {
+		resolved := runResolution(&configuration, definition.Resolve, schema, decoded, input.document)
+		diagnostics = append(diagnostics, resolved.diagnostics...)
+		if hasErrors(resolved.diagnostics) {
+			return resolvedLoad[T]{}, diagnostics
+		}
+		final = resolved.final
+		resolutionSnapshots = resolved.snapshots
+		applyResolutionMetadata(&metadata, resolved)
+	}
+	applications := []historyApplication(nil)
+	if input.composition != nil {
+		applications = cloneHistoryApplications(input.composition.applications)
+	} else if input.document != nil {
+		applications = []historyApplication{{layer: LayerBase, value: input.document}}
+	}
+	return resolvedLoad[T]{configuration: configuration, decoded: decoded, metadata: metadata, final: final, snapshots: resolutionSnapshots, applications: applications}, diagnostics
+}
+
+func detachLoadConfiguration[T any](schema *schemaDescriptor, configuration T, mode secretCloneMode) (T, *Diagnostic) {
+	detached, issue := cloneConfigurationWithMode(schema, reflect.ValueOf(configuration), defaultProjectionLimits(), mode)
+	if issue != nil {
+		diagnostic := diagnosticFromDecodeIssue(decodeIssueFromProjection(issue))
+		var zero T
+		return zero, &diagnostic
+	}
+	return detached.Interface().(T), nil
+}
+
+func publishLoadResult[T any](schema *schemaDescriptor, definition Definition[T], resolved resolvedLoad[T], references map[string]string, accumulator *diagnosticAccumulator) (*Result[T], error) {
+	// A read-only validator can replace a value with an equal borrowed object.
+	// Detach without re-reading the environment or discarding validated state.
+	configuration, issue := detachLoadConfiguration(schema, resolved.configuration, cloneValidatedSecrets)
+	if issue != nil {
+		accumulator.add(*issue)
+		return nil, accumulator.loadError()
+	}
+	decoded, metadata := resolved.decoded, resolved.metadata
+	final, applications, resolutionSnapshots := resolved.final, resolved.applications, resolved.snapshots
+	finalizeMetadataPaths(&metadata, final, applications, decoded.baseline, decoded.final)
+	secrets := classifySecretPaths(schema, definition.Secret, metadata, final, applications, decoded.baseline, decoded.final)
+	return &Result[T]{
+		Config:           configuration,
+		metadata:         metadata,
+		sources:          cloneSourceInfos(accumulator.sources),
+		diagnostics:      canonicalDiagnostics(accumulator.diagnostics),
+		baseline:         decoded.baseline,
+		input:            decoded.final,
+		inputOrigins:     cloneOriginIndex(decoded.origins),
+		final:            final,
+		resolution:       resolutionSnapshots,
+		applications:     applications,
+		secrets:          secrets,
+		secretReferences: cloneSecretReferences(references),
+	}, nil
+}
+
+func diagnosticFromSchemaIssue(issue *schemaIssue) Diagnostic {
+	return Diagnostic{Code: issue.code, Severity: SeverityError, Path: issue.path.clone(), Message: issue.message}
+}
+
+func diagnosticFromDecodeIssue(issue decodeIssue) Diagnostic {
+	return Diagnostic{
+		Code: issue.code, Severity: SeverityError, Path: issue.path.clone(), Message: issue.message,
+		Primary: documentLocationPointer(issue.location),
+	}
+}

metadata.go

@@ -85,8 +85,8 @@ func (m Metadata) hasHistoricalPath(path Path) bool {
 func finalizeMetadataPaths(m *Metadata, final *document.Node, applications []historyApplication, earlier ...*document.Node) {
 	m.effectivePaths = make(map[string]Path)
 	m.historicalPaths = make(map[string][]Path)
-	walkDocumentPaths(final, Path{}, func(path Path) { m.effectivePaths[path.String()] = path.clone() })
-	add := func(path Path) {
+	walkDocument(final, Path{}, func(path Path, _ *document.Node) { m.effectivePaths[path.String()] = path.clone() })
+	add := func(path Path, _ *document.Node) {
 		pointer := path.String()
 		for _, prior := range m.historicalPaths[pointer] {
 			if matchesPathShape(path, prior) {
@@ -95,9 +95,9 @@ func finalizeMetadataPaths(m *Metadata, final *document.Node, applications []his
 		}
 		m.historicalPaths[pointer] = append(m.historicalPaths[pointer], path.clone())
 	}
-	walkDocumentPaths(final, Path{}, add)
+	walkDocument(final, Path{}, add)
 	for _, tree := range earlier {
-		walkDocumentPaths(tree, Path{}, add)
+		walkDocument(tree, Path{}, add)
 	}
 	for _, application := range applications {
 		// Overrides have mapping-only prefixes; parsed tokens are keys in this layer.
@@ -105,19 +105,6 @@ func finalizeMetadataPaths(m *Metadata, final *document.Node, applications []his
 		for _, segment := range application.path.segments {
 			prefix = prefix.Key(segment.key)
 		}
-		walkDocumentPaths(application.value, prefix, add)
-	}
-}
-
-func walkDocumentPaths(node *document.Node, path Path, visit func(Path)) {
-	if node == nil {
-		return
-	}
-	visit(path)
-	for _, entry := range node.Mapping {
-		walkDocumentPaths(entry.Value, path.Key(entry.Key), visit)
-	}
-	for i, child := range node.Sequence {
-		walkDocumentPaths(child, path.Index(i), visit)
+		walkDocument(application.value, prefix, add)
 	}
 }

options.go

@@ -0,0 +1,41 @@
+package configkit
+
+func selectOptions[T any](source Source, supplied []Options[T]) (Options[T], []Diagnostic) {
+	if len(supplied) > 1 {
+		return Options[T]{}, []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "Load accepts at most one options value")}
+	}
+	var options Options[T]
+	if len(supplied) == 1 {
+		options = supplied[0]
+	}
+	var diagnostics []Diagnostic
+	definition := options.Definition
+	if !validProfileName(options.Profile) {
+		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "profile name must contain only ASCII letters, digits, underscore, or hyphen"))
+	}
+	if options.Filesystem != nil {
+		diagnostics = append(diagnostics, filesystemOptionDiagnostics(source, options.Filesystem)...)
+	}
+	if source.kind == sourceNone && options.Imports {
+		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "NoSource cannot enable imports"))
+	}
+	if source.kind == sourceNone && options.Profile != "" && options.Profile != "default" {
+		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "NoSource cannot select an active profile"))
+	}
+	if options.Filesystem == nil && (source.kind == sourceBytes || source.kind == sourceReader) && (options.Imports || activeProfile(options.Profile)) {
+		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "byte and reader imports or profiles require filesystem context"))
+	}
+	if definition.Version != nil {
+		if !definition.Version.Path.valid() {
+			diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "schema-version path is invalid"))
+		}
+		if definition.Version.Check == nil {
+			diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "schema-version rule requires a checker"))
+		}
+	}
+	return options, canonicalDiagnostics(diagnostics)
+}
+
+func optionDiagnostic(code Code, message string) Diagnostic {
+	return Diagnostic{Code: code, Severity: SeverityError, Message: message}
+}

overlay.go

@@ -10,8 +10,6 @@ import (
 type overlayRecord struct {
 	change    Change
 	displaced []displacedDefinition
-	before    *document.Node
-	after     *document.Node
 }
 
 type displacedDefinition struct {
@@ -26,15 +24,7 @@ func overlayDocuments(base *composedDocument, overlay *document.Node) (*composed
 			Message: "profile overlay requires mapping document roots",
 		}}
 	}
-	result := &composedDocument{
-		root:         document.Clone(base.root),
-		claims:       cloneCompositionClaims(base.claims),
-		origins:      cloneOriginIndex(base.origins),
-		overlays:     cloneOverlayRecords(base.overlays),
-		applications: cloneHistoryApplications(base.applications),
-		inputBytes:   base.inputBytes,
-		inputNodes:   base.inputNodes,
-	}
+	result := cloneComposedDocument(base)
 	mergeOverlayOrigin(result.origins, Path{}, overlay.Location, LayerProfile)
 	mergeOverlayMappings(result, result.root, overlay, Path{}, LayerProfile, true)
 	result.applications = append(result.applications, historyApplication{layer: LayerProfile, value: overlay})
@@ -73,7 +63,6 @@ func mergeOverlayMappings(result *composedDocument, target, overlay *document.No
 					Previous: previousOrigins(previous),
 				},
 				displaced: displaced,
-				before:    document.Clone(existing), after: document.Clone(incoming.Value),
 			})
 		}
 	}
@@ -161,8 +150,6 @@ func cloneOverlayRecords(records []overlayRecord) []overlayRecord {
 	cloned := make([]overlayRecord, len(records))
 	for index, record := range records {
 		cloned[index].change = cloneChange(record.change)
-		cloned[index].before = document.Clone(record.before)
-		cloned[index].after = document.Clone(record.after)
 		cloned[index].displaced = make([]displacedDefinition, len(record.displaced))
 		for displacedIndex, displaced := range record.displaced {
 			cloned[index].displaced[displacedIndex] = displacedDefinition{

override.go

@@ -1,9 +1,6 @@
 package configkit
 
 import (
-	"math"
-	"reflect"
-	"slices"
 	"strconv"
 	"strings"
 	"unicode"
@@ -22,17 +19,7 @@ type preparedOverride struct {
 	nodes  int
 }
 
-type overrideValueBuilder struct {
-	sourceID string
-	active   map[valueVisit]bool
-	bytes    int64
-	nodes    int
-}
-
-func applyOverrides(base *composedDocument, sources []SourceInfo, overrides []Override, rule *VersionRule, limits importLimits) (*composedDocument, []SourceInfo, []Diagnostic) {
-	if len(overrides) == 0 {
-		return base, cloneSourceInfos(sources), nil
-	}
+func prepareOverrides(base *composedDocument, sources []SourceInfo, overrides []Override, rule *VersionRule, limits importLimits) ([]preparedOverride, []SourceInfo, []Diagnostic) {
 	if len(overrides) > maxOverrides || len(sources)+len(overrides) > limits.sources {
 		return nil, cloneSourceInfos(sources), []Diagnostic{{
 			Code: CodeOverrideLimitExceeded, Severity: SeverityError,
@@ -147,13 +134,7 @@ func applyOverrides(base *composedDocument, sources []SourceInfo, overrides []Ov
 		return nil, allSources, canonicalDiagnostics(diagnostics)
 	}
 
-	result := cloneComposedDocument(base)
-	for _, override := range prepared {
-		applyPreparedOverride(result, override)
-	}
-	result.inputBytes += usedBytes
-	result.inputNodes += usedNodes
-	return result, allSources, nil
+	return prepared, allSources, nil
 }
 
 func validOverrideLabel(label string) bool {
@@ -240,223 +221,3 @@ func overrideDirectivePath(node *document.Node, path Path) (Path, bool) {
 	}
 	return Path{}, false
 }
-
-func (b *overrideValueBuilder) build(value any, path Path, depth int) (*document.Node, *Diagnostic) {
-	if depth > maxDocumentDepth {
-		return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the depth limit")
-	}
-	b.nodes++
-	if b.nodes > maxDocumentNodes {
-		return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the node limit")
-	}
-	location := document.Location{SourceID: b.sourceID}
-	switch value := value.(type) {
-	case nil:
-		return &document.Node{Kind: document.Null, Location: location}, nil
-	case string:
-		if !b.addBytes(len(value)) {
-			return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the record string-byte limit")
-		}
-		return &document.Node{Kind: document.String, Text: value, Location: location}, nil
-	case bool:
-		return &document.Node{Kind: document.Boolean, Text: strconv.FormatBool(value), Location: location}, nil
-	case int:
-		return overrideNumber(strconv.FormatInt(int64(value), 10), location), nil
-	case int8:
-		return overrideNumber(strconv.FormatInt(int64(value), 10), location), nil
-	case int16:
-		return overrideNumber(strconv.FormatInt(int64(value), 10), location), nil
-	case int32:
-		return overrideNumber(strconv.FormatInt(int64(value), 10), location), nil
-	case int64:
-		return overrideNumber(strconv.FormatInt(value, 10), location), nil
-	case uint:
-		return overrideNumber(strconv.FormatUint(uint64(value), 10), location), nil
-	case uint8:
-		return overrideNumber(strconv.FormatUint(uint64(value), 10), location), nil
-	case uint16:
-		return overrideNumber(strconv.FormatUint(uint64(value), 10), location), nil
-	case uint32:
-		return overrideNumber(strconv.FormatUint(uint64(value), 10), location), nil
-	case uint64:
-		return overrideNumber(strconv.FormatUint(value, 10), location), nil
-	case float32:
-		if math.IsNaN(float64(value)) || math.IsInf(float64(value), 0) {
-			return nil, overrideValueDiagnostic(CodeOverrideInvalidValue, path, "configuration override float must be finite")
-		}
-		return overrideNumber(strconv.FormatFloat(float64(value), 'g', -1, 32), location), nil
-	case float64:
-		if math.IsNaN(value) || math.IsInf(value, 0) {
-			return nil, overrideValueDiagnostic(CodeOverrideInvalidValue, path, "configuration override float must be finite")
-		}
-		return overrideNumber(strconv.FormatFloat(value, 'g', -1, 64), location), nil
-	case []any:
-		if value == nil {
-			return &document.Node{Kind: document.Null, Location: location}, nil
-		}
-		leave, diagnostic := b.enter(reflect.ValueOf(value), path)
-		if diagnostic != nil {
-			return nil, diagnostic
-		}
-		defer leave()
-		if len(value) > maxDocumentNodes-b.nodes {
-			return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the node limit")
-		}
-		node := &document.Node{Kind: document.Sequence, Location: location, Sequence: make([]*document.Node, len(value))}
-		for index, child := range value {
-			built, diagnostic := b.build(child, path.Index(index), depth+1)
-			if diagnostic != nil {
-				return nil, diagnostic
-			}
-			node.Sequence[index] = built
-		}
-		return node, nil
-	case map[string]any:
-		if value == nil {
-			return &document.Node{Kind: document.Null, Location: location}, nil
-		}
-		leave, diagnostic := b.enter(reflect.ValueOf(value), path)
-		if diagnostic != nil {
-			return nil, diagnostic
-		}
-		defer leave()
-		if len(value) > (maxDocumentNodes-b.nodes)/2 {
-			return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the node limit")
-		}
-		keys := make([]string, 0, len(value))
-		for key := range value {
-			keys = append(keys, key)
-		}
-		slices.Sort(keys)
-		node := &document.Node{Kind: document.Mapping, Location: location, Mapping: make([]document.Entry, 0, len(keys))}
-		for _, key := range keys {
-			b.nodes++ // mapping key
-			if !b.addBytes(len(key)) {
-				return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path.Key(key), "configuration override exceeds the record string-byte limit")
-			}
-			built, diagnostic := b.build(value[key], path.Key(key), depth+1)
-			if diagnostic != nil {
-				return nil, diagnostic
-			}
-			node.Mapping = append(node.Mapping, document.Entry{Key: key, KeyLocation: location, ValueLocation: location, Value: built})
-		}
-		return node, nil
-	default:
-		return nil, overrideValueDiagnostic(CodeOverrideInvalidValue, path, "configuration override value has an unsupported type")
-	}
-}
-
-func (b *overrideValueBuilder) addBytes(count int) bool {
-	if count < 0 || int64(count) > maxSourceBytes-b.bytes {
-		return false
-	}
-	b.bytes += int64(count)
-	return true
-}
-
-func (b *overrideValueBuilder) enter(value reflect.Value, path Path) (func(), *Diagnostic) {
-	visit, ok := visitFor(value)
-	if !ok {
-		return func() {}, nil
-	}
-	if b.active[visit] {
-		return nil, overrideValueDiagnostic(CodeOverrideInvalidValue, path, "configuration override values must not contain cycles")
-	}
-	b.active[visit] = true
-	return func() { delete(b.active, visit) }, nil
-}
-
-func overrideValueDiagnostic(code Code, path Path, message string) *Diagnostic {
-	return &Diagnostic{Code: code, Severity: SeverityError, Path: path.clone(), Message: message}
-}
-
-func overrideNumber(text string, location document.Location) *document.Node {
-	return &document.Node{Kind: document.Number, Text: text, Location: location}
-}
-
-func cloneComposedDocument(base *composedDocument) *composedDocument {
-	return &composedDocument{
-		root: document.Clone(base.root), claims: cloneCompositionClaims(base.claims),
-		origins: cloneOriginIndex(base.origins), overlays: cloneOverlayRecords(base.overlays),
-		applications: cloneHistoryApplications(base.applications),
-		inputBytes:   base.inputBytes, inputNodes: base.inputNodes,
-	}
-}
-
-func applyPreparedOverride(result *composedDocument, override preparedOverride) {
-	location := document.Location{SourceID: override.source.ID}
-	mergeOverlayOrigin(result.origins, Path{}, location, LayerCLI)
-	current := result.root
-	currentPath := Path{}
-	for index, segment := range override.path.segments {
-		path := currentPath.Key(segment.key)
-		position := documentEntryIndex(current.Mapping, segment.key)
-		if index < len(override.path.segments)-1 {
-			if position < 0 {
-				child := &document.Node{Kind: document.Mapping, Location: location, Mapping: []document.Entry{}}
-				current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, KeyLocation: location, ValueLocation: location, Value: child})
-				collectOverlayOrigins(result.origins, child, path, LayerCLI)
-				current = child
-			} else {
-				current = current.Mapping[position].Value
-				mergeOverlayOrigin(result.origins, path, location, LayerCLI)
-			}
-			currentPath = path
-			continue
-		}
-
-		previous := cloneOrigin(result.origins[path.String()])
-		var displaced []displacedDefinition
-		var before *document.Node
-		if position < 0 {
-			incoming := document.Clone(override.value)
-			current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, KeyLocation: location, ValueLocation: location, Value: incoming})
-			collectOverlayOrigins(result.origins, incoming, path, LayerCLI)
-		} else {
-			existing := current.Mapping[position].Value
-			before = document.Clone(existing)
-			displaced = affectedOverrideOrigins(existing, override.value, result.origins, path)
-			if existing.Kind == document.Mapping && override.value.Kind == document.Mapping {
-				mergeOverlayOrigin(result.origins, path, location, LayerCLI)
-				mergeOverlayMappings(result, existing, override.value, path, LayerCLI, false)
-			} else {
-				deleteOriginSubtree(result.origins, path)
-				current.Mapping[position] = document.Entry{Key: segment.key, KeyLocation: location, ValueLocation: location, Value: document.Clone(override.value)}
-				collectOverlayOrigins(result.origins, current.Mapping[position].Value, path, LayerCLI)
-			}
-		}
-		position = documentEntryIndex(current.Mapping, segment.key)
-		result.overlays = append(result.overlays, overlayRecord{change: Change{
-			Path: path.clone(), Origin: overlayOrigin(LayerCLI, location), Previous: previousOrigins(previous),
-		}, displaced: displaced, before: before, after: document.Clone(current.Mapping[position].Value)})
-		result.applications = append(result.applications, historyApplication{
-			layer: LayerCLI, path: path.clone(), value: override.value,
-			origin: overlayOrigin(LayerCLI, location),
-		})
-	}
-}
-
-func affectedOverrideOrigins(existing, incoming *document.Node, origins map[string]Origin, path Path) []displacedDefinition {
-	displaced := []displacedDefinition{{path: path.clone(), origin: cloneOrigin(origins[path.String()])}}
-	if existing.Kind == document.Mapping && incoming.Kind == document.Mapping {
-		for _, entry := range incoming.Mapping {
-			position := documentEntryIndex(existing.Mapping, entry.Key)
-			if position < 0 {
-				continue
-			}
-			childPath := path.Key(entry.Key)
-			childExisting := existing.Mapping[position].Value
-			if childExisting.Kind == document.Mapping && entry.Value.Kind == document.Mapping {
-				displaced = append(displaced, affectedOverrideOrigins(childExisting, entry.Value, origins, childPath)...)
-			} else {
-				displaced = append(displaced, displacedOrigins(childExisting, origins, childPath)...)
-			}
-		}
-	} else {
-		displaced = displacedOrigins(existing, origins, path)
-	}
-	slices.SortFunc(displaced, func(left, right displacedDefinition) int {
-		return strings.Compare(left.path.String(), right.path.String())
-	})
-	return displaced
-}

override_apply.go

@@ -0,0 +1,100 @@
+package configkit
+
+import (
+	"slices"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func applyOverrides(base *composedDocument, sources []SourceInfo, overrides []Override, rule *VersionRule, limits importLimits) (*composedDocument, []SourceInfo, []Diagnostic) {
+	if len(overrides) == 0 {
+		return base, cloneSourceInfos(sources), nil
+	}
+	prepared, allSources, diagnostics := prepareOverrides(base, sources, overrides, rule, limits)
+	if len(diagnostics) != 0 {
+		return nil, allSources, diagnostics
+	}
+	result := cloneComposedDocument(base)
+	for _, override := range prepared {
+		applyPreparedOverride(result, override)
+		result.inputBytes += override.bytes
+		result.inputNodes += override.nodes
+	}
+	return result, allSources, nil
+}
+
+func applyPreparedOverride(result *composedDocument, override preparedOverride) {
+	location := document.Location{SourceID: override.source.ID}
+	mergeOverlayOrigin(result.origins, Path{}, location, LayerCLI)
+	current := result.root
+	currentPath := Path{}
+	for index, segment := range override.path.segments {
+		path := currentPath.Key(segment.key)
+		position := documentEntryIndex(current.Mapping, segment.key)
+		if index < len(override.path.segments)-1 {
+			if position < 0 {
+				child := &document.Node{Kind: document.Mapping, Location: location, Mapping: []document.Entry{}}
+				current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, KeyLocation: location, ValueLocation: location, Value: child})
+				collectOverlayOrigins(result.origins, child, path, LayerCLI)
+				current = child
+			} else {
+				current = current.Mapping[position].Value
+				mergeOverlayOrigin(result.origins, path, location, LayerCLI)
+			}
+			currentPath = path
+			continue
+		}
+
+		previous := cloneOrigin(result.origins[path.String()])
+		var displaced []displacedDefinition
+		if position < 0 {
+			incoming := document.Clone(override.value)
+			current.Mapping = append(current.Mapping, document.Entry{Key: segment.key, KeyLocation: location, ValueLocation: location, Value: incoming})
+			collectOverlayOrigins(result.origins, incoming, path, LayerCLI)
+		} else {
+			existing := current.Mapping[position].Value
+			displaced = affectedOverrideOrigins(existing, override.value, result.origins, path)
+			if existing.Kind == document.Mapping && override.value.Kind == document.Mapping {
+				mergeOverlayOrigin(result.origins, path, location, LayerCLI)
+				mergeOverlayMappings(result, existing, override.value, path, LayerCLI, false)
+			} else {
+				deleteOriginSubtree(result.origins, path)
+				current.Mapping[position] = document.Entry{Key: segment.key, KeyLocation: location, ValueLocation: location, Value: document.Clone(override.value)}
+				collectOverlayOrigins(result.origins, current.Mapping[position].Value, path, LayerCLI)
+			}
+		}
+		result.overlays = append(result.overlays, overlayRecord{change: Change{
+			Path: path.clone(), Origin: overlayOrigin(LayerCLI, location), Previous: previousOrigins(previous),
+		}, displaced: displaced})
+		result.applications = append(result.applications, historyApplication{
+			layer: LayerCLI, path: path.clone(), value: override.value,
+			origin: overlayOrigin(LayerCLI, location),
+		})
+	}
+}
+
+func affectedOverrideOrigins(existing, incoming *document.Node, origins map[string]Origin, path Path) []displacedDefinition {
+	displaced := []displacedDefinition{{path: path.clone(), origin: cloneOrigin(origins[path.String()])}}
+	if existing.Kind == document.Mapping && incoming.Kind == document.Mapping {
+		for _, entry := range incoming.Mapping {
+			position := documentEntryIndex(existing.Mapping, entry.Key)
+			if position < 0 {
+				continue
+			}
+			childPath := path.Key(entry.Key)
+			childExisting := existing.Mapping[position].Value
+			if childExisting.Kind == document.Mapping && entry.Value.Kind == document.Mapping {
+				displaced = append(displaced, affectedOverrideOrigins(childExisting, entry.Value, origins, childPath)...)
+			} else {
+				displaced = append(displaced, displacedOrigins(childExisting, origins, childPath)...)
+			}
+		}
+	} else {
+		displaced = displacedOrigins(existing, origins, path)
+	}
+	slices.SortFunc(displaced, func(left, right displacedDefinition) int {
+		return strings.Compare(left.path.String(), right.path.String())
+	})
+	return displaced
+}

override_value.go

@@ -0,0 +1,150 @@
+package configkit
+
+import (
+	"math"
+	"reflect"
+	"slices"
+	"strconv"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+type overrideValueBuilder struct {
+	sourceID string
+	active   map[valueVisit]bool
+	bytes    int64
+	nodes    int
+}
+
+func (b *overrideValueBuilder) build(value any, path Path, depth int) (*document.Node, *Diagnostic) {
+	if depth > maxDocumentDepth {
+		return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the depth limit")
+	}
+	b.nodes++
+	if b.nodes > maxDocumentNodes {
+		return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the node limit")
+	}
+	location := document.Location{SourceID: b.sourceID}
+	switch value := value.(type) {
+	case nil:
+		return &document.Node{Kind: document.Null, Location: location}, nil
+	case string:
+		if !b.addBytes(len(value)) {
+			return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the record string-byte limit")
+		}
+		return &document.Node{Kind: document.String, Text: value, Location: location}, nil
+	case bool:
+		return &document.Node{Kind: document.Boolean, Text: strconv.FormatBool(value), Location: location}, nil
+	case int:
+		return overrideNumber(strconv.FormatInt(int64(value), 10), location), nil
+	case int8:
+		return overrideNumber(strconv.FormatInt(int64(value), 10), location), nil
+	case int16:
+		return overrideNumber(strconv.FormatInt(int64(value), 10), location), nil
+	case int32:
+		return overrideNumber(strconv.FormatInt(int64(value), 10), location), nil
+	case int64:
+		return overrideNumber(strconv.FormatInt(value, 10), location), nil
+	case uint:
+		return overrideNumber(strconv.FormatUint(uint64(value), 10), location), nil
+	case uint8:
+		return overrideNumber(strconv.FormatUint(uint64(value), 10), location), nil
+	case uint16:
+		return overrideNumber(strconv.FormatUint(uint64(value), 10), location), nil
+	case uint32:
+		return overrideNumber(strconv.FormatUint(uint64(value), 10), location), nil
+	case uint64:
+		return overrideNumber(strconv.FormatUint(value, 10), location), nil
+	case float32:
+		if math.IsNaN(float64(value)) || math.IsInf(float64(value), 0) {
+			return nil, overrideValueDiagnostic(CodeOverrideInvalidValue, path, "configuration override float must be finite")
+		}
+		return overrideNumber(strconv.FormatFloat(float64(value), 'g', -1, 32), location), nil
+	case float64:
+		if math.IsNaN(value) || math.IsInf(value, 0) {
+			return nil, overrideValueDiagnostic(CodeOverrideInvalidValue, path, "configuration override float must be finite")
+		}
+		return overrideNumber(strconv.FormatFloat(value, 'g', -1, 64), location), nil
+	case []any:
+		if value == nil {
+			return &document.Node{Kind: document.Null, Location: location}, nil
+		}
+		leave, diagnostic := b.enter(reflect.ValueOf(value), path)
+		if diagnostic != nil {
+			return nil, diagnostic
+		}
+		defer leave()
+		if len(value) > maxDocumentNodes-b.nodes {
+			return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the node limit")
+		}
+		node := &document.Node{Kind: document.Sequence, Location: location, Sequence: make([]*document.Node, len(value))}
+		for index, child := range value {
+			built, diagnostic := b.build(child, path.Index(index), depth+1)
+			if diagnostic != nil {
+				return nil, diagnostic
+			}
+			node.Sequence[index] = built
+		}
+		return node, nil
+	case map[string]any:
+		if value == nil {
+			return &document.Node{Kind: document.Null, Location: location}, nil
+		}
+		leave, diagnostic := b.enter(reflect.ValueOf(value), path)
+		if diagnostic != nil {
+			return nil, diagnostic
+		}
+		defer leave()
+		if len(value) > (maxDocumentNodes-b.nodes)/2 {
+			return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path, "configuration override exceeds the node limit")
+		}
+		keys := make([]string, 0, len(value))
+		for key := range value {
+			keys = append(keys, key)
+		}
+		slices.Sort(keys)
+		node := &document.Node{Kind: document.Mapping, Location: location, Mapping: make([]document.Entry, 0, len(keys))}
+		for _, key := range keys {
+			b.nodes++ // mapping key
+			if !b.addBytes(len(key)) {
+				return nil, overrideValueDiagnostic(CodeOverrideLimitExceeded, path.Key(key), "configuration override exceeds the record string-byte limit")
+			}
+			built, diagnostic := b.build(value[key], path.Key(key), depth+1)
+			if diagnostic != nil {
+				return nil, diagnostic
+			}
+			node.Mapping = append(node.Mapping, document.Entry{Key: key, KeyLocation: location, ValueLocation: location, Value: built})
+		}
+		return node, nil
+	default:
+		return nil, overrideValueDiagnostic(CodeOverrideInvalidValue, path, "configuration override value has an unsupported type")
+	}
+}
+
+func (b *overrideValueBuilder) addBytes(count int) bool {
+	if count < 0 || int64(count) > maxSourceBytes-b.bytes {
+		return false
+	}
+	b.bytes += int64(count)
+	return true
+}
+
+func (b *overrideValueBuilder) enter(value reflect.Value, path Path) (func(), *Diagnostic) {
+	visit, ok := visitFor(value)
+	if !ok {
+		return func() {}, nil
+	}
+	if b.active[visit] {
+		return nil, overrideValueDiagnostic(CodeOverrideInvalidValue, path, "configuration override values must not contain cycles")
+	}
+	b.active[visit] = true
+	return func() { delete(b.active, visit) }, nil
+}
+
+func overrideValueDiagnostic(code Code, path Path, message string) *Diagnostic {
+	return &Diagnostic{Code: code, Severity: SeverityError, Path: path.clone(), Message: message}
+}
+
+func overrideNumber(text string, location document.Location) *document.Node {
+	return &document.Node{Kind: document.Number, Text: text, Location: location}
+}

parse.go

@@ -33,6 +33,21 @@ type parsedSource struct {
 	bytes    int64
 }
 
+// parserDiagnostics translates adapter issues into detached, ordered public records.
+func parserDiagnostics(sourceID string, issues []yamladapter.Issue) []Diagnostic {
+	diagnostics := make([]Diagnostic, len(issues))
+	for index, issue := range issues {
+		diagnostics[index] = Diagnostic{
+			Code: Code(issue.Code), Severity: SeverityError, Message: issue.Message,
+			Primary: &Location{SourceID: sourceID, Line: issue.Line, Column: issue.Column},
+		}
+		for _, related := range issue.Related {
+			diagnostics[index].Related = append(diagnostics[index].Related, publicLocation(related))
+		}
+	}
+	return canonicalDiagnostics(diagnostics)
+}
+
 func parseSource(source Source, sourceID string, limits parseLimits) (parsedSource, []Diagnostic) {
 	read, diagnostics := readSource(source, sourceID, limits.source)
 	if len(diagnostics) != 0 || read.info == nil {
@@ -41,27 +56,7 @@ func parseSource(source Source, sourceID string, limits parseLimits) (parsedSour
 
 	root, issues := yamladapter.Parse(bytes.NewReader(read.data), sourceID, limits.document)
 	if len(issues) != 0 {
-		diagnostics := make([]Diagnostic, len(issues))
-		for i, issue := range issues {
-			diagnostics[i] = Diagnostic{
-				Code:     Code(issue.Code),
-				Severity: SeverityError,
-				Message:  issue.Message,
-				Primary: &Location{
-					SourceID: sourceID,
-					Line:     issue.Line,
-					Column:   issue.Column,
-				},
-			}
-			for _, related := range issue.Related {
-				diagnostics[i].Related = append(diagnostics[i].Related, Location{
-					SourceID: related.SourceID,
-					Line:     related.Line,
-					Column:   related.Column,
-				})
-			}
-		}
-		return parsedSource{source: read.info, bytes: int64(len(read.data))}, canonicalDiagnostics(diagnostics)
+		return parsedSource{source: read.info, bytes: int64(len(read.data))}, parserDiagnostics(sourceID, issues)
 	}
 	return parsedSource{document: root, source: read.info, bytes: int64(len(read.data))}, nil
 }

profile.go

@@ -3,14 +3,12 @@ package configkit
 import (
 	"bytes"
 	"errors"
-	"io"
 	"io/fs"
 	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
 
-	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
 	yamladapter "gitea.maximumdirect.net/eric/ConfigKit/internal/yaml"
 )
 
@@ -68,9 +66,14 @@ func loadProfileDocument(source Source, context *FilesystemContext, main parsedS
 		value.Primary = nil
 		return nil, cloneSourceInfos(sources), []Diagnostic{value}
 	}
+	rootClosed := false
+	defer func() {
+		if !rootClosed {
+			_ = root.Close()
+		}
+	}()
 	relative, err := filepath.Rel(rootPath, canonical)
 	if err != nil || filepath.IsAbs(relative) || relative == ".." || strings.HasPrefix(relative, ".."+string(filepath.Separator)) {
-		_ = root.Close()
 		return nil, cloneSourceInfos(sources), []Diagnostic{importDiagnostic(CodeProfileOutsideRoot, "selected profile could not be addressed inside the configuration root", nil)}
 	}
 
@@ -80,32 +83,29 @@ func loadProfileDocument(source Source, context *FilesystemContext, main parsedS
 	sources = append(cloneSourceInfos(sources), profileSource)
 	data, diagnostic := readProfileFile(root, relative, sourceID, limits.bytes-base.inputBytes)
 	if diagnostic != nil {
-		_ = root.Close()
 		return nil, sources, []Diagnostic{*diagnostic}
 	}
 	profileRoot, issues := yamladapter.Parse(bytes.NewReader(data), sourceID, yamladapter.Limits{Depth: maxDocumentDepth, Nodes: maxDocumentNodes})
 	if len(issues) != 0 {
-		_ = root.Close()
-		return nil, sources, importParseDiagnostics(sourceID, issues)
+		return nil, sources, parserDiagnostics(sourceID, issues)
 	}
 	nodeCount := countInputNodes(profileRoot)
 	if base.inputNodes+nodeCount > limits.nodes {
-		_ = root.Close()
 		return nil, sources, []Diagnostic{importDiagnostic(CodeProfileLimitExceeded, "selected profile exceeds the aggregate node limit", profileLocation)}
 	}
 	if diagnostics := profileDirectiveDiagnostics(profileRoot, Path{}); len(diagnostics) != 0 {
-		_ = root.Close()
 		return nil, sources, diagnostics
 	}
 	if versionNode := fragmentVersionClaim(profileRoot, rule); versionNode != nil {
 		location := publicLocation(versionNode.Location)
-		_ = root.Close()
 		return nil, sources, []Diagnostic{{
 			Code: CodeProfileVersion, Severity: SeverityError, Path: rule.Path.clone(),
 			Message: "profiles cannot contribute to or replace the schema-version path", Primary: &location,
 		}}
 	}
-	if err := root.Close(); err != nil {
+	closeErr := root.Close()
+	rootClosed = true
+	if closeErr != nil {
 		return nil, sources, []Diagnostic{importDiagnostic(CodeImportRead, "configuration root could not be closed after reading the selected profile", nil)}
 	}
 
@@ -122,67 +122,10 @@ func readProfileFile(root *os.Root, relative, sourceID string, remaining int64)
 	if limit < 0 {
 		limit = 0
 	}
-	preflight, err := root.Stat(relative)
-	if err != nil {
-		value := classifySourceError(err, sourceID)
-		return nil, &value
-	}
-	if !preflight.Mode().IsRegular() {
-		value := sourceDiagnostic(CodeSourceNotRegular, sourceID, "source is not a regular file")
-		return nil, &value
-	}
-	file, err := root.Open(relative)
-	if err != nil {
-		value := classifySourceError(err, sourceID)
-		return nil, &value
-	}
-	defer func() { _ = file.Close() }()
-	info, err := file.Stat()
-	if err != nil {
-		value := classifySourceError(err, sourceID)
-		return nil, &value
-	}
-	if !info.Mode().IsRegular() {
-		value := sourceDiagnostic(CodeSourceNotRegular, sourceID, "source is not a regular file")
-		return nil, &value
-	}
-	if info.Size() > limit {
-		value := importDiagnostic(CodeProfileLimitExceeded, "selected profile exceeds a source or aggregate byte limit", &Location{SourceID: sourceID})
-		return nil, &value
-	}
-	data, err := io.ReadAll(io.LimitReader(file, limit+1))
-	if err != nil {
-		value := classifySourceError(err, sourceID)
-		return nil, &value
-	}
-	if int64(len(data)) > limit {
-		value := importDiagnostic(CodeProfileLimitExceeded, "selected profile exceeds a source or aggregate byte limit", &Location{SourceID: sourceID})
+	data, failure := readRegularFile(relative, root.Stat, root.Open, limit)
+	if failure != nil {
+		value := sourceReadDiagnostic(failure, sourceID, CodeProfileLimitExceeded, "selected profile exceeds a source or aggregate byte limit")
 		return nil, &value
 	}
 	return data, nil
 }
-
-func profileDirectiveDiagnostics(node *document.Node, current Path) []Diagnostic {
-	if node.Kind == document.Mapping {
-		for _, entry := range node.Mapping {
-			childPath := current.Key(entry.Key)
-			if entry.Key == "_configkit" {
-				location := publicLocation(entry.KeyLocation)
-				return []Diagnostic{{
-					Code: CodeProfileDirective, Severity: SeverityError, Path: childPath,
-					Message: "profiles cannot contain configuration directives", Primary: &location,
-				}}
-			}
-			if diagnostics := profileDirectiveDiagnostics(entry.Value, childPath); len(diagnostics) != 0 {
-				return diagnostics
-			}
-		}
-	} else if node.Kind == document.Sequence {
-		for index, child := range node.Sequence {
-			if diagnostics := profileDirectiveDiagnostics(child, current.Index(index)); len(diagnostics) != 0 {
-				return diagnostics
-			}
-		}
-	}
-	return nil
-}

projection.go

@@ -1,6 +1,7 @@
 package configkit
 
 import (
+	"cmp"
 	"encoding"
 	"math"
 	"reflect"
@@ -12,35 +13,6 @@ import (
 	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
 )
 
-type projectionLimits struct {
-	depth int
-	nodes int
-}
-
-func defaultProjectionLimits() projectionLimits {
-	return projectionLimits{depth: maxDocumentDepth, nodes: maxDocumentNodes}
-}
-
-type projectionIssue struct {
-	code    Code
-	path    Path
-	message string
-}
-
-type valueVisit struct {
-	typeOf reflect.Type
-	kind   reflect.Kind
-	ptr    uintptr
-}
-
-type valueOperation struct {
-	preserveSecrets bool
-	schema          *schemaDescriptor
-	limits          projectionLimits
-	active          map[valueVisit]bool
-	nodes           int
-}
-
 func projectConfiguration(schema *schemaDescriptor, value reflect.Value, limits projectionLimits) (*document.Node, *projectionIssue) {
 	if schema == nil || schema.root == nil || !value.IsValid() || value.Type() != schema.root.typeOf {
 		return nil, &projectionIssue{code: CodeSchemaUnsupportedType, message: "configuration value does not match its schema"}
@@ -49,19 +21,6 @@ func projectConfiguration(schema *schemaDescriptor, value reflect.Value, limits
 	return operation.project(value, schema.root, Path{}, 0)
 }
 
-func cloneConfiguration(schema *schemaDescriptor, value reflect.Value, limits projectionLimits) (reflect.Value, *projectionIssue) {
-	return cloneConfigurationState(schema, value, limits, false)
-}
-
-// Publication copies preserve only already-validated private reference state.
-func cloneConfigurationState(schema *schemaDescriptor, value reflect.Value, limits projectionLimits, preserveSecrets bool) (reflect.Value, *projectionIssue) {
-	if schema == nil || schema.root == nil || !value.IsValid() || value.Type() != schema.root.typeOf {
-		return reflect.Value{}, &projectionIssue{code: CodeSchemaUnsupportedType, message: "configuration value does not match its schema"}
-	}
-	operation := valueOperation{schema: schema, limits: limits, active: make(map[valueVisit]bool), preserveSecrets: preserveSecrets}
-	return operation.clone(value, schema.root, Path{}, 0)
-}
-
 func (o *valueOperation) project(value reflect.Value, descriptor *typeDescriptor, path Path, depth int) (*document.Node, *projectionIssue) {
 	if issue := o.checkDepth(path, depth); issue != nil {
 		return nil, issue
@@ -149,7 +108,7 @@ func (o *valueOperation) project(value reflect.Value, descriptor *typeDescriptor
 		result.Mapping = make([]document.Entry, 0, value.Len())
 		keys := value.MapKeys()
 		slices.SortFunc(keys, func(left, right reflect.Value) int {
-			return cmpString(left.String(), right.String())
+			return cmp.Compare(left.String(), right.String())
 		})
 		for _, key := range keys {
 			childPath := path.Key(key.String())
@@ -258,171 +217,6 @@ func (o *valueOperation) project(value reflect.Value, descriptor *typeDescriptor
 	}
 }
 
-func (o *valueOperation) clone(value reflect.Value, descriptor *typeDescriptor, path Path, depth int) (reflect.Value, *projectionIssue) {
-	if issue := o.checkDepth(path, depth); issue != nil {
-		return reflect.Value{}, issue
-	}
-	if descriptor.kind == descriptorPointer {
-		if value.IsNil() {
-			return reflect.Zero(value.Type()), nil
-		}
-		leave, issue := o.enter(value, path)
-		if issue != nil {
-			return reflect.Value{}, issue
-		}
-		defer leave()
-		child, issue := o.clone(value.Elem(), descriptor.element, path, depth)
-		if issue != nil {
-			return reflect.Value{}, issue
-		}
-		result := reflect.New(value.Type().Elem())
-		result.Elem().Set(child)
-		return result, nil
-	}
-
-	switch descriptor.kind {
-	case descriptorStruct:
-		result := reflect.New(value.Type()).Elem()
-		for _, member := range descriptor.members {
-			memberPath, memberDepth := path, depth
-			if !member.inline {
-				memberPath, memberDepth = path.Key(member.name), depth+1
-			}
-			cloned, issue := o.clone(value.Field(member.index), member.descriptor, memberPath, memberDepth)
-			if issue != nil {
-				return reflect.Value{}, issue
-			}
-			result.Field(member.index).Set(cloned)
-		}
-		return result, nil
-	case descriptorMap:
-		if value.IsNil() {
-			return reflect.Zero(value.Type()), nil
-		}
-		leave, issue := o.enter(value, path)
-		if issue != nil {
-			return reflect.Value{}, issue
-		}
-		defer leave()
-		result := reflect.MakeMapWithSize(value.Type(), value.Len())
-		for _, key := range value.MapKeys() {
-			cloned, issue := o.clone(value.MapIndex(key), descriptor.element, path.Key(key.String()), depth+1)
-			if issue != nil {
-				return reflect.Value{}, issue
-			}
-			result.SetMapIndex(key, cloned)
-		}
-		return result, nil
-	case descriptorSlice:
-		if value.IsNil() {
-			return reflect.Zero(value.Type()), nil
-		}
-		leave, issue := o.enter(value, path)
-		if issue != nil {
-			return reflect.Value{}, issue
-		}
-		defer leave()
-		result := reflect.MakeSlice(value.Type(), value.Len(), value.Len())
-		for i := 0; i < value.Len(); i++ {
-			cloned, issue := o.clone(value.Index(i), descriptor.element, path.Index(i), depth+1)
-			if issue != nil {
-				return reflect.Value{}, issue
-			}
-			result.Index(i).Set(cloned)
-		}
-		return result, nil
-	case descriptorArray:
-		result := reflect.New(value.Type()).Elem()
-		for i := 0; i < value.Len(); i++ {
-			cloned, issue := o.clone(value.Index(i), descriptor.element, path.Index(i), depth+1)
-			if issue != nil {
-				return reflect.Value{}, issue
-			}
-			result.Index(i).Set(cloned)
-		}
-		return result, nil
-	case descriptorDynamic:
-		if value.IsNil() {
-			return reflect.Zero(value.Type()), nil
-		}
-		concrete := value.Elem()
-		dynamic, issue := o.dynamicDescriptor(concrete.Type(), path)
-		if issue != nil {
-			return reflect.Value{}, issue
-		}
-		cloned, issue := o.clone(concrete, dynamic, path, depth)
-		if issue != nil {
-			return reflect.Value{}, issue
-		}
-		result := reflect.New(value.Type()).Elem()
-		result.Set(cloned)
-		return result, nil
-	case descriptorSecret:
-		result := reflect.New(value.Type()).Elem()
-		reference := value.Interface().(Secret)
-		if o.preserveSecrets {
-			result.Set(value)
-		} else if reference.specified {
-			result.Set(reflect.ValueOf(SecretEnv(reference.EnvName())))
-		}
-		return result, nil
-	case descriptorText:
-		text, issue := marshalCanonicalText(value, path)
-		if issue != nil {
-			return reflect.Value{}, issue
-		}
-		result := reflect.New(value.Type()).Elem()
-		unmarshaler := result.Addr().Interface().(encoding.TextUnmarshaler)
-		if err := unmarshaler.UnmarshalText([]byte(text)); err != nil {
-			return reflect.Value{}, &projectionIssue{code: CodeSchemaCodec, path: path.clone(), message: "custom text scalar could not be reconstructed"}
-		}
-		return result, nil
-	case descriptorFloat:
-		if math.IsNaN(value.Float()) || math.IsInf(value.Float(), 0) {
-			return reflect.Value{}, &projectionIssue{code: CodeSchemaNonFinite, path: path.clone(), message: "configuration float must be finite"}
-		}
-		fallthrough
-	default:
-		result := reflect.New(value.Type()).Elem()
-		result.Set(value)
-		return result, nil
-	}
-}
-
-func (o *valueOperation) dynamicDescriptor(current reflect.Type, path Path) (*typeDescriptor, *projectionIssue) {
-	if current == secretType {
-		return nil, &projectionIssue{code: CodeSchemaDynamicType, path: path.clone(), message: "dynamic configuration values cannot establish secret-reference semantics"}
-	}
-	builder := schemaBuilder{cache: o.schema.types, building: make(map[reflect.Type]bool)}
-	descriptor, issue := builder.describe(current, path)
-	if issue != nil {
-		return nil, &projectionIssue{code: CodeSchemaDynamicType, path: path.clone(), message: "dynamic configuration value has an unsupported type"}
-	}
-	if descriptorContainsSecret(descriptor, make(map[*typeDescriptor]bool)) {
-		return nil, &projectionIssue{code: CodeSchemaDynamicType, path: path.clone(), message: "dynamic configuration values cannot establish secret-reference semantics"}
-	}
-	return descriptor, nil
-}
-
-func descriptorContainsSecret(descriptor *typeDescriptor, visited map[*typeDescriptor]bool) bool {
-	if descriptor == nil || visited[descriptor] {
-		return false
-	}
-	if descriptor.kind == descriptorSecret {
-		return true
-	}
-	visited[descriptor] = true
-	if descriptorContainsSecret(descriptor.element, visited) {
-		return true
-	}
-	for _, member := range descriptor.members {
-		if descriptorContainsSecret(member.descriptor, visited) {
-			return true
-		}
-	}
-	return false
-}
-
 func (o *valueOperation) node(kind document.Kind, path Path, depth int) (*document.Node, *projectionIssue) {
 	if issue := o.checkDepth(path, depth); issue != nil {
 		return nil, issue
@@ -433,64 +227,6 @@ func (o *valueOperation) node(kind document.Kind, path Path, depth int) (*docume
 	return &document.Node{Kind: kind}, nil
 }
 
-func (o *valueOperation) charge(path Path) *projectionIssue {
-	o.nodes++
-	if o.limits.nodes >= 0 && o.nodes > o.limits.nodes {
-		return &projectionIssue{code: CodeSchemaProjectionLimit, path: path.clone(), message: "configuration projection exceeds the node limit"}
-	}
-	return nil
-}
-
-func (o *valueOperation) checkDepth(path Path, depth int) *projectionIssue {
-	if depth > o.limits.depth {
-		return &projectionIssue{code: CodeSchemaProjectionLimit, path: path.clone(), message: "configuration projection exceeds the depth limit"}
-	}
-	return nil
-}
-
-func (o *valueOperation) enter(value reflect.Value, path Path) (func(), *projectionIssue) {
-	visit, ok := visitFor(value)
-	if !ok {
-		return func() {}, nil
-	}
-	if o.active[visit] {
-		return nil, &projectionIssue{code: CodeSchemaCycle, path: path.clone(), message: "configuration values must not contain cycles"}
-	}
-	o.active[visit] = true
-	return func() { delete(o.active, visit) }, nil
-}
-
-func visitFor(value reflect.Value) (valueVisit, bool) {
-	if isNilValue(value) {
-		return valueVisit{}, false
-	}
-	visit := valueVisit{typeOf: value.Type(), kind: value.Kind()}
-	switch value.Kind() {
-	case reflect.Pointer, reflect.Slice:
-		if value.Kind() == reflect.Slice && value.Len() == 0 {
-			return valueVisit{}, false
-		}
-		visit.ptr = value.Pointer()
-	case reflect.Map:
-		if value.Len() == 0 {
-			return valueVisit{}, false
-		}
-		visit.ptr = uintptr(value.UnsafePointer())
-	default:
-		return valueVisit{}, false
-	}
-	return visit, visit.ptr != 0
-}
-
-func isNilValue(value reflect.Value) bool {
-	switch value.Kind() {
-	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
-		return value.IsNil()
-	default:
-		return false
-	}
-}
-
 func marshalCanonicalText(value reflect.Value, path Path) (string, *projectionIssue) {
 	var marshaler encoding.TextMarshaler
 	if value.CanInterface() {
@@ -510,113 +246,3 @@ func marshalCanonicalText(value reflect.Value, path Path) (string, *projectionIs
 	}
 	return string(text), nil
 }
-
-func cmpString(left, right string) int {
-	switch {
-	case left < right:
-		return -1
-	case left > right:
-		return 1
-	default:
-		return 0
-	}
-}
-
-type documentDeltaKind uint8
-
-const (
-	documentAdded documentDeltaKind = iota + 1
-	documentRemoved
-	documentReplaced
-)
-
-type documentDelta struct {
-	path Path
-	kind documentDeltaKind
-}
-
-func compareDocumentTrees(before, after *document.Node) []documentDelta {
-	var deltas []documentDelta
-	compareDocumentNode(before, after, Path{}, &deltas)
-	slices.SortFunc(deltas, func(left, right documentDelta) int {
-		if order := cmpString(left.path.String(), right.path.String()); order != 0 {
-			return order
-		}
-		return int(left.kind) - int(right.kind)
-	})
-	return deltas
-}
-
-func compareDocumentNode(before, after *document.Node, path Path, deltas *[]documentDelta) {
-	if before == nil && after == nil {
-		return
-	}
-	if before == nil {
-		*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentAdded})
-		return
-	}
-	if after == nil {
-		*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentRemoved})
-		return
-	}
-	if before.Kind != after.Kind {
-		*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentReplaced})
-		return
-	}
-	switch before.Kind {
-	case document.Mapping:
-		beforeEntries := make(map[string]*document.Node, len(before.Mapping))
-		afterEntries := make(map[string]*document.Node, len(after.Mapping))
-		keys := make(map[string]bool, len(before.Mapping)+len(after.Mapping))
-		for _, entry := range before.Mapping {
-			beforeEntries[entry.Key] = entry.Value
-			keys[entry.Key] = true
-		}
-		for _, entry := range after.Mapping {
-			afterEntries[entry.Key] = entry.Value
-			keys[entry.Key] = true
-		}
-		ordered := make([]string, 0, len(keys))
-		for key := range keys {
-			ordered = append(ordered, key)
-		}
-		slices.Sort(ordered)
-		for _, key := range ordered {
-			compareDocumentNode(beforeEntries[key], afterEntries[key], path.Key(key), deltas)
-		}
-	case document.Sequence:
-		if !documentNodesEqual(before, after) {
-			*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentReplaced})
-		}
-	default:
-		if before.Text != after.Text {
-			*deltas = append(*deltas, documentDelta{path: path.clone(), kind: documentReplaced})
-		}
-	}
-}
-
-func documentNodesEqual(left, right *document.Node) bool {
-	if left == nil || right == nil {
-		return left == right
-	}
-	if left.Kind != right.Kind || left.Text != right.Text || len(left.Mapping) != len(right.Mapping) || len(left.Sequence) != len(right.Sequence) {
-		return false
-	}
-	if left.Kind == document.Mapping {
-		leftMap := make(map[string]*document.Node, len(left.Mapping))
-		for _, entry := range left.Mapping {
-			leftMap[entry.Key] = entry.Value
-		}
-		for _, entry := range right.Mapping {
-			if !documentNodesEqual(leftMap[entry.Key], entry.Value) {
-				return false
-			}
-		}
-	}
-	for i := range left.Sequence {
-		if !documentNodesEqual(left.Sequence[i], right.Sequence[i]) {
-			return false
-		}
-	}
-	return true
-}

projection_test.go

@@ -328,7 +328,7 @@ func TestCompareDocumentTreesTracksSemanticChanges(t *testing.T) {
 	if issue != nil {
 		t.Fatal(issue.message)
 	}
-	deltas := compareDocumentTrees(before, after)
+	deltas := compareConfigurationValues(before, after)
 	want := []struct {
 		path string
 		kind documentDeltaKind
@@ -352,7 +352,7 @@ func TestCompareDocumentTreesTracksSemanticChanges(t *testing.T) {
 			t.Fatal("sequence comparison created index correspondence")
 		}
 	}
-	if equal := compareDocumentTrees(after, document.Clone(after)); len(equal) != 0 {
+	if equal := compareConfigurationValues(after, document.Clone(after)); len(equal) != 0 {
 		t.Fatalf("equal trees changed = %#v", equal)
 	}
 }

provenance_test.go

@@ -138,7 +138,7 @@ empty: {}
 		t.Fatal(issue)
 	}
 	projected, projectionIssue := projectConfiguration(schema, reflect.ValueOf(result.Config), defaultProjectionLimits())
-	if projectionIssue != nil || !documentNodesEqual(projected, result.final) {
+	if projectionIssue != nil || !configurationValuesEqual(projected, result.final) {
 		t.Fatalf("typed projection and private snapshot disagree: %#v", projectionIssue)
 	}
 

release_check_test.go

@@ -9,91 +9,99 @@ import (
 	"testing"
 )
 
-func TestReleaseCheckerShellHandlesFilenamesAndStopsOnFailure(t *testing.T) {
-	script, err := os.ReadFile("scripts/release-check.sh")
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, fail := range []bool{false, true} {
-		name := "success"
-		if fail {
-			name = "failed-go-check"
-		}
-		t.Run(name, func(t *testing.T) {
-			root := t.TempDir()
-			bin := t.TempDir()
-			log := filepath.Join(bin, "gofmt.args")
-			calls := filepath.Join(bin, "go.calls")
-			for _, directory := range []string{"scripts", "nested"} {
-				if err := os.Mkdir(filepath.Join(root, directory), 0700); err != nil {
-					t.Fatal(err)
-				}
-			}
-			write := func(path string, data []byte, mode os.FileMode) {
-				t.Helper()
-				if err := os.WriteFile(path, data, mode); err != nil {
-					t.Fatal(err)
-				}
-			}
-			write(filepath.Join(root, "scripts", "release-check.sh"), script, 0700)
-			write(filepath.Join(root, "go.mod"), []byte("module example.invalid/check\n"), 0600)
-			write(filepath.Join(root, "go.sum"), nil, 0600)
-			files := []string{"nested/a space.go", "nested/a\nnewline.go"}
-			for _, file := range files {
-				write(filepath.Join(root, file), []byte("package example\n"), 0600)
-			}
-			// Isolate expensive toolchain commands: this test owns shell orchestration,
-			// not Go's compiler or the production tests exercised by the real checker.
-			write(filepath.Join(bin, "go"), []byte("#!/bin/sh\nprintf '%s\\n' \"$*\" >> \"$CONFIGKIT_TEST_GO_LOG\"\nif [ \"${CONFIGKIT_TEST_FAIL-}\" = yes ] && [ \"${1-}\" = test ]; then exit 37; fi\n"), 0700)
-			write(filepath.Join(bin, "gofmt"), []byte("#!/bin/sh\nprintf '%s\\000' \"$@\" > \"$CONFIGKIT_TEST_FMT_LOG\"\n"), 0700)
-			init := exec.Command("git", "init", "-q")
-			init.Dir = root
-			if out, err := init.CombinedOutput(); err != nil {
-				t.Fatalf("git init: %v %s", err, out)
-			}
-			// HEAD is required by the whitespace gate. Commit only the module baseline.
-			for _, args := range [][]string{{"add", "go.mod", "go.sum"}, {"-c", "user.name=Test", "-c", "user.email=test@example.invalid", "-c", "commit.gpgsign=false", "commit", "-qm", "Test fixture"}} {
-				cmd := exec.Command("git", args...)
-				cmd.Dir = root
-				if out, err := cmd.CombinedOutput(); err != nil {
-					t.Fatalf("git fixture: %v %s", err, out)
-				}
-			}
-			cmd := exec.Command("/bin/bash", filepath.Join(root, "scripts", "release-check.sh"))
-			cmd.Env = append(os.Environ(), "PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"), "CONFIGKIT_BASELINE_TOOLCHAIN=test-baseline", "CONFIGKIT_NEWER_TOOLCHAIN=test-newer", "CONFIGKIT_TEST_FMT_LOG="+log, "CONFIGKIT_TEST_GO_LOG="+calls)
-			if fail {
-				cmd.Env = append(cmd.Env, "CONFIGKIT_TEST_FAIL=yes")
-			}
-			out, err := cmd.CombinedOutput()
-			if fail {
-				if err == nil {
-					t.Fatal("checker ignored failed Go test")
-				}
-			} else if err != nil {
-				t.Fatalf("checker: %v %s", err, out)
-			}
-			arguments, err := os.ReadFile(log)
+func TestCheckScriptsHandleFilenamesAndStopOnFailure(t *testing.T) {
+	for _, scriptName := range []string{"release-check.sh", "check.sh"} {
+		t.Run(scriptName, func(t *testing.T) {
+			script, err := os.ReadFile("scripts/" + scriptName)
 			if err != nil {
 				t.Fatal(err)
 			}
-			parts := bytes.Split(arguments, []byte{0})
-			for _, file := range files {
-				found := false
-				for _, arg := range parts {
-					if string(arg) == file {
-						found = true
+			for _, name := range []string{"success", "failed-go-check", "untracked-whitespace"} {
+				fail := name != "success"
+				t.Run(name, func(t *testing.T) {
+					root := t.TempDir()
+					bin := t.TempDir()
+					log := filepath.Join(bin, "gofmt.args")
+					calls := filepath.Join(bin, "go.calls")
+					for _, directory := range []string{"scripts", "nested"} {
+						if err := os.Mkdir(filepath.Join(root, directory), 0700); err != nil {
+							t.Fatal(err)
+						}
 					}
-				}
-				if !found {
-					t.Fatalf("filename was split: %q", file)
-				}
-			}
-			invoked, err := os.ReadFile(calls)
-			if err != nil {
-				t.Fatal(err)
-			}
-			if fail && strings.Contains(string(invoked), "vet ./...") {
-				t.Fatal("checker continued after failed test")
+					write := func(path string, data []byte, mode os.FileMode) {
+						t.Helper()
+						if err := os.WriteFile(path, data, mode); err != nil {
+							t.Fatal(err)
+						}
+					}
+					write(filepath.Join(root, "scripts", scriptName), script, 0700)
+					write(filepath.Join(root, "go.mod"), []byte("module example.invalid/check\n"), 0600)
+					write(filepath.Join(root, "go.sum"), nil, 0600)
+					write(filepath.Join(root, "obsolete.go"), []byte("package obsolete\n"), 0600)
+					files := []string{"nested/a space.go", "nested/a\nnewline.go"}
+					for _, file := range files {
+						write(filepath.Join(root, file), []byte("package example\n"), 0600)
+					}
+					if name == "untracked-whitespace" {
+						write(filepath.Join(root, "notes.md"), []byte("trailing space \n"), 0600)
+					}
+					// Isolate expensive toolchain commands: this test owns shell orchestration,
+					// not Go's compiler or the production tests exercised by the real checker.
+					write(filepath.Join(bin, "go"), []byte("#!/bin/sh\nprintf '%s\\n' \"$*\" >> \"$CONFIGKIT_TEST_GO_LOG\"\nif [ \"${CONFIGKIT_TEST_FAIL-}\" = yes ] && [ \"${1-}\" = test ]; then exit 37; fi\n"), 0700)
+					write(filepath.Join(bin, "gofmt"), []byte("#!/bin/sh\nprintf '%s\\000' \"$@\" > \"$CONFIGKIT_TEST_FMT_LOG\"\n"), 0700)
+					init := exec.Command("git", "init", "-q")
+					init.Dir = root
+					if out, err := init.CombinedOutput(); err != nil {
+						t.Fatalf("git init: %v %s", err, out)
+					}
+					// HEAD is required by the whitespace gate. Commit only the module baseline.
+					for _, args := range [][]string{{"add", "go.mod", "go.sum", "obsolete.go"}, {"-c", "user.name=Test", "-c", "user.email=test@example.invalid", "-c", "commit.gpgsign=false", "commit", "-qm", "Test fixture"}} {
+						cmd := exec.Command("git", args...)
+						cmd.Dir = root
+						if out, err := cmd.CombinedOutput(); err != nil {
+							t.Fatalf("git fixture: %v %s", err, out)
+						}
+					}
+					if err := os.Remove(filepath.Join(root, "obsolete.go")); err != nil {
+						t.Fatal(err)
+					}
+					cmd := exec.Command("/bin/bash", filepath.Join(root, "scripts", scriptName))
+					cmd.Env = append(os.Environ(), "PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"), "CONFIGKIT_BASELINE_TOOLCHAIN=test-baseline", "CONFIGKIT_NEWER_TOOLCHAIN=test-newer", "CONFIGKIT_TEST_FMT_LOG="+log, "CONFIGKIT_TEST_GO_LOG="+calls)
+					if name == "failed-go-check" {
+						cmd.Env = append(cmd.Env, "CONFIGKIT_TEST_FAIL=yes")
+					}
+					out, err := cmd.CombinedOutput()
+					if fail {
+						if err == nil {
+							t.Fatal("checker ignored failed Go test")
+						}
+					} else if err != nil {
+						t.Fatalf("checker: %v %s", err, out)
+					}
+					arguments, err := os.ReadFile(log)
+					if err != nil {
+						t.Fatal(err)
+					}
+					parts := bytes.Split(arguments, []byte{0})
+					for _, file := range files {
+						found := false
+						for _, arg := range parts {
+							if string(arg) == file {
+								found = true
+							}
+						}
+						if !found {
+							t.Fatalf("filename was split: %q", file)
+						}
+					}
+					invoked, err := os.ReadFile(calls)
+					if err != nil {
+						t.Fatal(err)
+					}
+					if fail && strings.Contains(string(invoked), "vet ./...") {
+						t.Fatal("checker continued after failed test")
+					}
+				})
 			}
 		})
 	}

resolution.go

@@ -241,7 +241,7 @@ func runResolution[T any](configuration *T, resolver func(*T, *Resolution) error
 		state.addDiagnostic(CodeResolveInvalidValue, issue.path, "application resolution produced an invalid configuration value")
 		return resolutionResult{diagnostics: canonicalDiagnostics(state.diagnostics)}
 	}
-	deltas := compareDocumentTrees(decoded.final, after)
+	deltas := compareConfigurationValues(decoded.final, after)
 	ordered := orderedResolutionRecords(state.records)
 	for _, delta := range deltas {
 		if coveringResolutionRecord(ordered, delta.path) == nil {
@@ -249,16 +249,15 @@ func runResolution[T any](configuration *T, resolver func(*T, *Resolution) error
 		}
 	}
 	for _, record := range ordered {
-		beforeNode, beforePresent := documentAtPath(decoded.final, record.path)
+		_, beforePresent := documentAtPath(decoded.final, record.path)
 		afterNode, afterPresent := documentAtPath(after, record.path)
 		if !beforePresent && !afterPresent {
 			state.addDiagnostic(CodeResolveInvalidRecord, record.path, "resolution record does not identify an existing or removed value")
 			continue
 		}
-		if record.helperExpected != nil && (!afterPresent || !documentNodesEqual(record.helperExpected, afterNode)) {
+		if record.helperExpected != nil && (!afterPresent || !configurationValuesEqual(record.helperExpected, afterNode)) {
 			state.addDiagnostic(CodeResolveInvalidTarget, record.path, "resolution helper assignment does not match its declared configuration path")
 		}
-		_ = beforeNode
 	}
 	if hasErrors(state.diagnostics) {
 		return resolutionResult{diagnostics: canonicalDiagnostics(state.diagnostics)}
@@ -343,17 +342,3 @@ func clonePaths(paths []Path) []Path {
 	}
 	return cloned
 }
-
-func cloneResolutionSnapshots(snapshots []resolutionSnapshot) []resolutionSnapshot {
-	if snapshots == nil {
-		return nil
-	}
-	cloned := make([]resolutionSnapshot, len(snapshots))
-	for index, snapshot := range snapshots {
-		cloned[index] = resolutionSnapshot{
-			change: cloneChange(snapshot.change),
-			before: document.Clone(snapshot.before), after: document.Clone(snapshot.after),
-		}
-	}
-	return cloned
-}

scripts/check.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repository_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$repository_dir"
+
+# Use the installed toolchain unless the caller explicitly selects another.
+# Toolchains and dependencies must already be available locally.
+export GOTOOLCHAIN=${GOTOOLCHAIN:-local}
+export GOPROXY=off
+go version
+
+go_files=()
+while IFS= read -r -d '' go_file; do
+  if [[ -f "$go_file" ]]; then
+    go_files+=("$go_file")
+  fi
+done < <(git ls-files --cached --others --exclude-standard -z -- '*.go')
+if ((${#go_files[@]})); then
+  unformatted=$(gofmt -l -- "${go_files[@]}")
+  if [[ -n "$unformatted" ]]; then
+    printf 'gofmt required for:\n%s\n' "$unformatted" >&2
+    exit 1
+  fi
+fi
+
+git diff --check HEAD --
+while IFS= read -r -d '' candidate_file; do
+  # --no-index returns 1 for differing content even when whitespace is clean;
+  # whitespace errors return 2. Preserve other failures as well.
+  git diff --no-index --check -- /dev/null "$candidate_file" || {
+    check_status=$?
+    if ((check_status != 1)); then
+      exit "$check_status"
+    fi
+  }
+done < <(git ls-files --others --exclude-standard -z)
+
+go test ./...
+go vet ./...
+go build ./...

scripts/release-check.sh

@@ -25,8 +25,13 @@ bash -n scripts/release-check.sh
 
 temporary_dir=$(mktemp -d)
 trap 'rm -rf -- "$temporary_dir"' EXIT
-git ls-files --cached --others --exclude-standard -z |
-  tar --null --files-from=- --create --file=- |
+candidate_manifest=$temporary_dir/candidate-files
+while IFS= read -r -d '' candidate_file; do
+  if [[ -e "$candidate_file" || -L "$candidate_file" ]]; then
+    printf '%s\0' "$candidate_file" >>"$candidate_manifest"
+  fi
+done < <(git ls-files --cached --others --exclude-standard -z)
+tar --null --files-from="$candidate_manifest" --create --file=- |
   tar --extract --file=- --directory="$temporary_dir"
 (
   cd "$temporary_dir"
@@ -37,7 +42,9 @@ diff -u go.sum "$temporary_dir/go.sum"
 
 go_files=()
 while IFS= read -r -d '' go_file; do
-  go_files+=("$go_file")
+  if [[ -f "$go_file" ]]; then
+    go_files+=("$go_file")
+  fi
 done < <(git ls-files --cached --others --exclude-standard -z -- '*.go')
 if ((${#go_files[@]})); then
   unformatted=$(gofmt -l -- "${go_files[@]}")
@@ -49,6 +56,9 @@ fi
 
 git diff --check HEAD --
 while IFS= read -r -d '' candidate_file; do
+  if [[ ! -f "$candidate_file" ]]; then
+    continue
+  fi
   case "$candidate_file" in
     *.go|*.md|*.sh|go.mod|go.sum|LICENSE|.gitignore|AGENTS.md)
       if LC_ALL=C grep -nE '[[:blank:]]+$' -- "$candidate_file"; then

secret.go

@@ -144,21 +144,10 @@ func schemaSecretRoot(schema *schemaDescriptor, path Path) (Path, bool) {
 // is equal. Validators must preserve this inspection metadata as well as values.
 func projectedSensitivity(root *document.Node) map[string]Path {
 	result := make(map[string]Path)
-	var visit func(*document.Node, Path)
-	visit = func(node *document.Node, path Path) {
-		if node == nil {
-			return
-		}
+	walkDocument(root, Path{}, func(path Path, node *document.Node) {
 		if node.Sensitive {
 			result[path.String()] = path.clone()
 		}
-		for _, entry := range node.Mapping {
-			visit(entry.Value, path.Key(entry.Key))
-		}
-		for i, child := range node.Sequence {
-			visit(child, path.Index(i))
-		}
-	}
-	visit(root, Path{})
+	})
 	return result
 }

secret_reference.go

@@ -1,6 +1,7 @@
 package configkit
 
 import (
+	"cmp"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -139,7 +140,7 @@ func resolveSecretValue(value reflect.Value, descriptor *typeDescriptor, path Pa
 			return
 		}
 		keys := value.MapKeys()
-		slices.SortFunc(keys, func(left, right reflect.Value) int { return cmpString(left.String(), right.String()) })
+		slices.SortFunc(keys, func(left, right reflect.Value) int { return cmp.Compare(left.String(), right.String()) })
 		for _, key := range keys {
 			entry := reflect.New(value.Type().Elem()).Elem()
 			entry.Set(value.MapIndex(key))
@@ -167,7 +168,7 @@ func secretDiagnostic(code Code, path Path, message string, input *document.Node
 func changedSecretStates(root reflect.Value, descriptor *typeDescriptor, lookups map[string]secretLookupResult) []Path {
 	var changed []Path
 	collectChangedSecretStates(root, descriptor, Path{}, lookups, &changed)
-	slices.SortFunc(changed, func(left, right Path) int { return cmpString(left.String(), right.String()) })
+	slices.SortFunc(changed, func(left, right Path) int { return cmp.Compare(left.String(), right.String()) })
 	return changed
 }
 
@@ -198,7 +199,7 @@ func collectChangedSecretStates(value reflect.Value, descriptor *typeDescriptor,
 			return
 		}
 		keys := value.MapKeys()
-		slices.SortFunc(keys, func(left, right reflect.Value) int { return cmpString(left.String(), right.String()) })
+		slices.SortFunc(keys, func(left, right reflect.Value) int { return cmp.Compare(left.String(), right.String()) })
 		for _, key := range keys {
 			collectChangedSecretStates(value.MapIndex(key), descriptor.element, path.Key(key.String()), lookups, changed)
 		}
@@ -211,3 +212,14 @@ func collectChangedSecretStates(value reflect.Value, descriptor *typeDescriptor,
 		}
 	}
 }
+
+func cloneSecretReferences(values map[string]string) map[string]string {
+	if values == nil {
+		return nil
+	}
+	cloned := make(map[string]string, len(values))
+	for path, name := range values {
+		cloned[path] = name
+	}
+	return cloned
+}

snapshot.go

@@ -0,0 +1,63 @@
+package configkit
+
+import (
+	"bytes"
+	"slices"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+	yamladapter "gitea.maximumdirect.net/eric/ConfigKit/internal/yaml"
+)
+
+// Snapshot projection is the shared redaction boundary for effective YAML
+// and explanation values. It borrows frozen trees and returns a detached tree.
+func valueSnapshot(root *document.Node, path Path, secrets map[string]bool) ValueSnapshot {
+	node, present := documentAtPath(root, path)
+	if !present {
+		return ValueSnapshot{}
+	}
+	safe, redacted := safeSnapshotDocument(node, secrets, path)
+	var output bytes.Buffer
+	if err := yamladapter.Write(&output, safe); err != nil {
+		return ValueSnapshot{Present: true, Redacted: true, YAML: "'[REDACTED]'\n"}
+	}
+	return ValueSnapshot{Present: true, Redacted: redacted, YAML: output.String()}
+}
+
+func safeSnapshotDocument(node *document.Node, secrets map[string]bool, path Path) (*document.Node, bool) {
+	if node == nil {
+		return nil, false
+	}
+	if pathIsSecret(secrets, path) {
+		return &document.Node{Kind: document.String, Text: "[REDACTED]"}, true
+	}
+	result := *node
+	redacted := false
+	switch node.Kind {
+	case document.Mapping:
+		result.Mapping = make([]document.Entry, len(node.Mapping))
+		copy(result.Mapping, node.Mapping)
+		sortDocumentMapping(result.Mapping)
+		for index := range result.Mapping {
+			entry := &result.Mapping[index]
+			entry.Value, redacted = safeSnapshotChild(entry.Value, secrets, path.Key(entry.Key), redacted)
+		}
+	case document.Sequence:
+		result.Sequence = make([]*document.Node, len(node.Sequence))
+		for index, child := range node.Sequence {
+			result.Sequence[index], redacted = safeSnapshotChild(child, secrets, path.Index(index), redacted)
+		}
+	}
+	return &result, redacted
+}
+
+func safeSnapshotChild(node *document.Node, secrets map[string]bool, path Path, prior bool) (*document.Node, bool) {
+	safe, redacted := safeSnapshotDocument(node, secrets, path)
+	return safe, prior || redacted
+}
+
+func sortDocumentMapping(entries []document.Entry) {
+	slices.SortFunc(entries, func(left, right document.Entry) int {
+		return strings.Compare(left.Key, right.Key)
+	})
+}

source.go

@@ -125,10 +125,7 @@ func readSource(source Source, sourceID string, limits sourceLimits) (sourceRead
 	}
 	info := &SourceInfo{ID: sourceID, Label: source.label, Layer: LayerBase}
 
-	var (
-		input io.Reader
-		close func() error
-	)
+	var input io.Reader
 	switch source.kind {
 	case sourceFile:
 		absolute, err := filepath.Abs(source.path)
@@ -141,32 +138,11 @@ func readSource(source Source, sourceID string, limits sourceLimits) (sourceRead
 			return sourceRead{info: info}, []Diagnostic{classifySourceError(err, sourceID)}
 		}
 		info.Path = canonical
-		preflight, err := os.Stat(canonical)
-		if err != nil {
-			return sourceRead{info: info}, []Diagnostic{classifySourceError(err, sourceID)}
+		data, failure := readRegularFile(canonical, os.Stat, os.Open, limit)
+		if failure != nil {
+			return sourceRead{info: info}, []Diagnostic{sourceReadDiagnostic(failure, sourceID, CodeSourceLimitExceeded, "source exceeds the configured byte limit")}
 		}
-		if !preflight.Mode().IsRegular() {
-			return sourceRead{info: info}, []Diagnostic{sourceDiagnostic(CodeSourceNotRegular, sourceID, "source is not a regular file")}
-		}
-		file, err := os.Open(canonical)
-		if err != nil {
-			return sourceRead{info: info}, []Diagnostic{classifySourceError(err, sourceID)}
-		}
-		close = file.Close
-		stat, err := file.Stat()
-		if err != nil {
-			_ = file.Close()
-			return sourceRead{info: info}, []Diagnostic{classifySourceError(err, sourceID)}
-		}
-		if !stat.Mode().IsRegular() {
-			_ = file.Close()
-			return sourceRead{info: info}, []Diagnostic{sourceDiagnostic(CodeSourceNotRegular, sourceID, "source is not a regular file")}
-		}
-		if stat.Size() > limit {
-			_ = file.Close()
-			return sourceRead{info: info}, []Diagnostic{sourceDiagnostic(CodeSourceLimitExceeded, sourceID, "source exceeds the configured byte limit")}
-		}
-		input = file
+		return sourceRead{data: bytes.Clone(data), info: info}, nil
 	case sourceBytes:
 		input = bytes.NewReader(source.data)
 	case sourceReader:
@@ -177,16 +153,9 @@ func readSource(source Source, sourceID string, limits sourceLimits) (sourceRead
 	default:
 		return sourceRead{info: info}, []Diagnostic{sourceDiagnostic(CodeSourceInvalid, sourceID, "source is invalid")}
 	}
-	if close != nil {
-		defer func() { _ = close() }()
-	}
-
-	data, err := io.ReadAll(io.LimitReader(input, limit+1))
-	if err != nil {
-		return sourceRead{info: info}, []Diagnostic{classifySourceError(err, sourceID)}
-	}
-	if int64(len(data)) > limit {
-		return sourceRead{info: info}, []Diagnostic{sourceDiagnostic(CodeSourceLimitExceeded, sourceID, "source exceeds the configured byte limit")}
+	data, failure := readBoundedSource(input, limit)
+	if failure != nil {
+		return sourceRead{info: info}, []Diagnostic{sourceReadDiagnostic(failure, sourceID, CodeSourceLimitExceeded, "source exceeds the configured byte limit")}
 	}
 	return sourceRead{data: bytes.Clone(data), info: info}, nil
 }

source_file.go

@@ -0,0 +1,75 @@
+package configkit
+
+import (
+	"errors"
+	"io"
+	"io/fs"
+	"os"
+)
+
+type sourceReadFailureKind uint8
+
+const (
+	sourceReadIO sourceReadFailureKind = iota
+	sourceReadNotRegular
+	sourceReadLimit
+)
+
+// sourceReadFailure never escapes the private source boundary. missingTarget is
+// set only for preflight/open failures; a later missing-file error is not optional.
+type sourceReadFailure struct {
+	kind          sourceReadFailureKind
+	cause         error
+	missingTarget bool
+}
+
+// readRegularFile borrows stat/open operations so root-bound callers retain their
+// containment policy. Preflight rejects FIFOs before open can block. The opened
+// handle is checked again and always closed; read-only close errors are ignored.
+func readRegularFile(name string, stat func(string) (fs.FileInfo, error), open func(string) (*os.File, error), limit int64) ([]byte, *sourceReadFailure) {
+	info, err := stat(name)
+	if err != nil {
+		return nil, &sourceReadFailure{cause: err, missingTarget: errors.Is(err, fs.ErrNotExist)}
+	}
+	if !info.Mode().IsRegular() {
+		return nil, &sourceReadFailure{kind: sourceReadNotRegular}
+	}
+	file, err := open(name)
+	if err != nil {
+		return nil, &sourceReadFailure{cause: err, missingTarget: errors.Is(err, fs.ErrNotExist)}
+	}
+	defer func() { _ = file.Close() }()
+	info, err = file.Stat()
+	if err != nil {
+		return nil, &sourceReadFailure{cause: err}
+	}
+	if !info.Mode().IsRegular() {
+		return nil, &sourceReadFailure{kind: sourceReadNotRegular}
+	}
+	if info.Size() > limit {
+		return nil, &sourceReadFailure{kind: sourceReadLimit}
+	}
+	return readBoundedSource(file, limit)
+}
+
+func readBoundedSource(input io.Reader, limit int64) ([]byte, *sourceReadFailure) {
+	data, err := io.ReadAll(io.LimitReader(input, limit+1))
+	if err != nil {
+		return nil, &sourceReadFailure{cause: err}
+	}
+	if int64(len(data)) > limit {
+		return nil, &sourceReadFailure{kind: sourceReadLimit}
+	}
+	return data, nil
+}
+
+func sourceReadDiagnostic(failure *sourceReadFailure, sourceID string, limitCode Code, limitMessage string) Diagnostic {
+	switch failure.kind {
+	case sourceReadNotRegular:
+		return sourceDiagnostic(CodeSourceNotRegular, sourceID, "source is not a regular file")
+	case sourceReadLimit:
+		return sourceDiagnostic(limitCode, sourceID, limitMessage)
+	default:
+		return classifySourceError(failure.cause, sourceID)
+	}
+}

source_file_test.go

@@ -0,0 +1,48 @@
+package configkit
+
+import (
+	"io/fs"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// Files disappearing between filesystem operations are not deterministic with
+// real concurrent deletion. Exercise the private seam that controls optionality.
+func TestRegularFileMissingFailurePhases(t *testing.T) {
+	name := filepath.Join(t.TempDir(), "input.yml")
+	if err := os.WriteFile(name, []byte("{}"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	for _, test := range []struct {
+		name    string
+		stat    func(string) (fs.FileInfo, error)
+		open    func(string) (*os.File, error)
+		missing bool
+	}{
+		{"preflight", func(string) (fs.FileInfo, error) { return nil, fs.ErrNotExist }, os.Open, true},
+		{"open", os.Stat, func(string) (*os.File, error) { return nil, fs.ErrNotExist }, true},
+		{"post-open stat", os.Stat, func(name string) (*os.File, error) {
+			file, err := os.Open(name)
+			if err == nil {
+				err = file.Close()
+			}
+			return file, err
+		}, false},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			data, failure := readRegularFile(name, test.stat, test.open, 16)
+			if data != nil || failure == nil || failure.kind != sourceReadIO || failure.missingTarget != test.missing {
+				t.Fatalf("data = %v, failure = %#v", data, failure)
+			}
+		})
+	}
+	_, failure := readBoundedSource(missingDuringRead{}, 16)
+	if failure == nil || failure.kind != sourceReadIO || failure.missingTarget {
+		t.Fatalf("late read failure = %#v", failure)
+	}
+}
+
+type missingDuringRead struct{}
+
+func (missingDuringRead) Read([]byte) (int, error) { return 0, fs.ErrNotExist }

validation.go

@@ -109,21 +109,7 @@ func runValidation[T any](configuration *T, validator func(*T, *Validation), sch
 		state.diagnostics = append(state.diagnostics, validationMutationDiagnostic(issue.path))
 		return canonicalDiagnostics(state.diagnostics)
 	}
-	for _, delta := range compareDocumentTrees(before, after) {
-		state.diagnostics = append(state.diagnostics, validationMutationDiagnostic(delta.path))
-	}
-	beforeSensitivity := projectedSensitivity(before)
-	afterSensitivity := projectedSensitivity(after)
-	for pointer, path := range beforeSensitivity {
-		if _, exists := afterSensitivity[pointer]; !exists {
-			state.diagnostics = append(state.diagnostics, validationMutationDiagnostic(path))
-		}
-	}
-	for pointer, path := range afterSensitivity {
-		if _, exists := beforeSensitivity[pointer]; !exists {
-			state.diagnostics = append(state.diagnostics, validationMutationDiagnostic(path))
-		}
-	}
+	state.diagnostics = append(state.diagnostics, validationValueMutations(before, after)...)
 	for _, path := range changedSecretStates(reflect.ValueOf(*configuration), schema.root, lookups) {
 		state.diagnostics = append(state.diagnostics, validationMutationDiagnostic(path))
 	}
@@ -178,3 +164,71 @@ func nearestDocumentLocation(root *document.Node, path Path) (document.Location,
 func locationKnown(location document.Location) bool {
 	return location.SourceID != "" || location.Line != 0 || location.Column != 0
 }
+
+// validationValueMutations combines value and sensitivity changes; resolved
+// secret state is audited separately because it never enters projected trees.
+func validationValueMutations(before, after *document.Node) []Diagnostic {
+	var diagnostics []Diagnostic
+	for _, delta := range compareConfigurationValues(before, after) {
+		diagnostics = append(diagnostics, validationMutationDiagnostic(delta.path))
+	}
+	beforeSensitivity := projectedSensitivity(before)
+	afterSensitivity := projectedSensitivity(after)
+	for pointer, path := range beforeSensitivity {
+		if _, exists := afterSensitivity[pointer]; !exists {
+			diagnostics = append(diagnostics, validationMutationDiagnostic(path))
+		}
+	}
+	for pointer, path := range afterSensitivity {
+		if _, exists := beforeSensitivity[pointer]; !exists {
+			diagnostics = append(diagnostics, validationMutationDiagnostic(path))
+		}
+	}
+	return diagnostics
+}
+
+func checkVersion(rule *VersionRule, root *document.Node) []Diagnostic {
+	if rule == nil {
+		return nil
+	}
+	version := Version{}
+	node, present := documentAtPath(root, rule.Path)
+	if present {
+		version.Present = true
+		switch node.Kind {
+		case document.Null:
+			version.Null = true
+		case document.String:
+			version.Text = node.Text
+		default:
+			location, _ := nearestDocumentLocation(root, rule.Path)
+			primary := documentLocationPointer(location)
+			return []Diagnostic{{
+				Code: CodeVersionType, Severity: SeverityError, Path: rule.Path.clone(),
+				Message: "schema version must be a string or null", Primary: primary,
+			}}
+		}
+	}
+	state := &validationState{
+		active: true, errorCode: CodeVersionError, warningCode: CodeVersionWarning,
+		invalidPath: CodeVersionError, document: root,
+	}
+	validation := &Validation{state: state}
+	err := rule.Check(version, validation)
+	state.active = false
+	if err != nil && !hasErrors(state.diagnostics) {
+		location, _ := nearestDocumentLocation(root, rule.Path)
+		state.diagnostics = append(state.diagnostics, Diagnostic{
+			Code: CodeVersionHookFailed, Severity: SeverityError, Path: rule.Path.clone(),
+			Message: "schema-version check failed", Primary: documentLocationPointer(location),
+		})
+	}
+	return canonicalDiagnostics(state.diagnostics)
+}
+
+func documentLocationPointer(location document.Location) *Location {
+	if !locationKnown(location) {
+		return nil
+	}
+	return &Location{SourceID: location.SourceID, Line: location.Line, Column: location.Column}
+}

value_operation.go

@@ -0,0 +1,126 @@
+package configkit
+
+import "reflect"
+
+type projectionLimits struct {
+	depth int
+	nodes int
+}
+
+func defaultProjectionLimits() projectionLimits {
+	return projectionLimits{depth: maxDocumentDepth, nodes: maxDocumentNodes}
+}
+
+type projectionIssue struct {
+	code    Code
+	path    Path
+	message string
+}
+
+type valueVisit struct {
+	typeOf reflect.Type
+	kind   reflect.Kind
+	ptr    uintptr
+}
+
+// valueOperation owns one traversal's cycle and budget state and reuses the
+// current load's descriptor cache for dynamic values.
+type valueOperation struct {
+	cloneMode secretCloneMode
+	schema    *schemaDescriptor
+	limits    projectionLimits
+	active    map[valueVisit]bool
+	nodes     int
+}
+
+func (o *valueOperation) dynamicDescriptor(current reflect.Type, path Path) (*typeDescriptor, *projectionIssue) {
+	if current == secretType {
+		return nil, &projectionIssue{code: CodeSchemaDynamicType, path: path.clone(), message: "dynamic configuration values cannot establish secret-reference semantics"}
+	}
+	builder := schemaBuilder{cache: o.schema.types, building: make(map[reflect.Type]bool)}
+	descriptor, issue := builder.describe(current, path)
+	if issue != nil {
+		return nil, &projectionIssue{code: CodeSchemaDynamicType, path: path.clone(), message: "dynamic configuration value has an unsupported type"}
+	}
+	if descriptorContainsSecret(descriptor, make(map[*typeDescriptor]bool)) {
+		return nil, &projectionIssue{code: CodeSchemaDynamicType, path: path.clone(), message: "dynamic configuration values cannot establish secret-reference semantics"}
+	}
+	return descriptor, nil
+}
+
+func descriptorContainsSecret(descriptor *typeDescriptor, visited map[*typeDescriptor]bool) bool {
+	if descriptor == nil || visited[descriptor] {
+		return false
+	}
+	if descriptor.kind == descriptorSecret {
+		return true
+	}
+	visited[descriptor] = true
+	if descriptorContainsSecret(descriptor.element, visited) {
+		return true
+	}
+	for _, member := range descriptor.members {
+		if descriptorContainsSecret(member.descriptor, visited) {
+			return true
+		}
+	}
+	return false
+}
+
+func (o *valueOperation) charge(path Path) *projectionIssue {
+	o.nodes++
+	if o.limits.nodes >= 0 && o.nodes > o.limits.nodes {
+		return &projectionIssue{code: CodeSchemaProjectionLimit, path: path.clone(), message: "configuration projection exceeds the node limit"}
+	}
+	return nil
+}
+
+func (o *valueOperation) checkDepth(path Path, depth int) *projectionIssue {
+	if depth > o.limits.depth {
+		return &projectionIssue{code: CodeSchemaProjectionLimit, path: path.clone(), message: "configuration projection exceeds the depth limit"}
+	}
+	return nil
+}
+
+func (o *valueOperation) enter(value reflect.Value, path Path) (func(), *projectionIssue) {
+	visit, ok := visitFor(value)
+	if !ok {
+		return func() {}, nil
+	}
+	if o.active[visit] {
+		return nil, &projectionIssue{code: CodeSchemaCycle, path: path.clone(), message: "configuration values must not contain cycles"}
+	}
+	o.active[visit] = true
+	return func() { delete(o.active, visit) }, nil
+}
+
+func visitFor(value reflect.Value) (valueVisit, bool) {
+	if isNilValue(value) {
+		return valueVisit{}, false
+	}
+	visit := valueVisit{typeOf: value.Type(), kind: value.Kind()}
+	switch value.Kind() {
+	case reflect.Pointer, reflect.Slice:
+		if value.Kind() == reflect.Slice && value.Len() == 0 {
+			return valueVisit{}, false
+		}
+		visit.ptr = value.Pointer()
+	case reflect.Map:
+		if value.Len() == 0 {
+			return valueVisit{}, false
+		}
+		visit.ptr = uintptr(value.UnsafePointer())
+	default:
+		return valueVisit{}, false
+	}
+	return visit, visit.ptr != 0
+}
+
+func isNilValue(value reflect.Value) bool {
+	switch value.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return value.IsNil()
+	default:
+		return false
+	}
+}