ledgerdb

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 5, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AcknowledgePendingCompletionParams 

type AcknowledgePendingCompletionParams struct {
	Tier      string
	RequestID int64
	MessageID int64
}

type AcknowledgePoolRunnerSourceParams 

type AcknowledgePoolRunnerSourceParams struct {
	UpdatedAt string
	LeaseID   string
}

type Admission 

type Admission struct {
	ID         int64
	Mode       string
	Generation int64
	Provenance string
	Reason     string
	Actor      string
	ChangedAt  string
}

type AdvanceRolloutControllerParams 

type AdvanceRolloutControllerParams struct {
	ControllerPhase string
	ID              string
	ExpectPhase     string
}

type AdvanceRolloutNodeParams 

type AdvanceRolloutNodeParams struct {
	Phase           string
	Attempts        int64
	NextAttemptAt   string
	Blocker         string
	RollbackResult  string
	ExemptReason    string
	PriorRelease    string
	DispatchEpoch   int64
	ConvergedDigest string
	UpdatedAt       string
	RolloutID       string
	Node            string
	ExpectPhase     string
}

type ArchiveJobHistoryParams 

type ArchiveJobHistoryParams struct {
	LeaseID            string
	Tier               string
	Node               sql.NullString
	RunID              sql.NullInt64
	RequestID          sql.NullInt64
	Conclusion         sql.NullString
	FailureReason      string
	Disruption         string
	DisruptedAt        string
	ChosenProvider     string
	InstanceType       string
	Vcpu               int64
	Memory             int64
	Site               string
	PriceMicrosPerHour int64
	ImageCache         string
	CacheGeneration    string
	ActionsCache       string
	QueuedAt           string
	FinishedAt         sql.NullString
}

type AssignLeaseParams 

type AssignLeaseParams struct {
	Phase       string
	RunID       sql.NullInt64
	RequestID   sql.NullInt64
	HeartbeatAt string
	ExpiresAt   string
	ID          string
	Epoch       int64
}

type BackfillFailureReasonParams 

type BackfillFailureReasonParams struct {
	FailureReason string
	ID            string
}

type BackfillLeaseFailureReasonParams 

type BackfillLeaseFailureReasonParams struct {
	FailureReason string
	ID            string
}

type BindDeploymentParams 

type BindDeploymentParams struct {
	DeploymentID string
	BoundAt      string
}

type BindLeaseParams 

type BindLeaseParams struct {
	Node              sql.NullString
	ChosenProvider    string
	HolderIncarnation string
	ID                string
	Epoch             int64
}

type BindPoolRunnerJobParams 

type BindPoolRunnerJobParams struct {
	ActualRequestID int64
	RunID           int64
	JobID           string
	UpdatedAt       string
	LeaseID         string
}

type ClaimControllerParams 

type ClaimControllerParams struct {
	Holder    string
	ClaimedAt string
}

type ClaimPoolRunnerForRetirementParams 

type ClaimPoolRunnerForRetirementParams struct {
	UpdatedAt string
	LeaseID   string
}

type CompleteForceDestroyParams 

type CompleteForceDestroyParams struct {
	State       string
	CompletedAt string
	Generation  int64
	WasState    string
}

type CorrectProvisionalHistoryParams 

type CorrectProvisionalHistoryParams struct {
	Conclusion sql.NullString
	LeaseID    string
}

type CorrectProvisionalLeaseParams 

type CorrectProvisionalLeaseParams struct {
	Phase string
	ID    string
}

type CountCacheBlocksParams 

type CountCacheBlocksParams struct {
	Owner      string
	Repository string
}

type CountForceTargetsInStateParams 

type CountForceTargetsInStateParams struct {
	Generation int64
	State      string
}

type CountLiveWorkOnNodeParams 

type CountLiveWorkOnNodeParams struct {
	Node string
	Now  string
}

type CountOpenPerTierRow 

type CountOpenPerTierRow struct {
	Tier       string
	OpenLeases int64
}

type CredentialSweep 

type CredentialSweep struct {
	Region       string
	Path         string
	SweptAt      string
	Removed      int64
	RemovedTotal int64
	Kept         int64
	Unaccounted  int64
	ForeignNames int64
	Error        string
}

type DBTX 

type DBTX interface {
	ExecContext(context.Context, string, ...interface{}) (sql.Result, error)
	PrepareContext(context.Context, string) (*sql.Stmt, error)
	QueryContext(context.Context, string, ...interface{}) (*sql.Rows, error)
	QueryRowContext(context.Context, string, ...interface{}) *sql.Row
}

type DecideEnrollmentParams 

type DecideEnrollmentParams struct {
	State     string
	CertPem   string
	DecidedAt string
	Name      string
}

type DecommissionNodeParams 

type DecommissionNodeParams struct {
	DecommissionedAt   string
	DecommissionProven int64
	DecommissionActor  string
	Name               string
}

type DeleteAcknowledgedCompletionParams 

type DeleteAcknowledgedCompletionParams struct {
	Tier      string
	RequestID int64
	MessageID int64
}

type DeleteCacheBlockParams 

type DeleteCacheBlockParams struct {
	ScopeType  string
	Owner      string
	Repository string
}

type DeleteMovedScaleSetParams 

type DeleteMovedScaleSetParams struct {
	Org         string
	ScaleSetID  int64
	RunnerGroup string
	Label       string
}

type DeleteRetiredCompletionParams 

type DeleteRetiredCompletionParams struct {
	Tier      string
	RequestID int64
	MessageID int64
}

type DeleteScaleSetParams 

type DeleteScaleSetParams struct {
	Org         string
	RunnerGroup string
	Label       string
}

type ExpireLeaseParams 

type ExpireLeaseParams struct {
	ExpiresAt string
	ID        string
}

type FenceQuarantinedLeaseParams 

type FenceQuarantinedLeaseParams struct {
	Phase string
	ID    string
	Epoch int64
}

type FinishRolloutParams 

type FinishRolloutParams struct {
	State          string
	FinishedAt     string
	TerminalReason string
	ID             string
	ExpectState    string
}

type FleetClaimHolderParams 

type FleetClaimHolderParams struct {
	Fleet string
	Name  string
}

type ForceDestroy 

type ForceDestroy struct {
	Generation          int64
	AdmissionGeneration int64
	State               string
	Reason              string
	Actor               string
	RequestedAt         string
	CompletedAt         string
}

type ForceTargetsRow 

type ForceTargetsRow struct {
	LeaseID          string
	Tier             string
	Node             string
	RunID            string
	SchedulerRequest int64
	Phase            string
	State            string
	Detail           string
}

type HeartbeatLeaseParams 

type HeartbeatLeaseParams struct {
	HeartbeatAt string
	ExpiresAt   string
	ID          string
	Epoch       int64
}

type HoldLeaseParams 

type HoldLeaseParams struct {
	Phase             string
	HeldAt            string
	HeartbeatAt       string
	ExpiresAt         string
	HolderIncarnation string
	ID                string
	Epoch             int64
}

type InsertEnrollmentParams 

type InsertEnrollmentParams struct {
	Name        string
	Fingerprint string
	CsrPem      string
	State       string
	RequestedAt string
}

type InsertForceDestroyParams 

type InsertForceDestroyParams struct {
	Generation          int64
	AdmissionGeneration int64
	State               string
	Reason              string
	Actor               string
	RequestedAt         string
}

type InsertForceDestroyTargetParams 

type InsertForceDestroyTargetParams struct {
	Generation       int64
	LeaseID          string
	Tier             string
	Node             string
	RunID            string
	SchedulerRequest int64
	Phase            string
	State            string
}

type InsertJoinTokenParams 

type InsertJoinTokenParams struct {
	TokenSha256   string
	Note          string
	UsesRemaining int64
	CreatedAt     string
	ExpiresAt     string
}

type InsertLeaseParams 

type InsertLeaseParams struct {
	ID                 string
	Tier               string
	TargetNode         sql.NullString
	MacosSlot          int64
	GuestOs            string
	Providers          string
	Phase              string
	Vcpu               int64
	Memory             int64
	RequestedVcpu      int64
	RequestedMemory    int64
	InstanceType       string
	Site               string
	PriceMicrosPerHour int64
	CreatedAt          string
	HeartbeatAt        string
	ExpiresAt          string
}

type InsertPoolRunnerParams 

type InsertPoolRunnerParams struct {
	LeaseID         string
	Tier            string
	LaunchRequestID int64
	RunnerID        int64
	RunnerName      string
	Status          string
	UpdatedAt       string
}

type InsertRolloutNodeParams 

type InsertRolloutNodeParams struct {
	RolloutID string
	Node      string
	Phase     string
	UpdatedAt string
}

type InsertRolloutParams 

type InsertRolloutParams struct {
	ID              string
	Generation      int64
	Channel         string
	TargetVersion   string
	TargetDigest    string
	Policy          string
	ControllerPhase string
	PriorVersion    string
	State           string
	CreatedBy       string
	CreatedAt       string
}

type IssuedCert 

type IssuedCert struct {
	Serial   string
	Node     string
	Source   string
	NotAfter string
	IssuedAt string
}

type ListAppliedMigrationsRow 

type ListAppliedMigrationsRow struct {
	Version  int64
	Name     string
	Checksum string
}

type ListAttributedFailuresParams 

type ListAttributedFailuresParams struct {
	Succeeded string
	Since     string
	MaxRows   int64
}

type ListAttributedFailuresRow 

type ListAttributedFailuresRow struct {
	LeaseID       string
	Tier          string
	Node          string
	RunID         int64
	Result        string
	FailureReason string
	Disruption    string
	DisruptedAt   string
	ResultAt      string
}

type ListBarrierRunsRow 

type ListBarrierRunsRow struct {
	Node               string
	NodeEpoch          int64
	DispatchGeneration int64
	EmptySince         string
	ObservedAt         string
}

type ListCodeBuildRegistrationPathsRow 

type ListCodeBuildRegistrationPathsRow struct {
	Name             string
	CodebuildRegion  string
	CodebuildJitPath string
	DecommissionedAt string
}

type ListExpiredLeasesParams 

type ListExpiredLeasesParams struct {
	Cutoff  string
	MaxRows int64
}

type ListExpiredLeasesRow 

type ListExpiredLeasesRow struct {
	ID                 string
	Tier               string
	Node               sql.NullString
	TargetNode         sql.NullString
	MacosSlot          int64
	ChosenProvider     string
	Phase              string
	Vcpu               int64
	Memory             int64
	RequestedVcpu      int64
	RequestedMemory    int64
	InstanceType       string
	Site               string
	PriceMicrosPerHour int64
	ImageCache         string
	CacheGeneration    string
	ActionsCache       string
	HeldAt             string
	ForceRelease       int64
	HolderIncarnation  string
	FailureReason      string
	Disruption         string
	DisruptedAt        string
	Epoch              int64
	RunID              sql.NullInt64
	RequestID          sql.NullInt64
}

type ListFleetClearanceRow 

type ListFleetClearanceRow struct {
	Name               string
	Live               int64
	Epoch              int64
	DispatchGeneration int64
	WireVersion        int64
	DecommissionedAt   string
	DecommissionProven int64
	DecommissionActor  string
}

type ListForceDestroyCandidatesParams 

type ListForceDestroyCandidatesParams struct {
	Tier string
	Node string
}

type ListForceDestroyCandidatesRow 

type ListForceDestroyCandidatesRow struct {
	ID        string
	Tier      string
	Node      string
	Phase     string
	RunID     string
	RequestID int64
	Since     string
}

type ListHeldLeasesParams 

type ListHeldLeasesParams struct {
	Custody    string
	Teardown   string
	Quarantine string
}

type ListHeldLeasesRow 

type ListHeldLeasesRow struct {
	ID                string
	Tier              string
	Node              string
	Phase             string
	Vcpu              int64
	Memory            int64
	HeldAt            string
	ForceRelease      int64
	HolderIncarnation string
	NodeIncarnation   sql.NullString
	NodeLive          sql.NullInt64
	NodeSeenAt        sql.NullString
}

type ListJobHistoryRow 

type ListJobHistoryRow struct {
	LeaseID       string
	Tier          string
	Node          string
	RunID         int64
	RequestID     int64
	Conclusion    sql.NullString
	FailureReason string
	Result        string
	Disruption    string
	QueuedAt      string
	StartedAt     string
	FinishedAt    string
}

type ListJoinTokensRow 

type ListJoinTokensRow struct {
	Note          string
	UsesRemaining int64
	CreatedAt     string
	ExpiresAt     string
}

type ListLeaseIDsOnNodeParams 

type ListLeaseIDsOnNodeParams struct {
	Node      sql.NullString
	Launching string
	Online    string
	Busy      string
	Custody   string
	Teardown  string
}

type ListNodeInventoriesRow 

type ListNodeInventoriesRow struct {
	Name       string
	Live       int64
	Epoch      int64
	NodeEpoch  sql.NullInt64
	Running    sql.NullInt64
	ReceivedAt sql.NullString
}

type ListNodeWireVersionsRow 

type ListNodeWireVersionsRow struct {
	Name           string
	Live           int64
	NodeRelease    string
	WireMin        int64
	WireMax        int64
	WireVersion    int64
	Epoch          int64
	NodeDigest     string
	HighestRelease string
}

type ListOutstandingLeasesRow 

type ListOutstandingLeasesRow struct {
	ID           string
	Tier         string
	Node         string
	Phase        string
	RunID        string
	Since        string
	Deregistered int64
}

type ListOutstandingRemoteShapesRow 

type ListOutstandingRemoteShapesRow struct {
	Node         sql.NullString
	InstanceType string
	Outstanding  int64
}

type ListPendingCompletionsRow 

type ListPendingCompletionsRow struct {
	Tier         string
	RequestID    int64
	RunID        int64
	Result       string
	LeaseID      string
	LeaseEpoch   int64
	LeaseNode    string
	Outcome      string
	ReleaseOnly  int64
	MessageID    int64
	Retired      int64
	Acknowledged int64
}

type ListPlaceableNodesRow 

type ListPlaceableNodesRow struct {
	Name        string
	Provider    string
	Site        string
	TotalVcpu   int64
	TotalMemory int64
	Ec2Shapes   string
}

type ListQuarantinedLeaseIDsOnParams 

type ListQuarantinedLeaseIDsOnParams struct {
	Phase   string
	Node    string
	Settled string
}

type ListQuarantinedLeasesRow 

type ListQuarantinedLeasesRow struct {
	ID          string
	Tier        string
	Node        string
	Vcpu        int64
	Memory      int64
	HeartbeatAt string
}

type ListRegisteredNodesRow 

type ListRegisteredNodesRow struct {
	Name               string
	Provider           string
	Site               string
	Live               int64
	DecommissionedAt   string
	DecommissionProven int64
	DecommissionActor  string
}

