replay

type Arrival struct {
	// Seq numbers the arrivals from 1 in arrival order. It is the request id the
	// scripted GitHub offers the job under, so the ledger's request_id joins a
	// recorded row back to this line without any table of the harness's own.
	Seq int64 `json:"seq"`
	// At is when the job was queued.
	At time.Time `json:"at"`
	// Tier is the runs-on label, which is the scale set that will carry it.
	Tier string `json:"tier"`
	// Owner, Repository and WorkflowRef are what GitHub puts on the message.
	Owner       string `json:"owner"`
	Repository  string `json:"repository"`
	WorkflowRef string `json:"workflow"`
	RunID       int64  `json:"run_id"`
	// Duration is how long the job ran once a runner had it.
	Duration Duration `json:"duration"`
	// Result is GitHub's conclusion; empty means ResultSucceeded.
	Result string `json:"result"`
}

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

type Duration time.Duration

type Fleet struct {
	Hosts []Host
	Tiers []TierShape
	// MaxVCPU and MaxMemory are the deployment ceiling, server.max_vcpu and
	// server.max_memory.
	MaxVCPU   int
	MaxMemory config.ByteSize
	// Placement is server.placement; empty means pack, as it does in a config.
	Placement config.PlacementPolicy
	// Boot is the modelled time between a mint and the runner taking a job. Zero
	// means DefaultBoot.
	Boot time.Duration
}

type Host struct {
	Name   string
	VCPU   int
	Memory config.ByteSize
	// Site is where the machine is, or empty for a fleet in one place.
	Site string
	// RatePerHour is what running this machine costs per hour, in dollars. The
	// harness's input, like the trace: an owned box's rate is not a fact billet
	// records. Zero means unpriced.
	RatePerHour float64
}

type Options struct {
	// Log receives billet's own diagnostics. Nil writes them to the test log.
	Log *slog.Logger
	// SettleWithin bounds, in wall time, how long billet may take to settle
	// after one event before the replay is declared stuck. Zero means a minute.
	SettleWithin time.Duration
}

type Params struct {
	// Jobs is how many arrivals to generate.
	Jobs int
	// Tiers are the labels jobs are spread over, first the most common.
	Tiers []string
	// Repositories are the repositories jobs belong to, first the most common.
	Repositories []string
	// Start is the trace's first instant. A Monday at nine, by default.
	Start time.Time
}

type Percentiles struct {
	Count         int
	P50, P95, Max time.Duration
}

type Record struct {
	Seq         int64  `json:"seq"`
	LeaseID     string `json:"lease_id"`
	Tier        string `json:"tier"`
	Owner       string `json:"owner"`
	Repository  string `json:"repository"`
	WorkflowRef string `json:"workflow"`
	Node        string `json:"node"`

	// Provider, InstanceType, VCPU, Memory and Site are what the lease was
	// charged for: the backend it ran on, the shape placement bought (empty for a
	// host-backed backend), the charged vCPU and memory, and the host's site.
	Provider     string          `json:"provider"`
	InstanceType string          `json:"instance_type,omitempty"`
	VCPU         int             `json:"vcpu"`
	Memory       config.ByteSize `json:"memory"`
	Site         string          `json:"site,omitempty"`
	// PriceMicrosPerHour is the rate the shape was charged at when the lease was
	// escrowed, in millionths of a dollar. Zero means no price was recorded,
	// which is what a host-backed lease has.
	PriceMicrosPerHour int64 `json:"price_micros_per_hour"`
	// Cost is the run's cost in dollars and CostSource says what rate produced
	// it: "ledger" when the recorded price was positive, "fleet-rate" when the
	// fleet's per-host rate was applied to the charged vCPU-hours, and "" when
	// neither was available, in which case Cost is zero and means unknown.
	Cost       float64 `json:"cost"`
	CostSource string  `json:"cost_source,omitempty"`
	// ImageCache, CacheGeneration and ActionsCache are what the node observed the
	// cache do, in the ledger's closed vocabularies; empty means nothing was
	// observed, which is what a simulated guest reports.
	ImageCache      string `json:"image_cache,omitempty"`
	CacheGeneration string `json:"cache_generation,omitempty"`
	ActionsCache    string `json:"actions_cache,omitempty"`

	Arrival time.Time `json:"arrival"`
	// ChargedFrom is when the lease was escrowed, which is when its shape began
	// to count against the host and the deployment: before the job was assigned,
	// while the lease was still the tier's discovery slot.
	ChargedFrom time.Time `json:"charged_from"`
	AssignedAt  time.Time `json:"assigned_at"`
	StartedAt   time.Time `json:"started_at"`
	FinishedAt  time.Time `json:"finished_at"`

	// QueueWait is from the trace's arrival to the ledger's recorded start, and
	// RunDuration from that start to the lease's archive.
	QueueWait   Duration `json:"queue_wait"`
	RunDuration Duration `json:"run_duration"`

	Conclusion string `json:"conclusion"`
	Result     string `json:"result"`
	Disruption string `json:"disruption,omitempty"`

	// Locality is DERIVED FROM PLACEMENT, not observed: an earlier job of the
	// same repository was placed on the same node. Beside the observed cache
	// columns because a simulated guest observes nothing, and locality is the
	// question a placement policy can be asked without one.
	Locality bool `json:"locality"`
}

type Report struct {
	Fleet Fleet
	// Records are the jobs the ledger knows about, in sequence order.
	Records []Record
	// Missing are trace jobs with no ledger row: gaps in the recording, reported
	// as gaps rather than filled in.
	Missing []int64
	// Unstarted are recorded jobs the ledger never saw start.
	Unstarted []int64
	// Unfinished are recorded leases the ledger never archived: their charge has
	// no end, so the sweep charges it and never releases it, and a capacity
	// verdict over such a ledger is provisional rather than final.
	Unfinished []int64
	// EscrowRows counts history rows for leases that were never assigned a job:
	// the discovery slots released at shutdown. Reported so a reader can tell
	// them from a missing job.
	EscrowRows int

	// Violations are the overcommits the ledger's charges prove: a host or the
	// deployment charged more than it has, at some instant.
	Violations []string
	// contains filtered or unexported fields
}

type TierShape struct {
	Label  string
	VCPU   int
	Memory config.ByteSize
}

type Trace struct {
	Arrivals []Arrival
}