keepwarm

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package keepwarm owns bounded, generation-local prompt-cache maintenance policy. It consumes provider-neutral residency observations and direct controller handles; it does not select routes, parse provider requests, or enable provider enrollment.

Index

Constants

View Source 
const (
	DefaultMaxRefreshesPerIdleEpoch = 6
	DefaultMaxIdleDuration          = time.Hour
	DefaultMaxActiveTargets         = 1024
	DefaultMaxConcurrentRenewals    = 4
	DefaultRenewTimeout             = 15 * time.Second
	DefaultMaxPolicyEntries         = 4096
)
View Source 
const ID = "keepwarm"

ID is the canonical feature identifier.

Variables

View Source 
var (
	ErrInvalidConfig  = errors.New("keepwarm: invalid configuration")
	ErrQuiescing      = errors.New("keepwarm: generation is quiescing")
	ErrDisabled       = errors.New("keepwarm: disabled")
	ErrPolicyCapacity = errors.New("keepwarm: session policy capacity exhausted")
	ErrPolicyNotFound = errors.New("keepwarm: session policy not found")
	ErrNoSchedule     = errors.New("keepwarm: target has no safe schedule")
	ErrStale          = errors.New("keepwarm: stale renewal result")
)
View Source 
var ErrManagerNotRegistered = errors.New("keepwarm: manager not registered")

Functions

This section is empty.

Types

type ArmInput 

type ArmInput struct {
	ALegID              string
	BLegID              string
	CommittedSuccessful bool
	ToolEvents          []lipapi.ToolEvent
	Observations        []promptcache.Observation
	BackendInstanceID   string
	CanonicalModelID    string
	Controller          promptcache.Controller
}

func CommittedTurn 

func CommittedTurn(aLegID, bLegID, backendInstanceID, canonicalModelID string, tools []lipapi.ToolEvent, observations []promptcache.Observation, controller promptcache.Controller) ArmInput

CommittedTurn is a convenience constructor that keeps the arm adapter tied to canonical tool events and the residency sideband only.

type ArmResult 

type ArmResult struct {
	Armed       bool
	Reason      string
	Epoch       EpochRevision
	TargetCount int
}

type Clock 

type Clock interface{ Now() time.Time }

Clock is injectable so scheduler tests never need wall-clock sleeps.

type ClockFunc 

type ClockFunc func() time.Time

func (ClockFunc) Now 

func (f ClockFunc) Now() time.Time

type Config 

type Config struct {
	Enabled                       bool
	MaxRefreshesPerIdleEpoch      int
	MaxIdleDuration               time.Duration
	MaxActiveTargets              int
	MaxConcurrentRenewals         int
	RenewTimeout                  time.Duration
	ContinueAfterColdRecreate     bool
	MaxColdRecreatesPerIdleEpoch  int
	MaxProviderTokensPerIdleEpoch *int64
	HeuristicOverrides            []HeuristicOverride
}

func ConfigFromYAML 

func ConfigFromYAML(data []byte) (Config, error)

ConfigFromYAML parses only prompt_cache.keepwarm. Provider enrollment is intentionally not represented here and therefore cannot be enabled by this generic scheduler setting.

func DecodeConfig 

func DecodeConfig(n yaml.Node) (Config, error)

DecodeConfig unmarshals a YAML node directly into Config with strict unknown field checks.

func DefaultConfig 

func DefaultConfig() Config

func ParseYAML 

func ParseYAML(data []byte) (Config, error)

func (Config) Validate 

func (c Config) Validate() error

type EpochRevision 

type EpochRevision uint64

type EvidenceGate 

type EvidenceGate struct {
	SafeControl               bool
	AffinityPreserved         bool
	CacheEffectProven         bool
	ForegroundIsolationProven bool
}

EvidenceGate is supplied by an adapter/composition root. The scheduler does not know provider names or request shapes; active renewal requires every independent safety property to be proven by the issuing backend.

func (EvidenceGate) ActiveRenewalSupported 

func (g EvidenceGate) ActiveRenewalSupported() bool

type HeuristicOverride 

type HeuristicOverride struct {
	BackendInstance string
	CanonicalModel  string
	Interval        time.Duration
}

func (HeuristicOverride) Validate 

func (h HeuristicOverride) Validate() error

type Hooks 

