report

type AutoupdateCheck struct {
	// Scanned is every package the run looked at, in the order it looked at
	// them, whether or not an update was found. It is what makes a package
	// that is up to date distinguishable from a package that was never
	// scanned.
	Scanned []PackageResult `json:"scanned"`
	// Plan is the pending updates the run intended to validate, including the
	// ones policy excluded. Dropping those would produce a reassuring tally
	// about the easy packages and say nothing about the rest. It is also the
	// denominator the tally is reconciled against.
	Plan []PlanEntry `json:"plan"`
	// Results is what the gates answered, one row per planned package the run
	// reached. For an interrupted run it covers only the packages reached
	// before the interrupt, and NotEvaluated is how many of the rest there
	// were.
	Results []ValidationRow `json:"results"`
	// Tally is the four counts taken over Plan. It stays HERE while Complete
	// and NotEvaluated moved up, and the asymmetry is the line between the two
	// halves: this check counts four validation outcomes, a manifest run counts
	// ok and failed, and one universal tally would either lose the four or
	// invent columns the other has no answer for.
	Tally Tally `json:"tally"`
	// DistfilesToFetch is how many packages this run has to hold a tarball
	// for: an upper bound per package, not a download count, since a distfile
	// the host already holds is not fetched again and a package with several
	// SRC_URI entries still counts once.
	//
	// It is the ONE run-level fact that could not be recomputed from anything
	// else here. It means "the packages this run takes past the shallowest
	// depth", and the model deliberately does not know the depth ladder's
	// ordering — Depth is a string spelled the way the flag spells it, with no
	// notion of which rung is deeper. So a renderer, or a reader of the JSON
	// export, cannot derive it from Plan: the producer must carry it across or
	// the number is lost.
	//
	// It matters because it is the figure an operator decides on. Every depth
	// above the shallowest reads the new archive, so on a metered connection
	// or a laptop this is what makes the answer no.
	DistfilesToFetch int `json:"distfiles_to_fetch"`
}

type CategoryCount struct {
	// Category is the atom's first half — "dev-lang", "app-editors" — as the
	// producer read it, never abbreviated.
	Category string `json:"category"`
	// Count is how many of the group's members are in that category.
	//
	// It carries no omitempty, and the zero is reachable in exactly one way: a
	// producer that established the entry without establishing its count. That
	// is worth being able to see, which is what dropping the key would prevent.
	Count int `json:"count"`
}

type CauseCount struct {
	Cause string `json:"cause"`
	Count int    `json:"count"`
}

