Documentation
¶
Overview ¶
Package compactiondetect implements the proxy-derived coding-agent session compaction detector: a concrete, process-owned detector that inspects the effective canonical baseline after an upstream B-leg opens and every canonical event actually released by the retry stream, and derives typed started/completed lifecycle observations for fail-open SDK observers.
The detector is pure with respect to external I/O: it returns derived compaction.Event values for the runtime to dispatch after the detector lock is released. It stores only bounded hashes/counts/timestamps and transaction metadata keyed by the authoritative A-leg, never prompt content, and requires no database state.
Index ¶
- Constants
- func ExactFactsFromCall(call lipapi.Call) compactionfacts.RequestFacts
- type Config
- type Detector
- func (d *Detector) PreviewRequest(meta compaction.PreservationMeta, call lipapi.Call) RequestPreview
- func (d *Detector) PreviewRequestFacts(meta compaction.PreservationMeta, facts compactionfacts.RequestFacts) RequestPreview
- func (d *Detector) PreviewResponse(meta compaction.PreservationMeta, ev lipapi.Event) ResponsePreview
- func (d *Detector) RequestOpened(meta compaction.PreservationMeta, call lipapi.Call) []compaction.Event
- func (d *Detector) RequestOpenedFacts(meta compaction.PreservationMeta, facts compactionfacts.RequestFacts) []compaction.Event
- func (d *Detector) ResponseReleased(meta compaction.PreservationMeta, ev lipapi.Event) []compaction.Event
- type PreviewKind
- type RequestPreview
- type ResponsePreview
- type StartRuleMatchInput
- type StartRuleMatchResult
Constants ¶
const ( // HeuristicRuleID is the generic local-compaction rule id used for // completion-only history-heuristic observations. HeuristicRuleID = "local.compaction_heuristic.v1" // DefaultSweepInterval bounds how often the full-map inactivity sweep runs. // The release path calls the detector for every canonical event, so the // O(maxLegs) TTL scan is amortized to once per interval instead of once per // event (F3). TTL expiry is therefore approximate within one interval — // acceptable for lazy hygiene, since the hard max-entry cap is enforced // separately at leg creation (O(1) check on every call). DefaultSweepInterval = time.Minute )
const ( PreviewNone = compaction.PreviewNone PreviewStartCandidate = compaction.PreviewStartCandidate PreviewCompletionCandidate = compaction.PreviewCompletionCandidate )
Variables ¶
This section is empty.
Functions ¶
func ExactFactsFromCall ¶
func ExactFactsFromCall(call lipapi.Call) compactionfacts.RequestFacts
ExactFactsFromCall extracts exact bounded RequestFacts from a canonical Call.
Types ¶
type Config ¶
type Config struct {
// MaxLegs bounds the number of concurrently tracked authoritative A-legs.
// Zero uses 4096. Entries beyond the bound are evicted lazily (least
// recently seen), with no background worker.
MaxLegs int
// IdleTTL expires tracked A-legs (and their transactions) after inactivity.
// Zero uses 24h. Eviction is lazy and time-sampled: the full-map inactivity
// sweep runs at most once per minute, so expiry is approximate within one
// interval; the hard max-entry cap is enforced separately at leg creation.
IdleTTL time.Duration
// Now overrides the clock for deterministic tests. Nil uses time.Now.
Now func() time.Time
}
Config tunes detector bounds. Zero values use documented defaults.
type Detector ¶
type Detector struct {
// contains filtered or unexported fields
}
Detector is a concrete, race-safe, process-owned compaction detector. One instance is shared by all runtime generations; it is not safe to copy. Callers must never invoke observers while holding the internal lock — the detector never does: RequestOpened and ResponseReleased return derived events for the caller to dispatch after the call returns.
func New ¶
New constructs a Detector with the given bounds. A zero Config applies the documented defaults.
func (*Detector) PreviewRequest ¶
func (d *Detector) PreviewRequest(meta compaction.PreservationMeta, call lipapi.Call) RequestPreview
PreviewRequest returns the request-side candidate that the shared detector would recognize without recording a fingerprint, changing a transaction, or emitting an event. It is safe to call before upstream Open. A strict start takes precedence over the history heuristic, matching committed detection.
func (*Detector) PreviewRequestFacts ¶
func (d *Detector) PreviewRequestFacts(meta compaction.PreservationMeta, facts compactionfacts.RequestFacts) RequestPreview
PreviewRequestFacts returns the request-side candidate that the shared detector would recognize from exact facts without recording a fingerprint, changing a transaction, or emitting an event.
func (*Detector) PreviewResponse ¶
func (d *Detector) PreviewResponse(meta compaction.PreservationMeta, ev lipapi.Event) ResponsePreview
PreviewResponse returns the response-side completion candidate without changing the rolling release-text window, transaction state, or observer output. It is intended to run before a separate preservation finalization; the committed ResponseReleased call must run afterwards on the final event.
func (*Detector) RequestOpened ¶
func (d *Detector) RequestOpened(meta compaction.PreservationMeta, call lipapi.Call) []compaction.Event
RequestOpened observes one logical request after its upstream B-leg opened successfully. It delegates to RequestOpenedFacts using ExactFactsFromCall.
func (*Detector) RequestOpenedFacts ¶
func (d *Detector) RequestOpenedFacts(meta compaction.PreservationMeta, facts compactionfacts.RequestFacts) []compaction.Event
RequestOpenedFacts observes one logical request using exact bounded semantic facts. It records the bounded fingerprint, runs the conservative same-A-leg history check, and matches strict start rules. Returns derived events in emission order.
func (*Detector) ResponseReleased ¶
func (d *Detector) ResponseReleased(meta compaction.PreservationMeta, ev lipapi.Event) []compaction.Event
ResponseReleased observes one canonical event actually released by the retry stream (live, gated, tool-finalizer, and recovery drains — exactly once per release). It runs protocol-strict and signature post completions; signature post markers are matched against the accumulated visible text of the response so markers split across streamed deltas are still recognized. Returns derived events for fail-open dispatch; observation never alters the event.
type PreviewKind ¶
type PreviewKind = compaction.PreviewKind
PreviewKind and the preview shapes are owned by the public compaction SDK seam so detector output can be passed directly to preservers. Aliases keep recognition and fingerprint authority in this package without introducing a conversion layer or a second contract.
type RequestPreview ¶
type RequestPreview = compaction.RequestPreview
type ResponsePreview ¶
type ResponsePreview = compaction.ResponsePreview
type StartRuleMatchInput ¶
type StartRuleMatchInput struct {
Operation lipapi.Operation
ToolCount int
HasText func(marker string) bool
}
StartRuleMatchInput provides facts to MatchStartRule for wire or canonical requests.
type StartRuleMatchResult ¶
type StartRuleMatchResult struct {
Matched bool
RuleID string
Mode compactionfacts.RuleMode
Evidence compaction.Evidence
}
StartRuleMatchResult is the output of MatchStartRule.
func MatchStartRule ¶
func MatchStartRule(in StartRuleMatchInput) StartRuleMatchResult
MatchStartRule evaluates the ordered compaction start-rule table against request facts.
Source Files