beads/cmd/bd/memory_budget_pure_test.go
Bee 1ea5145092
feat(remember): opt-in memories.budget-chars — warn at 80%, refuse a write that crosses the corpus budget (--force overrides) (#6508)
* feat(remember): opt-in memories.budget-chars — refuse a write that crosses the corpus budget (wy-2pox7y)

The wheelhouse-side tripwire only REPORTS the memory-corpus size, so the corpus
re-trips red every few days and nothing has ever stopped the write that crossed
the line. This is the stop.

New config key `memories.budget-chars` (integer, default 0 = OFF), wired exactly
like `prime.max-memory-chars`: recognized in cmd/bd/config.go, routed to yaml in
internal/config YamlOnlyKeys (it is read through viper, so a DB-backed write
would be accepted and then never read), validated non-negative at set time, and
documented in docs/reference/configuration.md.

With the budget ON, `bd remember` measures the corpus as the sum over every
memory of len(key)+len(content) — BYTES, the same unit `bd prime`'s
--max-memory-chars counts in — projected to AFTER the write would apply. An
overwrite replaces that key's old content in the sum rather than adding to it,
so a memory near the ceiling can still be edited.

  - over budget            -> refused, nothing written, exit 1, one line on stderr
  - over budget + --force  -> written, and the crossing is still announced
  - >= 80% and within      -> written, then warned
  - below 80%, or budget 0 -> silent; with the budget off the corpus is not even
                              read, so behavior is byte-identical to before

Every line goes to STDERR, so --json output is never corrupted; a --json refusal
additionally gets the normal machine-readable error object on stdout.

The whole decision is one pure function (rememberBudgetVerdict), which is what
lets the branches be pinned without a database.

Tests run (targeted, never ./...):
  go build ./...                                             rc 0
  go vet ./cmd/bd/ ./internal/config/                        rc 0
  go test ./cmd/bd/ -run 'Memor|Remember|Prime|Budget' -count=1   rc 0
  go test ./internal/config/ -count=1                        rc 0
  BEADS_TEST_EMBEDDED_DOLT=1 go test ./cmd/bd/ \
      -run TestEmbeddedMemoryCorpusBudget -count=1 -v        rc 0 (6/6 subtests)
  golangci-lint run --config=.golangci.yml --build-tags=gms_pure_go \
      ./cmd/bd/... ./internal/config/...                     0 issues in touched
                                                             files (one
                                                             pre-existing gosec
                                                             G304 in
                                                             internal/config/permissions_open_nonlinux.go)

New tests: cmd/bd/memory_budget_pure_test.go (byte unit incl. multibyte,
overwrite delta, budget-off silence, config read + negative clamp, the
at-budget/one-over boundary, --force, the 80% warn band and its edges,
unclamped percentage, single-line contract);
cmd/bd/memory_embedded_test.go TestEmbeddedMemoryCorpusBudget (the same five
spec points end to end against a real embedded-Dolt store, through
`bd config set`, asserting the exact stderr lines, the nonzero exit, and that a
refused write leaves the old content intact);
internal/config/yaml_config_test.go validation + yaml-only routing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013XmKxqKuXTaKivDiCoBwBV

* fix(remember): one --json refusal line, ceil on the over-budget percentage (wy-2pox7y)

Review fixes on ca9f14d65d. Three items; one review item turned out to be a
false alarm and is recorded here rather than acted on.

- BLOCKER 1 (CLI docs regeneration) — NO CHANGE NEEDED, and that is the
  finding. docs/cli-reference/ and docs/CLI_REFERENCE.md are not generated
  from this checkout: docs/cli-docs.pin pins them to release tag v1.2.2, and
  scripts/generate-cli-docs.sh, check-cli-docs-drift.sh and check-doc-flags.sh
  all resolve that pin (resolve-docs-bd.sh) and build bd from the TAG, because
  the published docs site describes the latest release, not main's source. No
  CI path sets BD_DOCS_IGNORE_PIN. So changing `bd remember`'s help surface on
  main cannot move the generated docs, and it did not:
  ./scripts/generate-cli-docs.sh ran to completion ("Generated CLI docs from:
  bd version 1.2.2 (dev)") and left the tree clean — zero diff. The gate is
  green at this commit and was green at ca9f14d65d. The --force flag and the
  Corpus budget paragraph reach the docs when the pin is bumped at release.

- NIT 1: the --json refusal said the same sentence twice, prose on stderr AND
  the envelope on stdout. It now says it ONCE, the way
  HandleErrorWithHintRespectJSON does it: --json gets only the stdout
  envelope, every other route gets the bare sentence on stderr. New subtest
  TestEmbeddedMemoryCorpusBudget/json_refusal_is_said_once asserts a nonzero
  exit, EXACTLY one JSON document on stdout (a second Decode must be io.EOF),
  the refusal sentence inside the envelope, a stderr with no "memory corpus"
  in it, and that the refused write left the old content intact.

- NIT 2: floor arithmetic made the refusal at 201 of 200 read "(100%)" — the
  exactly-at-budget value this code deliberately ALLOWS, so the refusal wore
  the number of the case it is not. The percentage now CEILINGS over the
  budget (101%) and still FLOORS within it. The split is on the VALUE, not on
  --force, so one projection cannot report two different percentages
  depending on a flag; that is why the forced over-budget line moved too.
  TestRememberBudgetVerdictBoundary, TestRememberBudgetVerdictForceWrites and
  TestMemoryBudgetLinePercentIsUnclamped updated; the warn band gains a
  999-of-1000 case pinning the floor inside the budget, so "100%" can only
  ever mean at-budget.

- NIT 5: one comment at the List/Remember seam saying the budget is ADVISORY
  and not atomic — the two are separate transactions, so concurrent writers
  can both measure inside the budget and both land. No locking.

Nits 3 (primeConfigInt duplication) and 4 were left alone by instruction.

Gates run from the worktree:
  go build ./...                                                      rc 0
  go vet ./cmd/bd/ ./internal/config/                                 rc 0
  go test ./cmd/bd/ -run 'Memor|Remember|Prime|Budget' -count=1       rc 0
  go test ./internal/config/ -count=1                                 rc 0
  BEADS_TEST_EMBEDDED_DOLT=1 go test ./cmd/bd/ \
      -run TestEmbeddedMemoryCorpusBudget -count=1 -v                 rc 0 (7/7)
  gofmt -l cmd/bd internal/config                                     no output
  golangci-lint run ./cmd/bd/ ./internal/config/                      1 issue, all
      pre-existing: gosec G304 in internal/config/permissions_open_nonlinux.go
      (last touched f4d496fed, not by this branch)
  ./scripts/check-cli-docs-drift.sh                                   rc 0
  ./scripts/check-doc-flags.sh                                        rc 0

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JFSKdUYCTyuhBM97tHyoye

* ci: list the PR's tests in the embedded shard manifest and cmd/bd BUILD.bazel

#7156 made the embedded-Dolt shard manifests exact-once, and Bazel equivalence
requires every test file in the go_test srcs. Adds TestEmbeddedMemoryCorpusBudget
(generator output, incremental) and memory_budget_pure_test.go (the line CI's
bazel-sync patch printed).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(remember): budget the key ResolveKey writes; hint on stderr too

Review fixes for #6508 (apply-fixes iteration 1; all minor or nit):

- The budget credits an overwrite under memoryapi.ResolveKey's key, the
  one rule every Remember implementation writes under, instead of a
  parallel flag-else-derived copy of it. A write ResolveKey refuses
  skips the budget, so a whitespace-only --key gets the role's "memory
  key must not be empty" instead of an over-budget refusal that points
  at --force.
- The stderr refusal now carries the same hint as the --json envelope
  (raise the budget, forget a memory, or --force), printed the way
  HandleErrorWithHintRespectJSON prints one.
- The memoryCorpusChars comment and `bd remember --help` no longer
  imply that a budget equal to prime.max-memory-chars keeps prime from
  eliding memories: the unit (bytes) is the same, but prime counts each
  memory as rendered, markup included, so the budget has to sit below
  that cap for that.
- New embedded pins: a write without --key that crosses the budget is
  refused with exit 1 and writes nothing; a blank --key gets the
  validation error; the Hint line is on stderr and not under --json.
  Each pin was checked red against a mutant of the code it guards.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
2026-10-06 23:04:06 +00:00

258 lines
10 KiB
Go

// Pure-Go tests for the `bd remember` corpus budget (memories.budget-chars).
// No cgo / Dolt dependency, so this file carries no build tag and compiles
// under CGO_ENABLED=0 with gms_pure_go, exactly like memory_pure_test.go.
//
// The whole budget decision lives in one pure function (rememberBudgetVerdict),
// so every branch the knob has — off, boundary, overwrite delta, --force, the
// 80% warn — is pinned here without a database. The end-to-end plumbing (the
// stderr routing and the nonzero exit) is pinned against a real store by
// TestEmbeddedMemoryCorpusBudget in memory_embedded_test.go.
package main
import (
"fmt"
"strings"
"testing"
)
// budgetCorpus builds a corpus whose measured size is exactly want bytes,
// under a single key. len(key)+len(content) is the unit the budget counts in,
// so the content is padded to want-len(key).
func budgetCorpus(t *testing.T, key string, want int) map[string]string {
t.Helper()
if want < len(key) {
t.Fatalf("corpus of %d bytes cannot hold key %q (%d bytes)", want, key, len(key))
}
corpus := map[string]string{key: strings.Repeat("x", want-len(key))}
if got := memoryCorpusChars(corpus); got != want {
t.Fatalf("corpus fixture measured %d bytes, want %d", got, want)
}
return corpus
}
// TestMemoryCorpusCharsCountsKeyAndContentBytes pins the UNIT: bytes of
// len(key)+len(content), the same unit prime's --max-memory-chars counts in.
// A rune-counting implementation would disagree on any non-ASCII memory, which
// is why the multibyte case is here.
func TestMemoryCorpusCharsCountsKeyAndContentBytes(t *testing.T) {
if got := memoryCorpusChars(nil); got != 0 {
t.Fatalf("empty corpus = %d, want 0", got)
}
corpus := map[string]string{"ab": "cde", "f": "gh"}
if got, want := memoryCorpusChars(corpus), 2+3+1+2; got != want {
t.Fatalf("corpus = %d, want %d", got, want)
}
// "é" is two bytes; the budget must see two.
if got, want := memoryCorpusChars(map[string]string{"k": "é"}), 3; got != want {
t.Fatalf("multibyte corpus = %d, want %d (bytes, not runes)", got, want)
}
}
// TestProjectedMemoryCorpusCharsOverwriteCountsDelta is spec point (c): an
// overwrite REPLACES the key's old content in the sum instead of adding to it.
// Without this, editing one memory down to nothing would still read as growth
// and a corpus at its ceiling could never be repaired.
func TestProjectedMemoryCorpusCharsOverwriteCountsDelta(t *testing.T) {
existing := map[string]string{"k": "aaaa", "other": "bb"} // 1+4 + 5+2 = 12
// New key: pure addition.
if got, want := projectedMemoryCorpusChars(existing, "new", "xyz"), 12+3+3; got != want {
t.Errorf("new key projection = %d, want %d", got, want)
}
// Overwrite with longer content: only the delta lands.
if got, want := projectedMemoryCorpusChars(existing, "k", "aaaaaa"), 12+2; got != want {
t.Errorf("growing overwrite projection = %d, want %d", got, want)
}
// Overwrite with shorter content: the corpus SHRINKS.
if got, want := projectedMemoryCorpusChars(existing, "k", "a"), 12-3; got != want {
t.Errorf("shrinking overwrite projection = %d, want %d", got, want)
}
// Identical rewrite: no change at all.
if got, want := projectedMemoryCorpusChars(existing, "k", "aaaa"), 12; got != want {
t.Errorf("identical overwrite projection = %d, want %d", got, want)
}
// A key whose stored value is empty still has its key counted once, not twice.
empty := map[string]string{"k": ""}
if got, want := projectedMemoryCorpusChars(empty, "k", "zz"), 3; got != want {
t.Errorf("empty-valued overwrite projection = %d, want %d", got, want)
}
}
// TestRememberBudgetVerdictOffIsSilent is spec point (a): with the budget unset
// (or 0, or a nonsense negative) nothing is ever refused and nothing is ever
// printed, no matter how large the corpus is.
func TestRememberBudgetVerdictOffIsSilent(t *testing.T) {
huge := budgetCorpus(t, "k", 1_000_000)
for _, budget := range []int{0, -1, -1000} {
for _, force := range []bool{false, true} {
line, refuse := rememberBudgetVerdict(huge, "new", strings.Repeat("y", 5000), budget, force)
if refuse || line != "" {
t.Fatalf("budget=%d force=%v: budget-off must be silent, got refuse=%v line=%q", budget, force, refuse, line)
}
}
}
}
// TestMemoryCorpusBudgetReadsConfig pins the config read, including the clamp
// that keeps a negative value meaning OFF rather than "refuse everything".
func TestMemoryCorpusBudgetReadsConfig(t *testing.T) {
orig := memoryConfigInt
t.Cleanup(func() { memoryConfigInt = orig })
values := map[string]int{}
memoryConfigInt = func(key string) int { return values[key] }
if got := memoryCorpusBudget(); got != 0 {
t.Fatalf("unset budget = %d, want 0 (off)", got)
}
values["memories.budget-chars"] = 4096
if got := memoryCorpusBudget(); got != 4096 {
t.Fatalf("configured budget = %d, want 4096", got)
}
values["memories.budget-chars"] = -5
if got := memoryCorpusBudget(); got != 0 {
t.Fatalf("negative budget = %d, want 0 (off)", got)
}
}
// TestRememberBudgetVerdictBoundary is spec point (b): a projection exactly AT
// the budget writes; exactly one byte over refuses. The two cases differ by a
// single byte of content, so nothing but the comparison can explain a failure.
func TestRememberBudgetVerdictBoundary(t *testing.T) {
const budget = 200
// Corpus at 100 bytes; the new memory's key costs 3.
existing := budgetCorpus(t, "old", 100)
// Exactly at the budget: 100 + 3 + 97 = 200. Writes (and warns: 100%).
atBudget, refuse := rememberBudgetVerdict(existing, "new", strings.Repeat("z", 97), budget, false)
if refuse {
t.Fatalf("a projection exactly at the budget must write, got refusal %q", atBudget)
}
if !strings.Contains(atBudget, "at 200 of 200 chars (100%)") {
t.Errorf("at-budget line = %q, want the 100%% warn line", atBudget)
}
// One byte over: 201. Refused.
over, refuse := rememberBudgetVerdict(existing, "new", strings.Repeat("z", 98), budget, false)
if !refuse {
t.Fatalf("a projection one byte over the budget must refuse, got line %q", over)
}
// 201 of 200 is 100.5%, and it must NOT round down into "100%": that is the
// at-budget reading the case just above deliberately ALLOWS, so a floored
// refusal would wear the number of the case it is not. Over the line the
// percentage ceilings.
want := "bd remember: memory corpus would be 201 chars, budget is 200 (101%) — refused; use --force to override"
if over != want {
t.Errorf("refusal line =\n %q\nwant\n %q", over, want)
}
}
// TestRememberBudgetVerdictForceWrites is spec point (d): --force turns the
// refusal into a write, and STILL prints a line — a forced crossing that said
// nothing would make the budget invisible exactly when it matters most.
func TestRememberBudgetVerdictForceWrites(t *testing.T) {
existing := budgetCorpus(t, "old", 100)
line, refuse := rememberBudgetVerdict(existing, "new", strings.Repeat("z", 98), 200, true)
if refuse {
t.Fatalf("--force must not refuse, got refusal %q", line)
}
if line == "" {
t.Fatal("--force over budget must still print a line")
}
// (101%), not (100%): the ceiling over the budget is a property of the
// VALUE, so the same projection cannot report two different percentages
// depending on whether --force was passed.
for _, want := range []string{"201", "200", "(101%)", "--force"} {
if !strings.Contains(line, want) {
t.Errorf("forced line %q is missing %q", line, want)
}
}
if strings.Contains(line, "refused") {
t.Errorf("forced line must not claim a refusal: %q", line)
}
}
// TestRememberBudgetVerdictWarnBand is spec point (e) plus its two edges: below
// 80% of the budget the command is silent (today's behavior), and from 80% up
// to the budget it writes AND warns.
func TestRememberBudgetVerdictWarnBand(t *testing.T) {
const budget = 1000
cases := []struct {
name string
projected int
wantLine bool
wantPct int
}{
{"well below", 100, false, 0},
{"one byte under the warn band", 799, false, 0},
{"exactly 80 percent", 800, true, 80},
{"inside the band", 950, true, 95},
// One byte under: 99.9%, which must FLOOR to 99. Within the budget the
// rounding goes down, so "100%" belongs to the exactly-at-budget case
// alone and never to a projection that merely rounds up to it.
{"one byte under the budget", 999, true, 99},
{"exactly at budget", 1000, true, 100},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
// Project by writing a fresh key of known cost into an empty corpus.
key := "k"
content := strings.Repeat("q", tc.projected-len(key))
line, refuse := rememberBudgetVerdict(map[string]string{}, key, content, budget, false)
if refuse {
t.Fatalf("projection %d of %d must not refuse", tc.projected, budget)
}
if !tc.wantLine {
if line != "" {
t.Fatalf("projection %d of %d must be silent, got %q", tc.projected, budget, line)
}
return
}
want := fmt.Sprintf("bd remember: memory corpus at %d of %d chars (%d%%)", tc.projected, budget, tc.wantPct)
if line != want {
t.Errorf("warn line =\n %q\nwant\n %q", line, want)
}
})
}
}
// TestMemoryBudgetLinePercentIsUnclamped pins the arithmetic: over the budget
// the percentage is ceil(projected*100/budget) and is NOT clamped at 100, so a
// corpus forced well past its ceiling reports how far past it actually is. A
// clamp here would make 101% and 400% read identically — exactly the reading an
// operator needs. The ceiling is what keeps an over-budget line off the "100%"
// that means at-budget-and-allowed.
func TestMemoryBudgetLinePercentIsUnclamped(t *testing.T) {
cases := []struct {
projected, budget int
want string
}{
{101, 100, "(101%)"},
{201, 200, "(101%)"}, // ceil(100.5) — never floors back onto at-budget
{400, 100, "(400%)"}, // exact: ceil and floor agree
{1001, 1000, "(101%)"},
}
for _, tc := range cases {
line, _ := memoryBudgetLine(tc.projected, tc.budget, false)
if !strings.Contains(line, tc.want) {
t.Errorf("memoryBudgetLine(%d, %d) = %q, want it to contain %q", tc.projected, tc.budget, line, tc.want)
}
}
}
// TestMemoryBudgetLineHasNoTrailingNewline guards the "ONE line" contract: the
// callers add the newline, so a line that carried its own would print a blank
// line into stderr between the warning and whatever follows.
func TestMemoryBudgetLineHasNoTrailingNewline(t *testing.T) {
for _, force := range []bool{false, true} {
line, _ := memoryBudgetLine(500, 100, force)
if line == "" {
t.Fatalf("force=%v: expected an over-budget line", force)
}
if strings.ContainsAny(line, "\n\r") {
t.Errorf("force=%v: budget line must be a single line, got %q", force, line)
}
}
}