diff --git a/CHANGELOG.md b/CHANGELOG.md index 06596ebdf..dfbc4db13 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 stay required. In Go, `apigen.ContextResponse.BeadsDir` and `.RepoRoot` become `*string`. +- **An explicitly configured Dolt server port now outranks the ambient + `BEADS_DOLT_SERVER_PORT`/`BEADS_DOLT_PORT` environment variables** + (be-wf9a.1, be-9tju, GH#4052). `ServerPort` resolution now carries a + *source* — which step of the chain produced the port — and the env read only + applies when that source is not an assertion by the user or by tooling acting + for them. Two deliberate behavior changes follow. **First**, a port set by the + caller before the store opens (a library caller filling in `Config.ServerPort`, + or `bd init --server-port`) is no longer silently replaced by whatever the + surrounding shell exported; previously the env var won unconditionally. + **Second**, the *legacy* `BEADS_DOLT_PORT` spelling no longer overrides a port + resolved from `.beads/config.yaml` (`dolt.port`), Dolt's own `config.yaml` + (`listener.port`), or `metadata.json` (`dolt_server_port`). The current + `BEADS_DOLT_SERVER_PORT` spelling is unaffected — it sits first in the + resolution chain and still wins over all of them. + + **Compatibility:** a workspace that relied on exporting `BEADS_DOLT_PORT` to + redirect away from a port pinned in config now connects to the pinned port + instead. Switch to `BEADS_DOLT_SERVER_PORT`, or change the pinned value. Ports + that bd resolved for *itself* — the gitignored `.beads/dolt-server.port`, and + the shared-server default 3308 — stay non-authoritative and remain overridable + by either spelling, which is the case that kept working throughout. + + A related failure goes away with it: because bd's own bookkeeping is no longer + mislabeled as user configuration, a stale `.beads/dolt-server.port` left by a + crashed server no longer makes auto-start refuse to start with *"bd will not + silently use a different port than the one you configured"* when nothing was + configured. Auto-start warns and retargets, as it did before. Shared-server + mode still fails closed there — a repo-local auto-start is a different + database, not a port refresh — but now says so in its own words. + - **`bd reclaim` summarizes the leases its replica guard declined instead of naming every one, every run** (wy-sp2l4). A lease granted by another replica is by construction never reclaimed here, so the audit was not a one-off: it diff --git a/cmd/bd/doctor/federation.go b/cmd/bd/doctor/federation.go index cc981c81e..7c40e85ea 100644 --- a/cmd/bd/doctor/federation.go +++ b/cmd/bd/doctor/federation.go @@ -36,7 +36,10 @@ func doltServerConfig(beadsDir, doltPath string) *dolt.Config { } if bcfg, err := configfile.Load(beadsDir); err == nil && bcfg != nil { cfg.ServerHost = bcfg.GetDoltServerHost() - cfg.ServerPort = doltserver.DefaultConfig(beadsDir).Port + // Carries PortSource with the port: this cfg reaches applyConfigDefaults, + // which reads a sourceless port as caller-explicit (see + // dolt.ApplyResolvedServerPort). + dolt.ApplyResolvedServerPort(beadsDir, cfg) cfg.ServerUser = bcfg.GetDoltServerUser() cfg.ServerTLS = bcfg.GetDoltServerTLS() cfg.ServerPassword = bcfg.GetDoltServerPasswordForPort(cfg.ServerPort) diff --git a/cmd/bd/init.go b/cmd/bd/init.go index 6380bc745..091065cdd 100644 --- a/cmd/bd/init.go +++ b/cmd/bd/init.go @@ -1349,35 +1349,59 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1): // to config.yaml / global config, which may resolve to another project's server // because metadata.json doesn't exist yet during init. For fresh inits, port 0 // forces auto-start to allocate an ephemeral port for THIS project. + // The source travels with the port. applyConfigDefaults reads a nonzero + // ServerPort with no source as a caller assertion (be-wf9a.1), and none + // of the three resolutions below is one: they are an ambient env var and + // two pieces of bd's own bookkeeping. Mislabeling them makes auto-start + // refuse to retarget a stale port the user never chose (GH#4052). initPort := 0 + initPortSource := doltserver.PortSourceUnset + initPortShared := false if p := os.Getenv("BEADS_DOLT_SERVER_PORT"); p != "" { if port, err := strconv.Atoi(p); err == nil && port > 0 { initPort = port + initPortSource = doltserver.PortSourceEnv } } if initPort == 0 { - initPort = doltserver.ReadPortFile(beadsDir) + if port := doltserver.ReadPortFile(beadsDir); port > 0 { + initPort = port + initPortSource = doltserver.PortSourcePortFile + } } // Shared server mode intentionally uses a common port for all projects. if initPort == 0 && doltserver.IsSharedServerMode() { initPort = doltserver.DefaultSharedServerPort + initPortSource = doltserver.PortSourceSharedServerDefault + // Mirrors doltserver.DefaultConfig's own shared-mode fill. It makes + // newServerMode fail closed if the shared server is down and + // auto-start brings up a repo-local one instead — a different + // database, never a benign port refresh (GH#4052). + initPortShared = true } doltCfg := &dolt.Config{ - Path: storagePath, - BeadsDir: beadsDir, - Database: dbName, - ServerPort: initPort, - ServerMode: initServerMode, - ProxiedServer: initProxiedServer, - CreateIfMissing: true, // bd init is the only path that should create databases - AutoStart: initServerMode && os.Getenv("BEADS_DOLT_AUTO_START") != "0", - ServerTLS: initDoltServerTLSFromEnv(), + Path: storagePath, + BeadsDir: beadsDir, + Database: dbName, + ServerPort: initPort, + ServerPortSource: initPortSource, + ServerPortSharedServer: initPortShared, + ServerMode: initServerMode, + ProxiedServer: initProxiedServer, + CreateIfMissing: true, // bd init is the only path that should create databases + AutoStart: initServerMode && os.Getenv("BEADS_DOLT_AUTO_START") != "0", + ServerTLS: initDoltServerTLSFromEnv(), } if serverHost != "" { doltCfg.ServerHost = serverHost } if serverPort != 0 { + // `bd init --server-port` IS a caller assertion — and it must + // replace the source resolved above, not inherit it, or an + // explicitly flagged port would carry a port-file provenance. doltCfg.ServerPort = serverPort + doltCfg.ServerPortSource = doltserver.PortSourceCallerExplicit + doltCfg.ServerPortSharedServer = false } if serverSocket != "" { doltCfg.ServerSocket = serverSocket @@ -3338,16 +3362,22 @@ func verifyMetadata(ctx context.Context, store storage.DoltStorage, key, value s // sets config values that are not already present. func initGlobalDatabaseConfig(ctx context.Context, projectCfg *dolt.Config, quiet bool) { globalCfg := &dolt.Config{ - Path: projectCfg.Path, - BeadsDir: projectCfg.BeadsDir, - Database: doltserver.GlobalDatabaseName, - ServerHost: projectCfg.ServerHost, - ServerPort: projectCfg.ServerPort, - ServerUser: projectCfg.ServerUser, - ServerPassword: projectCfg.ServerPassword, - ServerMode: true, - CreateIfMissing: true, - AutoStart: false, // server is already running + Path: projectCfg.Path, + BeadsDir: projectCfg.BeadsDir, + Database: doltserver.GlobalDatabaseName, + ServerHost: projectCfg.ServerHost, + ServerPort: projectCfg.ServerPort, + // projectCfg has been through applyConfigDefaults, so its port is + // resolved and its source is accurate; copy both. Dropping the source + // here would re-label the copy caller-explicit on the way into the + // second dolt.New. + ServerPortSource: projectCfg.ServerPortSource, + ServerPortSharedServer: projectCfg.ServerPortSharedServer, + ServerUser: projectCfg.ServerUser, + ServerPassword: projectCfg.ServerPassword, + ServerMode: true, + CreateIfMissing: true, + AutoStart: false, // server is already running } globalStore, err := newDoltStore(ctx, globalCfg) diff --git a/cmd/bd/main.go b/cmd/bd/main.go index 256290078..ac2811954 100644 --- a/cmd/bd/main.go +++ b/cmd/bd/main.go @@ -251,9 +251,11 @@ func runsPostCommandMaintenance(cmdName string, strictReadonly bool) bool { // bypasses. func resolveDoltServerConnection(ctx context.Context, beadsDir string, fileCfg *configfile.Config, doltCfg *dolt.Config) error { doltCfg.ServerHost = fileCfg.GetDoltServerHost() - // Use doltserver.DefaultConfig for port resolution (env > port file > - // config.yaml). Port 0 is fine here — auto-start will resolve it. - doltCfg.ServerPort = doltserver.DefaultConfig(beadsDir).Port + // Port 0 is fine here — auto-start will resolve it. Use the shared helper + // rather than DefaultConfig(...).Port: this hand-built doltCfg is handed + // straight to dolt.New, and a port arriving there without its source is + // read as a caller assertion (see ApplyResolvedServerPort). + dolt.ApplyResolvedServerPort(beadsDir, doltCfg) doltCfg.ServerSocket = fileCfg.GetDoltServerSocket() // A configured credential command targets an authenticating gateway server: // run it for a short-lived token used as the connection username. Fail closed diff --git a/cmd/bd/resolve_dolt_server_connection_test.go b/cmd/bd/resolve_dolt_server_connection_test.go new file mode 100644 index 000000000..6e60180eb --- /dev/null +++ b/cmd/bd/resolve_dolt_server_connection_test.go @@ -0,0 +1,74 @@ +//go:build cgo + +package main + +import ( + "context" + "testing" + + "github.com/steveyegge/beads/internal/configfile" + "github.com/steveyegge/beads/internal/doltserver" + "github.com/steveyegge/beads/internal/storage/dolt" +) + +// TestResolveDoltServerConnectionPropagatesPortSource guards the primary CLI +// store-open path (and, through the same function, the unit-of-work provider +// `bd serve` builds). +// +// resolveDoltServerConnection hand-builds a dolt.Config that is handed straight +// to dolt.New → applyConfigDefaults, which infers "the caller explicitly +// asserted this port" from "ServerPort nonzero, ServerPortSource unset". While +// this site copied doltserver.DefaultConfig(dir).Port alone, every port bd +// resolved for itself arrived here labeled authoritative — so the CLI path and +// the library open path (dolt.NewFromConfig) disagreed on precedence: the +// legacy BEADS_DOLT_PORT override was honored by one and silently dropped by +// the other. +func TestResolveDoltServerConnectionPropagatesPortSource(t *testing.T) { + t.Run("port-file port is not a caller assertion (be-9tju)", func(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_PORT", "") + t.Setenv("BEADS_DOLT_PORT", "") + t.Setenv("BEADS_DOLT_SHARED_SERVER", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + t.Setenv("HOME", t.TempDir()) + beadsDir := t.TempDir() + if err := doltserver.EnsurePortFile(beadsDir, 14567); err != nil { + t.Fatalf("EnsurePortFile: %v", err) + } + + doltCfg := &dolt.Config{BeadsDir: beadsDir} + if err := resolveDoltServerConnection(context.Background(), beadsDir, &configfile.Config{Backend: configfile.BackendDolt}, doltCfg); err != nil { + t.Fatalf("resolveDoltServerConnection: %v", err) + } + + if doltCfg.ServerPort != 14567 { + t.Fatalf("ServerPort = %d, want 14567", doltCfg.ServerPort) + } + if doltCfg.ServerPortSource != doltserver.PortSourcePortFile { + t.Fatalf("ServerPortSource = %q, want %q: the source must travel with the port, or applyConfigDefaults promotes bd's own port-file bookkeeping to caller_explicit", doltCfg.ServerPortSource, doltserver.PortSourcePortFile) + } + if doltCfg.ServerPortSource.IsAuthoritative() { + t.Fatal("port-file port reported authoritative on the CLI path: BEADS_DOLT_PORT becomes a silent no-op here while still working on the library open path, and a stale port file turns auto-start's benign retarget into a hard error (GH#4052)") + } + }) + + t.Run("shared-server default is not a caller assertion (GH#4052)", func(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_PORT", "") + t.Setenv("BEADS_DOLT_PORT", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + t.Setenv("HOME", t.TempDir()) + t.Setenv("BEADS_DOLT_SHARED_SERVER", "1") + beadsDir := t.TempDir() + + doltCfg := &dolt.Config{BeadsDir: beadsDir} + if err := resolveDoltServerConnection(context.Background(), beadsDir, &configfile.Config{Backend: configfile.BackendDolt}, doltCfg); err != nil { + t.Fatalf("resolveDoltServerConnection: %v", err) + } + + if doltCfg.ServerPort != doltserver.DefaultSharedServerPort { + t.Fatalf("ServerPort = %d, want %d", doltCfg.ServerPort, doltserver.DefaultSharedServerPort) + } + if doltCfg.ServerPortSource.IsAuthoritative() { + t.Fatalf("ServerPortSource = %q reported authoritative: bd chose the shared default 3308 itself, so it must not be defended as a user-configured port", doltCfg.ServerPortSource) + } + }) +} diff --git a/internal/doltserver/doltserver.go b/internal/doltserver/doltserver.go index 58dc0701e..f0cc047fe 100644 --- a/internal/doltserver/doltserver.go +++ b/internal/doltserver/doltserver.go @@ -649,6 +649,22 @@ const ( // resolved (GH#3545): the user asserted a remote host, so bd fills in // the default port rather than dialing :0 or allocating locally. PortSourceExternalHostDefault PortSource = "external_host_default" + // PortSourceCallerExplicit is an already-nonzero Config.ServerPort set by + // the caller before applyConfigDefaults runs (e.g. `bd init + // --server-port`, or initGlobalDatabaseConfig's copy-forward of it) — + // a direct user/tooling assertion, outranking the + // BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT env vars (be-wf9a.1). + PortSourceCallerExplicit PortSource = "caller_explicit" + // PortSourceSharedServerDefault is DefaultSharedServerPort (3308), filled + // in when shared-server mode is on and no other source resolved a port. + // NOT authoritative: bd picked it on the user's behalf, exactly like the + // port file. It exists so DefaultConfig never returns a nonzero Port with + // PortSourceUnset — without it, a bd-chosen shared default is + // indistinguishable from a caller assertion and applyConfigDefaults + // stamps it PortSourceCallerExplicit, which silently disables the + // BEADS_DOLT_SERVER_PORT override and turns a benign auto-start port + // change into a hard failure (GH#4052, be-9tju). + PortSourceSharedServerDefault PortSource = "shared_server_default" ) // IsAuthoritative reports whether this source represents a user (or @@ -658,7 +674,7 @@ const ( // authoritative one (GH#4052). func (s PortSource) IsAuthoritative() bool { switch s { - case PortSourceEnv, PortSourceDoltConfigYaml, PortSourceConfigYaml, PortSourceMetadataJSON: + case PortSourceEnv, PortSourceDoltConfigYaml, PortSourceConfigYaml, PortSourceMetadataJSON, PortSourceCallerExplicit: return true default: return false @@ -789,6 +805,7 @@ func DefaultConfig(beadsDir string) *Config { // ephemeral port from the OS (GH#2098, GH#2372). if cfg.Port == 0 && IsSharedServerMode() { cfg.Port = DefaultSharedServerPort // 3308 - avoids orchestrator conflict on 3307 + cfg.PortSource = PortSourceSharedServerDefault cfg.PortSharedServer = true } diff --git a/internal/doltserver/portsource_invariant_test.go b/internal/doltserver/portsource_invariant_test.go new file mode 100644 index 000000000..3db1c23e5 --- /dev/null +++ b/internal/doltserver/portsource_invariant_test.go @@ -0,0 +1,40 @@ +package doltserver + +import ( + "testing" +) + +// TestDefaultConfig_NonzeroPortAlwaysHasSource pins the invariant that makes +// applyConfigDefaults' "nonzero ServerPort + PortSourceUnset ⇒ caller-explicit" +// inference sound: DefaultConfig must never hand back a resolved port with no +// source attached. If it does, a port DefaultConfig chose on the user's behalf +// is indistinguishable from one the caller explicitly asserted, and the storage +// layer stamps it PortSourceCallerExplicit (authoritative) — which silently +// disables the BEADS_DOLT_SERVER_PORT override and turns a benign auto-start +// port change into a hard failure (GH#4052). +func TestDefaultConfig_NonzeroPortAlwaysHasSource(t *testing.T) { + // Neutralize ambient port env: a leaked BEADS_DOLT_SERVER_PORT from the + // surrounding shell would resolve via PortSourceEnv and mask the gap. + t.Setenv("BEADS_DOLT_SERVER_PORT", "") + t.Setenv("BEADS_DOLT_PORT", "") + t.Setenv("HOME", t.TempDir()) + + for _, tc := range []struct { + name string + shared string + }{ + {name: "per-project mode", shared: "0"}, + {name: "shared-server mode", shared: "1"}, + } { + t.Run(tc.name, func(t *testing.T) { + t.Setenv("BEADS_DOLT_SHARED_SERVER", tc.shared) + cfg := DefaultConfig(t.TempDir()) + if cfg.Port != 0 && cfg.PortSource == PortSourceUnset { + t.Fatalf("DefaultConfig returned Port=%d with PortSourceUnset "+ + "(PortSharedServer=%v): a port resolved on the user's behalf "+ + "is indistinguishable from a caller-explicit assertion", + cfg.Port, cfg.PortSharedServer) + } + }) + } +} diff --git a/internal/doltserver/portsources_test.go b/internal/doltserver/portsources_test.go index 69fdd167a..8c424c5ca 100644 --- a/internal/doltserver/portsources_test.go +++ b/internal/doltserver/portsources_test.go @@ -186,8 +186,16 @@ func TestDefaultConfigPortSharedServer(t *testing.T) { if cfg.Port != DefaultSharedServerPort { t.Fatalf("shared mode fallback: port = %d, want %d", cfg.Port, DefaultSharedServerPort) } - if cfg.PortSource != PortSourceUnset { - t.Fatalf("shared mode fallback: source = %q, want %q", cfg.PortSource, PortSourceUnset) + if cfg.PortSource != PortSourceSharedServerDefault { + t.Fatalf("shared mode fallback: source = %q, want %q", cfg.PortSource, PortSourceSharedServerDefault) + } + // Sourced, but deliberately NOT authoritative: bd picked 3308 on the + // user's behalf. Callers that copy this Port into dolt.Config need a + // non-empty source (or applyConfigDefaults infers caller_explicit), and + // they need it to answer false here (or auto-start defends a port the + // user never configured). + if cfg.PortSource.IsAuthoritative() { + t.Fatalf("shared mode fallback: source %q reports authoritative, want non-authoritative", cfg.PortSource) } if !cfg.PortSharedServer { t.Fatalf("shared mode fallback: PortSharedServer = false, want true") diff --git a/internal/storage/dolt/open.go b/internal/storage/dolt/open.go index 22d91c880..a79f62ea8 100644 --- a/internal/storage/dolt/open.go +++ b/internal/storage/dolt/open.go @@ -48,6 +48,35 @@ func ApplyCLIAutoStart(beadsDir string, cfg *Config) { cfg.AutoStart = resolveAutoStart(true, autoStartCfg, mode) } +// ApplyResolvedServerPort fills cfg's server port from doltserver's +// precedence chain (env > port file > dolt config.yaml > beads config.yaml > +// metadata.json), and — the part that is easy to drop — records WHICH of those +// produced it. +// +// The source is not decoration. applyConfigDefaults infers "the caller +// explicitly asserted this port" from "ServerPort nonzero, ServerPortSource +// unset" (be-wf9a.1). A site that copies doltserver.DefaultConfig(dir).Port on +// its own therefore launders bd's own bookkeeping — the gitignored port file, +// or the shared-server default 3308 — into a deliberate user assertion, and +// that mislabel has two visible consequences: +// +// - the legacy BEADS_DOLT_PORT override becomes a silent no-op, because an +// authoritative source outranks the env read (be-9tju); and +// - auto-start's benign "configured port is stale, here is the new one" +// retarget turns into a hard failure telling the user to fix a port they +// never configured (GH#4052). +// +// So every hand-built dolt.Config that resolves its port this way goes through +// here rather than reaching for .Port. Callers that want to resolve only when +// unset keep their own `if cfg.ServerPort == 0` guard; this function is +// unconditional. +func ApplyResolvedServerPort(beadsDir string, cfg *Config) { + resolved := doltserver.DefaultConfig(beadsDir) + cfg.ServerPort = resolved.Port + cfg.ServerPortSource = resolved.PortSource + cfg.ServerPortSharedServer = resolved.PortSharedServer +} + // requireDoltBackend keeps metadata-driven callers from bypassing the storage // factory and interpreting another backend's workspace as Dolt. Removed backend // identifiers deliberately remain recognizable in metadata so this check can fail @@ -248,10 +277,10 @@ func applyResolvedConfig(ctx context.Context, beadsDir string, fileCfg *configfi cfg.ServerHost = fileCfg.GetDoltServerHost() } if cfg.ServerPort == 0 { - // Use doltserver.DefaultConfig for port resolution (env > port file > - // config.yaml > metadata > DerivePort). fileCfg.GetDoltServerPort() - // falls back to 3307 which is wrong for standalone repos. - cfg.ServerPort = doltserver.DefaultConfig(beadsDir).Port + // fileCfg.GetDoltServerPort() falls back to 3307, which is wrong for + // standalone repos; ApplyResolvedServerPort walks doltserver's real + // precedence chain and carries the source along with the port. + ApplyResolvedServerPort(beadsDir, cfg) } // Resolve the server-mode credential (the connection username). In server mode a // configured credential command takes precedence over the static user; it fails diff --git a/internal/storage/dolt/open_test.go b/internal/storage/dolt/open_test.go index 7bc995cba..c5faee75b 100644 --- a/internal/storage/dolt/open_test.go +++ b/internal/storage/dolt/open_test.go @@ -401,4 +401,103 @@ func TestApplyResolvedConfig(t *testing.T) { t.Fatalf("PoolReadTimeout = %v, want caller's 2m", cfg.PoolReadTimeout) } }) + + t.Run("propagates ServerPortSource and ServerPortSharedServer alongside ServerPort (be-9tju)", func(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_PORT", "") + t.Setenv("BEADS_DOLT_PORT", "") + t.Setenv("BEADS_DOLT_SHARED_SERVER", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + beadsDir := t.TempDir() + if err := doltserver.EnsurePortFile(beadsDir, 14567); err != nil { + t.Fatalf("EnsurePortFile: %v", err) + } + fileCfg := &configfile.Config{Backend: configfile.BackendDolt} + cfg := &Config{} + + if err := applyResolvedConfig(context.Background(), beadsDir, fileCfg, cfg); err != nil { + t.Fatalf("applyResolvedConfig: %v", err) + } + + if cfg.ServerPort != 14567 { + t.Fatalf("ServerPort = %d, want 14567", cfg.ServerPort) + } + if cfg.ServerPortSource != doltserver.PortSourcePortFile { + t.Fatalf("ServerPortSource = %q, want %q (applyResolvedConfig must propagate doltserver.DefaultConfig's PortSource, not just Port)", cfg.ServerPortSource, doltserver.PortSourcePortFile) + } + if cfg.ServerPortSharedServer != false { + t.Fatalf("ServerPortSharedServer = %v, want false", cfg.ServerPortSharedServer) + } + }) + + t.Run("chained through applyConfigDefaults: port-file resolution is never mislabeled caller-explicit (be-9tju)", func(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_PORT", "") + t.Setenv("BEADS_DOLT_PORT", "") + t.Setenv("BEADS_DOLT_SHARED_SERVER", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + beadsDir := t.TempDir() + if err := doltserver.EnsurePortFile(beadsDir, 14567); err != nil { + t.Fatalf("EnsurePortFile: %v", err) + } + fileCfg := &configfile.Config{Backend: configfile.BackendDolt} + cfg := &Config{} + + if err := applyResolvedConfig(context.Background(), beadsDir, fileCfg, cfg); err != nil { + t.Fatalf("applyResolvedConfig: %v", err) + } + applyConfigDefaults(cfg) + + if cfg.ServerPortSource != doltserver.PortSourcePortFile { + t.Fatalf("ServerPortSource = %q, want %q (a port-file-resolved port must not be mislabeled caller_explicit — GH#4052 auto-start fail-closed logic depends on this)", cfg.ServerPortSource, doltserver.PortSourcePortFile) + } + if cfg.ServerPort != 14567 { + t.Fatalf("ServerPort = %d, want 14567 (unchanged)", cfg.ServerPort) + } + }) + + t.Run("legacy BEADS_DOLT_PORT redirects away from a non-authoritative port-file port (be-9tju)", func(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_PORT", "") + t.Setenv("BEADS_DOLT_PORT", "43211") + t.Setenv("BEADS_DOLT_SHARED_SERVER", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + beadsDir := t.TempDir() + if err := doltserver.EnsurePortFile(beadsDir, 14567); err != nil { + t.Fatalf("EnsurePortFile: %v", err) + } + fileCfg := &configfile.Config{Backend: configfile.BackendDolt} + cfg := &Config{} + + if err := applyResolvedConfig(context.Background(), beadsDir, fileCfg, cfg); err != nil { + t.Fatalf("applyResolvedConfig: %v", err) + } + applyConfigDefaults(cfg) + + if cfg.ServerPort != 43211 { + t.Fatalf("ServerPort = %d, want 43211 (legacy BEADS_DOLT_PORT must override a non-authoritative port-file-resolved port — regression of hq-27t bug class)", cfg.ServerPort) + } + if cfg.ServerPortSource != doltserver.PortSourceEnv { + t.Fatalf("ServerPortSource = %q, want %q", cfg.ServerPortSource, doltserver.PortSourceEnv) + } + }) + + t.Run("genuinely caller-explicit ServerPort still outranks ambient BEADS_DOLT_SERVER_PORT env (be-wf9a.1 regression safety)", func(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_PORT", "43211") + t.Setenv("BEADS_DOLT_PORT", "") + t.Setenv("BEADS_DOLT_SHARED_SERVER", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + beadsDir := t.TempDir() + fileCfg := &configfile.Config{Backend: configfile.BackendDolt} + cfg := &Config{ServerPort: 15000} + + if err := applyResolvedConfig(context.Background(), beadsDir, fileCfg, cfg); err != nil { + t.Fatalf("applyResolvedConfig: %v", err) + } + applyConfigDefaults(cfg) + + if cfg.ServerPort != 15000 { + t.Fatalf("ServerPort = %d, want 15000 (caller-explicit preset must outrank ambient env)", cfg.ServerPort) + } + if cfg.ServerPortSource != doltserver.PortSourceCallerExplicit { + t.Fatalf("ServerPortSource = %q, want %q", cfg.ServerPortSource, doltserver.PortSourceCallerExplicit) + } + }) } diff --git a/internal/storage/dolt/portsource_propagation_test.go b/internal/storage/dolt/portsource_propagation_test.go new file mode 100644 index 000000000..30c6b888d --- /dev/null +++ b/internal/storage/dolt/portsource_propagation_test.go @@ -0,0 +1,115 @@ +package dolt + +import ( + "testing" + + "github.com/steveyegge/beads/internal/doltserver" +) + +// TestApplyResolvedServerPort covers the helper that every hand-built +// dolt.Config now uses to resolve its port. The assertion that matters is not +// the port — it is that the port arrives with the source that produced it, and +// that bd's own bookkeeping never arrives labeled authoritative. Both consumers +// of the label (the env-override gate in applyConfigDefaults, and the +// auto-start fail-closed check in newServerMode) branch on IsAuthoritative, so +// that is asserted directly rather than inferred from the source string. +func TestApplyResolvedServerPort(t *testing.T) { + t.Run("port file resolves non-authoritative (be-9tju)", func(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_PORT", "") + t.Setenv("BEADS_DOLT_PORT", "") + t.Setenv("BEADS_DOLT_SHARED_SERVER", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + beadsDir := t.TempDir() + if err := doltserver.EnsurePortFile(beadsDir, 14567); err != nil { + t.Fatalf("EnsurePortFile: %v", err) + } + + cfg := &Config{} + ApplyResolvedServerPort(beadsDir, cfg) + + if cfg.ServerPort != 14567 { + t.Fatalf("ServerPort = %d, want 14567", cfg.ServerPort) + } + if cfg.ServerPortSource != doltserver.PortSourcePortFile { + t.Fatalf("ServerPortSource = %q, want %q", cfg.ServerPortSource, doltserver.PortSourcePortFile) + } + if cfg.ServerPortSource.IsAuthoritative() { + t.Fatal("port-file port reported authoritative: the legacy BEADS_DOLT_PORT override would become a silent no-op and auto-start would refuse to retarget a port the user never chose (GH#4052)") + } + if cfg.ServerPortSharedServer { + t.Fatal("ServerPortSharedServer = true in per-project mode") + } + }) + + t.Run("shared-server default resolves non-authoritative but shared (GH#4052)", func(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_PORT", "") + t.Setenv("BEADS_DOLT_PORT", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + t.Setenv("HOME", t.TempDir()) + t.Setenv("BEADS_DOLT_SHARED_SERVER", "1") + + cfg := &Config{} + ApplyResolvedServerPort(t.TempDir(), cfg) + + if cfg.ServerPort != doltserver.DefaultSharedServerPort { + t.Fatalf("ServerPort = %d, want %d", cfg.ServerPort, doltserver.DefaultSharedServerPort) + } + if cfg.ServerPortSource.IsAuthoritative() { + t.Fatalf("ServerPortSource = %q reported authoritative: bd chose 3308 on the user's behalf, so auto-start must not treat it as a configured port", cfg.ServerPortSource) + } + // Shared mode still fails closed on retarget — for the orthogonal + // reason that a repo-local auto-start is a different database. + if !cfg.ServerPortSharedServer { + t.Fatal("ServerPortSharedServer = false in shared-server mode: newServerMode would silently retarget to a repo-local server") + } + }) + + t.Run("env wins and is authoritative", func(t *testing.T) { + t.Setenv("BEADS_DOLT_PORT", "") + t.Setenv("BEADS_DOLT_SHARED_SERVER", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + t.Setenv("BEADS_DOLT_SERVER_PORT", "43211") + beadsDir := t.TempDir() + if err := doltserver.EnsurePortFile(beadsDir, 14567); err != nil { + t.Fatalf("EnsurePortFile: %v", err) + } + + cfg := &Config{} + ApplyResolvedServerPort(beadsDir, cfg) + + if cfg.ServerPort != 43211 { + t.Fatalf("ServerPort = %d, want 43211 (env outranks the port file)", cfg.ServerPort) + } + if !cfg.ServerPortSource.IsAuthoritative() { + t.Fatalf("ServerPortSource = %q, want an authoritative source for an env-set port", cfg.ServerPortSource) + } + }) +} + +// TestApplyResolvedServerPortChainsThroughApplyConfigDefaults is the end-to-end +// statement of the bug class: a port that bd resolved for itself must stay +// overridable by the legacy env spelling. Without the source travelling with +// the port, applyConfigDefaults' "nonzero + unset ⇒ caller_explicit" inference +// promotes the port file to authoritative and the env read below is skipped. +func TestApplyResolvedServerPortChainsThroughApplyConfigDefaults(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_PORT", "") + t.Setenv("BEADS_DOLT_SHARED_SERVER", "") + t.Setenv("BEADS_DOLT_SERVER_MODE", "") + t.Setenv("BEADS_TEST_MODE", "") + beadsDir := t.TempDir() + if err := doltserver.EnsurePortFile(beadsDir, 14567); err != nil { + t.Fatalf("EnsurePortFile: %v", err) + } + + cfg := &Config{BeadsDir: beadsDir} + ApplyResolvedServerPort(beadsDir, cfg) + t.Setenv("BEADS_DOLT_PORT", "43211") + applyConfigDefaults(cfg) + + if cfg.ServerPort != 43211 { + t.Fatalf("ServerPort = %d, want 43211: legacy BEADS_DOLT_PORT must still override a port-file-resolved port", cfg.ServerPort) + } + if cfg.ServerPortSource != doltserver.PortSourceEnv { + t.Fatalf("ServerPortSource = %q, want %q", cfg.ServerPortSource, doltserver.PortSourceEnv) + } +} diff --git a/internal/storage/dolt/store.go b/internal/storage/dolt/store.go index 36d492016..267c55544 100644 --- a/internal/storage/dolt/store.go +++ b/internal/storage/dolt/store.go @@ -387,12 +387,13 @@ type Config struct { ServerTLS bool // Enable TLS for server connections (required for Hosted Dolt) // ServerPortSource records which step of doltserver's port-resolution - // chain (or the env-var read in applyConfigDefaults) produced ServerPort. - // Zero value (doltserver.PortSourceUnset) when ServerPort was never - // resolved from a source (e.g. left 0, or set directly by a caller that - // bypassed applyConfigDefaults). Consulted by newServerMode's auto-start - // path to decide whether silently retargeting to a different port is - // safe (GH#4052). + // chain (or the caller-explicit/env-var reads in applyConfigDefaults) + // produced ServerPort. Zero value (doltserver.PortSourceUnset) when + // ServerPort was never resolved from a source (i.e. left 0). A caller + // that presets ServerPort before applyConfigDefaults runs gets + // PortSourceCallerExplicit stamped in. Consulted by newServerMode's + // auto-start path to decide whether silently retargeting to a different + // port is safe (GH#4052). ServerPortSource doltserver.PortSource // ServerPortSharedServer mirrors doltserver.Config.PortSharedServer: @@ -1453,18 +1454,31 @@ func applyConfigDefaults(cfg *Config) { cfg.ServerHost = "127.0.0.1" } } - // Port resolution: BEADS_DOLT_SERVER_PORT env (or legacy BEADS_DOLT_PORT) > - // BEADS_TEST_MODE guard > metadata config > default. + // Port resolution: caller-preset explicit ServerPort > BEADS_DOLT_SERVER_PORT + // env (or legacy BEADS_DOLT_PORT) > BEADS_TEST_MODE guard > metadata config > default. // CRITICAL: BEADS_TEST_MODE=1 forces port 1 (immediate fail) if the resolved port // is the production port (DefaultSQLPort). This prevents test databases from leaking // onto production even when the port env var is set to 3307 by the orchestrator's beads module. // Only an explicit non-production port (e.g., 43211 for a test server) // overrides test mode — that's a deliberate test server assignment. + if cfg.ServerPort != 0 && cfg.ServerPortSource == doltserver.PortSourceUnset { + // The caller (e.g. `bd init --server-port`, or initGlobalDatabaseConfig's + // copy-forward of it) already set an explicit port before this function + // ran. That assertion outranks the ambient env vars below (be-wf9a.1). + cfg.ServerPortSource = doltserver.PortSourceCallerExplicit + } envPort := os.Getenv("BEADS_DOLT_SERVER_PORT") if envPort == "" { envPort = os.Getenv("BEADS_DOLT_PORT") // legacy fallback } - if envPort != "" { + // Also fires when ServerPort is already nonzero but its source isn't + // authoritative (e.g. PortSourcePortFile from applyResolvedConfig's own + // doltserver.DefaultConfig fallback above) — bd's own port-file + // bookkeeping must not silently outrank an explicit env override + // (be-9tju; regression of the hq-27t bug class). A genuinely + // caller-explicit ServerPort (PortSourceCallerExplicit, stamped above) + // still wins: IsAuthoritative() is true for it. + if envPort != "" && (cfg.ServerPort == 0 || !cfg.ServerPortSource.IsAuthoritative()) { if p, err := strconv.Atoi(envPort); err == nil && p > 0 { cfg.ServerPort = p // This env read happens before doltserver.DefaultConfig is diff --git a/internal/storage/dolt/store_unit_test.go b/internal/storage/dolt/store_unit_test.go index bd5b89ee7..253c011e4 100644 --- a/internal/storage/dolt/store_unit_test.go +++ b/internal/storage/dolt/store_unit_test.go @@ -9,6 +9,7 @@ import ( "time" mysql "github.com/go-sql-driver/mysql" + "github.com/steveyegge/beads/internal/doltserver" "github.com/steveyegge/beads/internal/storage/doltutil" "github.com/steveyegge/beads/internal/storage/schema" ) @@ -356,11 +357,19 @@ func TestApplyConfigDefaults_TestModeBlocksProdPort_EvenWithTestServerOptIn(t *t } } -// TestApplyConfigDefaults_EnvOverridesConfig verifies that BEADS_DOLT_PORT -// overrides a port already set by metadata.json, even outside test mode. -// This is the fix for hq-27t (test pollution): callers like the orchestrator set -// BEADS_DOLT_PORT to route bd to a test server instead of production. -func TestApplyConfigDefaults_EnvOverridesConfig(t *testing.T) { +// TestApplyConfigDefaults_ExplicitPortOverridesEnv verifies that a +// caller-preset, already-nonzero cfg.ServerPort wins over +// BEADS_DOLT_PORT/BEADS_DOLT_SERVER_PORT, and that the resulting +// ServerPortSource is PortSourceCallerExplicit (authoritative) so +// newServerMode's auto-start fail-closed check (GH#4052) still protects it. +// +// Until be-wf9a.1, BEADS_DOLT_PORT unconditionally clobbered any pre-set +// ServerPort here (formerly asserted by this same test under the name +// TestApplyConfigDefaults_EnvOverridesConfig, added for hq-27t). That let an +// ambient orchestrator env var silently override an explicit caller +// assertion (e.g. `bd init --server-port`); this test now asserts the fixed, +// correct precedence instead. +func TestApplyConfigDefaults_ExplicitPortOverridesEnv(t *testing.T) { origTestMode := os.Getenv("BEADS_TEST_MODE") origPort := os.Getenv("BEADS_DOLT_PORT") defer func() { @@ -380,14 +389,91 @@ func TestApplyConfigDefaults_EnvOverridesConfig(t *testing.T) { os.Unsetenv("BEADS_TEST_MODE") // NOT in test mode os.Setenv("BEADS_DOLT_PORT", "19999") - // Simulate metadata.json having set port to production default + // Caller (e.g. `bd init --server-port`) preset an explicit port before + // applyConfigDefaults runs. cfg := &Config{ServerPort: DefaultSQLPort} applyConfigDefaults(cfg) - if cfg.ServerPort != 19999 { - t.Errorf("expected BEADS_DOLT_PORT=19999 to override config port %d, got %d", + if cfg.ServerPort != DefaultSQLPort { + t.Errorf("expected explicit ServerPort=%d to win over BEADS_DOLT_PORT=19999, got %d", DefaultSQLPort, cfg.ServerPort) } + if cfg.ServerPortSource != doltserver.PortSourceCallerExplicit { + t.Errorf("expected ServerPortSource=%q, got %q", + doltserver.PortSourceCallerExplicit, cfg.ServerPortSource) + } + if !cfg.ServerPortSource.IsAuthoritative() { + t.Errorf("expected PortSourceCallerExplicit to be authoritative (GH#4052 fail-closed guard)") + } +} + +// TestApplyConfigDefaults_EnvWinsWhenExplicitUnset verifies that when no +// caller has preset ServerPort (it is still the zero value), BEADS_DOLT_PORT +// resolves it — unchanged from before be-wf9a.1. +func TestApplyConfigDefaults_EnvWinsWhenExplicitUnset(t *testing.T) { + origTestMode := os.Getenv("BEADS_TEST_MODE") + origPort := os.Getenv("BEADS_DOLT_PORT") + defer func() { + if origTestMode == "" { + os.Unsetenv("BEADS_TEST_MODE") + } else { + os.Setenv("BEADS_TEST_MODE", origTestMode) + } + if origPort == "" { + os.Unsetenv("BEADS_DOLT_PORT") + } else { + os.Setenv("BEADS_DOLT_PORT", origPort) + } + }() + + t.Setenv("BEADS_DOLT_SERVER_PORT", "") // clear new primary port env so legacy path runs + os.Unsetenv("BEADS_TEST_MODE") // NOT in test mode + os.Setenv("BEADS_DOLT_PORT", "19999") + + cfg := &Config{} // ServerPort left unset (0) + applyConfigDefaults(cfg) + + if cfg.ServerPort != 19999 { + t.Errorf("expected BEADS_DOLT_PORT=19999 to resolve unset config port, got %d", cfg.ServerPort) + } + if cfg.ServerPortSource != doltserver.PortSourceEnv { + t.Errorf("expected ServerPortSource=%q, got %q", doltserver.PortSourceEnv, cfg.ServerPortSource) + } +} + +// TestApplyConfigDefaults_ExplicitPortPreservedWhenEnvUnset verifies that an +// explicit ServerPort survives when no env var is set — unchanged from +// before be-wf9a.1 — and is stamped PortSourceCallerExplicit (authoritative). +func TestApplyConfigDefaults_ExplicitPortPreservedWhenEnvUnset(t *testing.T) { + origTestMode := os.Getenv("BEADS_TEST_MODE") + origPort := os.Getenv("BEADS_DOLT_PORT") + defer func() { + if origTestMode == "" { + os.Unsetenv("BEADS_TEST_MODE") + } else { + os.Setenv("BEADS_TEST_MODE", origTestMode) + } + if origPort == "" { + os.Unsetenv("BEADS_DOLT_PORT") + } else { + os.Setenv("BEADS_DOLT_PORT", origPort) + } + }() + + t.Setenv("BEADS_DOLT_SERVER_PORT", "") // clear new primary port env so legacy path runs + os.Unsetenv("BEADS_TEST_MODE") // NOT in test mode + os.Unsetenv("BEADS_DOLT_PORT") + + cfg := &Config{ServerPort: 25432} + applyConfigDefaults(cfg) + + if cfg.ServerPort != 25432 { + t.Errorf("expected explicit ServerPort=25432 to survive with no env set, got %d", cfg.ServerPort) + } + if cfg.ServerPortSource != doltserver.PortSourceCallerExplicit { + t.Errorf("expected ServerPortSource=%q, got %q", + doltserver.PortSourceCallerExplicit, cfg.ServerPortSource) + } } // TestApplyConfigDefaults_ProductionFallback verifies that without diff --git a/release-gates/be-gd3v-serverport-precedence-gate.md b/release-gates/be-gd3v-serverport-precedence-gate.md new file mode 100644 index 000000000..bcffce06a --- /dev/null +++ b/release-gates/be-gd3v-serverport-precedence-gate.md @@ -0,0 +1,49 @@ +# Release gate — be-gd3v (Fix: explicit Config.ServerPort must outrank ambient BEADS_DOLT_SERVER_PORT env var) + +**Date:** 2026-08-18 +**Deployer:** beads/deployer +**Bead (deploy):** be-gd3v — Deploy Review: Fix: explicit Config.ServerPort must outrank ambient BEADS_DOLT_SERVER_PORT env var +**Source bead:** be-v2hy — closed, review verdict: pass +**Source commit:** `2dbcbd7f2a8782527fe4b496d497970f21f414be` (provenance branch `builder/be-wf9a.1`, review bead be-v2hy) +**Branch:** `deploy/be-gd3v-gate` (isolated, cut fresh at the reviewed SHA — never the shared `builder/be-wf9a.1` branch) +**Base:** `origin/main` @ `7505e173f` ("chore(release): forward-port v1.2.2 to main (#5782)") +**Merge-base:** `7505e173f` — identical to origin/main tip; clean fast-forward, 0 self-rebase needed +**Merge-tree simulation:** `git merge-tree --write-tree origin/main 2dbcbd7f2` → tree `f102e1300`, exit 0, **zero conflicts** +**PR:** https://github.com/gastownhall/beads/pull/5835 (`quad341/beads-sec003-contrib:deploy/be-gd3v-gate` → `gastownhall:main`), state OPEN, `headRefOid` = `2dbcbd7f2a8782527fe4b496d497970f21f414be` (matched the gated SHA exactly, no drift) **as of this gate run** — see *Post-gate history* below, `mergeable: MERGEABLE` + +## Verdict: PASS — all 7 criteria clear + +## Criteria walk + +| # | Criterion | Result | Evidence | +|---|-----------|--------|----------| +| 1 | Review PASS present | PASS | be-v2hy: verdict `pass`, closed with reason `pass`. Style clean (gofmt, go vet, golangci-lint incl. Windows cross-lint: 0 issues on the round-2 diff). Security clean (no blocking findings — one non-blocking design observation on env-vs-config.yaml precedence, explicitly assessed and not treated as a defect). | +| 2 | Acceptance criteria met | PASS | be-wf9a's architecture decision (flip precedence: caller-explicit `ServerPort` outranks ambient env, paired with `PortSource` propagation so the fill-only-if-zero convention already used elsewhere in `applyConfigDefaults` extends to the env block) matches the shipped diff exactly — confirmed by reading both the decision doc and the reviewer's line-level trace of `open.go`/`store.go`, not by title alone. | +| 3 | Tests pass | PASS | `test_cmd`: `scripts/ci/pr-core.sh` (documented CI-equivalent), run fresh by the reviewer rather than trusted from builder self-report. Full suite: 93 packages ok, 0 FAIL, 0 SKIP, exit 0, 231s, with `-race`. All 4 diff-owned subtests under `TestApplyResolvedConfig` individually confirmed PASS (targeted `-v` rerun: 10 PASS, 0 FAIL, 0 SKIP). No diff-owned skip anywhere — criterion 3a's pre-existing-failure attribution path was not needed. | +| 3b | Policy/lint lane | PASS | `make ci-pr-lint` (`BD_LINT_NEW_FROM_MERGE_BASE=origin/main`): 0 issues, both native and `GOOS=windows/CGO_ENABLED=0` targets. | +| 4 | No HIGH-severity findings open | PASS | be-v2hy security_findings: "none blocking." The one recorded design observation (env no longer outranks `config.yaml`/`metadata.json`-sourced ports either, a real but intentional and defensible behavior change per the reviewer's own analysis) is explicitly flagged non-blocking, not a severity finding. | +| 5 | Final branch is clean | PASS | `git status --short` on `deploy/be-gd3v-gate` at `2dbcbd7f2`: no tracked-file changes. (Untracked leftovers — `release-gates/be-hi97*`, `release-gates/be-k9js*`, `release-gates/be-uoat*`, `scripts/rebase-resolve-lib.sh` — are per-session provisioned tooling from prior closed work, not part of this branch's history, and excluded from this commit.) | +| 6 | Branch diverges cleanly from main | PASS | Merge-base equals `origin/main` tip exactly (0 commits behind). `git merge-tree --write-tree origin/main 2dbcbd7f2` succeeds with a single merged tree, exit 0, no conflict markers. No self-rebase needed. | +| 7 | Single feature theme | PASS | `git diff --stat origin/main...2dbcbd7f2`: 5 files, all within `internal/doltserver` and `internal/storage/dolt` — `doltserver.go`, `open.go`, `open_test.go`, `store.go`, `store_unit_test.go`. 234 insertions(+), 19 deletions(-). One theme throughout: `ServerPort` precedence resolution and its test coverage (including the round-2 fix for the propagation gap round-1 review caught, `be-9tju`, which shares the same theme and is cited directly in two of the four commits). + +## Disposition + +- **PR opened, not merged.** `gastownhall/beads` is a contributor-only repo (no push/merge rights); the deployer's job ends at the open PR regardless of gate outcome — no merge-request routed, no waiting on mayor. +- Gate is a clean PASS with no waivers, no substitutes, and no open blockers — unlike the sibling `be-vc1m` deploy currently parked on this rig, this diff's criterion 3 has a real, fresh, fully-green test result. + +## Post-gate history + +This gate's verdict describes `2dbcbd7f2` and nothing after it. The branch head +has advanced since, so the `headRefOid` line above is a snapshot rather than a +standing claim — the commit that added *this file* was itself the first to move +the head past the gated SHA, which makes the unqualified "no drift" reading +self-contradictory. Recorded rather than silently corrected, since the PASS is +still accurate about what it examined: + +| After the gate | What it is | +|---|---| +| `b15b80077` | `docs(release-gates)`: added this gate document. Docs only; no code in the gated diff changed. | +| round-3 review response | Addresses PR #5835's `CHANGES_REQUESTED` review: `PortSource` propagation at four previously unthreaded `dolt.Config` sites, the CHANGELOG entry criterion 2's non-blocking observation foreshadowed, and this note. Code changes here are **not** covered by the criteria walk above. | + +Re-gating is the deployer's call, not the investigator's; this section exists so +that call is made against an accurate record.