Stateful models: keyed shareable instances, instance subscriptions, and a bank example that demonstrates them (closes #18)

CHANGELOG.md

@@ -32,9 +32,56 @@ API surface).
   (`scripts/check_deprecated_markers.sh`) enforcing that every
   `[[deprecated("...")]]` marker names a replacement and a target removal
   version.
+- **Keyed, shareable model instances.** One `BRIDGE_MODEL_KEY(Model, Action,
+  &Action::field)` beside the existing registrations designates the action that
+  defines a model's key and deduces the key type from that field, so the model's
+  own class body says nothing about keys; further actions carrying the same key
+  use `BRIDGE_KEY_FROM`, and creating actions use the `…_FROM_RESULT` variants.
+  `BridgeHandler<M, AllowShared>` joins a server-side directory keyed on
+  `(typeId, primary)`, so handlers in one process — or in two clients over one
+  `RemoteServer` — reach the same instance. Adds `attach()`, `primary()` and
+  `instances()` to the handler, the `primary`/`shared` envelope fields and the
+  `attach`/`assign`/`instances` wire kinds, all additive. See
+  `docs/spec/core/shared_instances.md`.
+- **Instance subscriptions.** `BridgeHandler::subscribe<R>(cb)`, keyed on the
+  result/state type, fires whenever an `R` is produced on the instance the
+  handler is attached to — by any handler attached to it. Fan-out is per
+  `Bridge`; there is no server-initiated push. See
+  `docs/spec/core/bridge.md#subscription-semantics`.
+
+### Changed
+
+- **`RemoteServer::closeConnection` now releases one reference per attachment
+  rather than erasing every model in the scope.** Required by cross-client
+  instance sharing: otherwise one client's disconnect destroys an instance
+  another client is still attached to. A connection scope records an
+  attachment *count* per instance for the same reason. Unshared instances have
+  exactly one attacher, so their lifetime is unchanged.
+- `examples/bank` is reshaped onto stateful, keyed models: `AccountModel` holds
+  one account in memory keyed by account id, and the new `CustomerModel` takes
+  the per-owner half (`ListAccounts`/`OpenAccount`).
+
+### Removed
+
+- **The reactive-draft mechanism** — `BridgeHandler::set<&A::field>`,
+  `reset<A>`, the action-keyed `subscribe<A>`, and their in-flight coalescing.
+  Its job is done better by a stateful model holding the draft itself, and
+  `subscribe` now means instance subscriptions (above). `morph::flows::FlowSession`
+  already owned its own draft tuple and now gates on `ActionValidator` and
+  dispatches directly; its public API, the `w-*`/`app-*` schema and
+  `WizardView.qml` are unchanged. `ActionValidator` keeps its server-side
+  validation role and loses only its draft-readiness one. Pre-1.0, per
+  `docs/spec/VERSIONING.md`.
 
 ### Fixed
 
+- `CustomerModel::execute(ListAccounts)` dereferenced `QuerySingle`'s optional
+  unchecked (inherited verbatim from the old `AccountModel`); it now throws
+  `NotFound`.
+- A flaky assertion in `tests/test_concurrency_invariants.cpp`: `succeeded > 0`
+  during backend churn is a scheduling race, not an invariant — under a
+  thread-serialising tool the switcher can cancel every in-flight call. The
+  same structural property is now asserted against the quiesced bridge.
 - Stale pre-JSON "5-part"/"6-part protocol" wording in `docs/ARCHITECTURE.md`
   and a test comment — the wire has been a JSON `Envelope` since it superseded
   the pipe-delimited protocol.

README.md

@@ -120,7 +120,7 @@ and the call site above are unchanged.
   `Bridge` and share it.
 - **`BridgeHandler<M>`** — your typed, GUI-facing handle to one model type `M`.
   It registers `M` on the bridge on construction and deregisters on destruction
-  (RAII). This is the object you call `.execute(...)` / `.subscribe<A>(...)` on.
+  (RAII). This is the object you call `.execute(...)` / `.subscribe<R>(...)` on.
   Create one per model type, wherever in the UI you need to talk to that model.
 
 ## Multiple models across multiple files
@@ -196,6 +196,60 @@ out of scope it cleanly deregisters itself.
 > locally via a capturing factory will fail at `register` time in remote mode if
 > it isn't macro-registered.
 
