entity

type Build struct {
	// ID is the build's own key: the runner-assigned id returned by
	// Trigger (e.g. a Buildkite build number). Opaque; never parsed or
	// derived by stovepipe.
	ID string `json:"id"`
	// RequestID is the Request this build validates (Build->Request
	// navigation; no reverse index from Request to its builds is needed).
	RequestID string `json:"request_id"`
	// Status is the build's lifecycle state.
	Status BuildStatus `json:"status"`
	// Version is used for optimistic locking. Versioning starts at 1 and
	// is incremented for each change to the object.
	Version int32 `json:"version"`
}

type BuildID struct {
	// ID is the runner-assigned identifier for the build.
	ID string `json:"id"`
}

type BuildIssue struct {
	// TaskID identifies the logical validation task, stable across builds and retries; it must be nonempty.
	TaskID string `json:"task_id"`
	// UnitID identifies the failed unit within the task; empty for a task-wide issue.
	// Repeated observations of the same condition use the same TaskID and UnitID.
	UnitID string `json:"unit_id"`
	// FixID is the opaque executor-provided repair identifier; empty means none is recorded.
	FixID string `json:"fix_id"`
	// Version is the optimistic-lock version, initially zero.
	Version int32 `json:"version"`
}

type BuildMetadata map[string]string

type BuildStatus string

type BuildStrategy string

type GetProjectStatusRequest struct {
	// Queue identifies the queue containing the validation request.
	Queue string
	// RequestID is the queue-scoped decimal identifier, empty when selecting by URI.
	RequestID string
	// ChangeURI identifies the exact commit under validation, empty when selecting by request ID.
	ChangeURI string
	// Projects limits results to the supplied consumer-defined project IDs; empty selects all recorded projects.
	Projects []string
	// PageSize is the maximum number of project results per page.
	PageSize int32
	// PageToken is an opaque continuation token for full project-result pagination.
	PageToken string
}

type GetProjectStatusResult struct {
	// RequestSummary is the authoritative validation projection selected by the lookup.
	RequestSummary RequestSummary
	// RepositoryValidationFact is the repository result when HasRepositoryValidationFact is true.
	RepositoryValidationFact ValidationFact
	// HasRepositoryValidationFact distinguishes a missing fact from a recorded green result.
	HasRepositoryValidationFact bool
	// ProjectResultsComplete reports whether the implementation has finished its project-result set.
	ProjectResultsComplete bool
	// ProjectValidationFacts contains recorded results in request order, or descending degree then ascending project ID when Projects is empty.
	ProjectValidationFacts []ValidationFact
	// NextPageToken continues requested-project result pagination when another page exists.
	NextPageToken string
	// UpdatedAtMs is the newest durable lifecycle or result timestamp represented by the response.
	UpdatedAtMs int64
}

type GetQueueStatusRequest struct {
	// Queue is the stable repo-and-ref namespace.
	Queue string
	// ChangeURI is an immutable commit URI; empty selects current enablement.
	ChangeURI string
}

type GetQueueStatusResult struct {
	// Queue is the selected repo-and-ref namespace.
	Queue string
	// Enablement is current enablement or enablement covering the requested commit.
	Enablement QueueState
}

type GetRequestHistoryByIDRequest struct {
	// ID is the queue-scoped identifier of the request.
	ID string
	// Queue is the logical queue containing the request and scopes the lookup.
	Queue string
}

type GetRequestHistoryByURIRequest struct {
	// URI is the exact VCS-agnostic commit URI associated with the request.
	URI string
	// Queue is the logical queue containing the request and scopes the lookup.
	Queue string
}

type IngestRequest struct {
	// Queue is the name of the queue whose head commit should be ingested.
	Queue string
	// HasEnablement distinguishes an explicit decision from ordinary ingestion.
	HasEnablement bool
	// Enablement is the optional explicit enabled or disabled setting.
	Enablement QueueEnablement
}

type IngestResult struct {
	// ID is the canonical decimal request identifier assigned within the selected queue.
	ID string
	// Enablement is the applied decision or the observed durable enablement.
	Enablement QueueState
}

type IssueEvent string

