ladder

type ActionType string

type AllocateResult struct {
	Allocations []Allocation
	Reshapes    []PlannedAction
	Holds       []PlannedAction
}

type Allocation struct {
	Layer         LayerType
	GapUSDPerHour *big.Rat
	Rationale     string
	DataSources   []string
}

type AllocationInput struct {
	Now                time.Time
	LayerStates        map[LayerType]LayerState
	Layers             []LayerSpec
	DataSources        []string
	Baseline           UsageBaseline
	Config             LadderConfig
	InFlightUSDPerHour *float64
}

type BufferReshapeConfig struct {
	// MaxPaymentPerExchangeUSD caps the payment for a single exchange. nil
	// means no per-exchange cap is applied.
	MaxPaymentPerExchangeUSD *float64
	// MaxPaymentDailyUSD caps the total exchange payments for the current day.
	// nil means no daily cap is applied.
	MaxPaymentDailyUSD *float64
	// UtilizationThresholdPct triggers a reshape when commitment utilization
	// drops below this percentage.
	UtilizationThresholdPct float64
	// LookbackDays is the window used to measure utilization when deciding
	// whether to trigger a reshape.
	LookbackDays int
	// DryRun, when true, simulates the reshape without executing any exchanges.
	DryRun bool
	// LadderRunID links the exchange records this reshape creates to the ladder
	// run that triggered it, so the exchange layer scopes its pending
	// cancellation to this origin (ladder) instead of the standalone task's
	// pendings (gap G10 / issue #1348). Nil means "no ladder run" (the caller is
	// not a ladder run); the reshape runner then behaves as the standalone
	// origin. The concrete runner (wired in L16) MUST forward this to
	// exchange.RunAutoExchangeParams.LadderRunID — the exchangeRunner seam
	// requires it so a future runner cannot silently drop it and reintroduce the
	// cross-origin cancellation bug.
	LadderRunID *string
}

type LadderCadence string

type LadderCapability interface {
	// Provider returns the cloud provider identifier (common.ProviderAWS,
	// common.ProviderAzure, or common.ProviderGCP).
	Provider() common.ProviderType

	// SupportedLayers returns the commitment layers this provider can fulfill.
	// Each LayerSpec declares both the layer type and the roles it covers.
	//
	// Role-cardinality contract (enforced by the engine): the returned set
	// must contain exactly one layer carrying RoleFlex, at most one carrying
	// RoleBase, and at most one carrying RoleBuffer. The only permitted
	// multi-role merge is base+buffer on a single layer (e.g. an Azure
	// reservation serving both roles).
	SupportedLayers() []LayerSpec

	// ListCommitments returns all active commitments for the given scope.
	ListCommitments(ctx context.Context, scope Scope) ([]common.Commitment, error)

	// GetLayerStates returns a point-in-time snapshot for each supported layer.
	// Layers with no active commitments carry explicit zeros in
	// ExistingUSDPerHour/ExpiringUSDPerHour; nil is reserved for genuinely
	// unmeasured metrics (e.g. UtilizationPct on an empty layer) and is
	// treated as missing data by the engine.
	GetLayerStates(ctx context.Context, scope Scope) (map[LayerType]LayerState, error)

	// GetUsageBaseline computes a statistical baseline from historical
	// on-demand usage over the given lookback window and percentile.
	GetUsageBaseline(ctx context.Context, scope Scope, lookbackDays int, percentile float64) (UsageBaseline, error)

	// PurchaseLayer buys commitments for the given layer using the provided
	// recommendation. Implementations return an error wrapping
	// common.ErrCommitmentPurchaseNotSupported when the layer cannot be
	// purchased programmatically; callers detect it with
	// errors.Is(err, common.ErrCommitmentPurchaseNotSupported).
	//
	// Precision note: the engine plans amounts as exact *big.Rat values
	// (PlannedAction.AmountUSDPerHour), but this boundary converts them to
	// the float64 cost fields of common.Recommendation. This is a documented
	// precision seam; exact-decimal plumbing through the purchase path is
	// addressed in a later PR.
	PurchaseLayer(ctx context.Context, layer LayerType, rec common.Recommendation, opts common.PurchaseOptions) (common.PurchaseResult, error)

	// ReshapeBuffer exchanges or modifies buffer-layer commitments to improve
	// utilization when it falls below the configured threshold.
	ReshapeBuffer(ctx context.Context, scope Scope, cfg BufferReshapeConfig) (ReshapeSummary, error)
}

