Callers that need ready work across several statuses (e.g. Gas City's
native store Ready(), which spans open/blocked/deferred/pinned/hooked/
review/testing) currently issue one GetReadyWork per status. Each call
re-pays the deferred-parents pre-query, the wisps arm, and the
per-transaction round trips — measured at 30-70ms per call on a live
server-mode store, ~7x per Ready().
WorkFilter.Statuses (OR semantics) renders a single status IN (...)
clause through BuildReadyWorkWhere and propagates to the wisp-side
IssueFilter.Statuses, so multi-status callers pay the fixed per-call
work once. Singular Status keeps precedence; both empty keeps the
legacy ('open', 'in_progress') default.
Review round 2: a conformance audit case (ReadyMultiStatusFilter) pins
the contract at the result level against both backends — real issues
and wisps across several statuses, OR semantics in one call, singular-
Status precedence, the empty default, a custom status through the same
IN clause, and the ephemeral exclusion of wisps without
IncludeEphemeral. The library guide documents Statuses, and
BuildReadyWorkWhere computes the status clause and args in one pass.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(stats): add --no-blocked flag; fix Blocked:0 red render (be-nnqp, be-4b63)
- types.go: BlockedIssues int → *int (nil when --no-blocked skips computation)
- storage: add FastStatisticsStore interface + GetStatisticsNoBlocked to DoltStorage;
implement in DoltStore and EmbeddedDoltStore (ScanIssueCountsInTx only, no blocked traversal)
- status.go: --no-blocked flag (no short alias), BlockedCountSkipped bool in StatusOutput;
fast path calls GetStatisticsNoBlocked; human output renders "(skipped)" in muted style
- be-4b63: Blocked:0 now renders plain text; only Blocked:N>0 uses RenderFail (red)
- nil-guard BlockedIssues callers: getAssignedStatistics, status_test.go, queries_test.go,
examples/library-usage/main.go
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(cli): regen CLI reference for `bd status --no-blocked`
Regenerates docs/CLI_REFERENCE.md and the website CLI reference pages
(`website/docs/cli-reference/status.md` and the version-1.0.0 / 1.0.4
snapshots) from the live `bd help` output so the doc-flags freshness
check passes.
Picks up the new `--no-blocked` flag, the updated `--no-activity`
description ("Skip git activity summary"), and the matching example
lines added in ddf53438c.
Fixes the CI "Check doc flags freshness" failure on PR #4022.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: release gate PASS for be-nnqp+be-4b63 (bd stats --no-blocked)
* fix(stats): ReadyIssues *int, data-derived skip render, proxied-server warning
Address the adjudicated cross-vendor review on PR #4022:
- internal/types.Statistics.ReadyIssues is now *int, mirroring BlockedIssues:
nil when --no-blocked skips the computation (readiness needs the blocked
set), populated by all three backends' full GetStatistics, by
issueops.GetStatisticsInTx, and by buildAssignedStats. Left nil only in
the *NoBlocked fast-path variants. JSON now emits `"ready_issues": null`
instead of a fake 0 a CI consumer could misread as "nothing ready".
- renderStatus derives "(skipped)" rendering from the data itself
(stats.BlockedIssues/ReadyIssues == nil) instead of the noBlocked flag,
fixing the --assigned + --no-blocked contradiction where fully-recomputed
stats were mislabeled as skipped. The noBlocked parameter is gone from
renderStatus entirely; both call sites (status.go, status_proxied_server.go)
simplified accordingly.
- Proxied-server mode now prints a one-line stderr warning when --no-blocked
is passed but not honored, instead of silently discarding the flag; the
flag's help string documents the limitation.
Agent-Signature: claude-sonnet-medium on behalf of maphew
* test(stats): cover GetStatisticsNoBlocked nil semantics and renderStatus skip branch
- internal/storage/dolt: new TestGetStatisticsNoBlocked_LeavesBlockedAndReadyNil
asserts the --no-blocked fast path leaves BlockedIssues/ReadyIssues nil
while the full GetStatistics path on the same store populates both.
- cmd/bd: new TestGetStatisticsNoBlocked (storage-level, same assertion via
the CLI-facing store handle), TestRenderStatus_SkipJSONEmitsNullNotZero
(asserts blocked_count_skipped:true plus literal `"blocked_issues": null`
/ `"ready_issues": null` in the JSON envelope),
TestRenderStatus_SkipHumanRendersSkippedNotZero (asserts the "(skipped)"
human branch renders for both fields), and
TestRenderStatus_AssignedIgnoresSkipEvenWithNoBlockedFlag (guards the
--assigned + --no-blocked fix: fully-populated stats never render
"(skipped)").
- Update existing statistics assertions in
internal/storage/conformance/audit_search-counts-stats.go,
internal/storage/dolt/queries_test.go, and
internal/storage/domain/db/ready_helpers*_test.go for
ReadyIssues's int -> *int change.
Agent-Signature: claude-sonnet-medium on behalf of maphew
* docs(cli): drop --no-blocked doc lines from CLI_REFERENCE.md/status.md (pinned-generator policy)
CI's "Check doc flags freshness" job builds bd from the release pin in
docs/cli-docs.pin (currently v1.1.0) to regenerate docs/CLI_REFERENCE.md
and docs/cli-reference/status.md, not from this branch's HEAD. v1.1.0
predates --no-blocked entirely, so the pinned generator's output omits
every --no-blocked reference (use case bullet, both example lines, the
flag description) and also reverts the --no-activity flag description
wording, flagging both files as stale relative to it. Same trap PR #3920
hit for --mem-profile.
Applied the exact patch CI generated and uploaded as the
cli-docs-freshness-patch artifact on the failing job
(run 30063539327 / job 89390739992) verbatim to both files; the lines
will reappear automatically once the pin advances past a release that
includes --no-blocked.
Agent-Signature: claude-sonnet-medium on behalf of maphew
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
* /{engdocs,examples,go.mod}: bump go version
* deps: bump golang.org/x/text to v0.39.0 (GO-2026-5970)
govulncheck against today's vuln DB flags GO-2026-5970 (infinite loop on
invalid input in x/text, reachable via internal/routing), published after
this PR's original clean scan. Bump x/text to the fixed v0.39.0 (with its
MVS sibling x/* minimums) and re-tidy examples/library-usage, which
builds against the parent via a replace directive and would otherwise
fail with missing go.sum entries.
examples/bd-example-extension-go is left untouched: it already fails
'go build' (needs go mod tidy) at the PR's base state, so its tidy is
pre-existing follow-up work, not fallout from this bump.
Verified: CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd; both
example modules build; go test ./internal/routing; govulncheck now
reports 0 affecting vulnerabilities.
Agent-Signature: claude-fable-5-high on behalf of maphew
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
* feat(metadata): MergeMetadata — atomic single-key metadata merge
SlotSet did a read-modify-write across TWO transactions: GetIssue (tx 1),
metadata[key]=value in memory, then UpdateIssue (tx 2). Two concurrent SlotSet
calls — even on DIFFERENT keys — both read the same base metadata and each
wrote back its whole blob, so the second clobbered the first's key. SlotClear
had the same bug. Add MergeMetadata, which does the read-modify-write inside
ONE transaction (so a concurrent conflict is retried and re-reads), stores a
JSON value (nested objects/arrays, not just strings), and reimplement SlotSet
and SlotClear on top of it so they inherit the atomicity.
- issueops.MergeMetadataInTx / DeleteMetadataInTx: read the metadata (routed
issues/wisps; missing issue -> ErrNotFound), merge/delete the one key, and
write the whole object back THROUGH UpdateIssueInTx — so the operation keeps
everything the old SlotSet got from UpdateIssue (the EventUpdated history
event with actor attribution, the configured metadata-schema validation, and
updated_at), now atomic. The read and write share the caller's transaction,
so a concurrent merge of a different key is retried and re-read, never
clobbered.
- Storage.MergeMetadata implemented on DoltStore (perm withRetryTx +
DOLT_ADD(issues,events) + DOLT_COMMIT; wisp path no commit) and
EmbeddedDoltStore (withConn); forwarded on InstrumentedStorage; auto-promoted
on HookFiringStore; no-op on the configStore mock. SlotSet/SlotClear rebuilt
on it (a string value marshals to a JSON string, byte-compatible with the
historical rewrite).
- Cross-backend conformance covers MergeMetadata + atomic SlotClear; the
8-goroutine concurrent-no-clobber test proves the B1 fix on real Dolt, and
a test asserts the EventUpdated event and schema validation are preserved.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(concurrency): expose a per-row version on Issue reads (RowVersion)
The engine's internal row_lock column — a random non-zero int64 the engine
rewrites on every status/ownership-mutating write and on the generic update
path — was not surfaced on the public types.Issue. Consumers that wanted a
fine-grained optimistic-concurrency token had only updated_at, which is stored
at second granularity, so two same-second writes were indistinguishable. Expose
row_lock read-only as types.Issue.RowVersion so a caller can tell same-second
writes apart.
- types.Issue gains RowVersion int64 (json:"-": a Go-only concurrency token,
never on the CLI/export JSON wire — it is opaque and equality-only). Added
row_lock to the canonical sqlbuild.IssueBaseColumns and a matching scan target
in issueops.ScanIssueFrom; both engine write stacks, wisps, and the counts /
dependents parallel scans share those, so the field hydrates everywhere from a
single-point change. Read-only — no CAS/write behavior (that is a follow-up).
- Doc is precise about coverage: RowVersion changes on claim/close/unclaim and
the generic update path; it does NOT change on some direct-UPDATE paths
(restore, compaction text), which bump updated_at — so a complete change key
combines RowVersion with updated_at, status, and labels. A created row is
already non-zero (create stamps row_lock); 0 only appears on legacy rows
backfilled by migration 0054's DEFAULT 0.
- Tests: RowVersion hydrates on read and on the list path, changes on a mutating
write, distinguishes two same-second writes (identical updated_at, distinct
RowVersion), and never appears on any JSON surface.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(deps): return a typed error on dependency type-conflict
Adding a dependency between a pair that already has an edge of a different type
is a deterministic rejection, but the two engine write paths disagreed on how
they surfaced it: one returned a typed *DependencyTypeConflictError, the other a
plain fmt.Errorf string. So a caller could errors.As the conflict on one path
but had to string-match the message on the other. Make both paths return the
same typed error, and re-export the two dependency-conflict types on the public
beads package so `bd` (and the library's own call sites) classify by errors.As
instead of parsing message text.
- issueops.AddDependencyInTx now returns *domain.DependencyTypeConflictError for
the type-conflict case (byte-identical message — the struct's Error() is the
exact former string, so no string-matcher changes). The hierarchy/cross-type
case already returned *domain.DependencyHierarchyConflictError on both paths;
self-dependency and cycle are already typed sentinels.
- beads.go re-exports DependencyTypeConflictError and
DependencyHierarchyConflictError as type aliases, so errors.As against the
public type matches the value the engine returns.
- Tests assert errors.As + the four fields + the byte-identical message on both
write paths (permanent issues->issues and the wisp-source BeginTx/Commit seam),
and lock the re-exports; the deterministic conflict is returned immediately
(never retried as a transient serialization error).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(deps): emit dependency_added / dependency_removed events
`bd dep add` and `bd dep remove` recorded no event, so the events feed never
surfaced dependency changes even though the event types (types.EventDependencyAdded
/ EventDependencyRemoved) have existed since the original SQLite backend, which
emitted them on every add/remove. The emission was dropped when that backend was
removed for the Dolt-only migration and never ported to the current write paths.
Restore it on both Dolt write plumbings, matching the original shape (an events
row on the source issue: "Added dependency: <src> <type> <target>" /
"Removed dependency on <target>").
- issueops.AddDependencyInTx / RemoveDependencyInTx record the event via
RecordEventInTable on the source's event table (wisp-routed), on the genuine
add/remove only — the idempotent same-type re-add and the no-op remove of a
missing edge record nothing.
- The event is committed with the edge: DoltStore.AddDependency/RemoveDependency
DOLT_ADD `events`, and the transaction-path (RunInTransaction / batch /
graph-apply) methods mark the source's event table dirty (events or wisp_events)
so StageAndCommit commits it — without this the event row would dangle in the
working set.
- Emission is gated to the explicit dep-add/remove verb on both plumbings: the
proxied-server repo only records when the use-case sets DepInsertOpts.EmitEvent,
which create-with-deps (implicit parent-child / --deps / waits-for, via a direct
repo Insert) does not — so `bd create --parent` produces the same history on
either backend (the embedded create path via PersistDependencies likewise emits
nothing).
- Tests on both plumbings: add/remove emit exactly once and commit (verified via
`events AS OF 'HEAD'`), idempotent re-add and no-op remove emit nothing, wisp
sources route to wisp_events, and create-with-deps emits no dependency_added.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(close): optional ExpectedVersion CAS on CloseIssueChecked
CloseIssueChecked guards a close on is_blocked in-transaction, but a caller that
read an issue and then closes it has no way to say "only if it hasn't changed
since I read it" — a lost-update window. Add an optional compare-and-swap on the
row's version (the RowVersion / row_lock token): when the caller supplies an
ExpectedVersion, the close proceeds only if the row still has that version, else
it refuses with a typed ErrVersionMismatch. The version read and the close share
one transaction, so it is a true CAS with no read-then-write gap.
- storage.ErrVersionMismatch (re-exported as beads.ErrVersionMismatch) and
CloseIssueOptions.ExpectedVersion *int64 (nil disables the check; a pointer so
nil "no check" is distinct from "require version 0").
- issueops.CheckVersionInTx reads row_lock (wisp-routed; ErrNotFound on a missing
row) and returns ErrVersionMismatch on divergence. CloseIssueCheckedInTx runs
it FIRST — before the is_blocked guard and before the Force short-circuit, so
Force bypasses only the guard, never the CAS (the version check is an
orthogonal precondition). A mismatch returns before any write, so the tx rolls
back leaving the issue open with no `closed` event (atomic refuse).
- The CAS has two limbs: the read-side check catches a writer that committed
before the close began, and on the retry-wrapped permanent path a commit-time
row_lock conflict is replayed by withRetryTx so the re-read refuses.
- Tests on both stores: match closes, stale refuses atomically (still open, zero
closed events), a committed concurrent write invalidates a captured version,
nil is unchanged behavior, Force does not bypass, missing id → ErrNotFound,
wisp sources route to the wisps table, and an already-closed re-close with the
post-close version stays idempotent (Unchanged).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(close): document RowVersion CAS coverage boundary on ExpectedVersion
Both adoption reviewers flagged that the public ExpectedVersion godoc and the
shared CloseIssueCheckedInTx doc could be misread as a full-row "unchanged"
check. RowVersion (row_lock) only tracks lifecycle/ownership writes
(status/assignee/started_at), so concurrent label, dependency, rename, or
is_blocked writes leave it untouched and are intentionally outside this CAS
boundary. Document that on both sites, grounded in the freshRowLock invariant.
Doc-only; no behavior change.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* refactor(cli): bd close delegates to the engine's guarded close
The embedded `bd close` path ran its own is_blocked pre-check and then closed in
a separate call — a read-then-write TOCTOU that duplicated a guard the engine
provides atomically. The verb now builds CloseIssueOptions and delegates to
CloseIssueChecked, which runs the guard and the close in ONE transaction; the
CLI's duplicated guard is deleted. --force maps to Options.Force; a blocked
close refuses with the blockers named and the --force hint.
Behavior-preserving on purpose (verified against the previous binary):
- The engine guard now uses the exact historical CLI predicate — refuse only on
a LIVE direct blocker (blocked && len(blockers) > 0), not on the bare
denormalized is_blocked column. A transitively-blocked child (is_blocked
inherited from a blocked parent, zero direct blockers) still closes without
--force, and a stale is_blocked with since-closed blockers self-heals, exactly
as before.
- An already-closed issue stays an idempotent success: it still appears in the
--json array and the text report (same output shape), still exits 0, but no
longer produces a spurious closed->closed audit entry, a no-op commit, or the
real-close side effects (molecule auto-close, newly-unblocked, claim-next).
Tests cover: direct blocker refuses atomically (still open) and closes with
--force; transitively-blocked and stale-is_blocked beads close without --force;
already-closed emits in --json alone and in a mixed batch; idempotent exit 0 —
on the engine (both stores) and through the bd binary.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(update): UpdateIssueChecked — optional ExpectedVersion CAS on the update
UpdateIssue applies a field-map update with no optimistic-concurrency option, so
a caller that wants "update only if unchanged since I read it" had to
read-then-write — a lost-update window. Add UpdateIssueChecked: when the caller
supplies an ExpectedVersion (the RowVersion / row_lock token), the version read
and the update share ONE transaction, refusing with the typed ErrVersionMismatch
if the row has moved — a true compare-and-swap. Nil disables the check and is
byte-identical to UpdateIssue, which is left untouched on the hot path.
- storage.UpdateIssueOptions{ExpectedVersion *int64} (aliased as
beads.UpdateIssueOptions) + Storage.UpdateIssueChecked, mirroring the
CloseIssueChecked pattern: CheckVersionInTx runs first inside the same
transaction on every route — the permanent withRetryTx path, the wisp path,
AND the demote route (an update carrying no_history/wisp routes through the
demote flow; a pure demoteToWispInTx extraction lets the check compose
atomically with the row move — verified byte-identical to the old
DemoteToWisp).
- Implemented on DoltStore and EmbeddedDoltStore; InstrumentedStorage wraps it;
HookFiringStore fires on_update only on success (never on a refused update).
- Tests on both stores: match updates and bumps RowVersion; stale refuses
atomically (field unchanged, zero updated events); a committed concurrent
write invalidates a captured version; nil behaves exactly like UpdateIssue;
wisp match/stale; demote-route match (migrates + applies) and stale (still in
issues, unchanged); missing id → ErrNotFound; the hook decorator fires once on
success and never on refusal.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(cli): proxied bd close delegates to a library checked close
The proxied-server `bd close` path duplicated the close guard in the CLI:
it queried blockers via the dependency use-case, refused with its own message,
and then closed in a separate use-case call. Move the guard into the library —
IssueUseCase gains CloseIssueChecked / CloseWispChecked, which run the same
live-direct-blocker predicate (refuse only on blocked && len(blockers) > 0)
and then the untouched unchecked close — and thin the CLI verb to a single
delegated call. Both `bd close` paths now enforce the guard in the library and
emit the byte-identical refusal: the same storage.ErrCloseBlocked sentinel
("cannot close blocked issue: <id> is blocked by [...]") plus the
"(use --force to override)" hint.
- Guard and close run on the one pinned unit-of-work connection (the whole
close batch is a single transaction), and the guard is read-only and refuses
before any write — a refused id leaves the shared batch transaction clean,
and an all-refused batch skips the commit entirely, exactly as before.
- The unchecked CloseIssue / CloseWisp are untouched: internal closes (molecule
auto-close, gate closes, bd todo done) intentionally stay unguarded.
- Behavior-parity preserved: guard ordering (validate → epic-child → gate →
blocked), exit codes, JSON/batch shape, already-closed handling, audit fields,
and commit-message contents are unchanged; a transitively-blocked bead
(is_blocked with no direct open blocker) still closes without --force, and
--force still bypasses. The guard-failure diagnostic now uses the embedded
path's generic wording (further convergence; nothing matched the old text).
- Tests: use-case level on real Dolt (direct blocker refuses with blockers
named + still open, transitive-only closes, force closes, already-closed
parity, wisp refuse/force) plus the proxied CLI integration suite.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(review): cross-backend dependency-event + RowVersion parity
Maintainer review fixups for PR #4911 (adopt-pr review loop):
- RowVersion: the proxied/domain create (insertIssueRow) and generic Update
paths never stamped or rewrote row_lock, so an issue written through the
proxied-server backend read back RowVersion 0 on create and unchanged on
update -- a stale CAS token that violated the types.Issue.RowVersion
contract on that backend. Stamp a fresh non-zero row_lock on insert (and the
duplicate-key rewrite) and append RowLockClause() to the generic update,
mirroring the classic issueops insert/update invariant. Adds domain/db
regression tests proving CreateIssue/CreateWisp are non-zero and
UpdateIssue/UpdateWisp change it.
- Dependency events: embedded issueops AddDependencyInTx/RemoveDependencyInTx
recorded history unconditionally, so structural create-with-deps
(bd create --parent/--deps/--waits-for) and reparent (bd update --parent)
emitted dependency_added/removed on embedded but were silent on the proxied
backend, diverging issue history for identical commands. Gate the embedded
emit on EmitEvent and thread it through AddDependencyWithOptions /
RemoveDependencyWithOptions on both the store and transaction interfaces:
the plain AddDependency/RemoveDependency are the no-event structural default
(create-with-deps, reparent), while the explicit dep verbs (bd dep add/remove,
bd link, bd relate/unrelate) pass EmitEvent -- matching the proxied
DepInsertOpts.EmitEvent gate. DoltStore stages the events table only when an
event was actually written (GH#2455). Corrects the false
"parity with PersistDependencies" comments and adds symmetric embedded/proxied
dep-event coverage for create-with-parent/deps and structural removal.
- Retain iteration-1 fixups: heal molecules on already-closed re-close,
idempotent proxied checked-close, and documented public Storage growth.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(storage): drop always-constant event param from fireDependencyHookByID (unparam)
golangci-lint (latest, v2.12.2 in CI) unparam flags fireDependencyHookByID:
its `event` parameter always receives hooks.EventUpdate. The parameter was
already effectively constant before this PR (both base call sites passed
EventUpdate); this PR adds two more call sites, all EventUpdate. Remove the
dead parameter and hardcode hooks.EventUpdate at the single runner.Run call.
All four call sites pass hooks.EventUpdate, so behavior is unchanged; go
build, go vet, and a scoped golangci-lint run pass clean.
Maintainer fixup during adoption finalize (PR #4911).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Test User <test@test.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <ci@beads.test>
The #4847 reapply brought back tests written when sqlite was still a
supported backend; update them to the tombstone contract:
- internal/beads: FindDatabasePath returns "" for sqlite metadata (fail
closed at store selection) and never creates the database file.
- doctor: server health reports the generic non-Dolt warning; the perf
refusal message names the backend without a support claim.
- examples/library-usage: exercise the API against embedded Dolt instead
of the removed sqlite backend.
Also sweep stragglers flagged in review: bd sql help text, conformance
audit provenance comments, the test-strategy example path, and a comment
tying the flake devShell sqlite3 CLI to the legacy migration scripts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Document the rollback of direct PostgreSQL and MySQL adapters because supporting additional general-purpose server databases adds operational and maintenance complexity. Our goal is to keep Beads as simple as possible and consume as few resources as possible.
Clarify that embedded Dolt, Dolt server, and SQLite remain supported, including Dolt server use of the MySQL wire protocol.
Existing PostgreSQL and MySQL databases are not opened or modified. Migration requires an export from a supporting build, reinitialization guided by bd help init-safety, and import; JSONL remains issue-level interchange rather than a complete backup.
Refresh generated CLI reference material alongside the storage guidance.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Test User
Roll back the direct adapters, dialect layers, credential handling, dependencies, CI services, and conformance profiles for general-purpose server databases. That support adds operational and testing complexity at odds with our goal of keeping Beads as simple as possible and consuming as few resources as possible.
Keep the Storage and DoltStorage interfaces unchanged. Embedded Dolt, Dolt server, and SQLite remain supported; the MySQL wire driver remains because Dolt server uses it.
Retain legacy metadata identifiers and hidden init flags only as compatibility tombstones. Removed, unknown, or corrupt backend metadata now fails safely across CLI, SDK, bootstrap, doctor, factories, and Dolt administration before storage is opened or modified, with guidance to export using a supporting build and reinitialize via bd help init-safety.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Test User
* docs: fix broken xref to docs/EXTENDING.md in extension example
The extension example README referenced docs/EXTENDING.md in three
places, but that file was deliberately deleted in the SQLite -> Dolt
migration (see CHANGELOG entry "Deleted deprecated docs - removed
EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer
applicable)"). Anyone following the example hits a broken link.
Removed all three references. The example README is itself the
canonical reference for the extension pattern, so no redirect target
is needed.
Note: other docs in the repo still reference the deleted EXTENDING.md
(docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md,
website/docs/reference/advanced.md). Those are out of scope for this
fix and should be addressed in follow-up issues.
Tracking bead: mybd-q71
GH: #3683
PR: builds on follow-up audit from PR #3706
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: fix remaining broken xrefs to deleted EXTENDING.md across repo
Round 1 (commit ddeff314c) only fixed the extension example README
because the original prompt scoped that PR narrowly. The bead
(mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so
this follow-up sweeps the rest in the same PR per the project's
"one issue per PR" rule.
Per-file treatment (EXTENDING.md was deleted in commit 508387377
before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has
been broken since release):
- docs/ADVANCED.md (3 refs):
* Note in Extensible Database section: drop trailing "See
EXTENDING.md for details" — the surrounding sentence about
Dolt-era alternatives stands on its own.
* Bold "See EXTENDING.md for complete documentation" line:
redirect to the canonical working example
(examples/bd-example-extension-go).
* Next Steps bullet: same redirect.
- docs/CONFIG.md (2 refs):
* Namespace doc for compact_*: replace "(see EXTENDING.md)" with
"(used by `bd admin compact`)" — the doc itself describes the
keys, no external reference needed.
* See Also bullet: replace with link to docs/ADVANCED.md
(Extensible Database section).
- examples/library-usage/README.md (1 ref):
* See Also bullet: replace EXTENDING.md link with link to the
sibling bd-example-extension-go example.
- website/docs/reference/advanced.md (1 ref):
* Custom Tables section: replace EXTENDING.md link with link to
the bd-example-extension-go README on GitHub.
- website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref):
* Same fix as the live docs. EXTENDING.md was deleted before
v1.0.0 release (commit 508387377 is an ancestor of tag v1.0.0),
so this versioned snapshot has been broken since cut and a fix
here doesn't violate frozen-in-time correctness — the link was
never valid in the v1.0.0 release.
- website/static/llms-full.txt (1 ref, auto-generated artifact):
* Updated to match the corrected source so the on-disk artifact
isn't broken until next regeneration.
- beads.go and internal/beads/beads.go (package doc comments):
* Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a
pointer to examples/bd-example-extension-go. These were real
broken pointers in published Go source comments.
CHANGELOG.md historical entries left untouched (intentional history).
cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG
entry rendered by `bd info`, equivalent to a CHANGELOG line).
Verification:
grep -rn 'EXTENDING\.md' --include='*.md' .
returns only CHANGELOG.md hits.
Tracking bead: mybd-q71
GH: #3683
PR: #3713 (round 2)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: backward-compatible JSONL import for all pre-v1.0 formats
Three breaking changes accumulated across versions that prevent
importing old JSONL data:
1. Comment.ID changed from int64 to string in v1.0 — old JSONL
with numeric comment IDs crashes the importer. Add custom
UnmarshalJSON that accepts both types.
2. "wisp" field renamed to "ephemeral" in v0.38 — JSONL from
v0.35–v0.37 silently loses the ephemeral flag. Map the old
field name during import.
3. BondRef.proto_id renamed to source_id — old JSONL silently
loses bond source references. Accept proto_id as alias.
Also improve auto-import error messaging: when upgrade recovery
fails, tell the user their data is safe and suggest bd init
--from-jsonl instead of silently swallowing the error.
* fix: use American English spelling for misspell linter
* test: add unit tests for backward-compatible UnmarshalJSON and legacy import
- TestCommentUnmarshalJSON: string IDs, numeric IDs (pre-v1.0),
zero, large numbers, missing ID, invalid JSON
- TestBondRefUnmarshalJSON: source_id, proto_id (legacy),
both fields (precedence), neither, invalid JSON
- TestImportFromLocalJSONL_LegacyFormats: numeric comment IDs
survive import, wisp→ephemeral mapping (true/false/absent)
Add --database flag to bd init so callers can specify a pre-existing server
database name, overriding prefix-based naming. Prevents orphan database creation
when an external tool (e.g. gastown) has already created the database.
Also fixes display bug showing storage path instead of DB name in server mode,
and exports ValidateDatabaseName for use by init validation.
Co-Authored-By: Peter Chanthamynavong <peterkc@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Delete migrate_hash_ids.go (760 lines) and remove hash-ids subcommand,
doctor checks, and readonly test cases. Relocate copyFile to migrate.go
for migrate_dolt.go and repair.go. Rename public API beads.NewStorage()
to beads.Open() across code, tests, examples, and docs. Clean up
transitional SQLite-era comments in store.go and context.go. Add server
mode watchdog with TCP+SQL health probes, auto-restart with stale PID
cleanup, exponential backoff, and clean shutdown.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Update documentation examples from deprecated NewSQLiteStorage to
NewStorage(ctx, path). Fix monitor-webui to import the public beads
package instead of internal/beads.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Remove 60 lines of re-exported type aliases and constants from internal/beads
that duplicated internal/types. Update integration tests to import types
directly. Fix examples to use the public beads package API instead of
internal imports.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Adds closed_by_session tracking for entity CV building per Gas Town
decision 009-session-events-architecture.md.
Changes:
- Add ClosedBySession field to Issue struct
- Add closed_by_session column to issues table (migration 034)
- Add --session flag to bd close command
- Support CLAUDE_SESSION_ID env var as fallback
- Add --session flag to bd update for status=closed
- Display closed_by_session in bd show output
- Update Storage interface to include session parameter in CloseIssue
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Executed-By: beads/crew/dave
Rig: beads
Role: crew
Replaces manual working directory save/restore patterns
with Go's built-in `t.Chdir()` helper across 23 test files.
The manual pattern involved calling `os.Getwd()` to save
the original directory, using `defer os.Chdir(origWd)` for
restoration, and manually handling errors during directory
changes. This boilerplate has been replaced with single
`t.Chdir(path)` calls that handle cleanup automatically.
The `t.Chdir()` method automatically restores the working
directory when the test completes, eliminating the need for
manual defer statements and error handling.
Total:
~75 instances replaced (assuming Claude's math is right)
Co-authored-by: Claude <noreply@anthropic.com>
Expose full Storage interface and all types through public beads.go API,
enabling external Go projects (like VC) to import Beads directly instead
of spawning CLI processes.
Changes:
- Expanded beads.go with all public types (Issue, Dependency, Comment, etc.)
- Added all constants (Status, IssueType, DependencyType, EventType)
- Created comprehensive integration tests (beads_integration_test.go)
- Added library usage example at examples/library-usage/
- Documented library integration in README.md
Test coverage: 96.4% on public API, 14 integration tests, all passing.
Closes bd-58, bd-59
Amp-Thread-ID: https://ampcode.com/threads/T-f0093c79-7422-45e2-b0ed-0ddfebc9ffea
Co-authored-by: Amp <amp@ampcode.com>