config

type BackupConfig struct {
	// S3 is an S3-compatible bucket. Nil means billet uploads nothing and the
	// archive directory is the seam.
	S3 *BackupS3Config `yaml:"s3,omitempty"`
}

type BackupS3Config struct {
	// Bucket receives one object per archive entry.
	Bucket string `yaml:"bucket"`
	// Region is the SIGNING region. With no Endpoint it also selects the AWS
	// endpoint, so a typo there is a request signed for somewhere else.
	Region string `yaml:"region"`
	// Prefix isolates one deployment inside a shared bucket. Archives land under
	// <prefix>/<deployment-id>/<created-at>/, so IAM can be scoped by prefix and
	// two deployments cannot read each other's credentials.
	Prefix string `yaml:"prefix,omitempty"`
	// Endpoint overrides the AWS endpoint billet derives from Region, for an
	// S3-compatible store: Ceph RGW — which billet's own reference hardware
	// already runs — MinIO, or R2. Addressing is PATH style against it
	// (<endpoint>/<bucket>/<key>), because virtual-host style is what MinIO does
	// not do by default.
	Endpoint string `yaml:"endpoint,omitempty"`
	// KMSKeyID selects a customer-managed key for server-side encryption. Empty
	// uses SSE-S3 (AES256), which every S3-compatible store supports.
	//
	// AN ARCHIVE IS TWO PRIVATE KEYS AND A LEDGER, so what encrypts it at rest is
	// a real decision rather than a detail — and the one thing billet can enforce
	// from here is that it asks for encryption at all.
	KMSKeyID string `yaml:"kms_key_id,omitempty"`
}

type ByteSize int64

type CacheScope struct {
	Owner       string `yaml:"owner"`
	Repository  string `yaml:"repository"`
	WorkflowRef string `yaml:"workflow_ref"`
}

type CephConfig struct {
	// ConfPath is the ceph.conf naming this cluster's monitors. Empty means Ceph's
	// own search path, which finds /etc/ceph/ceph.conf.
	ConfPath string `yaml:"conf_path,omitempty"`

	// User is the RADOS identity billet authenticates as, WITHOUT the `client.`
	// prefix.
	//
	// DEFAULTS TO billet RATHER THAN admin, which is what the rbd command picks on
	// its own. An admin key can delete a pool, so defaulting to it would make a
	// compromised node able to destroy the cluster it caches in rather than the
	// images it was handed — and it would do so silently, because everything works.
	User string `yaml:"user,omitempty"`

	// KeyringPath holds that identity's secret. Empty means Ceph's own search path,
	// which finds /etc/ceph/ceph.<user>.keyring.
	KeyringPath string `yaml:"keyring_path,omitempty"`

	// ImagePool holds golden images and the per-job root clones taken from them.
	ImagePool string `yaml:"image_pool"`

	// CachePool holds cache volumes: sticky disks, build state, the layer cache.
	//
	// SEPARATE FROM ImagePool, and validation refuses one name for both. Not for
	// tuning — RBD's object size is a per-IMAGE property, so the reason ZFS wanted
	// two datasets does not survive the move. It is about blast radius: a cache is
	// disposable and a golden image is not, so "throw the cache away" has to be
	// something an operator can do to a whole pool without taking the images with
	// it, and a garbage collector walking one pool must not be able to reach the
	// other.
	CachePool string `yaml:"cache_pool"`
}

type CodeBuildConfig struct {
	// Region is which AWS region to build in. It also selects the API endpoint,
	// so an ordinary install configures no host of its own.
	Region string `yaml:"region"`
	// Endpoint overrides the API endpoint billet derives from Region — for a VPC
	// interface endpoint, a non-commercial partition, or a test.
	Endpoint string `yaml:"endpoint,omitempty"`

	// Project is the CodeBuild project billet starts builds in, and it must be
	// DEDICATED to this deployment and this node.
	//
	// THE PROJECT IS HALF THE OWNERSHIP BOUNDARY, because a CodeBuild build cannot
	// be tagged: `StartBuild` has no field that becomes one, so the per-instance
	// `sh.billet.owner` tag the ec2 backend filters `List` on does not exist here.
	// What replaces it is this project plus per-build markers read back through
	// BatchGetBuilds — and `List` feeds a loop that STOPS builds, so a project
	// shared with an ordinary CodeBuild workload is a way for billet to stop
	// somebody else's build.
	Project string `yaml:"project"`

	// FleetARN selects a reserved-capacity fleet. Empty means on-demand compute.
	//
	// ITS PRESENCE IS ALSO A STATEMENT ABOUT ISOLATION, which is why the provider
	// reads it rather than only passing it along: AWS documents a reserved
	// instance as remaining alive between builds and as sharing cached data with
	// other projects in the account, by design. macOS is reserved-only, so every
	// macOS build inherits that.
	//
	// A fleetOverride ALSO discards the project's VPC configuration — the fleet's
	// own network governs — so a network reviewed on the project proves nothing
	// about a build that named a fleet.
	FleetARN string `yaml:"fleet_arn,omitempty"`

	// EnvironmentType is the CodeBuild environment builds run in, and it is what
	// this node's guest OS is DERIVED from.
	EnvironmentType CodeBuildEnvironment `yaml:"environment_type"`

	// ComputeTypes are the compute types billet may buy, each DECLARING what it
	// holds, for the same reason node.ec2.instance_types are declared: billet
	// ships no table of them, and being out of date here means starting a build
	// smaller than the lease the allocator already escrowed.
	//
	// ORDERED, most preferred first, and placement charges the first entry that
	// fits rather than the smaller tier request.
	ComputeTypes []RemoteShape `yaml:"compute_types"`

	// AcceptExternalBuildCeiling acknowledges that every job on this node inherits
	// CodeBuild's ceilings, which billet cannot lift.
	//
	// NO DEFAULT, AND ITS ABSENCE IS THE REFUSAL — the same shape as
	// node.firecracker.untrusted_bridge and node.ec2.untrusted_security_group_ids.
	// It is not a feature flag: nothing changes when it is set. It exists so that
	// the sentence "this tier cannot run a job longer than 36 hours" is read by a
	// person before a tier advertises capacity, rather than discovered from a build
	// that died at hour 36 with GitHub reporting a failed job.
	AcceptExternalBuildCeiling bool `yaml:"accept_external_build_ceiling"`

	// BuildTimeoutMinutes is the ceiling billet asks CodeBuild for, 5 to 2160.
	//
	// THE OPERATOR'S NUMBER, NOT BILLET'S. billet adds no deadline of its own and
	// no drain or upgrade ever stops a build for taking too long; this is passed
	// through as timeoutInMinutesOverride. It defaults to the maximum, so a config
	// that says nothing gets the longest job CodeBuild permits.
	//
	// It also SIZES THE INVENTORY WINDOW, which is the one non-obvious consequence.
	// CodeBuild cannot list only active builds, so `List` walks recent history and
	// stops once every build it sees is older than this plus the queued ceiling —
	// at which point CodeBuild has necessarily ended them. Declaring a tighter
	// ceiling therefore makes this node's inventory cheaper; declaring the maximum
	// is supported and costs a longer walk.
	BuildTimeoutMinutes int `yaml:"build_timeout_minutes,omitempty"`

	// QueuedTimeoutMinutes is how long a build may wait for capacity, 5 to 480,
	// after which CodeBuild FAILS it. Defaults to the maximum.
	QueuedTimeoutMinutes int `yaml:"queued_timeout_minutes,omitempty"`

	// JITParameterPath is the SSM Parameter Store path prefix billet writes each
	// build's single-use runner registration under.
	//
	// REQUIRED, because it is an IAM boundary rather than a naming preference: the
	// node's policy grants ssm:PutParameter and ssm:DeleteParameter on exactly this
	// path, so a value billet guessed would either be unwritable or — worse — wider
	// than the grant an operator reviewed.
	//
	// THE REGISTRATION GOES HERE RATHER THAN INTO THE LAUNCH REQUEST because every
	// StartBuild field is rendered in the console and in CloudTrail. What travels in
	// the request is the parameter's NAME; the value is resolved into the build by
	// CodeBuild itself, under the BUILD's service role, which is a different
	// principal from this node's.
	JITParameterPath string `yaml:"jit_parameter_path"`

	// JITKMSKeyID selects the customer-managed key SecureString parameters are
	// encrypted with. Empty uses the account's aws/ssm key.
	JITKMSKeyID string `yaml:"jit_kms_key_id,omitempty"`

	// LogGroup pins where a build's logs go. Empty leaves the project's own
	// configuration alone.
	LogGroup string `yaml:"log_group,omitempty"`

	// PrivilegedMode grants the build the privilege Docker needs, and is only
	// meaningful for a CONTAINER environment — an EC2 or macOS environment is the
	// machine, so there is nothing to privilege and setting it is refused rather
	// than ignored.
	//
	// A GitHub Actions job routinely runs `docker build` and service containers, so
	// a container-environment tier that leaves this off produces jobs that fail on
	// their first Docker step. It is not defaulted on, because it is a real
	// privilege grant and billet does not hand one out on somebody's behalf.
	PrivilegedMode bool `yaml:"privileged_mode,omitempty"`

	// UntrustedVPCID, UntrustedSubnetIDs and UntrustedSecurityGroupIDs name the
	// isolated network a fork pull-request build runs in, and THEIR ABSENCE IS THE
	// REFUSAL — the same shape as node.ec2.untrusted_security_group_ids and
	// node.firecracker.untrusted_bridge. A build container isolates the kernel, not
	// the network, and a subnet somebody already had usually reaches more than they
	// are picturing.
	//
	// UNLIKE ec2, THE NETWORK LIVES ON THE PROJECT, because StartBuild has no VPC
	// override — CodeBuild sets a build's network from the project's vpcConfig (and a
	// fleetOverride discards even that). So these three fields are what the project
	// billet launches into was created with, and the provider VERIFIES the project
	// carries exactly this network before it starts an untrusted build. Declaring
	// them is only meaningful on an on-demand container node: reserved capacity is
	// shared between builds and macOS is reserved-only, so an untrusted build is
	// refused there whatever the network says, and declaring a network beside
	// fleet_arn or a reserved environment_type is refused as dead config.
	UntrustedVPCID            string   `yaml:"untrusted_vpc_id,omitempty"`
	UntrustedSubnetIDs        []string `yaml:"untrusted_subnets,omitempty"`
	UntrustedSecurityGroupIDs []string `yaml:"untrusted_security_group_ids,omitempty"`
}

