Server push (spec 8): actions declare what they change, the server tells every GUI

AGENTS.md

@@ -137,6 +137,12 @@ So, before claiming something works:
 State results as measured or as inferred, and never round the second up to the
 first.
 
+## Adding or changing an action
+
+An action that changes data declares what it changes (`BRIDGE_REGISTER_EFFECTS`, beside its
+`BRIDGE_REGISTER_ACTION`), and screens never say what to refresh. Work through the checklist in
+[`docs/KEEPING-SCREENS-CURRENT.md`](docs/KEEPING-SCREENS-CURRENT.md) for every new or changed action.
+
 ## Design specs (`docs/spec/`)
 
 One file per public type or subsystem. There is **no size limit** on spec

CMakeLists.txt

@@ -453,8 +453,13 @@ target_sources(morph
         include/morph/core/timeout_scheduler.hpp
         include/morph/core/model.hpp
         include/morph/core/registry.hpp
+        include/morph/core/records.hpp
+        include/morph/core/effects.hpp
+        include/morph/core/change_types.hpp
+        include/morph/core/changes.hpp
         include/morph/core/backend.hpp
         include/morph/core/envelope_transport.hpp
+        include/morph/core/connection_writer.hpp
         include/morph/core/remote.hpp
         include/morph/core/bridge.hpp
         include/morph/core/wire.hpp
@@ -510,6 +515,7 @@ target_sources(morph
         include/morph/ui/service_client.hpp
         include/morph/ui/shell_frame.hpp
         include/morph/ui/explorer.hpp
+        include/morph/ui/agent.hpp
         include/morph/ui/preferences.hpp
         include/morph/ui/preference_sync.hpp
         include/morph/ui/host_vocabulary.hpp
@@ -601,6 +607,9 @@ target_sources(morph
         include/morph/core/detail/owner_probe.hpp
         include/morph/core/detail/reply_router.hpp
         include/morph/core/detail/subscription_registry.hpp
+        include/morph/core/detail/result_walker.hpp
+        include/morph/core/detail/watch_table.hpp
+        include/morph/core/detail/change_coalescer.hpp
         include/morph/forms/detail/session_common.hpp
         include/morph/forms/detail/schema_name.hpp
         include/morph/forms/engine/detail/text.hpp
@@ -1041,6 +1050,7 @@ if(MORPH_BUILD_QT)
             include/morph/qt/qt_tls.hpp
             include/morph/qt/qt_websocket_server.hpp
             include/morph/qt/qt_websocket_backend.hpp
+            include/morph/qt/detail/outbound_ledger.hpp
     )
 
     # Compiled implementation (QObject subclass needs MOC via a .cpp file)
@@ -1154,6 +1164,10 @@ if(MORPH_BUILD_EXAMPLES)
     if(MORPH_BUILD_QT_QUICK OR MORPH_BUILD_TUI)
         add_subdirectory(examples/client)
     endif()
+elseif(TARGET ladder_bank_server)
+    # The bank server serves bank's screens, so it needs them without the generic examples; their tests, which use
+    # the generic app, are built only with them.
+    add_subdirectory(examples/bank/screens)
 endif()
 
 # ── Documentation ───────────────────────────────────────────────────────────

README.md

@@ -530,9 +530,10 @@ in [`docs/spec/`](docs/spec) before relying on any of these in production:
 - **`Completion<T>` is a leaf callback primitive**, not a composable future: one
   handler per outcome, no `T→U` chaining, no `co_await`, no cancellation.
 - **Instance subscriptions are best-effort and in-process.** `subscribe<R>`
-  fans out to handlers on the same `Bridge`; there is no server-initiated push,
-  so two separate clients sharing an instance do not see each other's results
-  until they ask again. No replay, no durability, no coalescing.
+  fans out to handlers on the same `Bridge`, with no replay and no durability.
+  Across clients, screens stay current through declared effects, which tell
+  every watching connection what changed but not the new values
+  ([`docs/KEEPING-SCREENS-CURRENT.md`](docs/KEEPING-SCREENS-CURRENT.md)).
 - **Exact numbers are fixed-width.** `Rational` is an `int64` pair; `+`/`-`/`*`
   *saturate* at `±INT64_MAX/1` and log at `error` rather than returning an error
   value, so an out-of-envelope result is clamped and inexact rather than exact —
@@ -561,7 +562,10 @@ in [`docs/spec/`](docs/spec) before relying on any of these in production:
 
 - [`docs/GETTING-STARTED.md`](docs/GETTING-STARTED.md) — the step-by-step
   tutorial: build one small app end to end and understand why each piece
-  exists. Read this before the two below.
+  exists. Read this before the others below.
+- [`docs/KEEPING-SCREENS-CURRENT.md`](docs/KEEPING-SCREENS-CURRENT.md) — how
+  screens refresh after an action, on every client and for AI agents: records,
+  effects, the checklist for a new action, and every error with its fix.
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — namespace map, layer diagram,
   wire protocol, deployment topologies, and design rationale.
 - [`docs/spec/`](docs/spec) — the authoritative per-type/subsystem design specs.

docs/ARCHITECTURE.md

@@ -39,7 +39,9 @@ The public surface is split per topic so callers always know whether a name is p
 | `morph::log` | Configurable logging | `LogLevel`, `setLogger`, `setLogLevel`, `getLogLevel`, `logDebug`, `logInfo`, `logWarn`, `logError` |
 | `morph::exec` | Executor primitives | `IExecutor`, `ThreadPoolExecutor`, `MainThreadExecutor` |
 | `morph::async` | Async result handle | `Completion<T>` |
-| `morph::model` | Model & action traits | `ModelTraits<>`, `ActionTraits<>`, `ActionValidator<>`, `ActionLogPolicy<>`, `Loggable` |
+| `morph::model` | Model & action traits | `ModelTraits<>`, `ActionTraits<>`, `ActionValidator<>`, `ActionLogPolicy<>`, `Loggable`, `EffectsRegistrationError` |
+| `morph::record` | Result types that are shared data (see `docs/KEEPING-SCREENS-CURRENT.md`) | `BRIDGE_REGISTER_RECORD`, `key<&T::m>`, `keyless`, `derivedFrom<S...>`, `privateKeys`, `RecordInfo` |
+| `morph::effects` | What an action changes, and the changes an execute made | `BRIDGE_REGISTER_EFFECTS`, `updates<R>`, `changes<R>`, `changesInstance`, `none`, `Effect`, `ActionRecord`, `effectsOf`, `recordsOf`, `recordNamed`, `actionsHolding`, `deriveChanges`, `Changes`, `kMaxChangeKeys` |
 | `morph::backend` | Pluggable backends | `LocalBackend`, `RemoteServer`, `SimulatedRemoteBackend` |
 | `morph::bridge` | Bridge between handler and backend | `Bridge`, `BridgeHandler<M>` |
 | `morph::offline` | Connectivity + replay | `NetworkMonitor`, `NetworkMonitorConfig`, `IOfflineQueue`, `QueueItem`, `OfflineQueueFullError`, `InMemoryOfflineQueue`, `FileOfflineQueue`, `FileOfflineQueueError`, `SqliteOfflineQueue`, `SqliteOfflineQueueError`, `SyncWorker` (incl. `DeadLetterSink`), `SyncResult`, `ReconnectCoordinator`, `ReconnectOutcome`, `ReconnectCoordinatorConfig` |
@@ -420,6 +422,14 @@ struct MyModel {
 
 BRIDGE_REGISTER_MODEL (MyModel,  "MyModel")
 BRIDGE_REGISTER_ACTION(MyModel, MyAction, "MyAction")
+```
+
+   An action that changes data also says what it changes, so every screen showing it refreshes
+   (`docs/KEEPING-SCREENS-CURRENT.md`):
+
+```cpp
+BRIDGE_REGISTER_RECORD(MyRow, "MyRow")                                    // a result type that is shared data
+BRIDGE_REGISTER_EFFECTS(MyAction, ::morph::effects::changes<MyRow>)       // beside the action's registration
 ```
 
 3. Use from the GUI (same code for local and remote):
@@ -514,6 +524,26 @@ sidebar.execute(Deposit{.amountMinor = 5000});
 | **Callback thread** | Always the executor passed at handler construction. |
 
 
+## Keeping screens current across clients
+
+`subscribe<R>` reaches handlers on one `Bridge`. What keeps every client's screens current, and an agent's changes
+visible to them, is declared effects:
+
+- `BRIDGE_REGISTER_RECORD` names a result type that is shared data, with its key.
+- `BRIDGE_REGISTER_EFFECTS`, beside an action's registration, says which records it changes (`updates<R>` when the
+  reply carries the changed rows, `changes<R>` when it does not, `changesInstance`, or `none`).
+- After a successful execute, `RemoteServer` derives the changes from the effects and the result, and sends an
+  `event` to every connection watching a changed record, after re-authorising each watch. A UI client watches the
+  records its query cache holds, before it fetches them, and applies a change by patching or refetching the entries
+  that hold the record. The caller applies its own reply's effects at once.
+- Screens declare no refreshes: a document naming `invalidates`, `patch` or `refreshOn` is refused, and so is a query
+  whose action declares effects.
+- `morph::ui::McpAdapter` (`ui/agent.hpp`) lets an AI agent drive the same server over MCP, as one more connection.
+
+The user guide is [`KEEPING-SCREENS-CURRENT.md`](KEEPING-SCREENS-CURRENT.md); the rules are in
+`docs/spec/core/registry.md` ("Effects"), `docs/spec/core/backend.md` ("Fan-out"), `docs/spec/ui/interpreter.md` and
+`docs/spec/ui/document.md`.
+
 ## Exact values, units, and schema-driven forms
 
 Three headers extend actions from "any aggregate" to *self-describing*
@@ -657,6 +687,10 @@ folder.
 | `core/completion.hpp` | `CompletionState<T>` (detail) + `Completion<T>` (public) — result handle |
 | `core/model.hpp` | `IModelHolder`, `ModelHolder<T>`, `ModelFactory`, `IBackendChangedSink`, `BackendChangedNotifiable` — type-erased model storage; `IModelHolder::attachActionLog`/`hasActionLog`/`recordIfAttached` (`morph::model::detail::`) |
 | `core/registry.hpp` | `ModelTraits<>`, `ActionTraits<>`, `ActionValidator<>`, `ActionLogPolicy<>`, `Loggable` (public) + `ActionDispatcher` (also tracking each action's `coalesce` policy), `ModelRegistryFactory`, `defaultDispatcher()`, `defaultRegistry()`, `ParseError`, `registerModelOnce`, `registerActionOnce`, `actionLoggable<A>()` (detail). Registration macros `BRIDGE_REGISTER_MODEL`, `BRIDGE_REGISTER_ACTION` (optional 4th `Loggable` argument), `BRIDGE_REGISTER_VALIDATOR` are defined here at file scope. |
+| `core/records.hpp` | `BRIDGE_REGISTER_RECORD` and its options `key<&T::m>`, `keyless`, `derivedFrom<S...>`, `privateKeys`; `RecordInfo` (`morph::record::`) — result types that are shared data. See `docs/spec/core/registry.md`, "Record registry". |
+| `core/effects.hpp` | `BRIDGE_REGISTER_EFFECTS` and `updates<R>`, `changes<R>`, `changesInstance`, `none`; `Effect`, `ActionRecord`, `effectsOf`, `recordsOf`, `recordNamed`, `actionsHolding` (`morph::effects::`); `EffectsRegistrationError` (`morph::model::`) — what each action changes, matched with the records its result holds and validated on the first read. See `docs/spec/core/registry.md`, "Effects". |
+| `core/changes.hpp`, `core/change_types.hpp` | `deriveChanges`, `Changes`, `RecordChange`, `InstanceChange`, `kMaxChangeKeys` (`morph::effects::`) — the changes a successful execute made. |
+| `core/connection_writer.hpp` | `ConnectionWriter`, `kEventBacklogHigh`, `kEventBacklogLow` (`morph::backend::`) — how `RemoteServer` writes events to a connection, and the backlog above which it holds them back. |
 | `core/backend.hpp` | `LocalBackend` (public) + `ActionCall`, `IBackend` (detail), including the non-breaking `registerModelWithContext()` default method |
 | `core/remote.hpp` | `RemoteServer` (configured by `ServerConfig`, incl. `logProvider`), `SimulatedRemoteBackend` (`morph::backend::`) |
 | `core/bridge.hpp` | `Bridge`, `BridgeHandler<M>` (public) + `HandlerBinding` (carrying `contextKey`), `MemberPointerTraits` (detail) |
@@ -736,6 +770,7 @@ folder.
 | `ui/expression.hpp` | `Expr`, `ExprKind`, `FunctionId`, `parseExpression`, `NameResolver`, `PermissiveResolver`, `checkExpression`, `Environment`, `StaticEnvironment`, `FormatContext`, `UnitTable`, `UnitInfo`, `evaluate`, `walk`, `isName`, `functionNames` — the `expr/1` language. See `docs/spec/ui/expressions.md`. |
 | `ui/document.hpp` | `Document`, `ScopeDecl` and the declaration structs, `Command`, `CommandKind`, `DocNode`, `Component`, `CustomizePoint`, `Catalog`, `ModelInfo`, `ActionInfo`, `LoadOptions`, `loadDocument`, `loadDocumentText`, `nodeKinds` — the document model and its load-time validation. See `docs/spec/ui/document.md`. |
 | `ui/interpreter.hpp` | `Interpreter`, `Screen`, `Session`, `SessionOptions`, `Dispatcher`, `ModelChannel`, `CallOptions`, `BridgeDispatcher`, `InterpreterHost`, `NavigateRequest`, `InterpreterOptions`, `MountOptions`, `BorrowedModel` (`morph::ui::`) — mounts a loaded document: scopes, the session's query cache, mutations, relations and commands, lowered to the view tree. See `docs/spec/ui/interpreter.md`. |
+| `ui/agent.hpp` | `McpAdapter`, `McpOptions`, `serveStdio` and the JSON-RPC error codes (`morph::ui::`) — an AI agent over MCP, as one more connection to the server. See `docs/spec/ui/agent.md`. |
 | `ui/author.hpp` | `Handle`, `AnyHandle`, `Body`, `ModelHandle`, `QueryHandle`, `MutationHandle`, `DeclScope`, `Scope`, `Command`, `Commands`, `Node`, `Nodes`, a builder per node kind and command, `Screen`, `screen`, `ScreenRegistry`, `screenRegistry`, `CatalogFacts`, `ModelFacts`, `ActionFacts`, `checkAccessibility`, `MORPH_REGISTER_SCREEN` (`morph::ui::author::`) — server-side authoring: typed builders that write a screen's document, and its registration with the load-time and accessibility rules. See `docs/spec/ui/author.md`. |
 | `ui/view.hpp` | `Node`, `NodeData`, `Prop<T>`, `SlotId`, `SlotBinding`, `slot()`, `Key`, `Common`, `Accessibility`, `KeyBinding`, `FieldState`, `MenuItem`, `Sizing`, `LayoutHints`, every node kind and its builder, `switchOn`, `forEach`, `table` (`morph::ui::`) — the immutable view tree whose properties are constants or slots. See `docs/spec/ui/view_tree.md`. |
 | `ui/backend.hpp` | `Widget`, `ContainerWidget`, `FieldWidget`, one widget interface per kind, `MenuEntry`, `IViewBackend` — the retained widgets a renderer implements. See `docs/spec/ui/backend_contract.md`. |

docs/GETTING-STARTED.md

@@ -638,10 +638,10 @@ abridged):
 auto const marks = screen.model<BookmarkModel>("marks", {.instance = ui::Instance::Private});
 auto const list = ui::element("list");
 auto const bookmarks = screen.query<ListBookmarks>("bookmarks", marks, {});
-auto const archive = screen.mutation<BulkEdit>("archive", marks, {.invalidates = {bookmarks, tags}});
+auto const archive = screen.mutation<BulkEdit>("archive", marks);
 auto const rows = bookmarks.value().at(&ListBookmarksResult::bookmarks);
 return ui::column({
-    ui::form<CreateBookmark>(marks, {.onSuccess = refreshed}).id(ui::element("createForm")).testId("createForm"),
+    ui::form<CreateBookmark>(marks).id(ui::element("createForm")).testId("createForm"),
     ui::table(rows, {.key = ui::row("id"), /* title and URL columns */, .selection = ui::Selection::Multiple})
         .id(list).testId("bookmarks"),
     ui::button({.label = "Archive selected",
@@ -652,8 +652,9 @@ return ui::column({
 ```
 
 The screen decides nothing about the domain. It names the model, the query
-that lists bookmarks, the mutation, and when the list refetches; every rule
-about what a bookmark may be stays in `BookmarkModel`. Archiving a selection is
+that lists bookmarks and the mutation; every rule about what a bookmark may be
+stays in `BookmarkModel`, and nothing on the screen says when the list
+refetches. Archiving a selection is
 one `BulkEdit` built from the table's own selection, so it is one transaction
 in the model however many rows are selected.
 
@@ -676,6 +677,32 @@ REQUIRE(harness.submitForm("createForm"));
 REQUIRE(harness.waitForText("count", "1 bookmarks"));
 ```
 
+### What refreshes after an action
+
+The action says what it changes, beside its registration, and every screen
+showing that data refreshes: on this client, on every other connected client,
+and when an AI agent runs the action over MCP. Two declarations do it
+([`models/bookmark_model.hpp`](../examples/bookmarks/include/bookmarks/models/bookmark_model.hpp),
+[`dto/bookmark_dto.hpp`](../examples/bookmarks/include/bookmarks/dto/bookmark_dto.hpp)):
+
+```cpp
+// A result type that is shared data, keyed by its `id` member
+BRIDGE_REGISTER_RECORD(bookmarks::BookmarkSummary, "Bookmarks_Bookmark", ::morph::record::privateKeys)
+
+// What the action changes: archiving moves bookmarks between lists, and changes the tag counts
+BRIDGE_REGISTER_ACTION(bookmarks::BookmarkModel, bookmarks::BulkEdit, "BulkEdit", ::morph::model::Loggable::No)
+BRIDGE_REGISTER_EFFECTS(bookmarks::BulkEdit, ::morph::effects::changes<bookmarks::BookmarkSummary>,
+                        ::morph::effects::changes<bookmarks::BookmarkView>,
+                        ::morph::effects::changes<bookmarks::TagSummary>)
+```
+
+`changes<R>` refetches every query holding an `R`; `updates<R>` is for an
+action whose reply carries the changed rows, which the caller's screens show
+at once, before any fetch; `none` is for an action that changes nothing. A query whose
+action declares effects is refused, because a query must only read. How to
+choose, the checklist for a new action and every error message with its fix
+are in [`docs/KEEPING-SCREENS-CURRENT.md`](KEEPING-SCREENS-CURRENT.md).
+
 ## 10. Forms from the compiled action type
 
 `morph::forms::schemaJson<A>()` derives a JSON Schema from the action type
@@ -856,9 +883,10 @@ client.
 A guide that only sells is worth less than one that tells you when to stop.
 Read [`docs/spec/`](spec/) before relying on any of these; the short version:
 
-- **It is not a general-purpose RPC framework.** Request/response only. No
-  streaming, no bidirectional channels, no server-initiated push. bookmarks'
-  `GetChangesSince` is the polling answer a client uses instead.
+- **It is not a general-purpose RPC framework.** Request/response, plus one
+  kind of server-initiated message: the change notifications that keep
+  screens current ([`docs/KEEPING-SCREENS-CURRENT.md`](KEEPING-SCREENS-CURRENT.md)).
+  No streaming and no general bidirectional channel.
 - **`Completion<T>` is a leaf callback primitive, not a future.** No `T→U`
   chaining, no `co_await`, and no cancellation; lifetime binding is the opt-in
   `CallbackScope` of section 8.
@@ -871,9 +899,9 @@ Read [`docs/spec/`](spec/) before relying on any of these; the short version:
   the default; a server that configures none of them assumes a trusted,
   authenticated transport and is not a hardened public-internet server.
 - **Instance subscriptions are best-effort and in-process.** `subscribe<R>`
-  fans out to handlers on the same `Bridge`; two separate clients sharing an
-  instance do not see each other's results until they ask again. No replay, no
-  durability, no coalescing.
+  fans out to handlers on the same `Bridge`, with no replay and no durability.
+  Across clients, what keeps screens current is declared effects, which tell
+  every connection what changed but not the new values.
 - **Exact numbers are fixed-width.** `Rational` is an `int64` pair; `+`/`-`/`*`
   can overflow rather than returning an error, and high decimal precision
   shrinks the representable magnitude.
@@ -905,6 +933,8 @@ You now have a question rather than a topic, which is what the map is for.
 | who is allowed to do what? | `docs/spec/security.md`, `docs/spec/session/session.md` |
 | what serialises access to my model? | `docs/spec/concurrency_and_lifetimes.md` |
 | how do I keep several screens on one model instance? | `docs/spec/core/shared_instances.md` |
+| how do screens refresh after an action, and what do I declare? | [`docs/KEEPING-SCREENS-CURRENT.md`](KEEPING-SCREENS-CURRENT.md) |
+| how does an AI agent drive my app? | `docs/spec/ui/agent.md`, and bank's `--mcp-stdio` ([`examples/bank/README.md`](../examples/bank/README.md)) |
 | how do I generate a form? | `docs/spec/forms/forms.md`, and [`examples/forms`](../examples/forms) |
 | how do I test all this? | [`examples/TESTING.md`](../examples/TESTING.md) |
 | what are the rules for an app built on morph? | [`examples/IMPLEMENTATION.md`](../examples/IMPLEMENTATION.md) |