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 four 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 back 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

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
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

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 now recorded here, so this
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 — the exact failure the
  record path's fold semantics exist to prevent. 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, and turning a cancel into a full bounce of a healthy replica set. That
  contradicts the design's own "same outcome, minus the tick" justification, so
  the cut-over now converges via the controller's reconcile_replicas kernel.
• How a cut-over settles a carried record. The design said "as cancelled"
  unconditionally. It now 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.