fix(dolt): stop telling bd init not to run bd init on an identity mismatch (#5558) (#6745)

* fix(dolt): stop telling bd init not to run bd init on an identity mismatch (#5558)

Root cause: GH#4637 Part A made newServerMode run verifyProjectIdentity for a
CreateIfMissing open whenever the database already existed on the server, so
the check is now reachable from inside bd init (a re-init whose metadata.json
already carries a project_id, against a server whose database of that name
belongs to another project). The refusal it returns was written only for
ordinary opens and ends in "Do NOT run 'bd init'", telling the user not to
run the command they are running, with no remedy that works from there.

Fix: extract the message into a pure projectIdentityMismatchError and pass
cfg.CreateIfMissing through verifyProjectIdentity. The init-time variant
names the database and points at remedies that apply to an init: re-run with
bd init --database <name> or --server-host/--server-port, or run
bd doctor --fix / bd bootstrap when metadata.json is the stale side. The
ordinary-open message is unchanged, and whether the check runs is unchanged.
A unit test pins both variants.

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(dolt): key the init wording on an explicit OpenedByInit, not CreateIfMissing (#6745 review)

CreateIfMissing does not identify bd init. The library API
(beads.OpenFromConfig, beads.OpenGated), bd doctor --fix and bd bootstrap
open with it too, so they were getting the init-time advice on an identity
mismatch, and doctor and bootstrap were told to run themselves.

- New dolt.Config.OpenedByInit, set only by bd init's open (init.go), now
  selects the init wording. Whether the check runs is unchanged.
- The init advice no longer presents `bd init --database` as a sure fix:
  checkExistingBeadsDataAt can refuse it as "already initialized" when
  metadata.json names an existing server database. The message says to
  follow init's own steps in that case, and names this project's server
  first.
- TestCrossProject_IdentityCheck_ExistingDatabase_ForeignRejected now pins
  the wiring through New. A CreateIfMissing-only open keeps the
  ordinary-open advice, and an OpenedByInit open gets the init wording.
  It needs a Dolt server, so it runs in CI.

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs(changelog): match the #5558 entry to the OpenedByInit wiring

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(dolt): align the init mismatch block, and narrow the #5558 repro

Maintainer review fixup for PR #6745 (adopt-pr iteration 1). Synthesis and
quality scorecard both say approve with no blocker or major findings; these
are the non-gating nits, taken because all three sit in the material this PR
exists to improve — the refusal message and the test that pins it.

- Both reviewers flagged that the init variant interpolates the database name
  into the label column ("Database %q project ID:"), so the two ID values line
  up only for a 7-character name. Give the database its own line and restore
  the aligned pair the ordinary-open branch already uses. Rendered for a 5-,
  9- and 30-character database name: both columns now line up in every case.
- Rendering also turned up a line the diff alone does not show: the
  "already initialized" parenthetical was 84 columns in a block hand-wrapped
  at ~78. Rewrapped; every line of both messages is now <= 79.
- The new test's subtest name ("create-if-missing") and doc comment still
  stated the selector commit d48a83655 deliberately rejected, and that the
  sibling assertion in cross_project_test.go now calls wrong. Re-keyed both
  on Config.OpenedByInit.
- The CHANGELOG described the repro as plainly re-running `bd init` in an
  initialized workspace. That shape is intercepted before the store open by
  checkExistingBeadsData (cmd/bd/init.go:801-802, bypassed only by
  --reinit-local/--force), so it is not the reachable one; the refusal is
  reached when the open is redirected at another server or database. Restated
  as the condition rather than an unreachable recipe. The PR body carries the
  same wording and is left for the maintainer to amend at finalize.

Deliberately not taken: the synthesis's one minor (pin `OpenedByInit: true` at
cmd/bd/init.go:1382 with a cmd/bd assertion). The prescribed remedy — extract
the dolt.Config construction at cmd/bd/init.go:1372-1389 into a testable
builder — is a refactor of a literal that lives inside init's cobra RunE
closure over ~15 captured locals, in the file whose worst_changed function is
already the scorecard's complexity penalty (newServerMode, 51/101). That is
not the "nearby, cheap, low-risk" cleanup the contract allows opportunistically,
and the finding is non-gating. Worth a follow-up issue instead.

Validation: go build ./... clean; go vet ./internal/storage/dolt clean;
go test ./internal/storage/dolt -run
'TestProjectIdentityMismatchError_InitAdvice|TestCrossProject_IdentityCheck_ExistingDatabase_ForeignRejected|TestCrossProject_IdentityCheck_ExistingDatabase_MatchingSucceeds'
all PASS against a live Dolt container.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
This commit is contained in:
Harry Miller 2026-09-26 03:12:04 -07:00 • committed by GitHub
commit 7a81e297d9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 140 additions and 8 deletions

View file

@ -157,6 +157,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
with no `--max-rows` flag to refuse. Rules are keyed on the full command
path now.
- **`bd init` no longer tells you not to run `bd init` when it refuses a
foreign database** ([#5558](https://github.com/gastownhall/beads/issues/5558)).
When `bd init` opens a server database that already exists and belongs to a
different project — for example when `--server-host`/`--server-port`/
`--database` point it somewhere other than this workspace's own server — it
correctly refuses with `PROJECT IDENTITY MISMATCH`, but the refusal was the
one written for ordinary opens, ending in "Do NOT run 'bd init'". The
init-time refusal now names the database and points at remedies that work
from there: point `bd init` at this project's server
(`--server-host`/`--server-port`) or an unused database name
(`--database`), or run `bd doctor --fix` / `bd bootstrap` if `metadata.json`
is the stale side. Only `bd init`'s own open gets this wording; every other
open, including the library API, `bd doctor --fix` and `bd bootstrap`, keeps
the existing message.
### Changed
- **Proxied-server refusals now say *why* they refuse.** The JSON a refused

View file

@ -1379,6 +1379,7 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
ServerMode: initServerMode,
ProxiedServer: initProxiedServer,
CreateIfMissing: true, // bd init is the only path that should create databases
OpenedByInit: true, // shapes the identity-mismatch advice (GH#5558)
AutoStart: initServerMode && os.Getenv("BEADS_DOLT_AUTO_START") != "0",
ServerTLS: initDoltServerTLSFromEnv(),
}

View file

@ -770,6 +770,23 @@ func TestCrossProject_IdentityCheck_ExistingDatabase_ForeignRejected(t *testing.
if !strings.Contains(err.Error(), "PROJECT IDENTITY MISMATCH") {
t.Fatalf("expected PROJECT IDENTITY MISMATCH error, got: %v", err)
}
// CreateIfMissing alone is not bd init: the library API, bd doctor --fix
// and bd bootstrap open this way too, and keep the ordinary-open advice
// (GH#5558). Only Config.OpenedByInit selects the init wording.
if strings.Contains(err.Error(), "refusing to initialize") {
t.Errorf("a non-init CreateIfMissing open got the bd init wording: %v", err)
}
initCfg := f.config()
initCfg.OpenedByInit = true
initStore, err := New(ctx, initCfg)
if err == nil {
initStore.Close()
t.Fatalf("expected identity mismatch error for the bd init open, got nil")
}
if !strings.Contains(err.Error(), "refusing to initialize") || strings.Contains(err.Error(), "Do NOT run 'bd init'") {
t.Errorf("the bd init open did not get the init wording: %v", err)
}
}
// TestCrossProject_IdentityCheck_ExistingDatabase_MatchingSucceeds is the

View file

@ -0,0 +1,52 @@
package dolt
import (
"strings"
"testing"
)
// TestProjectIdentityMismatchError_InitAdvice pins GH#5558: when the identity
// check fires inside bd init (Config.OpenedByInit), the refusal must not tell
// the user not to run the command they are running, and must name remedies that
// work from there. Every other open keeps its original advice — including a
// CreateIfMissing open, which is not by itself bd init.
func TestProjectIdentityMismatchError_InitAdvice(t *testing.T) {
const localID, dbID, database = "project-AAAA", "project-BBBB", "shared_db"
t.Run("opened-by-init", func(t *testing.T) {
msg := projectIdentityMismatchError(localID, dbID, database, true).Error()
if strings.Contains(msg, "Do NOT run 'bd init'") {
t.Errorf("init-time refusal tells the user not to run bd init:\n%s", msg)
}
for _, want := range []string{
"PROJECT IDENTITY MISMATCH",
localID,
dbID,
`"` + database + `"`,
"bd dolt status",
"bd init --database <other-name>",
"bd init --server-host <host> --server-port <port>",
"bd doctor --fix",
"bd bootstrap",
} {
if !strings.Contains(msg, want) {
t.Errorf("init-time refusal missing %q:\n%s", want, msg)
}
}
})
t.Run("normal open", func(t *testing.T) {
msg := projectIdentityMismatchError(localID, dbID, database, false).Error()
for _, want := range []string{
"PROJECT IDENTITY MISMATCH — refusing to connect",
localID,
dbID,
"bd dolt status",
"Do NOT run 'bd init' — your data likely exists, just on a different server.",
} {
if !strings.Contains(msg, want) {
t.Errorf("normal-open refusal missing %q:\n%s", want, msg)
}
}
})
}

View file

@ -435,6 +435,14 @@ type Config struct {
// creation of shadow databases on the wrong server.
CreateIfMissing bool
// OpenedByInit marks the open `bd init` makes. It only shapes the advice in
// a project-identity mismatch error (GH#5558), never whether the check runs.
// It is a field of its own because CreateIfMissing does not identify init:
// the library API (beads.OpenFromConfig, beads.OpenGated), `bd doctor --fix`
// and `bd bootstrap` open with CreateIfMissing too, and must not be told to
// re-run bd init.
OpenedByInit bool
// ServerMode indicates this config targets an external dolt sql-server
// rather than the embedded Dolt engine. Set by the store factory based
// on metadata.json dolt_mode or BEADS_DOLT_SERVER_MODE env var.
@ -2045,7 +2053,7 @@ func newServerMode(ctx context.Context, cfg *Config) (*DoltStore, error) {
if cfg.Database == doltserver.GlobalDatabaseName {
verifyErr = store.verifyGlobalProjectIdentity(ctx, cfg.BeadsDir)
} else {
verifyErr = store.verifyProjectIdentity(ctx, cfg.BeadsDir)
verifyErr = store.verifyProjectIdentity(ctx, cfg.BeadsDir, cfg.OpenedByInit)
}
if verifyErr != nil {
return nil, verifyErr
@ -2208,7 +2216,9 @@ func shouldPersistResolvedPortFile() bool {
// verifyProjectIdentity checks that the database belongs to the expected project.
// If both the local metadata.json and the database have a project_id, they must match.
// Returns nil if verification passes or is not applicable (missing IDs = old setup).
func (s *DoltStore) verifyProjectIdentity(ctx context.Context, beadsDir string) error {
// openedByInit is Config.OpenedByInit: it only shapes the error's advice (see
// projectIdentityMismatchError), never whether the check runs.
func (s *DoltStore) verifyProjectIdentity(ctx context.Context, beadsDir string, openedByInit bool) error {
if beadsDir == "" {
return nil // can't verify without knowing beadsDir
}
@ -2230,21 +2240,58 @@ func (s *DoltStore) verifyProjectIdentity(ctx context.Context, beadsDir string)
}
if localID != dbID {
return fmt.Errorf(
"PROJECT IDENTITY MISMATCH — refusing to connect\n\n"+
" Local project ID (metadata.json): %s\n"+
" Database project ID: %s\n\n"+
"This means the Dolt server is serving a DIFFERENT project's database.\n"+
"This can happen when:\n"+
" - Another project's server is running on the same port\n"+
" - The server restarted with a different data directory\n\n"+
"To diagnose: bd dolt status\n"+
"Do NOT run 'bd init' — your data likely exists, just on a different server.",
localID, dbID)
return projectIdentityMismatchError(localID, dbID, s.database, openedByInit)
}
return nil
}
// projectIdentityMismatchError builds verifyProjectIdentity's refusal when
// metadata.json and the database disagree on project_id.
//
// openedByInit is true only for bd init's own open (Config.OpenedByInit), which
// since GH#4637 Part A runs this check against a database that already exists
// on the server. That caller IS bd init, so it must not be told "Do NOT run
// 'bd init'" (GH#5558); it gets the remedies that make sense from inside an
// init instead. Every other open, CreateIfMissing or not, keeps its original
// text.
func projectIdentityMismatchError(localID, dbID, database string, openedByInit bool) error {
if openedByInit {
return fmt.Errorf(
"PROJECT IDENTITY MISMATCH — refusing to initialize against an existing database\n\n"+
// The database name is variable-length, so it gets its own line:
// interpolating it into a label would unalign the two ID columns.
" Database: %q\n"+
" Local project ID (metadata.json): %s\n"+
" Database project ID: %s\n\n"+
"The Dolt server already has a database with this name, and it belongs to\n"+
"a DIFFERENT project. bd init will not adopt or write to it.\n"+
"This can happen when:\n"+
" - Another project's server is running on the same port\n"+
" - Another project already uses this database name on a shared server\n"+
" - The server restarted with a different data directory\n\n"+
"To diagnose: bd dolt status\n"+
"To fix, point bd init at this project's data instead:\n"+
" - this project's server: bd init --server-host <host> --server-port <port>\n"+
" - an unused database: bd init --database <other-name>\n"+
" (if bd init then reports the workspace is already initialized,\n"+
" follow those steps)\n"+
"If this database really is this project's and metadata.json is stale,\n"+
"run 'bd doctor --fix' or 'bd bootstrap' to reconcile metadata.json with it.",
database, localID, dbID)
}
return fmt.Errorf(
"PROJECT IDENTITY MISMATCH — refusing to connect\n\n"+
" Local project ID (metadata.json): %s\n"+
" Database project ID: %s\n\n"+
"This means the Dolt server is serving a DIFFERENT project's database.\n"+
"This can happen when:\n"+
" - Another project's server is running on the same port\n"+
" - The server restarted with a different data directory\n\n"+
"To diagnose: bd dolt status\n"+
"Do NOT run 'bd init' — your data likely exists, just on a different server.",
localID, dbID)
}
func (s *DoltStore) verifyGlobalProjectIdentity(ctx context.Context, beadsDir string) error {
if beadsDir == "" {
return nil