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

[Yaraslaut]

Closes #18.

What the survey found

Issue #18 asked what morph is missing versus Axelor, Jmix, Causeway and Orleans. Reading those feature lists side by side produces a ~25-item backlog, most of which morph should never build — it owns neither a database, a process engine, nor an IDE. So the survey was done the other way round: against use cases in examples/bank, asking where a developer hits a wall.

That produced one finding that subsumes most of the others:

morph's models were anonymous and stateless, so the model layer was doing nothing. Every bank model's only member was the std::optional<DataMapper> inherited from WithMapper — a connection, not domain state. The per-instance strand morph advertises as its core service therefore protected nothing, and because a BridgeHandler registers one instance, the desktop GUI held five AccountModel instances (and five SQLite connections) for one logical thing.

Orleans names this directly — a grain is identity + behaviour + state, and morph had only behaviour. The fix is not to become an actor runtime; it is to make the existing model layer do what it already claims.

docs/todo.md §F records the full analysis, including a refusal table so the survey does not get re-run: entity metamodels, BPMN, field-level permissions, clustering, reporting engines and the rest, each with the reason it is out of identity.

What shipped

F1 — examples/bank reshaped onto stateful models. AccountModel holds one account in memory, keyed by account id, hydrated on first use and written through on mutation. CustomerModel takes the per-owner half (ListAccounts/OpenAccount), which was never account-scoped — the owner field on those DTOs was the symptom of one model doing two jobs.

F2 — Keyed, shareable model instances. A model declares a nested PrimaryKey alias (detected structurally, like views.md's kind/query); actions declare which field carries it via BRIDGE_KEY_FROM, or that their result establishes it via BRIDGE_KEY_FROM_RESULT. BridgeHandler<M, AllowShared> joins a server-side directory keyed on (typeId, primary), so two handlers — in one process or in two clients over one RemoteServer — reach the same instance.

F3 — Instance subscriptions. subscribe<R>(cb) is keyed on the result/state type and fires whenever an R is produced on the attached instance, by any handler attached to it. A subscriber names what it renders, not what somebody else must call to produce it.

Things worth a reviewer's attention

• A7 changed. closeConnection now releases one reference per attachment rather than erasing. Without this, one client's disconnect destroys an instance another client is still using. Connection-scope membership became a count for the same reason.
• Shared instances are ownerless. authorizeInstance's documented ownerPrincipal == ctx.principal policy would otherwise reject every client but the creator, defeating cross-client sharing outright. Gating a shared model is authorize's job or the model's own.
• A public API was removed. The reactive-draft mechanism (set<&A::field>, reset<A>, the action-keyed subscribe, in-flight coalescing) is gone. FlowSession already owned its own draft tuple and merely mirrored into the handler's, so it now gates on ActionValidator and dispatches directly — its public API, the w-*/app-* schema, and WizardView.qml are unchanged. ActionValidator keeps its A1 server-side role. morph is 0.1.0 and VERSIONING.md reserves exactly this latitude.
• The bank's sharp edge is shown, not hidden. Transfers and bill payments settle inside a SqlTransaction owned by a different model, so they land behind a cached row's back. bank/db/row_versions.hpp bumps a per-row counter and cached readers re-hydrate on a stale version. morph has no cross-instance transaction and the example must not imply otherwise.
• Not included: cross-client push. Subscription fan-out is per Bridge. Two handlers in one process — the case the bank GUI has — see each other's work; two separate clients do not. A server-initiated notify frame would need both transports to grow an unsolicited-message path, which is its own item and is recorded as such.

Verification

Configuration	Result
clang-release	775 tests, 8091 assertions
clang-debug + net + sqlite + load tests	860 tests
gcc-debug + Qt6 (offscreen QML)	910 tests
examples/bank (SQLite/Lightweight)	21 tests, 145 assertions
Bank desktop GUI, CLI, WASM shadow models	build clean
Doxygen WARN_AS_ERROR=FAIL_ON_WARNINGS	clean
clang-tidy-diff on changed lines	clean
scripts/check_spec_citations.sh	clean

New tests pin the new semantics: tests/test_shared_instances.cpp (18 cases,
including result-sourced keys and in-place promotion), two real-socket cases in
tests/net/test_socket_backend.cpp covering the sharing wire path, and
examples/bank/tests/test_stateful_account.cpp (4 cases).
tests/test_subscription.cpp was rewritten for the new subscription meaning.

Two things CI caught that were worth fixing properly

A throughput regression on the hot path. publishResult ran on every
successful result — building a std::type_index and copying into a std::any
before the Completion could resolve — work every existing caller paid for a
feature they aren't using. A relaxed atomic subscription count short-circuits
it; measured over 200k executes, throughput is back to parity with master
(~537k/s vs ~548k/s, within noise).

A pre-existing flaky assertion, not a weakened one. The Valgrind job failed
on test_concurrency_invariants.cpp's succeeded > 0. Valgrind serialises every
thread onto one core, so a switcher looping every 1ms can legitimately cancel all
200 in-flight calls and leave zero successes — master passed that line by luck,
not by invariant. The structural property it was asserting (the
snapshot-and-dispatch path still resolves successfully after repeated switching)
is now checked against the quiesced bridge, which tests the same thing without
racing the switcher. The churn assertions — every call resolves, none is lost —
are unchanged.

Docs follow the repo's convention: docs/planned/ is empty again, the keyed-instance design landed as docs/spec/core/shared_instances.md, and the rest folded into bridge.md, ARCHITECTURE.md, workflows_navigation.md, forms.md and the bank README. README.md's "Status & limitations" also loses three claims that §A/§B had already invalidated.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 87.69575% with 55 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
include/morph/core/remote.hpp	81.96%	33 Missing ⚠️
include/morph/core/backend.hpp	77.04%	14 Missing ⚠️
include/morph/core/bridge.hpp	94.16%	8 Missing ⚠️

📢 Thoughts on this report? Let us know!