fix: reliable metadata writes for Dolt backend (bd_version, repo_id, clone_id) by peterkc · Pull Request #1741 · steveyegge/beads

peterkc · 2026-02-14T17:26:53Z

Summary

Fixes #1725 — bd init --backend dolt silently swallows metadata write failures, leaving databases without bd_version, repo_id, and clone_id. This PR adds three complementary repair paths so metadata is reliably set regardless of how a Dolt database was created.

Repair Paths

              Three paths to reliable metadata
              ================================

  NEW DB                    EXISTING DB               UPGRADING DB
    |                           |                          |
    v                           v                          v
  bd init                   bd doctor --fix            bd migrate
    |                           |                          |
    v                           v                          v
  verifyMetadata()          FixMissingMetadata()       handleDoltMetadataUpdate()
  [write + read-back]       [detect gaps + fill]       [check all 3 + fill gaps]
    |                           |                          |
    +--------> bd_version <-----+---------> bd_version <---+
    +--------> repo_id    <-----+---------> repo_id    <---+
    +--------> clone_id   <-----+---------> clone_id   <---+

  Error handling:
    bd_version  = FATAL (required for version checks)
    repo_id     = WARN + continue (degrades gracefully)
    clone_id    = WARN + continue (degrades gracefully)

Changes

1. Belt-and-suspenders init (`init.go`)

verifyMetadata() helper: write + read-back verification for each metadata field. On failure: warns with actionable guidance ("run bd doctor --fix"). Preserves existing Pattern B (warn-and-continue) semantics.

2. Doctor fix remediation (`doctor/fix/metadata.go`)

New FixMissingMetadata check for bd doctor --fix. Detects and repairs missing fields on existing Dolt databases. Identity fields are non-fatal.

3. Migration metadata extension (`migrate.go`)

handleDoltMetadataUpdate() now sets all three fields. Checks upfront; early-returns only when ALL are present.

  handleDoltMetadataUpdate() -- before vs after

  BEFORE:                          AFTER:
    |                                |
    v                                v
  read bd_version                  read bd_version, repo_id, clone_id
    |                                |
    +-- matches? --> return          +-- ALL present? --> return
    |                                |
    v                                v
  set bd_version                   set bd_version (if needed, FATAL)
    |                                |
    v                                v
  return                           set repo_id (if needed, WARN)
                                     |
                                     v
                                   set clone_id (if needed, WARN)

4. Lint cleanup (`init.go`)

Removed unused quiet parameter from verifyMetadata (golangci-lint unparam finding).

Commit Guide

Commit	Scope	Focus
`8235e227`	init.go, init_test.go, e2e	Belt-and-suspenders write + verify
`f78558d8`	doctor/fix/, doctor_fix.go, e2e	FixMissingMetadata check
`79ac5fda`	migrate.go, migrate tests, e2e	Extend handleDoltMetadataUpdate
`fccbc535`	init.go, init_test.go	Remove unused quiet param (lint)

Testing

