Beads - A memory upgrade for your coding agent https://beads.gascity.com
  • Go 95.2%
  • Python 1.6%
  • Starlark 1.5%
  • Shell 1.3%
  • Rust 0.2%
Find a file
Jim Wordelman 5c9c02ab77
Phase 3 (R20): epoch-transition enforcement + minted-address CAS - gastownhall/beads#6136 (#6664)
* test(conformance): un-skip R16 CAS + R20 epoch tests with honest not-implemented stubs

Wires all 10 ExpectedRevisionFixture-gated Run* functions and both
EpochFixture-gated Run* functions to real (non-nil) hooks on all three
storage legs (dolt, embeddeddolt, uow), replacing the Phase 0 all-nil
fixtures that made these cases t.Skip.

Every wired hook is an unconditional "not implemented yet" stub rather
than a partial-real implementation. This is deliberate: every Run*
function under test calls its primary hook (CompareAndSetVersion, or
CurrentEpoch/MintUnderEpoch) first, before any other hook, so a stub
that errors unconditionally on that first call guarantees deterministic
RED with zero risk of an accidental pass -- a concern that's concrete,
not hypothetical, since at least one case
(RunExpectedRevisionAcceptsAWriteNamingNoVersion) would go green under
a partially-real read/unconditional-write strategy backed by Phase 1's
already-persisted current_revision/store_epoch columns.

Each case now fails for its documented reason: most via a direct
t.Fatalf quoting the stub's "not implemented" error, and two
(RefusalIsDistinguishableFromNotFound,
RefusalIsDistinguishableFromValidationFailure) via a clean want/got
mismatch against the sentinel errors they expect.

Explicitly out of scope and untouched: CrossRecordInvariantFixture
(R16.1) and the non-epoch RetentionFixture cases (R17) -- confirmed via
test run that TestRetentionContract still reports PASS with all 13
subtests SKIP on every leg.

TestEveryLegWiresEveryRoleContract (internal/storage/leg_contract_wiring_test.go)
is a source-level AST naming check independent of hook nil-ness; all 12
entrypoints were already called by every leg pre-change, so this lock
was satisfied before and remains satisfied after.

Sentinel error messages reference be-x5jqd.3 (R16 CAS implementation)
and be-x5jqd.4 (R20 epoch enforcement implementation), the two builder
children this un-skip unblocks.

Verified via go build ./..., go vet ./..., and go test -tags cgo across
all three legs: all 10 R16 + 2 R20 subtests FAIL for the documented
reason, TestRetentionContract unaffected.

Bead: be-x5jqd.1

* feat: green — Implement R20 epoch-transition enforcement (refs be-x5jqd.4)

* fix(epoch): honor R20-n's retained-mapping exception in StillServes/Resolve