type CodeBuildEnvironment string

type Config struct {
	// Server is required by `billet server`. A node reads it too when the two
	// share a file on one machine: it is where a certless node learns which
	// deployment it is joining.
	Server *ServerConfig `yaml:"server,omitempty"`
	// Node is required by `billet node`, ignored by a pure server.
	Node *NodeConfig `yaml:"node,omitempty"`
	// GitHub is the target named DefaultTargetName: the one organization or
	// repository a single-target deployment serves. `billet server` needs it or
	// at least one entry under Targets.
	GitHub *GitHubConfig `yaml:"github,omitempty"`
	// Targets are the further organizations and repositories this deployment
	// serves, each with its own App credential. See GitHubTargets.
	Targets []GitHubConfig `yaml:"targets,omitempty"`
	// Tiers is the runner catalog. Each tier becomes one GitHub scale set, and
	// its Label is what users put in `runs-on`.
	Tiers []Tier `yaml:"tiers,omitempty"`
	// Backup is where archives go when they leave this disk. Optional: absent
	// means `billet local backup --out <dir>` is the whole story and an
	// operator's own tooling carries the directory.
	Backup *BackupConfig `yaml:"backup,omitempty"`

	// Nodes describes per-host policy to the server. Separate from the Node section
	// on purpose: Node is how a host describes ITSELF, while Nodes is how the control
	// plane describes the FLEET — and host policy has to live server-side, because
	// the limits it expresses are enforced across tiers the host never sees.
	//
	// Every field defaults, so a deployment wanting standard behaviour omits it.
	Nodes []NodePolicy `yaml:"nodes,omitempty"`

	// Sites are the places this deployment has compute in. Optional: a single-machine
	// deployment never writes one.
	//
	// A SITE IS WHERE COMPUTE AND ITS STORAGE SHARE A FAST NETWORK — the answer to
	// "which storage", which every cache needs one of.
	//
	// DECLARED RATHER THAN INFERRED FROM WHAT NODES SAY, because the failure a free
	// string produces is silent: a node that means "home" and types "hom" would get
	// its own site, with its own empty cache, and every job placed there would run
	// cold while looking perfectly healthy.
	Sites []SiteConfig `yaml:"sites,omitempty"`

	// Images says where published guest images are fetched from. Optional: a
	// deployment that omits it pulls from where billet publishes.
	Images *ImagesConfig `yaml:"images,omitempty"`

	// Release says how this deployment learns about new billet releases.
	//
	// Optional, and its absence is the behaviour every existing install already
	// has: follow the signed stable channel, and update only when an operator
	// asks. See ReleaseConfig — nothing here starts a rollout by itself unless a
	// deployment says so in a sentence.
	Release *ReleaseConfig `yaml:"release,omitempty"`
	// contains filtered or unexported fields
}

type Contribution struct {
	// VCPU and Memory are what the allocator may place work against.
	VCPU   int
	Memory ByteSize

	// Warnings are things the operator should know but that are not errors —
	// billet is doing what it was told, and what it was told looks like a typo.
	Warnings []string
}

type ControllerMode string