type ListRemoteCostNodesRow 

type ListRemoteCostNodesRow struct {
	Name        string
	Provider    string
	TotalVcpu   int64
	TotalMemory int64
	Ec2Shapes   string
}

type ListRolloutNodePhasesRow 

type ListRolloutNodePhasesRow struct {
	Node  string
	Phase string
}

type ListRolloutNodesRow 

type ListRolloutNodesRow struct {
	Node            string
	Phase           string
	Attempts        int64
	NextAttemptAt   string
	Blocker         string
	PriorRelease    string
	RollbackResult  string
	ExemptReason    string
	UpdatedAt       string
	DispatchEpoch   int64
	ConvergedDigest string
}

type ListRunningLeasesWithReplacedHolderParams 

type ListRunningLeasesWithReplacedHolderParams struct {
	Launching string
	Online    string
	Busy      string
}

type ListRunningLeasesWithReplacedHolderRow 

type ListRunningLeasesWithReplacedHolderRow struct {
	ID                string
	Tier              string
	Node              string
	Phase             string
	Vcpu              int64
	Memory            int64
	HolderIncarnation string
	HeartbeatAt       string
	NodeIncarnation   string
	NodeLive          int64
	NodeSeenAt        string
}

type ListScaleSetsRow 

type ListScaleSetsRow struct {
	Org         string
	RunnerGroup string
	Label       string
	ScaleSetID  int64
}

type LiveCertsForParams 

type LiveCertsForParams struct {
	Node string
	Now  string
}

type LiveJoinTokenExistsParams 

type LiveJoinTokenExistsParams struct {
	TokenSha256 string
	Now         string
}

type MarkLeaseFailureParams 

type MarkLeaseFailureParams struct {
	FailureReason string
	ID            string
	Epoch         int64
}

type MarkNodeNotLiveParams 

type MarkNodeNotLiveParams struct {
	Name  string
	Epoch int64
}

type MarkPoolRunnerBusyParams 

type MarkPoolRunnerBusyParams struct {
	RunnerID  int64
	UpdatedAt string
	LeaseID   string
}

type MarkPoolRunnerRetiredParams 

type MarkPoolRunnerRetiredParams struct {
	UpdatedAt string
	LeaseID   string
}

type MarkPoolRunnerRetiringParams 

type MarkPoolRunnerRetiringParams struct {
	UpdatedAt string
	LeaseID   string
}

type NodeEnrollment 

type NodeEnrollment struct {
	Name        string
	Fingerprint string
	CsrPem      string
	CertPem     string
	State       string
	RequestedAt string
	DecidedAt   string
	Source      string
}

type PendingCompletionMessageParams 

type PendingCompletionMessageParams struct {
	Tier      string
	RequestID int64
}

type PendingCompletionMessageRow 

type PendingCompletionMessageRow struct {
	MessageID int64
	Retired   int64
}

type PendingForceTargetsParams 

type PendingForceTargetsParams struct {
	Generation int64
	Tier       string
	State      string
}

type PendingForceTargetsRow 

type PendingForceTargetsRow struct {
	LeaseID          string
	Tier             string
	Node             string
	RunID            string
	SchedulerRequest int64
	Phase            string
	State            string
	Detail           string
}

type PoolRunner 

type PoolRunner struct {
	LeaseID            string
	Tier               string
	LaunchRequestID    int64
	RunnerID           int64
	RunnerName         string
	Status             string
	ActualRequestID    int64
	RunID              int64
	JobID              string
	SourceAcknowledged int64
	UpdatedAt          string
}

type Queries 

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

func New 

func New(db DBTX) *Queries

func (*Queries) AcknowledgePendingCompletion 

func (q *Queries) AcknowledgePendingCompletion(ctx context.Context, arg AcknowledgePendingCompletionParams) error

Record that GitHub will not redeliver this message.

func (*Queries) AcknowledgePoolRunnerSource 

func (q *Queries) AcknowledgePoolRunnerSource(ctx context.Context, arg AcknowledgePoolRunnerSourceParams) error

Record that GitHub cannot redeliver the completion that used this member.

func (*Queries) AdvanceRolloutController 

func (q *Queries) AdvanceRolloutController(ctx context.Context, arg AdvanceRolloutControllerParams) error

Move the control plane's own phase, refusing if it moved underneath us.

THE PHASE IS IN THE WHERE as well as the SET. The caller read it inside this transaction and validated the transition; repeating it here means the write can never land on a row it did not read.

func (*Queries) AdvanceRolloutNode 

func (q *Queries) AdvanceRolloutNode(ctx context.Context, arg AdvanceRolloutNodeParams) error

Move one host through the rollout state machine.

THE THREE CASE COLUMNS ARE WRITE-ONCE-OR-KEEP, not optional parameters: a prior release, a dispatch epoch and a converged digest are each recorded by whichever pass first learns them, and every later pass passes nothing and must not erase what is there. Expressed in SQL rather than by building the statement two ways, because a branch applied in one path and forgotten in another is how a rollback loses the release it was meant to return to.

func (*Queries) AnyBarrierRunExists 

func (q *Queries) AnyBarrierRunExists(ctx context.Context) (bool, error)

Whether the fleet has any run at all, for the same reason.

func (*Queries) ArchiveJobHistory 

func (q *Queries) ArchiveJobHistory(ctx context.Context, arg ArchiveJobHistoryParams) error

Close the history row when the lease terminalizes.

EVERY COALESCE HERE PRESERVES WHAT THE ASSIGNMENT ROW ALREADY KNEW. A lease terminalizing may carry less than the row does -- a reap has no run id -- and overwriting with a null would erase the identity of the job that ran.

THE DISRUPTION IS WRITE-ONCE-OR-KEEP for the same reason it is on the lease: the FIRST observation is the one that can still have been causal, and a disruption recorded during teardown must not replace the spot interruption that caused the teardown.

THE PLACEMENT FACTS ARE THE LEASE'S TERMINAL ONES and overwrite: the backend it ran on, the shape placement bought, the charged vCPU and memory, the site and the price that shape was charged at were all decided on the lease row, which is about to be reaped, and the history is where they survive. The price is what the lease recorded when the shape was charged, never today's catalogue.

THE CACHE OBSERVATIONS ARE WRITE-ONCE-OR-KEEP like the disruption, and for the same reason: they are written onto this row the moment the node observes them, and an archive arriving from a caller that did not load them must not blank an observation already here. The generation moves with the image-cache token, so a report never shows a generation with nothing to attribute it to.

func (*Queries) AssignLease 

func (q *Queries) AssignLease(ctx context.Context, arg AssignLeaseParams) error

Bind an escrowed lease to a GitHub job and refresh its TTL.

func (*Queries) BackfillFailureReason 

func (q *Queries) BackfillFailureReason(ctx context.Context, arg BackfillFailureReasonParams) error

Explain a failure the reaper archived without a reason, on both rows.

ONLY WHERE NOTHING EXPLAINS IT YET. A launch that failed conclusively can have its parked release lose the race to the reaper, which terminalizes an escrow-only lease outright; the retry then arrives at a failed row and still knows why. A reason already recorded is the earlier fact and stands.

func (*Queries) BackfillLeaseFailureReason 

func (q *Queries) BackfillLeaseFailureReason(ctx context.Context, arg BackfillLeaseFailureReasonParams) error

The lease-row half of BackfillFailureReason: a failed row with no reason.

func (*Queries) BarrierRunExists 

func (q *Queries) BarrierRunExists(ctx context.Context, node string) (bool, error)

Whether one host has a run at all.

READ BEFORE THE WRITE, and that is not a micro-optimisation: the invalidation runs on EVERY registration, ahead of the revocation check, so a credential an operator has taken back can call it as fast as it can open connections. An unconditional write transaction would let it reserve SQLite's single writer slot over and over and starve every scheduling decision in the process.

func (*Queries) BindDeployment 

func (q *Queries) BindDeployment(ctx context.Context, arg BindDeploymentParams) error

Record the deployment these rows belong to, for the first and only time.

A PLAIN INSERT RATHER THAN AN UPSERT, and the absence of a DO UPDATE clause is the guarantee. The caller has already read the row inside this same write transaction and found none, and every writer serializes (SQLite at BEGIN IMMEDIATE, PostgreSQL on the advisory lock beginWrite takes), so nothing can bind between the read and this insert. If one somehow did, the primary key refuses rather than quietly relabelling a deployment.

func (*Queries) BindLease 

func (q *Queries) BindLease(ctx context.Context, arg BindLeaseParams) error

Record which host the work actually went to, and the backend it runs on.

THE PROVIDER IS THE HOST'S REGISTERED ONE, read in this transaction rather than taken from a catalogue: the registration is what the machine itself reported.

holder_incarnation IS THAT HOST'S INCARNATION, read in the same transaction: the process that is launching this compute. A report compares it with the node's current incarnation to say whether the process that was given the work is still the one the deployment talks to. It decides nothing.

func (*Queries) BindPoolRunnerJob 

func (q *Queries) BindPoolRunnerJob(ctx context.Context, arg BindPoolRunnerJobParams) error

Fill in the job a recovered busy member turned out to be running.

IT DOES NOT TOUCH status OR runner_id, and the reason is narrower than it looks: the caller reads the row and reaches this in ONE transaction, so a status written here could not differ from the one it just read. What the narrow projection buys is that the statement cannot be reused, later, on a path that has not established the member is busy -- measured, adding `status = 'busy'` here changes no observable behaviour today.

func (*Queries) BumpDispatchGeneration 

func (q *Queries) BumpDispatchGeneration(ctx context.Context, name string) (int64, error)

The compute barrier: a durable request that every host in the fleet be ASKED what it is running, and the fenced answers.

WHY THE LEDGER CANNOT ANSWER THIS ON ITS OWN. alloc.Quiescence reads leases, and the class this exists for is compute whose lease has already gone: a listener that loses a running lease keeps an in-memory obligation to destroy what it launched, and a launch whose lease was reclaimed can create compute it then fails to destroy. Neither is in the ledger and neither survives a restart, but both leave an instance carrying billet's own name on the host's provider.

WHAT MAKES AN ANSWER CAUSAL IS TWO FENCES, and every statement here carries both. `node_epoch` is the registration in force -- a reconnect moves it, so a proof about a previous incarnation stops counting. `dispatch_generation` is advanced durably BEFORE a launch enters that host's queue, so an answer that crossed a launch matches nothing rather than being believed.

WHAT IS STORED IS A CONTINUOUS RUN, NOT A SNAPSHOT. An error, a non-empty list or either fence moving DELETES the row rather than ageing it, and the proof is `observed_at - empty_since` -- two observations spanning the grace, never one observation plus elapsed wall clock. A host that answered empty once and then disconnected must not age into proved. Advance one host's launch-dispatch fence and return the new value.

IT COUNTS LAUNCHES, NOT COMMANDS. A destroy, sweep, tend or inventory cannot create compute, so charging them would void proofs for no reason.

sql.ErrNoRows means the host has no row -- and a host with no row cannot be proved clear either, since every clearance walks the node table, so there is no fence to advance and nothing about it that could later be believed.

func (*Queries) CertRevocation 

func (q *Queries) CertRevocation(ctx context.Context, serial string) (int64, error)

Whether this serial has been withdrawn.

ABSENCE IS sql.ErrNoRows, which the caller separates from a read error. A database fault must not answer "not revoked": that would make an unreadable ledger equivalent to an empty one, which is the whole check switched off by a transient fault.

func (*Queries) ClaimController 

func (q *Queries) ClaimController(ctx context.Context, arg ClaimControllerParams) (int64, error)

Record this process as the controller and advance the generation.

THE EPOCH ONLY EVER GOES UP, and it is computed from the row rather than supplied: a caller that passed one could pass the same one twice, and two controllers agreeing on a number is exactly what a fencing token must never allow. The first claim is 1, because the column refuses zero and a zero epoch would be indistinguishable from a row nothing has written.

func (*Queries) ClaimPoolRunnerForRetirement 

func (q *Queries) ClaimPoolRunnerForRetirement(ctx context.Context, arg ClaimPoolRunnerForRetirementParams) (sql.Result, error)

Claim a member for teardown, refusing one that is already past it.

THE STATUS FILTER IS THE CLAIM, so this is :execresult: zero rows affected is how the caller learns the member was already retiring, retired, or gone, and it then reads the row to say which. An :exec could not tell those apart.

func (*Queries) CompleteForceDestroy 

func (q *Queries) CompleteForceDestroy(ctx context.Context, arg CompleteForceDestroyParams) error

Close out a request once nothing is pending.

Guarded on the state it is leaving, so a second listener arriving at the same conclusion cannot rewrite completed_at.

func (*Queries) CorrectProvisionalHistory 

func (q *Queries) CorrectProvisionalHistory(ctx context.Context, arg CorrectProvisionalHistoryParams) error

The same correction, in the history row.

func (*Queries) CorrectProvisionalLease 

func (q *Queries) CorrectProvisionalLease(ctx context.Context, arg CorrectProvisionalLeaseParams) error

Replace inventory's provisional verdict with GitHub's own.

ONLY INVENTORY'S PROVISIONAL VERDICT MAY BE CORRECTED, which the caller checks by comparing failure_reason: an operator or a node can independently fail a quarantined lease at a later epoch too, so epoch order is a fence and never provenance.

func (*Queries) CountActiveRunnerLeases 

func (q *Queries) CountActiveRunnerLeases(ctx context.Context, tier string) (int64, error)

How many runners GitHub could still route a job to, in one tier.

KEYED ON deregistered RATHER THAN ON PHASE, because the question is whether the GitHub registration is gone rather than what billet's compute lifecycle is doing: a teardown still retrying its destroy is deregistered and must stop counting, while a teardown whose runner was never deregistered must keep counting or a replacement is launched against a runner GitHub can still schedule.

func (*Queries) CountCacheBlocks 

func (q *Queries) CountCacheBlocks(ctx context.Context, arg CountCacheBlocksParams) (int64, error)

Blocks covering one repository: its organisation's, or its own.

ONE QUERY FOR BOTH SCOPES, because the answer is "is either blocked" and two reads could straddle a write that added the org block after the repository read said no.

func (*Queries) CountForceDestroyInState 

func (q *Queries) CountForceDestroyInState(ctx context.Context, state string) (int64, error)

How many force-destroy requests sit in one state.

Asked inside the write transaction that would create the next one: two concurrent forces would each enumerate a target set the other was midway through destroying.

func (*Queries) CountForceTargetsInState 

func (q *Queries) CountForceTargetsInState(ctx context.Context, arg CountForceTargetsInStateParams) (int64, error)

How many of one request's targets are still in a given state.