StillServesInTx and ResolveEpochInTx only ever checked whether the
literal queried address's own row matched the current epoch. Per R20-n
(#5898 rev 9), a version that survives an epoch transition keeps its
prior-epoch address resolving once its id has been carried forward into
the current epoch (via CurrentAddressForInTx or a fresh
MintUnderEpochInTx) — that carried-forward row wasn't being consulted,
so a legitimately retained address would wrongly stop resolving.

Add mintedIDHasAddressAtEpochInTx and consult it as a fallback in both
functions when the queried address's own row is stale. Addresses whose
id was never carried forward are unaffected (row.mintedID has no row
at the current epoch, same false/GoneReorganization answer as before).

Round-2 response to be-rskwc's causal_disproof finding: the merge-base
commit FAILed honestly on this defect, this branch's tdd_green SKIPped
instead (attribution_evidence). This fix is real and verified via a new
sqlmock unit test (TestStillServesInTxHonorsARetainedMapping et al.),
but does not by itself flip
TestEpochContract/EpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed
from SKIP to PASS: that test's own construction mints two records
identically and never carries either forward before comparing
StillServes on both, so no backend implementation can make them differ
(escalation follows on a needs-mayor bead).

refs be-x5jqd.4, be-rskwc round 2

* test(feat): red — harden EpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed (refs be-9fiaw)

Per mayor ruling on be-9fiaw: fix the test rather than waive it. The
fixture already lets record-a survive an epoch bump by minting it again
under the new epoch; record-b, never re-minted, does not survive. That
asymmetry was previously only discovered after the fact (skip if
StillServes agreed for both addresses), which meant the case could pass
by observing either polarity. Assert the concrete expected values
instead: servesA must be true, servesB must be false. This makes the
case deterministically exercise both halves of R20-n, and closes a
latent gap where a backend with the polarity reversed could have
silently passed via the old discover-then-swap logic.

* fix(schema): renumber epoch_minted_addresses to 0070, linearizing our own slot collision (refs be-hs42e.7)

R20's epoch_minted_addresses and R7.1's removed_restriction both claimed
migration slot 0069 on parallel sibling branches. Neither contained the
other, so nothing in either branch's own CI could see the union: each was
green alone, and the second to merge would panic checkNoDuplicateVersions at
store open -- before any command's RunE, so every bd invocation bricks rather
than one package reddening. Same hazard bee reproduced for #6358 vs #6008.

This linearizes them instead of leaving it to merge order. R7.1 keeps 0069:
it is published beneath #6661 and cannot move without rewriting a branch a
reviewer is reading. R20 stops being a sibling, rebases onto R7.1, and takes
the next contiguous slot.

Contiguity is why the renumber could not be done pre-emptively in either
branch alone: TestAllMigrationsSQLAppliesThroughDoltCLIAndRecordsLatestVersion
asserts COUNT(*) == LatestVersion(), so a jump to a far slot fails until the
gap is filled. The order had to be settled first.

- migrations/0069_add_epoch_minted_addresses.{up,down}.sql -> 0070_*
- migration_0069_add_epoch_minted_addresses_test.go -> migration_0070_*, with
  TestLatestVersionIncludesMigration0069 -> ...0070 (want 70)
- 0069_add_removed_restriction_test.go retires its own LatestVersion pin in
  favour of 0070's, keeping the one-pin-at-a-time chain 0068 -> 0069 -> 0070

cli_migrations.go needs no change: its only override is R7.1's guarded
PREPARE, which keeps 0069. The epoch migration is a plain unguarded
CREATE TABLE IF NOT EXISTS and needs none.

Verified: TestEmbeddedMigrationSourcesHaveNoDuplicateVersions,
TestLatestVersionIncludesMigration0070,
TestAllMigrationsSQLAppliesThroughDoltCLIAndRecordsLatestVersion (applies the
full 0001..0070 chain through the dolt CLI),
TestBundleMigrationsWithPreparedALTERAreOverriddenOrJustified and
TestAllMigrationsSQLUsesDirectDDLForKnownCLIIncompatibilities all pass.
go build ./... and go vet ./... clean.

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

* test(feat): red — Fix PR #6664: restore R16 honest-skip (stale be-x5jqd.3 premise) + address bee's 2 blockers on epoch_cas.go (refs be-ah0jf)

* feat: green — Fix PR #6664: restore R16 honest-skip (stale be-x5jqd.3 premise) + address bee's 2 blockers on epoch_cas.go (refs be-ah0jf)

* test(feat): red — Review: Fix PR #6664: restore R16 honest-skip (stale be-x5jqd.3 premise) + address bee's 2 blockers on epoch_cas.go (refs be-yj55d)

* feat: green — Review: Fix PR #6664: restore R16 honest-skip (stale be-x5jqd.3 premise) + address bee's 2 blockers on epoch_cas.go (refs be-yj55d)

* docs(epoch): cite epoch_minted_addresses as migration 0071

Upstream's 0069_widen_issue_versions_datetime_precision (#6675) took slot
0069 first, so removed_restriction moved to 0070 and epoch_minted_addresses
to 0071. The three epoch_cas.go headers still named 0070.

Rebase note (maintainer): the migration is now 0072, per the landing-order
ruling (#6943's participation_generation is 0070 and #6661's
removed_restriction is 0071); the commit "chore(schema): renumber
epoch_minted_addresses to 0072 after #6661's 0071" updates these three
headers.

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

* test(feat): red — move #6664's Dolt server leg to post-transaction publish for store_epoch and epoch_minted_addresses (latent lost-update pattern)

Tests only. On the commit before this one they fail for these reasons:

- the server leg publishes store_epoch / epoch_minted_addresses inside the open
  SQL transaction (DOLT_ADD before COMMIT) for BumpEpoch, MintUnderEpoch and
  CurrentAddressFor: the lost-update hazard documented on doltAddAndCommitInTx
- MintUnderEpoch and CurrentAddressFor stage only epoch_minted_addresses, so the
  first mint leaves store_epoch modified in the working set, on both legs
  (#6664 Major 2, reproduced with Status() on a real server and embedded)
- BumpEpoch must surface a Dolt commit that fails after its SQL commit, while
  the mint paths keep their rows
- ensureStoreEpochRow seeds with INSERT IGNORE and reads the row back

TestMintOverlappingABumpCommitsAnAddressThatIsAlreadyGone characterizes current
behaviour and passes now: a mint overlapping a bump commits an address the bump
already voided. Its doc comment records why that is left as it is.

* feat: green — move #6664's Dolt server leg to post-transaction publish for store_epoch and epoch_minted_addresses (latent lost-update pattern)

Server leg (internal/storage/dolt/epoch_cas.go): BumpEpoch, MintUnderEpoch and
CurrentAddressFor no longer stage and Dolt-commit inside the open SQL
transaction. The two mint paths publish through runIssueOperationTxWithMessage,
which commits the SQL transaction first. BumpEpoch commits it, then publishes
with doltAddAndCommitPostTx and RETURNS a failed Dolt commit: a bump that is
committed but unpublished must not read as success.

Both legs: a mint stages store_epoch with epoch_minted_addresses, because the
first mint inserts the singleton row (#6664 Major 2). The set lives in
issueops.EpochMintDirtyTables so the legs cannot drift from what the body writes.

issueops: ensureStoreEpochRow seeds with INSERT IGNORE and reads the row back,
as version_history.go does for the same row.

Not changed, on purpose: a mint overlapping a concurrent bump can still commit an
address the bump already voided. Dolt has no lock for it and the only conflicting
write would overwrite bumped_at/bumped_reason; see the doc comment on
TestMintOverlappingABumpCommitsAnAddressThatIsAlreadyGone. One comment in that
test file is reworded; no test logic changed since the red commit.

* chore(bazel): bazel-sync (gazelle) for the two new epoch test files

Only the two go_test srcs entries for the test files this branch adds:
epoch_cas_publish_test.go (dolt) and epoch_cas_status_test.go (embeddeddolt).
gazelle wanted nothing else for them (no deps change).

* test(conformance): add the optional EpochFixture.LoseVersion capability

Record survival explicitly instead of inferring it (gastownhall/beads#6664,
review 5360880888, Major 1). Once an address stays served unless its own row
says the store lost it, the only way for the contract to produce a Gone
address is an explicit loss, so the contract needs a way to say "the store
lost this Version".

LoseVersion is additive and optional: no existing field changes signature,
and a nil LoseVersion makes the cases that need one skip with a named reason.
It is its own commit so that it can be judged, or replaced, on its own: the
same semantics could ride on BumpEpoch taking a lost set, and only the
plumbing would differ. Nothing uses it yet.

* chore(epoch): add signature-only stubs for the survival rework

The tests that follow exercise BumpEpochCarryingInTx, LoseVersionInTx,
ErrEpochAddressNotServed and the BumpEpochCarrying and LoseVersion store
methods (gastownhall/beads#6664, review 5360880888). Stubs give those names
so the tree builds and the tests fail for their real, behavioural reasons
instead of failing to compile.

No logic: ErrEpochAddressNotServed is a sentinel, BumpEpochCarrying advances
the counter exactly as BumpEpoch does and carries nothing, and LoseVersion
returns "not implemented". The next commit adds the tests; the one after
replaces these bodies.

* test(feat): red — record survival explicitly in epoch_minted_addresses, make CurrentAddressFor read-only, carry on a token-scheme change

Tests for the survival rework of gastownhall/beads#6664 (review 5360880888:
Major 1, Minors 3 and 4). Every test is written before any production change.

- Contract: the earlier mint-driven R20-n case is restated as three named
  phases (a survivor and a lost Version, loss is terminal, survival needs no
  upkeep), plus three new cases for a token-scheme change (carry the live
  lineages and only those, a carried address keeps resolving across later
  bumps, a lost address stays Gone across a scheme change). All three legs
  register them and wire LoseVersion and the carrying bump.
- Shared body: unit tests for the row-based resolver (exactly the address's
  row and the epoch, fail closed on a row from a future epoch), a read-only
  CurrentAddressFor with typed errors, LoseVersion, a bump that writes only
  store_epoch, a mint that never hands back a lost address, and the
  per-database counter (Minor 3). Minor 4 gets a guard that no address in the
  test file is written by hand.
- Real engine: the carry on the embedded leg (one carry row per live id, the
  lineage root, the collision rule, a row from a future epoch, a rewound
  counter, database-wide, lost lineages), the publication sets of every
  writer, and on the server leg the overlap of a mint with a bump (now a Live
  survivor) and a deterministic mint-after-loss interleaving that must not
  revive the lost address.
- Migration 0071 byte pin and a real-dolt shape check for carried_from,
  gone_at_epoch, the carried_from index and the gone-not-before-mint CHECK.

These fail on the current code, and some do not build yet because
BumpEpochCarryingInTx, LoseVersionInTx, ErrEpochAddressNotServed and the store
methods they exercise do not exist.

* feat: green — record survival explicitly in epoch_minted_addresses, make CurrentAddressFor read-only, carry on a token-scheme change

The survival rework of gastownhall/beads#6664 (review 5360880888: Major 1,
Minors 3 and 4). An address's status is now a function of its own row and the
current epoch, never inferred from other rows.

- Migration 0071 (edited in place; no new slot, no ALTER): the table gains
  carried_from, gone_at_epoch, an index on carried_from and a CHECK that a loss
  epoch is not before the mint epoch.
- Shared body: Live unless gone_at_epoch is set, and a row from an epoch that
  has not happened yet fails closed; the chain query is deleted. CurrentAddressFor
  only reads and returns typed errors. LoseVersion marks a whole lineage lost,
  once, guarded by gone_at_epoch IS NULL. BumpEpochCarrying (token-scheme change)
  writes one carry row per live lineage naming the lineage root, resolves a
  shared-id collision by carrying the newest and losing the rest, and fails if a
  row already sits at the new epoch. A mint only inserts its own root row and
  never hands back an address that is not served. A restore or reinit bump
  still writes only store_epoch.
- Both Dolt legs: BumpEpochCarrying publishes store_epoch and
  epoch_minted_addresses, LoseVersion publishes epoch_minted_addresses and
  returns a failed publication, and CurrentAddressFor runs on the read path and
  publishes nothing. The per-database epoch counter (Minor 3) and the
  requirement that a caller of the carrying bump hold the workspace gate
  exclusively are documented where they apply.

One change to tests written in the previous commit: the three real-server
publication probes that only need a clean working set now open a database of
their own, as the overlap tests do, instead of queueing on the shared test
database's schema-init lock. Its five-second acquire timeout ran out under load
and failed two of them; no assertion changed.

* test(dolt): run the epoch contract on a database of its own

TestEpochContract set up through setupTestStore, which puts every parallel
test on the shared test database and queues their schema initialization on one
lock with a five-second acquire timeout. Under host load a setup that waits
behind another parallel test's runs out of it and fails at its first line with
"schema migration lock unavailable: timeout". That failed the unchanged
first-mint test twice in the dolt lane once this change had added tests to it,
and the contract's own setup is exposed to the same timeout.

The contract now opens a database of its own, the way the overlap tests and the
publication probes already do, so this change adds no contention on the shared
database's lock. No assertion changed.

* docs: replace internal tracker ids in the epoch comments and test names with plain descriptions

Comment and text edits only; no behavior changes and no line is added or
removed (21 lines are replaced one for one). Each replaced line named an
internal tracker id in a header, a test comment, a failure message or the
migration header; it now says what it meant in plain words or cites the
upstream issue or pull request. The EpochFixture API lines and the already
published commit messages are left as they were.

* ci: list this PR's embedded storage tests in the embedded shard manifest

#7156 made the embedded-Dolt tier's shard manifests exact-once (50 cmd
shards, 15 storage shards), so every embedded test must be listed. This PR
adds eleven embedded storage tests and no embedded cmd tests; this commit is
exactly what the generators write for them:

  python3 scripts/ci/gen_embedded_cmd_shard_manifest.py 50 --weights=duration --write
  python3 scripts/ci/gen_embedded_storage_shard_manifest.py 15 --weights=duration --write

Incremental: 11 lines added, none moved; the cmd manifest is unchanged.

Rebase note (maintainer): regenerated on current main, whose embedded storage
manifest uses a 40-shard block; the generator's incremental output placed
these tests at shards 7, 9, 11, 20, 21, 28, 31, 32, 33, 34 and 36 of 40, one
test per shard (gen_embedded_storage_shard_manifest.py 40 --weights=duration
--write; --check passes).

* chore(bazel): bazel-sync for the epoch sources and migration 0071

The BUILD files did not list epoch_cas.go in the dolt, embeddeddolt and
issueops libraries, issueops' epoch_cas_test.go, or migration 0071 and its
test, so Bazel could not compile those packages' tests. This is exactly the
patch make bazel-sync writes (gazelle plus go_srcs.py; the PR's BUILD-sync
CI step printed it): 4 files, 6 lines, nothing else.

Rebase note (maintainer): the migration is now 0072, per the landing-order
ruling (#6943's participation_generation is 0070 and #6661's
removed_restriction is 0071); the commit "chore(schema): renumber
epoch_minted_addresses to 0072 after #6661's 0071" renames these BUILD
entries. On the rebased base, this commit's internal/storage/schema/BUILD.bazel
hunk is merged with the base's 0070 and 0071 entries.

* chore(schema): renumber epoch_minted_addresses to 0072 after #6661's 0071

Migrations are numbered by landing order. #6943 (participation_generation,
the versioned-history write fence) owns main-plane 0070 and #6661
(removed_restriction) owns 0071, so this PR's epoch_minted_addresses
migration moves to the next free slot, 0072. The rename is done here, as one
maintainer commit, rather than inside the replayed commits, so the history
shows exactly what changed relative to the PR as reviewed.

