model.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
#include <chrono>
#include <concepts>
#include <core/platform/Clock.hpp>
#include <exception>
#include <functional>
#include <memory>
#include <stdexcept>
#include <string_view>
#include <type_traits>
#include <typeindex>
#include <typeinfo>
#include <utility>
 
// strand.hpp defines no symbol this header uses. It is kept deliberately:
// consumers (tests/test_model.cpp among them) reach
// morph::exec::detail::ModelId through it, and for a header-only public library
// dropping a transitive include is a source-breaking change for its users --
// not worth the tidiness. The <concepts> include above is the real gap it was
// masking; this file uses std::same_as and `concept` without including it.
#include "../journal/action_log.hpp"
#include "../session/session.hpp"
#include "detail/task_handler.hpp"
#include "logger.hpp"
#include "strand.hpp"
 
namespace morph::model {
 
// ── Post-commit tail ──────────────────────────────────────────────────────────
 
/// @brief Runs @p tail, an action handler's work *after* its commit, and
///        contains any exception it throws.
///
/// Once a handler has committed, its mutation is durable. What it does next --
/// journalling, a rule cascade, rebuilding cached state -- can still fail, and
/// if that failure leaves `execute()` the caller is told the action failed
/// while the write it made stands. This is the seam that keeps the two apart:
/// the tail's exception is logged through `morph::log::logError` and goes no
/// further. Only work that follows the commit belongs in @p tail; an exception
/// from before it still means the mutation did not happen and must still reach
/// the caller.
///
/// Anything the caller's return value depends on is best computed before the
/// commit, where a failure rolls the write back. A handler that cannot do that
/// uses the value-returning overload instead.
///
/// @tparam Tail Nullary callable returning `void`.
/// @param tail The post-commit work to run.
/// @param what Names the handler in the log line, e.g. `"[bookmarks::BookmarkModel] BulkEdit"`.
template <typename Tail>
    requires std::invocable<Tail> && std::is_void_v<std::invoke_result_t<Tail>>
void runPostCommitTail(Tail&& tail, std::string_view what) noexcept {
    try {
        std::invoke(std::forward<Tail>(tail));
    } catch (const std::exception& error) {
        ::morph::log::logError("{} committed, but its post-commit tail failed: {}", what, error.what());
    } catch (...) {
        ::morph::log::logError("{} committed, but its post-commit tail threw a non-std::exception", what);
    }
}
 
/// @brief The same containment for a tail that produces the handler's result,
///        falling back to the state the handler committed if the tail throws.
///
/// For a handler whose return value is refreshed by its post-commit work --
/// a state rebuilt after a rule cascade, say -- and which already holds a
/// truthful answer from before the tail began. If the tail throws, that answer
/// is returned instead: it describes what the commit made durable, which is
/// the one thing the caller must not be misinformed about.
///
/// @tparam Result The handler's result type; deduced from @p committed.
/// @tparam Tail Nullary callable whose result converts to @p Result.
/// @param tail The post-commit work to run.
/// @param committed The result to return if @p tail throws.
/// @param what Names the handler in the log line.
/// @return @p tail's result, or @p committed if it threw.
template <typename Result, typename Tail>
    requires std::invocable<Tail> && std::convertible_to<std::invoke_result_t<Tail>, Result>
[[nodiscard]] Result runPostCommitTail(Tail&& tail, Result committed,
                                       std::string_view what) noexcept(std::is_nothrow_move_constructible_v<Result>) {
    try {
        return std::invoke(std::forward<Tail>(tail));
    } catch (const std::exception& error) {
        ::morph::log::logError("{} committed, but its post-commit tail failed: {}", what, error.what());
    } catch (...) {
        ::morph::log::logError("{} committed, but its post-commit tail threw a non-std::exception", what);
    }
    return committed;
}
 
}  // namespace morph::model
 
namespace morph::model::detail {
 
template <typename Model>
struct ModelHolder;
 
// ── Backend-change notification interface ─────────────────────────────────────
 
/// @brief Optional interface for models that need to react to backend switches.
///
/// Implemented automatically by `ModelHolder<M>` when `M` declares
/// `void onBackendChanged()`. `Bridge::switchBackend()` discovers this
/// capability via `dynamic_cast` without coupling to the concrete type.
// NOLINTBEGIN(cppcoreguidelines-special-member-functions)
struct IBackendChangedSink {
    virtual ~IBackendChangedSink() = default;
 
