runnerrelease

type Freshness struct {
	// Installed is the version the fleet actually runs, as this package read it.
	//
	// REPORTED BY THE CALLER RATHER THAN ITS OWN COPY, which is the one-representation
	// rule this repository has been bitten by three times in internal/config: Resolve
	// normalizes what it was given (a leading "v", surrounding space) and answers about
	// the result, so a command printing the string it passed IN would attribute this
	// answer to a version it was not computed for.
	Installed string

	// Latest is the newest stable release, which is what a rebuild takes up. It is
	// NOT what the deadline is counted from.
	//
	// ITS PUBLICATION DATE IS DELIBERATELY NOT CARRIED. It decides nothing — the
	// deadline comes from FirstNewerPublished — so a field holding it would be one
	// nothing reads and one more value a caller could reach for by mistake, which
	// is exactly the substitution this package exists to remove.
	Latest string

	// FirstNewer is the earliest stable release newer than Installed — the one that
	// started GitHub's clock — and FirstNewerPublished is when it appeared. Both are
	// zero when nothing newer exists.
	//
	// EARLIEST BY PUBLICATION, NOT BY VERSION. A patch backported after a later
	// minor release is newer than Installed and did not start the clock; the
	// release that did is whichever appeared first.
	FirstNewer          string
	FirstNewerPublished time.Time

	// HistoryComplete says the walk finished because it had read everything it
	// needed, rather than because it ran out of budget.
	//
	// THREE WAYS IT IS TRUE and none of them is "read every release GitHub has": the
	// installed release was found (everything below it was published earlier and was
	// already available when it shipped), a page came back shorter than requested, or
	// an empty one did.
	//
	// WHAT IT PROMISES, EXACTLY: every release published after the installed one was
	// read, so FirstNewer and the deadline are settled. `Latest` is settled over that
	// plus the remainder of the page the installed release was on — which is where a
	// higher version published earlier realistically sits, and is free because those
	// records are already fetched. A higher version published earlier AND more than
	// one page further back would be missed, and the fleet would read as current
	// while sitting on an old maintenance branch; closing that costs a page per check
	// forever to catch a case nobody has produced.
	//
	// FALSE MEANS OLDER RELEASES WERE NEVER READ, and one of them could be newer than
	// Installed and published EARLIER than FirstNewer — the same thing that makes
	// stopping at the installed tag unsound (see maxPages). The true window would
	// then have opened before the one billet found, so the computed deadline is LATER
	// than the truth.
	//
	// WHICH DIRECTION THAT SPOILS IS THE POINT. An unseen earlier opener only moves
	// the deadline EARLIER, so Expired and Due can still only under-report: a proved
	// expiry stays a proof. What it costs is the other direction — "not expired" and
	// "current" are no longer conclusive — which is why a caller that would report
	// nothing-to-do has to look at this.
	//
	// In practice one page reaches back FIVE YEARS (measured), so this is false only
	// for a fleet whose runner predates everything two pages cover; such a runner is
	// expired many times over and the sound direction already says so. It is carried
	// because the claim has to match what was read, not because the gap is likely.
	HistoryComplete bool

	// InstalledKnown says the history billet read actually named Installed.
	//
	// THE THIRD ANSWER, AND IT DECIDES WHICH SENTENCES ARE PROOFS. False means the
	// installed release is older than everything fetched, so the true clock started
	// at or BEFORE FirstNewerPublished: Expired and Due stay sound (they can only
	// under-report), while Remaining is an over-estimate and must be spoken of as
	// "at most". Collapsing this into "current" is the false negative this package
	// exists to remove; collapsing it into "expired" would refuse a fleet that is
	// fine.
	InstalledKnown bool
}