doc: design for the cluster-controller legacy removal (reference only, do not merge)

[aljoscha]

Not intended to merge. This sits on top of the stack purely as reference for
what the changes below it did and why. Read it first, merge it last or never.

If you'd rather it landed — the repo does keep design docs under
doc/developer/design/ — say so and I'll move it to the bottom of the stack so
it merges ahead of the code. There's a real argument for it: the "what stays,
and why" and "alternatives" sections answer questions that will come up again
the next time someone touches this area, and a commit message is a worse place
to keep them.

The stack, in merge order

Merged:

1. adapter: remove ENABLE_CLUSTER_CONTROLLER and the legacy REFRESH scheduler #38101 — adapter: remove ENABLE_CLUSTER_CONTROLLER and the legacy REFRESH scheduler
2. adapter: let the cluster controller own system clusters #38102 — adapter: let the cluster controller own system clusters

Open:

3. adapter: delete the staged cluster reconfiguration machine #38103 — adapter: delete the staged cluster reconfiguration machine
4. sql: accept WITH (WAIT ...) on ALTER CLUSTER unconditionally #38104 — sql: accept WITH (WAIT ...) on ALTER CLUSTER unconditionally
5. adapter: don't leak arrangement compression into the realized config #38112 — adapter: don't leak arrangement compression into the realized config
6. adapter: let the synchronous cut-over change the replication factor #38174 — adapter: let the synchronous cut-over change the replication factor
7. this one

What the design says

The cluster controller has been merged and default-on since v26.29, but it still
lived behind the ENABLE_CLUSTER_CONTROLLER break-glass dyncfg, and system
clusters were excluded from its ownership. Those two facts kept three legacy code
paths alive: the REFRESH scheduler, the staged (WaitForHydrated / Finalize /
-pending) reconfiguration machine, and the sequencer's own replica create/drop
implementation for system clusters.

The doc walks each part, and carries two sections that are the reason it exists
at all rather than being folded into commit messages: "What stays, and why"
(the four things that look deletable and are not) and "Alternatives" (in
particular why deleting the direct reshape path entirely was rejected, which is
the load-bearing decision in part 3).

Amended to match what shipped

The design left some things open that the implementation had to settle, and one
thing it specified turned out to be wrong. Both are recorded here, so the
document describes what we built rather than what we first proposed:

• The cut-over folds its target. The design just said "write the target
  config". A statement that mentions one shape dimension while a reconfiguration
  is in flight would then have silently reverted the in-flight transition along
  every dimension it did not mention. Both paths now share
  alter_reconfiguration_target.
• The cut-over is not a blind whole-set recreate. The design specified "drop
  the observed owned replica set and recreate it", which would cold-restart a
  replica that already had the target shape, making a forced commit of a
  stuck-but-hydrating resize more disruptive than letting the controller do it.
  That contradicts the design's own "same outcome, minus the tick"
  justification, so the cut-over converges via the controller's
  reconcile_replicas kernel.
• How a cut-over settles a carried record. The design said "as cancelled"
  unconditionally. It settles Finalized { forced: true } when the cut-over
  landed on the record's own target, and Cancelled otherwise.
• Part 4 was not in the original design and now has its own section.
• The mixed-version flag pins are bound at v26.38, the version this lands in.

Known gap, tracked elsewhere

The synchronous cut-over still decides its replica set from a hand-built
baseline-only desired set rather than the controller's full strategy set, so it
drops an in-flight hydration-burst replica that the controller would have kept
(found in review on #38103). The record survives and the controller re-creates
the replica on the next tick, so it's a cold bounce rather than a strand, and
the old code path did the same thing. Fixing it properly means sharing the
decision function, which is worth doing structurally rather than patching the
symptom.