type LadderConfig struct {
	Scope   Scope
	Mode    LadderMode
	Cadence LadderCadence
	// MaxHourlyCommitPerRun caps the total hourly commitment delta a single
	// run may purchase. nil means no cap is applied; when present the cap
	// must be positive (validated by Validate).
	MaxHourlyCommitPerRun *float64
	Ramp                  RampSchedule
	TargetCoveragePct     float64
	BufferFraction        float64
	BaselinePercentile    float64
	LookbackDays          int
	// MaxActionsPerRun limits how many PlannedActions the engine may execute
	// per run. Must be > 0.
	MaxActionsPerRun int
	// BufferUtilizationThresholdPct is the utilization percentage below which a
	// buffer layer is flagged for reshape. Must be in (0, 100]. Use
	// DefaultBufferUtilizationThresholdPct when no threshold is configured.
	BufferUtilizationThresholdPct float64
}

type LadderMode string

type LadderPlan struct {
	Scope       Scope
	GeneratedAt time.Time
	// TargetUSDPerHour is the hourly commitment target derived from
	// Baseline * TargetCoveragePct. nil means it could not be computed.
	TargetUSDPerHour *big.Rat
	// ExistingUSDPerHour is the sum of hourly amortized costs across all
	// active commitment layers. nil means it could not be measured.
	ExistingUSDPerHour *big.Rat
	// GapUSDPerHour is TargetUSDPerHour - ExistingUSDPerHour. nil when either
	// input is nil.
	GapUSDPerHour *big.Rat
	Actions       []PlannedAction
	Baseline      UsageBaseline
}

type LadderStore interface {
	// SaveRun persists a new run record or updates an existing one (upsert by
	// ID).
	SaveRun(ctx context.Context, run *RunRecord) error

	// LatestRunStartedAt returns the CreatedAt timestamp of the most recent
	// run for the given scope, or nil when no run has been recorded yet.
	LatestRunStartedAt(ctx context.Context, scope Scope) (*time.Time, error)

	// SaveTranches persists a batch of tranches. Every tranche must carry a
	// non-empty RunID (Tranche.RunID is the single source of truth for run
	// linkage); implementations persist tranches exactly as given and must
	// not infer linkage from anything else. Tranches are fully
	// self-describing (Layer, AmountUSDPerHour, Term, PaymentOption):
	// executors must be able to fire a tranche as a purchase without any
	// RunRecord or PlanJSON lookup. Callers may call this multiple times
	// (e.g., once per ramp step) and implementations should upsert by
	// tranche ID.
	SaveTranches(ctx context.Context, tranches []Tranche) error
}

type LayerRole string

type LayerSpec struct {
	Type  LayerType
	Roles []LayerRole
}

type LayerState struct {
	// ExistingUSDPerHour is the total hourly amortized cost of active
	// commitments in this layer.
	ExistingUSDPerHour *float64
	// ExpiringUSDPerHour is the share of ExistingUSDPerHour whose commitments
	// expire within the current run cadence window.
	ExpiringUSDPerHour *float64
	// CoveragePct is the percentage of eligible on-demand spend currently
	// covered by commitments in this layer.
	CoveragePct *float64
	// UtilizationPct is the current utilization percentage of commitments in
	// this layer.
	UtilizationPct *float64
	// Layer identifies which commitment layer this snapshot describes.
	Layer LayerType
}

type LayerType string

type PaymentOption string

type PlannedAction struct {
	Action ActionType
	Layer  LayerType
	// AmountUSDPerHour is the hourly commitment delta. It must be non-nil and
	// positive for ActionPurchase, and must be nil for ActionHold and
	// ActionReshape (whose financial impact is implicit in the underlying
	// exchange operation).
	AmountUSDPerHour *big.Rat
	// Term is the commitment term. Must be a valid Term for purchase
	// actions; empty for hold and reshape.
	Term Term
	// PaymentOption is the payment structure. Must be a valid PaymentOption
	// for purchase actions; empty for hold and reshape.
	PaymentOption PaymentOption
	// Rationale is a human-readable explanation of why this action was chosen.
	// Must be non-empty for all action types.
	Rationale string
	// DataSources lists the data feeds (Cost Explorer, CloudWatch, etc.) used
	// to derive this action. Aids auditability.
	DataSources []string
}

type RampSchedule struct {
	Steps []RampStep `json:"steps"`
}

type RampStep struct {
	// AfterDays is the number of days after the run starts at which this
	// tranche fires. Must be strictly greater than the previous step's
	// AfterDays (ascending order required by RampSchedule.Validate).
	AfterDays int `json:"after_days"`
	// Fraction is the share of the total target allocation committed by this
	// tranche. Must be in (0, 1]; fractions across all steps must sum to 1.0.
	Fraction float64 `json:"fraction"`
}

