LASTRADA-Software
diff --git a/‎docs/ddl2cpp-relation-generation.md‎
Lines changed: 5 additions & 2 deletions b/‎docs/ddl2cpp-relation-generation.md‎
Lines changed: 5 additions & 2 deletions
diff --git a/‎src/Lightweight/DataMapper/CompositeForeignKey.hpp‎
Lines changed: 35 additions & 6 deletions b/‎src/Lightweight/DataMapper/CompositeForeignKey.hpp‎
Lines changed: 35 additions & 6 deletions
diff --git a/‎src/Lightweight/DataMapper/DataMapper.hpp‎
Lines changed: 76 additions & 36 deletions b/‎src/Lightweight/DataMapper/DataMapper.hpp‎
Lines changed: 76 additions & 36 deletions
@@ -113,8 +113,11 @@ considered throughout; composite ones are counted and skipped as before.
 2. **`HasManyThrough`** on each of the two referenced tables, when a table qualifies as a join
    table: exactly two single-column foreign keys, pointing at two *distinct* tables, and no
    non-key columns beyond those two foreign keys and its own key columns.
-3. **`HasOneThrough`** in place of `HasManyThrough` when the join table's foreign key to the far
-   side is covered by a single-column unique index.
+3. **`HasOneThrough`** in place of `HasManyThrough`, on a given owner's side, when the join table's
+   foreign key back to *that owner* is covered by a single-column unique index — meaning that owner
+   can appear in at most one join row, hence reach at most one record on the other side. The other
+   side keeps whatever `HasManyThrough`/`HasOneThrough` its own foreign key's uniqueness implies,
+   independently.
 4. **`HasMany`** on the referenced side of every remaining foreign key, i.e. one that is not part
    of a join table already covered by rule 2 or 3.
 5. **Scalar rather than collection** when the child's foreign key is itself covered by a
 
@@ -12,6 +12,7 @@
 #include <cstddef>
 #include <functional>
 #include <memory>
+#include <ranges>
 #include <tuple>
 #include <type_traits>
 #include <utility>
@@ -139,15 +140,15 @@ namespace detail
     };
 } // namespace detail
 
-/// @brief Satisfied by @ref Connection specializations.
+/// @brief Satisfied by `Connection` specializations.
 ///
 /// @ingroup DataMapper
 template <typename T>
 concept ConnectionType = detail::IsConnectionType<std::remove_cvref_t<T>>::value;
 
 /// @brief Represents a foreign key spanning several columns.
 ///
-/// Declared as a list of @ref Connection, each pairing one of this record's columns with the column it
+/// Declared as a list of `Connection`, each pairing one of this record's columns with the column it
 /// references. The referenced and referencing records are *derived* from those pointers rather than
 /// named again, so they cannot disagree with the connections.
 ///
@@ -160,7 +161,7 @@ concept ConnectionType = detail::IsConnectionType<std::remove_cvref_t<T>>::value
 /// order before binding, because that is the order a primary key lookup emits its predicates in - see
 /// @ref OrderedValuesOf and `src/tests/CompositeKeyOrderingTests.cpp`.
 ///
-/// @tparam Connections One @ref Connection per column of the foreign key.
+/// @tparam Connections One `Connection` per column of the foreign key.
 ///
 /// @ingroup DataMapper
 ///