type EBSS3Config struct {
	// Region is the signing region for both services and must match node.ec2.
	Region string `yaml:"region"`
	// AvailabilityZone is where cache volumes are created. EBS volumes and the
	// instances consuming them must be in the same zone.
	AvailabilityZone string `yaml:"availability_zone"`
	// Bucket holds the atomic pointer, lease and fencing state objects.
	Bucket string `yaml:"bucket"`
	// Prefix isolates one deployment and site inside a bucket.
	Prefix string `yaml:"prefix,omitempty"`
	// KMSKeyID optionally selects one customer-managed key for EBS volumes and
	// snapshots. Empty uses the account's EBS encryption default key.
	//
	// A PER-DEPLOYMENT key is what closes the cross-deployment READ boundary:
	// the IAM tag conditions cannot stop another deployment cloning a snapshot
	// and reading the cache (ec2:CreateVolume does not authorize the parent
	// snapshot; the value-scoped conditions give destructive integrity only).
	// With each deployment's snapshots encrypted under its own key — whose key
	// policy delegates to IAM and admits no foreign role — and its role's KMS
	// grants scoped to exactly that key, as `billet init iam` and the terraform
	// module both do, the foreign clone fails at the KMS grant instead
	// (measured with iam:SimulateCustomPolicy: every KMS action on another
	// deployment's key is implicitly denied). Sharing one key between
	// deployments silently reopens that boundary — as does a key whose own
	// policy or grants admit other roles, which no identity policy can see.
	// Leaving this EMPTY encrypts under the ACCOUNT's default EBS key — the
	// AWS-managed aws/ebs unless the account configured another — and aws/ebs
	// authorizes any principal in the account through EC2, so an opted-out
	// deployment's snapshots stay readable no matter what keys its neighbours
	// set. A key protects only snapshots created after it was set; evict or
	// re-snapshot older generations to bring them under it.
	KMSKeyID string `yaml:"kms_key_id,omitempty"`
}

type EC2Config struct {
	// Region is which AWS region to launch in. It also selects the API endpoint,
	// so an ordinary install configures no host of its own.
	Region string `yaml:"region"`
	// Endpoint overrides the API endpoint billet derives from Region — for a VPC
	// interface endpoint, a non-commercial partition, or a test.
	Endpoint string `yaml:"endpoint,omitempty"`

	// SubnetID is where instances are launched. Its route to GitHub is the
	// operator's to arrange: a private subnet needs a NAT gateway, a public one
	// needs AssignPublicIP.
	SubnetID string `yaml:"subnet_id"`
	// SecurityGroupIDs apply to trusted work.
	SecurityGroupIDs []string `yaml:"security_group_ids"`
	// UntrustedSecurityGroupIDs apply to fork pull-request work, and their
	// ABSENCE is what refuses it.
	//
	// A whole instance is a real isolation boundary, which is why this backend can
	// run code billet cannot vouch for at all — but that boundary is the KERNEL,
	// not the network. A fork's job in the same security group as everything else
	// reaches whatever that group reaches, which on a subnet somebody already had
	// is usually more than they are picturing. So untrusted work runs only once
	// its network has been described separately, rather than defaulting onto the
	// trusted group because nobody said otherwise.
	UntrustedSecurityGroupIDs []string `yaml:"untrusted_security_group_ids,omitempty"`
	// AssignPublicIP gives instances a public address, for a subnet with no NAT
	// gateway. A runner that cannot reach GitHub registers and then does nothing.
	AssignPublicIP bool `yaml:"assign_public_ip,omitempty"`

	// InstanceProfile is the IAM role TRUSTED instances receive. OPTIONAL, and
	// empty is the right answer unless a job genuinely needs AWS credentials: an
	// instance profile is readable from inside the guest, so it is a credential
	// handed to whatever the job runs.
	//
	// UNTRUSTED WORK NEVER GETS IT, whatever this says. A fork's pull request runs
	// its steps directly on the instance, so it could read the role's temporary
	// credentials out of the metadata service — past the isolation that lets this
	// backend run untrusted work at all.
	InstanceProfile string `yaml:"instance_profile,omitempty"`

	// InstanceTypes are the shapes billet may buy, each DECLARING what it holds,
	// because billet ships no table of EC2 instance types.
	//
	// A table would be out of date within a quarter — AWS adds types continuously
	// — and being out of date here means launching a machine that does not fit a
	// lease the allocator has already escrowed. Declaring them keeps the fleet's
	// cost surface in the operator's own file, which is where a spending decision
	// belongs anyway.
	InstanceTypes []EC2InstanceType `yaml:"instance_types"`

	// Spot buys interruptible capacity.
	//
	// DEFAULTS OFF, which reverses the assumption this backend was filed under.
	// It exists so one `runs-on` label survives the bare-metal host going away,
	// and GitHub does not requeue a job whose runner vanished mid-execution — so a
	// spot reclaim is a FAILED BUILD rather than a retry. Defaulting to spot would
	// make the failover path the unreliable one, which is the opposite of what a
	// failover is for. An operator who would rather have a cheap build that
	// sometimes dies says so here.
	Spot bool `yaml:"spot,omitempty"`
	// InterruptionQueueURL receives EventBridge's EC2 Spot interruption warnings.
	// Required with Spot: without it a reclaim is an unexplained failed build.
	InterruptionQueueURL string `yaml:"interruption_queue_url,omitempty"`
	// NodeName is filled from the effective node identity before the provider is
	// constructed. It is not a second operator-configured identity.
	NodeName string `yaml:"-"`
}

type EC2InstanceType struct {
	Type   string   `yaml:"type" json:"type"`
	VCPU   int      `yaml:"vcpu" json:"vcpu"`
	Memory ByteSize `yaml:"memory" json:"memory"`
	// PriceUSDPerHour is the operator-audited compute rate used to report the
	// maximum configured exposure. It is required because the answer has to be in
	// the config, not fetched from a mutable service when a job arrives. It is not
	// an admission gate and cannot make an already-accepted job wait because a
	// copied price went stale.
	PriceUSDPerHour USDPerHour `yaml:"price_usd_per_hour" json:"price_usd_per_hour"`
}

