kanban: openBoard() is dispatched without waiting for its handler registration to bind (Remote mode)

[Yaraslaut]

Summary

BoardBridge::openBoard() is dispatched from QML with no gate on its handler's registration having bound. In Remote/Socket mode a dispatch that lands before registration settles is rejected with "handler not bound", which would surface as a failed() toast on a board that never loads.

Verification status

Inferred from reading, not reproduced. Established by reading Main.qml, board_qml_bridge.cpp and examples/common/gui/presenter.hpp on origin/master @ 9371c1a0. No Socket-mode client was stood up and raced, and no failure was observed. What follows is a structural argument, not a measurement.

What the code says

examples/common/gui/presenter.hpp:40 documents that a BridgeHandler in Remote mode rejects dispatch with "handler not bound" until its registration round trip lands, and that bound() is the settlement signal for it.

ProjectListView.qml:56-61 consumes exactly that for projectAdminBridge, gating its first refreshProjects() on onBound.

BoardBridge relays the same signal (examples/kanban/gui_lib/board_qml_bridge.cpp:232) and nothing consumes it — not QML, not tests. Meanwhile examples/kanban/gui/qml/Main.qml:92-95 dispatches unconditionally:

onProjectOpened: (projectId, myRole) => {
    root.boardBridge.setMyRole(myRole)
    root.boardBridge.openBoard(projectId)
    stack.push(boardPage)
}

So the first dispatch on BoardBridge is user-triggered with no bind gate. In Local mode this is a non-issue — the handler is bound by construction.

Why it is improbable rather than impossible

Both bridges are constructed together at startup (examples/kanban/gui/main.cpp), and reaching onProjectOpened requires a login round trip, a project-list render, and a human click. The registration round trip has, in practice, many seconds of head start.

The ordering is protected by human latency, not by construction. That is the defect: the guarantee is incidental.

What would change the verdict

• Close it if someone shows the registration is guaranteed to settle before any BoardBridge dispatch can be issued — e.g. if Bridge queues pre-bind dispatches rather than rejecting them. That seems unlikely, since it would also make ProjectListView's own onBound gate unnecessary.
• Confirm it by driving a Socket-mode client with a stalled registration reply and calling openBoard(). examples/common/testkit/fault_proxy.hpp is the tool.

Interaction with the in-flight #291 work

The branch fixing morph#291 deletes BoardBridge::bound as dead QML surface. That is correct for the audit — the signal is unconsumed and, given the Main.qml:92-95 ordering above, could not be consumed usefully where it stands: a handler on BoardView attaches after openBoard() has already been dispatched. Gating properly means restructuring navigation, not adding a handler.

That deletion neither creates this hazard nor worsens it. BoardPresenter::bound remains, and restoring the relay is one line if the fix turns out to be gating navigation on it.

Recorded separately rather than folded into a QML-wiring change, per AGENTS.md.

[Yaraslaut]

Triage: valid — premise confirmed, fix direction is right

What I verified, and how

Read, not assumed — every line cited in the issue still matches master
after #313 (7ae3ad4, merged 2026-08-26T18:10:41Z, ~3h after this issue was
filed at 14:18:36Z):

• examples/kanban/gui/qml/Main.qml:92-95 still dispatches unconditionally:

  onProjectOpened: (projectId, myRole) => {
      root.boardBridge.setMyRole(myRole)
      root.boardBridge.openBoard(projectId)
      stack.push(boardPage)
  }

  stack.push(boardPage) (line 95) — which is what would instantiate a
  BoardView capable of attaching an onBound handler — runs after
  openBoard() is already dispatched. So even adding a handler inside
  BoardView.qml could not catch a bound() that already fired; the gate
  has to live in Main.qml's onProjectOpened itself.

• examples/kanban/gui_lib/board_qml_bridge.hpp:385-394 confirms kanban: populate the automation-rules pane, and work the unbound-surface backlog off member by member #313
  removed the bound() relay rather than fixing the race — the comment
  left in its place says exactly that:

  "No bound() relay here, unlike ProjectAdminBridge. [...] This bridge
  has no such caller and could not usefully acquire one where it stands
  [...] BoardPresenter::bound is still emitted; re-relaying it is one
  line if a future shell gates navigation on it."

  I confirmed BoardPresenter::bound is in fact still emitted:
  board_presenter.cpp:23 calls trackBound(_handler.whenBound()) in the
  constructor, unchanged. So kanban: populate the automation-rules pane, and work the unbound-surface backlog off member by member #313 correctly identified and described this
  gap while triaging unbound QML surface, but explicitly deferred it rather
  than closing it — it does not supersede this issue.

• Mechanics of the race, traced to source: Bridge::executeVia
  (include/morph/core/bridge.hpp:1352-1362) reads binding->currentId
  lock-free; if raw == 0U it resolves synchronously with
  std::runtime_error("handler not bound") — no queueing, no retry. The
  spec (docs/spec/core/backend.md, "Asynchronous registration") confirms
  this is intended, not a bug in Bridge: "the binding is returned
  unbound (currentId == 0) — executeVia fails fast with handler not bound for any call made before onRegistered fires, so a caller using
  the async path must wait for registration (e.g. gate its UI on it) rather
  than fire an action immediately after constructing the handler." The
  spec's own queueing exception ("Queueing before the first connect") covers
  only the pre-connect window, not the post-connect,
  pre-registration-reply window this issue is about — so there is no
  framework-level queue this call site is failing to use.

