registry.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
#include <algorithm>
#include <atomic>
#include <cassert>
#include <concepts>
#include <cstdint>
#include <cstdio>
#include <cstdlib>
#include <functional>
#include <glaze/glaze.hpp>
#include <map>
#include <memory>
#include <morph/util/rational.hpp>
#include <stdexcept>
#include <string>
#include <string_view>
#include <type_traits>
#include <typeindex>
#include <unordered_map>
#include <utility>
#include <vector>
 
#include "../forms/field_errors.hpp"
#include "../forms/forms.hpp"
#include "detail/result_walker.hpp"
#include "model.hpp"
#include "payload_schema.hpp"
#include "profiler.hpp"
 
namespace morph::model {
 
/// @brief Traits specialisation that maps a model type to its string type-id.
///
/// Users must specialise this (or use `BRIDGE_REGISTER_MODEL`) before the model
/// can be registered with a backend.
/// @tparam Model Concrete model type.
template <typename Model>
struct ModelTraits;
 
/// @brief Traits specialisation that maps an action type to its id, JSON codec,
///        and result type.
///
/// Users must specialise this (or use `BRIDGE_REGISTER_ACTION`).
/// @tparam Action Concrete action type.
template <typename Action>
struct ActionTraits;
 
// ── The registration-phase latch ────────────────────────────────────────────
//
// The three process-level registries (`ActionDispatcher`,
// `ModelRegistryFactory`, `ActionExecuteRegistry`) are unsynchronised
// `unordered_map`s, and `docs/spec/core/registry.md` ("Thread safety") states
// the precondition that makes that safe as a hard constraint: writes happen
// during static initialisation, and after `main()` begins the maps are
// read-only. Nothing detected a violation. A `dlopen`ed module registering on
// a worker thread while another thread dispatches is undefined behaviour whose
// only symptom is intermittent map corruption.
//
// This latch makes that precondition checkable. It starts open, closes when
// the program says the registration phase is over, and the three `register*Once`
// helpers assert against it. Closing is one-way: nothing re-opens it outside
// `detail::reopenRegistrationPhaseForTesting`.
 
namespace detail {
 
/// @brief The process-wide registration-phase flag.
///
/// A function-local `static` in an `inline` function, for the reason the
/// registries themselves are: one instance per process with no header-level
/// static-ordering problem. `std::atomic` because the whole point is that it
/// is read from the threads the constraint is about.
///
/// @return Reference to the process-wide flag; `true` once the registration
///         phase has closed.
[[nodiscard]] inline std::atomic<bool>& registrationPhaseFlag() noexcept {
    static std::atomic<bool> closed{false};
    return closed;
}
 
}  // namespace detail
 
/// @brief Declares the registration phase over: no further registration with
///        the process-level registries is permitted.
///
/// Call it once, early in `main()`, before any thread is spawned. From that
/// point a debug build asserts on every `registerModelOnce` /
/// `registerActionOnce` / `registerActionExecutorOnce` — which is what a
/// `dlopen`ed module's static initialisers run — turning the spec's hard
/// constraint from advice into a diagnosable failure.
///
/// Calling it is optional: a **debug** build also closes the latch by itself on
/// the first read of a process-level registry (`ActionDispatcher::dispatch`,
/// `ModelRegistryFactory::create`, `ActionExecuteRegistry::execute` on the
/// singleton instance), so an application that never calls this still gets the
/// check from its first dispatch onwards. Calling it explicitly closes the
/// window between `main()` and that first dispatch.
///
/// Idempotent, thread-safe, and a no-op after the first call.
inline void closeRegistrationPhase() noexcept {
    detail::registrationPhaseFlag().store(true, std::memory_order_release);
}
 
/// @brief Reports whether the registration phase has closed.
///
/// @return `true` once `closeRegistrationPhase` has been called, or — in a
///         debug build only — once a process-level registry has been read.
///         Release builds do not close the latch on their own, so this answers
///         `false` there until the application closes it explicitly.
[[nodiscard]] inline bool registrationPhaseClosed() noexcept {
    return detail::registrationPhaseFlag().load(std::memory_order_acquire);
}
 
namespace detail {
 
/// @brief Re-opens the registration-phase latch. **Test-only.**
///
/// The latch is one-way by design: an application that re-opens it has
/// re-created exactly the hazard the latch exists to catch. It is exposed for
/// morph's own suite, which must run a registrar on both sides of the latch in
/// one process to prove the assertion fires for the right reason.
inline void reopenRegistrationPhaseForTesting() noexcept {
    registrationPhaseFlag().store(false, std::memory_order_release);
}
 
/// @brief Closes the latch on the first read of a process-level registry.
///
/// Debug builds only — in a release build this is an empty function and the
/// latch closes only when the application calls `closeRegistrationPhase`. That
/// asymmetry is deliberate: the auto-close exists to feed an `assert`, which a
/// release build has already compiled out, and `ActionDispatcher::dispatch` is
/// a per-request path that should not pay for a check nothing reads.
///
/// @param isProcessRegistry `true` when the registry being read is the
///        process-level singleton. A locally constructed `ActionDispatcher` (as
///        several tests own) is not covered by the constraint and must not
///        close the latch for the whole program.
inline void noteRegistryRead([[maybe_unused]] bool isProcessRegistry) noexcept {
#ifndef NDEBUG
    if (isProcessRegistry) {
        ::morph::model::closeRegistrationPhase();
    }
#endif
}
 
/// @brief A `(modelId, actionId)` pair as a pair of views, for lookups.
///
/// The type a caller looks a registry entry up *with*. The stored key is a
/// pair of `std::string`s, because the registry owns its ids; a caller has
/// `string_view`s, because every id it can name arrives as one — a wire
/// envelope's decoded field, or a `constexpr` `ModelTraits<M>::typeId()`.
/// Materialising the stored type just to hash it would charge every lookup up
/// to two `std::string` constructions, so the hash and equality below are
/// transparent and this is what `find()` is given.
using PairKeyView = std::pair<std::string_view, std::string_view>;
 
/// @brief Transparent hash functor for `(modelId, actionId)` registry keys.
///
/// Shared between `ActionDispatcher` (server-side dispatch) and
/// `ActionExecuteRegistry` (client-side generic-execute) since their key types
/// are structurally identical.
///
/// Both overloads reduce to the same `string_view` body rather than calling
/// `std::hash<std::string>` on one side and `std::hash<std::string_view>` on
/// the other. Those two happen to agree on every standard library morph
/// builds against, but "happens to agree" is not a property a heterogeneous
/// lookup may rest on: if they ever disagreed, a transparent `find()` would
/// hash into the wrong bucket and report a registered action as unknown, with
/// no diagnostic anywhere. Routing both through one body makes the agreement
/// structural instead of coincidental.
struct PairKeyHash {
    /// @brief Marks the functor transparent, enabling heterogeneous lookup.
    using is_transparent = void;
 
    /// @brief Combines the hashes of `key.first` and `key.second`.
    /// @param key The pair of views to hash.
    /// @return The combined hash value.
    [[nodiscard]] std::size_t operator()(PairKeyView key) const noexcept {
        std::size_t seed = std::hash<std::string_view>{}(key.first);
        // NOLINTNEXTLINE(readability-magic-numbers, cppcoreguidelines-avoid-magic-numbers)
        seed ^= std::hash<std::string_view>{}(key.second) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
        return seed;
    }
 
    /// @brief Hashes a stored key by viewing it.
    /// @param key The stored pair to hash.
    /// @return The combined hash value.
    [[nodiscard]] std::size_t operator()(const std::pair<std::string, std::string>& key) const noexcept {
        return (*this)(PairKeyView{key.first, key.second});
    }
};
 
/// @brief Transparent equality functor for `(modelId, actionId)` registry keys.
///
/// The second half of what `unordered_map`'s heterogeneous lookup needs: a
/// transparent hash alone is not enough, the equality must accept the lookup
/// type too.
struct PairKeyEqual {
    /// @brief Marks the functor transparent, enabling heterogeneous lookup.
    using is_transparent = void;
 
    /// @brief Compares two keys of any mix of owned and viewed halves.
    /// @tparam LhsT Left-hand pair type; both halves must view as `string_view`.
    /// @tparam RhsT Right-hand pair type; both halves must view as `string_view`.
    /// @param lhs Left-hand key.
    /// @param rhs Right-hand key.
    /// @return `true` if both halves compare equal as text.
    template <typename LhsT, typename RhsT>
    [[nodiscard]] bool operator()(const LhsT& lhs, const RhsT& rhs) const noexcept {
        return std::string_view{lhs.first} == std::string_view{rhs.first} &&
               std::string_view{lhs.second} == std::string_view{rhs.second};
    }
};
 
/// @brief Concept satisfied by actions that expose a `bool validate() const` member.
///
/// Drives the default `ActionValidator::ready(...)` path: if the action supplies
/// a `validate()` method, it is called automatically; otherwise readiness defaults
/// to `true` (matching the existing one-shot semantics).
template <typename A>
concept HasValidate = requires(const A& act) {
    { act.validate() } -> std::convertible_to<bool>;
};
 
}  // namespace detail
 
/// @brief Per-action readiness predicate deciding whether an action may execute.
///
/// Enforced on every dispatch path that reaches `Model::execute` (see
/// `ValidationError` below for the sites), and consulted by
/// `morph::flows::FlowSession::set<>` (forms/flows.hpp) to decide whether an
/// in-progress draft is complete enough to fire.
///
/// Resolution order (highest-priority first):
///   1. **Explicit specialisation** of `ActionValidator<Action>` — typically via
///      `BRIDGE_REGISTER_VALIDATOR(Action, fn)`. Wins over everything.
///   2. **`bool validate() const`** member on `Action` — picked up automatically.
///      Co-locates the predicate with the data it inspects; preferred when you
///      own the action type.
///   3. **Default** — returns `true`, matching one-shot semantics (the first
///      `set<>` lands and the action fires).
///
/// Validation is intentionally a property of the **action**, not the model:
/// different actions on the same model have different readiness requirements,
/// and keeping the predicate next to the action keeps the GUI side oblivious
/// to model internals.
///
/// @code
/// struct FormAction {
///     double a;
///     double b;
///     double c;
///     bool validate() const { return a != 0.0 && b != 0.0 && c != 0.0; }
/// };
/// // No macro needed; ActionValidator<FormAction>::ready calls .validate() automatically.
/// @endcode
///
/// @tparam Action Concrete action type.
template <typename Action>
struct ActionValidator {
    /// @brief Returns `true` if the action is in a state that should be executed.
    ///
    /// Auto-detects a `bool validate() const` member on @p action via the
    /// `morph::model::detail::HasValidate` concept. Falls back to `true`.
    ///
    /// @param action Draft action whose readiness is being checked.
    /// @return `true` if the action should fire, `false` to keep collecting fields.
    static constexpr bool ready(const Action& action) {
        if constexpr (detail::HasValidate<Action>) {
            return action.validate();
        } else {
            (void)action;
            return true;
        }
    }
};
 
/// @brief Thrown when a model id, or a model's action id, is registered for a type other than the one that already
///        holds it.
///
/// Two registrations of one id would otherwise leave whichever static initialiser ran last, an order the link
/// decides: two applications linked into one process could each reach the other's model. Registering the same type
/// again, as every translation unit including a `BRIDGE_REGISTER_*` header does, is not a conflict. The static-init
/// helpers report it and abort, because there is no caller to catch it before `main`.
struct DuplicateRegistrationError : std::logic_error {
    /// @brief Constructs the error naming the id and both types.
    /// @param what     `model` or `action`.
    /// @param taken    The id, `model` or `model/action`.
    /// @param held     The type that holds it.
    /// @param incoming The type registered again under it.
    DuplicateRegistrationError(std::string_view what, std::string_view taken, std::type_index held,
                               std::type_index incoming)
        : std::logic_error("morph: the " + std::string{what} + " id `" + std::string{taken} +
                           "` is registered for two types (" + held.name() + " and " + incoming.name() +
                           "); give each type its own id") {}
};
 
namespace detail {
 
/// @brief Records that @p name belongs to @p type, refusing it for any other type.
/// @param types    The ids registered so far, with their types.
/// @param what     `model` or `action`, for the message.
/// @param name     The id.
/// @param type     The type registering it.
/// @throws DuplicateRegistrationError when another type holds @p name.
template <typename Map, typename Key>
// NOLINTNEXTLINE(bugprone-easily-swappable-parameters): a kind, then the id; swapped, only the message reads oddly.
void claimId(Map& types, std::string_view what, Key const& key, std::string_view name, std::type_index type) {
    auto const [iter, inserted] = types.try_emplace(key, type);
    if (!inserted && iter->second != type) {
        throw DuplicateRegistrationError{what, name, iter->second, type};
    }
}
 
/// @brief Ends a static-init registration that conflicts: there is no caller to catch it before `main`.
/// @param error The conflict.
[[noreturn]] inline void abortRegistration(DuplicateRegistrationError const& error) noexcept {
    static_cast<void>(std::fputs(error.what(), stderr));
    static_cast<void>(std::fputc('\n', stderr));
    std::abort();
}
 
}  // namespace detail
 
/// @brief Thrown when a decoded action fails `ActionValidator<Action>::ready(...)`
///        on a server-side or local execution path, before `Model::execute` runs.
///
/// Raised by `morph::model::detail::ActionDispatcher::registerAction`'s runner
/// (the server dispatch path used by `RemoteServer`, every remote and Qt
/// WebSocket topology) and by `Bridge::executeVia`'s `localOp` (the in-process
/// path used by `LocalBackend`) — the two sites an action can reach ungated: the
/// runner by a hand-built envelope from an untrusted remote client, `localOp` by
/// an action built by hand and handed to `BridgeHandler::execute<Action>()`. An
/// action that *did* pass `morph::flows::FlowSession::set<>`'s gate
/// (forms/flows.hpp) or the type-erased `executeJson` gate
/// (`ActionExecuteRegistry::registerAction`) still reaches whichever of the two
/// its topology dispatches through — `FlowSession::fireStep` goes through the
/// handler like any other caller — and is simply re-checked there.
///
/// Deriving from `std::runtime_error` means existing `catch (const std::exception&)`
/// handling — e.g. `RemoteServer::dispatchExecute`'s strand catch, which turns any
/// thrown exception into an `err` reply — keeps working unchanged; callers that care
/// can `catch`/`dynamic_cast` the specific type instead.
struct ValidationError : std::runtime_error {
    /// @brief Constructs the error with a message of the form
    ///        `"action failed validation: <modelType>/<actionType>"`.
    /// @param modelType  `ModelTraits<Model>::typeId()` of the target model.
    /// @param actionType `ActionTraits<Action>::typeId()` of the rejected action.
    ValidationError(std::string_view modelType, std::string_view actionType)
        : std::runtime_error("action failed validation: " + std::string{modelType} + "/" + std::string{actionType}) {}
};
 
/// @brief Thrown when an action executed and its mutation committed, but the
///        framework could not finish reporting that success.
///
/// Raised by the two sites that actually run `Model::execute` — the server
/// dispatch path (`morph::model::detail::ActionDispatcher::registerAction`'s
/// runner) and the in-process path (`Bridge::executeVia`'s `localOp`,
/// `bridge.hpp`) — for anything that fails *after* `Model::execute` returned:
/// serialising the result (`ActionTraits<Action>::resultToJson`, which throws
/// `detail::ParseError`) and appending the journal entry (a
/// `journal::IActionLog` whose `append` could not reach its backend, which
/// `action_log.hpp` requires it to signal by throwing).
///
/// It exists because those failures are not execution failures and must not be
/// reported as one. An action whose journal append throws has already changed
/// the model; telling the caller the action was rejected invites a retry of a
/// write that landed, and recording `journal::Outcome::Failed` for it puts a
/// permanent lie in the audit trail, attributed to the action rather than to
/// the infrastructure that failed. So a post-execution failure is a distinct
/// type carrying a distinct message: the action ran, the reporting did not.
///
/// No journal entry is written when the throw came from `resultToJson`. A
/// `Succeeded` entry carries the result by definition (see
/// `docs/spec/journal/journal.md`, `LogEntry::result`), and there is none to
/// carry; the caller is told instead, which is the only channel left.
///
/// Deriving from `std::runtime_error` keeps existing `catch (const
/// std::exception&)` handling working — `RemoteServer::dispatchExecute`'s
/// strand catch still turns this into an `err` reply, and `LocalBackend`'s
/// still rejects the `Completion` — while a caller that wants to tell a
/// committed-but-unrecorded action from a rejected one can catch this type and
/// read `result()`.
class ActionRecordingError : public std::runtime_error {
public:
    /// @brief Constructs the error with a message of the form
    ///        `"action executed but was not recorded: <cause>"`.
    /// @param result JSON-encoded result of the committed action, or `""` when
    ///               serialising it is what failed.
    /// @param cause  `std::exception::what()` from the failure that stopped the
    ///               recording.
    ActionRecordingError(std::string result, std::string cause)
        : std::runtime_error("action executed but was not recorded: " + cause),
          _result(std::move(result)),
          _cause(std::move(cause)) {}
 