type FirecrackerConfig struct {
	// BinaryPath and JailerPath locate the firecracker and jailer binaries.
	//
	// BinaryPath IS NOT ONLY AN EXECUTABLE. The jailer names its chroot after this
	// file AFTER RESOLVING SYMLINKS, so it also decides the directory billet
	// enumerates to find out what is running here — see the firecracker provider's
	// jail type, where getting it wrong reads as an empty inventory.
	BinaryPath string `yaml:"binary_path,omitempty"`
	JailerPath string `yaml:"jailer_path,omitempty"`
	// KernelImage is the uncompressed guest kernel. It must be built with
	// everything Docker needs; validate with moby's contrib/check-config.sh
	// rather than a hand-maintained list.
	KernelImage string `yaml:"kernel_image"`

	// KernelDir is where `billet images pull` keeps the kernels it fetches.
	//
	// SEPARATE FROM KernelImage BECAUSE THEY ANSWER DIFFERENT QUESTIONS. KernelImage
	// is the fallback for a generation that records no kernel of its own — a
	// hand-built image, whose builder installs none. This is where a PAIRED kernel is
	// looked up, and a generation that names one boots that one instead: the two are
	// published together and a mismatch fails inside somebody's job rather than at
	// launch.
	//
	// Empty means the default, which is where a pull puts them.
	KernelDir string `yaml:"kernel_dir,omitempty"`
	// ChrootBase is where the jailer builds each microVM's chroot. It defaults to
	// the jailer's own default, and it must be on local storage with room for a
	// hard link to the guest kernel per running job.
	ChrootBase string `yaml:"chroot_base,omitempty"`
	// JailUIDMin and JailUIDCount are the range of uids microVMs run as, ONE PER
	// GUEST.
	//
	// NOT ONE ACCOUNT FOR ALL OF THEM. The jailer drops each VMM to a uid, and a
	// shared one means every VMM on the host is the same user to the kernel — so a
	// VMM that escapes its chroot can reach every other jail's files, signal every
	// other VMM, and open every other guest's root disk. The chroot is what
	// separates them while it holds; a uid of its own is what separates them when
	// it does not.
	//
	// THEY ARE NUMBERS, NOT ACCOUNTS, and deliberately: an account a person could
	// log in as is a bigger thing than an integer the kernel uses to keep two
	// processes apart, and creating one per job is a deployment step per job. The
	// default range is far above anything a distribution allocates.
	JailUIDMin   int `yaml:"jail_uid_min,omitempty"`
	JailUIDCount int `yaml:"jail_uid_count,omitempty"`
	// Bridge is the host bridge trusted guests attach to.
	Bridge string `yaml:"bridge"`
	// UntrustedBridge is the bridge fork pull-request guests attach to, and its
	// ABSENCE is what refuses them.
	//
	// A microVM is a real isolation boundary, which is why this backend can run
	// code billet cannot vouch for at all — but that boundary is the KERNEL, not
	// the network. A guest on the ordinary bridge reaches whatever that bridge
	// reaches, which on a machine that also holds the Ceph cluster and the
	// control-plane database is everything that matters. So untrusted work runs
	// only once its network has been described separately, rather than defaulting
	// onto the trusted bridge because nobody said otherwise. This is the same rule,
	// and the same reasoning, as node.ec2.untrusted_security_group_ids.
	UntrustedBridge string `yaml:"untrusted_bridge,omitempty"`
	// ImageVerifyPort is the host port a verification guest reports to. It is
	// fixed so host policy can admit exactly this service instead of opening an
	// arbitrary high port to every guest. Only one verification runs per host,
	// enforced by the verification lock.
	ImageVerifyPort int `yaml:"image_verify_port,omitempty"`
}

type GitHubConfig struct {
	// Name is the target's name under `targets:`, what a tier's `target` names.
	// Refused under `github:`, whose name is DefaultTargetName.
	Name string `yaml:"name,omitempty"`
	// Org is the organization this target is. Exactly one of Org and Repository.
	Org string `yaml:"org,omitempty"`
	// Repository is the repository this target is, as owner/name. Its runners
	// belong to the repository alone: a repository has no runner groups, so a
	// tier under it is untrusted only.
	Repository string `yaml:"repository,omitempty"`
	AppID      int64  `yaml:"app_id"`
	// ClientID is the App's OAuth client identifier, and it is OPTIONAL.
	//
	// GitHub's newer guidance prefers it over the numeric app id as the JWT
	// issuer, and the scale-set client accepts either — its GitHubAppAuth
	// documents ClientID as "the Client ID of the application (app id also
	// works)". So this must never become required: every config written before
	// the field existed keeps working.
	//
	// It is recorded because the manifest conversion already returns it, and
	// throwing away a value GitHub handed over means a second trip through the
	// browser to get it back. It is an identifier, not a secret — App.Forget
	// deliberately keeps it while blanking the client SECRET beside it.
	ClientID       string `yaml:"client_id,omitempty"`
	InstallationID int64  `yaml:"installation_id"`
	// PrivateKeyPath points at the App private key PEM. This file is the single
	// most sensitive thing in a billet deployment: it lives only on the control
	// plane, and nodes never hold long-lived GitHub credentials.
	PrivateKeyPath string `yaml:"private_key_path"`
}

type GitHubTarget struct {
	// Name is the target's name in config: DefaultTargetName for the `github:`
	// block, or the entry's own name under `targets:`.
	Name string
	// Org is the organization login, for an organization target.
	Org string
	// Repository is owner/name, for a repository target.
	Repository string
	AppID      int64
	ClientID   string
	// InstallationID is the App's installation on the organization or on the
	// repository's owner.
	InstallationID int64
	// PrivateKeyPath is where this target's App key lives, when the deployment
	// keeps keys in files.
	PrivateKeyPath string
}

type GuestOS string

type IdentityBackend string

type IdentityConfig struct {
	Backend IdentityBackend `yaml:"backend"`

	// AWSSSM configures the store when Backend selects it, and is REFUSED
	// otherwise rather than ignored — the same rule the `state:` block follows,
	// and for the same reason: silently ignoring a block produces a deployment
	// that believes it configured something.
	AWSSSM *IdentitySSMConfig `yaml:"aws_ssm,omitempty"`
}

type IdentitySSMConfig struct {
	// Region is the SIGNING region, and it also selects the endpoint: there is no
	// override, because an override is a way to send a deployment's private key to
	// a host of somebody's choosing.
	Region string `yaml:"region"`

	// Prefix isolates one deployment inside an account. Everything billet stores
	// lands under it, so IAM can be scoped by path and two deployments cannot read
	// each other's authority.
	Prefix string `yaml:"prefix"`

	// KMSKeyID names the key that encrypts the SecureStrings. Empty uses the
	// account's default SSM key, which is what a deployment that has not chosen
	// one gets — and which is a real choice rather than an omission, because that
	// key's policy is what decides who else in the account can read them.
	KMSKeyID string `yaml:"kms_key_id,omitempty"`
}

type ImagesConfig struct {
	// Source is the directory the manifest and its assets sit in.
	//
	// Empty means billet's own published images. The default lives in
	// internal/imagesource, next to the one constant naming this project, so a
	// move does not have to be remembered in two places.
	Source string `yaml:"source,omitempty"`

	// SigningIdentity is the certificate SAN pattern a valid signature must carry.
	//
	// REQUIRED FOR A SOURCE THAT IS NOT BILLET'S OWN, because billet's identity
	// cannot vouch for what somebody else's mirror serves — and the alternative to
	// requiring it is silently not verifying, which is the failure this exists to
	// prevent.
	SigningIdentity string `yaml:"signing_identity,omitempty"`

	// SigningIssuer is the OIDC issuer that certificate must come from.
	//
	// A SAN says who a certificate is FOR; the issuer says who vouched for it.
	// Without this, any authority able to mint a certificate carrying that name
	// satisfies the policy.
	SigningIssuer string `yaml:"signing_issuer,omitempty"`
}

type MaintenanceWindow struct {
	// Start and End are "HH:MM" in UTC.
	//
	// UTC RATHER THAN LOCAL, because a fleet spans machines whose local time is
	// not one thing, and a window that meant something different on each host is a
	// window nobody can reason about. It is also stable across a DST transition,
	// which a local window is not — and the hour that repeats or vanishes is
	// exactly the hour somebody chose because it is quiet.
	Start string `yaml:"start"`
	End   string `yaml:"end"`
}

