compaction

Documentation

Overview

Package compaction plans context compaction summaries and preserves file-operation hints.

Index

• Constants
• Variables
• func AppendDeterministicState(summary string, files []FileOperation, validations []ValidationRecord, ...) string
• func AppendFileOperationsSummary(summary string, operations []FileOperation) string
• func BranchTokens(branch []database.EntryEntity, countTokens TokenCounter) int
• func NothingToDoError(message string) error
• func RepairPrompt() string
• func StripDeterministicState(summary string) string
• func StripFileOperationsSummary(summary string) string
• func SystemPrompt(previousSummary, splitTurnSummary string) string
• func ValidateCheckpoint(text string) error
• type ActiveWorkRecord
  • func CollectActiveWorkRecords(entries []database.EntryEntity) []ActiveWorkRecord
• type CheckpointStructureError
  • func (err *CheckpointStructureError) Error() string
  • func (err *CheckpointStructureError) Unwrap() error
• type Chunk
  • func Partition(groups []SemanticGroup, availableInputTokens, maxChunks int) ([]Chunk, error)
• type FileOperation
  • func CollectFileOperations(entries []database.EntryEntity) []FileOperation
• type Operation
  • func (operation Operation) Validate() error
• type Plan
  • func PlanBranch(branch []database.EntryEntity, recentTailTokens int, countTokens TokenCounter) (Plan, error)
  • func PlanBranchFromFirstKept(branch []database.EntryEntity, firstKeptEntryID string, ...) (Plan, error)
• type Reason
  • func (reason Reason) Validate() error
• type RetryIntent
  • func (intent RetryIntent) Validate() error
• type SemanticGroup
  • func GroupsFromMessages(messages []database.MessageEntity, entryIDs []string) []SemanticGroup
• type SemanticGroupKind
• type SummaryError
  • func (summaryError *SummaryError) Error() string
  • func (summaryError *SummaryError) Unwrap() []error
• type SummaryOutcome
• type TokenCounter
• type ValidationOutcome
• type ValidationRecord
  • func CollectValidationRecords(entries []database.EntryEntity) []ValidationRecord

Constants

const (

	// MaxValidationRecords bounds validation records retained in a checkpoint.
	MaxValidationRecords = 32
	// MaxActiveWorkRecords bounds active work records retained in a checkpoint.
	MaxActiveWorkRecords = 32
)

const (
	// MaxChunksPerReductionRound bounds model calls in one reduction round.
	MaxChunksPerReductionRound = 32
	// MaxReductionDepth bounds recursive summary reduction rounds.
	MaxReductionDepth = 4
)

const (
	// FileOperationsKey is the details key used for preserved file-operation metadata.
	FileOperationsKey = "file_operations"
)

Variables

var (
	// ErrSummaryInputOverflow indicates that summary input exceeds its budget.
	ErrSummaryInputOverflow = errors.New("summary input overflow")
	// ErrSummaryOutputTruncated indicates that the provider truncated summary output.
	ErrSummaryOutputTruncated = errors.New("summary output truncated")
	// ErrSummaryEmpty indicates that the provider returned an empty summary.
	ErrSummaryEmpty = errors.New("compaction summary was empty")
	// ErrSummaryContentFilter indicates that provider policy filtered the summary.
	ErrSummaryContentFilter = errors.New("compaction summary was content filtered")
	// ErrSummaryRefusal indicates that the model refused to produce the summary.
	ErrSummaryRefusal = errors.New("compaction summary was refused")
	// ErrSummaryProviderFailure indicates that generation ended without a usable summary.
	ErrSummaryProviderFailure = errors.New("compaction summary provider failure")
	// ErrSummaryAborted indicates that summary generation was canceled or aborted.
	ErrSummaryAborted = errors.New("compaction summary was aborted")
	// ErrSummaryReductionNoProgress indicates that reduction did not shrink the input.
	ErrSummaryReductionNoProgress = errors.New("summary reduction made no progress")
	// ErrSummaryFixedOverhead indicates that fixed prompt content exceeds the input budget.
	ErrSummaryFixedOverhead = errors.New("summary fixed overhead exceeds budget")
	// ErrSummaryIndivisibleGroup indicates that one semantic group exceeds the input budget.
	ErrSummaryIndivisibleGroup = errors.New("summary semantic group exceeds budget")
)