+## Shared model instances
+
+By default each `BridgeHandler` owns its own model instance — two handlers for
+`AccountModel` are two independent objects. When several screens should be
+looking at *the same* account, give the model a **primary key** and opt the
+handlers into sharing. The model class itself does not change:
+
+```cpp
+struct AccountModel {                        // still a plain C++ class
+    AccountInfo execute(const LoadAccount&); // ← names the account
+    Balance     execute(const Deposit&);     // ← keyless
+    Balance     execute(const GetBalance&);  // ← keyless
+};
+
+BRIDGE_REGISTER_MODEL (AccountModel, "AccountModel")
+BRIDGE_REGISTER_ACTION(AccountModel, LoadAccount, "LoadAccount")
+BRIDGE_REGISTER_ACTION(AccountModel, Deposit,     "Deposit")
+BRIDGE_REGISTER_ACTION(AccountModel, GetBalance,  "GetBalance")
+
+// One line: deduces the key type from the field, and marks LoadAccount as the
+// action that carries it.
+BRIDGE_MODEL_KEY(AccountModel, LoadAccount, &LoadAccount::id);
+```
+
+Attachment is then automatic — a key is named exactly once, and everything
+afterwards follows the handler:
+
+```cpp
+using morph::bridge::AllowShared;
+morph::bridge::BridgeHandler<AccountModel, AllowShared> screen {bridge, &guiExecutor};
+morph::bridge::BridgeHandler<AccountModel, AllowShared> sidebar{bridge, &guiExecutor};
+
+screen .execute(LoadAccount{.id = 32});   // no instance for 32 yet → constructs one
+sidebar.execute(LoadAccount{.id = 32});   // 32 is live → attaches, constructs nothing
+
+screen .execute(Deposit{.amountMinor = 100});   // keyless → instance 32
+sidebar.execute(GetBalance{});                  // keyless → instance 32, sees the 100
+```
+
+- **The directory is server-side**, so with a remote backend two *clients* also
+  meet on one instance, not just two handlers in one process.
+- **Lifetime is refcounted**: the instance lives until the last handler attached
+  to it goes away — including across a dropped connection.
+- **`BridgeHandler<Model>` is unchanged.** Sharing is opt-in per handler; a
+  plain handler still gets its own private instance and is invisible to the
+  directory.
+- `handler.instances()` returns the live keys, and `handler.attach(key)` binds
+  without executing anything.
+
+Sharing only earns its keep when a model actually *holds* state — see
+[`examples/bank`](examples/bank), whose `AccountModel` keeps one account in
+memory. Full design in
+[`docs/spec/core/shared_instances.md`](docs/spec/core/shared_instances.md).
+
 ## Subsystems
 
 morph is layered: the async/bridge core is always present; everything else is an
@@ -205,7 +259,7 @@ opt-in header you include only if you need it.
 |---|---|---|
 | `morph::exec` | `executor.hpp`, `strand.hpp` | `IExecutor`, `ThreadPoolExecutor`, `MainThreadExecutor`, per-model `StrandExecutor` |
 | `morph::async` | `completion.hpp` | `Completion<T>` — move-only result handle with `.then` / `.onError` |
-| `morph::model` | `registry.hpp`, `model.hpp` | Registration traits, validators, `ActionDispatcher`, type-erased holders |
+| `morph::model` | `registry.hpp`, `model.hpp`, `model_key.hpp` | Registration traits, validators, `ActionDispatcher`, type-erased holders, model primary keys |
 | `morph::backend` | `backend.hpp`, `remote.hpp` | `LocalBackend`, `RemoteServer`, `SimulatedRemoteBackend` |
 | `morph::bridge` | `bridge.hpp` | `Bridge`, `BridgeHandler<M>` — the user-facing API |
 | `morph::wire` | `wire.hpp` | JSON `Envelope` protocol between client and server |
@@ -382,14 +436,19 @@ morph is a young, actively developed library with thorough test coverage of its
 core. It is honest about the following boundaries — read the per-subsystem specs
 in [`docs/spec/`](docs/spec) before relying on any of these in production:
 
-- **Security is app-supplied.** The wire protocol has no version negotiation,
-  no message-size or timeout bounds, and no built-in authentication; `Context`
-  identity is unauthenticated and `RemoteServer` model ids are guessable
-  sequential integers with control messages unauthorized. `RemoteServer`
-  assumes a trusted, authenticated transport — it is not a hardened
-  public-internet server as shipped.
+- **Security is app-supplied.** There is no built-in authentication: `Context`
+  identity is whatever the client claims until an `IAuthorizer` verifies it, and
+  the default authorizer allows everything. Protocol version negotiation,
+  message-size and timeout bounds, opaque model ids, and register/per-instance
+  authorization hooks all ship (see `docs/spec/security.md`), but they are
+  **opt-in** — a server that configures none of them assumes a trusted,
+  authenticated transport and is not a hardened public-internet server.
 - **`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.
 - **Exact numbers are fixed-width.** `Rational` is an `int64` pair; `+`/`-`/`*`
   can overflow (undefined behaviour) rather than returning an error, and high
   decimal precision shrinks the representable magnitude. Wire input is *clamped*,
@@ -399,8 +458,10 @@ in [`docs/spec/`](docs/spec) before relying on any of these in production:
   the store/log divergence gap by opting into `IModelHolder::setOutboxManaged` +
   `journal::OutboxRelay` (see `docs/spec/journal/journal.md`); a model that
   doesn't opt in keeps the default fire-after-success append.
-- **Offline durability is bring-your-own.** Only an in-memory queue ships; the
-  crash-safety story depends on a durable queue you implement.
+- **Offline durability is opt-in.** `FileOfflineQueue` (NDJSON, always built)
+  and `SqliteOfflineQueue` (`MORPH_BUILD_OFFLINE_SQLITE`) both persist across
+  restarts; the in-memory queue remains the default, so crash-safety depends on
+  selecting a durable one.
 - **Registration is global and macro-driven** (per-TU, static-init, string type
   ids); there is no runtime deregistration and unknown ids fail at runtime, not
   compile time.