Skip to content

Latest commit

 

History

History
957 lines (746 loc) · 84.6 KB

ARCHITECTURE.md

File metadata and controls

957 lines (746 loc) · 84.6 KB

morph Architecture

Overview

morph is a typed, asynchronous bridge between a GUI thread and business-object models. Models may live in-process (local mode) or in a remote server process (remote mode). The GUI code is identical in both cases — only the backend implementation changes.

The core library, morph::morph, is a compiled library (C++23, namespace morph), static by default and shared with MORPH_BUILD_SHARED=ON; its templates and the macro-sensitive core headers stay in headers. It depends on Glaze for JSON reflection and on core-cpp for its event-loop timers, base64 and wakeup primitive; core-cpp's core::base, core::net and core::platform are static libraries, so a project that links morph::morph also builds those. The optional parts are separate targets, and some are compiled: the Qt integration (morph::qt), the terminal frontend (morph::tui), the Qt Quick frontend (morph::qt_quick) and the generic client (morph::client) are static libraries with sources under src/.

New to morph? docs/GETTING-STARTED.md is the step-by-step tutorial that comes before this document: it builds one small app end to end (examples/bookmarks) and explains why each piece exists. This page assumes you are already oriented. (Named, not linked, for the Doxygen reason below.)

Design specs. This document is the cross-cutting map. The authoritative, per-subsystem reference lives in docs/spec/ — one file per public type or subsystem, capturing invariants, API surface, and the reasoning behind each design. docs/spec/README.md indexes all of them, and is the quickest way to find the one you need: it groups every spec by the question it answers and traces one action end to end. (Named, not linked: Doxygen reads this file but not docs/spec/, and WARN_AS_ERROR turns a link it cannot resolve into a failed docs build — which is why every spec reference below is backticked too.) Consult the matching spec before changing a public type: e.g. docs/spec/security.md (authenticated sessions and the trust model), docs/spec/VERSIONING.md (the semantic-versioning / deprecation-window commitment), docs/spec/core/completion.md, docs/spec/core/executor.md, docs/spec/core/bridge.md, docs/spec/journal/journal.md, docs/spec/offline/offline.md, docs/spec/session/session.md, docs/spec/core/wire.md. Where this document and a spec disagree, the spec wins.

Namespace map

The public surface is split per topic so callers always know whether a name is part of the stable API or an implementation detail.

Namespace Purpose Public symbols
morph:: Macros only at this level BRIDGE_REGISTER_MODEL, BRIDGE_REGISTER_ACTION, BRIDGE_REGISTER_VALIDATOR (at file scope, but specialise morph::model::* templates)
morph::version Release version constants kMajor, kMinor, kPatch, kString (see docs/spec/VERSIONING.md)
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, 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
morph::session Per-call session context + authentication Context, IAuthorizer, AllowAllAuthorizer, allowAllAuthorizer, current; authenticated sessions (session_auth.hpp): SessionToken, TokenIssuer, TokenVerifier, SigningAuthorizer, MacFunction, hmacSha256, AuthError
morph::journal Ordered, replayable action log LogEntry, IActionLog, InMemoryActionLog, FileActionLog, SessionLog, OutboxRelay, OutboxRelayResult, PayloadMigrationRegistry, SchemaMismatchError, SerializationError, NullSinkError, replay(), toJson/fromJson, setActionLog, defaultActionLog, ScopedActionLog
morph::math Exact numeric values for actions Rational, DecimalPlaces, RationalError, kMaxDecimalPlaces, abs/ceil/floor/trunc
morph::units Unit-tagged, optionally-empty values Quantity<U>, UnitMeta, UnitTraits<E> (app-specialised), UnitAlternative<E>, HasUnitRelations, UnitEnum, isQuantity
morph::time UTC timestamps for actions DateTime, Timestamp
morph::forms JSON-Schema generation for auto-built GUIs, and the forms engine that reads it back and renders it through the view tree (see docs/spec/forms/engine.md) schemaJson<A>(), allRequiredEngaged(), Choice<T, ...>, FixedString, isChoice, EmptyCapableField, BlankAs; FormModel, FieldSpec, RuleExpr, FormSession, FieldState, Submitter, ChoiceFetcher, handlerSubmitter, Form<A, M, S>, CollectionSession, WizardSession, formView, collectionView, wizardView
morph::reactive Signal graph, view state and declarative control (see docs/spec/reactive/) Runtime, RuntimeOptions, Signal<T>, Computed<T>, Effect, Scope, EqualityPolicy, kEqualityUsable, Store<ViewState, Msg>, ExhaustiveUpdate, request(), Query<A, R>, QueryOptions, InvalidationLink, Mutation<A, R>, MutationOptions<A>, Concurrency, Subscription<R>, Refetchable, errorMessage, Scheduler, TimerHandle; testing::ManualScheduler
morph::ui The UI document and expr/1, its interpreter, the view tree, mount and the frontend seam (see docs/spec/ui/) Value, Type, Document, DocNode, Command, Catalog, loadDocument, Interpreter, Screen, Session, Dispatcher, BridgeDispatcher, ModelChannel, InterpreterHost, Expr, parseExpression, checkExpression, evaluate, Environment, StaticEnvironment, parseMessage, formatMessage, Node, Prop<T>, SlotId, slot(), Key, Common, Accessibility, KeyBinding, FieldState, MenuItem, ActionButton, Step, KeyValueItem, the node kinds and their builders, forEach, table, switchOn; Widget, ContainerWidget, FieldWidget, the widget interfaces, MenuEntry, IViewBackend; Mounted; AppContext, AppSource, Bundle, ConnectError, Backend, Frontend, FrontendOption, FrontendError, EnvironmentReader, processEnvironment, selectFrontend, MountedShell, ShellFactory, runApp; testing::RecordingBackend, testing::ConformanceProbe, testing::conformanceCases; the UI service's UiRegistry, ServedBundle, UiService, UiClient, VerifiedCache, IBundleStore, MemoryBundleStore, Manifest, CatalogReply, contentHash; author:: — Handle, Scope, DeclScope, Screen, ScreenRegistry, checkAccessibility, MORPH_REGISTER_SCREEN
morph::testing The installed owner test kit StepExecutor, OwnerProbeRecorder
morph::tui The terminal renderer and frontend (built only when MORPH_BUILD_TUI=ON; see docs/spec/tui/) Backend, Frontend, FrontendConfig, ShellFactory, frontendOption, kInterruptExitCode, LoopExecutor
morph::qt Qt integration (built only when MORPH_BUILD_QT=ON) QtExecutor, QtWebSocketBackend, QtWebSocketServer
morph::qt_quick The Qt Quick renderer and frontend (built only when MORPH_BUILD_QT_QUICK=ON; see docs/spec/qt_quick/) Backend, BackendOptions, CustomWidget, CustomRequest, Components, ComponentFailure, Frontend, FrontendConfig, ShellFactory, frontendOption, usableHere, QtScheduler
morph::net The raw-socket WebSocket transport (built only when MORPH_BUILD_NET=ON, POSIX only) SocketBackend, SocketServer
morph::table The table engine: sort, filter and view mapping over a data source (see docs/spec/table/engine.md) Engine, EngineOptions, the data-source, query, selection and edit types
morph::render Client-side rendering helpers that never reach the wire the translation-catalog seam (i18n.hpp), locale numeric-entry normalisation (locale_format.hpp)
morph::client The generic client's source, command line and shell (built when MORPH_BUILD_CLIENT=ON, the default; see docs/spec/client/client.md) Args, Source, RemoteSource, LocalSource, LocalApp, RemoteTransport, ApplicationHost, ShellOptions