@@ -228,8 +229,8 @@ class CompositeForeignKey
     static_assert(
         []() consteval {
             auto const indices = std::array { Connections::IntoMemberIndex... };
-            for (auto outer = std::size_t { 0 }; outer != indices.size(); ++outer)
-                for (auto inner = outer + 1; inner != indices.size(); ++inner)
+            for (auto const outer: std::views::iota(std::size_t { 0 }, indices.size()))
+                for (auto const inner: std::views::iota(outer + 1, indices.size()))
                     if (indices[outer] == indices[inner])
                         return false;
             return true;
@@ -257,7 +258,7 @@ class CompositeForeignKey
     /// because the referenced indices are asserted pairwise distinct above.
     template <std::size_t Slot>
     static constexpr std::size_t ConnectionForSlot = []() consteval {
-        for (auto candidate = std::size_t { 0 }; candidate != Count; ++candidate)
+        for (auto const candidate: std::views::iota(std::size_t { 0 }, Count))
         {
             auto rank = std::size_t { 0 };
             for (auto const other: IntoIndices)
@@ -384,7 +385,25 @@ class CompositeForeignKey
     /// Carries the deferred load, installed by the DataMapper.
     struct Loader
     {
+        /// Loads and returns the referenced record, or `nullptr` if none exists.
         std::function<std::shared_ptr<ReferencedRecord>()> loadReference {};
+
+        /// Loaders carry no comparable state of their own, so any two are considered equivalent.
+        std::weak_ordering operator<=>(Loader const& /*other*/) const noexcept
+        {
+            return std::weak_ordering::equivalent; // Loader is not comparable, so we return equivalent
+        }
+
+        /// Loaders carry no comparable state of their own, so any two compare equal.
+        ///
+        /// A defaulted `==` on the enclosing class does not derive equality from a member's `<=>` - each
+        /// member needs its own viable `==`, or the default is silently deleted. See HasMany::Loader for
+        /// the same shape (there, without this operator; equal by convention since it holds none of the
+        /// relation's state).
+        bool operator==(Loader const& /*other*/) const noexcept
+        {
+            return true;
+        }
     };
 
     /// Used internally to configure on-demand loading of the referenced record.
@@ -395,6 +414,16 @@ class CompositeForeignKey
         _loader = std::move(loader);
     }
 
+    /// Three-way comparison operator.
+    ///
+    /// Without this, the relation is neither `std::equality_comparable` nor (owing to its private
+    /// members) an aggregate, and `Reflection::CollectDifferences` - which falls back to recursing into
+    /// non-comparable members as aggregates - hard-errors on any record holding one. HasMany,
+    /// HasOneThrough and HasManyThrough all define one for the same reason.
+    std::weak_ordering operator<=>(CompositeForeignKey const& other) const noexcept = default;
+    /// Equality comparison operator.
+    bool operator==(CompositeForeignKey const& other) const noexcept = default;
+
   private:
     void RequireLoaded() const
     {
 
@@ -622,6 +622,25 @@ class DataMapper
     template <typename FieldType>
     std::optional<typename FieldType::ReferencedRecord> LoadBelongsTo(FieldType::ValueType value);
 
+    /// Queries the record referenced by a composite foreign key, without touching the relation itself.
+    ///
+    /// Shared by the eager path (`LoadCompositeForeignKey`) and the lazy loader installed by
+    /// `ConfigureRelationAutoLoading`, so both resolve a missing target row and wrap a found one the
+    /// same way instead of maintaining two copies of that logic.
+    ///
+    /// Takes the already-permuted key values rather than the owning record itself: the lazy loader
+    /// must evaluate `FieldType::OrderedValuesOf()` while the record is known to be live (at
+    /// `ConfigureRelationAutoLoading` time) and capture the resulting values by value, not a pointer to
+    /// the record - a `std::optional<Record>` returned by value from a query method is not guaranteed to
+    /// stay at the same address (NRVO is not mandated by the standard, and does not reliably apply to
+    /// every such function in practice), so a captured pointer can dangle by the time the loader runs.
+    ///
+    /// @param keys The foreign key values, in the referenced record's member order.
+    /// @return The referenced record, or `nullptr` if no matching row exists.
+    template <typename FieldType>
+    std::shared_ptr<typename FieldType::ReferencedRecord> LoadCompositeForeignKeyRecord(
+        typename FieldType::OrderedValueType const& keys);
+
     /// Eagerly loads the record referenced by a composite foreign key.
     ///
     /// @param record The record holding the foreign key.
@@ -1112,7 +1131,7 @@ size_t SqlCoreDataMapperQueryBuilder<Record, Derived, QueryOptions>::CountImpl()
                                         this->_query.searchCondition.condition));
     auto reader = stmt.ExecuteWithVariants(_boundInputs);
     if (reader.FetchRow())
-        return reader.GetColumn<size_t>(1);
+        return reader.template GetColumn<size_t>(1);
     return 0;
 }
 
@@ -1217,7 +1236,7 @@ auto SqlCoreDataMapperQueryBuilder<Record, Derived, QueryOptions>::AllImpl() ->
         }
 
         if (!outputColumnsBound)