Read in the SAME transaction as the settlement above, because completion is decided from it: two listeners settling their last target concurrently would otherwise both see work outstanding and leave a request nothing will finish.

func (*Queries) CountLiveWorkOnNode 

func (q *Queries) CountLiveWorkOnNode(ctx context.Context, arg CountLiveWorkOnNodeParams) (int64, error)

How much work on one host would be invalidated by a placement change.

STRICTER THAN CountOutstandingLeasesOnNode: an escrow that has already expired holds no compute and is about to be reaped, so it must not block a host from correcting its own registration -- but anything past `launching` has compute behind it whatever its TTL says.

func (*Queries) CountOpenInTier 

func (q *Queries) CountOpenInTier(ctx context.Context, tier string) (int64, error)

Everything one tier holds, live host or not.

func (*Queries) CountOpenPerTier 

func (q *Queries) CountOpenPerTier(ctx context.Context) ([]CountOpenPerTierRow, error)

How much each tier already holds, for the floor arithmetic.

A LEASE ON A HOST THAT IS GONE COUNTS FOR NOTHING, which is what the LEFT JOIN and the liveness test express: a floor is about capacity a tier can actually use. An UNPLACED lease still counts, because escrow has promised it.

THAT UNPLACED CLAUSE IS UNREACHABLE THROUGH TODAY'S API, and that is said here rather than left for somebody to discover: every reservation names a machine now -- Reserve refuses when placement finds no host, so insertLease always has a target -- and only a row written before that was true has an empty one. Measured: deleting the clause fails no test in internal/alloc. It stays because such rows exist in deployments upgraded from before, and dropping them from a tier's committed count understates what that tier already holds.

func (*Queries) CountOutstandingLeasesOnNode 

func (q *Queries) CountOutstandingLeasesOnNode(ctx context.Context, node string) (int64, error)

How many leases still charge capacity against one host.

COALESCE(node, target_node), the way the rest of this package attributes a lease: an escrow AIMED at a machine has already committed that machine's room whether or not a container has started.

func (*Queries) DecideEnrollment 

func (q *Queries) DecideEnrollment(ctx context.Context, arg DecideEnrollmentParams) error

Record an operator's approval or denial.

func (*Queries) DecommissionNode 

func (q *Queries) DecommissionNode(ctx context.Context, arg DecommissionNodeParams) error

Stop expecting one host to answer.

decommission_proven RECORDS WHETHER ANYTHING PROVED IT WAS IDLE, and a forced exclusion writes 0 rather than being omitted: an exclusion that cannot be told from a proof is the whole membership rule defeated. `drained = 1` is what both placement queries and the floor arithmetic already read.

func (*Queries) DeleteAcknowledgedCompletion 

func (q *Queries) DeleteAcknowledgedCompletion(ctx context.Context, arg DeleteAcknowledgedCompletionParams) error

Remove an obligation that is both retired and acknowledged.

Paired with RetirePendingCompletion in one transaction: the row may only go once GitHub will not redeliver it AND settlement is durable, and whichever of the two happens second is what removes it.

func (*Queries) DeleteBarrierRun 

func (q *Queries) DeleteBarrierRun(ctx context.Context, node string) error

Discard one host's continuous-empty run.

func (*Queries) DeleteCacheBlock 

func (q *Queries) DeleteCacheBlock(ctx context.Context, arg DeleteCacheBlockParams) error

Re-enable interception for one explicit scope by removing its block.

func (*Queries) DeleteComputeBarrier 

func (q *Queries) DeleteComputeBarrier(ctx context.Context) error

Remove a request that can no longer mean anything.

func (*Queries) DeleteEveryBarrierRun 

func (q *Queries) DeleteEveryBarrierRun(ctx context.Context) error

Discard what every host had proved.

REACHED FROM THREE PLACES AND EACH ONE MATTERS. A superseded barrier's observations go with it, because they were taken under a generation somebody has since moved and admission was open in between. A dropped barrier takes its own. And an arrival that cannot be ATTRIBUTED to a host -- a loopback registration whose body would not decode -- invalidates everything, because "I could not tell who arrived" must not read as "nothing changed".

func (*Queries) DeleteEveryNodeInventory 

func (q *Queries) DeleteEveryNodeInventory(ctx context.Context) error

And forget what they last said they were running.

A REPORT RECEIVED BY A PREVIOUS PROCESS SAYS NOTHING ABOUT NOW, and the node epoch does NOT move on a plane restart -- so without this the record would survive with a matching epoch and read as current to everything that consults it.

func (*Queries) DeleteMovedScaleSet 

func (q *Queries) DeleteMovedScaleSet(ctx context.Context, arg DeleteMovedScaleSetParams) error

Forget a record whose scale set id now answers to a different name.

A scale set deleted and recreated outside billet keeps its name and takes a new id; one RENAMED keeps its id under a new name. This removes the stale (group, label) so the orphan report does not name an object that is gone.

func (*Queries) DeletePoolRunner 

func (q *Queries) DeletePoolRunner(ctx context.Context, leaseID string) error

Forget the settlement metadata, after compute and capacity are both gone.

func (*Queries) DeleteRetiredCompletion 

func (q *Queries) DeleteRetiredCompletion(ctx context.Context, arg DeleteRetiredCompletionParams) error

The other half of the pair above, from the acknowledgement side.

func (*Queries) DeleteScaleSet 

func (q *Queries) DeleteScaleSet(ctx context.Context, arg DeleteScaleSetParams) error

Drop the record for a scale set billet has deleted.

func (*Queries) DisruptableLease 

func (q *Queries) DisruptableLease(ctx context.Context, id string) ([]string, error)

Disruption: what billet's OWN infrastructure did to a lease while the job on it may still have been running.

AN OBSERVATION, NEVER A VERDICT. Nothing here says a job failed because of a disruption; what makes one interesting is reading it beside GitHub's own result for the same job, which is why the two are recorded separately and neither is stored as an answer.

THE GUARD IS WRITTEN TWICE, and it has to be: SQL has no way to compose a predicate the way the Go constant it replaced did. TestBothDisruptionStatementsPinTheirWholeStatement pins each statement's COMPLETE text -- the locator as well as the guard -- because a guard that drifts on one path is the path that attributes somebody's ordinary test failure to billet, and a locator that widens is every lease in the deployment.

WHAT THE GUARD SAYS, clause by clause: 

an empty disruption        The FIRST observation is the one kept. A later
                           disruption is a consequence of the earlier one at
                           least as often as it is a separate event, and only
                           the earliest can still have been causal.

phase IN (...)             Phases in which a job COULD still have been
                           running. Could, not was: `launching` admits a
                           lease whose guest never started. `capacity` and
                           `assigned` are absent because nothing was started
                           under them, and attributing a build failure to one
                           would attribute it to a machine that never ran the
                           build. `quarantine` IS here, because quarantine
                           exists precisely while compute is unconfirmed.

NOT EXISTS job_history     A disruption landing after GitHub has reported the
NOT EXISTS pending_...     job cannot have caused it. BOTH records are asked
                           because pending_completions is written FIRST, when
                           the listener makes the delivery durable, and
                           job_history.result follows in a SECOND
                           transaction: reading only the second leaves a
                           committed interval in which a concurrent NodeGone
                           or reclaim sees no result and attributes a job that
                           had already finished. It also survives a crash
                           between the two writes, since the pending row does
                           and the column does not.

Whether one lease may still have a disruption recorded against it.

func (*Queries) DisruptableLeasesOnNode 

func (q *Queries) DisruptableLeasesOnNode(ctx context.Context, node string) ([]string, error)

Which of one host's leases may still have a disruption recorded against them.

COALESCE(node, target_node), the way the rest of this package attributes a lease: a reservation aimed at a machine that is being given up on is as disrupted as one bound to it.

func (*Queries) ExpireLease 

func (q *Queries) ExpireLease(ctx context.Context, arg ExpireLeaseParams) error

Move a lease's expiry, which is how a test drives the real reaper.

func (*Queries) FenceQuarantinedLease 

func (q *Queries) FenceQuarantinedLease(ctx context.Context, arg FenceQuarantinedLeaseParams) error

Settle a quarantined lease, refusing one whose epoch moved.

THE EPOCH IS IN THE WHERE, unlike the two above: this is the operator's force path, which read the lease and then decided, so the write must not land on a row something else has since taken over.

func (*Queries) FinishRollout 

func (q *Queries) FinishRollout(ctx context.Context, arg FinishRolloutParams) error

Close a rollout, refusing one that is no longer open.

func (*Queries) FleetClaimHolder 

func (q *Queries) FleetClaimHolder(ctx context.Context, arg FleetClaimHolderParams) (string, error)

Another host that still claims one reserved CodeBuild fleet.

A RESERVED FLEET IS ONE SHARED POOL, so two nodes naming it each register its whole capacity and the deployment promises GitHub more concurrent jobs than AWS will run. Only the control plane can see that, because the two config files are on two machines.

WHAT RELEASES A CLAIM IS decommission_proven = 1, NOT LIVENESS AND NOT AN EXCLUSION. Liveness says nothing about remote compute -- a control plane start marks every host not-live while its builds keep running -- and `--force` records decommission_proven = 0 precisely because nothing could be asked. The ordinary replacement needs none of this because it reuses the node NAME, which the `name <> @name` clause excludes.

func (*Queries) ForceDestroyInState 

func (q *Queries) ForceDestroyInState(ctx context.Context, state string) (ForceDestroy, error)

The one request sitting in a given state, if any.

func (*Queries) ForceTargets 

func (q *Queries) ForceTargets(ctx context.Context, generation int64) ([]ForceTargetsRow, error)

Every lease one request covers, whatever became of it.

func (*Queries) ForgetEveryNode 

func (q *Queries) ForgetEveryNode(ctx context.Context) error

Mark the whole fleet unreachable, which is what a control-plane start knows.

IT REMOVES NOTHING. A node row is the durable placement identity of a machine, and a plane that has just started has no judgement about any host -- not that the host is gone.

func (*Queries) HeartbeatLease 

func (q *Queries) HeartbeatLease(ctx context.Context, arg HeartbeatLeaseParams) error

Push a lease's expiry out.

func (*Queries) HighestForceDestroyGeneration 

func (q *Queries) HighestForceDestroyGeneration(ctx context.Context) (int64, error)

The highest generation on file, or 0 when there has never been a force.

CAST because sqlc types a bare MAX (and a bare COALESCE) as interface{}; measured. COALESCE first, because CAST(NULL AS BIGINT) is still NULL. The 0 reproduces exactly what a NULL scanned into sql.NullInt64 used to yield, so the caller's +1 still makes the first request generation 1.

func (*Queries) HighestRolloutGeneration 

func (q *Queries) HighestRolloutGeneration(ctx context.Context) (int64, error)

Rollout queries: one durable fleet decision, and where every component of it has got to.

THE STATEMENTS HERE ARE internal/rollout's, NOT internal/state's, and that is deliberate: the ledger's SQL lives in one directory so the guards that police it -- the prepare-against-the-migrated-schema check, the read/write classification, the ASCII rule and the wildcard ban -- cover every domain rather than only the ones that happened to be converted first. internal/rollout binds them through state.ReadQueries / state.WriteQueries. The highest generation any rollout has ever carried.

CAST(COALESCE(...)) because sqlc types a bare MAX() -- and a bare COALESCE(MAX(), 0) -- as interface{}. Zero on an empty table, so the caller's +1 makes the first rollout generation 1, which the table's CHECK requires.

func (*Queries) HoldLease 

func (q *Queries) HoldLease(ctx context.Context, arg HoldLeaseParams) error

Move a lease into a phase that holds compute, and keep its TTL alive.

held_at IS WHEN THE OBLIGATION STARTED, which is what an operator report ages from. The TTL still moves because a held lease is still being tended.

holder_incarnation IS REWRITTEN ON THE WAY INTO CUSTODY OR TEARDOWN, because the process taking the obligation may not be the one that launched the compute -- a restart adopts what it finds -- and the caller passes the value it read for every other phase so the column is never blanked.

func (*Queries) HostReportsCompute 

func (q *Queries) HostReportsCompute(ctx context.Context, node string) (bool, error)

The same question about one host.

ASKED BY provedTx AS WELL AS BY THE FLEET REPORT, so the two cannot disagree about one host at one instant. Without it a machine actively reporting compute could be decommissioned as PROVEN -- permanently out of the expected set, on a run whose samples simply predated the instance becoming visible.

func (*Queries) InsertEnrollment 

func (q *Queries) InsertEnrollment(ctx context.Context, arg InsertEnrollmentParams) error

Record a request for a name nothing holds.

func (*Queries) InsertForceDestroy 

func (q *Queries) InsertForceDestroy(ctx context.Context, arg InsertForceDestroyParams) error

Record one operator decision to destroy running compute.

completed_at is empty rather than null: this row is read back into a struct whose fields are strings, and a nullable column would make "not finished" and "billet could not read it" the same value.

func (*Queries) InsertForceDestroyTarget 

func (q *Queries) InsertForceDestroyTarget(ctx context.Context, arg InsertForceDestroyTargetParams) error

Record one lease the operator authorised destroying.

EVERY FIELD IS STORED so the diagnostic survives the command: a listener acting on this a poll later, or a second control plane after a restart, has no other record of what the person actually approved.

func (*Queries) InsertJobIdentity 

func (q *Queries) InsertJobIdentity(ctx context.Context, jobID string) error

Durable negative scheduler identities.

ZERO IS NEVER A SCHEDULER IDENTITY. GitHub's direct JobAssigned path carries runnerRequestId 0, and its desired-count signal names a quantity rather than a job at all -- so billet mints its own id for both. Negative, so it can never collide with one of GitHub's own positive request ids, and allocated under the immediate writer transaction so a redelivery or a restart recovers the SAME number rather than minting a second identity for one job.

HASHING THE JOB ID WAS THE ALTERNATIVE AND IT IS WORSE: it would make hash collisions a correctness property of the scheduler.

THE MINIMUM IS TAKEN ACROSS BOTH TABLES, which is what keeps the two families of identity in one number space. Reading only its own table would let a job and a pool slot be handed the same id. Mint the identity for one direct-assignment job, if it has none.

DO NOTHING rather than DO UPDATE: a job that already has an identity must keep it, because that number is what an in-flight message is keyed on.

func (*Queries) InsertJoinToken 

func (q *Queries) InsertJoinToken(ctx context.Context, arg InsertJoinTokenParams) error

Join tokens: the short-lived credential that lets a machine ASK to enroll.

The token is never stored. What the table holds is its sha256, which is why every statement here takes a hash rather than a secret. Mint one join token.

func (*Queries) InsertLease 

func (q *Queries) InsertLease(ctx context.Context, arg InsertLeaseParams) error

Escrow one slot.

