Documentation
¶
Overview ¶
Package tracker provides state change tracking for delta snapshot queries. It maintains a ring buffer of state changes with configurable size and age limits.
Index ¶
- Constants
- Variables
- func RecordFileChanges(session, root string, agents []string, before map[string]FileState, ...)
- func SnapshotDirectory(root string, opts SnapshotOptions) (map[string]FileState, error)
- func SnapshotGit(root string, opts SnapshotOptions) (map[string]FileState, error)
- type ChangeType
- type CoalescedChange
- type Conflict
- type FileChange
- type FileChangeStore
- type FileChangeType
- type FileState
- type RecordedFileChange
- type SnapshotOptions
- type StateChange
- type StateTracker
- func (t *StateTracker) All() []StateChange
- func (t *StateTracker) Clear()
- func (t *StateTracker) Coalesce() []CoalescedChange
- func (t *StateTracker) Count() int
- func (t *StateTracker) Prune()
- func (t *StateTracker) Record(change StateChange)
- func (t *StateTracker) RecordAgentOutput(session, pane, output string)
- func (t *StateTracker) RecordAgentState(session, pane, state string)
- func (t *StateTracker) RecordAlert(session, pane, alertType, message string)
- func (t *StateTracker) RecordPaneCreated(session, pane, agentType string)
- func (t *StateTracker) RecordSessionCreated(session string)
- func (t *StateTracker) Since(ts time.Time) []StateChange
- func (t *StateTracker) SinceBySession(ts time.Time, session string) []StateChange
- func (t *StateTracker) SinceByType(ts time.Time, changeType ChangeType) []StateChange
Constants ¶
const ( // CriticalConflictAgentCount is the number of agents touching a file to trigger critical severity. CriticalConflictAgentCount = 3 // CriticalConflictWindow is the time window within which multiple edits trigger critical severity. CriticalConflictWindow = 10 * time.Minute )
const DefaultMaxAge = 5 * time.Minute
DefaultMaxAge is the default maximum age of changes to retain
const DefaultMaxSize = 1000
DefaultMaxSize is the default maximum number of changes to retain
const MaxConcurrentFileRecords = 50
MaxConcurrentFileRecords limits pending RecordFileChanges goroutines to prevent unbounded growth
Variables ¶
var GlobalFileChanges = NewFileChangeStore(500)
GlobalFileChanges is the shared change store.
Functions ¶
func RecordFileChanges ¶
func RecordFileChanges(session, root string, agents []string, before map[string]FileState, delay time.Duration)
RecordFileChanges captures and stores file changes after a delay. It is best-effort and meant to attribute changes to targeted agents. Uses bounded concurrency to prevent goroutine accumulation.
func SnapshotDirectory ¶
func SnapshotDirectory(root string, opts SnapshotOptions) (map[string]FileState, error)
SnapshotDirectory walks a directory and captures file modtime/size. Returns a map keyed by absolute path.
func SnapshotGit ¶
func SnapshotGit(root string, opts SnapshotOptions) (map[string]FileState, error)
SnapshotGit uses 'git status' to efficiently find changed/untracked files. This is O(1) git operation + O(N) stat calls for *dirty files only*, compared to O(M) stat calls for *all files* with WalkDir.
Types ¶
type ChangeType ¶
type ChangeType string
ChangeType represents the type of state change
const ( ChangeAgentOutput ChangeType = "agent_output" ChangeAgentState ChangeType = "agent_state" ChangeBeadUpdate ChangeType = "bead_update" ChangeMailReceived ChangeType = "mail_received" ChangeAlert ChangeType = "alert" ChangePaneCreated ChangeType = "pane_created" ChangePaneRemoved ChangeType = "pane_removed" ChangeSessionCreated ChangeType = "session_created" ChangeSessionRemoved ChangeType = "session_removed" ChangeFileChange ChangeType = "file_change" )
type CoalescedChange ¶
type CoalescedChange struct {
Type ChangeType `json:"type"`
Session string `json:"session,omitempty"`
Pane string `json:"pane,omitempty"`
Count int `json:"count"`
FirstAt time.Time `json:"first_at"`
LastAt time.Time `json:"last_at"`
}
CoalescedChange represents multiple changes merged into one summary
type Conflict ¶
type Conflict struct {
Path string `json:"path"`
Changes []RecordedFileChange `json:"changes,omitempty"`
Severity string `json:"severity,omitempty"` // "warning", "critical"
Agents []string `json:"agents,omitempty"`
LastAt time.Time `json:"last_at,omitempty"`
}
Conflict represents a detected file conflict
func ConflictsSince ¶
ConflictsSince returns files changed by more than one agent since the timestamp.
func DetectConflicts ¶
func DetectConflicts(changes []RecordedFileChange) []Conflict
DetectConflicts analyzes a set of changes for conflicts.
func DetectConflictsRecent ¶
DetectConflictsRecent analyzes global file changes within the given window.
type FileChange ¶
type FileChange struct {
Path string `json:"path"`
Type FileChangeType `json:"type"`
Before *FileState `json:"before,omitempty"`
After *FileState `json:"after,omitempty"`
}
FileChange represents a single file change between two snapshots.
func DetectFileChanges ¶
func DetectFileChanges(before, after map[string]FileState) []FileChange
DetectFileChanges compares two snapshots and returns the delta.
type FileChangeStore ¶
type FileChangeStore struct {
// contains filtered or unexported fields
}
FileChangeStore keeps a bounded buffer of recent file changes.
func NewFileChangeStore ¶
func NewFileChangeStore(limit int) *FileChangeStore
NewFileChangeStore creates a store with the provided capacity.
func (*FileChangeStore) Add ¶
func (s *FileChangeStore) Add(entry RecordedFileChange)
Add records a change and prunes oldest entries when over capacity.
func (*FileChangeStore) All ¶
func (s *FileChangeStore) All() []RecordedFileChange
All returns a copy of all recorded changes.
func (*FileChangeStore) Since ¶
func (s *FileChangeStore) Since(ts time.Time) []RecordedFileChange
Since returns changes after the provided timestamp.
type FileChangeType ¶
type FileChangeType string
FileChangeType indicates what happened to a file.
const ( FileAdded FileChangeType = "added" FileModified FileChangeType = "modified" FileDeleted FileChangeType = "deleted" )
type FileState ¶
type FileState struct {
ModTime time.Time `json:"mod_time"`
Size int64 `json:"size"`
GitStatus string `json:"git_status,omitempty"` // ??, M, A, etc.
}
FileState captures minimal file metadata for change detection.
type RecordedFileChange ¶
type RecordedFileChange struct {
Timestamp time.Time `json:"timestamp"`
Session string `json:"session"`
Agents []string `json:"agents,omitempty"`
Change FileChange `json:"change"`
}
RecordedFileChange captures file changes with attribution metadata.
func RecordedChanges ¶
func RecordedChanges() []RecordedFileChange
RecordedChanges returns all recorded file changes.
func RecordedChangesSince ¶
func RecordedChangesSince(ts time.Time) []RecordedFileChange
RecordedChangesSince returns file changes after the provided timestamp.
type SnapshotOptions ¶
type SnapshotOptions struct {
// IgnoreHidden skips files/dirs beginning with '.'
IgnoreHidden bool
// IgnorePaths are path prefixes (absolute) to skip.
IgnorePaths []string
// IgnoreGitIgnored attempts to skip files ignored by git (best-effort).
IgnoreGitIgnored bool
}
SnapshotOptions controls how directory snapshots are taken.
func DefaultSnapshotOptions ¶
func DefaultSnapshotOptions(root string) SnapshotOptions
DefaultSnapshotOptions provides conservative defaults (skip .git and common huge dirs).
type StateChange ¶
type StateChange struct {
Timestamp time.Time `json:"timestamp"`
Type ChangeType `json:"type"`
Session string `json:"session,omitempty"`
Pane string `json:"pane,omitempty"`
Details map[string]interface{} `json:"details,omitempty"`
}
StateChange represents a single state change event
type StateTracker ¶
type StateTracker struct {
// contains filtered or unexported fields
}
StateTracker maintains a ring buffer of state changes
func NewWithConfig ¶
func NewWithConfig(maxSize int, maxAge time.Duration) *StateTracker
NewWithConfig creates a new StateTracker with custom settings
func (*StateTracker) All ¶
func (t *StateTracker) All() []StateChange
All returns all tracked changes
func (*StateTracker) Coalesce ¶
func (t *StateTracker) Coalesce() []CoalescedChange
Coalesce merges consecutive changes of the same type for the same pane into summary entries. Useful for reducing output volume.
func (*StateTracker) Count ¶
func (t *StateTracker) Count() int
Count returns the number of tracked changes
func (*StateTracker) Prune ¶
func (t *StateTracker) Prune()
Prune manually triggers pruning of old entries
func (*StateTracker) Record ¶
func (t *StateTracker) Record(change StateChange)
Record adds a new state change to the tracker
func (*StateTracker) RecordAgentOutput ¶
func (t *StateTracker) RecordAgentOutput(session, pane, output string)
RecordAgentOutput records an agent output change
func (*StateTracker) RecordAgentState ¶
func (t *StateTracker) RecordAgentState(session, pane, state string)
RecordAgentState records an agent state change (idle, active, error)
func (*StateTracker) RecordAlert ¶
func (t *StateTracker) RecordAlert(session, pane, alertType, message string)
RecordAlert records an alert
func (*StateTracker) RecordPaneCreated ¶
func (t *StateTracker) RecordPaneCreated(session, pane, agentType string)
RecordPaneCreated records a new pane
func (*StateTracker) RecordSessionCreated ¶
func (t *StateTracker) RecordSessionCreated(session string)
RecordSessionCreated records a new session
func (*StateTracker) Since ¶
func (t *StateTracker) Since(ts time.Time) []StateChange
Since returns all changes since the given timestamp
func (*StateTracker) SinceBySession ¶
func (t *StateTracker) SinceBySession(ts time.Time, session string) []StateChange
SinceBySession returns changes since the given timestamp for a specific session
func (*StateTracker) SinceByType ¶
func (t *StateTracker) SinceByType(ts time.Time, changeType ChangeType) []StateChange
SinceByType returns changes since the given timestamp, filtered by type
Source Files