Explicit setup-time coupling for CoupledSimulations (replaces couple_buffers)

[knutambot]

Summary

Replaces the implicit, per-call coupled-buffer mechanism (couple_buffers, the keyword-only
CoupledSimulations partner bag, and the 3-arg work!(worker, sim, coupled)) with an
explicit, setup-time CoupledSimulations group. This fixes BUG-003 (stale partner time
increments under threading) at the root, and closes the whole class of bugs it belonged to
(stale/deepcopied partner buffer references in general, not just Δt), and also closes
BUG-017 (coupling setup silently under-validating domain/task compatibility).

• CoupledSimulations((a = sima, b = simb); refs = (c = simc,)) builds a group once: every
  primary reads every other primary and every ref (a ref has no outgoing dependencies but is
  still accessible/workable). Setup validates matching grids, single/dictionary domain shape,
  supported buffer kinds (rejecting e.g. facet buffers with an actionable error, including for
  a sole primary with no partners), per-domain cell coverage, per-domain task-count
  compatibility (a threaded reader requires equal task counts, a sequential partner counting
  as 1 slot), reserved member names, and that no two members alias the same mutable
  item-buffer scratch (including scratch preserved by replace_material).
• work!(worker, group.member_name) needs no extra arguments — the member handle already
  carries its resolved coupling, and scatters each partner's task-local buffers from its base
  before dispatch so a threaded reader always observes the partner's current state (this is
  the BUG-003 fix, generalized to the new design).
• New CoupledCellBuffer holds direct, nonrecursive references into partners' own
  CellBuffers and Simulations — never a deepcopy, never rebuilt per cell or per work!
  call. Coupling is direct, not transitive: a partner's own coupling (if any) is not exposed.
• A new AbstractSimulation{DB} type unifies Simulation and CoupledSimulation, with
  generic forwarding for the accessor API (get_dofhandler, get_state,
  set_time_increment!, update_states!, revert_states!, etc.) and a single, shared set of
  work!/work_domain_sequential!/work_domain_threaded!/scatter! methods dispatching on
  AbstractSimulation type-alias bounds — no more duplicated work-dispatch machinery between
  plain and coupled simulations.
• CoupledSimulation (a handle to one primary member, e.g. group.a) forwards ordinary
  Simulation property access (.a, .aold, .db) via getproperty/propertynames, so it
  tab-completes and behaves like the underlying Simulation for everything except coupling
  and replacement.
• FerriteAssembly.replace_material(group, member, f; domain=nothing) rebuilds the whole
  group from source simulations (rerunning validation and autodiff configuration
  construction); other members are reused by reference. Previously obtained handles keep
  their prior configuration. A member handle rejects replace_material directly, pointing the
  caller at the group-level call.
• Migrated the phase-field fracture tutorial (the only in-repo coupled-buffer user) and the
  coupling test suite to the new API, and rewrote the coupling documentation
  (docs/src/DomainBuffers/Setup.md) including an explicit concurrency contract: coupled
  buffers reference partners' actual mutable storage, so work! calls sharing any of that
  storage (two members of the same group, a group member and its pre-group source
  Simulation, two groups sharing members by reference, or re-entrant calls) must not run
  concurrently — only ordinary sequential/staggered use is safe.

This is a breaking change: couple_buffers and the keyword-only CoupledSimulations/3-arg
work! are removed with no compatibility shim, per the agreed design.

Test plan

• Pkg.test() — full suite green with both 1 and 4 threads (CoupledSimulations
  testset: 1724 assertions covering mutual/one-way/mixed groups; the BUG-003 Δt
  regression; autodiff-through-coupling numerical agreement vs. a hand-differentiated
  reference; replace_material through a group, including material-type changes;
  constant-propagation and tab-completion for the forwarded properties; and setup
  validation failures, including unsupported buffer kinds and incompatible task counts)
• All literate tutorials/howtos run clean, including phasefield_fracture.jl
• Full docs/make.jl HTML build completes without error
• Reviewed with an independent Codex reviewer across the incremental development of this
  branch, and again as a complete, whole-branch review of the final diff against main
  (plan review + final-diff review); all accepted findings were fixed and re-verified

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com

🤖 Generated with Claude Code

https://claude.ai/code/session_01KySgpVgJ5fWR9AvPK1JQoU

[codecov]

Codecov Report

❌ Patch coverage is 98.79518% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.17%. Comparing base (6c7564c) to head (367a73c).

Files with missing lines	Patch %	Lines
src/work.jl	96.49%	2 Missing ⚠️
src/Coupling.jl	99.28%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #92      +/-   ##
==========================================
+ Coverage   96.94%   97.17%   +0.23%     
==========================================
  Files          30       32       +2     
  Lines        1210     1347     +137     
==========================================
+ Hits         1173     1309     +136     
- Misses         37       38       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.