type NodeCacheConfig struct {
	// Listen is one literal, non-loopback address guests can reach. Wildcards are
	// refused because they can expose the bearer-token API on another interface.
	Listen string `yaml:"listen"`
	// GuestEndpoint is the HTTP origin placed in guest metadata. It must name the
	// same address as Listen; the per-instance bearer token authorizes every call.
	GuestEndpoint string `yaml:"guest_endpoint"`
	// TLSCert and TLSKey terminate the HTTPS endpoint an EC2 guest reaches across
	// the VPC. Firecracker's isolated bridge uses HTTP and refuses these fields.
	TLSCert string `yaml:"tls_cert,omitempty"`
	TLSKey  string `yaml:"tls_key,omitempty"`
}

type NodeConfig struct {
	// Name identifies this node to the server and in tier pinning. Defaults to
	// the hostname.
	Name string `yaml:"name,omitempty"`
	// ServerAddr is the control plane to dial. Nodes always initiate the
	// connection, so a node needs no inbound reachability of its own.
	ServerAddr string `yaml:"server_addr"`
	// BootstrapAddr is where `billet node --enroll` asks to join, when the control
	// plane serves enrollment on an address of its own (server.bootstrap_listen).
	//
	// USED ONCE AND NEVER AGAIN. A running node never touches those routes, so
	// this decides nothing after the certificate is written. Unset falls back to
	// server_addr, which is right for a control plane that has no separate
	// enrollment address; against one that does, the node wire refuses a
	// connection with no certificate and the fallback cannot work.
	BootstrapAddr string `yaml:"bootstrap_addr,omitempty"`
	// Provider selects the compute backend for this host.
	Provider ProviderKind `yaml:"provider"`

	// Site is where this machine physically is, naming one of the control
	// plane's declared sites. Optional, and only meaningful once a deployment
	// has more than one place.
	Site string `yaml:"site,omitempty"`

	// MaxVCPU and MaxMemory are what this host CONTRIBUTES, which is not what it has.
	// Unset means "everything I can detect".
	//
	// DECLARED ON THE MACHINE rather than in the control plane's config, because the
	// person running this host knows what else it does — the same reason the provider
	// is declared here.
	//
	// Setting them ABOVE what the machine has is allowed and warned about;
	// overcommitting is a decision an operator is entitled to make.
	MaxVCPU   int      `yaml:"max_vcpu,omitempty"`
	MaxMemory ByteSize `yaml:"max_memory,omitempty"`

	// TLS is the certificate bundle this node presents, issued by the control
	// plane's `billet ca issue`.
	//
	// REQUIRED TO DIAL ANYTHING BUT LOOPBACK. The wire's whole authorisation model
	// is the name in this certificate, so a node without one can only talk to a
	// control plane in its own machine.
	TLS *NodeTLS `yaml:"tls,omitempty"`
	// LockDir is where this node places the host-wide deployment lock.
	//
	// THE LOCK BELONGS TO THE NODE ROLE, because the node is what manages containers
	// and a control plane manages none. It is exclusive per identity, so a server that
	// took it would keep a node on the same machine from ever starting.
	//
	// THE LOCK'S SCOPE HAS TO MATCH THE DAEMON'S, and billet cannot derive that: every
	// process reaching the same container runtime must meet at the same directory. The
	// per-user default is wrong for a system service sharing /var/run/docker.sock, and
	// for containers sharing a socket with private filesystems.
	//
	// It must NOT be world-writable, or any local user could hold the file and keep
	// billet from starting. A directory shared between two accounts must be SETGID;
	// 2770 works everywhere, while 2730 works only where a directory can be opened for
	// search without reading it (Linux O_PATH, darwin and FreeBSD O_SEARCH).
	LockDir string `yaml:"lock_dir,omitempty"`
	// AllowUnlockedDeployment starts this node even when the host-wide lock cannot be
	// placed.
	//
	// AN OPT-IN, BECAUSE AUTHORIZATION MUST NOT BE DERIVED FROM AN I/O FAILURE.
	// Downgrading automatically would let a symlink loop, a permissions change,
	// ENOLCK, descriptor exhaustion or a service manager with no HOME each silently
	// switch off the protection, with a log line as the only evidence.
	AllowUnlockedDeployment bool `yaml:"allow_unlocked_deployment,omitempty"`
	// StateDir holds node-local data: the generation pointer store (which is
	// authoritative for this node's volumes), image cache, and mTLS identity.
	StateDir string `yaml:"state_dir"`
	// Firecracker is required when Provider is ProviderFirecracker.
	Firecracker *FirecrackerConfig `yaml:"firecracker,omitempty"`
	// Tart configures the Apple Silicon backend. Optional: a node running only
	// trusted tiers needs none of it.
	Tart *TartConfig `yaml:"tart,omitempty"`
	// EC2 is required when Provider is ProviderEC2.
	EC2 *EC2Config `yaml:"ec2,omitempty"`
	// CodeBuild is required when Provider is ProviderCodeBuild, and refused for
	// every other backend — the same rule as node.ec2 and node.firecracker, for
	// the same reason: nothing else reads it, so on another provider it is a
	// project, a fleet and a parameter path that look configured and are consulted
	// by nothing.
	CodeBuild *CodeBuildConfig `yaml:"codebuild,omitempty"`
	// EBSS3 is the cache store local to an EC2 site's instances. EBS carries
	// block generations and S3 carries the fenced per-key state.
	EBSS3 *EBSS3Config `yaml:"ebs_s3,omitempty"`
	// Ceph is the site's storage, required when Provider is ProviderFirecracker
	// and refused for every other backend.
	//
	// REFUSED RATHER THAN IGNORED, because nothing reads it on a host that cannot
	// attach a block device: a container has nowhere to put one, and an ec2 node
	// orchestrates compute in a region that cannot reach this cluster at all. A
	// block of settings that looks configured and is inert is the failure billet
	// refuses elsewhere — it reads as a working cache right up to the first job
	// that expected one.
	Ceph *CephConfig `yaml:"ceph,omitempty"`
	// Cache exposes the per-job sticky-volume API on a Firecracker guest bridge or
	// over TLS to EC2 guests. Optional: a node without it offers no dynamic cache
	// volumes to workflows.
	//
	// OPTIONAL IS NOT FREE, and `billet check` says so. A node that names a store
	// and no endpoint has a cache nothing can reach: an EBSS3 node is REFUSED
	// there, because that block backs nothing else, and a Ceph node is reported,
	// because image_pool still boots every guest. The refusal is not here because
	// `billet decommission` and `billet init iam` both read a store block on a
	// config that has already lost its listener.
	Cache *NodeCacheConfig `yaml:"cache,omitempty"`
	// RegistryMirrors are three site-local Distribution pull-through caches. One
	// instance per upstream is required because proxy mode has one remote URL.
	RegistryMirrors *RegistryMirrors `yaml:"registry_mirrors,omitempty"`

	// MaxCustody bounds how long billet holds capacity for compute it cannot account
	// for — a container adopted from a crashed run, or one an ambiguous launch may
	// have left behind — before destroying it. A Go duration string.
	//
	// EMPTY MEANS NO BOUND, deliberately. Elapsed time is not evidence that a job
	// stopped making progress: billet imposes no job limit and self-hosted runners are
	// routinely configured past GitHub's six-hour default, so a bound picked by billet
	// would kill legitimate long jobs for no reason visible in the logs. Billet warns
	// hourly about held capacity regardless.
	MaxCustody string `yaml:"max_custody,omitempty"`
	// DrainTimeout bounds how long a stopping node waits for the compute it is still
	// holding before letting the teardown destroy it. A Go duration string.
	//
	// Separate from the control plane's key: the two are restarted for different
	// reasons and need not wait the same amount of time.
	DrainTimeout string `yaml:"drain_timeout,omitempty"`
}