type ComparePkg struct {
	// Package is the atom, "<category>/<package>", as an operator types it.
	//
	// The two halves are joined by the adapter rather than carried apart, for
	// the reason ManifestTarget.Package gives: every reader of this field
	// prints the atom, and carrying the halves separately would leave each
	// renderer to re-join them with a separator of its own — two renderers
	// spelling one package name differently is the disagreement a model exists
	// to make impossible.
	Package string `json:"package"`
	// Local is the version the overlay carries and Remote the version the
	// compared repository carries, each exactly as the producer read it.
	//
	// Either may be empty, and empty is a fact rather than a gap: a package the
	// remote carries no version of has no remote version to state, and a
	// placeholder invented here would be this type answering a question the run
	// did not. Which of the two is missing is also what OnlyLocal counts one
	// level up.
	//
	// The two are the group key: KeepGroup collects the kept packages whose
	// (Local, Remote) pair is identical, so these strings are compared for
	// equality rather than parsed. Nothing here or downstream normalises them —
	// a version the producer read as "1.2.3-r1" is not the same string as
	// "1.2.3", and pretending otherwise would merge two groups that differ.
	Local  string `json:"local_version"`
	Remote string `json:"remote_version"`
	// Status is how the two versions relate, in the producer's own vocabulary:
	// up to date, outdated, newer, not in remote, or an error reading either.
	//
	// It answers "how do the versions compare", which is a different question
	// from "what should be done about it" — that one is answered by which of
	// CompareRun's lists this entry is in, and by Verdicts one level up. The
	// producer counts the two axes separately and every compared package is
	// counted exactly once on each; deriving one from the other would silently
	// change what the other means.
	Status string `json:"status"`
	// Reading is whether anybody read the difference between the two versions,
	// as one of four words: not requested, not comparable, failed, read.
	//
	// Four values, because a review note's zero value covers reviews disabled,
	// no reviewer available, a reviewer that errored, and a finding that was
	// never a candidate — so "is the note empty?" cannot answer "did anybody
	// read this?", the question an operator asks before acting on a
	// recommendation to delete.
	//
	// It is separate from Diff: one says whether the files differ, the other
	// whether anyone explained the difference. The empty string is not one of
	// the four; the adapter maps every case to a word, and an unmapped
	// combination is a defect, not a blank cell.
	Reading string `json:"reading"`
	// Diff is what the content check found, drawn from a CLOSED vocabulary:
	// "+N/-M" for a measured difference, "identical", "not compared", or
	// "unreadable".
	//
	// The vocabulary is closed so that "no difference was found" can never be
	// read as "no comparison was made". Those two are the same blank cell in
	// the output this payload replaces, and they are opposite answers: one says
	// the overlay's copy is redundant, the other says nobody has established
	// anything about it.
	//
	// It is a formatted string rather than two ints on purpose. The magnitude
	// is meaningful only when a comparison ran and found a difference; a pair
	// of zeroes would be indistinguishable from a check that never ran, which
	// is the conflation the closed vocabulary exists to prevent. The numbers
	// the producer measured are what the adapter formats into the first form.
	Diff string `json:"diff"`
	// Reason is this entry's finding, in one line: why the run recommends what
	// it recommends, or why it could not decide.
	//
	// It is empty when the entry has nothing of its own to add — a package
	// whose recommendation follows from its Status and needs no sentence — and
	// that emptiness is load-bearing rather than incidental. A kept package
	// with an empty Reason carries no finding, and a package carrying no
	// finding is one that grouping may absorb; a package with a finding is
	// never absorbed into a group, because grouping compresses repetition and a
	// finding is not repetition. GroupKeep reads this field for exactly that
	// test.
	//
	// It is ONE LINE by construction, folded by the adapter, because a raw
	// newline in a row's detail corrupts both the plain writer and the Markdown
	// pipe table. Anything that will not survive being shortened belongs in a
	// section's lead or notes, which wrap, rather than in a row detail, which
	// is cut. What travels here is the whole folded string at no width budget:
	// the export carries every explanation in full, whatever the terminal it
	// was rendered at was able to show.
	Reason string `json:"reason"`
	// FurtherFindings is everything ELSE the run established about this
	// package: the second finding and every one after it, in the producer's own
	// words and at full length.
	//
	// Reason holds the FIRST and this holds the rest, because a row detail is
	// one line that a narrow device cuts; what does not fit a cell is said
	// beside it, in prose that wraps, under the block holding this package's
	// row. The package is NOT named in the text — the block names it — so no
	// second spelling of Package can disagree with the row beside it.
	//
	// Every entry is ONE LINE, folded by the adapter, and nothing is shortened.
	// Only an empty list says "the run established nothing further", and no
	// omitempty drops it: a package with a single finding is the common case.
	FurtherFindings []string `json:"further_findings"`
	// Cause is why this row failed, in the adapter's closed vocabulary: the
	// upstream lookup's cause on a row whose Status is "error", the review's
	// cause on a row whose Reading is "failed", "" on a row with no failure.
	// No omitempty, for the reason Error gives.
	Cause string `json:"cause"`
	// Error is the full text of that failure, folded to one line and scrubbed
	// of the run's credentials by the producer, and "" on a row with no
	// failure. It follows ManifestResult.Error (model.go): kept whole here,
	// never shortened; only a table cell may cut it.
	Error string `json:"error"`
}

