- Go 95.2%
- Python 1.6%
- Starlark 1.5%
- Shell 1.3%
- Rust 0.2%
* 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" (
|
||
|---|---|---|
| .agent/workflows | ||
| .beads/formulas | ||
| .claude | ||
| .claude-plugin | ||
| .devcontainer | ||
| .githooks | ||
| .github | ||
| backend | ||
| beadserrors | ||
| cmd/bd | ||
| docs | ||
| engdocs | ||
| examples | ||
| format | ||
| integrations | ||
| internal | ||
| issueops | ||
| journalops | ||
| memoryops | ||
| npm-package | ||
| platforms | ||
| plugins/beads | ||
| release-gates | ||
| schema | ||
| scripts | ||
| test | ||
| tests | ||
| third_party | ||
| tools | ||
| winget | ||
| .bazelignore | ||
| .bazelrc | ||
| .bazelversion | ||
| .buildflags | ||
| .gitattributes | ||
| .gitignore | ||
| .golangci.yml | ||
| .goreleaser.yml | ||
| .pre-commit-config.yaml | ||
| .test-skip | ||
| AGENT_INSTRUCTIONS.md | ||
| AGENTS.md | ||
| ARTICLES.md | ||
| beads.go | ||
| beads_cgo.go | ||
| beads_gated_test.go | ||
| beads_nocgo.go | ||
| beads_test.go | ||
| BENCHMARKS.md | ||
| build-docs.md | ||
| BUILD.bazel | ||
| CHANGELOG.md | ||
| claim.go | ||
| claim_roundtrip_test.go | ||
| claim_test.go | ||
| CLAUDE.md | ||
| codecov.yml | ||
| CONTRIBUTING.md | ||
| CONTRIBUTING_PR_GUIDELINES.md | ||
| default.nix | ||
| errors_test.go | ||
| export_dependency_add_options_test.go | ||
| FEDERATION-SETUP.md | ||
| flake.lock | ||
| flake.nix | ||
| gazelle.go.work | ||
| go.mod | ||
| go.sum | ||
| install.ps1 | ||
| issue_lifecycle_external_test.go | ||
| issue_roles_external_test.go | ||
| issues.jsonl | ||
| LICENSE | ||
| Makefile | ||
| mint.sh | ||
| MODULE.bazel | ||
| MODULE.bazel.lock | ||
| NEWSLETTER.md | ||
| open_backend_selection_test.go | ||
| open_nocgo_test.go | ||
| overlay.nix | ||
| packages.nix | ||
| PR_MAINTAINER_GUIDELINES.md | ||
| PROPOSAL-cas-conditional-update.md | ||
| PROPOSAL-pluggable-storage-backends.md | ||
| PROPOSAL-pull-config-wedge.md | ||
| query_interfaces_cgo_test.go | ||
| query_interfaces_test.go | ||
| README.md | ||
| RELEASING.md | ||
| renovate.json | ||
| ROADMAP.md | ||
| SECURITY.md | ||
| THIRD_PARTY_LICENSES | ||
| VERSIONED-BEADS-WRITE-PATHS.md | ||
bd - Beads
Distributed graph issue tracker for AI agents, powered by Dolt.
Platforms: macOS, Linux, Windows, FreeBSD
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, andreplies-tofor 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 --contributorto 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 maintainerif 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 externaldolt sql-serverfor 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 closeddoes not recordclosed_by_session(from--sessionorCLAUDE_SESSION_ID), because the wire's update cannot carry it; the close itself happens as usual.bd closedoes record the session.bd reopen's history entry carries the server's own label.- Contributor auto-routing (
routing.*settings) is read from localconfig.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_DIRat a specific subdirectory - CI/CD — isolated task tracking without repo-level side effects
- Evaluation/testing — ephemeral databases in
/tmp
📝 Documentation
- Documentation site | Installing | Sync Concepts | Agent Setup | Copilot CLI Setup | Copilot VS Code MCP | Articles | Sync Branch Mode | Troubleshooting | FAQ
- Contributing: CONTRIBUTING.md (Bazel builds and tests beads: install Bazelisk, then
make test) | Roadmap | Contributor agent instructions