    /// @brief Returns the committed action's JSON-encoded result.
    /// @return The result JSON, or `""` when `resultToJson` is what threw.
    [[nodiscard]] const std::string& result() const noexcept { return _result; }
 
    /// @brief Returns the underlying failure's message, without this type's prefix.
    /// @return `std::exception::what()` of the failure that stopped the recording.
    [[nodiscard]] const std::string& cause() const noexcept { return _cause; }
 
private:
    std::string _result;
    std::string _cause;
};
 
/// @brief Whether an action's executions are recorded to an attached action log.
///
/// A strong type instead of a bare `bool` so registration call sites read as
/// intent (`Loggable::No`) rather than an unexplained `false`.
enum class Loggable : std::uint8_t { No, Yes };
 
/// @brief Per-action policy deciding how repeated executions are checkpointed
///        into a durable action log.
///
/// Deliberately minimal for now — only `coalesce` exists, and it has no
/// registration macro yet. Specialise directly for the rare action where only
/// the latest occurrence should survive a checkpoint (e.g. a form-field edit
/// fired repeatedly via `morph::flows::FlowSession::set<>`); every other action
/// defaults to `false`, meaning every execution is treated as a distinct, permanent fact
/// (the right default for anything resembling a business event).
/// @tparam Action Concrete action type.
template <typename Action>
struct ActionLogPolicy {
    /// @brief If `true`, a checkpoint keeps only the most recent entry per
    ///        `(modelType, entityKey, actionType)`. If `false` (default), every
    ///        entry survives.
    static constexpr bool coalesce = false;
};
 
namespace detail {
 
/// @brief Concept satisfied by `ActionTraits<A>` specialisations that expose a
///        `Loggable loggable` static member.
///
/// Lets `actionLoggable()` default to `Loggable::Yes` for hand-written
/// `ActionTraits` specialisations (as used in tests) that predate this member,
/// instead of requiring every existing specialisation to be updated.
template <typename A>
concept HasLoggableFlag = requires {
    { ActionTraits<A>::loggable } -> std::convertible_to<Loggable>;
};
 
/// @brief Returns `ActionTraits<A>::loggable` if present, otherwise `Loggable::Yes`.
///
/// Logging every action by default (opt out via the macro's 4th argument) means
/// new actions are captured automatically; only actions that are known to be
/// pure queries need to opt out explicitly.
template <typename A>
constexpr Loggable actionLoggable() {
    if constexpr (HasLoggableFlag<A>) {
        return ActionTraits<A>::loggable;
    } else {
        return Loggable::Yes;
    }
}
 
/// @brief Concept satisfied by `ActionTraits<A>` specialisations that expose a
///        `payloadSchema()` static member.
///
/// Both `BRIDGE_REGISTER_ACTION` and `BRIDGE_REGISTER_ACTION_FOR_CLIENT`
/// generate one; a hand-written `ActionTraits` does not have to.
template <typename A>
concept HasPayloadSchema = requires {
    { ActionTraits<A>::payloadSchema() } -> std::convertible_to<std::string_view>;
};
 
/// @brief Returns `ActionTraits<A>::payloadSchema()` if the specialisation
///        provides one, otherwise the empty string.
///
/// **The fingerprint is a property of the codec, not of the action type.** The
/// macro-generated codecs read and write through Glaze's reflection, so their
/// JSON shape *is* the struct's reflected shape and
/// `morph::model::payloadFingerprint` describes it exactly. A hand-written
/// `ActionTraits` may map its struct to entirely different JSON -- it may not
/// even be a reflectable type (`test_client_execute_deadline.cpp` registers an
/// anonymous-namespace struct, which Glaze's traditional reflection cannot name
/// at all) -- so deriving a "shape" from the struct would describe something
/// that never reaches the journal.
///
/// Empty means *unstamped*: entries for such an action are recorded without a
/// fingerprint and replay treats them exactly as every build before the
/// fingerprint existed did (see `journal::UnstampedPayloadPolicy`). A
/// hand-written specialisation that wants the guarantee opts in by defining its
/// own `payloadSchema()`.
///
/// @tparam A Action type.
/// @return The fingerprint, or `""` when the specialisation provides none.
template <typename A>
inline std::string actionPayloadSchema() {
    if constexpr (HasPayloadSchema<A>) {
        return std::string{ActionTraits<A>::payloadSchema()};
    } else {
        return {};
    }
}
 
/// @brief The request id of the session installed on the calling thread, or
///        empty when there is none: the text that links one dispatch's
///        profiler zones across the threads it crosses.
/// @return A view into the installed session, valid while it stays installed.
[[nodiscard]] inline std::string_view currentRequestId() noexcept {
    auto const* const ctx = ::morph::session::current();
    return ctx != nullptr ? std::string_view{ctx->requestId} : std::string_view{};
}
 
/// @brief Records one executed action's *successful* outcome to @p holder's
///        attached action log, if any (`IModelHolder::recordIfAttached` is
///        itself a no-op with none attached).
///
/// Shared by the two sites that actually execute an action and must record
/// the result either way: `ActionDispatcher::registerAction`'s runner
/// (server-side dispatch, this file) and `Bridge::executeVia`'s local op
/// (`bridge.hpp`, the in-process `LocalBackend` path). Paired with
/// `recordActionFailure` below rather than a single outcome-plus-two-strings
/// function, so a call site cannot transpose `result`/`error` into the wrong
/// slot for the outcome it is actually recording. `seq`, `entityKey`,
/// `principal`, and `timestampMs` are left at their `LogEntry` defaults —
/// `recordIfAttached` overwrites `entityKey`/`principal`/`timestampMs`
/// itself, and the sink assigns `seq` on append.
/// @param holder     Model holder to record against.
/// @param modelType  `ModelTraits<Model>::typeId()`.
/// @param actionType `ActionTraits<Action>::typeId()`.
/// @param payload    JSON-encoded request (`ActionTraits<Action>::toJson`).
/// @param schema     `actionPayloadSchema<Action>()`, computed once by the caller.
/// @param result     JSON-encoded result (`ActionTraits<Action>::resultToJson`).
inline void recordActionSuccess(IModelHolder& holder, std::string modelType, std::string actionType,
                                std::string payload, std::string schema, std::string result) {
    MORPH_ZONE("recordActionSuccess");
    holder.recordIfAttached(::morph::journal::LogEntry{
        .seq = 0,
        .modelType = std::move(modelType),
        .entityKey = {},
        .actionType = std::move(actionType),
        .payload = std::move(payload),
        .schema = std::move(schema),
        .result = std::move(result),
        .outcome = ::morph::journal::Outcome::Succeeded,
        .error = {},
        .principal = {},
        .timestampMs = 0,
    });
}
 
/// @brief Records one executed action's *failed* outcome to @p holder's
///        attached action log, if any. See `recordActionSuccess` above (its
///        paired counterpart) for the shared rationale.
/// @param holder     Model holder to record against.
/// @param modelType  `ModelTraits<Model>::typeId()`.
/// @param actionType `ActionTraits<Action>::typeId()`.
/// @param payload    JSON-encoded request (`ActionTraits<Action>::toJson`).
/// @param schema     `actionPayloadSchema<Action>()`, computed once by the caller.
/// @param error      `std::exception::what()`.
inline void recordActionFailure(IModelHolder& holder, std::string modelType, std::string actionType,
                                std::string payload, std::string schema, std::string error) {
    MORPH_ZONE("recordActionFailure");
    holder.recordIfAttached(::morph::journal::LogEntry{
        .seq = 0,
        .modelType = std::move(modelType),
        .entityKey = {},
        .actionType = std::move(actionType),
        .payload = std::move(payload),
        .schema = std::move(schema),
        .result = {},
        .outcome = ::morph::journal::Outcome::Failed,
        .error = std::move(error),
        .principal = {},
        .timestampMs = 0,
    });
}
 
/// @brief Exception thrown when JSON serialisation or deserialisation fails.
struct ParseError : std::runtime_error {
    using std::runtime_error::runtime_error;
};
 
/// @brief Write options for an action's/result's own JSON body: identical to
///        `morph::wire::detail::EscapingWriteOpts`, applied one layer down.
///
/// The envelope codec already escapes ASCII control bytes (see
/// `docs/spec/core/wire.md`, "Control bytes in string fields"); the action and
/// result bodies it carries are serialized here, separately, and need exactly
/// the same treatment for exactly the same two reasons. With the option off,
/// a raw `0x00`–`0x1F` in any caller-supplied string field of an action makes
/// the body invalid JSON that the peer's own reader rejects — and, when the
/// same string also contains an escaped character, glaze's chunked fast path
/// silently rewrites such a byte as two `0x00`s, destroying the payload in a
/// way that still decodes. Action bodies are pure caller data (a paste's
/// content, a message, a filename), so this is if anything more exposed than
/// the envelope was.
///
/// Deliberately duplicated rather than reused from `morph::wire`: the action
/// codec belongs to the model layer and must not acquire a dependency on the
/// transport layer's header just to share a four-line option struct.
///
/// Applies to writing only — glaze's reader already accepts `\\uXXXX`.
struct EscapingWriteOpts : glz::opts {
    /// @brief Emit control bytes as `\\uXXXX` rather than raw.
    // NOLINTNEXTLINE(readability-identifier-naming) — the name is glaze's, not ours; the option is matched by name.
    bool escape_control_characters = true;
};
 
/// @brief Everything a peer that is **not** linked against an action's C++ needs
///        in order to build, and to sanity-check, a payload for it.
///
/// Assembled once per action type (see `actionDescription`) and served verbatim
/// by `RemoteServer`'s `"schemas"` envelope kind. Two consumers, one document:
/// a generic client renders `schema` as a form, and `RemoteServer`'s optional
/// `PayloadCompleteness::RequireDeclaredFields` gate reads `required` — so the
/// rule the server enforces is by construction the rule it published.
struct ActionDescription {
    /// @brief `morph::forms::schemaJson<A>()` with two extra top-level keys
    ///        merged in: `x-payloadFingerprint` and `x-payloadShape`.
    ///
    /// Empty only when schema generation produced nothing usable at all.
    std::string schema;
 
