orchestrator

type AgentSpec struct {
	Files        map[string][]byte // arbitrary files to upload into the guest (path -> bytes)
	DownloadURL  string            // fetch the agent binary (e.g. GitHub releases)
	Command      string            // how to launch the daemon
	AuthToken    string            // pass-through bearer token
	Gateway      string            // pass-through gateway websocket URL
	GatewayToken string            // pass-through gateway token
	DrainCommand string            // command run inside the guest for graceful shutdown (” => skip)
	Expose       []ExposeSpec      // guest ports to publish as reachable endpoints, if any

	// TunnelConfigPath is the guest path of an uploaded tunnel config (see
	// ingress.go). when set, the host agent runs the tunnel sidecar against it
	// as a unit of its own, so it outlives restarts of the agent. empty means
	// no sidecar, which is every environment when no proxy is configured.
	TunnelConfigPath string
}

type ArtifactDeleter interface {
	DeleteArtifact(ctx context.Context, snapshotID string) error
}

type ArtifactEndpoint struct {
	HostID string
	URL    string
	Token  string
}

type ArtifactHolder struct {
	HostID     string
	SnapshotID string
}

type ArtifactMove struct {
	Digest     string
	SnapshotID string
	From       ArtifactEndpoint
	To         ArtifactEndpoint

	// Files is the memory half of a live snapshot, file name to hex sha256, to
	// be fetched and verified alongside the rootfs. Digest stays the rootfs
	// digest and stays the artifact's identity; these ride under the same
	// grant. empty for a disk artifact.
	Files map[string]string

	// Lazy leaves mem on the source; the target pages it in after resume.
	Lazy bool

	// SourceSnapshotID is the snapshot on From the files are read out of. a
	// live snapshot's identity is its rootfs digest, and checkpoints of an
	// idle guest can share one, so the peer is told exactly which to serve.
	SourceSnapshotID string

	// Base, when set, makes this a delta move: Files are a diff snapshot's
	// delta files and the receiving host merges them onto Base, a complete
	// live snapshot it already holds. DropBase removes Base after the merge.
	Base     string
	DropBase bool
}

type ArtifactMoved struct {
	SnapshotID string
	SizeBytes  int64
	// Kind is what the receiving host committed. an agent that predates moving
	// live snapshots ignores Files and commits the rootfs alone, and says so
	// here by reporting nothing, which reads as disk.
	Kind SnapshotKind
}

type ArtifactMover interface {
	MoveArtifact(ctx context.Context, move ArtifactMove) (ArtifactMoved, error)
}

type AttachSpec struct {
	// Cmd is the argv to run. Empty means the guest's login shell.
	Cmd []string

	// TTY requests a pty for the process. Rows and Cols seed its initial
	// window size; further resizes arrive as frames on the stream itself.
	TTY  bool
	Rows uint16
	Cols uint16
}

type Attacher interface {
	Attach(ctx context.Context, spec AttachSpec) (io.ReadWriteCloser, error)
}

type BootOptions struct {
	StartupScript string
	GatewayURL    string
	GatewayToken  string
	Expose        []ExposeSpec

	// Healthcheck is the environment-level readiness probe, or nil when the
	// caller declared none. It is shipped into the guest as a file (see
	// FusedAgentSpec) and evaluated there; the orchestrator only reads the
	// verdict back. See health.go.
	Healthcheck *HealthcheckSpec

	// Desktop is the graphical session's geometry, or nil when the caller
	// declared none. It is shipped into the guest as a file (see
	// FusedAgentSpec) and applied there; the orchestrator never renders
	// anything. See desktop.go.
	Desktop *DesktopSpec

	// TunnelConfig is the sidecar's config for an environment published
	// through fuse-proxy, or nil. set by the fleet, never by a caller.
	TunnelConfig []byte

	// Files are caller-supplied guest files (a Fusefile's `copy` block),
	// keyed by absolute guest path. The agent profile merges them into
	// AgentSpec.Files ahead of its own entries, so they are uploaded on the
	// same pass as the manifest and credentials and therefore land before
	// StartupScript runs, and so a caller can never displace a profile file.
	// The API refuses a path under ReservedGuestDir before it reaches here.
	Files map[string][]byte

	// StartupScriptTimeout bounds StartupScript. Zero means
	// DefaultStartupScriptTimeout. The script runs synchronously inside the
	// create request, so this must stay comfortably under the orchestrator's
	// HTTP write timeout (60s by default) for the caller to receive a real
	// error instead of a truncated response.
	StartupScriptTimeout time.Duration

	// HostID is the host the vm was scheduled onto. it is filled in by the
	// fleet, not the caller, so egress provisioning can name the host.
	HostID string

	// EgressRegistry holds the fleet's egress backends, filled in by the
	// fleet. nil means no proxy egress can be provisioned; a proxy spec then
	// fails the boot rather than silently booting direct.
	EgressRegistry *egress.Registry
}

type BootResult struct {
	Env                Environment
	BootTime           time.Duration
	FromCache          bool       // true if restored from checkpoint
	AuthTokenEncrypted []byte     // AES-GCM encrypted per-VM auth token for persistence
	DrainCommand       string     // graceful-shutdown command for the configured agent (” => skip)
	Endpoints          []Endpoint // published endpoints, if the provider reported any
	// Egress is the resolved outbound policy: direct, or the proxy endpoint
	// that was provisioned for this boot.
	Egress egress.Status
}

type CapacityProber interface {
	Capacity(ctx context.Context) (HostCapacity, error)
}