    /// @brief Called after the bridge has switched to a new backend and
    ///        re-registered all handlers on it.
    virtual void onBackendChanged() = 0;
};
// NOLINTEND(cppcoreguidelines-special-member-functions)
 
// ── Concept ───────────────────────────────────────────────────────────────────
 
/// @brief Concept satisfied by model types that expose `void onBackendChanged()`.
template <typename M>
concept BackendChangedNotifiable = requires(M& model) {
    { model.onBackendChanged() } -> std::same_as<void>;
};
 
/// @brief Concept satisfied by model types that expose a model-level
///        `attachActionLog(std::shared_ptr<IActionLog>, std::string)`.
///
/// A small number of keyed/shared models cannot rely on `IModelHolder::recordIfAttached`'s auto-append alone (that
/// mechanism serves plain fire-after-success journaling; a model that needs
/// to read its own log back, e.g. for an activity-stream view, needs the
/// *same* `IActionLog` instance available on `Model` itself, not only on the
/// type-erased holder wrapping it) and so declares its own `attachActionLog`
/// method with this exact shape, purely by structural convention — there is
/// no shared base class or interface a model opts into. This concept is what
/// lets `ModelHolder<Model>::onActionLogAttached` forward to it generically,
/// the same "detect the hook structurally, forward only if present" shape
/// `BackendChangedNotifiable`/`BackendChangedMixin` already establish for
/// `onBackendChanged()`.
template <typename M>
concept ModelLevelActionLogAttachable =
    requires(M& model, std::shared_ptr<::morph::journal::IActionLog> log, std::string key) {
        { model.attachActionLog(log, key) } -> std::same_as<void>;
    };
 
/// @brief Concept satisfied by model types that expose a model-level
///        `attachIdentity(std::string primaryKey)`.
///
/// A registry-constructed instance (`ModelRegistryFactory::create`, used by
/// `RemoteServer`'s `register`/`attach` paths) knows its own primary key —
/// `env.primary` — at construction time, but nothing on that path previously
/// told the model itself: `ModelFactory::create<Model>()` default-constructs
/// it and the key only ever reached `Model::execute` inside a keyed action's
/// own payload. A model that wants to know its key once, at construction,
/// rather than re-deriving it from every action, opts in by declaring
/// `attachIdentity` with this exact shape — purely by structural convention,
/// the same "detect the hook structurally, forward only if present" shape
/// `ModelLevelActionLogAttachable`/`BackendChangedNotifiable` already
/// establish. This concept is what lets `ModelHolder<Model>::onIdentityAttached`
/// forward to it generically.
template <typename M>
concept ModelIdentityAttachable = requires(M& model, std::string key) {
    { model.attachIdentity(key) } -> std::same_as<void>;
};
 
// ── Conditional mixin ─────────────────────────────────────────────────────────
 
/// @brief Empty base when `M` does not declare `onBackendChanged()`.
template <typename M, bool = BackendChangedNotifiable<M>>
struct BackendChangedMixin {};
 
/// @brief Specialisation that adds `IBackendChangedSink` when `M` declares `onBackendChanged()`; its one virtual is
///        implemented by `ModelHolder<M>::onBackendChanged`.
template <typename M>
struct BackendChangedMixin<M, true> : IBackendChangedSink {};
 
// ── Core type-erasure ─────────────────────────────────────────────────────────
 
/// @brief Type-erased wrapper that owns a single model instance.
///
/// Used internally by backends to store heterogeneous models in a single map.
// NOLINTBEGIN(cppcoreguidelines-special-member-functions)
struct IModelHolder {
    virtual ~IModelHolder() = default;
 
    /// @brief Returns the `std::type_index` of the concrete model type.
    [[nodiscard]] virtual std::type_index type() const noexcept = 0;
 