    /// @brief Wire names of every member the schema's `required` array lists.
    ///
    /// Derived from the served document rather than recomputed, so a field the
    /// gate insists on is exactly a field the schema told the client about.
    std::vector<std::string> required;
};
 
/// @brief Builds `A`'s `ActionDescription`.
///
/// The merge is done over a DOM rather than by splicing text: the fingerprint
/// and shape are ordinary JSON string values, and glaze's writer is the only
/// thing here that knows how to escape them. On a DOM read failure the raw
/// `morph::forms::schemaJson<A>()` text is served unannotated and `required` is
/// left empty — a description facility degrades, it does not throw.
///
/// @tparam A Action type.
/// @return The assembled description.
template <typename A>
[[nodiscard]] inline ActionDescription buildActionDescription() {
    ActionDescription desc;
    desc.schema = ::morph::forms::schemaJson<A>();
    // u64 number mode for the same reason mergeSchemaExtras uses it: the
    // schema carries int64/uint64 bounds a double-only DOM would round on the
    // way back out.
    glz::generic_u64 dom{};
    if (glz::read_json(dom, desc.schema) || !dom.is_object()) {
        return desc;
    }
    if (dom.contains("required") && dom["required"].is_array()) {
        for (const auto& name : dom["required"].get_array()) {
            if (name.is_string()) {
                desc.required.push_back(name.template get<std::string>());
            }
        }
    }
    dom["x-payloadFingerprint"] = payloadFingerprint<A>();
    dom["x-payloadShape"] = payloadShapeString<A>();
    std::string merged;
    // COVERAGE GAP, documented not closed: glz::write_json never fails on
    // this always-well-formed `dom` (every field just came from a
    // successful glz::read_json a few lines above, plus two plain string
    // insertions) -- closing this branch would need forging a failure
    // inside glaze's own serializer over data this function produces
    // itself, not something reachable through schemaJson<A>()'s return
    // text the way the two branches above this one are. No trigger found.
    //
    // WARNING for whoever next measures this file's coverage: this line
    // can read as "covered" in a merged/aggregated coverage report even
    // though the branch above is genuinely never taken by any real test.
    // tests/test_wire_schemas.cpp's WireSchemasUnsatisfiable
    // fixture (a different, deliberately-closed finding) throws partway
    // through this function, after llvm-cov's per-function body-region
    // counter has already incremented for that instantiation -- llvm-cov
    // then synthesizes phantom nonzero branch counts for every top-level
    // `if` in that one instantiation, including this one, and
    // aggregate_lcov_branches.py sums arm counts across instantiations, so
    // the phantom contribution folds into this line's aggregate. Verify via
    // `llvm-cov show -show-instantiations=true` scoped to a real,
    // non-throwing instantiation before trusting a "this line is covered"
    // reading here.
    if (!glz::write_json(dom, merged)) {
        desc.schema = std::move(merged);
    }
    return desc;
}
 
/// @brief `A`'s `ActionDescription`, computed once per type per process.
///
/// A function-local static, exactly like `morph::forms::schemaJson<A>()`'s own
/// cache: `RemoteServer` may answer `"schemas"` on any pool thread, and the
/// maps `ActionDispatcher` fills at static-init time are read-only afterwards,
/// so the only mutable state involved has to be the one C++ already guarantees
/// is initialised exactly once. A throw from `buildActionDescription` (an
/// action whose `formRules` are self-contradicting — see
/// `forms::UnsatisfiableFormError`) leaves the static uninitialised and a later
/// call retries, rather than serving a half-built document.
///
/// @tparam A Action type.
/// @return Reference to the process-lifetime description for `A`.
template <typename A>
[[nodiscard]] inline const ActionDescription& actionDescription() {
    static const ActionDescription kDesc = buildActionDescription<A>();
    return kDesc;
}
 
// Forward declarations so instance() methods inside the classes can reference them.
inline class ActionDispatcher& defaultDispatcher();
inline class ModelRegistryFactory& defaultRegistry();
 
/// @brief Registry that maps (modelId, actionId) pairs to type-erased runner functions.
///
/// Used by `RemoteServer` to dispatch incoming JSON requests without knowing the
/// concrete model or action types at the call site.
class ActionDispatcher {
public:
    /// @brief Type-erased action runner: deserialises, executes, and serialises the result.
    using Runner = std::function<std::string(IModelHolder&, std::string_view)>;
 
    /// @brief What `evaluate` answers for one action body.
    struct Evaluation {
        /// @brief The action, reconciled and recomputed, as `ActionTraits<Action>::toJson` writes it.
        std::string body;
        /// @brief `forms::fieldErrors` of the recomputed action: field name to message.
        std::map<std::string, std::string, std::less<>> errors;
        /// @brief Whether `dispatch` would hand this body to `Model::execute`: its `Quantity` fields are within
        ///        their units' bounds and `ActionValidator<Action>::ready` holds.
        ///
        /// Can hold while `errors` is not empty: a required field is reported even for an action whose validator
        /// does not require it, and `dispatch` checks only the validator.
        bool ready = false;
    };
 
    /// @brief Type-erased evaluator: deserialises, reconciles, recomputes and checks, without executing.
    using Evaluator = Evaluation (*)(std::string_view);
 
    /// @brief Receives the outcome of an asynchronous dispatch: the JSON result,
    ///        or the exception (with an empty result).
    using DispatchDone = std::function<void(std::string, std::exception_ptr)>;
 
    /// @brief Type-erased runner for a Task handler: deserialises, starts the
    ///        handler on the model's strand, and hands the serialised result or
    ///        the exception to its last argument when the Task completes.
    using AsyncRunner = void (*)(IModelHolder&, std::string_view,
                                 const std::shared_ptr<::morph::exec::detail::TaskResumer>&, ::core::async::StopToken,
                                 DispatchDone);
 
    /// @brief Registers a runner for `(Model, Action)` under the given string ids.
    ///
    /// This is the single execution site used by `RemoteServer` (every remote and
    /// Qt WebSocket topology) — `Model::execute()` runs here, on whichever process
    /// actually owns @p holder. Before `Model::execute` runs, the runner reconciles
    /// any `Quantity` fields to their declared precision
    /// (`morph::forms::reconcileDeclaredPrecision`), overwrites any declared
    /// computed fields from their inputs (`morph::forms::recomputeAll`,
    /// `forms.hpp`), and enforces `ActionValidator<Action>::ready(action)`,
    /// throwing `ValidationError` when it returns `false` — the same checks the
    /// client bridge dispatch path (`ActionExecuteRegistry::registerAction`,
    /// `bridge.hpp`) already performs. If a `journal::IActionLog` is attached to
    /// @p holder (via `IModelHolder::attachActionLog`) and `Action` is loggable
    /// (the default), the executed action is recorded automatically -- on a
    /// successful `Model::execute` with `outcome = Outcome::Succeeded` and the
    /// JSON result, and equally on a thrown `std::exception` (a validation
    /// failure, a rejected write) with `outcome = Outcome::Failed` and
    /// `error = what()`, `result` empty. An exception from `Model::execute`
    /// propagates unchanged after the `Failed` entry is recorded.
    ///
    /// `Outcome::Failed` means the model rejected the action, and nothing else:
    /// only `Model::execute` can produce it. Serialising the result and
    /// appending the entry both run after the model's mutation has committed,
    /// and both can throw -- `resultToJson` raises `detail::ParseError`, and a
    /// sink that could not reach its backend is required to say so by throwing
    /// (`journal/action_log.hpp`). Those surface as `ActionRecordingError`, so
    /// a committed write is never reported to the caller, or filed in the
    /// audit trail, as a rejected one.
    ///
    /// Every recorded entry is stamped with `payloadFingerprint<Action>()` in
    /// `LogEntry::schema`, and the same fingerprint is filed under
    /// `(modelId, actionId)` for `schemaFor()` to hand back to the type-erased
    /// replay path. That pair is what lets `journal::replay()` notice that the
    /// shape which wrote an entry is not the shape it is about to decode it
    /// with -- see `docs/spec/journal/journal.md`, "Payload schema fingerprint".
    /// @throws ValidationError if the decoded action fails `ActionValidator<Action>::ready`.
    /// @throws ActionRecordingError if the action executed but its result could
    ///         not be serialised or its journal entry could not be appended.
    template <typename Model, typename Action>
    void registerAction(std::string_view modelId, std::string_view actionId) {
        Key key{std::string{modelId}, std::string{actionId}};
        detail::claimId(_actionTypes, "action", key, key.first + "/" + key.second, std::type_index{typeid(Action)});
        ActionEntry& entry = _actions[std::move(key)];
        if constexpr (isTaskHandler<decltype(std::declval<Model&>().execute(std::declval<Action&>()))>) {
            entry.asyncRunner = &runTaskHandler<Model, Action>;
            entry.runner = [](IModelHolder&, std::string_view) -> std::string {
                throw std::logic_error{
                    "ActionDispatcher::dispatch: this action's handler returns core::async::Task and cannot complete "
                    "synchronously; dispatch it with dispatchAsync"};
            };
        } else {
            entry.runner = &runHandler<Model, Action>;
        }
        entry.evaluator = &evaluateAction<Model, Action>;
        entry.coalesce = ActionLogPolicy<Action>::coalesce;
        entry.schema = detail::actionPayloadSchema<Action>();
        // Deliberately a thunk, not the description itself: registration runs
        // at static-init time, where `buildActionDescription`'s throw path (an
        // action with self-contradicting `formRules`) would abort the process
        // before `main` rather than surface as an `err` reply. The thunk defers
        // the whole computation to the first caller who asks.
        entry.describe = []() -> const ActionDescription& { return actionDescription<Action>(); };
    }
 
private:
    /// @brief Decodes @p payloadJson into an `Action` and applies every gate
    ///        that must run before any handler sees it.
    /// @tparam Model  Concrete model type.
    /// @tparam Action Concrete action type.
    /// @param payloadJson The action's JSON body.
    /// @return The decoded, reconciled, recomputed and validated action.
    /// @throws ValidationError if the action fails `ActionValidator<Action>::ready`.
    template <typename Model, typename Action>
    static Action prepareAction(std::string_view payloadJson) {
        MORPH_ZONE("ActionDispatcher::prepareAction");
        auto action = ActionTraits<Action>::fromJson(payloadJson);
        // Retag any Quantity fields to their declared precision so a
        // hand-built wire payload matches the schema's advertised
        // x-decimalPlaces, exactly as the client bridge dispatch path
        // (ActionExecuteRegistry::registerAction, bridge.hpp) already does.
        // No-op for actions with no Quantity members. See
        // docs/spec/forms/forms.md.
        ::morph::forms::reconcileDeclaredPrecision(action);
        // Pre-decode wire validation seam: reject a Quantity field whose
        // engaged value falls outside its unit's declared bounds
        // (UnitTraits<E>::bounds), before the action's own validate()
        // (a business-rule check) ever runs. No-op for actions with no
        // Quantity members, or whose units declare no bounds(). See
        // docs/spec/forms/forms.md, "Pre-decode wire validation".
        ::morph::forms::enforceQuantityBounds(action);
        // Overwrite any computed fields from their declared inputs. This is
        // the true server-side execution site for every remote and Qt
        // WebSocket topology (RemoteServer -> ActionDispatcher::dispatch) --
        // the one path a hand-built wire envelope reaches directly,
        // bypassing every client-side gate. A tampered computed value on
        // the wire is discarded here, before the validator check and
        // Model::execute run. No-op for actions with no computedFields. See
        // docs/spec/forms/forms.md.
        ::morph::forms::recomputeAll(action);
        // Enforce the action's validator on the server dispatch path — the
        // one path an untrusted remote client can drive directly with a
        // hand-built envelope, bypassing the client-side gates
        // (morph::flows::FlowSession::set<> and
        // ActionExecuteRegistry::registerAction). ActionValidator<Action>::ready
        // auto-detects a `bool validate() const` member and defaults to
        // `true` for actions with no validator, so this is a no-op for
        // unvalidated actions (zero behavior change) and a hard gate for
        // validated ones. The exception propagates out of this lambda to
        // ActionDispatcher::dispatch's caller (RemoteServer::dispatchExecute's
        // strand catch turns it into an `err` reply).
        if (!ActionValidator<Action>::ready(action)) {
            throw ValidationError{ModelTraits<Model>::typeId(), ActionTraits<Action>::typeId()};
        }
        return action;
    }
 
    /// @brief The evaluator of `(Model, Action)`: the gates `prepareAction` applies, made as checks rather than
    ///        refusals, with no `Model::execute`, no journal entry and no model instance.
    /// @tparam Model  Concrete model type.
    /// @tparam Action Concrete action type.
    /// @param payloadJson The action's JSON body.
    /// @return The recomputed body, its field errors and whether `dispatch` would execute it.
    template <typename Model, typename Action>
    static Evaluation evaluateAction(std::string_view payloadJson) {
        MORPH_ZONE("ActionDispatcher::evaluateAction");
        auto action = ActionTraits<Action>::fromJson(payloadJson);
        ::morph::forms::reconcileDeclaredPrecision(action);
        ::morph::forms::recomputeAll(action);
        Evaluation evaluation;
        evaluation.errors = ::morph::forms::fieldErrors(action);
        evaluation.ready =
            !::morph::forms::checkQuantityBounds(action).has_value() && ActionValidator<Action>::ready(action);
        evaluation.body = ActionTraits<Action>::toJson(action);
        return evaluation;
    }
 