type NodePolicy struct {
	// Name matches Tier.Node and NodeConfig.Name.
	Name string `yaml:"name"`

	// Provider is the compute backend this host runs, matching NodeConfig.Provider.
	// Optional, and used only to decide whether an unpinned tier could ever land
	// here: without it a macOS-only Mac would appear to conflict with every x64 Linux
	// tier in the deployment.
	Provider ProviderKind `yaml:"provider,omitempty"`

	// GuestOS is an allowlist of what may be scheduled here. Empty means
	// unconstrained, which is the default and preserves the behaviour of a
	// config that never mentions the node.
	//
	// Note the shape difference from Tier.GuestOS, which is a single value: a
	// tier boots exactly one guest OS, while a host may permit several.
	GuestOS []GuestOS `yaml:"guest_os,omitempty"`

	// MacOSVMLimit caps concurrent macOS guests on this host, counting warm ones. Nil
	// means DefaultMacOSVMLimit — an unconfigured Apple host is still bound by
	// Apple's licence, so the default is the licence, not "unlimited".
	//
	// Raising it above DefaultMacOSVMLimit is permitted because billet cannot know
	// what licence an operator has, but Apple's standard terms allow at most
	// DefaultMacOSVMLimit macOS guests per Apple-branded host — exceeding that is an
	// assertion about YOUR licence, not a tuning knob.
	MacOSVMLimit *int `yaml:"macos_vm_limit,omitempty"`
}

type NodeTLS struct {
	// CertPath is this node's certificate. Its common name is the node name the
	// control plane will act on.
	CertPath string `yaml:"cert"`
	// KeyPath is the matching private key. A secret.
	KeyPath string `yaml:"key"`
	// CAPath is the deployment authority this node verifies the control plane
	// against.
	CAPath string `yaml:"ca"`
}

type PlacementPolicy string

type PostgresStateConfig struct {
	// DSNEnv names the ENVIRONMENT VARIABLE holding the connection string, and
	// the indirection is the point: a DSN carries a password, and a secret
	// written into YAML ends up in a backup, a paste buffer, and eventually a
	// support thread. It is the same rule the GitHub App private key follows.
	DSNEnv string `yaml:"dsn_env"`
}

type ProviderKind string

type RegistryMirrors struct {
	DockerIO string `yaml:"docker.io" json:"docker.io"`
	GHCRIO   string `yaml:"ghcr.io" json:"ghcr.io"`
	QuayIO   string `yaml:"quay.io" json:"quay.io"`
}

type ReleaseConfig struct {
	// Channel is the signed pointer this deployment follows. Empty means stable.
	Channel string `yaml:"channel,omitempty"`

	// Version pins an exact release, and it NEVER MOVES.
	//
	// It wins over Channel, and setting both is an error rather than a precedence
	// puzzle: an operator who pinned a version and also named a channel has said
	// two things, and guessing which they meant is how a deployment that believes
	// itself pinned quietly follows a pointer.
	Version string `yaml:"version,omitempty"`

	// Automatic lets the control plane start a rollout by itself when the channel
	// advances, and lets the scheduled updaters on each host act on it.
	//
	// ON BY DEFAULT, AND THIS IS THE ONE ZERO VALUE IN THIS FILE THAT DOES NOT
	// REFUSE. Every other absent field here answers "hold"; this one answers "go",
	// because the failure an unattended deployment actually meets is the update
	// that never happens: a runner image GitHub stops queueing to, a fix that
	// shipped and never arrived. What makes that safe to default is everything
	// around it — a rollout drains every host for as long as its work takes, a
	// candidate is verified and rolled back on failure, and the ledger's release
	// watermark refuses to let an unattended update go backwards. A deployment
	// that must not move says so with `automatic: false`.
	//
	// A POINTER SO ABSENCE AND FALSE ARE DIFFERENT. A plain bool cannot tell "the
	// operator wrote false" from "the operator wrote nothing", and only the first
	// is an opt-out. Read it through AutomaticUpdates, never directly.
	Automatic *bool `yaml:"automatic,omitempty"`

	// MaintenanceWindow bounds when an automatic rollout may START.
	//
	// IT NEVER STOPS ONE. A rollout in progress waits for the work already running
	// on a host for as long as it takes, and a window that could interrupt that
	// would be a clock authorising a teardown — the thing this whole area exists
	// to refuse. What the window decides is whether a new one begins.
	MaintenanceWindow *MaintenanceWindow `yaml:"maintenance_window,omitempty"`

	// SigningIdentity and SigningIssuer override what a release manifest must be
	// signed by, for a deployment mirroring releases internally.
	SigningIdentity string `yaml:"signing_identity,omitempty"`
	SigningIssuer   string `yaml:"signing_issuer,omitempty"`
}

type RemoteCostNode struct {
	MaxVCPU     int
	MaxMemory   ByteSize
	Shapes      []RemoteShape
	Outstanding USDPerHour
}

type RemoteShape = EC2InstanceType