    /// @brief Returns `true` if the concrete model type declares `void onBackendChanged()`.
    ///
    /// Answered by `ModelHolder<Model>` from the `BackendChangedNotifiable<Model>`
    /// concept — a compile-time constant per concrete `Model` — so a backend can
    /// learn this once, at registration time, instead of `dynamic_cast`ing every
    /// holder on every backend switch. See `LocalBackend::registerModel` /
    /// `LocalBackend::notifyBackendChanged` (`backend.hpp`).
    [[nodiscard]] virtual bool isBackendChangeAware() const noexcept = 0;
 
    /// @brief Forwards to the concrete model's `onBackendChanged()`, if it declared one.
    ///
    /// Default implementation is a no-op, for holders whose model is not
    /// backend-change-aware. `ModelHolder<Model>` overrides this to call
    /// `Model::onBackendChanged()` when `BackendChangedNotifiable<Model>` holds.
    /// Called by `LocalBackend::notifyBackendChanged` through this base-class
    /// virtual — no `dynamic_cast`, no RTTI dependency on this path.
    virtual void onBackendChanged() {}
 
    /// @brief The gate every action on this instance enters before it runs.
    ///
    /// Held from an action's start to its end -- for a Task handler, until its
    /// Task completes -- so the next action does not start while a handler is
    /// suspended. Touched only on this instance's strand. See `ActionGate` and
    /// `docs/spec/core/coroutines.md`, "Not re-entrant: the action gate".
    /// @return This instance's gate.
    [[nodiscard]] ActionGate& actionGate() noexcept { return _actionGate; }
 
    /// @brief Down-casts to a concrete `Model` reference.
    ///
    /// @tparam Model The expected concrete type.
    /// @throws std::bad_cast if the stored type is not `Model`.
    template <typename Model>
    Model& into() {
        if (type() != std::type_index(typeid(Model))) {
            throw std::bad_cast{};
        }
        return static_cast<ModelHolder<Model>*>(this)->model;
    }
 
    /// @brief Attaches a durable action log and this instance's stable identity.
    ///
    /// Set once, typically from the same custom `HandlerBinding::modelFactory`
    /// closure already used to inject other dependencies, or from
    /// `RemoteServer::LogProvider` for a registry-constructed remote instance
    /// (see `docs/spec/journal/journal.md`, "Attaching a log to remote
    /// instances"). @p contextKey is stamped onto every `LogEntry` this
    /// instance produces (e.g. an account id) so log entries are identifiable
    /// without parsing `payload`/`result` JSON.
    ///
    /// Also forwards @p log/@p contextKey to the wrapped model's own
    /// `attachActionLog(log, contextKey)`, if it declares one matching
    /// `ModelLevelActionLogAttachable` — see `onActionLogAttached`'s doc
    /// comment for why this second call exists alongside the holder's own
    /// `_actionLog`/`_contextKey` state below.
    ///
    /// @p wallClock is what `recordIfAttached` stamps `LogEntry::timestampMs`
    /// from. It is borrowed, not owned, so it must outlive this holder; a test
    /// passes a `core::platform::ManualWallClock` to pin the stamp.
    /// @param log        Sink entries are forwarded to. Pass a `SessionLog` to also
    ///                   get undo/checkpoint support.
    /// @param contextKey Stable identity of this model instance.
    /// @param wallClock  Clock entries are timestamped from; the system clock by default.
    void attachActionLog(std::shared_ptr<::morph::journal::IActionLog> log, std::string contextKey,
                         ::core::platform::WallClockRef wallClock = ::core::platform::defaultSystemWallClock()) {
        onActionLogAttached(log, contextKey);
        _actionLog = std::move(log);
        _contextKey = std::move(contextKey);
        _wallClock = wallClock;
    }
 