type CompareRun struct {
	// Repository is the repository the overlay's packages were compared
	// against, in the operator's own words — "gentoo" for the ::gentoo tree.
	//
	// It is carried rather than assumed because a report is read after the run
	// that produced it is gone, and "outdated" means nothing without the tree
	// it is outdated against. Nothing here abbreviates it, decorates it with
	// the :: form or capitalises it: a repository name travels as the producer
	// spelled it, and every renderer prints the same string.
	Repository string `json:"repository"`
	// Scanned is how many packages the run read out of the overlay, InBoth how
	// many of those the compared repository also carries, and OnlyLocal how
	// many it carries no version of at all.
	//
	// They are FIELDS because a program holding the exported file cannot call a
	// method, and none is derived from another: the producer counts them on
	// different axes, so a subtraction here would invent an answer the run never
	// gave. A filter flag narrows none of them — a filtered row was evaluated,
	// the operator merely chose not to look at it.
	//
	// None carries omitempty: a dropped zero reads as "the producer never said",
	// and "the remote carries every package we do" is the healthy case that
	// would lose its zero.
	Scanned   int `json:"scanned"`
	InBoth    int `json:"in_both"`
	OnlyLocal int `json:"only_local"`
	// Redundant is every package the run recommends removing: the overlay's
	// copy adds nothing the compared repository does not already carry.
	//
	// It is the list an operator acts on destructively, which is why the entry
	// beside it carries a reading state and a diff cell rather than a bare
	// verdict — a recommendation to delete is only as good as the evidence that
	// somebody looked.
	//
	// A nil slice reaches the JSON export as null and an empty one as [], and
	// the two say different things: the first is a producer that established
	// nothing, the second a run that found nothing redundant. The renderer
	// rewrites neither into the other, so the adapter normalises every slice
	// here to non-nil and a consumer never has to tell "no rows" from "the
	// producer forgot".
	Redundant []ComparePkg `json:"redundant"`
	// NeedsRebase is every package ::gentoo moved ahead of while the overlay
	// carries changes of its own, so ours owes a bump AND a re-application of
	// the delta.
	//
	// It is its own list because its advice is its own: folding it into
	// Redundant would recommend deleting changes ::gentoo has no copy of — the
	// most expensive mistake this report exists to prevent — and folding it
	// into Keep would report the copy as earning its place while it falls
	// behind. `overlay compare` already printed this table (verdictSections in
	// internal/overlay/compare.go), so leaving the field out would have been a
	// regression.
	//
	// Nil versus empty says what it says on Redundant above.
	NeedsRebase []ComparePkg `json:"needs_rebase"`
	// Keep is every package the run recommends keeping, in the order the run
	// established them.
	//
	// It is the longest list a healthy overlay produces and the one KeepGroups
	// below compresses. The two are not alternatives: this holds every member,
	// one entry each, whatever the groups say, so a consumer that ignores the
	// groups still reads a complete list and a consumer that reads the groups
	// is not left re-deriving the membership it was handed.
	//
	// The ORDER is information rather than presentation, and nothing here or
	// downstream sorts it. What order the run established is the run's to
	// decide; a renderer that re-sorted would make two modes disagree about
	// what one run said.
	Keep []ComparePkg `json:"keep"`
	// KeepGroups is the sets of kept packages that share one version pair, as
	// the run established them.
	//
	// It is a field because it is the only place the exported document says a
	// large block of entries moves together; re-deriving it from the flat list
	// means re-implementing the rule — which pair counts, whether a package
	// carrying a finding may be absorbed, how ties break — and two
	// implementations of one rule is how a terminal and a file disagree.
	//
	// A group is never a group of one: grouping compresses repetition rather
	// than giving a single package a second name. Groups are ordered by member
	// count descending, ties broken by the first member's atom, so two runs over
	// one overlay produce byte-identical output.
	//
	// GroupKeep fills it, and it is the ADAPTER that calls GroupKeep, never
	// Sections: a group computed while rows are drawn would exist on a terminal
	// and nowhere in the exported file.
	KeepGroups []KeepGroup `json:"keep_groups"`
	// Unknown is every package the run reached no recommendation about — the
	// comparison failed, the remote answered nothing usable, or the package's
	// state was never recorded.
	//
	// It is deliberately its own list rather than an absence. A package that
	// fell out of the comparison and a package the comparison had no opinion
	// about would otherwise both be "not in any list", and only one of those is
	// something an operator should look at. Its entries carry the reason the
	// run could not answer, which is what turns a bucket into a finding.
	Unknown []ComparePkg `json:"unknown"`
	// Verdicts is the four-column tally: how many packages the run recommends
	// keeping, removing, rebasing, and how many it could not judge.
	//
	// It is the payload's own count and not the envelope's, which is the
	// asymmetry Run's doc comment states from the other side: "the run reached
	// the end of its plan" is answerable for any batch, while a tally is
	// counted in each command's own vocabulary and a universal one would either
	// lose a column or invent columns another command has no answer for.
	//
	// It is NOT derivable from the four slices above, and that is the point of
	// declaring it. Every scanned package carries a verdict, while the lists
	// hold only the packages that also exist in ::gentoo — 99 of the measured
	// run's 279 have no row in any of them — so a consumer summing the lists
	// answers a number smaller than the run's and has nothing to tell it so.
	// The summary section states that coverage gap in words for the same
	// reason.
	Verdicts VerdictTally `json:"verdicts"`
	// Unread is how many comparisons nobody read: a review that was never
	// requested, one that was attempted and failed, or a pair the content check
	// refused to compare.
	//
	// It is a run-level count because the per-package fact is already on each
	// entry (ComparePkg.Reading) and a total is what an operator reads before
	// deciding whether to trust the lists at all. "We checked and it matches"
	// and "nobody checked" are the two answers this whole payload exists to
	// keep apart; a report that stated the second only per row
	// would make an operator scanning 300 lines discover it by accident.
	//
	// It carries no omitempty for the reason the three counts above do not: a
	// run in which everything WAS read is the good case, and the good case is
	// the one that would lose its zero.
	Unread int `json:"unread"`
	// Notes is what the run has to say about ITSELF: the sentences no row
	// carries and no count states — the classification share, the baseline
	// review's coverage, a review that reached no model at all, the advice to
	// prune what is redundant.
	//
	// They are DATA rather than something the command prints beside the report
	// because an export re-derives its blocks from this payload: attached to the
	// terminal's sections only, every one of them reached the screen and none
	// reached an export, so the file was silently shorter than the screen.
	// Carried here, both paths read Sections and Sections reads this.
	//
	// They are SENTENCES, as ComparePkg.Reason is: a run-level summary names no
	// package to travel on, and no set of counts reconstitutes it. What this
	// type forbids is a sentence about the DEVICE, and none here mentions one.
	//
	// Null is a producer that never considered the question, [] a run that had
	// nothing to add; the adapter fills it either way, and no omitempty drops
	// it — a run with nothing to say still has to say so.
	Notes []string `json:"notes"`
	// ReadingFailures splits the failed readings among Unread by why each
	// review failed: one {cause, count} per cause, over the same population
	// Unread counts. The cause is a word the adapter spells, as it
	// spells Reading. No omitempty: a run with no failed review publishes an
	// empty list, which is the good case.
	ReadingFailures []CauseCount `json:"reading_failures"`
}

