ConfigKit/docs/roadmap/remediation.md

Integer schema version remediation

Review baseline: fd8a68d, covering implementation commits f5bbc2b through fd8a68d against b3e7b62. Status: finding resolved. This document records required corrective work, not an implemented contract or release approval.

R1 — Unify sequence-path interpretation between checking and decoding

Priority: medium. Status: resolved.

Resolution: sequence traversal now requires canonical nonnegative decimal index tokens in the shared schemaIndex helper. Version decoding reuses matchesPathShape, which shares that helper with traversal; its independent numeric matcher was removed. Signed tokens remain literal mapping keys but no longer alias sequence elements. Public-load regression coverage verifies numeric and quoted input, metadata lookup, mapping keys, and explicit segment intent. Focused Version/Decode/Path tests and the everyday checker passed on Linux.

Finding and evidence

The new pathMatches helper in validation.go implements sequence-token matching independently of the existing schemaIndex helper in schema.go. checkVersion looks up its node through documentAtPath, which uses schemaIndex; typed integer-to-string conversion instead uses pathMatches.

These rules disagree. schemaIndex currently accepts parsed +0 and -0 as sequence index zero through strconv.Atoi, but pathMatches requires the exact canonical spelling returned by strconv.Itoa, namely 0.

A public-API probe against the review baseline used a configuration with Versions []string bound to versions, a no-op version checker, and each path returned by ParsePath:

Configured path	YAML value	Checker receives	Load result
/versions/0	[4]	Present, text 4	Success
/versions/0	['4']	Present, text 4	Success
/versions/+0	[4]	Present, text 4	Decode failure
/versions/+0	['4']	Present, text 4	Success
/versions/-0	[4]	Present, text 4	Decode failure
/versions/-0	['4']	Present, text 4	Success

Thus the checker accepts and identifies a version node, but the decoder does not recognize that same node as the configured version path. Canonical index paths and the ordinary Notarius version mapping key work correctly. The permissive lookup predates these commits; the new, separately implemented matcher introduces the checker/decoder disagreement. The existing canonical-index tests do not catch it.

Required correction

Establish one sequence-token interpretation for version lookup and conversion, using shared semantic-path machinery rather than independent numeric spelling rules. Preserve explicit mapping-key versus index intent and exact string matching for mapping keys. Do not simply substitute a helper without checking its semantics: metadata matching also compares pointer spellings before interpreting indices.

Decide explicitly whether noncanonical signed sequence tokens are supported or rejected. If retaining current lookup behavior, decoding must identify the same node. If tightening it to canonical JSON Pointer sequence indices, apply that rule consistently to lookup and matching, document the compatibility impact, and ensure the checker cannot report a present version that conversion refuses to recognize. Do not broaden mapping-key matching or unrelated scalar coercion as a workaround.

Acceptance and verification

• Add public-load regressions for integer and string input with canonical and signed parsed sequence tokens, asserting checker presence/text and decoding outcomes under the chosen policy.
• Retain coverage for literal numeric/signed mapping keys, escaped keys, explicit Key/Index distinctions, and unrelated string fields.
• Verify lookup, version checking, and conversion share the chosen semantics; check other users of any shared path helper changed by the fix.
• Run go test . -run 'Version|Decode|Path', ./scripts/check.sh, and the full release checker before selecting a corrected release candidate.

Review validation and remaining release work

The full release checker passed on Linux at the review baseline with Go 1.25.5 and Go 1.26.7, including race tests, examples, documentation links, and cross-builds. The independent public-API probe above exposed behavior outside that suite. No production code or existing tests were modified during review.

Release selection, version-matched notes, retirement of completed roadmap material, and exact-candidate native Linux/macOS validation remain governed by the release procedure. They are separate from resolving R1; older release validation is not evidence for a newly changed candidate.