    /// @brief The runner of an ordinary handler: prepares the action, runs
    ///        `Model::execute`, journals the outcome and returns the JSON result.
    /// @tparam Model  Concrete model type.
    /// @tparam Action Concrete action type.
    /// @param holder      The model instance.
    /// @param payloadJson The action's JSON body.
    /// @return The JSON-encoded result.
    template <typename Model, typename Action>
    static std::string runHandler(IModelHolder& holder, std::string_view payloadJson) {
        auto action = prepareAction<Model, Action>(payloadJson);
        auto& model = holder.template into<Model>();
        // Model::execute is the only call inside this try, because it is
        // the only one whose failure means the action was rejected. A
        // rejected or throwing execution -- a validation failure, a lost
        // connection, a rejected write -- records Outcome::Failed (when a
        // log is attached and Action is loggable) so it leaves an audit
        // trail rather than silence, and the exception is rethrown
        // unchanged. See docs/spec/journal/journal.md, "Outcome".
// MSVC's C4702 fires on the `return` below for any action whose handler never
// returns -- a test double whose body is a bare `throw`, for instance. The
// warning is correct for that instantiation and wrong as a verdict on this
// statement, which every other instantiation reaches. It is suppressed here
// rather than in each translation unit that instantiates such a handler,
// because the set of those is open-ended: eleven test files already qualify.
#ifdef _MSC_VER
#pragma warning(push)
#pragma warning(disable : 4702)
#endif
        auto result = [&] {
            try {
                return model.execute(action);
            } catch (const std::exception& exc [[maybe_unused]]) {
                if constexpr (detail::actionLoggable<Action>() == Loggable::Yes) {
                    if (holder.hasActionLog()) {
                        detail::recordActionFailure(holder, std::string{ModelTraits<Model>::typeId()},
                                                    std::string{ActionTraits<Action>::typeId()},
                                                    std::string{payloadJson}, detail::actionPayloadSchema<Action>(),
                                                    exc.what());
                    }
                }
                throw;
            }
        }();
#ifdef _MSC_VER
#pragma warning(pop)
#endif
        // Past this point the model's mutation has committed, so neither
        // step below may be reported as an execution failure. Both can
        // still throw -- resultToJson raises ParseError, and a sink that
        // could not reach its backend is required to throw (see
        // journal/action_log.hpp) -- and inside the try above that throw
        // would tell the caller a durable write was rejected and file an
        // Outcome::Failed entry naming the infrastructure fault as the
        // action's own error. ActionRecordingError instead says what is
        // true: the action ran, the reporting of it did not. A throw from
        // resultToJson leaves no entry at all, because a Succeeded entry
        // carries the result and there is none to carry.
        std::string resultJson;
        try {
            resultJson = ActionTraits<Action>::resultToJson(result);
            if constexpr (detail::actionLoggable<Action>() == Loggable::Yes) {
                if (holder.hasActionLog()) {
                    // entityKey/principal/timestampMs are filled in by recordIfAttached.
                    detail::recordActionSuccess(holder, std::string{ModelTraits<Model>::typeId()},
                                                std::string{ActionTraits<Action>::typeId()}, std::string{payloadJson},
                                                detail::actionPayloadSchema<Action>(), resultJson);
                }
            }
        } catch (const std::exception& exc) {
            throw ActionRecordingError{std::move(resultJson), exc.what()};
        }
        return resultJson;
    }
 
    /// @brief The runner of a Task handler: prepares the action, starts the
    ///        handler on the model's strand, and -- when its Task completes --
    ///        journals the outcome and hands the JSON result or the exception to
    ///        @p done. See `docs/spec/core/coroutines.md`.
    /// @tparam Model  Concrete model type.
    /// @tparam Action Concrete action type.
    /// @param holder      The model instance; kept alive by @p done's owner until
    ///                    @p done has run.
    /// @param payloadJson The action's JSON body.
    /// @param executor    The handler's resumer, on the model's strand.
    /// @param token       The stop token the handler observes.
    /// @param done        Called exactly once, on the strand.
    template <typename Model, typename Action>
    // runHandler's decode, validation and journalling, around a Task instead of
    // a call; kept in one piece for the same reason runHandler is.
    // NOLINTNEXTLINE(readability-function-cognitive-complexity)
    static void runTaskHandler(IModelHolder& holder, std::string_view payloadJson,
                               const std::shared_ptr<::morph::exec::detail::TaskResumer>& executor,
                               ::core::async::StopToken token, DispatchDone done) {
        using R = HandlerResultT<decltype(std::declval<Model&>().execute(std::declval<Action&>()))>;
        // Owned here and kept by the completion callback: the handler may take
        // the action by reference, and its frame outlives this call.
        std::shared_ptr<Action> action;
        ::core::async::Task<R> task;
        try {
            action = std::make_shared<Action>(prepareAction<Model, Action>(payloadJson));
            task = holder.template into<Model>().execute(*action);
        } catch (...) {
            done(std::string{}, std::current_exception());
            return;
        }
        detail::startTaskHandler<R>(
            executor, std::move(task), std::move(token),
            [&holder, action, payload = std::string{payloadJson}, done = std::move(done)](
                std::optional<R> result, const std::exception_ptr& error) mutable {
                // `holder` is read only when the action is loggable; this keeps the capture used otherwise.
                static_cast<void>(holder);
                if (error) {
                    // The handler failed, so the action was rejected: recorded
                    // Outcome::Failed, as runHandler records a throw from
                    // Model::execute. A journal write that throws here fails the
                    // call with the handler's own exception still.
                    try {
                        if constexpr (detail::actionLoggable<Action>() == Loggable::Yes) {
                            if (holder.hasActionLog()) {
                                try {
                                    std::rethrow_exception(error);
                                } catch (const std::exception& exc) {
                                    detail::recordActionFailure(holder, std::string{ModelTraits<Model>::typeId()},
                                                                std::string{ActionTraits<Action>::typeId()}, payload,
                                                                detail::actionPayloadSchema<Action>(), exc.what());
                                } catch (...) {  // NOLINT(bugprone-empty-catch): as runHandler
                                    // Not a std::exception: recorded nowhere, as runHandler's
                                    // rethrow leaves such a throw unrecorded.
                                }
                            }
                        }
                    } catch (...) {  // NOLINT(bugprone-empty-catch): the handler's exception is reported
                    }
                    done(std::string{}, error);
                    return;
                }
                // The Task completed, so the model's mutation has committed: as in
                // runHandler, failing to serialise the result or to record it is an
                // ActionRecordingError, never a rejection.
                std::string resultJson;
                try {
                    resultJson = ActionTraits<Action>::resultToJson(*result);
                    if constexpr (detail::actionLoggable<Action>() == Loggable::Yes) {
                        if (holder.hasActionLog()) {
                            detail::recordActionSuccess(holder, std::string{ModelTraits<Model>::typeId()},
                                                        std::string{ActionTraits<Action>::typeId()}, payload,
                                                        detail::actionPayloadSchema<Action>(), resultJson);
                        }
                    }
                } catch (const std::exception& exc) {
                    done(std::string{},
                         std::make_exception_ptr(ActionRecordingError{std::move(resultJson), exc.what()}));
                    return;
                } catch (...) {
                    done(std::string{}, std::current_exception());
                    return;
                }
                done(std::move(resultJson), nullptr);
            });
    }
 
public:
    /// @brief Dispatches an action against @p holder and returns the JSON-encoded result.
    std::string dispatch(std::string_view modelId, std::string_view actionId, IModelHolder& holder,
                         std::string_view payload) {
        MORPH_ZONE("ActionDispatcher::dispatch");
        MORPH_ZONE_TEXT(actionId);
        MORPH_ZONE_TEXT(detail::currentRequestId());
        // A dispatch means the maps are being read, which in the registration
        // model means the registration phase is over. Debug builds only; see
        // `detail::noteRegistryRead`.
        detail::noteRegistryRead(this == &defaultDispatcher());
        // Looked up by view. Building the stored `Key` to hash it would cost
        // two `std::string` constructions per dispatch -- and two heap
        // allocations whenever an id passes the SSO threshold, which
        // `"CreateSwimlane"` (14 characters) misses by one.
        auto iter = _actions.find(detail::PairKeyView{modelId, actionId});
        if (iter == _actions.end()) {
            // The concatenation here is the one string cost left, and it is on
            // the error path only: a dispatch that is about to throw can pay
            // for its own diagnostic.
            throw std::runtime_error("unknown action: " + std::string{modelId} + "/" + std::string{actionId});
        }
        return iter->second.runner(holder, payload);
    }
 
    /// @brief Evaluates a body of `(modelId, actionId)` without running it.
    ///
    /// Decodes @p payload, reconciles its `Quantity` precision, recomputes its computed fields, and reports the
    /// result with its field errors and whether `dispatch` would execute it. No model instance is involved, nothing
    /// is journalled, and nothing changes, so an evaluation can be repeated freely. The answer for a body the
    /// gates refuse is a value, not a throw; only a body that does not decode throws.
    /// @param modelId  The model's registered type id.
    /// @param actionId The action's registered type id.
    /// @param payload  The action's JSON body.
    /// @return The evaluation.
    /// @throws std::runtime_error for an unregistered pair, or a body `ActionTraits<Action>::fromJson` refuses.
    [[nodiscard]] Evaluation evaluate(std::string_view modelId, std::string_view actionId,
                                      std::string_view payload) const {
        MORPH_ZONE("ActionDispatcher::evaluate");
        detail::noteRegistryRead(this == &defaultDispatcher());
        auto iter = _actions.find(detail::PairKeyView{modelId, actionId});
        if (iter == _actions.end()) {
            throw std::runtime_error("unknown action: " + std::string{modelId} + "/" + std::string{actionId});
        }
        return iter->second.evaluator(payload);
    }
 
    /// @brief Dispatches an action against @p holder and hands its JSON result,
    ///        or its exception, to @p done -- at once for an ordinary handler,
    ///        when its Task completes for a Task handler.
    ///
    /// Called on the model's strand. A Task handler is started there and
    /// resumed through @p executor; see `docs/spec/core/coroutines.md`.
    /// @param modelId  Model type-id.
    /// @param actionId Action type-id.
    /// @param holder   The model instance; must stay alive until @p done has run.
    /// @param payload  The action's JSON body.
    /// @param executor The handler's resumer, on the model's strand.
    /// @param token    The stop token a Task handler observes.
    /// @param done     Called exactly once, with the result or the exception.
    void dispatchAsync(std::string_view modelId, std::string_view actionId, IModelHolder& holder,
                       std::string_view payload, const std::shared_ptr<::morph::exec::detail::TaskResumer>& executor,
                       ::core::async::StopToken token, DispatchDone done) {
        MORPH_ZONE("ActionDispatcher::dispatchAsync");
        MORPH_ZONE_TEXT(detail::currentRequestId());
        const ActionEntry* entry = nullptr;
        try {
            detail::noteRegistryRead(this == &defaultDispatcher());
            auto iter = _actions.find(detail::PairKeyView{modelId, actionId});
            if (iter == _actions.end()) {
                throw std::runtime_error("unknown action: " + std::string{modelId} + "/" + std::string{actionId});
            }
            entry = &iter->second;
        } catch (...) {
            done(std::string{}, std::current_exception());
            return;
        }
        if (entry->asyncRunner != nullptr) {
            entry->asyncRunner(holder, payload, executor, std::move(token), std::move(done));
            return;
        }
        std::string result;
        try {
            result = entry->runner(holder, payload);
        } catch (...) {
            done(std::string{}, std::current_exception());
            return;
        }
        done(std::move(result), nullptr);
    }
 
    /// @brief Returns whether `(modelId, actionId)` has a Task handler, which
    ///        only `dispatchAsync` can run, rather than an ordinary one, which
    ///        `dispatch` runs too.
    ///
    /// Lets a caller that already holds everything an ordinary dispatch needs
    /// call `dispatch` directly, and pay for what a Task handler needs -- a
    /// resumer, shared state for its callback -- only when there is one.
    /// @return False for an unknown pair, which `dispatch` then reports.
    [[nodiscard]] bool dispatchesAsync(std::string_view modelId, std::string_view actionId) const {
        auto iter = _actions.find(detail::PairKeyView{modelId, actionId});
        return iter != _actions.end() && iter->second.asyncRunner != nullptr;
    }
 
    /// @brief Returns whether `(modelId, actionId)` was registered with
    ///        `ActionLogPolicy<Action>::coalesce == true`.
    ///
    /// Used by `journal::SessionLog::checkpoint()` to decide, from the type-erased
    /// `LogEntry` stream, which entries collapse to their latest occurrence.
    /// Unknown pairs (never registered) default to `false` — every entry kept.
    [[nodiscard]] bool coalesce(std::string_view modelId, std::string_view actionId) const {
        auto iter = _actions.find(detail::PairKeyView{modelId, actionId});
        return iter != _actions.end() && iter->second.coalesce;
    }
 
    /// @brief Returns the payload fingerprint `(modelId, actionId)` was
    ///        registered with, or an empty string if the pair is unregistered.
    ///
    /// This is the type-erased half of the journal's payload-evolution check:
    /// `registerAction` knows the concrete `Action` and can compute
    /// `payloadFingerprint<Action>()`; `journal::replay()` sees only strings on
    /// a `LogEntry` and needs to ask for the current build's fingerprint by id.
    /// The empty return is not an error -- an entry naming an unregistered
    /// action fails at `dispatch()` with "unknown action" a moment later, which
    /// is the better diagnostic for that case.
    ///
    /// @param modelId  Model type-id.
    /// @param actionId Action type-id.
    /// @return The registered fingerprint, or `""` if the pair is unregistered.
    [[nodiscard]] std::string schemaFor(std::string_view modelId, std::string_view actionId) const {
        auto iter = _actions.find(detail::PairKeyView{modelId, actionId});
        return iter == _actions.end() ? std::string{} : iter->second.schema;
    }
 