type GateFact struct {
	// Deciding reports that this gate participated in the verdict. A gate
	// that declined did not, and arrives false.
	Deciding bool
	// Passed reports that this deciding gate measured the bump and found
	// nothing wrong. It says nothing on a gate that did not decide.
	Passed bool
	// Failed reports that this deciding gate measured the bump and produced
	// an error finding.
	Failed bool
	// Cause is why a gate that did not decide declined: "candidate", "host",
	// or "" when its producer never said — validate.DeclineCause's value,
	// carried as a plain string so the boundary above stays uncrossed.
	//
	// Classify does NOT branch on it. It travels so the output can NAME the
	// cause, and so the rule has it in hand on the day it tightens.
	Cause string
	// ProvesSelectedDepth marks the ONE gate whose pass answers the depth the
	// policy selected for this bump. At most one fact in a slice carries it.
	//
	// It is a primitive fact for the same reason Cause is a plain string: the
	// depth->gate mapping lives in internal/autoupdate/validate (GateForDepth),
	// which a package under internal/common must not import. The adapter
	// resolves it and marks the fact; this package only reads the mark.
	//
	// Nothing carries it when the plan's depth cannot be parsed, or when no
	// gate stands for that depth — depth none, today. Both cases fall through
	// to Inconclusive rather than guessing a gate.
	ProvesSelectedDepth bool
}

type KeepGroup struct {
	// Label is the group's heading in the reader's own words. It is prose, not
	// a key: two groups may share one, and nothing matches on it.
	Label string `json:"label"`
	// Local and Remote are the version pair every member of this group shares —
	// the group's identity, and the only thing that decides membership.
	//
	// The JSON keys say "version" where the Go names do not, because the two
	// names have different readers: `.local_version` is how a consumer asks the
	// question, while the Go name sits beside a Label and a Members list where
	// no other reading is available. snapshot_run.go's Subvolumes carries the
	// same deliberate split in the other direction.
	Local  string `json:"local_version"`
	Remote string `json:"remote_version"`
	// Members are the atoms in this group, in the order the run established
	// them. The first one breaks ties when two groups have the same member
	// count, so this order is part of what makes the report byte-identical
	// across two runs over one overlay.
	//
	// A group always has at least two: a version pair with one member is an
	// ordinary row and never a group of one.
	Members []string `json:"members"`
	// ByCategory is how the group's members break down across categories —
	// "42 in dev-lang, 8 in app-editors" as values rather than as a sentence.
	//
	// It is a field rather than something a renderer counts off Members for the
	// reason the whole type is data: the export is read by a program, and a
	// breakdown that exists only in a renderer is a breakdown the exported
	// document does not carry. It is also what makes a group line useful
	// without expanding it — a count alone says how much was compressed, and
	// the breakdown says what was compressed.
	ByCategory []CategoryCount `json:"by_category"`
}

type Kind string

