Add single-source loading and version checks

docs/config.md

@@ -1,9 +1,9 @@
 # Configuration Input Contract
 
 This document owns ConfigKit's currently implemented source-input, YAML syntax,
-schema, typed-decoding, and ownership contracts. The parser, owned document
-representation, and decoder are private; a public typed loading lifecycle has not
-been implemented yet.
+schema, typed-decoding, loading, metadata, and ownership contracts. The parser,
+owned document representation, and decoder remain private behind the public loading
+lifecycle.
 
 ## Sources
 
@@ -14,7 +14,7 @@ ConfigKit exposes opaque sources through these constructors:
 | `File(path)` | Requires a nonempty path, opens a regular file for each consumption, and closes only the library-owned file handle. Missing, inaccessible, unreadable, directory, and other nonregular inputs fail. |
 | `Bytes(label, data)` | Requires a nonempty, non-secret diagnostic label and snapshots bytes during construction. Later caller mutation cannot affect the source. |
 | `Reader(label, input)` | Requires a nonempty, non-secret label and non-nil reader. The reader is claimed once across all copies of the source, consumed but never closed, and cannot be reused. |
-| `NoSource()` | Represents an explicit absence of input and creates no source record. Its defaults-only lifecycle behavior will become available with `Load`. |
+| `NoSource()` | Selects defaults-only loading, creates no source record, and marks no paths explicit. |
 
 The zero `Source` is invalid. Constructor argument failures are retained inside the
 opaque source and become safe structured diagnostics when the source is consumed.
@@ -25,6 +25,65 @@ and override input when those layers are implemented. Reads request at most the
 remaining allowance plus one byte so excess data is rejected rather than silently
 truncated. Data returned together with a read error is not accepted as partial input.
 
+## Single-source loading
+
+`Load[T](source, options...)` accepts zero or one `Options[T]`. The configuration
+root `T` must satisfy the application schema contract below. With no options it
+starts from the Go zero value. A `Definition[T].Defaults` factory, when supplied,
+runs exactly once after successful source parsing, schema construction, and optional
+schema-version checking. Its result is detached before input is applied.
+
+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
+```
+
+`File`, `Bytes`, and `Reader` each contribute one base source with the deterministic
+ID `source-1`. `NoSource` skips parsing, supplies an absent version to a configured
+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, resolver and semantic
+validator callbacks, 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
+`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.
+
+### Application schema versions
+
+`VersionRule` declares a semantic path and non-nil checker. Before defaults or typed
+decoding, the checker receives a `Version` preserving absent, explicit null, or
+string input. Any other input kind is a `version.type` error and the checker does not
+run. ConfigKit does not interpret the text or impose a universal version path.
+
+The checker reports safe, value-free errors and warnings through `Validation.Error`
+and `Validation.Warning`; ConfigKit resolves primary and related paths to exact or
+nearest input locations. Reported errors fail loading. If the checker returns an
+error without reporting one, ConfigKit emits a generic `version.hook_failed`
+diagnostic and suppresses the returned error text. Warnings alone are retained on a
+successful result. Callback panics remain programming failures.
+
+### Base/default metadata
+
+`Result.Metadata` describes every final canonical path. Exact surviving input paths
+are explicit and have a base origin; omitted paths have a default origin. An explicit
+parent mapping does not make omitted children explicit. Null state and available
+source coordinates are retained. `History` records the Go-zero or application
+default baseline followed by exact base definitions, including equal-valued input.
+All metadata queries and returned nested records are detached.
+
 ## YAML documents
 
 The private YAML boundary currently accepts exactly one nonempty document whose root
@@ -144,8 +203,8 @@ Paired text scalars decode only from strings through `encoding.TextUnmarshaler`,
 codec failures are classified without exposing application error text or input
 values.
 
-This decoder is currently an internal lifecycle foundation, not a public conversion
-API. Applications cannot call typed loading until `Load` is introduced.
+This decoder is available only through `Load`; ConfigKit exposes no generic document
+conversion API.
 
 ## Typed projection and ownership