    /// @brief Returns the `{actionType: schema}` document for every action
    ///        registered under @p modelId.
    ///
    /// The wire's answer to `"schemas"` (`wire::makeSchemas`). Action ids are
    /// emitted in sorted order so two calls — and two servers built from the
    /// same sources — produce byte-identical documents; `_describe` is an
    /// unordered map, whose iteration order is not a contract.
    ///
    /// A model type with no registered actions yields `{}` rather than an
    /// error: "this type exposes no actions" and "this type does not exist"
    /// are not distinguishable here (`ActionDispatcher` never sees a model
    /// type that registered no action at all), and inventing a distinction
    /// would tell an unauthenticated prober which type ids are real.
    ///
    /// @param modelId Model type-id to describe.
    /// @return The `{actionType: schema}` JSON object.
    /// @throws morph::forms::UnsatisfiableFormError if one of the model's
    ///         actions declares `formRules` no submission could satisfy —
    ///         propagated from `morph::forms::schemaJson`, which decides that
    ///         at generation time.
    [[nodiscard]] std::string schemasJson(std::string_view modelId) const {
        std::vector<std::string_view> actionIds;
        for (const auto& [key, entry] : _actions) {
            if (key.first == modelId) {
                actionIds.emplace_back(key.second);
            }
        }
        std::ranges::sort(actionIds);
        std::string out{"{"};
        bool first = true;
        for (std::string_view const actionId : actionIds) {
            if (!first) {
                out += ',';
            }
            first = false;
            // The id is a C++ string literal from BRIDGE_REGISTER_ACTION, but
            // it reaches a client as JSON, so it is written as JSON rather
            // than pasted between hand-written quotes.
            std::string quoted;
            (void)glz::write_json(std::string{actionId}, quoted);
            out += quoted;
            out += ':';
            const auto& desc = _actions.find(detail::PairKeyView{modelId, actionId})->second.describe();
            out += desc.schema.empty() ? "{}" : desc.schema;
        }
        out += '}';
        return out;
    }
 
    /// @brief Returns the wire names `(modelId, actionId)`'s served schema
    ///        marks `required`, or `nullptr` when there is no such list.
    ///
    /// The read side of `RemoteServer`'s optional
    /// `PayloadCompleteness::RequireDeclaredFields` gate. `nullptr` means
    /// *nothing to check* — the pair is unregistered, or its schema could not
    /// be generated at all — never *nothing is required*: an action whose
    /// description cannot be produced never published a requirement, so there
    /// is no published rule for the gate to enforce.
    ///
    /// @param modelId  Model type-id.
    /// @param actionId Action type-id.
    /// @return Pointer to the required-field list, or `nullptr`.
    [[nodiscard]] const std::vector<std::string>* requiredFieldsFor(std::string_view modelId,
                                                                    std::string_view actionId) const {
        auto iter = _actions.find(detail::PairKeyView{modelId, actionId});
        if (iter == _actions.end()) {
            return nullptr;
        }
        try {
            return &iter->second.describe().required;
        } catch (const std::exception&) {
            return nullptr;
        }
    }
 
    /// @brief The model type-ids @p actionId is registered under.
    ///
    /// An action id names one action, but the pair registered is
    /// `(model, action)`, so a server that knows only the action id, as a
    /// record watch's admission does, asks here which model types to
    /// authorize it against.
    ///
    /// @param actionId Action type-id.
    /// @return The model type-ids, sorted; empty for an unregistered action.
    [[nodiscard]] std::vector<std::string> modelsOf(std::string_view actionId) const {
        std::vector<std::string> models;
        for (const auto& [key, entry] : _actions) {
            if (key.second == actionId) {
                models.push_back(key.first);
            }
        }
        std::ranges::sort(models);
        return models;
    }
 
    /// @brief The action type-ids registered under @p modelId.
    ///
    /// What a server authorizes an instance watch against: a principal may
    /// watch an instance of a model only when it may run one of its actions.
    ///
    /// @param modelId Model type-id.
    /// @return The action type-ids, sorted; empty for a model with none.
    [[nodiscard]] std::vector<std::string> actionsOf(std::string_view modelId) const {
        std::vector<std::string> actions;
        for (const auto& [key, entry] : _actions) {
            if (key.first == modelId) {
                actions.push_back(key.second);
            }
        }
        std::ranges::sort(actions);
        return actions;
    }
 
    /// @brief Returns the process-level singleton dispatcher.
    static ActionDispatcher& instance() { return defaultDispatcher(); }
 
private:
    using Key = std::pair<std::string, std::string>;
    /// @brief Returns the process-lifetime `ActionDescription` for one action.
    ///
    /// Type-erased so `schemasJson`/`requiredFieldsFor` can reach a concrete
    /// action's forms schema without knowing its type, and a *thunk* rather
    /// than the value so the cost (and the throw path) lands on the first
    /// caller instead of on static init.
    using Describer = std::function<const ActionDescription&()>;
 
    /// @brief Everything registered under one `(modelId, actionId)` pair.
    ///
    /// One record, not four parallel maps keyed identically. Four maps filled
    /// together by `registerAction` could not go out of step in practice, but
    /// nothing would say so -- and `RemoteServer::handle` reaches this key
    /// three times on the way through one request (`schemaFor`,
    /// `requiredFieldsFor`, `dispatch`). One record makes the lockstep
    /// structural and makes those three one hash each rather than one hash
    /// into a different table each.
    struct ActionEntry {
        /// @brief Type-erased decode/execute/encode runner.
        Runner runner;
        /// @brief The Task handler runner, or null for an ordinary handler.
        AsyncRunner asyncRunner = nullptr;
        /// @brief The evaluator `evaluate` runs.
        Evaluator evaluator = nullptr;
        /// @brief `ActionLogPolicy<Action>::coalesce` as registered.
        bool coalesce = false;
        /// @brief `payloadFingerprint<Action>()` as registered.
        std::string schema;
        /// @brief Thunk yielding the process-lifetime `ActionDescription`.
        Describer describe;
    };
 
    std::unordered_map<Key, ActionEntry, PairKeyHash, PairKeyEqual> _actions;
    /// @brief The action type each `(model, action)` id pair was registered for.
    std::unordered_map<Key, std::type_index, PairKeyHash, PairKeyEqual> _actionTypes;
};
 
/// @brief Registry that creates `IModelHolder` instances by string type-id.
///
/// Used by `RemoteServer` to instantiate models on demand from incoming
/// `"register"` messages.
class ModelRegistryFactory {
public:
    /// @brief Registers a default-construction factory for `Model` under @p modelId.
    ///
    /// Equivalent to `registerModel<Model>(modelId, [] { return
    /// ModelFactory::create<Model>(); })` — the plain default-construction path
    /// every `BRIDGE_REGISTER_MODEL` invocation uses.
    /// @param modelId String id to register the factory under.
    template <typename Model>
    void registerModel(std::string_view modelId) {
        detail::claimId(_types, "model", std::string{modelId}, modelId, std::type_index{typeid(Model)});
        _factories.insert_or_assign(std::string{modelId}, [] { return ModelFactory::create<Model>(); });
    }
 
    /// @brief Registers a custom construction hook for `Model` under @p modelId.
    ///
    /// The per-instance dependency-injection seam for registry-constructed
    /// (`Socket`-mode / `RemoteServer`) models — the equivalent of
    /// `Bridge::HandlerBinding::modelFactory` for the client-side `Local`-mode
    /// path. @p factory runs once per incoming `"register"` message (and once
    /// per fresh shared-instance creation) and may capture arbitrary
    /// per-instance dependencies (an injectable clock, a secondary log handle,
    /// a feature flag) that `Model`'s default constructor cannot reach — this
    /// is also the seam a model whose only constructor takes arguments (i.e.
    /// is not default-constructible at all) needs in order to be registered
    /// for remote/socket instantiation in the first place.
    ///
    /// @p factory returns an owning pointer to a freshly built holder (e.g.
    /// `std::make_unique<ModelHolder<Model>>(...)`), not a bare `Model` — the
    /// caller controls construction end-to-end, including passing
    /// constructor arguments `ModelHolder`'s forwarding constructor accepts.
    /// This overload does **not** auto-attach the process-wide default action
    /// log the way the default-construction overload does: a caller supplying
    /// its own factory is assumed to attach whatever log/identity it needs
    /// (via `IModelHolder::attachActionLog`) inside the closure, or to rely on
    /// `RemoteServer`'s `LogProvider` doing so afterward, exactly as the
    /// default path allows.
    ///
    /// @tparam Model   Concrete model type. Used only to assert (debug builds)
    ///                 that @p factory's returned holder actually reports
    ///                 `typeid(Model)` — @p factory is otherwise free to build
    ///                 the holder however it likes, so nothing *prevents* a
    ///                 mismatched `Model`/@p factory pairing at compile time.
    /// @tparam Factory Callable returning an owning pointer convertible to
    ///                 `std::unique_ptr<IModelHolder>`; deduced from @p factory.
    /// @param modelId  String id to register the factory under.
    /// @param factory  Callable that constructs and returns a fresh holder.
    template <typename Model, typename Factory>
        requires std::invocable<Factory> &&
                 std::convertible_to<std::invoke_result_t<Factory>, std::unique_ptr<IModelHolder>>
    void registerModel(std::string_view modelId, Factory factory) {
        // The same type may replace its factory: that is how a custom construction hook overrides the default.
        detail::claimId(_types, "model", std::string{modelId}, modelId, std::type_index{typeid(Model)});
        _factories.insert_or_assign(std::string{modelId}, [factory = std::move(factory)]() mutable {
            std::unique_ptr<IModelHolder> holder{factory()};
            // misc-static-assert fires here -- `holder` is a runtime
            // `std::unique_ptr` the factory just returned, so nothing in this condition
            // is a constant expression, and the check's own fix does not compile:
            // "static assertion expression is not an integral constant expression /
            // function parameter 'holder' with unknown value cannot be used in a constant
            // expression". Same finding and same suppression as the three
            // `register*Once` helpers below.
            //
            // Note the suppression is needed even though `clang-tidy-diff` analyses
            // changed lines only: without it, the next person to edit this line
            // inherits a red build that is not theirs.
            //
            // Last re-checked at clang-tidy 22.1.8, the version CI pins: the diagnostic
            // still fires and the suggested fix still does not compile. The stamp is here
            // because nothing re-checks it for you -- no script flags a directive that has
            // stopped suppressing anything, and nothing triggers a re-read on a
            // CLANG_VERSION bump. Re-read this when the pin moves; if the finding is gone,
            // delete all four directives together.
            // NOLINTNEXTLINE(misc-static-assert,cert-dcl03-c)
            assert(!holder ||
                   (holder->type() == std::type_index(typeid(Model)) &&
                    "registerModel<Model>(modelId, factory): factory returned a holder for a different type"));
            return holder;
        });
    }
 
    /// @brief Creates a new model holder for the type registered under @p modelId.
    ///
    /// @param modelId Type-id the holder's factory was registered under.
    /// @param primary The instance's stable primary key, or empty for an
    ///                anonymous (unshareable) instance. Forwarded to the new
    ///                holder via `IModelHolder::attachIdentity` immediately
    ///                after construction, which in turn reaches `Model`'s own
    ///                `attachIdentity`, if it declares one matching
    ///                `ModelIdentityAttachable` — a no-op otherwise, and a
    ///                no-op entirely when @p primary is empty. This is what
    ///                lets `RemoteServer` (whose two construction call sites
    ///                already have `env.primary` in scope) tell a keyed
    ///                model its own key once, at construction, rather than
    ///                the model re-deriving it from every action's payload.
    std::unique_ptr<IModelHolder> create(std::string_view modelId, std::string_view primary = {}) {
        // See `ActionDispatcher::dispatch` -- same latch, same reason.
        detail::noteRegistryRead(this == &defaultRegistry());
        auto iter = _factories.find(std::string{modelId});
        if (iter == _factories.end()) {
            throw std::runtime_error("unknown model type: " + std::string{modelId});
        }
        auto holder = iter->second();
        holder->attachIdentity(std::string{primary});
        return holder;
    }
 
    /// @brief Whether a model type is registered under @p modelId.
    /// @param modelId Model type-id.
    /// @return True when `create(modelId)` would find a factory.
    [[nodiscard]] bool contains(std::string_view modelId) const {
        detail::noteRegistryRead(this == &defaultRegistry());
        return _factories.contains(std::string{modelId});
    }
 
