beads/internal/config
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
..
agent_profile.go docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
agents_file_test.go feat(init): add --agents-file flag to customize agent instructions filename 2026-03-22 11:17:43 -07:00
BUILD.bazel ci(bazel): run the scripts and source-walking tests remotely; retire their go test legs (#7320) 2026-10-06 22:20:16 +00:00
config.go fix(bd): cap auto-backup destination size to stop unbounded growth (#6071) 2026-10-01 01:00:25 -07:00
config_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
git_routing_test.go fix(init): use selected hook context in embedded initialization (#6464) 2026-09-29 16:54:33 -07:00
permissions.go fix(worktree): repair permissive .beads/ after worktree create (GH#3593) (#3640) 2026-07-14 13:14:14 -07:00
permissions_linux_test.go fix(worktree): repair permissive .beads/ after worktree create (GH#3593) (#3640) 2026-07-14 13:14:14 -07:00
permissions_open_linux.go fix(worktree): repair permissive .beads/ after worktree create (GH#3593) (#3640) 2026-07-14 13:14:14 -07:00
permissions_open_nonlinux.go fix(lint): suppress two darwin-only gosec findings and cross-lint the darwin build in CI (#6243) 2026-09-28 15:44:52 -07:00
permissions_test.go fix(worktree): repair permissive .beads/ after worktree create (GH#3593) (#3640) 2026-07-14 13:14:14 -07:00
permissions_windows.go fix(init): add FixBeadsDirPermissions stub for Windows build 2026-04-27 18:00:27 -04:00
repos.go Fix worktree-aware config.yaml resolution (#3265) 2026-04-24 07:33:31 -07:00
repos_test.go fix: bd repo commands write to YAML and cleanup on remove (#683) 2025-12-22 01:26:45 -08:00
sync.go refactor: remove dead sync mode scaffolding (GH#2485) 2026-03-10 11:48:11 -07:00
sync_test.go refactor: remove dead sync mode scaffolding (GH#2485) 2026-03-10 11:48:11 -07:00
testmain_test.go fix(config): reject unsafe user config paths (#5528) (#5602) 2026-08-10 21:10:49 -07:00
user_config_path.go fix(config): name profile variables in path error (#5671) (#5676) 2026-09-30 15:40:49 -07:00
user_config_path_test.go fix(config): bd config unset reported success while the key stayed set (#5760) 2026-10-01 05:07:04 -07:00
user_config_path_windows_test.go fix(config): reject unsafe user config paths (#5528) (#5602) 2026-08-10 21:10:49 -07:00
worktree_config_test.go fix(test): keep fixture commits from starting the auto maintenance that prunes a new worktree (#7314) 2026-10-06 21:51:20 +00:00
yaml_config.go feat(remember): opt-in memories.budget-chars — warn at 80%, refuse a write that crosses the corpus budget (--force overrides) (#6508) 2026-10-06 23:04:06 +00:00
yaml_config_test.go feat(remember): opt-in memories.budget-chars — warn at 80%, refuse a write that crosses the corpus budget (--force overrides) (#6508) 2026-10-06 23:04:06 +00:00
yaml_nested_roundtrip_test.go fix(config): bd config unset reported success while the key stayed set (#5760) 2026-10-01 05:07:04 -07:00
yaml_unset_newline_test.go fix(config): bd config unset reported success while the key stayed set (#5760) 2026-10-01 05:07:04 -07:00