bridge: opt-in way for BridgeHandler::execute to wait for an in-flight async registration instead of failing "handler not bound"

[Yaraslaut]

Problem

With QtWebSocketBackendConfig::asyncRegistrationEnabled (required for a WASM client, whose main thread cannot spin the nested QEventLoop the blocking registration uses), a freshly constructed BridgeHandler is unbound until the server replies. BridgeHandler::execute() on a plain (non-keyed) action then fails fast with "handler not bound".

whenBound() (#60) makes this gateable, but every call site has to do it. In practice an embedder ends up writing the same wrapper around every handler it owns, because view models typically construct a handler and dispatch their first action in the same breath (e.g. on screen open):

template <typename Model>
class BoundHandler final : public morph::bridge::BridgeHandler<Model> {
    using Base = morph::bridge::BridgeHandler<Model>;
public:
    using Base::Base;
    template <typename Action>
    auto execute(Action action) -> morph::async::Completion<typename morph::model::ActionTraits<Action>::Result> {
        if (Base::isBound()) return Base::execute(std::move(action));
        // makeSettleable + whenBound().then(Base::execute(...)) + a liveness token
    }
};

The payload- and result-keyed branches of execute() already defer through attachHandlerAsync / ensureBoundAsync, so plain actions are the only route without a deferred path.

Proposal

An opt-in way for plain actions to wait for an in-flight registration instead of failing fast, e.g. one of:

• a BridgeHandler constructor option / policy (UnboundPolicy::Defer vs the current FailFast), or
• a separate executeWhenBound(action) on BridgeHandler.

Semantics: if isBound(), dispatch as today; if a registration is in flight, chain on whenBound() and dispatch on success; reject with the registration error (or a "not bound" error when whenBound() resolves false); drop the continuation if the handler is destroyed first.

The default stays fail-fast, so the documented trade in asyncRegistrationEnabled is unchanged for anyone relying on it.

Why in morph

The wrapper needs a liveness guard against the handler being destroyed before the bind settles, which morph can provide more cheaply and correctly from inside BridgeHandler (it already tracks binding lifetime) than each embedder can from outside.

[Yaraslaut]

Triage: triage: valid, area: core

Verification, at 9d001052: read from the code, the spec and the existing tests. I did not re-run anything.

• Bridge::executeVia (include/morph/core/bridge.hpp) returns an already-rejected completion when currentId == 0, by calling sink->setException(... "handler not bound"). It never waits.
• docs/spec/core/backend.md states this as the contract: "executeVia fails fast with "handler not bound" for a call issued before the reply arrives; it does not queue." The asyncRegistrationEnabled doc in qt_websocket_backend.hpp says the same thing.
• tests/test_async_registration.cpp covers that window. Its whenBound cases dispatch only once completeNext() has bound the handler.
• This tree already has the gate the issue describes, built once in examples/common/gui/presenter.hpp (trackBound() with a QPointer liveness guard). 14 presenters across 6 rungs call it, and each rung's QML then waits for bound before its first dispatch. Invariant 6 applies: every consumer needs the same guarantee, and the rungs had to build it outside the framework.

Architecture fit. The proposal breaks no invariant. The deferred dispatch runs on the handler's GUI executor, the model is untouched (invariant 1), and nothing has to derive from anything (invariant 2). The default stays fail-fast. The spec's "does not queue" sentence was stating a fact, not a prohibition. It needs updating in the same change: backend.md ("Consequences" paragraph) and bridge.md ("Registration readiness").

Two corrections before anyone builds it:

1. "The payload- and result-keyed branches of execute() already defer": those branches exist only on AllowShared handlers, and they perform an attach rather than wait for an in-flight initial registration. On a NoSharing handler, which is the WASM case, every action takes the plain branch. The gap is real, but the keyed branches are not a precedent for this design.
2. On AllowShared handlers whenBound() never waits. bridge.md: "for an AllowShared handler whenBound() is only ever isBound() in awaitable clothing". A "defer until bound" for a shared handler's keyless action would therefore resolve false straight away. Either limit the new path to NoSharing with a static_assert, or say that on shared handlers it behaves exactly like fail-fast.

Recommendation on the shape: use a separate executeWhenBound(action) rather than a constructor policy. With a policy, the same execute() call behaves differently depending on how the handler was built, and a reader of the call site cannot tell which. A named method shows the waiting at the call site. For liveness, the continuation should hold the HandlerBinding weakly (or check _lifetime) and should not capture this.

What would change the verdict: a design that makes plain execute() wait by default. That would move the documented asyncRegistrationEnabled trade and needs its own discussion.