beads/docs
Julian Knutsen a4c47ccfdf
fix(schema,uow): route the proxied data-behind open to the #6575 stop (port of #6695 to main) (#7481)
* fix(schema,uow): route the proxied data-behind open to the #6575 stop with topology-correct guidance (port of #6695)

Port of the release/1.3.x commit bb03a310a9 (PR #6695) to main, where it
never landed: v1.3.1 is cut from a release branch that is not an ancestor
of main.

The proxied / `bd serve` open path never reached the #6575 data-behind
stop. doltSQLProvider.initSchemaAttempt passed a nil adopter to
CheckSharedStoreMigrateGate, so localDataBehind short-circuited and the
router could never emit smartDataBehind. A proxied store that was level
on schema and behind in data reported `shared-store` instead, whose body
is the designated-migrator recipe -- `bd migrate --force` then
`bd dolt push` -- which in that state is exactly the #6368 wedge the
stop exists to prevent. The refusal was always safe (the shared arm
suppresses the auto-migrate either way); the guidance was not.

- uow: wire a dataBehindAdopter with AheadBehind only
  (versioncontrolops.LocalAheadBehind). IsStrictAncestor/WorkingSetClean
  stay nil so the remote-ahead arm keeps its plain adopt directive, and
  FastForward stays nil because it would promote the schema for every
  co-resident client. Read-only proxied opens print the pull-first block
  instead of the shared-consent template.
- uow.WithProxiedServerMode(), set only by openProxiedServerUOWProvider,
  marks the refusal Proxied: the same provider serves `bd serve` on a
  SERVER-mode workspace, where `bd dolt pull` works.
- schema: a Proxied refusal names the server host as where the pull runs
  (`bd dolt pull` is refused at the proxied front door,
  proxy.dolt_pull.unsupported), the option id becomes
  pull-first-on-server-host, and the guidance says the forced
  `bd migrate schema --force` consent step IS runnable from the proxied
  workspace (the capability registry permits `migrate schema`), so it must
  wait for the pull, and that BD_ALLOW_REMOTE_MIGRATE=1 is reachable too.
- cmd/bd: the --json `expected` field carries the same location
  qualifier (dataBehindExpectedField).

Not ported, because main already has it: the release PR's F-B half (the
shared data-behind consent step naming `bd migrate schema --force` and
its --global twin, the printGlobalDatabaseConsentHint retarget, and the
shared_migrate_consent_test.go changes) landed on main as #6692.
Adapted to main: the release line's proxyMaintenanceRefusals table is
main's capability registry, so TestProxyMaintenanceAllowsTheSharedConsentVerb
drives validateProxyRegistryBeforeProvider for every proxied topology and
also pins that `bd dolt pull` and the bare `bd migrate` are refused; the
CHANGELOG paragraph is appended to main's existing #6575 entry.

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

* docs(upgrading): where the proxied data-behind pull runs; pin its plumbing

Review fixes for the proxied data-behind stop: the one major of review
attempt 1, the cheap minors, and the nit, plus the wording minor of
attempt 2.

- Clone behind the remote, the docs section the gate's payload links
  to, prescribed `bd dolt pull` with no topology qualifier: the remedy a
  proxied-server workspace refuses at its front door. Its intro now says
  so, and a proxied-server step pair puts the pull (and any conflict
  resolution) on the server host, from a workspace with direct database
  access, then `bd migrate schema --force` in the proxied workspace. It
  also warns that nothing there enforces that order: `--force` and
  BD_ALLOW_REMOTE_MIGRATE=1 are honored before the stop is reached, so
  the stop never sees them. The warning ends on the payload's own
  instruction, not to reach for either to get past the stop, rather than
  a negation ("neither is a way past it") that read as the topology
  blocking the wedge. The pending-migration exception above the section,
  the proxied-server list under Shared servers (now three differences)
  and the init-safety ordering rule say the same. The heading, and with
  it the anchor the gate links, is unchanged.
- The option plumbing that carries the fix is pinned link by link.
  TestApplyProviderOptions covers WithProxiedServerMode (it sets that
  field and no open posture). The cmd/bd append moves into
  proxiedProviderOptions, which TestProxiedProviderOptions holds to
  exactly one added option on a fresh slice. And
  TestNewDoltServerUOWProvider_CarriesProxiedServerMode opens two real
  providers on one server, with and without the option, and reads the
  field the gate copies; openAndInitSchema's provider literal and the
  shared test open helpers are left as they were.
- TestProxyMaintenanceAllowsTheSharedConsentVerb also pins `bd dolt
  push` and `bd conflicts resolve` as refused, the rest of the list the
  proxied refusal body recites. `dolt push` is refused as unimplemented,
  the kind of row that flips to allowed once a route lands.
- localDataBehind's doc comment is re-wrapped so the IsStrictAncestor
  sentence no longer breaks across the inserted parenthetical.
- The CHANGELOG entry notes the docs change.

Each new pin is red with its link reverted: the option dropped from the
cmd/bd append, the append made in place, the field copy deleted from
the provider literal, the constructor dropping its options, the option
also setting preview, and the push and conflicts codes changed. Still
unpinned: which option the cmd/bd append adds (options are opaque
outside uow) and that `bd serve`'s server-mode open passes none; both
need a seam in cmd/bd.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-10-11 00:23:25 +00:00
..
architecture Fix ResolveServerMode ambient port-var handling and the KillStaleServers regression it introduced (#5934) 2026-09-30 07:13:57 -07:00
cli-reference 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
core-concepts Refuse reserved words and fuzzy id matches on bd comment writes (#5393) 2026-10-01 05:04:32 -07:00
diagrams docs: port the Excalidraw diagram pipeline (machinery only) 2026-07-12 10:37:17 -07:00
getting-started fix(schema,uow): route the proxied data-behind open to the #6575 stop (port of #6695 to main) (#7481) 2026-10-11 00:23:25 +00:00
images docs: port user docs into the Mintlify site tree under docs/ 2026-07-12 10:37:07 -07:00
integrations docs(cursor): re-review docs/integrations/cursor.md against cmd/bd/setup/cursor.go (#7333) 2026-10-08 08:20:31 +00:00
multi-agent fix(reclaim): correct the heartbeat re-home invariant's scope in the new docs (wy-sp2l4) 2026-08-13 04:30:30 -07:00
recovery fix(schema,uow): route the proxied data-behind open to the #6575 stop (port of #6695 to main) (#7481) 2026-10-11 00:23:25 +00:00
reference show/list: render a derived GATED decoration when an open gate holds the bead (#6606) 2026-10-08 10:37:51 +00:00
workflows fix(gate): resolve a bead gate whose awaited bead no longer exists (#6395) 2026-10-08 17:10:33 +00:00
cli-docs.pin chore(release): forward-port v1.2.2 to main (version record, retracts, recovery guide, gate record) (#5782) 2026-08-14 21:45:02 -07:00
CLI_REFERENCE.md 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
community-tools.md docs: scope the shared-server read failure to pre-1.2.0 schemas; add eight community tools (#7301) 2026-10-06 10:56:39 -07:00
docs.json Beads 1.2 remediation: migration-consent gate — bd never migrates an existing database without explicit consent (#5764) 2026-10-08 08:21:31 +00:00
index.md release: prep v1.3.0 — version bump, changelog rollup, release process docs, formula fixes (#6038) 2026-08-30 22:19:35 -07:00
RECOVERY.md docs(recovery): reduce the stub to a pure pointer 2026-07-17 18:56:33 -07:00
related-projects.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00