Documentation
¶
Overview ¶
Package speculative — read cache + prefetcher for §8.5 Phase 5 speculative tool execution.
The idea: when the agent reads foo.go, it's overwhelmingly likely to read foo_test.go, neighbors in the same package, or files referenced from foo.go next. Cache the read, and async-prefetch the likely-next files so they're warm by the time the agent asks.
Design:
- ReadCache is a TTL + LRU cache keyed by absolute path. Each entry stores bytes + the file's mtime at read time so a stale-on-disk lookup invalidates the entry.
- Prefetcher is a small worker pool that runs heuristic-driven reads in the background. Empty by default — the wiring layer installs heuristics (sibling, test-pair, package-neighbor).
- Telemetry: HitRate / TotalReads exposed so the operator can check whether prefetching is actually working.
What this is NOT: a transparent FS layer. Tools that want the cache call Get/Put explicitly. The intent is to wrap the agent's file-read tool, not to intercept every os.Open.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DocHeuristic ¶
DocHeuristic suggests README / CHANGELOG / doc files in the same directory tree when the agent reads a code file. Useful for "agent's about to make a change; remind it of the docs".
func PackageNeighborHeuristic ¶
PackageNeighborHeuristic suggests other files in the same dir with the same extension — typical "this module has 4 files, agent will probably read at least one more" pattern. Capped at the first 5 alphabetical neighbors to avoid prefetching huge directories.
func ReadAndCache ¶
ReadAndCache reads the file from disk and stores it in the cache. Returns the bytes + the mtime that was stored. Useful as the canonical "miss path" — wrap your file-read tool so cache misses always populate the cache for next time.
func TestPairHeuristic ¶
TestPairHeuristic suggests the test file for a code file (and vice versa) based on common naming conventions across Go, Python, TypeScript, Rust. Only suggests paths that exist on disk.
Types ¶
type HeuristicFn ¶
HeuristicFn returns the list of paths to prefetch when the agent just read `path`. Return order doesn't matter — the prefetcher processes them via its worker pool.
func CombineHeuristics ¶
func CombineHeuristics(fns ...HeuristicFn) HeuristicFn
CombineHeuristics chains multiple heuristics; dedupes by path so a sibling that's also a test-pair doesn't get queued twice.
type Options ¶
type Options struct {
// MaxBytes caps the total stored size. Eviction is LRU. Default
// 32MB.
MaxBytes int64
// TTL after which an entry is considered stale even if its
// mtime hasn't changed. Default 5 minutes. Set to 0 for no TTL
// (mtime check only).
TTL time.Duration
}
Options configures the cache.
type Prefetcher ¶
type Prefetcher struct {
// contains filtered or unexported fields
}
Prefetcher runs a worker pool that fires async reads through a ReadCache. Heuristics decide what to prefetch; the cache decides what to keep.
func NewPrefetcher ¶
func NewPrefetcher(cache *ReadCache, workers, queueDepth int) *Prefetcher
NewPrefetcher wires a prefetcher to a cache. workers caps the concurrency; queueDepth bounds the in-flight prefetch backlog. Sane defaults: 2 workers, 64-deep queue.
func (*Prefetcher) Drain ¶
func (p *Prefetcher) Drain(ctx context.Context) error
Drain waits for the prefetch queue to empty. Used in tests so assertions don't race the worker pool.
func (*Prefetcher) Enqueue ¶
func (p *Prefetcher) Enqueue(path string) bool
Enqueue adds a path to the prefetch backlog. Non-blocking — a full queue drops the request rather than gating the caller. Returns true when accepted, false when dropped.
func (*Prefetcher) EnqueueAll ¶
func (p *Prefetcher) EnqueueAll(paths []string) int
EnqueueAll fires Enqueue for each path. Returns the count accepted; the rest were dropped due to a full queue.
func (*Prefetcher) Start ¶
func (p *Prefetcher) Start(workers int)
Start spins up the worker goroutines. Idempotent — second call is a no-op. The caller's ctx (in Stop) determines lifetime.
func (*Prefetcher) Stop ¶
func (p *Prefetcher) Stop()
Stop signals workers to exit and waits for them. Idempotent.
type ReadCache ¶
type ReadCache struct {
// contains filtered or unexported fields
}
ReadCache is a TTL + LRU cache. Concurrent-safe.
func NewReadCache ¶
func (*ReadCache) Clear ¶
func (c *ReadCache) Clear()
Clear empties the cache. Telemetry counters retained.
func (*ReadCache) Get ¶
Get returns cached bytes for path when present AND fresh. Fresh = (a) within TTL AND (b) file mtime matches the stored mtime. On miss returns (nil, false).
Source Files