waves

type ApplyOptions struct {
	// Set is the approved set plan document.
	Set *SetDocument
	// Approved is the approved set digest. Set must hash to it.
	Approved string
	// Waves is the set's split (from [Build] over Set).
	Waves *Document
	// Wave is the wave to apply, from 1.
	Wave   int
	Resume *Resume
	// Save writes the resume file. It is called after every root's
	// outcome is decided.
	Save   func(*Resume) error
	Runner ApplyRunner
}

type ApplyResult struct {
	ExitCode int `json:"exit_code"`
	Wave     int `json:"wave"`
	// Error is the refusal, for exit 1 and exit 3.
	Error string `json:"error,omitempty"`
	// Moved are the roots whose plans moved (exit 3); nothing was applied.
	Moved []Moved `json:"moved,omitempty"`
	// Outcomes are this run's outcomes for the wave's roots, including
	// those already landed before it ran.
	Outcomes []ResumeEntry `json:"outcomes"`
	// Applied are the roots this run applied, in order.
	Applied []string `json:"applied"`
}

type ApplyRunner interface {
	// PlanRoots plans every root afresh and returns one entry per root,
	// keyed by root. A root that fails to plan is an entry whose Status is
	// not "planned".
	PlanRoots(ctx context.Context, roots []string) (map[string]FreshPlan, error)
	// Apply applies planFile in root. A non-nil error is the root failing.
	Apply(ctx context.Context, root, planFile string) error
}

type Document struct {
	FormatVersion string `json:"format_version"`
	// Roots are the roots read, in directory order, with what each reads.
	Roots []Root `json:"roots"`
	Waves []Wave `json:"waves"`
	// Edges are every ordering constraint between two roots of the set.
	Edges []Edge `json:"edges"`
	// ExternalReads are reads of estates no root of the set owns.
	ExternalReads []External `json:"external_reads"`
	// Digest is the set digest over every root, present when plans were
	// given.
	Digest string `json:"digest,omitempty"`
	// RootDigests are each root's digest, present when plans were given.
	RootDigests map[string]string `json:"root_digests,omitempty"`
}

type Edge struct {
	Reader   string `json:"reader"`
	Producer string `json:"producer"`
	Estate   string `json:"estate"`
	From     string `json:"from"`
}

type External struct {
	Root   string `json:"root"`
	Estate string `json:"estate"`
	From   string `json:"from"`
}

type FreshPlan struct {
	RootPlan
	// PlanFile is the fresh plan's saved file, which is what is applied.
	PlanFile string
}

type Moved struct {
	Root     string `json:"root"`
	Approved string `json:"approved_digest"`
	Fresh    string `json:"fresh_digest"`
}

type Options struct {
	// Roots are the root directories as given, relative to BaseDir or
	// absolute. Empty means the roots of Set.
	Roots []string
	// BaseDir is what a relative root is relative to.
	BaseDir string
	// Canaries name roots by directory or estate.
	Canaries []string
	// Set, when non-nil, is the set plan document whose plans give every
	// wave its digest. It must name exactly the roots planned.
	Set *SetDocument
}

type Read struct {
	// Estate is the producer estate.
	Estate string `json:"estate"`
	// From is the data source that reads it, module-qualified when it is
	// declared inside one.
	From string `json:"from"`
}

type Resume struct {
	FormatVersion string `json:"format_version"`
	// SetDigest is the approved set this file belongs to. A file for
	// another set is refused.
	SetDigest string        `json:"set_digest"`
	Roots     []ResumeEntry `json:"roots"`
}

type ResumeEntry struct {
	Root    string `json:"root"`
	Wave    int    `json:"wave"`
	Outcome string `json:"outcome"`
	// Reason says why a root failed or was skipped.
	Reason string `json:"reason,omitempty"`
}

type Root struct {
	// Root is the root's directory as the set names it.
	Root string `json:"root"`
	// Estate is the estate the root owns.
	Estate string `json:"estate"`
	// Reads are the estates the root's configuration reads.
	Reads []Read `json:"reads,omitempty"`
}

type RootDigestEntry = setdigest.RootDigestEntry

type RootPlan = setdigest.RootPlan

type SetDocument = setdigest.SetDocument

type Wave struct {
	// Number counts from 1.
	Number int `json:"wave"`
	// Canary is true for the wave the explicit canaries form.
	Canary bool `json:"canary"`
	// Roots are the wave's roots, sorted.
	Roots []string `json:"roots"`
	// Edges are ordering constraints between two roots of this same wave.
	// Only the canary wave can have any.
	Edges []Edge `json:"edges,omitempty"`
	// Digest is the set digest over this wave's roots, when the roots'
	// plans were given.
	Digest string `json:"digest,omitempty"`
}

type Waves struct {
	Waves    []Wave     `json:"waves"`
	Edges    []Edge     `json:"edges"`
	External []External `json:"external_reads"`
	// WaveOf maps each root to its wave number.
	WaveOf map[string]int `json:"-"`
}