    /// @brief Tells this instance its own stable primary key, once, at
    ///        construction time.
    ///
    /// Called by `ModelRegistryFactory::create(modelId, primary)` immediately
    /// after building the holder, when @p primaryKey is non-empty — the
    /// registry-constructed counterpart of a model reading its key back out
    /// of every keyed action's payload. Forwards to the wrapped model's own
    /// `attachIdentity(primaryKey)`, if it declares one matching
    /// `ModelIdentityAttachable`; a no-op otherwise, for the majority of
    /// models that have no need to know their own key ahead of the first
    /// action that carries it.
    ///
    /// Independent of `attachActionLog`/`_contextKey`: `contextKey` is the
    /// action log's entity-key field, `primaryKey` is the shared-instance
    /// directory key (`backend.hpp`'s `BindRequest` carries them as two named
    /// fields, since they mean different things) — a caller
    /// wanting both calls both.
    /// @param primaryKey Stable identity of this model instance; a no-op if empty.
    void attachIdentity(std::string primaryKey) {
        if (primaryKey.empty()) {
            return;
        }
        onIdentityAttached(primaryKey);
    }
 
    /// @brief Returns `true` if an action log is attached to this instance.
    [[nodiscard]] bool hasActionLog() const noexcept { return static_cast<bool>(_actionLog); }
 
    /// @brief Marks this instance as outbox-managed: the model records its own
    ///        `LogEntry` (inside its own store's transaction) and relays it via
    ///        `journal::OutboxRelay`, so `recordIfAttached` must stop
    ///        auto-appending for it — otherwise the framework's normal
    ///        fire-after-success append would double-log the same action.
    ///
    /// Independent of `attachActionLog`/`hasActionLog()`: those keep reporting
    /// whatever log is attached and whether one is attached, respectively; this
    /// flag only changes whether `recordIfAttached` actually forwards to it.
    /// Defaults to `false` — every instance auto-appends exactly as before
    /// unless a model explicitly opts in.
    /// @param outboxManaged `true` to suppress `recordIfAttached`; `false` to
    ///        restore the ordinary fire-after-success behavior.
    void setOutboxManaged(bool outboxManaged) noexcept { _outboxManaged = outboxManaged; }
 
    /// @brief Returns `true` if `setOutboxManaged(true)` was called on this instance.
    [[nodiscard]] bool isOutboxManaged() const noexcept { return _outboxManaged; }
 
    /// @brief Records @p entry if a log is attached and this instance is not
    ///        outbox-managed; no-op otherwise.
    ///
    /// Called automatically by the two places `Model::execute()` is actually
    /// invoked (`ActionDispatcher`'s runner and `Bridge::executeVia`'s local
    /// op) — model code and application code never call this directly.
    /// Overwrites `entityKey`, `principal`, and `timestampMs` (from the clock
    /// given to `attachActionLog`) on @p entry;
    /// callers only need to fill `modelType`, `actionType`, `payload`, `result`.
    /// A no-op if no log is attached, **or** if `setOutboxManaged(true)` was
    /// called on this instance (the model records its own entry elsewhere).
    /// @param entry Entry to record; `seq` is assigned by the attached sink.
    void recordIfAttached(::morph::journal::LogEntry entry) {
        if (!_actionLog || _outboxManaged) {
            return;
        }
        entry.entityKey = _contextKey;
        if (const auto* ctx = ::morph::session::current()) {
            entry.principal = ctx->principal;
        }
        entry.timestampMs =
            std::chrono::duration_cast<std::chrono::milliseconds>(_wallClock.now().time_since_epoch()).count();
        _actionLog->append(std::move(entry));
    }
 
protected:
    /// @brief Forwards @p log/@p contextKey to the wrapped model's own
    ///        `attachActionLog`, if it declares one.
    ///
    /// `ModelHolder<Model>` implements it, detecting the member structurally
    /// (`ModelLevelActionLogAttachable<Model>`) and doing nothing for a model
    /// without one; this default does nothing, for a holder that is not a
    /// `ModelHolder`. It is what lets a registry-constructed instance hold a
    /// model-level log reference (e.g. for an activity-stream view) beside
    /// the holder's own, which `recordIfAttached`'s auto-append uses.
    /// @param log        Sink entries are forwarded to.
    /// @param contextKey Stable identity of this model instance.
    virtual void onActionLogAttached(const std::shared_ptr<::morph::journal::IActionLog>& log,
                                     const std::string& contextKey) {
        (void)log;
        (void)contextKey;
    }
 
