Documentation
¶
Overview ¶
Package contextguard contains the provider-independent, side-effect-free policy for ContextGuard auto-compaction. It deliberately has no dependency on adapters, persistence, or daemon workers: callers apply returned Decisions.
Index ¶
Constants ¶
const ( DefaultThreshold = 80 MinThreshold = 40 MaxThreshold = 95 RearmGapPercentagePoints = 10 MaxObservationDispatchAge = 30 * time.Second )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Decision ¶
type Decision struct {
Persist bool
Publish bool
RequestDispatch bool
Rejected RejectReason
}
Decision lets the daemon shell persist/publish/dispatch without policy I/O. RequestDispatch is emitted only for Prepared, before a provider write boundary.
type Event ¶
type Event struct {
Kind EventKind
At time.Time
Observation Observation
Config Config
Key Key
// SourceSequence orders external provider lifecycle edges. It shares the
// source/feed cursor with Observation.IngestSequence and is scoped by Key.
SourceSequence uint64
Corrupt bool // meaningful only for EventRecovery
}
Event has an explicit dispatch-time At so observation freshness remains a deterministic policy input. Key is used for replacement/epoch events.
type EventKind ¶
type EventKind string
EventKind identifies a serialized input to Reduce.
const ( EventObservation EventKind = "observation" EventConfigChanged EventKind = "config_changed" EventProviderUnsupported EventKind = "provider_unsupported" EventProviderSupported EventKind = "provider_supported" EventSessionIdle EventKind = "session_idle" EventSessionBusy EventKind = "session_busy" EventDispatchStarted EventKind = "dispatch_started" EventDispatchNoSideEffect EventKind = "dispatch_no_side_effect" EventActionWritten EventKind = "action_written" EventActionOutcomeUnknown EventKind = "action_outcome_unknown" EventProviderCompactionStarted EventKind = "provider_compaction_started" EventProviderCompactionCompleted EventKind = "provider_compaction_completed" EventEventLoss EventKind = "event_loss" EventBackendEpochChanged EventKind = "backend_epoch_changed" EventNewInstance EventKind = "new_instance" EventRecovery EventKind = "recovery" )
type Key ¶
type Key struct {
SessionID string
SessionInstance string
BackendEpoch string
ProviderThreadID string
}
Key binds an observation/action cycle to its provider provenance.
type Machine ¶
type Machine struct {
Config Config
Key Key
State State
LastObservation *Observation
TriggerThreshold int
SettingsChangedAt time.Time
FreshAfter time.Time
ProviderSupported bool
BackendChangedAt time.Time
InstanceChangedAt time.Time
// LastSourceSequence fences the one provider source/feed across exact
// telemetry and external provider lifecycle edges. A new backend epoch or a
// replacement session instance is the only reset boundary.
LastSourceSequence uint64
}
Machine is the complete durable policy state. LastObservation is retained in memory for revalidation but callers must not persist it; Recover always drops it.
type Observation ¶
type Observation struct {
Key Key
SettingsRevision uint64
IngestSequence uint64
ObservedAt time.Time
UsedTokens uint64
ContextLimit uint64
Quality Quality
}
Observation is the complete provenance-bound input required to consider a provider action. ContextLimit is provider-authored and must be positive.
type Quality ¶
type Quality string
Quality says whether the provider has supplied exact occupancy telemetry.
type RejectReason ¶
type RejectReason string
RejectReason tells a caller why no state or observable effect was produced.
const ( RejectNone RejectReason = "" RejectInvalidEvent RejectReason = "invalid_event" RejectWrongKey RejectReason = "wrong_key" RejectSettingsRevision RejectReason = "settings_revision" RejectSourceSequence RejectReason = "source_sequence" RejectQuality RejectReason = "quality" RejectMalformedLimit RejectReason = "malformed_limit" RejectStaleObservation RejectReason = "stale_observation" RejectInvalidConfig RejectReason = "invalid_config" RejectInvalidTransition RejectReason = "invalid_transition" )
type State ¶
type State string
State is a durable policy phase. Only the worker performs I/O; this package chooses the state and reports the requested effect.
const ( StateDisabled State = "disabled" StateUnsupported State = "unsupported" StateArmed State = "armed" StatePendingIdle State = "pending_idle" StatePrepared State = "prepared" StateExecuting State = "executing" StateAwaitingConfirmation State = "awaiting_confirmation" StateProviderCompacting State = "provider_compacting" StateLatched State = "latched" StateOutcomeUnknownHold State = "outcome_unknown_hold" StateEventLossHold State = "event_loss_hold" StateBlockedCorrupt State = "blocked_corrupt" )
Source Files