entity

type Author struct {
	// Name is the display name of the author.
	Name string `json:"name"`
	// Email is the email address of the author.
	Email string `json:"email"`
}

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

	// 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 BatchChanges struct {
	// BatchID is the batch being scored. Format: "<queue>/batch/<counter_value>".
	BatchID string
	// Queue is the queue the batch belongs to.
	Queue string
	// Changes is every change (URI + provider-supplied details) across all requests
	// in the batch. Order is unspecified.
	Changes []ChangeInfo
}

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"`
	// Queue is the name of the queue processing the batch. Empty on payloads written before the field existed.
	Queue string `json:"queue"`
}

type BatchOutcome struct {
	// BatchID is the input batch this outcome corresponds to.
	BatchID string
	// Outcomes is one entry per change in the batch, in apply order.
	Outcomes []ChangeOutcome
}

type BatchState string

type Build struct {
	// ID is the identifier minted by the queue's build runner when the build
	// is triggered; this is the primary storage key.
	ID string
	// BatchID is the batch for which this build is scheduled.
	BatchID string
	// PathID is the speculation path this build verifies, as carried by
	// SpeculationPathEntry.ID.
	PathID string
	// Attempt is which build attempt for that path this is, starting at 1.
	// A path may be built more than once, so ID names the run while
	// (PathID, Attempt) names the slot it occupies.
	Attempt int
	// 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"`
	// Queue is the name of the queue processing the batch this build verifies. Empty on payloads written before the field existed.
	Queue string `json:"queue"`
}

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"`
	// Queue is the name of the queue processing the request to cancel. Empty on payloads written before the field existed.
	Queue string `json:"queue"`
	// Reason is an optional free-form explanation of why the cancellation was requested.
	Reason string `json:"reason"`
}

type CandidatePath struct {
	// Path is the candidate: a head plus one assumption per dependency.
	Path SpeculationPath
	// RankingScore is the score the Generator ranked this candidate by. Higher
	// sorts first within the Generator's own ranking. Consumers take candidates
	// in iterator order and do not interpret the value. It is meaningful only
	// within the run that produced it, which is why it is never stored.
	RankingScore float64
}

type ChangeDetails struct {
	// Author is the author of the change.
	Author Author `json:"author"`
	// ChangedFiles is the list of files modified in this change. Order is unspecified.
	ChangedFiles []ChangedFile `json:"changed_files,omitempty"`
}

type ChangeInfo struct {
	// URI is the full change URI for correlation with the input request
	// (e.g., "github://github.example.com/uber/repo/pull/98/c3a4d5e6f7890123456789abcdef0123456789ab").
	URI string `json:"uri"`
	// Details is the provider-supplied facts for this URI.
	Details ChangeDetails `json:"details"`
}

type ChangeOutcome struct {
	// Change is the input change this outcome corresponds to.
	Change change.Change
	// Status describes whether the change produced commits or was already
	// present on the target branch.
	Status OutcomeStatus
	// CommitSHAs lists the commits this change produced on the target
	// branch, in apply order. A single Change may produce multiple commits
	// (e.g. a stack of PRs). Empty when Status is OutcomeStatusAlreadyExisted.
	CommitSHAs []string
}

type ChangeRecord struct {
	// URI identifies the change (RFC 3986). Same scheme/format as change.Change.URIs.
	// Example: "github://github.example.com/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 GetByURI.
	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"`

	// Details holds the provider-supplied facts about the change (author, changed
	// files, line counts). It is captured at claim time (the validate controller, after
	// fetching from the change provider) and written once with the record — records are
	// immutable, so Details is never updated after Create.
	Details ChangeDetails `json:"details"`

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

	// UpdatedAt is the Unix milliseconds timestamp when this record was created. Records
	// are immutable, so it always equals CreatedAt; retained for schema symmetry.
	UpdatedAt int64 `json:"updated_at"`

	// Version is the record version. Records are immutable, so it is always 1; retained
	// for schema symmetry with the other stores.
	Version int32 `json:"version"`
}

type ChangedFile struct {
	// Path is the file path relative to the repository root.
	Path string `json:"path"`
	// LinesAdded is the number of lines added in this file.
	LinesAdded int `json:"lines_added"`
	// LinesDeleted is the number of lines deleted in this file.
	LinesDeleted int `json:"lines_deleted"`
	// LinesModified is the number of lines modified in this file. Some providers
	// (e.g. GitHub) report only additions and deletions and leave this zero.
	LinesModified int `json:"lines_modified"`
}

