beads/engdocs
Julian Knutsen 1e754a0156
docs(engdocs): proxied-server surfaces an embedder reads, as observed at 1.3.1 (#6652)
* 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>
2026-09-23 21:59:27 -07:00
..
adr Add append-only provenance_events log and bd provenance CLI (#4461) 2026-08-07 09:43:20 -07:00
decisions docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
design release: make release/1.3.0 tag-ready — revert #6281, stamp 1.3.0, date the changelog (#6564) 2026-09-15 12:13:59 -07:00
staged-for-removal docs: pin the Dolt version instead of steering users to releases/latest (ga-m0dlk) (#5899) 2026-08-20 22:41:24 -07:00
ADDING_AN_ISSUEOPS_ROLE.md feat(journalops): the mutation journal becomes the third facade namespace (#5552) 2026-08-10 10:58:05 -07:00
AGENT_SIGNING.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
ATTRIBUTION.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
CI_CLEANUP_PLAN.md Make the pre-commit lint gate trustworthy, and stop one main-side lint word from reddening every PR (#5538) 2026-08-10 04:55:55 -07:00
CI_REQUIRED_CHECK_TOPOLOGY.md ci: PR-CI lane runs the full internal/storage/dolt suite against a live Dolt server (#5836) 2026-08-19 20:39:38 -07:00
CI_TEST_SURFACE_AUDIT.md ci: shard Embedded Dolt Storage into 5 manifest-driven shards (#5117) 2026-07-28 22:16:48 -07:00
CLAUDE.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
COLLISION_MATH.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
CONTRIBUTOR_NAMESPACE_ISOLATION.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
DOC_INVENTORY.md docs(engdocs): proxied-server surfaces an embedder reads, as observed at 1.3.1 (#6652) 2026-09-23 21:59:27 -07:00
EMBEDDING_OVER_PROXIED_SERVER.md docs(engdocs): proxied-server surfaces an embedder reads, as observed at 1.3.1 (#6652) 2026-09-23 21:59:27 -07:00
ERROR_HANDLING.md docs: port user docs into the Mintlify site tree under docs/ 2026-07-12 10:37:07 -07:00
EXCLUSIVE_LOCK.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
EXTENDING.md docs(engdocs): proxied-server surfaces an embedder reads, as observed at 1.3.1 (#6652) 2026-09-23 21:59:27 -07:00
ICU-POLICY.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
INTEGRATION_CHARTER.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
INTERNALS.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
LINTING.md Make the pre-commit lint gate trustworthy, and stop one main-side lint word from reddening every PR (#5538) 2026-08-10 04:55:55 -07:00
messaging.md fix(doctor): recommend 'bd prune' instead of nonexistent 'bd cleanup' (#5829) 2026-08-20 05:30:47 -07:00
PERFORMANCE_TESTING.md docs(engdocs): point storage test and bench references at the Dolt packages 2026-07-18 02:43:57 +00:00
PROJECT_CHARTER.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
README_TESTING.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
RELEASE-STABILITY-GATE.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
RELEASING.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
REPO_CONTEXT.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
RULES_AUDIT_DESIGN.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
SECURITY-DEPENDENCY-EXCEPTIONS.md Bump Go to 1.26.5 (#4942) 2026-07-23 18:54:32 -07:00
SERVE_RUNBOOK.md docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545) 2026-08-10 08:05:07 -07:00
TESTING.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
TESTING_PHILOSOPHY.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
UI_PHILOSOPHY.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00