Every nested detail namespace under those topics holds implementation symbols. These do appear in some public signatures (e.g. Bridge's constructor takes unique_ptr<backend::detail::IBackend>), but callers never type a detail name directly — std::make_unique<morph::backend::LocalBackend>(...) converts implicitly.

Layer diagram

┌─────────────────────────────────────────────────────────────────┐
│  Application / GUI                                              │
│  morph::bridge::BridgeHandler<Model>  ← typed user-facing API   │
├─────────────────────────────────────────────────────────────────┤
│  Public API  (morph::bridge / morph::async)                     │
│  Bridge · BridgeHandler<M> · Completion<T>                      │
├─────────────────────────────────────────────────────────────────┤
│  Backend abstraction  (morph::backend + morph::backend::detail) │
│  IBackend · LocalBackend · SimulatedRemoteBackend               │
│  RemoteServer · QtWebSocketBackend · QtWebSocketServer          │
├─────────────────────────────────────────────────────────────────┤
│  Registry & type erasure  (morph::model + morph::model::detail) │
│  ActionDispatcher · ModelRegistryFactory · ModelTraits · …      │
├─────────────────────────────────────────────────────────────────┤
│  Internal async core                                            │
│  IExecutor · ThreadPoolExecutor · MainThreadExecutor            │
│                                       (executor.hpp)            │
│  ModelStrands · ModelId               (strand.hpp)              │
│  CompletionState<T>                   (completion.hpp)          │
├─────────────────────────────────────────────────────────────────┤
│  Cross-cutting                                                  │
│  LogLevel · setLogger · log helpers   (logger.hpp)              │
└─────────────────────────────────────────────────────────────────┘

Deployment topologies

Local mode — model lives in the same process:

GUI thread
  └─ bridge::BridgeHandler<M>::execute(action)
       └─ bridge::Bridge::executeVia<M, A>
            └─ backend::LocalBackend::executeInto
                 └─ ModelStrands → worker thread → Model::execute(action)
                      └─ async::Completion<T>::then callback → GUI executor

Simulated-remote mode — model lives behind an in-process RemoteServer (used in tests):

GUI thread
  └─ bridge::BridgeHandler<M>::execute(action)
       └─ bridge::Bridge::executeVia<M, A>
            └─ backend::SimulatedRemoteBackend::execute
                 └─ serialize action → backend::RemoteServer::handle (JSON wire envelope)
                      └─ ActionDispatcher → ModelStrands → Model::execute
                           └─ serialize result → Completion<T>::then → GUI executor

Qt WebSocket mode — model lives in a separate process. Three classes with distinct responsibilities collaborate here: qt::QtWebSocketBackend is the network client (owns the QWebSocket, correlates replies to pending Completions, handles reconnect); qt::QtWebSocketServer is the network server (pure transport — receives text frames and forwards them verbatim to RemoteServer::handle(), sends the reply back); backend::RemoteServer is the protocol + dispatch layer (parses envelopes, authorizes, routes to models) and is transport-agnostic — the same class also serves the simulated-remote topology above.

GUI thread (Qt process)                         Server process
                                                qt::QtWebSocketServer (transport)
  └─ bridge::BridgeHandler<M>::execute(action)
       └─ bridge::Bridge::executeVia<M, A>
            └─ qt::QtWebSocketBackend::execute   (network client)
                 └─ assign callId, send JSON  ──► qt::QtWebSocketServer::handle
                                                        └─ backend::RemoteServer::handle (JSON wire envelope)
                                                             └─ ActionDispatcher → ModelStrands → Model::execute
                 ◄── JSON reply (ok|callId|result) ──────────────────────────────
            └─ resolve pending Completion
       └─ async::Completion<T>::then callback → qt::QtExecutor → GUI thread

The GUI sees the same morph::async::Completion<T> in all three modes.

Offline / sync mode — how the morph::offline primitives compose. These four classes do not form a backend of their own; they wrap whichever backend is active and drive Bridge::switchBackend + replay when connectivity flaps. The framework ships the primitives and the sequencing; the application wires them together (the probe, the queue's persistence, and the replay function are all caller-supplied):

morph::offline::NetworkMonitor            (detects connectivity; probe is caller-supplied)
  │ onOffline ──► app calls Bridge::switchBackend(local fallback)
  │               app/enqueuer writes pending actions into IOfflineQueue
  │                 (InMemoryOfflineQueue ships with the framework;
  │                  SqliteOfflineQueue/FileOfflineQueue ship; the app picks)
  │ onOnline  ──► morph::offline::ReconnectCoordinator  (sequences:)
  │                 1. tryReconnect()      → probe the primary backend
  │                 2. activatePrimary()   → Bridge::switchBackend(primary)
  │                 3. bindContext()       → rebind handlers
  │                 4. replay()            → morph::offline::SyncWorker::run()
  │                                            drains IOfflineQueue via a
  │                                            caller-supplied ReplayFunction

NetworkMonitor fires the transitions; ReconnectCoordinator owns the ordering and retry loop; SyncWorker owns the queue drain; IOfflineQueue owns the pending writes. Each is usable independently of the others.

Wire protocol

RemoteServer::handle accepts JSON envelopes (morph::wire::Envelope). The kind field is the discriminator:

kind Direction Required fields Meaning
"register" client → server typeId, contextKey (optional) Register a model instance; server replies ok with modelId
"deregister" client → server modelId Destroy model instance; server replies ok
"execute" client → server callId, modelId, modelType, actionType, body, session (optional) Dispatch an action
"ok" server → client callId, plus body (execute result) or modelId (register reply) Success
"err" server → client callId (echoed), message Failure

These are the kinds every client uses. The rest — hello (protocol-version negotiation), attach/assign/instances (shared instances), schemas, cancel, and watch/unwatch/event (change notifications) — are specified in docs/spec/core/wire.md.

All envelopes round-trip through Glaze JSON, so the protocol is self-describing, escaping-safe, and easy to extend (add a field, ignore unknowns). A kind the server does not answer itself goes to the IEnvelopeServices in ServerConfig::services; the UI service's ui-hello, ui-catalog and ui-fetch arrive that way (docs/spec/ui/service.md), and a server without it answers them unknown envelope kind.

The session field is a morph::session::Context carrying a verified bearer token alongside the (untrusted) client-asserted principal. The server runs every incoming execute envelope through its configured IAuthorizer; a false return causes the server to reply with err|unauthorized (callId echoed). The default authorizer permits everything. When a verifying authorizer (SigningAuthorizer) is installed, the server also calls IAuthorizer::authenticate and, when it yields a principal from a valid token, overwrites Context::principal with it before dispatch — so the verified principal is authoritative and session::current()->principal read inside a model is the authenticated identity, not the client's claim. See "Authenticated sessions" below and docs/spec/security.md.

RemoteServer::handleInline is the synchronous variant used for control messages (register/deregister) — e.g. when a BridgeHandler is constructed from inside an action handler running on the worker pool. It rejects execute up front with an err reply, because an execute reply is produced asynchronously on the strand, after the synchronous call has already returned and destroyed the reply buffer the deferred callback would write into.

contextKey carries a registering instance's stable identity (e.g. an account id) from HandlerBinding::contextKey across the wire, so a server-side RemoteServer::LogProvider can attach an action log to the instance it creates — see "Action log" below. Empty (the default) means no identity. The field is carried on register and attach and ignored on every other kind.

Component detail

Executors

All concurrency runs through morph::exec::IExecutor::post(fn):

  • ThreadPoolExecutor — fixed N worker threads, MPMC queue. A task exception is caught and logged via morph::log (std::exception with its what(), anything else as "unknown exception"); it never propagates out of the worker or aborts sibling tasks.
  • MainThreadExecutor — single-threaded queue pumped by runFor(timeout); used in non-Qt tests and tools as the "GUI" thread. A task exception is caught and logged the same way, and the pump continues with the next task.
  • QtExecutor — posts via QMetaObject::invokeMethod(Qt::QueuedConnection); safe from any thread. A task still queued when the executor is destroyed is dropped, not run.

A model instance's strand (morph::exec::detail::ModelStrands, below) is where Model::execute() actually runs; like ThreadPoolExecutor, it catches a task exception (std::exception or unknown) and logs it via morph::log so a throw neither stalls the strand nor vanishes — the next queued task for that model still runs.

Strands

morph::exec::detail::ModelStrands guarantees that all tasks for the same ModelId are serialised while tasks for different models are parallelised. It is core-cpp's core::async::KeyedStrands<ModelId> over the backend's IExecutor: a strand per model instance with work, made when it gets work and retired when it runs out, which queues itself on the executor once per turn and runs a batch of tasks there. morph adds the adapter to its IExecutor, the catch-and-log above, and the Task handler's session around each of the handler's resumptions (see docs/spec/core/coroutines.md).

Completion

Move-only public result handle (morph::async::Completion<T>). Internally backed by morph::async::detail::CompletionState<T>, which takes no lock: the first settle claims the state with an atomic exchange and publishes the value or error, and everything else — the attached handlers and their delivery — belongs to the callback executor. Key invariant: callbacks are always delivered via the IExecutor supplied at construction, so the GUI thread is never blocked and callbacks always fire on the right thread. Several handlers may be attached; they run in attachment order.

If a Completion is destroyed with an unhandled error (no .onError was attached), CompletionState::~CompletionState logs the exception through the configured logger.

Registry & type erasure

morph::model::ModelTraits<M> and morph::model::ActionTraits<A> are specialised by registration macros. They provide:

  • String type IDs for protocol routing — the string literals passed as the NAME argument to BRIDGE_REGISTER_MODEL(M, "MyModel") / BRIDGE_REGISTER_ACTION(M, A, "MyAction") in the .cpp that owns the model. These strings travel in the wire envelope's modelType/actionType fields and key the server's dispatch tables.
  • Glaze-based toJson / fromJson for actions and results.

morph::model::detail::ActionDispatcher maps (modelTypeId, actionTypeId) → a runner lambda that downcasts IModelHolder, calls model.execute(action), and returns the result as JSON.

morph::model::detail::ModelRegistryFactory maps modelTypeId → a factory closure that constructs an IModelHolder.

HandlerBinding — why it exists

When bridge::BridgeHandler<M> registers with the bridge::Bridge, the backend assigns it a ModelId (just a uint64_t). That ID is backend-local — if the backend is ever replaced, all existing IDs are meaningless.

The problem is that Bridge needs to be able to find every live BridgeHandler later (e.g. to re-register it on a new backend), but it cannot hold a strong reference to them — that would prevent BridgeHandler from being destroyed naturally at the end of its scope.

bridge::detail::HandlerBinding is the indirection that solves both constraints:

BridgeHandler<M>  ──owns──►  shared_ptr<HandlerBinding>
Bridge            ──holds──►  weak_ptr<HandlerBinding>   (does NOT keep it alive)

BridgeHandler holds the shared_ptr, so the HandlerBinding lives exactly as long as the handler does. Bridge holds a weak_ptr, so it can observe whether the handler is still alive — but it cannot prevent its destruction.

One owner. A Bridge, its handlers and its backend belong to the executor passed to the Bridge constructor (typically the GUI executor). Every member function runs there, so the bridge takes no lock; what arrives from other threads — bind replies, reconnects, the bridge-side work an action's result triggers — is posted to the owner. Only pendingCalls(), isBound() and hasSubscribers() read atomics and may be asked from anywhere. See docs/spec/core/bridge.md, "Thread safety — one owner".

RAII lifetime: When BridgeHandler goes out of scope, its destructor calls Bridge::deregisterHandler, which tells the backend to release the model instance. No manual cleanup is required from application code. Handlers are destroyed before their bridge. A handler that outlives its bridge checks the bridge's liveness token (Bridge::liveness()) and deregisters nothing once it has expired, so destroying it late is tolerated — but any call through it after the bridge is gone is not.

atomic<uint64_t> currentId: the backend-assigned ModelId the binding's calls go to; 0 means unbound. It is the one binding field read off the owner (by isBound()), which is why it is atomic. A call made while the binding is unbound or a bind is in flight is held and dispatched when the bind settles (docs/spec/core/bridge.md, "Registration readiness — the bind rule").

Backend switching: Bridge::switchBackend(newBackend) issues a bind on the new backend for every live binding. If a bind that settles before switchBackend returns failed, every instance acquired so far is released and the failure is rethrown with the old backend and every binding untouched. Otherwise the switch commits: the new ids are published, the backend is swapped, notifyBackendChanged() runs, and the old backend's pending calls are cancelled with BackendChangedError. LocalBackend posts onBackendChanged() onto the strand of every live model that implements IBackendChangedSink (detected at compile time via the BackendChangedNotifiable concept); SimulatedRemoteBackend does nothing, because its models live inside RemoteServer.

Logger

morph::log provides a global, mutex-protected, replaceable sink (std::function<void(LogLevel, std::string_view)>). LogLevel is a uint8_t-backed enum (debug < info < warn < error < off). All framework internals route through morph::log::detail::log(level, msg); call morph::log::setLogger at startup to redirect to spdlog, Qt logging, or a test spy.

Authenticated sessions

morph::session carries a per-call Context (principal, verified token, requestId, locale, and a free-form metadata bag) from the caller through the bridge to the model — session::current() reads it inside execute() without changing the model signature. The server-side authorization seam is IAuthorizer (authorize gates each execute; authenticate returns the verified principal to make authoritative); AllowAllAuthorizer / allowAllAuthorizer() is the default and permits everything.

session_auth.hpp adds the opt-in authenticated variant: signed, stateless bearer tokens (SessionToken claims, base64url(claims).base64url(mac)) minted by TokenIssuer, verified by TokenVerifier, and enforced per request by SigningAuthorizer. The MAC primitive is pluggable (MacFunction); a self-contained, test-vector-verified hmacSha256 is the default reference implementation. AuthError enumerates verification failures.

docs/spec/security.md is the authoritative spec for the trust model, the authoritative-principal flow, and the limits of the reference crypto — this section is only a map, not a substitute.

NetworkMonitor

morph::offline::NetworkMonitor probes connectivity on a timer of an I/O loop — the application's IoLoop, or one the monitor owns, with a thread of its own — and fires callbacks on transitions. The framework supplies no probe implementation — the caller provides a bool() callable that returns true when the system is reachable (TCP connect, HTTP ping, custom check, etc.). This keeps the monitor fully portable across OS and transport.

State machine:

  • Starts online (assumes connectivity until proven otherwise).
  • Goes offline after failureThreshold consecutive probe failures → fires onOffline.
  • Returns online after onlineThreshold consecutive probe successes → fires onOnline.
  • Each transition fires its callback exactly once.
  • The probe and the callbacks run on the loop's thread and must not block: while they run, nothing else on that loop makes progress.

Thread safety: isOnline() reads an std::atomic<bool> — safe from any thread. stop() is idempotent and safe from any thread, including from inside the probe or a callback; once it returns, no probe or callback of the monitor runs again. The destructor calls stop(), so explicit shutdown is optional.

Intended integration with switchBackend: the callbacks run on the loop's thread, and switchBackend belongs to the bridge's owner, so they post the switch there:

morph::offline::NetworkMonitor monitor{
    myTcpProbe,
    [&] { gui.post([&] { bridge.switchBackend(std::make_unique<morph::backend::LocalBackend>(localPool)); }); },
    [&] { gui.post([&] { bridge.switchBackend(std::make_unique<morph::backend::SimulatedRemoteBackend>(*server)); }); }
};

IOfflineQueue + InMemoryOfflineQueue

morph::offline::IOfflineQueue provides an interface over three operations:

Method Semantics
enqueue(payload) Append an opaque string item; returns a stable uint64_t id
drain() Return all pending items in enqueue order; does not remove them
markDone(id) Remove item by id; no-op if unknown

drain() returning items without removing them is deliberate — items survive a crash between drain() and markDone(). A SQL-backed implementation can persist items across process restarts by storing them in a table with a UNIQUE constraint on the payload.

InMemoryOfflineQueue implements the interface with a std::deque that belongs to the executor the queue is given at construction: its verbs run there, and a caller elsewhere posts its writes and asks its reads through completion overloads (see docs/spec/offline/offline.md, "One owner"). It does not deduplicate.

Action log — ordered, coalescing, identity-aware execution history

morph::journal records executed actions as an ordered, replayable log, distinct in purpose from IOfflineQueue above: IOfflineQueue holds pending writes awaiting retry and deletes them once delivered; the action log is a permanent audit/replay trail — entries are never removed by the framework.

IActionLog is the durable-sink interface (append, flush, entries), implemented by InMemoryActionLog and FileActionLog (append-only NDJSON, flush() fsyncs). Each LogEntry carries modelType, entityKey, actionType, payload/result JSON, principal, and a sink-assigned seq. FileActionLog::entries() tolerates a torn trailing line: a crash between append's write and the next flush can leave a truncated final line, so a malformed last line is logged and skipped rather than throwing — but a malformed line mid-file is genuine corruption and is re-thrown.

Set the sink once, in main() — every model uses it automatically. morph::journal::setActionLog(log) installs a process-wide default. ModelFactory::create<Model>() — the factory behind every ordinary model registration, local or remote — attaches that default to each new instance automatically (empty entityKey). No per-model, per-handler, or per-backend wiring is required; RemoteServer-owned instances get it exactly the same way, since they're constructed through the same factory. defaultActionLog() reads the current sink back; ScopedActionLog (RAII, mirrors morph::log::ScopedLoggerOverride) installs one temporarily and restores the previous one on scope exit — the tool tests use it to avoid leaking a sink across test cases.

Application code that needs a specific instance identity (e.g. per-account auditing) can still call IModelHolder::attachActionLog(log, contextKey) explicitly on that instance — an explicit call always overrides the default, and is the seam HandlerBinding::contextKey/RemoteServer::ServerConfig::logProvider (below) build on for the remote case. Recording itself happens at the two call sites that are the only two places Model::execute() is ever invoked in the whole codebase:

Site Topology
ActionDispatcher::registerAction's runner (registry.hpp) Every remote/Qt topology — RemoteServer owns the persistent IModelHolders and dispatches through here
Bridge::executeVia's localOp (bridge.hpp) Local mode only — LocalBackend calls this directly; remote backends never invoke localOp at all

Because these are mutually exclusive per topology, recording is automatically server-side wherever a client/server split exists, with no extra plumbing.

Loggable (morph::model::Loggable::{Yes,No}) is a strong-typed opt-out on BRIDGE_REGISTER_ACTION (an optional 4th argument; no separate registration macro). Default is Yes — every action is recorded unless explicitly marked Loggable::No (typically pure queries like GetAccount/ListAccounts). A hand-written ActionTraits specialisation without a loggable member is recorded too: morph::model::detail::actionLoggable<A>() defaults to Yes when the member is absent, via a HasLoggableFlag concept exactly like ActionValidator's HasValidate.

ActionLogPolicy<A>::coalesce (default false) decides whether repeated executions of the same action against the same entity should collapse to the latest occurrence at a checkpoint, or whether every occurrence is a distinct, permanent fact. This matters because a form driving one action per edit can fire the same action many times in a row — without coalescing, every keystroke-driven re-fire would become a permanent log entry. false is correct for anything resembling a business event (a deposit); true is for drafts/settings where only the final value matters.

SessionLog (journal.hpp) is where coalescing actually happens. It keeps full, uncoalesced history in memory (the raw material for undoLast()), and checkpoint(durableSink) reduces everything appended since the last checkpoint by (modelType, entityKey, actionType) — keeping only the latest entry where coalesce == true, every entry otherwise — before forwarding the reduced set to the real sink. undoLast() needs no inverse operations: it drops the most recent entry and calls journal::replay() over what remains, reusing the same ActionDispatcher/ModelRegistryFactory RemoteServer already relies on for dispatch. This is not a workaround — a model's entire state genuinely is "initial state plus its ordered actions replayed," so reconstructing it by replay is the direct statement of that fact, not a special case.

Replay/undo never records into the live default log. journal::replay() builds the reconstructed holder through ModelRegistryFactory::create, which (like every factory-built model) auto-attaches the process-wide default action log. Before replaying, replay() immediately detaches it (attachActionLog(nullptr, {})), so re-running the recorded actions does not re-record each one into the live sink — which would corrupt the very audit trail being read from. The suppression is scoped to the replay pass only: once replay finishes, the reconstructed instance becomes the live model, and any new action executed on it goes through the normal dispatch path (with the log attached) and is recorded as a new entry appended after the surviving entries — e.g. journal [A, B, C], undo C, execute D leaves [A, B, D].

Remote-mode per-instance identity (ServerConfig::logProvider) is the advanced escape hatch for when the global default isn't granular enough: RemoteServer owns the actual model instances behind any remote/simulated-remote client, so it is the only place able to attach a different log (or a specific entityKey) to a specific instance. HandlerBinding::contextKey (client-side) travels through the register wire envelope's contextKey field; if a LogProvider is installed, RemoteServer calls it with (modelType, contextKey) and attaches whatever IActionLog it returns (or nothing, if it returns nullptr or no contextKey was sent) before the instance ever executes an action — overriding whatever the global default would have attached.

Transactional outbox (opt-in): a model that also owns its own durable store can avoid the log and the store's committed state silently diverging by writing its own outbox row inside its own transaction, calling IModelHolder::setOutboxManaged(true) to suppress the automatic append, and draining that outbox through a journal::OutboxRelay into the real sink — see docs/spec/journal/journal.md's "Transactional outbox (opt-in)" section. examples/bookmarks' BulkEdit adopts the pattern; a model that does not keeps the two independent writes (its store, then the log).

SyncWorker

morph::offline::SyncWorker drains an IOfflineQueue on reconnect. The caller supplies a ReplayFunction (bool(const std::string& payload)) that knows how to process each item — the framework has no knowledge of what replay means (insert to DB, POST to API, etc.).

  • Returns true → markDone called, item removed.
  • Returns false or throws → item left in queue for the next run().
  • stop() signals the current run() to abort after the current item. Resets at the start of each run(), so it is one-shot.
  • A worker belongs to the executor it is given, which runs one task at a time (typically the coordinator's offline strand). run() drains there — at once when already on it, posted otherwise — and returns a Completion<SyncResult>, so two run()s never overlap.

ReconnectCoordinator

morph::offline::ReconnectCoordinator sequences the steps that must happen, in order, when connectivity returns: tryReconnect() → activatePrimary() → bindContext() → replay(). All side effects are injected via Deps callables — the class contains only the retry loop, the strict ordering guarantee (each step waits for the previous), and the abort checks (shouldContinue() is polled before each attempt and again before replay). It performs no I/O and owns no thread: it owns a strand over the executor it is given, and onOnline() / onOffline() post their bodies there, so they run one at a time in call order. onOnline(replyExec) returns a Completion<ReconnectOutcome> delivered on the caller's replyExec (Reconnected / GaveUp after maxAttempts / Aborted); retry tuning lives in ReconnectCoordinatorConfig (maxAttempts, retryDelay). tryReconnect and shouldContinue throwing are treated as a failed attempt / "do not continue" respectively.

Conflict Resolution — a domain concern, not a framework concern

Conflict resolution during offline-to-online sync belongs entirely in the model. The framework's role is to fire onBackendChanged() on the new model instance and then step back. How the model handles that notification is its own business.

What the framework guarantees:

  • onBackendChanged() fires exactly once per switchBackend() call.
  • It fires on the new backend's model instance (not the old one).
  • It fires after all handlers are re-registered — execute() calls issued from within onBackendChanged() will reach the new backend.
  • Each switchBackend() creates a fresh model instance via the registered factory. If the factory captures dependencies by reference, the new instance shares the same queue, resolver, and domain services as the old one.

Thread safety

Component Guarantee
Model::execute Never called concurrently for the same ModelId (strand).
Completion<T> / CompletionState<T> Settled from any thread, once (an atomic claim); handlers are attached and delivered on the supplied executor.
Bridge, BridgeHandler One owner: every call on the bridge's executor, no lock. pendingCalls(), isBound() and hasSubscribers() may be read from any thread.
Logger Sink and level accesses protected by mutex.
ModelStrands core-cpp's KeyedStrands: a registry lock taken before each strand's own; safe from any thread.
Bridge::switchBackend On the owner. A bind failure the new backend reports before returning rolls the switch back and leaves the old backend and every binding untouched; calls made during the switch are held until their binding is bound.

Error propagation

Model::execute(action) throws
  └─ LocalBackend's strand task catches via try/catch
       └─ CompletionState::setException(current_exception())
            └─ .onError(fn) handler posted to GUI executor
                 └─ fn receives exception_ptr; caller rethrows to inspect

If the Completion is abandoned (no .onError attached, or no callback executor to deliver it on), the destructor logs the exception through the orphan logger. Non-std::exception types are logged as "unknown exception".

Task exceptions on the executors themselves are handled independently: ThreadPoolExecutor, MainThreadExecutor and ModelStrands catch and log every task throw via morph::log. A throwing task therefore never kills a worker or stalls a strand — see "Executors" above.

Adding a new model and actions

  1. Define the model struct with execute overloads:
struct MyAction { int x = 0; };

struct MyModel {
    int execute(const MyAction& a) { return a.x * 2; }
};
  1. Specialise traits and register (in a .cpp that owns the model):
#include <morph/core/registry.hpp>

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):

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
  1. Use from the GUI (same code for local and remote):
morph::bridge::Bridge bridge{std::make_unique<morph::backend::LocalBackend>(pool), guiExecutor};
morph::bridge::BridgeHandler<MyModel> handler{bridge, &guiExecutor};

handler.execute(MyAction{21})
    .then([](int result) { /* runs on GUI thread */ })
    .onError([](std::exception_ptr e) { /* runs on GUI thread */ });

Keyed, shareable model instances

A BridgeHandler normally registers its own model instance. A model that declares a primary key can instead have its instances shared: handlers that name the same key reach one instance, through a directory the server owns, so the sharing spans clients and not merely handlers.

The key is declared beside the registrations, never inside the model class:

BRIDGE_MODEL_KEY(AccountModel, LoadAccount, &LoadAccount::id);  // key type deduced
BRIDGE_KEY_FROM(CloseAccount, &CloseAccount::id);               // also carries it

BRIDGE_MODEL_KEY appears once per model — it specialises ModelKeyTraits<Model>, which cannot be repeated — and every other action naming the same entity uses BRIDGE_KEY_FROM. Actions with neither declaration are keyless, which is the common case: they run against whichever instance their handler is already attached to.

Behavior

Aspect Default
Opt-in BridgeHandler<M, AllowShared>. Plain BridgeHandler<M> keeps a private instance and never enters the directory.
Attachment Automatic: executing a keyed action attaches, or re-points, the handler to that key's instance, constructing one only if none is live.
Re-pointing A keyed action naming a different key moves the handler. Instances never change identity, so a key always maps to one instance.
Lifetime Refcounted across every attachment, including across connections. The instance dies when the last one goes.
Ownership A shared instance is recorded with no owner principal — per-instance ownership and cross-client sharing are mutually exclusive.
Creating actions BRIDGE_MODEL_KEY_FROM_RESULT takes the key from the reply and promotes the instance the action ran on, so nothing it built is stranded.

Full design, including the wire additions (primary/shared fields and the attach/assign/instances kinds) and the connection-scope refcount, is in docs/spec/core/shared_instances.md.

Instance subscriptions

The framework offers two complementary surfaces for talking to a model:

  1. One-shot: handler.execute(action) -> Completion<R>. The action is built at the call site and dispatched in one call.
  2. Observing: handler.subscribe<R>(cb) fires whenever an R is produced on the instance this handler is attached to — by this handler, by another handler sharing that instance, or by another screen entirely. Suitable for a view that renders some model state and must stay current when anything changes it.

A subscription names the result/state type, not an action. The subscriber describes what it renders rather than what somebody else must call to produce it, so adding an action that also yields an R never breaks an existing subscriber.

API

morph::bridge::BridgeHandler<AccountModel, morph::bridge::AllowShared> screen{bridge, guiExec};
morph::bridge::BridgeHandler<AccountModel, morph::bridge::AllowShared> sidebar{bridge, guiExec};

screen.attach(42);
sidebar.attach(42);                       // same instance

screen.subscribe<AccountInfo>([](AccountInfo info) { renderBalance(info); });

sidebar.execute(Deposit{.amountMinor = 5000});
// -> screen's callback runs: it never had to know Deposit exists

Behavior

Aspect Default
Keying On the result type R. Any action producing an R notifies.
Scope The instance the handler is currently attached to. Matched at publish time, so a subscription follows a re-pointed handler.
Subscriber cardinality One callback per (handler, R). subscribe<R>(cb) replaces any prior callback.
Echo The originating handler is notified too — no "was this mine" bookkeeping in subscribers.
Failures A failed action notifies nobody.
Ordering Per instance, guaranteed by that instance's strand. Nothing is guaranteed between instances.
Durability None. Best-effort and unbuffered: no replay, no cursor, no coalescing.
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.
  • morph::ui::chat (ui/chat/) puts a chat in the client's shell, whose assistant runs on the server and calls the open screen's actions under the signed-in user's session.

The user guide is docs/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 aggregates a client can build its GUI from a runtime: rational.hpp (exact numbers), quantity.hpp (unit-tagged, optionally-empty values) and forms.hpp (JSON Schema generation). Nothing else in the framework includes them — they are an opt-in layer that composes with registration, validators, and the wire. examples/forms demonstrates the whole loop with two renderers: a self-contained HTML page and the forms engine's screens in the generic client, both driven purely by the generated schemas.

morph::math::Rational — exact numbers on the wire

A trivially-copyable numerator/denominator pair (int64_t) plus a DecimalPlaces strong type. Arithmetic is exact and reduces to canonical form; binary operations propagate the wider precision; comparison ignores precision entirely. Fallible operations (operator/, fromFloat) return std::expected<Rational, RationalError>, and mixed expressions containing an expected or a floating-point operand evaluate to expected with left-to-right error short-circuiting.

On the wire a Rational is {"num":617,"den":50,"dp":2}. The Glaze codec routes every read through the canonicalising constructor: a non-canonical payload (1234/100) lands reduced, a hostile one (den == 0, out-of-range dp) is clamped rather than asserted — wire input is untrusted by design.

morph::units::Quantity<U> — one kind of empty, units as types

enum class Unit : std::uint16_t { scalar, kg, m3, kg_per_m3 };

template <> struct morph::units::UnitTraits<Unit> {
    static constexpr morph::units::UnitMeta meta(Unit) noexcept { /* id, display, decimals */ }
};
consteval Unit operator/(Unit lhs, Unit rhs) { /* kg / m3 -> kg_per_m3, else throw */ }

using Mass    = morph::units::Quantity<Unit::kg>;
using Volume  = morph::units::Quantity<Unit::m3>;
// Mass{...} / Volume{...} deduces Quantity<Unit::kg_per_m3> at compile time.

Design decisions, in order:

  • One kind of empty. The blank state ("not entered", "not measured") lives inside the quantity as std::optional<Rational>; action structs never wrap a Quantity in another std::optional. Whether a field may still be empty at submit time is field metadata (below), not a second wrapper type. Empty propagates through arithmetic (spreadsheet/SQL-NULL semantics); division by zero also yields empty.
  • Units are types, defined by the application. morph ships no unit enum. The app supplies its own enum, a UnitTraits specialisation (schema id, display text, default decimals) and a consteval algebra; Quantity's operator* / operator/ deduce result units from that algebra, and unsupported combinations fail to compile at the call site. Unit ids are protocol vocabulary: append enumerators, never renumber or rename.
  • Units never travel. The wire payload is just the nullable Rational (glz::meta unwraps the member), so a client cannot send a mismatched unit. Units appear in generated schemas (ExtUnits) and in C++ types only.
  • Declared precision lives in the type; actual precision is runtime data. Quantity<U, Decimals>'s second argument is the field's declared decimal count — defaulted from UnitTraits, overridable per field (Quantity<Unit::m3, 4>) — and feeds x-decimalPlaces and fromDouble. The value's actual precision is the Rational's runtime tag: it max-propagates through arithmetic and is adjustable at run time — withDecimalPlaces retags for display and leaves the value alone, while roundedToDecimalPlaces / atDeclaredPrecision re-round the value exactly (math::roundToDecimalPlaces, half away from zero by default) so storage and display agree. Same-unit quantities convert freely across declared precisions; computed temporaries carry the unit default.

morph::forms — schemas for auto-built GUIs

schemaJson<A>() wraps Glaze's write_json_schema (which contributes types, $defs, and any per-field metadata declared via glz::json_schema<A>) and closes the gaps a form renderer needs:

  • required — derived, not declared twice: a member is required unless it is a std::optional<...> or named in the action's static constexpr std::array optionalFields{...} opt-out list.
  • x-decimalPlaces — on every Quantity property, from UnitTraits, so the client knows the input step.
  • x-order — the member's declaration index on every property, so field layout survives schema round-trips through order-losing DOMs.

allRequiredEngaged(action) is the matching readiness predicate ("every required empty-capable field is engaged" — Quantity, Choice, Timestamp, or any type with a hasValue()) intended as the body of the action's validate() — which the existing ActionValidator resolution picks up automatically. One declaration then drives the schema's required array, the client-side submit gate, and the server-side readiness check.

morph::time::Timestamp and morph::forms::Choice — dates and combo boxes

Two further field types follow the same one-kind-of-empty pattern:

  • Timestamp (over morph::time::DateTime, adapted from LASTRADA Toolbox/Chrono.hpp): a UTC instant travelling as a strict ISO-8601 string ("2026-07-05T14:30:00.000Z"). The parser is hand-rolled (no locale, no std::chrono::parse) so behaviour is identical across standard libraries, and — unlike the clamping Rational codec — a malformed timestamp is a JSON read error: there is no meaningful clamp for a mistyped instant. Schemas carry the standard "format": "date-time" annotation.
  • Unit switching (UnitTraits<E>::relations): a unit system may declare convertible entry units per canonical unit with exact rational ratios (grams -> kilograms as {g, 1, 1000}). They surface as x-unitAlternatives in the schema; renderers offer a unit selector and recalculate the entered value exactly on switch, and payloads always carry the canonical unit — the model never sees display units. The alternatives list is derived from the same relations that drive convert — there is no separate alternatives declaration to keep in sync.
  • Choice<T, "ListSamples", "id", "name">: declares in the type that the field is not free input — its options are the rows returned by executing the named action (itself just a registered action, typically Loggable::No). The schema carries x-optionsAction/x-optionValue/ x-optionLabel; renderers execute the options action, build a combo box from the rows, and submit the selected valueField as the payload. On the wire a Choice is its bare nullable value — options metadata never travels. The demo's HTML page resolves options at emit time (a static page cannot fetch); the QML client fetches them live over the same in-process wire it submits on.

Header map

The headers are grouped into per-sub-domain subdirectories that mirror the namespaces. Design specs live under docs/spec/<sub-domain>/ with the same folder names. One exception: include/morph/version.hpp sits directly under include/morph/, with no subdirectory — it is cross-cutting library metadata rather than part of any one sub-domain, so it is documented in the top-level docs/spec/VERSIONING.md instead of a docs/spec/<sub-domain>/ folder.

The tables list each subsystem's principal headers; docs/spec/README.md indexes the spec for every one.

Library headers (include/morph/)

core/ — async core, registry, bridge, backends, wire

Header Responsibility
core/logger.hpp LogLevel, log configuration and level helpers; internals in morph::log::detail
core/executor.hpp IExecutor, ThreadPoolExecutor, MainThreadExecutor (morph::exec::)
core/strand.hpp ModelId, ModelIdHash, ModelStrands, TaskResumer — serialises tasks per model over core-cpp's KeyedStrands (morph::exec::detail::)
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) — the backend interface every transport implements
core/remote.hpp RemoteServer (configured by ServerConfig, incl. logProvider), SimulatedRemoteBackend (morph::backend::)
core/bridge.hpp Bridge, BridgeHandler<M> (public) + HandlerBinding (carrying contextKey), MemberPointerTraits (detail)
core/wire.hpp Envelope, encode/decode, kMaxEnvelopeBytes (morph::wire::) — the JSON wire envelope and length-bounded framing between any client and RemoteServer
core/callback_scope.hpp CallbackScope, CallbackToken (morph::async::) — the opt-in lifetime gate for completion callbacks. See docs/spec/core/callback_scope.md.
core/coroutine.hpp Coroutines on core::async::Task: awaiting a Completion, and Task action handlers. See docs/spec/core/coroutines.md.
core/io_loop.hpp IoLoop (morph::exec::) — the I/O event loop the socket transport and NetworkMonitor run on
core/model_key.hpp BRIDGE_MODEL_KEY, BRIDGE_KEY_FROM, BRIDGE_MODEL_KEY_FROM_RESULT and the key types — keyed, shareable instances. See docs/spec/core/shared_instances.md.
core/observability.hpp Metric and trace hooks on the framework's hot paths. See docs/spec/core/observability.md.

journal/ — ordered, replayable action log

Header Responsibility
journal/action_log.hpp LogEntry, IActionLog, InMemoryActionLog, toJson/fromJson, SerializationError, setActionLog, defaultActionLog, ScopedActionLog (morph::journal::) — the durable-sink interface and the process-wide default sink, with zero dependency on core/model.hpp/core/registry.hpp
journal/journal.hpp SessionLog, replay() (morph::journal::) — full-fidelity session log with checkpoint() coalescing and undoLast(), built on action_log.hpp + the existing ActionDispatcher/ModelRegistryFactory
journal/file_action_log.hpp FileActionLog (morph::journal::) — append-only NDJSON IActionLog, flush() fsyncs

offline/ — connectivity + replay

Header Responsibility
offline/network_monitor.hpp NetworkMonitorConfig, NetworkMonitor — background probe thread, online/offline state machine
offline/offline_queue.hpp IOfflineQueue, QueueItem, InMemoryOfflineQueue — durable write queue abstraction
offline/sync_worker.hpp SyncWorker, SyncResult — drains offline queue on reconnect via caller-supplied replay
offline/reconnect_coordinator.hpp ReconnectCoordinator, ReconnectOutcome, ReconnectCoordinatorConfig — sequences reconnect → activate → bind → replay on connectivity return; all side effects injected via Deps

session/ — per-call context + authentication

Header Responsibility
session/session.hpp Context, IAuthorizer, AllowAllAuthorizer, allowAllAuthorizer, current (morph::session::) — per-call session bag carried through the bridge to the model, plus the server-side authorization seam; internals in morph::session::detail (ScopedContext, thread-local current context)
session/session_auth.hpp SessionToken, TokenIssuer, TokenVerifier, SigningAuthorizer, MacFunction, hmacSha256, AuthError (morph::session::) — opt-in signed bearer tokens and a verifying IAuthorizer; self-contained reference HMAC-SHA256 in morph::session::detail. See docs/spec/security.md.

forms/ — JSON-Schema generation for auto-built GUIs

Header Responsibility
forms/forms.hpp schemaJson<A>(), allRequiredEngaged(), EmptyCapableField (morph::forms::) — JSON Schema per action with derived required, x-decimalPlaces, x-order, x-options*
forms/choice.hpp Choice<T, "ListX", "id", "name">, FixedString, isChoice (morph::forms::) — a field whose options are the result of executing the named action; surfaces as x-optionsAction/x-optionValue/x-optionLabel in schemas, renders as a combo box
forms/blank_as.hpp BlankAs (morph::forms::) — what a blank string field submits, named by the emitters and the engine
forms/engine/field_model.hpp FieldKind, SubmitMode, FieldSpec, FieldGroupSpec, FormModel (morph::forms::) — a form's immutable model, read from the emitted schema JSON. See docs/spec/forms/engine.md.
forms/engine/rules.hpp RuleExpr, Tri, RuleOperand, gatingVerdict, visibleVerdict, readonlyVerdict, requiredVerdict (morph::forms::) — x-rules translated into expr/1 and evaluated by the UI document's evaluator
forms/engine/values.hpp encodeScalar, decodeScalar, convertDraft, parseOptions, FieldError, WireValue (morph::forms::) — exact encoders and decoders between draft text and the wire
forms/engine/form_session.hpp FormSession, FieldState, RowState, Submitter, ChoiceFetcher, FormSessionOptions (morph::forms::) — the reactive, headless state of one form
forms/engine/handler_submitter.hpp handlerSubmitter, handlerChoiceFetcher (morph::forms::) — a form submitting through the application's own BridgeHandlers
forms/engine/typed_form.hpp Form<A, M, S>, FormModel::forAction<A>() (morph::forms::) — a form over a registered action type, with typed access
forms/engine/overrides.hpp Overrides, FieldView (morph::forms::) — replacement controls by field path, widget, unit or kind
forms/engine/form_view.hpp formView, FormViewOptions (morph::forms::) — a form session rendered as a view tree
forms/engine/collection.hpp CollectionModel, CollectionSession, CollectionRow, SchemaLookup (morph::forms::) — a v-* view as a reactive list, its table::VectorSource, row and collection actions, the confirm step and the row editor
forms/engine/wizard.hpp WizardModel, WizardSession (morph::forms::) — a w-* wizard as one form per step, sequenced by successful submissions, with prefill from earlier steps
forms/engine/collection_view.hpp collectionView, CollectionViewOptions, CollectionChrome (morph::forms::) — a collection session rendered as a view tree: the table, its actions, the confirm and editor dialogs or master-detail
forms/engine/wizard_view.hpp wizardView, WizardViewOptions, WizardChrome (morph::forms::) — a wizard session rendered as a view tree: the header, the current step and Back/Next

util/ — exact values, units, time

Header Responsibility
util/rational.hpp Rational, DecimalPlaces, RationalError (morph::math::) — exact int64 rational arithmetic with a decimal-precision tag; Glaze wire codec ({"num","den","dp"}, canonicalised on read) and std::formatter
util/quantity.hpp Quantity<U>, UnitMeta, UnitTraits (morph::units::) — unit-tagged optional value over Rational; units are application enum NTTPs, schemas get ExtUnits automatically. See docs/spec/util/quantity_type.md for the full design.
util/datetime.hpp DateTime, Timestamp (morph::time::) — UTC instant (ms precision) with a strict ISO-8601 wire codec (malformed input is a read error) and the optionally-empty field wrapper; schemas carry "format": "date-time"

reactive/ — signal graph, view state, declarative control

Header Responsibility
reactive/runtime.hpp Runtime, RuntimeOptions (morph::reactive::) — the owner, batching, one posted flush per change, widget-event deferral. See docs/spec/reactive/signals.md.
reactive/signal.hpp Signal<T>, Computed<T>, Effect, EqualityPolicy, kEqualityUsable — the graph's nodes
reactive/scope.hpp Scope — owns nodes and objects, destroys them newest first, nests (child(), depth())
reactive/store.hpp Store<ViewState, Msg>, ExhaustiveUpdate, request() — user-intent view state changed only by messages. See docs/spec/reactive/store.md.
reactive/control.hpp Query, QueryOptions, InvalidationLink, Mutation, MutationOptions, Concurrency, Subscription, Refetchable, errorMessage — server interaction as reactive state. See docs/spec/reactive/control.md.
reactive/scheduler.hpp Scheduler, TimerHandle — timers a frontend runs on the owner, for a query's timed refresh and debounce
reactive/testing/manual_scheduler.hpp testing::ManualScheduler — a Scheduler whose clock moves only when a test advances it
reactive/detail/graph.hpp RuntimeCore, Node, TrackingFrame, Colour, FlushBounds, the misuse site names, kDefaultMaxEffectRunsPerFlush, kDefaultMaxThrowReposts (morph::reactive::detail::)

ui/ — the UI document, expr/1, view tree, mount, frontend seam

Header Responsibility
ui/value.hpp Value, ValueKind, ValueList, ValueRecord, Decimal, Quantity, Type, TypeKind, parseType, valueFromJson, valueToJson, parseJson, Json, Refusal, pointerAppend (morph::ui::) — the document's typed values and types and their JSON form. See docs/spec/ui/document.md.
ui/message.hpp MessagePattern, parseMessage, formatMessage, MessageLocale, FormattedMessage, PluralCategory, pluralCategory, formatNumber — the MessageFormat 2 subset of t and its CLDR plural rules. See docs/spec/ui/expressions.md.
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/chat/ ChatService, ChatClient, ChatPanelBinding, ConversationStore, screenTools and IProvider (morph::ui::chat::) — a chat in the client's shell whose assistant runs on the server. qt/qt_chat_provider.hpp is the one place that names a model provider. See docs/spec/ui/chat.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, widthClassOf — the retained widgets a renderer implements. See docs/spec/ui/backend_contract.md.
ui/mount.hpp Mounted — builds a tree's widgets once, keeps them current through bindings, mounts content in child scopes, keeps keyed rows, controls inputs by their slots
ui/frontend.hpp AppContext, AppSource, Bundle, ConnectError, Backend, Frontend, FrontendOption, FrontendError, selectFrontend, MountedShell, ShellFactory, runApp — the seam main picks a frontend through. See docs/spec/ui/frontend.md.
ui/service.hpp, ui/service_client.hpp, ui/bundle.hpp UiRegistry, ServedBundle, UiService, UiClient, Manifest — the UI service that serves an application's screens to clients by content hash. See docs/spec/ui/service.md.
ui/shell_frame.hpp, ui/workspace.hpp, ui/navigator.hpp, ui/host.hpp, ui/host_vocabulary.hpp The client shell: the frame with its sidebar and top bar, the tabbed workspace, the navigator, and the host contract a screen is mounted through. See docs/spec/ui/shell_frame.md, workspace.md, host.md.
ui/theme.hpp, ui/preferences.hpp, ui/catalogue.hpp Theme tokens, per-person preferences, and message catalogues. See docs/spec/ui/theme.md, preferences.md.
ui/explorer.hpp, ui/inspector.hpp The app explorer and the development inspector. See docs/spec/ui/explorer.md, inspector.md.
ui/testing/recording_backend.hpp testing::RecordingBackend — the headless reference backend: operation log, golden dump, interaction helpers
ui/testing/backend_conformance.hpp testing::ConformanceProbe, testing::ConformanceCase, testing::conformanceCases() — the scripted cases every backend passes

testing/ — the installed owner test kit

Header Responsibility
testing/step_executor.hpp StepExecutor (morph::testing::) — an executor whose posted tasks run only when a test steps it
testing/owner_probe_recorder.hpp OwnerProbeRecorder (morph::testing::) — records every owner check while it is alive, instead of a debug build asserting

table/ — the table engine

Header Responsibility
table/engine.hpp and its siblings Engine (morph::table::) — a table's sort chain, filter and source-to-view row mapping, owner-affine, with sorting and filtering run off the owner. See docs/spec/table/engine.md.

render/ — client-side rendering helpers

Header Responsibility
render/i18n.hpp The renderer-side translation-catalog seam over the forms layer's derived message keys (morph::render::)
render/locale_format.hpp Locale numeric-entry normalisation: a locale's typed number to the canonical exact payload

client/ — the generic client

Built as the compiled STATIC library morph::client (sources in src/client/) when MORPH_BUILD_CLIENT=ON, the default. See docs/spec/client/client.md.

Header Responsibility
client/args.hpp Args (morph::client::) — the client's command line: which source it opens and how it starts
client/source.hpp Source, RemoteSource, LocalSource, LocalApp — where screens and models come from: a server, or an application linked in-process
client/transport.hpp RemoteTransport — the transport a remote client connects with, chosen by its frontend
client/shell.hpp ShellOptions, ApplicationHost, SignedIn — the shell the client mounts once its source is open

Socket transport headers (include/morph/net/)

Built only when MORPH_BUILD_NET=ON (POSIX only).

Header Responsibility
net/socket_backend.hpp SocketBackend (morph::net::) — a WebSocket client IBackend over raw sockets on an IoLoop
net/socket_server.hpp SocketServer — a WebSocket server forwarding messages to RemoteServer

Terminal frontend headers (include/morph/tui/, sources in src/tui/)

Built only when MORPH_BUILD_TUI=ON, as the compiled STATIC library morph::tui over core-cpp's core::tui.

Header Responsibility
tui/backend.hpp Backend (morph::tui::) — ui::IViewBackend over a core::tui::Screen: every widget kind as a core::tui component, laid out in cells. See docs/spec/tui/frontend.md.
tui/frontend.hpp Frontend, FrontendConfig, ShellFactory, frontendOption, kInterruptExitCode — runs an AppSource in a terminal on one caller-driven IoLoop.
tui/loop_executor.hpp LoopExecutor — the IExecutor that runs tasks in later turns of a core::net::EventLoop; the runtime's owner and every handler's callback executor.

Qt integration headers (include/morph/qt/, sources in src/qt/)

Built only when MORPH_BUILD_QT=ON.

Header Responsibility
qt_executor.hpp QtExecutor — posts callables via QMetaObject::invokeMethod
qt_websocket_backend.hpp QtWebSocketBackend — WebSocket client; implements IBackend
qt_websocket_server.hpp QtWebSocketServer — QObject server; forwards messages to RemoteServer

Qt Quick renderer headers (include/morph/qt_quick/, sources in src/qt_quick/)

Built only when MORPH_BUILD_QT_QUICK=ON, as the compiled STATIC library morph::qt_quick with the private QML module MorphUi. The headers hold declarations only.

Header Responsibility
qt_quick/backend.hpp Backend, BackendOptions, CustomWidget, CustomRequest (morph::qt_quick::) — ui::IViewBackend over Qt Quick: every widget kind as an item made from its MorphUi component. See docs/spec/qt_quick/backend.md.
qt_quick/components.hpp Components, ComponentFailure — bundle components verified by digest and compiled in a contained engine, host components by version, and the restyle map
qt_quick/frontend.hpp Frontend, FrontendConfig, ShellFactory, frontendOption, usableHere — runs an AppSource in a Qt Quick window on Qt's event loop. See docs/spec/qt_quick/frontend.md.
qt_quick/scheduler.hpp QtScheduler — reactive::Scheduler on QTimers, with the owner current in every callback

Known limitations

RemoteServer must be heap-allocated

RemoteServer::handle() captures shared_from_this() to prevent a use-after-free if the worker pool outlives the server. This means RemoteServer must be created via std::make_shared<morph::backend::RemoteServer>(...). Constructing it on the stack and calling handle() will throw std::bad_weak_ptr at runtime.

NetworkMonitor callbacks must not block

The probe and the callbacks (onOffline, onOnline) run inline on the I/O loop's thread. A blocking call inside one stalls every probe, socket and timer on that loop. Keep them short — set an atomic flag or post to an executor — and run reconnect sequencing (ReconnectCoordinator) and replay (SyncWorker) elsewhere. See docs/spec/offline/offline.md, "NetworkMonitor callback constraint".

onBackendChanged runs on the model's strand, not inside switchBackend

LocalBackend posts each change-aware model's onBackendChanged() onto that model's strand, so it never overlaps an execute() on the same model and needs no lock of its own. It runs after switchBackend has returned, on a pool thread: a model that wants to reach the bridge from it posts to the bridge's owner.

A null callback executor drops the callback (but not the orphan log)

The cbExec pointer on CompletionState should be set before setValue / setException is called (or before attachThen / attachOnError if the state is already ready). If cbExec is null when a callback would fire, that callback is silently dropped — no error is raised. This is enforced by the Completion<T> constructor, which accepts an IExecutor*; the hazard only arises when using CompletionState directly (an internal type).

An abandoned error, however, is not silenced by a null executor: onErrAttached (the flag that suppresses the destructor's orphan log) is only set when an executor actually exists to deliver the handler. With a null executor the error handler is never posted, so onErrAttached stays false and ~CompletionState still logs the exception through the orphan logger rather than losing it.

MainThreadExecutor::runFor is a pump, not a flush

runFor(timeout) runs queued tasks and, while time remains, blocks for newly posted ones; it returns only when the deadline is reached, whether or not the queue drained. Tasks still queued then stay for the next call. A test that waits for a completion pumps in short slices until its condition holds.

Versioning & compatibility

morph is 0.1.0 and pre-1.0: per Semantic Versioning's own rule for major version 0, any release may still change anything without a major bump. The semantic-versioning, stable-surface, and deprecation-window commitment morph makes starting at 1.0 is fully specified in docs/spec/VERSIONING.md — this section is only a pointer, not a substitute. In short: the per-topic public namespaces above (everything outside a detail namespace) are the stable surface; because morph is a set of headers and static libraries there is no shared-object ABI to preserve, so the promise is source compatibility, checked against both a symbol's signature and its docs/spec/ documented behavior.

Key design decisions

Decision Rationale
Mostly-header core library Templates and the macro-sensitive core headers stay in headers, so consumers compile them under their own configuration; what does not depend on that is compiled once into morph::morph, a static library. core-cpp's static modules are built with it, as are the optional frontends, client and Qt transport.
core-cpp for timers, base64 and wakeup One implementation shared with the other Contour Terminal projects, including a WebAssembly subset whose host-driven loop runs TimeoutScheduler on the browser's main thread.
Per-topic public namespaces with per-topic detail:: Minimal public surface — callers see only what they need; internals are clearly walled off.
A strand per ModelId Parallelism across models; serial within one model — model authors write single-threaded code.
Completion<T> not std::future<T> Callbacks marshal to a specific executor; futures do not.
IBackend in detail:: Users never type the interface — they construct concrete backends and let conversion happen implicitly.
HandlerBinding with atomic currentId Handlers survive backend replacement without re-registering from application code.
LogLevel : uint8_t Minimises storage; 5 levels fit in one byte.
Glaze for JSON Reflects aggregate types automatically; no hand-written serialisation per action.
CompletionState<T> internal only Keeps the public API free of state-handling machinery; implementation can change without breaking callers.
JSON Envelope wire protocol Self-describing and forward-compatible (unknown keys ignored); carries a callId so async WebSocket replies can be correlated back to pending Completion objects.
Subscriptions keyed on the result type, scoped to the instance A subscriber is a renderer: it names the state it draws, not the actions that produce it, so a new action never breaks it. Scoping to the instance is what lets two screens on one shared model see each other's work without a query-invalidation vocabulary.
ActionValidator<A> is action-typed, not model-typed Different actions on the same model have different readiness requirements; pinning the predicate to the action keeps GUI code oblivious to model internals.
set<auto FieldPtr>(value) over set<Action>(&Action::f, value) Member-pointer NTTP encodes both the action type and the field type; the call site stays terse without losing type safety.
Rational wire codec canonicalises on read Wire input is untrusted; every deserialised value passes the reducing constructor, so invariants hold no matter what a client sends.
One optionality: empty state inside Quantity Drafts and lab data genuinely have "no value yet" with the unit still known; a second std::optional wrapper would split one concept across two types.
Units are enum NTTPs with app-defined algebra Mixing units is a compile error and result units are deduced, while morph stays domain-agnostic — the application owns the enum, metadata, and algebra.
required derived from types + one opt-out list The same declaration drives the schema, the client submit gate, and validate() — required-ness cannot drift between server and GUI.
Combo-box options declared as an action reference (Choice<T, "ListX">) Option lists are living data, so the single source is the action that serves them; the schema only carries the reference, and every renderer resolves it through the same dispatch seam as submits.
Strict (non-clamping) datetime codec Rational clamps hostile input because any int pair still denotes a value; a malformed timestamp denotes nothing — rejecting the read beats fabricating an epoch.

Non-goals

What morph deliberately does not build, and why. morph is a UI bridge with one server that owns neither the store nor the tooling; each row below follows from that.

Not building Why
Entity metamodel / naked objects (Causeway) morph's unit is the action, deliberately. Rows plus row-bound actions already are an object UI; what is missing is metadata on the row, not a second parallel metamodel.
Server-authoritative per-instance action availability ("see it, use it, do it") A real gap — a client cannot ask "may I?" before invoking an action — but not worth the surface area it would add.
Paging / sorting contract on view schemas views.md already records "no server-side query language" as a non-goal; paging stays a field on the query action.
Result-type presentation metadata (money, enum labels, badge severity) Every GUI controller hand-writes a toMap() projection. Genuine duplication, but it is a forms-layer concern, not a model-layer one.
Field- and row-level permissions (Jmix, Causeway SecMan) They own the ORM and the whole app; morph owns a seam. Per-principal schema redaction would break the one-cached-schema-per-type design. The model is the right place, and bank's loadOwned guard shows it works.
BPM / BPMN engine (Axelor, Jmix) A process engine without a store is meaningless, and morph does not own the store.
Grain call filters / interceptor pipeline (Orleans) morph already has validator + authorizer + observe + journal on every dispatch path. No observed friction.
Clustering, silos, placement, grain versioning, stateless workers, distributed ACID transactions (Orleans) morph is a UI bridge with one server, not a distributed runtime.
Managed streams with cursors and checkpoints (Orleans) Instance subscriptions are best-effort and unbuffered by design; durability here is a distributed-runtime concern.
Reporting engine (BIRT, JasperReports), ORM + schema migration, IDE Studio Out of identity. morph owns neither the store nor the tooling.
Runtime custom fields / dynamic attributes (Axelor, Jmix) Hard against compile-time reflection, and no observed need.
REST / GraphQL facade, blob transfer, tabular export, multi-tenancy discriminator Plausible, no observed need. Revisit when one exists.