node IS NULL AND target_node IS NOT. The two answer different questions: the target is where billet DECIDED the work goes, the node is where it actually went. Capacity is charged on COALESCE(node, target_node) precisely so a reservation aimed at a machine spends that machine's room immediately -- counting only bound leases let a tier escrow against the same host repeatedly in the window before its first launch, which is the deployment-level overcommit moved down to the machine.

THE REQUESTED AND CHARGED VECTORS ARE BOTH RECORDED. A remote lease is charged for the SHAPE placement bought rather than the smaller tier request, and a fallback resizes the charge; the immutable request is what a later shape is checked against.

THE PRICE IS THE SHAPE'S PRICE AT THE MOMENT IT IS CHARGED, in millionths of a dollar, and the site is the placed host's registered site. Both are written here rather than read back later because a node may re-register with a new catalogue while this lease is open, and the history a terminalization copies has to say what the deployment bought, not what it would pay today. Zero is a host-backed lease, which buys nothing.

func (*Queries) InsertPoolRunner 

func (q *Queries) InsertPoolRunner(ctx context.Context, arg InsertPoolRunnerParams) error

Pool runners: one GitHub registration backed by one compute lease.

A SCALE-SET RUNNER IS A POOL MEMBER, NOT THE JOB THAT CAUSED SCALE-UP, and this table is where that distinction is made durable. launch_request_id is the request billet launched for; actual_request_id, run_id and job_id are the job GitHub's own JobStarted says the runner actually consumed. Those two are routinely different, and the second set is authoritative about the compute.

THE PROJECTIONS INCLUDE updated_at, which nothing reads, and that is deliberate: selecting exactly the table's columns in exactly its order makes sqlc return the model struct, so all three reads share one type and one mapping function rather than three Row types that must be kept identical. Record one pool member.

THE STATUS IS A PARAMETER because a member is journaled at three different points: idle when billet registers what it launched, busy when recovery finds a legacy registration GitHub says is working, and retiring when recovery is claiming one for teardown and no row existed. The table's CHECK is what keeps the vocabulary closed.

func (*Queries) InsertPoolSlotIdentity 

func (q *Queries) InsertPoolSlotIdentity(ctx context.Context, leaseID string) error

Mint the identity for one escrowed lease becoming a physical pool member.

KEYED ON THE LEASE, because GitHub's desired-count signal names no job: the lease is the only stable identity available on redelivery and after a restart.

func (*Queries) InsertRollout 

func (q *Queries) InsertRollout(ctx context.Context, arg InsertRolloutParams) error

Record one fleet decision.

finished_at and terminal_reason are written empty rather than parameterised: a rollout being inserted has not finished, and there is no value a caller could legitimately pass.

func (*Queries) InsertRolloutNode 

func (q *Queries) InsertRolloutNode(ctx context.Context, arg InsertRolloutNodeParams) error

Enrol one host in a rollout, at the phase every host starts in.

The set of hosts is a SNAPSHOT taken when the rollout starts, so this is only ever called from Start: a host that registers later is running whatever it was installed with and is not part of a decision taken before it existed.

func (*Queries) LatestForceDestroy 

func (q *Queries) LatestForceDestroy(ctx context.Context) (ForceDestroy, error)

The most recent request, open or finished, for the report an operator reads after the fact.

func (*Queries) ListAdmissionRows 

func (q *Queries) ListAdmissionRows(ctx context.Context) ([]Admission, error)

Every row of the admission table, for the pristine check a restore depends on.

ALL OF THEM, not one: proving a ledger is untouched means proving there is exactly the single row its migration inserted, and a query that selected `WHERE id = 1` could not see a second one.

func (*Queries) ListAppliedMigrations 

func (q *Queries) ListAppliedMigrations(ctx context.Context) ([]ListAppliedMigrationsRow, error)

Every migration this ledger has recorded, oldest first.

ORDERED so two readings of one ledger compare and serialise identically; the migrator itself keys on version and does not depend on the order.

func (*Queries) ListAttributedFailures 

func (q *Queries) ListAttributedFailures(ctx context.Context, arg ListAttributedFailuresParams) ([]ListAttributedFailuresRow, error)

Jobs that did not succeed while billet's own infrastructure was disrupted.

TWO FACTS, NOT A VERDICT. Nothing here says the disruption caused the failure; billet cannot tell a broken host from a broken build, and the report that renders this says so.

WINDOWED ON result_at RATHER THAN finished_at, which is written when the LEASE terminalizes and stays empty for as long as a destroy is retrying -- a job whose teardown is wedged is exactly one worth reporting.

`result != @succeeded` RATHER THAN A LIST OF FAILURE WORDS. The vendored scale-set client enumerates no results, so the only value this codebase has ever seen confirmed is the one node teardown already keys on; everything else, including a spelling GitHub adds tomorrow, is treated as not succeeded. An unknown result is "could not tell", and collapsing that into "fine" would hide exactly the job an operator came here looking for.

func (*Queries) ListBarrierRuns 

func (q *Queries) ListBarrierRuns(ctx context.Context, barrierID string) ([]ListBarrierRunsRow, error)

Every run recorded under one barrier.

func (*Queries) ListCodeBuildRegistrationPaths 

func (q *Queries) ListCodeBuildRegistrationPaths(ctx context.Context, provider string) ([]ListCodeBuildRegistrationPathsRow, error)

Every codebuild host and the Parameter Store path it stages registrations under.

DECOMMISSIONED HOSTS INCLUDED, deliberately. The control plane sweeps these paths for registrations a dead node never removed, and a host that has been taken out of the fleet is exactly the one with nobody left to clean up after it. Rows with an empty path are included too: a host that registered before it could name its path is one `billet status` has to NAME as unswept rather than count as clean.

The provider is a parameter rather than a literal, so there is no second spelling of the backend name to drift.

func (*Queries) ListCredentialSweeps 

func (q *Queries) ListCredentialSweeps(ctx context.Context) ([]CredentialSweep, error)

Every path the sweep has ever recorded a pass over.

func (*Queries) ListEnrollments 

func (q *Queries) ListEnrollments(ctx context.Context) ([]NodeEnrollment, error)

Everything that has asked to join.

func (*Queries) ListEnrollmentsInState 

func (q *Queries) ListEnrollmentsInState(ctx context.Context, state string) ([]NodeEnrollment, error)

Everything in one state.

A SECOND STATEMENT RATHER THAN one query whose state filter is skipped when the parameter is empty, so each has one plan and the branch is visible in the Go that chooses it. An unfiltered read of this table is the operator's whole pending list; a filtered one is a lookup, and folding them into one query hides which is running.

func (*Queries) ListExpiredLeases 

func (q *Queries) ListExpiredLeases(ctx context.Context, arg ListExpiredLeasesParams) ([]ListExpiredLeasesRow, error)

The leases whose holders stopped heartbeating.

QUARANTINE IS EXCLUDED because it is already past this line: its compute is unconfirmed and its capacity stays charged until something proves otherwise, so reaping it again would be the reaper deciding a question only evidence settles.

EVERYTHING THE ARCHIVE COPIES IS SELECTED, chosen_provider included. The reaper terminalizes an expired escrow outright and archives it from this row, and a projection that left the provider out archived every reaped lease as having run on nothing.

func (*Queries) ListFleetClearance 

func (q *Queries) ListFleetClearance(ctx context.Context) ([]ListFleetClearanceRow, error)

Every host, with what a clearance needs to judge it.

func (*Queries) ListForceDestroyCandidates 

func (q *Queries) ListForceDestroyCandidates(ctx context.Context, arg ListForceDestroyCandidatesParams) ([]ListForceDestroyCandidatesRow, error)

The two lease listings whose phase set is a Go slice, and the one write that settles a forced lease.

THE PHASE LISTS HERE ARE LITERALS, WHICH IS THE ONE PLACE THIS CONVERSION HAD TO ACCEPT A SECOND SOURCE OF TRUTH. Everywhere else in these files a phase is passed as a parameter from its Go constant, so no spelling can drift. These two cannot: the sets are Go SLICES, whose length may change, and sqlc.slice() is not available on the SQLite engine -- so a variable-arity `IN (?, ...)` has no generated form.

TestTheForceDestroyStatementIsWhatTheGoSliceSays and TestTheDrainStatementIsWhatTheGoSliceSays compare each WHOLE STATEMENT against one assembled from its Go slice -- not the extracted list, and not the extracted WHERE, because both of those ignore what surrounds them: `0 = 1 AND` in front, or a `LIMIT 0` behind, empties the query while the compared fragment is byte-identical. Which means a changed PROJECTION fails these too, and should. A phase added to the Go slice alone is a lease an operator approved destroying that the query never offers; one added to the SQL alone is a lease destroyed without anybody having decided it may be. The running compute an operator could destroy, oldest first.

CUSTODY, TEARDOWN AND QUARANTINE ARE DELIBERATELY ABSENT from the phase list. Their compute is held by a NODE rather than by a listener, and billet already has the operation for them: `billet leases release --force` sets a request the holder observes on its next heartbeat, so the ledger never changes underneath a process that still believes it owns the proof obligation.

AN EMPTY FILTER MEANS UNFILTERED, expressed in SQL rather than by building the query two ways: a narrowing applied in one branch and forgotten in another is how a force reaches a tier the operator did not name.

run_id IS CAST BEFORE IT IS COALESCED, AND THAT ORDER IS THE WHOLE POINT. run_id is a bigint, so coalescing it with an empty string asks PostgreSQL to read that string as a bigint, and it refuses: invalid input syntax for type bigint. SQLite coerces and says nothing, which is how the statement survived being written that way. Casting first makes both arguments text on either engine. The OUTER cast is a second, unrelated requirement: without it sqlc types the whole expression interface{}, which takes whatever a caller passes.

The prose here avoids a quoted empty string on purpose: sqlc copies a query's leading comment into the generated doc and rewrites the quotes as it goes, so the explanation would arrive there saying something slightly different.

It generated cleanly and passed every check up to execution, which is what the conformance run against a real PostgreSQL is for.

func (*Queries) ListHeldLeases 

func (q *Queries) ListHeldLeases(ctx context.Context, arg ListHeldLeasesParams) ([]ListHeldLeasesRow, error)

Quarantine and custody: capacity held because compute could not be confirmed gone.

NOTHING HERE FREES CAPACITY ON A TIMEOUT. A quarantined lease is released by a proof -- an inventory taken under the registration this deployment is talking to, a node reporting a destroy, or an operator asserting a machine is never coming back. Every statement that terminalizes one is fenced by something that postdates the observation it acts on.

THE PHASES ARE PARAMETERS, NOT LITERALS. They are Go constants and passing them means there is no second spelling of the vocabulary to drift from. Every operator-visible proof obligation, oldest first.

WITH ITS HOST'S CURRENT PROCESS BESIDE THE HOLDER'S, so the report can say whether the process that took the obligation is the one the deployment talks to now. LEFT JOIN, because a lease may name a host the ledger has never registered, and that lease is held all the same.

func (*Queries) ListHostsReportingCompute 

func (q *Queries) ListHostsReportingCompute(ctx context.Context) ([]string, error)

The hosts whose own last word, under the registration in force, was that they were running something.

TELEMETRY THAT CAN NEVER CLEAR AND MAY ALWAYS BLOCK. The node lists its provider and THEN posts, so this can never be a proof -- but a host SAYING it is running something is a fact, and the two coexist precisely when a create the provider accepted has not yet been listed: a run completes around it and no fence moves.

func (*Queries) ListJobConclusionsForRequest 

func (q *Queries) ListJobConclusionsForRequest(ctx context.Context, requestID sql.NullInt64) ([]sql.NullString, error)

Every recorded outcome for one scheduler request, oldest first.

`conclusion IS NOT NULL` IS LOAD-BEARING, AND MORE SO THAN IT USED TO BE. A row is inserted at ASSIGNMENT with no conclusion and filled in only when the lease terminalizes, so a job in flight is not an outcome. The hand-written scan used to fail outright on a NULL, which made the filter partly a convenience; generated code reads it as a sql.NullString, so without this an unfinished lease would arrive silently as an empty outcome beside the real ones.

func (*Queries) ListJobHistory 

func (q *Queries) ListJobHistory(ctx context.Context, maxRows int64) ([]ListJobHistoryRow, error)

Every job this deployment recorded, oldest first, bounded.

FOR AN ISOLATED ACCEPTANCE RUN, whose whole ledger is minutes old and holds exactly the jobs that run represents -- so "every row" is a bounded set rather than an unbounded scan, and the bound is here anyway because nothing about the table's size is this query's to assume.

BOTH VERDICTS, because they are different facts and an acceptance report needs to be able to disagree. `result` is what GITHUB said about the job; `conclusion` is what billet's own lifecycle concluded about the lease. A run whose job went green while billet concluded `failed` is exactly the shape worth catching, and reporting one of the two would hide it.

EXPLICIT COLUMNS, never a wildcard projection, so an ordinary ALTER TABLE ADD COLUMN cannot change a byte of the generated code. (Spelling the wildcard out in this comment is what TestNoQueryUsesAWildcardProjection catches -- it reads the file rather than the parsed statement, which is the right direction for a guard whose job is to be impossible to talk past.)

func (*Queries) ListJoinTokenHashes 

func (q *Queries) ListJoinTokenHashes(ctx context.Context) ([]string, error)

Every key the table holds, for the test that says the secret is not among them.

func (*Queries) ListJoinTokens 

func (q *Queries) ListJoinTokens(ctx context.Context) ([]ListJoinTokensRow, error)

What is outstanding, without the secrets.

func (*Queries) ListLeaseIDsOnNode 

func (q *Queries) ListLeaseIDsOnNode(ctx context.Context, arg ListLeaseIDsOnNodeParams) ([]string, error)

The leases one host is running compute for.

func (*Queries) ListNodeInventories 

func (q *Queries) ListNodeInventories(ctx context.Context) ([]ListNodeInventoriesRow, error)

What every known host last said it was running.

NULLABLE RATHER THAN COALESCED TO A SENTINEL. A host with no row and a host reporting a number must not arrive as the same type, or the distinction has to be recovered by comparing against a magic value -- which is how an absent report becomes a zero somewhere downstream. The LEFT JOIN is what produces the nulls, and the caller compares i.node_epoch against n.epoch, because a report from before the host reconnected is not this host's current word.

func (*Queries) ListNodeWireVersions 

func (q *Queries) ListNodeWireVersions(ctx context.Context) ([]ListNodeWireVersionsRow, error)

What each host's registration said about its build, and what was negotiated.

highest_release is the newest release this host has EVER registered with, kept beside node_release so a report can say a host is running something older than it once did. It decides nothing: a rolled-back host is exactly that shape.

func (*Queries) ListOutstandingLeases 

