member

type Carry struct {
	Card    string
	Attempt int
	Head    string
}

type Child interface {
	// Done says whether the child has ended.
	Done() bool
	// Result is how it ended: ok, the head it finished at (a work card;
	// "" when unknown), and the report (one paragraph, the child's own words).
	Result() Result
}

type Config struct {
	As string // the member's (reader's) name in the fleet (readers) table
	// Width is an override of the most cards it runs at once, a twin's. A
	// worker with none runs the width its fleet row names, read with its
	// queue every tick (the fleet row is the truth): a member's own row, a
	// reader's the row of the machine it is named for (reader-<m> runs at
	// m's width, sprint.ReaderMachine).
	Width  int
	Reader bool // run the readers-table loop instead of the fleet's
	// Room is asked once a tick before any child is started (a recovered card or a taken
	// one): ok false starts none that tick, with why said once when it begins and once when
	// it ends. nil asks nothing (docs/SPEC-SWARM.md, `member`, the disk floor).
	Room func() (ok bool, why string)
	// Now is the clock the work pass's progress is read on (BeatLoop); nil is time.Now.
	Now func() time.Time
	// Meter is the machine's one-second CPU samples, taken by a goroutine of the caller
	// (hostload.Sampler.Run); nil, or with no sample since the last beat, the beat
	// measures the machine itself.
	Meter *hostload.Sampler
	// Sleep waits between two harness starts (StartGap); nil starts them back to back
	// (the tests' member). Clock is the time it measures the gap by; nil is time.Now.
	Sleep func(time.Duration)
	Clock func() time.Time
	// Background takes the long work out of the pass: a launch's start, its result and its
	// push run apart from the pass that began them and are collected by a later pass, and
	// Wake says when one posted or a child exited. false (the tests' member) does each where
	// the pass asks for it, so a pass is one step.
	Background bool
	// Attempt asks the attempt decision over every work take's end (docs/SPEC-SPRINT.md
	// section 2, the attempt decision; the card's bars decide at the server whether it routes
	// the finish, never whether it is asked): the packet,
	// the child's RESULT.md as text and the finish's reason line in; the decision's card line
	// (decide.Decided) and the decision as one JSON record line out, both carried by the
	// finish. It is long (a backend's answer), so it runs in the end's long work, beside the
	// push, never in the pass. nil asks none.
	Attempt func(p Packet, result, reason string) (decided string, decision []byte, err error)
	// ResolveStep resolves a step line's commit (7 to 40 hex) on the card's branch
	// to one full sha (docs/SPEC-SPRINT.md, the verdict per step). nil resolves in
	// the clone StepClone names, or, when that is nil too, in the launch checkout
	// the member verb's --slots or --root names. A member with neither accepts a
	// 40-hex sha as itself and refuses a shorter prefix as unknown.
	ResolveStep func(branch, prefix string) (sha string, err error)
	// StepClone is the checkout whose branch holds the card's step commits.
	// nil discovers it from the process arguments (the member verb).
	StepClone func(p Packet) string
	// ScriptVerify makes this reader a script reader (docs/SPEC-SPRINT.md, the script read):
	// a read of a script card (CLASS: script) is first asked of it, with the card's program
	// and deadline; ok is an ok read, whose finding is the one line why, counted as all the
	// reads the card needs. Not ok is no verdict: the read goes on to a model child as any
	// read does. nil asks none.
	ScriptVerify func(p Packet, class cardhdr.Class) (ok bool, why string)
}

type Ender interface {
	Ended(p Packet, failed bool)
}

type Epocher interface {
	Epoch(epoch uint64)
}

type Finish string

type Member struct {
	// contains filtered or unexported fields
}

