resource

type CapacityConfig struct {
	// CPUOvercommit multiplies detected cores. CPU is compressible:
	// exceeding it makes jobs slow, not dead, so overcommit is safe
	// where memory overcommit is not.
	CPUOvercommit float64
	// MemoryFraction is the share of the detected limit to advertise.
	MemoryFraction float64
	// DiskBytes is the staging cache budget. Zero omits the key.
	DiskBytes int64
	// Explicit overrides detection per key, and is the only way to
	// declare a custom resource.
	Explicit Set
}

type Estimator interface {
	Estimate(ctx context.Context, r Request) (Set, error)
}

type InputSize struct {
	// Name is the declared input slot name.
	Name string `json:"name"`
	// Bytes is the input's size.
	Bytes int64 `json:"bytes"`
	// Hash may be empty: the artifact plane fills content_hash
	// opportunistically at first staging, not at registration.
	Hash string `json:"hash,omitempty"`
}

type Lease interface {
	Held() Set
	Owner() string
	Release()
}

type LeaseInfo struct {
	Owner      string    `json:"owner"`
	Held       Set       `json:"held"`
	AcquiredAt time.Time `json:"acquired_at"`
}

type Manager interface {
	// Acquire blocks until want fits, reclaiming where a Reclaimer is
	// registered. It is bounded by ctx, so a blocked job can never
	// outlive its deadline. A want larger than total capacity fails
	// immediately: no release or reclamation could ever satisfy it, so
	// waiting would only defer a certain error.
	Acquire(ctx context.Context, owner string, want Set) (Lease, error)
	// TryAcquire is the non-blocking form. It never reclaims, because a
	// caller that cannot wait also cannot afford eviction I/O.
	TryAcquire(owner string, want Set) (Lease, bool)

	// Free is what is immediately available.
	Free() Set
	// Reclaimable is what registered reclaimers could free on top of Free.
	Reclaimable() Set
	// Capacity is the configured total.
	Capacity() Set
	// Leases is a snapshot of what is currently held.
	Leases() []LeaseInfo

	// RegisterReclaimer installs the reclaim policy for one key.
	RegisterReclaimer(key string, r Reclaimer)
	// Wake tells blocked acquirers that a reclaimer's holdings changed
	// — that something now reclaimable was not a moment ago.
	//
	// The manager broadcasts when a lease is released and on nothing
	// else, and it cannot see inside a reclaimer. An artifact cache
	// whose last stager lets go of an entry has just made those bytes
	// evictable without releasing anything, so the acquirer that asked
	// for them, was told "everything is pinned", and went to sleep will
	// sleep to its deadline unless it is told to look again.
	Wake()
}

type ManagerOption func(*manager)

type Reclaimer interface {
	// Reclaim frees up to need units of key, returning how many it
	// actually freed. Returning zero means nothing more is reclaimable.
	//
	// The units are returned to the manager by releasing the Lease that
	// held them. The return value is only a "something changed, re-check"
	// signal — the manager does not add it to the ledger, because those
	// units are still recorded against a live lease until that lease is
	// released, and counting them in both places would invent capacity.
	//
	// Reclaim is called with the manager's lock dropped, so releasing a
	// lease from inside it is safe and is the expected implementation.
	Reclaim(ctx context.Context, key string, need int64) (int64, error)
	// Available reports how much could be freed without blocking.
	Available(key string) int64
}

type Request struct {
	JobName    string
	Queue      string
	Payload    []byte
	Inputs     []InputSize
	InputBytes int64
	Declared   Set
	Attempt    int
	ScopeOrgID string
}

type ResolveInput struct {
	GlobalDefault Set
	QueueDefault  Set
	Declared      Set
	Func          ResourceFunc
	Estimator     Estimator
	Override      Set

	DeclaredLimits Set
	OverrideLimits Set

	Class   string
	Request Request

	// MaxCapacity is the largest single-worker capacity known to the
	// engine. Empty disables the unschedulable check, which is correct
	// for a single-process engine with no registered workers.
	MaxCapacity Set

	// OnError is called when Func or Estimator returns an error, with
	// the source that failed (SourceFunc or SourceEstimator).
	//
	// Neither may fail an enqueue — that contract is unchanged, and the
	// lower-precedence value stands. But a fallback with no signal is
	// how a misconfigured estimator under-sizes every job in the fleet
	// forever: the jobs enqueue, they run, they OOM, and nothing
	// anywhere says the estimator was the reason. Callers should log it.
	//
	// Optional. Nil discards, which is the right default for a test that
	// only cares about precedence. Called synchronously inside Resolve on
	// the enqueue path: it must not block or panic, or it fails or stalls
	// the enqueue that triggered it.
	OnError func(source string, err error)
}

type ResourceFunc func(ctx context.Context, r Request) (Set, error)

type Set map[string]int64

type Spec struct {
	// Requests is what admission accounts for and what a pod requests.
	Requests Set `json:"requests,omitempty"`
	// Limits is the enforcement ceiling. Memory defaults to Requests
	// (guaranteed); CPU is left unset (burstable), because overrunning
	// CPU makes a job slow while overrunning memory makes it dead.
	Limits Set `json:"limits,omitempty"`
	// Class is an opaque scheduling class for the isolation backend.
	Class string `json:"class,omitempty"`
}