- migrations/0071_add_epoch_minted_addresses.{up,down}.sql become 0072_*.
  Neither header names its own number, so the SQL and its comments are
  unchanged. Neither file exists on main, #6943 or #6661, so this is not an
  edit to a shipped migration.
- cli_migrations.go needs nothing: the migration is a plain CREATE TABLE IF
  NOT EXISTS with no CLI-bundle override.
- migration_0071_add_epoch_minted_addresses_test.go becomes
  migration_0072_add_epoch_minted_addresses_test.go; its consts, tests and
  messages say 0072, it owns the one LatestVersion pin (72), and its slot
  history now records the move past #6943's 0070.
  TestLatestVersionIncludesMigration0071 in #6661's removed_restriction test
  was already retired to a pointer comment by the rebase's resolution of
  "renumber epoch_minted_addresses to 0070"; that comment now names
  TestLatestVersionIncludesMigration0072 and its file.
- BUILD.bazel embedsrcs/srcs, and the three epoch_cas.go headers (dolt,
  embeddeddolt, issueops) that cite the migration number.

The intermediate commits of the rebase are not expected to build, for two
reasons:

- a duplicate migration version: the PR's epoch_minted_addresses migration
  shares 0069 with main's 0069_widen_issue_versions_datetime_precision until
  the PR's own "renumber epoch_minted_addresses to 0070", and from there
  shares 0071 with #6661's removed_restriction until this commit;