    /// @brief Returns the process-level singleton registry.
    static ModelRegistryFactory& instance() { return defaultRegistry(); }
 
private:
    std::unordered_map<std::string, std::function<std::unique_ptr<IModelHolder>()>> _factories;
    /// @brief The model type each id was registered for.
    std::unordered_map<std::string, std::type_index> _types;
};
 
/// @brief Returns the process-level `ActionDispatcher` singleton.
inline ActionDispatcher& defaultDispatcher() {
    static ActionDispatcher inst;
    return inst;
}
 
/// @brief Returns the process-level `ModelRegistryFactory` singleton.
inline ModelRegistryFactory& defaultRegistry() {
    static ModelRegistryFactory inst;
    return inst;
}
 
// The three `register*Once` helpers are `noexcept` while allocating, and that
// is a decision rather than an oversight. Their only caller is the
// initialiser of a namespace-scope variable generated by `BRIDGE_REGISTER_*`,
// and [basic.start.dynamic]/[except.terminate] already call `std::terminate`
// when an exception escapes the dynamic initialisation of a non-local
// variable. Dropping `noexcept` would therefore not change what an OOM during
// static init does -- it would only move the `terminate` one frame outwards
// and cost the callers an unwind path that can never be taken. The `noexcept`
// says what the call site already guarantees. The assertions below are what
// enforce that the call site really is the only one.
 
/// @brief Static-init helper for `BRIDGE_REGISTER_MODEL`.
template <typename Model>
inline bool registerModelOnce(std::string_view modelId) noexcept {
    // clang-tidy's misc-static-assert fires on any `assert(!f())` whose `f` takes no
    // argument, whether or not `f` is constexpr -- and this one loads an atomic.
    // Applying the check's own fix does not compile: `static_assert` on this
    // condition is "static assertion expression is not an integral constant
    // expression / non-constexpr function 'registrationPhaseClosed' cannot be used
    // in a constant expression". The finding is upstream of this repository.
    //
    // Last re-checked at clang-tidy 22.1.8, the version CI pins: the diagnostic
    // still fires and the suggested fix still does not compile. The stamp is here
    // because nothing re-checks it for you -- no script flags a directive that has
    // stopped suppressing anything, and nothing triggers a re-read on a
    // CLANG_VERSION bump. Re-read this when the pin moves; if the finding is gone,
    // delete all four directives together.
    // NOLINTNEXTLINE(misc-static-assert,cert-dcl03-c)
    assert(!::morph::model::registrationPhaseClosed() &&
           "registerModelOnce: registration after the registration phase closed. The process-level "
           "registries are unsynchronised and are read-only once dispatch begins -- registering now "
           "races their internals against concurrent lookups (see docs/spec/core/registry.md, "
           "\"Thread safety\"). Load and register plugin modules before the first dispatch.");
    try {
        ModelRegistryFactory::instance().registerModel<Model>(modelId);
    } catch (DuplicateRegistrationError const& error) {
        detail::abortRegistration(error);
    }
    return true;
}
 
/// @brief Static-init helper for `BRIDGE_REGISTER_ACTION`.
template <typename Model, typename Action>
inline bool registerActionOnce(std::string_view modelId, std::string_view actionId) noexcept {
    // clang-tidy's misc-static-assert fires on any `assert(!f())` whose `f` takes no
    // argument, whether or not `f` is constexpr -- and this one loads an atomic.
    // Applying the check's own fix does not compile: `static_assert` on this
    // condition is "static assertion expression is not an integral constant
    // expression / non-constexpr function 'registrationPhaseClosed' cannot be used
    // in a constant expression". The finding is upstream of this repository.
    //
    // Last re-checked at clang-tidy 22.1.8, the version CI pins: the diagnostic
    // still fires and the suggested fix still does not compile. The stamp is here
    // because nothing re-checks it for you -- no script flags a directive that has
    // stopped suppressing anything, and nothing triggers a re-read on a
    // CLANG_VERSION bump. Re-read this when the pin moves; if the finding is gone,
    // delete all four directives together.
    // NOLINTNEXTLINE(misc-static-assert,cert-dcl03-c)
    assert(!::morph::model::registrationPhaseClosed() &&
           "registerActionOnce: registration after the registration phase closed. The process-level "
           "registries are unsynchronised and are read-only once dispatch begins -- registering now "
           "races their internals against concurrent lookups (see docs/spec/core/registry.md, "
           "\"Thread safety\"). Load and register plugin modules before the first dispatch.");
    try {
        ActionDispatcher::instance().registerAction<Model, Action>(modelId, actionId);
    } catch (DuplicateRegistrationError const& error) {
        detail::abortRegistration(error);
    }
    return true;
}
 
/// @brief Static-init helper for every action registration: records where the
///        action's result holds which reflected aggregates.
///
/// Walks `ActionTraits<Action>::Result`, the unwrapped type, so a `Task<R>`
/// handler contributes `R`. Idempotent per action type: a registration repeated
/// in another translation unit does not walk again. A different action type
/// under an id already taken keeps the first type's slots and lists the id in
/// `actionResultConflicts()`.
/// @tparam Action The action type; `ActionTraits<Action>` must be visible.
/// @param actionId The action's registered type-id.
/// @return Always true, so the result can initialise a namespace-scope variable.
template <typename Action>
inline bool registerActionResultOnce(std::string_view actionId) noexcept {
    // NOLINTNEXTLINE(misc-static-assert,cert-dcl03-c)
    assert(!::morph::model::registrationPhaseClosed() &&
           "registerActionResultOnce: registration after the registration phase closed. The process-level "
           "registries are unsynchronised and are read-only once dispatch begins -- registering now "
           "races their internals against concurrent lookups. Load and register plugin modules before "
           "the first dispatch.");
    std::type_index const action{typeid(Action)};
    auto& entries = mutableActionResultSlots();
    if (auto const existing = entries.find(actionId); existing != entries.end()) {
        if (existing->second.action != action) {
            auto& conflicts = mutableActionResultConflicts();
            if (std::ranges::find(conflicts, actionId) == conflicts.end()) {
                conflicts.emplace_back(actionId);
            }
        }
        return true;
    }
    entries.emplace(
        std::string{actionId},
        ActionResult{.action = action, .resultSlots = walkResult<typename ActionTraits<Action>::Result>()});
    return true;
}
 
/// @brief Static-init helper for `BRIDGE_REGISTER_ACTION`'s generic-execute registration.
///
/// Forward declaration only; the definition is in `bridge.hpp` (after `ActionExecuteRegistry`
/// is visible) to avoid a `registry.hpp` -> `bridge.hpp` include cycle. `bridge.hpp` already
/// includes `registry.hpp`, not the other way round.
///
/// HARD REQUIREMENT: `BRIDGE_REGISTER_ACTION_4` calls this function unconditionally, but only
/// declares it here — it does NOT define it. Any translation unit that invokes
/// `BRIDGE_REGISTER_ACTION` MUST include `<morph/core/bridge.hpp>` (directly or transitively)
/// somewhere in the same translation unit, or the build will fail to link with an unresolved
/// external symbol for this function.
template <typename Model, typename Action>
bool registerActionExecutorOnce(std::string_view modelId, std::string_view actionId) noexcept;
 
/// @brief Link-time canary for `BRIDGE_DECLARE_MODEL` / `BRIDGE_REGISTER_MODEL_SOURCE`.
///
/// `BRIDGE_DECLARE_MODEL(M, NAME)` calls this specialisation behind an
/// `extern template` declaration, which suppresses implicit instantiation of
/// this always-visible, trivial definition and instead demands an *explicit*
/// instantiation elsewhere in the link. `BRIDGE_REGISTER_MODEL_SOURCE(M)` is
/// the only macro that provides one. A model declared via
/// `BRIDGE_DECLARE_MODEL` but never registered via
/// `BRIDGE_REGISTER_MODEL_SOURCE` anywhere in the same binary therefore fails
/// to *link* with an unresolved symbol naming this function, instead of
/// compiling clean and surfacing only as `ModelRegistryFactory::create`'s
/// runtime `"unknown model type"`, far from the cause. The body does nothing;
/// only whether an explicit instantiation for `Model` exists anywhere the
/// linker looks is being tested.
/// @tparam Model Concrete model type a `BRIDGE_DECLARE_MODEL` call named.
template <typename Model>
void modelSourceRegistrationRequired() {}
 
/// @brief Link-time canary for `BRIDGE_DECLARE_ACTION` / `BRIDGE_REGISTER_ACTION_SOURCE`.
///
/// Same mechanism as `modelSourceRegistrationRequired` above, keyed on the
/// `(Model, Action)` pair `BRIDGE_DECLARE_ACTION` and
/// `BRIDGE_REGISTER_ACTION_SOURCE` were each invoked with.
/// @tparam Model  Model type the action belongs to.
/// @tparam Action Concrete action type a `BRIDGE_DECLARE_ACTION` call named.
template <typename Model, typename Action>
void actionSourceRegistrationRequired() {}
 
}  // namespace detail
 
}  // namespace morph::model
 
// NOLINTBEGIN(bugprone-macro-parentheses)
// NOLINTBEGIN(cppcoreguidelines-macro-usage) — registration macros are the intended public API
// The registrars below are namespace-scope `const bool`s whose initialisers run
// before main, inside an unnamed namespace so each translation unit gets its own
// copy — and `BRIDGE_DECLARE_*` places that in a header by design. clang-tidy
// attributes these to every expansion site, so they are suppressed here, once:
//   * bugprone-throwing-static-initialization / cert-err58-cpp -- registration
//     cannot be wrapped in a try block; a throw aborts at start-up, which is the
//     right outcome for a type that cannot be registered.
//   * misc-anonymous-namespace-in-header / cert-dcl59-cpp -- the per-TU copy is
//     the point: it is what ODR-uses the link canary in each including TU.
// NOLINTBEGIN(bugprone-throwing-static-initialization,cert-err58-cpp,misc-anonymous-namespace-in-header,cert-dcl59-cpp)
 
// Keying the generated registrar names on `__COUNTER__` (rather than on the type spelling)
// keeps them valid identifiers regardless of how `M`/`A` are written. A namespace-qualified
// or template type (e.g. `app::models::Report`) would otherwise be pasted directly into the
// identifier, producing invalid tokens like `bridge_model_reg_app::models::Report`.
// `__LINE__` was tried first, but it is only unique *within a single physical file*: two
// headers that each invoke this macro on the same line number (e.g. `card_model.hpp:38` and
// `payment_model.hpp:38`) produce the same identifier once both are `#include`d into one
// translation unit, and since C++ unnamed namespaces are per-TU (not per-file), that is a
// hard redefinition error. `__COUNTER__` increments monotonically for the entire translation
// unit regardless of which file expands it, so it cannot collide this way. The extra
// indirection (`_CAT` calling `_CAT_`) is required so `__COUNTER__` is expanded to its numeric
// value before the paste, rather than being pasted as the literal text "__COUNTER__".
#define BRIDGE_DETAIL_CAT_(a, b) a##b
#define BRIDGE_DETAIL_CAT(a, b) BRIDGE_DETAIL_CAT_(a, b)
 
/// @brief Suppresses the two registrars whose bodies reference a model's
///        constructor/`execute()` definitions (`registerModelOnce`,
///        `registerActionOnce`), for a pure client that dispatches every
///        action to a remote peer and never constructs a model locally.
///
/// A model's constructor and `Model::execute` are ordinary functions the
/// compiler emits a call to inside these registrars' lambda bodies, whether
/// or not that lambda is ever invoked at runtime — so a plain client-only
/// build still forces the linker to resolve them, pulling in implementations
/// (a database driver, a native UI framework, an OS-specific API) the client
/// target may have no link path for at all, and will never call regardless.
/// The executor registrar (`registerActionExecutorOnce`, `bridge.hpp`) routes
/// through `Bridge::executeVia` -> `IBackend::execute` (fully abstract) and
/// needs only the action's JSON codecs plus `Model::execute`'s *declaration*
/// (for `ActionTraits::Result`, via `decltype`) — never its definition — so
/// it is unaffected and always emitted.
///
/// The result-slot registrar (`registerActionResultOnce`) references no model
/// code, but it is suppressed too: it records facts only a process that hosts
/// models serves, and a pure client takes them from the server's catalog.
///
/// Defined on the `morph` target's INTERFACE via the `MORPH_CLIENT_ONLY`
/// CMake option, never per translation unit: two TUs disagreeing on whether a
/// model registers itself would violate ODR. See docs/spec/core/registry.md,
/// "MORPH_CLIENT_ONLY".
///
/// @warning NEVER define this for a process that hosts models (a server, or
/// any `Bridge` running `LocalBackend`) — it silently registers nothing, and
/// the model fails at runtime with "unknown model type" rather than at
/// compile/link time.
/// @brief Emits the `extern template` link requirement `BRIDGE_DECLARE_MODEL`/
///        `BRIDGE_DECLARE_ACTION` place in the header (`MORPH_DETAIL_REQUIRE_SOURCE_LOCAL`),
///        and the matching explicit-instantiation definition
///        `BRIDGE_REGISTER_MODEL_SOURCE`/`BRIDGE_REGISTER_ACTION_SOURCE` place
///        in the `.cpp` (`MORPH_DETAIL_DEFINE_SOURCE_LOCAL`).
///
/// One pair of macros for both the model and action canaries: @p ...
/// carries the whole call expression (`modelSourceRegistrationRequired<M>()`
/// or `actionSourceRegistrationRequired<M, A>()`), passed through the
/// variadic parameter rather than a fixed one so the template argument
/// list's own comma isn't mistaken for a macro-argument separator. @p PREFIX
/// (`MORPH_DETAIL_REQUIRE_SOURCE_LOCAL` only) names the generated variable,
/// same role as the fixed prefixes `MORPH_DETAIL_REGISTER_MODEL_LOCAL`/
/// `MORPH_DETAIL_REGISTER_ACTION_LOCAL` above use directly.
#ifdef MORPH_CLIENT_ONLY
#define MORPH_DETAIL_REGISTER_MODEL_LOCAL(M, NAME)
#define MORPH_DETAIL_REGISTER_ACTION_LOCAL(M, A, NAME)
#define MORPH_DETAIL_REGISTER_RESULT_LOCAL(A)
#define MORPH_DETAIL_REQUIRE_SOURCE_LOCAL(PREFIX, ...)
#define MORPH_DETAIL_DEFINE_SOURCE_LOCAL(...)
#else
// clang-format off
// Hand-aligned: clang-format pulls the short registerModelOnce() call up onto the
// BRIDGE_DETAIL_CAT line and then breaks *inside* the token-paste invocation, which
// also splits the pair apart visually -- MORPH_DETAIL_REGISTER_ACTION_LOCAL has a
// longer right-hand side and so survives untouched. Keep the two parallel by hand.
#define MORPH_DETAIL_REGISTER_MODEL_LOCAL(M, NAME)                                                       \
    namespace {                                                                                          \
    [[maybe_unused]] const bool BRIDGE_DETAIL_CAT(bridge_model_reg_, __COUNTER__) =                      \
        morph::model::detail::registerModelOnce<M>(NAME);                                                \
    }