var ErrCheckpointStructure = errors.New("invalid checkpoint structure")

ErrCheckpointStructure identifies an invalid generated checkpoint structure.

Functions

func AppendDeterministicState

func AppendDeterministicState(
	summary string,
	files []FileOperation,
	validations []ValidationRecord,
	work []ActiveWorkRecord,
) string

AppendDeterministicState is the sole appendix writer.

func AppendFileOperationsSummary

func AppendFileOperationsSummary(summary string, operations []FileOperation) string

AppendFileOperationsSummary replaces stale operation text and appends current operations.

func BranchTokens

func BranchTokens(branch []database.EntryEntity, countTokens TokenCounter) int

BranchTokens returns the estimated model-facing token count for the effective branch.

func NothingToDoError

func NothingToDoError(message string) error

NothingToDoError returns the no-op compaction error used by planner callers.

func RepairPrompt

func RepairPrompt() string

RepairPrompt asks for a single structural repair without authorizing new facts.

func StripDeterministicState

func StripDeterministicState(summary string) string

StripDeterministicState removes deterministic appendices from a generated summary.

func StripFileOperationsSummary

func StripFileOperationsSummary(summary string) string

StripFileOperationsSummary removes the generated file-operation section from summary text.

func SystemPrompt

func SystemPrompt(previousSummary, splitTurnSummary string) string

SystemPrompt builds the summary prompt used for compaction provider requests.

func ValidateCheckpoint

func ValidateCheckpoint(text string) error

ValidateCheckpoint validates only the stable structure, never model prose.

Types

type ActiveWorkRecord

type ActiveWorkRecord struct {
	EntryID       string `json:"entry_id"`
	ID            string `json:"id"`
	Kind          string `json:"kind"`
	State         string `json:"state"`
	OwningSession string `json:"owning_session,omitempty"`
}

ActiveWorkRecord describes a durable task that may still require attention.

func CollectActiveWorkRecords

func CollectActiveWorkRecords(entries []database.EntryEntity) []ActiveWorkRecord

CollectActiveWorkRecords reads bounded typed task references from durable details.

type CheckpointStructureError

type CheckpointStructureError struct {
	Code    string
	Heading string
}

CheckpointStructureError reports format defects without retaining summary text.

func (*CheckpointStructureError) Error

func (err *CheckpointStructureError) Error() string

func (*CheckpointStructureError) Unwrap

func (err *CheckpointStructureError) Unwrap() error

type Chunk

type Chunk struct {
	Groups   []SemanticGroup
	Messages []database.MessageEntity
	Tokens   int
}

Chunk is a deterministic, protocol-safe summary request unit.

func Partition

func Partition(groups []SemanticGroup, availableInputTokens, maxChunks int) ([]Chunk, error)

Partition greedily packs the largest stable prefix of semantic groups.

type FileOperation

type FileOperation struct {
	EntryID string `json:"entry_id,omitempty"`
	Action  string `json:"action"`
	Path    string `json:"path"`
	Tool    string `json:"tool,omitempty"`
	Command string `json:"command,omitempty"`
}

FileOperation records file activity that should survive compaction summaries.

func CollectFileOperations

func CollectFileOperations(entries []database.EntryEntity) []FileOperation

CollectFileOperations extracts bounded, de-duplicated file operations from compacted entries.

type Operation

type Operation struct {
	ID          string
	Reason      Reason
	RetryIntent RetryIntent
}

Operation is immutable identity and policy for one logical compaction.

func (Operation) Validate

func (operation Operation) Validate() error

Validate verifies all operation contracts.

type Plan

type Plan struct {
	FirstKeptEntryID    string
	Messages            []database.MessageEntity
	PreviousSummary     string
	SplitTurnSummary    string
	SummarizedEntryIDs  []string
	KeptEntryIDs        []string
	FileOperations      []FileOperation
	ValidationRecords   []ValidationRecord
	ActiveWorkRecords   []ActiveWorkRecord
	SummaryGroups       []SemanticGroup
	TokensBefore        int
	FirstKeptEntryIndex int
}

Plan describes the history range selected for compaction and the retained tail.

func PlanBranch

func PlanBranch(
	branch []database.EntryEntity,
	recentTailTokens int,
	countTokens TokenCounter,
) (Plan, error)

PlanBranch selects model-facing branch history for compaction while preserving a recent tail.