type Packet struct {
	Card       string   `json:"card"`
	Kind       string   `json:"kind"` // work or read
	As         string   `json:"as"`
	Primary    string   `json:"primary"`
	Stream     string   `json:"stream"`
	Attempt    int      `json:"attempt"`
	Gen        int      `json:"gen,omitempty"`
	Epoch      uint64   `json:"epoch"`
	Brief      string   `json:"brief,omitempty"`
	Rules      string   `json:"rules,omitempty"` // the held rules file the card names, "" when it carries its own (sprint.Packet)
	Fix        string   `json:"fix,omitempty"`
	Finding    string   `json:"finding,omitempty"` // a rework's: the readers' words that found the attempt before broken
	Why        string   `json:"why,omitempty"`     // a rework's: how the attempt before ended
	Notes      []string `json:"notes"`
	Branch     string   `json:"branch,omitempty"`
	Base       string   `json:"base,omitempty"`
	BaseHead   string   `json:"base_head,omitempty"`
	BaseFrom   int      `json:"base_attempt,omitempty"` // the attempt BaseHead is the head of
	Worker     string   `json:"worker,omitempty"`
	Head       string   `json:"head,omitempty"`
	WorkBranch string   `json:"work_branch,omitempty"`
	WorkBase   string   `json:"work_base,omitempty"`
	Report     string   `json:"report,omitempty"`
	// A work card's route, as the deal drew it (docs/SPEC-SPRINT.md, the deal's
	// route): the model the child runs on, its budget and deadline (seconds);
	// empty when the store has no route, and the member's own run.
	Route    string `json:"route,omitempty"`
	Model    string `json:"model,omitempty"`
	Tokens   string `json:"tokens,omitempty"`
	USD      string `json:"usd,omitempty"`     // the dollar budget per card, a decimal; "" for none (#5094)
	Harness  string `json:"harness,omitempty"` // the harness the route names (pkg/harness); "" is the member's --harness
	Deadline int    `json:"deadline,omitempty"`
	// RateRPM and RateConcurrent are the route's global limits when the coordinator set
	// them (nova-sprint routes limit): the runner's provider proxy then takes the budget from
	// the sprint's server before every model request; 0 is unlimited and nothing changes.
	RateRPM        int `json:"rate_rpm,omitempty"`
	RateConcurrent int `json:"rate_concurrent,omitempty"`
	// Tier is the tier the route was drawn from when the sprint decided it (a read's
	// read tier, a rework's --tier); empty when the brief's line 1 names it.
	Tier string `json:"tier,omitempty"`
	// A decide read's bars on p(defect), as the ask wrote them on the read card
	// (docs/SPEC-SPRINT.md section 6, the decide read); empty for a strings read.
	DecideBounce string `json:"decide_bounce,omitempty"`
	DecideReview string `json:"decide_review,omitempty"`
	// A work card's gate decision bars, as the deal wrote them on the work card
	// (docs/SPEC-SPRINT.md section 5, the gate verdict); empty for none.
	DecideGateFlaky       string `json:"decide_gate_flaky,omitempty"`
	DecideGatePreexisting string `json:"decide_gate_preexisting,omitempty"`
}

type PassTimes struct {
	Queue, Push, Report, Fill time.Duration
}

type Printer interface {
	Printed() time.Time
}

type Push struct {
	Sha     string // pushed: the full sha origin's branch now holds
	None    string // not pushed: why (the child committed nothing); the finish is failed, no commit
	Refused string // the push failed: git's own line; the finish is a failure
	PR      string // the pull request the member opened for the pushed head, "" when none
	PRNote  string // why a pull request the result asked for was not opened, "" when none was asked or it opened
}

type Pusher interface {
	Push(p Packet, r Result) Push
}

type Result struct {
	Ran     bool
	OK      bool
	Shaped  bool
	Verdict string // a work card's "ok" or "not-done"; a read's "ok", "broken", or "" when the reader gave none
	Head    string
	Report  string
	Title   string // the pull request the child asked for (gh pr create), "" when none
	Body    string
	// End is how a run that did not finish ended, as the child's harness said it:
	// EndProvider, EndBudget, EndDeadline, or "" (Judge puts it first in a failed
	// finish's reason). Usage is what it spent, one line (its budget and wall),
	// reported with the finish onto the attempt's record.
	End   string
	Usage string
	// Provider is why End is EndProvider, as native read it from the harness's own log
	// or transcript: the cause, `provider: class=<c> status=<n|-> msg=<words>`
	// (docs/SPEC-CARD-CONTRACT.md section 4; tla/CardContract.tla, ProviderFailure).
	// "" when the end was a launch the provider never accepted, which names no reason.
	Provider string
	// Staging is why End is EndStaging: the reason of native's STAGE FAIL line, the launch
	// refused before any child ran (tla/CardContract.tla, StageRefused).
	Staging string
	// Budget is which budget ended a run whose End is EndBudget, and at what count, as
	// native's NATIVE BUDGET line says it ("tokens 509,940 of 400,000, $0.03"); Judge
	// says it after the end (nova-tools #5094). "" when native named none.
	Budget string
	// Step is why a tree card failed at its first work step: `step <n> <verdict>: <words>`
	// (treeFinish; docs/SPEC-SPRINT.md, a card is a tree of steps). Judge names it as the
	// failed finish's reason; "" for every other card.
	Step string
	// Gate is where native's gate decision sent a not-done child's red gate, its NATIVE GATE
	// line's route (docs/SPEC-SPRINT.md section 5, the gate verdict): GatePreExisting, which
	// Judge names as the failed finish's reason with GateTests; GateGreen (its flaky failures
	// passed their rerun), which the reader of the result takes as the verdict ok; "" for none.
	Gate      string
	GateTests string
	// Carry is where a rework was staged, as native's STAGE CARRY line says it
	// (cardcontract.Carry.Words: the staged commit, the tip of its base branch, and whether
	// the work before it carried); the finish's report carries it, so the card's timeline
	// says it. "" for a first attempt and a read.
	Carry string
}

type Runner interface {
	// Start runs the packet as one child and returns a handle for it.
	Start(p Packet) (Child, error)
}

type ScriptVerifier struct {
	Mirror string
	Temp   string
	Git    string
	Run    func(ctx context.Context, dir string, argv []string) error
}

type Sprint interface {
	Run(args ...string) (code int, out []byte)
}

type Stopper interface {
	Stop() (pid int)
}

type Waiter interface {
	Wait() <-chan struct{}
}