• Not merely theoretical — corroborated by a sibling rung's own comment.
  examples/pastebin/gui/qml/Main.qml:46-56 gates its first dispatch on
  onBound with a comment stating this was "Verified, not theorised: an
  unconditional refresh() on completion reliably reported exactly that error
  and left the list empty on every launch against a real server." Same
  mechanism, same codebase, already reproduced once. I did not stand up a
  fresh Socket-mode repro myself (no GUI launch, per my constraints) — this
  existing evidence plus the fail-fast code path above is what moves this
  from "unverified" to "valid" rather than requiring a fresh repro.

Invariant applied

#6 — a guarantee reimplemented per call site belongs in one place — and
here it already does. Presenter::trackBound() /
Bridge::HandlerBinding::whenBound()
(examples/common/gui/presenter.hpp) is the existing shared primitive for
exactly this ordering problem, and it is already used by 12 presenters
across bookmarks (3 QML consumers), kanban's own BoardPresenter, ledger,
lims, and pastebin — including BoardPresenter itself. So this is not
a case needing a new framework primitive: the primitive exists, is already
wired on the C++ side for this exact presenter, and only the QML relay +
the navigation-ordering fix are missing. The corrected framing the issue
already anticipates in its own "what would change the verdict" section is
correct: the fix is "wait for binding at this call site" (restore
BoardBridge::bound's relay, and gate Main.qml's openBoard() +
stack.push(boardPage) on it, the way ProjectListView.qml/
pastebin/Main.qml already gate their own first dispatch) — not "the
framework should queue dispatch until bound," which the spec explicitly
scopes only to the pre-connect window and documents as a deliberate
caller responsibility otherwise.

Verdict

triage: valid. Problem is real (confirmed against current master,
post-#313), the fix direction the issue outlines is architecturally
correct (gate on the existing bound()/trackBound() primitive, fix
navigation order in Main.qml, restore the one-line relay in
BoardBridge), and no framework change is warranted. Labeling
area: ladder (the defect and its fix are entirely in the kanban rung's
QML/bridge wiring, not in morph/core) alongside the existing area: qt
and bug.

[Yaraslaut]

Re-triage: invalid — premise refuted with a reproduction, not just a re-read

The prior triage on this issue (comment above) was thorough but read-only by its own admission — "I did not stand up a fresh Socket-mode repro myself (no GUI launch, per my constraints)" — and moved this from unverified to valid on the strength of executeVia's documented fail-fast contract plus a sibling rung's comment. That reasoning misses that openBoard() never reaches executeVia's fail-fast path at all.

What actually happens

OpenBoard is payload-keyed: BRIDGE_MODEL_KEY(BoardModel, OpenBoard, &OpenBoard::projectId) (examples/kanban/gui_lib/board_model.hpp:436). BridgeHandler::execute() (include/morph/core/bridge.hpp:1954-2007) branches on that at compile time — a payload-keyed action never falls through to the plain _bridge.executeVia(...) call (:2043) the fail-fast "handler not bound" throw lives in. It instead goes through Bridge::attachHandlerAsync first, and the method's own doc comment is unambiguous about the contract this produces (:1948-1952):

"A payload- or result-keyed action's attach/promote step never throws out of this call, even when the backend refuses it (e.g. a remote server at LimitPolicy::maxLiveModels, a transport error, or an unauthorized attach) — the failure is instead delivered through the returned Completion's .onError(...), exactly like any other dispatch failure."

Concretely (:1996-2006): execute() calls attachHandlerAsync, and the actual dispatch (executeVia) runs from inside that attach's own completion callback — so by construction, the dispatch never runs until the attach has already resolved one way or the other. There is no window in which openBoard() can observe "handler not bound", in Local or Remote/Socket mode.

This async-attach mechanism (attachHandlerAsync) landed in #42, well before this issue's own baseline (master@9371c1a0) — it isn't a fix that shipped after the issue was filed, the guarantee already held when it was triaged.

Verified, not asserted

New test (fix/305-kanban-openboard-bind-race, PR #333) drives a real Mode::Socket client through FaultProxy, stalling the attach reply itself by 300ms via delayReply() — the most adversarial timing this rung's own transport can produce — then calls openBoard() the instant the presenter is constructed, exactly the ordering this issue describes as hazardous. Result: the board is reported correctly once the delayed reply lands; failed() never fires.

Filters: "*stalled Socket-mode attach*"
...
All tests passed (5 assertions in 1 test case)

Full kanban suite unaffected: All tests passed (1038 assertions in 136 test cases).

On the rest of the issue's argument

The observation that BoardBridge::bound is dead QML surface (nothing relays or consumes it) is still accurate, and #313's own comment there is honest about it being a deliberate, documented gap rather than an oversight. But the issue's reason for wanting it back — protecting openBoard() from a bind race — doesn't hold, and nothing else in this rung's shipped QML dispatches a non-keyed action (createColumn, getRules, etc.) on BoardView load or otherwise before a user has had a chance to interact with an already-open board, so there is no other call site this gap actually threatens today.

What would change the verdict

Re-open if a future call site dispatches a non-keyed BoardModel action (one that does not go through attachHandlerAsync) before openBoard()'s own attach has had a chance to settle — that path still fails fast on an unattached handler, and would need exactly the gate this issue proposed.

Verdict

triage: invalid. Closing with PR #333's regression test as the counter-evidence, superseding the triage: valid label.