Unit tests: init verification (7), doctor fix (3 memory + 3 CGO-gated Dolt), migrate metadata (3 CGO-gated)
E2E tests: init->doctor roundtrip, doctor fix roundtrip, migrate metadata roundtrip (all //go:build cgo && integration)
Regression: make test clean (4 pre-existing failures in internal/syncbranch unrelated)
Lint: golangci-lint run --new-from-rev=upstream/main — 0 issues

Review Guidance

Priority	Files	Why
High	`migrate.go`	Restructured `handleDoltMetadataUpdate` — early-return logic changed
High	`doctor/fix/metadata.go`	New fix check — error handling for identity fields
Medium	`init.go`	`verifyMetadata` helper — straightforward write+read-back
Low	`doctor_fix.go`, `doctor/*.go`	Wiring + message updates
Low	`_test.go`, `_e2e_test.go`	Test coverage (patterns match existing codebase)

…kend bd init --backend dolt silently swallowed metadata write failures for bd_version, repo_id, and clone_id. Doctor and daemon then failed with confusing errors about missing metadata. Add verifyMetadata() helper that writes each field then reads it back, emitting a specific warning with "bd doctor --fix" guidance on failure. Init continues (non-fatal) but failures are now visible and actionable. - Add verifyMetadata() write+verify helper to init.go - Replace Pattern B (warn-and-swallow) with belt-and-suspenders pattern - Handle non-git environments gracefully (skip repo_id with warning) - Add function-level tests for all 3 fields, failure paths, and edge cases - Add e2e test for init→doctor roundtrip validation Refs: steveyegge#1725

… messages Add doctor --fix metadata remediation for existing Dolt databases missing bd_version, repo_id, or clone_id. Wire into both Database and Repo Fingerprint doctor check cases. Update fix messages to suggest 'bd doctor --fix' instead of 'bd migrate'.

Problem: - Migration skipped repo_id and clone_id when bd_version matched - Missing identity fields left Dolt metadata incomplete Solution: - Extend Dolt metadata migration to set repo_id and clone_id - Cover migration paths with unit and e2e tests Impact: - Repositories keep identity fields even when version is current - Metadata migration behaves consistently across scenarios

golangci-lint flagged the quiet parameter as unused (unparam). The function always prints warnings on failure, and callers already gate success messages externally. Metadata write warnings should always be visible regardless of quiet mode.

peterkc · 2026-02-14T17:51:57Z

CI Notes

4 of the CI checks show failures. Here's a breakdown:

Pre-existing (not from this PR)

Check	Failure	Evidence
Lint	`help_all.go` errcheck (3 findings)	File not touched by this PR
Check formatting	`sync_git_remote_test.go` gofmt	File not touched by this PR
Test (ubuntu)	`TestGetConfigFromDB/returns_value_when_key_exists`	`internal/syncbranch` — fails on `upstream/main` too
Test (macOS)	Same as ubuntu + `TestCheckDatabaseJSONLSync_UsesSyncWorktreeJSONL`, `TestCheckSyncDivergence_UsesSyncWorktreeJSONLForMtime`	`internal/syncbranch` + `cmd/bd/doctor` — not in our diff

Fixed in this push

Check	Issue	Fix
Check formatting	`migrate.go` map literal alignment	`gofmt -w` applied (force-pushed)

All failures are in files and packages outside this PR's scope (internal/syncbranch, cmd/bd/doctor JSONL tests, help_all.go).

…clone_id) (steveyegge#1741) * fix(init): add belt-and-suspenders metadata verification for Dolt backend bd init --backend dolt silently swallowed metadata write failures for bd_version, repo_id, and clone_id. Doctor and daemon then failed with confusing errors about missing metadata. Add verifyMetadata() helper that writes each field then reads it back, emitting a specific warning with "bd doctor --fix" guidance on failure. Init continues (non-fatal) but failures are now visible and actionable. - Add verifyMetadata() write+verify helper to init.go - Replace Pattern B (warn-and-swallow) with belt-and-suspenders pattern - Handle non-git environments gracefully (skip repo_id with warning) - Add function-level tests for all 3 fields, failure paths, and edge cases - Add e2e test for init→doctor roundtrip validation Refs: steveyegge#1725 * fix(doctor): add FixMissingMetadata for Dolt databases and update fix messages Add doctor --fix metadata remediation for existing Dolt databases missing bd_version, repo_id, or clone_id. Wire into both Database and Repo Fingerprint doctor check cases. Update fix messages to suggest 'bd doctor --fix' instead of 'bd migrate'. * fix(migrate): set repo_id and clone_id when version is current Problem: - Migration skipped repo_id and clone_id when bd_version matched - Missing identity fields left Dolt metadata incomplete Solution: - Extend Dolt metadata migration to set repo_id and clone_id - Cover migration paths with unit and e2e tests Impact: - Repositories keep identity fields even when version is current - Metadata migration behaves consistently across scenarios * fix(init): remove unused quiet parameter from verifyMetadata golangci-lint flagged the quiet parameter as unused (unparam). The function always prints warnings on failure, and callers already gate success messages externally. Metadata write warnings should always be visible regardless of quiet mode.

peterkc added 3 commits February 14, 2026 07:08

peterkc marked this pull request as ready for review February 14, 2026 17:50

peterkc force-pushed the fix/dolt-init-metadata branch from fccbc53 to 98b090a Compare February 14, 2026 17:51

steveyegge merged commit f7311e9 into steveyegge:main Feb 14, 2026
4 of 8 checks passed

peterkc deleted the fix/dolt-init-metadata branch February 15, 2026 00:39

peterkc mentioned this pull request Feb 17, 2026

:-( DOLT - AI Recommends To Drop Beads #1812

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: reliable metadata writes for Dolt backend (bd_version, repo_id, clone_id)#1741

fix: reliable metadata writes for Dolt backend (bd_version, repo_id, clone_id)#1741
steveyegge merged 4 commits intosteveyegge:mainfrom
peterkc:fix/dolt-init-metadata

peterkc commented Feb 14, 2026 •

edited

Loading

Uh oh!

peterkc commented Feb 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

peterkc commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Repair Paths

Changes

1. Belt-and-suspenders init (init.go)

2. Doctor fix remediation (doctor/fix/metadata.go)

3. Migration metadata extension (migrate.go)

4. Lint cleanup (init.go)

Commit Guide

Testing

Review Guidance

Uh oh!

peterkc commented Feb 14, 2026

CI Notes

Pre-existing (not from this PR)

Fixed in this push

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

peterkc commented Feb 14, 2026 •

edited

Loading

1. Belt-and-suspenders init (`init.go`)

2. Doctor fix remediation (`doctor/fix/metadata.go`)

3. Migration metadata extension (`migrate.go`)

4. Lint cleanup (`init.go`)