[Yaraslaut]

Implements spec 8 in full. Actions declare what they change, and the server tells every GUI that shows that data. Documents now declare only what a screen shows and what an edit sends; nothing lists what to refresh after an action. An agent's tool calls run through the same path, so an open GUI updates when an agent changes something.

• Design: docs/superpowers/specs/2026-10-16-server-push-design.md.
• Plan: docs/superpowers/plans/2026-10-18-server-push.md, 30 tasks in 9 parts, all done.

What you write

From examples/bookmarks. The full guide is docs/KEEPING-SCREENS-CURRENT.md.

1. Records, once per result type, beside the DTO:

BRIDGE_REGISTER_RECORD(bookmarks::BookmarkSummary, "Bookmarks_Bookmark", ::morph::record::privateKeys)
BRIDGE_REGISTER_RECORD(bookmarks::BookmarkView, "Bookmarks_BookmarkDetail", ::morph::record::privateKeys)
BRIDGE_REGISTER_RECORD(bookmarks::TagSummary, "Bookmarks_Tag", ::morph::record::privateKeys)

2. Effects, beside each action that changes something:

// Renaming a tag renames it on every bookmark that carries it.
BRIDGE_REGISTER_ACTION(bookmarks::TagModel, bookmarks::RenameTag, "RenameTag")
BRIDGE_REGISTER_EFFECTS(bookmarks::RenameTag, ::morph::effects::changes<bookmarks::TagSummary>,
                        ::morph::effects::changes<bookmarks::BookmarkSummary>,
                        ::morph::effects::changes<bookmarks::BookmarkView>)

// The reply is the edited bookmark's full view, so an open detail view is patched in place.
BRIDGE_REGISTER_ACTION(bookmarks::BookmarkModel, bookmarks::EditBookmark, "EditBookmark")
BRIDGE_REGISTER_EFFECTS(bookmarks::EditBookmark, ::morph::effects::updates<bookmarks::BookmarkView>,
                        ::morph::effects::changes<bookmarks::BookmarkSummary>,
                        ::morph::effects::changes<bookmarks::TagSummary>)

// A read declares nothing; an action run as a mutation that changes nothing says so.
BRIDGE_REGISTER_EFFECTS(bookmarks::ExportBookmarks, ::morph::effects::none)

3. Screens that say only what they show and what they send:

auto const tagModel = screen.model<TagModel>("tagModel", {.instance = ui::Instance::Private});
auto const tags = screen.query<ListTags>("tags", tagModel, {});
auto const picked = ui::element("tagList");
return ui::row({
    ui::table(tags.value().at(&ListTagsResult::tags), {.key = ui::row("id"), /* columns */}).id(picked),
    ui::form<RenameTag>(tagModel, {.prefill = ui::obj({{"id", ui::call("first", {picked.selection()})}}),
                                   .fields = {{&RenameTag::id, {.hidden = true}}}}),
});

When the rename succeeds, this table and every other screen holding tags, bookmark rows or a bookmark's detail
refresh, on every connected client, and the same happens when an agent renames the tag over MCP.

What goes away from screens (bookmarks on master, then on this branch):

// master
auto const archive = screen.mutation<BulkEdit>("archive", marks, {.invalidates = {bookmarks, tags}});
auto const remove = screen.mutation<DeleteBookmark>("remove", marks,
    {.body = {{&DeleteBookmark::id, editing}}, .invalidates = {bookmarks, tags}, .onSuccess = {ui::close(edit)}});
auto const refreshed = ui::Commands{ui::refetch(bookmarks), ui::refetch(tags)};  // passed to every form's onSuccess

// this branch
auto const archive = screen.mutation<BulkEdit>("archive", marks);
auto const remove = screen.mutation<DeleteBookmark>(
    "remove", marks, {.body = {{&DeleteBookmark::id, editing}}, .onSuccess = {ui::close(edit)}});

The action…	Declare
changes rows of R, and its reply holds them with their keys	updates<R>: the caller's screens show the reply's rows at once; watching clients refetch the entries holding those keys
changes rows of R, but its reply does not hold them (delete, bulk edit, import)	changes<R>: every entry holding R refetches
changes the state of the instance it ran on	changesInstance
changes nothing, but runs as a mutation	none
only reads	nothing

ui::refetch(q) stays for a refresh no action can declare, and .refreshEvery for data that changes with time.

What it does

Records and effects (core)

