feat(storage): add extension-safe backend registry seam (#4859)

* feat(storage): add downstream backend registry seam (bd-7oj)

Salvage the name-keyed extension contract from PR #4859 on current main while preserving the Dolt-only OSS policy. Stock builds register no alternate backends; tombstones and unknown names still fail closed. Downstream builds can register read-write/read-only opens and workspace discovery without editing shared dispatch.

Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of CI Bot

* fix(storage): dispatch and fail-closed for registered backends

Address review majors on the backend registry seam:

- bd init rejects a registered backend (open-existing-workspace-only)
  instead of silently provisioning Dolt and persisting backend: dolt.
- OpenBestAvailable dispatches registered backends before any Dolt path
  in both CGO and non-CGO builds, mirroring the CLI store factories.
- Public FindDatabasePath discovers WorkspaceIsBeadsDir workspaces via
  the shared registry authority instead of returning no database.
- Root command reuses the resolved .beads directory for hook-runner and
  molecule-catalog setup instead of filepath.Dir(dbPath). For a registered
  WorkspaceIsBeadsDir backend dbPath is the .beads directory itself, so
  filepath.Dir(dbPath) loaded hooks from <repo>/hooks and molecules from
  <repo>/molecules.jsonl instead of .beads/hooks and .beads/molecules.jsonl.

Add a single WorkspaceIsBeadsDir authority, document the init-time
registration invariant, and cover the paths with tests, including a
root-command test proving the .beads hook and molecule directories are
selected for WorkspaceIsBeadsDir backends.

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

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-07-31 03:05:48 -07:00 • committed by GitHub
commit 9fddc56055
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 904 additions and 19 deletions

View file

@ -7,6 +7,7 @@ import (
"fmt"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/storage/embeddeddolt"
)
@ -33,6 +34,13 @@ func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) {
return nil, configuredBackendUnavailable(cfg.Backend)
}
// Dispatch to a registered extension backend before any Dolt path, mirroring
// the CLI store factories so SDK callers get the backend they registered
// instead of a silently-opened embedded Dolt store.
if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
return backend.Open(ctx, beadsDir)
}
if cfg.IsDoltServerMode() {
store, err := dolt.NewFromConfig(ctx, beadsDir)
if err != nil {

View file

@ -7,6 +7,7 @@ import (
"fmt"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/storage/dolt"
)
@ -27,6 +28,13 @@ func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) {
return nil, configuredBackendUnavailable(cfg.Backend)
}
// Dispatch to a registered extension backend before any Dolt path, mirroring
// the CLI store factories so SDK callers get the backend they registered
// instead of the embedded-Dolt-requires-CGO error.
if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
return backend.Open(ctx, beadsDir)
}
if cfg.IsDoltServerMode() {
store, err := dolt.NewFromConfig(ctx, beadsDir)
if err != nil {

View file

@ -0,0 +1,85 @@
package main
import (
"context"
"errors"
"testing"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
)
var (
errRegistryReadWrite = errors.New("registry read-write open")
errRegistryReadOnly = errors.New("registry read-only open")
)
func registerContractBackend(t *testing.T, name string) {
t.Helper()
backends.Register(name, backends.Backend{
Open: func(context.Context, string) (storage.DoltStorage, error) {
return nil, errRegistryReadWrite
},
OpenReadOnly: func(context.Context, string) (storage.DoltStorage, error) {
return nil, errRegistryReadOnly
},
WorkspaceIsBeadsDir: true,
})
t.Cleanup(func() { backends.Deregister(name) })
}
func writeContractBackendConfig(t *testing.T, backend string) string {
t.Helper()
beadsDir := t.TempDir()
if err := (&configfile.Config{Backend: backend}).Save(beadsDir); err != nil {
t.Fatalf("save metadata.json: %v", err)
}
return beadsDir
}
func TestRegisteredBackendDispatchesReadWriteAndReadOnly(t *testing.T) {
const name = "contract"
registerContractBackend(t, name)
beadsDir := writeContractBackendConfig(t, name)
if err := validateConfiguredBackend(&configfile.Config{Backend: name}); err != nil {
t.Fatalf("validateConfiguredBackend() rejected registered backend: %v", err)
}
if _, err := newDoltStoreFromConfig(t.Context(), beadsDir); !errors.Is(err, errRegistryReadWrite) {
t.Fatalf("read-write factory error = %v, want %v", err, errRegistryReadWrite)
}
if _, err := newReadOnlyStoreFromConfig(t.Context(), beadsDir); !errors.Is(err, errRegistryReadOnly) {
t.Fatalf("read-only factory error = %v, want %v", err, errRegistryReadOnly)
}
}
func TestRegisteredBackendDrivesWorkspaceDiscovery(t *testing.T) {
const name = "contract-discovery"
registerContractBackend(t, name)
if !registeredBackendWorkspaceIsBeadsDir(&configfile.Config{Backend: name}) {
t.Fatal("registered backend did not expose its .beads workspace")
}
if registeredBackendWorkspaceIsBeadsDir(&configfile.Config{Backend: "unregistered"}) {
t.Fatal("unregistered backend exposed a .beads workspace")
}
if registeredBackendWorkspaceIsBeadsDir(&configfile.Config{Backend: configfile.BackendDolt}) {
t.Fatal("Dolt must retain its existing database discovery path")
}
}
func TestOSSRegistersNoRemovedBackends(t *testing.T) {
for _, name := range []string{
configfile.BackendPostgres,
configfile.BackendMySQL,
configfile.BackendSQLite,
} {
if backends.Registered(name) {
t.Errorf("OSS unexpectedly registered removed backend %q", name)
}
if err := validateConfiguredBackend(&configfile.Config{Backend: name}); err == nil {
t.Errorf("OSS unexpectedly accepted removed backend %q", name)
}
}
}

View file

@ -4,12 +4,16 @@ import (
"fmt"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage/backends"
)
func validateConfiguredBackend(cfg *configfile.Config) error {
if cfg == nil {
return nil
}
if backends.Registered(cfg.Backend) {
return nil
}
switch cfg.Backend {
case configfile.BackendPostgres, configfile.BackendMySQL, configfile.BackendSQLite:
return configfile.RemovedBackendError(cfg.Backend)
@ -20,6 +24,15 @@ func validateConfiguredBackend(cfg *configfile.Config) error {
}
}
// registeredBackendWorkspaceIsBeadsDir reports whether metadata selects a
// backend that has no separately discoverable local database.
func registeredBackendWorkspaceIsBeadsDir(cfg *configfile.Config) bool {
if cfg == nil {
return false
}
return backends.WorkspaceIsBeadsDir(cfg.GetBackend())
}
func requireDoltBackend(cfg *configfile.Config) error {
if err := validateConfiguredBackend(cfg); err != nil {
return err

View file

@ -283,6 +283,16 @@ func requireBootstrapDoltBackend(cfg *configfile.Config) error {
if err := validateConfiguredBackend(cfg); err != nil {
return err
}
// A registered extension backend passes validateConfiguredBackend so its
// existing workspaces can be opened, but every bd bootstrap action
// (sync, restore, jsonl-import, init) provisions or imports Dolt. Registered
// backends are open/discover-only, so reject them here — before
// detectBootstrapAction or executeBootstrapPlan — mirroring bd init's
// fail-closed gate. Downstream registrants supply their own workspace
// provisioning path.
if cfg != nil && cfg.GetBackend() != configfile.BackendDolt {
return fmt.Errorf("backend %q cannot be bootstrapped by bd bootstrap; it can only open an existing workspace (bd bootstrap provisions %q, the default)", cfg.GetBackend(), configfile.BackendDolt)
}
return nil
}

View file

@ -0,0 +1,140 @@
package main
import (
"bytes"
"io"
"os"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/configfile"
)
// TestRequireBootstrapDoltBackendRejectsRegisteredBackend pins the bootstrap
// fail-closed guard: a registered extension backend is open/discover-only, but
// every bd bootstrap action provisions or imports Dolt, so the guard must
// reject it with open-existing-workspace-only guidance. The default and
// explicit Dolt configs — the only workspaces bootstrap actually provisions —
// must still pass. This is the unit-level twin of TestInitRejectsRegisteredBackend.
func TestRequireBootstrapDoltBackendRejectsRegisteredBackend(t *testing.T) {
const name = "registry-bootstrap"
registerContractBackend(t, name)
err := requireBootstrapDoltBackend(&configfile.Config{Backend: name})
if err == nil {
t.Fatal("requireBootstrapDoltBackend accepted a registered backend; want fail-closed rejection")
}
if !strings.Contains(err.Error(), name) || !strings.Contains(err.Error(), "open an existing workspace") {
t.Fatalf("reject error = %v, want open-existing-workspace-only guidance naming %q", err, name)
}
// The guard must not reject the cases bd bootstrap is meant to provision:
// the default config, an unset backend (GetBackend normalizes "" to dolt),
// and an explicit dolt selection.
for _, tc := range []struct {
label string
cfg *configfile.Config
}{
{"default", configfile.DefaultConfig()},
{"empty backend", &configfile.Config{}},
{"explicit dolt", &configfile.Config{Backend: configfile.BackendDolt}},
} {
if err := requireBootstrapDoltBackend(tc.cfg); err != nil {
t.Errorf("requireBootstrapDoltBackend rejected the %s config: %v", tc.label, err)
}
}
}
// TestBootstrapRejectsRegisteredBackendBeforeWorkspaceWrites drives the guard
// through the real bd bootstrap command path: a workspace whose metadata.json
// selects a registered backend is rejected before any Dolt provisioning, the
// guidance reaches the user, and no local storage state is written. Registered
// backends are not compiled into the OSS binary, so this must run in-process —
// a subprocess bd would have no backend registered and could not reproduce the
// case (unlike the removed-backend guard tests, which use a subprocess).
func TestBootstrapRejectsRegisteredBackendBeforeWorkspaceWrites(t *testing.T) {
const name = "registry-bootstrap-e2e"
registerContractBackend(t, name)
beadsDir := writeContractBackendConfig(t, name)
metadataPath := filepath.Join(beadsDir, configfile.ConfigFileName)
metadataBefore, err := os.ReadFile(metadataPath)
if err != nil {
t.Fatalf("read seeded metadata.json: %v", err)
}
// bd bootstrap runs on the shared cobra command and reads package globals;
// snapshot and restore what the run can touch so the registered backend and
// flag state cannot leak into other tests sharing this state.
origDBPath := dbPath
origStore := store
origJSON := jsonOutput
t.Cleanup(func() {
if store != nil && store != origStore {
store.Close()
}
store = origStore
dbPath = origDBPath
jsonOutput = origJSON
_ = bootstrapCmd.Flags().Set("yes", "false")
})
dbPath = ""
store = nil
jsonOutput = false
t.Setenv("BEADS_DIR", beadsDir)
t.Setenv("BD_NON_INTERACTIVE", "1")
t.Setenv("BD_DISABLE_METRICS", "1")
t.Setenv("BD_DISABLE_EVENT_FLUSH", "1")
var execErr error
stderr := captureBootstrapStderr(t, func() {
rootCmd.SetArgs([]string{"bootstrap", "--yes"})
execErr = rootCmd.Execute()
})
if execErr == nil {
t.Fatalf("bd bootstrap accepted a registered backend; want fail-closed rejection\nstderr:\n%s", stderr)
}
if !strings.Contains(stderr, name) || !strings.Contains(stderr, "open an existing workspace") {
t.Fatalf("bootstrap reject stderr missing open-existing-workspace-only guidance naming %q:\n%s", name, stderr)
}
// Failing closed means the metadata is untouched and no Dolt state was
// provisioned for the unprovisionable backend.
metadataAfter, err := os.ReadFile(metadataPath)
if err != nil {
t.Fatalf("read metadata.json after rejected bootstrap: %v", err)
}
if !bytes.Equal(metadataAfter, metadataBefore) {
t.Errorf("rejected bootstrap rewrote metadata.json:\nbefore:\n%s\nafter:\n%s", metadataBefore, metadataAfter)
}
assertNoBootstrapStorageArtifacts(t, beadsDir)
}
// captureBootstrapStderr redirects os.Stderr for the duration of fn and returns
// what was written. bd bootstrap surfaces the guard message through HandleError,
// which writes to os.Stderr and returns an opaque exit error, so the message is
// only observable here — not on the error returned by rootCmd.Execute().
func captureBootstrapStderr(t *testing.T, fn func()) string {
t.Helper()
r, w, err := os.Pipe()
if err != nil {
t.Fatalf("os.Pipe: %v", err)
}
orig := os.Stderr
os.Stderr = w
done := make(chan string, 1)
go func() {
var buf bytes.Buffer
_, _ = io.Copy(&buf, r)
done <- buf.String()
}()
fn()
os.Stderr = orig
_ = w.Close()
out := <-done
_ = r.Close()
return out
}

View file

@ -23,6 +23,7 @@ import (
"github.com/steveyegge/beads/internal/git"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/storage/dbproxy/proxy"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/storage/schema"
@ -434,6 +435,14 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
}
return fmt.Errorf("unknown backend %q: the supported backend is \"dolt\" (default)", backendFlag)
}
// A registered extension backend passes IsSupportedBackend so its
// existing workspaces can be opened, but init provisions Dolt only and
// would otherwise create the workspace and persist backend: dolt. Reject
// it here rather than silently creating the wrong workspace; downstream
// registrants supply their own workspace-creation path.
if backends.Registered(backendFlag) {
return fmt.Errorf("backend %q cannot be created by bd init; it can only open an existing workspace (bd init provisions \"dolt\", the default)", backendFlag)
}
for _, legacyFlag := range removedBackendInitFlags {
if cmd.Flags().Changed(legacyFlag.name) {
return fmt.Errorf("--%s belonged to %s: %s; use --backend=dolt (the default)", legacyFlag.name, legacyFlag.origin, legacyFlag.rationale)

View file

@ -0,0 +1,51 @@
package main
import (
"os"
"path/filepath"
"strings"
"testing"
)
// TestInitRejectsRegisteredBackend verifies bd init fails closed for a
// registered extension backend instead of silently provisioning Dolt and
// persisting backend: dolt. Registered backends can only open an existing
// workspace; provisioning is the downstream registrant's own contract.
func TestInitRejectsRegisteredBackend(t *testing.T) {
const name = "registry-init"
registerContractBackend(t, name)
// bd init runs on the shared cobra command and mutates package globals;
// snapshot and restore both so the registered backend and its flag value
// cannot leak into other init tests that share this state.
origDBPath := dbPath
origStore := store
t.Cleanup(func() {
if store != nil && store != origStore {
store.Close()
}
store = origStore
dbPath = origDBPath
_ = initCmd.Flags().Set("backend", "")
_ = initCmd.Flags().Set("prefix", "")
_ = initCmd.Flags().Set("quiet", "false")
})
dbPath = ""
store = nil
tmpDir := t.TempDir()
t.Chdir(tmpDir)
rootCmd.SetArgs([]string{"init", "--backend", name, "--prefix", "test", "--quiet"})
err := rootCmd.Execute()
if err == nil {
t.Fatal("bd init accepted a registered backend; want fail-closed rejection")
}
if !strings.Contains(err.Error(), name) || !strings.Contains(err.Error(), "open an existing workspace") {
t.Fatalf("init reject error = %v, want open-existing-workspace-only guidance naming %q", err, name)
}
// Failing closed means no workspace is written for the unprovisionable backend.
if _, statErr := os.Stat(filepath.Join(tmpDir, ".beads")); !os.IsNotExist(statErr) {
t.Fatalf("rejected init created a .beads workspace (stat error: %v)", statErr)
}
}

View file

@ -33,6 +33,7 @@ import (
"github.com/steveyegge/beads/internal/remotecache"
"github.com/steveyegge/beads/internal/routing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/storage/dolt"
dbidentifier "github.com/steveyegge/beads/internal/storage/domain/db"
"github.com/steveyegge/beads/internal/storage/schema"
@ -1091,12 +1092,13 @@ var rootCmd = &cobra.Command{
if dbPath == "" {
if bd := beads.FindBeadsDir(); bd != "" {
cfg, cfgErr := configfile.Load(bd)
if cfgErr != nil || cfg != nil && (cfg.IsDoltProxiedServerMode() || !configfile.IsSupportedBackend(cfg.Backend)) {
// Proxied-server and removed-backend workspaces may have no
// local Dolt database file. Invalid or unknown metadata likewise must
// reach config validation instead of becoming a generic "no database"
// result. metadata.json identifies the workspace so store selection can
// route or reject it explicitly.
if cfgErr != nil || cfg != nil && (cfg.IsDoltProxiedServerMode() ||
registeredBackendWorkspaceIsBeadsDir(cfg) ||
!configfile.IsSupportedBackend(cfg.Backend)) {
// Proxied-server, registered remote, and removed-backend
// workspaces may have no local Dolt database file. Invalid
// or unknown metadata likewise must reach config validation
// instead of becoming a generic "no database" result.
dbPath = bd
}
}
@ -1433,7 +1435,15 @@ var rootCmd = &cobra.Command{
// Removing them WILL cause unrecoverable data corruption and data loss.
// Dolt manages these files itself; external interference is never safe.
store, err = newDoltStore(rootCtx, doltCfg)
if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
if useReadOnly {
store, err = backend.OpenReadOnly(rootCtx, beadsDir)
} else {
store, err = backend.Open(rootCtx, beadsDir)
}
} else {
store, err = newDoltStore(rootCtx, doltCfg)
}
// Track final read-only state for staleness checks (GH#1089)
storeIsReadOnly = doltCfg.ReadOnly
@ -1499,10 +1509,13 @@ var rootCmd = &cobra.Command{
}
}
// Initialize hook runner
// dbPath is .beads/something.db, so workspace root is parent of .beads
if dbPath != "" {
beadsDir := filepath.Dir(dbPath)
// Initialize hook runner using the .beads directory resolved above via
// resolveCommandBeadsDir. Do not use filepath.Dir(dbPath): for a
// registered WorkspaceIsBeadsDir backend dbPath is the .beads directory
// itself, so filepath.Dir(dbPath) would load hooks from the repo root
// (<repo>/hooks) instead of .beads/hooks; custom dolt_data_dir layouts
// can likewise place the Dolt data outside .beads.
if beadsDir != "" {
hookRunner = hooks.NewRunner(filepath.Join(beadsDir, "hooks"))
}
@ -1520,7 +1533,9 @@ var rootCmd = &cobra.Command{
// Templates are loaded after auto-import to ensure the database is up-to-date.
// Skip for import command to avoid conflicts during import operations.
if cmd.Name() != "import" && store != nil {
beadsDir := filepath.Dir(dbPath)
// Reuse the resolved .beads directory (see the hook runner note
// above) so a registered WorkspaceIsBeadsDir workspace loads
// .beads/molecules.jsonl rather than <repo>/molecules.jsonl.
loader := molecules.NewLoader(store)
if result, err := loader.LoadAll(rootCtx, beadsDir); err != nil {
debug.Logf("warning: failed to load molecules: %v", err)

View file

@ -0,0 +1,117 @@
package main
import (
"os"
"path/filepath"
"testing"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/molecules"
)
// TestRegisteredBackendResolvesHookAndMoleculeDirsUnderBeads guards the root
// command's directory derivation for a registered WorkspaceIsBeadsDir backend.
//
// For such a backend the command sets dbPath to the .beads directory itself
// (main.go: `dbPath = bd` when registeredBackendWorkspaceIsBeadsDir(cfg) is
// true), not to a .beads/<db-file>. The hook runner and molecule loader must
// therefore resolve their directory from the beadsDir the command already
// computed with resolveCommandBeadsDir(dbPath), never from filepath.Dir(dbPath):
// for this case filepath.Dir(dbPath) is the repository root, so hooks and
// molecule templates would load from <repo>/hooks and <repo>/molecules.jsonl
// instead of .beads/hooks and .beads/molecules.jsonl.
//
// Driving the full PersistentPreRunE end-to-end would require a live
// storage.DoltStorage from the fake backend, which is impractical — the
// interface is large and has no test double (see
// internal/storage/hook_decorator_test.go). This test instead reproduces the
// exact directory-derivation chain the command uses and asserts the .beads
// hooks directory and molecule catalog are selected over repo-root decoys.
func TestRegisteredBackendResolvesHookAndMoleculeDirsUnderBeads(t *testing.T) {
const name = "contract-workspace-paths"
registerContractBackend(t, name)
repo := t.TempDir()
beadsDir := filepath.Join(repo, ".beads")
if err := os.MkdirAll(beadsDir, 0o755); err != nil {
t.Fatalf("mkdir .beads: %v", err)
}
if err := (&configfile.Config{Backend: name}).Save(beadsDir); err != nil {
t.Fatalf("save metadata.json: %v", err)
}
// The workspace's real hooks directory and molecule catalog live under .beads.
wantHooksDir := filepath.Join(beadsDir, "hooks")
if err := os.MkdirAll(wantHooksDir, 0o755); err != nil {
t.Fatalf("mkdir .beads/hooks: %v", err)
}
wantMoleculeFile := filepath.Join(beadsDir, molecules.MoleculeFileName)
if err := os.WriteFile(wantMoleculeFile, []byte("{}\n"), 0o644); err != nil {
t.Fatalf("write .beads/molecules.jsonl: %v", err)
}
// Decoys at the repository root: the pre-fix filepath.Dir(dbPath) code would
// have selected these instead of the .beads copies.
decoyHooksDir := filepath.Join(repo, "hooks")
if err := os.MkdirAll(decoyHooksDir, 0o755); err != nil {
t.Fatalf("mkdir decoy hooks: %v", err)
}
decoyMoleculeFile := filepath.Join(repo, molecules.MoleculeFileName)
if err := os.WriteFile(decoyMoleculeFile, []byte("{}\n"), 0o644); err != nil {
t.Fatalf("write decoy molecules.jsonl: %v", err)
}
// This workspace is exactly the case that makes the command use the .beads
// directory as dbPath.
cfg, err := configfile.Load(beadsDir)
if err != nil {
t.Fatalf("load metadata.json: %v", err)
}
if !registeredBackendWorkspaceIsBeadsDir(cfg) {
t.Fatal("registered WorkspaceIsBeadsDir backend not recognized; dbPath would not be the .beads directory")
}
// Mirror the command: dbPath is the .beads directory and the hook/molecule
// setup resolves the beads dir with resolveCommandBeadsDir(dbPath).
dbPath := beadsDir
gotBeadsDir := resolveCommandBeadsDir(dbPath)
requireSameFile(t, "resolved beads dir", gotBeadsDir, beadsDir)
requireSameFile(t, "hook runner dir", filepath.Join(gotBeadsDir, "hooks"), wantHooksDir)
requireSameFile(t, "molecule catalog", filepath.Join(gotBeadsDir, molecules.MoleculeFileName), wantMoleculeFile)
// Regression guard: the pre-fix filepath.Dir(dbPath) resolves to the repo
// root, so hooks and molecules would have loaded from the decoys, not .beads.
preFix := filepath.Dir(dbPath)
if sameExistingFile(preFix, beadsDir) {
t.Fatalf("filepath.Dir(dbPath)=%q unexpectedly equals .beads %q; regression guard is vacuous", preFix, beadsDir)
}
requireSameFile(t, "pre-fix hook dir resolves to repo-root decoy", filepath.Join(preFix, "hooks"), decoyHooksDir)
}
func requireSameFile(t *testing.T, label, got, want string) {
t.Helper()
gotInfo, err := os.Stat(got)
if err != nil {
t.Fatalf("%s: stat %q: %v", label, got, err)
}
wantInfo, err := os.Stat(want)
if err != nil {
t.Fatalf("%s: stat %q: %v", label, want, err)
}
if !os.SameFile(gotInfo, wantInfo) {
t.Fatalf("%s: got %q, want %q (different paths)", label, got, want)
}
}
func sameExistingFile(a, b string) bool {
aInfo, err := os.Stat(a)
if err != nil {
return false
}
bInfo, err := os.Stat(b)
if err != nil {
return false
}
return os.SameFile(aInfo, bInfo)
}

View file

@ -12,6 +12,7 @@ import (
"github.com/steveyegge/beads/internal/doltserver"
"github.com/steveyegge/beads/internal/lockfile"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/storage/dbproxy/util"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/storage/embeddeddolt"
@ -121,6 +122,9 @@ func newDoltStoreFromConfig(ctx context.Context, beadsDir string) (storage.DoltS
if err := validateConfiguredBackend(cfg); err != nil {
return nil, err
}
if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
return backend.Open(ctx, beadsDir)
}
if cfg != nil && cfg.IsDoltProxiedServerMode() {
// TODO: this needs to be uow provider
return nil, fmt.Errorf("proxy server store should be uow provider")
@ -204,6 +208,9 @@ func newReadOnlyStoreFromConfig(ctx context.Context, beadsDir string) (storage.D
if err := validateConfiguredBackend(cfg); err != nil {
return nil, err
}
if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
return backend.OpenReadOnly(ctx, beadsDir)
}
if cfg != nil && cfg.IsDoltProxiedServerMode() {
// TODO: this needs to be uow provider
return nil, fmt.Errorf("proxy server store needs to be uow provider")

View file

@ -8,6 +8,7 @@ import (
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/storage/dbproxy/util"
"github.com/steveyegge/beads/internal/storage/dolt"
)
@ -57,6 +58,9 @@ func newDoltStoreFromConfig(ctx context.Context, beadsDir string) (storage.DoltS
if err := validateConfiguredBackend(cfg); err != nil {
return nil, err
}
if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
return backend.Open(ctx, beadsDir)
}
if cfg != nil && cfg.IsDoltProxiedServerMode() {
// TODO: this needs to be uow provider
return nil, fmt.Errorf("proxy server store should be uow provider")
@ -81,6 +85,9 @@ func newReadOnlyStoreFromConfig(ctx context.Context, beadsDir string) (storage.D
if err := validateConfiguredBackend(cfg); err != nil {
return nil, err
}
if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
return backend.OpenReadOnly(ctx, beadsDir)
}
if cfg != nil && cfg.IsDoltProxiedServerMode() {
// TODO: this needs to be uow provider
return nil, fmt.Errorf("proxy server store needs to be uow provider")

View file

@ -22,6 +22,7 @@ import (
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/git"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/utils"
)
@ -486,6 +487,14 @@ func findDatabaseInBeadsDir(beadsDir string, _ bool) string {
// through a leftover local Dolt directory.
return ""
}
// A registered backend whose workspace is the .beads directory has no
// separately discoverable local database; metadata.json plus its remote
// store identify the workspace. Return the .beads dir itself so extension
// callers discover it, mirroring the CLI's registered-workspace path in
// cmd/bd/main.go instead of falling through to Dolt-only discovery.
if backends.WorkspaceIsBeadsDir(cfg.GetBackend()) {
return beadsDir
}
// For Dolt server mode, database is on the server - no local directory required
if cfg.IsDoltServerMode() {
return cfg.DatabasePath(beadsDir)

View file

@ -11,13 +11,14 @@ import (
"time"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/storage/backendnames"
)
const ConfigFileName = "metadata.json"
type Config struct {
Database string `json:"database"`
Backend string `json:"backend,omitempty"` // Storage backend: "dolt" (default); legacy "postgres"/"mysql"/"sqlite" values are rejection tombstones. Read via GetBackend().
Backend string `json:"backend,omitempty"` // Storage backend: "dolt" (default), a registered extension, or a legacy rejection tombstone. Read via GetBackend().
// Deletions configuration
DeletionsRetentionDays int `json:"deletions_retention_days,omitempty"` // 0 means use default (3 days)
@ -249,19 +250,21 @@ func (c *Config) GetCapabilities() BackendCapabilities {
return CapabilitiesForBackend(backend)
}
// IsSupportedBackend reports whether backend selects an implementation shipped by
// beads. The empty value is the legacy/default spelling of Dolt.
// IsSupportedBackend reports whether backend selects Dolt or a backend
// registered by this binary. The empty value is the legacy/default spelling
// of Dolt. OSS registers no alternate backends.
func IsSupportedBackend(backend string) bool {
return backend == "" || backend == BackendDolt
return backend == "" || backend == BackendDolt || backendnames.Has(backend)
}
// GetBackend returns the configured storage backend. PostgreSQL, MySQL, and
// SQLite remain recognizable here so workspaces created by earlier builds can
// fail loudly at store selection instead of silently falling back to an empty
// Dolt database.
// Empty and explicit Dolt retain the established Dolt behavior. GetBackend keeps
// the historical Dolt fallback for unknown values, so storage-selection callers
// must check IsSupportedBackend(c.Backend) before opening or creating storage.
// Registered extension names are returned unchanged. Empty and explicit Dolt
// retain the established Dolt behavior. GetBackend keeps the historical Dolt
// fallback for unknown values, so storage-selection callers must check
// IsSupportedBackend(c.Backend) before opening or creating storage.
func (c *Config) GetBackend() string {
if c != nil {
switch c.Backend {
@ -272,6 +275,9 @@ func (c *Config) GetBackend() string {
case BackendSQLite:
return BackendSQLite
}
if backendnames.Has(c.Backend) {
return c.Backend
}
}
return BackendDolt
}

View file

@ -0,0 +1,36 @@
// Package backendnames holds the process-local set of registered storage
// backend names.
//
// This small, standard-library-only package lets configfile classify names
// without importing the typed backend registry and the storage interfaces it
// depends on. The backends package is the only writer.
package backendnames
import "sync"
var (
mu sync.RWMutex
names = make(map[string]struct{})
)
// Add records a registered backend name.
func Add(name string) {
mu.Lock()
defer mu.Unlock()
names[name] = struct{}{}
}
// Remove drops a registered backend name.
func Remove(name string) {
mu.Lock()
defer mu.Unlock()
delete(names, name)
}
// Has reports whether name is registered.
func Has(name string) bool {
mu.RLock()
defer mu.RUnlock()
_, ok := names[name]
return ok
}

View file

@ -0,0 +1,111 @@
// Package backends provides the extension seam for storage backends that
// return storage.DoltStorage directly.
//
// OSS Beads registers no alternate backend. A downstream distribution adds a
// registrant package and blank-imports it from cmd/bd; shared validation,
// discovery, and store dispatch then recognize the name without modification.
// The Dolt family remains hand-wired because proxied mode returns a unit of
// work provider rather than a store.
//
// The seam covers opening and discovering an existing registered workspace, not
// provisioning one: bd init and bd bootstrap create or import Dolt only and
// reject registered names, so a downstream registrant supplies its own
// workspace-creation path.
//
// Registration is init-time wiring. A registrant calls Register once during
// process initialization, before any concurrent store access; OSS never
// deregisters, and Deregister exists only for isolated single-threaded contract
// tests. This registry and the backendnames set that config validation reads are
// updated together under this package's lock, so as long as callers honor the
// init-only rule the two never diverge. Do not Register or Deregister
// concurrently with store dispatch.
package backends
import (
"context"
"fmt"
"sync"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backendnames"
)
// Backend describes a registered storage backend.
type Backend struct {
// Open opens the workspace store read-write.
Open func(ctx context.Context, beadsDir string) (storage.DoltStorage, error)
// OpenReadOnly opens the workspace for a read-only command.
OpenReadOnly func(ctx context.Context, beadsDir string) (storage.DoltStorage, error)
// WorkspaceIsBeadsDir means metadata.json and the remote store are enough
// to identify the workspace; no separately discoverable local DB exists.
WorkspaceIsBeadsDir bool
}
var (
mu sync.RWMutex
registry = make(map[string]Backend)
)
// Register adds a backend. Invalid or duplicate registrations panic because
// they are process-start wiring errors.
func Register(name string, backend Backend) {
switch {
case name == "":
panic("backends: Register called with empty backend name")
case name == "dolt":
panic(`backends: backend name "dolt" is reserved`)
case backend.Open == nil || backend.OpenReadOnly == nil:
panic(fmt.Sprintf("backends: backend %q requires Open and OpenReadOnly", name))
}
mu.Lock()
defer mu.Unlock()
if _, exists := registry[name]; exists {
panic(fmt.Sprintf("backends: backend %q registered twice", name))
}
registry[name] = backend
backendnames.Add(name)
}
// Deregister removes a backend. It exists for isolated contract tests;
// production registrants register once during process initialization.
func Deregister(name string) bool {
mu.Lock()
defer mu.Unlock()
if _, exists := registry[name]; !exists {
return false
}
delete(registry, name)
backendnames.Remove(name)
return true
}
// Lookup returns the backend registered under name.
func Lookup(name string) (Backend, bool) {
mu.RLock()
defer mu.RUnlock()
backend, ok := registry[name]
return backend, ok
}
// Registered reports whether name has a backend implementation.
func Registered(name string) bool {
mu.RLock()
defer mu.RUnlock()
_, ok := registry[name]
return ok
}
// WorkspaceIsBeadsDir reports whether name is a registered backend whose
// workspace is identified by the .beads directory alone — metadata.json plus a
// remote store — with no separately discoverable local database. It is the
// single authority for that classification so CLI and library discovery route
// such workspaces to the .beads directory instead of returning "no database".
func WorkspaceIsBeadsDir(name string) bool {
mu.RLock()
defer mu.RUnlock()
backend, ok := registry[name]
return ok && backend.WorkspaceIsBeadsDir
}

View file

@ -0,0 +1,84 @@
package backends_test
import (
"context"
"errors"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
)
var errFixtureOpen = errors.New("fixture backend open")
func fixtureBackend() backends.Backend {
open := func(context.Context, string) (storage.DoltStorage, error) {
return nil, errFixtureOpen
}
return backends.Backend{Open: open, OpenReadOnly: open}
}
func TestRegisterLookupAndDeregister(t *testing.T) {
const name = "fixture"
backends.Register(name, fixtureBackend())
t.Cleanup(func() { backends.Deregister(name) })
registered, ok := backends.Lookup(name)
if !ok {
t.Fatalf("Lookup(%q) did not find the registered backend", name)
}
if _, err := registered.Open(t.Context(), t.TempDir()); !errors.Is(err, errFixtureOpen) {
t.Fatalf("Open() error = %v, want %v", err, errFixtureOpen)
}
if !backends.Registered(name) {
t.Fatalf("Registered(%q) = false, want true", name)
}
if !backends.Deregister(name) {
t.Fatalf("Deregister(%q) = false, want true", name)
}
if _, ok := backends.Lookup(name); ok {
t.Fatalf("Lookup(%q) found a deregistered backend", name)
}
if backends.Deregister(name) {
t.Fatalf("second Deregister(%q) = true, want false", name)
}
}
func TestRegisterRejectsInvalidContracts(t *testing.T) {
mustPanic := func(t *testing.T, register func()) {
t.Helper()
defer func() {
if recover() == nil {
t.Fatal("Register did not panic")
}
}()
register()
}
t.Run("empty name", func(t *testing.T) {
mustPanic(t, func() { backends.Register("", fixtureBackend()) })
})
t.Run("reserved dolt name", func(t *testing.T) {
mustPanic(t, func() { backends.Register("dolt", fixtureBackend()) })
})
t.Run("missing open", func(t *testing.T) {
mustPanic(t, func() {
backends.Register("missing-open", backends.Backend{
OpenReadOnly: fixtureBackend().OpenReadOnly,
})
})
})
t.Run("missing read-only open", func(t *testing.T) {
mustPanic(t, func() {
backends.Register("missing-read-only", backends.Backend{
Open: fixtureBackend().Open,
})
})
})
t.Run("duplicate name", func(t *testing.T) {
const name = "duplicate"
backends.Register(name, fixtureBackend())
t.Cleanup(func() { backends.Deregister(name) })
mustPanic(t, func() { backends.Register(name, fixtureBackend()) })
})
}

View file

@ -0,0 +1,32 @@
package backends_test
import (
"testing"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage/backends"
)
func TestDeregisterRestoresUnknownBackendFailClosed(t *testing.T) {
const name = "transient-fixture"
cfg := &configfile.Config{Backend: name}
backends.Register(name, fixtureBackend())
t.Cleanup(func() { backends.Deregister(name) })
if !configfile.IsSupportedBackend(name) {
t.Fatalf("registered backend %q is not supported", name)
}
if got := cfg.GetBackend(); got != name {
t.Fatalf("registered backend GetBackend() = %q, want %q", got, name)
}
if !backends.Deregister(name) {
t.Fatalf("Deregister(%q) = false, want true", name)
}
if configfile.IsSupportedBackend(name) {
t.Fatalf("deregistered backend %q is still supported", name)
}
if got := cfg.GetBackend(); got != configfile.BackendDolt {
t.Fatalf("deregistered backend GetBackend() = %q, want fail-safe Dolt fallback", got)
}
}

View file

@ -0,0 +1,52 @@
package backends_test
import (
"testing"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage/backends"
)
func TestRegisteredCustomNameIsSupportedAndPreserved(t *testing.T) {
const name = "enterprise-fixture"
cfg := &configfile.Config{Backend: name}
if configfile.IsSupportedBackend(name) {
t.Fatalf("unregistered backend %q unexpectedly supported", name)
}
if got := cfg.GetBackend(); got != configfile.BackendDolt {
t.Fatalf("unregistered backend GetBackend() = %q, want Dolt fallback", got)
}
backends.Register(name, fixtureBackend())
t.Cleanup(func() { backends.Deregister(name) })
if !configfile.IsSupportedBackend(name) {
t.Fatalf("registered backend %q is not supported", name)
}
if got := cfg.GetBackend(); got != name {
t.Fatalf("registered backend GetBackend() = %q, want %q", got, name)
}
}
func TestRegistrationCanActivateRemovedNameWithoutChangingOSSPolicy(t *testing.T) {
const name = configfile.BackendPostgres
cfg := &configfile.Config{Backend: name}
if configfile.IsSupportedBackend(name) {
t.Fatal("PostgreSQL tombstone must remain unsupported without a registrant")
}
if got := cfg.GetBackend(); got != name {
t.Fatalf("PostgreSQL tombstone GetBackend() = %q, want %q", got, name)
}
backends.Register(name, fixtureBackend())
t.Cleanup(func() { backends.Deregister(name) })
if !configfile.IsSupportedBackend(name) {
t.Fatal("registered PostgreSQL backend is not supported")
}
if got := cfg.GetBackend(); got != name {
t.Fatalf("registered PostgreSQL GetBackend() = %q, want %q", got, name)
}
}

View file

@ -2,14 +2,37 @@ package beads_test
import (
"context"
"errors"
"os"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
)
var errRegistryBackendOpen = errors.New("registry backend open sentinel")
// registerWorkspaceBackend registers a fake WorkspaceIsBeadsDir backend whose
// Open/OpenReadOnly report a sentinel instead of touching a store, so tests can
// assert that discovery and open dispatch to the registry without provisioning
// Dolt. Register requires both hooks to be non-nil.
func registerWorkspaceBackend(t *testing.T, name string) {
t.Helper()
backends.Register(name, backends.Backend{
Open: func(context.Context, string) (storage.DoltStorage, error) {
return nil, errRegistryBackendOpen
},
OpenReadOnly: func(context.Context, string) (storage.DoltStorage, error) {
return nil, errRegistryBackendOpen
},
WorkspaceIsBeadsDir: true,
})
t.Cleanup(func() { backends.Deregister(name) })
}
func writeBackendMetadata(t *testing.T, backend string) string {
t.Helper()
beadsDir := filepath.Join(t.TempDir(), ".beads")
@ -120,3 +143,65 @@ func TestOpenBestAvailableRejectsCorruptMetadata(t *testing.T) {
t.Fatalf("corrupt metadata created embedded Dolt storage (stat error: %v)", statErr)
}
}
// TestOpenBestAvailableDispatchesRegisteredBackend covers the public library
// open path for a registered extension backend: OpenBestAvailable must call the
// backend rather than opening Dolt (CGO) or returning the embedded-Dolt error
// (non-CGO), mirroring the CLI store factories.
func TestOpenBestAvailableDispatchesRegisteredBackend(t *testing.T) {
const name = "registry-open"
registerWorkspaceBackend(t, name)
beadsDir := writeBackendMetadata(t, name)
store, err := beads.OpenBestAvailable(context.Background(), beadsDir)
if store != nil {
_ = store.Close()
t.Fatal("registered backend dispatch returned a store instead of the backend's own result")
}
if !errors.Is(err, errRegistryBackendOpen) {
t.Fatalf("OpenBestAvailable error = %v, want registered backend Open result", err)
}
// Dispatch must not fall through and provision an embedded Dolt store.
for _, artifact := range []string{"embeddeddolt", "dolt"} {
if _, statErr := os.Stat(filepath.Join(beadsDir, artifact)); !os.IsNotExist(statErr) {
t.Fatalf("registered backend dispatch created %s (stat error: %v)", artifact, statErr)
}
}
}
// TestFindDatabasePathDiscoversRegisteredWorkspace covers public discovery
// parity: a registered WorkspaceIsBeadsDir backend has no local Dolt database,
// so FindDatabasePath must return the .beads directory itself instead of the
// empty "no database" result the Dolt-only search would give.
func TestFindDatabasePathDiscoversRegisteredWorkspace(t *testing.T) {
const name = "registry-discovery"
registerWorkspaceBackend(t, name)
beadsDir := writeBackendMetadata(t, name)
t.Setenv("BEADS_DIR", beadsDir)
got := beads.FindDatabasePath()
if got == "" {
t.Fatal("FindDatabasePath returned empty for a WorkspaceIsBeadsDir backend")
}
// Path canonicalization (symlinked temp dirs) can rewrite the string, so
// compare the workspace by identity rather than raw path equality.
gotInfo, err := os.Stat(got)
if err != nil {
t.Fatalf("stat discovered path %q: %v", got, err)
}
wantInfo, err := os.Stat(beadsDir)
if err != nil {
t.Fatalf("stat beads dir %q: %v", beadsDir, err)
}
if !os.SameFile(gotInfo, wantInfo) {
t.Fatalf("FindDatabasePath = %q, want the .beads workspace dir %q", got, beadsDir)
}
// The registry-only workspace carries no local Dolt database and discovery
// must not create one.
for _, artifact := range []string{"embeddeddolt", "dolt"} {
if _, statErr := os.Stat(filepath.Join(beadsDir, artifact)); !os.IsNotExist(statErr) {
t.Fatalf("registry workspace discovery created %s (stat error: %v)", artifact, statErr)
}
}
}