-            value = reader.GetColumn<value_type>(1);
+            value = reader.template GetColumn<value_type>(1);
     }
 
     return result;
@@ -1338,16 +1357,27 @@ auto SqlCoreDataMapperQueryBuilder<Record, Derived, QueryOptions>::FirstImpl() -
 #else
         reader.BindOutputColumns(&(record.*ReferencedFields)...);
 #endif
-    if (!reader.FetchRow())
-        return std::nullopt;
-    if (!outputColumnsBound)
+
+    // A single return statement at the end is deliberate, not stylistic: a composite foreign key
+    // configured below (ConfigureRelationAutoLoading) captures a pointer to *optionalRecord. An earlier
+    // `return std::nullopt;` here defeats NRVO in both GCC and Clang (verified: it forces a
+    // move-construct into the caller's storage at a new address), which would leave that captured
+    // pointer dangling.
+    if (reader.FetchRow())
     {
-        using ElementMask = std::integer_sequence<size_t, MemberIndexOf<ReferencedFields>...>;
-        detail::GetAllColumns<ElementMask>(reader, record);
-    }
+        if (!outputColumnsBound)
+        {
+            using ElementMask = std::integer_sequence<size_t, MemberIndexOf<ReferencedFields>...>;
+            detail::GetAllColumns<ElementMask>(reader, record);
+        }
 
-    if constexpr (QueryOptions.loadRelations)
-        _dm.ConfigureRelationAutoLoading(record);
+        if constexpr (QueryOptions.loadRelations)
+            _dm.ConfigureRelationAutoLoading(record);
+    }
+    else
+    {
+        optionalRecord.reset();
+    }
 
     return optionalRecord;
 }
@@ -2177,18 +2207,22 @@ std::optional<Record> DataMapper::QuerySingle(PrimaryKeyTypes&&... primaryKeys)
     _stmt.Prepare(queryBuilder->First());
     auto reader = _stmt.Execute(std::forward<PrimaryKeyTypes>(primaryKeys)...);
 
+    // A single return statement at the end is deliberate, not stylistic: a composite foreign key
+    // configured below (ConfigureRelationAutoLoading) captures a pointer to *resultRecord. An earlier
+    // `return std::nullopt;` here defeats NRVO in both GCC and Clang (verified: it forces a move-construct
+    // into the caller's storage at a new address), which would leave that captured pointer dangling.
     auto resultRecord = std::optional<Record> { Record {} };
-    if (!detail::ReadSingleResult(_stmt.Connection().ServerType(), reader, *resultRecord))
-        return std::nullopt;
-
-    if (resultRecord)
+    if (detail::ReadSingleResult(_stmt.Connection().ServerType(), reader, *resultRecord))
+    {
         SetModifiedState<ModifiedState::NotModified>(resultRecord.value());
 
-    if constexpr (QueryOptions.loadRelations)
-    {
-        if (resultRecord)
+        if constexpr (QueryOptions.loadRelations)
             ConfigureRelationAutoLoading(*resultRecord);
     }
+    else
+    {
+        resultRecord.reset();
+    }
 
     return resultRecord;
 }
@@ -2484,6 +2518,19 @@ inline LIGHTWEIGHT_FORCE_INLINE void CallOnBelongsTo(Callable const& callable)
     });
 }
 