• BRIDGE_REGISTER_RECORD names a result type with a key (key<&T::m>, keyless, derivedFrom<…>, privateKeys).
• BRIDGE_REGISTER_EFFECTS declares updates<R>, changes<R>, changesInstance or none. Each action's registration records where its result holds which record types.
• Records and effects are matched and validated on the first registry read. A bad declaration fails at server construction with EffectsRegistrationError. This includes a derivedFrom source that is not a registered record, which would otherwise never refresh the record derived from it.
• deriveChanges computes the changes an execute made. Past kMaxChangeKeys keys, a change becomes a whole-type change.

The server-to-client channel

• An event envelope (changes, resync), which clients route before matching replies.
• RemoteServer writes to a connection through setConnectionWriter, post and connectionDrained.
• Events are held back above a 1 MiB backlog, and one resync follows the drain. Replies are never held.
• Both transports count each connection's backlog; over TLS, Qt counts the encrypted bytes. Qt gains sendTimeout.

Watching and fan-out

• watch and unwatch are core kinds. Admission is per principal and token, an instance watch also needs authorizeInstance, and a connection may watch at most 4096 topics.
• A successful execute fans out to every watching connection, the caller included. Each watch is re-authorised when an event is sent, and privateKeys records lose their keys for any other principal.
• A change of principal drops the connection's watches, and any dropped watch is owed a resync.
• Changes are coalesced per connection for 50 ms or 256 keys.

The client cache

• Every reply applies its action's effects through Session::actionSucceeded. This covers mutations and the submits of forms, collections and wizards.
  • updates R patches rows by the record's key field, at the catalog's paths, with no fetch.
  • changes R and changesInstance mark the entries that hold the record, or that were read through the instance.
  • A discarded latest reply only marks.
• A mark made while a fetch is in flight is kept (refetchAfter): that entry fetches once more, so no change is lost.
• Session::deliverEvent applies changes events, filtered by the event's keys, and answers resync.
• The session counts the topics its cache holds and watches them before it fetches, through SessionOptions::watcher, built with watcherOver. Session::reconnected(), and every resync, re-send the whole watch set with replace and mark every entry stale.
• AppSource::onConnected is a new seam. On every reconnect, the generic client re-sends ui-hello, re-watches, and forwards events.
• The catalog lists a record derived from a changed one as changes too, so the caller's own reply marks it in process as well as remotely.

Documents

• A query whose action declares effects is refused: a query must read.
• invalidates, patch and refreshOn are refused: an action's effects say what it changes, once, for every client. optimistic, refreshEvery and the refetch command stay.
• Two warnings, which never refuse a document: a mutation that declares nothing and refreshes nothing; a watch of a query that runs a mutation with effects.
• The explorer shows each action's effects, and the records its result holds, each with its key field and paths.

The example rungs. Bookmarks, bank and lims declare records and effects beside their actions. Their screens declare no refreshes, and each rung's bundle loads without refusals or warnings.

Documentation

• docs/KEEPING-SCREENS-CURRENT.md, a new guide for developers and coding agents: what to write, choosing an effect, what refreshes when, a checklist for a new action, every error and warning with its fix, testing, and agents over MCP.
• GETTING-STARTED.md, ARCHITECTURE.md, the README, examples/IMPLEMENTATION.md and AGENTS.md point to it and no longer show refresh keys or say morph has no server push.

The MCP adapter

• ui::McpAdapter speaks MCP's JSON-RPC 2.0 over an ordinary server connection, with one tool per permitted action and an evaluate dry run.
• serveStdio drives it over MCP's stdio transport.
• Bank's server serves it with --mcp-stdio, beside its WebSocket clients, and now also serves bank's screens through a UiService.

Changes from the plan

• serveStdio takes the adapter's owner, a MainThreadExecutor, and pumps it while it waits. McpOptions gains callbacks, the serial owner the adapter's completions are delivered on.
• A reply's effects are applied from the reply's value. applyChanges(ChangesBody) serves events only, because a patch needs rows, and a ChangesBody carries only keys.
• Watch changes go out at each fetch, not once per reactive batch, because the runtime has no end-of-batch hook. Each fetch is still preceded by its watch.
• One vocabulary. The plan's ui/2 is folded into ui/1: the refresh keys are refused there instead of in a second vocabulary, so there is no per-client choice of documents. Spec 5 §12 says a key leaves a vocabulary by being refused, never ignored.
• The --mcp-stdio identity comes from MORPH_MCP_PRINCIPAL, because bank's demo authorizer vouches for a principal and has no token. MORPH_MCP_TOKEN is carried as the token.

Verification

