diff --git a/CLAUDE.md b/CLAUDE.md index a7c78c4f7..c4d228d26 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -539,3 +539,60 @@ plus `in-progress` for active work. *Claude-specific:* project memory lives in `~/.claude/projects/-work-apps-archie-core/memory/`. Other harnesses should use their own equivalent — nothing in this repo depends on it. + + + +## Beads Issue Tracker + +This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # Complete work +``` + +### Rules + +- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists +- Run `bd prime` for detailed command reference and session close protocol +- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns. + +## Agent Context Profiles + +The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. + +- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. +- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. +- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. + +## Session Completion + +This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. + +1. **File issues for remaining work** - Create beads for anything that needs follow-up +2. **Run quality gates** (if code changed) - Tests, linters, builds +3. **Update issue status** - Close finished work, update in-progress items +4. **Handle git/sync by active profile**: + ```bash + # Conservative/minimal/default: report status and proposed commands; wait for approval. + git status + + # Team-maintainer opt-in only, unless current instructions forbid it: + git pull --rebase + bd dolt push + git push + git status + ``` +5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step + +**Critical rules:** +- Explicit user or orchestrator instructions override this Beads block. +- Do not commit or push without clear authority from the active profile or the current user request. +- If a required sync or push is blocked, stop and report the exact command and error. + diff --git a/internal/ratelimit/limiter.go b/internal/ratelimit/limiter.go index 4c37b6b05..32b566548 100644 --- a/internal/ratelimit/limiter.go +++ b/internal/ratelimit/limiter.go @@ -1,6 +1,11 @@ // Package ratelimit provides a sliding-window request limiter, keyed by // platform and user, for gating inbound gateway traffic per identity // rather than globally. +// +// A limiter's per-key map is unbounded until something calls EvictStale: +// long-lived instances should have it driven on a ticker so entries whose +// hits have all aged out of the window are removed instead of accumulating +// for the life of the process. package ratelimit import ( @@ -67,3 +72,42 @@ func (l *Limiter) Allow(platform, userID string) bool { l.hits[key] = append(live, now) return true } + +// EvictStale removes per-key entries whose hits have all aged out of the +// sliding window — an entry with no hit strictly within the last window is +// deleted, and entries that hold no hits at all (possible when maxRequests +// is zero) are always removed. It reports how many entries were removed. +// +// Eviction is behaviour-preserving by construction: the cutoff is Allow's +// own pruning cutoff (now - window), so a removed key would have +// contributed zero hits to its next Allow, which would lazily recreate it +// — sweeping can never grant fresh budget. +// +// The limiter runs no background sweeper; a long-lived limiter should have +// EvictStale driven on a ticker (e.g. once per window), as the daemon +// drives storage expiry. +func (l *Limiter) EvictStale() int { + l.mu.Lock() + defer l.mu.Unlock() + + cutoff := l.now().Add(-l.window) + evicted := 0 + for key, hits := range l.hits { + if !hasHitAfter(hits, cutoff) { + delete(l.hits, key) + evicted++ + } + } + return evicted +} + +// hasHitAfter reports whether any recorded hit is strictly after cutoff, +// mirroring the pruning predicate Allow applies to each key's hit log. +func hasHitAfter(hits []time.Time, cutoff time.Time) bool { + for _, h := range hits { + if h.After(cutoff) { + return true + } + } + return false +} diff --git a/internal/ratelimit/limiter_test.go b/internal/ratelimit/limiter_test.go index dbe3fcdd2..e85f1db3c 100644 --- a/internal/ratelimit/limiter_test.go +++ b/internal/ratelimit/limiter_test.go @@ -207,3 +207,175 @@ func TestLimiterConcurrentDifferentKeysNoCrossTalk(t *testing.T) { t.Errorf("allowed = %d, want %d (each user has an independent budget)", allowed, n) } } + +func TestEvictStaleRemovesIdleEntries(t *testing.T) { + l, clock := newTestLimiter(time.Minute, 3) + if !l.Allow("telegram", "user1") { + t.Fatal("1st request should be allowed") + } + + // The single hit is now two windows old; a sweep must drop the entry. + clock.Advance(2 * time.Minute) + if got := l.EvictStale(); got != 1 { + t.Fatalf("EvictStale() = %d, want 1", got) + } + if len(l.hits) != 0 { + t.Errorf("hits map has %d entries after sweep, want 0", len(l.hits)) + } +} + +func TestEvictStaleKeepsRecentEntries(t *testing.T) { + l, clock := newTestLimiter(time.Minute, 2) + if !l.Allow("telegram", "user1") { + t.Fatal("user1 1st request should be allowed") + } + clock.Advance(30 * time.Second) + if !l.Allow("telegram", "user2") { + t.Fatal("user2 1st request should be allowed") + } + + // Sweep 80s in: user1's hit (t=0) has aged out; user2's (t=30s) is + // still inside the one-minute window. + clock.Advance(50 * time.Second) + if got := l.EvictStale(); got != 1 { + t.Fatalf("EvictStale() = %d, want 1", got) + } + if _, ok := l.hits[limiterKey{platform: "telegram", userID: "user1"}]; ok { + t.Error("user1 entry should have been evicted") + } + if _, ok := l.hits[limiterKey{platform: "telegram", userID: "user2"}]; !ok { + t.Error("user2 entry should have been kept") + } +} + +func TestEvictStaleBoundaryIsWindowCutoff(t *testing.T) { + // EvictStale's cutoff is Allow's own pruning cutoff (now - window): + // a hit exactly one window ago is stale, one nanosecond inside is not. + tests := []struct { + name string + advance time.Duration + want int + }{ + {"hit well inside window is kept", 30 * time.Second, 0}, + {"hit one nanosecond inside window is kept", time.Minute - time.Nanosecond, 0}, + {"hit exactly one window ago is stale", time.Minute, 1}, + {"hit well past the window is stale", 2 * time.Minute, 1}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + l, clock := newTestLimiter(time.Minute, 2) + if !l.Allow("telegram", "user1") { + t.Fatal("1st request should be allowed") + } + clock.Advance(tt.advance) + if got := l.EvictStale(); got != tt.want { + t.Errorf("EvictStale() = %d, want %d", got, tt.want) + } + }) + } +} + +func TestEvictStalePreservesAllowOutcome(t *testing.T) { + // A sweep must never change what Allow would have decided: it only + // removes keys whose hits would have been pruned anyway, so an + // in-window key stays at its budget and an aged-out key gets a fresh + // one either way. + t.Run("in-window key stays blocked", func(t *testing.T) { + l, clock := newTestLimiter(time.Minute, 1) + if !l.Allow("telegram", "user1") { + t.Fatal("1st request should be allowed") + } + clock.Advance(61 * time.Second) + if !l.Allow("telegram", "user1") { + t.Fatal("2nd request after the 1st hit aged out should be allowed") + } + clock.Advance(31 * time.Second) // t=92s; the t=61s hit is still in-window + if got := l.EvictStale(); got != 0 { + t.Fatalf("EvictStale() = %d, want 0 (hit still in window)", got) + } + if l.Allow("telegram", "user1") { + t.Error("in-window key must remain blocked after a sweep") + } + }) + + t.Run("aged-out key gets fresh budget either way", func(t *testing.T) { + l, clock := newTestLimiter(time.Minute, 1) + if !l.Allow("telegram", "user1") { + t.Fatal("1st request should be allowed") + } + clock.Advance(2 * time.Minute) + if got := l.EvictStale(); got != 1 { + t.Fatalf("EvictStale() = %d, want 1 (hit aged out)", got) + } + if !l.Allow("telegram", "user1") { + t.Error("aged-out key should get a fresh budget after the sweep") + } + }) +} + +func TestEvictStaleRemovesEmptySliceEntries(t *testing.T) { + // max=0 stores an empty slice on every block; such an entry holds no + // hits at all and must be removed by any sweep. + l, _ := newTestLimiter(time.Minute, 0) + if l.Allow("telegram", "user1") { + t.Fatal("max=0 should block the request") + } + if got := l.EvictStale(); got != 1 { + t.Fatalf("EvictStale() = %d, want 1 (empty-slice entry)", got) + } +} + +func TestEvictStaleRemovesNothingWhileHitsFresh(t *testing.T) { + l, _ := newTestLimiter(time.Minute, 1) + if !l.Allow("telegram", "user1") { + t.Fatal("user1 1st request should be allowed") + } + if !l.Allow("telegram", "user2") { + t.Fatal("user2 1st request should be allowed") + } + // All hits are within the window: a sweep removes nothing. + if got := l.EvictStale(); got != 0 { + t.Fatalf("EvictStale() = %d, want 0 (all hits fresh)", got) + } + if len(l.hits) != 2 { + t.Errorf("hits map has %d entries, want 2", len(l.hits)) + } +} + +func TestEvictStaleEmptyMap(t *testing.T) { + l, _ := newTestLimiter(time.Minute, 1) + if got := l.EvictStale(); got != 0 { + t.Errorf("EvictStale() on an empty limiter = %d, want 0", got) + } +} + +func TestEvictStaleConcurrentWithAllow(t *testing.T) { + l, clock := newTestLimiter(time.Minute, 1000) + + const staleKeys = 20 + for i := range staleKeys { + if !l.Allow("telegram", fmt.Sprintf("stale%d", i)) { + t.Fatalf("seed request for stale%d should be allowed", i) + } + } + // Age the seed hits out of the window so the sweep actually has entries + // to delete while Allow races to keep a separate key fresh (the suite + // runs with -race). The clock stays frozen for the rest of the test, so + // the stale keys can never become live again and a correct EvictStale + // must remove all of them by the time the race settles. + clock.Advance(2 * time.Minute) + + var wg sync.WaitGroup + for range 50 { + wg.Go(func() { _ = l.Allow("telegram", "fresh") }) + wg.Go(func() { _ = l.EvictStale() }) + } + wg.Wait() + + if _, ok := l.hits[limiterKey{platform: "telegram", userID: "fresh"}]; !ok { + t.Error("fresh key evicted despite concurrent Allow keeping it live") + } + if len(l.hits) != 1 { + t.Errorf("hits map has %d entries, want 1 (only the fresh key); stale entries were not evicted", len(l.hits)) + } +}