type IssueLog struct {
	// TaskID identifies the logical validation task.
	TaskID string `json:"task_id"`
	// UnitID identifies the validation unit; empty for a task-wide issue.
	UnitID string `json:"unit_id"`
	// Event identifies the opening or resolution.
	Event IssueEvent `json:"event"`
	// BuildID identifies the build where the issue was first seen or confirmed resolved.
	BuildID string `json:"build_id"`
	// TimestampMs is when the transition was first recorded, in Unix milliseconds.
	TimestampMs int64 `json:"timestamp_ms"`
}

type IssueState struct {
	// TaskID identifies the logical validation task and must be nonempty.
	TaskID string `json:"task_id"`
	// UnitID identifies the validation unit; empty for a task-wide issue.
	UnitID string `json:"unit_id"`
	// Status distinguishes open and closed issues.
	Status IssueStatus `json:"status"`
	// FirstSeenBuildID identifies the current or most recent opening.
	FirstSeenBuildID string `json:"first_seen_build_id"`
	// LastProcessedBuildID identifies the most recent build applied to this issue.
	LastProcessedBuildID string `json:"last_processed_build_id"`
	// LastChangedBuildID identifies the build responsible for the current open or closed status.
	LastChangedBuildID string `json:"last_changed_build_id"`
	// ChangedAtMs is the latest status transition's timestamp in Unix milliseconds.
	ChangedAtMs int64 `json:"changed_at_ms"`
	// Version is the positive optimistic-lock version; it never resets on reopening.
	Version int32 `json:"version"`
}

type IssueStatus string

type IssueTrackingPhase string

type IssueTrackingState struct {
	// RequestID is the newest accepted source request, compared by ingest order.
	RequestID string `json:"request_id"`
	// BuildID identifies the source build whose pass is underway or most recently completed.
	BuildID string `json:"build_id"`
	// NotificationID identifies the message that owns this reconciliation pass.
	NotificationID string `json:"notification_id"`
	// CursorTaskID identifies the current issue's task; active passes revisit it on continuation.
	// Empty with an empty CursorUnitID starts the phase's range.
	CursorTaskID string `json:"cursor_task_id"`
	// CursorUnitID identifies the unit at the cursor; empty is task-wide.
	CursorUnitID string `json:"cursor_unit_id"`
	// Finalize identifies a terminal reconciliation pass rather than an ordinary refresh.
	Finalize bool `json:"finalize"`
	// HasTaskWideIssues records whether this pass has encountered a task-wide issue.
	HasTaskWideIssues bool `json:"has_task_wide_issues"`
	// Phase distinguishes active, completed, and abandoned work.
	Phase IssueTrackingPhase `json:"phase"`
	// Version is the positive optimistic-lock version of this state.
	Version int32 `json:"version"`
}

type ListRequest struct {
	// Queue is the required configured queue containing the requests.
	Queue string
	// AcceptedAtOrAfterMs is the inclusive Unix millisecond bound when HasAcceptedAtOrAfterMs is true.
	AcceptedAtOrAfterMs int64
	// HasAcceptedAtOrAfterMs distinguishes an explicit lower bound from an omitted one.
	HasAcceptedAtOrAfterMs bool
	// AcceptedBeforeMs is the exclusive Unix millisecond bound when HasAcceptedBeforeMs is true.
	AcceptedBeforeMs int64
	// HasAcceptedBeforeMs distinguishes an explicit upper bound from an omitted one.
	HasAcceptedBeforeMs bool
	// PageSize is the maximum number of summaries, from 1 to 200; zero selects 50.
	PageSize int32
	// PageToken is an opaque continuation bound to the queue and resolved time window.
	PageToken string
}

type ListResult struct {
	// Requests contains summaries ordered by descending acceptance time, then descending bytewise request ID.
	Requests []RequestSummary
	// NextPageToken continues after the last returned key; empty means no further mapping was observed.
	NextPageToken string
}

type OpenIssue struct {
	// TaskID identifies the logical validation task and must be nonempty.
	TaskID string `json:"task_id"`
	// UnitID identifies the validation unit; empty for a task-wide issue.
	UnitID string `json:"unit_id"`
	// FirstSeenBuildID identifies the build where this opening of the issue was first observed.
	FirstSeenBuildID string `json:"first_seen_build_id"`
}

type ProjectFactByDegree struct {
	// URI is the commit containing the project result.
	URI string
	// Degree is the breakage degree in [0, 1], ordered highest first.
	Degree float64
	// Project identifies the fact and breaks equal-degree ties in ascending bytewise order.
	Project string
}