func PlanBranchFromFirstKept

func PlanBranchFromFirstKept(
	branch []database.EntryEntity,
	firstKeptEntryID string,
	countTokens TokenCounter,
) (Plan, error)

PlanBranchFromFirstKept builds a compaction plan using an extension-selected retained tail.

type Reason

type Reason string

Reason identifies why one logical compaction operation ran.

const (
	// ReasonManual identifies user-requested compaction.
	ReasonManual Reason = "manual"
	// ReasonPreRequest identifies automatic compaction before a request.
	ReasonPreRequest Reason = "pre_request"
	// ReasonPostResponse identifies automatic compaction after a response.
	ReasonPostResponse Reason = "post_response"
	// ReasonProviderOverflow identifies recovery from provider context overflow.
	ReasonProviderOverflow Reason = "provider_overflow"
)

func (Reason) Validate

func (reason Reason) Validate() error

Validate rejects unknown reasons.

type RetryIntent

type RetryIntent string

RetryIntent describes whether a successful compaction is followed by a replacement request.

const (
	// RetryNone indicates that compaction is not followed by a replacement request.
	RetryNone RetryIntent = "none"
	// RetryAfterCompaction requests a replacement model request after compaction.
	RetryAfterCompaction RetryIntent = "retry_after_compaction"
)

func (RetryIntent) Validate

func (intent RetryIntent) Validate() error

Validate rejects unknown retry intent values.

type SemanticGroup

type SemanticGroup struct {
	Kind     SemanticGroupKind
	EntryIDs []string
	Messages []database.MessageEntity
	Tokens   int
}

SemanticGroup keeps a durable turn, including all tool results, intact.

func GroupsFromMessages

func GroupsFromMessages(messages []database.MessageEntity, entryIDs []string) []SemanticGroup

GroupsFromMessages groups model-facing history at user/custom/bash turn boundaries. Tokens use the same complete-message estimator as summary request preflight.

type SemanticGroupKind

type SemanticGroupKind string

SemanticGroupKind identifies an indivisible summary input unit.

const (
	// SemanticGroupHistoryTurn identifies an original conversation turn.
	SemanticGroupHistoryTurn SemanticGroupKind = "history_turn"
	// SemanticGroupReduction identifies a prior reduction result.
	SemanticGroupReduction SemanticGroupKind = "reduction"
)

type SummaryError

type SummaryError struct {
	Kind     error
	Cause    error
	Provider string
	Model    string
	Reason   Reason
	Input    int
	Limit    int
	Before   int
	After    int
}

SummaryError provides safe, typed summary failure context.

func (*SummaryError) Error

func (summaryError *SummaryError) Error() string

func (*SummaryError) Unwrap

func (summaryError *SummaryError) Unwrap() []error

Unwrap exposes both the stable category and an optional underlying cause.

type SummaryOutcome

type SummaryOutcome struct {
	Text                 string
	Provider             string
	Model                string
	Reason               Reason
	FinishReason         llm.FinishReason
	EstimatedInputTokens int
	ReportedInputTokens  int
	ReportedOutputTokens int
	OutputLimit          int
	Truncated            bool
}

SummaryOutcome records bounded summary generation without retaining prompt content.

type TokenCounter

type TokenCounter func(string) int

TokenCounter estimates token usage for text.

type ValidationOutcome

type ValidationOutcome string

ValidationOutcome describes the durable result of a validation command.

const (
	// ValidationPassed indicates a successful validation command.
	ValidationPassed ValidationOutcome = "passed"
	// ValidationFailed indicates an unsuccessful validation command.
	ValidationFailed ValidationOutcome = "failed"
	// ValidationCanceled indicates a canceled validation command.
	ValidationCanceled ValidationOutcome = "canceled"
	// ValidationUnknown indicates a validation command without a recognized result.
	ValidationUnknown ValidationOutcome = "unknown"
)

type ValidationRecord

type ValidationRecord struct {
	EntryID string            `json:"entry_id"`
	Command string            `json:"command"`
	Outcome ValidationOutcome `json:"outcome"`
}

ValidationRecord associates an exact validation command with its durable outcome.

func CollectValidationRecords

func CollectValidationRecords(entries []database.EntryEntity) []ValidationRecord

CollectValidationRecords extracts exact bash commands and durable outcomes, retaining the latest outcome for each exact command.