type Checkpoint struct {
	ID        string
	Comment   string
	SizeBytes int64
	CreatedAt time.Time

	// Digest is the hex sha256 the host agent computed over the artifact as it
	// wrote it, or "" from an agent (or a backend) that does not hash. It
	// verifies a later transfer of these exact bytes and nothing else: two
	// builds of the same recipe produce different rootfs bytes, so it is never
	// an identity two artifacts can share and never a cache key.
	Digest string

	// Kind is what this checkpoint actually contains: rootfs only, or rootfs
	// plus guest memory. Backends that only ever take disk snapshots leave it
	// empty, which callers read as SnapshotKindDisk; empty is not an error,
	// it is an older agent (or a backend with nothing to distinguish).
	Kind SnapshotKind

	// Files is the memory half of a live checkpoint, file name to hex sha256.
	// it plays the part Digest plays for the rootfs: what a receiving host
	// verifies each file against when the snapshot moves. empty for a disk
	// checkpoint, and for a live one from an agent that predates moving them.
	// for a diff checkpoint the names are the delta files instead.
	Files map[string]string

	// Parent is the checkpoint a diff was taken against, "" for a complete
	// one. a diff is not restorable on its own; it only merges onto a copy of
	// its parent on another host.
	Parent string
}

type DeadLetterKind string

type DeadLetterRecord struct {
	ID          int64
	Kind        DeadLetterKind
	EntityID    string
	TaskID      string
	Reason      string
	RetryCount  int
	Payload     json.RawMessage
	FirstSeenAt time.Time
	LastSeenAt  time.Time
}

type DeltaSnapshotCapable interface {
	CheckpointDiff(ctx context.Context, comment, parent string, keepPaused bool) (Checkpoint, error)
	Resume(ctx context.Context) error
}

type DesktopSpec struct {
	Width  int    `json:"width"`
	Height int    `json:"height"`
	WM     string `json:"wm,omitempty"`
}

type EgressAddresser interface {
	EgressAddresses() (listenIP, guestIP string)
}

type EgressEndpointKey struct {
	Provider string
	State    egress.HealthState
}

type EgressMetrics interface {
	EgressProvisionFailed(provider string)
	EgressTeardownFailed(provider string)
}

type Endpoint struct {
	As   string // caller-chosen label, e.g. "http"
	URL  string // reachable address, e.g. "http://203.0.113.5:41231"
	Port int    // the guest-side port this endpoint publishes
	// Protocol is the transport the host agent actually published on, not
	// what was requested. Empty from an agent that predates the field, which
	// a reader takes as tcp.
	Protocol Protocol
}

type EndpointReporter interface {
	Endpoints() []Endpoint
}

type Environment interface {
	// Name returns the sandbox identifier.
	Name() string

	// URL returns the sandbox's reachable address for the guest agent.
	URL() string

	// Exec runs argv inside the sandbox and reports the result. A non-zero
	// guest exit code is carried in ExecResult.ExitCode, not returned as an
	// error; err is reserved for transport and provider failures, so callers
	// must check both.
	Exec(ctx context.Context, cmd []string, opts ExecOptions) (ExecResult, error)

	// ExecStream runs a command with stdout/stderr wired to writers.
	ExecStream(ctx context.Context, stdout, stderr io.Writer, name string, args ...string) error

	// Upload writes data to a file path inside the sandbox.
	Upload(ctx context.Context, data []byte, path string) error

	// StartAgent launches the configured guest agent inside the sandbox.
	StartAgent(ctx context.Context, spec AgentSpec) error

	// Token returns the per-sandbox auth token that callers must include
	// when reaching URL(). Empty string for providers whose URL
	// self-authenticates.
	Token() string
}