type Hooks struct {
	// Accounting receives provider-billable maintenance evidence even when the
	// scheduling result is stale. The manager never merges it into foreground usage.
	// The context is bounded by the manager renewal timeout and canceled with the
	// scheduler/RunDue parent context.
	Accounting func(context.Context, RenewalRecord) error
	// Metric receives only bounded reason/result names, never target or session IDs.
	Metric func(name string)
}

type Invalidator 

type Invalidator interface{ BeginForegroundTurn(string) }

Invalidator is deliberately narrower than Manager so the process registry cannot retain provider handles, controllers, or backend generations.

type Manager 

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

Manager owns provider-neutral state for one immutable runtime generation. Scheduling, renewal execution, release cleanup, and observability live in focused companion files so this type remains the domain aggregate rather than an everything-object.

func NewManager 

func NewManager(cfg Config, clock Clock, hooks Hooks) (*Manager, error)

func (*Manager) ActiveEpochCount 

func (m *Manager) ActiveEpochCount() int

func (*Manager) ActiveTargetCount 

func (m *Manager) ActiveTargetCount() int

func (*Manager) ArmFromCommittedTurn 

func (m *Manager) ArmFromCommittedTurn(input ArmInput) ArmResult

func (*Manager) BeginForegroundTurn 

func (m *Manager) BeginForegroundTurn(aLegID string)

BeginForegroundTurn synchronously detaches the idle epoch and cancels its provider contexts. It intentionally does not wait for release RPCs.

func (*Manager) Config 

func (m *Manager) Config() Config

func (*Manager) EndSession 

func (m *Manager) EndSession(aLegID string)

EndSession invalidates maintenance and removes the generation-local policy shadow for the A-leg. The process policy store is forgotten by the runtime orchestrator alongside this call.

func (*Manager) Metrics 

func (m *Manager) Metrics() MetricsSnapshot

func (*Manager) NextDue 

func (m *Manager) NextDue() (time.Time, bool)

func (*Manager) Quiesce 

func (m *Manager) Quiesce(ctx context.Context) error

func (*Manager) RunDue 

func (m *Manager) RunDue(ctx context.Context)

RunDue dispatches all currently due work, bounded by concurrency and budgets. It is the deterministic fake-clock seam and uses the same bounded renewal execution path as the production scheduler workers.

func (*Manager) SetSessionDisabled 

func (m *Manager) SetSessionDisabled(aLegID string, disabled bool)

func (*Manager) Start 

func (m *Manager) Start()

Start owns one scheduler loop and a bounded worker pool for this generation. It is lazy: a default-on manager with no eligible target owns no goroutines.

type ManagerRegistry 

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

func NewManagerRegistry 

func NewManagerRegistry() *ManagerRegistry

func (*ManagerRegistry) Clear 

func (r *ManagerRegistry) Clear(aLegID string)

Clear restores inheritance on every live generation manager. Managers that can retain the process policy decision clear their shadow so future arms are allowed again; plain invalidators never retained the decision.

func (*ManagerRegistry) Disable 

func (r *ManagerRegistry) Disable(aLegID string)

func (*ManagerRegistry) Len 

func (r *ManagerRegistry) Len() int

func (*ManagerRegistry) Register 

func (r *ManagerRegistry) Register(manager Invalidator) (uint64, error)

func (*ManagerRegistry) Unregister 

func (r *ManagerRegistry) Unregister(id uint64) error

type MetricsSnapshot 

type MetricsSnapshot struct {
	ActiveEpochs  int
	ActiveTargets int
	Events        map[string]uint64
}

type Orchestrator 

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

Orchestrator is the runtime-facing adapter. Call BeginRealTurn immediately after A-leg authority correlation and before route planning; call ArmCommittedTurn exactly once after the committed successful terminal.

func NewOrchestrator 

func NewOrchestrator(manager *Manager, policy ...*PolicyStore) *Orchestrator

NewOrchestrator accepts an optional process policy store so session-end cleanup can remove both generation-local state and process-owned disables.

func (*Orchestrator) ArmCommittedTurn 

func (o *Orchestrator) ArmCommittedTurn(input ArmInput) ArmResult

func (*Orchestrator) BeginRealTurn 

func (o *Orchestrator) BeginRealTurn(aLegID string)

func (*Orchestrator) EndSession 

func (o *Orchestrator) EndSession(aLegID string)

EndSession releases the A-leg's maintenance state without invoking provider control synchronously and forgets the process-owned administrative policy.

func (*Orchestrator) Quiesce 

func (o *Orchestrator) Quiesce(ctx context.Context) error

func (*Orchestrator) RunDue 

func (o *Orchestrator) RunDue(ctx context.Context)

