| Document | draft-fossil-submanifests-00 |
| Section | 8.1 — Emission Gate (a local request to enable while an out-of-range k is stored) |
| Type | Technical (the draft treats an invalid stored pin as absent; the implementation refuses to enable over it) |
| Status | Applied in draft-fossil-submanifests-00 (2026-10-19) |
| Reported | 2026-10-18 |
| Submitter | Dan Mestas |
| Found via | Testing go-libfossil's writer, written from the draft, against zit's enable path |
1. Summary
§8.1 says "an existing pinned k from 1 to 12 inclusive takes precedence" and "if no valid pin exists ... if no explicit value is supplied, the writer performs the automatic selection". A stored submanifest-k outside 1 to 12 is therefore no valid pin, and enabling proceeds as if the repository were unpinned. zit instead refuses the request and names the stored value. A value outside the range can only be the result of a hand edit or a defective writer; selecting a new value over it silently discards evidence of that, and the operator should see it. The draft should say what zit does.
2. The text in error
§8.1, second paragraph: "For a local request, an existing pinned k from 1 to 12 inclusive takes precedence. ... If no valid pin exists, an operator MAY supply an explicit k from 1 to 12 inclusive; if no explicit value is supplied, the writer performs the automatic selection of Section 6.3."
3. What the implementations do
zit (submanifestEnable in src/cmd/checkout.zig): a stored non-zero k
counts as pinned; the request without an explicit k takes the stored
value, finds it outside 1 to 12 and refuses with
k must be 1..12 (got N). A request with an explicit k from 1 to 12
replaces the stored value. go-libfossil followed the draft and treated
the invalid value as absent; it will follow the corrected text.
4. Corrected text
Add to §8.1, after "For a local request, an existing pinned k from 1 to 12 inclusive takes precedence.":
A stored submanifest-k outside that range is not a valid pin and is not treated as absent either: a request that supplies no explicit k MUST be refused with the stored value named, and automatic selection MUST NOT run over it. A request that supplies an explicit k from 1 to 12 inclusive replaces the stored value.
5. Observable consequence of the uncorrected text
A repository whose stored k was damaged enables under a freshly selected value with no indication that anything was wrong, in one implementation, and is refused in the other.
6. Implementations
zit already does this; no change. go-libfossil will follow the corrected text.