The for-each-ref ordering was pinned but its RELATION was never modelled

[gunbai-bot]

Raised by the operator on #9506, and the answer turned out to be more interesting than either "it is documented" or "it is not".

What was already right

git.Core.ForEachRefIn pins --sort=refname in its transport argv — the order is not inherited from a default, it is requested. There is a cited ExternalAuthority at git-scm.com/docs/git-for-each-ref. And extdeps.git.enumeration deliberately validates the order rather than imposing it, so the flag stays falsifiable: a decoder that sorted its own rows would make the pin decorative, and deleting --sort=refname would leave every witness green.

None of that changes here.

What was missing

Pinning the flag fixes the ORDER and says nothing about the RELATION — and a consumer has to reimplement that relation in order to check it. Ours does:

• git orders refnames bytewise. Refnames are byte strings; git-check-ref-format(1) constrains which bytes may appear and says nothing about an encoding.
• string_is_lexicographically_before -> string_lex_compare compares code points (code_point(char_at(s, 0)), recursing).

Those are two different relations from two different authorities, equated by adjacency. They do agree — because UTF-8 is order-preserving: a code point's encoding sorts, byte for byte, in the same relation as the code point itself. That is a property of the encoding, not of either comparator, and it was written down nowhere.

Why that is worth a change rather than a shrug

The check is correct today and reads as coincidence, which fails in a specific and nasty direction: make string_lex_compare locale-aware — an entirely reasonable-looking improvement — and the decoder starts refusing valid for-each-ref output with "ref names are not strictly increasing", a message that accuses git rather than the change that broke it. The reader who investigates begins at the wrong end.

So the relation is now stated at both ends: the upstream half beside the operation that pins the flag, and the mismatch named at the check that relies on it.

Two gaps declared rather than papered over

Non-UTF-8 refnames. git permits them; a code-point comparator has no defined relation to them. No refusal is claimed, because whether such a name survives the shell transport into a String at all is unestablished, and a wall whose reachability has not been measured is asserted coverage rather than a wall (§4b). The next rung here is a measurement, not a check — and saying so is the point, since the tempting move is to add a guard that might be permanently green.

No git version is pinned. ExternalAuthority carries a Uri and nothing else — there is no version field to pin one with. §3 asks an extdeps subject to declare its version, so this is a standing gap for the whole module, named here because sort semantics are exactly the kind of fact that is version-relative. Not fixed here: adding a version axis to ExternalAuthority touches every citation in the corpus and belongs in its own change.

Scope

Annotations only — no type, function, argv or emitted byte changes. Deliberately not folded into #9506, which consumes this decoder: a correction to a merged module should not arrive inside a feature that depends on it.

— sent from calm-ram-380