- a helper-name collision: from the PR's "feat: green — Fix PR #6664: restore
  R16 honest-skip ... (refs be-ah0jf)" on, internal/storage/issueops declares
  readStoreEpochInTx twice, once in #6943's version_history.go and once in
  this PR's epoch_cas.go, until "fix(epoch): rename #6664's read-only
  store_epoch read past #6943's readStoreEpochInTx" later in this stack.

This commit ends the duplicate version, but it still does not compile on its
own because of the collision; the stack builds from the rename commit on.

Checked at the tip of the stack, where the rename has landed: go test
./internal/storage/schema/... with the dolt CLI lane
(including TestAllMigrationsSQLAppliesThroughDoltCLIAndRecordsLatestVersion
and TestMigration0072RecordsSurvivalInTheAddressTableThroughDoltCLI), and
scripts/check-migration-hygiene.sh with BASE_SHA=origin/main and
BASE_SHA=vh/6661-rebase.

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

* test(epoch): waive #6664's three new epoch contracts on main's http leg

main gained an HTTP storage leg (#7247) after this PR's base, and
TestEveryLegWiresEveryRoleContract requires every leg to name or waive every
role contract. This PR adds three EpochFixture cases
(RunTokenSchemeChangeCarriesLiveAddressesAndOnlyThose,
RunACarriedAddressKeepsResolvingAcrossLaterBumps and
RunALostAddressStaysGoneAcrossASchemeChange); dolt, embeddeddolt and uow wire
them, and the http leg did not name them.

They are waived on the http leg with the existing
retentionEpochNoRoleWaiverReason, which already covers every other
RetentionFixture/EpochFixture case there: EpochFixture is raw storage hooks
(CurrentEpoch, BumpEpoch, MintUnderEpoch, StillServes, Resolve,
CurrentAddressFor, LoseVersion) with no publicops role behind them,
and internal/httpclient is a remote client with no epoch counter or address
table of its own. The constant's doc comment now counts eighteen cases.

Test-only; no production code changes. After this, the http leg's only
unnamed entrypoints are #6943's seven RunParticipationGeneration* contracts,
whose waivers belong to #6943.

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

* fix(epoch): rename #6664's read-only store_epoch read past #6943's readStoreEpochInTx

#6943's "a create stamps participation even when the row is flagged
no-history" (7c00d65fa6) adds readStoreEpochInTx to version_history.go: the
mint's read of store_epoch, which SEEDS the singleton row when it is absent.
This PR's epoch_cas.go already declared a readStoreEpochInTx of its own, so
the package stopped compiling once #6664 was stacked on that commit.

The two cannot be folded into one. This PR's helper is deliberately
read-only: an absent row answers epoch 1 without writing, so
CurrentEpochInTx, StillServesInTx, ResolveEpochInTx, CurrentAddressForInTx and
LoseVersionInTx never write from a read (review item B4, pinned by
TestCurrentAddressForNeverReseedsAnAbsentStoreEpochRow and
TestCurrentAddressForWritesAndPublishesNothing). Calling #6943's seeding read
from those paths would break that.

So #6664's helper becomes readStoreEpochWithoutSeedingInTx, and its doc
comment says why it is not readStoreEpochInTx. The five call sites and the
ensureStoreEpochRow comment that names it follow. No behavior changes on
either side: #6943's mint path keeps its seeding read, and this PR's read-only
paths keep theirs. (ensureStoreEpochRow, which BumpEpochInTx and
MintUnderEpochInTx use, now has the same body as #6943's readStoreEpochInTx;
it is left as it is rather than folded in here.)

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

* test(storage): say exactly why the retention and epoch contracts stay waived on http

All but four of the participation-generation contracts (#6943's write
fence) now run over the served wire
(internal/httpclient/served_participation_generation_test.go): their subject
is a create or an update, which the client can send, and the fixture reads
the reference store's raw columns. The four stay waived, because the
mutation each needs has no form on the wire. This checked whether the
eighteen RetentionFixture/EpochFixture cases waived on the http leg,
including the three this PR adds, can be wired the same way. They cannot,
cheaply or otherwise, without a new wire operation:

- every EpochFixture hook (CurrentEpoch, BumpEpoch, MintUnderEpoch,
  StillServes, Resolve, CurrentAddressFor, LoseVersion) is the operation
  under test, not a seed or a raw read. Those operations are methods on the
  concrete *DoltStore and *EmbeddedDoltStore over issueops' *InTx bodies, on
  no storage interface, no publicops role and no wire operation. Every call
  path into them starts in a test: the methods are called only from each
  store leg's own _test.go files (its EpochFixture, which the conformance
  contracts drive, and its epoch tests), and the *InTx bodies only from those
  methods, from each other and from tests (the uow leg's fixture through a
  test-only type assertion, and issueops' and the dolt leg's own tests). No
  command, role or server handler reaches them, so no client mutation
  touches epoch state either;
- RetentionFixture's hooks (Resolve, Remove, Hold, ForceRemove, Erase, Mint)
  are implemented by no backend yet (every store leg wires them nil and its
  cases skip), and the wire has no removal, hold, erasure or gone/unknown
  resolve to bind them to.

Binding the epoch hooks to the reference store behind the served env would
pass, but as a property of that store, which the store legs already pin,
never of the client. So the waivers stay; retentionEpochNoRoleWaiverReason's
comment and reason string now say the above, in the shape #6661 gave
asOfReadNoHTTPWireWaiverReason, instead of the earlier general "raw storage
hooks with no publicops role" wording.

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

* fix(epoch): report applied-but-unpublished epoch writes as indeterminate, bound address length, verify dup-key mints

Maintainer fixup for the #6664 review (adopt-pr attempt 1, iteration 1).

Major 1, applied writes reported as failed. An epoch writer whose SQL
commit has landed, or may have, now wraps storage.ErrCommitIndeterminate
on both legs and hands back what it applied, so nothing replays a bump
that has already advanced the counter:
- embedded BumpEpoch and BumpEpochCarrying return the new epoch with the
  error (failedBump), and MintUnderEpoch its address;
- server bumps wrap the sentinel on every Dolt failure after the SQL
  commit, including a failed staged-set read (unpublishedBump), and so
  does LoseVersion; an indeterminate SQL commit returns the epoch or
  address it may have committed, and a definite (typed MySQL) commit
  error returns neither.
Tests: TestEpochWritesReportAnUnpublishedCommitAsIndeterminate (new,
embedded, through an afterSQLCommit seam in runTransactionWithMessage);
on the server leg TestEpochWritesMarkAFailedStagedReadIndeterminate,
TestEpochWritesReturnWhatAnIndeterminateSQLCommitMayHaveApplied and
TestEpochWritesReturnNothingWhenTheSQLCommitFailsDefinitely, and the
sentinel asserted in every publication-failure test.