type ManifestRun struct {
	// Targets is every package the run was given, in the order it was given
	// them, whatever became of each.
	//
	// A nil slice reaches the JSON export as null and an empty one as [], and
	// the two say different things: the first is a producer that established
	// nothing, the second a run that was handed no target at all. Neither is
	// rewritten into the other on the way out.
	Targets []ManifestTarget `json:"targets"`
	// Ok is how many targets had their Manifest regenerated, and Failed is how
	// many did not.
	//
	// They are FIELDS although overlay.ManifestResult derives the same answers
	// with methods: that type is read by Go code, this one by a program holding
	// the exported document, and a count that exists only as a method is a
	// count the JSON export does not carry.
	//
	// They are established by the run, never summed from Targets: a dry run
	// marks every previewed target Success false, so a sum would report every
	// package failed in a run that invoked nothing. The adapter branches on the
	// preview BEFORE it counts, as Run.Complete's fact travels from the run.
	//
	// Neither carries omitempty: a dropped zero reads as "the producer never
	// said", and "no target failed" is the common case that would lose it.
	Ok     int `json:"ok"`
	Failed int `json:"failed"`
	// DryRun reports that the run was a preview: the targets below were
	// resolved and listed, and nothing was invoked for any of them.
	//
	// It is a fact about what the run DID, not about how it is displayed —
	// which is what earns it a place in a model that holds no presentation. It
	// is also the one thing that explains the shape of everything else here: on
	// a preview Ok and Failed are both zero while Targets is full, and without
	// this field a reader meeting those three numbers would have to guess
	// whether the run failed silently or never started. Sections states it in
	// words for the same reason.
	DryRun bool `json:"dry_run"`
}

type ManifestTarget struct {
	// Package is the atom, "<category>/<package>", as an operator types it.
	//
	// The two halves are joined by the adapter rather than carried apart,
	// because every reader of this field prints the atom: carrying them
	// separately would leave each renderer to re-join them with a separator of
	// its own, and two renderers spelling one package name differently is the
	// disagreement the model exists to make impossible.
	Package string `json:"package"`
	// Success reports that this target's Manifest was regenerated.
	//
	// It is false for a target that was merely previewed, and that reading is
	// the producer's: "did not succeed" covers "never attempted". Which of the
	// two happened is said by DryRun above, once for the run, rather than by a
	// third state per target — a distinction the run makes once cannot drift
	// between rows.
	Success bool `json:"success"`
	// Error is why this target failed, in the producer's own words, and empty
	// for a target that did not fail.
	//
	// It carries no atom: Package is right beside it, and a copy of the atom
	// in here would be printed twice on every failure line.
	Error string `json:"error"`
	// Output is what the failing command printed, verbatim — the diagnostic the
	// operator acts on, kept because by the time a report is rendered the
	// terminal that streamed it live is gone.
	//
	// It is populated only on failure, and that is the producer's decision
	// rather than this type's: the capture is unbounded, and a whole-overlay
	// run would otherwise hold one copy per target for no reader. Sections
	// states that omission rather than leaving a reader to wonder where a
	// successful target's output went.
	Output string `json:"output"`
}

type Mode string

type ModeInputs struct {
	// Flag is the --ui value, empty when the flag was not passed.
	Flag string
	// Env is the BENTOO_UI value, empty when the variable is unset. Per the
	// same convention tui.Enabled follows, an empty value means "not set".
	Env string
	// Config is the ui.mode configuration value, empty when the key is
	// absent. Absent must produce exactly today's behaviour.
	Config string
	// NoTUI is the opt-out layer, and the CALLER MUST FOLD ALL THREE OPT-OUTS
	// INTO IT:
	//
	//	NoTUI: noTUIFlag ||
	//		os.Getenv("BENTOO_NO_TUI") != "" ||
	//		os.Getenv("NO_COLOR") != ""
	//
	// All three, not just the flag. tui.Enabled returns false on THREE
	// opt-outs — the --no-tui flag, NO_COLOR and BENTOO_NO_TUI — and this
	// struct deliberately has no NO_COLOR field of its own. Drop NO_COLOR
	// from that expression and a user who set it, and configured nothing
	// about ui.mode, silently starts getting inline output where they get
	// plain today: precisely the change an unconfigured run must never see.
	//
	// It is applied as ModePlain at the flag layer, so --no-tui is an
	// alias for --ui=plain rather than a second mechanism competing with it.
	NoTUI bool
	// Interactive is the stdout-TTY answer ALONE — output.IsTerminal(), the
	// same probe tui.Enabled ends on.
	//
	// It is NOT tui.Enabled's full return value. That answer already folds
	// the opt-outs in, and folding them in twice would report an opted-out
	// run as a terminal that "cannot support" the mode, which is a false
	// sentence: the terminal was fine, the operator opted out. The opt-outs
	// go in NoTUI; the capability goes here.
	Interactive bool
}

type Outcome string

