From 6c9d4467423979b5edf54562d3c6019f2ac7ab34 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 15 Aug 2026 14:12:08 +1000 Subject: [PATCH 1/2] docs: add Beads tracker guidance to CLAUDE.md --- CLAUDE.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) 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. + From 2897838e6a5ccf6577850715909fd3a0318cb1e0 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 15 Aug 2026 22:25:07 +1000 Subject: [PATCH 2/2] feat(ratelimit): add window-based stale-entry eviction EvictStale sweeps the per-key hit map and removes entries whose hits have all aged out of the sliding window, so a long-lived limiter driven on a ticker doesn't accumulate one map entry per identity for the life of the process. The package doc now states the map is unbounded until something actually calls EvictStale, rather than claiming it's bounded by a mechanism nothing yet wires up. --- internal/ratelimit/limiter.go | 44 ++++++++ internal/ratelimit/limiter_test.go | 172 +++++++++++++++++++++++++++++ 2 files changed, 216 insertions(+) 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)) + } +}