compaction

type AfterResponseReleasePreserver ¶

type AfterResponseReleasePreserver interface {
	AfterResponseRelease(context.Context, lipapi.Event, PreservationMeta, Services) error
}

AfterResponseReleasePreserver is an optional, non-mutating notification at the last synchronous point before a canonical event is returned to the client. Core passes an isolated event copy; errors and panics are fail-open. It is deliberately separate from Preserver so existing implementations remain source-compatible.

type Event ¶

type Event struct {
	Phase         Phase
	Evidence      Evidence
	RuleID        string
	TransactionID string
	TraceID       string
	ALegID        string
	BLegID        string
	AttemptSeq    int
	SessionID     string
	OccurredAt    time.Time
}

Event is a metadata-only compaction lifecycle observation. It carries correlation and evidence fields only; it never exposes canonical request or response content and carries no numeric confidence score.

type Evidence ¶

type Evidence string

Evidence is the epistemic class of the observation.

const (
	// EvidenceProtocolStrict means canonical protocol semantics directly prove
	// compaction (explicit compact operation or released compaction item).
	EvidenceProtocolStrict Evidence = "protocol_strict"
	// EvidenceSignatureStrict means a versioned, deterministic conjunction of
	// implementation markers identified a compaction utility call or an
	// installed summary/post marker.
	EvidenceSignatureStrict Evidence = "signature_strict"
	// EvidenceHistoryHeuristic means a conservative same-A-leg history rewrite
	// strongly inferred a local-only compaction when no strict signal existed.
	EvidenceHistoryHeuristic Evidence = "history_heuristic"
)

type Observer ¶

type Observer interface {
	OnCompaction(context.Context, Event) error
}

Observer subscribes to typed compaction lifecycle observations. Implementors must be non-mutating: the callback has no replacement/decision result. Errors and panics raised by an observer are isolated by the dispatcher and never fail or alter the request.

type Phase ¶

type Phase string

Phase is the compaction lifecycle phase carried by an Event.

const (
	// PhaseStarted marks the beginning of a detected compaction transaction.
	// It is emitted only after an upstream B-leg actually opened.
	PhaseStarted Phase = "started"
	// PhaseCompleted marks the end of a compaction transaction. It is emitted
	// only when evidence proves or strongly infers the compaction installed.
	PhaseCompleted Phase = "completed"
)

type PreservationMeta ¶

type PreservationMeta struct {
	TraceID       string
	SessionID     string
	ALegID        string
	BLegID        string
	AttemptSeq    int
	TransactionID string
	RuleID        string
	Evidence      Evidence
}

PreservationMeta carries bounded correlation and detector metadata. It does not carry raw prompt, response, capsule, or provider payload content.

type Preserver ¶

type Preserver interface {
	ID() string
	BeforeRequest(context.Context, *lipapi.Call, RequestPreview, PreservationMeta, Services) error
	RequestOpened(context.Context, lipapi.Call, []Event, PreservationMeta, Services) error
	BeforeResponseRelease(context.Context, *lipapi.Event, ResponsePreview, PreservationMeta, Services) error
}

Preserver is the content-bearing compaction preservation seam. It is deliberately distinct from Observer: callbacks may inspect canonical request/response content at the three explicit lifecycle boundaries.

Core invokes BeforeRequest and BeforeResponseRelease transactionally. A callback error, panic, or invalid canonical mutation restores the exact pre-callback object and is isolated from primary traffic. RequestOpened is called only after the primary upstream request opened and is fail-open; its content arguments are callback-local defensive copies.

type PreviewKind ¶

type PreviewKind string

PreviewKind identifies a content-free detector candidate exposed to a preservation callback. A preview never commits detector state or emits an Observer event.

const (
	PreviewNone                PreviewKind = "none"
	PreviewStartCandidate      PreviewKind = "start_candidate"
	PreviewCompletionCandidate PreviewKind = "completion_candidate"
)

type RequestOpenFailedPreserver ¶

type RequestOpenFailedPreserver interface {
	RequestOpenFailed(context.Context, PreservationMeta, Services) error
}

RequestOpenFailedPreserver is an optional lifecycle side-channel for a preservation implementation that needs to discard a pre-open, non-billable intent after the primary open loop exhausts without opening a B-leg. It is deliberately separate from Preserver so existing implementations remain source-compatible. The callback is metadata-only, synchronous, and fail-open.

type RequestPreview ¶

type RequestPreview struct {
	Evidence            Evidence
	RuleID              string
	Kind                PreviewKind
	TransactionID       string
	BoundaryFingerprint string
}

RequestPreview is the content-free request-side detector candidate. The boundary fingerprint is a stable, non-billable identity for completion-only candidates that do not yet have a committed transaction.

type ResponsePreview ¶

type ResponsePreview struct {
	Evidence      Evidence
	RuleID        string
	Kind          PreviewKind
	TransactionID string
}

ResponsePreview is the content-free response-side detector candidate. It does not mark a transaction complete; committed detection runs after preservation finalization on the exact released event.

type Services ¶

type Services struct {
	State         state.Store
	BackgroundAux auxiliary.BackgroundClient
}

Services exposes narrow preservation capabilities. BackgroundAux is the process-owned bounded background collection surface; a nil capability means disabled. State remains the ordinary plugin state facade and is safe to leave nil.