type Queue struct {

	// Name is the stable logical id for the queue. It should be unique within the system.
	Name string `json:"name"`

	// LastGreenURI is the queue's last-known-good commit: the most recent head at which
	// whole-repo validation recorded green (health degree 0). Empty until the first such outcome.
	LastGreenURI string `json:"last_green_uri"`

	// LastGreenRequestID is the request that established LastGreenURI. The bookmark only
	// moves forward: a green outcome adopts the pair only when this id is empty or older
	// than the candidate's, compared by ingest order via CompareRequestID.
	LastGreenRequestID string `json:"last_green_request_id"`

	// InFlightCount is the number of trunk validations admitted by process but not yet terminal.
	InFlightCount int32 `json:"in_flight_count"`

	// LatestRequestID is the request id of the newest head ingest accepted for this queue.
	// Empty until the first request is created. Coalescing compares IDs via CompareRequestID.
	LatestRequestID string `json:"latest_request_id"`

	// Enablement is the applied enabled/disabled state; empty means unregistered.
	Enablement QueueEnablement `json:"enablement"`

	// EnablementVersion is the queue-scoped enablement sequence; zero means unregistered.
	// Operational changes do not advance this sequence.
	EnablementVersion int64 `json:"enablement_version"`

	// EffectiveFromCommitURI is the inclusive immutable enablement boundary; empty for initial registration.
	EffectiveFromCommitURI string `json:"effective_from_commit_uri"`

	// EnablementChangedAtMs is the enablement application timestamp in Unix milliseconds.
	EnablementChangedAtMs int64 `json:"enablement_changed_at_ms"`

	// Version is the version of the object. It is used for optimistic locking.
	// Versioning starts at 1 and is incremented for each change to the object.
	Version int32 `json:"version"`
}

type QueueConfig struct {
	// Name uniquely identifies this queue within the system.
	// Referenced by Request.Queue.
	Name string `json:"name" yaml:"name"`
	// MaxConcurrent is the cap on concurrent in-flight validations for the queue.
	MaxConcurrent int32 `json:"max_concurrent" yaml:"max_concurrent"`
	// GateWaitDelayMs is the redelivery delay while the latest head waits for a slot.
	GateWaitDelayMs int64 `json:"gate_wait_delay_ms" yaml:"gate_wait_delay_ms"`
}

type QueueEnablement string

type QueueLog struct {
	// ID is the stable queue-scoped occurrence identity derived from QueueStateVersion.
	ID string
	// Queue is the stable repo-and-ref namespace.
	Queue string
	// TimestampMs is the application's timestamp in Unix milliseconds.
	TimestampMs int64
	// State is the committed enabled or disabled value.
	State QueueEnablement
	// QueueStateVersion is the positive version identifying the applied state.
	QueueStateVersion int64
	// EffectiveFromCommitURI is the inclusive immutable boundary; empty only at version 1.
	EffectiveFromCommitURI string
}

type QueueState struct {
	// Queue is the stable repo-and-ref namespace, at most 255 bytes.
	Queue string
	// State is enabled or disabled.
	State QueueEnablement
	// EffectiveFromCommitURI is the inclusive immutable boundary, at most 255 bytes; empty only at version 1.
	EffectiveFromCommitURI string
	// ChangedAtMs is the application timestamp in Unix milliseconds.
	ChangedAtMs int64
	// Version is the positive queue-scoped enablement sequence.
	Version int64
}

type QueueSummary struct {
	// Queue is the stable repo-and-ref namespace, at most 255 bytes.
	Queue string
	// State is the latest materialized enabled/disabled value.
	State QueueEnablement
	// QueueStateVersion identifies the applied enablement occurrence represented here.
	QueueStateVersion int64
	// EffectiveFromCommitURI is the inclusive immutable boundary; empty at state version 1.
	EffectiveFromCommitURI string
	// StateTimestampMs is the occurrence timestamp in Unix milliseconds.
	StateTimestampMs int64
	// Version is the positive optimistic-lock version of this projection.
	Version int64
}

