entity

type Batch struct {
	// ID is the globally unique identifier for the batch. Format: "<queue>/batch/<counter_value>".
	ID string

	// Queue is the name of the queue processing the land request. Queue name is defined in the configuration and should be unique within the system.
	Queue string

	// Contains is a list of land request IDs that are part of this batch.
	// Request IDs will always be part of the same queue.
	//
	// For e.g. - [queueA/1, queueA/2, queueA/3].
	//
	Contains []string

	// Dependencies is a list of other batch IDs that this batch depends on.
	// Dependencies will always be part of the same queue. This way batches form a directed acyclic graph (DAG).
	// If a batch A depends on batch B directly, it means that some request in batch A has overlapping changed targets with
	// some another request in batch B. The Dependencies list contains all the transitive closure of all the dependencies, both direct and indirect.
	// The order is not specified. Only active batches are considered for dependencies, i.e. if the batch is in a terminal state, it does not need to be included.
	// Because batch states are eventually consistent, dependent batches identified at the time of batch creation may move to terminal states. The interpretation logic
	// should reconcile batch states separately (i.e. ignore them for processing).
	//
	//This field is ok to be updated whether the state of the dependency graph changes. Update should use Version property for optimistic locking.
	//
	// Example: consider batches - queueA/batch/1, queueA/batch/2, queueA/batch/3
	// such that - queueA/batch/2 and queueA/batch/3 have overlapping targets with requests in queueA/batch/1, but queueA/batch/2 and queueA/batch/3 do not have overlapping targets with each other.
	//
	// In this case, the Dependencies field for -
	// - queueA/batch/1 will be empty
	// - queueA/batch/2 will contain queueA/batch/1
	// - queueA/batch/3 will contain queueA/batch/1
	Dependencies []string

	// Score is the predicted probability of build success for this batch, ranging from 0.0 to 1.0.
	// Set during the scoring phase. Zero value means the batch has not been scored yet.
	Score float64

	// The state of the batch lifecycle this batch is in. Updateable field with Version for optimistic locking.
	State BatchState

	// 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
}

type BatchDependent struct {
	// BatchID is the globally unique identifier of the upstream batch. Format: "<queue>/batch/<counter_value>".
	BatchID string

	// Dependents is a list of batch IDs that depend on this batch (i.e. batches whose Dependencies list contains BatchID).
	// Updated as new batches are created that conflict with this batch. Uses Version for optimistic locking on updates.
	Dependents []string

	// 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
}

type BatchID struct {
	// ID is the globally unique identifier for the batch.
	ID string `json:"id"`
}

type BatchState string

type Build struct {
	// ID represents the build ID. It is the responsibility of a build management system to ensure
	// that this is unique.
	ID string
	// BatchID is the batch for which this build is scheduled.
	BatchID string
	// SpeculationPath is the speculation path that represents this build. For
	// a given batch this path is crafted from the graph that is generated from the
	// dependencies of this batch.
	SpeculationPath SpeculationPathInfo
	// Score represents the build prediction score for this speculation path.
	Score float32
	// Status represents the state of the build lifecycle this build is in.
	Status BuildStatus
}

type BuildID struct {
	// ID is the globally unique identifier for the build.
	ID string `json:"id"`
}

type BuildMetadata map[string]string

type BuildStatus string

type CancelRequest struct {
	// ID is the globally unique identifier of the request to cancel. Format: "<queue>/<counter_value>".
	ID string `json:"id"`
	// Reason is an optional free-form explanation of why the cancellation was requested.
	Reason string `json:"reason"`
}

type Change struct {
	// URIs identifies the change(s) to land (RFC 3986 compliant).
	// The scheme identifies the change provider, and the path contains provider-specific resource identifiers.
	//
	// GitHub is supported by default (though other providers can be added):
	//   Template: "<scheme>://<org>/<repo>/pull/<pr>/<head_commit_sha>"
	//   Example:  "github://uber/submitqueue/pull/123/c3a4d5e6f7890123456789abcdef0123456789ab"
	//   Schemes:  "github", "ghe", "ghes". Head commit SHA must be full 40-char lowercase hex.
	//
	URIs []string `json:"uris"`
}