func (q *Queries) ListOutstandingLeases(ctx context.Context) ([]ListOutstandingLeasesRow, error)

Everything the deployment is still holding, for a drain.

THE PHASE LIST IS WHAT COMPUTE MEANS HERE: phases that imply compute exists or that GitHub can still route to it. `capacity` is included even though nothing is running under it, because a listener is advertising that slot and has promised it to GitHub.

IT CANNOT SEE COMPUTE WHOSE LEASE HAS ALREADY GONE, which is why a drain has a SECOND barrier that asks the hosts directly. See internal/state/queries/ barrier.sql.

func (*Queries) ListOutstandingRemoteShapes 

func (q *Queries) ListOutstandingRemoteShapes(ctx context.Context) ([]ListOutstandingRemoteShapesRow, error)

What each remote host currently has running, by the shape it was charged for.

THE SHAPE, NOT THE TIER REQUEST. A remote lease is charged for the instance placement actually bought, so a cost report keyed on anything else understates a fallback. Same pinned provider list as ListRemoteCostNodes.

func (*Queries) ListPendingCompletions 

func (q *Queries) ListPendingCompletions(ctx context.Context, tier string) ([]ListPendingCompletionsRow, error)

One tier's outstanding obligations.

func (*Queries) ListPlaceableNodes 

func (q *Queries) ListPlaceableNodes(ctx context.Context) ([]ListPlaceableNodesRow, error)

The hosts a lease may be placed on at all.

ORDERED BY NAME, because Go map iteration is not and this list decides placement: an unordered candidate set makes the same fleet produce different answers on different runs, which is untestable and unexplainable in a log.

ONE STATEMENT FOR BOTH READERS. eligibleNodes filters it down to a tier's acceptable providers in Go and liveNodes takes the whole fleet, because a floor belonging to one tier is held on the hosts THAT tier could use and the asking tier may not share them -- so the two differ in what they do with the rows, never in which rows exist.

`drained = 0` IS REDUNDANT WITH `live = 1` IN EVERY STATE REACHABLE TODAY, and that is said here rather than left for somebody to discover: a decommission writes drained = 1 and live = 0 together, and a re-registration clears both together, so no API path produces a live host that is drained. Measured -- deleting either half of this predicate fails no test in internal/alloc, while deleting `live = 1` alone does. It stays because the two columns answer different questions (can this host be reached, and does anybody still expect it to serve), and the next path that sets liveness without going through registration must not silently start placing work on an excluded host.

func (*Queries) ListPoolRunnersInTier 

func (q *Queries) ListPoolRunnersInTier(ctx context.Context, tier string) ([]PoolRunner, error)

Every durable member of one tier's GitHub runner pool.

func (*Queries) ListQuarantinedLeaseIDsOn 

func (q *Queries) ListQuarantinedLeaseIDsOn(ctx context.Context, arg ListQuarantinedLeaseIDsOnParams) ([]string, error)

The quarantined leases attributed to one host, optionally only those that expired before an instant.

THE EMPTY SETTLED VALUE MEANS UNFILTERED, expressed in SQL rather than by building the statement two ways: a node asking which of its containers something is still waiting for must see EVERY quarantine, and a young one is exactly the one it must not destroy. A narrowing applied in one branch and forgotten in another is how that goes wrong.

func (*Queries) ListQuarantinedLeases 

func (q *Queries) ListQuarantinedLeases(ctx context.Context, phase string) ([]ListQuarantinedLeasesRow, error)

The leases holding capacity for compute nobody has accounted for, oldest first.

WHAT AN OPERATOR LOOKS AT WHEN CAPACITY IS MISSING: a quarantined lease is the one thing that shrinks a fleet without anything having failed.

func (*Queries) ListRegisteredNodes 

func (q *Queries) ListRegisteredNodes(ctx context.Context) ([]ListRegisteredNodesRow, error)

Registered hosts: the durable placement identity of one compute machine.

A NODE ROW OUTLIVES THE HOST'S CONNECTION. `live` is this control plane's judgement and is cleared for the whole fleet whenever one starts, so nothing here may read an absent or not-live host as a host that is gone. What removes a machine from the set a drain expects to hear from is a decommission, and `drained` is the column that records it. Every host the deployment has recorded, offline ones included.

func (*Queries) ListRemoteCostNodes 

func (q *Queries) ListRemoteCostNodes(ctx context.Context) ([]ListRemoteCostNodesRow, error)

Every host whose compute is bought rather than owned.

THE PROVIDER LIST IS A LITERAL AND IT IS PINNED. sqlc.slice() is not available on SQLite, so this cannot take config.RemoteProviders() as a bound list -- and a literal that drifts from that function is a backend whose cost stops being reported at all, which reads as a fleet that costs nothing. TestTheRemoteProviderListMatchesTheQueries is what keeps the two the same.

func (*Queries) ListRevokedCerts 

func (q *Queries) ListRevokedCerts(ctx context.Context) ([]RevokedCert, error)

What has been withdrawn, newest first.

func (*Queries) ListRolloutHistory 

func (q *Queries) ListRolloutHistory(ctx context.Context, maxRows int64) ([]Rollout, error)

Rollouts newest first, for the operator's report.

func (*Queries) ListRolloutNodePhases 

func (q *Queries) ListRolloutNodePhases(ctx context.Context, rolloutID string) ([]ListRolloutNodePhasesRow, error)

Just the phase of every host in one rollout, for the completion check.

SEPARATE FROM ListRolloutNodes because the completion check reads every host on every pass and needs two columns of the eleven; the projection is the difference between a cheap question and the whole table.

func (*Queries) ListRolloutNodes 

func (q *Queries) ListRolloutNodes(ctx context.Context, rolloutID string) ([]ListRolloutNodesRow, error)

Where every host in one rollout has got to, in a stable order.

func (*Queries) ListRunningLeasesWithReplacedHolder 

func (q *Queries) ListRunningLeasesWithReplacedHolder(ctx context.Context, arg ListRunningLeasesWithReplacedHolderParams) ([]ListRunningLeasesWithReplacedHolderRow, error)

Every lease in a running phase whose holding process is not the one its host registered with, oldest renewal first.

THE SHAPE AN OPERATOR ONCE HAD NOTHING TO READ ABOUT: a completion bound to a process that died, its lease renewed by the listener and reported held by nobody. The process that was given the work is not the one this host's commands reach; the lease is still charged, and what settles it is its expiry and the host's inventory. INCARNATIONS, NOT EPOCHS: the epoch moves on every registration and the same process registers again after a control-plane restart, so comparing epochs would report every surviving lease as replaced after each one. An empty incarnation on either side was never recorded and is not compared.

func (*Queries) ListScaleSets 

func (q *Queries) ListScaleSets(ctx context.Context, org string) ([]ListScaleSetsRow, error)

Every scale set billet recorded creating for one organization.

func (*Queries) ListServiceableRunnerLeaseIDs 

func (q *Queries) ListServiceableRunnerLeaseIDs(ctx context.Context, tier string) ([]string, error)

The leases in one tier whose compute a restart should re-adopt.

RETIRING AND RETIRED POOL MEMBERS ARE EXCLUDED: their registration is being removed or is gone, so re-adopting them would hold capacity for a runner nothing can route to.

func (*Queries) LiveCertsFor 

func (q *Queries) LiveCertsFor(ctx context.Context, arg LiveCertsForParams) ([]IssuedCert, error)

The credentials one node holds that are neither expired nor already revoked.

func (*Queries) LiveJoinTokenExists 

func (q *Queries) LiveJoinTokenExists(ctx context.Context, arg LiveJoinTokenExistsParams) (bool, error)

Whether a token with this hash could possibly be spent right now.

IT AUTHORISES NOTHING. Someone else may spend the last use a microsecond later, and the enrollment transaction is what actually decides; this exists only to keep a caller with no usable token off the single writer connection.

func (*Queries) MarkLeaseDeregistered 

func (q *Queries) MarkLeaseDeregistered(ctx context.Context, id string) error

Record that GitHub's runner registration for this lease has been removed.

DELIBERATELY UNFENCED. Deregistration is a monotonic fact about GitHub, not about who holds the lease: once RemoveRunner has succeeded the runner is gone whatever the epoch. A quarantined lease has only terminal successors and a reap never relaunches on the same row -- new capacity is always a fresh id -- so no live runner can occupy a row this flag has set. Fencing it would let a reap landing between RemoveRunner and this mark strand a gone runner as counted forever.

func (*Queries) MarkLeaseFailure 

func (q *Queries) MarkLeaseFailure(ctx context.Context, arg MarkLeaseFailureParams) error

Record why a still-open lease is destined to fail.

SEPARATE FROM RELEASING IT, because the fact often arrives before the compute is gone and capacity must stay charged throughout that interval.

func (*Queries) MarkNodeNotLive 

func (q *Queries) MarkNodeNotLive(ctx context.Context, arg MarkNodeNotLiveParams) error

Record that the control plane has given up on one host.

FENCED ON THE EPOCH. Registration commits to the ledger BEFORE it takes the plane's mutex, and expiry holds that mutex while dropping the old entry -- so a host that restarts quickly could commit its new registration and then be marked dead by the expiry of the incarnation it replaced. A no-op once the epoch has moved, which is the point.

func (*Queries) MarkPoolRunnerBusy 

func (q *Queries) MarkPoolRunnerBusy(ctx context.Context, arg MarkPoolRunnerBusyParams) error

Journal a recovered legacy registration as working, without a job identity.

THE EMPTY JOB FIELDS ARE A RESERVATION FOR THIS EXACT PHYSICAL RUNNER, not a competing binding, which is why they are left alone rather than zeroed: a delayed JobStarted fills them through BindPoolRunnerJob.

func (*Queries) MarkPoolRunnerRetired 

func (q *Queries) MarkPoolRunnerRetired(ctx context.Context, arg MarkPoolRunnerRetiredParams) error

Record that compute settled while GitHub may still redeliver the completion.

THE ROW SURVIVES, which is the point: a redelivery must resolve to the same compute even after teardown and capacity release have both completed.

func (*Queries) MarkPoolRunnerRetiring 

func (q *Queries) MarkPoolRunnerRetiring(ctx context.Context, arg MarkPoolRunnerRetiringParams) error

Claim a member for teardown, having already decided it may be claimed.

func (*Queries) NodeRevocationCutoff 

func (q *Queries) NodeRevocationCutoff(ctx context.Context, node string) (string, error)

The instant before which every certificate for this name is refused.

sql.ErrNoRows means no cutoff was ever recorded for the node, which is not the same as a cutoff of zero and is why this is not a COALESCE.

func (*Queries) PendingCompletionMessage 

func (q *Queries) PendingCompletionMessage(ctx context.Context, arg PendingCompletionMessageParams) (PendingCompletionMessageRow, error)

The message id and retirement of an obligation already on file.

Read INSIDE the same transaction as the upsert below, because the disposition it decides (stale, retired, or actionable) describes the row the upsert is about to act on.

func (*Queries) PendingForceTargets 

func (q *Queries) PendingForceTargets(ctx context.Context, arg PendingForceTargetsParams) ([]PendingForceTargetsRow, error)

The leases one tier still owes a destroy for.

SCOPED TO A TIER because a listener may only act on its own escrow: destroying another tier's compute would be tearing down a lease it never held and cannot release.

func (*Queries) ReadAdmission 

func (q *Queries) ReadAdmission(ctx context.Context) (ReadAdmissionRow, error)

The deployment's admission state.

The row is inserted by the migration that creates the table, so sql.ErrNoRows means something is wrong with the ledger rather than that admission is open. ReadAdmission in admission.go is where that distinction is made.

func (*Queries) ReadBarrierRun 

func (q *Queries) ReadBarrierRun(ctx context.Context, arg ReadBarrierRunParams) (ReadBarrierRunRow, error)

One host's run under one barrier.

func (*Queries) ReadComputeBarrier 

func (q *Queries) ReadComputeBarrier(ctx context.Context) (ReadComputeBarrierRow, error)

The durable barrier request, if there is one.

func (*Queries) ReadControllerClaim 

func (q *Queries) ReadControllerClaim(ctx context.Context) (ReadControllerClaimRow, error)

Which process is this deployment's controller, and which generation of it.

THE ROW IS THE RECORD, NOT THE EXCLUSION. What actually stops a second control plane is a lock: the exclusive hold on the state directory when the ledger is a file, and a session-scoped advisory lock when it is a database two machines can reach. This table is what lets a refusal SAY WHO HAS IT, and what carries the epoch forward.

A row read from here is never permission to proceed, and that is the whole discipline of the table: it is written after the exclusion is taken, and it is read to REFUSE rather than to allow. A claim decided from a row would be deciding from what is present rather than from what is proved, which is the mistake `ca retire` took three rounds to stop making. Who holds it, and at which generation.

TWO READERS, AND THE FENCE IS THE ONE ON THE HOT PATH. DB.Tx re-reads this row inside every write transaction and refuses when the epoch has moved, which is what makes a controller that lost its exclusion unable to write rather than merely able to notice; the other reader is a refusal explaining who holds the claim it could not take. One statement serves both because the fence's own diagnostic wants the holder anyway, and reading it from the same consistent row costs nothing.

sql.ErrNoRows MEANS DIFFERENT THINGS TO THE TWO OF THEM, and neither collapses it into the other. To the diagnostic it is a fresh deployment nothing has ever claimed, which is ordinary. To the fence it is a process that DID claim and can no longer find the record, which is a refusal.

func (*Queries) ReadDeploymentBinding 

func (q *Queries) ReadDeploymentBinding(ctx context.Context) (ReadDeploymentBindingRow, error)

Which deployment these rows belong to.

THE PAIRING USED TO NEED NOTHING TO ENFORCE IT. While the ledger was a file in the identity directory, one directory meant one identity and one ledger, and there was no way to point a second identity at the same rows. A PostgreSQL ledger is reachable from anywhere and recorded nothing about whose it was, so two hosts could share one capacity record under two identities: each control plane admitting nodes against its own authority, both charging capacity into one ledger, and nothing anywhere naming the disagreement.

WRITTEN ONCE AND READ TO REFUSE, which is the same discipline as the controller claim one file over. There is no statement here that replaces a binding, deliberately: the operation that would need one is relabelling a deployment, and billet refuses that everywhere else it can arise.

(The prose in this file is ASCII, like every query file: sqlc rewrites named parameters on BYTE offsets, so one multi-byte character shifts every statement after it and the parse error names neither the file nor the character.) Which deployment this ledger says it belongs to.

sql.ErrNoRows IS AN ORDINARY STATE AND NOT A REFUSAL. A ledger migrated before this table existed carries no binding, and neither does one whose controller has not claimed yet, so an absent row means "not yet bound" and never "bound to nobody". Collapsing the two would refuse every deployment upgrading through the release that adds this.