type PackageResult struct {
	// Package is the full atom, category/package.
	Package string `json:"package"`
	// Type is the tier the package resolved to, "bin" or "source". It is empty
	// when the current ebuild could not be read, and empty is meaningful:
	// nobody resolved it, so nothing may be assumed from it.
	Type string `json:"type"`
	// CurrentVersion is the version the overlay holds today.
	CurrentVersion string `json:"current_version"`
	// CandidateVersion is the version found upstream. It is present even when
	// it could not be ordered against CurrentVersion, because the unusable
	// value is exactly what a reader needs to fix the parser configuration.
	CandidateVersion string `json:"candidate_version"`
	// HasUpdate reports that CandidateVersion is newer than CurrentVersion. It
	// is false whenever the two could not be compared.
	HasUpdate bool `json:"has_update"`
	// NotComparable reports that the upstream value could not be ordered
	// against the current one. It is carried apart from HasUpdate so that a
	// broken parser is never read as "up to date".
	NotComparable bool `json:"not_comparable"`
	// Orphaned reports that the package no longer has any ebuild in the
	// overlay. When set, the version fields say nothing.
	Orphaned bool `json:"orphaned"`
	// FromCache reports that the upstream version was answered from cache
	// rather than fetched, which is why the run may not reflect a bump made in
	// the last few minutes.
	FromCache bool `json:"from_cache"`
	// Error is why the scan could not answer for this package, in full and
	// exactly as it was reported. It is empty when the scan succeeded, and a
	// string rather than an error because the model carries facts and has no
	// behaviour.
	Error string `json:"error"`
	// Requirements is the state of each package this bump requires (the
	// record's `requires`), in atom order, and empty for a record without them.
	// Always a key, like every field here: an absent key could not be told from
	// an unanswered one.
	Requirements []Requirement `json:"requirements"`
}

type Payload interface {
	// Sections returns the payload's blocks in the order they are meant to be
	// read. opts says what the report should SAY; nothing in it says how the
	// report should look.
	Sections(opts SectionOptions) []Section
}

type PlanEntry struct {
	// Package is the full atom, category/package.
	Package string `json:"package"`
	// CurrentVersion and CandidateVersion are the two ends of the bump. Both
	// are carried because the depth follows the distance between them, and a
	// reader checking the plan against the policy needs the two values the
	// classifier saw.
	CurrentVersion   string `json:"current_version"`
	CandidateVersion string `json:"candidate_version"`
	// Class is how far the bump moved — how the version distance was
	// classified.
	Class string `json:"class"`
	// Depth is the resolved depth, spelled the way the --depth flag and the
	// config key spell it, so a plan line can be typed back as a flag.
	Depth string `json:"depth"`
	// Reason names the input that decided the depth, in full, and quotes an
	// override's stated justification where one exists. It is never shortened
	// here; a renderer that lacks the room shortens its own copy.
	Reason string `json:"reason"`
	// Skipped marks an entry no gate will run for, because policy said so — a
	// depth of none, or a package type the run excludes. It travels with the
	// entry rather than being derived when the entry is shown, because the
	// reason has to travel with it, and because it is what separates Skipped
	// from Inconclusive in the tally.
	Skipped bool `json:"skipped"`
}

type Requirement struct {
	Package string `json:"package"`
	Version string `json:"version"`
	State   string `json:"state"`
}

type Row struct {
	// Cells are the record's values, one per column, in header order. A row
	// may hold fewer than the headers name — a value the run never
	// established — and it may hold more; Columns is what keeps the surplus
	// from being dropped.
	Cells []string
	// Detail is the row's reason, IN FULL. A writer with a width budget cuts
	// its own copy; a writer without one prints all of it.
	//
	// Empty means this row has nothing of its own to add, which is a decision
	// about content and not a sign that the report held no reason: a result
	// whose reason repeats its plan entry leaves this empty so the sentence is
	// printed once, while the report itself still carries the whole string.
	// Every writer omits an empty detail rather than printing a bare indent.
	Detail string
}

type Run struct {
	// Schema is the document's version, always SchemaVersion. It is written
	// even though every document this release produces carries the same
	// number, because a version a consumer has to infer from the keys present
	// is the situation schema 1 is already in.
	Schema int `json:"schema"`
	// Kind names the command that produced this document. It is what a
	// consumer branches on, and the only key that says what the payload
	// below is.
	Kind Kind `json:"kind"`
	// Title is the run's heading in the reader's own words — "Autoupdate
	// check", "42 targets". It is a label, not a discriminator: two runs may
	// share one, and a consumer that matched on it would be matching on prose.
	Title string `json:"title"`
	// Complete reports that the run reached the end of its plan. A run stopped
	// early — by an interrupt, or by a failure it could not continue past —
	// sets this false, and the report still holds everything established up to
	// that point.
	//
	// It has no omitempty, and that is load-bearing: a `false` dropped from the
	// document reads as "the producer never said", which is exactly the
	// conflation this field exists to remove.
	Complete bool `json:"complete"`
	// NotEvaluated is how many planned units the run never reached. It is zero
	// for a complete run, and for an interrupted one it is the number that
	// turns a short list into a stated gap rather than a silent one.
	//
	// It carries no omitempty for the same reason Complete does not.
	NotEvaluated int `json:"not_evaluated"`
	// Payload is the domain half, and it marshals NESTED under its own key.
	// The nesting is the whole point of the envelope: `.tally.proved` becomes
	// `.payload.tally.proved`, and every kind added after this one adds a
	// value to Kind rather than a key at the root. A payload flattened up
	// here would be schema 1 again, with Kind saying nothing about the shape
	// beside it.
	Payload Payload `json:"payload"`
}