Major 2, address overflow. MintUnderEpochInTx refuses a pair whose
address would outgrow epoch_minted_addresses.address (VARCHAR(255)) at
the widest epoch the counter can reach, with a typed
ErrEpochAddressTooLong, so a carry can never fail on a lineage that
gained an epoch digit.

Major 3, duplicate-key mint. A duplicate key from the mint's INSERT is
no longer success: the row is read again and the mint stands only if
this transaction sees it served; a Gone row fails the mint with
ErrEpochAddressNotServed, an unreadable one with the duplicate-key
error. Measured on dolt-sql-server 2.2.0, the stale-snapshot INSERT does
not report a duplicate key at all: its COMMIT fails with Error 1213 and
the retried mint answers ErrEpochAddressNotServed
(TestAMintRacingTheMintAndLossOfItsAddressConflictsAtCommit).

Minors:
- absent store_epoch row: sqlmock cases pin that CurrentEpoch,
  StillServes, Resolve, CurrentAddressFor and LoseVersion never seed it;
  switching any of the five to the seeding reader now fails the test;
- the server publication tests mint their address instead of writing it
  by hand, and TestEpochCASTestsBuildEveryAddressWithEpochAddress scans
  that file too (issueops_test gains //internal/storage/dolt:go_srcs as
  data);
- stale text: the duplicate-key and carry comments, the issueops
  header's CompareAndSetVersionInTx citation, the embedded header's
  parity claim, and the 0072 header's "upserts the same row" (0072 is
  past the frozen floor).

Declined, for the owner:
- a scheme-change carry voids an older live lineage re-minted after a
  restore: rule (a), document and pin it, or rule (b), resolve the loser
  to the winner's carry, is a design call about R20-n, not a review fix;
- the uow epoch fixtures' in-transaction DOLT_COMMIT('-Am'): test-only
  fixtures with no production caller; routing them through RunTxScoped
  is follow-up work.

