bot

type AnalysisCandidate struct {
	Move  game.Point
	Score int
	Bound ScoreBound
}

type AnalysisOptions struct {
	// Limits replace the guards the analysis searches under. A zero field
	// keeps the analysis default, which is the hint's: the highest-effort
	// levers the package has under a two-second guard.
	Limits Limits
	// OnComplete, when set, is called once for every deepening iteration that
	// finished, in order. It is not called for an iteration that was cut
	// short, for the ordering fallback that answers a search no iteration
	// finished, or for a win taken without searching: none of those is a
	// finished iteration.
	//
	// It runs synchronously inside the search, on the goroutine that called
	// Analyze, so blocking in it spends the search's own budget; and the game
	// it was called about is the search's working position, so it must not be
	// edited from here. The snapshot it is given is its own, and changing it
	// cannot change the search. Analyze does not keep the function after it
	// returns.
	OnComplete func(AnalysisProgress)
}

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

type AnalysisProgress struct {
	// Recommended is the best move of this iteration.
	Recommended game.Point
	// Candidates is this iteration's root list, best first, and belongs to the
	// observer: editing it cannot reach the search.
	Candidates []AnalysisCandidate
	// Stats is the work spent up to this iteration. StopReason is empty
	// because the search has not stopped.
	Stats SearchStats
}

type AnalysisResult struct {
	// Result is the result of the position analysed, and never the result of
	// the position the recommendation would produce.
	Result game.Result
	// Policy is the restriction the analysis ran under.
	Policy AnalysisPolicy
	// Before is the decomposition of the analysed position for the side to
	// move. On a finished game that is the side the game was left with: a
	// connection win does not hand the turn over.
	Before Terms
	// After is the decomposition once the recommended move is played, nil when
	// there is no recommendation.
	After *Terms
	// Recommended is the hole to play, nil for a finished game.
	Recommended *game.Point
	// Candidates are the root placements the search kept, best first. It is
	// empty for a finished game.
	Candidates []AnalysisCandidate
	// Reason is the code of the explanation — "advance", "only-defence",
	// "deadlock" and so on. It is empty for a finished game, which gets no
	// explanation at all.
	Reason string
	// Headline and Detail are the explanation in words, empty alongside an
	// empty Reason. They state only what the decomposition measured.
	Headline, Detail string
	// Highlight lists the holes the explanation refers to, the recommended one
	// first. It is empty for a finished game.
	Highlight []game.Point
	// Stats is what the search spent, nil for a finished game because no
	// search ran.
	Stats *SearchStats
}

type Bot interface {
	Tier() Tier
	// Move returns the hole to play. It never returns an illegal move.
	//
	// A deadline or a cancellation on ctx cuts the search short and Move
	// returns the best move it had reached, which is how a per-move budget is
	// enforced; it is not an error, and even an already-cancelled context
	// yields a legal move chosen by the ordering heuristic. An error means the
	// position cannot be searched: the game is over, there is nowhere left to
	// play, or the turn in progress has uncommitted edits.
	Move(ctx context.Context, g *game.Game) (game.Point, error)
	// Hint explains the move the bot would consider best for the side to move.
	// A hint is always computed with the highest-effort settings the package
	// has, whatever tier is playing, so that a beginner-tier game does not also
	// give beginner-tier advice.
	Hint(ctx context.Context, g *game.Game) (Hint, error)
}

type Hint struct {
	Move game.Point
	// Headline is one short line: what to play.
	Headline string
	// Detail is one to three short sentences saying why, in terms of the
	// numbers the search actually measured.
	Detail string
	// Highlight lists the holes the explanation refers to, for the board to
	// mark.
	Highlight []game.Point
	// Policy is the restriction the advice was produced under. Every hint this
	// package returns carries PlacementOnlyPolicy; the zero value states
	// nothing, which is what a stub or scripted bot leaves behind.
	Policy AnalysisPolicy
}

type Limits struct {
	// Nodes is the most nodes the search may visit across all its iterations.
	// Zero keeps the tier's own ceiling, which for every tier is none.
	Nodes int64
	// Depth is the deepest iteration the search may run. Zero keeps the tier's
	// own ceiling, and MaxDepth is the most the search can hold.
	Depth int
	// Time is a search-time guard, checked at work boundaries rather than a
	// hard real-time deadline. Zero keeps the tier's own budget.
	Time time.Duration
}

type ScoreBound string

type SearchProgress struct {
	// Generation counts the Move searches this engine has started, so a
	// reader can tell a new search from the one it looked at last. Zero means
	// none has started yet.
	Generation uint64
	// Started is when that search began.
	Started time.Time
	// Running is true from the moment the search starts until Move returns.
	Running bool
	// Completed says at least one deepening iteration finished, or a winning
	// hole was taken without searching. Depth, Recommended and Stats mean
	// something only when it is true: before then the only answer the search
	// has is the ordering heuristic's guess, and that is not a search.
	Completed bool
	// Depth is the deepest completed iteration, and zero for a win taken
	// without searching.
	Depth int
	// Recommended is the best move of the last completed iteration. It is the
	// search's own choice, before the beginner tier samples among the
	// alternatives, so it need not be the move Move returns on that tier.
	Recommended game.Point
	// Stats is the work as of the last completed iteration while Running is
	// true, with an empty StopReason because the search has not stopped. Once
	// Running is false it is what StatsOf reports for the same search.
	Stats SearchStats
}

type SearchStats struct {
	// Nodes is how many positions the search visited below the root, summed
	// over every iteration of its deepening loop.
	Nodes int64
	// Evaluations is how many positions it loaded and scored, root and threat
	// probes included, so it is normally larger than Nodes.
	Evaluations int64
	// Depth is the deepest completed iteration. Zero includes immediate wins
	// and searches interrupted before their first iteration completed.
	Depth int
	// Elapsed is how long the search took.
	Elapsed time.Duration
	// StopReason names what ended it: "immediate" for a winning hole taken
	// without searching, "depth" for every allowed iteration finished,
	// "decided" for a forced result inside the selective search tree (not a
	// proof about every legal TwixT continuation), "time" for the budget or the
	// caller's deadline, "nodes" for the node ceiling, "canceled" for a
	// cancelled context, "no-move" for a position with nowhere to play, and
	// "error" for a search that could not restore the position it was given.
	// The first three mean the search ended on its own terms and Depth is what
	// it reached; the rest mean it was cut short and Depth is the last
	// iteration it had completed.
	StopReason string
}

type Terms struct {
	// Dist is the cost of the side's cheapest chain still open to it: the pegs
	// it would place along that chain if nothing interfered. Zero means the
	// chain is complete; NoChain means the evaluation found no route left.
	Dist int
	// OppDist is the same count for the opponent.
	OppDist int
	// Bottlenecks counts the holes every one of the side's cheapest chains has
	// to run through, so a single opposing peg would set the plan back. Zero
	// means every step of the plan has an alternative.
	Bottlenecks int
	// OppBottlenecks is the same count for the opponent.
	OppBottlenecks int
	// Ground is how much more of the board the side can reach cheaply than the
	// opponent, in parts per thousand of the usable holes. It is negative when
	// the opponent has the wider reach.
	Ground int
}

type Tier int