type Section struct {
	// Title names the block. It is the only string a writer may decorate.
	Title string
	// Lead is what is said before the rows — the counts that tell a reader
	// what they are about to look at.
	Lead []string
	// Rows is the block's table. A section with no rows prints its lead alone,
	// which is how "nothing to validate" is said without an empty frame.
	Rows Table
	// Notes is what is said after the rows: what was left out and why, and
	// what the run did not do. An omitted row is stated here, never silent.
	Notes []string
}

type SectionOptions struct {
	// ShowAll lists the units a run found nothing to report about — the
	// packages already up to date — instead of only counting them. It is the
	// --all flag.
	//
	// False prints the count alone, and that is the default because those
	// units are the bulk of a large run: listing them unasked is most of why a
	// check that found four updates printed 348 lines.
	ShowAll bool
	// SkipPlan omits the section describing what the run intended to do. It
	// exists for exactly one caller: the on-screen report of a run whose plan
	// was already printed before the confirmation prompt, so the operator is
	// not shown the same list twice.
	//
	// An export must never set it. A record missing the plan answers no
	// question later, and the reader of the file is not the operator
	// who saw the plan go by on screen.
	SkipPlan bool
}

type SnapshotRun struct {
	// Subvolumes is every subvolume the run set out to operate on, in
	// configuration order, whatever became of each.
	//
	// The JSON key is singular on purpose: it names the question a consumer
	// asks — "which subvolume did this run operate on?" — while the Go name
	// names what the field holds, a list, because a run covers every subvolume
	// its configuration names.
	//
	// It is the PLAN, and Steps below is what the run reached; neither is
	// derived from the other. A failed create skips that subvolume's remaining
	// steps and a cancelled run never produces steps for the rest, yet this
	// field still names every subvolume, which is what lets a reader see WHICH
	// one is missing — the envelope's NotEvaluated says only how many.
	Subvolumes []string `json:"subvolume"`
	// Steps is every pipeline step that reached an outcome, in the order the
	// run established them.
	//
	// A nil slice reaches the JSON export as null and an empty one as [], and
	// the two say different things: the first is a producer that established
	// nothing, the second a run that ran no step at all. Neither is rewritten
	// into the other on the way out.
	//
	// The ORDER is information rather than presentation — "prune failed after
	// create succeeded" and "create failed and prune never ran" are different
	// runs, and position is the only thing that distinguishes them in a flat
	// list — so nothing here or downstream sorts it.
	Steps []SnapshotStep `json:"steps"`
	// Ok is how many steps did what they were asked, and Failed is how many did
	// not.
	//
	// They are FIELDS although the rows below could be walked to re-derive
	// them, for the reason ManifestRun.Ok gives at length: this document is
	// read by a program holding the exported file, and a program holding a file
	// cannot call a method. A count that exists only as a method is a count the
	// JSON export does not carry.
	//
	// Neither carries omitempty, and that is load-bearing: a zero dropped from
	// the document reads as "the producer never said", which conflates "no step
	// failed" with "nobody counted" — and a run in which everything succeeded
	// is the common case that would lose its zero.
	Ok     int `json:"ok"`
	Failed int `json:"failed"`
}