func (*Queries) ReadEnrollment 

func (q *Queries) ReadEnrollment(ctx context.Context, name string) (NodeEnrollment, error)

Node enrollment: what has asked to join, and what an operator decided.

THE PROJECTIONS ARE IN TABLE DECLARATION ORDER on purpose. sqlc returns the model struct for a query that selects exactly the table's columns in exactly its order, and a Row type of its own for anything else -- so writing the three full reads the same way gives all three one shared type and the adapter one mapping function instead of three that must be kept identical. One request, by the name it claims.

func (*Queries) ReadEnrollmentFingerprint 

func (q *Queries) ReadEnrollmentFingerprint(ctx context.Context, name string) (string, error)

Just the key a name is currently admitted as.

SEPARATE FROM ReadEnrollment because the caller is about to overwrite the row and needs only what it is displacing; reading the CSR and the certificate to compare one column is the whole credential in memory for nothing.

func (*Queries) ReadJobConclusion 

func (q *Queries) ReadJobConclusion(ctx context.Context, leaseID string) (sql.NullString, error)

What billet's own lifecycle concluded about one lease.

func (*Queries) ReadJobFailureReason 

func (q *Queries) ReadJobFailureReason(ctx context.Context, leaseID string) (string, error)

Why it concluded that.

func (*Queries) ReadJobIdentity 

func (q *Queries) ReadJobIdentity(ctx context.Context, jobID string) (int64, error)

The identity one job holds.

READ AFTER THE INSERT RATHER THAN RETURNED BY IT, because the insert may have done nothing: the identity that matters is whatever the row holds now, which is not necessarily the number this call would have minted.

func (*Queries) ReadJobNode 

func (q *Queries) ReadJobNode(ctx context.Context, leaseID string) (sql.NullString, error)

The host a lease's job was attributed to, which outlives the lease row.

A LEASE THE LEDGER HAS ENDED STILL BELONGS TO A HOST. The wire admits a registration removal for an ended lease on the strength of this, because the lease row's placement is gone by then and a node must not be able to name another host's lease and withdraw its runner.

func (*Queries) ReadJobPlacement added in v0.8.0 

func (q *Queries) ReadJobPlacement(ctx context.Context, leaseID string) (ReadJobPlacementRow, error)

What one lease was charged for and what the cache did, from the row that outlives the lease.

ZERO IS NOT A PRICE. A host-backed lease buys nothing, so its instance_type is empty and its price is zero; a remote row written before the column existed has a shape and a zero, and a reader renders that as unknown, never as $0. The cache tokens are empty when nothing was observed, and a token this binary does not recognise is a NEWER binary's observation, rendered verbatim rather than dropped.

func (*Queries) ReadJobResult 

func (q *Queries) ReadJobResult(ctx context.Context, leaseID string) (string, error)

Job history: what GitHub concluded, kept apart from what billet's lifecycle did.

result IS GITHUB'S OWN WORD AND conclusion IS THE LEASE'S TERMINAL PHASE, and they answer different questions. A job GitHub reports as failed on a lease billet tore down perfectly is `done` in conclusion, and always was -- so nothing in the ledger could tell an operator their build failed until result existed. What GitHub concluded about the job one lease ran.

AN EMPTY ANSWER IS ONE OF THREE THINGS and no caller may collapse them: the job has not finished, this lease never ran one, or the row predates the column. sql.ErrNoRows is a fourth and separate state -- no history row at all.

func (*Queries) ReadJobStarted 

func (q *Queries) ReadJobStarted(ctx context.Context, leaseID string) (bool, error)

Whether GitHub was ever seen to start a job on this lease.

EXISTS RATHER THAN A NULLABLE READ, so "no history row" and "a row that never started" are the same answer -- neither is evidence a job ran.

func (*Queries) ReadLease 

func (q *Queries) ReadLease(ctx context.Context, id string) (ReadLeaseRow, error)

One lease, whatever phase it is in.

func (*Queries) ReadLeaseCharge added in v0.9.0 

func (q *Queries) ReadLeaseCharge(ctx context.Context, id string) (ReadLeaseChargeRow, error)

What one lease has charged the fleet since it was escrowed: the host it is charged to, the shape, and when the charge began.

FROM ESCROW, NOT ASSIGNMENT. A lease is charged the moment it is inserted, while it is still a discovery slot nobody has been given, and job_history opens its row only at assignment; a reader auditing what a host carried at an instant has to start the interval here. COALESCE(node, target_node) is the host the arithmetic charges, as everywhere else.

func (*Queries) ReadLeaseClosure 

func (q *Queries) ReadLeaseClosure(ctx context.Context, id string) (ReadLeaseClosureRow, error)

Whether one lease has finished, and when the ledger closed it.

THE ONE QUESTION THAT MAY AUTHORISE DELETING A STAGED REGISTRATION. A CodeBuild runner's JIT configuration outlives its build in Parameter Store, and from the provider alone "no build for this lease" and "the build has not appeared yet" are the same observation. What separates them is this row: a terminal phase, closed longer ago than any build could still be running. sql.ErrNoRows is a lease the ledger has never heard of, which the caller reports and never acts on.

finished_at comes from job_history, which every terminalization writes; the COALESCE is for a row that predates the column, which reads as "closed at an unknown time" and is therefore never old enough.

func (*Queries) ReadLeaseEpoch 

func (q *Queries) ReadLeaseEpoch(ctx context.Context, id string) (int64, error)

The capacity ledger's central row.

A LEASE IS THE UNIT OF CAPACITY, and every rule about not promising a machine billet does not have is expressed as a predicate on this table. Two of them recur in almost every statement and are worth knowing before reading any of them: 

COALESCE(node, target_node)   `node` is where the work actually went and
                              `target_node` is where billet decided it
                              would go. Capacity is charged on the
                              coalesce, because a reservation aimed at a
                              machine has already spent that machine's
                              room -- counting only bound leases let a tier
                              escrow against the same host repeatedly in
                              the window before its first launch.

AND epoch = @epoch            The fence. A holder declared dead and replaced
                              must not keep writing to a lease somebody else
                              now owns, so every write that acts on a row a
                              caller read presents the epoch it read.

One lease's current fencing token.

sql.ErrNoRows means the lease is gone, which callers report as ErrLeaseNotFound rather than as a read failure.

func (*Queries) ReadLeaseJob 

func (q *Queries) ReadLeaseJob(ctx context.Context, id string) (ReadLeaseJobRow, error)

The tier and job identity one lease carries.

func (*Queries) ReadLeaseSettlement 

func (q *Queries) ReadLeaseSettlement(ctx context.Context, id string) (ReadLeaseSettlementRow, error)

What settling one lease against a completion needs to know.

func (*Queries) ReadLeaseTargetSize 

func (q *Queries) ReadLeaseTargetSize(ctx context.Context, id string) (ReadLeaseTargetSizeRow, error)

One lease's target host, its cost, and whether that host is reachable.

LEFT JOIN, because a target naming a host the ledger has never heard of is the same situation as one it has forgotten: there is nowhere for that reservation to go, and an inner join would report the lease as absent instead.

func (*Queries) ReadNewestRolloutForTarget added in v0.6.0 

func (q *Queries) ReadNewestRolloutForTarget(ctx context.Context, targetDigest string) (Rollout, error)

The newest rollout, in any state, to one manifest digest: what an automatic start consults before it would restart bytes an operator abandoned.

func (*Queries) ReadNodeBarrierFence 

func (q *Queries) ReadNodeBarrierFence(ctx context.Context, name string) (ReadNodeBarrierFenceRow, error)

The fence a barrier observation of this host must carry, plus liveness.

LIVENESS IS NOT PART OF THE FENCE and travels here only so one read answers the whole question: a host billet cannot reach still holds whatever it holds.

func (*Queries) ReadNodeCapacity 

func (q *Queries) ReadNodeCapacity(ctx context.Context, name string) (ReadNodeCapacityRow, error)

What one host has, and the shapes it can buy.

func (*Queries) ReadNodeEpoch 

func (q *Queries) ReadNodeEpoch(ctx context.Context, name string) (int64, error)

One host's registration fence.

A REGISTRATION BUMPS IT AND NOTHING ELSE DOES, so a value that has not moved proves the answer is about the same incarnation the caller was talking to. sql.ErrNoRows means the host is not in the fleet, which is not the same as a host whose epoch has moved and must not be reported as one.

func (*Queries) ReadNodeFence 

func (q *Queries) ReadNodeFence(ctx context.Context, name string) (ReadNodeFenceRow, error)

Just the two fences, for the paths that have already decided about liveness.

func (*Queries) ReadNodeHighestRelease added in v0.6.0 

func (q *Queries) ReadNodeHighestRelease(ctx context.Context, name string) (string, error)

The newest release one host has registered with, for the registration that is about to decide whether this one is newer still.

sql.ErrNoRows means the host was never registered, which the caller reads as "nothing recorded" rather than as an error.

func (*Queries) ReadNodeIncarnation 

func (q *Queries) ReadNodeIncarnation(ctx context.Context, name string) (string, error)

The process one host presented at its current registration, or ” for a host that never presented one.

THE DURABLE NAME OF A PROCESS, which the epoch is not: the epoch moves on every registration and the same process registers again after a control-plane restart. A lease records this at Bind and on entry to custody or teardown, so a report can say whether the process holding it is the one the host runs now. sql.ErrNoRows means the host is not in the fleet.

func (*Queries) ReadNodeLiveness 

func (q *Queries) ReadNodeLiveness(ctx context.Context, name string) (int64, error)

Whether the deployment can currently reach one host.

sql.ErrNoRows means the host was never registered, which the caller reports differently from a host that is simply not answering.

func (*Queries) ReadNodeProvider 

func (q *Queries) ReadNodeProvider(ctx context.Context, name string) (string, error)

The backend one host reported at registration.

THE REGISTERED ONE, NEVER A CATALOGUE'S CLAIM. Placement asks whether a lease's acceptable backends include what the machine itself said it runs; a firecracker lease cannot run on a Tart host whatever the config says.

func (*Queries) ReadNodeRegistration 

func (q *Queries) ReadNodeRegistration(ctx context.Context, name string) (ReadNodeRegistrationRow, error)

The facts a re-registration has to be checked against.

func (*Queries) ReadNodeSize 

func (q *Queries) ReadNodeSize(ctx context.Context, name string) (ReadNodeSizeRow, error)

What one host says it has.

func (*Queries) ReadPoolRunnerByLease 

func (q *Queries) ReadPoolRunnerByLease(ctx context.Context, leaseID string) (PoolRunner, error)

The pool member backed by one lease.

THE COMPUTE AUTHORITY WHEN NO MESSAGE CARRIES A RUNNER NAME. Read inside the write transaction by every mutation below, against the row that write acts on.

func (*Queries) ReadPoolRunnerByName 

func (q *Queries) ReadPoolRunnerByName(ctx context.Context, runnerName string) (PoolRunner, error)

GitHub's runner identity resolved to billet's compute lease.

func (*Queries) ReadPoolRunnerSettlementByRequest 

func (q *Queries) ReadPoolRunnerSettlementByRequest(ctx context.Context, arg ReadPoolRunnerSettlementByRequestParams) (ReadPoolRunnerSettlementByRequestRow, error)

What settling one launch request needs to know.

ONE STATEMENT FOR BOTH SETTLEMENT PATHS. A completion settles the physical runner and an acknowledgement records that GitHub cannot redeliver; each reads two of these three columns, and splitting them into two queries would be two statements that must agree about how a request identifies a member.

func (*Queries) ReadPoolSlotIdentity 

func (q *Queries) ReadPoolSlotIdentity(ctx context.Context, leaseID string) (int64, error)

The identity one lease's pool slot holds.

func (*Queries) ReadReleaseWatermark added in v0.6.0 

func (q *Queries) ReadReleaseWatermark(ctx context.Context) (ReadReleaseWatermarkRow, error)

The newest release that has served this ledger.

A SCHEMA VERSION IS NOT A RELEASE VERSION. A binary refuses a migration it has never heard of, and that was the only downgrade guard the ledger had; it is silent for every pair of releases that share a schema, which is most of them. This row is what lets an open say "a newer billet has been serving these rows" whether or not a migration happened in between.

WRITTEN BY THE CONTROL PLANE ONLY, and only forwards. An operator command from a newer binary records nothing, because a `billet check` run from a laptop would otherwise fence the running server out of its own next restart. The one write that lowers it is the host upgrade's deliberate downgrade, through the maintenance handle, after the ledger snapshot that keeps the higher mark for a rollback.

(The prose in this file is ASCII, like every query file: sqlc rewrites named parameters on BYTE offsets, so one multi-byte character shifts every statement after it and the parse error names neither the file nor the character.) Which release last raised the mark, and when.

sql.ErrNoRows IS AN ORDINARY STATE. A ledger migrated before this table existed carries no mark, and so does one no control plane has served since; the caller reads an absent row as "nothing is known" and never as a release.

func (*Queries) ReadRolloutControllerPhase 

func (q *Queries) ReadRolloutControllerPhase(ctx context.Context, id string) (string, error)

Where the control plane itself has got to in one rollout.

func (*Queries) ReadRolloutInState 

func (q *Queries) ReadRolloutInState(ctx context.Context, state string) (Rollout, error)

The rollout in one state.

A :one AND ONLY SAFE FOR 'open', which is the single state carrying a partial unique index (rollouts_open). Its one caller passes StateOpen; a caller that passed 'completed' would get an arbitrary one of many rows, which is why the state stays a parameter naming the Go constant rather than a literal here that would read as a guarantee this statement cannot make.

func (*Queries) ReadRolloutNodeProgress 

func (q *Queries) ReadRolloutNodeProgress(ctx context.Context, arg ReadRolloutNodeProgressParams) (ReadRolloutNodeProgressRow, error)

One host's phase and attempt count, read against the row a write will act on.

func (*Queries) ReclaimLease 

func (q *Queries) ReclaimLease(ctx context.Context, arg ReclaimLeaseParams) error

Terminalize or quarantine an expired lease, bumping the fence.

THE EPOCH BUMP IS THE POINT. A holder that comes back -- a paused process, a healed partition -- finds its writes refused rather than silently operating on a lease somebody else now owns.

held_at IS SET ONLY ON THE WAY INTO QUARANTINE, and only if it is empty: that is when the proof obligation starts, and a lease reaped twice must not have its age reset.

func (*Queries) RecordBarrierRun 

func (q *Queries) RecordBarrierRun(ctx context.Context, arg RecordBarrierRunParams) error

Extend one host's continuous-empty run, or start a new one.

