realign

type Options struct {
	// Overlay is the published overlay the staged tree copies its eclasses and
	// profiles out of. It is READ here and never written:
	// every write this package causes lands under StagingRoot.
	Overlay, StagingRoot string

	// Depth is how far up the ladder the operator asked to go, passed through
	// unchanged. Prove never substitutes a depth of its own — a
	// realignment proved shallower than requested is a proof of something nobody
	// asked about, and one proved deeper spends machine time nobody agreed to.
	//
	// DepthNone is the zero value, and it covers no build gate at all: the ladder
	// then returns an empty list, nothing has FAILED, and this package reports a
	// proof of nothing as Passed. That vacuity is not resolved here, because the
	// depth is the operator's to choose and validate already answers a
	// depth nobody chose where it is chosen — ParseDepth refuses the empty string
	// rather than answering DepthNone, "so a mistyped config key cannot switch
	// validation off in silence". The command that registers --depth is therefore
	// the place that owes a realign run a depth worth having.
	Depth validate.Depth

	// StagedManifest answers, for the PUBLISHED package directory, the Manifest
	// content the staged tree must carry before a build gate can run in it.
	//
	// It is the seam `overlay validate --depth` already goes through, and this
	// package neither produces the bytes nor knows where they come from:
	// Manifest GENERATION lives in autoupdate, and validate accepts only what a
	// caller supplies. Nil means NOTHING TRAVELS — nothing is staged
	// and nothing is built — which is validate's rule verbatim rather than a
	// second one stated here.
	StagedManifest func(pkgDir string) ([]byte, error)

	// RequireIsolation is the operator's policy, carried and never asserted. The
	// refusal it governs lives inside RunBuildGates and fires only when the
	// request carries it; hardcoding a true here would refuse every build on a
	// host that cannot create the namespace, which is the ordinary case.
	RequireIsolation bool

	// LogDir is where the build's whole transcript is kept for whoever has to go
	// past the summary. Empty is still accepted — the gate's own reason then
	// says the log was not retained — but a FAILED gate with no log is the one
	// case where the summary is not enough.
	LogDir string

	// Distdir is the directory the build reads its archives from, carried into
	// the prepared build and set on the child as DISTDIR.
	//
	// Carried, never resolved: this package adds no rule of its own about where
	// archives come from, exactly as it adds none about depth or isolation. A
	// realignment is a SAME-VERSION edit, so no fetch of its own has produced an
	// archive — whatever directory already holds the release's tarball is the
	// command layer's answer to give.
	//
	// Empty sets nothing and invents nothing: the build then reads
	// the host's own configured DISTDIR, which is what every realign proof did
	// before this field existed.
	Distdir string

	// Deps are the process- and host-level seams the build gates run through,
	// passed to RunBuildGates untouched. Its zero value means "use the real
	// thing" — every field is normalised by validate itself — so a caller with
	// nothing to substitute passes nothing.
	Deps validate.BuildDeps
}

type Proof struct {
	// StagedRoot is the staged repository the gates read, outside the published
	// overlay. It is named on the proof rather than discarded because it is
	// the evidence: a maintainer asked to approve a realignment can read the exact
	// tree that was judged, and a failure nobody can inspect is a failure nobody
	// can act on.
	StagedRoot string

	// Gates are the ladder's results, in the order and the number it returned
	// them. Not filtered, not re-worded, not appended to: this package adds no
	// gate, so a Proof that carried a different list from the one the ladder
	// produced would be reporting an authority that does not exist.
	Gates []validate.GateResult

	// Passed is validate.PromotionDecision's answer over those gates — "every gate
	// reported PASS or SKIPPED" — and it is only ONE of the two conditions
	// publishing requires. The other is the maintainer's approval, which this package does
	// not ask for and this field must never be read as. Passing gates are a
	// permission to ask; they are not the answer.
	Passed bool
}

type Proposal struct {
	Category, Package, Version string
	Ebuild                     []byte
}