type ServerConfig struct {
	// Listen is the address nodes dial. Nodes always connect outbound, so on a
	// single-box deployment this stays on loopback and billet needs no open port
	// reachable from anywhere else.
	Listen string `yaml:"listen"`
	// BootstrapListen is a SECOND address serving only the two routes a machine
	// that has never enrolled needs: reading this deployment's authority, and
	// asking to join.
	//
	// ITS ABSENCE IS A REFUSAL, not a default. Without it this control plane does
	// not enroll over the network at all, and admission happens out of band —
	// `billet ca issue <node>` on the server, the bundle copied to the host.
	//
	// It exists because those two routes cannot require a certificate, and a
	// listener that admits callers who need not prove anything cannot share a
	// connection budget with the fleet: an anonymous caller that completes a
	// handshake and idles holds a slot, and once the budget is full a healthy
	// node's connection is never accepted. So `listen` demands a certificate in
	// the handshake and serves nothing else, and this address carries the rest.
	//
	// Both listeners present the same certificate, so whatever name a node dials
	// this one by has to be covered by node_tls_hosts (or by a concrete host in
	// one of the two listen addresses, which billet derives them from).
	//
	// Refused against a loopback `listen`: there are no certificates on a loopback
	// wire, so there is nothing to enroll into.
	BootstrapListen string `yaml:"bootstrap_listen,omitempty"`
	// StateDir is the SHORTHAND, and it is what most deployments write: one
	// directory holding the SQLite ledger, the process lock, the maintenance
	// fence and the mTLS CA. It MUST be on local storage, because SQLite's WAL
	// cannot work on a network filesystem and the state package fails closed if
	// it detects otherwise.
	//
	// It means exactly `identity_dir: <dir>` plus `state: {backend: sqlite}`, and
	// it stays supported. Writing it TOGETHER with `state:` is refused rather
	// than merged: two spellings of one value is a mistake internal/config has
	// already made three times, and it is silent every time.
	StateDir string `yaml:"state_dir,omitempty"`

	// IdentityDir holds what is NOT rows: the deployment identity, the node-wire
	// CA and its rotation state, the process lock, and the maintenance fence.
	//
	// SEPARATE FROM THE LEDGER BECAUSE THE TWO ARE NOT INTERCHANGEABLE. A ledger
	// can move into a database billet does not operate; a private key cannot
	// follow it there, and local process coordination has nothing to do with SQL
	// rows. The pairing is a refusal for the same reason: a subset of a
	// deployment is one that starts, looks healthy, and is not.
	//
	// Required when `state:` is written out; `state_dir` supplies it otherwise.
	IdentityDir string `yaml:"identity_dir,omitempty"`

	// State selects the backend the ledger lives in. Absent means the shorthand
	// above.
	State *StateConfig `yaml:"state,omitempty"`

	// Controllers says whether this deployment runs one control plane or an
	// active/passive pair. Absent means `single`, which is what every deployment
	// before this key had.
	//
	// REFUSED ON A SQLITE LEDGER. There is nothing to elect over: the ledger is a
	// file on local storage that a second machine cannot open at all, so a standby
	// would be a second process on one host waiting for a lock its own service
	// manager already restarts it to take.
	Controllers ControllerMode `yaml:"controllers,omitempty"`

	// Identity says where the deployment's identity material lives. Absent means
	// `file`, which is what every deployment before this key had.
	Identity *IdentityConfig `yaml:"identity,omitempty"`
	// MaxVCPU and MaxMemory bound what the allocator will ever hand out across every
	// tier combined. Required and positive: capacity is escrowed before each listener
	// advertises, so an absent ceiling lets concurrent listeners collectively
	// overcommit the machine.
	MaxVCPU   int      `yaml:"max_vcpu"`
	MaxMemory ByteSize `yaml:"max_memory"`

	// Placement decides which of several suitable machines a job is sent to.
	// Empty means pack. Only meaningful once a deployment has more than one.
	Placement PlacementPolicy `yaml:"placement,omitempty"`
	// NodeTLSHosts are the names and addresses nodes will dial this control plane by.
	// They become the subject names of the certificate it serves.
	//
	// REQUIRED WHEN listen IS A WILDCARD, which says which interfaces to accept on and
	// nothing about what a node types: a certificate minted for "0.0.0.0" matches
	// nothing, and the failure arrives as a handshake error on the node. A concrete
	// listen address supplies itself.
	NodeTLSHosts []string `yaml:"node_tls_hosts,omitempty"`
	// DrainTimeout bounds how long a stopping control plane waits for the jobs it is
	// already running before it destroys them. A Go duration string: "6h", "90m".
	//
	// A service manager's stop timeout must exceed this plus the teardown, or its own
	// expiry arrives first as a SIGKILL — skipping the teardown and stranding exactly
	// the compute the drain was protecting.
	DrainTimeout string `yaml:"drain_timeout,omitempty"`
}

type SiteConfig struct {
	// Name is what a node and a tier refer to this site by.
	Name string `yaml:"name"`
	// Store is the storage local to this site. Ceph serves host-backed compute;
	// EBS snapshots and S3 serve AWS without exposing the home cluster over a WAN.
	Store SiteStoreKind `yaml:"store"`
}

type SiteStoreKind string

type StateBackend string

type StateConfig struct {
	Backend StateBackend `yaml:"backend"`

	// Postgres configures the ledger when Backend selects it, and is REFUSED
	// otherwise rather than ignored — the same way a `node.ceph` block on a
	// non-firecracker backend is, and for the same reason: silently ignoring it
	// produces a deployment that believes it configured something.
	//
	// THERE IS NO `sqlite:` BLOCK, and its absence is deliberate. The only thing
	// it could carry is a path, the SQLite ledger is always billet.db inside
	// identity_dir, and every part of billet that reads a ledger FILE — the
	// restore planner, the writer barrier, the archive — derives it that way. A
	// key that billet accepted and then did not use would be a deployment
	// started against a freshly created empty ledger, which is not a failure
	// anybody would see until the fleet came back empty.
	Postgres *PostgresStateConfig `yaml:"postgres,omitempty"`
}

type TargetScope string

type TartConfig struct {
	// UntrustedIsolation names the mechanism that confines a fork pull
	// request's guest, and its ABSENCE is what refuses one.
	//
	// The same rule, and the same reasoning, as
	// node.firecracker.untrusted_bridge: a tart VM is a real kernel boundary,
	// and the NETWORK is not one. Tart's default is shared NAT, where a guest
	// reaches the host and can ARP-spoof the vmnet bridge to read another
	// guest's traffic — so untrusted work runs only once its confinement has
	// been described, rather than landing on the default because nobody said
	// otherwise.
	//
	// STATED BY THE OPERATOR RATHER THAN DETECTED, because billet cannot prove
	// this from the host. What it can see of softnet is two metadata bits — a
	// setuid bit and an owner of root — which say the helper could start, not
	// what its policy then permits. Naming it here is the operator asserting
	// the mechanism is the one they want, exactly as naming a bridge is.
	UntrustedIsolation TartIsolation `yaml:"untrusted_isolation,omitempty"`

	// UntrustedDNS are the resolvers an isolated guest is given, and billet
	// gives them because billet is what took the working one away.
	//
	// MEASURED: under softnet a guest's DHCP-assigned resolver is the vmnet
	// gateway, which sits in the private address space softnet blocks. Egress
	// to public addresses keeps working and TCP/443 keeps working, so nothing
	// looks wrong — every job simply fails to resolve github.com. Public
	// resolvers are reachable under exactly the policy that broke the gateway
	// one.
	UntrustedDNS []string `yaml:"untrusted_dns,omitempty"`
}

type TartIsolation string