type SnapshotStep struct {
	// Subvolume is the subvolume this step operated on.
	//
	// It may be empty, and empty is a fact rather than a gap: a step that
	// sweeps a remote holding objects from every subvolume is not attributable
	// to one, and the producer leaves it blank to say so. Nothing here invents
	// a placeholder for it — a made-up "all" would be this type answering a
	// question the run did not.
	Subvolume string `json:"subvolume"`
	// Step is what the run was doing: create, prune, ship or gfs, in the
	// producer's own words.
	Step string `json:"step"`
	// Target is the ship destination this step served, and empty for a step
	// that serves no destination.
	//
	// It is the destination's NAME — the one configured for it, or the driver
	// word when it was left unnamed — and never its address. A ship target's
	// address carries a host, a user and a remote path, and this value travels
	// into a file an operator may attach to a bug report.
	//
	// That rule covers Subvolume, Step and Target, each a name this package
	// controls the shape of. It does NOT cover Error, which is producer stderr
	// taken verbatim and says so itself; claiming the whole type address-free
	// would be a false safety claim about the field most likely to carry one.
	Target string `json:"target"`
	// Success reports that the step did what it was asked.
	//
	// It is derived once, by the adapter, from the producer's own status word,
	// and the payload's counts are taken from THAT SAME expression — so the
	// word printed on a row and the number printed above it cannot describe
	// different runs.
	Success bool `json:"success"`
	// Error is why this step failed, in the producer's own words, and empty for
	// a step that did not fail.
	//
	// It carries the failing command's own stderr, taken verbatim and never
	// reworded: a rewritten diagnostic is one the operator cannot search for or
	// reproduce.
	//
	// VERBATIM CUTS BOTH WAYS: this field is the exception to Target's
	// no-address rule. A failed `btrbk ssh` send writes `user@host:/path`, so a
	// remote address CAN reach an export through here, and nothing scrubs it.
	// An export that includes a FAILED ship step should be read before it is
	// shared; redaction, if ever wanted, belongs at the producer that knows
	// which text is an address.
	//
	// It carries no subvolume and no step name: both sit beside it in this same
	// row, and a copy of either in here would print twice on every failure.
	Error string `json:"error"`
}

type Table struct {
	// Headers names each column. It may be empty — a table of bare rows is
	// still a table — and it may be shorter than a row is wide, which is what
	// Columns exists to survive.
	Headers []string
	// Rows are the records, in the order the run established them. Nothing
	// here is sorted, shortened or padded: order is a fact about the run, and
	// the other three are decisions a writer makes.
	Rows []Row
}

type Tally struct {
	// Proved counts the packages whose deciding gates all passed.
	Proved int `json:"proved"`
	// Errored counts the packages with at least one failing deciding gate.
	Errored int `json:"errored"`
	// Inconclusive counts the packages the toolkit could not evaluate, plus
	// the ones whose results named no cause. Both are limitations of the
	// toolkit rather than choices of the operator.
	Inconclusive int `json:"inconclusive"`
	// Skipped counts the packages policy said not to evaluate. "Nothing was
	// said" is never folded into Proved.
	Skipped int `json:"skipped"`
}

type ValidationRow struct {
	// Package is the full atom, category/package.
	Package string `json:"package"`
	// CandidateVersion is the version that was evaluated.
	CandidateVersion string `json:"candidate_version"`
	// Outcome is the one verdict that stands for the whole package, across
	// every gate that spoke for it.
	Outcome Outcome `json:"outcome"`
	// Depth is how far validation actually got, which is not always how far it
	// was asked to go — PlanEntry.Depth is the request. Both are needed to say
	// "compile was asked for, configure is as far as it got", because an
	// outcome has to name its own reach.
	Depth string `json:"depth"`
	// Reason is why this package earned this outcome, IN FULL: the gate's own
	// reason where there is one, otherwise the reason the run reported for the
	// depth or the plan. It is never shortened, never truncated and never
	// summarized in the model — that is a rendering decision, and doing it
	// here would make it a loss of data.
	//
	// A row that produced no verdict always carries a reason: a package
	// reported without one reads as a result.
	Reason string `json:"reason"`
	// SameReasonAsPlan reports that Reason repeats the plan entry's reason
	// word for word. The run sets it; a renderer uses it to print a reason
	// once instead of twice, and a differing reason is new information
	// that gets printed. It is computed where the two strings are both
	// in hand rather than by a renderer that would have to go looking for the
	// plan entry.
	SameReasonAsPlan bool `json:"same_reason_as_plan"`
	// Notes are facts about how the outcome was reached that no gate carries,
	// such as a vendor tarball generated for this check. They are printed with
	// the row whether or not its reason is.
	Notes []string `json:"notes"`
}

type VerdictTally struct {
	// Keep is how many packages the run recommends keeping.
	Keep int `json:"keep"`
	// Redundant is how many the run recommends removing, because the overlay's
	// copy adds nothing the compared repository does not already carry.
	Redundant int `json:"redundant"`
	// NeedsRebase is how many carry changes of ours on top of a version the
	// compared repository has since moved past: the overlay's work is worth
	// keeping and has to be re-applied.
	NeedsRebase int `json:"needs_rebase"`
	// Unknown is how many the run reached no recommendation about. It is never
	// folded into any of the three above: a package nothing is known about must
	// not be counted as one recommended for removal, which is the rule the
	// producer's own verdict table is written to guarantee.
	Unknown int `json:"unknown"`
}