[NopeCharon]

Summary

A package whose only orderable keys are pre-releases cannot be reached by any range, because a range sees a pre-release only when it names one at the same numbers. compat.glad = "*" (or "^0.0") against an index that publishes 0.0.0-651a425 alone failed with constraint '*' matches none of: [0.0.0-651a425] and nothing more. resolve_semver gave the exact-pin hint only for unorderable keys, and these keys are orderable, so they took the plain branch.

When every orderable key is a pre-release, the error now says why the range misses and offers the exact pin. The value is the highest pre-release:

error: dependency 'acme.rc': constraint '^1.0' matches none of: [1.0.0-rc.1, 1.0.0-rc.2]
  These keys are pre-releases, which a range matches only when it names a pre-release of the same version — pin one exactly:
    acme.rc = "1.0.0-rc.2"

When a package also publishes a release, the message is unchanged, because a range can reach the release. docs/05-dependencies.md (both languages) states the rule.

Closes #370.

Criteria

• e2e 196 (tests/e2e/196_version_identity_and_lock.sh), new section 4b:
  • * and ^0.0 over 0.0.0-651a425 alone: the error says why and shows acme.pre = "0.0.0-651a425".
  • Over 1.0.0-rc.1 and 1.0.0-rc.2: the pin offered is 1.0.0-rc.2.
  • The offered pin resolves: the build gets past resolution and fails at install, because no payload is seeded.
  • ^2 over 1.92.8 and 1.92.8-docking adds no pre-release hint.
• Both binaries were built on aarch64 Linux with the 2026.10.30.1 release binary. With the binary from main, e2e 196 fails at expected the error to say why '*' matches none. With the binary from this branch, e2e 196 passes, and so does e2e 69 (69_package_templates.sh, which also asserts matches none of).
• Other hosts and the rest of the e2e suite are left to CI.

Intersections

New rule or feature	Invariant it crosses	Test at the crossing
Pin hint when every orderable key is a pre-release	A range never reaches a pre-release it does not name (#363)	e2e 196 §1 (^1.92.8 never picks -docking), §4b
The hint's remedy is a bare exact key	A bare version equal to a published key addresses that key exactly	e2e 196 §2 and §4b (the offered pin resolves)
The hint beside the unorderable-key hint	Unorderable keys get their own pin line	e2e 196 §4 (unchanged)

Compatibility

Only the text of a resolution error changes. It gains two lines when every orderable key is a pre-release. Resolution itself is unchanged.

Checks before merging

• bash .github/tools/check_docs_style.sh, check_docs_structure.sh and check_version_pins.sh pass.
• python3 .github/tools/check_workflow_assertions.py passes (a step asserts what its name says).
• No commit on the branch carries an attribution trailer:
  git log origin/main..HEAD -i --grep='Co-Authored-By' prints nothing.
• The squash merge is given an explicit subject and body, so GitHub does not
  compose one from the branch's commits. Suggested subject: fix: a range that matches none of a package's pre-release keys names the pin that works.