buildrunner

type BuildRunner interface {
	// Trigger submits a build that applies base then head, in order, on top
	// of the queue's target branch and validates the resulting tree.
	// Validation is implicit and holistic — it is what the runner does
	// after applying everything, not a per-change action.
	//
	// base contains changes from the dependency batches (an assumed-good
	// prefix). head contains changes from the batch being verified.
	// Splitting them lets a runner cache or short-circuit the base when
	// it has validated the same prefix before, and lets it attribute
	// terminal failure to base vs head in BuildMetadata.
	//
	// metadata carries free-form caller-supplied attributes (e.g. requester,
	// ticket ID, trace ID) that the runner MAY persist or echo back via
	// Status. Implementations MUST NOT depend on any specific key; nil is
	// equivalent to an empty map.
	//
	// Trigger MUST return promptly; runner-side work happens
	// asynchronously. Callers learn the build's progress via Status, not
	// via Trigger.
	//
	// queueName selects the runner-specific job configuration.
	// Returns an error if the request is invalid.
	Trigger(
		ctx context.Context,
		queueName string,
		base []entity.Change,
		head []entity.Change,
		metadata entity.BuildMetadata,
	) (buildID entity.BuildID, err error)

	// Status returns the current status and runner-defined metadata
	// (build URL, duration, etc.) for a build. Unlike Trigger, Status MAY be
	// synchronous and lengthy — a runner round trip is typical.
	//
	// Returns an error if the build does not exist.
	Status(
		ctx context.Context,
		buildID entity.BuildID,
	) (entity.BuildStatus, entity.BuildMetadata, error)

	// Cancel requests cancellation and returns once the request has reached
	// the runner; it does not wait for the build to actually stop. A no-op
	// on already-terminal builds. Returns an error if the build does not exist.
	Cancel(ctx context.Context, buildID entity.BuildID) error
}