type Conflict struct {
	// BatchID is the ID of the in-flight batch that conflicts with the
	// analyzed batch.
	BatchID string
	// Type classifies the conflict. A single (analyzed, in-flight) pair may
	// be reported with multiple Conflict entries when different conflict
	// types apply.
	Type ConflictType
}

type ConflictType string

type DependencyAssumption string

type GetRequestHistoryByChangeURIRequest struct {
	// ChangeURI is the exact change URI supplied in a Land request.
	ChangeURI string
	// Queue is the name of the queue to search. It scopes the lookup: a change URI
	// landed into several queues matches separately in each.
	Queue string
}

type GetRequestHistoryByIDRequest struct {
	// ID is the globally unique identifier of the request.
	ID string
	// Queue is the name of the queue processing the request. It scopes the lookup:
	// a request is only resolvable within its own queue.
	Queue string
}

type GetRequestSummaryByChangeURIRequest struct {
	// ChangeURI is the exact change URI supplied in a Land request.
	ChangeURI string
	// Queue is the name of the queue to search. It scopes the lookup: a change URI
	// landed into several queues matches separately in each.
	Queue string
}

type GetRequestSummaryByIDRequest struct {
	// ID is the globally unique identifier of the request. Format: "<queue>/<counter_value>".
	ID string
	// Queue is the name of the queue processing the request. It scopes the lookup:
	// a request is only resolvable within its own queue.
	Queue string
}

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.Change `json:"change"`
	// LandStrategy is the source control integration strategy to use for this
	// land operation. It applies to every URI of Change, the same way to each.
	LandStrategy mergestrategy.MergeStrategy `json:"land_strategy"`
}

type LandResult struct {
	// ID is the globally unique identifier assigned to the accepted land request.
	// Format: "<queue>/<counter_value>".
	ID string
}

type ListRequest struct {
	// Queue is the exact queue to query.
	Queue string
	// ReceivedAtOrAfterMs is the inclusive lower receipt-time bound in Unix milliseconds.
	ReceivedAtOrAfterMs int64
	// ReceivedBeforeMs is the exclusive upper receipt-time bound in Unix milliseconds.
	ReceivedBeforeMs int64
	// PageSize is the maximum number of results to return. Zero selects the server default.
	PageSize int32
	// PageToken is an opaque continuation token from a previous result.
	PageToken string
}

type ListResult struct {
	// Requests are ordered by receipt time descending, then request ID descending.
	Requests []RequestQueueSummary
	// NextPageToken is an opaque continuation token. Empty means this is the last page.
	NextPageToken string
}

type MergeResult struct {
	// Mergeable is true if the request's changes are expected to merge cleanly.
	Mergeable bool
	// Reason is a human-readable explanation when Mergeable is false.
	// Empty when Mergeable is true.
	Reason string
}

type OutcomeStatus string

type PathAction string

type PathBuild struct {
	// Queue is the name of the queue the path's head batch belongs to. It is
	// unique together with PathID and Attempt.
	Queue string
	// PathID is the speculation path, as carried by SpeculationPathEntry.ID,
	// unique within Queue.
	PathID string
	// Attempt is which build attempt for that path this is, starting at 1.
	Attempt int
	// BuildID is the build started for that attempt. Never empty.
	BuildID string
}

type PathDependency struct {
	// Batch is the dependency batch ID.
	Batch string
	// Assumption is what the path assumes about that dependency's outcome.
	Assumption DependencyAssumption
}

type PushResult struct {
	// Batches is one entry per pushed batch, in the same order as the batches
	// passed to the push. The slice length equals the input length.
	Batches []BatchOutcome
}