#define MORPH_DETAIL_REGISTER_ACTION_LOCAL(M, A, NAME)                                                   \
    namespace {                                                                                          \
    [[maybe_unused]] const bool BRIDGE_DETAIL_CAT(bridge_action_reg_, __COUNTER__) =                     \
        morph::model::detail::registerActionOnce<M, A>(morph::model::ModelTraits<M>::typeId(), NAME);    \
    }
#define MORPH_DETAIL_REGISTER_RESULT_LOCAL(A)                                                            \
    namespace {                                                                                          \
    [[maybe_unused]] const bool BRIDGE_DETAIL_CAT(bridge_action_result_reg_, __COUNTER__) =              \
        morph::model::detail::registerActionResultOnce<A>(morph::model::ActionTraits<A>::typeId());      \
    }
#define MORPH_DETAIL_REQUIRE_SOURCE_LOCAL(PREFIX, ...)      \
    extern template void __VA_ARGS__;                       \
    namespace {                                             \
    [[maybe_unused]] const bool BRIDGE_DETAIL_CAT(PREFIX, __COUNTER__) = (__VA_ARGS__, true); \
    }
#define MORPH_DETAIL_DEFINE_SOURCE_LOCAL(...) template void __VA_ARGS__;
// clang-format on
#endif
 
/// @brief `ModelTraits<M>`'s specialisation alone -- the type-only half
///        `BRIDGE_REGISTER_MODEL` and `BRIDGE_DECLARE_MODEL` both build on, so
///        the two cannot drift apart the way two independently hand-written
///        copies could.
/// @param M    Concrete model type.
/// @param NAME String literal used as the type-id.
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_DETAIL_MODEL_TRAITS_ONLY_BODY(M, NAME)                        \
    template <>                                                              \
    struct morph::model::ModelTraits<M> {                                    \
        static constexpr std::string_view typeId() noexcept { return NAME; } \
    };
// clang-format on
 
/// @brief Registers model type @p M with the string id @p NAME.
///
/// Specialises `morph::model::ModelTraits<M>` and registers a factory with the
/// process-level `ModelRegistryFactory` at static-init time — unless
/// `MORPH_CLIENT_ONLY` is defined, in which case that registrar is suppressed
/// (see `MORPH_DETAIL_REGISTER_MODEL_LOCAL`'s doc comment above).
///
/// @param M    Concrete model type.
/// @param NAME String literal used as the type-id.
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_REGISTER_MODEL(M, NAME)            \
    BRIDGE_DETAIL_MODEL_TRAITS_ONLY_BODY(M, NAME) \
    MORPH_DETAIL_REGISTER_MODEL_LOCAL(M, NAME)
// clang-format on
 
/// @brief Declares model type @p M's `ModelTraits<M>` specialisation without
///        registering it -- the header-safe half `BRIDGE_REGISTER_MODEL`
///        decomposes into.
///
/// `BRIDGE_REGISTER_MODEL`'s registrar initialiser instantiates
/// `registerModelOnce<M>` in every translation unit that includes the header
/// it sits in; `BRIDGE_DECLARE_MODEL` emits only the trait specialisation
/// (essentially free to repeat per TU) and defers the actual registration to
/// `BRIDGE_REGISTER_MODEL_SOURCE(M)`, called once in the one `.cpp` that
/// should own it. See docs/spec/core/registry.md, "Moving a registrar out of
/// the header", for when this is worth doing and for the link-time canary
/// this macro emits in @p M's place: a `BRIDGE_DECLARE_MODEL` with no
/// matching `BRIDGE_REGISTER_MODEL_SOURCE` anywhere in the link fails to
/// *link* with an unresolved symbol, rather than compiling clean and only
/// surfacing as `ModelRegistryFactory::create`'s runtime
/// `"unknown model type"`.
///
/// @param M    Concrete model type.
/// @param NAME String literal used as the type-id.
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_DECLARE_MODEL(M, NAME)                        \
    BRIDGE_DETAIL_MODEL_TRAITS_ONLY_BODY(M, NAME)            \
    MORPH_DETAIL_REQUIRE_SOURCE_LOCAL(bridge_model_src_req_, \
                                      morph::model::detail::modelSourceRegistrationRequired<M>())
// clang-format on
 
/// @brief Registers model type @p M -- previously declared via
///        `BRIDGE_DECLARE_MODEL(M, NAME)` -- with the process-level
///        `ModelRegistryFactory` at static-init time.
///
/// Call exactly once, in the one `.cpp` that owns @p M's registration --
/// typically the translation unit that defines @p M's out-of-line members.
/// Requires `morph::model::ModelTraits<M>` already visible (from
/// `BRIDGE_DECLARE_MODEL` or `BRIDGE_REGISTER_MODEL` in an included header)
/// and reads its `typeId()` rather than taking a `NAME` argument again, so the
/// two cannot register under a different string than the one @p M's traits
/// actually report. Suppressed under `MORPH_CLIENT_ONLY`, exactly like the
/// registrar `BRIDGE_REGISTER_MODEL` emits directly.
///
/// @param M Concrete model type, already declared via `BRIDGE_DECLARE_MODEL`.
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_REGISTER_MODEL_SOURCE(M)                                                          \
    MORPH_DETAIL_DEFINE_SOURCE_LOCAL(morph::model::detail::modelSourceRegistrationRequired<M>()) \
    MORPH_DETAIL_REGISTER_MODEL_LOCAL(M, morph::model::ModelTraits<M>::typeId())
// clang-format on
 
/// @brief Registers action type @p A (for model @p M) with the string id @p NAME.
///
/// Specialises `morph::model::ActionTraits<A>` with JSON codec functions and
/// registers the action with the process-level `ActionDispatcher` at static-init time.
/// `BRIDGE_REGISTER_MODEL(M, ...)` must be called before this macro.
///
/// An optional 4th argument overrides whether executions of @p A are recorded to
/// an attached action log (see `IModelHolder::attachActionLog`); omitted, it
/// defaults to `morph::model::Loggable::Yes`, so every action is captured unless
/// explicitly opted out — typically for pure queries:
/// @code
/// BRIDGE_REGISTER_ACTION(AccountModel, Deposit,    "Deposit")                            // logged
/// BRIDGE_REGISTER_ACTION(AccountModel, GetAccount, "GetAccount", morph::model::Loggable::No)  // opt out
/// @endcode
///
/// HARD REQUIREMENT: this macro's expansion unconditionally calls
/// `morph::model::detail::registerActionExecutorOnce<M, A>`, which is only *declared* in
/// `registry.hpp` and *defined* in `<morph/core/bridge.hpp>`. Every translation unit that invokes
/// `BRIDGE_REGISTER_ACTION` MUST include `<morph/core/bridge.hpp>` (directly or transitively) in
/// that same translation unit, or the build will fail to link with an unresolved external
/// symbol for `registerActionExecutorOnce<M, A>`.
///
/// @param M    Concrete model type that handles the action.
/// @param A    Concrete action type.
/// @param NAME String literal used as the action type-id.
/// @param ...  Optional: a `morph::model::Loggable` value (defaults to `Loggable::Yes`).
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_REGISTER_ACTION(...)                                                              \
    BRIDGE_REGISTER_ACTION_PICK(__VA_ARGS__, BRIDGE_REGISTER_ACTION_4, BRIDGE_REGISTER_ACTION_3) \
    (__VA_ARGS__)
// clang-format on
 
/// @brief Registers action type @p A (for model @p M) the same way
///        `BRIDGE_REGISTER_ACTION` does, but names the action's result type
///        @p RESULT explicitly instead of deducing it from
///        `decltype(std::declval<M&>().execute(std::declval<A>()))`.
///
/// `BRIDGE_REGISTER_ACTION`'s `Result` deduction requires `M` to be a
/// **complete type with `execute(A)` declared** at the point of registration
/// — ordinarily the model's own header, which a client must then `#include`
/// (and everything that header transitively pulls in — a persistence mixin's
/// database-driver headers, for a model backed by one) just to compute
/// `ActionTraits<A>::Result`, even under `MORPH_CLIENT_ONLY`, where the
/// client never constructs `M` or calls `M::execute` at all (see
/// `docs/spec/core/registry.md`, "MORPH_CLIENT_ONLY").
///
/// A pure client names @p RESULT directly instead, so @p M can be a
/// lightweight, declaration-only facade type — forward-declared or declaring
/// no members at all — carrying none of the real model's persistence
/// surface. @p M still needs `BRIDGE_REGISTER_MODEL(M, ...)` (for
/// `ModelTraits<M>::typeId()`, itself needing no completeness either) and is
/// used only as `BridgeHandler<M>`'s template tag and dispatch-registry key;
/// nothing on the path a `MORPH_CLIENT_ONLY` build actually calls
/// (`BridgeHandler<M>::execute<A>()`/`executeJson`, routed through
/// `Bridge::executeVia`) reads a member of `M`, so `M` need not be complete
/// at the call site at all.
///
/// A build that does **not** define `MORPH_CLIENT_ONLY` may also use this
/// macro — the emitted `ActionTraits<A>` specialisation is identical either
/// way — but gets none of the header-avoidance benefit unless `M` really is
/// left incomplete, since something in that same link must still define the
/// real model to satisfy `MORPH_DETAIL_REGISTER_MODEL_LOCAL`/
/// `MORPH_DETAIL_REGISTER_ACTION_LOCAL`'s registrars (suppressed only under
/// `MORPH_CLIENT_ONLY`).
///
/// @warning @p RESULT must name the exact same type `BRIDGE_REGISTER_ACTION`
/// would have deduced from the real model's `M::execute(A)`. Nothing checks
/// this — a mismatch is a silent JSON (de)serialisation bug (wrong shape
/// on the wire), not a compile error, since `resultToJson`/`resultFromJson`
/// below are instantiated against whatever @p RESULT names, and the server
/// side (registered separately, from the real model's own header, via the
/// plain `BRIDGE_REGISTER_ACTION`) still serialises the type `M::execute`
/// actually returns.
///
/// @param M      Model type -- may be a declaration-only facade under
///               `MORPH_CLIENT_ONLY`; must be the real, complete model type
///               otherwise (see above).
/// @param A      Concrete action type.
/// @param RESULT The action's result type, named explicitly.
/// @param NAME   String literal used as the action type-id.
/// @param ...    Optional: a `morph::model::Loggable` value (defaults to `Loggable::Yes`).
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_REGISTER_ACTION_FOR_CLIENT(...)                                               \
    BRIDGE_REGISTER_ACTION_FOR_CLIENT_PICK(__VA_ARGS__, BRIDGE_REGISTER_ACTION_FOR_CLIENT_5, \
                                           BRIDGE_REGISTER_ACTION_FOR_CLIENT_4)              \
    (__VA_ARGS__)
// clang-format on
 
/// @cond detail
#define BRIDGE_REGISTER_ACTION_FOR_CLIENT_PICK(_1, _2, _3, _4, _5, NAME, ...) NAME
 
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_REGISTER_ACTION_FOR_CLIENT_4(M, A, RESULT, NAME) \
    BRIDGE_REGISTER_ACTION_FOR_CLIENT_5(M, A, RESULT, NAME, ::morph::model::Loggable::Yes)
// clang-format on
 
