Documentation
¶
Overview ¶
Package pin is the version pin: the gate fifteen of §9's sixteen commands compare themselves against before reading a second file, and the edit the sixteenth makes to the file they read (§9, §11, ADR-0020).
The two live together because they are one fact read from its two ends. Check answers *may this binary act on this repository*; Declaration answers *what does the file say once `hyper project` has written what it derived*. A gate reading one spelling of `version:` and a writer producing another is the day a `project` leaves behind a repository its own binary Refuses, so the schema of the thing is stated once, here.
**Nothing here reads or writes a file.** Both doors take the declaration's bytes and answer a value: what a command does with the answer is internal/cli's, and where the bytes came from is internal/repository's. That is what lets the gate run before the repository is loaded at all, and what lets the writer be exercised over a byte string rather than a temp directory.
The Repository declaration's full schema — its `kind:`, its `retention:`, and unknown-key rejection — is internal/artefact's, which is where every artefact's schema is (§3, §4).
Index ¶
Constants ¶
const ( CodeMismatch = "version-pin-mismatch" CodeAbsent = "version-pin-absent" )
Codes the gate Refuses under (§12).
Variables ¶
This section is empty.
Functions ¶
func Declared ¶
Declared is the version pin these bytes carry, and "" where they carry none — no `version:` key, a value that is not a plain scalar, or a file that will not parse at all.
It is what decides whether `project` reaches the network: a pin already equal to the binary's version resolves nothing, and the digest already in the declaration is copied into every workflow (§11). Where it answers "" — the repository that has never been projected — the two differ and the checksum is resolved, which is the same act an upgrade performs.
It answers a value where Check answers a decision, and the two read one member through one struct so that *what the pin says* and *what the gate does about it* cannot come apart.
func Written ¶
Written is `hyper.yaml`'s bytes carrying version and digest — the two derived facts `hyper project` writes into the Repository declaration and nothing else in the tool writes at all (§3, §11, ADR-0020).
**The file is edited, never regenerated.** `retention:` is authored, the comments and the layout are the author's, and the whole-file rule that governs a projected workflow protects files that are *entirely* derived — so what happens here is two scalars replaced in place and every other byte carried through untouched. A declaration is a reviewed artefact that carries two derived facts, not a generated file.
present is false where the repository holds no `hyper.yaml` at all, and what it gets then is a declaration carrying `kind:`, `version:`, `digest:` and **no `retention:`**: a repository that has not stated a policy has not agreed to lose anything, and `project` does not author one on its behalf (§3).
It judges neither value. A version is what the binary says it is and a digest is what the release published, and the diff this writes is where both are read (§9, ADR-0020).
Source Files