    /// @brief Forwards @p primaryKey to the wrapped model's own
    ///        `attachIdentity`, if it declares one.
    ///
    /// `ModelHolder<Model>` implements it, detecting the member structurally
    /// (`ModelIdentityAttachable<Model>`) and doing nothing for a model
    /// without one; this default does nothing, for a holder that is not a
    /// `ModelHolder`.
    /// @param primaryKey Stable identity of this model instance; never empty
    ///                    (the public `attachIdentity` filters that case out).
    virtual void onIdentityAttached(const std::string& primaryKey) { (void)primaryKey; }
 
private:
    ActionGate _actionGate;
    std::shared_ptr<::morph::journal::IActionLog> _actionLog;
    std::string _contextKey;
    ::core::platform::WallClockRef _wallClock{::core::platform::defaultSystemWallClock()};
    bool _outboxManaged{false};
};
// NOLINTEND(cppcoreguidelines-special-member-functions)
 
/// @brief Concrete holder that stores a `Model` by value.
///
/// Inherits `BackendChangedMixin<Model>` so that backend-change notifications
/// are forwarded automatically when `Model` opts in.
template <typename Model>
struct ModelHolder : IModelHolder, BackendChangedMixin<Model> {
    /// @brief The owned model instance.
    Model model;
 
    /// @brief Constructs the model by forwarding all arguments.
    template <typename... Args>
    explicit ModelHolder(Args&&... args) : model{std::forward<Args>(args)...} {}
 
    /// @brief Returns `typeid(Model)` wrapped in a `std::type_index`.
    [[nodiscard]] std::type_index type() const noexcept override { return typeid(Model); }
 
    /// @brief Returns `BackendChangedNotifiable<Model>` — a compile-time constant.
    [[nodiscard]] bool isBackendChangeAware() const noexcept override { return BackendChangedNotifiable<Model>; }
 
    /// @brief Forwards to `Model::onBackendChanged()` iff `Model` declared one; no-op otherwise.
    ///
    /// This single definition is the final overrider for two unrelated base
    /// virtuals: `IModelHolder::onBackendChanged` (always), and — when `Model`
    /// is notifiable — `IBackendChangedSink::onBackendChanged`, reached via
    /// `BackendChangedMixin<Model, true>`; both call paths (`IModelHolder*` and
    /// `dynamic_cast<IBackendChangedSink*>`) land here.
    void onBackendChanged() override {
        if constexpr (BackendChangedNotifiable<Model>) {
            model.onBackendChanged();
        }
    }
 
protected:
    /// @brief Forwards to `Model::attachActionLog(log, contextKey)` iff `Model`
    ///        declared one matching `ModelLevelActionLogAttachable`; no-op otherwise.
    void onActionLogAttached(const std::shared_ptr<::morph::journal::IActionLog>& log,
                             const std::string& contextKey) override {
        if constexpr (ModelLevelActionLogAttachable<Model>) {
            model.attachActionLog(log, contextKey);
        }
    }
 
    /// @brief Forwards to `Model::attachIdentity(primaryKey)` iff `Model`
    ///        declared one matching `ModelIdentityAttachable`; no-op otherwise.
    void onIdentityAttached(const std::string& primaryKey) override {
        if constexpr (ModelIdentityAttachable<Model>) {
            model.attachIdentity(primaryKey);
        }
    }
};
 
/// @brief Factory that creates default-constructed `ModelHolder<Model>` instances.
class ModelFactory {
public:
    /// @brief Creates a new `ModelHolder<Model>` on the heap.
    ///
    /// If a process-wide default action log is installed (see
    /// `morph::journal::setActionLog`), it is attached to the new holder
    /// automatically (with an empty `entityKey`) — this is the single
    /// construction path behind every ordinary model registration, local or
    /// remote, which is what makes "set the log once in `main()`" work
    /// uniformly across topologies. Callers that need a specific instance
    /// identity call `attachActionLog` again afterward to override it.
    /// @tparam Model The model type to instantiate.
    /// @return Owning pointer to the new holder.
    template <typename Model>
    static std::unique_ptr<IModelHolder> create() {
        auto holder = std::make_unique<ModelHolder<Model>>();
        if (auto log = ::morph::journal::defaultActionLog()) {
            holder->attachActionLog(std::move(log), {});
        }
        return holder;
    }
};
 
}  // namespace morph::model::detail