Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

add db guardrails

Justin D'Souza6bc3fe317dd7
diff --git a/cli/beacon/cmd/endpoint_traces.go b/cli/beacon/cmd/endpoint_traces.go
index 6fce53d5..3998d975 100644
--- a/cli/beacon/cmd/endpoint_traces.go
+++ b/cli/beacon/cmd/endpoint_traces.go
@@ -47,6 +47,11 @@ var endpointTracesStatusCmd = &cobra.Command{
fmt.Printf("Trace store: %s\n", status.Path)
fmt.Printf("Runtime log: %s\n", logPath)
fmt.Printf("Traces: %d\nEvents: %d\nIndex rows: %d\n", status.Traces, status.Events, status.IndexRows)
+ fmt.Printf("Size: %d bytes", status.SizeBytes)
+ if status.WALBytes > 0 {
+ fmt.Printf(" (+%d bytes WAL)", status.WALBytes)
+ }
+ fmt.Println()
if status.IndexedAt != "" {
fmt.Printf("Indexed at: %s\n", status.IndexedAt)
}
diff --git a/cli/beacon/internal/endpoint/dashboard/trace_store.go b/cli/beacon/internal/endpoint/dashboard/trace_store.go
index bc92957f..7f25cee2 100644
--- a/cli/beacon/internal/endpoint/dashboard/trace_store.go
+++ b/cli/beacon/internal/endpoint/dashboard/trace_store.go
@@ -18,7 +18,12 @@ const traceStoreFile = "traces.db"
// traceStoreSchemaVersion is written to the database's user_version. The store
// is a rebuildable index over the runtime log, never a source of truth, so a
// version bump drops the tables and reindexes rather than migrating them.
-const traceStoreSchemaVersion = 2
+const traceStoreSchemaVersion = 3
+
+// Search rows are an acceleration structure, not retained evidence. Keep them
+// small and fall back to the JSONL scan for free-text queries when truncation
+// could hide a match.
+const maxTraceStoreSearchBodyBytes = 16 * 1024
type traceStore struct {
dbPath string
@@ -34,6 +39,8 @@ type traceStoreStatus struct {
Traces int `json:"traces"`
Events int `json:"events"`
IndexRows int `json:"index_rows"`
+ SizeBytes int64 `json:"size_bytes"`
+ WALBytes int64 `json:"wal_bytes,omitempty"`
IndexedAt string `json:"indexed_at,omitempty"`
}
@@ -163,7 +170,8 @@ func ensureTraceStoreSchema(db *sql.DB) error {
event_type TEXT,
tool_name TEXT,
event_number INTEGER,
- body TEXT NOT NULL
+ body TEXT NOT NULL,
+ body_truncated INTEGER NOT NULL DEFAULT 0
)`,
`CREATE INDEX IF NOT EXISTS trace_search_by_source_trace ON trace_search (source_key, source, trace_id)`,
}
@@ -217,6 +225,9 @@ func (s *traceStore) reindexDB(db *sql.DB, fingerprint string) error {
return err
}
defer tx.Rollback()
+ if err := purgeMissingTraceSources(tx); err != nil {
+ return err
+ }
for _, stmt := range []string{
`DELETE FROM trace_search WHERE source_key = ?`,
`DELETE FROM trace_events WHERE source_key = ?`,
@@ -237,7 +248,10 @@ func (s *traceStore) reindexDB(db *sql.DB, fingerprint string) error {
s.sourceKey, fingerprint, now); err != nil {
return err
}
- return tx.Commit()
+ if err := tx.Commit(); err != nil {
+ return err
+ }
+ return checkpointTraceStore(db)
}
func insertTraceAggregate(tx *sql.Tx, sourceKey string, agg *traceAggregate, now string) error {
@@ -249,8 +263,7 @@ func insertTraceAggregate(tx *sql.Tx, sourceKey string, agg *traceAggregate, now
sourceKey, agg.summary.ID, string(summaryJSON), agg.summary.UpdatedAt, now); err != nil {
return err
}
- if _, err := tx.Exec(`INSERT INTO trace_search (source_key, trace_id, source, body) VALUES (?, ?, 'trace', ?)`,
- sourceKey, agg.summary.ID, traceSummaryHaystack(agg.summary)); err != nil {
+ if err := insertTraceSearchRow(tx, sourceKey, agg.summary.ID, "", "trace", "", "", 0, traceSummaryHaystack(agg.summary)); err != nil {
return err
}
for _, event := range agg.events {
@@ -270,15 +283,25 @@ func insertTraceAggregate(tx *sql.Tx, sourceKey string, agg *traceAggregate, now
sourceKey, agg.summary.ID, event.Number, event.ID, event.Type, toolName, string(eventJSON), now); err != nil {
return err
}
- if _, err := tx.Exec(`INSERT INTO trace_search (source_key, trace_id, event_id, source, event_type, tool_name, event_number, body)
- VALUES (?, ?, ?, 'event', ?, ?, ?, ?)`,
- sourceKey, agg.summary.ID, event.ID, event.Type, toolName, event.Number, traceEventHaystack(event)); err != nil {
+ if err := insertTraceSearchRow(tx, sourceKey, agg.summary.ID, event.ID, "event", event.Type, toolName, event.Number, traceEventHaystack(event)); err != nil {
return err
}
}
return nil
}
+func insertTraceSearchRow(tx *sql.Tx, sourceKey, traceID, eventID, source, eventType, toolName string, eventNumber int, body string) error {
+ body, truncated := truncateTraceSearchBody(body)
+ truncatedInt := 0
+ if truncated {
+ truncatedInt = 1
+ }
+ _, err := tx.Exec(`INSERT INTO trace_search (source_key, trace_id, event_id, source, event_type, tool_name, event_number, body, body_truncated)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+ sourceKey, traceID, eventID, source, eventType, toolName, eventNumber, body, truncatedInt)
+ return err
+}
+
func (s *traceStore) Status() (traceStoreStatus, error) {
if err := s.ensureCurrent(); err != nil {
return traceStoreStatus{}, err
@@ -288,7 +311,7 @@ func (s *traceStore) Status() (traceStoreStatus, error) {
return traceStoreStatus{}, err
}
defer db.Close()
- status := traceStoreStatus{Path: s.dbPath}
+ status := traceStoreStatus{Path: s.dbPath, SizeBytes: fileSize(s.dbPath), WALBytes: fileSize(s.dbPath + "-wal")}
_ = db.QueryRow(`SELECT COUNT(*) FROM traces WHERE source_key = ?`, s.sourceKey).Scan(&status.Traces)
_ = db.QueryRow(`SELECT COUNT(*) FROM trace_events WHERE source_key = ?`, s.sourceKey).Scan(&status.Events)
_ = db.QueryRow(`SELECT COUNT(*) FROM trace_search WHERE source_key = ?`, s.sourceKey).Scan(&status.IndexRows)
@@ -522,6 +545,11 @@ func (s *traceStore) matchingTraceIDs(q string, kinds ...string) (map[string]boo
return nil, err
}
defer db.Close()
+ if truncated, err := s.hasTruncatedSearchRows(db, kinds...); err != nil {
+ return nil, err
+ } else if truncated {
+ return nil, errTraceStoreUnsupported
+ }
args := []any{s.sourceKey}
for _, kind := range kinds {
args = append(args, kind)
@@ -650,6 +678,84 @@ func traceLogFingerprint(logPath string) string {
return strings.Join(parts, "|")
}
+func purgeMissingTraceSources(tx *sql.Tx) error {
+ rows, err := tx.Query(`SELECT source_key FROM trace_index_state`)
+ if err != nil {
+ return err
+ }
+ var missing []string
+ for rows.Next() {
+ var source string
+ if err := rows.Scan(&source); err != nil {
+ rows.Close()
+ return err
+ }
+ if _, err := os.Stat(source); os.IsNotExist(err) {
+ missing = append(missing, source)
+ }
+ }
+ if err := rows.Close(); err != nil {
+ return err
+ }
+ if err := rows.Err(); err != nil {
+ return err
+ }
+ for _, source := range missing {
+ for _, stmt := range []string{
+ `DELETE FROM trace_search WHERE source_key = ?`,
+ `DELETE FROM trace_events WHERE source_key = ?`,
+ `DELETE FROM traces WHERE source_key = ?`,
+ `DELETE FROM trace_index_state WHERE source_key = ?`,
+ } {
+ if _, err := tx.Exec(stmt, source); err != nil {
+ return err
+ }
+ }
+ }
+ return nil
+}
+
+func checkpointTraceStore(db *sql.DB) error {
+ _, err := db.Exec(`PRAGMA wal_checkpoint(TRUNCATE)`)
+ return err
+}
+
+func fileSize(path string) int64 {
+ info, err := os.Stat(path)
+ if err != nil {
+ return 0
+ }
+ return info.Size()
+}
+
+func truncateTraceSearchBody(body string) (string, bool) {
+ if len(body) <= maxTraceStoreSearchBodyBytes {
+ return body, false
+ }
+ used := 0
+ for i, r := range body {
+ next := used + len(string(r))
+ if next > maxTraceStoreSearchBodyBytes {
+ return body[:i], true
+ }
+ used = next
+ }
+ return body, false
+}
+
+func (s *traceStore) hasTruncatedSearchRows(db *sql.DB, kinds ...string) (bool, error) {
+ if len(kinds) == 0 {
+ return false, nil
+ }
+ args := []any{s.sourceKey}
+ for _, kind := range kinds {
+ args = append(args, kind)
+ }
+ var count int
+ err := db.QueryRow(`SELECT COUNT(*) FROM trace_search WHERE source_key = ? AND source IN (`+placeholders(len(kinds))+`) AND body_truncated = 1`, args...).Scan(&count)
+ return count > 0, err
+}
+
// placeholders builds an n-wide SQL "?,?,..." list.
func placeholders(n int) string {
if n <= 0 {
diff --git a/cli/beacon/internal/endpoint/dashboard/traces_test.go b/cli/beacon/internal/endpoint/dashboard/traces_test.go
index 5dad11a2..03049a6a 100644
--- a/cli/beacon/internal/endpoint/dashboard/traces_test.go
+++ b/cli/beacon/internal/endpoint/dashboard/traces_test.go
@@ -402,6 +402,9 @@ func TestTraceStoreIndexesAndRefreshesRuntimeLog(t *testing.T) {
if status.Traces != 1 || status.Events != 2 || status.IndexRows != 3 {
t.Fatalf("status = %#v, want 1 trace, 2 events, 3 index rows", status)
}
+ if status.SizeBytes == 0 {
+ t.Fatalf("status size = %#v, want a non-empty trace store", status)
+ }
results, err := SearchTraces(path, TraceQuery{EventQuery: EventQuery{Q: "dashboard"}, ResultLevel: "event", Limit: 10})
if err != nil {
@@ -426,6 +429,43 @@ func TestTraceStoreIndexesAndRefreshesRuntimeLog(t *testing.T) {
}
}
+func TestTraceStoreTruncatesSearchRowsAndFallsBackForExactSearch(t *testing.T) {
+ needle := "needle-after-index-cap"
+ prompt := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")
+ prompt.Event.ID = "evt-prompt"
+ prompt.Session = &schema.SessionInfo{ID: "s1"}
+ prompt.Prompt = &schema.PromptInfo{Text: strings.Repeat("a", maxTraceStoreSearchBodyBytes+1024) + needle}
+ path := traceStoreIndexedLog(t, marshalEvents(t, prompt))
+ if _, err := TraceStoreStatus(path); err != nil {
+ t.Fatalf("TraceStoreStatus returned error: %v", err)
+ }
+
+ db, err := openTraceStore(path).db()
+ if err != nil {
+ t.Fatalf("open trace store: %v", err)
+ }
+ defer db.Close()
+ var maxBodyLen int
+ var truncatedRows int
+ if err := db.QueryRow(`SELECT MAX(length(body)), SUM(body_truncated) FROM trace_search WHERE source_key = ?`, traceSourceKey(path)).Scan(&maxBodyLen, &truncatedRows); err != nil {
+ t.Fatalf("query trace search rows: %v", err)
+ }
+ if maxBodyLen > maxTraceStoreSearchBodyBytes {
+ t.Fatalf("indexed search body length = %d, want <= %d", maxBodyLen, maxTraceStoreSearchBodyBytes)
+ }
+ if truncatedRows == 0 {
+ t.Fatalf("truncated rows = 0, want at least one capped search row")
+ }
+
+ list, err := ReadTraceList(path, TraceQuery{EventQuery: EventQuery{Q: needle}, Limit: 10})
+ if err != nil {
+ t.Fatalf("ReadTraceList returned error: %v", err)
+ }
+ if list.TotalMatched != 1 {
+ t.Fatalf("ReadTraceList matched %d traces, want fallback to find the truncated term", list.TotalMatched)
+ }
+}
+
// traceStoreBlockedLog copies the given log lines into a directory where the
// trace store cannot be opened (a directory sits where traces.db would go), so
// a query against the returned path exercises the JSONL fallback.
@@ -597,6 +637,47 @@ func TestTraceStoreScopesTracesBySourceLog(t *testing.T) {
}
}
+func TestTraceStorePurgesMissingSourceLogs(t *testing.T) {
+ dir := filepath.Join(t.TempDir(), "logs")
+ if err := os.MkdirAll(dir, 0700); err != nil {
+ t.Fatalf("mkdir log dir: %v", err)
+ }
+ first := filepath.Join(dir, "runtime.jsonl")
+ second := filepath.Join(dir, "old-runtime.jsonl")
+ event := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")
+ event.Event.ID = "evt-prompt"
+ event.Session = &schema.SessionInfo{ID: "s1"}
+ event.Prompt = &schema.PromptInfo{Text: "purge stale source"}
+ writeTestLog(t, first, marshalEvents(t, event)...)
+ writeTestLog(t, second, marshalEvents(t, event)...)
+
+ if _, err := TraceStoreStatus(first); err != nil {
+ t.Fatalf("index first source: %v", err)
+ }
+ if _, err := TraceStoreStatus(second); err != nil {
+ t.Fatalf("index second source: %v", err)
+ }
+ if err := os.Remove(second); err != nil {
+ t.Fatalf("remove second source: %v", err)
+ }
+ if err := ReindexTraceStore(first); err != nil {
+ t.Fatalf("reindex first source: %v", err)
+ }
+
+ db, err := openTraceStore(first).db()
+ if err != nil {
+ t.Fatalf("open trace store: %v", err)
+ }
+ defer db.Close()
+ var sources int
+ if err := db.QueryRow(`SELECT COUNT(*) FROM trace_index_state`).Scan(&sources); err != nil {
+ t.Fatalf("count sources: %v", err)
+ }
+ if sources != 1 {
+ t.Fatalf("indexed sources = %d, want stale source purged", sources)
+ }
+}
+
// A relative and an absolute path to one log are one source, not two.
func TestTraceStoreTreatsEquivalentLogPathsAsOneSource(t *testing.T) {
path := traceStoreIndexedLog(t, marshalEvents(t, func() schema.Event {