type PolicyService 

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

PolicyService is the narrow core service an authenticated admin adapter can call after resolving and validating proxy-owned A-leg authority. It stores no provider identity, cache key, handle, or controller.

func NewPolicyService 

func NewPolicyService(store *PolicyStore, registry *ManagerRegistry, clock Clock) *PolicyService

func (*PolicyService) Clear 

func (s *PolicyService) Clear(aLegID string) error

Clear restores global inheritance on the live generation managers and intentionally does not arm an epoch.

func (*PolicyService) Disable 

func (s *PolicyService) Disable(aLegID string) (SessionPolicy, error)

func (*PolicyService) ForgetSession 

func (s *PolicyService) ForgetSession(aLegID string)

func (*PolicyService) Get 

func (s *PolicyService) Get(aLegID string) (SessionPolicy, bool)

type PolicyStore 

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

func NewPolicyStore 

func NewPolicyStore(maxEntries int) (*PolicyStore, error)

func (*PolicyStore) Clear 

func (s *PolicyStore) Clear(aLegID string) error

func (*PolicyStore) ClearAndBroadcast 

func (s *PolicyStore) ClearAndBroadcast(registry *ManagerRegistry, aLegID string) error

ClearAndBroadcast mirrors PolicyStore.DisableAndBroadcast: the store is mutated first, and only a successful clear restores inheritance on the live generation managers.

func (*PolicyStore) Disable 

func (s *PolicyStore) Disable(aLegID string, now time.Time) (SessionPolicy, error)

func (*PolicyStore) DisableAndBroadcast 

func (s *PolicyStore) DisableAndBroadcast(registry *ManagerRegistry, aLegID string, now time.Time) (SessionPolicy, error)

func (*PolicyStore) DisabledALegIDs 

func (s *PolicyStore) DisabledALegIDs() []string

DisabledALegIDs returns a bounded snapshot used when a new generation registers. Provider state and manager references never enter this store.

func (*PolicyStore) Forget 

func (s *PolicyStore) Forget(aLegID string)

func (*PolicyStore) Get 

func (s *PolicyStore) Get(aLegID string) (SessionPolicy, bool)

func (*PolicyStore) Len 

func (s *PolicyStore) Len() int

type PrometheusCollector 

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

PrometheusCollector exports only bounded keep-warm state and finite event labels. It retains no provider handles, cache identities, prompts, or session IDs.

The collector lives with its feature owner (not in generic metrics infrastructure): it reads MetricsSnapshot and owns the feature-specific event vocabulary. Collector registration lifetime stays with the metrics bundle owner, which registers this collector through a generic prometheus.Registerer without importing the feature.

func NewPrometheusCollector 

func NewPrometheusCollector() *PrometheusCollector

NewPrometheusCollector constructs an unregistered collector. Registration is the metrics bundle owner's responsibility.

func (*PrometheusCollector) Collect 

func (p *PrometheusCollector) Collect(ch chan<- prometheus.Metric)

func (*PrometheusCollector) Describe 

func (p *PrometheusCollector) Describe(ch chan<- *prometheus.Desc)

func (*PrometheusCollector) Manager 

func (p *PrometheusCollector) Manager() *Manager

Manager returns the currently exported keep-warm manager, if any.

func (*PrometheusCollector) SetManager 

func (p *PrometheusCollector) SetManager(manager *Manager)

SetManager changes the generation whose state is exported.

func (*PrometheusCollector) SwapCount 

func (p *PrometheusCollector) SwapCount() int

SwapCount returns the number of times SetManager was invoked.

type RealClock 

type RealClock struct{}

func (RealClock) Now 

func (RealClock) Now() time.Time

type RenewalRecord 

type RenewalRecord struct {
	OperationID string
	ALegID      string
	TargetID    promptcache.TargetID
	BackendID   string
	ModelID     string
	Status      promptcache.RenewStatus
	Accounting  *promptcache.AccountingEvidence
	Err         error
	Stale       bool
}

type SessionDisabler 

type SessionDisabler interface {
	Invalidator
	SetSessionDisabled(string, bool)
}

SessionDisabler is an optional extension used by generation managers that can retain the process policy decision. The registry still accepts plain Invalidators for compatibility with minimal/test managers.

type SessionPolicy 

type SessionPolicy struct {
	ALegID    string
	Disabled  bool
	Revision  uint64
	UpdatedAt time.Time
}

type TargetRevision 

type TargetRevision uint64

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.