type ChangeProvider struct {
	// RequestID is the globally unique identifier for the land request. Format: "<queue>/<counter_value>".
	RequestID string
	// ChangeProviderSrc defines the source of the change. For e.g. - Github, Gitlab etc.
	ChangeProviderSrc string
	// ChangeProviderID is the identifier specified by the change provider source. For e.g. - Github PR ID etc.
	ChangeProviderID string
	// Metadata is the interesting data from the change provider that we want to store.
	// This is a freeform JSON object.
	Metadata map[string]string
}

type ChangeRecord struct {
	// URI identifies the change (RFC 3986). Same scheme/format as entity.Change.URIs.
	// Example: "github://uber/submitqueue/pull/123/c3a4d5e6f7890123456789abcdef0123456789ab".
	URI string `json:"uri"`

	// RequestID is the owning land request that claimed this URI.
	// Format matches entity.Request.ID: "<queue>/<counter_value>".
	//
	// RequestID participates in the change-store primary key so that concurrent claims
	// by different requests on the same URI coexist as distinct rows. Same-request
	// retries collide on the PK and are absorbed idempotently; different-request
	// collisions surface as additional rows that callers detect via FindOverlapping.
	RequestID string `json:"request_id"`

	// Queue is the queue the owning request belongs to. It is the leading column of
	// the change-store primary key, so queue-scoped duplicate checks become PK-prefix
	// scans and the table is shardable by queue.
	Queue string `json:"queue"`

	// Metadata is a JSON-encoded blob of provider-specific information about the change
	// (e.g., PR title, author, mergeable state). Stored as `'{}'` when no metadata has
	// been populated yet; updated by downstream enrichment.
	Metadata string `json:"metadata,omitempty"`

	// CreatedAt is the Unix milliseconds timestamp when this record was first created.
	CreatedAt int64 `json:"created_at"`

	// UpdatedAt is the Unix milliseconds timestamp when this record's Metadata was last updated.
	// Equal to CreatedAt when the record has never been updated.
	UpdatedAt int64 `json:"updated_at"`

	// Version is the optimistic-locking counter for mutable fields (Metadata).
	// Starts at 1 on Create and is incremented by callers on every update.
	// Mirrors the request-store convention: callers compute newVersion = oldVersion + 1
	// and pass both to the update method; the store performs a pure conditional write.
	Version int32 `json:"version"`
}

type LandRequest struct {
	// ID is the globally unique identifier for the land request. Format: "<queue>/<counter_value>".
	ID string `json:"id"`
	// Queue is the name of the queue processing the land request.
	Queue string `json:"queue"`
	// Change is the set of code changes to land.
	Change Change `json:"change"`
	// LandStrategy is the source control integration strategy to use for this land operation.
	LandStrategy RequestLandStrategy `json:"land_strategy"`
}

type QueueConfig struct {
	// Name uniquely identifies this queue within the system.
	// Referenced by Request.Queue.
	Name string `json:"name" yaml:"name"`

	// VCSType identifies the version control system (e.g., "git", "svn", "perforce").
	// A queue operates on exactly one VCS.
	VCSType string `json:"vcs_type" yaml:"vcs_type"`

	// VCSAddress identifies the repository in the version control system.
	// The format is VCS-specific:
	//   - Git: remote URL (e.g., "git@github.com:uber/submitqueue.git")
	//   - Perforce: depot path (e.g., "//depot/project")
	//   - SVN: repository URL (e.g., "https://svn.example.com/repos/project")
	VCSAddress string `json:"vcs_address" yaml:"vcs_address"`

	// Target is the landing target where changes are merged.
	// The format is VCS-specific:
	//   - Git: branch ref (e.g., "main", "release/v2")
	//   - Perforce: stream or depot path (e.g., "//depot/main/...")
	//   - SVN: repository path (e.g., "trunk/")
	Target string `json:"target" yaml:"target"`

	// BuildRunner identifies the CI pipeline or job that runs builds for this queue.
	// Opaque to the system; meaningful only to the build runner extension implementation.
	// Examples:
	//   - Buildkite: "buildkite.com/uber/submitqueue-ci"
	//   - Jenkins: "jenkins.example.com/job/submitqueue-verify"
	BuildRunner string `json:"build_runner" yaml:"build_runner"`

	// ChangeProvider identifies the change provider implementation for this queue.
	// Opaque to the system; meaningful only to the change provider extension implementation.
	// Examples: "github", "gitlab", "phabricator"
	ChangeProvider string `json:"change_provider" yaml:"change_provider"`

	// MergeChecker identifies the merge checker implementation for this queue.
	// Opaque to the system; meaningful only to the merge checker extension implementation.
	// Examples: "github", "gitlab"
	MergeChecker string `json:"merge_checker" yaml:"merge_checker"`

	// LandProvider identifies the land provider implementation for this queue.
	// Opaque to the system; meaningful only to the land provider extension implementation.
	// Examples: "github", "gitlab"
	LandProvider string `json:"land_provider" yaml:"land_provider"`
}