type Request struct {

	// ID is the canonical decimal request identifier, unique within Queue.
	ID string `json:"id"`
	// Queue is the name of the queue (a named repo+ref) being validated. Together with ID it
	// identifies the request and is the stable handle the ingest caller supplies.
	Queue string `json:"queue"`
	// URI is the opaque, VCS-agnostic locator of the commit under validation, as produced by the
	// SourceControl extension.
	URI string `json:"uri"`

	// BuildStrategy is the validation scope process chose when admitting this request.
	BuildStrategy BuildStrategy `json:"build_strategy"`
	// BaseURI is the base URI to be used for this request when the strategy is incremental.
	// Empty for full builds and cold start.
	BaseURI string `json:"base_uri"`

	// State is the current state of the request in the pipeline.
	State RequestState `json:"state"`
	// TerminalBuildID is the build that established this request's terminal
	// state. It is empty when no build established the terminal state.
	TerminalBuildID string `json:"terminal_build_id"`
	// Version is the version of the object. It is used for optimistic locking.
	// Versioning starts at 1 and is incremented for each change to the object.
	Version int32 `json:"version"`
}

type RequestAcceptance struct {
	// Queue is the queue containing the request.
	Queue string
	// AcceptedAtMs is the original retained acceptance timestamp in Unix milliseconds and is positive.
	AcceptedAtMs int64
	// RequestID identifies the request within Queue and breaks timestamp ties bytewise.
	RequestID string
}

type RequestEvent string

type RequestHistory struct {
	// RequestID is the queue-scoped identifier of the request.
	RequestID string
	// Events are retained request-log events ordered by occurrence time and stable identity.
	Events []RequestLog
	// RequestSummary is the current lifecycle projection for this request.
	RequestSummary RequestSummary
}

type RequestLog struct {
	// ID is the stable identity of the occurrence within the request.
	ID string `json:"id"`
	// Queue is the logical queue containing the request and scopes RequestID.
	Queue string `json:"queue"`
	// RequestID identifies the request whose log contains this record.
	RequestID string `json:"request_id"`
	// TimestampMs is when the occurrence was first retained, in Unix milliseconds.
	TimestampMs int64 `json:"timestamp_ms"`
	// State is the durable request state recorded by a state record and is unset on an event record.
	State RequestState `json:"state"`
	// Event identifies the occurrence recorded by an event record and is unset on a state record.
	Event RequestEvent `json:"event"`
	// RequestVersion is the durable request version recorded by a state record and is zero on an event record.
	RequestVersion int32 `json:"request_version"`
	// OutcomeReason is the durable domain reason for a terminal request state and is otherwise unset.
	OutcomeReason RequestOutcomeReason `json:"outcome_reason"`
	// Metadata contains optional occurrence context; nil and empty maps are equivalent.
	Metadata map[string]string `json:"metadata"`
}

type RequestOutcomeReason string

type RequestState string

type RequestSummary struct {
	// RequestID is the canonical decimal request identifier, unique within Queue.
	RequestID string
	// Queue is the queue containing the request.
	Queue string
	// URI is the commit validated by the request.
	URI string
	// BaseURI is the incremental-validation baseline and is empty before selection or for a full build.
	BaseURI string
	// State is the current durable request lifecycle state.
	State RequestState
	// RequestVersion is the version of the request state represented by this summary.
	RequestVersion int32
	// StateTimestampMs is when the represented state was first retained, in Unix milliseconds.
	StateTimestampMs int64
	// AcceptedAtMs is the original acceptance timestamp in Unix milliseconds; zero means unknown and a positive value is immutable.
	AcceptedAtMs int64
	// ProjectResultsCompletedAtMs is the completion timestamp in Unix milliseconds; zero means unknown and a positive value is immutable.
	ProjectResultsCompletedAtMs int64
	// OutcomeReason is the reason for the represented state; empty means unavailable or inapplicable.
	OutcomeReason RequestOutcomeReason
	// Version is the optimistic-lock version of this materialized view.
	Version int32
}

type ValidationFact struct {
	// URI is the commit the fact describes, in the queue's VCS-agnostic locator
	// form. Unique per (queue, URI, project).
	URI string `json:"uri"`
	// Project is the scope the degree applies to. Empty means the whole
	// repository; named projects narrow the fact to part of it.
	Project string `json:"project"`
	// Degree is how broken the scope was, on the closed interval
	// [DegreeGreen, DegreeBroken]. A failed repository with project results has
	// DegreePartial; without project results it has DegreeBroken.
	Degree float64 `json:"degree"`
	// RequestID is the request that established the fact.
	RequestID string `json:"request_id"`
	// CreatedAt is the millisecond timestamp at which the fact was recorded.
	CreatedAt int64 `json:"created_at"`
}