* fix(http): bd promote over http through issueops.Promote and issues.update.persistence (S21b)
`bd promote` refused over a connected HTTP workspace: it called the raw
PromoteFromEphemeral, which the http backend stubs, and updateIssue's patch
did not publish persistence. MC's PR-intake formula
(mol-normalized-issue-pr-v1) runs `gc bd promote <id> --reason ...`, so this
blocked the HTTP cutover.
- One library entry, issueops.Promote(ctx, PromoteRoles{Reader, Lifecycle,
Commenter}, PromoteRequest{Actor, IssueID, Reason, Provenance}): read the
row, refuse a non-wisp (*NotAWispError, the sentence bd promote always
printed), move it with ONE Lifecycle.Update whose patch is Persistence =
persistent (the role's atomic plane move: same id, labels, deps, events and
comments carried), then write the promotion comment (a comment failure is
reported, the promotion stands). A no-op move is a lost race and reports
NotAWispError without a second comment.
- cmd/bd: the direct route runs it over the store's own role accessors, so a
connected http workspace and a local one take the same entry. The history
label is "bd: promote <id>" where the store carries caller labels.
- bd serve: IssuePatchBody.persistence (persistent|ephemeral|no_history,
anything else a 400 naming patch.persistence) on PATCH
/v0/beads/issues/{id}, behind the new additive behavior token
issues.update.persistence. wire_revision unchanged. Spec, apigen and the
wire-shape golden regenerated; the handler only decodes and passes it to
the role.
- httpclient: Lifecycle.Update sends patch.persistence only to a server
advertising the token, and otherwise refuses BEFORE the dial with
*wire.CapabilityError naming it (unwraps to *storage.ErrUnsupported with
Capability set). The batchApply item still refuses it
(W-IssuePatch.Persistence now reads "ON issues:batchApply").
- Conformance: RunLifecycleUpdatePersistentPromotesAWisp on dolt, embedded,
uow and the served http leg; the served
PersistentPreservesUnversionedClass case is unparked.
- Served e2e TestE2E_PromoteOverHTTP: the mc-promote shape end to end
(label kept, comment written, one PATCH, re-promote refused), and under
the MC server mask a pre-dial refusal naming the token with no write.
- Corpus: mc-promote stays pending, relabelled SRV-1 with the reference
profile's exact refusal (the 1.3.0 server lacks issues.update.persistence).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(promote): run the proxied-server route through issueops.Promote (bd-4y73m9)
The adoption review found (major) that the proxied-server route still
promoted through the old engine, IssueUseCase.PromoteWisp in one
transaction with the comment, while the PR's docs said every route runs
issueops.Promote. Converge rather than reword: runPromoteProxiedServer
resolves the id, then runs issueops.Promote over the provider's own
notifying role accessors (proxiedIssueReader, proxiedIssueLifecycle,
proxiedCommenter), the entry the direct route runs. Both routes now share
promoteFailure (the error mapping) and reportPromotion (the comment
warning and the output), so neither contract can drift.
What a script sees change on the proxied-server route:
- the move is the persistence branch of Lifecycle.Update, so the child
counter moves with the row: a promoted parent's next
`bd create --parent` mints .3 after .1/.2 instead of failing with
"issue already exists";
- on_update fires twice, for the move and for the comment, as on the
direct route (it fired once, for the comment);
- a promotion is two Dolt commits, "bd: promote <id>" and
"bd: comment <id>" (it was one);
- a comment that cannot be written leaves the promotion standing behind
a warning, as on every other route, instead of rolling it back;
- a dual-plane id is refused rather than merged, the update role's
template guard applies, and a lost race reads "<id> is not a wisp
(already persistent)".
The PromoteWisp exemption in TestRecordingIssueUseCaseCoversItsSurface
stays, with its reason corrected: no route calls PromoteWisp now, and
its DoltStorage twin fires no hook either. The doc comments on the old
engine (PromoteFromEphemeral on DoltStore and the db layer, PromoteWisp)
no longer say bd promote uses it.
CHANGELOG: the promote entry now names what a script can see on the
direct and proxied-server routes: the hook firings, the comment row
`bd comments` lists, the child-counter carry, the two-commit shape, and
a comment failure that warns instead of rolling back.
Tests:
- TestEmbeddedPromoteMovesAWispParent promotes a wisp parent with .1/.2
children, a dependency and a comment under a counting on_update hook:
the hook fires twice, the dependency and the children's parent edge
survive, `bd comments` lists the old comment and the promotion reason,
and the next child is .3. At the pre-PR base it fails (the hook fired
0 times).
- The proxied journey pins the two commits, and new subtests pin the
child counter (the child_counters row, next child .3) and the two hook
firings. Against the contributor head each fails: one commit, no
counter row and a failing create, one firing.
Review iteration 2:
- TestEmbeddedPromoteMovesAWispParent gets its row in the embedded cmd
shard manifest (shard 64 of 100, from the generator's incremental
--write). Without it //scripts:go_test_sources_test fails both the
NotStale and the bare-write guard, and the generator's --check fails.
- notifying.go no longer lists the promotion comment as a divergence.
The direct route now writes that comment through st.Commenter(),
which HookFiringStore wraps, so an embedded promote fires on_update
for it (TestEmbeddedPromoteMovesAWispParent counts both firings). The
list counts four, and the empty-commit note becomes the fifth item.
- batchapplier.go no longer says persistence is absent from both patch
bodies: the update body publishes it behind issues.update.persistence,
and only batchApply refuses it (W-IssuePatch.Persistence).
- Three comments still tied promotion to the old engine: the
conformance fixture's PromoteWisp no longer claims to do what
`bd promote` does, the CLI differential's promote scenario names
issueops.Promote, and export_source's wisp-relations note names
issueops.MoveIssuePersistenceInTx.
- The Promote unit test compares the whole update patch with
reflect.DeepEqual. The helper it replaces checked 9 of the patch's 22
members, so a Promote that also set Description passed it.
Review iteration 3:
- A refused persistence move answered 500 `internal` over http and
emitted request_error, though the caller could fix the request. The
role now returns two refusals as ErrValidation, so bd serve answers
400 invalid_argument and the client maps that back to ErrValidation:
an unversioned row asked for ephemeral or no_history (the role wraps
types.ErrUnversionedWispMove, a new sentinel NormalizePersistenceMode
returns for that case alone, with its message unchanged), and a
demotion of a row with retained snapshots. A row that breaks its own
persistence invariants still answers 500.
- RunLifecycleUpdateWispModesRefuseAnUnversionedRow pins the refusal on
every leg (dolt, embedded dolt, the unit of work, served http): both
wisp modes match ErrValidation and leave the row durable, unversioned
and off the wisp plane. Without the wrap the dolt leg fails, and the
served leg fails on "answered 500 internal".
- TestMoveIssuePersistenceInTxRefusesDemotionWithRetainedSnapshots is
the first test of the snapshot refusal, and fails without its wrap.
The unversioned unit test now requires both sentinels. The types tests
pin the sentinel, its unchanged message, and that no row-invariant
error matches it: checking the unversioned class ahead of the
invariant checks fails them.
- CHANGELOG: the promote entry counts five script-visible changes, the
fifth being the lost-race refusal sentence, and says the two refusals
now answer 400 over bd serve and gain a `validation failed: ` prefix
locally.
- NotAWispError's doc comment records that a no-history wisp is refused
too: the gate reads the Ephemeral flag, as bd promote always has, and
`bd update --persistent` is the move for that row.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat(backend/http): add the public HTTP backend door, cmd/bd registration, and bd connect
internal/httpclient (S1-S5) had no production caller for the per-open
backends.OpenOptions.Credential seam and no way for a workspace to actually
select it. This slice (S6) closes both gaps in OSS's own idiom, without
carrying over anything from bd-enterprise's gateway/box-login/storage-profile
machinery:
- backend/http (bdhttp) is the public, out-of-tree extension door: Register
adds "http" to the backend registry and installs its transport, Open/
Handshake dial a server directly with no workspace on disk, and the
registered OpenWith hook threads a per-call credential through
beads.OpenBestAvailableWith for a multi-tenant embedder.
- internal/httpclient/open_with.go is the backends.Backend.OpenWith hook
itself: a fresh dial per open (opts.Credential/HTTPClient/UserAgent),
distinct from the process-wide registered dialer Open/OpenReadOnly use.
- cmd/bd/http_backend.go registers the backend for the OSS binary, so a
workspace whose metadata.json names "http" opens through the ordinary
OpenBestAvailable path; any other unregistered backend name still refuses.
- cmd/bd/connect.go adds the minimal `bd connect <url>` command: a handshake
that must succeed before anything is written, a per-user activation
sidecar (.beads/http_target.json, never git-tracked), a plaintext-to-
non-loopback refusal without --allow-plaintext, and a backend-switch
refusal without --force. No credential is ever accepted on the command
line or written to disk.
- cmd/bd/doctor/gitignore.go requires the new http_target.json /
http_local_metadata.json sidecars be git-ignored, the same way the
proxied-server client info already is.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(storage): keep external-dependency blocking over http unless the server enforces it
bd ready / bd close / claim hard-failed against the new http backend with
"GetAllDependencyRecords not supported by the http backend": cmd/bd's
storage chain wraps every opened store in the externaldeps policy
decorator, which needs either the narrow ExternalDependencyQueryStore
interface or the broad GetAllDependencyRecords fallback to resolve
blocking state, and the http client implemented neither.
The decorator now stays on for a remote store. It is skipped only when the
server's handshake advertises policy.external_dependencies (the server
enforces the policy before answering). Without that capability the client
resolves blocking itself from the listing and chunked dependency reads, so
an issue with an unresolvable external: dependency stays out of bd ready
exactly as it does on a local backend; it is never silently skipped
(DESIGN 3.6). Server-side enforcement is slice S10.
storage.RemoteBackendStore marks a DoltStorage that is a pure network
client of a remote bd serve; the http backend's Store satisfies it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(cmd/bd): suppress the CreatedBy stamp on create against a remote backend
bd create failed against the http backend with "Issue.CreatedBy: ... is not
expressible on the v0 wire": the http client's create role deliberately
refuses any POPULATED CreatedBy/CreatedAt (the creation stamp belongs to the
server's own journal entry, not a value the caller supplies), but
cmd/bd/create.go unconditionally stamped getActorWithGit() onto every
created issue regardless of backend. The refusal only fires on a non-zero
field, so suppressing the stamp for a registered remote backend is wire-
compatible by construction, not a workaround.
Add isRemoteBackendWorkspace()/creationActorStamp() to backend_support.go,
reusing the existing resolveCommandBeadsDir(dbPath) +
backendNameForErrorFraming(beadsDir) + backends.IsRemote(name) pattern
already used elsewhere in that file, and use creationActorStamp() at both
create.go call sites (the dry-run preview and the real create).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* test(backend/http): add an embedder linkage test over public packages only
Prove the one promise S6 makes to an out-of-tree embedder (gc is the
motivating case): importing nothing but github.com/steveyegge/beads,
.../backend, and .../backend/http is enough to register the http backend,
open a workspace through it with a per-call credential
(beads.OpenBestAvailableWith), and read through the role-accessor surface
(IssueReader().Ready) against a stand-in server — with no internal/...
import in the test file, which is itself the thing under test.
Written fresh for OSS beads S6; no bd-enterprise source copied.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document the HTTP backend, bd connect, and the public backend/http door
Add a README section with bd connect usage, the credential ladder, and the
plaintext/force refusals, plus a CHANGELOG entry for the new cmd/bd
registration, bd connect command, and the public backend/http package.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpclient): address bee-ghosttrack review on #7288 (connect --clear restore, persisted --allow-plaintext)
Closes the CHANGES_REQUESTED items on the HTTP backend door PR:
- Must-fix: `bd connect --force` over a workspace with its own local
(dolt) identity now has writes succeed instead of tripping "workspace
identity mismatch detected" — validateWorkspaceIdentity (cmd/bd/main.go)
and the sidecar (internal/httpclient/metadata.go) now compare against
the http backend's own pinned project id. New e2e regression test
TestE2E_ForceConnectWritesSucceedDespiteDifferingLocalProjectID
(backend/http/e2e_cli_test.go), confirmed to fail without the fix.
- Should-fix 1: `bd connect --clear` now restores metadata.json's
backend selection to whatever it was before this workspace connected,
instead of leaving it pinned to "http" with no sidecar to dial.
Target.PreviousBackend (internal/httpclient/target.go) is recorded by
Attach (backend/http/attach.go) and round-tripped through the sidecar;
connect.go reads it back on --clear. New tests in
backend/http/attach_test.go and internal/httpclient/target_test.go.
- Should-fix 2: `bd connect --allow-plaintext` is now remembered in the
sidecar (Target.AllowInsecureCredential), scoped to the target it was
granted for, so every later ordinary command's dial honors the grant
without also needing BEADS_HTTP_ALLOW_INSECURE=1 set
(internal/httpclient/dial.go). Fixed BearerProvider.warnInsecure's
wording (internal/httpclient/credential.go), which used to assert a
token was being sent immediately above a refusal saying the opposite.
New test TestDialWithWiresTargetAllowInsecureCredentialThroughToTheGuard.
- Should-fix 3: README no longer claims HTTP mode works "exactly as
with a local database" — it lists what round-trips and points at the
divergence ledger (engdocs/design/http-divergence-ledger.md) for what
differs.
- Verified, no code change needed: Attach already handles an existing
metadata.json project_id coherently (only cfg.Backend is touched); bd
show's isNotFoundErr already matches a http 404 (issueops.ErrNotFound
is storage.ErrNotFound, the same sentinel a local miss uses), so it
reads as "not found" rather than an unsupported-operation error.
- Doc fix: guardInsecureCredential's doc comment and refusal message
were stale against should-fix 2's own change — they named only
DialOptions.AllowInsecureCredential and the env var as ways to get
past the guard, not the newly-persisted target.AllowInsecureCredential
or `bd connect --allow-plaintext` itself.
Gates run clean on this branch: go build/vet, go test over
internal/httpclient, backend/http (including the full e2e suite under
BEADS_TEST_EMBEDDED_DOLT=1) and cmd/bd, make api-check, make
ci-pr-lint, make bazel-sync-check, bazel run //:gazelle -- -mode=diff,
and internal/storage's TestEveryLegWiresEveryRoleContract.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* test(backend/http): give the e2e server the BatchGetter role #7248 added to the required set
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix: exact http ready totals, connect capability row, doc corrections
Ready totals over http (review major). externaldeps drops externally
blocked rows client-side for a store that cannot express ExcludeIDs
(today httpclient.Store). dropBlockedIssuesWithCounts compacted the
fetched rows in place (`kept := rows[:0]`), and
readyWorkWithCountsAndTotal then re-scanned `rows` to count the blocked
rows it had dropped. By then the compaction had overwritten them, so
whenever a blocked row came back ahead of a kept one the re-scan
undercounted the drops: `bd ready --json`'s total and text-mode `bd
ready`'s count (CountReadyWork) overstated ready work against any server
that does not advertise policy.external_dependencies. Both drop helpers
now copy into a fresh slice, and dropBlockedIssuesWithCounts reports how
many rows it dropped, so nothing re-scans `rows`.
fakeStore gains an excludeIDsUnsupported switch that, like
httpclient.Store, refuses any ExcludeIDs. The new
TestReadyTotalsWhenStoreCannotExpressExcludeIDs puts the blocked issue
first and checks the page and total for an unlimited filter, a Limit
whose bumped window holds the whole set, and one the set outgrows, then
CountReadyWork. TestServedReadyExcludesUnsatisfiedExternalDependencyWithoutServerCapability
now also checks the total and count against a real in-process bd serve.
Against the previous decorator the unit test's unlimited case reports
total and count 3 beside a 2-row page, and the served test 2 beside a
1-row page.
Review minors, all wording:
- `bd connect --clear` pointed at `bd config set backend dolt`, which
writes the database's config table rather than metadata.json and, in
the state that prints the advice (metadata.json says http, sidecar
gone), fails the pre-open identity check. It now says to reconnect, or
to set "backend" in metadata.json.
- CHANGELOG described the superseded skip-at-wrap design; it now
describes the always-wrap decorator with its capability probe and
client-side drop.
- RemoteBackendStore's docs no longer name a consumer; nothing in-tree
checks it.
- creationActorStamp's comment pointed at backend/http/lifecycle.go; the
refusal lives in internal/httpclient/lifecycle.go.
Capability row. TestProxyCapabilityRegistryCoversCommandTree fails at
60b7128204: the command tree walk finds `connect`, which this PR adds,
with no row in cmd/bd/capability_registry.go ("1 command(s) have no
proxied-server capability row: connect"). The test predates the PR
(#6582 is an ancestor of its base) and passes at the base dabf20ef07.
connect opts out of store init (skipStoreAnnotation) and never reaches
the store factory, so it belongs in proxyPermittedPaths beside init and
setup. The row is runtime-neutral: validateProxyRegistryBeforeProvider
returns nil both for a permitted row and for a path with no row, so
this only records the policy decision the coverage test asks for.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(httpclient): regenerate the divergence ledger doc after the S5 rebase
The rebase onto feat/http-client-batch-apply's rebased head (S3/S4 merged to
main) left the ledger doc's summary line at a conflict-resolution placeholder
count. Regenerate it from internal/httpclient/encode.Ledger() so
TestDivergenceLedgerDocMatchesLedger passes against the merged ledger.go.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(backend/http): host-scope S6's test BEADS_HTTP_TOKEN values
Rebasing onto feat/http-client-batch-apply's rebased head pulled in main's
#7247 review-fix round, which made BEADS_HTTP_TOKEN/BEADS_HTTP_TOKEN_COMMAND
host-scoped (host[:port]=value, scopedEnvValue/parseScopedEnv in
internal/httpclient/credential.go) after S6's own tests were written against
the unscoped form. Five S6 tests across backend/http/open_test.go,
backend/http/register_test.go and
internal/httpclient/insecure_credential_guard_test.go set a bare token and
now hit the new ladder's "an unscoped token would be used for whatever
server..." refusal. Scope each to the test server's actual host
(127.0.0.1 for the httptest.Server-backed recording servers,
nonLoopbackTestHost for the insecure-credential-guard integration tests)
so they exercise the same ladder rung as before.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* build(bazel): resync go_srcs/repo_files for the new backend/http and test/embedder packages
make bazel-sync-check failed after the rebase: tools/bazel/go_srcs.py's
managed repo_files filegroups for backend/http and test/embedder (new in
this slice) hadn't been generated, and the root BUILD.bazel / tools/bazel's
release_cross_build target list hadn't picked up the new package either.
Regenerate with `python3 tools/bazel/go_srcs.py`; `bazel run //:gazelle --
-mode=diff` reports no further drift.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(cmd/bd): route swarm's create paths through creationActorStamp after main's currentActor change
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix: police http's served roles, refuse close --claim-next, exact totals
External-dependency policy over http (review blocker). cmd/bd wraps
every store, http included, in the externaldeps decorator, and its role
accessors rebuilt each role over legacy methods httpclient.Store refuses
(SearchIssuesWithCounts, GetDependencyTree, ClaimReadyIssue, IsBlocked,
GetDependencyRecordsForIssues, BatchCloserWithPolicy). Over http `bd
list`, `bd dep tree`, `bd ready --claim` and a policed `bd close`
therefore exited 1, even in a workspace with no external dependency.
Over a store that reports storage.RemoteBackendStore, each accessor now
starts from the inner store's served role and layers the policy around
it (remote_roles.go):
- IssueReader serves List and Get from the served reader; Ready and a
ready-flagged List go through the policy reader.
- IssueClaimer refuses an externally blocked claim before the served
one.
- ReadyClaimer uses the served claim-next while no issue, closed ones
included, holds an unsatisfied external ref. Otherwise it claims down
the policy's filtered ready page through the served Claimer, because
claimNext cannot exclude ids.
- BlockingAnnotator and TreeWalker merge external blockers into, or add
external leaves to, the served answer. They read only the named
issues' edges through the served EdgeReader, 100 anchors per call.
- BatchCloser refuses externally blocked open items and sends the rest
to the served closer as one request. --force keeps the base path, and
a next claim is refused whole (below).
RemoteBackendStore now only chooses this composition. Whether the policy
runs is still ServerEnforcesExternalDependencyPolicy's answer (design
3.6), and the storage and httpclient docs say so. remote_roles_test.go
drives each role over a store that refuses the legacy methods.
TestServedRolesKeepTheExternalDependencyPolicy runs every role over a
real http server. TestE2E_BDOverHTTP adds `bd list` (JSON, text and
--deps), `bd dep tree`, `bd ready`, `bd list --ready`, `bd ready
--claim`, a refused `bd close --claim-next`, and a refused then forced
close of an externally blocked issue. At the fixup before the
composition, the role tests then written (bar one pin of the next-claim
refusal, since replaced) and the e2e's list, dep tree, claim and close
steps of that round were red.
Close with a next claim over http (review major). batchCloseIssues has
no member for a next claim, so httpclient refuses any ClaimNext before
the dial (ledger W-CloseBatchRequest.ClaimNext). Over http `bd close
--claim-next` therefore always exited 1 and closed nothing. With an
external ref anywhere in the workspace (a closed holder or --force
included) the decorator's base path failed first, with an opaque
`BatchCloserWithPolicy` unsupported. remoteBatchCloser now refuses a
next claim whole, before it reads or closes anything, and the error
says nothing closed: close without --claim-next, then run `bd ready
--claim`. A request that is invalid on every backend is still
ErrValidation first, and a server that enforces the policy itself gets
the request unchanged.
Composing close-then-claim was not taken. The role closes and claims in
one transaction and answers with an error or with outcomes, never both,
so a claim that failed after the closes committed could not report
them; httpclient refuses the same request for that reason. A CLI-level
close then claim that can report a partial result is the follow-up.
The review also suggested leaving closed holders out of the blocking
state. They stay in, as on every backend: a closed issue is never a
claim candidate, so they change no claim, and leaving them out would
cost a status read per holder because the wire has no batch read.
TestRemoteBatchCloserRefusesANextClaim covers an open holder, a closed
one, none, --force, and a server that enforces the policy; with the
previous remote_roles.go the first four are red.
TestRemoteBatchCloserValidatesANextClaimFirst keeps ErrValidation ahead
of the refusal. Dropping the filter check, or loading the blocking
state before refusing, is each caught. TestE2E_BDOverHTTP runs `bd
close --claim-next` while the holder is open and again after it is
closed; with the previous remote_roles.go both steps are red and print
`operation "BatchCloserWithPolicy" not supported`. Ledger F-close no
longer says --claim-next is served, and no longer names a
renderEscapedHTTPRefusal that does not exist. L14 says the decorator's
claim leg applies while any issue, closed or not, holds an unsatisfied
ref. The README and CHANGELOG mention the refusal, and the decorator's
IsBlocked, IsBlockedBatch and CloseIssueChecked say they refuse over a
store that serves its roles.
Ready totals with external blockers (review majors, both rounds).
CountReadyWork asks for Limit=0, and readyWorkWithCountsAndTotal took
any Limit<=0 to mean "the window held the whole ready set". Over http a
zero limit never reaches the wire: the server answers with its default
page (workapi.DefaultReadyLimit, 100 rows) while the bridge reports the
full total, so past 100 ready issues text-mode `bd ready` kept counting
externally blocked issues beyond the first page. Exactness is now judged
from the rows that came back (total <= len(rows)). A window that holds
only part of the set no longer subtracts every externally blocked id in
the workspace either: that set includes closed issues and ones the
filter excludes, none of them in the total, so the count came out low.
It refetches the filtered ready set, ids only, and subtracts the blocked
rows in it; the old bound is left as the fallback for a refetch that
comes back truncated too.
fakeStore gains the bridge's shape: a defaultPage for a zero Limit,
with GetReadyWorkWithCountsAndTotal still totalling the whole set.
TestReadyTotalsWhenAnUnlimitedFetchComesBackAsOnePage (a blocked issue
past the first page) and
TestReadyTotalsIgnoreExternallyBlockedIssuesOutsideTheReadySet (a
blocked issue outside the ready set) have served counterparts,
TestServedReadyCountExcludesAnExternallyBlockedIssuePastTheDefaultPage
and TestServedReadyTotalIgnoresAnExternallyBlockedIssueOutsideTheFilter
(an assignee filter). The first pair is red on the Limit<=0
condition, the second on the subtract-every-blocked-id branch.
Docs: ledger L8 now says which decorator paths take the chunked
GetAllDependencyRecords scan and which read only named edges, and L14
records the decorator's composed claim leg; http-divergence-ledger.md
is regenerated. The README names the verified commands, and the README
and CHANGELOG say how cross-repo dependencies behave over http.
Minors from the reviews:
- Drop creationActorStamp/isRemoteBackendWorkspace and restore the base
stamps at all 11 sites. The arm guarded a refusal the http create
role does not make: since #7247 (actorStampedCreateMember) it accepts
a CreatedBy naming the actor. Because the arm keyed on the CWD
workspace, a create routed from an http workspace into a local one
(--repo) stored an empty created_by. TestE2E_BDOverHTTP checks
created_by for a direct and a routed create; the routed check is red
with the arm restored. The CHANGELOG sentence describing the arm goes
with it.
- bdhttp.Attach decides a reconnect from the raw metadata.json backend.
GetBackend() reads an unregistered "http" as the dolt default, so in
an embedder that never called Register a reconnect recorded dolt as
the backend --clear restores. The reconnect test now seeds postgres
(TestAttachOnAReconnectKeepsTheEarlierPreviousBackend) and is red
with the old check.
- README, CHANGELOG and `bd connect --help` document the host-scoped
BEADS_HTTP_TOKEN=host[:port]=<token> form (and _COMMAND), and say why
a bare value is refused.
- bdhttp.Attach also gitignores http_local_metadata.json, the per-user
file the store writes on first use, so an embedder activating through
Attach alone gets the coverage `bd connect` already had.
TestAttachGitignoresBothPerUserFiles pins it.
- ServerSnapshot.WireRevision's doc names the handshake's actual check
instead of a comparison `bd connect` never makes.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(backend/http): give the e2e server the LeaseReclaimer role #7412 added to the required set
main's #7412 made LeaseReclaimer part of httpapi's required role set and
updated main's own binders, but backend/http's e2eServeConfig predates it,
so every TestE2E_* that binds the in-process server failed with
"httpapi: no database source". Same shape as e63f7da36a for BatchGetter.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(externaldeps): lead the --claim-next refusal with the wire fact; pin the L14 leg and connect --clear
Review i4 minors/nits on the stranded fixup, carried as a separate commit:
- remoteBatchCloser's --claim-next refusal now says the served batch close
cannot carry a next claim (the real cause), rather than blaming
externally blocked work a workspace may not have. The test asserts the
reason, that nothing closed, and the remedy.
- GetDependencyTree's doc says a served store refuses its reads and that
bd dep tree goes through remoteTreeWalker.
- README no longer gives `bd ready --claim` local semantics everywhere; it
names when ledger row L14's two-step claim applies.
- TestE2E_BDOverHTTP claims once more after the external-ref holder is
closed, pinning L14's composed leg (a mutant whose composed leg claims
nothing turns only that step red).
- New TestE2E_ConnectClearRestoresThePreviousBackend: --clear restores
the prior dolt backend with its identity intact, removes the sidecar,
and a second --clear changes nothing.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(backend/http): run the served e2e under bazel
//backend/http:http_test declared no bd binary, so under bazel the e2e
files (bazeltest.PrebuiltBD) failed on BEADS_TEST_BD_BINARY with
BEADS_HTTP_TEST_REQUIRED=1 and only "passed" by skipping otherwise. It now
takes //cmd/bd:bd_for_tests (visibility added), size large / timeout long:
the served cases run 4-5 minutes on the farm under BEADS_TEST_EMBEDDED_DOLT=1.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(backend/http): run the e2e tier in the embedded lane as http_served_test
The previous commit gives //backend/http:http_test the bd binary, but no
lane sets BEADS_TEST_EMBEDDED_DOLT for it, so its TestE2E_* cases still
skipped in CI. http_served_test runs the same test binary through
//tools/bazel:go_test_variant.sh with BEADS_TEST_EMBEDDED_DOLT=1 and
BEADS_HTTP_TEST_REQUIRED=1 (a skip fails it). It is tagged embedded, so
the --config=embedded lane runs it and prcore/ci keep their current
shape, the same split as //internal/httpclient:httpclient_served_test.
Under plain --config=embedded all 8 TestE2E_* cases run, none skipped.
TestBazelRetiredLanesCannotBeNarrowed pins every embedded-lane target's
args and env; the new target is added to that pin list.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(externaldeps): cap the ready rows kept, not the bumped http window
An http store cannot carry ExcludeIDs on listReadyWork, so readyExclusion
fetches the unfiltered ready set, widened by len(blocked) under a limit,
and drops the externally blocked rows client-side. The http ready bridge
enforced MaxRows on the rows it fetched rather than the rows kept. So
`bd ready --limit N --max-rows N` exited 2 whenever more than N issues
were ready and any workspace issue held an unsatisfied external blocker
(a closed one counts), even with no blocked row in the window, and a
blocked row in the page counted against the cap although the caller
never sees it. Locally neither can happen: issueops enforces the cap on
the filtered page it delivers, after the Limit trim
(finishReadyWorkWithCounts).
The client-side path now takes MaxRows off the inner query and enforces
the caller's cap on the rows it keeps, after the trim, in all three
listings. The inner query keeps the cap whenever nothing is dropped
client-side. MaxRows never rode the wire, so the fetch is the size it
was; refetchedReadyTotal already clears the cap on its own over-fetch.
TestServedReadyMaxRowsCountsTheRowsKept runs the decorator over a served
http store holding three free issues and one externally blocked one: a
cap equal to the limit, a cap under a wider limit, an unlimited listing,
and a kept page wider than the cap, which must still return
ErrTooManyRows with the caller's cap and source. Each case runs through
GetReadyWork, GetReadyWorkWithCounts and GetReadyWorkWithCountsAndTotal.
Leaving the cap on the inner query fails the first three cases in all
three methods, dropping the re-applied cap fails the fourth, and
enforcing it before the Limit trim fails the first.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
* ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files
//scripts:scripts_test declared //:repo_files (the whole checkout), so every
PR re-ran it, and it took ~181s on rbe-west. Most of that (60-79s) was
TestBazelGatedLanesNeverRetryFlakyTests line-regexping the --run_under
wrapper's pinned dolt binary (tools/bazel/hermetic_bin/dolt, in every
test's runfiles); it now skips binary files, as git grep -I does.
tools/bazel/go_srcs.py's per-package repo_files block now partitions each
package's files into repo_go_srcs, repo_go_test_srcs, repo_doc_files and
repo_other_files, aggregated at the root; //:repo_files is their union
(same 4679 files). The //scripts tests are split into go_test targets by
what they read (traced per test with strace over a runfiles-shaped tree):
scripts_test CI/Bazel policy: //:repo_other_files (+1 Go file)
shell_scripts_test script fixtures: //scripts files, a few root files
go_test_sources_test _test.go scans: //:repo_go_test_srcs + shard files
go_sources_test check-testing-short.sh: every .go file
tracked_files_test every tracked file: //:repo_files
Shared helpers move to helpers-only files; TestScriptsTestTargetsPartition-
TheTests fails on a test file in no target or in two. //test/docsync and
the //scripts/repochecks slices declare partitions or single files instead
of //:repo_files where they can.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* ci(bazel): skip only the non-checkout hermetic_bin dir in the flaky-retry walk
Skipping every binary file also stopped scanning tracked binaries (images,
.binpb fixtures). Skip just tools/bazel/hermetic_bin, the --run_under
wrapper's runfiles directory, which is not in the checkout, so the walk's
coverage of tracked files is unchanged.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
conformance.yml ran two tiers on a GitHub runner. Tier 1 (the embedded-Dolt
TestConformance) already runs as the embedded lane's
embeddeddolt_conformance_{core,audit}_test. Tier 2, the real-binary CLI
corpus (`go test -tags 'gms_pure_go e2e' ./test/conformance`), had only a
go_library under Bazel. Its two test files now build under `e2e ||
integration`, so gazelle generates //test/conformance:conformance_test
(integration-only, against the injected non-race bd_for_tests) and
--config=integration runs it remotely in bazel-integration, which pr.yml's
gate requires. PR Core's go test builds neither tag, so the --config=ci
equivalence check is unchanged; scripts/conformance.sh keeps working with
-tags e2e as the local go test entrypoint. With both tiers covered,
conformance.yml and main.yml's warm-up compiles for it are removed.
docs-mintlify.yml drops its docsync job (`go test ./test/docsync`, run by
bazel-test as //test/docsync:docsync_test on every PR) and keeps only
Mintlify's broken-link check, which needs the network (npx mint) and the
base branch's history; its path filter narrows to what that check reads.
Refs: ga-96smfk.17
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
//scripts:scripts_test and //scripts/check-versions:check-versions_test
drop their host-tools/no-remote-exec/no-remote-cache tags and run on the
rbe-west workers like every other target (the worker image ships bash, git,
python3, jq, yq, curl, openssl, unzip and coreutils; a missing tool fails the
test under Bazel rather than skipping it). Go comes in hermetically as the
registered SDK; check-versions.sh's `go build` is stood in for by the
Bazel-built checker.
The tests that walked the source checkout now get it as data:
tools/bazel/go_srcs.py keeps a managed `repo_files` filegroup in every
package and aggregates them into //:repo_files (exactly the tracked files
Bazel can see; make bazel-sync-check fails on a package without one).
scripts_test and docsync_test take it instead of hand-listed filegroups,
and every TEST_SRCDIR/IsBazel skip and go-test-only block in them is gone.
The release formula under .bazelignore'd .beads/ comes in through a
@beads_formulas local repository; npm-package/ and .claude/ are visible to
Bazel again (only their node_modules/worktrees stay ignored), so the npm
manifest release check and the AGENTS.md skill links run under Bazel too.
TestZZStdioNotLeaked falls back to TestMain's pre-run streams instead of
skipping in a shard without its baseline.
tools/bazel/equivalence_allowlist.txt shrinks from 20 skip entries to the
two cmd/bd tests of plain go test's own bd build fallback, which Bazel never
takes; pr-preflight-platforms now runs them on Linux, macOS and Windows. The
scripts-go-checks scripts-test and allowlisted legs, their scripts
(scripts-go-test.sh, allowlisted-go-tests.sh, run_allowlisted_go_tests.py)
and main.yml's --compile-only warm for them are removed. The vet leg stays
(ga-96smfk.18).
Refs: ga-96smfk.16
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Makes the repo's agent and contributor surface describe developing beads, not using bd, and requires every PR to link a documented issue.
- Contributor-only root AGENTS.md with a routing table; cmd/bd/AGENTS.md and engdocs/AGENTS.md seam files; CLAUDE.md symlinks so Claude Code loads nested files.
- Bug and feature issue forms, a PR template that requires Closes #, CONTRIBUTING sections for the triage and pipeline labels, and the opt-in fork-cache during dev setup.
- ROADMAP.md for 1.4: versioned beads (#6132), Graph Preview 2 (#7170), contributor onboarding (#7228).
- docsync guards: root AGENTS.md at or under 20 KB; every AGENTS.md symlinked, routed, and with resolving links, paths, and guard-test names.
Agent-Signature: claude-code-claude-opus-5-5-high on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): isolate the bazel test environment like pr-core's go test
Every `bazel test` process now runs under //tools/bazel:test_env (wired with
`test --run_under`), a wrapper that mirrors scripts/ci/lib/test-env.sh: a
private HOME/USERPROFILE, XDG_CONFIG_HOME, DOLT_ROOT_PATH and empty
GIT_CONFIG_GLOBAL, GIT_CONFIG_NOSYSTEM, BEADS_TEST_IGNORE_REPO_CONFIG, and
the same scrub of workspace/Dolt-server variables. Everything lives in one
fresh mktemp directory under /tmp that is removed when the test exits, so
TMPDIR (t.TempDir) stays short enough for unix sockets and is never shared
between concurrent runs.
This replaces `--test_env=HOME` (the client's HOME string entered the action
key and was shipped to remote workers, where it does not exist: the
embeddeddolt suite panicked on "stat /home/ubuntu") and the shared
`--test_tmpdir=/tmp/bbt`. No host path or client env enters the action key.
bd_test (~10 min under -race -short) and embeddeddolt_test (~6 min) get
size = "large" / timeout = "long" instead of Bazel's 300 s default; pr-core
gives go test -timeout=30m. rules_shell (already in the module graph) becomes
a direct dep for sh_binary. MODULE.bazel.lock records the pybind11 extension
that building these test targets evaluates, so `make bazel-sync` is stable.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): inject the bd binary into subprocess tests (slice B3)
Tests that exec bd used to `go build` it themselves, which cannot work under
`bazel test` (no Go toolchain or module tree in the sandbox or on a remote
worker): 135 cmd/bd subtests failed with "go build failed", and protocol,
doctor and uow failed the same way.
- //cmd/bd:bd_for_tests: a go_binary named bd, race = "off" (the non-race
gms_pure_go binary these tests build today, even under --config=prcore).
- bd_test, protocol_test, doctor_test and uow_test declare it as data and set
BEADS_TEST_BD_BINARY to its $(rlocationpath).
- bazeltest.PrebuiltBD is the one resolver: under Bazel it resolves the
rlocationpath through runfiles (via the new bazeltest.RunfileEnv) and
requires it; under plain go test it keeps today's semantics (absolute form
of BEADS_TEST_BD_BINARY, or "" so the caller builds bd).
- cmd/bd's findPrebuiltBDBinary delegates to it, and the sites that read the
variable by hand (init_embedded, shared_server_integration, cli_fast,
migrate front door) now go through findPrebuiltBDBinary; uow calls it
directly.
- Raw `go build` sites that never honored the variable (protocol, doctor
dolt_e2e, test/conformance e2e, internal/beads integration TestMain) use
it only under Bazel, so go test is unchanged; protocol and doctor fail
instead of skipping when the injection is miswired. tests/regression is
left alone (it builds candidate and baseline binaries on purpose).
- The read-only canary still forces a source build under go test; under
Bazel the injected binary is already built from this tree.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): declare what cmd/bd and doctor tests read under bazel
With bd injected, the remaining //cmd/bd:bd_test and //cmd/bd/doctor failures
under `bazel test` were inputs the tests read from the checkout without
declaring them (they were hidden behind the go-build failures before):
- source-scanning guards (capability registry, events-journal construction,
serve database source) parse cmd/bd, cmd/bd/doctor, cmd/bd/doctor/fix and
internal/storage/embeddeddolt/cmd: those packages get go_srcs filegroups
(tools/bazel/go_srcs.py) declared as data; serve_test resolves its package
dir with bazeltest.CallerDir.
- .githooks (managed-section parity) and examples/formulas/primitives are
declared through //:bd_test_files.
- the gofmt preflight tests exec gofmt: under Bazel they use the Go SDK's,
declared as data and named by BEADS_TEST_GOFMT (bazeltest.RunfileEnv).
- TestGOMODCACHENotUnderTestHome guards in-test `go build`, which does not
happen under Bazel, so it skips there.
- doctor's TestCheckDeletionsManifest_LegacyFile only passed because the
process cwd happened to be inside a git checkout; its fixture is now a git
repo and the check runs in it.
go test behavior is unchanged except that the deletions-manifest test no
longer depends on the caller's cwd.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(bazel): give test_env a dolt identity; never fail on cleanup
beads_test_env_enter sets a dolt user.name/user.email in the fresh
DOLT_ROOT_PATH; test_env.sh created it empty, so tests that shell out to
dolt (remotecache, storage/dolt) failed with 'Author identity unknown'.
Write config_global.json directly (no dolt exec per test).
Also keep rm -rf in the EXIT trap from overriding the test's exit status
when a leftover child is still writing to the tmp root.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* build(bazel): re-sync BUILD files with main
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): add internal/testutil/bazeltest runfiles helpers
Repository-path resolution for tests that works identically under plain
go test (package cwd, full checkout), bazel test locally, and remote
execution (declared runfiles only):
- IsBazel, RepoRoot (BEADS_TEST_REPO_ROOT, then the runfiles workspace
root, then a go.mod walk), OverrideRoot (drop-in condition for existing
helpers; empty under plain go test), CallerDir
- Runfile for $(rlocationpath) values, GOROOT for type-checking tests
- ShardFreeEnv for helpers that re-exec a test binary
Every helper reduces to the pre-Bazel behavior under go test.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): declare source/data reads for 14 scan-guard targets
Source-scanning and repo-file tests read files their Bazel targets never
declared, so they failed under `bazel test` (and could not run on remote
workers at all). Declare narrow inputs as `data` and resolve paths through
bazeltest where the test located the tree via runtime.Caller:
- tools/bazel/go_srcs.py (run by `make bazel-sync` after gazelle) keeps a
managed `go_srcs` filegroup in the packages whose Go source tests scan,
plus `//internal/storage:tree_go_srcs` for the storage-tree walk. Bazel
globs stop at package boundaries, so the aggregate needs one filegroup
per package; the script keeps it in sync and gazelle-stable.
- Hand-written narrow inputs: //internal/storage/schema:migrations,
//:docsync_files, //plugins/beads:plugin_files, and exports of
.gitattributes, .claude-plugin/marketplace.json, cmd/bd list.go and
ready.go, testutil/testdoltcommon.go, scripts README.md and the release
catalog, each visible only to its consumer.
- runtime.Caller-based roots in backend, backend/conformance,
internal/storage, internal/formula and test/docsync now go through
bazeltest.CallerDir / OverrideRoot; relative-path tests need data only.
- integrations/ leaves .bazelignore (it is still gazelle-excluded) so the
docsync link check can declare integrations/beads-mcp/PYPI.md.
Under --config=prcore every target reports the same PASS/SKIP/FAIL test
set as `go test -race -short` for its package, locally and remotely.
Plain `go test` behavior is unchanged.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): guard generated go_srcs and harden bazeltest root override
- tools/bazel/go_srcs.py: add --check (print diff, exit 1 on stale blocks);
new `make bazel-sync-check` target runs it.
- scripts/bazel_policy_test.go: under go test, assert every tree_go_srcs
(//internal/storage) lists exactly the BUILD.bazel packages below its
root, run go_srcs.py --check, and forbid BUILD files under docs/ and
engdocs/ (they would cut subtrees out of //:docsync_files).
- bazeltest: honor BEADS_TEST_REPO_ROOT only when it holds go.mod
(RepoRoot fails loudly otherwise); drop the unused GOROOT() helper,
whose compiled-in branch could never fire under rules_go.
- scripts/ci/lib/test-env.sh: unset BEADS_TEST_REPO_ROOT.
- Document the hand-listed out-of-tree link targets in //:docsync_files.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* build(bazel): re-sync BUILD files with main
Regenerated with make bazel-sync after commits that landed while the
scaffold PR was in CI (new internal/execenv, gitenv, gitignore packages
and new sources/deps).
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): declare init_safety_help.go for docsync
TestInitSafetyCLIHelpCoversReCloneGotchas (#6431) reads
cmd/bd/init_safety_help.go; export it to //test/docsync only.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(docs): red — Docs: init-safety re-clone playbook must say damaged stores go OUTSIDE data_dir and a fresh clone needs bd migrate schema (refs be-wv0d0)
* feat: green — Docs: init-safety re-clone playbook must say damaged stores go OUTSIDE data_dir and a fresh clone needs bd migrate schema (refs be-wv0d0)
- docs/recovery/init-safety.md: new re-clone-gotchas section covering both
live gotchas from ga-vrq5pu (damaged/set-aside stores must move OUTSIDE
data_dir; a fresh clone needs `bd migrate schema` for dolt-ignored
clone-local tables), with cross-reference pointers from the two existing
bd bootstrap mentions and a pointer (not a duplication) to bd doctor
--fix's automated corrupt-manifest convention. Freshness markers bumped.
- cmd/bd/init_safety_help.go: RECOVERY section of the init-safety Long help
gets a brief RE-CLONE GOTCHAS addendum with both symptom signatures and
the fix command.
- test/docsync/init_safety_recovery_test.go: retargeted
TestInitSafetyCLIReferenceCoversReCloneGotchas (written during RED) to
TestInitSafetyCLIHelpCoversReCloneGotchas, asserting on
cmd/bd/init_safety_help.go's Long field instead of the generated
docs/cli-reference/init-safety.md. That generated page is pinned to a
released bd (docs/cli-docs.pin = v1.2.2, built in a detached worktree per
scripts/resolve-docs-bd.sh) and does not pick up a Long-field edit at
HEAD until a maintainer bumps the pin at the next release — confirmed
empirically (`git show v1.2.2:cmd/bd/init_safety_help.go` still points at
the deprecated docs/RECOVERY.md path, and a full
./scripts/generate-cli-docs.sh run here produced zero diff to the
committed docs/cli-reference/). CI's own drift gate
(scripts/check-cli-docs-drift.sh) is blame-scoped for exactly this
reason. The original RED test was asserting on an artifact this PR
cannot legitimately change without fighting that pin.
* fix(docs): address review feedback on init-safety re-clone playbook
Three fixes per bee-ghosttrack's REQUEST-CHANGES on PR #6431:
- Correct Gotcha 1's "The fix" paragraph: bd doctor --fix's
corrupt-manifest repair renames the whole data_dir directory to a
sibling .<ts>.corrupt.backup path, not a backup nested inside the
database's own directory. Verified against
cmd/bd/doctor/fix/database_integrity.go and
cmd/bd/doctor/tracked_runtime.go.
- Replace the hardcoded "Schema already at v64" literal with
version-agnostic "Schema already at v<N>" in the doc and CLI help
text, and narrow the docsync test assertion to the prefix "schema
already at v" so it survives future version bumps instead of
rotting again.
- Drop the dead GitHub-issue-style link around ga-vrq5pu (a Gas City
bead id, not a GitHub issue) — keep it as plain text.
Ref: be-hobyw
* review: correct re-clone gotchas and tighten their guards (PR #6431 iters 1-2)
Maintainer review fixup for the adopted PR. This is a docs-only PR whose
entire deliverable is factual accuracy, so every finding here is about a
claim the doc makes rather than about code behaviour.
=== Iteration 1 ===
[major] Gotcha 1's "The fix" paragraph misattributed the automated repair
and pointed an operator mid-crash-loop at a path that cannot run. Verified
first-hand in the worktree:
- internal/doltserver/manifest_recovery.go:231-235 renames
<data_dir>/<db>/.dolt -> <db>/.dolt.<ts>.corrupt.backup, i.e. IN PLACE,
not the whole data_dir to a sibling as the doc claimed. It also only
fires behind nomsDirLooksCorrupt, whose own comment is "recovery only
fires when we can prove there is nothing the user would want to keep"
(:94-100) - so it never touches the superseded-but-populated store the
gotcha is about.
- The whole-data_dir -> sibling rename is a different fix:
cmd/bd/doctor/fix/database_integrity.go:35,43-45 over
getDatabasePath(beadsDir) (validation.go:15-21).
- That fix opens with serverModeIntegrityRecoveryGuard, which refuses
outright in Dolt server mode (:79-96).
Rewritten to state all three facts and to tell the reader plainly that the
move is theirs to make by hand. Kept the correct headline sentence. The
paragraph deliberately does not assert anything about where the in-place
backup lands under the legacy single-database layout (data_dir/.dolt), the
one premise the review left unproven - the wording is scoped to the standard
<data_dir>/<db>/ layout instead of minting a fresh unverified claim.
[minor] Gotcha 2's mechanism sentence ("bd's ordinary open does not recreate
them") is false for embedded mode: newStore -> initSchema (store.go:285,470)
calls schema.MigrateUp (:574), and migrationWorkNeeded returns true whenever
!ignoredSource.atLatest (schema.go:866-867) - and ignored_schema_migrations
is itself in doltIgnorePatterns, so a fresh clone always qualifies. Replaced
the universal with the actual condition. The replacement list of opens that
do NOT self-heal was itself wrong on its first item; see iteration 2 below.
The prescribed remedy was already correct and is unchanged.
[minor] The doc's prose Freshness source list gained cmd/bd/init_safety_help.go
but the enforcing DOCS array did not. Added to both scripts/check-doc-freshness.sh
and the pinned row in scripts/check_doc_freshness_test.go - a coupled pair:
editing only the script reds the pinned test with "Freshness source does not
name cmd/bd/init_safety_help.go" (verified by running exactly that mutation).
[nit] The docsync guard for the headline rule was two independent whole-file
substring checks. Scoped it to Gotcha 1's own section and matched the advice
as a phrase, and pinned both ends of the help text's #re-clone-gotchas
cross-reference, which neither markdown link checker can see because it lives
in a Go string. Five mutation legs, each reddening only its own assertion:
inverting the advice, moving the phrase outside the section, renaming the
heading, breaking the help anchor, and removing the Gotcha 1 heading. The
inversion leg is the one that matters - the file still contained "outside"
(2x) and "data_dir" (13x), so the old form stayed green on inverted advice.
[nit] Bumped Last reviewed: to the revision date.
=== Iteration 2 ===
Both lanes verified all five iteration-1 fixes. Three prose findings remained,
none a merge gate (scorecard: approve, Required Changes: none). All three are
the same defect class - a sentence that quantifies over a set the author did
not census - so each is fixed by removing the quantifier rather than by
restating it more carefully.
[minor] Gotcha 2's replacement enumeration was false on its first item: a
server, shared or proxied open DOES replay the clone-local series in this
doc's own scenario. Re-derived at head, both lanes independently:
- internal/storage/uow/dolt_sql_provider.go:267-287 calls
MigrateUpWithLock UNCONDITIONALLY on the non-team-server, non-preview
arm; p.readOnly is consulted only after a RemoteMigrateGateError comes
back (:288-296), so it cannot suppress the pass.
- The gate cannot refuse a main-current clone: PendingVersions is
mainSource.pendingVersions only (schema.go:525-527) and the gate
early-returns nil on len(pending)==0 (remote_migrate_gate.go:731-737),
so the ignored series is invisible to it.
- migrationWorkNeeded is true whenever !ignoredSource.atLatest
(schema.go:866-869), so the locked pass runs the full MigrateUp
including ignoredSource.migrate (schema.go:822). DoltStore.initSchema
reaches the same call on the writable-open path (dolt/store.go:3076).
So the positive clause is widened to any writable open (embedded, server or
proxied), and the negative clause is rewritten as a tautology plus an open
list: the open that hit the error was not self-healing, and the kinds that
skip or only verify "include" read-only/preview opens, team-server opens
(verifyTeamServerSchema only checks - dolt_sql_provider.go:342-371), the
preview-attach arm, and gate-refused opens. Each named arm was verified
individually; the list deliberately does not claim to be exhaustive, which
is what the previous wording got wrong. Nothing in docsync can enforce this
paragraph, so an open list is also the honest shape.
[minor] Gotcha 1's data_dir locator omitted the mode that overrides both
knobs it names. ResolveDoltDir checks IsSharedServerMode() FIRST and returns
SharedDoltDir() before it ever reaches projectDoltDirPath
(doltserver.go:316-330); the knobs are BEADS_DOLT_SHARED_SERVER=1|true or the
dolt.shared-server config key (:117-122), and the directory is
~/.beads/shared-server/dolt/, overridable via BEADS_SHARED_SERVER_DIR
(:248-257, :275-285). Added as its own paragraph rather than growing the
parenthetical, with the reason it matters most there: one shared data_dir
holds every project's database, so a single stray subdirectory crash-loops
the server for all of them.
[nit] "neither of bd doctor --fix's TWO Dolt-database repairs" made a numeric
claim the sentence does not need, and the count is wrong:
cmd/bd/doctor/fix/repo_fingerprint.go:135-161 os.RemoveAll's
cfg.DatabasePath(beadsDir) behind an interactive "This will DELETE %s. [y/N]",
and cleanCruftBeadsDirFiles (artifacts.go:238) can remove a .beads
subdirectory too when a redirect is expected. Dropping the word "two" would
have left "neither", which is itself a two-quantifier, so the count is
removed instead: "no bd doctor --fix repair performs this move here. The two
that come closest are:" - now a statement about the two bullets that follow,
not a census of the repairs. The operative universal survives the census
(the move-performing rename sites are only database_integrity.go:46,54; the
others delete or rename in place), so the reader's action is unchanged.
Validation (iteration 2): go test -tags=gms_pure_go ./test/docsync (8 tests,
green, zero skips, both InitSafety tests among them); go test -tags=integration
-count=1 -run Freshness ./scripts (33 pass, 1 Windows-only skip);
./scripts/check-doc-freshness.sh PASS with docs/recovery/init-safety.md at 0
days old and all five of its Freshness sources resolving; git diff --check
clean. Prose-only: no code, test or freshness-pair file changed this
iteration.
---------
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
* build(bazel): add side-by-side Bazel scaffold (module + gazelle)
Add a Bzlmod Bazel build alongside the Go toolchain. `go build` and
`go test` are unchanged; nothing in CI invokes Bazel yet.
- MODULE.bazel: rules_go 0.63.0, gazelle 0.53.0, Go SDK 1.26.7 (matches
the go.mod toolchain directive), go_deps from go.mod.
- ICU policy (engdocs/ICU-POLICY.md): a go-mysql-server gazelle_override
selects the pure-Go regex backend and excludes regex_cgo.go, and
.bazelrc builds with --@rules_go//go/config:tags=gms_pure_go, so no
target depends on go-icu-regex or links libicu.
- third_party/patches: three module_override patches for dolt deps that
ship WORKSPACE-era BUILD files, adapted from the gascity project.
- .bazelrc: prcore/ci test configs (inert for now; they match pr-core's
test selection, not yet its environment isolation) and a generic
remote-exec config with a bounded remote timeout. Executor endpoints and
TLS credentials come only from a gitignored .bazelrc.local/user.bazelrc
or a CI rc outside the workspace.
- .bazelversion pins Bazel 9.2.0; .bazelignore skips separate modules,
non-Go trees, nested agent worktrees (.claude, .worktrees) and local
data/output dirs (.beads, .dolt, dist, .runtime, tmp), so a primary
checkout neither builds nor gazelle-rewrites nested worktree copies.
- Gazelle-generated BUILD.bazel files for every Go package.
- Makefile: `make bazel-sync` (gazelle + bazel mod tidy).
- .gitignore: bazel-* output symlinks and machine-local rc files.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): policy tests for the Bazel configuration
Add scripts/bazel_policy_test.go, plain Go tests that run under both
`go test ./scripts` and `bazel test //scripts:scripts_test`:
- MODULE.bazel go_sdk.download version equals the go.mod toolchain.
- ICU policy: .bazelrc sets gms_pure_go for build, the go-mysql-server
gazelle_override excludes regex_cgo.go, and the root BUILD.bazel
carries `# gazelle:build_tags gms_pure_go`.
- .bazelversion pins an exact Bazel release.
- .bazelrc.local and user.bazelrc are gitignored (parsed from .gitignore
and cross-checked with git check-ignore when in a checkout).
- No remote-execution endpoints or credentials in committed bazelrc-like
files, Markdown docs or .github/**: remote/BES/TLS flags
(--remote_executor, --remote_cache, --bes_backend, --remote_header,
--tls_client_certificate, ...) with a literal value, with or without a
URL scheme, and non-loopback gRPC URLs in rc/.github files. Placeholders,
$VARIABLES, and loopback are allowed; Markdown gRPC URLs (OTel exporter
docs) are not flagged. Skipped outside a git checkout, e.g. in the Bazel
sandbox.
Each check is a pure function also exercised against fixtures that break
the invariant. The files the tests read are declared as data via
//:bazel_policy_files so they resolve from runfiles under Bazel.
scripts/check-build-tags.sh now treats Bazel invocations as governed by
.bazelrc: the shell command segment that invokes Bazel (split on &&, ||,
;, |, $( and backticks) is exempt from the per-line `go` tag check, while
a bare `go` in another segment of the same line is still flagged. When
any scanned file invokes Bazel (or .bazelrc exists) .bazelrc must set
--@rules_go//go/config:tags=gms_pure_go for build.
scripts/check_build_tags_test.go covers both in a temp repository.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(scripts): split bazel lines in pure bash so check-build-tags works with BSD sed
BSD sed (macOS) does not expand \n in s/// replacements, so the segment
split never happened and the Bazel-exemption tests failed on macos-latest.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(scripts): skip check-build-tags tests when bash lacks mapfile
macOS runners use /bin/bash 3.2, which has no mapfile; check-build-tags.sh
has always required bash >= 4, so the new tests are skipped there.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Maintainer decision D-7: the ~52k-line exported Go surface added since
v1.2.2 should not freeze as a v1 compatibility commitment at the 1.3.0
tag. backend/ and backend/conformance/ already carried a Stability
section; this adds the matching disclaimer to the other new root-level
exported packages.
Doc comments only, no behavior change.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
The install instructions told users to run the upstream install.sh from
releases/latest, which today resolves to Dolt 2.3.1. Dolt 2.3.0 regressed
CALL DOLT_RESET('--hard'): a few percent of freshly created databases come
up with that procedure answering "Error 1105 (HY000): context canceled" for
the life of the server process. bd flatten and the Dolt-history compaction
in bd admin compact both finish by hard-resetting main onto a temporary
branch, and the merge-settle path behind bd dolt pull falls back to a hard
reset when it abandons a merge — so the documented happy path installed a
Dolt that breaks those operations on a database that otherwise looks fine.
Point the docs at a pinned version instead, with the measurements and the
raise criterion, and tell anyone already on 2.3.x how to check a database
and what to do about it. The pin and its rationale live in
scripts/ci/install-dolt.sh; the docs name the version once, on the Dolt
page, and everything else links there.
Also note that releases/latest resolves to the most recently created
release rather than the highest version, so it can move backwards — v1.88.2
was created after v2.2.4 and v2.3.0 — which makes "install latest" unsafe
independently of this defect.
test/docsync/doltpin_test.go keeps the documented pin, the copy-paste
install snippet and testutil.DoltDockerImage from drifting apart, which is
how the docs ended up on a broken release in the first place.
This documents the pin that gastownhall/beads#5894 applies to CI; land
after it so the reference to scripts/ci/install-dolt.sh resolves.
* test(feat): red — Three TestMains defer TerminateDoltContainer then os.Exit in the same function — teardown is dead code, 101 dolt containers leaked over 6 days and exhausted swap (refs be-5kkk6)
* fix(feat): green — Three TestMains defer TerminateDoltContainer then os.Exit in the same function — teardown is dead code, 101 dolt containers leaked over 6 days and exhausted swap (refs be-5kkk6)
* chore(release-gates): add be-r3ysh gate evaluation (PASS 7/7)
refs be-r3ysh, be-43oyc, be-5kkk6
* feat(search): include closed issues by default (bd-t5yex)
The dominant real-world search query is 'was this already
found/filed/fixed?' — exactly the query where silently excluding closed
issues produces a false 'no'. Downstream repos grew shell wrappers
(wyvern's bd-find.sh) purely to undo the open-only default; when a repo
writes a wrapper to change a default, the default is probably wrong.
Reverses the hq-319 open-only default on both the embedded and
proxied-server paths. bd list keeps its open-only default. --status open
(etc.) narrows explicitly; --status all still works, now redundantly.
No in-repo programmatic caller depends on the old default (prime/skill
docs mention the command generically; docs/cli-reference regenerates
from the release pin). Changelog note added; embedded + proxied search
suites green including new default_includes_closed coverage both paths.
* fix(search): review fixes — conformance corpus spec, page-eviction + bd-query-divergence docs (bd-t5yex)
Fable adversarial review (FIX_THEN_MERGE) items:
- test/conformance corpus: the search-desc-contains-and-status scenario's
comment still documented the old closed-exclusion default (the corpus
comments are the written spec future backends build against), and the
flip left the scenario with two identical steps — comment updated and
one step switched to --status open to keep an explicit exclusion probe.
- CHANGELOG + help: document the page-eviction consequence (matches
beyond --limit are dropped under a status-blind sort; use --status open
or raise --limit when hunting live work) and that bd query / HTTP q=
deliberately keep their closed-exclusion default.
* bd-h3dib.2: move storage conformance suite to public backend/conformance
Relocate internal/storage/conformance to backend/conformance so external
Go modules can import and run the suite against out-of-tree storage
backends (the conformance-gated external-backend path promised on #4415).
Pure move: package name, entry points, and assertions are unchanged; the
seven in-tree test importers are rewritten and path references in doc
comments updated. The package doc now states the external usage and the
experimental stability terms.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* bd-h3dib.2: add public backend package exporting the storage backend contract
The alias facade an external Go module implements a storage backend
against: the engine interface (storage.DoltStorage) and its capability
sub-interfaces, every named type reachable from their method signatures
(measured by type-closure walk: 24 storage types, 36 domain types, plus
the already-public issueops request/response surface), the sentinel
errors and message fragments the contract requires by identity, the
Iter/SliceIter kit, and thin wrappers over the internal/storage/backends
registry. Aliases only - the internal packages remain the source of
truth and no behavior changes.
TestPublicSurfaceComplete is the drift guard: it reflects over the
public contract's type closure and fails if any reachable internal type
lacks an alias here, so a future signature change cannot silently
re-lock the external-backend door. It already caught two types a static
signature scan missed (IssueDetails via issueops.Reader's page results,
PersistenceMode via wisp fields).
Follows the established public-facade convention of the root beads
package and issueops. Stability: documented EXPERIMENTAL.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* bd-h3dib.2: changelog for the public external-backend surface
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* bd-h3dib.2: point the root beads package doc at the backend implementer surface
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Adversarial review of the landed replica-aware lease work (966ddac5a) found
that deriving the granting replica from os.Hostname() answers the wrong
question: the hostname names the CLIENT PROCESS's machine, not the store.
That is a fail-CLOSED regression in three topologies with no federation to
defend against. With a shared or remote dolt sql-server (BEADS_DOLT_SERVER_HOST,
ServerModeExternal, Hosted Dolt, a VPS) many hosts are clients of ONE store, so
a supervisor would match no worker's lease and reclaim 0 forever. In a container
the hostname is a per-run container ID, so a replaced worker's successor sees
its own single-machine leases as foreign. On macOS/DHCP the transient hostname
follows the network. Stranding a lease on a single-store deployment is a worse
failure than the cross-replica reclaim the guard exists to prevent.
So the guard is now OPT-IN: config.NodeID() reads BEADS_NODE_ID / BD_NODE_ID /
node_id in config.yaml and nowhere else, and "" (the default) disarms the guard
back to exactly the pre-feature behavior. This also settles the heartbeat
backfill hazard — on an unnamed deployment the backfill writes '' over '' and
cannot silently convert a fail-open row into a fail-closed one.
Also from the review:
- node_id joins recognizedConfigKeys and YamlOnlyKeys, so the documented
`node_id: mini` mitigation no longer warns and no longer writes to the Dolt
config table that NodeID() never reads (the GH#536 class YamlOnlyKeys exists
to prevent).
- reclaimReplicaSQL/warnReplica/reportForeignSkips move above the
ReclaimExpiredLeasesInTx doc block, which they had orphaned onto a private
helper.
- The --any-replica audit line moves past both re-checks, so it can no longer
log a revert that a post-snapshot heartbeat prevented.
- lease_granted_node joins ephemeralExportKeys in the conformance round trip.
- New cmd/bd/protocol coverage for the JSONL path (RestoreLeaseOnImportInTx),
the sole reason the field is on the wire: a lease claimed under
BEADS_NODE_ID=mini keeps mini after import on laptop, laptop's reaper
declines it, and --any-replica reverts that same row.
- The embeddeddolt test stops claiming its surviving-lease assertion exercises
the DELETE-side guard; inside one transaction that copy is defense in depth.
- A stray U+201D and an inconsistent COALESCE in reportForeignSkips.
Extend #4847's rollback to the last alternative backend: bd now ships a
single storage engine (Dolt, embedded and server mode).
- Delete internal/storage/{sqlite,sqlitedialect} and the packages the
removal orphans: sqlkit (sole importer was the sqlite store),
unsupportedgen (sole go:generate consumer), the NonCommitGraphBackend
marker and its two dead consumer checks, and the domain-db parity test
that used sqlite as its harness. Drop modernc.org/sqlite from go.mod
and regenerate the nix vendorHash.
- Tombstone backend="sqlite" exactly like postgres/mysql: recognized in
metadata (never silently aliased to a fresh Dolt DB), rejected before
any open with its own rationale and the export -> re-init -> import
guidance. The fail-closed guarantee now also covers never creating the
beads.db file the removed backend would have provisioned.
- bd init: --backend=sqlite reaches removed-backend guidance;
--sqlite-path becomes a hidden parser tombstone like the pg/mysql
flags; help text and supported-backend enumerations say Dolt only.
- Doctor: sqlite workspaces fail closed like the other tombstones; the
modern sqlite stub payloads are gone. The legacy pre-Dolt surface
(artifact scans, migration validation, migrate-sqlite-to-current.sh,
the migration-test harness) is untouched; genuine pre-Dolt workspaces
carry no backend field and never hit the tombstone.
- Conformance: drop the sqlite profile; the CLI differential runner
idles (skip, not fail) until another backend profile is registered,
and the export/import round-trip keeps running against the embedded
Dolt reference. Tier-1 oracle legs are unchanged.
Backend selection has never shipped in a release (v1.1.0 predates it),
so released workflows are unaffected and the pinned CLI docs already
describe the resulting behavior.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Released v1.1.0 binaries print
github.com/gastownhall/beads/blob/main/docs/RECOVERY.md#pk-fork-refused in
the Dolt merge-refusal guidance (printAncestorPKMismatchGuidance,
cmd/bd/dolt.go at the tag), and github.com blob paths cannot be redirected —
the URL has 404ed since the docs restructure, at exactly the moment a user
is mid-incident. main's binary already prints the new path; this stub
un-rots the link for binaries already in the wild.
The stub reproduces the old file's section headings verbatim so GitHub
mints the same anchor slugs, and each section forwards to its successor in
docs/recovery/init-safety.md (all four sections map there 1:1). It is
registered in test/docsync's docsPublishExemptions as a deliberate,
documented exception to the no-pointer-stubs rule (decision 6), scoped to
last only while supported releases print the path.
Claims/heartbeats no longer mint dolt commits: lease state (holder,
granted_at, lease_expires_at, heartbeat_at) moves off the issues table
into a leases table registered in dolt_ignore. Migration 0055 +
ignored/0012 move live leases over; all full-issue query sites hydrate
via LEFT JOIN; import never clobbers a live local lease.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Roll back the direct adapters, dialect layers, credential handling, dependencies, CI services, and conformance profiles for general-purpose server databases. That support adds operational and testing complexity at odds with our goal of keeping Beads as simple as possible and consuming as few resources as possible.
Keep the Storage and DoltStorage interfaces unchanged. Embedded Dolt, Dolt server, and SQLite remain supported; the MySQL wire driver remains because Dolt server uses it.
Retain legacy metadata identifiers and hidden init flags only as compatibility tombstones. Removed, unknown, or corrupt backend metadata now fails safely across CLI, SDK, bootstrap, doctor, factories, and Dolt administration before storage is opened or modified, with guidance to export using a supporting build and reinitialize via bd help init-safety.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Test User
- docsmint: all page rewrites (HTML-comment, relative-link, ESM) now skip
fenced code blocks; fence contents render verbatim
- docsmint: spliceCLINav fails closed when the "pages" key found after
"group": "CLI Reference" is not a sibling key of the same object, and
validates the spliced docs.json parses before writing
- docsmint: neutralize MDX ESM hazards in docs/CLI_REFERENCE.md too (bd
emits it without the per-page transforms, but Mintlify serves it as a
hidden page); regenerated docs/CLI_REFERENCE.md accordingly
- help_all: fail loudly when two commands collide on the same doc page ID
instead of letting the later write win; repair a garbled comment
- generate-cli-docs.sh: --check no longer trusts a repo-root ./bd it was
not explicitly given (the CGO guard detects CGO-ness, not staleness)
- docsync: validate the docs.json redirects array (well-formed, no dup
sources, destinations resolve)
- pour: runtime strings match the corrected Long text (Dolt sync, issue
database — not "sync to git" / "persistent in .beads/")
- testdata: formula_help.txt asserts the new docs/workflows/formulas.md path
Per decision 6: the eleven pointer stubs at old top-level docs/ paths are
deleted; the docs.json redirects array now maps every moved page's old
route to its new home (43 entries covering the full pre-port top-level
namespace). The docsync exemption list shrinks to the one generated file
(docs/CLI_REFERENCE.md). Plugin and npm-package quickstart pointers now
link the real in-repo page.
Old GitHub deep links to the deleted paths 404 from here on — accepted in
the decision record; bd's own printed paths are updated to the new
locations in the next commit, so only already-released binaries are
affected.
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.
The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).
Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.
Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).
Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one
canonical concept page (modeled on Gas City's how-gas-city-works):
problem-first framing, the bead -> dependencies -> ready-work loop, hash
IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync,
federation, and storage modes, led by four mermaid diagrams. Other pages
link here instead of re-deriving the model.
- Fact fixes caught while writing (verified against source/live help):
hash IDs are content-derived SHA-256 (internal/types/id_generator.go),
not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real
surface is bd mol pour, bd mol wisp, bd assign, bd update --claim);
wisps are not stored in .beads-wisp/; cross-repo dependency syntax is
external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed
SQLite errors in a Dolt product.
- Section overview pages: rewrite workflows/index, extend recovery,
multi-agent, and integrations indexes to list every child with one-line
summaries; add reference/index and put it in the nav.
- New concept diagrams: sequential-vs-hash ID merge collision
(core-concepts/hash-ids) and embedded-vs-server mode
(architecture/dolt).
- website/README.md: real build/verify instructions and parallel-run
status for the Docusaurus site.
- Repoint example READMEs and page labels at the real quickstart page.
- mint.sh + make docs-dev: local preview of the docs/ Mintlify site
(Node 22 handling modeled on the Gas City wrapper).
- test/docsync: Go guard keeping docs/ and docs.json in exact
correspondence — every nav entry has a file, every page is in the nav
(tiny stub allowlist for paths released bd binaries print), published
pages use root-relative extensionless links that resolve, and engdocs/
plus curated root markdown keep exact GitHub-style paths. Wired into
make check-docs.
- .github/workflows/docs-mintlify.yml: docsync + baseline-aware
mint broken-links check on PRs touching docs/**.
- Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six
mirrored files now live once in the Mintlify site; the committed
Docusaurus mirrors stay frozen so the parallel-run site keeps building.
- Repoint inbound links to moved docs across README, guides, examples,
npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md
pointer stub (bd's agent templates print that path). Runtime strings in
cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print
old paths — covered by stubs, flagged in the PR.
An adversarial fable red-team of the multi-backend PR surfaced 19 findings; the
verified, non-regressing subset is fixed here (two were confirmed intentional and
left as-is with clarified comments).
Dolt-parity (high):
- sqlkit tx AddLabel/RemoveLabel/CloseIssue recorded no audit event, unlike both
Dolt references, so bd label add/remove and bd batch / mol squash close lost
their EventLabel*/EventClosed rows on Postgres/MySQL/SQLite. Delegate to the
same issueops with-event helpers the embedded oracle uses.
- Heartbeat left updated_at stale on Postgres/SQLite (no ON UPDATE trigger;
MySQL/Dolt auto-bump), so bd stale diverged. Stamp updated_at on the heartbeat
UPDATE (claim already stamps it, so no double-assign).
Correctness / hardening:
- postgres/mysql/sqlite stampSchemaVersion: idempotent insert (ON CONFLICT /
INSERT IGNORE / INSERT OR IGNORE) + re-read, so concurrent first provisions do
not fail one opener with a duplicate-key error.
- sqlkit tx SetConfig now syncs custom_statuses/custom_types like the oracle.
- pgdialect INSTR->POSITION leaves the call loud when both args carry a
placeholder, preventing a silent parameter swap.
- creds command runner uses cmd.exe on Windows (sh is POSIX-only).
- Dolt gateway credential command is gated on the Dolt backend, not just
shared-server mode (was failing closed for SQL workspaces).
- Scrub pg/mysql URL passwords from the bd.args telemetry span.
Conformance rigor:
- E2E normalize() maps zero/epoch timestamps to <ZERO-TS> so a lost timestamp no
longer reads as byte-identical to a real one.
- E2E logs its candidate set and honors BEADS_CONFORMANCE_REQUIRE so a
sqlite-only run cannot masquerade as full coverage.
Docs/hygiene:
- Scrub dev-machine paths (/data/tmp/pg-recon, proposal_2.md, "proof-wedge") from
the Postgres schema DDL comment; clarify the SQLite timestamp comment.
Deliberately not changed (would regress): sqlkit UpdateIssue uses the without-event
variant to MATCH dolt-server (only embedded differs); sub-second timestamp
precision is an intentional per-backend waiver (whole-second round-trip is the
portable contract) — forcing round-down would discard PG/SQLite fidelity.
Verified: embedded + postgres + mysql + sqlite + server-dolt TestConformance and
the pg/mysql/sqlite E2E differential all pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fixing the Tier-1 reconcile ambiguity unmasked a Tier-2 (TestConformanceE2E)
failure previously hidden behind the aborted Tier-1 run: on CI the SQL candidate
backends print the "beads.role not configured (GH#2950)" nudge to stderr while
the dolt-embedded reference does not, so 8 scenarios diverged on that warning
alone (stdout byte-identical on all three backends).
The nudge fires from git-config state (unset beads.role) that differs on the CI
runner vs a dev box — it does not fire locally — so it is cross-env noise, not a
storage divergence. Strip it in normalize() exactly as the random tip banner
already is; the strip runs on both reference and candidate and preserves any
genuine error line that precedes it.
Verified: full TestConformanceE2E passes locally against pg + mysql + sqlite
candidates (231s); the regex strips the exact 3-line nudge while keeping real
error lines.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rebase of PR #4601 (feat/choose-your-own-backend) onto current origin/main,
squashed to a single commit because the original 73-commit history built and then
removed the uowStore derisk spike incrementally, which does not replay cleanly
over the 125 commits main has since advanced (notably #4679, the ready-work
counts fix, which merged to main and is now inherited rather than re-applied).
The full pre-rebase history remains on the original branch tip for reference.
Contents (multi-backend feature + the six review follow-ups):
- bd init --backend=postgres|mysql|sqlite provisioning behind the Dolt-parity
seam; the three SQL backends share *sqlkit.Store over pluggable dialects and
carry a generated typed-unsupported shell for the non-core surface.
- Passwords in init DSNs are redacted before persisting to metadata.json (driver
parser + re-parse verification), with a negative-test matrix proving no secret
survives (pgdialect + mysql).
- The uowStore derisk spike and its report artifacts are removed; the shell
generator now lives in internal/storage/unsupportedgen (neutral name).
- Compile-time guard `var _ storage.DoltStorage = (*Store)(nil)` on each backend
plus a regen-idempotence test keep the generated skip lists honest.
- sqlkit exposes CountReadyWork so every SQL backend satisfies
storage.ReadyWorkCounter and inherits the shared page-pushed ready-counts path.
- Commercial/product names scrubbed from the feature's own code for vendor
neutrality.
Rebase reconciliations: adopted main's metadata-load hardening in the store
factories alongside the backend dispatch; combined the config interface
(GetMetadata + ReconcileVersion) and the conformance registrations (ReadyCounts +
Claim/lease); took main's versions of the shared-infra concurrency (uow
doltserver_tx) and delete-cascade (domain/issue_delete) evolutions; implemented
the interface's new UnclaimIssue on sqlkit (delegating to issueops) and added it
to the skip lists.
Verified: go build (cgo + CGO_ENABLED=0) and go vet clean; unit tests
(sqlbuild/issueops/pgdialect/mysql/unsupportedgen) and the SQLite conformance
suite green (RunAll, incl. ReadyCounts equivalence and Claim/lease on the real
sqlkit backend).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>