88 lines
4.7 KiB
Markdown
88 lines
4.7 KiB
Markdown
# 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](../../validation.go) implements
|
|
sequence-token matching independently of the existing `schemaIndex` helper in
|
|
[schema.go](../../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](../release.md). They are separate from resolving R1; older
|
|
release validation is not evidence for a newly changed candidate.
|