type Request struct {

	// ID is the globally unique identifier for the land request. Format: "<queue>/<counter_value>".
	ID string `json:"id"`
	// Queue is the name of the queue processing the land request. Queue name is defined in the configuration and should be unique within the system.
	Queue string `json:"queue"`
	// Change is a number of code changes (such as pull requests) to land into the target branch. Target branch is defined by the queue configuration.
	Change Change `json:"change"`
	// LandStrategy is the source control integration strategy to use for this land operation.
	LandStrategy RequestLandStrategy `json:"land_strategy"`

	// State is the current state of the land request.
	State RequestState `json:"state"`
	// 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 RequestID struct {
	// ID is the globally unique identifier for the land request.
	ID string `json:"id"`
}

type RequestLandStrategy string

type RequestLog struct {
	// RequestID is the ID of the request this log entry belongs to. References entity.Request.ID.
	RequestID string `json:"request_id"`
	// TimestampMs is the time this log entry was created, in milliseconds since Unix epoch.
	TimestampMs int64 `json:"timestamp_ms"`
	// Status is the request status at the time this log entry was created. It may contain requests states from the state machine and also display-friendly intermediate statuses.
	Status RequestStatus `json:"status"`
	// RequestVersion is the version of the request at the time this log entry was created.
	// Zero if the version is not available.
	RequestVersion int32 `json:"request_version"`
	// LastError is the last error message associated with the status at the time of this log entry.
	// Empty string if no error.
	LastError string `json:"last_error"`
	// Metadata is a set of key-value pairs providing additional context for this log entry.
	// Empty map if no metadata.
	Metadata map[string]string `json:"metadata"`
}

type RequestState string

type RequestStatus string

type SpeculationInfo struct {
	// Path represents the speculation path; which is an ordered list of batches.
	Path []string
	// Action is a state that this path is in.
	Action SpeculationPathAction
	// Score is score for this speculation path.
	Score float32
}

type SpeculationPathAction string

type SpeculationPathInfo struct {
	// Base is a list of batchIDs(in order) that form the base of this speculation path.
	Base []string
}

type SpeculationTree struct {
	// BatchID is the batch for which this speculation tree is constructed.
	BatchID string
	// Speculations is a list of speculation paths for this batch based on a graph of its
	// dependents.
	//
	// For e.g - Consider batches - queueA/batch/1, queueA/batch/2, queueA/batch/3
	// such that - queueA/batch/2 and queueA/batch/3 depend on queueA/batch/1
	//
	// Speculations for queueA/batch/1 - [{Path: []string{"queueA/batch/1"}, State: "scheduled", Score: 0.1}]
	// Speculations for queueA/batch/2 - [{Path: []string{"queueA/batch/2"}, State: "scheduled", Score: 0.9}, {Path: []string{"queueA/batch/1", "queueA/batch/2"}, State: "scheduled", Score: 0.3}]
	// Speculations for queueA/batch/3 - [{Path: []string{"queueA/batch/3"}, State: "scheduled", Score: 0.9}, {Path: []string{"queueA/batch/1", "queueA/batch/3"}, State: "scheduled", Score: 0.3}]
	//
	Speculations []SpeculationInfo
}