THE RUN'S START IS PRESERVED, AND ONLY WHERE EVERY PART OF ITS IDENTITY MATCHES. Taking excluded.empty_since unconditionally would restart the clock on every sample, so a host could never cross the grace no matter how long it stayed empty; taking the stored one unconditionally would carry a run across a reconnect or a launch. The CASE is what makes it a run rather than either.

func (*Queries) RecordCredentialSweep 

func (q *Queries) RecordCredentialSweep(ctx context.Context, arg RecordCredentialSweepParams) error

What the control plane's sweep of staged CodeBuild registrations did, one row per region and Parameter Store path.

A RECORD, NOT A DECISION. Nothing reads this to decide whether a parameter may be deleted -- that is answered per lease by ReadLeaseSettlement. It exists so `billet status`, which runs in another process, can say what the sweep removed, what it is still waiting on, and whether its last pass failed. Record one pass over one path.

removed IS THE LAST PASS AND removed_total ACCUMULATES, so a status line can show both "3 removed in total" and whether the most recent pass did anything. Every other column describes the last pass only: kept and unaccounted are counts of what is there now, and error is empty on a pass that completed.

func (*Queries) RecordHistoryCacheObservation added in v0.8.0 

func (q *Queries) RecordHistoryCacheObservation(ctx context.Context, arg RecordHistoryCacheObservationParams) error

And onto its history row, the moment it is observed.

WRITTEN NOW, NOT LEFT TO archive, for the reason a disruption is: a lease terminalizes whenever its teardown finally succeeds, which can be hours after the job ended or never. Unfenced, like RecordHistoryDisruption: the row is keyed by the lease and the observation is about the job, not about who holds the lease. A lease that never reached Assign has no history row and this updates nothing, which is correct: it ran no job.

func (*Queries) RecordHistoryDisruption 

func (q *Queries) RecordHistoryDisruption(ctx context.Context, arg RecordHistoryDisruptionParams) error

And onto its history row.

WRITTEN NOW, NOT LEFT TO archive. A lease terminalizes whenever its teardown finally succeeds, which can be hours after the job ended or never -- and a job whose teardown is wedged on a host that vanished is exactly the one an operator is looking for. A lease that never reached Assign has no history row and this updates nothing, which is correct: it ran no job.

func (*Queries) RecordIssuedCert 

func (q *Queries) RecordIssuedCert(ctx context.Context, arg RecordIssuedCertParams) error

Certificates this deployment issued, and the ones it has taken back.

TWO REVOCATION MECHANISMS, and both are here because neither is sufficient alone: a serial names one credential, which is the right granularity because a node name is legitimately re-issued to a replacement machine; a per-node cutoff reaches the credentials billet never recorded, which is the only handle a deployment upgraded from a version that did not record serials has. Write down a credential at the moment it is handed out.

DO NOTHING rather than DO UPDATE: a serial identifies one credential, so a second insert under the same serial is a retry rather than a new fact.

func (*Queries) RecordJobAssignment 

func (q *Queries) RecordJobAssignment(ctx context.Context, arg RecordJobAssignmentParams) error

Open the history row when the job is assigned.

AT ASSIGNMENT RATHER THAN AT TERMINALIZATION, so the row carries a real assignment time instead of one fabricated when the lease closes.

THE HOST IS COALESCE(node, target_node), the way the rest of the arithmetic reads a lease: `node` is filled at bind and escrow chose the machine long before that, so a lease that never binds -- assigned by GitHub, then the process dies -- recorded no host at all, and the jobs most worth investigating are exactly the ones that end that way.

func (*Queries) RecordJobResult 

func (q *Queries) RecordJobResult(ctx context.Context, arg RecordJobResultParams) error

Store GitHub's conclusion, verbatim.

STORED VERBATIM, and the caller's trim is only ever a blankness TEST. Normalising here would decide the report: `" succeeded "` trimmed to `"succeeded"` vanishes from it, and the one thing this column must not do is turn a value billet does not recognise into one it does. An unknown result fails OPEN into the report, quoted, where a person can see the padding.

func (*Queries) RecordJobRun 

func (q *Queries) RecordJobRun(ctx context.Context, arg RecordJobRunParams) error

Fill in the workflow run when the ledger has none, and only then.

NEVER AN OVERWRITE. A pooled runner is launched before GitHub chooses its job, so the escrow records run 0 and the lease's own launch request id; the run an operator needs is the one on the COMPLETION. But a recorded run is the one this lease was assigned, and replacing it would let a swapped pool member rewrite another job's history -- which is why the filter is in the statement rather than in a branch above it.

func (*Queries) RecordJobStart 

func (q *Queries) RecordJobStart(ctx context.Context, arg RecordJobStartParams) error

Record that GitHub started a job on this lease, once.

THE LEDGER'S OWN EVIDENCE THAT A JOB RAN, written when the lease reaches `busy`, and kept at its first value: the phase moves on to custody or teardown and forgets it was ever busy, while a reason a node sends later may claim the launch never ran. A row that never reached busy keeps NULL.

func (*Queries) RecordLeaseCacheObservation added in v0.8.0 

func (q *Queries) RecordLeaseCacheObservation(ctx context.Context, arg RecordLeaseCacheObservationParams) error

Cache observations: what the cache did for one job, as the node saw it.

AN OBSERVATION, NEVER A VERDICT, and from a CLOSED vocabulary the node writes from what it saw rather than what the tier intended -- alloc.ImageCache and alloc.ActionsCache hold the sets, and every new observation goes through their Valid() before it reaches a statement here. The empty string is the zero value and means nothing was observed.

THE FIRST OBSERVATION IS KEPT, and the guard is in the statement rather than in a branch above it: each column is written only while it is empty, so a repeat from a node retrying a lost response changes nothing and a later, different observation cannot replace what the guest first saw. The generation moves with the image-cache token so a report never shows a generation with nothing to attribute it to. TestBothCacheObservationStatementsKeepTheFirst pins the guard on both statements. Write the observation onto the live lease, fenced on its epoch.

func (*Queries) RecordLeaseDisruption 

func (q *Queries) RecordLeaseDisruption(ctx context.Context, arg RecordLeaseDisruptionParams) error

Write the observation onto the live lease.

func (*Queries) RecordMigration 

func (q *Queries) RecordMigration(ctx context.Context, arg RecordMigrationParams) error

Record one migration as applied, in the same transaction that applied it.

The checksum is over the statement BYTES, so this row is what a later open compares against to refuse an edited migration.

func (*Queries) RecordNodeRevocation 

func (q *Queries) RecordNodeRevocation(ctx context.Context, arg RecordNodeRevocationParams) error

Refuse every certificate for this name minted before an instant.

UPSERT, because a node revoked twice moves its cutoff forward. The reason and the timestamp move with it, so the row describes the revocation in force rather than the first one ever recorded.

func (*Queries) RefreshLeaseHolder 

func (q *Queries) RefreshLeaseHolder(ctx context.Context, arg RefreshLeaseHolderParams) error

Re-record which process holds a lease already in a held phase.

FOR A REPORT OF A HOLD THE LEASE IS ALREADY IN. A restart adopts a teardown or custody it finds and reports the same phase; the idempotent report writes nothing else, and without this the process that died would stay the durable holder while its replacement renews and tends the compute. Fenced on the epoch like every other write, and a no-op when nothing changed.

func (*Queries) ReplaceDeniedEnrollment 

func (q *Queries) ReplaceDeniedEnrollment(ctx context.Context, arg ReplaceDeniedEnrollmentParams) error

Let a different key take a name a denial is holding.

ONLY FOR A DENIED ROW, which the caller checks: pending and approved still hold the name, because an operator who compared a fingerprint yesterday must not be approving a different machine today under a name they already trust. A denial holds nothing, because the enrolling process keeps its private key in memory while it waits for a human -- so a reboot loses the key and, without this, the machine that comes back is refused forever.

func (*Queries) RequestForceRelease 

func (q *Queries) RequestForceRelease(ctx context.Context, arg RequestForceReleaseParams) error

Ask a live custody holder to give up a lease.

IT DOES NOT TERMINALIZE. Custody and teardown have a process that still believes it owns the proof obligation; this makes its next heartbeat return ErrForceRelease so that process drops its record and releases the lease itself, rather than the ledger changing underneath it.

THE OPERATOR'S ASSERTION IS RECORDED AS THE REASON, in the same statement, unless a reason is already there: the holder releases the lease as failed and the history would otherwise carry a failure nothing explains.

func (*Queries) ResizeLease 

func (q *Queries) ResizeLease(ctx context.Context, arg ResizeLeaseParams) error

Authorise a remote fallback shape, atomically with the budget check above it.

A LATER FALLBACK IS A NEW PURCHASE DECISION, so its larger resource vector must fit before the launch request is allowed onto the wire -- never reconciled afterwards.

THE PRICE MOVES WITH THE SHAPE: a fallback is a different purchase at a different rate, and the history records what was bought.

func (*Queries) RetirePendingCompletion 

func (q *Queries) RetirePendingCompletion(ctx context.Context, arg RetirePendingCompletionParams) error

Make replay a no-op BEFORE deletion is attempted.

Scoped to the message id: a redelivery that arrives as a later message is a new obligation, not one this settlement covers.

func (*Queries) RevokeCert 

func (q *Queries) RevokeCert(ctx context.Context, arg RevokeCertParams) error

Withdraw one certificate, idempotently.

Revoking twice is not an error: an operator who is not sure whether the first attempt landed must be able to run it again.

func (*Queries) SetAdmission 

func (q *Queries) SetAdmission(ctx context.Context, arg SetAdmissionParams) error

One admission transition, refusing if the generation moved.

THE GENERATION IS IN THE WHERE as well as the SET: the caller has already compared it inside this transaction, and repeating it here means a write can never land on a row it did not read.

func (*Queries) SetLeasePhase 

func (q *Queries) SetLeasePhase(ctx context.Context, arg SetLeasePhaseParams) error

Move a lease to a phase the caller has already validated.

func (*Queries) SetReleaseWatermark added in v0.6.0 

func (q *Queries) SetReleaseWatermark(ctx context.Context, arg SetReleaseWatermarkParams) error

Record the release now serving this ledger.

AN UPSERT, BECAUSE THE MARK MOVES. Forward on every control-plane open that finds itself newer than the record, and backward exactly once, by a person, on a downgrade they asked for by name. Which direction is allowed is decided in Go under the writer's own transaction, where the comparison and the write are one decision; the statement itself takes whatever it is handed.

func (*Queries) SettleForceTarget 

func (q *Queries) SettleForceTarget(ctx context.Context, arg SettleForceTargetParams) (sql.Result, error)

Record what became of one lease, and only while it is still pending.

:execresult because ALREADY SETTLED IS NOT AN ERROR. A listener that restarts re-observes the request and may act on a target another incarnation already finished, so the caller reads RowsAffected to tell "I settled it" from "somebody already had".

func (*Queries) SpendJoinToken 

func (q *Queries) SpendJoinToken(ctx context.Context, arg SpendJoinTokenParams) (sql.Result, error)

Check a token and consume one use, in one statement.

CHECK AND DECREMENT TOGETHER, so two machines racing on a single-use token cannot both be admitted: this matches only while a use remains and the token is unexpired, and whichever commits second changes no rows. The caller reads RowsAffected, which is why this is :execresult and not :exec -- an :exec returns nothing to distinguish "spent" from "there was nothing to spend".

func (*Queries) StartPoolRunner 

func (q *Queries) StartPoolRunner(ctx context.Context, arg StartPoolRunnerParams) error

Bind an idle member to the job GitHub gave it.

func (*Queries) TerminalizeQuarantinedLease 

func (q *Queries) TerminalizeQuarantinedLease(ctx context.Context, arg TerminalizeQuarantinedLeaseParams) error

Settle a quarantined lease with the caller's outcome, bumping the fence.

THE OUTCOME IS THE CALLER'S. A listener resolving one after a completion knows the job finished; a node cleaning up compute it could not account for, and an operator forcing a machine that is never coming back, both know the opposite. Recording every one of them as failed puts a lie in the history of a job GitHub reported completed.

func (*Queries) TerminalizeQuarantinedLeaseWithReason 

func (q *Queries) TerminalizeQuarantinedLeaseWithReason(ctx context.Context, arg TerminalizeQuarantinedLeaseWithReasonParams) error

Fail a quarantined lease whose guest an inventory did not contain.

SEPARATE FROM THE STATEMENT ABOVE because it also records WHY, and that reason may be the provisional marker a later GitHub completion is allowed to correct.

func (*Queries) TerminateForcedLease 

func (q *Queries) TerminateForcedLease(ctx context.Context, arg TerminateForcedLeaseParams) error

Settle a lease whose compute an operator destroyed.

FENCED, because the phase was read inside this transaction and a lease can acquire a live holder between a backend being asked to stop a guest and its capacity being returned.

func (*Queries) TotalUsage 

func (q *Queries) TotalUsage(ctx context.Context) (TotalUsageRow, error)

What the whole deployment has committed.

func (*Queries) UpsertCacheBlock 

func (q *Queries) UpsertCacheBlock(ctx context.Context, arg UpsertCacheBlockParams) error

Disable interception for one explicit scope, refreshing when it was decided.

func (*Queries) UpsertComputeBarrier 

func (q *Queries) UpsertComputeBarrier(ctx context.Context, arg UpsertComputeBarrierParams) error

Record the one barrier request this deployment may have outstanding.

A SINGLETON BY CONSTRUCTION (id = 1, CHECKed by the schema): two barriers would each be collecting observations the other's generation invalidates.

func (*Queries) UpsertIssuedEnrollment 

func (q *Queries) UpsertIssuedEnrollment(ctx context.Context, arg UpsertIssuedEnrollmentParams) error

Record a certificate handed out directly by `billet ca issue`.

IT OVERWRITES, unlike the wire, and that is deliberate: issuing is a deliberate operator act and refusing would leave a name unusable after a machine was rebuilt. csr_pem is left alone by the update because this path never had one; requested_at likewise keeps the first admission's timestamp.

func (*Queries) UpsertNodeInventory 

func (q *Queries) UpsertNodeInventory(ctx context.Context, arg UpsertNodeInventoryParams) error

Record what a host last said it was running.

EVIDENCE, NOT PROOF. The node lists its provider and THEN posts, so received_at is when the report ARRIVED and never when the snapshot was taken -- a launch can be dispatched to that host immediately afterwards. Nothing may read this as clearance.

func (*Queries) UpsertNodeRegistration 

func (q *Queries) UpsertNodeRegistration(ctx context.Context, arg UpsertNodeRegistrationParams) (int64, error)

Register a host, or re-register one, and return its new fence.

THE EPOCH ALWAYS MOVES, which is what makes it the fleet's one causal signal: a registration is the only thing that bumps it, so a value that has not changed proves an answer is about the same incarnation.