Validation: go build ./...; go vet; nogo (bazel --config=nogo) on
issueops, dolt and embeddeddolt; issueops epoch tests; the dolt epoch
tests against a real dolt-sql-server (56 pass) and the fake-backed
publication tests; embedded epoch tests with BEADS_TEST_EMBEDDED_DOLT=1;
uow epoch contract; the schema package; the address guard under bazel
in the local sandbox. All 14 overlay mutants of the fixes are killed.

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: Jim Wordelman <mayor@quad341.uk>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
2026-10-18 21:20:57 +00:00
.agent/workflows docs: replace bd sync with bd dolt push/pull in agent instructions (GH#2563) 2026-03-13 11:01:06 -07:00
.beads/formulas release: prep v1.3.0 — version bump, changelog rollup, release process docs, formula fixes (#6038) 2026-08-30 22:19:35 -07:00
.claude docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
.claude-plugin release: make release/1.3.0 tag-ready — revert #6281, stamp 1.3.0, date the changelog (#6564) 2026-09-15 12:13:59 -07:00
.devcontainer docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
.githooks fix(hooks): key the push-time suite on the remote ref, never on the local ref's shape (#7352) 2026-10-08 07:49:57 +00:00
.github Phase 3 (R20): epoch-transition enforcement + minted-address CAS - gastownhall/beads#6136 (#6664) 2026-10-18 21:20:57 +00:00
backend Phase 3 (R20): epoch-transition enforcement + minted-address CAS - gastownhall/beads#6136 (#6664) 2026-10-18 21:20:57 +00:00
beadserrors ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
cmd/bd bd versions + a config switch for versioned history — the minimum cut that makes versioned beads usable (#6138) (#6661) 2026-10-18 17:28:16 +00:00
docs bd versions + a config switch for versioned history — the minimum cut that makes versioned beads usable (#6138) (#6661) 2026-10-18 17:28:16 +00:00
engdocs feat(http): bd blocked over bd serve (blocked.list), plus bd blocked --flags [--raw] (#7649) 2026-10-17 12:29:13 +00:00
examples fix(examples): bump grpc to 1.83.2 and thrift to 0.24.0 in example modules (#7467) 2026-10-10 12:15:33 +00:00
format ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
integrations fix(beads-mcp): bump pyjwt to 2.15.1 and urllib3 to 2.8.0 for security advisories (#7466) 2026-10-10 12:36:14 +00:00
internal Phase 3 (R20): epoch-transition enforcement + minted-address CAS - gastownhall/beads#6136 (#6664) 2026-10-18 21:20:57 +00:00
issueops feat(http): bd blocked over bd serve (blocked.list), plus bd blocked --flags [--raw] (#7649) 2026-10-17 12:29:13 +00:00
journalops ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
memoryops fix(memory): preserve presence for empty values (#5964) 2026-10-12 19:28:54 +00:00
npm-package release: make release/1.3.0 tag-ready — revert #6281, stamp 1.3.0, date the changelog (#6564) 2026-09-15 12:13:59 -07:00
platforms build(rbe): re-pin worker-env to gascity's go1.26.9 worker host (#7411) 2026-10-09 07:38:56 +00:00
plugins/beads ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
release-gates fix(metrics): stop failing the reap test on a transient zombie (#6262) 2026-09-08 18:16:35 -07:00
schema ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
scripts fix(scripts): update-nix-vendorhash no longer reports a build failure as success (#7504) 2026-10-14 22:18:15 +00:00
test fix(http): bd promote over http through issueops.Promote and issues.update.persistence (S21b) (#7554) 2026-10-14 05:51:53 +00:00
tests ci(bazel): dolt-int gates server-storage + cmd-dolt in mode remote (item 5 A2) (#7535) 2026-10-13 09:17:54 +00:00
third_party ci(bazel): fetch pinned Ubuntu debs in parallel from a gascity mirror first (#7434) 2026-10-09 17:47:17 +00:00
tools bd versions + a config switch for versioned history — the minimum cut that makes versioned beads usable (#6138) (#6661) 2026-10-18 17:28:16 +00:00
winget fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
.bazelignore ci(bazel): run pr.yml's repository guards as Bazel tests (#7329) 2026-10-07 00:59:18 +00:00
.bazelrc ci(bazel): dolt-int gates server-storage + cmd-dolt in mode remote (item 5 A2) (#7535) 2026-10-13 09:17:54 +00:00
.bazelversion ci(bazel): Bazel 9.3.0 (prerequisite for the remote repo contents cache) (#7439) 2026-10-09 21:03:41 +00:00
.buildflags chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
.gitattributes build: make repository text EOL deterministic (#5319) 2026-08-10 20:48:09 -07:00
.gitignore build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
.golangci.yml fix(http): bd gate check over HTTP through issueops.ListGates (#7578) 2026-10-16 09:20:24 +00:00
.goreleaser.yml fix(release): branch install header for prerelease vs stable (#4530) 2026-07-01 22:59:50 -07:00
.pre-commit-config.yaml ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341) 2026-10-07 05:17:22 +00:00
.test-skip fix: rewrite TestRepairMultiplePrefixes for Dolt rename semantics (bd-alk64) 2026-02-14 11:05:39 -08:00
AGENT_INSTRUCTIONS.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
AGENTS.md docs(bazel): make bazel test the primary build and test path (ga-96smfk.23) (#7348) 2026-10-07 07:46:02 +00:00
ARTICLES.md fix(docs): remove stale --branch flag and SQLite refs from QUICKSTART (GH#2522) (#2525) 2026-03-11 12:54:30 -07:00
beads.go feat(backends): registry Remote + OpenWith options; beads.OpenBestAvailableWith for embedders (#7188) 2026-10-04 09:34:36 -07:00
beads_cgo.go feat(backends): registry Remote + OpenWith options; beads.OpenBestAvailableWith for embedders (#7188) 2026-10-04 09:34:36 -07:00
beads_gated_test.go feat(workspacegate): shared physical-root resolver, beads.OpenGated, and CLI gate wiring (part 2) (#5093) 2026-07-31 01:41:20 -07:00
beads_nocgo.go feat(backends): registry Remote + OpenWith options; beads.OpenBestAvailableWith for embedders (#7188) 2026-10-04 09:34:36 -07:00
beads_test.go test(testutil): opt-in local dolt sql-server backend for Dolt-backed tests (#6891) 2026-09-28 04:06:49 -07:00
BENCHMARKS.md test: add perf reference benchmarks (#4032) 2026-05-19 18:39:13 -07:00
build-docs.md fix: correct brew commands and remove dead homebrew CI job 2026-02-09 08:02:42 +01:00
BUILD.bazel bd versions + a config switch for versioned history — the minimum cut that makes versioned beads usable (#6138) (#6661) 2026-10-18 17:28:16 +00:00
CHANGELOG.md bd versions + a config switch for versioned history — the minimum cut that makes versioned beads usable (#6138) (#6661) 2026-10-18 17:28:16 +00:00
claim.go feat(issueops): put every issue capability behind one library surface 2026-08-04 12:27:56 -07:00
claim_roundtrip_test.go feat(storage): events + dependents reads, batched blocked, public claim surface (#4926) 2026-07-22 07:41:47 -07:00
claim_test.go feat(storage): events + dependents reads, batched blocked, public claim surface (#4926) 2026-07-22 07:41:47 -07:00
CLAUDE.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
codecov.yml test: improve coverage signal policy (#4219) 2026-05-27 22:05:14 -07:00
CONTRIBUTING.md ci(bazel): run the hook-timeout-backends check under Bazel; test-nix stops running tests (#7357) 2026-10-07 11:05:39 +00:00
CONTRIBUTING_PR_GUIDELINES.md docs: add CONTRIBUTING_PR_GUIDELINES.md (codify reviewer expectations for contributors) (#3913) 2026-07-06 22:12:29 -07:00
default.nix fix(deps): bump grpc to 1.83.2 and thrift to 0.24.0 (#7495) 2026-10-11 09:58:58 +00:00
errors_test.go feat(issueops): name the two dependency-endpoint refusals (bd-yby99.9) 2026-08-07 19:45:54 +00:00
export_dependency_add_options_test.go feat: export DependencyAddOptions from the root package (#4870) 2026-07-17 20:34:32 -07:00
FEDERATION-SETUP.md chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
flake.lock flake.lock: Update (#4501) 2026-07-08 12:21:24 -07:00
flake.nix ci(bazel): run the hook-timeout-backends check under Bazel; test-nix stops running tests (#7357) 2026-10-07 11:05:39 +00:00
gazelle.go.work ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341) 2026-10-07 05:17:22 +00:00
go.mod fix(deps): bump grpc to 1.83.2 and thrift to 0.24.0 (#7495) 2026-10-11 09:58:58 +00:00
go.sum fix(deps): bump grpc to 1.83.2 and thrift to 0.24.0 (#7495) 2026-10-11 09:58:58 +00:00
install.ps1 docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
issue_lifecycle_external_test.go feat(storage): one guarded issue-lifecycle surface for the CLI and linked consumers (#5191) 2026-07-31 11:26:38 -07:00
issue_roles_external_test.go feat(http): bd blocked over bd serve (blocked.list), plus bd blocked --flags [--raw] (#7649) 2026-10-17 12:29:13 +00:00
issues.jsonl ci: add nix build check to catch vendorHash drift (GH#3298) (#3364) 2026-04-20 13:21:53 -07:00
LICENSE Initial commit: Beads issue tracker with security fixes 2025-10-11 20:07:36 -07:00
Makefile fix(bazel): one nogo-validating lane per race configuration (F5 S1) (#7479) 2026-10-10 18:05:17 +00:00
mint.sh chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
MODULE.bazel fix(build): pair Darwin SDKs with the native Apple linker (#7460) 2026-10-11 03:51:25 +00:00
MODULE.bazel.lock ci(bazel): Bazel 9.3.0 (prerequisite for the remote repo contents cache) (#7439) 2026-10-09 21:03:41 +00:00
NEWSLETTER.md Retire legacy Homebrew tap publishing (#4478) 2026-06-22 19:26:46 -07:00
open_backend_selection_test.go feat(backends): registry Remote + OpenWith options; beads.OpenBestAvailableWith for embedders (#7188) 2026-10-04 09:34:36 -07:00
open_nocgo_test.go :remove uneccessary locking 2026-05-01 17:46:37 -07:00
overlay.nix feat(nix): expose packages as an overlay for downstream override (#3910) 2026-07-06 22:39:37 -07:00
packages.nix feat(nix): expose packages as an overlay for downstream override (#3910) 2026-07-06 22:39:37 -07:00
PR_MAINTAINER_GUIDELINES.md docs(maintainer): prior-art pass is part of every review; rebases are maintainer work (#5094) 2026-07-26 21:40:34 -07:00
PROPOSAL-cas-conditional-update.md fix(claim): verify claim-family writes by re-read under a degraded server (bd-zccb9) (#5006) 2026-07-24 07:21:24 -07:00
PROPOSAL-pluggable-storage-backends.md Reapply "Simplify the supported backends: roll back the direct PostgreSQL and MySQL adapters" (#4857) 2026-07-18 02:43:56 +00:00
PROPOSAL-pull-config-wedge.md fix(dolt): pre-pull commit must include config (kv.memory.* pull-wedge) (#4412) 2026-06-19 21:31:33 -07:00
query_interfaces_cgo_test.go feat(storage): events + dependents reads, batched blocked, public claim surface (#4926) 2026-07-22 07:41:47 -07:00
query_interfaces_test.go feat(storage): events + dependents reads, batched blocked, public claim surface (#4926) 2026-07-22 07:41:47 -07:00
README.md feat(list): bd list's remaining filters over http behind issues.list.filters (#7647) 2026-10-17 11:21:18 +00:00
RELEASING.md ci(bazel): retire main.yml's Linux jobs, nightly's go test jobs and ci-measurements (#7354) 2026-10-07 10:06:59 +00:00
renovate.json chore: harden release and dependency security 2026-04-28 08:45:22 +00:00
ROADMAP.md docs(contributing): recommend issues when they add context instead of requiring one per PR (#7323) 2026-10-06 23:29:09 +00:00
SECURITY.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
THIRD_PARTY_LICENSES revert: restore embedded Dolt mode (was only supposed to be removed from Gas Town) 2026-02-07 21:21:24 -08:00
VERSIONED-BEADS-WRITE-PATHS.md storage: add participation_generation (migration 0070) and the versioned-history write fence (#6943) 2026-10-18 13:10:57 +00:00

bd - Beads

Distributed graph issue tracker for AI agents, powered by Dolt.

Platforms: macOS, Linux, Windows, FreeBSD

License Go Report Card Release npm version PyPI

Docs: https://beads.gascity.com/

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

flowchart LR
    create["bd create<br/>new bead"] --> depgraph["dependency<br/>graph"]
    depgraph --> ready["bd ready<br/>claimable work"]
    ready --> claim["bd update --claim<br/>agent takes it"]
    claim --> close["bd close<br/>work done"]
    close -->|blockers released| ready
    depgraph <-->|"bd dolt push / pull"| remote[("other machines<br/>and agents")]

⚡ Quick Start

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: refresh or install richer instructions for your agent
bd setup codex    # Codex CLI - installs skill, AGENTS.md guidance, and hooks
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

bd init creates or updates AGENTS.md by default so agents can discover the beads workflow, and also installs the project Claude Code, Codex, and Cursor integrations unless you pass --skip-agents or --stealth. Use bd setup --list to see supported integrations, including bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor, and more. See Agent and IDE setup.

Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun bd init/bd setup, or custom instruction files. In those cases, run bd onboard and paste the printed snippet into the file your agent reads.

If your agent is not covered by bd setup, add this minimal AGENTS.md section:

This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for durable project facts; keep per-operator preferences in your harness's own memory.
- Do not use markdown TODO lists for task tracking.

🛠 Features

  • Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
  • Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
  • Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
  • Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
  • Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
  • Graph Links: relates-to, duplicates, supersedes, and replies-to for knowledge graphs.

📖 Essential Commands

Command Action
bd ready List tasks with no open blockers.
bd create "Title" -p 0 Create a P0 task.
bd update <id> --claim Atomically claim a task (sets assignee + in_progress).
bd dep add <child> <parent> Link tasks (blocks, related, parent-child).
bd show <id> View task details and audit trail.
bd prime Print agent workflow context and persistent memories.
bd remember "insight" Store project memory that bd prime injects later.

🔗 Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

  • bd-a3f8 (Epic)
  • bd-a3f8.1 (Task)
  • bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects. See Git-Free Usage below.

Contributor vs Maintainer: When working on open-source projects:

  • Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
  • Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation

brew install beads           # macOS / Linux (recommended)
npm install -g @beads/bd     # Node.js users

Other methods: install script | go install | from source | Windows | Arch AUR

Requirements: macOS, Linux, Windows, or FreeBSD. See docs/getting-started/installation.md for complete installation guide.

Upgrading? Replacing the binary is not always the whole story. Short version: sync remote-backed databases with your current bd, back up with bd export --all, upgrade the binary, then run bd info --whats-new, bd hooks install, and bd version. If the upgrade crosses a schema migration on a remote-backed database, exactly one designated clone runs bd migrate schema and bd dolt push; other clones install the new binary and run bd bootstrap. See the full upgrade guide or docs/getting-started/installation.md.

Security And Verification

Before trusting any downloaded binary, verify its checksum against the release checksums.txt.

The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.

On macOS, scripts/install.sh preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via BEADS_INSTALL_RESIGN_MACOS=1.

See docs/reference/antivirus.md for Windows AV false-positive guidance and verification workflow.

💾 Storage Modes

Beads uses Dolt as its database. Two modes:

  • Embedded (default) — bd init. Dolt runs in-process, data lives in .beads/embeddeddolt/, single writer. Recommended for most users.
  • Server — bd init --server. Connects to an external dolt sql-server for multiple concurrent writers; data lives in .beads/dolt/.

Cross-machine sync uses bd dolt push / bd dolt pull against refs/dolt/data on your git remote; .beads/issues.jsonl is an export for viewers and interchange, not the source of truth or a backup. Back up and migrate between modes with bd backup; reclaim space with bd prune / bd purge.

Full detail — connection flags, sockets, maintenance, backup, and migration — in the Dolt backend guide.

Schema Version Guard

bd checks the database schema version at open time. If the database has been migrated by a newer binary and an older binary tries to open it, bd exits with an actionable error rather than issuing queries that fail with cryptic SQL errors:

schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)

  Your bd binary is stale. Queries for dropped or renamed columns will fail
  with cryptic SQL errors (e.g. "column X could not be found in any table in scope").

  Rebuild from main:
    CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd

  Or install the latest release:
    CGO_ENABLED=0 go install -tags gms_pure_go github.com/steveyegge/beads/cmd/bd@latest

  To proceed despite the risk (some read commands may still work):
    BD_IGNORE_SCHEMA_SKEW=1 bd <command>
    bd --ignore-schema-skew <command>

When this fires: only when the database schema is ahead of the binary (a newer binary migrated the database; this binary doesn't know those migrations). Normal upgrades, where the binary migrates the database forward, are unaffected.

Escape hatch: BD_IGNORE_SCHEMA_SKEW=1 (or --ignore-schema-skew) bypasses the guard with a warning on stderr. Use this only if you know the forward migrations are additive and safe for your specific workload.

🔌 HTTP Backend (experimental)

A workspace can also talk to a remote bd serve over HTTP instead of opening a local Dolt database — useful for a thin client against a shared server, or for embedding beads in another program as a library.

# Point this workspace at a server (verifies the server first; writes nothing on failure)
bd connect https://bd.example.com --expect-project-id my-project

# The everyday commands work the same way: create, show, list, update, close,
# dependencies (including `bd dep tree`), comments, ready/count queries, and
# batch apply all round-trip over the wire with the same semantics as a local
# database. So does `bd ready --claim`, except against an older server or while
# any issue holds an unsatisfied external ref: then it lists and claims in two
# steps rather than one transaction (ledger row L14, linked below).
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd close bd-a1b2 "Fixed"

# Loopback needs no TLS
bd connect http://127.0.0.1:8080

# Forget the server and restore this workspace's previous backend selection
bd connect --clear

HTTP mode is not a byte-for-byte mirror of local mode, though: some operations are knowingly refused (the wire has no way to express them) or degrade to a different-but-not-misreadable behavior (for example, a few unbounded listing shapes lose single-query snapshot isolation and instead walk the server page by page). Every one of these is a deliberate, tested row, never a silent gap — see engdocs/design/http-divergence-ledger.md for the full, generated list of what differs and why before depending on an HTTP-backed workspace for a workflow you haven't checked against it. One refusal to know up front: bd close --claim-next closes nothing over HTTP, because the wire's batch close cannot carry the claim. Close without it, then run bd ready --claim.

Cross-repo dependencies keep their policy over HTTP. The client resolves each external: reference against its own external_projects configuration. bd dep tree shows the reference as a leaf, and while it is unsatisfied the issue stays out of bd ready and bd ready --claim, and bd close refuses it without --force. A server that advertises enforcing that policy itself is trusted to do so instead.

Three CLI-level differences are worth knowing up front:

  • IDs resolve exactly: an abbreviated id is not expanded (the wire has no substring search), and a missing id is reported as not found after one lookup.
  • bd update -s closed does not record closed_by_session (from --session or CLAUDE_SESSION_ID), because the wire's update cannot carry it; the close itself happens as usual. bd close does record the session. bd reopen's history entry carries the server's own label.
  • Contributor auto-routing (routing.* settings) is read from local config.yaml / environment only, never from the server's settings: its targets are local paths.

bd connect writes two things on success: .beads/metadata.json gets "backend": "http", and a per-user, never-git-tracked sidecar (.beads/http_target.json) records the server URL and pinned project id. It never writes a credential to disk. A bearer credential, if the server requires one, comes from BEADS_HTTP_TOKEN=host[:port]=<token>, then BEADS_HTTP_TOKEN_COMMAND=host[:port]=<command> (a helper that prints a token), then the credentials file, then no credential at all. Both variables must name the server they are for (a pattern without a port matches that host on any port); a bare value is refused, because it would be sent to whatever server the workspace's http_target.json names. Connecting to a non-loopback server over plain http:// is refused by default (a bearer credential would cross the network unencrypted) — pass --allow-plaintext to override, or use https://. Switching a workspace that already selects a different backend needs --force.

Each read (a GET, or the POST batch get) gives its first attempt 15s, from when the request is sent, to get the server's response headers (BEADS_HTTP_RESPONSE_HEADER_TIMEOUT: a duration such as 30s, a number of seconds, or off). A read whose headers do not arrive in time, or whose connection is reset, is retried once on another connection, and each retry is logged to stderr with its count. The retry has no header timer, but it runs on what is left of the 60s bound on the whole request, counted from when the first attempt was sent: a slow but healthy read still finishes if the retry's headers and body together fit in that remainder (about 45s after a header timeout), and one that needs longer now fails at 60s. The header timer never cuts off a body that is still streaming; the 60s bound still does. The events:watch stream's connect gets neither the header timer nor the retry. On Windows a reset connection is retried only when it surfaces as an early EOF, because the check matches the Unix reset error (ECONNRESET), which a Windows reset (WSAECONNRESET) is not. A write gets no header timer (the server answers a write only after it commits, so a large one can be slow and healthy) and is never retried; if the 60s bound expires after it was sent but before its headers, it fails with an error naming the server's host, because it may or may not have been applied. A batch apply of more than 100 items (a large bd create --graph plan, say) gets 6 minutes instead of 60s, because bd serve gives such a request its --large-apply-ceiling (5 minutes by default) and finishes it even after the client has given up. A server whose ceiling is raised past about 5m15s can still outlast the client. A dial or TLS timeout stays a plain connection error, since the server never saw the request. off turns off only the header timer: a reset read is still retried, and a write's timeout is still reported as above.

bd search, bd show --current and bd recompute-blocked work over HTTP too, each in its own way. bd search asks the server's listing with its text (q, behind the issues.list.search capability) and refuses before dialing against a server that does not advertise it. bd list --no-assignee, --title and --id likewise ride the listing's no_assignee, title and repeatable id, each behind its own capability (issues.list.noAssignee, issues.list.title, issues.list.ids), and the rest of bd list's filters (--updated-*, --closed-*, --defer-*, --due-*, --priority*, the text and external-ref matches, --spec, --label-pattern/--label-regex, --exclude-type, --no-parent, --no-labels, --empty-description, --pinned/--no-pinned, --deferred, --overdue, --mol-type, --wisp-type) ride it behind one capability, issues.list.filters. Time bounds are resolved on the client as they are locally; --overdue compares against the server's clock. The default --parent tree view does not carry those filters yet and refuses one rather than drop it; --flat or --json applies them to the parent's direct children (not its whole subtree). bd show --current finds the actor's in-progress or hooked issue through the server's boolean query. bd recompute-blocked is a no-op that exits 0: the server maintains is_blocked on every write, and repairing a stale flag is done in the server's own workspace (--json reports {"rows_corrected": 0, "maintained_by": "server"}).

An embedding program that links beads as a library rather than running cmd/bd registers this backend itself through the public backend/http package (bdhttp.Register), and can open a workspace with a credential scoped to one caller via beads.OpenBestAvailableWith — see that package's doc comment for the multi-tenant case. This surface is EXPERIMENTAL: pin an exact beads version.

🌐 Community Tools

See docs/community-tools.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

See docs/related-projects.md for adjacent or complementary projects that solve different problems in the same neighborhood.

🚀 Git-Free Usage

Beads works without git. The Dolt database is the storage backend — git integration (hooks, repo discovery, identity) is optional.

# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR tells bd where to put the .beads/ database directory, bypassing git repo discovery. --stealth sets no-git-ops: true in config, disabling all git hook installation and git operations.

This is useful for:

  • Non-git VCS (Sapling, Jujutsu, Piper) — no .git/ directory needed
  • Monorepos — point BEADS_DIR at a specific subdirectory
  • CI/CD — isolated task tracking without repo-level side effects
  • Evaluation/testing — ephemeral databases in /tmp

📝 Documentation