type EnvironmentEvent struct {
	ID        string    `json:"id"`
	Kind      string    `json:"event"`
	VMID      string    `json:"vm_id"`
	State     VMState   `json:"state"`
	URL       string    `json:"url,omitempty"`
	Error     string    `json:"error,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
}

type EventRecord struct {
	ID         int64
	EntityType string
	EntityID   string
	EventType  string
	Payload    json.RawMessage
	CreatedAt  time.Time
}

type ExecOptions struct {
	// Timeout bounds how long the guest command may run. Zero means
	// DefaultExecTimeout. Values above MaxExecTimeout are clamped.
	Timeout time.Duration
}

type ExecResult struct {
	ExitCode int
	Stdout   []byte
	Stderr   []byte
}

type ExposeSpec struct {
	Port int
	As   string
	// Protocol is "tcp" or "udp". Empty means tcp: the API boundary
	// normalizes it (toOrchestratorExpose), but a record written before the
	// field existed still reads back empty, so consumers fall back rather
	// than assume.
	Protocol Protocol
}

type FleetConfig struct {
	Provider          Provider
	StateStore        StateStore
	Prefix            string        // VM name prefix, e.g. "fuse-"
	ReconcileInterval time.Duration // default 30s

	// TaskStuckTimeout is the maximum age of a Running VM with no state
	// transitions before it is considered stuck. This is a leak-detection
	// ceiling, NOT a heartbeat — healthy long-running tasks must set
	// Spec.MaxRuntime to override this. Default 2h.
	TaskStuckTimeout time.Duration

	// DefaultIdleTimeout applies to VMs whose Spec.IdleTimeout is zero. It is
	// how long a Running VM may go with no exec and no attach session before
	// it is destroyed. Unlike TaskStuckTimeout this is a liveness check, but
	// only over control-plane activity. Zero (the default) disables idle
	// expiry for VMs that do not ask for it.
	DefaultIdleTimeout time.Duration

	// OrphanDestroyMaxRetries is the number of consecutive reconcile cycles
	// an orphan VM may fail to destroy before being dead-lettered and
	// skipped on subsequent cycles. Default 5.
	OrphanDestroyMaxRetries int

	// StartupScriptTimeout bounds a caller's boot-time startup script when
	// BootOptions does not set its own. Default
	// DefaultStartupScriptTimeout. Keep it under the HTTP write timeout so
	// a create that trips it still returns a classified error.
	StartupScriptTimeout time.Duration

	// MaxStartupScriptTimeout is the largest bound a caller may request via
	// BootOptions.StartupScriptTimeout. Default
	// DefaultMaxStartupScriptTimeout. A request above it is refused with
	// ErrStartupScriptTimeoutTooLarge. Keep it under the HTTP write timeout
	// for the same reason StartupScriptTimeout is kept under it.
	MaxStartupScriptTimeout time.Duration

	// DefaultSnapshotRetention applies to snapshots created without an
	// explicit retention window. Zero leaves snapshots unbounded until
	// explicitly deleted.
	DefaultSnapshotRetention time.Duration

	// SnapshotQuotaMaxCount limits ready/in-flight snapshots per tenant.
	// Zero disables count-based enforcement.
	SnapshotQuotaMaxCount int

	// SnapshotQuotaMaxBytes limits the aggregate size of ready/in-flight
	// snapshots per tenant. Zero disables byte-based enforcement.
	SnapshotQuotaMaxBytes int64

	// ArtifactMover copies a build artifact from one host agent to another.
	// Nil (the default) means artifacts cannot move, in which case an
	// environment seeded from one is pinned to the host that holds it — the
	// behaviour that predates peer-to-peer distribution. See ArtifactMover.
	ArtifactMover ArtifactMover

	// Ingress publishes environments through fuse-proxy so their urls survive
	// a migrate. nil means every url is the host's dnat port, as it always
	// was. See ingress.go.
	Ingress IngressProxy

	// ArtifactPullTimeout bounds a single host-to-host artifact transfer.
	// Zero inherits the caller's context, which for a create is the HTTP
	// request. Transfer time scales with artifact size and link speed, so any
	// fixed bound is either too small for the largest legitimate artifact or
	// too large to detect anything; set it only where the fleet's artifacts and
	// links are known.
	ArtifactPullTimeout time.Duration

	// CheckpointInterval turns on background checkpoints: every interval each
	// firecracker vm takes a diff live snapshot that is merged onto a copy
	// kept on another host, so a live migrate to that host only moves what
	// changed since. each tick pauses the guest briefly and sends its dirty
	// pages over the network; the first tick of a chain sends the whole
	// memory image and rootfs. zero, the default, disables it.
	CheckpointInterval time.Duration

	// ArtifactIdleTTL is how long a layer artifact may go unreferenced and
	// unused before the reconcile loop collects it. "Used" includes cache hits,
	// not just environments holding it open. Zero (the default) disables idle
	// collection: an orchestrator upgrade must not start deleting artifacts an
	// existing fleet relies on.
	ArtifactIdleTTL time.Duration

	// ArtifactMaxPerTenant caps how many ready layer artifacts one tenant may
	// keep, evicting least recently used on overflow. It is the cheap ceiling
	// behind ArtifactIdleTTL, for a tenant that builds often enough to keep
	// every layer inside the idle window. Zero (the default) disables it.
	ArtifactMaxPerTenant int

	// PlacementPolicy controls how the scheduler picks among hosts
	// when multiple are registered. Default is spread.
	PlacementPolicy PlacementPolicy

	// TokenEncryptionKey is the 32-byte AES-256 key used to encrypt
	// per-VM auth tokens before storing them in the state store.
	// When nil, VM credential generation is skipped (insecure mode).
	TokenEncryptionKey []byte

	// HostProviderFactory builds a Provider for a given (url, token,
	// backend) triple. The fleet uses it during recoverState to
	// rehydrate the per-host providers that RegisterHost would have
	// created during normal operation. Without it, an orchestrator
	// restart loses the scheduler's host registry and falls back to
	// single-provider mode for all subsequent placements.
	HostProviderFactory func(url, token string, backend HostBackend) Provider

	// EgressRegistry holds the egress backends this orchestrator can
	// provision. nil, or an empty registry, means a proxy-mode create is
	// refused; there is no fallback to direct.
	EgressRegistry *egress.Registry

	Metrics ReconcileMetrics
	Logger  *slog.Logger
}

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

type ForkOptions struct {
	// Comment is attached to the seed snapshot when ForkEnvironment
	// creates one (empty ReuseSnapshotID). ignored when reusing an
	// existing snapshot.
	Comment string

	// ReuseSnapshotID selects an existing ready snapshot of the source
	// vm to seed the fork from. empty means snapshot the source first.
	ReuseSnapshotID string
}

type GPUDevice struct {
	UUID          string `json:"uuid,omitempty"`
	Model         string `json:"model,omitempty"`
	PCIBusID      string `json:"pci_bus_id,omitempty"`
	MemoryMB      int    `json:"memory_mb,omitempty"`
	DriverVersion string `json:"driver_version,omitempty"`
	CUDAVersion   string `json:"cuda_version,omitempty"`
	ComputeCap    string `json:"compute_cap,omitempty"`
	MIGCapable    bool   `json:"mig_capable,omitempty"`
	MIGMode       string `json:"mig_mode,omitempty"`
	IOMMUGroup    string `json:"iommu_group,omitempty"`
}

type GuestEgress struct {
	Mode     string `json:"mode"`
	Provider string `json:"provider,omitempty"`
	Protocol string `json:"protocol,omitempty"`
	Endpoint string `json:"endpoint,omitempty"`
	// NoProxy is the bypass set the variables carry, as bare ips: the vm's
	// loopback (compose publishes every service port there), the guest's own
	// tap address and the host side of the tap. many clients silently
	// ignore cidr in NO_PROXY, so a /16 can look like coverage and provide
	// none.
	NoProxy []string `json:"no_proxy,omitempty"`
}

type GuestHTTPResponse struct {
	Status int
	Body   []byte
}

type HTTPStatusError struct {
	Code int
	Body string
}

type HealthState string

type HealthStatus struct {
	State HealthState `json:"state"`
	// Since is when the probe entered State, so a consumer can tell a
	// long-standing failure from one that just started.
	Since time.Time `json:"since,omitempty"`
	// Failures is the count of consecutive failed attempts. It is reset by
	// any success, so a passing probe always reports zero.
	Failures int `json:"failures,omitempty"`
	// Message is the last attempt's failure detail (a non-2xx status, a
	// connection error, a non-zero exit), empty while passing.
	Message string `json:"message,omitempty"`
}

type HealthcheckHTTP struct {
	Port int    `json:"port"`
	Path string `json:"path,omitempty"`
}

type HealthcheckSpec struct {
	HTTP *HealthcheckHTTP `json:"http,omitempty"`
	Exec []string         `json:"exec,omitempty"`

	IntervalSeconds    int64 `json:"interval_seconds,omitempty"`
	TimeoutSeconds     int64 `json:"timeout_seconds,omitempty"`
	Retries            int   `json:"retries,omitempty"`
	StartPeriodSeconds int64 `json:"start_period_seconds,omitempty"`
}

type Host struct {
	ID      string
	URL     string // base URL of the host agent (e.g. https://agent-1.local)
	Token   string // bearer token for this host's agent
	Region  string
	Backend HostBackend // "firecracker" or "qemu"; empty means firecracker (default)
	// Labels are operator-declared key/value pairs supplied at registration
	// and matched against a spec's placement label selectors. They are never
	// probed from the host agent, the same trust model as Capacity.GPUKind.
	Labels    map[string]string
	Capacity  HostCapacity
	Allocated HostCapacity
	State     HostState
	LastSeen  time.Time
	CreatedAt time.Time
	UpdatedAt time.Time
}

type HostBackend string

type HostCapacity struct {
	CPUs      int `json:"cpus"`
	RamMB     int `json:"ram_mb"`
	StorageGB int `json:"storage_gb"`
	VMCount   int `json:"vm_count"` // max concurrent VMs

	// Arch is the host's CPU architecture in GOARCH vocabulary ("amd64",
	// "arm64"). Probed from the host agent like CPUs/RamMB; an operator may
	// also declare it at registration. Empty means amd64: every host that
	// existed before this field was x86_64, so old records stay schedulable
	// without migration.
	Arch string `json:"arch,omitempty"`

	// GPUs is the count of whole GPU devices available on the host.
	// Zero means no GPUs. Only qemu-backed hosts may report GPUs > 0
	// (enforced at registration, see internal/api registerHost).
	GPUs int `json:"gpus,omitempty"`

	// GPUKind identifies the GPU model (e.g. "a100"). Empty when GPUs is 0.
	GPUKind string `json:"gpu_kind,omitempty"`

	// MIGProfiles is fractional GPU capacity: MIG instance count by
	// profile name (e.g. {"1g.10gb": 4}). A GPU in MIG mode stays on the
	// nvidia driver and exports mdev devices, so it is never part of the
	// whole-device GPUs pool — the two counters are independent (D5).
	// Only qemu-backed hosts may advertise MIG profiles.
	//
	// When the host reports per-instance MIG inventory (MIGInstances), this
	// map is a derived summary (count by profile) and the scheduler binds
	// specific instance uuids rather than decrementing a counter. When a
	// host only declares counts (the --mig-profile registration override,
	// or a hand-managed mig-inventory.txt without parent detail), this map
	// remains the scheduling unit so legacy callers do not break.
	MIGProfiles map[string]int `json:"mig_profiles,omitempty"`

	// MIGInstances is the per-instance MIG inventory probed from the host
	// agent (one entry per carved MIG GPU instance). When non-empty, the
	// scheduler switches from count-based to instance-based allocation:
	// fits() checks for free instances of the requested profile on a
	// kind-matching card, and allocate binds concrete uuids to VMs. This
	// is strictly additive — a host that reports no instances falls back
	// to the MIGProfiles count path (issue #41).
	MIGInstances []MIGInstance `json:"mig_instances,omitempty"`

	// GPUDevices is the per-device detail probed from the host agent
	// (one entry per whole GPU). It rides the capacity wire alongside the
	// scalar GPUs/GPUKind counters. In-memory + wire only in this PR; the
	// durable per-device schema is issue #37.
	GPUDevices []GPUDevice `json:"gpu_devices,omitempty"`

	// GPUDeviceUUIDs is the set of device uuids currently bound to VMs. It
	// is populated only on a host's Allocated struct (never on Capacity),
	// and only for hosts that report per-device inventory. fits() derives
	// the free-device set as Capacity.GPUDevices minus this set. It is
	// in-memory only: allocation/deallocation maintain it, and recovery
	// recomputes it from live VM bindings, so it is never persisted as its
	// own column (the durable source of truth is the per-VM gpu_uuids).
	GPUDeviceUUIDs []string `json:"gpu_device_uuids,omitempty"`

	// MIGInstanceUUIDs is the set of MIG instance uuids currently bound to
	// VMs. Populated only on Allocated (never on Capacity), and only for
	// hosts that report per-instance MIG inventory. fits() derives the
	// free-instance set as Capacity.MIGInstances minus this set. In-memory
	// only, like GPUDeviceUUIDs: the durable source of truth is the
	// per-VM mig_instance_uuids binding.
	MIGInstanceUUIDs []string `json:"mig_instance_uuids,omitempty"`
}

type HostFilter struct {
	Limit  int
	Cursor string
}

type HostRecord struct {
	ID             string
	URL            string
	TokenEncrypted []byte
	Region         string
	State          HostState
	TenantID       string
	Backend        HostBackend
	Labels         map[string]string
	Capacity       HostCapacity
	Allocated      HostCapacity
	LastSeen       time.Time
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

type HostState string

type IngressGrant struct {
	ProxyAddr     string
	ServerCertPEM string
	Routes        []IngressRoute
}

type IngressPort struct {
	Name      string
	GuestPort int
}

type IngressProxy interface {
	Publish(ctx context.Context, req IngressRequest) (IngressGrant, error)
	Lookup(ctx context.Context, owner string) (IngressGrant, error)
	Unpublish(ctx context.Context, owner string) error
}

type IngressRequest struct {
	Owner string
	// Token is the credential the guest will present. it is minted per vm, for
	// the reason fork mints everything else per vm: a disk copy must not be
	// able to speak as its source.
	Token string
	Ports []IngressPort
	// AdoptFrom names an owner whose public ports this one takes over, route
	// by route, matched on name. it is how a migrated environment keeps its
	// url. empty means fresh ports.
	AdoptFrom string
}

type IngressRoute struct {
	Name      string
	GuestPort int
	// URL is the stable host:port clients connect to.
	URL string
}

type LiveSnapshotCapable interface {
	CheckpointLive(ctx context.Context, comment string) (Checkpoint, error)
}

type MIGInstance struct {
	UUID          string `json:"uuid,omitempty"`
	Profile       string `json:"profile,omitempty"`
	Kind          string `json:"kind,omitempty"`
	ParentGPUUUID string `json:"parent_gpu_uuid,omitempty"`
}

type MemoryShrinkCapable interface {
	CheckpointLiveShrunk(ctx context.Context, comment string) (Checkpoint, error)
}

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

type MemoryStatus struct {
	ResidentChunks int    `json:"resident_chunks"`
	TotalChunks    int    `json:"total_chunks"`
	Done           bool   `json:"done"`
	Error          string `json:"error,omitempty"`
}

type MemoryWatcher interface {
	MemoryStatus(ctx context.Context, vmID string) (MemoryStatus, error)
}

type MigrateOptions struct {
	// TargetHostID is the host to migrate to. empty means the orchestrator
	// picks a host other than the source's, preferring the vm's checkpoint
	// standby. a vm with no host (single-provider mode) stays where it is.
	TargetHostID string

	// Live carries the guest's memory across and resumes it on the target, so
	// processes survive the move, instead of cold-booting a disk snapshot.
	//
	// it is opt-in and never falls back to a cold migration. the seed it takes
	// is a live snapshot, whose rootfs is not bootable without its memory, so
	// there is nothing to fall back onto; and a caller who asked for processes
	// to survive should hear that they would not, while the source is still
	// running, rather than find out afterwards. it needs a target other than
	// the source's host, the same cpu and firecracker build on both, and the
	// source's network slot free on the target (the frozen guest keeps its
	// addresses and nothing remaps them yet).
	Live bool

	// Lazy resumes the guest on the target before its memory has arrived and
	// pages it in from the source afterwards, so the move does not wait on a
	// full copy of the memory image. it needs Live and a vm booted with
	// HugePages. until the target reports every page resident the guest still
	// depends on the source's seed snapshot, which stays pinned until then;
	// if the source host is lost first, the guest is lost with it.
	Lazy bool
}

type OperationMetrics interface {
	OperationCompleted(op string, d time.Duration, err error)
}

type PlacementDecision struct {
	HostID       string          `json:"host_id"`
	Policy       PlacementPolicy `json:"policy"`
	Candidates   int             `json:"candidates"`    // eligible hosts considered
	HeadroomCPUs int             `json:"headroom_cpus"` // CPUs remaining after placement
	HeadroomRam  int             `json:"headroom_ram"`  // RAM remaining after placement

	// ArtifactLocal reports that the winning host already held the spec's seed
	// artifact, so the environment boots from a local copy with no transfer.
	// When it is false and the spec seeds from an artifact, the caller has to
	// move the artifact to the winner before creating the VM, so this is the
	// field that says whether a transfer is about to happen.
	ArtifactLocal bool `json:"artifact_local,omitempty"`

	// ArtifactHolders is how many of the eligible candidates held the artifact.
	// Zero alongside ArtifactLocal=false means no host that could take the
	// workload had it; a positive count alongside ArtifactLocal=false cannot
	// happen, and reading both is how a decision stays self-explaining.
	ArtifactHolders int `json:"artifact_holders,omitempty"`
}

type PlacementHints struct {
	// ArtifactHosts are the hosts that already hold the spec's seed artifact.
	//
	// This is a PREFERENCE and never a constraint. A host in this set that
	// cannot fit the workload, is cordoned, is the wrong arch, has the wrong
	// labels, or cannot serve the GPU request is rejected by the ordinary gates
	// before this map is ever consulted; locality only ever breaks a tie among
	// hosts that already qualify. Letting it do more would trade a correct
	// placement for a fast one, which is how a cache hit turns a working create
	// into a failing one.
	ArtifactHosts map[string]bool
}

type PlacementPolicy string

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

type Protocol string

type Provider interface {
	// Create provisions a new sandbox.
	Create(ctx context.Context, spec Spec) (Environment, error)

	// Get returns a handle to an existing sandbox by name.
	Get(ctx context.Context, name string) (Environment, error)

	// Destroy tears down a sandbox.
	Destroy(ctx context.Context, name string) error

	// List returns all sandboxes matching the given prefix.
	List(ctx context.Context, prefix string) ([]Environment, error)

	// Close releases provider resources.
	Close() error
}

type ReconcileMetrics interface {
	ReconcileCompleted(summary ReconcileSummary)
}

type ReconcileSummary struct {
	TrackedVMs          int
	ProviderVMs         int
	OrphansDestroyed    int
	OrphansFailed       int
	OrphansDeadLettered int
	StuckTasksSuspected int
	StuckTasksFailed    int
	IdleVMsSuspected    int
	IdleVMsFailed       int
	VMsMissingProvider  int
	// HealthChecked counts VMs whose guest returned a usable health verdict
	// this cycle; HealthFailing is how many of those were failing. Neither
	// causes a teardown: the environment-level probe reports, it does not act.
	HealthChecked int
	HealthFailing int
	// EgressChecked counts proxy-mode VMs whose endpoint was probed this
	// cycle; EgressUnhealthy is how many of those did not answer. Like the
	// environment probe, an unhealthy proxy reports and nothing acts on it:
	// the vm keeps running with no egress, never with direct egress.
	EgressChecked   int
	EgressUnhealthy int
	// EgressEndpoints is the live count of provisioned endpoints by provider
	// and health state, for the gauge. nil when nothing was probed.
	EgressEndpoints map[EgressEndpointKey]int
	Duration        time.Duration
}

type SnapshotCapable interface {
	Checkpoint(ctx context.Context, comment string) (string, error)
	Restore(ctx context.Context, checkpointID string) error
	ListCheckpoints(ctx context.Context) ([]Checkpoint, error)
}

type SnapshotCountKey struct {
	State SnapshotState
	Mode  SnapshotMode
}

type SnapshotDeleter interface {
	DeleteCheckpoint(ctx context.Context, checkpointID string) error
}

type SnapshotDigester interface {
	CheckpointWithDigest(ctx context.Context, comment string) (Checkpoint, error)
}

type SnapshotExportRecord struct {
	Destination string
	Status      SnapshotExportStatus
	RequestedAt time.Time
	UpdatedAt   time.Time
	LastError   string
}

type SnapshotExportStatus string

type SnapshotFilter struct {
	VMID     string
	TaskID   string
	TenantID string
	State    SnapshotState

	// Mode narrows to one creation mode, e.g. SnapshotModeBuild to list only
	// build artifacts.
	Mode SnapshotMode

	// LayerKey narrows to artifacts materializing one setup step. Unlike Name
	// below, this is a real indexed column rather than a key read out of the
	// metadata blob: it is an equality lookup performed on every build, so it
	// cannot afford to be a JSON probe over every row. Note that listing is
	// not the hot path for it either; see StateStore.FindSnapshotByLayerKey.
	LayerKey string

	// Arch narrows to artifacts built on one architecture. It is a separate
	// field from LayerKey rather than folded into it because the key is
	// derived client-side before any host is scheduled, so arch is only known
	// after the build lands somewhere. It constrains what may be served, not
	// what the recipe is.
	Arch string

	// Name matches the "name" key inside the snapshot's metadata blob. It is
	// how a build artifact is found by something other than its random id.
	// Metadata is free-form JSON, so an absent key or a malformed blob simply
	// does not match rather than erroring.
	Name string

	Limit  int
	Cursor string
}

type SnapshotForkable interface {
	CreateFromCheckpoint(ctx context.Context, spec Spec, srcVMID, checkpointID string) (Environment, error)
}

type SnapshotKind string

type SnapshotMode string

type SnapshotOptions struct {
	// Comment is a free-form note attached to the snapshot. Passed
	// through to the underlying Environment.Checkpoint implementation
	// and persisted in the snapshot record.
	Comment string

	// Mode records whether this snapshot was taken manually (via the
	// REST API) or by an automated process. Defaults to
	// SnapshotModeManual when empty.
	Mode SnapshotMode

	// RetentionUntil, if non-nil, records when the snapshot is
	// eligible for garbage collection.
	RetentionUntil *time.Time

	// Metadata augments the persisted metadata blob. Reserved fields
	// such as "comment" are set by the orchestrator.
	Metadata map[string]string

	// Exports records optional object-storage export intents/status.
	Exports []SnapshotExportRecord

	// TenantID is the scope a layer artifact is filed under, and it is only
	// consulted when LayerKey is set.
	//
	// It exists because the two halves of the cache have to agree on a scope,
	// and the default one cannot. An ordinary snapshot is filed under
	// snapshotTenantID, which is the task id, and `fuse build` derives a task
	// id that is unique per build on purpose. A layer filed under that is
	// filed under a name no later build can ever ask for, so the cache could
	// never hit.
	//
	// This is a security boundary. The API layer derives it from how the
	// caller authenticated and never from a query param or a request body,
	// because a caller that could name its own scope could read another
	// tenant's cache. See callerTenantID.
	//
	// It is deliberately ignored for non-layer snapshots, so nothing about
	// existing snapshot tenancy or quota accounting moves.
	TenantID string

	// LayerKey is set by `fuse build` when this snapshot is a cacheable setup
	// layer, and is empty for every ordinary snapshot. It is what makes an
	// artifact findable by recipe rather than by id: without it a build
	// artifact can only be named, and a name is not something a later build
	// can derive from the Fusefile it is holding.
	LayerKey string

	// Live asks for guest memory to be captured alongside the rootfs, so the
	// restore resumes the guest instead of cold-booting it.
	//
	// It stays opt-in rather than becoming the default, because the cost is
	// real and paid on every create: the full memory image is written to disk
	// with no sparseness to hide behind, and the guest is paused for as long
	// as that write takes. A caller that does not ask for it, or a provider
	// that cannot do it, keeps getting exactly the disk snapshot it always
	// got.
	//
	// The kind is not carried into the restore path. The host agent records
	// it per snapshot and branches on it there, so RestoreSnapshot needs to
	// know nothing about this field; see LiveSnapshotCapable.
	Live bool

	// Diff takes a diff live snapshot: only the memory pages and rootfs
	// blocks changed since Parent, which must be the last live snapshot this
	// vm took (the host refuses with 409 otherwise). requires Live. a diff is
	// never restorable on its own; it merges onto a copy of Parent elsewhere.
	Diff   bool
	Parent string

	// KeepPaused leaves the guest frozen after a diff, for the last hop of a
	// migrate. whoever asks for it owns resuming the guest if that migrate
	// does not finish (DeltaSnapshotCapable.Resume).
	KeepPaused bool

	// ShrinkMemory asks the guest to give back the memory it is not using
	// before a full live snapshot, so the image is smaller to move. an
	// optimization only: an environment that cannot do it takes a plain live
	// snapshot (see MemoryShrinkCapable).
	ShrinkMemory bool

	// NoLineage leaves ParentSnapshotID empty. checkpoint and migrate
	// snapshots are removed by the code that took them, and a lineage link to
	// the previous one would make each undeletable while its successor lives.
	NoLineage bool
}

type SnapshotQuotaUsage struct {
	Count int
	Bytes int64
}

type SnapshotRecord struct {
	SnapshotID       string
	VMID             string
	TaskID           string
	HostID           string
	TenantID         string
	ParentSnapshotID string
	Mode             SnapshotMode

	// LayerKey is the derived cache key of the setup step this artifact
	// materializes (see internal/fusefile.LayerKeys). It is what separates a
	// layer from the rest of SnapshotModeBuild: layers reuse that mode rather
	// than adding a new one, so a non-empty LayerKey is the only thing that
	// marks a build artifact as cache-addressable. Empty on every snapshot
	// that is not a layer, and empty never matches a lookup.
	LayerKey string

	// Arch is the goarch of the host that actually built this artifact, not
	// of whoever asked for it. It is part of every layer lookup even though it
	// is deliberately absent from LayerKey: an ext4 rootfs is not portable
	// across architectures, but the key is derived client-side before a host
	// is scheduled, so arch can only be observed after the fact and applied as
	// a filter.
	Arch string

	// Digest is the hex sha256 of the artifact rootfs, recorded so a transfer
	// of these bytes can be verified against them. It is an integrity check
	// only and is NOT a cross-build identity: two builds of the same recipe
	// produce different rootfs bytes (timestamps, inode ordering, package
	// caches), so it can never serve as a cache key and nothing dedups on it.
	Digest string

	// Kind records whether this snapshot carries guest memory as well as the
	// rootfs. It is written from what the provider reports it actually wrote,
	// never from what the caller asked for, so a live request served by an
	// agent that could only take a disk snapshot is filed as disk.
	//
	// Empty means disk. Every row predating live snapshots reads back that way
	// (the column defaults to 'disk'), and so does any provider that has no
	// second kind to distinguish, which is all of them but firecracker.
	//
	// Nothing consults this on restore: the host agent keeps its own copy in
	// the snapshot's metadata and branches on that, so this is here for
	// reporting, quota reasoning, and telling an operator why one artifact is
	// five times the size of its neighbour.
	Kind SnapshotKind

	State          SnapshotState
	SizeBytes      int64
	RetentionUntil *time.Time
	Metadata       json.RawMessage
	Exports        []SnapshotExportRecord
	LastError      string
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

type SnapshotState string

type Spec struct {
	Name      string // e.g. "fuse-{task-id}"
	CPUs      int
	RamMB     int
	StorageGB int
	Region    string

	// Arch restricts scheduling to hosts of this CPU architecture, in
	// GOARCH vocabulary ("amd64", "arm64"). Empty means any host: images
	// are resolved host-side, so a spec that doesn't care about arch keeps
	// the pre-arch behavior. A host with no reported arch counts as amd64.
	Arch string

	// GPUs is the count of GPU devices requested: whole devices, or MIG
	// instances when GPUProfile is set. Zero means no GPU.
	GPUs int32

	// GPUKind identifies the requested GPU model (e.g. "a100"). Empty when
	// GPUs is 0.
	GPUKind string

	// GPUProfile requests fractional GPU allocation: a MIG profile in
	// mig-parted vocabulary (e.g. "1g.10gb"), passed through as an mdev
	// device by the qemu host agent (decision D5). Empty means whole-device
	// allocation.
	GPUProfile string

	// GPUUUIDs are the concrete device uuids this VM is bound to. Populated
	// by allocation on hosts that report per-device inventory
	// (Capacity.GPUDevices non-empty) and persisted per-VM so the binding
	// survives an orchestrator restart. Empty on legacy homogeneous hosts
	// that only track a scalar GPU count.
	GPUUUIDs []string `json:"gpu_uuids,omitempty"`

	// MIGInstanceUUIDs are the concrete MIG instance uuids this VM is bound
	// to. Populated by allocation on hosts that report per-instance MIG
	// inventory (Capacity.MIGInstances non-empty) and persisted per-VM so
	// the binding survives an orchestrator restart. Empty when the host
	// only tracks MIG allocation by profile count (the MIGProfiles path).
	// Mirrors GPUUUIDs for whole devices (issue #41).
	MIGInstanceUUIDs []string `json:"mig_instance_uuids,omitempty"`

	// HostID pins this sandbox to an exact host id. Unlike GPUUUIDs and
	// MIGInstanceUUIDs, which allocation fills in, this is caller-settable:
	// it comes from the Fusefile's placement.host. A pin is a hard gate, not
	// an override, so the pinned host still has to be active, run the right
	// backend, and fit the spec.
	HostID string

	// Labels are placement label selectors: every pair must match the target
	// host's declared labels. Caller-settable, from placement.labels.
	Labels map[string]string

	// MaxRuntime overrides FleetConfig.TaskStuckTimeout for this task.
	// Zero means "use the fleet default". This is a leak-detection ceiling,
	// not a liveness check — set it higher than any plausible healthy runtime.
	MaxRuntime time.Duration

	// IdleTimeout destroys this VM once it has gone this long with no exec
	// and no attach session. Zero means "use FleetConfig.DefaultIdleTimeout"
	// (itself zero by default, i.e. no idle expiry). Unlike MaxRuntime this
	// is a liveness check, but only over control-plane activity: in-guest CPU
	// and network traffic are not observed.
	IdleTimeout time.Duration

	// Image names a base rootfs for the provider to boot from, resolved by
	// the provider (e.g. the firecracker host agent looks it up in its own
	// named-rootfs directory). Empty means the provider's default base.
	Image string

	// SeedSnapshotID boots this VM from a persisted snapshot artifact instead
	// of Image. Unlike a fork there is no live source VM: the artifact is
	// resolved out of the host agent's snapshot store. It is host-local, which
	// is why SeedSnapshotID always travels with PinnedHostID. Empty means boot
	// from Image. Mutually exclusive with Image.
	SeedSnapshotID string

	// ResumeSeed asks the provider to resume the guest from the seed's memory
	// image instead of cold-booting its rootfs. only a live migration sets it,
	// and only with a live SeedSnapshotID already copied to PinnedHostID. it is
	// a request the host may refuse (wrong cpu, network slot taken), never a
	// hint it may ignore: a live snapshot's rootfs is not bootable on its own.
	ResumeSeed bool

	// HugePages backs guest memory with 2M pages. it is fixed at boot, the
	// host needs that much memory reserved as hugepages, and only a vm booted
	// with it can be migrated lazily (MigrateOptions.Lazy).
	HugePages bool

	// PinnedHostID restricts scheduling to a single host. Set when the VM must
	// land where its host-local seed artifact already is. Empty means schedule
	// across the fleet as usual.
	PinnedHostID string

	// Egress is the outbound networking policy. the zero value is direct,
	// which is the pre-egress behaviour, so every stored record and every
	// caller that predates the field deserializes into it without naming
	// it. see internal/egress.
	Egress egress.Spec
}

type StateStore interface {
	UpsertVM(ctx context.Context, vm VMRecord) error
	DeleteVM(ctx context.Context, vmID string) error
	ListVMs(ctx context.Context) ([]VMRecord, error)

	UpsertTask(ctx context.Context, task TaskRecord) error
	ListTasks(ctx context.Context) ([]TaskRecord, error)

	UpsertSnapshot(ctx context.Context, snapshot SnapshotRecord) error
	GetSnapshot(ctx context.Context, snapshotID string) (SnapshotRecord, error)
	ListSnapshots(ctx context.Context) ([]SnapshotRecord, error)
	DeleteSnapshot(ctx context.Context, snapshotID string) error

	// ListSnapshotsByVM returns snapshots for a single VM, scoped at the
	// store layer (a WHERE clause for Postgres) rather than requiring the
	// caller to load and filter every snapshot in the fleet.
	ListSnapshotsByVM(ctx context.Context, vmID string) ([]SnapshotRecord, error)

	// ListSnapshotsByDigest returns every ready snapshot for tenantID whose
	// artifact hashes to digest. It is the artifact index: the orchestrator
	// answers "which hosts already hold these bytes" by reading the host_id of
	// each row it returns.
	//
	// The index is DERIVED, never a second table. A snapshot row is already the
	// statement "host H holds artifact A", so a separate index could only ever
	// disagree with it, and the disagreement would be invisible until a pull was
	// aimed at a host that no longer had the bytes. Deriving also makes recovery
	// free: there is nothing to rehydrate at startup because the query is the
	// index, and a row whose digest was never recorded is simply not findable
	// rather than wrongly findable.
	//
	// tenantID is a security boundary for the same reason it is one in
	// FindSnapshotByLayerKey: an artifact carries whatever its build baked in.
	ListSnapshotsByDigest(ctx context.Context, tenantID, digest string) ([]SnapshotRecord, error)

	// FindSnapshotByLayerKey returns the newest ready layer artifact matching
	// (tenantID, layerKey, arch), or ok=false when there is no hit.
	//
	// This is its own store method rather than a SnapshotFilter because it
	// runs once per chain key on every build, and ListSnapshotsFiltered loads
	// every snapshot in the fleet and filters in Go. Postgres serves this off
	// a single indexed query.
	//
	// tenantID scoping is a security boundary, not an optimization: serving
	// one tenant's artifact to another leaks whatever that build baked in, so
	// a cross-tenant match must be a miss, never a hit.
	FindSnapshotByLayerKey(ctx context.Context, tenantID, layerKey, arch string) (SnapshotRecord, bool, error)

	// SnapshotQuotaUsage returns the count and aggregate size of snapshots
	// for tenantID that count toward the per-tenant quota: states
	// Creating/Ready/Restoring, excluding SnapshotModeBuild artifacts (see
	// FleetManager.enforceSnapshotQuota). Computed at the store layer (a
	// COUNT/SUM query for Postgres) so quota checks don't require a
	// full-table scan on every CreateSnapshot call.
	SnapshotQuotaUsage(ctx context.Context, tenantID string) (SnapshotQuotaUsage, error)

	AppendEvent(ctx context.Context, event EventRecord) error

	// UpsertDeadLetter inserts or updates a dead-letter entry keyed by
	// (Kind, EntityID). On update, RetryCount and LastSeenAt are advanced.
	UpsertDeadLetter(ctx context.Context, entry DeadLetterRecord) error

	// ListDeadLetters returns all dead-letter entries. Implementations
	// may order arbitrarily.
	ListDeadLetters(ctx context.Context) ([]DeadLetterRecord, error)

	// UpsertHost inserts or updates a host registration.
	UpsertHost(ctx context.Context, host HostRecord) error

	// DeleteHost removes a host from the registry. No-op if absent.
	DeleteHost(ctx context.Context, hostID string) error

	// ListHosts returns all registered hosts.
	ListHosts(ctx context.Context) ([]HostRecord, error)

	// GetHost returns a single host by ID, or an error if not found.
	GetHost(ctx context.Context, hostID string) (HostRecord, error)
}

type TaskRecord struct {
	TaskID     string
	VMID       string
	RunStatus  TaskRunStatus
	RetryCount int
	LastError  string
	AssignedAt time.Time
	UpdatedAt  time.Time
}

type TaskRunStatus string

type TokenSetter interface {
	SetToken(token string)
}

type VMFilter struct {
	TaskID string
	State  VMState
	HostID string
	Limit  int
	Cursor string
}

type VMInfo struct {
	ID        string
	State     VMState
	TaskID    string
	HostID    string
	URL       string
	Spec      Spec
	CreatedAt time.Time
	UpdatedAt time.Time
	Error     string
	Endpoints []Endpoint
	// Health is the environment-level probe's last verdict, or nil when the
	// environment declared no probe or none has been read back yet. See
	// health.go.
	Health *HealthStatus
	// Egress is the resolved outbound policy. always set: a vm created
	// without asking reports direct.
	Egress egress.Status
}

type VMRecord struct {
	ID                 string
	HostID             string
	NetworkHost        string
	State              VMState
	URL                string
	TaskID             string
	TenantID           string
	Spec               Spec
	LastError          string
	AuthTokenEncrypted []byte     // AES-GCM encrypted per-VM auth token (nil for legacy VMs)
	SecretsEncrypted   []byte     // AES-GCM encrypted JSON of the secret map (nil when no secrets supplied)
	Endpoints          []Endpoint // published endpoints (e.g. ingress), if any
	// Egress is the resolved outbound policy. persisted so a restarted
	// orchestrator knows which backend to release on teardown; the health
	// inside it is not meaningful once stored and is not written.
	Egress    egress.Status
	CreatedAt time.Time
	UpdatedAt time.Time
}

type VMState string