/// @brief `ActionTraits<A>`'s specialisation alone -- the type-only half
///        `BRIDGE_DETAIL_ACTION_TRAITS_BODY` decomposes into, reused directly
///        by `BRIDGE_DECLARE_ACTION` for the case that wants the trait
///        specialisation in a header without registering anything there.
///        Parameterised only on how `Result` is spelled, exactly like
///        `BRIDGE_DETAIL_ACTION_TRAITS_BODY` below.
/// @param M           Model type (see each public macro's own doc comment for
///                     the completeness requirement `RESULT_ALIAS` differs on).
/// @param A            Concrete action type.
/// @param RESULT_ALIAS Expression naming the action's result type -- either
///                      `RESULT` (named explicitly) or the `decltype(...)`
///                      deduction from `M::execute(A)`.
/// @param NAME         String literal used as the action type-id.
/// @param LOGGABLE     A `morph::model::Loggable` value.
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_DETAIL_ACTION_TRAITS_ONLY_BODY(M, A, RESULT_ALIAS, NAME, LOGGABLE)                              \
    template <>                                                                                                \
    struct morph::model::ActionTraits<A> {                                                                     \
        using Result = RESULT_ALIAS;                                                                           \
        static constexpr std::string_view typeId() { return NAME; }                                            \
        static constexpr ::morph::model::Loggable loggable = (LOGGABLE);                                       \
        /* Structural fingerprint of the JSON shape the codecs below read and write.  */                       \
        /* Stamped on every journal entry and checked on replay -- see                */                       \
        /* morph::model::payloadFingerprint and docs/spec/journal/journal.md.          */                      \
        static const std::string& payloadSchema() { return ::morph::model::payloadFingerprint<A>(); }          \
        static std::string toJson(const A& action) {                                                           \
            std::string out;                                                                                   \
            /* EscapingWriteOpts, not write_json: a raw control byte in any     */                             \
            /* caller-supplied string field would otherwise produce a body the  */                             \
            /* peer's reader rejects, or be silently mangled by glaze's chunked */                             \
            /* fast path — see its doc comment in registry.hpp.                 */                             \
            if (auto const errCode = glz::write<::morph::model::detail::EscapingWriteOpts{}>(action, out)) {   \
                throw morph::model::detail::ParseError{glz::format_error(errCode, out)};                       \
            }                                                                                                  \
            return out;                                                                                        \
        }                                                                                                      \
        static A fromJson(std::string_view jsonStr) {                                                          \
            A action{};                                                                                        \
            /* null_terminated=false: jsonStr is a caller-supplied view with no      */                        \
            /* guaranteed trailing '\0' (e.g. an execute envelope's `body`) — see    */                        \
            /* the identical fix + rationale on morph::wire::decode (wire.hpp).      */                        \
            static constexpr glz::opts kLenientRead{.null_terminated = false, .error_on_unknown_keys = false}; \
            /* The codec boundary for an action payload: morph::wire carries `body` as                         \
               an opaque string and never parses it, so this is the first and only                             \
               place a Rational inside it is decoded. A Rational decode cannot fail --                         \
               it clamps what it cannot represent -- so {"num":5,"den":0,"dp":2} would                         \
               otherwise arrive as a plausible 5/1 that no model-level validate() could                        \
               recognise as altered. Deciding that a silently-altered payload is a                             \
               protocol violation belongs here, where we know the bytes came off a wire. */                    \
            ::morph::math::WireClampScope const clampedRationals;                                              \
            if (auto const errCode = glz::read<kLenientRead>(action, jsonStr)) {                               \
                throw morph::model::detail::ParseError{glz::format_error(errCode, jsonStr)};                   \
            }                                                                                                  \
            if (clampedRationals.clamped() != 0) {                                                             \
                throw morph::model::detail::ParseError{                                                        \
                    "action body contains a Rational that cannot be represented exactly"};                     \
            }                                                                                                  \
            return action;                                                                                     \
        }                                                                                                      \
        static std::string resultToJson(const Result& result) {                                                \
            std::string out;                                                                                   \
            /* EscapingWriteOpts: see toJson() above — a result body carries    */                             \
            /* caller data back (a paste's content, a fetched record) and needs */                             \
            /* the identical treatment.                                          */                            \
            if (auto const errCode = glz::write<::morph::model::detail::EscapingWriteOpts{}>(result, out)) {   \
                throw morph::model::detail::ParseError{glz::format_error(errCode, out)};                       \
            }                                                                                                  \
            return out;                                                                                        \
        }                                                                                                      \
        static Result resultFromJson(std::string_view jsonStr) {                                               \
            Result result{};                                                                                   \
            /* null_terminated=false: see the identical fix on fromJson() above. */                            \
            static constexpr glz::opts kLenientRead{.null_terminated = false, .error_on_unknown_keys = false}; \
            if (auto const errCode = glz::read<kLenientRead>(result, jsonStr)) {                               \
                throw morph::model::detail::ParseError{glz::format_error(errCode, jsonStr)};                   \
            }                                                                                                  \
            return result;                                                                                     \
        }                                                                                                      \
    };
// clang-format on
 
/// @brief The registrar blocks `BRIDGE_DETAIL_ACTION_TRAITS_BODY` appends
///        after `BRIDGE_DETAIL_ACTION_TRAITS_ONLY_BODY`'s trait
///        specialisation, factored out so `BRIDGE_REGISTER_ACTION_SOURCE` can
///        emit exactly the same registrars from a `.cpp`, without
///        repeating the trait specialisation `BRIDGE_DECLARE_ACTION` already
///        placed in the header.
///
/// There are three: the dispatcher's runner (`registerActionOnce`), the
/// result's slots (`registerActionResultOnce`), both suppressed under
/// `MORPH_CLIENT_ONLY`, and the generic executor
/// (`registerActionExecutorOnce`), always emitted.
///
/// Reads `morph::model::ActionTraits<A>::typeId()` rather than taking a
/// `NAME` parameter, so a `BRIDGE_DECLARE_ACTION`/`BRIDGE_REGISTER_ACTION_SOURCE`
/// pair cannot register under a different string than the one @p A's traits
/// specialisation actually reports -- there is only one place `NAME` is
/// spelled, in whichever macro declared the traits.
/// @param M Model type that handles the action.
/// @param A Concrete action type; `morph::model::ActionTraits<A>` must already
///          be visible.
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_DETAIL_ACTION_REGISTRARS(M, A)                                                            \
    MORPH_DETAIL_REGISTER_ACTION_LOCAL(M, A, morph::model::ActionTraits<A>::typeId())                    \
    MORPH_DETAIL_REGISTER_RESULT_LOCAL(A)                                                                \
    namespace {                                                                                          \
    [[maybe_unused]] const bool BRIDGE_DETAIL_CAT(bridge_action_exec_reg_, __COUNTER__) =                \
        morph::model::detail::registerActionExecutorOnce<M, A>(morph::model::ModelTraits<M>::typeId(),   \
                                                               morph::model::ActionTraits<A>::typeId()); \
    }
// clang-format on
 
/// @brief Shared body for `ActionTraits<A>`'s specialisation plus its
///        registrars -- everything `BRIDGE_REGISTER_ACTION_4` and
///        `BRIDGE_REGISTER_ACTION_FOR_CLIENT_5` expand to alike, parameterised
///        only on how `Result` is spelled. Composes
///        `BRIDGE_DETAIL_ACTION_TRAITS_ONLY_BODY` (the type) with
///        `BRIDGE_DETAIL_ACTION_REGISTRARS` (the registrars) -- the same
///        two pieces `BRIDGE_DECLARE_ACTION`/`BRIDGE_REGISTER_ACTION_SOURCE`
///        emit separately, in a header and a `.cpp` respectively.
///
/// `BRIDGE_REGISTER_ACTION_4` deduces `Result` from `M::execute(A)`, which
/// requires `M` complete at the call site; `BRIDGE_REGISTER_ACTION_FOR_CLIENT_5`
/// takes `RESULT_ALIAS` as an explicit type instead, so `M` may stay
/// declaration-only (see `BRIDGE_REGISTER_ACTION_FOR_CLIENT`'s doc comment).
/// That one line is the only difference between the two public macros; every
/// other member here is byte-identical between them.
/// @param M           Model type (see each public macro's own doc comment for
///                     the completeness requirement `RESULT_ALIAS` differs on).
/// @param A            Concrete action type.
/// @param RESULT_ALIAS Expression naming the action's result type -- either
///                      `RESULT` (named explicitly) or the `decltype(...)`
///                      deduction from `M::execute(A)`.
/// @param NAME         String literal used as the action type-id.
/// @param LOGGABLE     A `morph::model::Loggable` value.
#define BRIDGE_DETAIL_ACTION_TRAITS_BODY(M, A, RESULT_ALIAS, NAME, LOGGABLE)  \
    BRIDGE_DETAIL_ACTION_TRAITS_ONLY_BODY(M, A, RESULT_ALIAS, NAME, LOGGABLE) \
    BRIDGE_DETAIL_ACTION_REGISTRARS(M, A)
 
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_REGISTER_ACTION_FOR_CLIENT_5(M, A, RESULT, NAME, LOGGABLE) \
    BRIDGE_DETAIL_ACTION_TRAITS_BODY(M, A, RESULT, NAME, LOGGABLE)
// clang-format on
/// @endcond
 
/// @cond detail
#define BRIDGE_REGISTER_ACTION_PICK(_1, _2, _3, _4, NAME, ...) NAME
 
#define BRIDGE_REGISTER_ACTION_3(M, A, NAME) BRIDGE_REGISTER_ACTION_4(M, A, NAME, ::morph::model::Loggable::Yes)
 
/// `Result` deduction shared by `BRIDGE_REGISTER_ACTION_4` and
/// `BRIDGE_DECLARE_ACTION_4` -- both need `M` complete with `execute(A)`
/// declared for the same reason, spelled once so the two cannot drift.
/// Wrapped in `HandlerResultT` so a `core::async::Task<R>`-returning handler
/// resolves to `R` on both paths alike; without that, a declare-only header
/// and its out-of-line registration would disagree on the action's result
/// type for every coroutine handler.
#define BRIDGE_DETAIL_DEDUCED_ACTION_RESULT(M, A) \
    ::morph::model::HandlerResultT<decltype(std::declval<M&>().execute(std::declval<A>()))>
 
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_REGISTER_ACTION_4(M, A, NAME, LOGGABLE) \
    BRIDGE_DETAIL_ACTION_TRAITS_BODY(M, A, BRIDGE_DETAIL_DEDUCED_ACTION_RESULT(M, A), NAME, LOGGABLE)
// clang-format on
/// @endcond
 
/// @brief Declares action type @p A's `ActionTraits<A>` specialisation
///        without registering it -- the header-safe half `BRIDGE_REGISTER_ACTION`
///        decomposes into.
///
/// Same 3-or-4-argument shape as `BRIDGE_REGISTER_ACTION` (an optional
/// trailing `Loggable`) and the same `Result`-deduction requirement -- `M`
/// must be complete with `execute(A)` *declared* at this point, though (unlike
/// `BRIDGE_REGISTER_ACTION_SOURCE` below) not necessarily *defined*, since
/// nothing this macro emits calls it. Pair with
/// `BRIDGE_REGISTER_ACTION_SOURCE(M, A)` in the one `.cpp` that should
/// actually register @p A -- see `BRIDGE_DECLARE_MODEL`'s doc comment for why,
/// and docs/spec/core/registry.md, "Moving a registrar out of the header", for
/// the measured cost this exists to move out of the header.
///
/// @param M    Concrete model type that handles the action.
/// @param A    Concrete action type.
/// @param NAME String literal used as the action type-id.
/// @param ...  Optional: a `morph::model::Loggable` value (defaults to `Loggable::Yes`).
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_DECLARE_ACTION(...)                                                            \
    BRIDGE_DECLARE_ACTION_PICK(__VA_ARGS__, BRIDGE_DECLARE_ACTION_4, BRIDGE_DECLARE_ACTION_3) \
    (__VA_ARGS__)
// clang-format on
 
/// @cond detail
#define BRIDGE_DECLARE_ACTION_PICK(_1, _2, _3, _4, NAME, ...) NAME
 
#define BRIDGE_DECLARE_ACTION_3(M, A, NAME) BRIDGE_DECLARE_ACTION_4(M, A, NAME, ::morph::model::Loggable::Yes)
 
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_DECLARE_ACTION_4(M, A, NAME, LOGGABLE)                                                      \
    BRIDGE_DETAIL_ACTION_TRAITS_ONLY_BODY(M, A, BRIDGE_DETAIL_DEDUCED_ACTION_RESULT(M, A), NAME, LOGGABLE) \
    MORPH_DETAIL_REQUIRE_SOURCE_LOCAL(bridge_action_src_req_,                                              \
                                      morph::model::detail::actionSourceRegistrationRequired<M, A>())
// clang-format on
/// @endcond
 
/// @brief Registers action type @p A (for model @p M) -- previously declared
///        via `BRIDGE_DECLARE_ACTION(M, A, ...)` -- with the process-level
///        `ActionDispatcher` and `ActionExecuteRegistry` at static-init time.
///
/// Call exactly once, in the one `.cpp` that owns @p M's registration.
/// Requires `morph::model::ActionTraits<A>` already visible (from
/// `BRIDGE_DECLARE_ACTION` or `BRIDGE_REGISTER_ACTION` in an included header)
/// and, unlike `BRIDGE_DECLARE_ACTION`, requires @p M complete with
/// `execute(A)` *defined* -- the registered runner calls it. Reads
/// `ActionTraits<A>::typeId()` rather than taking a `NAME` argument again, so
/// the two cannot register under a different string than the one @p A's
/// traits actually report. Suppressed under `MORPH_CLIENT_ONLY`, exactly like
/// the two registrars `BRIDGE_REGISTER_ACTION` emits directly.
///
/// HARD REQUIREMENT: this macro's expansion unconditionally calls
/// `morph::model::detail::registerActionExecutorOnce<M, A>`, exactly as
/// `BRIDGE_REGISTER_ACTION` does -- the translation unit calling it MUST
/// include `<morph/core/bridge.hpp>` (directly or transitively), or the build
/// fails to link with an unresolved external symbol for
/// `registerActionExecutorOnce<M, A>`.
///
/// @param M Concrete model type that handles the action, already declared via
///          `BRIDGE_DECLARE_ACTION`.
/// @param A Concrete action type, already declared via `BRIDGE_DECLARE_ACTION`.
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_REGISTER_ACTION_SOURCE(M, A)                                                          \
    MORPH_DETAIL_DEFINE_SOURCE_LOCAL(morph::model::detail::actionSourceRegistrationRequired<M, A>()) \
    BRIDGE_DETAIL_ACTION_REGISTRARS(M, A)
// clang-format on
 
/// @brief Registers a readiness predicate for action @p A.
///
/// Specialises `morph::model::ActionValidator<A>` so that @p FN gates @p A on every
/// dispatch path before `Model::execute` runs, and gates
/// `morph::flows::FlowSession::set<>`'s auto-fire (forms/flows.hpp).
///
/// @param A  Concrete action type.
/// @param FN Callable `bool(const A&)`.
// clang-format off -- public macro surface; see CONTRIBUTING.md, "Formatting/linting".
#define BRIDGE_REGISTER_VALIDATOR(A, FN)                            \
    template <>                                                     \
    struct morph::model::ActionValidator<A> {                       \
        static bool ready(const A& action) { return (FN)(action); } \
    };
// clang-format on
// NOLINTEND(bugprone-throwing-static-initialization,cert-err58-cpp,misc-anonymous-namespace-in-header,cert-dcl59-cpp)
// NOLINTEND(cppcoreguidelines-macro-usage)
// NOLINTEND(bugprone-macro-parentheses)