beads/engdocs
Julian Knutsen b303d494df
perf(http): answer a command's repeated reads from one response; bd show --json makes 1 request (port of bd-enterprise e626072b8) (#7588)
* perf(http): answer a command's repeated reads from one response (port of bd-enterprise e626072b8)

Over an http workspace, bd show <id> --json made three identical
GET /v0/beads/issues/<id> requests: the id resolver's exact probe,
routed.go's GetIssue and show's detail read all build the same URL. Text
show made six. Over a gateway each one is a sequential round trip, so the
request count is the command's latency floor (mc-5dkzp).

This ports bd-enterprise e626072b8 (bts-xpw.3.14.6, #217) verbatim, except
cmd/bd/main.go, where OSS still opens the identity preview inline, and
bd-enterprise's httpgw dialer test, which has no OSS counterpart:

- httpclient.WithSharedConnections: the identity-gate preview and the real
  open share one transport, so a write makes one handshake.
- httpclient.WithReadMemo and a wire.Client read memo, for one-shot
  commands only (not bd serve, --watch or --follow): identical getIssue,
  getSetting and listSettings reads are answered from the response already
  received. An entry ages from the server's answer (5 s), any write clears
  the memo, a read that overlapped a write is not stored, and expired
  entries are swept.
- bd list's three vocabulary reads come from one memoized listSettings.
- bd update --status / --if-status skips the custom-status read for a
  built-in status.
- The hook decorator skips its post-write re-reads when no executable hook
  exists for the event.
- bd dep add reads its confirmation titles before the write, from the memo.

Against a loopback bd serve: show --json goes from 3 requests to 1, text
show 6 to 3, update 5 to 3, close 6 to 4. Dolt and the other registered
backends receive the same ctx and ignore it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(http): BD_HTTP_READ_MEMO=0 turns the per-command read memo off

An operator who suspects a stale read can rule the memo out without a
rebuild. Any other value, or none, leaves the default.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(http): pin bd show to one fetch per issue (mc-5dkzp)

TestE2E_PerCommandRequestBudget allowed show two requests, and a read
that drifts to a URL of its own (a mutant whose reader spells
brief_deps=false) fits that ceiling on both handshake shapes. These guards
pin the single fetch instead:

- TestE2E_ShowFetchesTheIssueOnce: the exact requests, path and query, of
  show --json, show --json --id, show --short, show of two ids and text
  show, against both handshake shapes, plus a BD_HTTP_READ_MEMO=0 step
  that must read the row more than once.
- TestDefaultIssueReadsShareOneMemoKey: the resolver's exact probe,
  GetIssue, GetDependenciesWithMetadata, GetLabels and IssueReader().Get
  build one URL, checked without a server.
- TestE2E_CloseRereadsItsOwnWrite: against the MC handshake, closing a
  lone molecule re-reads its own closed row from the server after the
  write, and prints no false "completed molecule" note.
- Corpus shapes can pin `requests:`, counted on the served run alone (not
  setup, verify or {rev:ID} reads). The seven gc and mc show shapes pin
  1, 4, 1, 1, 3, 1 and 3.

Also: TestReadMemoOptInReadsTheRealPollingFlags holds the opt-in to the
real show/list --watch and -w, events tail --follow and bd serve; the
show budget drops from 2 to 1; requestCounter records each request's
query; and ledger row L-read-memo records the memo's bounded difference
from local reads.

Mutation runs against this tree: brief_deps=true on GetIssue and
brief_deps=false on the reader's Get each fail the e2e list and the unit
test; show opting out of the memo fails the e2e list; writes that leave
the memo standing fail the read-your-own-write e2e; a memo keyed by path
alone fails the e2e list; dropping the kill switch fails its unit test
and the e2e step.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs(config): list BD_HTTP_READ_MEMO

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(http): memoize a read's answer only once it has decoded

wire.Client.Do stored a memoable read's 2xx before it checked the body,
so an empty or undecodable 200 would have answered every identical read
in the command for the memo's whole TTL with the same failure, instead
of asking the server again. The answer is now stored only after it
decodes; a read that decodes nothing (out == nil) is not stored, and
every memoable read in this package decodes its answer.

TestReadMemoKeepsOnlyAnswersThatDecoded pins it (empty body, truncated
body, undecoded answer). Ledger row L-read-memo says so.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(http): pin the read memo's 5xx, write-method, per-client, in-flight-write and hook-gate behavior

Review follow-ups for the per-command read memo (mc-5dkzp):

- TestReadMemoNeverKeepsA5xx: a 503, 500 or 502 is not memoized and the
  2xx after it is. TestDispatchRetryOfABusyMemoizedReadAsksTheServer
  holds the same through dispatch's retry loop over a real wire.Client:
  the retry reaches the server instead of replaying the 503.
- TestReadMemoIsDroppedByAnyWrite covers POST, PUT and DELETE, not just
  PATCH.
- TestReadMemoIsPerClient: in either order, one client's read is never
  answered from another's memo, and opting one client in opts in no
  other. (A shared memo was otherwise caught only by test-order
  pollution.)
- TestReadMemoDropsAnAnswerReadWhileAWriteWasInFlight pins the clear on
  the write's way back: a read that starts and ends while the write is
  on the wire is not answered again once the write has returned.
- TestHookFiringStoreReReadsOnlyForAnEventWithAHook pins hookConfigured's
  probe: the decorator asks the runner about the event it fires, and
  re-reads the row to build a payload only when a hook for that event
  exists, through a probing double and through a real hooks.Runner.

Each was run against a mutant of the code it pins and fails there:
5xx stored before the status check; only PATCH clearing; one memo
shared by every client; no clear after the write returns;
hookConfigured answering true, false, or about the wrong event.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs(changelog): note the per-command http read memo

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-16 04:26:37 +00:00
..
adr fix(init): #5791 follow-up — name --recreate-missing without a paste-ready command; align help, playbook and ADR 0004 (#7070) 2026-10-01 07:22:49 -07:00
decisions docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
design perf(http): answer a command's repeated reads from one response; bd show --json makes 1 request (port of bd-enterprise e626072b8) (#7588) 2026-10-16 04:26:37 +00:00
staged-for-removal docs: pin the Dolt version instead of steering users to releases/latest (ga-m0dlk) (#5899) 2026-08-20 22:41:24 -07:00
ADDING_AN_ISSUEOPS_ROLE.md feat(journalops): the mutation journal becomes the third facade namespace (#5552) 2026-08-10 10:58:05 -07:00
AGENT_SIGNING.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
AGENTS.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
ATTRIBUTION.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
BDP_BEAD_GRAPH_PLAN.md BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) 2026-09-28 22:12:19 -07:00
BDP_GRAPH_ARCHITECTURE.md BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) 2026-09-28 22:12:19 -07:00
BDP_GRAPH_CLI_AND_STORAGE_SPEC.md BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) 2026-09-28 22:12:19 -07:00
CI_CLEANUP_PLAN.md fix(preflight): share checkout lint authority (#5780) 2026-09-30 22:41:55 -07:00
CI_REQUIRED_CHECK_TOPOLOGY.md ci(bazel): dolt-int gates server-storage + cmd-dolt in mode remote (item 5 A2) (#7535) 2026-10-13 09:17:54 +00:00
CI_TEST_SURFACE_AUDIT.md ci(bazel): pin the slowest cmd/bd Dolt-server tests to their own shards (#7413) 2026-10-09 05:50:09 +00:00
CLAUDE.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
COLLISION_MATH.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
complexity-baseline.txt ci: add advisory cyclomatic complexity reporting (#6081) 2026-08-30 19:05:17 -07:00
COMPLEXITY_TRACKING.md ci: add advisory cyclomatic complexity reporting (#6081) 2026-08-30 19:05:17 -07:00
CONTRIBUTOR_NAMESPACE_ISOLATION.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
DOC_INVENTORY.md ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341) 2026-10-07 05:17:22 +00:00
ERROR_HANDLING.md docs(engdocs): re-review ERROR_HANDLING.md against cmd/bd and refresh its marker (#7267) 2026-10-06 12:46:26 -07:00
EXCLUSIVE_LOCK.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
EXTENDING.md perf(storage): SearchIssueSummaries narrow-projection foundation (be-nu4.3) (#3458) 2026-10-01 01:19:24 -07:00
ICU-POLICY.md ci(bazel): run the upgrade smoke tests under Bazel; retire cross-version-smoke.yml (#7331) 2026-10-07 02:49:39 +00:00
INTEGRATION_CHARTER.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
INTERNALS.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
LINTING.md ci: F5 S2 Variant A — nogo ownership for the integration configuration group (#7486) 2026-10-10 23:19:16 +00:00
messaging.md fix(doctor): recommend 'bd prune' instead of nonexistent 'bd cleanup' (#5829) 2026-08-20 05:30:47 -07:00
PERFORMANCE_TESTING.md docs(engdocs): point storage test and bench references at the Dolt packages 2026-07-18 02:43:57 +00:00
PROJECT_CHARTER.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
README_TESTING.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
RELEASE-STABILITY-GATE.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
RELEASING.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
REPO_CONTEXT.md fix(context): resolve from .beads when outside a git repository (#4772) (#4792) 2026-10-01 07:08:12 -07:00
RULES_AUDIT_DESIGN.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
SECURITY-DEPENDENCY-EXCEPTIONS.md Bump Go to 1.26.5 (#4942) 2026-07-23 18:54:32 -07:00
SERVE_RUNBOOK.md fix(httpclient): dial a large batchApply under the server's extended budget (#7582) 2026-10-15 23:43:54 +00:00
TESTING.md docs(ci): finish the retired-shard-job comment sweep after #7478 (wy-wqq7c1) (#7456) 2026-10-15 06:50:08 +00:00
TESTING_PHILOSOPHY.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
UI_PHILOSOPHY.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00