A HOST THAT COMES BACK IS A MEMBER AGAIN. A decommission is a person asserting a machine is gone; the machine registering is that assertion being contradicted by the machine itself, and an exclusion nobody remembers would hide a live host from every later drain forever. `drained` is cleared with it, because that is the column placement and the floor arithmetic read.

func (*Queries) UpsertPendingCompletion 

func (q *Queries) UpsertPendingCompletion(ctx context.Context, arg UpsertPendingCompletionParams) error

Durably record a result-delivery obligation.

THE CASE ARMS ARE THE REDELIVERY RULE, and they are not decoration. A redelivery of the SAME message must not undo settlement that has already happened: once a row is retired, or once it has been narrowed to a release only, the lease fields and outcome on file win over what the delivery carries. A LATER message (a higher message_id) replaces them outright, and the trailing WHERE drops an EARLIER one entirely.

release_only, retired and acknowledged are max()'d for the same message so a redelivery can only ever move them forward.

func (*Queries) UpsertScaleSet 

func (q *Queries) UpsertScaleSet(ctx context.Context, arg UpsertScaleSetParams) error

Remember that billet created this scale set.

The id is REFRESHED rather than kept: the server reconciles every tier on every start, so this runs constantly against rows that already exist, and a stale id would send an operator looking for an object that no longer exists.

func (*Queries) UsageByNode 

func (q *Queries) UsageByNode(ctx context.Context) ([]UsageByNodeRow, error)

Every host's committed capacity, keyed the way a lease is attributed.

func (*Queries) UsageOnNode 

func (q *Queries) UsageOnNode(ctx context.Context, node string) (UsageOnNodeRow, error)

One host's committed capacity.

func (*Queries) WithTx 

func (q *Queries) WithTx(tx *sql.Tx) *Queries

func (*Queries) WithdrawNode 

func (q *Queries) WithdrawNode(ctx context.Context, arg WithdrawNodeParams) (int64, error)

Record that one host said it is leaving, and take it out of placement.

FENCED ON THE EPOCH AND THE INCARNATION, and both are needed. The epoch is the registration fence -- a withdrawal that arrives after the host has registered again matches nothing -- and the incarnation is the durable name of the PROCESS, so a superseded process that still holds the certificate cannot take its replacement out of the fleet. Zero rows is the caller's answer that the fence moved.

ONLY `live`. A withdrawal is not a decommission (drained, decommissioned_at and the proof columns are untouched), releases no lease, and leaves the host's inventory and barrier run alone -- the next registration discards those, exactly as it does after silence. What changes is that ListPlaceableNodes stops offering the host at once instead of after the silence window.

type ReadAdmissionRow 

type ReadAdmissionRow struct {
	Mode       string
	Generation int64
	Provenance string
	Reason     string
	Actor      string
	ChangedAt  string
}

type ReadBarrierRunParams 

type ReadBarrierRunParams struct {
	Node      string
	BarrierID string
}

type ReadBarrierRunRow 

type ReadBarrierRunRow struct {
	NodeEpoch          int64
	DispatchGeneration int64
	EmptySince         string
	ObservedAt         string
}

type ReadComputeBarrierRow 

type ReadComputeBarrierRow struct {
	BarrierID           string
	AdmissionGeneration int64
	RequestedAt         string
	RequestedBy         string
}

type ReadControllerClaimRow 

type ReadControllerClaimRow struct {
	Holder    string
	Epoch     int64
	ClaimedAt string
}

type ReadDeploymentBindingRow 

type ReadDeploymentBindingRow struct {
	DeploymentID string
	BoundAt      string
}

type ReadJobPlacementRow added in v0.8.0 

type ReadJobPlacementRow struct {
	ChosenProvider     string
	InstanceType       string
	Vcpu               int64
	Memory             int64
	Site               string
	PriceMicrosPerHour int64
	ImageCache         string
	CacheGeneration    string
	ActionsCache       string
}

type ReadLeaseChargeRow added in v0.9.0 

type ReadLeaseChargeRow struct {
	Host      string
	Vcpu      int64
	Memory    int64
	CreatedAt string
}

type ReadLeaseClosureRow 

type ReadLeaseClosureRow struct {
	Phase      string
	FinishedAt string
}

type ReadLeaseJobRow 

type ReadLeaseJobRow struct {
	Tier      string
	RunID     sql.NullInt64
	RequestID sql.NullInt64
}

type ReadLeaseRow 

type ReadLeaseRow struct {
	ID                 string
	Tier               string
	Node               sql.NullString
	TargetNode         sql.NullString
	MacosSlot          int64
	GuestOs            string
	Providers          string
	ChosenProvider     string
	Phase              string
	Vcpu               int64
	Memory             int64
	RequestedVcpu      int64
	RequestedMemory    int64
	InstanceType       string
	Site               string
	PriceMicrosPerHour int64
	ImageCache         string
	CacheGeneration    string
	ActionsCache       string
	HeldAt             string
	ForceRelease       int64
	HolderIncarnation  string
	FailureReason      string
	Disruption         string
	DisruptedAt        string
	Epoch              int64
	RunID              sql.NullInt64
	RequestID          sql.NullInt64
}

type ReadLeaseSettlementRow 

type ReadLeaseSettlementRow struct {
	Phase         string
	Epoch         int64
	FailureReason string
}

type ReadLeaseTargetSizeRow 

type ReadLeaseTargetSizeRow struct {
	TargetNode sql.NullString
	Vcpu       int64
	Memory     int64
	Live       sql.NullInt64
}

type ReadNodeBarrierFenceRow 

type ReadNodeBarrierFenceRow struct {
	Epoch              int64
	DispatchGeneration int64
	WireVersion        int64
	Live               int64
}

type ReadNodeCapacityRow 

type ReadNodeCapacityRow struct {
	TotalVcpu   int64
	TotalMemory int64
	Ec2Shapes   string
}

type ReadNodeFenceRow 

type ReadNodeFenceRow struct {
	Epoch              int64
	DispatchGeneration int64
}

type ReadNodeRegistrationRow 

type ReadNodeRegistrationRow struct {
	Provider       string
	Site           string
	Ec2Shapes      string
	CodebuildFleet string
}

type ReadNodeSizeRow 

type ReadNodeSizeRow struct {
	TotalVcpu   int64
	TotalMemory int64
}

type ReadPoolRunnerSettlementByRequestParams 

type ReadPoolRunnerSettlementByRequestParams struct {
	Tier            string
	LaunchRequestID int64
}

type ReadPoolRunnerSettlementByRequestRow 

type ReadPoolRunnerSettlementByRequestRow struct {
	LeaseID            string
	Status             string
	SourceAcknowledged int64
}

type ReadReleaseWatermarkRow added in v0.6.0 

type ReadReleaseWatermarkRow struct {
	Release    string
	RecordedAt string
}

type ReadRolloutNodeProgressParams 

type ReadRolloutNodeProgressParams struct {
	RolloutID string
	Node      string
}

type ReadRolloutNodeProgressRow 

type ReadRolloutNodeProgressRow struct {
	Phase    string
	Attempts int64
}

type ReclaimLeaseParams 

type ReclaimLeaseParams struct {
	Phase      string
	Quarantine string
	HeldAt     string
	ID         string
	Epoch      int64
}

type RecordBarrierRunParams 

type RecordBarrierRunParams struct {
	Node               string
	BarrierID          string
	NodeEpoch          int64
	DispatchGeneration int64
	Now                string
}

type RecordCredentialSweepParams 

type RecordCredentialSweepParams struct {
	Region       string
	Path         string
	SweptAt      string
	Removed      int64
	Kept         int64
	Unaccounted  int64
	ForeignNames int64
	Error        string
}

type RecordHistoryCacheObservationParams added in v0.8.0 

type RecordHistoryCacheObservationParams struct {
	ImageCache      string
	CacheGeneration string
	ActionsCache    string
	LeaseID         string
}

type RecordHistoryDisruptionParams 

type RecordHistoryDisruptionParams struct {
	Disruption  string
	DisruptedAt string
	LeaseID     string
}

type RecordIssuedCertParams 

type RecordIssuedCertParams struct {
	Serial   string
	Node     string
	Source   string
	NotAfter string
	IssuedAt string
}

type RecordJobAssignmentParams 

type RecordJobAssignmentParams struct {
	LeaseID    string
	Tier       string
	Node       sql.NullString
	RunID      sql.NullInt64
	RequestID  sql.NullInt64
	QueuedAt   string
	AssignedAt sql.NullString
}

type RecordJobResultParams 

type RecordJobResultParams struct {
	Result   string
	ResultAt string
	LeaseID  string
}

type RecordJobRunParams 

type RecordJobRunParams struct {
	RunID   sql.NullInt64
	LeaseID string
}

type RecordJobStartParams 

type RecordJobStartParams struct {
	StartedAt sql.NullString
	LeaseID   string
}

type RecordLeaseCacheObservationParams added in v0.8.0 

type RecordLeaseCacheObservationParams struct {
	ImageCache      string
	CacheGeneration string
	ActionsCache    string
	ID              string
	Epoch           int64
}

type RecordLeaseDisruptionParams 

type RecordLeaseDisruptionParams struct {
	Disruption  string
	DisruptedAt string
	ID          string
}

type RecordMigrationParams 

type RecordMigrationParams struct {
	Version   int64
	Name      string
	Checksum  string
	AppliedAt string
}

type RecordNodeRevocationParams 

type RecordNodeRevocationParams struct {
	Node          string
	RevokedBefore string
	Reason        string
	RevokedAt     string
}

type RefreshLeaseHolderParams 

type RefreshLeaseHolderParams struct {
	HolderIncarnation string
	ID                string
	Epoch             int64
}

type ReplaceDeniedEnrollmentParams 

type ReplaceDeniedEnrollmentParams struct {
	Fingerprint string
	CsrPem      string
	State       string
	RequestedAt string
	Name        string
}

type RequestForceReleaseParams 

type RequestForceReleaseParams struct {
	Reason string
	ID     string
	Epoch  int64
}

type ResizeLeaseParams 

type ResizeLeaseParams struct {
	Vcpu               int64
	Memory             int64
	InstanceType       string
	PriceMicrosPerHour int64
	ID                 string
	Epoch              int64
}

type RetirePendingCompletionParams 

type RetirePendingCompletionParams struct {
	Tier      string
	RequestID int64
	MessageID int64
}

type RevokeCertParams 

type RevokeCertParams struct {
	Serial    string
	Node      string
	Reason    string
	RevokedAt string
}

type RevokedCert 

type RevokedCert struct {
	Serial    string
	Node      string
	Reason    string
	RevokedAt string
}

type Rollout 

type Rollout struct {
	ID              string
	Generation      int64
	Channel         string
	TargetVersion   string
	TargetDigest    string
	Policy          string
	ControllerPhase string
	PriorVersion    string
	State           string
	CreatedBy       string
	CreatedAt       string
	FinishedAt      string
	TerminalReason  string
}

type SetAdmissionParams 

type SetAdmissionParams struct {
	Mode       string
	Generation int64
	Provenance string
	Reason     string
	Actor      string
	ChangedAt  string
	Expect     int64
}

type SetLeasePhaseParams 

type SetLeasePhaseParams struct {
	Phase string
	ID    string
	Epoch int64
}

type SetReleaseWatermarkParams added in v0.6.0 

type SetReleaseWatermarkParams struct {
	Release    string
	RecordedAt string
}

type SettleForceTargetParams 

type SettleForceTargetParams struct {
	State      string
	Detail     string
	Generation int64
	LeaseID    string
	WasState   string
}

type SpendJoinTokenParams 

type SpendJoinTokenParams struct {
	TokenSha256 string
	Now         string
}

type StartPoolRunnerParams 

type StartPoolRunnerParams struct {
	RunnerID        int64
	ActualRequestID int64
	RunID           int64
	JobID           string
	UpdatedAt       string
	LeaseID         string
}

type TerminalizeQuarantinedLeaseParams 

type TerminalizeQuarantinedLeaseParams struct {
	Phase string
	ID    string
}

type TerminalizeQuarantinedLeaseWithReasonParams 

type TerminalizeQuarantinedLeaseWithReasonParams struct {
	FailureReason string
	ID            string
}

type TerminateForcedLeaseParams 

type TerminateForcedLeaseParams struct {
	Phase         string
	FailureReason string
	ID            string
	Epoch         int64
}

type TotalUsageRow 

type TotalUsageRow struct {
	Vcpu   int64
	Memory int64
	Leases int64
}

type UpsertCacheBlockParams 

type UpsertCacheBlockParams struct {
	ScopeType  string
	Owner      string
	Repository string
	DisabledAt string
}

type UpsertComputeBarrierParams 

type UpsertComputeBarrierParams struct {
	BarrierID           string
	AdmissionGeneration int64
	RequestedAt         string
	RequestedBy         string
}

type UpsertIssuedEnrollmentParams 

type UpsertIssuedEnrollmentParams struct {
	Name        string
	Fingerprint string
	CertPem     string
	State       string
	RequestedAt string
	DecidedAt   string
}

type UpsertNodeInventoryParams 

type UpsertNodeInventoryParams struct {
	Node       string
	NodeEpoch  int64
	ReceivedAt string
	Running    int64
}

type UpsertNodeRegistrationParams 

type UpsertNodeRegistrationParams struct {
	Name             string
	Provider         string
	Site             string
	TotalVcpu        int64
	TotalMemory      int64
	Ec2Shapes        string
	LastSeenAt       string
	NodeRelease      string
	WireMin          int64
	WireMax          int64
	WireVersion      int64
	NodeDigest       string
	CodebuildFleet   string
	CodebuildJitPath string
	CodebuildRegion  string
	Incarnation      string
	HighestRelease   string
}

type UpsertPendingCompletionParams 

type UpsertPendingCompletionParams struct {
	Tier         string
	RequestID    int64
	RunID        int64
	Result       string
	LeaseID      string
	LeaseEpoch   int64
	LeaseNode    string
	Outcome      string
	ReleaseOnly  int64
	MessageID    int64
	Retired      int64
	Acknowledged int64
}

type UpsertScaleSetParams 

type UpsertScaleSetParams struct {
	Org         string
	RunnerGroup string
	Label       string
	ScaleSetID  int64
	CreatedAt   string
}

type UsageByNodeRow 

type UsageByNodeRow struct {
	Node       string
	Vcpu       int64
	Memory     int64
	MacosSlots int64
}

type UsageOnNodeRow 

type UsageOnNodeRow struct {
	Vcpu   int64
	Memory int64
	Leases int64
}

type WithdrawNodeParams 

type WithdrawNodeParams struct {
	Name        string
	Epoch       int64
	Incarnation string
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.