From 4e8b017fd47d961cc8f2f90ab5ec788d2b327e14 Mon Sep 17 00:00:00 2001 From: Julian Knutsen Date: Fri, 7 Aug 2026 03:57:04 -0700 Subject: [PATCH] Put the memory plane behind memoryops, conformance-tested at three backends (#5387) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The memory commands get the treatment the sixteen issue commands got in #5378: a role interface in a leaf package, conformance-tested at all three backends, with the CLI routes and the HTTP handlers as thin callers over one implementation. memoryops is its own namespace rather than an addition to issueops. The two planes share a config table and nothing else; a memory whose key shadows a settings name is still a memory, and that separation is now the role's, pinned by its contract, rather than a filter each caller reapplies. Closes an unauthenticated disclosure found on the way: memory content was served in cleartext on GET /v0/beads/config, and reachable through two more doors — `bd config show` and `bd info --json`, the latter republished into agent transcripts by MCP get_schema_info. Enumeration is now filtered at the shared seam (workapi.FilterSettingsEnumeration); `bd config show` is left alone deliberately, since an operator asks for it by name. Two wire contracts were settled after the review council, recorded in full on the PR: the search parameter is spelled `search` rather than `q`, because issues:query already publishes `q` as a boolean expression and one surface must not spell two questions one name; and getMemory keeps its 404, because the status reports the distinction the front door already reports and `bd recall` exits 1 on a miss where `bd config get` exits 0. --- CHANGELOG.md | 28 + backend/conformance/memories_contract.go | 806 ++++++++++++++++++ .../conformance/workspaceconfig_contract.go | 51 ++ cmd/bd/info.go | 16 +- cmd/bd/info_kv_exclusion_test.go | 47 + cmd/bd/info_proxied_server.go | 16 +- cmd/bd/memory.go | 289 ++++--- cmd/bd/memory_embedded_test.go | 92 ++ cmd/bd/memory_proxied_integration_test.go | 16 + cmd/bd/memory_proxied_server.go | 121 --- cmd/bd/prime.go | 31 +- cmd/bd/prime_proxied_server.go | 40 +- cmd/bd/serve.go | 7 + cmd/bd/serve_proxied_integration_test.go | 1 + cmd/bd/serve_source_test.go | 2 + cmd/bd/serve_store_identity_test.go | 7 +- engdocs/ADDING_AN_ISSUEOPS_ROLE.md | 124 ++- internal/httpapi/apigen/types.gen.go | 74 +- internal/httpapi/claim.go | 9 + internal/httpapi/memories.go | 348 ++++++++ internal/httpapi/memories_test.go | 739 ++++++++++++++++ internal/httpapi/problem.go | 54 ++ internal/httpapi/roles_test.go | 108 +++ internal/httpapi/routes.go | 44 + internal/httpapi/server.go | 29 +- internal/httpapi/server_test.go | 4 +- internal/httpapi/spec/openapi.v0.yaml | 475 ++++++++++- internal/httpapi/spec_parity_test.go | 52 ++ internal/jira/tracker_test.go | 4 + internal/memoryapi/memoryapi.go | 160 ++++ internal/memoryapi/memoryapi_test.go | 262 ++++++ internal/storage/dolt/memories.go | 100 +++ .../storage/dolt/memories_contract_test.go | 111 +++ .../dolt/workspace_config_contract_test.go | 3 + internal/storage/embeddeddolt/memories.go | 98 +++ .../embeddeddolt/memories_contract_test.go | 102 +++ .../workspace_config_contract_test.go | 3 + internal/storage/hook_memories.go | 23 + internal/storage/memoryops/memories.go | 169 ++++ internal/storage/memoryops/memories_test.go | 94 ++ .../storage/role_accessor_decorator_test.go | 54 +- internal/storage/storage.go | 20 + internal/storage/uow/memories.go | 141 +++ .../storage/uow/memories_contract_test.go | 109 +++ internal/storage/uow/workspace_config.go | 10 +- .../uow/workspace_config_contract_test.go | 3 + internal/telemetry/memories.go | 57 ++ .../telemetry/role_accessor_decorator_test.go | 103 ++- .../storeworkspaceconfig/workspaceconfig.go | 14 +- internal/workapi/workspaceconfig.go | 50 +- internal/workapi/workspaceconfig_test.go | 61 ++ issue_roles_external_test.go | 38 + issueops/workspaceconfig.go | 33 +- memoryops/doc.go | 42 + memoryops/errors.go | 29 + memoryops/memories.go | 198 +++++ 56 files changed, 5359 insertions(+), 362 deletions(-) create mode 100644 backend/conformance/memories_contract.go create mode 100644 cmd/bd/info_kv_exclusion_test.go delete mode 100644 cmd/bd/memory_proxied_server.go create mode 100644 internal/httpapi/memories.go create mode 100644 internal/httpapi/memories_test.go create mode 100644 internal/memoryapi/memoryapi.go create mode 100644 internal/memoryapi/memoryapi_test.go create mode 100644 internal/storage/dolt/memories.go create mode 100644 internal/storage/dolt/memories_contract_test.go create mode 100644 internal/storage/embeddeddolt/memories.go create mode 100644 internal/storage/embeddeddolt/memories_contract_test.go create mode 100644 internal/storage/hook_memories.go create mode 100644 internal/storage/memoryops/memories.go create mode 100644 internal/storage/memoryops/memories_test.go create mode 100644 internal/storage/uow/memories.go create mode 100644 internal/storage/uow/memories_contract_test.go create mode 100644 internal/telemetry/memories.go create mode 100644 memoryops/doc.go create mode 100644 memoryops/errors.go create mode 100644 memoryops/memories.go diff --git a/CHANGELOG.md b/CHANGELOG.md index aa06f4dbb..9c93c340c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -254,6 +254,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- **BREAKING: `bd config list` and `GET /v0/beads/config` no longer enumerate + the `kv.` plane, which is where `bd remember` memories live.** Memories and + generic `bd kv` values are stored as config rows under `kv.` — user data + riding in the settings table because there is one table, not because they are + settings — and both doors onto the settings plane were listing them with + their values. On the HTTP door that meant an unauthenticated + `GET /v0/beads/config` handed every stored memory to anything that could + reach the port, and the surface's redaction is no defence there: it decides + on the KEY name, while a memory's content is in the VALUE, so a memory + containing a credential under an innocuous slug was served verbatim. + + The exclusion is in the shared role both doors call, not in the HTTP handler, + so the CLI and the API cannot drift apart on what a setting is. The whole + `kv.` prefix goes, not just `kv.memory.`. + + **What still works:** `bd memories`, `bd recall` and `bd kv list` are + unaffected — they read the store directly and are the purpose-built views + over those rows. So are `bd prime`'s memory injection and export's memory + extraction. Point access is unchanged and deliberately so: `bd config get + kv.foo` and `GET /v0/beads/config/kv.foo` still answer a key named exactly, + and `bd config set` / `bd config unset` still write and remove one. The + enumeration was what made a memory discoverable; naming one you already know + is a different question, and refusing it would take away the escape hatch of + removing a wedged memory through `bd config unset`. + + **What breaks:** a script parsing `bd config list` or its `--json` output for + `kv.` rows. Generic `kv.` rows have no other HTTP view today. + - **BREAKING: `bd --readonly serve` is now refused instead of binding a server that cannot do what it advertises.** On a Dolt SQL-server workspace this previously bound a fully functional, fully writable server — the flag was a diff --git a/backend/conformance/memories_contract.go b/backend/conformance/memories_contract.go new file mode 100644 index 000000000..c7b33221c --- /dev/null +++ b/backend/conformance/memories_contract.go @@ -0,0 +1,806 @@ +package conformance + +import ( + "context" + "errors" + "strings" + "testing" + + "github.com/steveyegge/beads/memoryops" +) + +// This file holds the contract every implementation of memoryops.Memories must +// satisfy. Each case asserts what memoryops/memories.go PROMISES rather than +// what any one backend happens to do today; a backend that disagrees is parked +// at its own wiring site with skipKnownDivergence so the case still runs on the +// ones that agree. +// +// THE VOTE COUNT. Three wirings — the server-backed store, the embedded store +// and the unit-of-work provider — and TWO independent bodies between them: the +// two stores share the InTx functions in internal/storage/memoryops, and the +// unit of work composes domain.ConfigUseCase instead. So this is two readings +// plus an engine check, never "three backends agree". The refusals are a third +// shared thing: they all come from internal/memoryapi, so below that validator +// what these cases test is the EXECUTION half. +// +// THE SEEDING DISCIPLINE IS THE POINT OF THIS FILE, more than the case list is. +// The config table holds FOUR classes of row at once and this plane owns +// exactly one of them: +// +// settings rows issue_prefix, custom.* +// generic kv rows kv.* written by `bd kv set` +// memory rows kv.memory.* +// the trap class kv.memory. — a memory that SHADOWS a +// setting, which is a memory, while the setting is not +// +// Every READ case runs against a table seeded with all four, and every WRITE +// case asserts the other three survived, through RAW ROWS rather than through +// the role. A suite that seeded only memory rows would be green over every bug +// this plane can actually have: a body filtering on "kv." instead of +// "kv.memory.", a prefix trim of the wrong length, a LIKE-shaped delete. Each +// of those produces a plausible answer, which is why reading it back through +// the role is exactly the check that passes on a corrupted table. The Deleter +// suite went 59 cases green over a live-row corruption for want of one seeded +// cross-plane row. +// +// KEYS ARE NAMESPACED WITH THE FIXTURE PREFIX wherever they can be, because +// config keys are global to a workspace and these cases share one. The two that +// cannot be are issue_prefix and its shadow: the whole point of the trap class +// is that the shadowed name is a real settings key. +// +// WHAT THIS CONTRACT DELIBERATELY DOES NOT PIN: the one-transaction promise. It +// is structural, not black-box-observable — a single-threaded case cannot +// falsify it and a concurrency case would be flaky at three engines. It is +// pinned instead by the SHAPE of the bodies (there is no two-call composition +// to regress to without deleting the …InTx functions) and by review. If a cheap +// deterministic probe ever emerges — a transaction-counting seam on the kit — +// add a case for it; do not fake one with sleeps. + +// MemoriesFixture supplies adapter-specific storage access for the memory +// assertions. Every field is named and typed exactly like the per-backend +// roleFixtureKit hook it is filled from. +type MemoriesFixture struct { + // IssuePrefix namespaces the keys each assertion writes, so several of them + // can share one database. + IssuePrefix string + Memories memoryops.Memories + // SetConfig writes one workspace config key OUT OF BAND, past the role, by + // its FULL storage key. It is how these cases seed the three classes this + // plane does not own, and how they create the one row no front door can: a + // memory stored as the empty string. + SetConfig func(context.Context, string, string) error + // QueryScalar runs a single-row query and scans it, and RETURNS the error + // rather than failing the test. It is how the cases read RAW ROWS — the + // only way to tell "the answer looks right" from "the table is right". + QueryScalar func(context.Context, string, []any, ...any) error + // CountHistory reports how many history entries the fixture's branch has. + // A nil hook means "this backend cannot observe history", and the case that + // needs it SKIPS with that reason rather than passing quietly. + CountHistory func(context.Context) (int, error) +} + +// memoriesNeighbors are the rows a memory operation must not touch: one +// settings row, one generic kv row, one ordinary memory and the shadow memory +// whose user key is a settings name. +type memoriesNeighbors struct { + settingKey, settingValue string + genericKey, genericValue string + memoryKey, memoryValue string + shadowKey, shadowValue string +} + +// seedMemoriesAllFourClasses writes one row of every class the config table +// holds and returns them, so a case can assert afterwards that the three it +// does not own are byte-identical. +// +// It is called by EVERY case, read and write alike. That is deliberate +// repetition: a helper that only some cases called would leave the others +// running against whichever rows the previous subtest happened to leave. +func seedMemoriesAllFourClasses(t *testing.T, ctx context.Context, fixture MemoriesFixture) memoriesNeighbors { + t.Helper() + n := memoriesNeighbors{ + settingKey: "custom." + fixture.IssuePrefix + "-setting", + settingValue: "a settings row, not a memory", + genericKey: "kv." + fixture.IssuePrefix + "-generic", + genericValue: "a bd kv row, not a memory", + memoryKey: "kv.memory." + fixture.IssuePrefix + "-neighbor", + memoryValue: "a memory that no case under test names", + // The trap: a memory CALLED issue_prefix. Its storage key differs from + // the workspace's own issue_prefix row by the prefix alone, so a + // de-prefixing bug re-keys the workspace's identity. + shadowKey: "kv.memory.issue_prefix", + shadowValue: "the prefix rename runbook lives in engdocs", + } + for _, row := range [][2]string{ + {"issue_prefix", fixture.IssuePrefix}, + {n.settingKey, n.settingValue}, + {n.genericKey, n.genericValue}, + {n.memoryKey, n.memoryValue}, + {n.shadowKey, n.shadowValue}, + } { + if err := fixture.SetConfig(ctx, row[0], row[1]); err != nil { + t.Fatalf("seed %q out of band: %v", row[0], err) + } + } + return n +} + +// assertMemoriesNeighborsSurvived is the other half of the discipline: after a +// write, the three classes this plane does not own are still exactly what the +// seed left, read as RAW ROWS. +func assertMemoriesNeighborsSurvived(t *testing.T, ctx context.Context, fixture MemoriesFixture, n memoriesNeighbors) { + t.Helper() + assertMemoriesRawValue(t, ctx, fixture, "issue_prefix", fixture.IssuePrefix) + assertMemoriesRawValue(t, ctx, fixture, n.settingKey, n.settingValue) + assertMemoriesRawValue(t, ctx, fixture, n.genericKey, n.genericValue) + assertMemoriesRawValue(t, ctx, fixture, n.memoryKey, n.memoryValue) + assertMemoriesRawValue(t, ctx, fixture, n.shadowKey, n.shadowValue) +} + +// RunMemoriesListOfAnEmptyPlaneAnswersAnEmptyMap pins memoryops.ListResult's +// "empty map, never nil" on the one state that can produce a nil: a workspace +// with no memory rows at all. +// +// IT MUST RUN FIRST in each wiring, before any case seeds. All three backends +// build a fresh workspace per suite, so "first" is enough; the case says so +// loudly rather than weakening itself, because the property it pins is only +// reachable from an untouched plane. +func RunMemoriesListOfAnEmptyPlaneAnswersAnEmptyMap(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + result, err := fixture.Memories.List(ctx, memoryops.ListRequest{}) + if err != nil { + t.Fatalf("List on an empty plane: %v", err) + } + if result.Memories == nil { + t.Fatal("List returned a nil map; the contract promises an empty one") + } + if len(result.Memories) != 0 { + t.Fatalf("List on what should be an untouched plane returned %v.\n"+ + "This case pins the nil-versus-empty answer and can only see it before "+ + "anything is stored: run it FIRST in this wiring's subtest order.", result.Memories) + } +} + +// RunMemoriesRememberStoresContentVerbatim pins memoryops.RememberRequest's +// "stored VERBATIM": newlines, surrounding space and unicode all survive. +// +// The raw-row assertion is the load-bearing half. Reading the value back +// through Recall would pass on a body that truncated for display and on a body +// that stored under the wrong key, because it would make the same two mistakes +// in reverse. This asserts the row is at EXACTLY kv.memory. holding +// EXACTLY those bytes. +func RunMemoriesRememberStoresContentVerbatim(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + key := fixture.IssuePrefix + "-verbatim" + const content = " first line\nsecond line — with an em dash " + + result := rememberMemory(t, ctx, fixture, memoryops.RememberRequest{Key: key, Content: content}) + if result.Key != key { + t.Fatalf("Remember result key = %q, want %q", result.Key, key) + } + if result.Value != content { + t.Fatalf("Remember result value = %q, want the content verbatim %q", result.Value, content) + } + assertMemoriesRawValue(t, ctx, fixture, "kv.memory."+key, content) + assertMemoriesRecall(t, ctx, fixture, key, content, true) + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) +} + +// RunMemoriesRememberDerivesTheKeyWhenAbsent pins that a request with no key is +// the NORMAL case and that the role derives it — memoryops.RememberRequest.Key. +// +// The expected key is SPELLED OUT here rather than recomputed with DeriveKey, +// so this case is a second, independent statement of the derivation and not a +// tautology. The byte-level golden table lives in internal/memoryapi's unit +// tests; this one pins that the role reaches it at all, and that the memory is +// recallable under what the result reported. +func RunMemoriesRememberDerivesTheKeyWhenAbsent(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + content := fixture.IssuePrefix + " Derives The Key, From Content!" + want := strings.ToLower(fixture.IssuePrefix) + "-derives-the-key-from-content" + + result := rememberMemory(t, ctx, fixture, memoryops.RememberRequest{Content: content}) + if result.Key != want { + t.Fatalf("Remember(%q) derived key %q, want %q", content, result.Key, want) + } + assertMemoriesRawValue(t, ctx, fixture, "kv.memory."+want, content) + assertMemoriesRecall(t, ctx, fixture, want, content, true) + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) +} + +// RunMemoriesRememberWithExplicitKeyStoresVerbatim pins the other half of +// RememberRequest.Key: an explicit key is used with NO normalization, so a +// memory stays recallable under the exact bytes the caller used. +// +// The key carries a space, a dot and a non-ASCII character on purpose: every +// one of them is something a slugifier would eat, and `bd remember --key` has +// always accepted all three. +func RunMemoriesRememberWithExplicitKeyStoresVerbatim(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + key := fixture.IssuePrefix + "-Has Spaces.✓" + const content = "an explicit key is not a slug" + + result := rememberMemory(t, ctx, fixture, memoryops.RememberRequest{Key: key, Content: content}) + if result.Key != key { + t.Fatalf("Remember result key = %q, want the explicit key verbatim %q", result.Key, key) + } + assertMemoriesRawValue(t, ctx, fixture, "kv.memory."+key, content) + assertMemoriesRecall(t, ctx, fixture, key, content, true) + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) +} + +// RunMemoriesRememberReplacesAndReportsIt pins +// memoryops.RememberResult.Replaced, including the leg that makes it different +// from RecallResult.Found. +// +// Three legs: a first write reports false, a second reports true and REPLACES +// rather than appends, and a write over an out-of-band EMPTY row reports true +// even though a Recall of that key would have reported Found false. The third +// is the divergence the leaf doc states — Replaced is about the ROW — and it is +// the one a body computing `previous != ""` gets wrong. +func RunMemoriesRememberReplacesAndReportsIt(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + key := fixture.IssuePrefix + "-replaced" + + first := rememberMemory(t, ctx, fixture, memoryops.RememberRequest{Key: key, Content: "first"}) + if first.Replaced { + t.Fatalf("Remember of a key nothing stored reported Replaced true") + } + second := rememberMemory(t, ctx, fixture, memoryops.RememberRequest{Key: key, Content: "second"}) + if !second.Replaced { + t.Fatalf("Remember over an existing memory reported Replaced false") + } + assertMemoriesRawValue(t, ctx, fixture, "kv.memory."+key, "second") + + // The row exists and holds "". No front door can create it; an out-of-band + // write and a cross-clone merge both can. + emptied := fixture.IssuePrefix + "-replaced-empty" + if err := fixture.SetConfig(ctx, "kv.memory."+emptied, ""); err != nil { + t.Fatalf("seed an empty memory row out of band: %v", err) + } + assertMemoriesRecall(t, ctx, fixture, emptied, "", false) + overEmpty := rememberMemory(t, ctx, fixture, memoryops.RememberRequest{Key: emptied, Content: "now it has content"}) + if !overEmpty.Replaced { + t.Fatalf("Remember over a row stored EMPTY reported Replaced false: Replaced is about the row, " + + "not the value — see memoryops.RememberResult.Replaced") + } + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) +} + +// RunMemoriesRememberRefusesEmptyContent pins the first refusal as the SENTINEL +// rather than the message text — a wrapper that reformatted the prose would +// still satisfy every caller that classifies, and a message assertion would +// fail on it — and pins that NOTHING lands when it fires. +func RunMemoriesRememberRefusesEmptyContent(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + key := fixture.IssuePrefix + "-refused-empty" + + for _, blank := range []string{"", " "} { + if _, err := fixture.Memories.Remember(ctx, memoryops.RememberRequest{Key: key, Content: blank}); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("Remember(content %q) error = %v, want ErrValidation", blank, err) + } + assertMemoriesRawAbsent(t, ctx, fixture, "kv.memory."+key) + } + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) +} + +// RunMemoriesRememberRefusesAWhitespaceOnlyKey pins the rule Remember shares +// with Recall and Forget, over the quadrant that had no case. +// +// Recall and Forget refuse a key that is empty after trimming — cases 8 and 13 +// pin that. Remember used to accept any non-empty string, so `--key " "` +// minted a row no memory operation could ever name again: enumerated by List +// forever, unrecallable, unforgettable, reachable only through +// `bd config unset` on the raw storage key. The write door accepted what every +// read door refused, and the HTTP surface inherited the split exactly — POST +// accepted the key that GET and DELETE answered 400 for. +// +// The surviving half is asserted too, because the rule is that a key must NAME +// something and not that it must be tidy: a key with surrounding space is +// stored and recalled byte for byte. +func RunMemoriesRememberRefusesAWhitespaceOnlyKey(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + + for _, key := range []string{" ", " ", "\t"} { + _, err := fixture.Memories.Remember(ctx, memoryops.RememberRequest{Key: key, Content: "content"}) + if !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("Remember(key %q) error = %v, want ErrValidation: a key no read can name must not be writable", key, err) + } + assertMemoriesRawAbsent(t, ctx, fixture, "kv.memory."+key) + } + + // Surrounding space survives: this is a trim REFUSAL, not a trim. + spaced := " " + fixture.IssuePrefix + "-spaced " + if _, err := fixture.Memories.Remember(ctx, memoryops.RememberRequest{Key: spaced, Content: "kept"}); err != nil { + t.Fatalf("Remember(key %q) error = %v, want it stored verbatim", spaced, err) + } + got, err := fixture.Memories.Recall(ctx, memoryops.RecallRequest{Key: spaced}) + if err != nil { + t.Fatalf("Recall(%q) error = %v", spaced, err) + } + if !got.Found || got.Value != "kept" { + t.Errorf("Recall(%q) = %+v, want the value under the exact bytes written", spaced, got) + } + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) +} + +// RunMemoriesRememberRefusesAnUnderivableKey pins the second refusal: content +// with nothing to derive from, and no key to fall back on. +// +// The raw assertion is on the EMPTY user key, because that is what a body which +// skipped the check would have written: a row at "kv.memory." holding the +// content, which nothing can ever name again. +func RunMemoriesRememberRefusesAnUnderivableKey(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + + if _, err := fixture.Memories.Remember(ctx, memoryops.RememberRequest{Content: "!!!"}); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("Remember(content %q, no key) error = %v, want ErrValidation", "!!!", err) + } + assertMemoriesRawAbsent(t, ctx, fixture, "kv.memory.") + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) +} + +// RunMemoriesRecallAnswersTheStoredValue pins that Recall reads THIS plane and +// only this plane, against a table holding all four classes. +// +// The shadow leg is the sharp one: `bd recall issue_prefix` answers the MEMORY +// called issue_prefix, not the workspace's issue prefix. A body that trimmed +// the wrong number of bytes, or looked the user key up unprefixed, would serve +// the workspace's identity as a user's note. +func RunMemoriesRecallAnswersTheStoredValue(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + + assertMemoriesRecall(t, ctx, fixture, fixture.IssuePrefix+"-neighbor", neighbors.memoryValue, true) + assertMemoriesRecall(t, ctx, fixture, "issue_prefix", neighbors.shadowValue, true) + + // The three classes this plane does not own are not reachable through it, + // under either the bare name or the stored one. + for _, absent := range []string{ + neighbors.settingKey, + neighbors.genericKey, + fixture.IssuePrefix + "-generic", + "kv.memory." + fixture.IssuePrefix + "-neighbor", + } { + assertMemoriesRecall(t, ctx, fixture, absent, "", false) + } +} + +// RunMemoriesRecallReportsAMissAsNotFoundNotAnError pins the decision recorded +// in memoryops/errors.go: there is no ErrNotFound on this role, because the +// seam beneath it cannot see the difference the error would claim. +func RunMemoriesRecallReportsAMissAsNotFoundNotAnError(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + seedMemoriesAllFourClasses(t, ctx, fixture) + key := fixture.IssuePrefix + "-never-remembered" + + result, err := fixture.Memories.Recall(ctx, memoryops.RecallRequest{Key: key}) + if err != nil { + t.Fatalf("Recall of a key nothing stored = %v, want a nil error with Found false", err) + } + if result.Found || result.Value != "" { + t.Fatalf("Recall of a key nothing stored = %+v, want Found false and an empty value", result) + } + if result.Key != key { + t.Fatalf("Recall result key = %q, want %q", result.Key, key) + } + + // The empty key is a refusal rather than a miss: there is no row a caller + // could mean by it. + for _, blank := range []string{"", " "} { + if _, err := fixture.Memories.Recall(ctx, memoryops.RecallRequest{Key: blank}); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("Recall(%q) error = %v, want ErrValidation", blank, err) + } + } +} + +// RunMemoriesRecallConflatesStoredEmptyWithAbsent pins +// memoryops.RecallResult.Found's central claim, and the one asymmetry that lets +// a caller see past it: List enumerates the key, because the ROW exists. +// +// That is the same same-answer-different-row shape the settings contract pins +// for `bd config get`, and stating it is what keeps a backend from "fixing" it +// on one leg and making the answer depend on the route. +func RunMemoriesRecallConflatesStoredEmptyWithAbsent(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + seedMemoriesAllFourClasses(t, ctx, fixture) + emptied := fixture.IssuePrefix + "-stored-empty" + never := fixture.IssuePrefix + "-never-stored" + + if err := fixture.SetConfig(ctx, "kv.memory."+emptied, ""); err != nil { + t.Fatalf("seed an empty memory row out of band: %v", err) + } + assertMemoriesRecall(t, ctx, fixture, emptied, "", false) + assertMemoriesRecall(t, ctx, fixture, never, "", false) + + plane := listMemories(t, ctx, fixture, "") + if value, ok := plane[emptied]; !ok || value != "" { + t.Fatalf("List[%q] = %q (present=%v), want an empty value that IS enumerated: "+ + "the row exists even though Recall denies it", emptied, value, ok) + } + if _, ok := plane[never]; ok { + t.Fatalf("List carries %q, which nothing stored", never) + } +} + +// RunMemoriesForgetRemovesExactlyTheNamedRow IS THE QUADRANT CASE, and the +// reason this contract has a seeding discipline instead of a case list. +// +// It seeds a memory whose key is a PREFIX of another memory's key, a generic kv +// row whose storage key is what the memory's would be one prefix up, and a +// settings row — then forgets the first and asserts, through raw rows, that the +// other three are still there. +// +// Each of the three bugs it catches produces a plausible answer through the +// role: a LIKE-shaped delete takes the adjacent memory with it, a delete +// composed from the short prefix takes the `bd kv` row instead, and an +// unanchored match takes the settings row. This is the Deleter bug family, and +// the analog of it went 59 green cases undetected. +func RunMemoriesForgetRemovesExactlyTheNamedRow(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + + target := fixture.IssuePrefix + "-a" + adjacent := fixture.IssuePrefix + "-a-b" + generic := "kv." + target // what the memory's key would be one prefix up + + for _, row := range [][2]string{ + {"kv.memory." + target, "the memory being forgotten"}, + {"kv.memory." + adjacent, "the memory that must survive"}, + {generic, "a bd kv value that must survive"}, + } { + if err := fixture.SetConfig(ctx, row[0], row[1]); err != nil { + t.Fatalf("seed %q out of band: %v", row[0], err) + } + } + + result := forgetMemory(t, ctx, fixture, target) + if !result.Found || result.Value != "the memory being forgotten" { + t.Fatalf("Forget(%q) = %+v, want Found true with the stored value", target, result) + } + + assertMemoriesRawAbsent(t, ctx, fixture, "kv.memory."+target) + assertMemoriesRawValue(t, ctx, fixture, "kv.memory."+adjacent, "the memory that must survive") + assertMemoriesRawValue(t, ctx, fixture, generic, "a bd kv value that must survive") + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) + + // And through the role, because a delete that also broke the read would + // otherwise look consistent. + assertMemoriesRecall(t, ctx, fixture, target, "", false) + assertMemoriesRecall(t, ctx, fixture, adjacent, "the memory that must survive", true) +} + +// RunMemoriesForgetNeverTouchesTheSettingsPlane is foldable into the case above +// and kept separate because its failure mode deserves its own name: a +// de-prefixing bug here does not lose a note, it RE-KEYS THE WORKSPACE. Every +// bead created before the write and every bead created after it would disagree +// about their own namespace, with nothing to reconcile them. +func RunMemoriesForgetNeverTouchesTheSettingsPlane(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + + result := forgetMemory(t, ctx, fixture, "issue_prefix") + if !result.Found || result.Value != neighbors.shadowValue { + t.Fatalf("Forget(%q) = %+v, want the SHADOW memory's value %q", "issue_prefix", result, neighbors.shadowValue) + } + + assertMemoriesRawAbsent(t, ctx, fixture, "kv.memory.issue_prefix") + assertMemoriesRawValue(t, ctx, fixture, "issue_prefix", fixture.IssuePrefix) + assertMemoriesRawValue(t, ctx, fixture, neighbors.settingKey, neighbors.settingValue) + assertMemoriesRawValue(t, ctx, fixture, neighbors.genericKey, neighbors.genericValue) +} + +// RunMemoriesForgetReportsTheForgottenValue pins memoryops.ForgetResult.Value: +// what `bd forget` prints is the content of the row it removed, read in the +// same transaction as the delete. +func RunMemoriesForgetReportsTheForgottenValue(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + key := fixture.IssuePrefix + "-reported" + const content = "the value the caller is about to be shown" + + rememberMemory(t, ctx, fixture, memoryops.RememberRequest{Key: key, Content: content}) + result := forgetMemory(t, ctx, fixture, key) + if result.Key != key { + t.Fatalf("Forget result key = %q, want %q", result.Key, key) + } + if !result.Found || result.Value != content { + t.Fatalf("Forget(%q) = %+v, want Found true with value %q", key, result, content) + } + // The row really went, and nothing beside it did. This is the only + // forget-after-Remember sequence in the suite — every other forget case + // removes an out-of-band seed — so it is the one place a delete whose + // storage key came from the PRECEDING write could do collateral damage. + // Without these two lines the next case's seed rewrites all four neighbor + // rows and repairs the damage before anything observes it. + assertMemoriesRawAbsent(t, ctx, fixture, "kv.memory."+key) + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) + assertMemoriesRecall(t, ctx, fixture, key, "", false) +} + +// RunMemoriesForgetOfAnAbsentKeyIsNotFoundAndDeletesNothing pins that a miss is +// a RESULT and not an error, that it changes no row anywhere in the table, that +// the second call — the one a retrying caller actually makes — answers the same +// way, and that the SECOND kind of miss behaves like the first: a memory stored +// as the empty string is Found false, and its row is left standing. +// +// That last leg is memoryops.ForgetResult.Found's parenthesis, and it keeps +// Forget's answer and Recall's answer the same statement. A body that deleted +// on "the row is there" rather than on "Recall would find it" would report +// nothing removed while removing something. +// +// The whole-table row count is the assertion that matters: "the key is still +// absent" would pass on a delete that swept a neighboring plane. +func RunMemoriesForgetOfAnAbsentKeyIsNotFoundAndDeletesNothing(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + key := fixture.IssuePrefix + "-never-stored-forget" + emptied := fixture.IssuePrefix + "-empty-forget" + if err := fixture.SetConfig(ctx, "kv.memory."+emptied, ""); err != nil { + t.Fatalf("seed an empty memory row out of band: %v", err) + } + + var before int + if err := fixture.QueryScalar(ctx, "SELECT COUNT(*) FROM config", nil, &before); err != nil { + t.Fatalf("count config rows before: %v", err) + } + + for attempt := 1; attempt <= 2; attempt++ { + for _, miss := range []string{key, emptied} { + result, err := fixture.Memories.Forget(ctx, memoryops.ForgetRequest{Key: miss}) + if err != nil { + t.Fatalf("Forget(%q) attempt %d = %v, want success with Found false", miss, attempt, err) + } + if result.Found || result.Value != "" { + t.Fatalf("Forget(%q) attempt %d = %+v, want Found false and no value", miss, attempt, result) + } + } + } + + var after int + if err := fixture.QueryScalar(ctx, "SELECT COUNT(*) FROM config", nil, &after); err != nil { + t.Fatalf("count config rows after: %v", err) + } + if after != before { + t.Fatalf("config rows went %d -> %d across four forgets that found nothing, want no change", before, after) + } + // The stored-empty row is specifically still there: Found false said nothing + // was removed, and that has to be true of the row as well as of the answer. + assertMemoriesRawValue(t, ctx, fixture, "kv.memory."+emptied, "") + assertMemoriesNeighborsSurvived(t, ctx, fixture, neighbors) + + // The empty key is a refusal, not a miss. + for _, blank := range []string{"", " "} { + if _, err := fixture.Memories.Forget(ctx, memoryops.ForgetRequest{Key: blank}); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("Forget(%q) error = %v, want ErrValidation", blank, err) + } + } +} + +// RunMemoriesListReturnsOnlyTheMemoryPlane pins memoryops.ListResult.Memories +// against a table holding all four classes. +// +// It asserts in both directions, and the second one is what the case is for: +// the seeded memories are present under their STRIPPED keys, and no answer key +// belongs to a plane this role does not own. A body filtering on "kv." answers +// with keys beginning "memory."; a trim of the wrong length answers with the +// same; no filter at all answers with the workspace's settings. All three look +// like memories to a caller. +func RunMemoriesListReturnsOnlyTheMemoryPlane(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + neighbors := seedMemoriesAllFourClasses(t, ctx, fixture) + + plane := listMemories(t, ctx, fixture, "") + + if got := plane[fixture.IssuePrefix+"-neighbor"]; got != neighbors.memoryValue { + t.Fatalf("List[%q] = %q, want %q — the key must arrive with kv.memory. stripped", + fixture.IssuePrefix+"-neighbor", got, neighbors.memoryValue) + } + // The trap: the answer DOES carry issue_prefix, and it carries the memory's + // value rather than the workspace's prefix. + if got := plane["issue_prefix"]; got != neighbors.shadowValue { + t.Fatalf("List[%q] = %q, want the shadow MEMORY's value %q, not the workspace's prefix %q", + "issue_prefix", got, neighbors.shadowValue, fixture.IssuePrefix) + } + + for _, foreign := range []string{ + neighbors.settingKey, // the settings row, unfiltered + neighbors.genericKey, // the generic kv row, unfiltered + fixture.IssuePrefix + "-generic", // the generic kv row, "kv." trimmed + "memory." + fixture.IssuePrefix + "-neighbor", // a memory with only "kv." trimmed + } { + if value, ok := plane[foreign]; ok { + t.Fatalf("List carries %q = %q, which is not a memory: the answer is the kv.memory. plane only", + foreign, value) + } + } + for key := range plane { + if strings.HasPrefix(key, "kv.") || strings.HasPrefix(key, "memory.") || strings.HasPrefix(key, "custom.") { + t.Fatalf("List carries %q: the keys are USER keys, so a storage prefix in one means the "+ + "answer was narrowed or trimmed at the wrong boundary", key) + } + } +} + +// RunMemoriesListSearchMatchesTheUserKeyNotTheStorageKey pins WHICH STRING the +// search folds over, which no other case can see. +// +// ListRequest.Search promises a match against the USER key. Every term the +// case below uses is a substring of the user key exactly when it is a substring +// of the storage key, so a body that filtered BEFORE stripping the prefix — +// one transposed line — passes all of them. A term that appears only in the +// storage form separates the two: "kv." matches every row before the strip and +// none after it. +// +// The failure it catches is route-dependent answers: `bd memories memory` would +// return the ENTIRE plane on the leg that folded over storage keys, because +// every storage key contains "kv.memory.", while the other leg returned genuine +// matches. That is the wrong-boundary bug family this file's own header names. +func RunMemoriesListSearchMatchesTheUserKeyNotTheStorageKey(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + seedMemoriesAllFourClasses(t, ctx, fixture) + rememberMemory(t, ctx, fixture, memoryops.RememberRequest{ + Key: fixture.IssuePrefix + "-plain", Content: "nothing prefix-shaped in here", + }) + + for _, term := range []string{"kv.", "kv.memory.", "memory."} { + if got := listMemories(t, ctx, fixture, term); len(got) != 0 { + t.Errorf("List(search %q) matched %d memories, want 0: the fold is over the USER key, "+ + "and %q appears only in the storage form", term, len(got), term) + } + } +} + +// RunMemoriesListSearchMatchesKeyOrValueCaseInsensitively pins +// memoryops.ListRequest.Search's "the folding is THIS ROLE'S": the raw term the +// user typed goes in, and matching is case-insensitive on both sides. +// +// The shipped `bd memories` lowercased the term at the front door, so a second +// door passing it through raw would have reported an empty plane. This case +// passes an UPPERCASE term at a lowercase value and vice versa, which is the +// pair that fails if either fold is missing. +func RunMemoriesListSearchMatchesKeyOrValueCaseInsensitively(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + seedMemoriesAllFourClasses(t, ctx, fixture) + byKey := fixture.IssuePrefix + "-searchable-KEY" + byValue := fixture.IssuePrefix + "-searched-by-value" + + rememberMemory(t, ctx, fixture, memoryops.RememberRequest{Key: byKey, Content: "content with nothing to match on"}) + rememberMemory(t, ctx, fixture, memoryops.RememberRequest{Key: byValue, Content: "this one mentions PHANTOMS"}) + + // A lowercase term against an uppercase key, and an uppercase term against + // a value whose match is uppercase too — both sides folded. + if got := listMemories(t, ctx, fixture, "searchable-key"); got[byKey] == "" { + t.Fatalf("List(search=%q) = %v, want the memory whose KEY matches case-insensitively", "searchable-key", got) + } + if got := listMemories(t, ctx, fixture, "phantoms"); got[byValue] == "" { + t.Fatalf("List(search=%q) = %v, want the memory whose VALUE matches case-insensitively", "phantoms", got) + } + if got := listMemories(t, ctx, fixture, "SEARCHED-BY-VALUE"); got[byValue] == "" { + t.Fatalf("List(search=%q) = %v, want the memory whose key matches the folded term", "SEARCHED-BY-VALUE", got) + } + + // A miss is an empty map, never nil and never an error. + miss := listMemories(t, ctx, fixture, fixture.IssuePrefix+"-matches-nothing-at-all") + if len(miss) != 0 { + t.Fatalf("List(search that matches nothing) = %v, want an empty map", miss) + } +} + +// RunMemoriesARefusedWriteRecordsNoHistory pins the other half of "and NOTHING +// is written": a refusal does not reach storage at all, so it leaves no history +// entry behind either. +// +// The delta is taken around the refusals rather than read off the top of the +// log, because two commits made inside one second tie on date. +func RunMemoriesARefusedWriteRecordsNoHistory(t *testing.T, ctx context.Context, fixture MemoriesFixture) { + t.Helper() + if fixture.CountHistory == nil { + t.Skip("this backend cannot observe history, so the no-write half of a refusal is unobservable here") + } + before, err := fixture.CountHistory(ctx) + if err != nil { + t.Fatalf("CountHistory before: %v", err) + } + + for _, req := range []memoryops.RememberRequest{ + {Key: fixture.IssuePrefix + "-refused-history", Content: ""}, + {Key: fixture.IssuePrefix + "-refused-history", Content: " "}, + {Content: "!!!"}, + } { + if _, err := fixture.Memories.Remember(ctx, req); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("Remember(%+v) error = %v, want ErrValidation", req, err) + } + } + if _, err := fixture.Memories.Forget(ctx, memoryops.ForgetRequest{Key: ""}); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("Forget(\"\") error = %v, want ErrValidation", err) + } + + after, err := fixture.CountHistory(ctx) + if err != nil { + t.Fatalf("CountHistory after: %v", err) + } + if after != before { + t.Fatalf("history entries went %d -> %d across four refused writes, want no change", before, after) + } +} + +func rememberMemory(t *testing.T, ctx context.Context, fixture MemoriesFixture, req memoryops.RememberRequest) memoryops.RememberResult { + t.Helper() + result, err := fixture.Memories.Remember(ctx, req) + if err != nil { + t.Fatalf("Remember(key=%q, content=%q): %v", req.Key, req.Content, err) + } + return result +} + +func forgetMemory(t *testing.T, ctx context.Context, fixture MemoriesFixture, key string) memoryops.ForgetResult { + t.Helper() + result, err := fixture.Memories.Forget(ctx, memoryops.ForgetRequest{Key: key}) + if err != nil { + t.Fatalf("Forget(%q): %v", key, err) + } + return result +} + +func listMemories(t *testing.T, ctx context.Context, fixture MemoriesFixture, search string) map[string]string { + t.Helper() + result, err := fixture.Memories.List(ctx, memoryops.ListRequest{Search: search}) + if err != nil { + t.Fatalf("List(search=%q): %v", search, err) + } + if result.Memories == nil { + t.Fatalf("List(search=%q) returned a nil map; the contract promises an empty one", search) + } + return result.Memories +} + +func assertMemoriesRecall(t *testing.T, ctx context.Context, fixture MemoriesFixture, key, wantValue string, wantFound bool) { + t.Helper() + result, err := fixture.Memories.Recall(ctx, memoryops.RecallRequest{Key: key}) + if err != nil { + t.Fatalf("Recall(%q): %v", key, err) + } + if result.Key != key { + t.Fatalf("Recall(%q) echoed key %q", key, result.Key) + } + if result.Value != wantValue || result.Found != wantFound { + t.Fatalf("Recall(%q) = value %q found %v, want value %q found %v", key, result.Value, result.Found, wantValue, wantFound) + } +} + +// assertMemoriesRawValue reads ONE config row by its full storage key. It is +// how every write case checks the three planes it does not own, and how the +// encoding itself is pinned: the role gives no way to see whether a memory +// landed at kv.memory. or somewhere adjacent that reads back the same. +func assertMemoriesRawValue(t *testing.T, ctx context.Context, fixture MemoriesFixture, storageKey, want string) { + t.Helper() + var got string + if err := fixture.QueryScalar(ctx, "SELECT value FROM config WHERE `key` = ?", []any{storageKey}, &got); err != nil { + t.Fatalf("read raw config row %q: %v", storageKey, err) + } + if got != want { + t.Fatalf("raw config row %q = %q, want %q", storageKey, got, want) + } +} + +// assertMemoriesRawAbsent counts rather than selects, because a backend's +// missing-row error is its own business and a case that asserted on one would +// pass for the wrong reason on the others. +func assertMemoriesRawAbsent(t *testing.T, ctx context.Context, fixture MemoriesFixture, storageKey string) { + t.Helper() + var rows int + if err := fixture.QueryScalar(ctx, "SELECT COUNT(*) FROM config WHERE `key` = ?", []any{storageKey}, &rows); err != nil { + t.Fatalf("count raw config rows for %q: %v", storageKey, err) + } + if rows != 0 { + t.Fatalf("raw config row %q exists (%d rows), want none", storageKey, rows) + } +} diff --git a/backend/conformance/workspaceconfig_contract.go b/backend/conformance/workspaceconfig_contract.go index 2b7b2c674..c98575496 100644 --- a/backend/conformance/workspaceconfig_contract.go +++ b/backend/conformance/workspaceconfig_contract.go @@ -3,8 +3,10 @@ package conformance import ( "context" "errors" + "strings" "testing" + "github.com/steveyegge/beads/internal/storage/kvkeys" publicops "github.com/steveyegge/beads/issueops" ) @@ -141,6 +143,55 @@ func RunWorkspaceConfigListsEveryStoredSetting(t *testing.T, ctx context.Context } } +// RunWorkspaceConfigListExcludesTheKVPlane pins workspaceconfig.go's +// ListSettings: no key under `kv.` is enumerated, and the asymmetry that stops +// the exclusion there — GetSetting still answers each of those keys by name. +// +// The two planes share one table, so this is the case that tells a body +// filtering the SETTINGS plane from one that just happens to hold no memories. +// Both probes are written THROUGH the role, because SetSetting still accepts +// them: a write that lands and an enumeration that omits it is the whole claim, +// and seeding out of band would leave the write half untested. +// +// The generic key and the memory key are both here because the exclusion is the +// whole prefix. A body that reached for kvkeys.MemoryConfigKeyPrefix — the +// narrower constant, and the tempting one — passes on the memory and fails on +// the generic row. +// +// The value on the memory probe is shaped like a credential on purpose. That is +// what the exclusion is for: the HTTP surface's redaction decides on the KEY +// name, so a memory whose content is a secret under an innocuous slug was +// served verbatim by an unauthenticated GET /v0/beads/config. +func RunWorkspaceConfigListExcludesTheKVPlane(t *testing.T, ctx context.Context, fixture WorkspaceConfigFixture) { + t.Helper() + setting := workspaceConfigKey(fixture, "kv-neighbor") + generic := kvkeys.Prefix + fixture.IssuePrefix + "-generic" + memory := kvkeys.MemoryConfigKeyPrefix + fixture.IssuePrefix + "-slug" + + setWorkspaceConfigSetting(t, ctx, fixture, setting, "settings row") + setWorkspaceConfigSetting(t, ctx, fixture, generic, "kv row") + setWorkspaceConfigSetting(t, ctx, fixture, memory, "the deploy token is sk-live-000") + + settings := listWorkspaceConfigSettings(t, ctx, fixture) + // The settings row FIRST: an enumeration that dropped everything would + // satisfy the exclusion and mean nothing. + if got, ok := settings[setting]; !ok || got != "settings row" { + t.Fatalf("ListSettings[%q] = %q (present=%v), want %q — the settings plane must survive the exclusion", + setting, got, ok, "settings row") + } + for key := range settings { + if strings.HasPrefix(key, kvkeys.Prefix) { + t.Fatalf("ListSettings carries %q: the kv plane is user data riding in the settings table, not a setting", key) + } + } + + // And the stated asymmetry: the exclusion is on the ENUMERATION only, so a + // caller naming an exact key still gets it. Removing this half would not + // fail any other case — it is pinned here or nowhere. + assertWorkspaceConfigValue(t, ctx, fixture, generic, "kv row") + assertWorkspaceConfigValue(t, ctx, fixture, memory, "the deploy token is sk-live-000") +} + // RunWorkspaceConfigUnsetRemovesTheSetting pins that a removed key is gone from // BOTH answers the role gives — the single read and the enumeration — rather // than from one of them. diff --git a/cmd/bd/info.go b/cmd/bd/info.go index 60d73cbd4..8dcecb927 100644 --- a/cmd/bd/info.go +++ b/cmd/bd/info.go @@ -8,6 +8,7 @@ import ( "github.com/spf13/cobra" "github.com/steveyegge/beads/internal/metrics" "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/internal/workapi" ) var infoCmd = &cobra.Command{ @@ -71,9 +72,20 @@ Examples: info["issue_count"] = len(issues) } + // THE SAME FILTER THE SETTINGS ROLE USES. `bd info --json` serves + // this map whole, and the beads MCP server's get_schema_info tool + // runs `bd info --schema --json` and returns the parsed dict — + // config included — so every memory key AND VALUE landed in the + // transcript of any agent that asked a SCHEMA question. `bd info` + // is also the diagnostic people paste into bug reports. + // + // Unlike `bd config show`, which an operator asks for by name to + // see provenance, nothing here says "show me my memories". configMap, err := store.GetAllConfig(ctx) - if err == nil && len(configMap) > 0 { - info["config"] = configMap + if err == nil { + if filtered := workapi.FilterSettingsEnumeration(configMap); len(filtered) > 0 { + info["config"] = filtered + } } if schemaFlag { diff --git a/cmd/bd/info_kv_exclusion_test.go b/cmd/bd/info_kv_exclusion_test.go new file mode 100644 index 000000000..9bfcd1879 --- /dev/null +++ b/cmd/bd/info_kv_exclusion_test.go @@ -0,0 +1,47 @@ +package main + +import ( + "strings" + "testing" + + "github.com/steveyegge/beads/internal/storage/kvkeys" + "github.com/steveyegge/beads/internal/workapi" +) + +// TestInfoConfigExcludesTheKVPlane pins that `bd info --json` does not serve +// memories. +// +// It asserts the FILTER both info routes now apply, rather than shelling out: +// the two call sites differ only in which seam supplies the map, and the thing +// that can regress is somebody re-inlining GetAllConfig at one of them. +// +// Why it matters more than an ordinary config read: the beads MCP server's +// get_schema_info tool runs `bd info --schema --json` and returns the parsed +// dict whole, so every memory key and VALUE landed in the transcript of any +// agent that asked a schema question — and `bd info` is the diagnostic people +// paste into bug reports. +func TestInfoConfigExcludesTheKVPlane(t *testing.T) { + stored := map[string]string{ + "issue_prefix": "bd", + "custom.statuses": "awaiting_review", + kvkeys.MemoryConfigKeyPrefix + "deploy-notes": "the staging deploy token is sk-live-000", + kvkeys.Prefix + "release.channel": "beta", + // Near misses that must SURVIVE: the rule is a prefix, not a substring. + "kvetch": "not under the kv prefix", + "custom.mentions.kv.inside": "kept", + } + + got := workapi.FilterSettingsEnumeration(stored) + + for key := range got { + if strings.HasPrefix(key, kvkeys.Prefix) { + t.Errorf("bd info would serve %q: the kv plane is not settings, and this map reaches "+ + "agent transcripts through the MCP get_schema_info tool", key) + } + } + for _, want := range []string{"issue_prefix", "custom.statuses", "kvetch", "custom.mentions.kv.inside"} { + if _, ok := got[want]; !ok { + t.Errorf("%q was dropped; only keys under %q may be", want, kvkeys.Prefix) + } + } +} diff --git a/cmd/bd/info_proxied_server.go b/cmd/bd/info_proxied_server.go index 440be2b92..01ce2fee8 100644 --- a/cmd/bd/info_proxied_server.go +++ b/cmd/bd/info_proxied_server.go @@ -4,6 +4,7 @@ import ( "context" "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/internal/workapi" ) func runInfoProxiedServer(ctx context.Context, schemaFlag bool) error { @@ -27,9 +28,20 @@ func runInfoProxiedServer(ctx context.Context, schemaFlag bool) error { info["issue_count"] = len(issues) } + // THE SAME FILTER THE SETTINGS ROLE USES. `bd info --json` serves + // this map whole, and the beads MCP server's get_schema_info tool + // runs `bd info --schema --json` and returns the parsed dict — + // config included — so every memory key AND VALUE landed in the + // transcript of any agent that asked a SCHEMA question. `bd info` + // is also the diagnostic people paste into bug reports. + // + // Unlike `bd config show`, which an operator asks for by name to + // see provenance, nothing here says "show me my memories". configMap, err := uw.ConfigUseCase().GetAllConfig(ctx) - if err == nil && len(configMap) > 0 { - info["config"] = configMap + if err == nil { + if filtered := workapi.FilterSettingsEnumeration(configMap); len(filtered) > 0 { + info["config"] = filtered + } } if schemaFlag { diff --git a/cmd/bd/memory.go b/cmd/bd/memory.go index 30bbdf44b..7695d5d10 100644 --- a/cmd/bd/memory.go +++ b/cmd/bd/memory.go @@ -1,49 +1,88 @@ package main import ( + "errors" "fmt" "os" - "regexp" "sort" "strings" "github.com/spf13/cobra" + "github.com/steveyegge/beads/internal/memoryapi" "github.com/steveyegge/beads/internal/metrics" "github.com/steveyegge/beads/internal/storage/kvkeys" + "github.com/steveyegge/beads/internal/storage/uow" + "github.com/steveyegge/beads/memoryops" ) +// openMemories hands back the persistent-memory role for whichever route this +// invocation is on, each through its OWN capability accessor — the store's for +// the direct route and the provider's for the proxied one. +// +// directRequirement is the message `ensureDirectMode` reports when a workspace +// is reachable by neither route. It is per-verb because the shipped text names +// the verb. +func openMemories(directRequirement string) (memoryops.Memories, error) { + if usesProxiedServer() { + return proxiedMemories() + } + if err := ensureDirectMode(directRequirement); err != nil { + return nil, err + } + return store.Memories() +} + +// proxiedMemories hands back the guarded persistent-memory surface for this +// invocation's proxied-server provider, through the provider's OWN capability +// accessor — the same two-step proxiedWorkspaceConfig performs. +func proxiedMemories() (memoryops.Memories, error) { + if uowProvider == nil { + return nil, errors.New("proxied-server UOW provider not initialized") + } + return memoriesFromProvider(uowProvider) +} + +// memoriesFromProvider is that accessor step for a provider the caller names. +// +// It takes the provider rather than reading the global one because `bd prime` +// opens a provider SCOPED to its read — prime is in noDbCommands, so the root +// pre-run opens nothing — and one spelling of "ask this provider for the memory +// surface" is the whole point of having an accessor at all. +func memoriesFromProvider(provider uow.UnitOfWorkProvider) (memoryops.Memories, error) { + src, ok := provider.(uow.MemoriesSource) + if !ok { + return nil, fmt.Errorf("proxied-server provider %T does not offer the persistent-memory surface", provider) + } + return src.Memories() +} + +// noteDirectMemoryWrite marks the invocation as having written, which is what +// the auto-commit epilogue in main.go keys on. +// +// It is DIRECT-ROUTE ONLY, and both halves of that matter. A direct memory +// write lands in the Dolt working set and nothing else commits it, so a verb +// that forgets to call this stores a memory that exists until the process exits +// and then sits uncommitted — visible to the session that wrote it and to +// nothing after. A proxied write already committed inside the role's unit of +// work, so flagging it there would ask the epilogue to commit a second time on +// a route with nothing outstanding. +// +// The RunEs cannot make that distinction themselves: openMemories hides which +// route they are on, which is the point. So the guard lives here, once, the way +// noteDirectConfigWrite does for the settings plane. +func noteDirectMemoryWrite() { + if !usesProxiedServer() { + commandDidWrite.Store(true) + } +} + // memoryPrefix is prepended (after kvPrefix) to all memory keys. const memoryPrefix = kvkeys.MemoryPrefix // memoryKeyFlag allows explicit key override for bd remember. var memoryKeyFlag string -// slugify converts a string to a URL-friendly slug for use as a memory key. -// Takes the first ~8 words, lowercases, replaces non-alphanumeric with hyphens. -func slugify(s string) string { - s = strings.ToLower(s) - // Replace non-alphanumeric chars with hyphens - re := regexp.MustCompile(`[^a-z0-9]+`) - s = re.ReplaceAllString(s, "-") - s = strings.Trim(s, "-") - - // Limit to first ~8 "words" (hyphen-separated segments) - parts := strings.SplitN(s, "-", 10) - if len(parts) > 8 { - parts = parts[:8] - } - slug := strings.Join(parts, "-") - - // Cap total length - if len(slug) > 60 { - slug = slug[:60] - // Don't end on a hyphen - slug = strings.TrimRight(slug, "-") - } - return slug -} - // matchesKnownCommand reports whether insight is a single bare word that // matches the name or an alias of a top-level bd command. It is used to catch // `bd remember ` mistakes before they become accidental memories. @@ -69,9 +108,9 @@ func matchesKnownCommand(cmd *cobra.Command, insight string) (string, bool) { // rememberBareKeyPath implements the desire-path / footgun guard for // `bd remember ` (no --key): a bare slug naming an EXISTING memory -// is recalled instead of stored; a bare slug naming nothing is refused. -// Shared by the classic and proxied-server paths. The caller only invokes it -// when memoryKeyFlag == "" and slugify(insight) == insight. +// is recalled instead of stored; a bare slug naming nothing is refused. The +// caller only invokes it when memoryKeyFlag == "" and the insight round-trips +// through memoryapi.DeriveKey unchanged, having already read the key. func rememberBareKeyPath(key, insight, existing string) error { if existing != "" { if jsonOutput { @@ -95,8 +134,7 @@ func rememberBareKeyPath(key, insight, existing string) error { key, insight, key) } -// printRememberResult renders the `bd remember` success output. Shared by -// the classic and proxied-server paths. +// printRememberResult renders the `bd remember` success output. func printRememberResult(verb, key, insight string) error { if jsonOutput { return outputJSON(map[string]string{ @@ -109,34 +147,7 @@ func printRememberResult(verb, key, insight string) error { return nil } -// memoriesFromConfig filters a full config map down to the kv.memory.* -// namespace (stripping the prefix), optionally filtered by a lowercase -// search term matched against key or value. Shared by the classic and -// proxied-server paths. -func memoriesFromConfig(allConfig map[string]string, search string) map[string]string { - fullPrefix := kvkeys.MemoryConfigKeyPrefix - memories := make(map[string]string) - for k, v := range allConfig { - if strings.HasPrefix(k, fullPrefix) { - userKey := strings.TrimPrefix(k, fullPrefix) - memories[userKey] = v - } - } - if search != "" { - filtered := make(map[string]string) - for k, v := range memories { - if strings.Contains(strings.ToLower(k), search) || - strings.Contains(strings.ToLower(v), search) { - filtered[k] = v - } - } - memories = filtered - } - return memories -} - -// printMemoriesResult renders the `bd memories` output. Shared by the -// classic and proxied-server paths. +// printMemoriesResult renders the `bd memories` output. func printMemoriesResult(memories map[string]string, search string) error { if jsonOutput { return outputJSON(memories) @@ -171,7 +182,7 @@ func printMemoriesResult(memories map[string]string, search string) error { } // printForgetNotFound renders the `bd forget` missing-key output (including -// the SilentExit contract). Shared by the classic and proxied-server paths. +// the SilentExit contract). func printForgetNotFound(key string) error { if jsonOutput { if jerr := outputJSON(map[string]string{ @@ -186,8 +197,7 @@ func printForgetNotFound(key string) error { return SilentExit() } -// printForgetResult renders the `bd forget` success output. Shared by the -// classic and proxied-server paths. +// printForgetResult renders the `bd forget` success output. func printForgetResult(key, existing string) error { if jsonOutput { return outputJSON(map[string]string{ @@ -200,7 +210,7 @@ func printForgetResult(key, existing string) error { } // printRecallResult renders the `bd recall` output (including the not-found -// SilentExit contract). Shared by the classic and proxied-server paths. +// SilentExit contract). func printRecallResult(key, value string) error { if jsonOutput { if jerr := outputJSON(map[string]interface{}{ @@ -257,9 +267,6 @@ Examples: }() insight := args[0] - if strings.TrimSpace(insight) == "" { - return HandleErrorRespectJSON("memory content cannot be empty") - } // Guard against a subcommand-like first argument being silently stored // as memory content. `bd remember` is a leaf command, so a mistaken @@ -268,6 +275,11 @@ Examples: // intended (GH#4401). A genuine insight is a phrase, so only a single // bare word that matches a known command is treated as suspect, and an // explicit --key signals deliberate intent and bypasses the guard. + // + // It stays at the FRONT DOOR and stays FIRST: it reads the cobra command + // tree, which no role can see, and it must answer before any storage is + // opened so that `bd remember list` in a directory with no workspace + // still says "looks like a command". if memoryKeyFlag == "" { if name, ok := matchesKnownCommand(cmd, insight); ok { return HandleErrorWithHintRespectJSON( @@ -277,52 +289,63 @@ Examples: } } - // Generate or use provided key - key := memoryKeyFlag - if key == "" { - key = slugify(insight) - } - if key == "" { - return HandleErrorRespectJSON("could not generate key from content; use --key to specify one") - } - - if usesProxiedServer() { - return runRememberProxiedServer(rootCtx, key, insight) - } - - if err := ensureDirectMode("remember requires direct database access"); err != nil { + memories, err := openMemories("remember requires direct database access") + if err != nil { return HandleError("%v", err) } - storageKey := kvPrefix + memoryPrefix + key - - ctx := rootCtx - - existing, _ := store.GetConfig(ctx, storageKey) - verb := "Remembered" - if existing != "" { - verb = "Updated" - } - // Desire path + footgun guard: `bd remember ` is a WRITE whose positional arg is // the CONTENT, not a key -- but "remember X" reads as a getter in English, so agents // routinely type `bd remember some-key` meaning "do you remember X?". The tell-tale of - // a mistyped read is content that round-trips through slugify unchanged (a bare slug); - // real prose insights never do. When that happens and no explicit --key was given: + // a mistyped read is content that round-trips through the key derivation unchanged (a + // bare slug); real prose insights never do. When that happens and no explicit --key was + // given: // - the key EXISTS -> pave the desire path: recall it instead of writing // - no such key -> refuse; storing a key-like token as its own content would // create a junk memory that hides the mistake // Passing --key states write intent and bypasses both branches. - if memoryKeyFlag == "" && slugify(insight) == insight { - return rememberBareKeyPath(key, insight, existing) + // + // It stays ABOVE the role because it decides WHETHER TO WRITE AT ALL, and + // because it exists to disambiguate English: an HTTP POST is not ambiguous + // and must not inherit it. The read below is a plain Recall, so this whole + // branch touches nothing. + // + // `derived != ""` is load-bearing and is not decoration: DeriveKey("") + // is "", so without it every empty or unslugifiable insight would satisfy + // derived == insight and be routed into a "recall" of the empty key. The + // shipped code was saved from that by an empty-content check that ran + // first; that check is the role's now, so the condition has to say it. + derived := memoryapi.DeriveKey(insight) + if memoryKeyFlag == "" && derived != "" && derived == insight { + recalled, err := memories.Recall(rootCtx, memoryops.RecallRequest{Key: derived}) + if err != nil { + return HandleErrorRespectJSON("recalling memory: %v", err) + } + return rememberBareKeyPath(derived, insight, recalled.Value) } - if err := store.SetConfig(ctx, storageKey, insight); err != nil { + result, err := memories.Remember(rootCtx, memoryops.RememberRequest{Key: memoryKeyFlag, Content: insight}) + if err != nil { + // The role's two refusals ARE this command's shipped sentences — + // "memory content cannot be empty" and "could not generate key from + // content; use --key to specify one" — so they print as themselves. + // Wrapping would reword output an agent may be matching on into + // "storing memory: validation failed: ..." to say the same thing. + if errors.Is(err, memoryops.ErrValidation) { + return HandleErrorRespectJSON("%s", strings.TrimPrefix(err.Error(), memoryops.ErrValidation.Error()+": ")) + } return HandleErrorRespectJSON("storing memory: %v", err) } - commandDidWrite.Store(true) + noteDirectMemoryWrite() - return printRememberResult(verb, key, insight) + // Remembered versus Updated is Replaced, observed in the SAME + // transaction as the write. The shipped code read the row first and + // described a moment that had already passed. + verb := "Remembered" + if result.Replaced { + verb = "Updated" + } + return printRememberResult(verb, result.Key, result.Value) }, } @@ -350,24 +373,27 @@ Examples: var search string if len(args) > 0 { - search = strings.ToLower(args[0]) + search = args[0] } - if usesProxiedServer() { - return runMemoriesProxiedServer(rootCtx, search) - } - - if err := ensureDirectMode("memories requires direct database access"); err != nil { + memories, err := openMemories("memories requires direct database access") + if err != nil { return HandleError("%v", err) } - - ctx := rootCtx - allConfig, err := store.GetAllConfig(ctx) + // The term goes to the role RAW. Case folding is List's, so the two + // routes cannot come to disagree about what matches — which is the + // whole reason the filter moved down. + result, err := memories.List(rootCtx, memoryops.ListRequest{Search: search}) if err != nil { return HandleErrorRespectJSON("listing memories: %v", err) } - return printMemoriesResult(memoriesFromConfig(allConfig, search), search) + // The ECHO, on the other hand, has always been lowercased: `bd memories + // FOO` prints `No memories matching "foo"`. It is a wart — a front door + // should say back what the user typed — but it is shipped output, and + // this commit is a convergence, not a change. Fixing it is a one-liner + // with its own test, like truncateMemory's rune splitting. + return printMemoriesResult(result.Memories, strings.ToLower(search)) }, } @@ -396,31 +422,23 @@ Examples: } }() - key := args[0] - - if usesProxiedServer() { - return runForgetProxiedServer(rootCtx, key) - } - - if err := ensureDirectMode("forget requires direct database access"); err != nil { + memories, err := openMemories("forget requires direct database access") + if err != nil { return HandleError("%v", err) } - - storageKey := kvPrefix + memoryPrefix + key - - ctx := rootCtx - - existing, _ := store.GetConfig(ctx, storageKey) - if existing == "" { - return printForgetNotFound(key) - } - - if err := store.DeleteConfig(ctx, storageKey); err != nil { + // No pre-read here, deliberately: the value printed below is the one + // the role's transaction actually deleted, not the one an earlier read + // happened to see. + result, err := memories.Forget(rootCtx, memoryops.ForgetRequest{Key: args[0]}) + if err != nil { return HandleErrorRespectJSON("forgetting memory: %v", err) } - commandDidWrite.Store(true) + if !result.Found { + return printForgetNotFound(result.Key) + } + noteDirectMemoryWrite() - return printForgetResult(key, existing) + return printForgetResult(result.Key, result.Value) }, } @@ -445,25 +463,16 @@ Examples: } }() - key := args[0] - - if usesProxiedServer() { - return runRecallProxiedServer(rootCtx, key) - } - - if err := ensureDirectMode("recall requires direct database access"); err != nil { + memories, err := openMemories("recall requires direct database access") + if err != nil { return HandleError("%v", err) } - - storageKey := kvPrefix + memoryPrefix + key - - ctx := rootCtx - value, err := store.GetConfig(ctx, storageKey) + result, err := memories.Recall(rootCtx, memoryops.RecallRequest{Key: args[0]}) if err != nil { return HandleErrorRespectJSON("recalling memory: %v", err) } - return printRecallResult(key, value) + return printRecallResult(result.Key, result.Value) }, } diff --git a/cmd/bd/memory_embedded_test.go b/cmd/bd/memory_embedded_test.go index 8b349a155..694a7200f 100644 --- a/cmd/bd/memory_embedded_test.go +++ b/cmd/bd/memory_embedded_test.go @@ -6,11 +6,38 @@ import ( "fmt" "os" "os/exec" + "path/filepath" "strings" "sync" "testing" + + "github.com/steveyegge/beads/internal/configfile" + "github.com/steveyegge/beads/internal/storage/embeddeddolt" ) +// countMemoryDoltCommits reads dolt_log for an embedded workspace. It is how +// the auto-commit epilogue is observed: a direct-route write that never flags +// it still answers `bd recall` perfectly well, because the row is in the +// working set — dolt_log is the only place the difference shows. +func countMemoryDoltCommits(t *testing.T, beadsDir string) int { + t.Helper() + cfg, _ := configfile.Load(beadsDir) + database := "" + if cfg != nil { + database = cfg.GetDoltDatabase() + } + db, cleanup, err := embeddeddolt.OpenSQL(t.Context(), filepath.Join(beadsDir, "embeddeddolt"), database, "main") + if err != nil { + t.Fatalf("OpenSQL: %v", err) + } + defer cleanup() + var count int + if err := db.QueryRowContext(t.Context(), "SELECT COUNT(*) FROM dolt_log").Scan(&count); err != nil { + t.Fatalf("query dolt_log: %v", err) + } + return count +} + // bdRemember runs "bd remember" with the given args and returns stdout. func bdRemember(t *testing.T, bd, dir string, args ...string) string { t.Helper() @@ -183,6 +210,30 @@ func TestEmbeddedMemory(t *testing.T) { bdRecallFail(t, bd, dir, "brand-new-slug-memory") }) + // The two refusals that sit either side of the desire path, and the reason + // the bare-slug test is `derived != "" && derived == insight` rather than + // the shipped `slugify(insight) == insight`: DeriveKey("") is "", so empty + // and underivable content satisfies derived == insight and would be routed + // into a "recall" of the empty key instead of being refused. The shipped + // code was saved from that by an empty-content check that ran BEFORE the + // branch; that check belongs to the role now, so the branch has to exclude + // the empty key itself. + t.Run("remember_refuses_content_no_key_derives_from", func(t *testing.T) { + for _, tc := range []struct{ insight, want string }{ + {"", "memory content cannot be empty"}, + {" ", "memory content cannot be empty"}, + {"!!!", "could not generate key from content"}, + } { + out := bdRememberFail(t, bd, dir, tc.insight) + if !strings.Contains(out, tc.want) { + t.Errorf("bd remember %q: expected %q, got: %s", tc.insight, tc.want, out) + } + if strings.Contains(out, "a bare existing key READS") || strings.Contains(out, "no memory named") { + t.Errorf("bd remember %q took the bare-slug desire path, got: %s", tc.insight, out) + } + } + }) + t.Run("remember_new_slug_with_explicit_key_stores", func(t *testing.T) { // --key states write intent: slug-like content stores fine. bdRemember(t, bd, dir, "brand-new-slug-memory", "--key", "brand-new-slug-memory") @@ -229,6 +280,47 @@ func TestEmbeddedMemory(t *testing.T) { bdRecallFail(t, bd, dir, "forget-me") }) + // THE AUTO-COMMIT EPILOGUE, which is the trap this convergence was most + // likely to spring. A direct-route write lands in the Dolt WORKING SET and + // nothing else commits it: durability is the epilogue in main.go, keyed on + // commandDidWrite, which noteDirectMemoryWrite is the only thing that sets + // for this plane. A converged RunE that forgets it produces memories that + // exist until the process exits and then sit uncommitted — and every other + // assertion in this file still passes, because a working-set row recalls + // and lists exactly like a committed one. + // + // Its own workspace, so the counts are deterministic (the pattern + // close_multiple_ids_single_dolt_commit uses). + t.Run("write_verbs_flag_the_auto_commit_epilogue", func(t *testing.T) { + edir, ebeads, _ := bdInit(t, bd, "--prefix", "ep") + + // Warm-up write: a fresh workspace's first command may commit + // bookkeeping of its own, which is not what this is measuring. + bdRemember(t, bd, edir, "warm the workspace up", "--key", "epilogue-warmup") + + before := countMemoryDoltCommits(t, ebeads) + bdRemember(t, bd, edir, "the epilogue is what makes a direct write durable", "--key", "epilogue-subject") + afterRemember := countMemoryDoltCommits(t, ebeads) + if got := afterRemember - before; got != 1 { + t.Errorf("bd remember: dolt_log %d -> %d (delta %d), want exactly one auto-commit", before, afterRemember, got) + } + + bdForget(t, bd, edir, "epilogue-subject") + afterForget := countMemoryDoltCommits(t, ebeads) + if got := afterForget - afterRemember; got != 1 { + t.Errorf("bd forget: dolt_log %d -> %d (delta %d), want exactly one auto-commit", afterRemember, afterForget, got) + } + + // A forget that found nothing deleted nothing, so it must leave no + // commit either — the other half of the contract, and the one a + // `noteDirectMemoryWrite()` placed before the not-found branch would + // break while every output assertion stayed green. + bdForgetFail(t, bd, edir, "epilogue-subject") + if got := countMemoryDoltCommits(t, ebeads); got != afterForget { + t.Errorf("bd forget of an absent key: dolt_log %d -> %d, want no commit", afterForget, got) + } + }) + // ===== Error Cases ===== t.Run("recall_missing_key", func(t *testing.T) { diff --git a/cmd/bd/memory_proxied_integration_test.go b/cmd/bd/memory_proxied_integration_test.go index 72f2784cd..e62a4d73b 100644 --- a/cmd/bd/memory_proxied_integration_test.go +++ b/cmd/bd/memory_proxied_integration_test.go @@ -149,6 +149,22 @@ func TestProxiedServerMemory(t *testing.T) { if !strings.Contains(out, "looks like a command") { t.Errorf("expected command-word guard, got: %s", out) } + + // The two refusals either side of the desire path fire the same way + // here as on the direct route — one branch, one derivation, both + // routes. DeriveKey("") is "", so an insight nothing derives from + // would satisfy the bare-slug test and be READ instead of refused if + // the branch did not exclude the empty key. + for _, tc := range []struct{ insight, want string }{ + {"", "memory content cannot be empty"}, + {" ", "memory content cannot be empty"}, + {"!!!", "could not generate key from content"}, + } { + out = bdProxiedMemFail(t, bd, p.dir, "remember", tc.insight) + if !strings.Contains(out, tc.want) { + t.Errorf("bd remember %q: expected %q, got: %s", tc.insight, tc.want, out) + } + } }) t.Run("remember_creates_dolt_commit", func(t *testing.T) { diff --git a/cmd/bd/memory_proxied_server.go b/cmd/bd/memory_proxied_server.go deleted file mode 100644 index fe7dbc6f5..000000000 --- a/cmd/bd/memory_proxied_server.go +++ /dev/null @@ -1,121 +0,0 @@ -package main - -import ( - "context" - "fmt" - - "github.com/steveyegge/beads/internal/storage/uow" -) - -// Proxied-server handlers for the memory surface (`bd remember`, `bd -// memories`, `bd forget`, `bd recall`). Memories are a thin prefix layer -// (kv.memory.*) over the config table, so these mirror -// config_proxied_server.go / kv_proxied_server.go: one RunTx per write -// invocation with a real commit message, RunTxRead for reads. Validation and -// key derivation happen in the RunE before dispatch; presentation goes -// through the shared helpers in memory.go so output cannot drift from the -// classic path. Storage keys stay kv.memory. so export tooling picks -// memories up alongside the rest of the kv namespace. -// -// Error handling note: the underlying storage error is passed through %v -// unmodified — callers retry on the 'Merge conflict detected' / -// 'constraint violation, transaction rolled back' substrings, which must -// survive to the CLI surface. - -// memoryGetProxied reads one kv.memory.* value; mirrors the classic path's -// tolerant read (`existing, _ := store.GetConfig(...)`) where noted. -func memoryGetProxied(ctx context.Context, storageKey string) (string, error) { - return uow.RunTxRead(ctx, uowProvider, func(ctx context.Context, uw uow.UnitOfWork) (string, error) { - return uw.ConfigUseCase().GetConfig(ctx, storageKey) - }) -} - -func runRememberProxiedServer(ctx context.Context, key, insight string) error { - if uowProvider == nil { - return HandleErrorRespectJSON("proxied-server UOW provider not initialized") - } - - storageKey := kvPrefix + memoryPrefix + key - - // Classic path ignores the existence-check error; mirror that. - existing, _ := memoryGetProxied(ctx, storageKey) - verb := "Remembered" - if existing != "" { - verb = "Updated" - } - - // Desire path + footgun guard (see the classic RunE in memory.go): a bare - // slug with no --key is a mistyped READ — recall it if it exists, refuse - // to store it as its own content if it doesn't. No write happens on this - // branch, so it runs before the RunTx. - if memoryKeyFlag == "" && slugify(insight) == insight { - return rememberBareKeyPath(key, insight, existing) - } - - err := uow.RunTx(ctx, uowProvider, func(ctx context.Context, uw uow.UnitOfWork) (string, error) { - if err := uw.ConfigUseCase().SetConfig(ctx, storageKey, insight); err != nil { - return "", err - } - return fmt.Sprintf("bd: remember %s", key), nil - }) - if err != nil { - return HandleErrorRespectJSON("storing memory: %v", err) - } - - return printRememberResult(verb, key, insight) -} - -func runMemoriesProxiedServer(ctx context.Context, search string) error { - if uowProvider == nil { - return HandleErrorRespectJSON("proxied-server UOW provider not initialized") - } - - allConfig, err := uow.RunTxRead(ctx, uowProvider, func(ctx context.Context, uw uow.UnitOfWork) (map[string]string, error) { - return uw.ConfigUseCase().GetAllConfig(ctx) - }) - if err != nil { - return HandleErrorRespectJSON("listing memories: %v", err) - } - - return printMemoriesResult(memoriesFromConfig(allConfig, search), search) -} - -func runForgetProxiedServer(ctx context.Context, key string) error { - if uowProvider == nil { - return HandleErrorRespectJSON("proxied-server UOW provider not initialized") - } - - storageKey := kvPrefix + memoryPrefix + key - - // Classic path ignores the existence-check error; mirror that. - existing, _ := memoryGetProxied(ctx, storageKey) - if existing == "" { - return printForgetNotFound(key) - } - - err := uow.RunTx(ctx, uowProvider, func(ctx context.Context, uw uow.UnitOfWork) (string, error) { - if err := uw.ConfigUseCase().DeleteConfig(ctx, storageKey); err != nil { - return "", err - } - return fmt.Sprintf("bd: forget %s", key), nil - }) - if err != nil { - return HandleErrorRespectJSON("forgetting memory: %v", err) - } - - return printForgetResult(key, existing) -} - -func runRecallProxiedServer(ctx context.Context, key string) error { - if uowProvider == nil { - return HandleErrorRespectJSON("proxied-server UOW provider not initialized") - } - - storageKey := kvPrefix + memoryPrefix + key - value, err := memoryGetProxied(ctx, storageKey) - if err != nil { - return HandleErrorRespectJSON("recalling memory: %v", err) - } - - return printRecallResult(key, value) -} diff --git a/cmd/bd/prime.go b/cmd/bd/prime.go index c1cbcc7e1..94ec1f67c 100644 --- a/cmd/bd/prime.go +++ b/cmd/bd/prime.go @@ -17,6 +17,7 @@ import ( internalbeads "github.com/steveyegge/beads/internal/beads" "github.com/steveyegge/beads/internal/config" "github.com/steveyegge/beads/internal/metrics" + "github.com/steveyegge/beads/memoryops" ) var ( @@ -421,8 +422,10 @@ func outputMemoriesOnlyContext(w io.Writer) error { return nil } -// formatMemoriesForPrime queries memories from the k/v store and formats them for injection. -// Returns empty string if no memories or if store is unavailable. +// formatMemoriesForPrime reads the memory plane through memoryops.Memories and +// formats it for injection. Returns empty string if no memories or if the plane +// is unavailable — prime degrades silently rather than failing a session-start +// hook, which is prime's presentation policy and not the role's. func formatMemoriesForPrime(compact bool) string { // bd-mm8wf: in a proxied-server workspace the memory read must ride the // proxied plane (UOW provider), never ensureStoreActiveForPrime — the @@ -452,20 +455,26 @@ func formatMemoriesForPrime(compact bool) string { if store == nil { return "" } - ctx := context.Background() - allConfig, err := store.GetAllConfig(ctx) + memories, err := store.Memories() if err != nil { return "" } - return renderPrimeMemoriesFromAllConfig(allConfig, compact) + result, err := memories.List(context.Background(), memoryops.ListRequest{}) + if err != nil { + return "" + } + return renderPrimeMemoryPlane(result.Memories, compact) } -// renderPrimeMemoriesFromAllConfig extracts the kv.memory.* entries from a -// full config-table read and renders them for injection — the shared tail of -// the classic and proxied (bd-mm8wf) memory-read paths, so the two cannot -// drift in what a memory looks like once fetched. -func renderPrimeMemoriesFromAllConfig(allConfig map[string]string, compact bool) string { - memories := memoriesFromConfig(allConfig, "") +// renderPrimeMemoryPlane renders the memory plane for injection — the shared +// tail of the classic and proxied (bd-mm8wf) memory-read paths, so the two +// cannot drift in what a memory looks like once fetched. +// +// It takes the PLANE, not a config map: which rows are memories is +// memoryops.Memories.List's answer now, on both routes, which is what stopped +// prime from being a fifth front door with its own copy of the kv.memory. +// prefix rule. +func renderPrimeMemoryPlane(memories map[string]string, compact bool) string { if len(memories) == 0 { return "" } diff --git a/cmd/bd/prime_proxied_server.go b/cmd/bd/prime_proxied_server.go index 2fba3cff5..7ff0ddc94 100644 --- a/cmd/bd/prime_proxied_server.go +++ b/cmd/bd/prime_proxied_server.go @@ -7,6 +7,7 @@ import ( "github.com/steveyegge/beads/internal/beads" "github.com/steveyegge/beads/internal/storage/uow" + "github.com/steveyegge/beads/memoryops" ) // Proxied-server dual of prime's memory read (bd-mm8wf, from lion's #5361 @@ -17,12 +18,13 @@ import ( // data, exactly the seam class bd-m7zzd closed in relate.go and human.go // (there in write verbs, here in a read-only limb). // -// The read now rides the proxied plane: one read-only UOW -// (ConfigUseCase().GetAllConfig, same verb the bd memories proxied dual -// uses), through a provider opened scoped to this read. Prime's contract is -// preserved on every failure edge: silent skip when the plane is unavailable, -// the timeout banner on a deadline, and rendering through the same shared -// tail as the classic path. +// The read rides the proxied plane: memoryops.Memories.List through the +// provider's own capability accessor, on a provider opened scoped to this read. +// It is the same call `bd memories` makes, which is what stopped prime from +// being a fifth front door with its own copy of the kv.memory. prefix rule. +// Prime's contract is preserved on every failure edge: silent skip when the +// plane is unavailable, the timeout banner on a deadline, and rendering through +// the same shared tail as the classic path. // primeProxiedProviderOpen opens the proxied-plane provider for prime's // memory read; a var so unit tests can stub the plane. Production opens the @@ -44,23 +46,23 @@ func formatMemoriesForPrimeProxied(compact bool) string { ctx, cancel = context.WithTimeout(ctx, timeout) defer cancel() } - allConfig, err := primeProxiedAllConfig(ctx) + plane, err := primeProxiedMemoryPlane(ctx) if err != nil { if errors.Is(err, context.DeadlineExceeded) || errors.Is(ctx.Err(), context.DeadlineExceeded) { return formatPrimeMemoryTimeout(compact, timeout) } return "" // Silently skip — proxied plane unavailable } - return renderPrimeMemoriesFromAllConfig(allConfig, compact) + return renderPrimeMemoryPlane(plane, compact) } -// primeProxiedAllConfig reads the full config table through the proxied -// plane. When the root pre-run opened the global provider (it never does for -// prime itself — noDbCommands — but the branch keeps any future caller -// honest), that provider is used and left open for its owner to close; +// primeProxiedMemoryPlane reads the memory plane through the proxied plane's +// own capability accessor. When the root pre-run opened the global provider (it +// never does for prime itself — noDbCommands — but the branch keeps any future +// caller honest), that provider is used and left open for its owner to close; // otherwise a provider is opened scoped to this one read and closed before // returning. -func primeProxiedAllConfig(ctx context.Context) (map[string]string, error) { +func primeProxiedMemoryPlane(ctx context.Context) (map[string]string, error) { provider := uowProvider if provider == nil { beadsDir := beads.FindBeadsDir() @@ -74,7 +76,13 @@ func primeProxiedAllConfig(ctx context.Context) (map[string]string, error) { defer func() { _ = p.Close(ctx) }() provider = p } - return uow.RunTxRead(ctx, provider, func(ctx context.Context, uw uow.UnitOfWork) (map[string]string, error) { - return uw.ConfigUseCase().GetAllConfig(ctx) - }) + memories, err := memoriesFromProvider(provider) + if err != nil { + return nil, err + } + result, err := memories.List(ctx, memoryops.ListRequest{}) + if err != nil { + return nil, err + } + return result.Memories, nil } diff --git a/cmd/bd/serve.go b/cmd/bd/serve.go index 99a993a46..aff3450bb 100644 --- a/cmd/bd/serve.go +++ b/cmd/bd/serve.go @@ -16,6 +16,7 @@ import ( "github.com/steveyegge/beads/internal/storage/contextinfo" "github.com/steveyegge/beads/internal/storage/domain" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) // serveCmdName is the command name, shared with the root command's post-run @@ -190,6 +191,7 @@ func runServe() error { Sweeper: roles.sweeper, Deleter: roles.deleter, BatchCreator: roles.batchCreator, + Memories: roles.memories, Workspace: info, SchemaVersion: JSONSchemaVersion, Mode: serveResolvedMode(info, db), @@ -443,6 +445,7 @@ func serveIssueRoles(src storage.DoltStorage) (serveRoles, error) { {"sweeper", func() (err error) { roles.sweeper, err = src.Sweeper(); return }}, {"deleter", func() (err error) { roles.deleter, err = src.Deleter(); return }}, {"batch creator", func() (err error) { roles.batchCreator, err = src.BatchCreator(); return }}, + {"memories", func() (err error) { roles.memories, err = src.Memories(); return }}, } { if err := b.get(); err != nil { return serveRoles{}, fmt.Errorf("%s: %w", b.name, err) @@ -469,6 +472,10 @@ type serveRoles struct { sweeper issueops.Sweeper deleter issueops.Deleter batchCreator issueops.BatchCreator + // memories is the one role here that is not an issueops role: the memory + // plane is user data riding in the config table under its own merge class, + // so it has its own leaf package. + memories memoryops.Memories } // serveResolvedMode labels the topology for the startup log line. Cosmetic — diff --git a/cmd/bd/serve_proxied_integration_test.go b/cmd/bd/serve_proxied_integration_test.go index 098db92bf..bf4514705 100644 --- a/cmd/bd/serve_proxied_integration_test.go +++ b/cmd/bd/serve_proxied_integration_test.go @@ -234,6 +234,7 @@ func TestProxiedServerServeLifecycle(t *testing.T) { "dependencies.blocking", "dependencies.cycles", "dependencies.list", "dependencies.tree", "issues.batchCreate", "issues.claim", "issues.delete", "issues.get", "issues.list", "issues.query", "issues.sweep", + "memories.forget", "memories.get", "memories.list", "memories.remember", "ready.count", "ready.list", "stats.get", } if !reflect.DeepEqual(caps, want) { diff --git a/cmd/bd/serve_source_test.go b/cmd/bd/serve_source_test.go index 6e7dd5835..de27ad1fa 100644 --- a/cmd/bd/serve_source_test.go +++ b/cmd/bd/serve_source_test.go @@ -12,6 +12,7 @@ import ( "github.com/steveyegge/beads/internal/storage" "github.com/steveyegge/beads/internal/storage/domain" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) // TestServeDatabaseSourceClassifiesTheWorkspace drives the one decision point @@ -207,6 +208,7 @@ func (*serveRolesStore) Querier() (issueops.Querier, error) func (*serveRolesStore) Sweeper() (issueops.Sweeper, error) { return nil, nil } func (*serveRolesStore) Deleter() (issueops.Deleter, error) { return nil, nil } func (*serveRolesStore) BatchCreator() (issueops.BatchCreator, error) { return nil, nil } +func (*serveRolesStore) Memories() (memoryops.Memories, error) { return nil, nil } type serveStubReader struct{} diff --git a/cmd/bd/serve_store_identity_test.go b/cmd/bd/serve_store_identity_test.go index 299fc11f8..3416125d2 100644 --- a/cmd/bd/serve_store_identity_test.go +++ b/cmd/bd/serve_store_identity_test.go @@ -20,6 +20,7 @@ import ( "github.com/steveyegge/beads/internal/storage/backends" "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) // TestServeAnswersFromTheStoreTheRootCommandOpened pins the one property this @@ -204,8 +205,11 @@ func (*serveIdentityStore) Deleter() (issueops.Deleter, error) { return serveIde func (*serveIdentityStore) BatchCreator() (issueops.BatchCreator, error) { return serveIdentityRole{}, nil } +func (*serveIdentityStore) Memories() (memoryops.Memories, error) { + return serveIdentityRole{}, nil +} -// serveIdentityRole satisfies all eleven at once, which it can because no two +// serveIdentityRole satisfies all twelve at once, which it can because no two // of those interfaces declare a method of the same name. If a future role // collides, split this into one type per role — the embedded method would stop // being promoted and the build would say so. @@ -221,6 +225,7 @@ type serveIdentityRole struct { issueops.Sweeper issueops.Deleter issueops.BatchCreator + memoryops.Memories } type serveIdentityReader struct{ id string } diff --git a/engdocs/ADDING_AN_ISSUEOPS_ROLE.md b/engdocs/ADDING_AN_ISSUEOPS_ROLE.md index cbe4cbfa4..2ed97d56b 100644 --- a/engdocs/ADDING_AN_ISSUEOPS_ROLE.md +++ b/engdocs/ADDING_AN_ISSUEOPS_ROLE.md @@ -7,7 +7,9 @@ new accessor. Never append a method to an existing role.** That rule is why What the rule does not say is what a new role COSTS. This page is the measured answer, derived from `issueops.Counter` — the first role added under the rule, and the one every later role commit follows. Nothing here is aspirational: each -item names a file that exists in that commit. +item names a file that exists in that commit. The last section is for the rarer +case: a capability that does not belong in `issueops` at all, which +`memoryops` was the first of. ## Is it a role at all? @@ -278,3 +280,123 @@ MEANS, and the parts every later reader trusts. - **Three wirings are not three votes.** dolt and embeddeddolt share step 3. Say "two independent bodies plus an engine check" in the commit message, not "three backends agree". + +## The second namespace + +`memoryops.Memories` is the first role in a leaf that is NOT `issueops`: the +`kv.memory.*` plane behind `bd remember`, `bd recall`, `bd forget`, +`bd memories` and `bd prime`'s injection. Steps 1-11 transferred without +argument — same accessor on `storage.Storage`, same two decorators declared +rather than inherited, same three wirings over two independent bodies. What +follows is only where the second namespace had to DECIDE instead of copy, +because that is the list a third one inherits, and each of these reads like a +convention until you notice it was situational. + +**Alias the sentinels; do not mint a second vocabulary.** `memoryops/errors.go` +is one line of declaration — `var ErrValidation = issueops.ErrValidation` +(:16) — and the IDENTITY is the entire point. `errors.Is` against that one +value is what the HTTP problem classifier, `cmd/bd`'s error handling and every +conformance contract already do. A `memoryops`-flavored twin would be a +different value meaning the same thing, so all of those sites would have to +match both forever; and the cost is not the double-match, it is the site that +adds only the first arm and classifies a validation refusal as an internal +error. Re-exporting rather than telling callers to reach through `issueops` is +the other half: code holding only `Memories` can classify a refusal without +knowing the issue package exists. + +That import is the leaf's only non-stdlib one, and it makes step 1's rule +NARROWER here rather than wider — a memory is a string under a string key, so +nothing in `internal/types` is needed and importing it would invite +issue-shaped types into a plane that has none. Say that in the package doc, +along with the fact that `internal/types` still arrives transitively through +`issueops` (`memoryops/doc.go:27-35`): it looks like a dependency, it is an +artifact of the alias, and the obvious "fix" for it is to copy the sentinel. + +The open question is a THIRD namespace's to answer, not to inherit. Two +namespaces sharing one vocabulary by alias is right. At three, the shared +sentinels probably want their own tiny leaf that all of them re-export from — +and that move is CHEAP BEFORE the third namespace exists and expensive after, +because by then every `errors.Is` site in the tree points at the `issueops` +value and either the new leaf aliases backwards or every site moves at once. + +**No `.golangci.yml` entry, and that is not an omission.** `memoryops` adds +nothing to the `cmd-bd-role-constructors` deny list because there is nothing to +deny: the role needs one transaction for probe-and-act, so step 3 moved DOWN +into `internal/storage/memoryops`, where every function takes a `*sql.Tx` that +no front door holds (`internal/storage/memoryops/memories.go:15-18`). Step 3's +address is what decides the entry, so a namespace of tx-level bodies has no +entries at all, and the absence has to be readable as a decision rather than as +a step someone skipped. + +The test: **does step 3 have an exported constructor returning the role +interface, in a package a `cmd/bd` file can import?** +`internal/workapi/store` does, so it gets an entry. A `…InTx` function +does not. What the test is NOT is "does the namespace have a package below the +role" — `internal/memoryapi` is exactly that, holds `DeriveKey`, the two +refusals and the search filter, and is deliberately importable from `cmd/bd` +(`internal/memoryapi/memoryapi.go:7-13`), +because the `bd remember` front door has to derive a key to recognize the +bare-slug case before it knows which method to call. Denying the meaning layer +would be denying step 2, which every role depends on being reachable. +Constructors are the boundary; meaning functions are not. + +**A miss is a RESULT FIELD, not `ErrNotFound`, because of a fact about the +substrate.** `RecallResult.Found` and `ForgetResult.Found` carry the miss and +the front doors translate — the CLI to its SilentExit contract, HTTP to its 404 +(`memoryops/errors.go:18-29`). The reason is checkable and it is not taste: the +config table this plane rides in CANNOT DISTINGUISH AN ABSENT ROW FROM A ROW +STORED AS THE EMPTY STRING, which `issueops/workspaceconfig.go:42-46` already +states for settings over the same seam. A role answering `ErrNotFound` would be +minting an error out of a distinction it cannot see, and the first out-of-band +empty write turns that error into a lie. The honest, weaker promise is what +shipped: `Found` is `Value != ""`, an empty row and no row are the same answer, +and `List` still enumerates the empty row because its KEY exists — the one way +a caller can tell them apart, stated at `memoryops/memories.go:63-72` and +pinned by a case. + +The next namespace should re-run the check rather than copy the conclusion: ask +whether YOUR seam can tell absent from zero-valued. If it can — a NOT NULL +column, a distinct id, a row a delete actually removes — then `ErrNotFound` is +honest and a result-carried `Found` is just a second spelling of it. The shape +follows the substrate, and the substrate is the thing to cite. + +**One promise the contract declares UNPINNABLE rather than faking.** Every +implementation promises that the existence probe and the act it qualifies +happen in ONE transaction; that is why step 3 moved down, and it is what makes +`Replaced` and the value `bd forget` prints true statements instead of hopeful +ones. The contract does not test it, and SAYS SO, in the file header beside the +vote count (`backend/conformance/memories_contract.go:51-57`). + +The promise is structural, not black-box observable. A single-threaded case +cannot falsify it — one transaction and two produce identical answers when +nothing else is writing — and a concurrent case would be flaky at three +engines, which buys a red suite people learn to re-run rather than a guarantee. +What pins it instead is the SHAPE of the bodies: there is no two-call +composition to regress into without deleting the `…InTx` functions. A green +single-threaded case named after the promise would have been strictly worse +than nothing, because a reviewer greps for the promise, finds a test named for +it, and stops looking. So state the promise in the contract's coverage +paragraph, name the mechanism that actually holds it, and name the probe that +would upgrade it (here: a transaction-counting seam on the fixture kit). Do not +fake it with sleeps. + +**And one trap the second namespace hit that a third will.** +`memoryops.Memories.List` and `issueops.Reader.List` are ONE METHOD NAME WITH +TWO SIGNATURES, so no single Go type satisfies both, and the shared sentinel +that stood in for every role in both `role_accessor_decorator_test.go` files +could not implement the new one. Each file needed a second sentinel type +(`internal/storage/role_accessor_decorator_test.go:302`, +`internal/telemetry/role_accessor_decorator_test.go:252`). That part is +mechanical and the compiler drives it. + +What is not mechanical is what the split does to the telemetry table, whose +rows fail on `surface == test.inner` — the accessor that recurses +(`return s.Unwrap().Memories()`) instead of wrapping, dropping every span and +timing on the role. Every row compared against one implied sentinel, so a +memories row written the same way would have compared the memory surface +against the ISSUE sentinel: a value it can never equal, wrapped or not. Green +forever, including against the exact regression the table exists for. The rows +now carry a per-row `inner` comparand naming the surface each one must not be +(`internal/telemetry/role_accessor_decorator_test.go:279-282`). **A shared test +fixture a new namespace cannot satisfy is a signal: the row you add beside it +may be a row that cannot fail.** diff --git a/internal/httpapi/apigen/types.gen.go b/internal/httpapi/apigen/types.gen.go index c9a3fee4d..45f7fd88a 100644 --- a/internal/httpapi/apigen/types.gen.go +++ b/internal/httpapi/apigen/types.gen.go @@ -214,7 +214,7 @@ type ContextResponse struct { // BeadsDir Absolute path of the served workspace's `.beads` directory. A host path, kept because it is the single-workspace server's only workspace-identity handshake; disclosing it to network peers is part of what an operator accepts when binding beyond loopback. BeadsDir string `json:"beads_dir"` - // Capabilities The operations this server actually implements, derived from its route table. v0's vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.get`, `issues.claim`, `issues.sweep`, `issues.delete`, `issues.batchCreate`, `stats.get`, `config.list`, `config.get`, `dependencies.cycles`, `dependencies.list`, `dependencies.blocking`, `dependencies.tree`; it grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation — never the version string. + // Capabilities The operations this server actually implements, derived from its route table. v0's vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.get`, `issues.claim`, `issues.sweep`, `issues.delete`, `issues.batchCreate`, `stats.get`, `config.list`, `config.get`, `dependencies.cycles`, `dependencies.list`, `dependencies.blocking`, `dependencies.tree`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`; it grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation — never the version string. Capabilities []string `json:"capabilities"` // Database Logical database name (not a host or a DSN). @@ -369,6 +369,33 @@ type IssuesPage struct { NextCursor *string `json:"next_cursor,omitempty"` } +// MemoriesPage defines model for MemoriesPage. +type MemoriesPage struct { + // HasMore Always false in v0: the whole plane is returned in one page. It is present so that a later revision can page this collection without changing the response shape. + HasMore bool `json:"has_more"` + + // Items The stored memories, ordered by key. Empty array (never null) when the workspace holds none, or when `q` matched none. + Items []Memory `json:"items"` + + // NextCursor Present if and only if `has_more` is true, which is never in v0. + NextCursor *string `json:"next_cursor,omitempty"` +} + +// Memory One entry of the workspace's persistent memory plane. +// +// NOT `x-go-type`-PINNED, for the reason `Setting` is not: the CLI marshals an ad-hoc map per verb, so there is no canonical Go struct whose JSON encoding is this contract, and minting one to pin to would mean changing what `bd recall --json` prints in order to satisfy a rule about not changing it. +// +// IT HAS NO `redacted` MEMBER, and that is the deliberate difference from `Setting`. Redaction there is a decision about the KEY NAME, which works because settings keys are configured names; memory keys are derived from the content, so the same rule would withhold a memory about credentials and serve one containing a credential under an innocuous slug. This surface has no authentication and states the exposure rather than implying a protection it does not have. +type Memory struct { + // Key The memory's key, echoed verbatim. + Key string `json:"key"` + + // Value The stored content, verbatim: newlines, surrounding space and unicode as stored, never truncated and never withheld. + // + // Always present. It is the empty string only where a row was written out of band with an empty value, which `GET /v0/beads/memories/{key}` answers as a `404` and `GET /v0/beads/memories` enumerates. + Value string `json:"value"` +} + // Problem RFC 9457 problem detail. This is the only error shape on this surface. The core declares `type`; this server never emits it, so `about:blank` is implied throughout. type Problem struct { // Assignee With `already_claimed`: the actor currently holding the issue. @@ -428,6 +455,35 @@ type ReadyPage struct { Items []IssueWithCounts `json:"items"` } +// RememberRequest What to remember, and optionally under what key. +type RememberRequest struct { + // Content The memory itself, stored VERBATIM: newlines, surrounding space and unicode all survive. Flattening it to one line is what a front door does when it prints, not what this plane does when it stores. + // + // Empty after trimming is a `400`. So is content from which no key can be derived when `key` is omitted — `"!!!"` derives to nothing — and the recovery for that one is to send a `key`. + Content string `json:"content"` + + // Key The key to store under. OMIT IT to have the server derive one from `content`; the response's `key` is then how the caller learns where the memory landed. + // + // Supplied, it is used verbatim — no trimming, no slugging, no charset restriction. A key carrying a control character is storable this way and by `bd remember --key`, and is then unreachable through `GET`/`DELETE /v0/beads/memories/{key}`, which refuse one: see those operations. + Key *string `json:"key,omitempty"` +} + +// RememberedMemory One stored memory, plus whether storing it overwrote a previous value. +// +// It is `Memory`'s shape with `replaced` added rather than a composition of it, because this document repeats property lists instead of using `allOf` (see the note at the top of the file). +type RememberedMemory struct { + // Key The key the memory now lives under: the one the request supplied, or the one derived from `content`. Recall it under exactly these bytes. + Key string `json:"key"` + + // Replaced True when a previous value existed under `key` and this request overwrote it; false when the key was new. It is observed in the same transaction as the write, so it describes the row this request wrote. + // + // A previous value that was the EMPTY STRING reports true: the ROW existed, even though `GET /v0/beads/memories/{key}` would have answered `404` for it. That divergence is the storage seam's conflation showing through, and it is stated rather than smoothed over, because smoothing it would mean this member reporting "nothing was there" about a write that overwrote something. + Replaced bool `json:"replaced"` + + // Value The stored content, echoed verbatim. Always present, and never withheld — this plane has no redaction; see the operation description. + Value string `json:"value"` +} + // Setting One entry of the workspace's stored settings plane. // // THIS SCHEMA IS DELIBERATELY NOT `x-go-type`-PINNED, and it is the only response component on this surface that is not. The seven pinned schemas above are pinned because a canonical Go struct already IS the contract — `types.Issue`'s JSON encoding is what `bd show --json` emits. A setting has no such struct: the CLI marshals an ad-hoc `map[string]string` per verb, so there is nothing to pin TO, and minting a type to pin to would mean changing what `bd config get --json` prints in order to satisfy a rule about not changing it. @@ -563,6 +619,9 @@ type TreeNode = types.TreeNode // IssueID defines model for IssueID. type IssueID = string +// MemoryKey defines model for MemoryKey. +type MemoryKey = string + // SettingKey defines model for SettingKey. type SettingKey = string @@ -724,6 +783,16 @@ type QueryIssuesParams struct { // QueryIssuesParamsSort defines parameters for QueryIssues. type QueryIssuesParamsSort string +// ListMemoriesParams defines parameters for ListMemories. +type ListMemoriesParams struct { + // Search Narrows the answer to memories that MATCH: a memory matches when the lowercase of its key, or the lowercase of its value, contains the lowercase of this term. Absent or empty means everything, and a term nothing matches is a `200` with an empty `items`. + // + // IT IS A SUBSTRING MATCH, NOT THE `issues:query` EXPRESSION LANGUAGE, and it is spelled `search` rather than `q` FOR THAT REASON. On `GET /v0/beads/issues:query`, `q` is a boolean expression over issue fields that is refused when it does not parse; here there is nothing to parse, no vocabulary and no refusal — every string is a legal search term, `status=open` included, and it is matched literally. Two names because two questions: a client that sent this operation the other `q` would otherwise get a literal substring search back instead of an error. + // + // The term reaches the role UNFOLDED. Case folding is the role's, so that this surface and `bd memories` cannot come to disagree about what matching means; a client sends what its user typed. + Search *string `form:"search,omitempty" json:"search,omitempty"` +} + // ListReadyWorkParams defines parameters for ListReadyWork. type ListReadyWorkParams struct { // Assignee Only issues assigned to this actor. @@ -865,3 +934,6 @@ type DeleteIssuesJSONRequestBody = DeleteIssuesRequest // SweepIssuesJSONRequestBody defines body for SweepIssues for application/json ContentType. type SweepIssuesJSONRequestBody = SweepRequest + +// RememberMemoryJSONRequestBody defines body for RememberMemory for application/json ContentType. +type RememberMemoryJSONRequestBody = RememberRequest diff --git a/internal/httpapi/claim.go b/internal/httpapi/claim.go index 754ab75a4..15abf4aa7 100644 --- a/internal/httpapi/claim.go +++ b/internal/httpapi/claim.go @@ -17,6 +17,7 @@ import ( "github.com/steveyegge/beads/internal/storage/uow" "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) const ( @@ -367,6 +368,7 @@ var ( _ uow.SweeperSource = timedProvider{} _ uow.DeleterSource = timedProvider{} _ uow.BatchCreatorSource = timedProvider{} + _ uow.MemoriesSource = timedProvider{} ) // IssueReader builds the reader OVER THIS WRAPPER rather than delegating to the @@ -473,6 +475,13 @@ func (p timedProvider) BatchCreator() (issueops.BatchCreator, error) { return uow.NewBatchCreator(p) } +// Memories builds the persistent-memory role OVER THIS WRAPPER, for the same +// reason and with the same hazard as IssueReader. It is the one accessor here +// whose role is not an issueops role; the binding rule is the same. +func (p timedProvider) Memories() (memoryops.Memories, error) { + return uow.NewMemories(p) +} + func (p timedProvider) NewUOW(ctx context.Context) (uow.UnitOfWork, error) { start := time.Now() uw, err := p.inner.NewUOW(ctx) diff --git a/internal/httpapi/memories.go b/internal/httpapi/memories.go new file mode 100644 index 000000000..2bf3271c0 --- /dev/null +++ b/internal/httpapi/memories.go @@ -0,0 +1,348 @@ +package httpapi + +import ( + "encoding/json" + "errors" + "net/http" + "slices" + "strings" + + "github.com/steveyegge/beads/internal/httpapi/apigen" + "github.com/steveyegge/beads/memoryops" +) + +// The memory operations. Each one decodes its parameters, hands the whole +// request to the persistent-memory role, and shapes the answer onto the wire. +// +// WHAT IS NOT HERE, as in settings.go: no storage key is assembled, no key is +// derived from content, no search term is folded, no plane is filtered out of +// the config table this one shares. All of that is memoryops.Memories' +// implementation, which `bd remember` and `bd memories` reach through the same +// accessor — and the `kv.memory.` encoding in particular is deliberately +// invisible from here, because a second place that spelled the prefix would be +// a second place that could spell it wrong. +// +// THERE IS NO REDACTION ON THIS PLANE, and that is a decision rather than an +// omission. The settings surface withholds a value when the KEY NAME marks it +// credential-bearing; memory keys are derived from the content, so the same +// rule would withhold a memory about tokens and serve one that contains a token +// under an innocuous slug. Each operation's description states the exposure +// instead of making a promise this surface cannot keep. + +// The request body's member vocabulary. The schema is +// additionalProperties: false, so anything else is refused BY NAME, the same +// posture every other body-carrying operation here takes. +const ( + rememberContentMember = "content" + rememberKeyMember = "key" +) + +// rememberMembers is the whole vocabulary, in one place, so the unknown-member +// refusal and the decoding below cannot come to disagree about what this +// operation accepts. +var rememberMembers = []string{ + rememberContentMember, + rememberKeyMember, +} + +// handleRememberMemory answers POST /v0/beads/memories. +func (s *Server) handleRememberMemory(w http.ResponseWriter, r *http.Request) { + if !s.requireNoQuery(w, r) { + return + } + if !s.requireJSONContent(w, r) { + return + } + request, ok := s.rememberRequest(w, r) + if !ok { + return + } + + memories, err := s.memories(r) + if err != nil { + s.failErr(w, r, err) + return + } + result, err := memories.Remember(r.Context(), request) + if err != nil { + s.failMemoryErr(w, r, err) + return + } + writeJSON(w, apigen.RememberedMemory{ + Key: result.Key, + Value: result.Value, + Replaced: result.Replaced, + }) +} + +// memorySearchParam is the one query parameter this surface's memory plane +// takes, and it is deliberately NOT spelled `q`. +// +// `q` on GET /v0/beads/issues:query is a boolean expression over issue fields, +// with a vocabulary and a parse refusal; this is a substring match with +// neither. Spelling both `q` would let a client that assumed the other meaning +// send `status=open` and receive a literal search over memory text instead of +// an error — one surface answering two different questions to the same name. +// Under the second name that request is an unknown parameter, which is what it +// actually is. +const memorySearchParam = "search" + +// handleListMemories answers GET /v0/beads/memories. +func (s *Server) handleListMemories(w http.ResponseWriter, r *http.Request) { + // The one-parameter shape of the unknown-parameter rule. requireNoQuery is + // for operations that take NONE; this one takes exactly one, so it goes + // through the same query decoder every filtering read uses — which tracks + // what was read and refuses what was not, so the allowlist is the parameter + // table itself rather than a second copy of it that can drift. + q := newQuery(r.URL.Query()) + // str, not list: a repeated `search` is refused rather than silently + // resolved to one of its values, because a client that sent two terms asked + // a question this operation cannot answer and must not be told it did. + search := q.str(memorySearchParam) + if !s.acceptQuery(w, r, q) { + return + } + + memories, err := s.memories(r) + if err != nil { + s.failErr(w, r, err) + return + } + // The term goes in UNFOLDED and unparsed. Matching semantics are the role's + // — case folding included — so that this surface and `bd memories` cannot + // come to disagree about what a search means. + result, err := memories.List(r.Context(), memoryops.ListRequest{Search: search}) + if err != nil { + s.failMemoryErr(w, r, err) + return + } + + keys := make([]string, 0, len(result.Memories)) + for key := range result.Memories { + keys = append(keys, key) + } + // Ordered by key, which is what makes the paginated envelope honest: the + // order is stable across calls, so a keyset cursor over it is expressible + // later without changing what a client already receives. + slices.Sort(keys) + + items := make([]apigen.Memory, 0, len(keys)) + for _, key := range keys { + items = append(items, apigen.Memory{Key: key, Value: result.Memories[key]}) + } + writeJSON(w, apigen.MemoriesPage{Items: items, HasMore: false}) +} + +// handleGetMemory answers GET /v0/beads/memories/{key}. +func (s *Server) handleGetMemory(w http.ResponseWriter, r *http.Request) { + if !s.requireNoQuery(w, r) { + return + } + key, ok := s.memoryKey(w, r) + if !ok { + return + } + + memories, err := s.memories(r) + if err != nil { + s.failErr(w, r, err) + return + } + result, err := memories.Recall(r.Context(), memoryops.RecallRequest{Key: key}) + if err != nil { + s.failMemoryErr(w, r, err) + return + } + // A MISS IS A 404 HERE, and this is the one operation on this surface where + // that diverges from its settings counterpart. The rule both follow is that + // the status reports the distinctions the FRONT DOOR already reports, and + // the two front doors differ: `bd config get` on an absent key prints + // "(not set)" and exits 0, so getSetting has no 404 to give; `bd recall` on + // a miss prints to stderr and exits 1 (printRecallResult in cmd/bd, via + // SilentExit), and the role answers Found rather than a bare value, so the + // status here reports a distinction that exists rather than inventing one. + // + // A row stored as the EMPTY STRING falls on the miss side of it, because + // that is where the role puts it — the storage seam cannot tell it from an + // absent row, and this handler will not claim to see what the role cannot. + // listMemories enumerates such a row, which is the one way a client tells + // the two apart. + if !result.Found { + s.fail(w, r, MemoryNotFound()) + return + } + writeJSON(w, apigen.Memory{Key: result.Key, Value: result.Value}) +} + +// handleForgetMemory answers DELETE /v0/beads/memories/{key} — the third +// DESTRUCTIVE operation on this surface, and the only one that is a DELETE. +// +// WHAT THIS HANDLER DOES NOT DO is the point, as for the sweep and the delete. +// It does not assemble a storage key, does not decide which rows belong to the +// memory plane, and does not read the value it reports: all of that is inside +// memoryops.Memories, whose implementation removes exactly the named row in the +// same transaction that reads it. The memory plane shares one table with the +// workspace's settings and with the generic `bd kv` namespace, so a delete +// written here would be one prefix-length mistake away from erasing a +// workspace's issue prefix — which is why the role's conformance contract owns +// that promise and this file does not restate it. +func (s *Server) handleForgetMemory(w http.ResponseWriter, r *http.Request) { + if !s.requireNoQuery(w, r) { + return + } + key, ok := s.memoryKey(w, r) + if !ok { + return + } + + memories, err := s.memories(r) + if err != nil { + s.failErr(w, r, err) + return + } + result, err := memories.Forget(r.Context(), memoryops.ForgetRequest{Key: key}) + if err != nil { + s.failMemoryErr(w, r, err) + return + } + // Found false means NOTHING WAS REMOVED, which is a 404 on the same terms + // as the read beside it. It is a status rather than a 200 with an empty + // body because a client that retried a forget has to be able to tell "I + // removed this" from "there was nothing to remove", and the role already + // answers the difference. + if !result.Found { + s.fail(w, r, MemoryNotFound()) + return + } + writeJSON(w, apigen.Memory{Key: result.Key, Value: result.Value}) +} + +// memoryKey validates the path parameter and reports whether the request may +// proceed. It is settingKey's rules, deliberately unchanged, so the two keyed +// planes refuse the same shapes with the same `param` and the same `reason`. +// +// A control character is refused rather than looked up, because a +// percent-escape in the path decodes to one and a key carrying a newline could +// only have come from a client assembling paths by concatenation. THE ROLE +// STAYS VERBATIM: `bd remember --key` accepts any string, so such a memory can +// exist, and it stays reachable from the CLI and from the collection read. It +// is unreachable by path, and the document says so rather than this refusal +// being discovered. +// +// The refusal is a 400 and not the 404 beside it: the 404 says this workspace +// holds no such memory, which is a claim about storage that nothing here has +// asked storage about. +func (s *Server) memoryKey(w http.ResponseWriter, r *http.Request) (string, bool) { + key := r.PathValue("key") + switch { + case strings.TrimSpace(key) == "": + s.fail(w, r, InvalidArgument("key", ReasonInvalidValue, "`key` is empty after trimming")) + return "", false + case strings.ContainsFunc(key, isControlChar): + requestInfo(r.Context()).refuse(key) + s.fail(w, r, InvalidArgument("key", ReasonInvalidValue, "`key` must not contain control characters")) + return "", false + } + return key, true +} + +// rememberRequest decodes the body into the role's request, member by member, +// so that every refusal can NAME the member it is about. +// +// It validates the SHAPE and nothing else. Whether the content is empty, and +// whether a key can be derived from it, are the role's two refusals — routing +// them through the role is what keeps one definition of what a memory is, and +// it is what makes `bd remember` and this endpoint refuse the same inputs with +// the same sentences. +func (s *Server) rememberRequest(w http.ResponseWriter, r *http.Request) (memoryops.RememberRequest, bool) { + members, res := decodeJSONObjectBody(w, r) + if res != nil { + s.fail(w, r, *res) + return memoryops.RememberRequest{}, false + } + + var unknown []string + for name := range members { + if !slices.Contains(rememberMembers, name) { + unknown = append(unknown, name) + } + } + if len(unknown) > 0 { + // One offender, chosen deterministically so a client dispatching on + // `param` never sees it depend on map order. + offender := slices.Min(unknown) + requestInfo(r.Context()).refuse(offender) + s.fail(w, r, InvalidArgument(offender, ReasonUnknownParameter, + "this operation's request body carries "+rememberMemberList()+" and nothing else")) + return memoryops.RememberRequest{}, false + } + + var request memoryops.RememberRequest + + raw, ok := members[rememberContentMember] + if !ok { + s.fail(w, r, InvalidArgument(rememberContentMember, ReasonInvalidValue, + "`"+rememberContentMember+"` is required")) + return memoryops.RememberRequest{}, false + } + // Through a POINTER, so that `null` reaches the type-mismatch branch rather + // than unmarshaling as a no-op and being reported downstream as empty + // content — the right refusal attached to prose that misdescribes what the + // client sent. + var content *string + if err := json.Unmarshal(raw, &content); err != nil || content == nil { + s.fail(w, r, InvalidArgument(rememberContentMember, ReasonInvalidValue, + "`"+rememberContentMember+"` must be a string")) + return memoryops.RememberRequest{}, false + } + request.Content = *content + + if raw, ok := members[rememberKeyMember]; ok { + var key *string + if err := json.Unmarshal(raw, &key); err != nil || key == nil { + s.fail(w, r, InvalidArgument(rememberKeyMember, ReasonInvalidValue, + "`"+rememberKeyMember+"` must be a string")) + return memoryops.RememberRequest{}, false + } + // VERBATIM, deliberately: the role stores the bytes it is given, and a + // trim here would put a memory under a key the client cannot name. An + // absent member is the empty string, which is what tells the role to + // derive one. + request.Key = *key + } + + return request, true +} + +func rememberMemberList() string { + quoted := make([]string, len(rememberMembers)) + for i, name := range rememberMembers { + quoted[i] = "`" + name + "`" + } + return strings.Join(quoted, ", ") +} + +// failMemoryErr answers a failed memory operation. +// +// It draws the ErrValidation-is-a-400 line the sweep, delete, tree, edges and +// batch-create handlers each draw in their own handler, deliberately in the +// same shape: this role performs request validation the handler does not +// duplicate, and widening ClassifyError instead would change what every other +// operation returns for an error it has never produced. +// +// memoryops.ErrValidation is an ALIAS of issueops.ErrValidation rather than a +// second sentinel, so this match is the same identity every other handler here +// tests. Naming it through the memory package is what lets this file classify a +// refusal from the role it actually calls. +func (s *Server) failMemoryErr(w http.ResponseWriter, r *http.Request, err error) { + if errors.Is(err, memoryops.ErrValidation) { + // No `param`: the role's two refusals are about the request as a whole + // — content that cannot be remembered, and content no key can be + // derived from — and the second one's recovery is a member the client + // did not send. The detail carries the role's own sentence, which names + // what to send instead. + s.fail(w, r, InvalidArgument("", ReasonInvalidValue, err.Error())) + return + } + s.failErr(w, r, err) +} diff --git a/internal/httpapi/memories_test.go b/internal/httpapi/memories_test.go new file mode 100644 index 000000000..6ccbe5b00 --- /dev/null +++ b/internal/httpapi/memories_test.go @@ -0,0 +1,739 @@ +package httpapi + +import ( + "net/http" + "slices" + "strings" + "testing" + + "github.com/steveyegge/beads/memoryops" +) + +// The pins for the memory operations. What is asserted here is the WIRE EDGE — +// that the handler decodes the document's members into the role's request +// faithfully, refuses what the document refuses, and does not re-implement +// anything the role owns. What a memory MEANS (the key derivation, the storage +// encoding, which plane a row belongs to) is the conformance contract's, and is +// deliberately not re-asserted here. + +const memoriesPath = "/v0/beads/memories" + +func (ts *testServer) remember(t *testing.T, body string) *http.Response { + t.Helper() + return ts.claimRequest(t, memoriesPath, "application/json", body) +} + +func (ts *testServer) forget(t *testing.T, path string) *http.Response { + t.Helper() + req, err := http.NewRequest(http.MethodDelete, ts.base+path, nil) + if err != nil { + t.Fatalf("new request: %v", err) + } + resp, err := ts.client.Do(req) + if err != nil { + t.Fatalf("DELETE %s: %v", path, err) + } + t.Cleanup(func() { _ = resp.Body.Close() }) + return resp +} + +// TestRememberForwardsBothDocumentedMembers is the operation's central pin: +// `content` and `key` reach the role's request unchanged, key VERBATIM. +// +// Asserted on the REQUEST the role received rather than on the response: a +// response echoing the right key says nothing about which bytes were stored, +// and a handler that trimmed the key would put the memory somewhere the client +// cannot name. +func TestRememberForwardsBothDocumentedMembers(t *testing.T) { + memories := &roleMemories{remembered: memoryops.RememberResult{ + Key: "Has Spaces.✓", Value: " keep\nme ", Replaced: true, + }} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.remember(t, `{"content":" keep\nme ","key":"Has Spaces.✓"}`) + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + + reqs := memories.rememberRequests() + if len(reqs) != 1 { + t.Fatalf("%d remembers, want 1", len(reqs)) + } + want := memoryops.RememberRequest{Content: " keep\nme ", Key: "Has Spaces.✓"} + if reqs[0] != want { + t.Errorf("role received %#v, want %#v", reqs[0], want) + } + + body := decodeBody(t, resp) + if got := body["key"]; got != "Has Spaces.✓" { + t.Errorf("key = %v, want the stored key verbatim", got) + } + if got := body["value"]; got != " keep\nme " { + t.Errorf("value = %q, want the content verbatim — this plane does not flatten what it stores", got) + } + if got := body["replaced"]; got != true { + t.Errorf("replaced = %v, want true", got) + } +} + +// TestRememberWithoutAKeyLeavesTheDerivationToTheRole: an omitted `key` reaches +// the role as the empty string, which is what tells it to derive one, and the +// response is where the caller learns the answer. +// +// The handler must not derive: memoryapi.DeriveKey is importable from cmd/bd +// for the CLI's desire path, so a handler could call it — and then two places +// would decide where a memory lands. +func TestRememberWithoutAKeyLeavesTheDerivationToTheRole(t *testing.T) { + memories := &roleMemories{remembered: memoryops.RememberResult{ + Key: "always-run-tests-with-race", Value: "always run tests with -race", + }} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.remember(t, `{"content":"always run tests with -race"}`) + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + + reqs := memories.rememberRequests() + if len(reqs) != 1 { + t.Fatalf("%d remembers, want 1", len(reqs)) + } + if reqs[0].Key != "" { + t.Errorf("role received key %q, want the empty string: the handler must not derive", reqs[0].Key) + } + + body := decodeBody(t, resp) + if got := body["key"]; got != "always-run-tests-with-race" { + t.Errorf("key = %v, want the key the role reported", got) + } + if got := body["replaced"]; got != false { + t.Errorf("replaced = %v, want false", got) + } +} + +// TestRememberRefusesWhatTheDocumentRefuses covers the body vocabulary. The two +// refusals that are the ROLE's — empty content, and content no key derives from +// — have their own case below, because the point of that one is that they come +// from BELOW the wire. +func TestRememberRefusesWhatTheDocumentRefuses(t *testing.T) { + for _, tc := range []struct { + name string + body string + wantParam string + reason Reason + }{ + { + name: "unknown member", + body: `{"content":"x","ttl":5}`, + wantParam: "ttl", + reason: ReasonUnknownParameter, + }, + { + name: "content missing", + body: `{"key":"k"}`, + wantParam: "content", + reason: ReasonInvalidValue, + }, + { + name: "content null", + body: `{"content":null}`, + wantParam: "content", + reason: ReasonInvalidValue, + }, + { + name: "content not a string", + body: `{"content":42}`, + wantParam: "content", + reason: ReasonInvalidValue, + }, + { + name: "key null", + body: `{"content":"x","key":null}`, + wantParam: "key", + reason: ReasonInvalidValue, + }, + { + name: "key not a string", + body: `{"content":"x","key":["k"]}`, + wantParam: "key", + reason: ReasonInvalidValue, + }, + } { + t.Run(tc.name, func(t *testing.T) { + memories := &roleMemories{} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.remember(t, tc.body) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["code"]; got != string(CodeInvalidArgument) { + t.Errorf("code = %v, want %q", got, CodeInvalidArgument) + } + if got := body["param"]; got != tc.wantParam { + t.Errorf("param = %v, want %q", got, tc.wantParam) + } + if got := body["reason"]; got != string(tc.reason) { + t.Errorf("reason = %v, want %q", got, tc.reason) + } + if n := len(memories.rememberRequests()); n != 0 { + t.Errorf("the role was called %d times for a refused request, want 0", n) + } + }) + } +} + +// TestRememberSurfacesTheRolesRefusalAsABadRequest: the two refusals this +// operation has that the handler does NOT implement — empty content, and +// content from which no key can be derived — reach the client as the 400 the +// document promises, carrying the role's own sentence. +// +// It is the same line the sweep and delete handlers draw: the role validates, +// the handler classifies. Widening ClassifyError instead would change what +// every other operation returns for an error it has never produced. +func TestRememberSurfacesTheRolesRefusalAsABadRequest(t *testing.T) { + memories := &roleMemories{err: memoryops.ErrValidation} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.remember(t, `{"content":"!!!"}`) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["code"]; got != string(CodeInvalidArgument) { + t.Errorf("code = %v, want %q", got, CodeInvalidArgument) + } + if _, ok := body["param"]; ok { + t.Errorf("param = %v, want it absent: the role's refusals are about the request, not one member of it", body["param"]) + } + if got := body["reason"]; got != string(ReasonInvalidValue) { + t.Errorf("reason = %v, want %q", got, ReasonInvalidValue) + } + // The role's own sentence, not a rewrite of it: `bd remember` and this + // endpoint refuse the same input with the same words. + if got, _ := body["detail"].(string); got != memoryops.ErrValidation.Error() { + t.Errorf("detail = %q, want the role's message", got) + } +} + +// TestRememberRefusesAQueryString: a write whose narrowing the server silently +// ignored is the failure the unknown-parameter rule exists to prevent, and this +// operation takes no parameters at all. +func TestRememberRefusesAQueryString(t *testing.T) { + memories := &roleMemories{} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.claimRequest(t, memoriesPath+"?key=k", "application/json", `{"content":"x"}`) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["param"]; got != "key" { + t.Errorf("param = %v, want \"key\"", got) + } + if got := body["reason"]; got != string(ReasonUnknownParameter) { + t.Errorf("reason = %v, want %q", got, ReasonUnknownParameter) + } + if n := len(memories.rememberRequests()); n != 0 { + t.Errorf("the role was called %d times for a refused request, want 0", n) + } +} + +// TestGetMemoryAnswersTheStoredValue: the path segment reaches the role +// verbatim — percent-decoded once and not otherwise touched — and the answer is +// the stored bytes. +// +// The key here carries a space, a dot and a non-ASCII rune on purpose: +// `bd remember --key` accepts any string, so a handler that slugged, folded or +// trimmed the segment would answer about a different memory than the one asked +// for. +func TestGetMemoryAnswersTheStoredValue(t *testing.T) { + memories := &roleMemories{recalled: memoryops.RecallResult{ + Key: "Has Spaces.✓", Value: " the\nstored bytes ", Found: true, + }} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.get(t, memoriesPath+"/Has%20Spaces.%E2%9C%93") + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + + reqs := memories.recallRequests() + if len(reqs) != 1 { + t.Fatalf("%d recalls, want 1", len(reqs)) + } + if reqs[0].Key != "Has Spaces.✓" { + t.Errorf("role received key %q, want the decoded segment verbatim", reqs[0].Key) + } + + body := decodeBody(t, resp) + if got := body["value"]; got != " the\nstored bytes " { + t.Errorf("value = %q, want the stored content verbatim", got) + } + // No redaction on this plane, deliberately: there is no member to carry it + // and no value to withhold. + if _, ok := body["redacted"]; ok { + t.Error("the response carries `redacted`; this plane has no redaction, and a member that says otherwise is a promise the key-name heuristic cannot keep") + } +} + +// TestGetMemoryAnswersAMissWithA404 is the deliberate divergence from the +// settings surface's no-404 doctrine. +// +// Both legs are the SAME answer from the role — Found false — and both are a +// 404: a row stored as the empty string is a miss here because the storage seam +// cannot tell it from an absent row, and the wire does not claim to see what +// the role cannot. `GET /v0/beads/memories` enumerating such a row is the one +// way a client tells them apart. +func TestGetMemoryAnswersAMissWithA404(t *testing.T) { + for _, tc := range []struct { + name string + result memoryops.RecallResult + }{ + {name: "nothing stored", result: memoryops.RecallResult{Key: "gone"}}, + {name: "stored as the empty string", result: memoryops.RecallResult{Key: "gone", Value: ""}}, + } { + t.Run(tc.name, func(t *testing.T) { + ts := newTestServer(t, rolesConfig(Config{Memories: &roleMemories{recalled: tc.result}})) + + resp := ts.get(t, memoriesPath+"/gone") + if resp.StatusCode != http.StatusNotFound { + t.Fatalf("status = %d, want 404: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["code"]; got != string(CodeNotFound) { + t.Errorf("code = %v, want %q", got, CodeNotFound) + } + if body["request_id"] == nil { + t.Error("no request_id on the problem body") + } + // The detail is about the MEMORY plane. Reusing the issue-id + // sentence would tell a client its memory key was an issue id. + if got, _ := body["detail"].(string); !strings.Contains(got, "memory") { + t.Errorf("detail = %q, want it to name the memory plane", got) + } + }) + } +} + +// TestGetMemoryRefusesAKeyItCannotAddress covers the two 400s, and the second +// one is the documented consequence worth pinning: a control character is +// refused at the door rather than looked up, so a memory stored under such a +// key is unreachable by path while the ROLE stays verbatim and the CLI still +// recalls it. +// +// The refusal is a 400 and not the 404 beside it, because a 404 would be a +// claim about storage that nothing here asked storage about. +func TestGetMemoryRefusesAKeyItCannotAddress(t *testing.T) { + for _, tc := range []struct { + name string + path string + }{ + {name: "empty after trimming", path: memoriesPath + "/%20%20"}, + {name: "control character", path: memoriesPath + "/bad%0Akey"}, + } { + t.Run(tc.name, func(t *testing.T) { + memories := &roleMemories{recalled: memoryops.RecallResult{Found: true, Value: "v"}} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.get(t, tc.path) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["param"]; got != "key" { + t.Errorf("param = %v, want \"key\"", got) + } + if got := body["reason"]; got != string(ReasonInvalidValue) { + t.Errorf("reason = %v, want %q", got, ReasonInvalidValue) + } + if n := len(memories.recallRequests()); n != 0 { + t.Errorf("the role was called %d times for a key the door refused, want 0", n) + } + }) + } +} + +// TestGetMemoryRefusesAQueryString: this operation takes no parameters, and an +// ignored one is a client's silently unanswered question. +func TestGetMemoryRefusesAQueryString(t *testing.T) { + memories := &roleMemories{recalled: memoryops.RecallResult{Found: true, Value: "v"}} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.get(t, memoriesPath+"/k?verbose=1") + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["param"]; got != "verbose" { + t.Errorf("param = %v, want \"verbose\"", got) + } + if got := body["reason"]; got != string(ReasonUnknownParameter) { + t.Errorf("reason = %v, want %q", got, ReasonUnknownParameter) + } + if n := len(memories.recallRequests()); n != 0 { + t.Errorf("the role was called %d times for a refused request, want 0", n) + } +} + +// TestForgetMemoryRemovesTheNamedKeyAndReportsWhatItHeld: the surface's first +// DELETE. The path segment reaches the role verbatim and the 200 body carries +// what was removed, which is what `bd forget` prints. +// +// WHICH ROW WAS REMOVED IS NOT ASSERTED HERE and must not be: the memory plane +// shares one table with the workspace's settings and the generic kv namespace, +// and "exactly the named row" is the role's promise, pinned by its conformance +// contract against three backends. A handler test with a fake role could only +// restate what the fake was told to do. +func TestForgetMemoryRemovesTheNamedKeyAndReportsWhatItHeld(t *testing.T) { + memories := &roleMemories{forgotten: memoryops.ForgetResult{ + Key: "Has Spaces.✓", Value: " what it held ", Found: true, + }} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.forget(t, memoriesPath+"/Has%20Spaces.%E2%9C%93") + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + + reqs := memories.forgetRequests() + if len(reqs) != 1 { + t.Fatalf("%d forgets, want 1", len(reqs)) + } + if reqs[0].Key != "Has Spaces.✓" { + t.Errorf("role received key %q, want the decoded segment verbatim", reqs[0].Key) + } + + body := decodeBody(t, resp) + if got := body["key"]; got != "Has Spaces.✓" { + t.Errorf("key = %v, want the forgotten key", got) + } + if got := body["value"]; got != " what it held " { + t.Errorf("value = %q, want what the memory held, verbatim", got) + } +} + +// TestForgetMemoryOfAnAbsentKeyIs404AndRemovesNothing: Found false is the +// role's answer and NOTHING WAS REMOVED, which is a 404 rather than a 200 with +// an empty body — a client that retried a forget has to be able to tell "I +// removed this" from "there was nothing to remove". +func TestForgetMemoryOfAnAbsentKeyIs404AndRemovesNothing(t *testing.T) { + memories := &roleMemories{forgotten: memoryops.ForgetResult{Key: "gone"}} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.forget(t, memoriesPath+"/gone") + if resp.StatusCode != http.StatusNotFound { + t.Fatalf("status = %d, want 404: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["code"]; got != string(CodeNotFound) { + t.Errorf("code = %v, want %q", got, CodeNotFound) + } + if body["request_id"] == nil { + t.Error("no request_id on the problem body") + } + // The role was still called: whether a key holds a memory is a question for + // storage, and a handler that answered 404 without asking would be guessing. + if n := len(memories.forgetRequests()); n != 1 { + t.Errorf("the role was called %d times, want 1", n) + } +} + +// TestForgetMemoryRefusesAKeyItCannotAddress: the door refuses the same keys +// the read refuses, and the role is never reached — which on a DESTRUCTIVE +// operation is the half that matters. A stored key carrying a control +// character is therefore forgettable from the CLI and not through this +// operation, with the role still verbatim. +func TestForgetMemoryRefusesAKeyItCannotAddress(t *testing.T) { + for _, tc := range []struct { + name string + path string + }{ + {name: "empty after trimming", path: memoriesPath + "/%20%20"}, + {name: "control character", path: memoriesPath + "/bad%0Akey"}, + } { + t.Run(tc.name, func(t *testing.T) { + memories := &roleMemories{forgotten: memoryops.ForgetResult{Found: true}} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.forget(t, tc.path) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["param"]; got != "key" { + t.Errorf("param = %v, want \"key\"", got) + } + if n := len(memories.forgetRequests()); n != 0 { + t.Errorf("the role was called %d times for a key the door refused, want 0 — this operation deletes", n) + } + }) + } +} + +// TestForgetMemoryRefusesAQueryString: this operation takes no parameters, and +// on a destructive one an ignored parameter is the shape where a client +// believes it narrowed what it erased. +func TestForgetMemoryRefusesAQueryString(t *testing.T) { + memories := &roleMemories{forgotten: memoryops.ForgetResult{Found: true}} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.forget(t, memoriesPath+"/k?dry_run=true") + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["param"]; got != "dry_run" { + t.Errorf("param = %v, want \"dry_run\"", got) + } + if got := body["reason"]; got != string(ReasonUnknownParameter) { + t.Errorf("reason = %v, want %q", got, ReasonUnknownParameter) + } + if n := len(memories.forgetRequests()); n != 0 { + t.Errorf("the role was called %d times for a refused request, want 0", n) + } +} + +// TestDeleteOnTheMemoryCollectionIsNotRouted: the DELETE row is registered for +// `/v0/beads/memories/{key}`, and ServeMux requires the separating slash — so +// the collection path has no DELETE and answers the catch-all's 404. +// +// Worth a case because this is the surface's first DELETE method: a pattern +// that had swallowed the collection would be an undocumented way to ask for a +// bulk erase, and the parity test compares path STRINGS rather than probing +// what the router matches. +func TestDeleteOnTheMemoryCollectionIsNotRouted(t *testing.T) { + memories := &roleMemories{forgotten: memoryops.ForgetResult{Found: true}} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.forget(t, memoriesPath) + if resp.StatusCode != http.StatusNotFound { + t.Fatalf("status = %d, want 404: %s", resp.StatusCode, readAll(t, resp)) + } + if n := len(memories.forgetRequests()); n != 0 { + t.Errorf("the role was called %d times for the collection path, want 0", n) + } +} + +// TestListMemoriesAnswersThePlaneOrderedByKey: the collection read. The order +// is what makes the paginated envelope honest — a keyset cursor over it is +// expressible later without changing what a client already receives — and +// `has_more` is always false because the whole plane comes back in one page. +func TestListMemoriesAnswersThePlaneOrderedByKey(t *testing.T) { + memories := &roleMemories{listed: memoryops.ListResult{Memories: map[string]string{ + "zebra": "last by key", + "alpha": "first by key", + "Has Spaces.✓": "an explicit key", + // A row written out of band with an empty value. It is enumerated here + // — its KEY exists — while GET /v0/beads/memories/{key} answers 404 for + // it, and that asymmetry is the one way a client tells a row stored + // empty from a row that is not there. + "stored-empty": "", + }}} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.get(t, memoriesPath) + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + + body := decodeBody(t, resp) + if got := body["has_more"]; got != false { + t.Errorf("has_more = %v, want false: the whole plane comes back in one page", got) + } + if _, ok := body["next_cursor"]; ok { + t.Error("next_cursor is present; it is documented as present if and only if has_more is true") + } + items, _ := body["items"].([]any) + var gotKeys []string + for _, item := range items { + entry, _ := item.(map[string]any) + key, _ := entry["key"].(string) + gotKeys = append(gotKeys, key) + } + wantKeys := []string{"Has Spaces.✓", "alpha", "stored-empty", "zebra"} + if !slices.Equal(gotKeys, wantKeys) { + t.Errorf("keys = %v, want %v (ordered by key)", gotKeys, wantKeys) + } + + values := map[string]any{} + for _, item := range items { + entry, _ := item.(map[string]any) + key, _ := entry["key"].(string) + values[key] = entry["value"] + } + if got := values["stored-empty"]; got != "" { + t.Errorf("the empty-valued row's value = %v, want the empty string: `value` is required on Memory", got) + } + if got := values["alpha"]; got != "first by key" { + t.Errorf("value = %v, want the stored content", got) + } +} + +// TestListMemoriesOfAnEmptyPlaneIsAnEmptyArray: never null. A client must not +// have to tell an absent array from an empty one to learn that nothing is +// stored. +func TestListMemoriesOfAnEmptyPlaneIsAnEmptyArray(t *testing.T) { + ts := newTestServer(t, rolesConfig(Config{Memories: &roleMemories{}})) + + resp := ts.get(t, memoriesPath) + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + raw := readAll(t, resp) + if !strings.Contains(raw, `"items":[]`) { + t.Errorf("body = %s, want an empty items array rather than null", raw) + } +} + +// TestListMemoriesPassesTheSearchTermUnfolded: the term reaches the role as the +// client sent it. +// +// Case folding is the ROLE's — it owns what matching means, so that this +// surface and `bd memories` cannot come to disagree — and a handler that +// lowercased on the way past would be the second definition. Asserted on the +// REQUEST the role received for that reason: a response says nothing about +// which term was searched for. +func TestListMemoriesPassesTheSearchTermUnfolded(t *testing.T) { + memories := &roleMemories{} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.get(t, memoriesPath+"?search=Dolt%20PHANTOMS") + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + + reqs := memories.listRequests() + if len(reqs) != 1 { + t.Fatalf("%d lists, want 1", len(reqs)) + } + if reqs[0].Search != "Dolt PHANTOMS" { + t.Errorf("role received search %q, want the term verbatim", reqs[0].Search) + } +} + +// TestListMemoriesTreatsAnAbsentTermAsEverything: absent `q` is the empty +// search, which the role reads as "everything" — not as a filter that matches +// only memories containing "". +func TestListMemoriesTreatsAnAbsentTermAsEverything(t *testing.T) { + memories := &roleMemories{} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + if resp := ts.get(t, memoriesPath); resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + reqs := memories.listRequests() + if len(reqs) != 1 { + t.Fatalf("%d lists, want 1", len(reqs)) + } + if reqs[0].Search != "" { + t.Errorf("role received search %q for an absent parameter, want the empty string", reqs[0].Search) + } +} + +// TestListMemoriesRefusesAnUnknownQueryParameter is the pin the design asked +// for by name: it is the only operation on the memory plane that takes a +// parameter at all, so it is the only one that goes through the query DECODER +// rather than through requireNoQuery — and that decoder's allowlist is the set +// of names the handler actually read, so a handler reading nothing accepts +// nothing while one reading `search` accepts exactly `search`. +// +// Silently ignoring an unrecognized parameter is what this prevents. On a +// filtering operation it WIDENS the answer, so a client one version ahead of +// the server would receive memories it believed it had filtered out — and on +// this plane a widened answer is a disclosure. It is also a client's only +// per-parameter capability probe, since `capabilities` is operation-level. +func TestListMemoriesRefusesAnUnknownQueryParameter(t *testing.T) { + for _, tc := range []struct { + name string + query string + wantParam string + reason Reason + }{ + { + // `q` SPECIFICALLY, which is the whole reason this operation's + // parameter is not called that. On GET /v0/beads/issues:query, `q` + // is a boolean expression over issue fields; a client carrying that + // habit here has asked a question this operation does not answer, + // and the one useful reply is that the name is unknown. Were the + // parameter spelled `q`, `?q=status:open` would come back as a + // literal substring search over memory text — a wrong answer with + // a 200 on it. + name: "the other operation's q", + query: "?q=status:open", + wantParam: "q", + reason: ReasonUnknownParameter, + }, + { + // The paging vocabulary of the issue reads. This operation has no + // limit and no cursor, and accepting one silently would promise + // paging that does not happen. + name: "a parameter another operation does have", + query: "?search=dolt&limit=10", + wantParam: "limit", + reason: ReasonUnknownParameter, + }, + { + // A repeated `search` is two search terms, which is a question this + // operation cannot answer. Resolving it to one of them silently + // would answer a different question from the one asked. + name: "a repeated search", + query: "?search=one&search=two", + wantParam: "search", + reason: ReasonInvalidValue, + }, + { + // The degenerate spelling: a parameter whose NAME is empty. The + // document promises `param` on every 400 but an unparseable body, + // so it is named rather than omitted. + name: "the empty parameter name", + query: "?=1", + wantParam: "", + reason: ReasonUnknownParameter, + }, + } { + t.Run(tc.name, func(t *testing.T) { + memories := &roleMemories{} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + resp := ts.get(t, memoriesPath+tc.query) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if got := body["code"]; got != string(CodeInvalidArgument) { + t.Errorf("code = %v, want %q", got, CodeInvalidArgument) + } + param, ok := body["param"] + if !ok { + t.Fatalf("no `param` on the refusal; the document promises one on every 400 but an unparseable body") + } + if param != tc.wantParam { + t.Errorf("param = %v, want %q", param, tc.wantParam) + } + if got := body["reason"]; got != string(tc.reason) { + t.Errorf("reason = %v, want %q", got, tc.reason) + } + if n := len(memories.listRequests()); n != 0 { + t.Errorf("the role was called %d times for a refused request, want 0", n) + } + }) + } +} + +// TestListMemoriesAcceptsSearchAndNothingElse states the other half of the rule +// as a positive: `search` is accepted, so the refusals above are about the +// OTHER names rather than about a decoder that refuses everything. +func TestListMemoriesAcceptsSearchAndNothingElse(t *testing.T) { + memories := &roleMemories{} + ts := newTestServer(t, rolesConfig(Config{Memories: memories})) + + if resp := ts.get(t, memoriesPath+"?search=dolt"); resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d for the one parameter this operation takes, want 200: %s", + resp.StatusCode, readAll(t, resp)) + } + if n := len(memories.listRequests()); n != 1 { + t.Errorf("the role was called %d times, want 1", n) + } +} diff --git a/internal/httpapi/problem.go b/internal/httpapi/problem.go index 6a0aafa82..d0f44419f 100644 --- a/internal/httpapi/problem.go +++ b/internal/httpapi/problem.go @@ -181,6 +181,25 @@ const ( OpDeleteIssues = "deleteIssues" // OpBatchCreateIssues creates many issues as one transaction, or none. OpBatchCreateIssues = "batchCreateIssues" + // OpRememberMemory stores one memory, behind memoryops.Memories. It is the + // first operation on this surface that reaches a role outside issueops: the + // memory plane is user data riding in the config table, not settings, and + // the two have different merge semantics and a different miss contract. + OpRememberMemory = "rememberMemory" + // OpGetMemory reads one memory by key. It is the ONE operation on this + // surface that answers a miss with a 404 where its settings counterpart + // deliberately does not: see its operationCodes row. + OpGetMemory = "getMemory" + // OpForgetMemory is the THIRD destructive operation on this surface, and the + // only one that is a DELETE method: it names one memory by path, carries no + // body and takes no flags, which is what that method already means. The two + // destructive issue operations are collection-level custom methods because + // they act on a set the request describes. + OpForgetMemory = "forgetMemory" + // OpListMemories enumerates the memory plane, narrowed by one search term. + // It is the operation that makes stored memories DISCOVERABLE rather than + // merely readable by a caller who already knows a key. + OpListMemories = "listMemories" ) // operationCodes is the per-operation problem vocabulary: exactly the codes @@ -270,6 +289,29 @@ var operationCodes = map[string][]Code{ // item can collide with a stored row and the role's ErrAlreadyExists is // unreachable from the wire. OpBatchCreateIssues: {CodeInvalidArgument, CodeBusy, CodeDBUnavailable, CodeInternal}, + // No 404 and no conflict code: this is an UPSERT with a server-derivable + // key, so there is no resource it can fail to address and no row it can + // collide with. Its 400 is the body vocabulary plus the ROLE's two + // refusals — empty content, and content no key can be derived from. + OpRememberMemory: {CodeInvalidArgument, CodeBusy, CodeDBUnavailable, CodeInternal}, + // THE 404 IS THE DIVERGENCE, and it is deliberate. OpGetSetting has none + // because on that plane an absent key and a key stored empty are one answer + // the CLI itself prints identically, so a 404 would publish an invented + // distinction. Here the CLI already distinguishes a miss — `bd recall` has + // an exit-code contract for it — and the role answers Found rather than a + // value, so the 404 reports a distinction that exists. The stored-empty row + // falls on the miss side of it, which the document states. + OpGetMemory: {CodeInvalidArgument, CodeNotFound, CodeBusy, CodeDBUnavailable, CodeInternal}, + // The read's vocabulary exactly, because the two operations address the same + // resource the same way and this one's Found false is the same answer: a key + // nothing stored is a 404 and nothing was removed. No 409 — a memory another + // caller already forgot is simply not there, which is what the 404 says. + OpForgetMemory: {CodeInvalidArgument, CodeNotFound, CodeBusy, CodeDBUnavailable, CodeInternal}, + // The 400 here IS this operation's own, unlike listSettings' absent row: it + // has one parameter, and a repeated `q` is refused rather than resolved to + // one of its values. No 404 — a search matching nothing is an empty page, + // because a question about a set has an answer even when the set is empty. + OpListMemories: {CodeInvalidArgument, CodeBusy, CodeDBUnavailable, CodeInternal}, } // Result is a problem response ready to be written: the envelope plus the @@ -360,6 +402,18 @@ func NotFound() Result { return newResult(CodeNotFound, "no issue or wisp with that id") } +// MemoryNotFound builds the 404 for a key this workspace holds no memory under. +// +// A separate constructor rather than a detail argument on NotFound, because the +// two say different things: that one is about the issue id space, and reusing +// its sentence here would tell a client its memory key was an issue id. The +// detail deliberately does NOT distinguish an absent row from one stored as the +// empty string — the role cannot see the difference, so the wire must not claim +// to. +func MemoryNotFound() Result { + return newResult(CodeNotFound, "this workspace holds no memory under that key") +} + // ClassifyError maps an error from the storage seam onto the wire. The caller // is responsible for logging err: everything mapped to a 5xx deliberately // drops the error text on the floor (see staticDetail). diff --git a/internal/httpapi/roles_test.go b/internal/httpapi/roles_test.go index 179e46461..ccc2fbe05 100644 --- a/internal/httpapi/roles_test.go +++ b/internal/httpapi/roles_test.go @@ -15,6 +15,7 @@ import ( "github.com/steveyegge/beads/internal/storage/uow" "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) // These tests cover the OTHER database source: a backend whose facade is a @@ -251,6 +252,91 @@ func (c *roleBatchCreator) createRequests() []issueops.CreateBatchRequest { return append([]issueops.CreateBatchRequest(nil), c.requests...) } +// roleMemories is the store-shaped source's persistent-memory role — the one +// role of the set that is not an issueops role. +// +// It records the request each method was handed, because what is worth +// asserting at this seam is that the WIRE's parameters reach the role +// unrewritten: the key derivation, the search folding and the plane filtering +// all belong to the conformance contract, not to a handler test. +type roleMemories struct { + remembered memoryops.RememberResult + recalled memoryops.RecallResult + forgotten memoryops.ForgetResult + listed memoryops.ListResult + err error + + mu sync.Mutex + remember []memoryops.RememberRequest + recall []memoryops.RecallRequest + forget []memoryops.ForgetRequest + list []memoryops.ListRequest +} + +func (m *roleMemories) Remember(_ context.Context, req memoryops.RememberRequest) (memoryops.RememberResult, error) { + m.mu.Lock() + m.remember = append(m.remember, req) + m.mu.Unlock() + if m.err != nil { + return memoryops.RememberResult{}, m.err + } + return m.remembered, nil +} + +func (m *roleMemories) Recall(_ context.Context, req memoryops.RecallRequest) (memoryops.RecallResult, error) { + m.mu.Lock() + m.recall = append(m.recall, req) + m.mu.Unlock() + if m.err != nil { + return memoryops.RecallResult{}, m.err + } + return m.recalled, nil +} + +func (m *roleMemories) Forget(_ context.Context, req memoryops.ForgetRequest) (memoryops.ForgetResult, error) { + m.mu.Lock() + m.forget = append(m.forget, req) + m.mu.Unlock() + if m.err != nil { + return memoryops.ForgetResult{}, m.err + } + return m.forgotten, nil +} + +func (m *roleMemories) List(_ context.Context, req memoryops.ListRequest) (memoryops.ListResult, error) { + m.mu.Lock() + m.list = append(m.list, req) + m.mu.Unlock() + if m.err != nil { + return memoryops.ListResult{}, m.err + } + return m.listed, nil +} + +func (m *roleMemories) rememberRequests() []memoryops.RememberRequest { + m.mu.Lock() + defer m.mu.Unlock() + return append([]memoryops.RememberRequest(nil), m.remember...) +} + +func (m *roleMemories) recallRequests() []memoryops.RecallRequest { + m.mu.Lock() + defer m.mu.Unlock() + return append([]memoryops.RecallRequest(nil), m.recall...) +} + +func (m *roleMemories) forgetRequests() []memoryops.ForgetRequest { + m.mu.Lock() + defer m.mu.Unlock() + return append([]memoryops.ForgetRequest(nil), m.forget...) +} + +func (m *roleMemories) listRequests() []memoryops.ListRequest { + m.mu.Lock() + defer m.mu.Unlock() + return append([]memoryops.ListRequest(nil), m.list...) +} + type roleClaimer struct { result issueops.ClaimResult err error @@ -402,6 +488,9 @@ func rolesConfig(cfg Config) Config { if cfg.BatchCreator == nil { cfg.BatchCreator = &roleBatchCreator{} } + if cfg.Memories == nil { + cfg.Memories = &roleMemories{} + } return cfg } @@ -647,6 +736,25 @@ func TestListenRequiresExactlyOneDatabaseSource(t *testing.T) { cfg: Config{Provider: &fakeProvider{}, BatchCreator: &roleBatchCreator{}}, wantErr: "exactly one database source", }, + { + // The role that is not an issueops role. It is in the same + // all-or-nothing set for the same reason: without it the server + // binds, advertises the memory operations, and nil-dereferences on + // the first request that reaches one. + name: "no memories role", + cfg: rolesConfigWithout(func(c *Config) { c.Memories = nil }), + wantErr: "no database source", + }, + { + name: "a memories role alone", + cfg: Config{Memories: &roleMemories{}}, + wantErr: "no database source", + }, + { + name: "a provider and a memories role", + cfg: Config{Provider: &fakeProvider{}, Memories: &roleMemories{}}, + wantErr: "exactly one database source", + }, { name: "a provider and a ready counter", cfg: Config{Provider: &fakeProvider{}, ReadyCounter: &roleReadyCounter{}}, diff --git a/internal/httpapi/routes.go b/internal/httpapi/routes.go index 01789fbe5..4d3cfe99d 100644 --- a/internal/httpapi/routes.go +++ b/internal/httpapi/routes.go @@ -245,6 +245,50 @@ var routeTable = []route{ implemented: true, handler: (*Server).handleDelete, }, + { + op: OpListMemories, + method: http.MethodGet, + pattern: "/v0/beads/memories", + capability: "memories.list", + implemented: true, + handler: (*Server).handleListMemories, + }, + { + op: OpRememberMemory, + method: http.MethodPost, + // A plain collection POST, not a custom method: this creates one member + // of the collection the path names, which is what POST already means. + // The two destructive issue operations above are custom methods because + // they act on a SET the request describes; nothing here does. + pattern: "/v0/beads/memories", + capability: "memories.remember", + implemented: true, + handler: (*Server).handleRememberMemory, + }, + { + op: OpGetMemory, + method: http.MethodGet, + // A single-segment wildcard, so pattern and specPath agree and no + // declaration is needed. It cannot collide with the collection read + // above: ServeMux requires the separating slash, so `/memories` and + // `/memories/{key}` never match the same request. + pattern: "/v0/beads/memories/{key}", + capability: "memories.get", + implemented: true, + handler: (*Server).handleGetMemory, + }, + { + op: OpForgetMemory, + method: http.MethodDelete, + // The surface's first DELETE. It shares a pattern with the read above + // and differs only in method, which is the whole argument for the + // method: one named resource, no body, no flags. ServeMux registers + // method and pattern together, so the two rows cannot collide. + pattern: "/v0/beads/memories/{key}", + capability: "memories.forget", + implemented: true, + handler: (*Server).handleForgetMemory, + }, } // specPathOf is the document path for a route, defaulting to the router diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go index 39e0b17af..c9223d641 100644 --- a/internal/httpapi/server.go +++ b/internal/httpapi/server.go @@ -28,6 +28,7 @@ import ( "github.com/steveyegge/beads/internal/storage/domain" "github.com/steveyegge/beads/internal/storage/uow" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) // APIVersion is the path major this package serves, reported as @@ -187,6 +188,13 @@ type Config struct { // Deleter is the OTHER destructive one, required for the same reason. Deleter issueops.Deleter BatchCreator issueops.BatchCreator + // Memories is the workspace's persistent memory plane, and the one field + // here that is not an issueops role: memories are user data riding in the + // config table under their own merge class, not settings, so they have + // their own leaf package. Required on the same terms as every field above — + // a partial set is refused, so the field and the operations that reach it + // land together. + Memories memoryops.Memories // Workspace is the startup snapshot GET /v0/beads/context answers from. // Only the allowlisted fields are ever serialized — see contextResponse, // which names the whole set and the reasons for the exclusions. @@ -227,6 +235,7 @@ type Server struct { issueSweeper issueops.Sweeper issueDeleter issueops.Deleter issueBatchCreator issueops.BatchCreator + workspaceMemories memoryops.Memories listener net.Listener http *http.Server @@ -336,6 +345,7 @@ func Listen(cfg Config) (*Server, error) { issueSweeper: cfg.Sweeper, issueDeleter: cfg.Deleter, issueBatchCreator: cfg.BatchCreator, + workspaceMemories: cfg.Memories, sem: make(chan struct{}, maxInflight), semTimeout: semAcquireTimeout, @@ -425,12 +435,12 @@ func Listen(cfg Config) (*Server, error) { // actually sets; a typed nil stored in one of these fields is a value as far as // this check is concerned. func sourceRoles(cfg Config) []any { - return []any{cfg.Reader, cfg.Claimer, cfg.Settings, cfg.Stats, cfg.CycleDetector, cfg.EdgeReader, cfg.BlockingAnnotator, cfg.TreeWalker, cfg.ReadyCounter, cfg.Querier, cfg.Sweeper, cfg.Deleter, cfg.BatchCreator} + return []any{cfg.Reader, cfg.Claimer, cfg.Settings, cfg.Stats, cfg.CycleDetector, cfg.EdgeReader, cfg.BlockingAnnotator, cfg.TreeWalker, cfg.ReadyCounter, cfg.Querier, cfg.Sweeper, cfg.Deleter, cfg.BatchCreator, cfg.Memories} } // roleSourceNames spells sourceRoles for the refusal message, in the same // order, so a caller reading the error learns the whole set it must pass. -const roleSourceNames = "Reader, Claimer, Settings, Stats, CycleDetector, EdgeReader, BlockingAnnotator, TreeWalker, ReadyCounter, Querier, Sweeper, Deleter and BatchCreator" +const roleSourceNames = "Reader, Claimer, Settings, Stats, CycleDetector, EdgeReader, BlockingAnnotator, TreeWalker, ReadyCounter, Querier, Sweeper, Deleter, BatchCreator and Memories" func anyRoleSet(cfg Config) bool { return slices.ContainsFunc(sourceRoles(cfg), func(r any) bool { return r != nil }) @@ -745,6 +755,21 @@ func (s *Server) batchCreator(r *http.Request) (issueops.BatchCreator, error) { return checkedBatchCreator{inner: creator}, nil } +// memories returns the persistent-memory surface for one request, on the same +// terms as every role above and held by INTERFACE so uow.MemoriesSource is +// load-bearing rather than decorative. +// +// It goes out UNWRAPPED: all four of this role's results are VALUES, so no +// handler dereferences a pointer it returned, and a miss is a Found field +// rather than a nil the wire would have to interpret. +func (s *Server) memories(r *http.Request) (memoryops.Memories, error) { + if s.provider == nil { + return s.workspaceMemories, nil + } + var src uow.MemoriesSource = timedProvider{inner: s.provider, rec: requestInfo(r.Context())} + return src.Memories() +} + // WithUOW runs fn inside one unit of work and guarantees the rollback. // // The close context is DETACHED on purpose. Close sends ROLLBACK on the pinned diff --git a/internal/httpapi/server_test.go b/internal/httpapi/server_test.go index a886b5881..0bc91487f 100644 --- a/internal/httpapi/server_test.go +++ b/internal/httpapi/server_test.go @@ -589,7 +589,9 @@ func TestCapabilitiesAdvertiseEveryImplementedOperation(t *testing.T) { "config.get", "config.list", "dependencies.blocking", "dependencies.cycles", "dependencies.list", "dependencies.tree", "issues.batchCreate", "issues.claim", "issues.delete", "issues.get", "issues.list", - "issues.query", "issues.sweep", "ready.count", "ready.list", "stats.get", + "issues.query", "issues.sweep", "memories.forget", "memories.get", + "memories.list", "memories.remember", "ready.count", "ready.list", + "stats.get", } if !slices.Equal(got, want) { t.Errorf("capabilities = %v, want %v", got, want) diff --git a/internal/httpapi/spec/openapi.v0.yaml b/internal/httpapi/spec/openapi.v0.yaml index 4586f5cc4..3ebe01f8f 100644 --- a/internal/httpapi/spec/openapi.v0.yaml +++ b/internal/httpapi/spec/openapi.v0.yaml @@ -1542,7 +1542,7 @@ paths: operationId: listSettings summary: List the workspace's stored settings description: >- - Every setting stored in the workspace DATABASE, which is the plane + The SETTINGS stored in the workspace database, which is the plane `bd config list` reads. It is not the effective configuration: values that reach a running `bd` from `config.yaml`, from environment variables or from git config are absent and cannot be here, because @@ -1551,6 +1551,18 @@ paths: has no HTTP operation for the same reason. + IT IS NOT EVERY ROW OF THAT TABLE. Keys under `kv.` are omitted — the + generic `bd kv` namespace and the `bd remember` memories nested under + it. Those rows are USER DATA that rides in the settings table because + there is one table, not because they are settings, and enumerating them + here published a workspace's memories, key and value, to anything that + could reach this port. `bd config list` omits them too: the exclusion is + in the shared role both doors call, so the two cannot drift. + + `getSetting` still answers a `kv.` key NAMED EXACTLY, and this + operation is where it stopped being discoverable. + + SETTINGS WHOSE KEY MARKS THEM AS CREDENTIAL-BEARING ARE WITHHELD. Their entry is present with `redacted: true` and no `value`, so a client can see that the key is configured without the surface handing a secret to @@ -1804,6 +1816,321 @@ paths: '503': $ref: '#/components/responses/Unavailable' + /v0/beads/memories: + get: + operationId: listMemories + summary: List the workspace's stored memories + description: >- + Every memory this workspace holds, optionally narrowed by `search`. It + is the plane `bd memories` reads. + + + ONLY THE MEMORY PLANE. Memories ride in the same database table as the + workspace's settings and as the generic `bd kv` namespace, and neither + of those appears here, whatever it contains — including a memory whose + key SHADOWS a settings name: a memory called `issue_prefix` is a memory, + and the workspace's real issue prefix is not one. That separation is the + role's, pinned by its conformance contract, not a filter applied to this + answer. + + + MEMORY CONTENT IS SERVED IN FULL and this API has no authentication. + Every entry carries its value verbatim; there is no `redacted` member + and nothing is withheld. See `POST /v0/beads/memories` for why a + key-name heuristic would be worse here than no promise at all. This is + the operation that makes stored memories DISCOVERABLE rather than merely + readable by a caller who already knows a key — an operator binding + beyond loopback is accepting exactly that. + + + A memory stored as the EMPTY STRING is enumerated here, because its key + exists, while `GET /v0/beads/memories/{key}` answers `404` for it. That + asymmetry is the one way a client can tell a row stored empty from a row + that is not there, and it is the storage seam's conflation showing + through rather than a rule this surface invented. + + + The envelope is the paginated one and `has_more` is ALWAYS false: + memories are a keyed namespace a workspace holds tens of, not a + collection to scan, so the whole plane comes back in one page. There is + no `limit` and no cursor. The envelope is used anyway because entries + are ordered by key, which makes a keyset cursor expressible later + without a breaking change. + parameters: + - name: search + in: query + description: >- + Narrows the answer to memories that MATCH: a memory matches when the + lowercase of its key, or the lowercase of its value, contains the + lowercase of this term. Absent or empty means everything, and a term + nothing matches is a `200` with an empty `items`. + + + IT IS A SUBSTRING MATCH, NOT THE `issues:query` EXPRESSION LANGUAGE, + and it is spelled `search` rather than `q` FOR THAT REASON. On `GET + /v0/beads/issues:query`, `q` is a boolean expression over issue + fields that is refused when it does not parse; here there is nothing + to parse, no vocabulary and no refusal — every string is a legal + search term, `status=open` included, and it is matched literally. + Two names because two questions: a client that sent this operation + the other `q` would otherwise get a literal substring search back + instead of an error. + + + The term reaches the role UNFOLDED. Case folding is the role's, so + that this surface and `bd memories` cannot come to disagree about + what matching means; a client sends what its user typed. + schema: + type: string + responses: + '200': + description: The stored memories, ordered by key. + content: + application/json: + schema: + $ref: '#/components/schemas/MemoriesPage' + '400': + description: >- + Invalid request: an unknown query parameter, or a repeated + `search`. `search` is the only parameter this operation accepts — + `q` is NOT one of them, and is refused as unknown rather than + treated as a search term. + x-bd-codes: [invalid_argument] + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + '500': + $ref: '#/components/responses/InternalError' + '503': + $ref: '#/components/responses/Unavailable' + post: + operationId: rememberMemory + summary: Store one memory + description: >- + Stores one memory in the workspace's persistent memory plane — the + operation behind `bd remember`. It is an UPSERT: a key that already + holds a memory is overwritten, and `replaced` in the response reports + which of the two happened. + + + `key` is OPTIONAL, and omitting it is the normal case. The server then + derives the key from `content` using the one derivation `bd remember` + has used since it shipped, and the response's `key` is where the caller + learns what to recall. A `key` that IS supplied is used verbatim: no + trimming, no slugging, no charset restriction, because a stored key has + to stay recallable under the exact bytes the caller used. + + + MEMORY CONTENT IS SERVED IN FULL, here and on every other operation of + this plane, and this API has no authentication. There is no `redacted` + member and no value withholding: the settings surface's redaction is a + heuristic over the KEY NAME, and memory keys are derived from the + content, so the same rule would withhold a memory ABOUT tokens while + serving one that CONTAINS a token under an innocuous slug. A promise + that cannot be kept is not made. Do not store credentials in this plane. + + + There is no `201`/`200` split. `replaced` already says whether a row + existed, saying it twice in a second vocabulary would add nothing, and + an upsert whose key the server may derive has no stable `Location` to + point at. + + + Hooks do not fire and the per-command auto-commit machinery does not + run, exactly as for the other write operations on this surface. The + only durable effect is the single storage commit the role makes in its + own transaction — which also observes whether a previous value existed, + so `replaced` is a statement about the row this request wrote rather + than about a row some earlier read happened to see. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RememberRequest' + responses: + '200': + description: >- + The memory was stored. `key` is where it lives, derived or verbatim. + content: + application/json: + schema: + $ref: '#/components/schemas/RememberedMemory' + '400': + description: >- + Invalid request: an unknown query parameter, an unparseable or + oversized body, an unknown body member, a missing or non-string + `content`, a `content` that is empty after trimming, or a `content` + from which no key can be derived when none was supplied — the last + two the ROLE's refusals, reaching the wire with its own sentences. + Nothing is stored in any of these cases. + x-bd-codes: [invalid_argument] + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + '500': + $ref: '#/components/responses/InternalError' + '503': + $ref: '#/components/responses/Unavailable' + + /v0/beads/memories/{key}: + get: + operationId: getMemory + summary: Get one stored memory + description: >- + The memory stored under one key, used verbatim: no namespace completion, + no case folding, no dash/underscore equivalence. It is the operation + behind `bd recall`. + + + THIS OPERATION HAS A REAL 404, and it is the one place this surface + diverges from `GET /v0/beads/config/{key}`, which deliberately has none. + The planes genuinely differ. On the settings plane a key nothing stored + and a key stored empty are one answer that `bd config get` prints + identically, so a 404 would publish a distinction the server would have + to invent. On this plane `bd recall` ALREADY distinguishes a miss, by + exit code, and the role answers a miss as a result rather than a value + — so a 404 reports a distinction that exists rather than minting one. + + + A MEMORY STORED AS THE EMPTY STRING IS A 404 TOO. No front door can + create one — storing empty content is refused — but an out-of-band write + to the config table can, and the role does not invent a distinction the + storage seam beneath it cannot see. `GET /v0/beads/memories` DOES + enumerate such a row, because its key exists, and that asymmetry is the + one way a client can tell the two apart. + + + MEMORY CONTENT IS SERVED IN FULL and this API has no authentication: + `Memory` carries no `redacted` member and withholds nothing. See + `POST /v0/beads/memories` for why a key-name heuristic would be worse + than no promise at all. + + + KEYS THIS OPERATION CANNOT REACH. `bd remember --key` accepts any + string, so a stored key may carry a control character — and `key` is one + path segment, percent-decoded once, so such a key would arrive here as a + decoded control character in a path. This operation refuses it with a + `400` rather than looking it up, exactly as `getSetting` does. The ROLE + stays verbatim: breaking `bd recall` of an odd key someone already + stored, to tidy a wire rule, would be the tail wagging the dog. Such a + memory is reachable from the CLI and from `GET /v0/beads/memories`, and + not by path. + parameters: + - $ref: '#/components/parameters/MemoryKey' + responses: + '200': + description: The stored memory. + content: + application/json: + schema: + $ref: '#/components/schemas/Memory' + '400': + description: >- + Invalid request: an unknown query parameter, or a `key` that is + empty after trimming or carries a control character. + x-bd-codes: [invalid_argument] + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + '404': + description: >- + This workspace holds no memory under that key — or holds one stored + as the empty string, which answers the same way. `detail` says which + plane was asked, not which of those two it was. + x-bd-codes: [not_found] + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + '500': + $ref: '#/components/responses/InternalError' + '503': + $ref: '#/components/responses/Unavailable' + delete: + operationId: forgetMemory + summary: Forget one stored memory + description: >- + Removes the memory stored under one key and answers with what it held — + the operation behind `bd forget`. IT IS DESTRUCTIVE and nothing it + removes comes back, on a surface that has NO AUTHENTICATION: every + process that can reach the port can erase any memory whose key it knows, + exactly as `issues:sweep` and `issues:delete` state for beads. The + recovery is the workspace's version control, not this API. + + + THE FIRST `DELETE` METHOD ON THIS SURFACE, and the shape is why. The two + destructive issue operations are collection-level custom methods because + they act on a SET the request describes and carry flags that change what + is erased — a query string is exactly where a dropped parameter widens a + deletion. This one names ONE resource by path, carries no body and takes + no flags, which is what the `DELETE` method already means. The + alternative spelling `POST /v0/beads/memories/{key}:forget` would in + addition recreate the claim route's wildcard contortion, since + `{key}:forget` is not a router pattern, for no gain. + + + REMOVING EXACTLY THE NAMED ROW is the ROLE's promise, pinned by its + conformance contract rather than restated here: the memory plane shares + one table with the workspace's settings and with the generic `bd kv` + namespace, and a memory called `issue_prefix` is not the workspace's + issue prefix. + + + Forgetting a key nothing stored is a `404` and removes nothing. + Forgetting the same key twice is therefore a `200` and then a `404`, + which is what a retrying client actually sees; the second answer is not + a failure to act, it is the same fact reported after the act. + + + The same keys are unreachable here as on the `GET` beside it: a stored + key carrying a control character is refused with a `400` rather than + looked up, while the role stays verbatim, so such a memory can be + forgotten from the CLI and not through this operation. + + + Hooks do not fire, as for every write on this surface. There is no + `dry_run`: one named row is not a set to cost first. + parameters: + - $ref: '#/components/parameters/MemoryKey' + responses: + '200': + description: >- + The memory was removed. The body carries what it held, read in the + same transaction as the deletion — so it is what was actually + removed rather than what an earlier read happened to see. + content: + application/json: + schema: + $ref: '#/components/schemas/Memory' + '400': + description: >- + Invalid request: an unknown query parameter, or a `key` that is + empty after trimming or carries a control character. Nothing is + removed in either case. + x-bd-codes: [invalid_argument] + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + '404': + description: >- + This workspace holds no memory under that key — or holds one stored + as the empty string, which answers the same way — and NOTHING WAS + REMOVED. + x-bd-codes: [not_found] + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + '500': + $ref: '#/components/responses/InternalError' + '503': + $ref: '#/components/responses/Unavailable' + components: parameters: @@ -1818,6 +2145,19 @@ components: schema: type: string minLength: 1 + MemoryKey: + name: key + in: path + required: true + description: >- + Exact memory key, used verbatim. It occupies one path segment and is + percent-decoded once. Keys may contain spaces, dots and unicode — the + plane stores what `bd remember --key` was given — and a key carrying a + CONTROL character is refused here rather than looked up; see the + operation description. + schema: + type: string + minLength: 1 IssueID: name: id in: path @@ -2810,7 +3150,9 @@ components: `issues.list`, `issues.query`, `issues.get`, `issues.claim`, `issues.sweep`, `issues.delete`, `issues.batchCreate`, `stats.get`, `config.list`, `config.get`, `dependencies.cycles`, - `dependencies.list`, `dependencies.blocking`, `dependencies.tree`; + `dependencies.list`, `dependencies.blocking`, `dependencies.tree`, + `memories.list`, `memories.get`, `memories.remember`, + `memories.forget`; it grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation — never the version string. @@ -3312,6 +3654,135 @@ components: Always present, including when false, so a client never has to infer redaction from an absent member. + Memory: + type: object + required: [key, value] + description: >- + One entry of the workspace's persistent memory plane. + + + NOT `x-go-type`-PINNED, for the reason `Setting` is not: the CLI + marshals an ad-hoc map per verb, so there is no canonical Go struct + whose JSON encoding is this contract, and minting one to pin to would + mean changing what `bd recall --json` prints in order to satisfy a rule + about not changing it. + + + IT HAS NO `redacted` MEMBER, and that is the deliberate difference from + `Setting`. Redaction there is a decision about the KEY NAME, which works + because settings keys are configured names; memory keys are derived from + the content, so the same rule would withhold a memory about credentials + and serve one containing a credential under an innocuous slug. This + surface has no authentication and states the exposure rather than + implying a protection it does not have. + properties: + key: + type: string + description: The memory's key, echoed verbatim. + value: + type: string + description: >- + The stored content, verbatim: newlines, surrounding space and + unicode as stored, never truncated and never withheld. + + + Always present. It is the empty string only where a row was written + out of band with an empty value, which + `GET /v0/beads/memories/{key}` answers as a `404` and + `GET /v0/beads/memories` enumerates. + + MemoriesPage: + type: object + required: [items, has_more] + properties: + items: + type: array + description: >- + The stored memories, ordered by key. Empty array (never null) when + the workspace holds none, or when `q` matched none. + items: + $ref: '#/components/schemas/Memory' + has_more: + type: boolean + description: >- + Always false in v0: the whole plane is returned in one page. It is + present so that a later revision can page this collection without + changing the response shape. + next_cursor: + type: string + description: >- + Present if and only if `has_more` is true, which is never in v0. + + RememberRequest: + type: object + additionalProperties: false + required: [content] + description: >- + What to remember, and optionally under what key. + properties: + content: + type: string + description: >- + The memory itself, stored VERBATIM: newlines, surrounding space and + unicode all survive. Flattening it to one line is what a front door + does when it prints, not what this plane does when it stores. + + + Empty after trimming is a `400`. So is content from which no key can + be derived when `key` is omitted — `"!!!"` derives to nothing — and + the recovery for that one is to send a `key`. + key: + type: string + description: >- + The key to store under. OMIT IT to have the server derive one from + `content`; the response's `key` is then how the caller learns where + the memory landed. + + + Supplied, it is used verbatim — no trimming, no slugging, no charset + restriction. A key carrying a control character is storable this way + and by `bd remember --key`, and is then unreachable through + `GET`/`DELETE /v0/beads/memories/{key}`, which refuse one: see those + operations. + + RememberedMemory: + type: object + required: [key, value, replaced] + description: >- + One stored memory, plus whether storing it overwrote a previous value. + + + It is `Memory`'s shape with `replaced` added rather than a composition + of it, because this document repeats property lists instead of using + `allOf` (see the note at the top of the file). + properties: + key: + type: string + description: >- + The key the memory now lives under: the one the request supplied, or + the one derived from `content`. Recall it under exactly these bytes. + value: + type: string + description: >- + The stored content, echoed verbatim. Always present, and never + withheld — this plane has no redaction; see the operation + description. + replaced: + type: boolean + description: >- + True when a previous value existed under `key` and this request + overwrote it; false when the key was new. It is observed in the same + transaction as the write, so it describes the row this request + wrote. + + + A previous value that was the EMPTY STRING reports true: the ROW + existed, even though `GET /v0/beads/memories/{key}` would have + answered `404` for it. That divergence is the storage seam's + conflation showing through, and it is stated rather than smoothed + over, because smoothing it would mean this member reporting + "nothing was there" about a write that overwrote something. + SettingsPage: type: object required: [items, has_more] diff --git a/internal/httpapi/spec_parity_test.go b/internal/httpapi/spec_parity_test.go index 773ba81fc..f65e638d4 100644 --- a/internal/httpapi/spec_parity_test.go +++ b/internal/httpapi/spec_parity_test.go @@ -331,6 +331,58 @@ func TestSpecDefaultsMatchSharedConstants(t *testing.T) { } } +// capabilityToken matches one backticked capability token in the +// `capabilities` description. The shape — a lowercase resource, a dot, a +// lowerCamel verb — is what every token on this surface is, and it is narrow +// enough that no other backticked word in that paragraph can be mistaken for +// one. +var capabilityToken = regexp.MustCompile("`([a-z]+\\.[a-zA-Z]+)`") + +// TestSpecCapabilityVocabularyMatchesTheRouteTable is the gate for the ONE +// piece of per-operation plumbing that had no gate. +// +// The `capabilities` description enumerates every token explicitly, in prose, +// and prose is not generated from anything: an operation could land with its +// route row, its handler, its problem codes and its spec path all correct and +// still never appear in the list a client is told to check. Nothing would fail. +// The document would simply be wrong about the one member it tells clients to +// dispatch on, and the drift would be discovered by a client, not by CI. +// +// Set equality both ways: a token in the prose with no implemented route is a +// capability advertised to readers and not to clients, and a route whose token +// the prose omits is an operation the document forgets it has. +// +// ORDER IS NOT CHECKED. The prose groups tokens by resource for a reader; +// Capabilities() sorts them for a client. Both are deliberate, and pinning one +// to the other would be a rule about paragraph layout. +func TestSpecCapabilityVocabularyMatchesTheRouteTable(t *testing.T) { + doc := loadSpec(t) + schema := mapAt(t, mapAt(t, mapAt(t, doc, "components"), "schemas"), "ContextResponse") + caps := mapAt(t, mapAt(t, schema, "properties"), "capabilities") + desc, _ := caps["description"].(string) + if desc == "" { + t.Fatal("the capabilities property has no description; it is where the token vocabulary is published") + } + + documented := map[string]bool{} + for _, m := range capabilityToken.FindAllStringSubmatch(desc, -1) { + documented[m[1]] = true + } + served := map[string]bool{} + for _, token := range Capabilities() { + served[token] = true + } + + if missing := diff(served, documented); len(missing) > 0 { + t.Errorf("this build serves capabilities the document does not enumerate: %v\n"+ + "add them to the `capabilities` description in internal/httpapi/spec/openapi.v0.yaml — "+ + "that paragraph is the vocabulary a client is told to check", missing) + } + if extra := diff(documented, served); len(extra) > 0 { + t.Errorf("the document enumerates capabilities no implemented route contributes: %v", extra) + } +} + func specParam(t *testing.T, so specOp, name string) map[string]any { t.Helper() raw, ok := so.op["parameters"].([]any) diff --git a/internal/jira/tracker_test.go b/internal/jira/tracker_test.go index a1aabdff2..f1b52789b 100644 --- a/internal/jira/tracker_test.go +++ b/internal/jira/tracker_test.go @@ -17,6 +17,7 @@ import ( "github.com/steveyegge/beads/internal/tracker" "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) func TestRegistered(t *testing.T) { @@ -663,6 +664,9 @@ func (s *configStore) Counter() (issueops.Counter, error) { func (s *configStore) WorkspaceConfig() (issueops.WorkspaceConfig, error) { return nil, &storage.ErrUnsupported{Op: "WorkspaceConfig", Backend: "jira-config-stub"} } +func (s *configStore) Memories() (memoryops.Memories, error) { + return nil, &storage.ErrUnsupported{Op: "Memories", Backend: "jira-config-stub"} +} func (s *configStore) StatsReporter() (issueops.StatsReporter, error) { return nil, &storage.ErrUnsupported{Op: "StatsReporter", Backend: "jira-config-stub"} } diff --git a/internal/memoryapi/memoryapi.go b/internal/memoryapi/memoryapi.go new file mode 100644 index 000000000..87966576c --- /dev/null +++ b/internal/memoryapi/memoryapi.go @@ -0,0 +1,160 @@ +// Package memoryapi holds the parts of the memory plane that decide what an +// answer MEANS: the key derivation, the two refusals and the search filter. +// Every implementation of memoryops.Memories goes through them, so they are the +// single definition of what `bd remember` and `bd memories` mean, and they are +// checkable in milliseconds with no database. +// +// It is its own package rather than a file in internal/workapi because nothing +// in it is issue-shaped, and it is deliberately importable by cmd/bd: the +// `bd remember` front door needs DeriveKey to spot the bare-slug desire path +// BEFORE it decides which role method to call, exactly as the twenty-odd cmd/bd +// files that import workapi need the builders. What a front door must not +// reach is a role CONSTRUCTOR, and there is none here — these are meaning +// functions, not bodies. +// +// The kv.memory. storage encoding is NOT here: that is +// internal/storage/memoryops, below the role, because a user key is what this +// package reasons about. +package memoryapi + +import ( + "fmt" + "regexp" + "strings" + + "github.com/steveyegge/beads/memoryops" +) + +// nonSlugChars matches every run of characters a derived key collapses to a +// single hyphen. +var nonSlugChars = regexp.MustCompile(`[^a-z0-9]+`) + +// DeriveKey turns memory content into the key it is stored under when the +// caller supplies none. It is `bd remember`'s slugify, moved verbatim. +// +// ITS QUIRKS ARE LOAD-BEARING AND MUST NOT BE TIDIED. Content is lowercased, +// every run of non-alphanumerics becomes ONE hyphen, the first EIGHT +// hyphen-separated segments are kept and the rest DROPPED, and the result is +// capped at 60 BYTES with a hyphen left at the cut trimmed off. All four are +// observable in the key, and a "cleanup" here silently re-keys every memory +// anyone re-remembers: `bd remember "always run tests with -race flag"` would +// mint a new key beside the old one instead of updating it, and the old memory +// would sit there forever answering an obsolete question. memoryapi_test.go +// pins the whole shape with a golden table. +// +// The SplitN bound of TEN below is the one quirk with no observable effect — +// keeping eight of at-most-ten segments and keeping eight of all of them agree +// on every input. It is preserved verbatim anyway, because "this simplification +// cannot change the answer" is exactly the reasoning that re-keys a workspace +// when it turns out to be wrong, and the golden table is what would catch it. +// +// The result is "" for content with no alphanumerics at all. Callers that +// derive must treat that as a refusal (ValidateDerivedKey), not as a key. +func DeriveKey(content string) string { + s := strings.ToLower(content) + s = nonSlugChars.ReplaceAllString(s, "-") + s = strings.Trim(s, "-") + + // Ten, then eight: the extra two segments are what keeps the tail of a long + // insight attached to the eighth word instead of being discarded. + parts := strings.SplitN(s, "-", 10) + if len(parts) > 8 { + parts = parts[:8] + } + slug := strings.Join(parts, "-") + + if len(slug) > 60 { + slug = slug[:60] + // A cap that landed mid-word must not leave the key ending in the + // separator. + slug = strings.TrimRight(slug, "-") + } + return slug +} + +// ValidateContent checks the content a caller wants to remember. +// +// The prose is `bd remember`'s, preserved: it is the sentence agents have been +// reading since the command shipped, and the sentinel is what code classifies +// on. +func ValidateContent(content string) error { + if strings.TrimSpace(content) == "" { + return fmt.Errorf("%w: memory content cannot be empty", memoryops.ErrValidation) + } + return nil +} + +// ValidateKey checks a key a caller wants to read or remove, and returns it +// UNCHANGED. +// +// Unchanged is the whole point: `bd remember --key` accepts any string, so a +// key differing from another only by surrounding space is a key someone may +// genuinely hold, and trimming it here would answer a different question from +// the one asked. The only rule is that a key has to name something. +func ValidateKey(key string) (string, error) { + if strings.TrimSpace(key) == "" { + return "", fmt.Errorf("%w: memory key must not be empty", memoryops.ErrValidation) + } + return key, nil +} + +// ResolveKey answers which key a Remember lands under: the caller's if it gave +// one, otherwise the derivation of the content. +// +// It is one function rather than a derivation at each implementation because +// the ORDER matters and is invisible once it is spelled twice: an explicit key +// is used verbatim even when it is content-shaped, and content is only ever +// derived from when no key was given. The refusal for content that derives to +// nothing lives here too, so a caller cannot get a row under the empty key by +// reaching the write through a body that forgot to check. +func ResolveKey(key, content string) (string, error) { + if err := ValidateContent(content); err != nil { + return "", err + } + if key != "" { + // THE SAME RULE READS AND WRITES USE. ValidateKey — which Recall and + // Forget run — refuses a key that is empty after trimming, so accepting + // one here mints a row that no memory operation can ever name again: + // enumerable by List forever, unrecallable, unforgettable, reachable + // only through `bd config unset` on the raw storage key. The HTTP + // surface inherits the same split, so POST would accept what GET and + // DELETE refuse. + // + // Surrounding space is still preserved on keys that survive this: the + // rule is that a key must NAME something, not that it must be tidy. + return ValidateKey(key) + } + derived := DeriveKey(content) + if derived == "" { + return "", fmt.Errorf("%w: could not generate key from content; use --key to specify one", memoryops.ErrValidation) + } + return derived, nil +} + +// FilterMemories narrows already-prefix-stripped memories by a raw search term. +// +// THE FOLDING IS HERE, on both sides. The shipped `bd memories` lowercased the +// term at the front door and the filter lowercased the stored values, which +// worked only for as long as every caller remembered the first half; a second +// door that passed the term through raw would have matched nothing and reported +// an empty plane. Now the caller passes what the user typed. +// +// The answer is a fresh map, never nil and never the argument: a caller holding +// the full plane must still hold it after asking a narrower question. +func FilterMemories(all map[string]string, search string) map[string]string { + if search == "" { + out := make(map[string]string, len(all)) + for k, v := range all { + out[k] = v + } + return out + } + needle := strings.ToLower(search) + out := make(map[string]string) + for k, v := range all { + if strings.Contains(strings.ToLower(k), needle) || strings.Contains(strings.ToLower(v), needle) { + out[k] = v + } + } + return out +} diff --git a/internal/memoryapi/memoryapi_test.go b/internal/memoryapi/memoryapi_test.go new file mode 100644 index 000000000..8951d38b4 --- /dev/null +++ b/internal/memoryapi/memoryapi_test.go @@ -0,0 +1,262 @@ +package memoryapi + +import ( + "errors" + "maps" + "testing" + + "github.com/steveyegge/beads/memoryops" +) + +// TestDeriveKeyGoldenTable is the pin that matters most in this package. +// +// DeriveKey has minted every auto-generated memory key since `bd remember` +// shipped, and the keys it minted are STORED: a change here does not fail, it +// re-keys. `bd remember "always run tests with -race flag"` would start writing +// a second row beside the memory the user has been updating for months, both +// rows would show up in `bd memories`, and nothing would report a problem. +// +// So this table is GOLDEN. Every row was produced by the shipped slugify, not +// by reading the code, and a row that changes is a decision about existing +// workspaces rather than a test to update. The rows are grouped by the property +// each one holds down. +func TestDeriveKeyGoldenTable(t *testing.T) { + for _, test := range []struct { + name string + content string + want string + }{ + // The everyday shape, including the two examples in the command's own + // help text — the keys agents have in their notes. + {"help text example", "always run tests with -race flag", "always-run-tests-with-race-flag"}, + {"prose insight", "Dolt phantom DBs hide in three places", "dolt-phantom-dbs-hide-in-three-places"}, + {"a bare slug round-trips", "dolt-phantoms", "dolt-phantoms"}, + + // Case folding and separator collapsing: one hyphen per RUN, whatever + // the run was made of. + {"uppercase folds", "UPPER CASE SHOUTING", "upper-case-shouting"}, + {"mixed whitespace collapses", "a b\tc\nd", "a-b-c-d"}, + {"dots collapse", "v1.2.3 release notes", "v1-2-3-release-notes"}, + {"underscores collapse", "snake_case_words here", "snake-case-words-here"}, + {"existing hyphens are just separators", "hyphenated-word stays split", "hyphenated-word-stays-split"}, + {"digits survive", "12345 67890", "12345-67890"}, + + // The eight-segment truncation, from both sides of the boundary. The + // tail is DROPPED, not folded into the eighth segment. + {"eight segments are kept whole", "one two three four five six seven eight", "one-two-three-four-five-six-seven-eight"}, + {"the ninth is dropped", "one two three four five six seven eight nine", "one-two-three-four-five-six-seven-eight"}, + {"and so is everything after the tenth", "one two three four five six seven eight nine ten eleven", "one-two-three-four-five-six-seven-eight"}, + {"segments from hyphens count the same", "one two three four five six seven eight-nine-ten", "one-two-three-four-five-six-seven-eight"}, + {"real prose hits the limit too", "the quick brown fox jumps over the lazy dog and keeps running forever", "the-quick-brown-fox-jumps-over-the-lazy"}, + + // The 60-byte cap, and the trailing-hyphen trim that only fires when + // the cut lands exactly on a separator. + {"cap cuts mid-word", "supercalifragilisticexpialidocious antidisestablishmentarianism pneumonoultramicroscopic", "supercalifragilisticexpialidocious-antidisestablishmentarian"}, + {"cap cuts mid-word again", "aaaaaaaaaa bbbbbbbbbb cccccccccc dddddddddd eeeeeeeeee ffffffffff", "aaaaaaaaaa-bbbbbbbbbb-cccccccccc-dddddddddd-eeeeeeeeee-fffff"}, + {"cap on a separator trims it", "aaaaaaaaaaa bbbbbbbbbbb ccccccccccc ddddddddddd eeeeeeeeeee fff", "aaaaaaaaaaa-bbbbbbbbbbb-ccccccccccc-ddddddddddd-eeeeeeeeeee"}, + {"one long word is capped", "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-tail", "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}, + + // Non-ASCII is not transliterated, it is SEPARATOR. An accented word + // shatters into fragments, and a script with no ASCII at all derives + // nothing — which is the case ResolveKey has to refuse. + {"accents shatter the word", "Café naïve résumé", "caf-na-ve-r-sum"}, + {"non-latin derives nothing", "日本語のメモ", ""}, + + // Nothing to derive from. + {"punctuation only", "!!!", ""}, + {"hyphens only", "---", ""}, + {"whitespace only", " ", ""}, + {"empty", "", ""}, + {"trailing punctuation is trimmed", "trailing punctuation!!!", "trailing-punctuation"}, + } { + t.Run(test.name, func(t *testing.T) { + if got := DeriveKey(test.content); got != test.want { + t.Fatalf("DeriveKey(%q) = %q, want %q\n"+ + "This is a GOLDEN table: if the change was deliberate, it re-keys every "+ + "memory whose content derives differently, and the old rows stay behind.", + test.content, got, test.want) + } + }) + } +} + +// TestDeriveKeyNeverExceedsTheCap is the property behind three of the rows +// above, asserted over all of them at once so a future row cannot quietly widen +// the key space past what the config key column and the merge resolver have +// been carrying. +func TestDeriveKeyNeverExceedsTheCap(t *testing.T) { + for _, content := range []string{ + "supercalifragilisticexpialidocious antidisestablishmentarianism pneumonoultramicroscopic", + "aaaaaaaaaa bbbbbbbbbb cccccccccc dddddddddd eeeeeeeeee ffffffffff", + "aaaaaaaaaaa bbbbbbbbbbb ccccccccccc ddddddddddd eeeeeeeeeee fff", + } { + got := DeriveKey(content) + if len(got) > 60 { + t.Fatalf("DeriveKey(%q) is %d bytes, want at most 60", content, len(got)) + } + if got != "" && got[len(got)-1] == '-' { + t.Fatalf("DeriveKey(%q) = %q ends on the separator", content, got) + } + } +} + +// TestValidateContentRefusesNothingToRemember pins the first refusal as the +// SENTINEL rather than the message: the front doors and the HTTP problem +// classifier both branch on errors.Is, and a body that wrapped this error would +// keep them working while a string comparison would not. +func TestValidateContentRefusesNothingToRemember(t *testing.T) { + for _, blank := range []string{"", " ", "\t\n"} { + if err := ValidateContent(blank); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("ValidateContent(%q) = %v, want ErrValidation", blank, err) + } + } + if err := ValidateContent(" x "); err != nil { + t.Fatalf("ValidateContent(%q) = %v, want success: trimming decides the refusal, not the storage", " x ", err) + } +} + +// TestValidateKeyReturnsTheKeyUntouched pins that this validator does not +// normalize. A key with surrounding space is a key someone can hold, and +// trimming it here would read a different row from the one `bd remember --key` +// wrote. +func TestValidateKeyReturnsTheKeyUntouched(t *testing.T) { + for _, blank := range []string{"", " "} { + if _, err := ValidateKey(blank); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("ValidateKey(%q) = %v, want ErrValidation", blank, err) + } + } + for _, key := range []string{" padded ", "Has Spaces.✓", "dolt-phantoms", "issue_prefix"} { + got, err := ValidateKey(key) + if err != nil { + t.Fatalf("ValidateKey(%q) = %v, want success", key, err) + } + if got != key { + t.Fatalf("ValidateKey(%q) = %q, want the key unchanged", key, got) + } + } +} + +// TestResolveKeyPrefersTheExplicitKey pins the order: an explicit key wins even +// when it is content-shaped, and content is only derived from when none was +// given. +func TestResolveKeyPrefersTheExplicitKey(t *testing.T) { + got, err := ResolveKey("Has Spaces.✓", "always run tests with -race flag") + if err != nil { + t.Fatalf("ResolveKey with an explicit key = %v, want success", err) + } + if got != "Has Spaces.✓" { + t.Fatalf("ResolveKey = %q, want the explicit key verbatim", got) + } + + got, err = ResolveKey("", "always run tests with -race flag") + if err != nil { + t.Fatalf("ResolveKey with no key = %v, want success", err) + } + if got != "always-run-tests-with-race-flag" { + t.Fatalf("ResolveKey = %q, want the derivation", got) + } +} + +// TestResolveKeyRefusesWhatItCannotName pins both refusals at the one seam +// every implementation goes through, including the ORDER: empty content is +// refused as empty content even though it also derives to nothing, because that +// is the message a caller can act on. +func TestResolveKeyRefusesWhatItCannotName(t *testing.T) { + if _, err := ResolveKey("", " "); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("ResolveKey(\"\", blank) = %v, want ErrValidation", err) + } + if _, err := ResolveKey("", "!!!"); !errors.Is(err, memoryops.ErrValidation) { + t.Fatalf("ResolveKey(\"\", \"!!!\") = %v, want ErrValidation", err) + } + // An explicit key rescues underivable content: that is what --key is for. + if _, err := ResolveKey("shouting", "!!!"); err != nil { + t.Fatalf("ResolveKey(\"shouting\", \"!!!\") = %v, want success", err) + } +} + +// TestFilterMemoriesFoldsBothSides pins the property that made this function +// worth extracting: the caller passes the term the user typed, and matching is +// case-insensitive on the key AND the value. +func TestFilterMemoriesFoldsBothSides(t *testing.T) { + all := map[string]string{ + "dolt-phantoms": "Dolt phantom DBs hide in three places", + "auth-jwt": "auth module uses JWT not sessions", + "race-flag": "always run tests with -race flag", + } + + for _, test := range []struct { + name string + search string + want []string + }{ + {"uppercase term matches a lowercase key", "DOLT", []string{"dolt-phantoms"}}, + {"lowercase term matches an uppercase value", "jwt", []string{"auth-jwt"}}, + {"a term matching only the value still matches", "sessions", []string{"auth-jwt"}}, + {"empty search is everything", "", []string{"auth-jwt", "dolt-phantoms", "race-flag"}}, + {"a miss is empty, not nil", "nothing-here", nil}, + } { + t.Run(test.name, func(t *testing.T) { + got := FilterMemories(all, test.search) + if got == nil { + t.Fatal("FilterMemories returned a nil map; the contract promises an empty one") + } + if len(got) != len(test.want) { + t.Fatalf("FilterMemories(%q) = %v, want keys %v", test.search, got, test.want) + } + for _, key := range test.want { + if got[key] != all[key] { + t.Fatalf("FilterMemories(%q)[%q] = %q, want %q", test.search, key, got[key], all[key]) + } + } + }) + } +} + +// TestFilterMemoriesDoesNotAliasItsArgument pins that a caller holding the +// whole plane still holds it after asking a narrower question. Returning the +// argument map for an empty search would be the cheap version, and it would +// make one caller's filtering visible to another. +func TestFilterMemoriesDoesNotAliasItsArgument(t *testing.T) { + all := map[string]string{"a": "1", "b": "2"} + before := maps.Clone(all) + + filtered := FilterMemories(all, "") + filtered["c"] = "3" + delete(filtered, "a") + + if !maps.Equal(all, before) { + t.Fatalf("FilterMemories mutated its argument: %v, want %v", all, before) + } +} + +// TestResolveKeyRefusesAWhitespaceOnlyExplicitKey pins the rule Remember shares +// with Recall and Forget. +// +// ValidateKey refuses a key that is empty after trimming, and Recall and Forget +// both run it. ResolveKey used to accept any non-empty string, so +// `--key " "` minted a row that no memory operation could name again: +// enumerable by List forever, unrecallable, unforgettable, reachable only +// through `bd config unset` on the raw storage key. Four separate review lenses +// found it independently. +// +// The keys that SURVIVE matter as much as the ones refused: surrounding space +// is preserved, because the rule is that a key must name something, not that it +// must be tidy. +func TestResolveKeyRefusesAWhitespaceOnlyExplicitKey(t *testing.T) { + const content = "some content that derives fine" + for _, key := range []string{" ", " ", "\t", "\n", " \t\n "} { + if _, err := ResolveKey(key, content); !errors.Is(err, memoryops.ErrValidation) { + t.Errorf("ResolveKey(%q) error = %v, want ErrValidation: a key no read can name must not be writable", key, err) + } + } + for _, key := range []string{" leading", "trailing ", " both ", "has space"} { + got, err := ResolveKey(key, content) + if err != nil { + t.Errorf("ResolveKey(%q) error = %v, want the key verbatim", key, err) + continue + } + if got != key { + t.Errorf("ResolveKey(%q) = %q, want it byte for byte: surrounding space is preserved", key, got) + } + } +} diff --git a/internal/storage/dolt/memories.go b/internal/storage/dolt/memories.go new file mode 100644 index 000000000..8ec10f89f --- /dev/null +++ b/internal/storage/dolt/memories.go @@ -0,0 +1,100 @@ +package dolt + +import ( + "context" + "database/sql" + + "github.com/steveyegge/beads/internal/memoryapi" + "github.com/steveyegge/beads/internal/storage" + storagememoryops "github.com/steveyegge/beads/internal/storage/memoryops" + "github.com/steveyegge/beads/memoryops" +) + +// Memories returns the guarded persistent-memory surface for this store. +func (s *DoltStore) Memories() (memoryops.Memories, error) { + return newMemories(s) +} + +// newMemories returns guarded memory operations backed by store. +// +// It is unexported, like newEdgeReader beside it: the shared body is a set of +// InTx functions that need a transaction this store owns, so no front door can +// reach it at all and there is nothing for a depguard entry to deny. +func newMemories(store *DoltStore) (memoryops.Memories, error) { + if store == nil { + return nil, &storage.ErrUnsupported{Op: "newMemories", Backend: "nil"} + } + return &memories{store: store}, nil +} + +type memories struct{ store *DoltStore } + +var _ memoryops.Memories = (*memories)(nil) + +// Remember validates and derives BEFORE opening the transaction, so a refusal +// cannot be mistaken at the call site for a write that rolled back, and then +// probes and writes inside ONE retryable transaction. +func (m *memories) Remember(ctx context.Context, req memoryops.RememberRequest) (memoryops.RememberResult, error) { + key, err := memoryapi.ResolveKey(req.Key, req.Content) + if err != nil { + return memoryops.RememberResult{}, err + } + var replaced bool + if err := m.store.withRetryTx(ctx, func(tx *sql.Tx) error { + var err error + replaced, err = storagememoryops.RememberInTx(ctx, tx, key, req.Content) + return err + }); err != nil { + return memoryops.RememberResult{}, err + } + return memoryops.RememberResult{Key: key, Value: req.Content, Replaced: replaced}, nil +} + +func (m *memories) Recall(ctx context.Context, req memoryops.RecallRequest) (memoryops.RecallResult, error) { + key, err := memoryapi.ValidateKey(req.Key) + if err != nil { + return memoryops.RecallResult{}, err + } + var value string + if err := m.store.withReadTx(ctx, func(tx *sql.Tx) error { + var err error + value, err = storagememoryops.RecallInTx(ctx, tx, key) + return err + }); err != nil { + return memoryops.RecallResult{}, err + } + return memoryops.RecallResult{Key: key, Value: value, Found: value != ""}, nil +} + +// Forget reads the value and deletes the row in ONE transaction, so the value +// it reports is the one it removed. +func (m *memories) Forget(ctx context.Context, req memoryops.ForgetRequest) (memoryops.ForgetResult, error) { + key, err := memoryapi.ValidateKey(req.Key) + if err != nil { + return memoryops.ForgetResult{}, err + } + var ( + previous string + found bool + ) + if err := m.store.withRetryTx(ctx, func(tx *sql.Tx) error { + var err error + previous, found, err = storagememoryops.ForgetInTx(ctx, tx, key) + return err + }); err != nil { + return memoryops.ForgetResult{}, err + } + return memoryops.ForgetResult{Key: key, Value: previous, Found: found}, nil +} + +func (m *memories) List(ctx context.Context, req memoryops.ListRequest) (memoryops.ListResult, error) { + var all map[string]string + if err := m.store.withReadTx(ctx, func(tx *sql.Tx) error { + var err error + all, err = storagememoryops.ListInTx(ctx, tx) + return err + }); err != nil { + return memoryops.ListResult{}, err + } + return memoryops.ListResult{Memories: memoryapi.FilterMemories(all, req.Search)}, nil +} diff --git a/internal/storage/dolt/memories_contract_test.go b/internal/storage/dolt/memories_contract_test.go new file mode 100644 index 000000000..4e7d0cdc4 --- /dev/null +++ b/internal/storage/dolt/memories_contract_test.go @@ -0,0 +1,111 @@ +package dolt + +import ( + "context" + "testing" + + "github.com/steveyegge/beads/backend/conformance" +) + +// TestMemoriesContract runs the Memories contract against the server-backed +// store. +// +// The cases are subtests of one parent so the whole role suite shares one store +// and one copy-on-write branch. Config keys are GLOBAL to a workspace, so the +// cases namespace their probe keys under the fixture prefix — except the two +// that cannot be, issue_prefix and the memory that shadows it, which are the +// point of the trap class. +// +// ORDER MATTERS HERE, in two places: ListOfAnEmptyPlaneAnswersAnEmptyMap has to +// see an untouched plane and so runs FIRST, and the refused-write case takes a +// history delta. Both are only meaningful while the subtests run sequentially. +// setupTestStore already marks the PARENT parallel; no subtest here calls +// t.Parallel. +func TestMemoriesContract(t *testing.T) { + fixture, ctx, cleanup := newDoltMemoriesFixture(t, "mem") + defer cleanup() + + t.Run("ListOfAnEmptyPlaneAnswersAnEmptyMap", func(t *testing.T) { + conformance.RunMemoriesListOfAnEmptyPlaneAnswersAnEmptyMap(t, ctx, fixture) + }) + t.Run("RememberStoresContentVerbatim", func(t *testing.T) { + conformance.RunMemoriesRememberStoresContentVerbatim(t, ctx, fixture) + }) + t.Run("RememberDerivesTheKeyWhenAbsent", func(t *testing.T) { + conformance.RunMemoriesRememberDerivesTheKeyWhenAbsent(t, ctx, fixture) + }) + t.Run("RememberWithExplicitKeyStoresVerbatim", func(t *testing.T) { + conformance.RunMemoriesRememberWithExplicitKeyStoresVerbatim(t, ctx, fixture) + }) + t.Run("RememberReplacesAndReportsIt", func(t *testing.T) { + conformance.RunMemoriesRememberReplacesAndReportsIt(t, ctx, fixture) + }) + t.Run("RememberRefusesEmptyContent", func(t *testing.T) { + conformance.RunMemoriesRememberRefusesEmptyContent(t, ctx, fixture) + }) + t.Run("RememberRefusesAWhitespaceOnlyKey", func(t *testing.T) { + conformance.RunMemoriesRememberRefusesAWhitespaceOnlyKey(t, ctx, fixture) + }) + t.Run("RememberRefusesAnUnderivableKey", func(t *testing.T) { + conformance.RunMemoriesRememberRefusesAnUnderivableKey(t, ctx, fixture) + }) + t.Run("RecallAnswersTheStoredValue", func(t *testing.T) { + conformance.RunMemoriesRecallAnswersTheStoredValue(t, ctx, fixture) + }) + t.Run("RecallReportsAMissAsNotFoundNotAnError", func(t *testing.T) { + conformance.RunMemoriesRecallReportsAMissAsNotFoundNotAnError(t, ctx, fixture) + }) + t.Run("RecallConflatesStoredEmptyWithAbsent", func(t *testing.T) { + conformance.RunMemoriesRecallConflatesStoredEmptyWithAbsent(t, ctx, fixture) + }) + t.Run("ForgetRemovesExactlyTheNamedRow", func(t *testing.T) { + conformance.RunMemoriesForgetRemovesExactlyTheNamedRow(t, ctx, fixture) + }) + t.Run("ForgetNeverTouchesTheSettingsPlane", func(t *testing.T) { + conformance.RunMemoriesForgetNeverTouchesTheSettingsPlane(t, ctx, fixture) + }) + t.Run("ForgetReportsTheForgottenValue", func(t *testing.T) { + conformance.RunMemoriesForgetReportsTheForgottenValue(t, ctx, fixture) + }) + t.Run("ForgetOfAnAbsentKeyIsNotFoundAndDeletesNothing", func(t *testing.T) { + conformance.RunMemoriesForgetOfAnAbsentKeyIsNotFoundAndDeletesNothing(t, ctx, fixture) + }) + t.Run("ListReturnsOnlyTheMemoryPlane", func(t *testing.T) { + conformance.RunMemoriesListReturnsOnlyTheMemoryPlane(t, ctx, fixture) + }) + t.Run("ListSearchMatchesTheUserKeyNotTheStorageKey", func(t *testing.T) { + conformance.RunMemoriesListSearchMatchesTheUserKeyNotTheStorageKey(t, ctx, fixture) + }) + t.Run("ListSearchMatchesKeyOrValueCaseInsensitively", func(t *testing.T) { + conformance.RunMemoriesListSearchMatchesKeyOrValueCaseInsensitively(t, ctx, fixture) + }) + t.Run("ARefusedWriteRecordsNoHistory", func(t *testing.T) { + conformance.RunMemoriesARefusedWriteRecordsNoHistory(t, ctx, fixture) + }) +} + +func newDoltMemoriesFixture(t *testing.T, prefix string) (conformance.MemoriesFixture, context.Context, func()) { + t.Helper() + store, storeCleanup := setupTestStore(t) + ctx, cancel := testContext(t) + // Through the accessor, never newMemories: the accessor is where each + // storage decorator adds its layer. + memories, err := store.Memories() + if err != nil { + cancel() + storeCleanup() + t.Fatalf("Memories(): %v", err) + } + kit := newDoltRoleFixtureKit(store, prefix) + fixture := conformance.MemoriesFixture{ + IssuePrefix: kit.IssuePrefix, + Memories: memories, + SetConfig: kit.SetConfig, + QueryScalar: kit.QueryScalar, + CountHistory: kit.CountHistory, + } + return fixture, ctx, func() { + cancel() + storeCleanup() + } +} diff --git a/internal/storage/dolt/workspace_config_contract_test.go b/internal/storage/dolt/workspace_config_contract_test.go index 31f40489a..b2437b3ea 100644 --- a/internal/storage/dolt/workspace_config_contract_test.go +++ b/internal/storage/dolt/workspace_config_contract_test.go @@ -33,6 +33,9 @@ func TestWorkspaceConfigContract(t *testing.T) { t.Run("ListsEveryStoredSetting", func(t *testing.T) { conformance.RunWorkspaceConfigListsEveryStoredSetting(t, ctx, fixture) }) + t.Run("ListExcludesTheKVPlane", func(t *testing.T) { + conformance.RunWorkspaceConfigListExcludesTheKVPlane(t, ctx, fixture) + }) t.Run("UnsetRemovesTheSetting", func(t *testing.T) { conformance.RunWorkspaceConfigUnsetRemovesTheSetting(t, ctx, fixture) }) diff --git a/internal/storage/embeddeddolt/memories.go b/internal/storage/embeddeddolt/memories.go new file mode 100644 index 000000000..75d3f6ad4 --- /dev/null +++ b/internal/storage/embeddeddolt/memories.go @@ -0,0 +1,98 @@ +//go:build cgo + +package embeddeddolt + +import ( + "context" + "database/sql" + + "github.com/steveyegge/beads/internal/memoryapi" + "github.com/steveyegge/beads/internal/storage" + storagememoryops "github.com/steveyegge/beads/internal/storage/memoryops" + "github.com/steveyegge/beads/memoryops" +) + +// Memories returns the guarded persistent-memory surface for this store. +func (s *EmbeddedDoltStore) Memories() (memoryops.Memories, error) { + return newMemories(s) +} + +// newMemories returns guarded memory operations backed by store. It is +// unexported for the reason the server-backed sibling gives: the accessor above +// is the door, because that is where each decorator adds its layer. +func newMemories(store *EmbeddedDoltStore) (memoryops.Memories, error) { + if store == nil { + return nil, &storage.ErrUnsupported{Op: "newMemories", Backend: "nil"} + } + return &memories{store: store}, nil +} + +type memories struct{ store *EmbeddedDoltStore } + +var _ memoryops.Memories = (*memories)(nil) + +// Remember validates and derives before the connection is taken, then probes +// and writes on ONE connection — the embedded engine's version of the single +// transaction the server-backed store gets from withRetryTx. +func (m *memories) Remember(ctx context.Context, req memoryops.RememberRequest) (memoryops.RememberResult, error) { + key, err := memoryapi.ResolveKey(req.Key, req.Content) + if err != nil { + return memoryops.RememberResult{}, err + } + var replaced bool + if err := m.store.withConn(ctx, true, func(tx *sql.Tx) error { + var err error + replaced, err = storagememoryops.RememberInTx(ctx, tx, key, req.Content) + return err + }); err != nil { + return memoryops.RememberResult{}, err + } + return memoryops.RememberResult{Key: key, Value: req.Content, Replaced: replaced}, nil +} + +func (m *memories) Recall(ctx context.Context, req memoryops.RecallRequest) (memoryops.RecallResult, error) { + key, err := memoryapi.ValidateKey(req.Key) + if err != nil { + return memoryops.RecallResult{}, err + } + var value string + if err := m.store.withConn(ctx, false, func(tx *sql.Tx) error { + var err error + value, err = storagememoryops.RecallInTx(ctx, tx, key) + return err + }); err != nil { + return memoryops.RecallResult{}, err + } + return memoryops.RecallResult{Key: key, Value: value, Found: value != ""}, nil +} + +func (m *memories) Forget(ctx context.Context, req memoryops.ForgetRequest) (memoryops.ForgetResult, error) { + key, err := memoryapi.ValidateKey(req.Key) + if err != nil { + return memoryops.ForgetResult{}, err + } + var ( + previous string + found bool + ) + if err := m.store.withConn(ctx, true, func(tx *sql.Tx) error { + var err error + previous, found, err = storagememoryops.ForgetInTx(ctx, tx, key) + return err + }); err != nil { + return memoryops.ForgetResult{}, err + } + return memoryops.ForgetResult{Key: key, Value: previous, Found: found}, nil +} + +func (m *memories) List(ctx context.Context, req memoryops.ListRequest) (memoryops.ListResult, error) { + var all map[string]string + if err := m.store.withConn(ctx, false, func(tx *sql.Tx) error { + var err error + all, err = storagememoryops.ListInTx(ctx, tx) + return err + }); err != nil { + return memoryops.ListResult{}, err + } + return memoryops.ListResult{Memories: memoryapi.FilterMemories(all, req.Search)}, nil +} diff --git a/internal/storage/embeddeddolt/memories_contract_test.go b/internal/storage/embeddeddolt/memories_contract_test.go new file mode 100644 index 000000000..28baf2b2c --- /dev/null +++ b/internal/storage/embeddeddolt/memories_contract_test.go @@ -0,0 +1,102 @@ +//go:build cgo + +package embeddeddolt_test + +import ( + "testing" + + "github.com/steveyegge/beads/backend/conformance" +) + +// TestMemoriesContract runs the Memories contract against the embedded store, +// which hands back the SAME body the server-backed store does (the …InTx +// functions in internal/storage/memoryops), differing only in the engine +// underneath. It is not an independent vote on the body. +// +// One environment for the whole suite, and here that is a CORRECTNESS +// requirement: config keys are global to a workspace, the trap class writes +// issue_prefix and its shadow by name, ListOfAnEmptyPlaneAnswersAnEmptyMap has +// to see an untouched plane and so runs FIRST, and the refused-write case takes +// a history delta — all of which need the subtests sequential over one plane. +func TestMemoriesContract(t *testing.T) { + skipUnlessEmbeddedDolt(t) + te := newTestEnv(t, "mem") + ctx := t.Context() + fixture := newEmbeddedMemoriesFixture(t, te, "mem") + + t.Run("ListOfAnEmptyPlaneAnswersAnEmptyMap", func(t *testing.T) { + conformance.RunMemoriesListOfAnEmptyPlaneAnswersAnEmptyMap(t, ctx, fixture) + }) + t.Run("RememberStoresContentVerbatim", func(t *testing.T) { + conformance.RunMemoriesRememberStoresContentVerbatim(t, ctx, fixture) + }) + t.Run("RememberDerivesTheKeyWhenAbsent", func(t *testing.T) { + conformance.RunMemoriesRememberDerivesTheKeyWhenAbsent(t, ctx, fixture) + }) + t.Run("RememberWithExplicitKeyStoresVerbatim", func(t *testing.T) { + conformance.RunMemoriesRememberWithExplicitKeyStoresVerbatim(t, ctx, fixture) + }) + t.Run("RememberReplacesAndReportsIt", func(t *testing.T) { + conformance.RunMemoriesRememberReplacesAndReportsIt(t, ctx, fixture) + }) + t.Run("RememberRefusesEmptyContent", func(t *testing.T) { + conformance.RunMemoriesRememberRefusesEmptyContent(t, ctx, fixture) + }) + t.Run("RememberRefusesAWhitespaceOnlyKey", func(t *testing.T) { + conformance.RunMemoriesRememberRefusesAWhitespaceOnlyKey(t, ctx, fixture) + }) + t.Run("RememberRefusesAnUnderivableKey", func(t *testing.T) { + conformance.RunMemoriesRememberRefusesAnUnderivableKey(t, ctx, fixture) + }) + t.Run("RecallAnswersTheStoredValue", func(t *testing.T) { + conformance.RunMemoriesRecallAnswersTheStoredValue(t, ctx, fixture) + }) + t.Run("RecallReportsAMissAsNotFoundNotAnError", func(t *testing.T) { + conformance.RunMemoriesRecallReportsAMissAsNotFoundNotAnError(t, ctx, fixture) + }) + t.Run("RecallConflatesStoredEmptyWithAbsent", func(t *testing.T) { + conformance.RunMemoriesRecallConflatesStoredEmptyWithAbsent(t, ctx, fixture) + }) + t.Run("ForgetRemovesExactlyTheNamedRow", func(t *testing.T) { + conformance.RunMemoriesForgetRemovesExactlyTheNamedRow(t, ctx, fixture) + }) + t.Run("ForgetNeverTouchesTheSettingsPlane", func(t *testing.T) { + conformance.RunMemoriesForgetNeverTouchesTheSettingsPlane(t, ctx, fixture) + }) + t.Run("ForgetReportsTheForgottenValue", func(t *testing.T) { + conformance.RunMemoriesForgetReportsTheForgottenValue(t, ctx, fixture) + }) + t.Run("ForgetOfAnAbsentKeyIsNotFoundAndDeletesNothing", func(t *testing.T) { + conformance.RunMemoriesForgetOfAnAbsentKeyIsNotFoundAndDeletesNothing(t, ctx, fixture) + }) + t.Run("ListReturnsOnlyTheMemoryPlane", func(t *testing.T) { + conformance.RunMemoriesListReturnsOnlyTheMemoryPlane(t, ctx, fixture) + }) + t.Run("ListSearchMatchesTheUserKeyNotTheStorageKey", func(t *testing.T) { + conformance.RunMemoriesListSearchMatchesTheUserKeyNotTheStorageKey(t, ctx, fixture) + }) + t.Run("ListSearchMatchesKeyOrValueCaseInsensitively", func(t *testing.T) { + conformance.RunMemoriesListSearchMatchesKeyOrValueCaseInsensitively(t, ctx, fixture) + }) + t.Run("ARefusedWriteRecordsNoHistory", func(t *testing.T) { + conformance.RunMemoriesARefusedWriteRecordsNoHistory(t, ctx, fixture) + }) +} + +func newEmbeddedMemoriesFixture(t *testing.T, te *testEnv, prefix string) conformance.MemoriesFixture { + t.Helper() + // Through the accessor, never newMemories: the accessor is where each + // storage decorator adds its layer. + memories, err := te.store.Memories() + if err != nil { + t.Fatalf("Memories(): %v", err) + } + kit := newEmbeddedRoleFixtureKit(te, prefix) + return conformance.MemoriesFixture{ + IssuePrefix: kit.IssuePrefix, + Memories: memories, + SetConfig: kit.SetConfig, + QueryScalar: kit.QueryScalar, + CountHistory: kit.CountHistory, + } +} diff --git a/internal/storage/embeddeddolt/workspace_config_contract_test.go b/internal/storage/embeddeddolt/workspace_config_contract_test.go index 6dba96c0f..9357db7ff 100644 --- a/internal/storage/embeddeddolt/workspace_config_contract_test.go +++ b/internal/storage/embeddeddolt/workspace_config_contract_test.go @@ -35,6 +35,9 @@ func TestWorkspaceConfigContract(t *testing.T) { t.Run("ListsEveryStoredSetting", func(t *testing.T) { conformance.RunWorkspaceConfigListsEveryStoredSetting(t, ctx, fixture) }) + t.Run("ListExcludesTheKVPlane", func(t *testing.T) { + conformance.RunWorkspaceConfigListExcludesTheKVPlane(t, ctx, fixture) + }) t.Run("UnsetRemovesTheSetting", func(t *testing.T) { conformance.RunWorkspaceConfigUnsetRemovesTheSetting(t, ctx, fixture) }) diff --git a/internal/storage/hook_memories.go b/internal/storage/hook_memories.go new file mode 100644 index 000000000..8bf7dfb32 --- /dev/null +++ b/internal/storage/hook_memories.go @@ -0,0 +1,23 @@ +package storage + +import ( + "github.com/steveyegge/beads/memoryops" +) + +// Memories returns the inner store's persistent-memory surface. +// +// IT RECURSES UNWRAPPED, and that is a decision rather than an omission. +// Remember and Forget are writes, so the reflex is to reach for hook_commenter +// — but this decorator's whole vocabulary is on_create, on_update and on_close, +// and every one of them hands a hook script an ISSUE. There is no on_remember, +// a memory has no id a script could read back, and inventing an event so this +// file could fire one would be a hook-vocabulary proposal wearing a role +// commit's clothes. This is the Sweeper case, not the Commenter case. +// +// So the accessor EXISTS on this decorator — declared, never inherited, which +// the reflection test in role_accessor_decorator_test.go asserts — and adds no +// layer. If a memory event ever joins the hook vocabulary, this file is where +// it lands. +func (h *HookFiringStore) Memories() (memoryops.Memories, error) { + return h.inner.Memories() +} diff --git a/internal/storage/memoryops/memories.go b/internal/storage/memoryops/memories.go new file mode 100644 index 000000000..a9c58e1ff --- /dev/null +++ b/internal/storage/memoryops/memories.go @@ -0,0 +1,169 @@ +// Package memoryops holds the transaction-level body of +// memoryops.Memories: the kv.memory. encoding and the four operations, each +// written so that the existence PROBE and the act it qualifies happen inside +// ONE transaction. +// +// It lives here rather than in internal/workapi/store/ for the reason +// internal/storage/issueops' relations.go and edges.go do: this role's writes +// are "read the row, then write over it and report what was there", and +// storage.DoltStorage publishes methods rather than transactions, so a body +// written against it could not scope the two calls together. The shipped +// commands did exactly that — GetConfig, then SetConfig — and papered over the +// gap with `existing, _ :=`, which makes "Remembered" versus "Updated" and the +// value `bd forget` prints hopeful rather than true. +// +// There is no exported constructor and no exported body type, so there is +// nothing for a depguard entry to deny: every function here takes a *sql.Tx, +// which no front door holds. That is why the cmd-bd-role-constructors list in +// .golangci.yml gains no entry for this role. +// +// TWO THINGS THIS PACKAGE DELIBERATELY DOES NOT DO: +// +// - NO CACHE WORK. DoltStore's config-adjacent caches key on status.custom, +// types.custom and types.infra only (dolt/config.go), and no kv.* key feeds +// one, so these raw-row writes leave nothing stale behind them. Stated so +// the next reader does not have to re-derive it from the cache code. +// - NO DOLT COMMIT. The store wrappers run these under the same runners the +// legacy SetConfig/DeleteConfig calls used (withRetryTx on the server-backed +// store, withConn(write) on the embedded one), and durability on that route +// stays the CLI's auto-commit epilogue. The unit-of-work route keeps its +// per-write commit. The two routes' Dolt history shapes differ today and +// continue to. +package memoryops + +import ( + "context" + "database/sql" + "errors" + "fmt" + "strings" + + "github.com/steveyegge/beads/internal/storage/issueops" + "github.com/steveyegge/beads/internal/storage/kvkeys" +) + +// StorageKey encodes a user key as the config-table key it is stored under. +// +// IT IS THE ONE ENCODE IN THE TREE, and the strip below is the one decode. Both +// implementations of the role reach them — the store-backed InTx functions in +// this file and the unit-of-work body, which composes the config use case +// instead of these functions but must agree with them byte for byte or the two +// routes stop seeing each other's memories. A second copy of +// `kvkeys.Prefix + kvkeys.MemoryPrefix + key` is the drift kvkeys was created to +// end. +func StorageKey(userKey string) string { + return kvkeys.MemoryConfigKeyPrefix + userKey +} + +// MemoriesFromConfig narrows a whole config map to the memory plane, stripping +// the prefix so the keys are the ones the caller named. +// +// THE PREFIX IS THE FULL "kv.memory.", not "kv.". The config table holds +// settings rows, generic `bd kv` rows and memory rows at once, and the two +// mistakes this function exists to not make are filtering on the shorter prefix +// — which serves every `bd kv set` value as a memory — and trimming a different +// number of bytes than it matched, which re-keys every answer. Both are silent: +// they produce a plausible map. +func MemoriesFromConfig(all map[string]string) map[string]string { + memories := make(map[string]string) + for key, value := range all { + if userKey, ok := strings.CutPrefix(key, kvkeys.MemoryConfigKeyPrefix); ok { + memories[userKey] = value + } + } + return memories +} + +// RememberInTx stores one memory and reports whether it replaced one, both in +// the caller's transaction. +// +// The probe is not tolerant: a read that fails fails the write. That is +// strictly better than the shipped `existing, _ :=`, because a database that +// cannot be read is a database the write was about to fail against anyway — and +// the alternative is reporting "Remembered" over a value the caller has just +// destroyed. +// +// replaced is about the ROW, not the value: a memory stored as the empty string +// reports true even though a Recall of it would report Found false. See +// memoryops.RememberResult.Replaced, which states that divergence rather than +// smoothing it over. +func RememberInTx(ctx context.Context, tx *sql.Tx, key, content string) (replaced bool, err error) { + storageKey := StorageKey(key) + replaced, err = configRowExistsInTx(ctx, tx, storageKey) + if err != nil { + return false, err + } + if err := issueops.SetConfigInTx(ctx, tx, storageKey, content); err != nil { + return false, err + } + return replaced, nil +} + +// RecallInTx reads one memory in the caller's transaction. A key nothing stored +// answers "" with a nil error: the seam cannot tell that from a row stored +// empty, and the role's Found field is where that conflation is stated. +func RecallInTx(ctx context.Context, tx *sql.Tx, key string) (string, error) { + return issueops.GetConfigInTx(ctx, tx, StorageKey(key)) +} + +// ForgetInTx removes one memory and returns what it held, both in the caller's +// transaction — which is what makes the returned value the one that was +// actually deleted rather than the one an earlier read happened to see. +// +// found is Recall's found, not the row's: a memory stored as the empty string +// reports found false and IS NOT DELETED. That keeps Forget's answer and +// Recall's answer the same statement, which is what a front door printing +// "No memory with key ..." after a successful Recall would otherwise contradict. +// +// The delete names the one encoded key. There is no LIKE and no prefix sweep in +// it, so forgetting "a" cannot take "a-b" with it. +func ForgetInTx(ctx context.Context, tx *sql.Tx, key string) (previous string, found bool, err error) { + storageKey := StorageKey(key) + previous, err = issueops.GetConfigInTx(ctx, tx, storageKey) + if err != nil { + return "", false, err + } + if previous == "" { + return "", false, nil + } + if err := issueops.DeleteConfigInTx(ctx, tx, storageKey); err != nil { + return "", false, err + } + return previous, true, nil +} + +// ListInTx reads the whole memory plane in the caller's transaction, keyed by +// user key. +// +// It reads the whole config table and narrows in Go rather than issuing a LIKE. +// The plane is tens of rows inside a table of tens of rows, so the query would +// buy nothing; what it would cost is a second definition of which rows are +// memories, expressed in a pattern language where `_` is a wildcard and +// "kv.memory." contains one. +func ListInTx(ctx context.Context, tx *sql.Tx) (map[string]string, error) { + all, err := issueops.GetAllConfigInTx(ctx, tx) + if err != nil { + return nil, err + } + return MemoriesFromConfig(all), nil +} + +// configRowExistsInTx reports whether the row is there, regardless of what it +// holds. +// +// issueops.GetConfigInTx cannot answer this: it maps a missing row to "" and is +// right to, because every other caller wants a value. Replaced is a statement +// about the ROW, so this role needs the distinction that helper deliberately +// drops — hence the one query in this package that is not composed from the +// shared config helpers. +func configRowExistsInTx(ctx context.Context, tx *sql.Tx, storageKey string) (bool, error) { + var one int + err := tx.QueryRowContext(ctx, "SELECT 1 FROM config WHERE `key` = ?", storageKey).Scan(&one) + if errors.Is(err, sql.ErrNoRows) { + return false, nil + } + if err != nil { + return false, fmt.Errorf("probe memory row %s: %w", storageKey, err) + } + return true, nil +} diff --git a/internal/storage/memoryops/memories_test.go b/internal/storage/memoryops/memories_test.go new file mode 100644 index 000000000..e1ea61506 --- /dev/null +++ b/internal/storage/memoryops/memories_test.go @@ -0,0 +1,94 @@ +package memoryops + +import "testing" + +// TestStorageKeyEncodesTheFullPrefix pins the encode against the constant +// rather than against a literal, and then pins the literal too. The constant +// alone would keep agreeing with itself if kvkeys were edited; the literal is +// what the rows in a shipped workspace actually say. +func TestStorageKeyEncodesTheFullPrefix(t *testing.T) { + for _, test := range []struct{ userKey, want string }{ + {"dolt-phantoms", "kv.memory.dolt-phantoms"}, + {"issue_prefix", "kv.memory.issue_prefix"}, + {"Has Spaces.✓", "kv.memory.Has Spaces.✓"}, + {"a", "kv.memory.a"}, + } { + if got := StorageKey(test.userKey); got != test.want { + t.Fatalf("StorageKey(%q) = %q, want %q", test.userKey, got, test.want) + } + } +} + +// TestMemoriesFromConfigNarrowsToTheMemoryPlane is the cheap half of the +// quadrant discipline the conformance contract applies against real backends: +// a config map holding all four classes at once, narrowed, with the other three +// expected to be absent. +// +// The three failures it exists to catch are each one character of difference +// and each produces a plausible-looking map: filtering on "kv." serves every +// `bd kv set` value as a memory, trimming "kv." while matching "kv.memory." +// re-keys every answer to "memory.", and matching a settings row by +// substring instead of prefix puts the workspace's own configuration in the +// answer. +func TestMemoriesFromConfigNarrowsToTheMemoryPlane(t *testing.T) { + all := map[string]string{ + // Settings rows. + "issue_prefix": "bd", + "custom.limits": "10", + // Generic kv rows — the neighbours one prefix up. + "kv.deploy-target": "staging", + "kv.a": "generic", + // Memory rows, including the shadow key: a memory NAMED after a + // setting is a memory, and the setting is not. + "kv.memory.dolt-phantoms": "Dolt phantom DBs hide in three places", + "kv.memory.issue_prefix": "the prefix rename runbook is in engdocs", + "kv.memory.a": "short key", + "kv.memory.a-b": "adjacent key", + // A row whose key merely CONTAINS the prefix rather than starting + // with it. + "legacy.kv.memory.smuggled": "not a memory", + } + + got := MemoriesFromConfig(all) + + want := map[string]string{ + "dolt-phantoms": "Dolt phantom DBs hide in three places", + "issue_prefix": "the prefix rename runbook is in engdocs", + "a": "short key", + "a-b": "adjacent key", + } + if len(got) != len(want) { + t.Fatalf("MemoriesFromConfig = %v, want exactly %v", got, want) + } + for key, value := range want { + if got[key] != value { + t.Fatalf("MemoriesFromConfig[%q] = %q, want %q", key, got[key], value) + } + } +} + +// TestMemoriesFromConfigRoundTripsTheEncode pins the encode and the decode +// against EACH OTHER, which is the property the two implementations of the role +// depend on: the unit-of-work body composes the config use case rather than the +// InTx functions here, so what keeps the two routes seeing the same memories is +// that both go through this pair. +func TestMemoriesFromConfigRoundTripsTheEncode(t *testing.T) { + for _, userKey := range []string{"dolt-phantoms", "issue_prefix", "Has Spaces.✓", "a", "kv.memory.nested"} { + got := MemoriesFromConfig(map[string]string{StorageKey(userKey): "v"}) + if len(got) != 1 || got[userKey] != "v" { + t.Fatalf("round trip of %q = %v, want a single entry under the original key", userKey, got) + } + } +} + +// TestMemoriesFromConfigAnswersAnEmptyMap pins that a plane with nothing in it +// is an empty map rather than nil, so a caller can range over the answer +// without a guard. +func TestMemoriesFromConfigAnswersAnEmptyMap(t *testing.T) { + if got := MemoriesFromConfig(map[string]string{"issue_prefix": "bd"}); got == nil || len(got) != 0 { + t.Fatalf("MemoriesFromConfig with no memory rows = %v, want an empty non-nil map", got) + } + if got := MemoriesFromConfig(nil); got == nil || len(got) != 0 { + t.Fatalf("MemoriesFromConfig(nil) = %v, want an empty non-nil map", got) + } +} diff --git a/internal/storage/role_accessor_decorator_test.go b/internal/storage/role_accessor_decorator_test.go index d2984c40b..e5b82fabf 100644 --- a/internal/storage/role_accessor_decorator_test.go +++ b/internal/storage/role_accessor_decorator_test.go @@ -9,11 +9,12 @@ import ( "testing" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) -// roleAccessorNames is the twenty-three-strong capability surface every storage +// roleAccessorNames is the twenty-four-strong capability surface every storage // decorator has to answer for. It is written out rather than derived so that -// adding a twenty-fourth role to DoltStorage without deciding what each decorator +// adding a twenty-fifth role to DoltStorage without deciding what each decorator // does with it is a compile-or-test failure somewhere, not silence. var roleAccessorNames = []string{ "IssueLifecycle", @@ -25,6 +26,7 @@ var roleAccessorNames = []string{ "TreeWalker", "Counter", "WorkspaceConfig", + "Memories", "VersionReconciler", "StatsReporter", "CycleDetector", @@ -76,7 +78,7 @@ func assertRoleAccessorsAreDeclared(t *testing.T, decorator reflect.Type) { } } -// roleAccessorStore is a DoltStorage whose only real methods are the twenty-three +// roleAccessorStore is a DoltStorage whose only real methods are the twenty-four // role accessors, each answering with a distinguishable sentinel so a test can // tell a decorated surface from a passed-through one. type roleAccessorStore struct { @@ -89,6 +91,7 @@ type roleAccessorStore struct { tree issueops.TreeWalker counter issueops.Counter settings issueops.WorkspaceConfig + memories memoryops.Memories versions issueops.VersionReconciler stats issueops.StatsReporter cycles issueops.CycleDetector @@ -109,6 +112,7 @@ type roleAccessorStore struct { func newRoleAccessorStore() *roleAccessorStore { sentinel := &roleAccessorSentinel{} return &roleAccessorStore{ + memories: &memoryRoleSentinel{}, lifecycle: sentinel, reader: sentinel, relations: sentinel, @@ -140,6 +144,9 @@ func (s *roleAccessorStore) Counter() (issueops.Counter, error) { retur func (s *roleAccessorStore) WorkspaceConfig() (issueops.WorkspaceConfig, error) { return s.settings, s.err } +func (s *roleAccessorStore) Memories() (memoryops.Memories, error) { + return s.memories, s.err +} func (s *roleAccessorStore) VersionReconciler() (issueops.VersionReconciler, error) { return s.versions, s.err } @@ -183,8 +190,8 @@ func (s *roleAccessorStore) DependencyEditor() (issueops.DependencyEditor, error return s.editor, s.err } -// roleAccessorSentinel implements all twenty-three roles at once. Nothing calls its -// methods; identity is the whole point. +// roleAccessorSentinel implements twenty-three of the twenty-four roles at once. +// Nothing calls its methods; identity is the whole point. type roleAccessorSentinel struct{} func (*roleAccessorSentinel) Create(context.Context, issueops.CreateRequest) (issueops.CreateResult, error) { @@ -292,6 +299,26 @@ func (*roleAccessorSentinel) RemoveDependency(context.Context, issueops.RemoveDe return issueops.RemoveDependencyResult{}, nil } +// memoryRoleSentinel is the twenty-fourth role's sentinel, and the one role +// that cannot share the struct above: memoryops.Memories.List and +// issueops.Reader.List are the same method name with different signatures, so +// no single Go type can satisfy both. A second sentinel value is all the split +// costs; identity is still the whole point. +type memoryRoleSentinel struct{} + +func (*memoryRoleSentinel) Remember(context.Context, memoryops.RememberRequest) (memoryops.RememberResult, error) { + return memoryops.RememberResult{}, nil +} +func (*memoryRoleSentinel) Recall(context.Context, memoryops.RecallRequest) (memoryops.RecallResult, error) { + return memoryops.RecallResult{}, nil +} +func (*memoryRoleSentinel) Forget(context.Context, memoryops.ForgetRequest) (memoryops.ForgetResult, error) { + return memoryops.ForgetResult{}, nil +} +func (*memoryRoleSentinel) List(context.Context, memoryops.ListRequest) (memoryops.ListResult, error) { + return memoryops.ListResult{}, nil +} + // TestHookFiringStoreWrapsTheWriteRolesAndPassesTheReadsThrough is the // behavioural half, and it catches what reflection cannot: an accessor that IS // declared but reads `return h.inner.Commenter()`. That edit compiles, keeps @@ -304,13 +331,14 @@ func (*roleAccessorSentinel) RemoveDependency(context.Context, issueops.RemoveDe // CycleDetector, EdgeReader, BlockingAnnotator, TreeWalker, ReadyCounter, // Querier and InitVerifier deliberately return the inner surface unwrapped, // each in its own hook_*.go. The ones in that column that are NOT reads are -// WorkspaceConfig, VersionReconciler, Bootstrapper, Sweeper and Deleter: a -// settings write changes the workspace rather than a bead, a version marker -// names no bead at all, a bootstrap lands on a workspace whose hooks are not -// installed yet, a swept row is gone, and the hook vocabulary has no name for a -// deletion — so this decorator's issue-shaped hook vocabulary has nothing to -// hand a hook script. This test pins every one of them as a decision rather -// than leaving it indistinguishable from the regression above. +// WorkspaceConfig, Memories, VersionReconciler, Bootstrapper, Sweeper and +// Deleter: a settings write changes the workspace rather than a bead, a +// remembered insight names no bead and there is no on_remember to fire, a +// version marker names no bead at all, a bootstrap lands on a workspace whose +// hooks are not installed yet, a swept row is gone, and the hook vocabulary has +// no name for a deletion — so this decorator's issue-shaped hook vocabulary has +// nothing to hand a hook script. This test pins every one of them as a decision +// rather than leaving it indistinguishable from the regression above. func TestHookFiringStoreWrapsTheWriteRolesAndPassesTheReadsThrough(t *testing.T) { inner := newRoleAccessorStore() store := NewHookFiringStore(inner, nil) @@ -334,6 +362,7 @@ func TestHookFiringStoreWrapsTheWriteRolesAndPassesTheReadsThrough(t *testing.T) {"TreeWalker", func() (any, error) { return store.TreeWalker() }, inner.tree, false}, {"Counter", func() (any, error) { return store.Counter() }, inner.counter, false}, {"WorkspaceConfig", func() (any, error) { return store.WorkspaceConfig() }, inner.settings, false}, + {"Memories", func() (any, error) { return store.Memories() }, inner.memories, false}, {"VersionReconciler", func() (any, error) { return store.VersionReconciler() }, inner.versions, false}, {"StatsReporter", func() (any, error) { return store.StatsReporter() }, inner.stats, false}, {"CycleDetector", func() (any, error) { return store.CycleDetector() }, inner.cycles, false}, @@ -386,6 +415,7 @@ func TestHookFiringStoreRoleAccessorsPropagateInnerErrors(t *testing.T) { {"TreeWalker", func() (any, error) { return store.TreeWalker() }}, {"Counter", func() (any, error) { return store.Counter() }}, {"WorkspaceConfig", func() (any, error) { return store.WorkspaceConfig() }}, + {"Memories", func() (any, error) { return store.Memories() }}, {"VersionReconciler", func() (any, error) { return store.VersionReconciler() }}, {"StatsReporter", func() (any, error) { return store.StatsReporter() }}, {"CycleDetector", func() (any, error) { return store.CycleDetector() }}, diff --git a/internal/storage/storage.go b/internal/storage/storage.go index 003936c58..4b260dea2 100644 --- a/internal/storage/storage.go +++ b/internal/storage/storage.go @@ -14,6 +14,7 @@ import ( "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) // The guarded issue-operation error vocabulary is declared and documented by @@ -189,6 +190,25 @@ type Storage interface { // re-project a value into a normalized lookup table. WorkspaceConfig() (issueops.WorkspaceConfig, error) + // Memories returns the guarded persistent-memory surface for this store: + // the keyed notes `bd remember`, `bd recall`, `bd forget` and `bd memories` + // work with, and that `bd prime` injects. + // + // IT IS NOT MORE WorkspaceConfig VERBS, and the rule forbidding that is the + // least of the reasons. Memories ride in the config table but they are user + // data in a reserved namespace, they are their own MERGE CLASS — a config + // conflict auto-resolves with --theirs only when every conflicted key is a + // memory — they have their own validation vocabulary (content, derived + // keys) and they have a found/not-found user contract the settings plane + // deliberately does not have. A settings enumeration that carried them + // would be answering a different question in the same list. + // + // Its hook decorator recurses UNWRAPPED for the vocabulary reason Sweeper's + // does: remembering is a write, but the hook vocabulary is on_create, + // on_update and on_close and each hands a script an ISSUE. See + // hook_memories.go. + Memories() (memoryops.Memories, error) + // VersionReconciler returns the clone-local version markers for this store: // the dolt-ignored pair recording which bd binary last opened this // workspace and the highest one that ever has. It is its own role rather diff --git a/internal/storage/uow/memories.go b/internal/storage/uow/memories.go new file mode 100644 index 000000000..fc5040881 --- /dev/null +++ b/internal/storage/uow/memories.go @@ -0,0 +1,141 @@ +package uow + +import ( + "context" + "fmt" + + "github.com/steveyegge/beads/internal/memoryapi" + storagememoryops "github.com/steveyegge/beads/internal/storage/memoryops" + "github.com/steveyegge/beads/memoryops" +) + +// MemoriesSource is the capability accessor a unit-of-work provider offers for +// the persistent-memory role, the sibling of WorkspaceConfigSource and +// CounterSource. +type MemoriesSource interface { + Memories() (memoryops.Memories, error) +} + +// memories answers memory queries and writes through a unit of work. +type memories struct { + provider UnitOfWorkProvider +} + +// Memories returns the guarded persistent-memory surface for this provider. +func (p *doltSQLProvider) Memories() (memoryops.Memories, error) { + return NewMemories(p) +} + +// NewMemories constructs a public persistent-memory surface backed by provider. +func NewMemories(provider UnitOfWorkProvider) (memoryops.Memories, error) { + if isNilUnitOfWorkProvider(provider) { + return nil, fmt.Errorf("new memories: unit-of-work provider must not be nil") + } + return &memories{provider: provider}, nil +} + +var _ memoryops.Memories = (*memories)(nil) + +// This is the genuinely independent body of the three: it composes +// domain.ConfigUseCase where the two store backends compose the shared InTx +// functions in internal/storage/memoryops. What keeps the two routes seeing +// each other's memories is that both encode and decode the kv.memory. prefix +// through that package's StorageKey and MemoriesFromConfig — the one encode and +// the one decode in the tree. +// +// VALIDATION HAPPENS BEFORE THE UNIT OF WORK IS OPENED, for the reason +// workspace_config.go gives: a validation failure raised inside RunTx is +// indistinguishable at the call site from a write that rolled back. + +// Remember probes and writes in ONE unit of work. +// +// The shipped proxied path pre-read in a SEPARATE RunTxRead and then opened a +// RunTx to write, so the "Remembered" versus "Updated" verb described a moment +// that had already passed. Nothing moves between the two now. +// +// The probe is GetAllConfig rather than GetConfig because Replaced is about the +// ROW: this seam maps a missing row and a row stored empty to the same "", and +// the map's key set is the only place the difference survives. It is one extra +// query on a table that holds tens of rows, and it is what makes the answer the +// same on this backend as on the other two. +func (m *memories) Remember(ctx context.Context, req memoryops.RememberRequest) (memoryops.RememberResult, error) { + key, err := memoryapi.ResolveKey(req.Key, req.Content) + if err != nil { + return memoryops.RememberResult{}, err + } + storageKey := storagememoryops.StorageKey(key) + replaced, err := RunTxResult(ctx, m.provider, func(ctx context.Context, uw UnitOfWork) (bool, string, error) { + cfg := uw.ConfigUseCase() + all, err := cfg.GetAllConfig(ctx) + if err != nil { + return false, "", err + } + _, replaced := all[storageKey] + if err := cfg.SetConfig(ctx, storageKey, req.Content); err != nil { + return false, "", err + } + return replaced, "bd: remember " + key, nil + }) + if err != nil { + return memoryops.RememberResult{}, err + } + return memoryops.RememberResult{Key: key, Value: req.Content, Replaced: replaced}, nil +} + +func (m *memories) Recall(ctx context.Context, req memoryops.RecallRequest) (memoryops.RecallResult, error) { + key, err := memoryapi.ValidateKey(req.Key) + if err != nil { + return memoryops.RecallResult{}, err + } + return RunTxRead(ctx, m.provider, func(ctx context.Context, uw UnitOfWork) (memoryops.RecallResult, error) { + value, err := uw.ConfigUseCase().GetConfig(ctx, storagememoryops.StorageKey(key)) + if err != nil { + return memoryops.RecallResult{}, err + } + return memoryops.RecallResult{Key: key, Value: value, Found: value != ""}, nil + }) +} + +// Forget reads the value and deletes the row in ONE unit of work, so the value +// it reports is the one it removed rather than the one a separate earlier read +// saw. +// +// A miss returns an EMPTY commit message, which is how this layer says "commit +// nothing": a Forget that found no memory must leave no Dolt commit behind, +// exactly as it leaves no row change. +func (m *memories) Forget(ctx context.Context, req memoryops.ForgetRequest) (memoryops.ForgetResult, error) { + key, err := memoryapi.ValidateKey(req.Key) + if err != nil { + return memoryops.ForgetResult{}, err + } + storageKey := storagememoryops.StorageKey(key) + result, err := RunTxResult(ctx, m.provider, func(ctx context.Context, uw UnitOfWork) (memoryops.ForgetResult, string, error) { + cfg := uw.ConfigUseCase() + previous, err := cfg.GetConfig(ctx, storageKey) + if err != nil { + return memoryops.ForgetResult{}, "", err + } + if previous == "" { + return memoryops.ForgetResult{Key: key}, "", nil + } + if err := cfg.DeleteConfig(ctx, storageKey); err != nil { + return memoryops.ForgetResult{}, "", err + } + return memoryops.ForgetResult{Key: key, Value: previous, Found: true}, "bd: forget " + key, nil + }) + if err != nil { + return memoryops.ForgetResult{}, err + } + return result, nil +} + +func (m *memories) List(ctx context.Context, req memoryops.ListRequest) (memoryops.ListResult, error) { + return RunTxRead(ctx, m.provider, func(ctx context.Context, uw UnitOfWork) (memoryops.ListResult, error) { + all, err := uw.ConfigUseCase().GetAllConfig(ctx) + if err != nil { + return memoryops.ListResult{}, err + } + plane := storagememoryops.MemoriesFromConfig(all) + return memoryops.ListResult{Memories: memoryapi.FilterMemories(plane, req.Search)}, nil + }) +} diff --git a/internal/storage/uow/memories_contract_test.go b/internal/storage/uow/memories_contract_test.go new file mode 100644 index 000000000..9725f306a --- /dev/null +++ b/internal/storage/uow/memories_contract_test.go @@ -0,0 +1,109 @@ +package uow + +import ( + "context" + "testing" + + "github.com/steveyegge/beads/backend/conformance" +) + +// TestMemoriesContract runs the Memories contract against the unit-of-work +// provider — the one implementation that does not compose the …InTx functions +// in internal/storage/memoryops. The two store backends share those, which +// makes this the SECOND of two votes rather than the third. +// +// It is also the wiring the atomicity upgrade was written for: this route used +// to pre-read in a separate RunTxRead and then open a RunTx to write, so the +// "Remembered" versus "Updated" verb and the value `bd forget` printed +// described a moment that had already passed. +// +// One provider for the whole suite (each newUOWRoleFixtureProvider boots a real +// Dolt sql-server) and NO t.Parallel: this backend has no per-test +// copy-on-write branch, so the config plane and dolt_log are database-global. +// ListOfAnEmptyPlaneAnswersAnEmptyMap runs FIRST because it needs an untouched +// plane. +func TestMemoriesContract(t *testing.T) { + ctx := context.Background() + fixture := newUOWMemoriesFixture(t, ctx, "mem") + + t.Run("ListOfAnEmptyPlaneAnswersAnEmptyMap", func(t *testing.T) { + conformance.RunMemoriesListOfAnEmptyPlaneAnswersAnEmptyMap(t, ctx, fixture) + }) + t.Run("RememberStoresContentVerbatim", func(t *testing.T) { + conformance.RunMemoriesRememberStoresContentVerbatim(t, ctx, fixture) + }) + t.Run("RememberDerivesTheKeyWhenAbsent", func(t *testing.T) { + conformance.RunMemoriesRememberDerivesTheKeyWhenAbsent(t, ctx, fixture) + }) + t.Run("RememberWithExplicitKeyStoresVerbatim", func(t *testing.T) { + conformance.RunMemoriesRememberWithExplicitKeyStoresVerbatim(t, ctx, fixture) + }) + t.Run("RememberReplacesAndReportsIt", func(t *testing.T) { + conformance.RunMemoriesRememberReplacesAndReportsIt(t, ctx, fixture) + }) + t.Run("RememberRefusesEmptyContent", func(t *testing.T) { + conformance.RunMemoriesRememberRefusesEmptyContent(t, ctx, fixture) + }) + t.Run("RememberRefusesAWhitespaceOnlyKey", func(t *testing.T) { + conformance.RunMemoriesRememberRefusesAWhitespaceOnlyKey(t, ctx, fixture) + }) + t.Run("RememberRefusesAnUnderivableKey", func(t *testing.T) { + conformance.RunMemoriesRememberRefusesAnUnderivableKey(t, ctx, fixture) + }) + t.Run("RecallAnswersTheStoredValue", func(t *testing.T) { + conformance.RunMemoriesRecallAnswersTheStoredValue(t, ctx, fixture) + }) + t.Run("RecallReportsAMissAsNotFoundNotAnError", func(t *testing.T) { + conformance.RunMemoriesRecallReportsAMissAsNotFoundNotAnError(t, ctx, fixture) + }) + t.Run("RecallConflatesStoredEmptyWithAbsent", func(t *testing.T) { + conformance.RunMemoriesRecallConflatesStoredEmptyWithAbsent(t, ctx, fixture) + }) + t.Run("ForgetRemovesExactlyTheNamedRow", func(t *testing.T) { + conformance.RunMemoriesForgetRemovesExactlyTheNamedRow(t, ctx, fixture) + }) + t.Run("ForgetNeverTouchesTheSettingsPlane", func(t *testing.T) { + conformance.RunMemoriesForgetNeverTouchesTheSettingsPlane(t, ctx, fixture) + }) + t.Run("ForgetReportsTheForgottenValue", func(t *testing.T) { + conformance.RunMemoriesForgetReportsTheForgottenValue(t, ctx, fixture) + }) + t.Run("ForgetOfAnAbsentKeyIsNotFoundAndDeletesNothing", func(t *testing.T) { + conformance.RunMemoriesForgetOfAnAbsentKeyIsNotFoundAndDeletesNothing(t, ctx, fixture) + }) + t.Run("ListReturnsOnlyTheMemoryPlane", func(t *testing.T) { + conformance.RunMemoriesListReturnsOnlyTheMemoryPlane(t, ctx, fixture) + }) + t.Run("ListSearchMatchesTheUserKeyNotTheStorageKey", func(t *testing.T) { + conformance.RunMemoriesListSearchMatchesTheUserKeyNotTheStorageKey(t, ctx, fixture) + }) + t.Run("ListSearchMatchesKeyOrValueCaseInsensitively", func(t *testing.T) { + conformance.RunMemoriesListSearchMatchesKeyOrValueCaseInsensitively(t, ctx, fixture) + }) + t.Run("ARefusedWriteRecordsNoHistory", func(t *testing.T) { + conformance.RunMemoriesARefusedWriteRecordsNoHistory(t, ctx, fixture) + }) +} + +func newUOWMemoriesFixture(t *testing.T, ctx context.Context, prefix string) conformance.MemoriesFixture { + t.Helper() + provider := newUOWRoleFixtureProvider(t, ctx, prefix) + // Through the capability accessor, not NewMemories: a provider that stopped + // offering the role is the regression a constructor call would hide. + source, ok := provider.(MemoriesSource) + if !ok { + t.Fatalf("provider %T does not offer the Memories accessor", provider) + } + memories, err := source.Memories() + if err != nil { + t.Fatalf("Memories(): %v", err) + } + kit := newUOWRoleFixtureKit(provider, prefix) + return conformance.MemoriesFixture{ + IssuePrefix: kit.IssuePrefix, + Memories: memories, + SetConfig: kit.SetConfig, + QueryScalar: kit.QueryScalar, + CountHistory: kit.CountHistory, + } +} diff --git a/internal/storage/uow/workspace_config.go b/internal/storage/uow/workspace_config.go index ab0efaf46..eef8e268f 100644 --- a/internal/storage/uow/workspace_config.go +++ b/internal/storage/uow/workspace_config.go @@ -53,14 +53,14 @@ func (c *workspaceConfig) GetSetting(ctx context.Context, req publicops.GetSetti func (c *workspaceConfig) ListSettings(ctx context.Context, _ publicops.ListSettingsRequest) (publicops.ListSettingsResult, error) { return RunTxRead(ctx, c.provider, func(ctx context.Context, uw UnitOfWork) (publicops.ListSettingsResult, error) { - settings, err := uw.ConfigUseCase().GetAllConfig(ctx) + stored, err := uw.ConfigUseCase().GetAllConfig(ctx) if err != nil { return publicops.ListSettingsResult{}, err } - if settings == nil { - settings = map[string]string{} - } - return publicops.ListSettingsResult{Settings: settings}, nil + // Same filter as the store-backed body, for the same reason: the config + // table holds the KV plane too, and what the settings enumeration may + // carry is one decision, not one per implementation. + return publicops.ListSettingsResult{Settings: workapi.FilterSettingsEnumeration(stored)}, nil }) } diff --git a/internal/storage/uow/workspace_config_contract_test.go b/internal/storage/uow/workspace_config_contract_test.go index c95a562c5..7d89b1a84 100644 --- a/internal/storage/uow/workspace_config_contract_test.go +++ b/internal/storage/uow/workspace_config_contract_test.go @@ -36,6 +36,9 @@ func TestWorkspaceConfigContract(t *testing.T) { t.Run("ListsEveryStoredSetting", func(t *testing.T) { conformance.RunWorkspaceConfigListsEveryStoredSetting(t, ctx, fixture) }) + t.Run("ListExcludesTheKVPlane", func(t *testing.T) { + conformance.RunWorkspaceConfigListExcludesTheKVPlane(t, ctx, fixture) + }) t.Run("UnsetRemovesTheSetting", func(t *testing.T) { conformance.RunWorkspaceConfigUnsetRemovesTheSetting(t, ctx, fixture) }) diff --git a/internal/telemetry/memories.go b/internal/telemetry/memories.go new file mode 100644 index 000000000..40fdd926e --- /dev/null +++ b/internal/telemetry/memories.go @@ -0,0 +1,57 @@ +package telemetry + +import ( + "context" + + "github.com/steveyegge/beads/memoryops" +) + +// Memories returns the inner store's persistent-memory surface wrapped in this +// layer's instrumentation. It recurses instead of delegating: a blind +// delegation would return the inner surface unspanned and untimed. +func (s *InstrumentedStorage) Memories() (memoryops.Memories, error) { + inner, err := s.Unwrap().Memories() + if err != nil { + return nil, err + } + return s.WrapMemories(inner), nil +} + +// WrapMemories instruments guarded persistent-memory access with this storage +// layer's existing telemetry meter and tracer. +func (s *InstrumentedStorage) WrapMemories(inner memoryops.Memories) memoryops.Memories { + return &instrumentedMemories{storage: s, inner: inner} +} + +type instrumentedMemories struct { + storage *InstrumentedStorage + inner memoryops.Memories +} + +func (m *instrumentedMemories) Remember(ctx context.Context, request memoryops.RememberRequest) (result memoryops.RememberResult, err error) { + ctx, span, started := m.storage.op(ctx, "Memories.Remember") + result, err = m.inner.Remember(ctx, request) + m.storage.done(ctx, span, started, err) + return result, err +} + +func (m *instrumentedMemories) Recall(ctx context.Context, request memoryops.RecallRequest) (result memoryops.RecallResult, err error) { + ctx, span, started := m.storage.op(ctx, "Memories.Recall") + result, err = m.inner.Recall(ctx, request) + m.storage.done(ctx, span, started, err) + return result, err +} + +func (m *instrumentedMemories) Forget(ctx context.Context, request memoryops.ForgetRequest) (result memoryops.ForgetResult, err error) { + ctx, span, started := m.storage.op(ctx, "Memories.Forget") + result, err = m.inner.Forget(ctx, request) + m.storage.done(ctx, span, started, err) + return result, err +} + +func (m *instrumentedMemories) List(ctx context.Context, request memoryops.ListRequest) (result memoryops.ListResult, err error) { + ctx, span, started := m.storage.op(ctx, "Memories.List") + result, err = m.inner.List(ctx, request) + m.storage.done(ctx, span, started, err) + return result, err +} diff --git a/internal/telemetry/role_accessor_decorator_test.go b/internal/telemetry/role_accessor_decorator_test.go index 7d48699c7..bc0f888d2 100644 --- a/internal/telemetry/role_accessor_decorator_test.go +++ b/internal/telemetry/role_accessor_decorator_test.go @@ -10,9 +10,10 @@ import ( "github.com/steveyegge/beads/internal/storage" "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" ) -// roleAccessorNames is the twenty-three-strong capability surface every storage +// roleAccessorNames is the twenty-four-strong capability surface every storage // decorator has to answer for. It is duplicated from the sibling test in // internal/storage rather than shared because that package cannot import this // one and this one's test helpers cannot be exported back. @@ -26,6 +27,7 @@ var roleAccessorNames = []string{ "TreeWalker", "Counter", "WorkspaceConfig", + "Memories", "VersionReconciler", "StatsReporter", "CycleDetector", @@ -66,13 +68,19 @@ func TestInstrumentedStorageDeclaresEveryRoleAccessor(t *testing.T) { } } -// roleAccessorStore is a DoltStorage whose only real methods are the twenty-three +// roleAccessorStore is a DoltStorage whose only real methods are the twenty-four // role accessors, each answering with a distinguishable sentinel so a test can tell // an instrumented surface from a passed-through one. +// +// TWO sentinels rather than one: memoryops.Memories.List and issueops.Reader.List +// are the same method name with different signatures, so no single Go type can +// satisfy both roles. Every assertion below therefore names the inner surface it +// expects rather than assuming there is only one. type roleAccessorStore struct { storage.DoltStorage - surface *roleAccessorSentinel - err error + surface *roleAccessorSentinel + memories *memoryRoleSentinel + err error } func (s *roleAccessorStore) IssueLifecycle() (issueops.Lifecycle, error) { return s.surface, s.err } @@ -82,6 +90,9 @@ func (s *roleAccessorStore) Counter() (issueops.Counter, error) { retur func (s *roleAccessorStore) WorkspaceConfig() (issueops.WorkspaceConfig, error) { return s.surface, s.err } +func (s *roleAccessorStore) Memories() (memoryops.Memories, error) { + return s.memories, s.err +} func (s *roleAccessorStore) VersionReconciler() (issueops.VersionReconciler, error) { return s.surface, s.err } @@ -125,8 +136,8 @@ func (s *roleAccessorStore) DependencyEditor() (issueops.DependencyEditor, error return s.surface, s.err } -// roleAccessorSentinel implements all twenty-three roles at once. Nothing calls its -// methods; identity is the whole point. +// roleAccessorSentinel implements twenty-three of the twenty-four roles at once. +// Nothing calls its methods; identity is the whole point. type roleAccessorSentinel struct{} func (*roleAccessorSentinel) Create(context.Context, issueops.CreateRequest) (issueops.CreateResult, error) { @@ -238,57 +249,82 @@ func (*roleAccessorSentinel) RemoveDependency(context.Context, issueops.RemoveDe return issueops.RemoveDependencyResult{}, nil } +// memoryRoleSentinel is the twenty-fourth role's sentinel — see +// roleAccessorStore for why it cannot be a method set on the struct above. +type memoryRoleSentinel struct{} + +func (*memoryRoleSentinel) Remember(context.Context, memoryops.RememberRequest) (memoryops.RememberResult, error) { + return memoryops.RememberResult{}, nil +} +func (*memoryRoleSentinel) Recall(context.Context, memoryops.RecallRequest) (memoryops.RecallResult, error) { + return memoryops.RecallResult{}, nil +} +func (*memoryRoleSentinel) Forget(context.Context, memoryops.ForgetRequest) (memoryops.ForgetResult, error) { + return memoryops.ForgetResult{}, nil +} +func (*memoryRoleSentinel) List(context.Context, memoryops.ListRequest) (memoryops.ListResult, error) { + return memoryops.ListResult{}, nil +} + // TestInstrumentedStorageInstrumentsEveryRoleAccessor catches what reflection // cannot: an accessor that IS declared but reads // `return s.Unwrap().Commenter()`. That edit compiles, keeps satisfying // DoltStorage, and silently drops every span and timing on that role. // // Unlike the hook decorator, this one has no read-role exemption: telemetry -// spans reads as well as writes, so ALL EIGHTEEN must come back wrapped. Only +// spans reads as well as writes, so EVERY role must come back wrapped. Only // IssueLifecycle and IssueReader had a recursion pin of their own before this // test; the rest had no test at all. +// +// Each row names the INNER surface it must not be, rather than sharing one +// sentinel: the memory role has a sentinel of its own (its List collides with +// the reader's), and a row that compared against the wrong one would be a row +// that cannot fail. func TestInstrumentedStorageInstrumentsEveryRoleAccessor(t *testing.T) { t.Setenv("BD_OTEL_STDOUT", "true") sentinel := &roleAccessorSentinel{} - inner := &roleAccessorStore{surface: sentinel} + memorySentinel := &memoryRoleSentinel{} + inner := &roleAccessorStore{surface: sentinel, memories: memorySentinel} wrapped, ok := WrapStorage(inner).(*InstrumentedStorage) if !ok { t.Fatal("WrapStorage did not instrument the store; telemetry is disabled in this environment") } for _, test := range []struct { - name string - got func() (any, error) + name string + got func() (any, error) + inner any }{ - {"IssueLifecycle", func() (any, error) { return wrapped.IssueLifecycle() }}, - {"IssueReader", func() (any, error) { return wrapped.IssueReader() }}, - {"IssueRelations", func() (any, error) { return wrapped.IssueRelations() }}, - {"EdgeReader", func() (any, error) { return wrapped.EdgeReader() }}, - {"BlockingAnnotator", func() (any, error) { return wrapped.BlockingAnnotator() }}, - {"TreeWalker", func() (any, error) { return wrapped.TreeWalker() }}, - {"Counter", func() (any, error) { return wrapped.Counter() }}, - {"WorkspaceConfig", func() (any, error) { return wrapped.WorkspaceConfig() }}, - {"VersionReconciler", func() (any, error) { return wrapped.VersionReconciler() }}, - {"StatsReporter", func() (any, error) { return wrapped.StatsReporter() }}, - {"CycleDetector", func() (any, error) { return wrapped.CycleDetector() }}, - {"ReadyCounter", func() (any, error) { return wrapped.ReadyCounter() }}, - {"Querier", func() (any, error) { return wrapped.Querier() }}, - {"Sweeper", func() (any, error) { return wrapped.Sweeper() }}, - {"Deleter", func() (any, error) { return wrapped.Deleter() }}, - {"Bootstrapper", func() (any, error) { return wrapped.Bootstrapper() }}, - {"InitVerifier", func() (any, error) { return wrapped.InitVerifier() }}, - {"Commenter", func() (any, error) { return wrapped.Commenter() }}, - {"ReadyClaimer", func() (any, error) { return wrapped.ReadyClaimer() }}, - {"BatchCloser", func() (any, error) { return wrapped.BatchCloser() }}, - {"BatchCreator", func() (any, error) { return wrapped.BatchCreator() }}, - {"DependencyEditor", func() (any, error) { return wrapped.DependencyEditor() }}, + {"IssueLifecycle", func() (any, error) { return wrapped.IssueLifecycle() }, sentinel}, + {"IssueReader", func() (any, error) { return wrapped.IssueReader() }, sentinel}, + {"IssueRelations", func() (any, error) { return wrapped.IssueRelations() }, sentinel}, + {"EdgeReader", func() (any, error) { return wrapped.EdgeReader() }, sentinel}, + {"BlockingAnnotator", func() (any, error) { return wrapped.BlockingAnnotator() }, sentinel}, + {"TreeWalker", func() (any, error) { return wrapped.TreeWalker() }, sentinel}, + {"Counter", func() (any, error) { return wrapped.Counter() }, sentinel}, + {"WorkspaceConfig", func() (any, error) { return wrapped.WorkspaceConfig() }, sentinel}, + {"Memories", func() (any, error) { return wrapped.Memories() }, memorySentinel}, + {"VersionReconciler", func() (any, error) { return wrapped.VersionReconciler() }, sentinel}, + {"StatsReporter", func() (any, error) { return wrapped.StatsReporter() }, sentinel}, + {"CycleDetector", func() (any, error) { return wrapped.CycleDetector() }, sentinel}, + {"ReadyCounter", func() (any, error) { return wrapped.ReadyCounter() }, sentinel}, + {"Querier", func() (any, error) { return wrapped.Querier() }, sentinel}, + {"Sweeper", func() (any, error) { return wrapped.Sweeper() }, sentinel}, + {"Deleter", func() (any, error) { return wrapped.Deleter() }, sentinel}, + {"Bootstrapper", func() (any, error) { return wrapped.Bootstrapper() }, sentinel}, + {"InitVerifier", func() (any, error) { return wrapped.InitVerifier() }, sentinel}, + {"Commenter", func() (any, error) { return wrapped.Commenter() }, sentinel}, + {"ReadyClaimer", func() (any, error) { return wrapped.ReadyClaimer() }, sentinel}, + {"BatchCloser", func() (any, error) { return wrapped.BatchCloser() }, sentinel}, + {"BatchCreator", func() (any, error) { return wrapped.BatchCreator() }, sentinel}, + {"DependencyEditor", func() (any, error) { return wrapped.DependencyEditor() }, sentinel}, } { t.Run(test.name, func(t *testing.T) { surface, err := test.got() if err != nil { t.Fatalf("%s() error = %v", test.name, err) } - if surface == any(sentinel) { + if surface == test.inner { t.Fatalf("%s() returned the inner surface uninstrumented, so every call on that role is unspanned and untimed", test.name) } }) @@ -318,6 +354,7 @@ func TestInstrumentedStorageRoleAccessorsPropagateInnerErrors(t *testing.T) { {"TreeWalker", func() (any, error) { return wrapped.TreeWalker() }}, {"Counter", func() (any, error) { return wrapped.Counter() }}, {"WorkspaceConfig", func() (any, error) { return wrapped.WorkspaceConfig() }}, + {"Memories", func() (any, error) { return wrapped.Memories() }}, {"VersionReconciler", func() (any, error) { return wrapped.VersionReconciler() }}, {"StatsReporter", func() (any, error) { return wrapped.StatsReporter() }}, {"CycleDetector", func() (any, error) { return wrapped.CycleDetector() }}, diff --git a/internal/workapi/storeworkspaceconfig/workspaceconfig.go b/internal/workapi/storeworkspaceconfig/workspaceconfig.go index 7dc8e647b..e4b755ab9 100644 --- a/internal/workapi/storeworkspaceconfig/workspaceconfig.go +++ b/internal/workapi/storeworkspaceconfig/workspaceconfig.go @@ -44,17 +44,15 @@ func (c *storeWorkspaceConfig) GetSetting(ctx context.Context, req issueops.GetS } func (c *storeWorkspaceConfig) ListSettings(ctx context.Context, _ issueops.ListSettingsRequest) (issueops.ListSettingsResult, error) { - settings, err := c.store.GetAllConfig(ctx) + stored, err := c.store.GetAllConfig(ctx) if err != nil { return issueops.ListSettingsResult{}, err } - if settings == nil { - // Empty, never nil: ListSettingsResult.Settings promises a caller can - // range over the answer without a guard, and this seam returns a nil - // map on at least one path that finds no rows. - settings = map[string]string{} - } - return issueops.ListSettingsResult{Settings: settings}, nil + // The store hands back the whole config table, which holds the KV plane as + // well as the settings plane. What may be enumerated is workapi's to say, + // shared with the unit-of-work body so the two doors cannot drift; it also + // gives the empty-never-nil map the result promises. + return issueops.ListSettingsResult{Settings: workapi.FilterSettingsEnumeration(stored)}, nil } // Set writes one setting through the store's own config verb. diff --git a/internal/workapi/workspaceconfig.go b/internal/workapi/workspaceconfig.go index 6ac8e1556..f6c25c999 100644 --- a/internal/workapi/workspaceconfig.go +++ b/internal/workapi/workspaceconfig.go @@ -4,12 +4,14 @@ import ( "fmt" "strings" + "github.com/steveyegge/beads/internal/storage/kvkeys" "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" ) // The single definition of what a write to the workspace's durable settings -// plane is allowed to be, beside BuildListFilter and BuildCountFilter. +// plane is allowed to be and of what an enumeration of it may carry, beside +// BuildListFilter and BuildCountFilter. // // It lives here for the reason those do: three implementations of // issueops.WorkspaceConfig have to agree about it, and it is checkable without @@ -61,3 +63,49 @@ func ValidateSettingWrite(key, value string) (string, error) { } return value, nil } + +// FilterSettingsEnumeration takes the rows a store handed back and returns the +// ones the settings enumeration is allowed to carry: everything except the KV +// plane. +// +// THE KV PLANE RIDES IN THE SAME TABLE AND IS NOT SETTINGS. Generic `bd kv` +// keys and the `bd remember` memories nested under them are USER DATA stored as +// config rows beneath kvkeys.Prefix, and an enumeration that returned them +// published that data on `bd config list` and on GET /v0/beads/config alike — +// the latter unauthenticated, and redacting on the KEY NAME while a memory's +// content is in the VALUE. `bd config list` carrying kv rows was never a +// design; it fell out of one storage table holding two planes. +// +// THE WHOLE PREFIX GOES, not just kv.memory.: "settings minus one user-data +// namespace but including the other" is not a rule anyone could state in a doc +// comment. Nothing is lost by it — the purpose-built views over those rows +// (`bd kv list`, `bd memories`) read the store directly and never come through +// this role. +// +// IT IS APPLIED HERE, beside the validators, because both WorkspaceConfig +// bodies call it and two doors onto one plane must answer the same. Filtering +// in the HTTP handler instead would leave `bd config list` printing memories +// into every terminal and transcript while the HTTP door claimed they were not +// settings. +// +// AND IT IS AN ENUMERATION EXCLUSION, NOT A FIREWALL. GetSetting still answers +// a verbatim kv.* key and SetSetting/UnsetSetting still write one; see +// issueops/workspaceconfig.go for why that asymmetry is deliberate. A caller +// who already knows the exact key is in a different class from one who +// discovers it by listing. Making it a wall is one more refusal in this +// function and nothing else changes. +// +// The result is always a fresh map, empty rather than nil, because +// ListSettingsResult.Settings promises a caller can range over the answer +// without a guard and at least one store path returns a nil map when it finds +// no rows. +func FilterSettingsEnumeration(stored map[string]string) map[string]string { + settings := make(map[string]string, len(stored)) + for key, value := range stored { + if strings.HasPrefix(key, kvkeys.Prefix) { + continue + } + settings[key] = value + } + return settings +} diff --git a/internal/workapi/workspaceconfig_test.go b/internal/workapi/workspaceconfig_test.go index e82a4c5b5..b16b0994e 100644 --- a/internal/workapi/workspaceconfig_test.go +++ b/internal/workapi/workspaceconfig_test.go @@ -102,3 +102,64 @@ func TestValidateSettingWriteReturnsTheValueUnchanged(t *testing.T) { } } } + +// TestFilterSettingsEnumerationDropsTheWholeKVPrefix is the machine half of the +// enumeration exclusion. The conformance contract pins it through a real +// backend at all three wirings; what is checkable here is the prefix boundary +// itself, which is where the plausible mistakes are — the narrower memory +// constant, a match that is not anchored, a "kv" that is not "kv.". +func TestFilterSettingsEnumerationDropsTheWholeKVPrefix(t *testing.T) { + stored := map[string]string{ + "issue_prefix": "bd", + "custom.thing": "kept", + "status.custom": "awaiting_review", + "kv.deploy-token": "a generic bd kv row", + "kv.memory.architecture": "the deploy token is sk-live-000", + "kv.memory.issue_prefix": "a memory shadowing a settings name", + "kvetch": "not the prefix: kv. carries the dot", + "memory.not-under-kv": "not the prefix either", + "custom.mentions.kv.somewhere": "the prefix has to be at the front", + } + want := map[string]string{ + "issue_prefix": "bd", + "custom.thing": "kept", + "status.custom": "awaiting_review", + "kvetch": "not the prefix: kv. carries the dot", + "memory.not-under-kv": "not the prefix either", + "custom.mentions.kv.somewhere": "the prefix has to be at the front", + } + + got := FilterSettingsEnumeration(stored) + if len(got) != len(want) { + t.Fatalf("FilterSettingsEnumeration returned %d keys %v, want %d %v", len(got), got, len(want), want) + } + for key, value := range want { + if got[key] != value { + t.Errorf("FilterSettingsEnumeration()[%q] = %q, want %q", key, got[key], value) + } + } + // The argument belongs to the caller, and one body passes the map its store + // handed back: filtering in place would empty the store's own answer. + if len(stored) != 9 { + t.Errorf("FilterSettingsEnumeration mutated its argument: %d keys left, want 9", len(stored)) + } +} + +// TestFilterSettingsEnumerationIsEmptyNeverNil pins the half of the promise the +// two bodies used to make separately: ListSettingsResult.Settings can be ranged +// over without a guard, and at least one store path answers nil. +func TestFilterSettingsEnumerationIsEmptyNeverNil(t *testing.T) { + for name, stored := range map[string]map[string]string{ + "nil": nil, + "empty": {}, + "only kv rows": {"kv.memory.a": "1", "kv.b": "2"}, + } { + got := FilterSettingsEnumeration(stored) + if got == nil { + t.Errorf("FilterSettingsEnumeration(%s) returned a nil map, want an empty one", name) + } + if len(got) != 0 { + t.Errorf("FilterSettingsEnumeration(%s) = %v, want empty", name, got) + } + } +} diff --git a/issue_roles_external_test.go b/issue_roles_external_test.go index 63711327e..92b6f7759 100644 --- a/issue_roles_external_test.go +++ b/issue_roles_external_test.go @@ -237,6 +237,44 @@ func TestWorkspaceConfigKeepsTelemetryOutermost(t *testing.T) { } } +// TestMemoriesKeepsTelemetryOutermost is the settings role's answer for the +// second plane that rides in the config table. +// +// Remember and Forget WRITE, so the reflex is to expect the hook wrapper here. +// The hook vocabulary is what decides it: on_create, on_update and on_close each +// hand a script an ISSUE, and a remembered insight is not one. There is no +// on_remember to fire and inventing one is a hook proposal, not a role commit. +// See internal/storage/hook_memories.go. +func TestMemoriesKeepsTelemetryOutermost(t *testing.T) { + t.Setenv("BD_OTEL_STDOUT", "true") + instrumented, ok := telemetry.WrapStorage(&dolt.DoltStore{}).(*telemetry.InstrumentedStorage) + if !ok { + t.Fatal("WrapStorage() did not create InstrumentedStorage") + } + + memories, err := storage.NewHookFiringStore(instrumented, nil).Memories() + if err != nil { + t.Fatalf("Memories() error = %v", err) + } + if got := reflect.TypeOf(memories).String(); got != "*telemetry.instrumentedMemories" { + t.Fatalf("outer layer = %s, want the telemetry wrapper unwrapped by the hook decorator", got) + } +} + +// TestMemoriesExposesTypedUnsupportedError pins the typed refusal a backend +// gives when it cannot serve the memory role, reachable through the public +// alias without importing internal/storage. +func TestMemoriesExposesTypedUnsupportedError(t *testing.T) { + memories, err := (*dolt.DoltStore)(nil).Memories() + if memories != nil { + t.Fatalf("Memories() memories = %T, want nil", memories) + } + var unsupported *beads.ErrUnsupported + if !errors.As(err, &unsupported) { + t.Fatalf("Memories() error = %v, want *beads.ErrUnsupported", err) + } +} + // TestVersionReconcilerKeepsTelemetryOutermost is the settings role's reason // plus one this role has on its own: it runs from PersistentPreRun on every // startup, so a hook wrapper here would run a user's script before every diff --git a/issueops/workspaceconfig.go b/issueops/workspaceconfig.go index fab740ae8..2659c7193 100644 --- a/issueops/workspaceconfig.go +++ b/issueops/workspaceconfig.go @@ -60,9 +60,11 @@ type ListSettingsRequest struct{} // ListSettingsResult is the whole stored settings map. type ListSettingsResult struct { - // Settings maps each stored key to its value. A workspace with nothing - // stored yields an empty map, never nil, so a caller can range over the - // result without a guard. + // Settings maps each stored setting's key to its value. A workspace with + // nothing stored yields an empty map, never nil, so a caller can range over + // the result without a guard. + // + // Rows of the KV plane are not settings and are not here; see ListSettings. // // It is the DURABLE plane only: values that reach a running bd from // config.yaml, from the environment or from git config are not here and @@ -158,6 +160,25 @@ type UnsetSettingResult struct { // key constants above describe, which is policed here because the damage is // not a dead row but a workspace whose ids stop agreeing with each other. // +// THE THIRD FAMILY IS NOT ROUTED ELSEWHERE — IT RIDES IN THIS PLANE'S TABLE. +// Everything under `kv.` is USER DATA: the generic keys `bd kv set` writes, and +// nested inside them the `bd remember` memories under `kv.memory.`, which have +// their own merge semantics (a config conflict auto-resolves --theirs only when +// every conflicted key is a memory) and their own front doors. They are stored +// as config rows because there is one table, not because they are settings. +// `bd kv` and the memory surface are their views; this role is not. So +// ListSettings OMITS them — see its own doc — while GetSetting, SetSetting and +// UnsetSetting still answer and write a verbatim `kv.` key. +// +// THAT ASYMMETRY IS DELIBERATE. It is the same shape as the protected key's +// (Set refuses issue_prefix, Unset does not): an exclusion from the ENUMERATION, +// not a firewall. The enumeration was the disclosure — it handed every stored +// memory, key and value, to `bd config list` and to an unauthenticated +// GET /v0/beads/config, whose redaction decides on the key name while a +// memory's content is in the value. A caller naming one exact key is a +// different question, and refusing it would break `bd config get kv.foo` and +// the escape hatch of deleting a wedged memory with `bd config unset`. +// // Deterministic request-validation failures match ErrValidation; result values // are unspecified when error is non-nil. Implementations never mutate // caller-owned request values. @@ -176,6 +197,12 @@ type WorkspaceConfig interface { // ListSettings returns every stored setting. // + // EXCEPT THE KV PLANE. No key under `kv.` appears here — not the generic + // `bd kv` keys and not the `bd remember` memories nested under them — even + // though those rows live in the same table and GetSetting still answers + // each one by name. See "KEYS THIS PLANE DOES NOT OWN" above for what that + // plane is and why the exclusion stops at the enumeration. + // // A read, on the same terms as GetSetting, and one whose answer is a MAP rather // than a page: settings are a keyed namespace a workspace holds tens of, // not a collection to scan, so there is no order, no limit and no cursor diff --git a/memoryops/doc.go b/memoryops/doc.go new file mode 100644 index 000000000..6db1e1638 --- /dev/null +++ b/memoryops/doc.go @@ -0,0 +1,42 @@ +// Package memoryops describes the workspace's PERSISTENT MEMORY PLANE: the +// keyed notes `bd remember`, `bd recall`, `bd forget` and `bd memories` store +// and read, and that `bd prime` injects into a session. +// +// It is a sibling of issueops rather than more verbs on +// issueops.WorkspaceConfig, and the reason is not that the rule forbids +// appending (it does): memories are not settings. They ride in the same config +// table but they are USER DATA under a reserved namespace +// (internal/storage/kvkeys), they have their own merge class — the storage +// merge resolver auto-resolves a config conflict with --theirs only when every +// conflicted key carries the kv.memory. prefix +// (internal/storage/versioncontrolops/mergesettle.go:639-671), so +// convergent-on-pull is part of what a memory MEANS and no settings row means +// that — and they have a found/not-found user contract the settings plane has +// no use for. +// +// THE STORAGE ENCODING IS NOT IN THIS PACKAGE, and that is deliberate. A +// memory named "dolt-phantoms" is stored under the config key +// "kv.memory.dolt-phantoms", but every request and result here carries the USER +// key. kvkeys is the single source of truth for the prefix and the +// implementations are the only code that spells it; naming it in a leaf type +// would make the encoding part of the caller's vocabulary and put a second copy +// one rename away from drifting. The encoding is stated here in prose because +// it is part of what the contract MEANS — it is why a memory converges on pull +// and a setting does not — not because a caller has to construct it. +// +// WHAT THIS PACKAGE IMPORTS: stdlib, plus github.com/steveyegge/beads/issueops +// for the error sentinels and nothing else. That is narrower than the issueops +// leaf rule ("internal/types and stdlib"): a memory is a string under a string +// key, so nothing in internal/types is needed here and importing it would only +// invite issue-shaped types into a plane that has none. The one sentinel is +// ALIASED rather than redeclared — see errors.go — and the transitive pull of +// internal/types through issueops is an artifact of that alias, not a +// dependency anything here uses. Nobody should "fix" it by copying the +// sentinel. +// +// THERE IS NO PAGE HERE. Memories are a keyed namespace a workspace holds tens +// of, exactly like settings, so List answers with a map: no order, no limit, no +// cursor. A front door that prints them sorts the keys, and both do today. If +// this plane ever grows to thousands of rows, a paged reader is a new role +// conversation and not a retrofit of this one. +package memoryops diff --git a/memoryops/errors.go b/memoryops/errors.go new file mode 100644 index 000000000..d46d4c534 --- /dev/null +++ b/memoryops/errors.go @@ -0,0 +1,29 @@ +package memoryops + +import "github.com/steveyegge/beads/issueops" + +// ErrValidation classifies this role's deterministic request-validation +// failures. It is an ALIAS of issueops.ErrValidation, not a second sentinel, +// and the identity is the point: the HTTP problem classifier, cmd/bd's error +// handling and every conformance suite already errors.Is against that one +// value, so a memoryops-flavored twin would make each of them double-match +// forever — one vocabulary with two doorplates instead of two vocabularies. +// +// It is re-exported here rather than left for callers to reach through +// issueops so that code holding only the Memories interface can classify a +// refusal without knowing the issue package exists, which is the courtesy +// issueops.ErrUnsupported's doc extends for the same reason. +var ErrValidation = issueops.ErrValidation + +// THERE IS DELIBERATELY NO ErrNotFound ON THIS ROLE. +// +// The storage seam beneath it cannot tell an absent config row from a row +// stored as the empty string (issueops/workspaceconfig.go:41-52 states the same +// conflation for settings, and it is the same table). A role that answered a +// Recall of an unknown key with ErrNotFound would be minting an error out of a +// distinction it cannot actually see, and the first out-of-band empty write +// would make it a lie. +// +// Misses are RESULT-CARRIED instead — RecallResult.Found, ForgetResult.Found — +// and the front doors translate: the CLI to its SilentExit contract, an HTTP +// door to its 404. That keeps the invention where a door can justify it. diff --git a/memoryops/memories.go b/memoryops/memories.go new file mode 100644 index 000000000..fd36482de --- /dev/null +++ b/memoryops/memories.go @@ -0,0 +1,198 @@ +package memoryops + +import "context" + +// RememberRequest stores one memory. +type RememberRequest struct { + // Key names the memory to store under. EMPTY MEANS DERIVE IT from Content, + // using the one canonical derivation (internal/memoryapi.DeriveKey — the + // function that has minted every auto-generated memory key since the + // command shipped). A request with no key is the NORMAL case, which is why + // the role derives rather than making the caller learn the derivation. + // + // A non-empty Key is used VERBATIM: no trimming, no slugging, no charset + // restriction. `bd remember --key` has always accepted any string, and a + // stored key has to stay recallable under the exact bytes the caller used. + Key string + // Content is the memory itself. + // + // Empty after trimming is ErrValidation. So is content from which no key + // can be derived when Key is empty — "!!!" derives to "" — because the + // alternative is a row under a key nothing can name. + // + // Otherwise it is stored VERBATIM: newlines, surrounding space and unicode + // all survive. Truncating it to one line is what a front door does when it + // prints; it is not what this plane does when it stores. + Content string +} + +// RememberResult reports what landed. +type RememberResult struct { + // Key is the key the memory now lives under: the request's, or the derived + // one. A caller that supplied no key learns here what to recall. + Key string + // Value echoes the stored content, verbatim. + Value string + // Replaced reports whether a previous value existed under Key, OBSERVED IN + // THE SAME TRANSACTION AS THE WRITE. It is what the CLI's "Remembered" + // versus "Updated" verb is made of, and unlike the two-step read it + // replaces it cannot be stale: no concurrent write can land between the + // observation and the act it describes. + // + // A previous value that was the EMPTY STRING reports Replaced true. The ROW + // existed, even though a Recall of that key would have answered Found + // false. That divergence is the storage seam's conflation showing through + // (see RecallResult.Found); it is stated here rather than smoothed over, + // because smoothing it would mean this field reporting "nothing was there" + // about a write that overwrote something. + Replaced bool +} + +// RecallRequest names one memory to read. An empty Key, or one that is empty +// after trimming, is ErrValidation: there is no row a caller could mean by it, +// and answering Found false would report "no such memory" for a question that +// was never asked. +type RecallRequest struct{ Key string } + +// RecallResult is one memory's stored content. +type RecallResult struct { + // Key echoes the request. + Key string + // Value is the stored content, or "" — and Found says how to read the "". + Value string + // Found is Value != "". A MEMORY STORED AS THE EMPTY STRING AND AN ABSENT + // MEMORY ARE THE SAME ANSWER: Found false, nil error. + // + // No front door can create the first of those — Remember refuses empty + // content — but an out-of-band config write can, and this role does not + // invent a distinction the seam beneath it cannot see. List DOES enumerate + // such a row, because its KEY exists, and that is the one way a caller can + // tell the two apart: the same same-answer-different-row asymmetry the + // settings contract pins for `bd config get`. + Found bool +} + +// ForgetRequest names one memory to remove. An empty Key is ErrValidation, for +// the reason RecallRequest's is. +type ForgetRequest struct{ Key string } + +// ForgetResult reports the removal. +type ForgetResult struct { + // Key echoes the request. + Key string + // Value is the content the removed memory held — what `bd forget` prints — + // read in the SAME TRANSACTION as the delete, so it is what was actually + // removed rather than what a previous read happened to see. + Value string + // Found false means nothing was stored under Key (or an empty string was: + // the same conflation RecallResult.Found describes) and NOTHING WAS + // DELETED. + // + // It is a result, not an error. The front doors own the not-found + // presentation — the CLI has an exit-code contract for it — and a role that + // returned an error here would force every one of them to classify a + // refusal to learn a fact. + Found bool +} + +// ListRequest asks for the memory plane, optionally narrowed. +type ListRequest struct { + // Search filters the answer: a memory matches when the lowercase of its key + // or the lowercase of its value contains the lowercase of Search. "" means + // everything. + // + // THE FOLDING IS THIS ROLE'S, not the caller's. A caller passes what the + // user typed; it does not pre-lower the term. That is the difference + // between a role that owns the matching semantics and one that documents + // them and hopes. + Search string +} + +// ListResult is the memory plane, narrowed by the request's Search. +type ListResult struct { + // Memories maps USER key (prefix stripped) to stored value, for every row + // of the memory plane that matched — and ONLY the memory plane. Settings + // rows, generic `bd kv` rows and every other row of the config table this + // plane shares are never here, whatever they contain, INCLUDING a memory + // whose key shadows a settings name: "kv.memory.issue_prefix" is a memory + // called "issue_prefix" and the workspace's real prefix is not a memory. + // + // Empty map, never nil, so a caller can range over the answer without a + // guard. No order and no page: callers that print sort the keys, as both + // front doors do today. + Memories map[string]string +} + +// Memories describes the workspace's persistent memory plane — see the package +// doc for what that plane is and why it is not the settings plane. +// +// IT IS ONE PLANE, WHICH IS WHY IT IS ONE ROLE WITH FOUR METHODS. Store, read, +// remove and enumerate over a single keyed namespace are four shapes of one +// question, the same argument that made issueops.WorkspaceConfig one role with +// four. The promises are statements about each other — what Remember stores is +// what Recall answers and what Forget reports it removed — so splitting them +// would put one role's promise inside another role's result. +// +// The read/write entitlement test the role rule applies (can one caller be +// entitled to the read and not the write?) comes back NO here: bd's readonly +// mode is a front-door guard applied uniformly across every role, and no +// shipped path is forbidden to write memories the way a provisioned identity is +// forbidden to write a workspace identity. If a genuinely read-only memory +// consumer appears — a credential that may read prime context but not write it +// — that is the day to mint a MemoryReader. Being born whole is allowed; +// appending later is not, and splitting later is cheap because the four methods +// already have separate request types. +// +// PROBE AND ACT SHARE ONE TRANSACTION on every implementation. Remember's +// Replaced and Forget's Value are observations of the row the same transaction +// then writes or deletes, not the results of an earlier read. The shipped +// commands did it in two calls and papered over the gap by ignoring the first +// one's error; this role does not, which also means a database that cannot be +// read now FAILS the write rather than mis-reporting it. +// +// Deterministic request-validation failures match ErrValidation; result values +// are unspecified when error is non-nil. Implementations never mutate +// caller-owned request values. +type Memories interface { + // Remember stores one memory, deriving its key from the content when the + // request supplies none, and reports whether it replaced a previous value. + // + // THE REFUSALS, in the order they are applied: + // + // - Content empty after trimming is ErrValidation. There is nothing to + // remember, and a row stored empty is a row Recall would then deny; + // - Content from which no key can be derived, when Key is empty, is + // ErrValidation. The caller's recourse is an explicit key, which the + // message says. + // + // A Remember of the value already stored still performs the write. Nothing + // compares first: this plane converges on merge, so a write that decided it + // was a no-op would be a write that declined to state a fact the merge + // resolver reads. + Remember(ctx context.Context, req RememberRequest) (RememberResult, error) + + // Recall returns one memory's content, or Found false. + // + // It is a READ: nothing here records a history entry, fires a completion + // hook or changes a row. A key nothing stored is Found false with a nil + // error, never ErrNotFound — see errors.go for why that is a decision and + // not an omission. + Recall(ctx context.Context, req RecallRequest) (RecallResult, error) + + // Forget removes one memory and reports what it held. + // + // Removing a key nothing stored is a SUCCESS with Found false, and it + // deletes nothing — including nothing from the settings plane or the + // generic kv namespace that share this table. Forgetting the same key twice + // is the second call a retrying caller actually makes, and it answers the + // same way. + Forget(ctx context.Context, req ForgetRequest) (ForgetResult, error) + + // List returns the memory plane, narrowed by the request's Search. + // + // A read, on the same terms as Recall, and one that SUBSUMES the matching: + // the caller hands over the search term the user typed and this role owns + // what matching means. A miss answers an empty map, never nil and never an + // error. + List(ctx context.Context, req ListRequest) (ListResult, error) +}