type QueueBatchState struct {
	// Queue is the name of the queue the batch belongs to. Queue name is defined in the
	// configuration and should be unique within the system.
	Queue string

	// State is the lifecycle state bucket this record files the batch under. Advisory:
	// the batch's authoritative state lives on the Batch entity and may differ transiently.
	State BatchState

	// BatchID is the globally unique identifier of the batch. Format: "<queue>/batch/<counter_value>".
	BatchID string
}

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

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.Change `json:"change"`
	// LandStrategy is the source control integration strategy to use for this
	// land operation. It applies to every URI of Change, the same way to each.
	LandStrategy mergestrategy.MergeStrategy `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 RequestBatch struct {
	// RequestID is the globally unique request identifier.
	RequestID string
	// BatchID is the globally unique identifier of the batch containing the request.
	BatchID string
	// Version is the version of the association. Immutable associations start at version 1.
	Version int32
}

type RequestHistory struct {
	// RequestID is the globally unique identifier of the request.
	RequestID string
	// Events are retained request-log events ordered chronologically.
	Events []RequestLog
}

type RequestID struct {
	// ID is the globally unique identifier for the land request.
	ID string `json:"id"`
	// Queue is the name of the queue processing the land request. Empty on payloads written before the field existed.
	Queue string `json:"queue"`
}

type RequestLog struct {
	// RequestID is the ID of the request this log entry belongs to. References entity.Request.ID.
	RequestID string `json:"request_id"`
	// Queue is the name of the queue processing the request. It is unique together
	// with RequestID: a request ID is only unique within its own queue.
	Queue string `json:"queue"`
	// 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 RequestQueueSummary struct {
	// RequestID is the globally unique request identifier.
	RequestID string
	// Queue is the queue supplied at receipt.
	Queue string
	// ChangeURIs are the change URIs supplied at receipt in caller order.
	ChangeURIs []string
	// ReceivedAtMs is the immutable receipt timestamp in Unix milliseconds.
	ReceivedAtMs int64
	// Status is the current customer-facing request status.
	Status RequestStatus
	// Version is copied from the authoritative RequestSummary and guards stale projection writers.
	Version int32
	// LastError is the error associated with the current status, or empty when absent.
	LastError string
	// Metadata is display and debugging metadata associated with the current status.
	Metadata map[string]string
}

type RequestState string

type RequestStatus string

type RequestSummary struct {
	// RequestID is the globally unique request identifier.
	RequestID string
	// Queue is the queue supplied at receipt.
	Queue string
	// ChangeURIs are the change URIs supplied at receipt in caller order.
	ChangeURIs []string
	// ReceivedAtMs is the immutable receipt timestamp in Unix milliseconds.
	ReceivedAtMs int64
	// Status is the current customer-facing request status.
	Status RequestStatus
	// RequestVersion is the orchestrator request version carried by the winning log entry, or zero when unavailable.
	RequestVersion int32
	// StatusTimestampMs is the timestamp of the winning log entry in Unix milliseconds.
	StatusTimestampMs int64
	// Version is the optimistic-lock version of this materialized view.
	Version int32
	// LastError is the error associated with the current status, or empty when absent.
	LastError string
	// Metadata is display and debugging metadata associated with the current status.
	Metadata map[string]string
}

type RequestURI struct {
	// ChangeURI is the exact canonical URI supplied at receipt.
	ChangeURI string
	// Queue is the name of the queue the request was received into. It scopes the
	// mapping: the same change URI landed into several queues maps separately in each.
	Queue string
	// ReceivedAtMs is the immutable receipt timestamp in Unix milliseconds.
	ReceivedAtMs int64
	// RequestID is the globally unique request identifier.
	RequestID string
}

type Speculation struct {
	// Path is the path the action applies to; its ID hashes the head and its
	// assumptions.
	Path SpeculationPath
	// Action is the proposed action (build or cancel).
	Action PathAction
}

type SpeculationPath struct {
	// Head is the ID of the batch being built along this path.
	Head string
	// Dependencies is one entry per dependency of Head, in queue order.
	Dependencies []PathDependency
}

type SpeculationPathEntry struct {
	// ID is the primary key: the hash of the path's content (head plus its
	// assumptions). It always equals Path.ID() — it is materialized here, rather
	// than recomputed from Path, because a stored record carries its own key:
	// lookups and comparisons read it without rehashing the path.
	ID string
	// Path is the head plus one assumption per dependency, in queue order.
	Path SpeculationPath
	// Status is the lifecycle status of the current build attempt.
	Status SpeculationPathStatus
	// Attempt is the build attempt number for this path, starting at 1. A path
	// can be built more than once (e.g. after a prior build is cancelled to free
	// budget, or fails and is retried), so ID alone does not identify an
	// execution — (ID, Attempt) does. It increments with each new build.
	Attempt int
	// 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
	// CreatedAtMs is the creation time in Unix epoch milliseconds.
	CreatedAtMs int64
	// UpdatedAtMs is the last-update time in Unix epoch milliseconds.
	UpdatedAtMs int64
}

type SpeculationPathSet struct {
	// Queue is the name of the queue the head batch belongs to. It is unique
	// together with Head.
	Queue string
	// Head is the ID of the head batch these paths speculate on, unique within
	// Queue. Every path in the set carries this same head.
	Head string
	// Paths is the head's chosen paths, live and recently finished.
	Paths []SpeculationPathEntry
	// 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 SpeculationPathStatus string