+template <typename FieldType>
+std::shared_ptr<typename FieldType::ReferencedRecord> DataMapper::LoadCompositeForeignKeyRecord(
+    typename FieldType::OrderedValueType const& keys)
+{
+    using ReferencedRecord = typename FieldType::ReferencedRecord;
+
+    auto loaded =
+        std::apply([this](auto const&... key) { return this->template QuerySingle<ReferencedRecord>(key...); }, keys);
+    if (!loaded)
+        return {};
+    return std::make_shared<ReferencedRecord>(std::move(*loaded));
+}
+
 template <typename Record, typename FieldType>
 void DataMapper::LoadCompositeForeignKey(Record const& record, FieldType& field)
 {
@@ -2496,8 +2543,7 @@ void DataMapper::LoadCompositeForeignKey(Record const& record, FieldType& field)
     // member of the referenced record, in that record's member declaration order, and binds its
     // arguments positionally - so the values have to be permuted into that order first. See
     // CompositeKeyOrderingTests.cpp.
-    auto loaded = std::apply([this](auto const&... key) { return QuerySingle<ReferencedRecord>(key...); },
-                             FieldType::OrderedValuesOf(record));
+    auto loaded = LoadCompositeForeignKeyRecord<FieldType>(FieldType::OrderedValuesOf(record));
 
     // A missing target row leaves the relation unloaded rather than throwing here: eagerly loading a
     // dangling foreign key is a data-integrity problem to surface at the accessor, which is where the
@@ -2509,7 +2555,7 @@ void DataMapper::LoadCompositeForeignKey(Record const& record, FieldType& field)
         return;
     }
 
-    field.EmplaceRecord(std::make_shared<ReferencedRecord>(std::move(*loaded)));
+    field.EmplaceRecord(std::move(loaded));
 }
 
 template <typename FieldType>
@@ -2930,30 +2976,24 @@ void DataMapper::ConfigureRelationAutoLoading(Record& record)
         {
             using ReferencedRecord = typename FieldType::ReferencedRecord;
 
-            // The key is read out of the record's own Field members *at load time*, through the
-            // connections' member pointers, rather than snapshotted here. Snapshotting would make the
-            // relation resolve to whichever parent the key named when the record was configured, so
-            // repointing the foreign key afterwards would silently keep returning the old parent. The
-            // relation deliberately owns no copy of the key - the Field that owns each column is the
-            // single source of truth.
-            //
-            // Capturing the record by pointer is safe because it is the mapper's own stored record: the
-            // same lifetime the HasMany/HasOneThrough loaders already rely on. Unlike those, no value is
-            // copied out, so a moved-from record would be observed rather than a stale duplicate.
+            // Captured by value, evaluated now while `record` is known to be live - not a pointer to
+            // `record` read later from inside the closure. A `std::optional<Record>` returned by value
+            // from a query method (QuerySingle, First, ...) is not guaranteed to keep its address: NRVO
+            // is not mandated by the standard, and - verified - does not reliably apply to the fuller
+            // body of those functions in at least one real build configuration, so a captured pointer
+            // can end up pointing at stack memory already reused for something else by the time the
+            // loader runs. The trade-off is the same one HasMany/BelongsTo already make: repointing the
+            // foreign key after this point does not change what the relation resolves to.
             //
             // OrderedValuesOf() - not ValuesOf() - because QuerySingle emits one WHERE predicate per
             // primary key member in the *referenced record's* member declaration order and binds its
             // arguments positionally. Passing them in connection-declaration order would bind each
             // value to the wrong predicate whenever the two orders differ, which with same-typed key
             // columns fetches a wrong row rather than failing. See CompositeKeyOrderingTests.cpp.
             field.SetAutoLoader(typename FieldType::Loader {
-                .loadReference = [owner = &record]() -> std::shared_ptr<ReferencedRecord> {
+                .loadReference = [keys = FieldType::OrderedValuesOf(record)]() -> std::shared_ptr<ReferencedRecord> {
                     DataMapper& dm = DataMapper::AcquireThreadLocal();
-                    auto loaded = std::apply([&dm](auto const&... key) { return dm.QuerySingle<ReferencedRecord>(key...); },
-                                             FieldType::OrderedValuesOf(*owner));
-                    if (!loaded)
-                        return {};
-                    return std::make_shared<ReferencedRecord>(std::move(*loaded));
+                    return dm.LoadCompositeForeignKeyRecord<FieldType>(keys);
                 },
             });
         }