Measured on Linux (Arch), clang 23, Debug, with net, Qt, the ladder and bank on, at 40740124; the later commits re-ran the full suite (all pass), Doxygen (clean), and a local branch-coverage run of include/morph/core (94.15% against the 94% floor, without the examples):

• Full build: OK.

• ctest: 4014 of 4016 pass. The two failures were timeouts under -j6 on a loaded disk. Both pass alone: ListBookmarks … nextCursor in 0.14 s, and App teardown survives fetch dispatches still outstanding in about 90 s. On master's own build that test takes 81 s on the same disk, so the load is the machine's, not the branch's.

• Doxygen (WARN_AS_ERROR): no warnings.

• GCC: every non-Qt translation unit under examples/, src/ and tests/ (378) compiles with GCC and CI's gcc-release flags. With a fix undone, the check flags the error.

• Mutation checks: each new behaviour's tests were run with the behaviour broken and fail as they should, including:

  • the cache's patch, mark, event and resync paths;
  • watch-before-fetch;
  • the reconnect order;
  • the document checks;
  • the refresh keys' refusals;
  • the explorer rows;
  • the adapter's tool list;
  • the derived-record expansion;
  • the adapter's keyed path, and the watch table's per-session drop.

  The net backlog test fails without the hold-back. The two-client test over net fails with B's events dropped.

CI on 40740124 was green on every build and test job, Windows cl and clang-cl and the sanitizers included. The exceptions were clang-tidy-diff and the coverage gate (core's branch coverage under its floor), both fixed in the commits after it.

Not verified locally:

• clang-tidy at CI's version (fixed from CI's logs);
• macOS on this round;
• MORPH_CLIENT_ONLY, beyond its guard probes in the normal build.

Known limitations

• An updates effect cannot express a patch whose reply replaces its row under a new key. Lims's re-capture declares changes and refetches.
• From the review of Parts 1–4, still open:
  • If Qt's TLS socket cannot be found, the connection fails open (no hold-back, no sendTimeout).
  • The unscoped ui-hello answers events: true.
  • The admission cache keeps policy changes for a live token until that token stops verifying.
  • A keyed row that lacks its key member is skipped in deriveChanges.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A4hwcANrTbPYnqmWX4iyMZ

[codecov]

Codecov Report

❌ Patch coverage is 88.32117% with 272 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
include/morph/ui/interpreter.hpp	79.42%	23 Missing and 34 partials ⚠️
include/morph/ui/agent.hpp	84.85%	17 Missing and 26 partials ⚠️
include/morph/core/remote.hpp	92.42%	12 Missing and 18 partials ⚠️
include/morph/ui/document.hpp	83.57%	7 Missing and 16 partials ⚠️
examples/common/app/tests/test_sources.cpp	81.63%	0 Missing and 18 partials ⚠️
include/morph/core/wire.hpp	77.14%	8 Missing and 8 partials ⚠️
examples/common/testkit/bundle_warnings.hpp	56.66%	5 Missing and 8 partials ⚠️
include/morph/core/records.hpp	84.72%	6 Missing and 5 partials ⚠️
examples/common/app/app_source.cpp	80.00%	3 Missing and 6 partials ⚠️
include/morph/core/backend.hpp	63.63%	7 Missing and 1 partial ⚠️
... and 14 more

📢 Thoughts on this report? Let us know!

[Copilot]

🟡 Changes recommended

Reconnect ordering, oversized-event handling, and the bank screens dependency leave unresolved correctness and build failures.

3 open issues

• Build bank_screens independently of generic examples · New
• Bound coalesced event size and preserve oversized invalidations · New
• Notify reconnect listeners only after rebinding begins · New

What changed in this PR

Adds action-driven server push so GUI caches refresh when another client or agent changes data, replacing per-screen refresh declarations.

Changes:

• Adds event delivery, connection backlog tracking, watches, and reconnect integration.
• Migrates authored screens to ui/2 with record and effect declarations.
• Adds bank MCP serving, regression coverage, and supporting documentation.

