Complete single-source semantic validation

docs/config.md

@@ -38,7 +38,8 @@ The current lifecycle is:
 ```text
 validate options → parse one source → reject reserved directives → build schema
   → check the optional application version → create and clone defaults
-  → strictly decode → snapshot configuration and metadata
+  → strictly decode → recorded application resolution → semantic validation
+  → snapshot configuration and metadata
 ```
 
 `File`, `Bytes`, and `Reader` each contribute one base source with the deterministic
@@ -46,17 +47,17 @@ ID `source-1`. `NoSource` skips parsing, supplies an absent version to a configu
 version checker, contributes no source, and continues through defaults, decode, and
 projection. A missing file remains an error; it is never interpreted as no input.
 
-The current `Options` boundary accepts a defaults factory and `VersionRule`.
-Imports, active profiles, filesystem context, overrides, semantic validator
-callbacks, and dynamic secret classification return an explicit
+The current `Options` boundary accepts a defaults factory, `VersionRule`, resolver,
+and semantic validator. Imports, active profiles, filesystem context, overrides,
+and dynamic secret classification return an explicit
 `options.unavailable` error because their lifecycle stages are not implemented.
 The reserved profile spelling `default` selects no active profile. `NoSource`
 additionally rejects imports, active profiles, and filesystem context as invalid
 combinations. Input containing a reserved `_configkit` mapping key is rejected while
 imports are disabled.
 
-Every source, options, schema, version, defaults, or decode failure returns a nil
-result and a `*LoadError`. Successful results contain caller-owned `Config`, detached
+Every source, options, schema, version, defaults, decode, resolution, or validation
+failure returns a nil result and a `*LoadError`. Successful results contain caller-owned `Config`, detached
 `Metadata`, a defensive source list, and defensive nonfatal diagnostics. Mutating
 the returned configuration or inspection records cannot alter ConfigKit's private
 snapshot. ConfigKit performs no logging and exposes no effective writer yet.
@@ -122,6 +123,33 @@ retain history. ConfigKit privately snapshots each recorded before/after subtree
 later safe explanation; caller mutations of `Result.Config` cannot alter those
 snapshots.
 
+### Semantic validation
+
+An optional `Definition.Validate` callback runs after successful resolution and
+receives the resolved configuration plus a per-load `Validation` context. It can
+collect multiple independent `validate.error` and `validate.warning` reports.
+Warnings continue the lifecycle and are returned on success; any error returns a nil
+result with the full safe diagnostic and source report.
+
+Primary and related paths must be valid for the application schema. Omitted declared
+fields and missing string-map or dynamic keys are valid report targets; unknown
+struct fields and malformed paths produce `validate.invalid_path`. ConfigKit attaches
+the exact surviving input location when one exists, otherwise the nearest input
+container location, or no primary location for defaults-only synthetic state.
+
+Validation is read-only. ConfigKit projects the configuration immediately before and
+after the callback and returns `validate.mutation` at every detected net-change path,
+including nested mutable state. A value that can no longer be projected is also a
+mutation failure. No mutated or otherwise invalid configuration is published.
+Callback panics remain programming failures, and retained contexts use the same
+fixed closed-context panic as version and resolution callbacks.
+
+Only schema-bound exported state participates in loading, resolution audit,
+validation audit, metadata, and snapshots. Ignored or unexported ordinary fields are
+zero in returned detached values. Applications retain responsibility for domain
+rules and runtime initialization; validators should not start clients or depend on
+live services as a substitute for configuration validation.
+
 ## YAML documents
 
 The private YAML boundary currently accepts exactly one nonempty document whose root