Documentation
¶
Overview ¶
Package contextsession plans durable session history into a bounded provider request with retention rules and overflow spooling. See docs/plans/contextsession.md.
Index ¶
Constants ¶
const StubContentBytes = 256
StubContentBytes bounds the stub Plan builds for a RetentionCompliance payload past its age-driven turn.
Variables ¶
var ( // ErrNilStore is NewPlanner's error when store is nil. ErrNilStore = errors.New("contextsession: store must not be nil") // ErrNilSession is Plan's error when sess is nil. ErrNilSession = errors.New("contextsession: session must not be nil") )
Sentinel errors for NewPlanner and Plan; test with errors.Is.
Functions ¶
func IsReasoningEvent ¶
func IsReasoningEvent(e contextstate.SourceEvent) bool
IsReasoningEvent reports whether e.Kind == provider.ReasoningEventKind.
func StubContent ¶
StubContent truncates content to StubContentBytes, appending truncationMarker inside that cap when truncation occurs. It returns content unchanged when content already fits. StubContentBytes is a cap, not a promised length: the cut prefix passes through bytes.ToValidUTF8 with an empty replacement, so every invalid byte drops and the result may be shorter.
Types ¶
type Elision ¶
type Elision struct {
Ref contextstate.ContentRef
Reason ElisionReason
Kept int
SpoolRef string
}
Elision is one drop or trim decision Plan made for one payload. Ref is always the resolved PayloadRecord's ContentRef. Kept is the byte length of StubContent's return for a stubbed payload; zero means Plan inserted no message at all for that payload. SpoolRef is the spool.Spool.Spool reference for a successful durable write, set only for ElisionReasonWindowOverflow and ElisionReasonRetentionExpired when Planner carries a non-nil spooler and the write succeeded. Empty in every other case, including a failed write.
type ElisionReason ¶
type ElisionReason string
ElisionReason is the closed set of reasons Plan drops or trims a payload.
const ( // ElisionReasonWindowOverflow marks a payload dropped because the // window filled before this payload's turn. ElisionReasonWindowOverflow ElisionReason = "window_overflow" // ElisionReasonRetentionExpired marks a payload whose full content // dropped for age, but whose RetentionClass earned it a stub // instead of a full removal. ElisionReasonRetentionExpired ElisionReason = "retention_expired" // ElisionReasonReasoningRedacted marks a payload excluded because // IsReasoningEvent marked its source event; the content never // entered Request.Messages at all. ElisionReasonReasoningRedacted ElisionReason = "reasoning_redacted" // ElisionReasonRevoked marks a payload contextstate.MemStore.Get // denied as revoked. Security-relevant, unlike the two budget-driven // reasons above: a caller that ignores this reason gets a Request // silently missing content its own store denied. ElisionReasonRevoked ElisionReason = "revoked" )
The reasons Plan records against an Elision.
type PlanResult ¶
PlanResult is Plan's output: the built request, every elision decision Plan made, and the estimator's total over Request.Messages. EstimatedTokens stays at or under Window.Budget() for a deterministic estimator whose empty-list total fits. A larger fixed overhead exceeds it; an estimator that errors on the final call reports zero.
type Planner ¶
type Planner struct {
// contains filtered or unexported fields
}
Planner fits one session's source events into a bounded provider request. Built only through NewPlanner. Safe for concurrent use: its dependencies guard their own state, and Plan holds no mutable state of its own between calls.
func NewPlanner ¶
NewPlanner builds a Planner over store, the durable payload source, and spooler, an optional durable overflow target. A nil store returns ErrNilStore. A nil spooler is valid: Plan never calls Spool.Spool, and behaves exactly as it does with a wired spooler that never gets used, byte for byte.
func (*Planner) Plan ¶
func (p *Planner) Plan(ctx context.Context, sess *contextstate.Session, w contextplan.Window, e provider.TokenEstimator) (PlanResult, error)
Plan walks sess.Source newest to oldest. For every event it resolves the full contextstate.PayloadRecord through one store.Get call before it decides anything, including a reasoning event's and a payload it ends up fully dropping. A revoked payload never enters Request.Messages and always produces an ElisionReasonRevoked entry, checked before the reasoning check. A reasoning event never enters Request.Messages and always produces an ElisionReasonReasoningRedacted entry. For every other event, Plan adds the decoded provider.Message while the running estimate stays at or under w.Budget(); once the next-oldest message would exceed the budget, a RetentionCompliance payload gets a stub instead, unless the stub itself would exceed the budget, in which case it drops too. A wired Spool receives the full payload behind every ElisionReasonWindowOverflow and ElisionReasonRetentionExpired entry, keyed to record.Ref.SubjectID, best-effort, never failing Plan. EstimatedTokens stays at or under w.Budget() for a deterministic estimator whose empty-list total fits. A larger fixed overhead exceeds it; an estimator that errors on the final call reports zero. Plan returns a non-nil error only on a malformed Window, a nil sess, or a payload-resolution failure other than a revocation; it never returns a partial PlanResult.
Source Files