type ReshapeSummary struct {
	// Details holds per-commitment outcome descriptions for logging and audit.
	Details []string
	// Analyzed is the total number of commitments inspected.
	Analyzed int
	// Reshaped is the number of commitments exchanged or modified.
	Reshaped int
	// Skipped is the number of commitments that did not meet the utilization
	// threshold or were blocked by a spend cap.
	Skipped int
}

type RunRecord struct {
	ID          string
	Scope       Scope
	Status      RunStatus
	CreatedAt   time.Time
	CompletedAt *time.Time
	// PlanJSON holds a serialized LadderPlan for audit. Stored as a string
	// rather than an embedded struct so the store interface stays
	// serialization-format-agnostic.
	PlanJSON string
}

type RunStatus string

type Scope struct {
	Provider  common.ProviderType
	AccountID string
}

type Term string

type Tranche struct {
	// FireAfter is the wall-clock time at or after which this tranche fires.
	FireAfter time.Time
	// FiredAt is nil until the tranche actually fires.
	FiredAt *time.Time
	// AmountUSDPerHour is the hourly commitment delta for this tranche step.
	// Validation requires any string that big.Rat.SetString parses as a
	// positive rational (e.g. "3/2", "1.5"); producers should emit the
	// canonical big.Rat.RatString() form, which is lossless and round-trips
	// through big.Rat.SetString without floating-point precision loss,
	// making it safe for DB persistence and rehydration.
	AmountUSDPerHour string
	ID               string
	RunID            string
	Status           TrancheStatus
	// Layer identifies the commitment layer this tranche purchases into.
	// Required so a fired tranche is executable without consulting the parent
	// run's plan.
	Layer LayerType
	// Term is the commitment term for the purchase (Term1Year or Term3Year).
	// Must pass Term.Validate: an unset or unknown term would silently
	// default at the provider boundary (money-shaping field, same rule as
	// PlannedAction.Term).
	Term Term
	// PaymentOption is the payment structure for the purchase (e.g.
	// PaymentNoUpfront). Must pass PaymentOption.Validate, for the same
	// reason as Term.
	PaymentOption PaymentOption
	StepIndex     int
}

type TrancheInput struct {
	// Config provides the ramp schedule and is re-validated by BuildTranches.
	Config *LadderConfig
	// RunID stamps every produced Tranche row for run linkage. Required.
	RunID string
	// Term is the commitment term (Term1Year or Term3Year) passed to each
	// buy-now purchase action and future tranche. The caller selects the
	// term; v1 uses a single term for all allocations. Must pass
	// Term.Validate.
	Term Term
	// PaymentOption is the payment structure (e.g. PaymentNoUpfront) passed
	// to each buy-now purchase action and future tranche. Must pass
	// PaymentOption.Validate.
	PaymentOption PaymentOption
	// NewID is called once per produced Tranche to assign a unique identifier.
	// Callers may inject a UUID function, a sequential counter, or any other
	// scheme. Must return a non-empty string on every call.
	NewID func() string
	// Now is the wall-clock time of the run. BuildTranches never calls
	// time.Now internally; callers inject the clock for testability and
	// audit-trail accuracy.
	Now time.Time
	// Allocations is the full set of per-layer sizing decisions from Allocate.
	// Each allocation is split across all ramp steps in the schedule.
	Allocations []Allocation
}

type TrancheResult struct {
	// BuyNow holds ActionPurchase actions for the immediate (AfterDays == 0)
	// ramp step, if one exists in the schedule.
	BuyNow []PlannedAction
	// Tranches holds future scheduled ramp rows for every step with
	// AfterDays > 0. Each row has status TrancheStatusScheduled and a
	// FireAfter timestamp set to Now + AfterDays.
	Tranches []Tranche
}

type TrancheStatus string

type UsageBaseline struct {
	// LowWaterUSDPerHour is the usage floor derived from the configured
	// percentile (e.g., the 5th percentile of hourly spend).
	LowWaterUSDPerHour *float64
	// StableUSDPerHour is the estimated stable portion after applying the
	// buffer fraction to LowWaterUSDPerHour.
	StableUSDPerHour *float64
	// Series holds the raw hourly values used for computation. It is optional
	// and may be nil when only the summary statistics are needed (e.g., when
	// populating the approval email body).
	Series []float64
	// LookbackDays is the window (in days) over which the baseline was
	// computed.
	LookbackDays int
	// Percentile is the statistical percentile used for LowWaterUSDPerHour.
	Percentile float64
}