type Tier struct {
	Label string `yaml:"label"`

	// Target names the GitHub target this tier's scale set belongs to. Defaults
	// to the deployment's only target and is required when there are several,
	// because a scale set exists on exactly one organization or repository and
	// the credential that creates it is that target's.
	Target string `yaml:"target,omitempty"`

	// Trust is the authority every member of this runner pool receives before
	// GitHub assigns it a job. It is explicit because scale-set JIT runners are
	// pool members, not registrations bound to the assignment that caused Billet
	// to create them.
	Trust WorkloadTrust `yaml:"trust"`
	// Workflows is the exact GitHub runner-group workflow allowlist a trusted
	// pool expects. An untrusted pool needs no routing claim for its safety.
	Workflows []string `yaml:"workflows,omitempty"`
	// CacheScope is the one immutable Actions cache identity placed in a guest at
	// launch. It is required for interception because JobStarted arrives after
	// the guest already has its launch-time credentials.
	CacheScope *CacheScope `yaml:"cache_scope,omitempty"`

	// Provider is the single backend this tier runs on. Kept because it is what
	// almost every deployment wants and what every existing config says; it is
	// normalized into Providers, which is what the rest of billet reads.
	Provider ProviderKind `yaml:"provider,omitempty"`

	// Providers is an ORDERED preference list, most preferred first.
	//
	// The reason one `runs-on` label can span a machine at home and a cloud: a tier
	// listing `[firecracker, ec2]` may be placed on either, so losing the bare-metal
	// host does not take the label down with it.
	//
	// THE ORDER DECIDES, AT ESCROW — the allocator walks it most-preferred-first over
	// the hosts that can serve the tier and have room, so a job reaches the cloud only
	// when home is full, rather than when a cloud node polls first. server.placement
	// decides only between hosts this order cannot separate.
	//
	// Setting both this and Provider is an error rather than a merge: guessing which
	// spelling an operator meant, when the answer decides where untrusted code runs,
	// is not a kindness. Every backend in allProviders is built and may appear here —
	// stated without a count, because both sides of this merge had independently
	// corrected the previous wording and one of them said "four" for a list of five.
	Providers []ProviderKind `yaml:"providers,omitempty"`
	// GuestOS defaults to linux. Set it explicitly for macOS and Windows tiers —
	// licensing and capability checks key off this field, not off the label.
	GuestOS GuestOS `yaml:"guest_os,omitempty"`
	// Node optionally pins this tier to a named node. Required when only one
	// node can serve it — macOS tiers, for example.
	Node string `yaml:"node,omitempty"`

	// Site optionally confines this tier to one place, the way Node confines it to one
	// machine — but a site holds several machines, so it constrains without giving up
	// the fallback that having several of them buys.
	//
	// The reason to reach for it is data rather than hardware: a job that must not
	// leave a location, or one whose cache exists in only one place.
	Site string `yaml:"site,omitempty"`
	// RunnerGroup is the GitHub runner group this tier's scale set belongs to. Empty
	// means GitHub's "default" group.
	//
	// Access control rather than scheduling: a runner group is how an organization
	// decides which repositories may use these runners, and putting every tier in the
	// default group hands them to every repository in the org.
	RunnerGroup string `yaml:"runner_group,omitempty"`

	// Command starts the runner inside this tier's image. Empty uses the provider's
	// packaged runner service.
	//
	// Expressible because a container image's default command is a shell: a backend
	// that launches one gets a container that exits immediately while every signal
	// reports success, so the command cannot be left to the image.
	Command []string `yaml:"command,omitempty"`

	// Launch holds backend-specific boot details for a tier that accepts more than
	// one provider. A Firecracker generation and an EC2 AMI are both images, but
	// neither backend can interpret the other's name; commands can differ for the
	// same reason. Single-provider tiers keep the simpler image and command fields.
	Launch map[ProviderKind]TierLaunch `yaml:"launch,omitempty"`

	VCPU   int      `yaml:"vcpu"`
	Memory ByteSize `yaml:"memory"`

	// Sizes expands this entry into one tier per vCPU count, most operators'
	// single largest source of hand-written YAML.
	//
	// A real deployment wants several sizes of the same thing and each one is
	// fifteen lines that differ in two numbers and a label — so `sizes: [2, 4, 8]`
	// against everything else this entry says writes the other thirteen. The
	// expansion happens in Parse, before defaults and before validation, so
	// nothing downstream ever sees an unexpanded tier.
	//
	// IT IS A TEMPLATE, NOT A RANGE. Each size becomes a real, separate tier with
	// its own label, its own scale set and its own escrow — because that is what
	// it already was when it was written out by hand, and a shorthand that meant
	// anything else would be a new scheduling concept wearing a convenience's
	// clothes.
	//
	// Refused beside an explicit vcpu or memory: two spellings of one value is a
	// mistake internal/config has already made three times, and it is silent
	// every time.
	Sizes []int `yaml:"sizes,omitempty"`
	// MemoryPerVCPU is the proportion `sizes` shapes each tier to. It is
	// meaningless without Sizes and refused there.
	//
	// The default is DefaultMemoryPerVCPU, which is the same 4GiB every generated
	// catalogue already uses — so a config that writes `sizes` and nothing else
	// gets exactly the ladder `billet init` would have written for it.
	MemoryPerVCPU ByteSize `yaml:"memory_per_vcpu,omitempty"`
	Disk          ByteSize `yaml:"disk,omitempty"`
	// SHM sizes /dev/shm. Chromium and Postgres both misbehave on the default,
	// so this is a tier knob rather than an image constant.
	SHM ByteSize `yaml:"shm,omitempty"`
	// BuildKitCacheMountLimit bounds each persistent RUN --mount=type=cache
	// record. BuildKit's ordinary GC bounds the whole worker; this catches one
	// active mount that never becomes old enough for that policy to trim.
	BuildKitCacheMountLimit ByteSize `yaml:"buildkit_cache_mount_limit,omitempty"`

	Image string `yaml:"image,omitempty"`

	// WarmPool is reserved for pre-booted idle VMs. Validation refuses a non-zero
	// value until a provider implements it, because accepting an inert cost setting
	// would tell an operator cold-start capacity exists when it does not.
	WarmPool int `yaml:"warm_pool,omitempty"`

	// Intercept routes the Actions results origin through the node-local cache proxy.
	// False is the safe default because the same origin carries artifact metadata.
	Intercept bool `yaml:"intercept,omitempty"`

	// MaxConcurrent caps simultaneous instances of this tier, counting warm ones.
	// Zero means "no per-tier cap" and is only legal for non-macOS tiers.
	MaxConcurrent int `yaml:"max_concurrent,omitempty"`

	// Reserved is how many simultaneous instances of this tier are always available to
	// it, no matter how busy every other tier is.
	//
	// A FLOOR, where MaxConcurrent is a ceiling. Billet shares one budget across every
	// tier and headroom is whatever is left, so a tier with steady demand can hold all
	// of it while the others advertise zero and their jobs queue at GitHub. A
	// reservation is deducted from what OTHER tiers may take, only while it is unmet.
	//
	// THE COST IS CAPACITY OTHER TIERS CANNOT USE. An idle listener keeps one discovery
	// slot rather than claiming its whole floor, but the allocator still holds every
	// unmet reserved slot away from competing tiers. Reserve for tiers that need a hard
	// guarantee under contention. Zero is the default.
	Reserved int `yaml:"reserved,omitempty"`
}

type TierLaunch struct {
	Image   string   `yaml:"image"`
	Command []string `yaml:"command,omitempty"`
}

type USDPerHour int64

type WorkloadTrust string