* test(conformance): author R7.1 as-of-read conformance contract Adds a new Phase 0 conformance contract for R7.1 (as-of reads, gastownhall/beads#6136, design doc #5898 rev 9) -- no fixture existed for this anywhere in backend/conformance/, so this is authored from scratch, not un-skipped. AsOfReadFixture supplies three hooks: Resolve (the read under test), MintAt (seeds a version at a controlled accept-time), and MakeUnanswerable (arranges a Gone/Unknown refusal independently of RetentionFixture/EpochFixture's own removal machinery, since R7.1's refusal is a sibling contract to R17/R20, not a dependent of them). Five Run* functions cover the bead's five required-coverage points verbatim: - selector accepts either an instant or a version address, and both name the same answer when they resolve to the same version; - resolution returns the latest version at-or-before T, with a version accepted after T strictly excluded even when close by; - a served result reports the exact address it served; - an unanswerable read refuses as a typed Gone*/Unknown outcome with a reason, and never substitutes a neighboring version, the nearest surviving version, or current state -- asserted directly by requiring Address == "" on every refusal; - local completeness only (TC3): a lineage minted into one of two stores resolves there and refuses Unknown (FR-06) on the store that never received it, asserting nothing about agreement between the two. The file's doc comment states the Memory-plane-consumer-policy non-goal explicitly (closed-before-T boundary, sibling exclusion, supersession exclusion are consumer policy per #5877, not part of this primitive) so the gap reads as deliberate scope, not an oversight. Wired onto all three storage legs (dolt, embeddeddolt, uow) with unconditional "not implemented" stubs rather than partial-real hooks, so every case fails via MintAt on its first fixture call -- deterministic RED with no risk of an accidental pass, per the precedent set by be-x5jqd.1. Sentinel error messages reference be-x5jqd.5, the implementation child this suite is written ahead of. TestEveryLegWiresEveryRoleContract requires zero waivers: all 5 new entrypoints are fully wired (not nil) on all three legs. Branch cut from the rebased be-2h167 head (5fdfb92fe5). Verified via go build ./..., go vet ./..., gofmt -l, and go test -tags cgo across all three legs: all 5 new subtests (8 counting the 4-way Gone/Unknown table) FAIL for the documented reason, TestEveryLegWiresEveryRoleContract passes cleanly on all three legs, and TestVersionedHistoryPhase0RunsInFullSkipMode is unaffected. Bead: be-x5jqd.2 * fix(history): refuse metadata integers binary64 cannot hold exactly (refs be-wdlod, #6358 follow-up) canonicalDurableState canonicalizes numbers per RFC 8785 (JCS), which renders every number as an IEEE-754 binary64 double regardless of magnitude. An integer-valued metadata literal past 2^53-1 therefore rounds to a DIFFERENT VALUE on the way into durable_state -- not a formatting change, a value change -- which can collapse two distinct issue states onto one durable_state and therefore one content token. refuseUnrepresentableIntegers is the fix: an admission gate, one layer above the JCS step, that parses each JSON number literal exactly with math/big (never float64 -- float64 rounding is the exact thing being guarded against) and refuses whenever the literal's VALUE, not its spelling, is an integer whose magnitude exceeds 2^53-1. Value-not-form matters because the first cut of this gate skipped any literal containing '.', 'e', or 'E' outright, reasoning that non-integer forms round-trip losslessly -- true for genuinely fractional literals, but not for an integer VALUE spelled in decimal or exponential form: QA found that 9007199254740993.0 and 9.007199254740993e15 walked straight past that first gate and canonicalized to the same colliding target as the bare literal. The predicate now inspects the value via big.Rat.SetString/.IsInt, so all three spellings are refused alike. 1e300 is refused too, no notation carve-out: it denotes the integer 10^300, and binary64 spacing near that magnitude is roughly 2^248 -- vastly wider than the collision window at the 2^53 boundary this gate exists to close. Admitting that spelling while refusing 9007199254740993 would be the same defect with a bigger window (mayor's ruling, citing this collision-window argument as decisive). Non-integer values stay admissible past the bound (1.5e300 is fine): ES6 shortest-round-trip formatting is a bijection on doubles, so two non-integer literals collide only if they already denoted the same double before this gate ever ran, and a fractional literal never carried a promise of exact decimal storage the way an integer -- an id, a count, a timestamp -- carries a promise of exactness that silent rounding would corrupt. jcsCanonicalize is canonicalDurableState's RFC 8785 step pulled out on its own, below the gate rather than behind it, because refusing 1e300 puts the admission policy at odds with one of this store's own spec- conformance fixtures: testdata/jcs/input/values.json, one of the 10 official RFC 8785 vectors shipped verbatim from the spec's reference suite (not authored here), itself contains 1E30. RFC 8785 conformance is a claim about the canonicalizer, not about this store's admission policy, so TestCanonicalDurableStateIsJCS now runs all 10 shipped vectors -- values.json included, still asserting 1E30 folds to 1e+30 per spec -- through the ungated jcsCanonicalize, while its two local ad hoc cases keep exercising the full gated canonicalDurableState, since neither conflicts and both are more faithful to production traffic that way. The gate's own refusal of that magnitude is pinned separately, on its own terms, in version_history_integer_admission_test.go. Severity is MINOR, not MAJOR: Dolt's JSON column type already renormalizes metadata to float64 on every read regardless of this gate (measured on dolt 2.2.3: 9007199254740993 reads back as 9007199254740992, 1e300 as 1e+300), which converges two distinct in-memory states to one stored state before any version row is minted. The collision this gate closes is therefore unreachable through normal bd update traffic on this backend; it stays real for off-path writes -- bd sql, a hand-written JSONL import, or a TEXT-column backend -- which is why this landed as a follow-up rather than gating Phase 2 itself. Verified clean: a full module compile; static analysis over the storage tree; the complete issueops package suite (260 subtests); the schema package suite; and the broader storage tree, apart from one dolt-package test that fails identically against the pre-this-diff baseline (a Dolt server port collision with a concurrent session's process on this host) -- confirmed pre-existing and environmental, not caused by this change. * feat(issueops): implement R7.1 as-of read's store-layer primitive (be-x5jqd.5) Turns backend/conformance/versioned_read_contract.go (authored RED in 6aefdce60, gastownhall/beads#5898 rev 9, #6136) towards GREEN. This commit lands the shared production seam; wiring the three per-leg fixtures (dolt, embeddeddolt, uow) onto it is a follow-up commit. asof_read.go (new): AsOfReadInTx resolves an AsOfSelector (an instant or a previously-served version address) to one issue_versions row -- the latest version accepted at or before T, everything later strictly excluded -- and reports either its state and address, or a typed refusal (gone-retention/gone-erasure/gone-reorganization/unknown) with a reason. storeID is accepted only for signature parity with the fixture hook shape (Design D: the conformance suite's own ad hoc dispatch string selects among per-leg isolated test stores; issue_versions carries no store_id column, matching CurrentEpochInTx's precedent). AsOfRestriction is string-backed, unlike R20's int-backed EpochRestriction, because it round-trips directly through the new removed_restriction column with a plain cast. Migration 0069 adds issue_versions.removed_restriction VARCHAR(30), nullable (NULL = live, never a stored value). Sits alongside removed_at/ removed_reason (migration 0067, virgin until this slice); AsOfReadInTx only READS all three -- a future R17 is the real writer via hold/remove/ erase primitives, no collision. Guarded PREPARE + CLI direct-DDL override + schema_test.go hygiene entries, all modeled on 0068's pattern; TestLatestVersionIncludesMigration0068 is superseded per the one-pin-at-a-time convention. version_history.go: splits RecordVersionInTx into a versionedHistoryEnabled- gated wrapper and a new exported RecordVersionAtInTx, both delegating to a shared recordVersionAtInTx(..., at time.Time) body. RecordVersionAtInTx is test-support only -- ungated, caller-chosen timestamp -- so an as-of- read fixture's MintAt hook can mint version rows dated in the past without flipping a store's history-enabled flag. No behavior change for existing RecordVersionInTx callers. The new/moved code shifted which function each completeness guard sees as the enclosing write site, so all three needed updating, not bypassing: - row_lock_guard_test.go's funcNameExemptions key moves from RecordVersionInTx to recordVersionAtInTx (the write's new actual enclosing function), reasoning extended to cover both callers. - journal_completeness_test.go's beadDMLExemptions and version_completeness_test.go's versionExemptions each gain a RecordVersionAtInTx entry mirroring RecordVersionInTx's own (test- support twin, no production caller, no mutation of its own to journal/mint beyond the seam itself). Also fixed a latent test-helper gotcha found while writing the 0069 Dolt-CLI test: queryDoltCSV trims the whole `dolt sql -r csv` output before parsing, so a row whose ONLY selected column is NULL renders as a bare blank line that strings.TrimSpace silently swallows when it's the trailing line, collapsing "one row, NULL value" into "zero rows". Fixed by selecting a non-NULL anchor column (issue_id) alongside the column under test. Verification performed: full module compile and static analysis, gofmt clean; the complete internal/storage/schema suite with the real-Dolt-CLI lane enabled; and the complete internal/storage/issueops suite, including every completeness/row-lock structural guard -- all clean. * feat(issueops): wire dolt, embeddeddolt, and uow onto R7.1 as-of read (be-x5jqd.5) Turns backend/conformance/versioned_read_contract.go fully GREEN (authored RED in 6aefdce60, gastownhall/beads#5898 rev 9, #6136): this follows up on 4da98a9a8's shared production seam by wiring all three storage legs' AsOfReadFixture (Resolve/MintAt/MakeUnanswerable) onto issueops.AsOfReadInTx, per that commit's own stated plan. Each leg's asOfReadHarness is Design D's dispatch table: the conformance suite invents storeID strings to select among N isolated stores, and isolating them is entirely the harness's job -- AsOfReadInTx itself stays storeID-oblivious. The three legs differ only in how they get that isolation cheaply: - dolt: one shared testcontainer, N randomly-named databases - embeddeddolt: N fully independent on-disk databases - uow: one shared dolt sql-server subprocess (NewDoltServerUOWProvider's adoption semantics collapse repeat calls against the same root dir onto the same process), N randomly-named databases All three harnesses are Fatalf/Skip-free below their own TestAsOfReadContract body: AsOfReadFixture's hooks carry no *testing.T of their own and run from inside t.Run subtest closures (sometimes nested two deep), where FailNow/SkipNow would panic with "subtest may have called FailNow on a parent test". Failures instead flow back as a plain error into conformance.RunAsOfReadXXX, which Fatalfs correctly on the subtest's own goroutine. Two small companion fixes surfaced while wiring the legs on: - issueops.asOfVersionAddress -> AsOfVersionAddress (exported): each leg's MintAt needs to build the exact token its own RecordVersionAtInTx write will resolve against, from a different package than issueops. - recordVersionAtInTx now truncates `at` to whole seconds before writing it to issue_versions.change_at (DATETIME, migration 0067). Measured on dolt 2.2.3: the column ROUNDS a sub-second value rather than truncating it, so a change_at of 13:32:04.77 lands at 13:32:05 -- strictly later than the instant it was meant to record. That breaks resolveAsOfRevisionInTx's "at or before T" comparison (asof_read.go) for any T between the true instant and the rounded- up one. This is a production correctness fix, not test-only: RecordVersionInTx hits the identical hazard on every real time.Now().UTC() call whose nanosecond component rounds up. Verification performed: - uow: TestAsOfReadContract green standalone (5 subtests, 4 nested restriction variants) and the full uow package green in isolation (673s, includes pre-existing TestReleaserContract and everything else). A `go test ./internal/storage/...` full-tree sweep flagged uow FAIL via a 600s hang inside TestReleaserContract's migration lock -- traced to cross-package parallel resource contention from running the whole storage tree's dolt-sql-server-spinning suites concurrently, not a regression: the same test is clean when the package runs alone. - embeddeddolt: TestAsOfReadContract green (22.89s, all subtests and all 4 restriction variants). - dolt: skipped on this host -- no Docker for the leg's testcontainer, the same pre-existing skipIfNoDolt gate the whole dolt package already runs under, unrelated to this change. - TestEveryLegWiresEveryRoleContract and TestEveryContractImporterInTheStorageTreeIsRegistered both pass for all three legs. - gofmt clean; whole-module build and vet clean. Bead: be-x5jqd.5 * feat(versions): bd versions + a config switch for versioned history (refs be-hs42e.6.2) Versioned history has been buildable but not usable: migrations 0067+ create issue_versions, and the Phase 2 writer fills it, but SetVersionedHistoryEnabled was a Go method nothing in cmd/bd ever called. There was no supported way for a person to turn the feature on, and no way at all to read it back without raw Dolt SQL. This adds the switch and a reader. - versioned-history.enabled (env BD_VERSIONED_HISTORY_ENABLED), default off, applied at the top of wireStorageDecorators. It MUST run on the raw store: the capability is a type assertion and no decorator forwards it, so applying it after a wrap would silently leave history off while the config said it was on. TestVersionedHistoryConfigAppliesToTheRawStore pins the ordering, and fails rather than skips if a decorator ever starts forwarding. - storage.VersionLister + issueops.ListVersionsInTx over issue_versions, on the dolt and embeddeddolt legs. A narrow capability rather than a Storage method, following ExternalRefHistoryQuerier: a backend that cannot know must be able to say so instead of answering "none". - bd versions <id>, with three distinguishable outcomes rather than two. Off, unsupported, and empty are different answers with different fixes; an empty list is a claim about the bead, and returning it for the other two would be a wrong answer rather than an empty one. The four removal restrictions render as four sentences, and unknown (no lineage knowledge here) is not gone. - REV is printed as a local ordinal with a footer saying so. It is deliberately NOT presented as a citable address: AsOfVersionAddress mints over the ordinal, two clones can both hold revision 8 of the same bead, and the durable version_id primary key has not landed. An address printed now would break every citation once it does. - bd version <id> now points at bd versions <id> instead of printing bd's own build and looking like the bead has no history. Bare bd version is unchanged. No migration: 0067/0068/0069 already carry every column this reads. Verified on a scratch store: create + 2 updates + close with the flag on lists 4 attributed versions; with the flag off, 0 rows in issue_versions and the command refuses naming the key. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(versions): emit local_revision, not revision, in --json (bee's #5898 consumer read) types.Issue already ships `json:"revision"` (types.go:1206) and it is the row-lock CAS token — an unrelated value, and a string where this one is an int64. Emitting "revision" from the versions payload would put two meanings and two types on one key in the place machines read: the `bd version` collision again, with worse consequences, since a script that learned one shape gets the other and cannot tell. local_revision also carries the non-citability with the value rather than only in a footer no script parses, and needs no rename when version_id lands beside it. Raised by @bee-ghosttrack's consumer read on #5898, who reported a couple of hundred script files parsing `bd … --json` — this is the part of the surface they would actually touch. Pinned by TestVersionsJSONDoesNotCollideWithIssueRevision. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(versions): make the advertised switch actually switch it on (#6661 review) @bee-ghosttrack's blocking finding: the help text and the off-refusal both told the user to run `bd config set versioned-history.enabled true`, and that command did not turn the feature on. The key is not yaml-only, so `bd config set` routed it to the workspace DATABASE; both readers called config.GetBool, which is viper (yaml + env) only. The user ran exactly what they were told, was told it was set, and recording stayed off — configured on, actually off, one layer up from the decorator-ordering hazard this command already guards. Takes bee's option (b): read the switch from the store's own config, where `bd config set` already writes it. That also makes recording a property of the STORE rather than of whoever is calling, which is what closes finding 2 — two clients of one sql-server can no longer disagree about whether a write is recorded. The two planes are OR'd rather than ranked. The hazard is a write that fails to record, never one that records when it needn't, so either saying yes is enough and neither can silently switch the other off. BD_VERSIONED_HISTORY_ENABLED still works for a one-off run. A store with no settings plane (proxied, no-db) falls back to viper instead of failing the command. Also from that review: - finding 3: the read no longer refuses just because recording is off. A store that recorded for a month and was switched off HAS versions; refusing made a claim about the store from a fact about this invocation's config, which VersionLister's own doc says are independent. Rows are listed either way, with a note when recording is currently off; refuse-with-remedy only when off AND empty. - finding 4: an unresolved id with no versions is "no such bead", not "none yet". Falling through on an unresolved id stays right — a deleted bead can still have versions — but only until the answer is empty. - finding 5: the ordering test's escape hatch is t.Fatal, not t.Skip; a skip returned before the assertion that actually guards the ordering. The storage_chain.go doc cited a test name that never existed. version_lister.go promised a list of compile-time assertions that was not there; the assertions now exist in each leg's own package, where they can compile. - `versioned-history.` is a recognized config prefix, so the set no longer prints "not a recognized config key" immediately before confirming the set. Test: TestVersionedHistorySwitchRoundTrip_Embedded drives the real `bd config set` through to a real `bd versions` against a real store, with BD_VERSIONED_HISTORY_ENABLED cleared so a pass proves the store setting carried it alone. This is the round trip bee asked for, and it is the only shape that could have caught the original defect — a fake-backed unit test cannot see a disagreement between two real planes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(versions): name what the OR'd switch planes cost (#6661 review) @bee-ghosttrack, round 2: with the two planes OR'd rather than ranked, the consequence worth naming is that once the store setting says on, BD_VERSIONED_HISTORY_ENABLED=0 cannot countermand it for a single run. The help now says so, and says where to turn it off instead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(versions): gate the wiring store read on the capability, not a recover (#6661 review) @bee-ghosttrack's round-3 blocking finding. wireStorageDecorators reads the versioned-history switch off the raw store on every bd invocation, and did so before anything established that the store could use the answer. cmd/bd's own fakeProbingDoltStore embeds a nil storage.DoltStorage, so the promoted WorkspaceConfig SIGSEGV'd at wiring time -- and a panic takes the whole test binary down, which is why one unguarded read showed up as two red CI steps (Test (macos-latest), PR Core (wrapper timing)) rather than one failed test. Takes the fix bee prescribed: assert storage.VersionedHistoryConfigurer first and read the store plane only when the store could act on the answer. The previous round fixed this with a recover plus a WorkspaceConfig on the fake, and left a comment arguing that no capability assertion could work. That argument was wrong, and wrong in a specific way worth recording: it reasoned about asserting WorkspaceConfig, which IS declared on storage.DoltStorage and so matches every store including the nil-embedding fake. bee proposed asserting VersionedHistoryConfigurer, which is a different interface -- SetVersionedHistoryEnabled is NOT part of DoltStorage, so the fake does not promote it and does not satisfy it. The comment rebutted a fix that had not been proposed. It now states what is actually true. So the fake goes back to byte-identical with the pushed head: the wiring fix fixes that test without touching it, as bee said it would, and the fake keeps the "only the methods below may be called" constraint its own doc asserts. The recover stays, as a backstop rather than the guard. It covers what the assertion does not: versionedHistoryEnabled is also called from `bd versions`, where the read is the point and no capability gate precedes it, and a store that DOES implement the capability can still have a half-built settings plane. The viper plane is still read first and unconditionally, so a set-but-unsupported store still reaches applyVersionedHistoryConfig and still gets its warning. Only the store-plane read is gated. The one case that loses a warning is a store whose own settings plane says true but which lacks the capability -- and `bd config set` could not have written that plane on such a store to begin with. Tests, split so each layer fails for its own reason: - TestWireStorageDecoratorsSkipsTheStoreReadForANonConfigurer asserts calls == 0, not merely that it survived. "It survived" is what the recover delivers too, which is how this regressed the first time. - TestWireStorageDecoratorsSurvivesAStoreThatCannotAnswer keeps the recover's case, now on a store that IS a configurer so the guard lets it through. - TestVersionedHistoryEnabledForWiringReadsTheStoreWhenItCanRecord pins that the guard did not stop reading the plane finding 1 existed to start reading. Mutation-verified both ways: removing the guard fails the first test on calls=1/want=0 while everything still "passes" by surviving; removing the recover leaves the first test green and fails only the second. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(versions): name the embedded round-trip so CI selects it (#6661 review) @bee-ghosttrack's round-3 finding 2. The round-trip test that proves the two config planes agree ran only on the author's machine. .github/scripts/embedded-test-shard.sh discovers what to run with `grep -rh '^func TestEmbedded' cmd/bd/*_embedded_test.go` and validates manifest entries against ^TestEmbedded[A-Za-z0-9_]+$. TestVersionedHistorySwitchRoundTrip_Embedded matched neither, so the only lane that sets BEADS_TEST_EMBEDDED_DOLT=1 for cmd/bd never selected it; the generic Test jobs run without that env, where the test's own guard skipped it. Skipped and passed look alike from outside, which is what made it invisible. Renaming is the whole fix -- a test absent from the shard manifest still gets a shard from the fallback distribution. Verified by running the script's own selector over the tree and confirming the new name is discovered. The rationale is now a comment on the test, because the old name reads more naturally and nothing else in the file explains why the prefix is load-bearing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(versions): drop the dead fixture, name the empty arm (#6661 review) @bee-ghosttrack's round-3 finding 3. TestVersionsRefusesWhenFlagOff built a backend holding one recorded version, handed it to nothing, and ended in `_ = backend`. The fixture was load-bearing for the assertion the test was named after -- that the read was refused BEFORE the backend was consulted. Finding 3 removed that behaviour on purpose, so the assertion went with it; the fixture stayed behind, unused, under a name still promising the old contract. Renamed to TestVersionsOffAndEmptyRefusesWithRemedy for what it actually pins, moved beside TestVersionsOffButRecordedStillLists so the two read as the pair they are -- recording off decides the FOOTER, never whether to read; off with rows lists them, off and empty is the one case that refuses -- and the dead fixture is gone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(proxy): give bd versions a capability row, a typed refusal (#6661) main's proxied-server capability registry (#6582) requires every command path to carry a row, and TestProxyCapabilityRegistryCoversCommandTree fails for `bd versions`, which this PR adds. It is refused, reason unimplemented, rather than permitted. It is a pure read (issueops.ListVersionsInTx in one read transaction), so nothing about it is unsafe on a shared backend and "design" would be wrong. But it reaches the backend only through the optional storage.VersionLister, which the dolt and embedded stores implement and the uow provider does not. Permitting it would open the proxied provider in the root pre-run (starting the proxy and dolt) and then fail untyped at errVersionsUnsupported. The row refuses with proxy.versions.unsupported before any side effect, and its tracking names the missing piece: a VersionLister over the proxied uow provider (tracker #6132). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(uow): register verified shutdown cleanup in TestAsOfReadContract (#6661) main's TestEveryServerFixtureRegistersVerifiedCleanup (#6441) requires every server fixture to use verifiedShutdownCleanup(t, storeRootDir) instead of calling proxy.Shutdown directly, so a shutdown that refuses cannot leave a live dolt sql-server behind a green run. TestAsOfReadContract still had its own proxy.Shutdown cleanup that only logged the error. The cleanup is registered at the same point, so the LIFO ordering the harness relies on (every provider closed before the shared server stops) is unchanged. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * style(schema): gofmt cli_migrations.go after the 0070 renumber The rebase onto upstream's 0069_widen_issue_versions_datetime_precision (#6675) joined its const and the renumbered 0070 comment without the separating blank line, which make fmt-check rejects. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(history): stop flooring change_at now that 0069 widened it (refs be-hs42e.10) recordVersionAtInTx carried `at = at.Truncate(time.Second)`. That was correct while 0067's plain DATETIME was in force: Dolt's datetime(0) does not truncate sub-second input, it ROUNDS half-up, so a change_at could be stored strictly LATER than the instant it recorded and break AsOfReadInTx's "latest version accepted at or before T". Flooring first left nothing to round. Migration 0069 widened change_at and removed_at to DATETIME(6), which removes the rounding entirely and makes the floor actively harmful — it threw away the microseconds the widening exists to keep. Two versions minted in the same second collapsed onto one stored value and stopped being distinguishable by change_at, which defeats --at, the only PORTABLE selector the read surface offers while revision stays a per-store ordinal and no durable version address has shipped. This was measured, not inferred. On a store carrying both the widening and the floor, four versions minted inside one second all read back 15:40:38.000000: the column could hold microseconds and the writer refused to supply them. Two correct fixes cancelling each other, and only the second one was visible. removed_at needs no matching change: MarkLatestVersionRemovedInTx already passes time.Now().UTC() straight through and was never floored. Audited rather than assumed. Pinned by TestRecordVersionKeepsSubSecondChangeAt (embeddeddolt), which mints two versions 500ms apart inside one second and asserts both that the fractional part survives and that the two differ. Verified it FAILS with the floor restored — reporting exactly the 11:04:07.000000 collapse — and passes without it, so it is a real guard rather than a test that passes either way. The column's own half of the contract stays pinned by TestMigration0069ChangeAtSurvivesSubSecondPrecisionThroughDoltCLI. Also drops this branch's own tx-minting guard commit, which upstream landed independently as #6833. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(feat): red — Activate versioned history in every store and provider factory, each store reading its own #6661 switch (stacked on #6661) (refs be-qxq70) Tests first, all failing on the right reasons at fb6e219d6a (#6661's head): - D1: on real embedded stores a routed update, a routed close and `bd create --repo` into a rig whose OWN row is on each gain 0 issue_versions rows, want 1; the control (a write inside the rig) gains 1. - D3: BD_VERSIONED_HISTORY_ENABLED=1 records into no routed store, and =0 is shown not to switch off a store whose row is on. - D4: TestEveryStoreConstructionActivatesVersionedHistory flags all 9 store and provider factories, and its mutation probe reports "probed 0 of 9". - wiring: wireStorageDecorators still reads the store's row (1 read) and switches it on; activation belongs to the factories. - internal/versionedhistory (does not exist yet) and the doctor repair opener: the resolver, the provider read (K1), the error-vs-absent diagnostics and the shared-activation requirement. * feat: green — Activate versioned history in every store and provider factory, each store reading its own #6661 switch (stacked on #6661) (refs be-qxq70) Stacked on #6661 (fb6e219d6a). #6661's plane and approved commits are unchanged: the switch stays a row of the store's own config table, OR'd with viper, and `bd config set versioned-history.enabled true` still writes that row and not config.yaml. The defect: applyVersionedHistoryConfig ran only from wireStorageDecorators, so the one store a command opens for its own workspace was activated and every store built by newDoltStoreFromConfig (prefix-routed update/close, `bd create --repo`, the direct-mode open) was not. With the switch on they recorded no issue_versions row while the command reported success. - Activation moves to where a store or unit-of-work provider is constructed (the store_factory.go/_nocgo.go twins, uow_factory.go's two provider constructors, the personal-migration planning store, and bd doctor's repair opener), on the raw store, before anything can wrap it. wireStorageDecorators no longer activates, so each store's row is read once per open. - One resolver, in internal/versionedhistory, reachable from doctor/fix which cannot import package main. #6661's semantics are preserved: one key spelling, viper first, then the capability check, then the row read, with the recover backstop. The behavior-preserving refactor of #6661's versioned_history_switch.go / storage_chain.go is the only edit to files #6661 introduced; the resolver tests moved with the code, assertions unchanged. - K1: a provider has no DoltStorage, so its row is read through a unit of work (NewUOW + ConfigUseCase().GetConfig) at construction: a pooled connection, one SELECT, rolled back. The constructors have already run initSchema, so this starts no server and creates nothing. It does not fall back to viper alone. - A row read that errors resolves to off but is reported under BD_DEBUG; an absent row stays silent. - Docs (configuration.md), a CHANGELOG entry, and a hint at `bd config set ... true` time that the setting replicates and is single-writer only. The bazel-sync run also wanted unrelated BUILD entries for files that already exist at #6661's head (versions.go, versioned_read_contract.go, ...); they are not part of this change and are left out. * test(feat): green — a served mutation records from the provider's own row, on a real server (refs be-qxq70) K1 is the one place the resolver cannot ask a DoltStorage: `bd serve` against a server-mode workspace writes through a unit-of-work provider, so its flag is read through NewUOW + ConfigUseCase().GetConfig at construction. The fakes in internal/versionedhistory prove the read; this proves it WORKS against a real Dolt server at that moment (pool open, database selected, schema migrated). Two server-mode workspaces on the shared test container: the one whose own row says on records a served HTTP mutation (+1 issue_versions row), the one with no row records none. Measured both ways: passes with the provider activation in place, and fails ("added 0 issue_versions row(s), want 1") with it deleted from both provider constructors in uow_factory.go. Proxied lane only (BEADS_TEST_PROXIED_SERVER=1 BEADS_TEST_ENV_RUN_DOLT=1 TESTCONTAINERS_RYUK_DISABLED=true), like TestServeActivatesTheEventsJournal, so it skips in a plain make test. * test(feat): red — #6661 review round, small items: findings 2, 4, 5, 6 and 8 Tests for the small findings in the second review round on #6661. - 2: `bd versions` must decide "recording" from the store's own setting. BD_VERSIONED_HISTORY_ENABLED=1 with the store's row unset and nothing recorded must refuse, not answer "none yet"; the help text must not offer the variable as a per-run switch for a read. - 4: `bd versions --json` is one object, {"versions": [...], "recording": bool}, with [] rather than null when nothing is recorded. - 5: AsOfReadInTx reports any stored removed_restriction outside its four values, "live" included, as unknown. - 6: the 0070 header spells the restriction vocabulary with the underscore spellings the code stores and compares. - 8: `bd version <arg>` exits 1 and points at `bd versions <arg>`. This one pins behaviour the branch already has, so it passes at red; it was shown to fail with the guard removed. Item 7 is a comment-only fix and has no test. * feat: green — #6661 review round, small items: findings 2, 4, 5, 6 and 7 - 2: `bd versions` reports the store's own setting. It read the environment and config.yaml as well, so BD_VERSIONED_HISTORY_ENABLED=1 made a store that never recorded answer "No versions recorded yet" instead of refusing with the remedy. It only reads, so those planes cannot make the store record. The "for one run" hint is dropped from the help and the refusal, since it could only ever produce the wrong answer. - 4: `bd versions --json` is always {"versions": [...], "recording": bool}, with [] rather than null when nothing is recorded. Previously a bare array, or null, and no recording flag. - 5: AsOfReadInTx reports a stored removed_restriction outside its four values, "live" included, as unknown instead of passing it through. - 6: the 0070 header and its test use the underscore spellings the code stores and compares. 0070 is unreleased, and this changes its content hash. - 7: comment only. DATETIME(6) still rounds to the microsecond; the comment said 0069 removed the rounding entirely. * test(fix): red — #6661 number admission: fractions past the bound, exponent cost, pre-enable scan Tests for the review round on the number-admission gate, written before the change: - a fraction whose nearest double is at or past 2^53 is refused (9007199254740993.5, 9007199254740994.5, 9007199254740991.5), and the gate is closed under its own canonicalization, checked as a property over a corpus - classification depends on magnitude, not on the size of an exponent: 1e100000000 and -1e400 are refusals, 1e-100000000 and 1e-400 are admitted, and allocation does not grow with the exponent - the sentinel's text names the I-JSON exact-integer range - CheckMetadataVersionable agrees with the mint, and FindUnversionableMetadata finds what the mint would refuse and skips what it never versions - bd config set versioned-history.enabled true refuses, writing nothing, over rows the mint would refuse, and false never scans Guards that pass before and after by design: the verdict on every literal as the store returns it, the mint's refusal writing nothing, and, on the server and embedded legs, the store-level property that no two literals reading back as different numbers share a canonical form. Those store tests also log what each Dolt holds for a number outside the range when history is off, and pin that a later write to such a row is refused once history is on. * fix: green — #6661 number admission: the nearest-double rule, ParseFloat classification, a pre-enable scan at the switch The admission gate now refuses a JSON number literal if and only if the binary64 nearest to it has magnitude above 2^53-1, or it overflows, whatever the literal's spelling: - a fraction that rounds to or past 2^53 (9007199254740993.5, 9007199254740994.5, 9007199254740991.5) is refused, so the gate is closed under its own canonicalization - literals are classified with strconv.ParseFloat, linear in their length, so 1e1000000 no longer builds a million-digit integer inside the writer's transaction; an overflow is the sentinel and a magnitude too small for binary64 is admitted; math/big is gone - the sentinel reads "number is outside the I-JSON exact-integer range (magnitude above 2^53-1)"; ErrIntegerNotRepresentable keeps its name, with a comment saying why - ordinary fractions such as 0.1 stay admitted; no verdict on a value the store hands back changes The header now says what the mint's refusal is: an integrity backstop inside the writer's transaction, not an admission policy for metadata. bd config set versioned-history.enabled true now checks the store first. It reads every issue the mint would version, runs the mint's own function over each one's metadata (issueops.CheckMetadataVersionable, through issueops.FindUnversionableMetadata), and refuses, writing nothing, while any is refused, printing the count, the ids and the fix. There is no override; setting it false never scans. The environment and config.yaml planes do not pass through the command and rely on the refusal at write time. Also: docs and a CHANGELOG entry, and comments in the existing admission tests that described the old rule. * test(fix): keep the exponent-cost allocation test stable under the race detector TestNumberAdmissionAllocationsDoNotGrowWithTheExponent compared two independently averaged allocation counts with a strict >. Under -race sync.Pool drops one Put in four at random, and the refusal's fmt.Errorf takes its printer from a pool, so a call now and then allocates one more than it would. The test failed on most runs of `go test -race -short`, the flag set of the required lane, and never without -race. That noise only ever adds allocations, so compare the fewest allocations over many single-call samples instead. The comparison stays strict, and it still fails on the exact big.Rat gate this test exists to keep out (49 allocations for 1e1000000 against 36 for 1e400). The doc comment no longer claims the count is deterministic under -race. * test(fix): red — set-many skips the pre-enable scan; pin what the scan reads bd config set-many versioned-history.enabled=true switches versioned history on with no pre-enable scan: only bd config set makes it. With a row holding a number outside the I-JSON exact-integer range the setting is turned on and the next write to that row fails. The new embedded test drives the real verb over such a row and expects the whole batch to be refused, writing nothing. The scan's own embedded test only used open issues, so deleting AllFlag or IncludeAllTypes, or replacing the unlimited Limit, left it green. It now adds a closed, a pinned and a gate offender, and a second test imports more rows than one default page and expects every one of them counted. * fix: green — bd config set-many runs the pre-enable scan for versioned-history.enabled bd config set refuses to turn versioned history on while an issue holds metadata a version could not record. bd config set-many writes the same setting through a validation loop of its own and made no such check, so it switched history on over a row whose next write then failed. It now runs the same check for that one key inside its validation loop, before any pair of the batch is written, so a refusal stores nothing. The check reads through the accessor it already used on both routes: the store the command has opened on the direct route, the provider on the proxied one. * chore: strip internal tracker ids from the comments and tests across #6661's range Comment and test-text changes only; no behaviour changes. Across every commit from the merge-base with upstream main to here, the comments and tests named internal tracker ids (one bead id in eleven comments and in one test failure message, an example id in the `bd version` guard's comment, and an internal decision's attribution in the huge-exponent admission test). They now cite gastownhall/beads#5898 and #6136 only, which is what a reader of the public branch can follow. The 0070 migration's header comment is one of the edits. That migration is new on this branch (it does not exist on upstream main), so the change is not an edit to a shipped migration, but it does change the file's content hash; the schema tests that compute hashes are self-consistent. Text that already exists on upstream main is left as it is, even where it mentions an id: this commit does not rewrite lines the range did not add. * chore(bazel): bazel-sync (gazelle) for the #6661 range * fix(bazel): give fix_test the store.go its activation guard parses TestVersionedHistoryDoctorRepairOpenerUsesTheSharedActivation parses store.go from its working directory. `go test` runs in the package directory, so the file is there. A Bazel test only sees its declared runfiles, so the test failed with parse store.go: open store.go: no such file or directory in //cmd/bd/doctor/fix:fix_test (--config=ci) and in shard 1 of //cmd/bd/doctor/fix:fix_dolt_test (--config=doltserver), which runs the same binary through data = [":fix_test"]. Declare store.go as data on fix_test. * test(fix): red — the pre-enable scan must check the whole issue, as the mint does bd config set versioned-history.enabled true runs a check over every issue before it turns history on. The check looked at each issue's metadata alone, while the mint canonicalizes the whole issue. A gate's timeout is a time.Duration that a version holds as nanoseconds, so a gate whose timeout is past 2^53-1 ns (about 104.25 days) holds a number outside the I-JSON exact-integer range: the mint refuses every write to it, the scan never looked, and the switch could be turned on over it. - The agreement test's domain widens from metadata documents to whole issues: the metadata corpus, plus timeouts at 2500h (admitted), 2600h, 8760h and -2600h (refused), exactly 2^53-1 ns (admitted) and 2^53 ns (refused). - The scan test covers a gate over 105 days and expects the verdict to name the field, "timeout". - The mint-level refusal test covers the same gate and expects the refusal to name the field as well as the literal, for a number in metadata too. - An end-to-end test on the direct route and one on the proxied route create gates with bd gate create --timeout, expect the enable to refuse and name them, and expect the issues the scan names to be exactly the issues whose next write the mint refuses. - Three guards keep the scan's lite read from hiding a number: every column it leaves out is a string or a list of strings, nothing the mint adds and the scan does not load can hold a number, and no exported check over part of an issue exists beside the one the mint runs. Each guard is also run against shapes it must refuse, so it cannot pass by finding nothing. The new symbols (CheckIssueVersionable, FindUnversionable and the Field of UnversionableIssue) do not exist yet, so the issueops tests do not build. * fix: green — the pre-enable scan runs the mint's own check over the whole issue The check behind bd config set versioned-history.enabled true looked at each issue's metadata alone. The mint canonicalizes the whole issue, and a gate's timeout, a time.Duration held as nanoseconds, is a number outside the I-JSON exact-integer range once it is past 2^53-1 ns (about 104.25 days). The mint refuses every write to such a gate, the scan cleared the switch over it, and the first write after that failed. CheckIssueVersionable is now exactly canonicalDurableState's refusal over the whole issue, and FindUnversionable runs it over every issue the mint would version. It replaces FindUnversionableMetadata, and CheckMetadataVersionable is gone, so no check over part of an issue is exported beside the one the mint runs. A refusal names the top-level field it found the value in ("metadata", "timeout") as well as the literal, on the mint and on the scan; the field is located only after a refusal, so a write that is admitted still reads the document once. A gate timeout above 2^53-1 ns is unrecordable by policy: it is refused at the write, named by field and documented, not re-encoded. The refusal at the switch gives the fix for each field. For a number in metadata that is bd update --metadata or --unset-metadata, which works with history on or off because a version is recorded from the state after the write. For a gate timeout, which bd update cannot change, it is removing the gate with bd delete, or setting the timeout_ns column with bd sql while history is off; bd sql needs a server-backed store, and the text says so. It also says the check runs once, now: a writer that does not record (an older bd, bd sql, a pull from a clone that had history off) can add such a row afterwards, and the first write to it then fails with the same refusal. Making the check and the write of the setting one transaction would narrow that window, not close it. Corrected in the comments, the docs and the changelog as well: an import is not a path that skips the mint, since it goes through the same batch create; and Dolt's JSON column collapses duplicate keys when it stores a document, so on a Dolt store neither the scan nor the mint can see one, and the duplicate-key refusal is a defence for a backend that keeps them. * test(fix): red — the listing must answer as the as-of read does; the SDK opens must be accounted for Three review findings on the versioned-history change and one wording fix, tests first. - A removed version's restriction. AsOfReadInTx answers a stored value outside the four-value vocabulary (a NULL or empty column, "live", a hyphenated or arbitrary string) as unknown, but ListVersionsInTx hands the column back as stored, for every row, and the label bd versions prints passes such a string through. A table test runs the listing and the as-of read on the same stored value, for a version that was removed and one that was not, and expects the same answer, and none for a version that was never removed. The label gets the same out-of-vocabulary values and is expected to render what unknown renders. - The SDK's store opens. The shared construction guard now scans the repository root as well, so the Go SDK's five opens (Open, OpenFromConfig and OpenGated, and OpenBestAvailable in each build-tag twin) are noticed. Nothing accounts for them yet, so both guards fail on exactly those five sites. - A bytes bound beside the allocation-count bound on the number admission gate. A classifier that builds the number it is asked about makes one allocation whatever the exponent, so the count bound passes it, and the bytes grow. The fewest bytes one call allocates for a literal with a huge exponent must be no more than for a small one plus a margin. It passes today, because the gate never builds the number; it fails for a gate that does. - The refusal at the switch names the gate remedy as bd delete <id> --force, says that without --force bd only previews, and says that removing the gate unblocks anything it was blocking. The embedded and proxied end-to-end tests expect all three. * fix: green — the listing answers as the as-of read does; the SDK opens are accounted for Three review findings on the versioned-history change and one wording fix. A removed version's restriction. A stored removed_restriction is a free string, and only the four values of the vocabulary are answers. The as-of read already reported anything else (a NULL or empty column, "live", a hyphenated or arbitrary string) as unknown, but the listing handed the column back as stored, for every row, and the label bd versions prints passed it through. NormalizeRemovedRestriction is now the one place that decision is made. AsOfReadInTx calls it; ListVersionsInTx calls it for a version that was removed and gives a version that was not removed no restriction; and restrictionLabel renders through it. The listing, its JSON and the label now say what the as-of read says for the same row. The SDK's store opens. The Go SDK's five opens (Open, OpenFromConfig and OpenGated, and OpenBestAvailable in each build-tag twin) apply neither per-store switch, the events journal's or versioned history's, and they still do not. Applying them would change the library's behavior for every embedder, so that is a separate change; this one declares the boundary. The shared construction guard now accounts for the five with one exemption reason that is true of both switches, so a new SDK open is noticed rather than missed, and its staleness check keeps the exemptions honest. The docs gain one bullet saying that writers built on the SDK do not apply the switch. The bytes bound on the number admission gate needs no production change: the gate never builds the number, which is what the bound pins. The refusal at the switch now names the gate remedy as bd delete <id> --force, says that without --force bd only previews, and says that removing the gate also unblocks anything it was blocking. The docs line says the same. For a gate that blocks an issue, bd delete without --force prints a preview and exits 1, and with --force the gate is removed and what it blocked is ready again. * test(bazel): declare the root package's Go source as data for //cmd/bd:bd_test The shared store-construction scan now reads the repository root, where the Go SDK's opens live, but //cmd/bd:bd_test declared none of the root package's source. Under bazel test the scan therefore saw an empty directory, reported the five SDK exemptions as no longer matching a store construction site, and failed the events-journal guard, while go test, which sees the whole checkout, passed. List the root in tools/bazel/go_srcs.py so the generator emits its managed go_srcs filegroup there, and add that filegroup to bd_test's data. The new block is the generator's own output and nothing else changes. * ci: list the switch scan's proxied gate-timeout test in the 30-shard manifest Upstream main (#7129) moved the proxied-server tier to 30 duration-balanced shards, and TestProxiedShardManifestGeneratorNotStale requires every TestProxiedServer*/TestServerMode* test exactly once in that block. This branch adds TestProxiedServerVersionedHistorySwitchRefusesAnUnrecordableGateTimeout (cmd/bd/versioned_history_switch_scan_proxied_integration_test.go), so the block needs its line. Written by the generator itself: python3 scripts/ci/gen_proxied_shard_manifest.py 30 --weights=duration --write (one line, shard 8); --check exits 0 afterwards. Rebase note (maintainer): regenerated on current main, whose proxied-server tier uses 34 shards; the generator's incremental output (gen_proxied_shard_manifest.py 34 --weights=duration --write) placed this test at shard 6 of the 34-shard block. * ci: list the PR's embedded versioned-history tests in the embedded shard manifests #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 five embedded cmd tests and three embedded storage 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: 8 lines added, none moved. Rebase note (maintainer): regenerated on current main, whose embedded manifests use 100 cmd shards and 40 storage shards; the generator's incremental output placed these tests at cmd shards 55 (TestEmbeddedVersionedHistorySwitchScansEveryRowNotOnePage), 56 (...SwitchRoundTrip), 57 (...SwitchRefusesUnversionableMetadata), 58 (...SwitchRefusesAnUnrecordableGateTimeout) and 59 (...SetManyRefusesUnversionableMetadata) of the 100-shard block, and at storage shards 5 (TestRecordVersionKeepsSubSecondChangeAt), 6 (TestVersionedHistoryKeepsNumbersTheStoreDistinguishesApart) and 23 (TestAsOfReadContract) of the 40-shard block. * test: exempt OpenBestAvailableWith, where #7188 moved the SDK's store construction Upstream #7188 split beads.OpenBestAvailable: it now delegates to the new OpenBestAvailableWith, which builds the store. This PR's two construction guards (TestEveryStoreConstructionActivatesTheEventsJournal and TestEveryStoreConstructionActivatesVersionedHistory) share one exemption list keyed by function, so after merging main they flagged OpenBestAvailableWith as an unexempted construction site and reported the OpenBestAvailable entries as stale. The two build-tag twins' keys now name OpenBestAvailableWith. The reason is unchanged: it is the SDK's library surface for embedders, and no code in the bd binary calls it. gofmt realigned the three neighbouring entries. * chore(schema): renumber removed_restriction to 0071 after #6943's 0070 Migrations are numbered by landing order. #6943 (participation_generation, the versioned-history write fence) lands first and owns main-plane 0070 and ignored/0028, so this PR's removed_restriction migration moves to the next free slot, 0071. 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; the intermediate commits of the rebase carry a duplicate 0070 and are not expected to build. - migrations/0070_add_removed_restriction.{up,down}.sql become 0071_*, with their header comments updated (the SQL itself is unchanged). Neither file exists on main or on #6943, so this is not an edit to a shipped migration. - cli_migrations.go: the CLI-bundle override is keyed to the new file name and renamed cliMigration0071AddRemovedRestriction, and its const now sits after 0070's. - migration_0070_add_removed_restriction_test.go becomes migration_0071_add_removed_restriction_test.go; its tests and messages say 0071, and it now owns the one LatestVersion pin (71). TestLatestVersionIncludesMigration0070 in #6943's participation_generation test is superseded by it and replaced by the usual pointer comment, and 0069's pointer comment now names the 0070 file that superseded it. - schema_test.go hygiene comments, BUILD.bazel embedsrcs/srcs, and the asof_read.go comment that cited the migration number. Checked: go test ./internal/storage/schema/... (with the dolt CLI lane, including TestAllMigrationsSQLAppliesThroughDoltCLIAndRecordsLatestVersion) and scripts/check-migration-hygiene.sh against origin/main and against #6943's tip. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(versions): reconcile #6661's tests and docs with #6943's write fence #6943's write fence (design §16.2b) makes an update-shaped write to a legacy record -- one whose participation_generation is NULL because it was created while versioned history was off -- a skip, not a refusal: the fence returns before the snapshot is canonicalized, so nothing is versioned and the mint's admission gate never runs. Several of #6661's tests seed rows with history off and then expect a later write to them to be versioned or refused, and several comments say every later write to an offending row fails. On a tree that carries both PRs those tests fail and those comments are wrong. This ports, without changing their substance, the fence-integration commits Jim Wordelman wrote for the donnabox integration fork, where both PRs were already folded together: - eff898db80 / 5d2e5a2ac4 (issueops, dolt, embeddeddolt): the mocked mint sequence scripts the fence's participation_generation read; the number fidelity test splits phase 2 into 2a (a legacy row is written, not versioned, not refused, stays NULL) and 2b (a participating row is refused and left untouched); TestRecordVersionInTxSkipsALegacyRowBefore- TheAdmissionGate pins the fence's order against the gate. - e0ad9d1e3c / 1528022dfa (cmd/bd): the switch round trip and the routing/env end-to-end tests build the rows they expect a version for after the setting is on, and assert that the pre-setting seeds gain nothing. - 18b9015bf5 (cmd/bd): the embedded and proxied gate-timeout scan tests assert the whole scan-vs-mint truth table (legacy offenders are named by the scan but not refused by the mint; participating offenders are both). - 5929ebd50c / 8ce872be03 (comments, CHANGELOG, configuration reference): the mint's refusal binds rows that participate in history; the pre-enable scan cannot see participation, so it over-approximates in the safe direction. Left out on purpose: the fork's mintSkipsRow helper and defer-wake sweep change, and its bd doctor "Versionable Issues" check and the docs that point at it; none of those are part of #6661 or #6943. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: Jim Wordelman <jim@wordelman.name> * test(versions): adapt #6661's guards to what main changed under it Three test-side adjustments for code that landed on main after #6661's last merge of it; no production code changes. - internal/storage/leg_contract_wiring_test.go: main gained an HTTP storage leg, and TestEveryLegWiresEveryRoleContract requires every leg to name or waive every role contract. The five R7.1 as-of read contracts this PR adds are a storage capability the HTTP client does not serve (internal/httpclient answers AsOf with an explicit unsupported error, and the wire has no instant/address selector or gone/unknown refusal), so they are waived on the http leg with that reason, as the donnabox integration fork does. - cmd/bd/versioned_history_construction_test.go: main split newDoltStoreFromConfig into two thin wrappers over openDoltStoreFromConfig, which is where the activation defer now lives (this rebase's resolution of the activation commit), so the factory guard keys on that body. - cmd/bd/versioned_history_serve_e2e_test.go: main's TestProxiedGatedTestsRunInTheProxiedLane requires a test that skips unless BEADS_TEST_PROXIED_SERVER=1 to be one the proxied lane selects, so TestVersionedHistoryServeActivatesTheProviderFromItsOwnRow becomes TestProxiedServerVersionedHistoryServeActivatesTheProviderFromItsOwnRow, and the 34-shard proxied manifest gains its line (written by gen_proxied_shard_manifest.py 34 --weights=duration --write, incremental; --check passes). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * chore(bazel): emit go_srcs.py's managed blocks for internal/versionedhistory Main's tools/bazel/go_srcs.py now manages a repo_files filegroup block in every package BUILD file, lists those filegroups in the root BUILD.bazel's aggregates, and lists every go_library in tools/bazel's release_cross_build target. internal/versionedhistory is a package this PR adds, so after the rebase those managed blocks were stale and TestBazelGoSrcsBlocksCurrent (go test ./scripts/...) failed. This is the generator's own output (python3 tools/bazel/go_srcs.py) and nothing else; --check passes afterwards. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(versions): don't publish change_agent in bd versions --json `bd versions <id> --json` prints storage.IssueVersion as-is, so every JSON tag on that struct is part of a public contract. Provenance V2 (gastownhall/beads#7510, as ruled by the maintainer) removes the ad hoc agent field in favour of an actor chain; shipping a "change_agent" key now would make a public contract out of a field that is on its way out. IssueVersion.ChangeAgent is now tagged json:"-". Nothing else changes: the issue_versions.change_agent column (migration 0067) stays, ListVersionsInTx still reads it, change_actor and change_message are still published, and the human listing never showed the agent. No doc or golden named the key. TestVersionsJSONDoesNotPublishChangeAgent pins the absence with a non-empty value, so an omitempty-style regression would still fail, and pins that change_actor and change_message are still there. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(issueops): pin what the unfenced test-support mint does on #6943's new paths #6943's two fixes to the shared mint body -- (a) no issues row means no mint and no error, and (b) a create-shaped call on a new issues-table row flagged no-history stamps participation_generation without minting -- were written for its two kinds. This PR's shared body has a third, mintUnfenced, behind RecordVersionAtInTx (the R7.1 as-of fixtures' controlled-timestamp mint). The rebase resolution decided what (a) and (b) mean for it; this pins that decision: - (a) applies. It is the plane rule (FR-8: the table that holds the row decides its plane), not the fence, and the unfenced kind already honoured the flag-based form of the same rule (IsWisp). Without it, an unfenced mint for an unflagged wisps-table row would insert a version row that no issues row points at. The shared body's issues-table read now runs for all three kinds; only the update kind acts on the value it reads. - (b) does not apply. The unfenced mint never declares participation, so a flagged row returns right after the snapshot, as before: no read, no stamp. - The fence still does not apply: a legacy row is minted, and the closing UPDATE advances current_revision alone. TestRecordVersionAtInTxKeepsThePlaneRuleButNotTheFence scripts each of those three sequences exactly with sqlmock. TestTestSupportMintsStayOutsideTheShapeSplit places RecordVersionAtInTx outside #6943's create / dual-shape / update classification explicitly (it is the seam's exempt twin, not a mutation entry point or mint site): it must be in none of the shape lists, stay in versionExemptions, and reach neither RecordVersionForCreateInTx (it never stamps) nor RecordVersionInTx (whose gate and fence would stop the as-of fixtures minting history-off rows). The row-lock guard's exemption comment for recordVersionAtInTx already names the stamp-only UPDATE: #6943's own wording of it (all three UPDATE issues statements) was carried into that exemption when the as-of read commit was replayed. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(storage): say exactly why the as-of read contracts stay waived on http #6943 now runs most of its participation-generation contracts 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. This checked whether the five R7.1 as-of read contracts can be wired the same way. They cannot, cheaply or otherwise, without a new wire operation: - their subject is the read itself (AsOfReadFixture.Resolve), and R7.1's read, issueops.AsOfReadInTx, is reached by no publicops role and served by no wire operation; - the wire carries neither selector (an instant or a served version address) nor the gone/unknown refusal the read answers with; - the client's only point-in-time read, DoltStorage.AsOf, is a Dolt commit-ref read, not R7.1, and is on the client's D8 unsupported allowlist. Binding Resolve 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 waiver stays; its comment and reason string now say the above instead of the earlier shorthand ("HTTP AsOf is explicitly unsupported"), which conflated the client's commit-ref AsOf with R7.1. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * docs(versions): describe what the write fence does to beads that predate recording With #6943's write fence (design §16.2b) a bead that existed before versioned history was turned on (participation_generation NULL) is legacy: an update-shaped write to it is skipped, so it is never versioned however often it is edited. Several user-facing strings from #6661 still described the behaviour before the fence, and an independent review reproduced each with a built bd (a legacy bead edited twice after enabling still lists no versions; a legacy bead the switch refuses over is written without refusal under BD_VERSIONED_HISTORY_ENABLED=1). Text only; no behaviour changes. - bd versions help: only beads created while recording is on are versioned; a bead that already existed is legacy and editing it records nothing; no backfill. (Was: "a bead edited yesterday shows nothing until it is edited again".) - bd versions empty listing: drops "yet" and says why the list is empty -- a bead created while recording is on always has its create version, so an empty list means the bead predates recording (or was made by a writer that was not recording), or is no-history or a wisp. The line still starts "No versions recorded for <id>", which the switch round-trip test pins. - bd versions with recording off: only beads created after it is turned on are versioned. - bd config set versioned-history.enabled true refusal: Jim's scan stays as conservative as he made it -- it cannot see participation, and a legacy row can still be minted create-shaped if it re-enters the issues plane -- but the text now says a listed issue's writes are refused only if it participates (created while history was on, or entered the issues plane while it was on), and that legacy issues are listed because the check cannot tell. The closing line says the same of a value a non-recording writer adds later. - docs/reference/configuration.md: the section opener says every accepted change to an issue created while history is on is snapshotted, and that a pre-existing issue is legacy; the "participates" parenthetical drops "or written" (a write never stamps participation; only a create-shaped mint does) and names entering the issues plane, matching the refusal text. CHANGELOG already says "if it participates in history" and is unchanged. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(versions): keep updated_at across update-shaped version mints The update-shaped mint ended with UPDATE issues SET current_revision = ? WHERE id = ?. current_revision always changes there, so the column's ON UPDATE CURRENT_TIMESTAMP clause fired: with versioned history on, every label, dependency or import write moved issues.updated_at to the session's wall clock (local time, read back as UTC). An import with RejectStaleUpserts then stored the wall clock instead of the source's updated_at, and the source's next genuine edit was rejected as stale. The statement now assigns updated_at to itself, the rule #4298, blocked_state.go's mark/unmark templates and the create-shaped mint statements already follow, so history on leaves updated_at exactly where history off does. It is the one statement every production update-shaped mint ends with. Tests: - TestEmbeddedMintLeavesUpdatedAtWhereHistoryOffDoes (embeddeddolt) ages a bead, adds and removes a label and a dependency, and runs two RejectStaleUpserts imports, with history off first as the control. With the fix reverted, history on fails all six arms (updated_at reads the wall clock, and the later source edit is rejected as stale); history off passes either way. - RunParticipationGenerationFlagOffSkipsUpdateOnParticipatingRecord, wired on the dolt, embeddeddolt, uow and http legs: a record created with the flag on and updated with it off mints nothing and keeps its current_revision. Every other flag-off case uses a legacy record, which the fence stops first, so with RecordVersionInTx's gate removed this is the only case that fails, on all four legs. That gate is the single entry for every production update-shaped mint, so the one update arm covers label and close writes too. - The sqlmock pin of the statement (version_history_preenable_scan_test.go) and the journal-completeness exemption comment follow the new SQL. - The createbatchequiv issues_updated_at goldens of small, depadd, import458 and import458-reject-stale are re-recorded. They pinned the wall-clock bump, so each row minted a second time (eq-n2; eq-db1 and eq-dl; eq-b3 and eq-b250) had dropped out of the compared set; CI's embedded and server legs both printed the new digests. Recorded on embedded Dolt, the fix-reverted tree reproduces every committed golden byte for byte, HEAD moves only these four digests, and its rows equal the history-off rows in every scenario. GoldenDirEnv's comment lists it as the goldens' third deliberate change. - The new embedded test has its line in the storage shard manifest (gen_embedded_storage_shard_manifest.py 40 --weights=duration --write), so TestStorageEmbeddedShardManifestGeneratorNotStale stays green. It sits after TestEmbeddedEveryAcceptedLifecycleMutationMintsOneVersion rather than at the end of the file, where #7646 appends its own test, so the two PRs still merge without a conflict in that file. Docs: - CHANGELOG: the feature's two entries under ### Fixed described fixes to a switch no released bd has. One ### Added entry replaces them, covering bd versions, the versioned-history.enabled switch and its per-store semantics, the pre-enable check, the single-writer caveat, migration 0071 and the bd version <arg> refusal. - The bd versions help, its recording-off refusal and empty-listing note, and the opening paragraph of the configuration doc's Versioned Issue History section now state the rule the pre-enable refusal prints: a bead participates if it was created, or entered the issues plane (a wisp promoted or made persistent), while recording was on. bd version: the "did you mean bd versions" refusal now runs after the command's metrics event is created, like the other in-RunE argument refusals, so a mistyped bd version <id> is counted as a version invocation instead of going uncounted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen --------- 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>
48 KiB
| title | description |
|---|---|
| Configuration | Complete reference for bd configuration across config.yaml and database-stored settings, with precedence, secrets, auto-commit, backup, and integrations. |
Complete configuration reference for beads.
Last reviewed: 2026-09-10
Freshness source: cmd/bd/main.go, cmd/bd/config.go, and internal/configfile/.
beads has two complementary configuration systems:
- Tool-level configuration (YAML, managed by Viper) — startup flags and tool behavior, stored in
config.yamlfiles. These are user preferences: output format, auto-commit behavior, CLI ergonomics. - Project-level configuration (managed by
bd config) — integration credentials, status maps, and project-specific settings, stored in the Dolt database. Some keys are routed toconfig.yamlinstead (see YAML-only keys below).
The split is deliberate: tool settings are user-specific; project config is team-shared and travels with the database when you run bd dolt push. That is also why secrets are refused in the database — see Security.
Dolt is the only storage backend. Embedded mode (the default) stores data at .beads/embeddeddolt/; server mode (bd init --server or BEADS_DOLT_SERVER_MODE=1) uses .beads/dolt/. See Dolt architecture.
Configuration Locations
config.yaml is searched in this order, with later files overriding earlier ones:
~/.beads/config.yaml(legacy user-level, lowest priority)~/.config/bd/config.yaml(user-level; this exact path is checked even on platforms whose native user-config directory differs)<repo>/.beads/config.yaml(project-level, walked up from the current directory)$BEADS_DIR/config.yaml(highest priority, whenBEADS_DIRpoints at a different workspace)
A config.local.yaml next to the project config.yaml is also merged in last for machine-specific overrides that should not be committed.
Precedence
For Viper-managed (YAML) keys, highest to lowest:
- Command-line flags (e.g.
--json,--db,--actor) - Environment variables (
BD_*, plus a small set of legacyBEADS_*names — see below) config.yamlfiles (in the order listed above)- Built-in defaults
Project-level keys written via bd config set (Jira, Linear, GitHub, status maps, etc.) live in the Dolt database. They are read at command time and have no env var override.
When a config.yaml value or environment variable shadows a database key, bd config list prints an override warning, and bd config show reports the source of every effective key.
Managing Configuration
# Set a value (auto-routes to config.yaml or the database)
bd config set jira.url "https://company.atlassian.net"
bd config set validation.on-create warn # YAML-only key
# Set many values in one go (single auto-commit; validates before writing)
bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ
# Get a value
bd config get jira.url
bd config get --json jira.url
# → {"key":"jira.url","value":"https://company.atlassian.net"}
# List all database-stored config (with override warnings)
bd config list
# Show all effective config with provenance (env / config.yaml / default / database)
bd config show
bd config show --source config.yaml
bd config show --json
# Validate sync-related configuration
bd config validate
# Remove a value
bd config unset jira.url
bd config set automatically routes the write to the right location: keys in the YAML namespace (see below) are written to the project config.yaml; everything else is written to the Dolt database. beads.role is stored in git config.
Unrecognized keys produce a warning with a did-you-mean suggestion; use the custom.* namespace for user-defined keys.
YAML-only Keys (Startup Settings)
These keys must live in config.yaml, not the database, because they are read before the database is opened. Writing them with bd config set automatically updates config.yaml.
The full namespaces routed to YAML are:
routing.*, sync.*, git.*, directory.*, repos.*, external_projects.*, validation.*, lint.*, hierarchy.*, ai.*, backup.*, export.*, dolt.*, federation.*, metrics.*, list.*, audit.*, storage-class.*
lint.* holds lint settings: lint.sections.<type> is a comma-separated, additive list of sections that bd lint additionally requires for issues of that type (built-in required sections still apply; unset means no behavior change).
Plus these individual keys:
no-db, json, db, actor, identity, no-push, no-git-ops, agent.profile, create.require-description, import.auto, import.path, prime.max-memories, prime.max-memory-chars, prime.disabled, memories.budget-chars, and the secret keys github.token, gitlab.token, jira.api_token, ado.pat, linear.api_key, linear.oauth_client_id, linear.oauth_client_secret, notion.token.
Any key whose name contains api_key, api-key, secret, token, or password is treated as a secret: it is refused on git-tracked config.yaml files unless you pass --force-git-tracked. Prefer exporting the value as an environment variable instead (e.g. LINEAR_API_KEY).
bd config unset on one of these secret keys clears the config.yaml entry and also deletes any copy an older bd stored in the database, reporting which of them it removed. Keys reached YAML routing at different points in bd's history, so a workspace configured before the move can still hold the value in a table that bd dolt push replicates. The database half is best effort: the command never creates a database to look in, so it is skipped where reaching the row would mean provisioning one — but not for a server-mode or proxied workspace whose database is real and simply not on local disk; a database that refuses the delete is reported as a row that is still stored. Deleting it locally does not unpublish it — rotate a secret that has already been pushed.
Tool-Level Settings (config.yaml)
| Setting | Flag | Env Var | Default | Description |
|---|---|---|---|---|
json |
--json |
BD_JSON |
false |
JSON output for scripting |
db |
--db |
BD_DB |
(auto-discover) | Database path |
actor |
--actor |
BEADS_ACTOR |
git config user.name |
Actor name for audit trail (see Actor identity) |
identity |
--identity |
BEADS_IDENTITY |
(git user / hostname) | Sender identity for bd mail |
no-db |
--no-db |
BD_NO_DAEMON (related) |
false |
Run without opening the database |
no-push |
--no-push |
BD_NO_PUSH |
false |
Skip pushing to the remote in bd dolt push |
no-git-ops |
— | — | false |
Disable git ops in bd prime close protocol |
agent.profile |
— | BD_AGENT_PROFILE |
conservative |
Policy profile bd prime uses for git/commit authority: conservative, minimal, team-maintainer; invalid values fall back to conservative |
prime.max-memories |
--max-memories |
BD_PRIME_MAX_MEMORIES |
0 |
Max persistent memories injected by bd prime (0 = unlimited) |
prime.max-memory-chars |
--max-memory-chars |
BD_PRIME_MAX_MEMORY_CHARS |
0 |
Max total bytes of memory entries injected by bd prime, at whole-memory boundaries (0 = unlimited) |
prime.disabled |
— | BD_PRIME_DISABLED |
false |
When true, bd prime prints nothing, as outside a workspace (an empty envelope under --hook-json), whatever its other flags. Set it in the environment of sessions whose host briefs the agent itself but that inherit a project's bd prime hook |
memories.budget-chars |
— | BD_MEMORIES_BUDGET_CHARS |
0 |
Ceiling on the whole persistent-memory corpus, in bytes of len(key)+len(content) summed over every memory (0 = off). bd remember refuses a write that would cross it — pass --force to store anyway — and warns on a write that lands at or above 80% of it. Read at bd remember time only; bd prime injection is capped separately by prime.max-memory-chars |
dolt.auto-commit |
--dolt-auto-commit |
BD_DOLT_AUTO_COMMIT |
on |
off|on|batch: on creates a Dolt history commit after each successful write; batch/off defer it to bd dolt commit (see below) |
dolt.auto-push |
— | BD_DOLT_AUTO_PUSH |
false |
Auto-push to Dolt remote after writes (opt-in; see below) |
dolt.auto-push-interval |
— | BD_DOLT_AUTO_PUSH_INTERVAL |
5m |
Minimum time between auto-pushes |
dolt.auto-push-timeout |
— | BD_DOLT_AUTO_PUSH_TIMEOUT |
30s |
Timeout for a single auto-push attempt |
dolt.shared-server |
--shared-server |
BEADS_DOLT_SHARED_SERVER |
false |
Share one Dolt server at ~/.beads/shared-server/ |
dolt.max-conns |
— | BEADS_DOLT_MAX_CONNS |
10 |
Connection pool size |
git.author |
— | BD_GIT_AUTHOR |
(none) | Override commit author for beads commits |
git.no-gpg-sign |
— | BD_GIT_NO_GPG_SIGN |
false |
Disable GPG signing for beads commits |
create.require-description |
— | BD_CREATE_REQUIRE_DESCRIPTION |
false |
Require description on bd create |
validation.on-create |
— | BD_VALIDATION_ON_CREATE |
none |
Template validation: none, warn, error |
validation.on-close |
— | BD_VALIDATION_ON_CLOSE |
none |
Template validation on close |
validation.on-sync |
— | BD_VALIDATION_ON_SYNC |
none |
Template validation before sync |
validation.metadata.mode |
— | — | none |
Metadata schema validation |
hierarchy.max-depth |
— | — | 3 |
Max hierarchical ID nesting depth |
backup.enabled |
— | BD_BACKUP_ENABLED |
false |
Enable periodic Dolt-native backup to .beads/backup/ (see below) |
backup.interval |
— | BD_BACKUP_INTERVAL |
15m |
Minimum time between auto-backups |
backup.git-push |
— | — | false |
Auto-push backup repo |
backup.git-repo |
— | BD_BACKUP_GIT_REPO |
(none) | Path to a local git repository (~/ expands); when set, auto-backup syncs to a backup/ directory inside it. A path without .git falls back to .beads/backup/ with a warning |
backup.size-cap-mb |
— | BD_BACKUP_SIZE_CAP_MB |
2048 |
Pause auto-backup once the destination directory reaches this size; 0 disables the cap (see below) |
backup.size-warn-interval |
— | BD_BACKUP_SIZE_WARN_INTERVAL |
24h |
Minimum time between repeated "auto-backup paused" warnings |
audit.enabled |
— | BD_AUDIT_ENABLED |
false |
Enable the optional JSONL interaction sidecar at .beads/interactions.jsonl, written by bd audit record / bd audit label. While disabled, bd init does not create the file and bd audit record / bd audit label refuse to write. Issue history is always recorded in the database either way — see bd history <id> --events |
export.auto |
— | — | false |
Refresh .beads/issues.jsonl export after every write; not cross-machine sync |
export.path |
— | — | issues.jsonl |
Output filename relative to .beads/ |
export.interval |
— | — | 60s |
Minimum time between auto-exports |
export.git-add |
— | — | false |
Run git add on the export file |
import.auto |
— | BD_IMPORT_AUTO |
true |
Master switch for automatic JSONL imports: the git-hook fallback used when no Dolt remote is configured, and the empty-database recovery import when .beads/issues.jsonl exists but the database is empty. false disables all auto-imports; explicit bd import always works |
import.path |
— | — | issues.jsonl |
Input filename relative to .beads/ for implied JSONL imports (including bd init --from-jsonl and empty-DB auto-import); use relative paths for portability |
routing.mode |
— | — | (none) | Multi-repo routing: auto, maintainer, contributor, explicit |
routing.default |
— | — | . |
Default routing target |
routing.maintainer |
— | — | . |
Maintainer-routed path |
routing.contributor |
— | — | ~/.beads-planning |
Contributor-routed path |
list.limit |
--limit / -n |
BD_LIST_LIMIT |
50 |
Default limit for bd list results |
directory.labels |
— | — | {} |
Map directory patterns → labels for monorepos |
external_projects |
— | — | {} |
Map project names → paths for cross-project deps |
federation.remote |
— | BD_FEDERATION_REMOTE |
(none) | Dolt remote URL (dolthub://, gs://, s3://, az://, file://) |
federation.sovereignty |
— | BD_FEDERATION_SOVEREIGNTY |
(none) | Sovereignty tier: T1, T2, T3, T4 (see below) |
federation.allowed-remote-patterns |
— | — | [] |
Glob patterns restricting allowed remote URLs |
federation.exclude_types |
— | — | [wisp] |
Issue types excluded from federation push |
sync.require_confirmation_on_mass_delete |
— | — | false |
Prompt before pushing when a merge deletes most issues |
output.title-length |
— | — | 255 |
Title display in feedback (0 hides); see routing note below |
ai.model |
— | BD_AI_MODEL |
claude-haiku-4-5-20251001 |
Default AI model |
agents.file |
— | — | AGENTS.md |
Agents instruction filename; see routing note below |
export.auto and export.git-add are disabled unless configured explicitly.
.beads/issues.jsonl is an optional export for viewers, interchange, and
issue-level migration. It is not the canonical source of truth, not
cross-machine sync, and not a full database backup.
Workflows that depend on a fresh, git-staged JSONL file should opt in:
bd config set export.auto true
bd config set export.git-add true
Use bd dolt push / bd dolt pull for sync and bd backup for restorable
database backups.
Routing note: output.title-length and agents.file are functionally tool-level settings, but bd config set writes them to the Dolt database. They are typically read from config.yaml when set there directly.
bd config show is the source of truth for what's currently effective on your machine, including provenance.
Dolt History, Backup, and Push
Three post-write behaviors run after each successful write command, in this order: auto-commit, auto-backup, auto-push.
Auto-commit: SQL Commits vs Dolt Commits
There are two different kinds of "commit":
- SQL transaction commit — what happens when a
bdcommand updates tables successfully (durable in the Dolt working set). - Dolt version-control commit — what records those changes into Dolt history (visible in
bd history, and what push/pull/merge workflows operate on).
By default (dolt.auto-commit: on), bd creates a Dolt history commit after each successful write command, so changes are never left only in the working set. The cost is more Dolt commits over time — one per write command — which is intentional; use bd compact to squash old history.
Disable for a single command:
bd --dolt-auto-commit off create "No history commit for this one"
Or in config.yaml:
dolt:
auto-commit: off
batch and off defer the Dolt history commit instead of skipping the write: the change is
still durable in the working set, and bd dolt commit records the accumulated batch as a single
Dolt commit. This applies on every storage mode — embedded, direct SQL-server, and
proxied-server. In proxied-server mode the deferral covers the writes the CLI makes on that
route, including workspace config and version metadata, and bd dolt commit is the only flush
point there: the SIGTERM/SIGHUP flush of a live batch-mode process needs an open store, which
proxied mode never has (it does run in embedded and direct SQL-server modes).
Two kinds of write stay outside the deferral, in every mode:
- Explicit commit points —
bd batch(whose commit message defaults to a synthesized one when-mis absent, so every batch commits),bd mol bond,bd mol pour,bd mol squash,bd mol wisp create, and the wisp half ofbd mol burn— commit what they wrote, with the message they were given: the commit is that command's contract rather than auto-commit policy. Burning a persistent molecule is an ordinary delete, so it honors the policy and defers with everything else. - Writes made by a
bd serveprocess, whose HTTP API requests carry their own context instead of the CLI's, so a daemon keeps committing per write even while the CLI on the same database defers.
Auto-backup
Periodic Dolt-native backup to .beads/backup/ provides a recovery path independent of the live database. Local Dolt commits (via dolt.auto-commit) remain the primary safety net; backup is a secondary layer. Unlike bd export or .beads/issues.jsonl, this is a full database backup: it preserves tables, branches, commit history, and working-set data.
backup:
enabled: true # Enable auto-backup after write commands
interval: 15m # Minimum time between auto-backups
size-cap-mb: 2048 # Pause auto-backup once the destination reaches this size; 0 disables the cap
size-warn-interval: 24h # Minimum time between repeated "paused" warnings
How it works:
- After each write command,
bdcompares the Dolt HEAD commit hash against the last backup state. - If data changed and the throttle interval has passed,
bdchecks the destination directory's on-disk size againstbackup.size-cap-mb.CALL DOLT_BACKUP('sync', ...)only ever adds new chunks to the destination — it never prunes ones that became unreachable on the source (history rewrites, superseded data), and Dolt exposes no supported way to GC a backup destination in place. Left uncapped, the destination can only grow until disk fills; this was the root cause of a 2026-06-19 outage where a 1.7GB store produced a 43GB backup directory. Once the cap is reached, auto-backup pauses — nothing is deleted, but no further syncs run until you raisebackup.size-cap-mbor pointbackup.git-repoat a different git repository, whosebackup/directory then becomes the destination.bd backup initdoes not end the pause: it configures the separate destination that manualbd backup syncpushes to. Setsize-cap-mb: 0to disable the cap entirely. - If the destination is under its cap, a Dolt-native backup is synced to
.beads/backup/(or to abackup/directory insidebackup.git-repowhen configured). - State is tracked in
backup_state.jsoninside the backup directory.bd backup statusprintsPAUSED (cap exceeded)when the destination is over its cap, and its--jsonoutput reports the same state assize_cap.exceeded: true— so an agent/CI caller relying on--jsonor--quietcan see that auto-backup has stopped instead of reading a reassuring "Last backup" line while nothing further syncs. - The cap applies only to auto-backup; manual
bd backup/bd backup syncare not capped.
Manual commands (see bd backup):
bd backup init <path> # Register a destination (filesystem or DoltHub URL)
bd backup sync # Push to the configured destination
bd backup restore [path] # Restore from a backup (--force to overwrite)
bd backup remove # Unregister the destination
bd backup status # Show configuration and last sync time
Auto-push
By default, bd does not push automatically after write commands. Auto-push is explicit opt-in because concurrent pushes to git-protocol Dolt remotes can corrupt or strand remote history when multiple writers race.
dolt:
auto-push: true # Explicit opt-in; safe for single-writer setups
auto-push-interval: 5m # Minimum time between auto-pushes
auto-push-timeout: 30s # Bound one push attempt when the remote is unreachable
How it works:
- After each write command (after auto-commit and auto-backup),
bdchecks whether a push is due. - Pushes are debounced: skipped if the last push was less than
dolt.auto-push-intervalago. - Change detection: skipped if the Dolt HEAD commit hasn't changed since the last push.
- Push failures are warnings only (non-fatal), and failed attempts are throttled too.
- Last push time and commit are tracked in
.beads/push-state.json, a per-machine file (not in the database, to avoid merge conflicts across machines).
Before pushing, bd verifies the local chunk store with dolt fsck --quiet, bounded by a 30-second timeout. For large stores, raise it with the runtime-only BEADS_FSCK_TIMEOUT environment variable (accepts durations like 2m or bare seconds like 90).
Actor Identity Resolution
The actor name (used for created_by and audit trails) is resolved in this order:
--actorflag (explicit override)BEADS_ACTORenvironment variableBD_ACTORenvironment variable (deprecated alias)git config user.name$USERenvironment variable"unknown"(final fallback)
For most developers no configuration is needed — issue authorship matches commit authorship automatically. To override, set BEADS_ACTOR in your shell profile:
export BEADS_ACTOR="my-github-handle"
Project-Level Settings (Database)
These are written to the Dolt database by bd config set and have no env var override, with one exception: versioned-history.enabled also honors BD_VERSIONED_HISTORY_ENABLED (see Versioned Issue History). Common namespaces:
| Namespace | Purpose |
|---|---|
jira.* |
Jira integration (URL, project(s), status_map, type_map, custom_fields) |
linear.* |
Linear integration (team_id(s), priority_map, state_map, label_type_map, relation_map) |
github.* |
GitHub integration (org, repo, label_map) |
gitlab.* |
GitLab integration |
ado.* |
Azure DevOps integration (org, project(s), state_map, type_map) |
notion.* |
Notion integration |
custom.* |
User-defined / custom integrations |
<tracker>.last_sync |
Updated automatically after each tracker sync; enables incremental sync |
status.custom |
Custom statuses with optional behavior categories (see below) |
types.custom |
Comma-separated list of custom issue types |
types.infra |
Infra types routed to the wisps table instead of the versioned issues table |
compact_tier1_days, compact_tier2_days |
Age thresholds in days for bd admin compact tier eligibility (defaults 30 and 90) |
issue_id_mode |
hash (default) | counter (see below) |
min_hash_length, max_hash_length |
Adaptive ID bounds (defaults 3 and 8) |
max_collision_prob |
Hash ID collision tolerance (default 0.25) |
claim.pools |
Comma-separated pool aliases: placeholder assignees that any actor can take with bd update <id> --claim (see below). Unset by default, which turns pool claiming off |
versioned-history.enabled |
true records a version row for every issue write to this store; off by default. Unlike the rest of this table it also honors an environment variable, which can only turn it on (see below) |
doctor.suppress.* |
Suppress specific bd doctor warnings by check slug (warnings only; errors always show) |
Issue prefix (issue_prefix) is not settable via bd config set — use bd init --prefix, bd bootstrap, or bd rename-prefix.
Custom Statuses and Types
Custom statuses supplement the built-ins (open, in_progress, blocked, deferred, closed). Each entry is name or name:category:
bd config set status.custom "in_review:active,qa_testing:wip,on_hold:frozen,archived:done"
The category controls how the status behaves:
| Category | In bd ready |
In default bd list |
|---|---|---|
active |
yes | yes |
wip |
no | yes |
done |
no | no (terminal) |
frozen |
no | no (on hold) |
| (none) | no | yes (backward compatible) |
Custom types extend the built-in issue types:
bd config set types.custom "agent,molecule,event"
Use bd statuses and bd types to list everything configured.
Sequential Counter IDs
By default, beads generates hash-based IDs (e.g. bd-a3f2). For projects that prefer short sequential IDs (bd-1, bd-2, ...), enable counter mode:
bd config set issue_id_mode counter
bd create "First issue" -p 1 # → bd-1
bd create "Second issue" -p 2 # → bd-2
| Value | Behavior |
|---|---|
hash |
(default) Hash-based IDs, adaptive length, collision-safe |
counter |
Sequential integers per prefix: bd-1, bd-2, bd-3, ... |
Counter mode behavior:
- Each prefix (
bd,plug, ...) has its own independent counter, so multi-repo or routed setups don't interleave. - The counter is stored atomically in the database; concurrent creates within a single Dolt session are safe.
- On first use (including switching an existing repository to counter mode), the counter seeds itself from the highest existing numeric ID for that prefix, so new IDs don't collide with old ones.
- An explicit
--idflag onbd createbypasses ID generation entirely; the counter is not incremented. - Counter mode applies only to regular issues, not wisps.
Tradeoff — hash vs. counter:
| Hash IDs | Counter IDs | |
|---|---|---|
| Human readability | Lower (bd-a3f2) |
Higher (bd-1) |
| Distributed/concurrent safety | Excellent (collision-free across branches) | Needs care (counters can diverge on parallel branches) |
| Predictability | Unpredictable | Sequential |
| Best for | Multi-agent, multi-branch workflows | Single-writer or project-management UIs |
Adaptive Hash IDs
Hash IDs size themselves to the database: lengths start at min_hash_length and grow toward max_hash_length to keep the collision probability under max_collision_prob.
bd config set max_collision_prob "0.01" # Stricter collision tolerance (default 0.25)
bd config set min_hash_length "5" # Force minimum 5-char IDs (default 3)
bd config set max_hash_length "8" # Upper bound (default 8)
Claim Pools
A dispatcher can pre-assign issues to a pool alias, a placeholder assignee such as fable-crew, and let any actor take them with bd update <id> --claim. List the aliases in claim.pools:
bd config set claim.pools "fable-crew,night-crew"
Claiming reads this key from the database only. A claim.pools value in config.yaml or in an environment variable has no effect, even though bd config show lists a config.yaml value with the source (config.yaml). A value that claiming uses shows the source (database).
- Exact match. The value is split on commas and each entry is trimmed of surrounding whitespace. An issue counts as pool-assigned only when its assignee equals one of the entries exactly, including case:
Crew-Ais not the poolcrew-a. - Claiming. Taking a pool-assigned issue works like taking an unassigned one: the claimer becomes the assignee, the status moves to
in_progress, and the claim gets the normal lease. - Anti-steal. Issues assigned to a real actor, or to an alias that is not listed, keep their protection:
--claimrefuses them. - Reassigning.
bd assignandbd update <id> --assigneecan move anin_progressissue that a pool alias holds without--force. bd ready --claimtakes only unassigned issues, so it skips pool-assigned ones even thoughbd readylists them. Claim those by ID.- Lease expiry. If the claimer's lease expires,
bd reclaimsets the issue back toopenwith no assignee. It does not return the issue to the pool alias, so a dispatcher that wants it back in the pool has to reassign it.
Versioned Issue History
While versioned-history.enabled is on, every accepted change to an issue that participates in history (one created while it is on, or that enters the issues plane while it is on: a wisp promoted or made persistent) stores a snapshot of it as a row of issue_versions, in the same transaction, and bd versions <id> lists them. It is off by default, and it does not backfill: an issue already on the issues plane when it was turned on is legacy, and editing it records nothing (the write fence, design §16.2b).
bd config set versioned-history.enabled true # turn it on
bd config set versioned-history.enabled false # turn it off
- The switch belongs to the store. It is a row of the database
configtable, sobd config setwrites it there and not toconfig.yaml. Every store answers for itself: a write routed into another workspace (a prefix-routedbd updateorbd close, orbd create --repo) reads the target store's row, never the row of the workspace you launchedbdfrom. - It replicates. The config table travels with
bd dolt pushandbd dolt pull, so enabling it on one clone turns it on for every clone that pulls. - Single writer only. Keep one writer at a time per store, and never two disconnected clones recording. Two writers that each mint the same revision for an issue collide on merge, and the pull fails (
VersionedHistoryConfigurerininternal/storage/storage.go, and #6379 item 4). Because the setting replicates, turning it on is a decision for the whole store, not for one clone. - Turning it on checks the store first.
bd config set versioned-history.enabled truereads every issue the store would version and refuses, writing nothing, while any holds a value a version could not record: a number outside the I-JSON exact-integer range (magnitude above 2^53-1, whatever its spelling, fractions and exponent forms included), in its metadata or in a gate's timeout. A timeout is held as nanoseconds, so a gate that waits longer than about 104.25 days (9007199254740991 ns) is refused. It prints how many issues, which ones (the first 20), what is wrong with each and which field it is in. With history on, a write that introduces such a value already fails at once and commits nothing, and so does a later write to a row that already holds one if that row participates in history (it was created, or entered the issues plane, while history was on); a legacy row, created before history was on, is skipped by the write fence and stays writable, but the check still names it, because it cannot see participation. The fix depends on the field. For a number in metadata, one command per issue, and it works with history on or off:bd update <id> --metadata '{"<key>": "<value as a string>"}'to replace the value, orbd update <id> --unset-metadata <key>to remove the key.bd updatecannot change a gate's timeout, so while history is off, remove the gate withbd delete <id> --force(without--force,bd deleteonly previews, and removing the gate also unblocks anything it was blocking), or set thetimeout_nscolumn of theissuestable within the limit withbd sql, which needs a server-backed store and does not run on an embedded one. Then run the command again. There is no override: the check has no flag, andbd config set versioned-history.enabled falsenever runs it. - What that check does not cover. It runs once, at the moment you turn the setting on. A writer that does not record versions (an older
bd,bd sql, a pull from a clone that had history off) can add such a row at any time afterwards, including right after the switch is on, and, if that row participates in history, the first write to it then fails with the same refusal; the same fix applies. Checking and writing the setting in one transaction would narrow that window, not close it. Turning recording on throughBD_VERSIONED_HISTORY_ENABLEDorconfig.yamldoes not go through the command at all, so nothing is checked ahead of time there; a write to such a row is refused when it happens. Duplicate keys in metadata are refused too, but Dolt's JSON column collapses them when it stores a document, so on a Dolt store neither the check nor a write can see one; that refusal is a defense for another backend that keeps them. - The environment can turn it on, never off.
BD_VERSIONED_HISTORY_ENABLED=1, or a hand-writtenenabled: trueunderversioned-history:inconfig.yaml, applies to every store the process opens, routed targets included. The environment and the row are OR'd, not ranked, soBD_VERSIONED_HISTORY_ENABLED=0does not turn off a store whose row saystrue. Turn it off where it was turned on:bd config set versioned-history.enabled false. - Server-backed modes read the same row. Proxied-server mode, and
bd serveagainst a server-mode workspace, write through a unit-of-work provider rather than a store. The provider reads the row from its own database when it is constructed, through a short read-only transaction that is rolled back, sobd config set versioned-history.enabled truecovers those modes too. It does not fall back to the environment alone. - The Go SDK is not covered. Writers built on the Go SDK (the
beadspackage:Open,OpenFromConfig,OpenGated,OpenBestAvailable) do not apply the switch: a write they make to a store whose row saystruerecords no version. Thebdbinary's store factories apply it, and the events journal's switch has the same boundary. Opening a store through the SDK and applying both switches is a separate change. - The value is read when a store is opened. A long-lived process such as
bd servekeeps the value it read at start until it is restarted, so after changing the setting, restart it.
Sync and Federation
Beads syncs exclusively through Dolt remotes (bd dolt push / bd dolt pull) with cell-level merge. Use bd export for issue portability and bd backup for restorable database backups.
Federation settings live in config.yaml:
federation:
remote: dolthub://myorg/beads
sovereignty: T2
federation.remote: Dolt remote URL (dolthub://org/beads,gs://bucket/beads,s3://bucket/beads,az://account.blob.core.windows.net/container/beads,file://...)federation.sovereignty: data sovereignty tier:T1: Full sovereignty — data never leaves controlled infrastructureT2: Regional sovereignty — data stays within region/jurisdictionT3: Provider sovereignty — data with trusted cloud providerT4: No restrictions — data can be anywhere
bd config validate checks the remote URL format, the sovereignty tier, federation.allowed-remote-patterns, and routing.mode.
Integration Configuration
Tracker settings are project-level config under the tracker's namespace; secrets (jira.api_token, linear.api_key, github.token, gitlab.token, ado.pat, notion.token) are YAML-routed and better supplied as environment variables. Every tracker records <tracker>.last_sync automatically after a sync, enabling incremental syncs.
Jira
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set jira.projects "PROJ1,PROJ2" # Multiple projects (comma-separated)
export JIRA_API_TOKEN="YOUR_TOKEN" # or: bd config set jira.api_token ...
# Map bd statuses to Jira statuses
bd config set jira.status_map.open "To Do"
bd config set jira.status_map.in_progress "In Progress"
bd config set jira.status_map.closed "Done"
# Map bd issue types to Jira issue types
bd config set jira.type_map.bug "Bug"
bd config set jira.type_map.feature "Story"
bd config set jira.type_map.task "Task"
# Set Jira custom fields on pushed issues
bd config set jira.custom_fields.customfield_10042 '{"value":"AI Platform"}'
bd config set jira.custom_fields.Story.customfield_10042 '{"value":"AI Platform"}'
jira.custom_fields.<field> applies to every issue pushed to Jira. jira.custom_fields.<JiraType>.<field> applies only when the mapped Jira issue type matches <JiraType>; per-type fields override global fields with the same field key. Values beginning with { or [ are sent as JSON (useful for select-like fields); other values are sent as strings. jira.url, jira.project/jira.projects, and jira.api_token fall back to the JIRA_URL, JIRA_PROJECT/JIRA_PROJECTS, and JIRA_API_TOKEN environment variables. See bd jira.
Linear
export LINEAR_API_KEY="lin_api_YOUR_API_KEY" # Settings → API → Personal API keys
bd config set linear.team_id "team-uuid-here"
bd config set linear.team_ids "uuid-1,uuid-2" # Multiple teams (or LINEAR_TEAM_IDS)
When linear.team_ids is set, bd linear sync fetches issues from all listed teams; push with multiple teams configured requires an explicit --team. The singular linear.team_id remains supported.
Mapping namespaces — linear.priority_map.* (Linear 0–4 → beads 0–4), linear.state_map.* (Linear state types and custom state names → beads statuses, e.g. bd config set linear.state_map.in_review in_progress), linear.label_type_map.* (Linear labels → bd issue types), and linear.relation_map.* (Linear relations → bd dependencies; imported only when pulling with --relations) — are documented with defaults in bd linear.
Staleness detection: after each successful pull, bd writes a timestamp to .beads/last_pull (a local-only, per-machine file covered by the .beads/.gitignore template). bd linear sync --pull-if-stale pulls only when data is older than the threshold (--threshold, default 20m), and a 5-minute debounce prevents agent loops. bd prime and other core commands never contact Linear — run bd linear sync --pull-if-stale from a session-start hook to keep data fresh in agent sessions.
GitHub
bd config set github.org "myorg"
bd config set github.repo "myrepo"
export GITHUB_TOKEN="YOUR_TOKEN" # or: bd config set github.token ...
# Map bd labels to GitHub labels
bd config set github.label_map.bug "bug"
bd config set github.label_map.feature "enhancement"
See bd github.
Azure DevOps
Connection keys (ado.pat, ado.org, ado.project, ado.projects, ado.url) each have an AZURE_DEVOPS_* environment variable equivalent; config keys take priority over env vars. When ado.projects is set, bd ado sync fetches work items from all listed projects in a single query. State maps default to the Agile process template (override with ado.state_map.* / ado.type_map.* for Scrum or CMMI), and priority mapping (ADO 1–4 ↔ beads 0–4, with backlog collapsing to low) is automatic and not configurable. Full setup, mapping tables, and sync commands: Azure DevOps integration and bd ado.
Environment Variables
The Viper env prefix is BD_. Config keys map to env vars by upper-casing and replacing . and - with _ (e.g. dolt.auto-commit → BD_DOLT_AUTO_COMMIT, validation.on-create → BD_VALIDATION_ON_CREATE).
Selected commonly-used variables:
| Variable | Description |
|---|---|
BD_DB, BEADS_DB |
Database path (legacy BEADS_DB still honored) |
BD_JSON |
Force JSON output |
BD_DOLT_AUTO_COMMIT |
Override dolt.auto-commit (on/off) |
BD_DOLT_AUTO_PUSH, BD_DOLT_AUTO_PUSH_INTERVAL, BD_DOLT_AUTO_PUSH_TIMEOUT |
Override auto-push settings |
BD_BACKUP_ENABLED, BD_BACKUP_INTERVAL, BD_BACKUP_GIT_REPO |
Override backup settings |
BD_VERSIONED_HISTORY_ENABLED |
Turn on versioned-history.enabled for every store the process opens. 1 turns recording on; 0 does not turn it off for a store whose row says true (see Versioned Issue History) |
BD_AGENT_PROFILE |
Override agent.profile |
BD_AI_MODEL |
Override AI model |
BD_FEDERATION_REMOTE, BD_FEDERATION_SOVEREIGNTY |
Override federation settings |
BD_VALIDATION_ON_CREATE / _ON_CLOSE / _ON_SYNC |
Override validation modes |
BD_NO_PAGER, BD_PAGER |
Pager behavior |
BD_NON_INTERACTIVE |
Disable prompts |
BD_DEBUG |
Enable debug logging |
BD_HTTP_READ_MEMO |
0 turns off the per-command read memo on an http workspace, so each repeated row or settings read in a command goes to the server; for ruling out a stale read |
BD_MIGRATION_FREEZE_FILE |
Check this exact path for the freeze marker instead of walking ancestor directories; authoritative when set (see Migration Freeze) |
BEADS_DIR |
Force the active beads workspace directory |
BEADS_CEILING_DIRECTORIES |
Directories (separated like PATH) that .beads and config.yaml discovery never looks at or above, like git's GIT_CEILING_DIRECTORIES; the starting directory is always examined. For sandboxes such as bazel test that must not reach the user's own ~/.beads |
BEADS_ACTOR |
Actor identity (preferred over BD_ACTOR, which is a deprecated alias) |
BEADS_IDENTITY |
Sender identity for bd mail |
BEADS_FSCK_TIMEOUT |
Runtime-only timeout for the pre-push dolt fsck --quiet integrity check (default 30s) |
BEADS_INIT_GATE_TIMEOUT |
How long bd init waits for another bd process (another init, or live commands on the same workspace or shared server) to release the workspace gate before refusing (default 60s; accepts durations like 2m or bare seconds like 90) |
BEADS_GATE_WAIT_TIMEOUT |
How long an ordinary bd command waits while a maintenance operation (bd init, backup restore, migrate, bootstrap — on the same workspace, or on any project sharing the server in shared-server mode) holds or is queued for the workspace gate, before failing (default 30s; accepts durations like 1m or bare seconds like 90; 0 fails immediately, for scripts that want the old fail-fast behavior). Queued maintenance operations run one after another and a waiting command waits for all of them; a queued one only delays a command, never fails it, and stops queueing others after 10s if it cannot get in. Git hooks always fail fast |
BEADS_MIGRATION_WATCHDOG_INTERVAL |
Interval between soft WARN lines while a schema migration's SQL keeps running (default 5m; accepts durations like 10m or bare seconds like 90). Observability only — it never aborts a migration |
BEADS_DOLT_SERVER_MODE, BEADS_DOLT_SHARED_SERVER, BEADS_DOLT_DATA_DIR, BEADS_DOLT_PORT, ... |
Embedded/server Dolt overrides |
BEADS_DOLT_BIN |
Pin the exact external dolt CLI binary managed proxied-server mode spawns, overriding PATH lookup (highest precedence; an explicit path that fails validation is an error, not a silent fallback to PATH). On Windows the executable extension may be omitted — C:\tools\dolt finds C:\tools\dolt.exe via PATHEXT, though a file at the exact spelled path wins if both exist |
Integration secrets follow tracker-specific conventions: LINEAR_API_KEY, GITHUB_TOKEN, GITLAB_TOKEN, JIRA_API_TOKEN, AZURE_DEVOPS_PAT, ANTHROPIC_API_KEY. These are preferred over storing the value in config.yaml for git-tracked projects.
bd config show will display the source of every effective key, making overrides explicit.
Migration Freeze
Maintenance that runs outside bd — moving a database to a new host, rewriting schema by hand — needs a way to stop writes for its duration without uninstalling the tool. Create a file named MIGRATION-FREEZE and every write command refuses to run until you delete it.
bd looks for the marker in the workspace directory and in the working directory, plus every ancestor of each, so one file above a tree of repositories freezes all of them at once — and targeting a frozen workspace from elsewhere (BEADS_DIR=…, bd -C …) is refused the same way.
Markers found in a world-writable sticky directory such as /tmp are ignored: anyone on a shared machine could plant one there, and the sticky bit would stop you removing it. Put the marker at the root of the tree you are freezing.
A freeze marker must be a regular file. A directory or a symlink named MIGRATION-FREEZE that the ancestor walk finds is ignored — the symlink with a one-line warning on stderr, so a stray link never disarms the gate in silence. To drive the freeze through an indirection on purpose, name that link with BD_MIGRATION_FREEZE_FILE (below), which bd follows.
touch MIGRATION-FREEZE # the file's existence is the whole signal
# Optional payload: operator, RFC3339 timestamp, and reason, tab-separated
# on one line. bd echoes it back in the refusal.
printf 'alice\t2026-08-16T12:00:00Z\tmoving to the new server\n' > MIGRATION-FREEZE
bd create "new work"
# ⛔ ERROR: workspace is frozen for migration (by alice).
# Reason: moving to the new server
# bd create is blocked by the freeze marker at /work/MIGRATION-FREEZE.
# To resume writes, remove that file.
rm MIGRATION-FREEZE # thaw
Blocked commands exit 14 — a stable code scripts branch on to tell "someone is migrating this workspace, come back later" from a generic failure worth an immediate retry. That includes the destructive ones: bd init --reinit-local and bd bootstrap are refused too.
Reads (bd list, bd show, bd ready, …) keep working during a freeze, and bd's own background maintenance stands down with them — version-bump migration, JSONL auto-import, Dolt auto-commit, auto-backup, auto-export and auto-push are all skipped, so running a read does not leave a commit in the store you are migrating.
If bd cannot tell whether a marker is present — a permission error on the marker or on a directory above it — it refuses the write and says so, rather than assuming the workspace is open.
BD_MIGRATION_FREEZE_FILE names one explicit path to consult instead of walking ancestors, for markers that live outside the tree. It is authoritative: when it is set, nothing else is checked. Because you name that path deliberately, it may be a symlink — bd follows it and freezes when the link resolves to a regular marker file — so an indirection such as current -> releases/42/MIGRATION-FREEZE works as the authoritative signal.
Security: Where Secrets Live
- Tokens and API keys are never stored in the Dolt database — database config is pushed to remotes, which would expose secrets and trip GitHub secret scanning.
bd config setroutes secret keys to the localconfig.yamlinstead. - Writing a secret to a git-tracked
config.yamlis refused unless you pass--force-git-tracked; environment variables are the safer default. bd initwrites a.beads/.gitignorethat keeps the database directories (embeddeddolt/,dolt/), runtime files, push state, and the federation credential key out of git.
Example .beads/config.yaml
# Default JSON output for scripting
json: true
# Dolt history & sync
dolt:
auto-commit: on # Create a Dolt commit after each successful write
auto-push: false # Opt-in for single-writer setups
# Issue creation policies
create:
require-description: true
validation:
on-create: warn # Warn when creating issues missing required sections
on-close: none
on-sync: none
# Git commit signing for beads commits (GH#600)
git:
author: "beads-bot <beads@example.com>"
no-gpg-sign: true
# Periodic Dolt-native backup to .beads/backup/
backup:
enabled: true
interval: 15m
# Optional auto-export of issues.jsonl after writes for viewers/interchange
export:
auto: false
path: issues.jsonl
interval: 60s
git-add: false
# Optional Dolt federation
federation:
remote: dolthub://myorg/beads
sovereignty: T2
# Directory-aware label scoping for monorepos (GH#541)
directory:
labels:
packages/maverick: maverick
packages/agency: agency
# Cross-project dependency resolution (bd-h807)
external_projects:
beads: ../beads
other-project: /absolute/path/to/other-project
output:
title-length: 255
For machine-specific overrides that should not be committed, drop them in .beads/config.local.yaml; it is merged in last.
Per-Command Override
bd --db /tmp/test.db list # Override database for one command
bd --json --actor "ci-bot" create "Fix things" # Multiple flags
Use in Scripts
Configuration is designed for scripting; every bd config subcommand takes --json:
# Get one value ({"key":"jira.url","value":"..."})
JIRA_URL=$(bd config get --json jira.url | jq -r '.value')
# Get all database config as a flat object
bd config list --json | jq -r '.["jira.project"]'
Viewing Active Configuration
bd config show # Effective config with provenance
bd config show --json # Machine-readable
bd config list # Database-stored config
bd info --json | jq '.config' # Quick snapshot