File	Description
tests/​ui/​golden/​results.json	Updates vocabulary golden.
tests/​ui/​golden/​palette.json	Updates vocabulary golden.
tests/​ui/​golden/​declarations.json	Removes obsolete refresh declarations.
tests/​ui/​golden/​commands.json	Updates vocabulary golden.
tests/​ui/​corpus/​documents.json	Covers ui/2 validation.
tests/​ui_interpreter_support.hpp	Adds effect and watch fixtures.
tests/​test_ui_explorer.cpp	Tests effect display.
tests/​test_ui_author.cpp	Migrates authoring tests.
tests/​test_remote_envelope_service.cpp	Tests connection facts and compatibility.
tests/​test_push_watch_table.cpp	Tests watch isolation and limits.
tests/​table/​test_table_view_change.cpp	Uses portable std::iota.
tests/​table/​test_table_sort.cpp	Uses portable std::iota.
tests/​table/​test_table_filter.cpp	Uses portable std::iota.
tests/​push_records_late.hpp	Defines late-registration fixtures.
tests/​push_records_late.cpp	Registers late fixture records.
tests/​net/​test_socket_backend.cpp	Exposes service overloads.
tests/​net/​CMakeLists.txt	Registers network push tests.
tests/​compile_checks/​effects_unseen_shared.hpp	Defines cross-unit fixtures.
tests/​compile_checks/​effects_unseen_b.cpp	Reads effects without registration visibility.
tests/​compile_checks/​effects_unseen_a.cpp	Checks shared effect registration.
tests/​CMakeLists.txt	Registers push tests and probes.
src/​qt/​qt_websocket_backend.cpp	Routes events before replies.
scripts/​check_coverage_objects.sh	Excludes the link probe.
scripts/​branch_partial_allowlist.json	Updates coverage locations.
include/​morph/​ui/​service.hpp	Negotiates events and bundle vocabularies.
include/​morph/​ui/​service_client.hpp	Adds remote watcher construction.
include/​morph/​ui/​frontend.hpp	Adds connection listeners.
include/​morph/​ui/​explorer.hpp	Displays effects and records.
include/​morph/​ui/​bundle.hpp	Adds event negotiation fields.
include/​morph/​qt/​qt_websocket_server.hpp	Declares backlog and timeout support.
include/​morph/​qt/​qt_websocket_backend.hpp	Declares event handlers.
include/​morph/​qt/​detail/​outbound_ledger.hpp	Tracks unwritten frames.
include/​morph/​net/​socket_server.hpp	Installs connection writers.
include/​morph/​net/​socket_backend.hpp	Adds connect and event callbacks.
include/​morph/​net/​detail/​ws_connection.hpp	Accounts for outbound backlog.
include/​morph/​core/​observability.hpp	Adds oversized-event metric.
include/​morph/​core/​detail/​reply_router.hpp	Separates events from replies.
include/​morph/​core/​detail/​change_coalescer.hpp	Merges pending changes.
include/​morph/​core/​connection_writer.hpp	Defines writers and backlog thresholds.
include/​morph/​core/​change_types.hpp	Defines change payloads.
include/​morph/​core/​backend.hpp	Adds backend event hooks.
examples/​lims/​screens/​tests/​test_lims_screens.cpp	Tests effect-driven screen updates.
examples/​lims/​screens/​lims_screens.cpp	Removes explicit refresh declarations.
examples/​lims/​README.md	Documents effect-driven updates.
examples/​lims/​include/​lims/​models/​sample_model.hpp	Declares sample action effects.
examples/​lims/​include/​lims/​models/​auth_model.hpp	Declares login effects.
examples/​lims/​include/​lims/​models/​analysis_catalog_model.hpp	Declares analysis effects.
examples/​lims/​include/​lims/​dto/​verification_dto.hpp	Registers verification records.
examples/​lims/​include/​lims/​dto/​sample_dto.hpp	Registers sample records.
examples/​lims/​include/​lims/​dto/​result_dto.hpp	Registers result records.
examples/​lims/​include/​lims/​dto/​offline_dto.hpp	Registers conflict records.
examples/​lims/​include/​lims/​dto/​analysis_dto.hpp	Registers analysis records.
examples/​common/​testkit/​bundle_warnings.hpp	Checks bundle validation warnings.
examples/​common/​app/​tests/​test_sources.cpp	Tests reconnect and event forwarding.
examples/​common/​app/​client_shell.cpp	Connects sessions to push notifications.
examples/​common/​app/​app_source.hpp	Declares watcher and listener interfaces.
examples/​common/​app/​app_source.cpp	Implements negotiation and reconnect notifications.
examples/​bookmarks/​screens/​tests/​test_bookmarks_screens.cpp	Checks warning-free bundles.
examples/​bookmarks/​screens/​bookmarks_screens.cpp	Removes explicit refresh declarations.
examples/​bookmarks/​README.md	Documents action effects.
examples/​bookmarks/​include/​bookmarks/​models/​tag_model.hpp	Declares tag effects.
examples/​bookmarks/​include/​bookmarks/​models/​bookmark_model.hpp	Declares bookmark effects.
examples/​bookmarks/​include/​bookmarks/​models/​auth_model.hpp	Declares login effects.
examples/​bookmarks/​include/​bookmarks/​dto/​tag_dto.hpp	Registers private-key tag records.
examples/​bookmarks/​include/​bookmarks/​dto/​bookmark_dto.hpp	Registers private-key bookmark records.
examples/​bank/​tests/​test_mcp_stdio.cpp	Tests MCP stdio responses.
examples/​bank/​src/​server/​main.cpp	Serves screens and MCP tools.
examples/​bank/​screens/​tests/​test_bank_screens.cpp	Checks warning-free bundles.
examples/​bank/​screens/​bank_screens.cpp	Removes explicit refresh declarations.
examples/​bank/​README.md	Documents MCP and action effects.
examples/​bank/​memory/​include/​bank/​models/​transaction_model.hpp	Declares in-memory transaction effects.
examples/​bank/​memory/​include/​bank/​models/​payment_model.hpp	Declares in-memory payment effects.
examples/​bank/​memory/​include/​bank/​models/​payee_model.hpp	Declares in-memory payee effects.
examples/​bank/​memory/​include/​bank/​models/​loan_model.hpp	Declares in-memory loan effects.
examples/​bank/​memory/​include/​bank/​models/​customer_model.hpp	Declares in-memory account-creation effects.
examples/​bank/​memory/​include/​bank/​models/​card_model.hpp	Declares in-memory card effects.
examples/​bank/​memory/​include/​bank/​models/​auth_model.hpp	Declares in-memory authentication effects.
examples/​bank/​memory/​include/​bank/​models/​account_model.hpp	Declares in-memory account effects.
examples/​bank/​include/​bank/​models/​transaction_model.hpp	Declares transaction effects.
examples/​bank/​include/​bank/​models/​payment_model.hpp	Declares payment effects.
examples/​bank/​include/​bank/​models/​payee_model.hpp	Declares payee effects.
examples/​bank/​include/​bank/​models/​notification_model.hpp	Declares notification effects.
examples/​bank/​include/​bank/​models/​loan_model.hpp	Declares loan effects.
examples/​bank/​include/​bank/​models/​customer_model.hpp	Declares account-creation effects.
examples/​bank/​include/​bank/​models/​card_model.hpp	Declares card effects.
examples/​bank/​include/​bank/​models/​budget_model.hpp	Declares budget effects.
examples/​bank/​include/​bank/​models/​auth_model.hpp	Declares authentication effects.
examples/​bank/​include/​bank/​models/​account_model.hpp	Declares account effects.
examples/​bank/​include/​bank/​dto/​transaction_dto.hpp	Registers transaction records.
examples/​bank/​include/​bank/​dto/​payment_dto.hpp	Registers payment records.
examples/​bank/​include/​bank/​dto/​payee_dto.hpp	Registers payee records.
examples/​bank/​include/​bank/​dto/​notification_dto.hpp	Registers notification records.
examples/​bank/​include/​bank/​dto/​loan_dto.hpp	Registers loan records.
examples/​bank/​include/​bank/​dto/​card_dto.hpp	Registers card records.
examples/​bank/​include/​bank/​dto/​budget_dto.hpp	Registers budgets and derived reports.
examples/​bank/​include/​bank/​dto/​account_dto.hpp	Registers account records.
examples/​bank/​CMakeLists.txt	Links screens and adds MCP tests.
docs/​superpowers/​specs/​2026-10-08-app-hosting-design.md	Updates push protocol description.
docs/​superpowers/​specs/​2026-10-07-ui-document-design.md	Documents ui/2 semantics.
docs/​spec/​ui/​service.md	Documents negotiation and watchers.
docs/​spec/​ui/​interpreter.md	Documents cache effects and resynchronization.
docs/​spec/​ui/​frontend.md	Documents reconnect integration.
docs/​spec/​ui/​explorer.md	Documents effect display.
docs/​spec/​ui/​author.md	Documents revised authoring API.
docs/​spec/​ui/​agent.md	Specifies MCP adapter behavior.
docs/​spec/​testing_strategy.md	Documents bundle warning checks.
docs/​spec/​offline/​offline.md	Explains replay-driven cache updates.
docs/​spec/​core/​wire.md	Specifies event and watch messages.
docs/​spec/​core/​shared_instances.md	Documents keyed-instance watches.
docs/​spec/​core/​observability.md	Documents oversized-event metric.
CMakeLists.txt	Exports new push and agent headers.

_{Review effort: Balanced}