* docs(engdocs): write down the proxied-server surfaces an embedder reads, as observed at 1.3.1
An embedder — an external tool linking bd's Go packages, or one running beside
bd against the same workspace — ends up depending on surfaces bd never
published: proxy.pid's field names, the db-proxy-child argv, the shape of
`bd dolt status --json`, whether a Go symbol is exported or reachable only by
type assertion. Eleven of those were asked about; none of them is a contract,
and the answer to "will these hold" is no promise. This writes them down
anyway, as observed behaviour with the commit they were read at, so that an
embedder can build against what the code does instead of guessing.
Framing is deliberate and the document says so twice: descriptive, not a
compatibility contract; every surface may change in any release, including a
patch release. Four are moving in 1.3.1 itself and are given as before/after —
`bd dolt status --json`'s reshape (#6580) has landed and is described in its new
shape; the `bd migrate schema` refusal, the explicit sidecar `idle_timeout`, and
clean-backend-exit handling plus backend-probing adoption (#6651) are decided
but had not landed at d487b9796, so each states current behaviour as current. A
closing section ranks which surfaces are likelier to move, and a final one lists
the claims that would need a running proxy to confirm and were inferred from
source instead.
Four of the eleven pointers the request carried were off, and are corrected
here rather than copied:
- The loopback root/no-password fact is not in the proxy's connection handler
at all. Only the byte-pump half lives there; the credentials come from
newManagedProxiedServerUOWProvider passing "root"/"" in cmd/bd/uow_factory.go,
over a generated sql-server config that binds 127.0.0.1 and declares no users.
- SetEventsJournalEnabled is not on the Storage interface and is not named in
beads_cgo.go. It is storage.EventsJournalConfigurer, an optional interface in
internal/storage/storage.go, which is not re-exported publicly — so the
assertion has to be written against a locally declared method set.
- The shared-store gate's 30s default constant lives in
internal/storage/uow/dolt_sql_provider.go, not in the provider that applies it.
- The argv pointer stopped at --config and missed --dolt-bin, --database and the
four --external-* flags.
While verifying #8 a routing fact turned up that an embedder needs more than the
interface question: neither copy of OpenBestAvailable has a proxied arm, and
IsDoltServerMode and IsDoltProxiedServerMode are mutually exclusive, so on a
proxied workspace it falls through to an embedded open over .beads/dolt — the
same directory the proxy's sql-server is serving. Documented, with the
consequence of that open marked as untested here.
Filed under engdocs/ beside EXTENDING.md, which is already the entry point for
"not user-facing; for code that embeds bd", linked from it, and registered in
DOC_INVENTORY.md's Active Docs and Reference Freshness tables. The Last
reviewed / Freshness source markers match check-doc-freshness.sh's format but
the doc is deliberately NOT added to that script's enforced list: putting a
90-day tripwire on a release branch is a maintainer's call.
scripts/check-doc-flags.sh and scripts/check-doc-freshness.sh both pass.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(engdocs): describe the data-port capability generically
The prior wording named an integration shape rather than the capability. State
what the byte pump plus the generated config actually let an embedder do.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(engdocs): correct five factual claims and drop four promise leaks
Two adversarial reviews returned FIX_FIRST on the observed-surfaces doc.
Corrections, each re-verified against source:
- §8: the embedded fall-through does not open the directory the proxy is
serving. embeddeddolt hardcodes <beadsDir>/embeddeddolt (newStore,
cacheKey, HasRepository); the proxy serves the proxied root, default
<beadsDir>/dolt. The hazard is a silently separate database — empty on a
workspace born proxied, stale on one that was ever embedded, since no
mode-migration verb removes that directory — not contention.
- §10: backend_running carries no omitempty, so five keys are always
present, not four. The doc's own external example contradicted its rule.
- §3: neither readiness probe uses credentials. Both poll
DatabaseServer.Dial, a bare TCP connect. root/"" belongs to bd's SQL open
and to DoltServer's shutdown GC.
- §2: the --external-* flags need both conditions — external backend AND a
set value — and ExternalDoltConfig.Validate makes host/port and socket
mutually exclusive, so all four never appear together.
- §6: the proxied migrate payload is NOT the direct path's shape. Direct
emits {status, applied, latest_version}; proxied drops applied and adds
mode and note.
- §4: Handle.Kill is SIGKILL on macOS too, and the stop epoch advances once
per call rather than per record.
Promise leaks removed: the invented "would break the same consumers twice"
maintainer policy, flat future tense on an unlanded warning, "safe for an
embedder to poll", and "least likely to move" as a stability signal.
check-doc-flags.sh and check-doc-freshness.sh both pass.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(engdocs): drop a Markdown-unsafe escaped quote from the §8 rewrite
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(engdocs): re-anchor to the rebase base and record the #6575 data-behind stop
Maintainer review fixup for #6652.
The doc landed marked `Read at: d487b9796`, but the branch merges into
`e1e1158dd`, and five of the sources it names as its freshness basis drifted
in between — including §7's sole source. By the doc's own rule that makes the
marker wrong, not merely old.
- Re-anchor `Read at:`/`Last reviewed:` and the four in-body read-commit
references to `e1e1158dd`, and add the sources the re-read reached:
`smart_remote_migrate_gate.go`, `internal/storage/embeddeddolt/`,
`cmd/bd/remote_migrate_gate.go`, `cmd/bd/store_factory.go`,
`internal/storage/dolt/store.go`.
- §7: record #6575's data-behind stop — trigger, its reporting ahead of
`shared-store`, the collapse to a single `pull-first` option, the exported
`IsDataBehind()`/`DataBehindRemedyCommand` an embedder classifies on, and
the lenient `OpenForRemoteSync` carve-out for the remedy.
- §7: scope the `OpenForRemoteSync` carve-out to the CLI. Both that function
and the `dolt.Config.RemoteSyncOpen` field live under `internal/`, and none
of the public open paths takes an option that could request the lenient open,
so an embedder cannot replicate the remedy in-process: it runs `bd dolt pull`
out of process, outside proxied mode, and re-opens.
- §7: scope that stop's reachability to the call sites that wire the ancestry
adopter, rather than asserting a proxied workspace meets it.
`localDataBehind` reads `FastForwardAdopter.AheadBehind` and reports "not
behind" when the adopter is nil; of the two production callers of
`CheckSharedStoreMigrateGate`, only `internal/storage/dolt`'s server-mode
open wires it. `internal/storage/uow/dolt_sql_provider.go` — the proxied CLI
path and `bd serve`'s own provider, per `cmd/bd/uow_factory.go` — passes
nil, so a proxied, remote-backed clone that is data-behind at schema parity
routes to `smartAutoMigrate` and gets the shared-store refusal, never the
pull-first one. Embedded mode reaches the stop by the other route,
`CheckRemoteMigrateGateWithAdopt` with a fully-wired adopter. The proxied
`dolt pull` observation is re-framed to match: the pull is still the
precondition and proxied mode still refuses the verb, but the gate never
names it there. The underlying gap is base behaviour at this commit.
- §7: the trigger is `behind >= 1` whatever `ahead` is, not the narrower
strict-ancestor relation — `localDataBehind` states that restricting the
stop to `ahead == 0` "would leave the larger half of the affected cohort
unprotected". The `DataDiverged` bullet now names `ahead >= 1` as the shape,
which is why that pull merges rather than fast-forwards.
- §7's "adds two refusals" is deliberately kept. That count is the shared
form's delta over the remote-backed flow and mirrors the source comment on
`CheckSharedStoreMigrateGate`; the data-behind stop lives in
`checkRemoteMigrateGate` underneath, so raising it to three would introduce
a new error. The section now says so in place.
- §8: four join sites, not three — name `openReadOnly` and scope the
create-rather-than-fail claim to the read-write path.
- §3: carry the "not verified by running" marker inline beside the MySQL
client claim, as §11 already does.
- §6: scope the migrate-verb consent to the arm that reads it. The headline
and the consent bullet said the verb migrates on a proxied workspace
unconditionally, contradicting §7's own already-correct wording.
`sharedMigrateConsent` has exactly one non-test read site,
`sharedNoRemoteGate`, reached only from `checkRemoteMigrateGate`'s
`if !hasRemote` branch; the comment there scopes it deliberately, because
with a remote configured #4259's cross-clone fork risk still demands the
stronger designated-migrator confirmation. A remote-backed shared or proxied
database consults only `--force` / `BD_ALLOW_REMOTE_MIGRATE` and otherwise
refuses the pending main-lane migration at the store open. §7's
`SharedConsentCommand` hedge is deliberately unchanged.
- §6: qualify the `--force` parenthetical in that same consent bullet.
`bd migrate schema --force` trips `isForcedMigrate`, but the bare
`bd migrate --force` never gets that far on a proxied workspace:
`validateProxyMaintenanceBeforeProvider` runs inside the proxied-mode block
of the root `PersistentPreRunE`, ahead of
`schema.SetForceAllowRemoteMigrate`, and its full-path lookup matches
`migrate` and exits with `proxy.migrate.unsupported` before any store opens
— the refusal §6's own second paragraph already states. `bd migrate schema`
escapes only because its command path contains a space and returns nil
first. The clause now scopes the bare verb instead of offering it as an
unlock on the one workspace that refuses it.
- §6: name the `migrate sync`/`migrate-personal`/`migrate-issues` rows and
the history-capability gate that runs before the multi-word fall-through.
- Update the "Four of the eleven" count and the `DOC_INVENTORY` freshness row
to match.
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>