Support integer schema versions through typed decoding

docs/roadmap/integer-schema-versions.md

@@ -0,0 +1,142 @@
+# String and integer schema versions
+
+Status: planned; not implemented. This document owns the intended end state.
+The [implementation plan](implementation.md) owns sequencing and
+progress. Current behavior remains defined by the [configuration contract](../config.md).
+
+## Motivation and scope
+
+Notarius historically declares `version: 4`. ConfigKit currently rejects this at
+the version-check boundary and independently rejects assigning an integer to a Go
+string during decoding. Consumers should be able to retain an integer version
+declaration while using a string for application version comparison and storage.
+
+Support this through the existing `VersionRule`, not a new parser mode, global
+coercion option, public union type, or application-side YAML rewrite. Applications
+continue to decide which version identifiers are supported. No downstream
+repository changes or automatic schema migrations are included.
+
+## Target contract
+
+The following is intended future behavior, not a description of today's release.
+
+### Version checking
+
+Only the semantic path designated by `Definition.Version.Path` receives version
+handling. There is no special behavior based on a field being named `version`.
+An absent rule leaves all existing decoding behavior unchanged.
+
+| Input at the configured path | Checker input |
+| --- | --- |
+| Absent | `Version{Present: false}` |
+| Explicit null | `Version{Present: true, Null: true}` |
+| String, including empty string | Present, non-null; `Text` preserves the string |
+| Number with integer syntax | Present, non-null; `Text` preserves the validated decimal spelling |
+| Fractional/exponent number, boolean, mapping, or sequence | `CodeVersionType`; checker not called |
+
+Integer syntax means the existing strict decimal integer grammar
+`^-?(0|[1-9][0-9]*)$`. Thus `4` and `"4"` both supply text `"4"`.
+`-0` supplies `"-0"`; do not silently canonicalize it to `"0"`. Negative and zero
+identifiers are structurally accepted; application policy may reject them.
+`4.0` and `4e0` are not integer syntax, even though their mathematical values are
+integral. Quoted versions such as `"4.0"` remain strings and remain accepted.
+The parser's existing rejection of leading zeroes, hexadecimal, leading plus,
+and other unsupported scalar spellings stays unchanged.
+
+Use the validated number text directly, without conversion through `int`, `int64`,
+or floating point. Textual versions need no machine-integer range limit beyond
+existing input resource limits. Numeric Go destinations retain their normal range
+checks. Preserve the public `Version` and `VersionRule` shapes: no new kind flag
+or opt-in field is needed.
+
+Checking remains before selected-profile application, defaults, typed decoding,
+resolution, and secret lookup. Callback warnings, errors, absent/null handling,
+safe diagnostics, and source attribution retain their current behavior.
+
+### Typed decoding
+
+At exactly the configured version path, an integer node may decode into a plain
+Go string descriptor, including a named string without custom text decoding and
+pointer wrappers around those types. The resulting string is the same text the
+version checker receives. This permits both integer and quoted version YAML when
+the application stores its version as a string.
+
+Other destination types retain ordinary decoding: an integer field can still
+decode integer YAML, but quoted strings are not coerced into integers. Dynamic
+`any` retains its usual scalar types and numeric bounds. This feature does not
+force every destination to become a string. Custom text codecs, durations, and
+secret-reference types gain no integer conversion, even if their path is the
+configured version path. Missing/null values and strict unknown-field validation
+also retain normal typed semantics; passing the checker does not bypass decoding.
+
+Unrelated fields, sibling fields with the same Go type, ancestors, descendants,
+and fields merely named `version` receive no coercion. Semantic path matching must
+respect escaped keys and contextual numeric tokens using existing path machinery.
+Do not alter pointer-versus-key/index distinctions by comparing field names alone.
+
+### Composition, inspection, and secrets
+
+Version ownership remains unchanged: imported fragments cannot supply the
+configured version, profiles cannot replace it or a covering ancestor, and CLI
+overrides cannot overlap it. No conversion may hide a composition conflict or
+weaken those checks.
+
+Keep the parsed input and retained history numeric when integer syntax was used.
+For a Go string destination, typed projection and effective YAML show a string;
+historical explanation should expose the existing decoding reconciliation event
+between numeric input and string output. Presence, source locations, origins,
+historical paths, and detached ownership remain intact. Do not represent this
+conversion as application resolution or invent a synthetic source.
+
+Existing sensitivity classification and redaction apply to both original and
+decoded snapshots. Conversion performs no environment access, invokes no codecs
+that previously required strings, and introduces no raw-value diagnostic text.
+
+## Intended architecture
+
+The current entry points are `checkVersion` in `validation.go`,
+`decodeLoadInput` in `load_result.go`, and `decodeConfiguration`/`decodeValue` in
+`decode.go`. The lifecycle in `load.go` already supplies the definition to both
+phases; retain its ordering.
+
+1. Share a small private integer-version text predicate/extractor between checking
+   and decoding, reusing the existing integer grammar. Do not extend the YAML
+   adapter or expose its node types.
+2. Carry an optional, per-load version-path capability into typed decoding through
+   private decode context. Follow it through recursive decoding, including
+   pointer, map, and dynamic-structure paths. Default private decoder callers
+   should remain strict unless they explicitly receive that capability.
+3. Apply the exception only when the current semantic path matches the configured
+   path, the source is an integer number, and the destination descriptor is a
+   plain string. All other cases use existing dispatch and errors.
+4. Let normal typed projection produce the final string representation. Retain
+   original input for provenance and explanation; avoid rewriting an assembled
+   document or cloning the entire tree solely to convert one scalar.
+
+Do not attach path-specific conversion to a shared type descriptor: descriptors
+can be reused by unrelated fields of the same Go type. Keep the capability local
+to one decoding operation, not global state or a public schema extension. Exact
+private context names/signatures are implementation choices, not API commitments.
+
+## Compatibility and completion
+
+Existing accepted strings keep their meaning. Newly accepted integers intentionally
+change the previous `version.type` rejection contract and cause application version
+checkers to run on inputs they previously never saw. Release review must account
+for that, rather than describing the change as entirely behavior-neutral. A
+pre-v1 minor release is the conservative choice under the
+[release policy](../policy/release.md); this roadmap chooses no tag and grants no
+patch-policy exception or publication authority.
+
+Completion requires end-to-end integer/string equivalence for a string-backed
+Notarius-shaped configuration, strict rejection outside the version exception,
+correct original/effective inspection, and retained version-ownership and secret
+safety guarantees. Update Go reference comments, the configuration contract, and
+consumer migration guidance as their behavior lands. Historical ADR rationale and
+published release notes remain unchanged. If an accepted ADR actually conflicts
+with the implementation decision, supersede it using the documentation policy;
+do not rewrite its accepted rationale.
+
+Once implemented, move target contracts to their canonical owners and replace
+duplicated roadmap text with links. Retire completed roadmap/plan documents during
+release preparation, preserving the execution record in Git history.