residency

type AttentionScorer interface {
	BlockAttentionScores(ctx context.Context, ranges []Range) ([]float32, error)
}

type Block struct {
	Range        Range
	Kind         string
	Stable       bool
	CacheClass   contextasm.CacheClass
	TokenHash    string
	LastUsed     int64
	Flags        BlockFlags
	Segment      int
	SplitOrdinal int
}

type BlockFlags uint16

type Capabilities struct {
	RemoveTail                   bool
	RemoveMiddle                 bool
	PositionShift                bool
	SparseAttention              bool
	SlidingWindowAttentionTokens int
	ColdStore                    bool
	RecomputeRange               bool
	AttentionScores              bool
}

type Controller interface {
	Capabilities() Capabilities
}

type EvictionBudget struct {
	SinkTokens   int // always-hot leading tokens (attention sinks)
	RecentTokens int // always-hot trailing window
	MaxTokens    int // hot budget; eviction keeps physical KV within this
}

type Executor interface {
	Controller
	EvictRange(ctx context.Context, r Range) error
	AdmitRange(ctx context.Context, r Range) error
}

type ManifestOptions struct {
	// ResidentTokens limits the manifest to the token range currently resident.
	// This lets callers run the planner after EnsurePrefix before volatile
	// segments have token ranges.
	ResidentTokens int
	// BlockSize splits large manifest segments into uniform logical blocks.
	// A non-positive value keeps each segment as one block.
	BlockSize int
	// LastUsed is copied onto every generated block. Callers that track richer
	// access recency can rewrite LastUsed before planning.
	LastUsed int64
	// RequireComplete reports missing ranges for every non-empty segment. Leave
	// false for prefix-only planning after EnsurePrefix, where volatile suffix
	// ranges have not been tokenized yet.
	RequireComplete bool
}

type MissingTokenRangesError struct {
	Segments []string
}

type Plan struct {
	BudgetTokens    int
	TotalTokens     int
	HotTokens       int
	ProtectedTokens int
	OverBudget      bool
	KeepHot         []Block
	EvictCold       []Block
	Diagnostics     []string
}

type PlanInput struct {
	Blocks       []Block
	BudgetTokens int
	// SinkTokens and RecentTokens mark blocks overlapping those token spans as
	// protected. The spans are coarse by design; block splitting controls
	// precision.
	SinkTokens   int
	RecentTokens int
	StreamPolicy StreamPolicy
	Capabilities Capabilities
	// AttentionScores optionally supplies one score per input block. Higher
	// means more important. When present, eviction within each CacheClass drops
	// lower-score blocks first; when absent, ordering remains recency-based.
	AttentionScores []float32
}

type Range struct {
	Start int
	End   int
}

type StreamPolicy struct {
	Enabled      bool
	SinkTokens   int
	RecentTokens int
}