Unordered sections: SectionSet<Model, Sections...> (#513)

[Yaraslaut]

Closes #513.

The gap

FlowSession::set<> throws std::logic_error on a field belonging to any step but the current one. That is right for a wizard and wrong for a screen whose blocks have no order — a settings page, a tab strip, a column of cards — where a user may edit the third block first and never touch the second. Before this, such a screen either hand-wired one execute call site per block (re-implementing draft accumulation and the readiness gate each time) or misused a wizard and got a logic_error for editing its own form out of order.

SectionSet keeps everything FlowSession does per action — per-action draft accumulation, the readiness gate, result capture, error routing, the callback lifetime gate — and drops only the position.

using ProfileSection = morph::forms::Section<UpdateProfile, "Profile">;
using PrefsSection   = morph::forms::Section<UpdatePrefs, "Preferences",
                                             morph::forms::Bind<"profileId", "UpdateProfile.id">>;

morph::forms::SectionSet<SettingsModel, ProfileSection, PrefsSection> sections{handler};
sections.set<&UpdatePrefs::theme>("dark");   // fires -- no ordering
sections.set<&UpdateProfile::name>("ada");   // fires

What is here

Commit
4cb331a3	Extract Bind, the tuple/pack walkers and the distinctness trait to forms/detail/session_common.hpp. Pure refactor; morph::flows::Bind stays as an alias.
064a4ee6	Section, SectionGroup, SectionGroupTraits, BRIDGE_REGISTER_SECTION_GROUP, sectionGroupSchemaJson<G>().
26982ae6	SectionSet — set<>, reset<A>(), draft<A>(), resolved(path), result capture, error routing, the callback scope.
3950cef8	Nine test cases.
76f79f12	docs/spec/forms/sections.md.
(last)	clang-tidy on changed lines.

app.hpp reached into flows::detail for a walker it uses on its own menu and screens tuples — nothing to do with wizards. It now includes the shared header directly.

Two decisions worth flagging

The schema emits no index or order key. A renderer arranges the sections itself, and a position in the wire format would suggest a sequence a section group does not have. That is the one thing distinguishing s-* from w-*, so emitting an index would erase the distinction the type exists to make.

Prefill is a declaration, not a write — exact parity with FlowSession. An earlier draft of the design had SectionSet reactively assign a bound field the moment its source resolved. With no ordering that is a coherent design, but it would silently overwrite a value the user had already typed, with no signal, and only for bound fields. The renderer knows whether its widget is dirty; the session does not.

Verification

Nine cases, each checked to fail with its implementation removed. Two of them measured nothing as first written, and that mutation run is what said so:

• "a not-ready draft" checked the recorder immediately after an incomplete set<>. Dispatch is asynchronous, so the check passed whether or not the gate existed. It now watches onError, which is where a missing gate is actually visible: BridgeHandler::execute enforces ActionValidator on its own path, so an ungated draft never reaches execute() either — it comes back as a validation failure. The round trip that can only fail is the cost the gate avoids. (My first comment on that test claimed an ungated draft would "dispatch a half-filled action". It would not. Corrected.)
• the lifetime case destroyed the set with nothing genuinely in flight, so it exercised no window at all. It now uses a section whose model call blocks until the test releases it, released only after the scope closes.

One limit, stated plainly: that lifetime case cannot distinguish the destructor's explicit requestStop() from CallbackScope's own destructor — both stop delivery, and the window a member-reordering regression would open is a few instructions wide, which neither ASan nor a blocking action reliably hits. It guards the property that matters (a completion arriving after destruction delivers nothing). The explicit call stays as forward-defence for a destructor body that might one day pump, which is what its comment claims and all it claims.

What CI caught that I did not

A segfault on Windows / cl-debug, in the #513 regression test. Not a flake and not a Windows quirk — a real use-after-free my tests caused, which TSan reproduces locally about once in fifteen runs.

CallbackScope::requestStop() does not wait for a callback already past its token check; that is its documented contract, and FlowSession has the same property. So a test may only destroy a SectionSet once no completion is running, and mine could not tell:

• the recorder is written inside execute(), which runs before the completion that touches the SectionSet, so waiting on it proved nothing;
• resolved() is no better — captureResult publishes its first key while still writing the rest, so a test that waits for one key and then leaves scope tears the set down underneath its own callback. That is exactly what TSan reports, in captureResult's write loop.

Every case except the lifetime one now uses StepExecutor and an explicit drain(), so the thread that delivers the completion is the thread that destroys the set — the case the guarantee actually covers. That removes the race rather than narrowing it, and the tests assert exact counts instead of polling for them. 0 failures in 100 TSan runs and 60 ASan runs, from ~1 in 15 before. The rule is now written down in the spec, since a caller can get this wrong the same way.

clang-tidy findings my local run missed. Filtering clang-tidy's output by filename hid glaze-DOM operator[] findings that the default run suppresses as non-user code; only an explicit --checks run surfaced them. Cleared with the marker forms.hpp already uses for the same DOM.

Mutations that the suite does catch: readiness gate removed, reset clearing every section, result fields not captured, draft fields not captured, onError branch dropped.

Local pre-flight, all green: tree-wide clang-format --dry-run -Werror; -Wdocumentation -Werror; clang and GCC full suites (1437 cases); TSan, ASan and Valgrind on [sections]; check_spec_citations.sh; clang-tidy clean on every changed line.

The spec-citation lint also caught a dangling section citation in the design doc — callback_scope.md's heading is "Thread safety and the boundary of the guarantee", not "Boundary of the guarantee". Fixed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SxkvtHvan2fWKDDaBpqkgv

[codecov]

Codecov Report

❌ Patch coverage is 98.01980% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
include/morph/forms/sections.hpp	97.53%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!