feat: generate inverse relations in ddl2cpp, and support composite foreign keys

[Yaraslaut]

Two related pieces of work, both driven by what a large production schema actually contains.

1. ddl2cpp generates inverse and through relations

Previously only Light::BelongsTo was emitted, so a generated model was navigable from child to
parent and no further. CxxModelPrinter::PlanRelations() now answers the schema-wide question — it is
a pure function over the table list, so it is testable without a database — and PrintTable()
consumes one table's share.

Rules, documented in docs/ddl2cpp-relation-generation.md:

• a join table (exactly two single-column foreign keys to two distinct tables, no payload
  columns) becomes a HasManyThrough on both referenced tables, and gets no inverse of its own
• it degrades to HasOneThrough when the owner side's key is uniquely indexed
• every other single-column foreign key becomes a HasMany on the referenced side
• a uniquely indexed child foreign key makes the relation one-to-one
• composite foreign keys are skipped, exactly as BelongsTo skips them

Two shapes are deliberately not collapsed. A join table carrying payload columns is an association
object, so it keeps its own record plus a HasMany on each side — otherwise the payload becomes
unreachable. A table whose two foreign keys point at the same table has no far side to hop to, so it
stays two HasMany relations rather than a nonsensical self-through.

Emission detail: an inverse relation names the child while the child's BelongsTo names the parent,
so including both ways would be a cycle. The parent forward-declares instead, which is sound because
every relation stores its records indirectly. A relation member is also never allowed to collide with
the referenced (non-self) struct's own name — legal C++, but GCC's -Wchanges-meaning rejects it under
-Werror, and it is genuinely confusing besides — so ddl2cpp reserves that name against the
generated struct before picking the member's own.

2. Composite foreign keys: CompositeForeignKey<Connection<...>, ...>

A composite foreign key references a composite primary key, so both sides need the same notion of "a
key spans several columns". Under the principle that every database column is one data member,
that means several members marked PrimaryKey on the referenced side, and several ordinary column
members plus one relation member on the referencing side:

struct Child {
    Field<int32_t, PrimaryKey::AutoAssign> id;
    Field<int32_t, SqlRealName{"ref_a"}> refA;   // ordinary columns
    Field<int32_t, SqlRealName{"ref_b"}> refB;
    CompositeForeignKey<Connection<&Child::refA, &Parent::partA>,
                        Connection<&Child::refB, &Parent::partB>> parent;
};

Why the pairing lives in the type. With two parallel column lists matched positionally,
transposing two same-typed columns is silently wrong and uncatchable. As a Connection<from, into> the
pairing is part of the type — a transposition is a different Connection, and where the paired columns
differ in value type it does not compile.

BelongsTo is deliberately untouched. It is inseparably a column — storage, FieldWithStorage,
a binder over one ODBC column index — as well as a navigator. Widening it would break the
"one member ⇒ one column" invariant that RecordColumnCount, every projection builder, the
output-binding loop and the multi-record column-offset arithmetic all rest on. So the new relation does
only the navigation half, in the mould of HasOneThrough: no Value()/IsModified(), therefore not
RecordColumnMember, therefore contributing 0 columns and skipped by every projection automatically.
No binder, projection or column-arithmetic code changed.

Ordering was settled by test first. CompositeKeyOrderingTests.cpp establishes that QuerySingle
emits one predicate per key member in the referenced record's member declaration order and binds
positionally — so a transposed argument pair returns a wrong row, not an error. OrderedValuesOf
therefore builds the ordered tuple by slot, resolving each position's connection at compile time, so
connections may be written in any order.

Reflected identity is additive: RecordPrimaryKeyTuple, RecordPrimaryKeyCount,
HasCompositePrimaryKey and GetPrimaryKeyFields() sit beside the single-key helpers, which keep
resolving one member index so no existing caller changes shape — notably CreateExplicit, which
returns RecordPrimaryKeyType.

The lazy auto-loader captures the foreign key's values, not a pointer back into the owning record:
QuerySingle's NRVO is not standard-mandated and does not reliably apply to its full (non-trivial)
body in practice, so a captured pointer into a std::optional<Record> returned by value could dangle
by the time the loader runs. Confirmed as a real bug (not a false positive) with a coverage-instrumented
build before switching to value capture — see CompositeForeignKeyTests.cpp's
"lazy auto-loader survives QuerySingle's return by value" regression test.

Review fixes and hardening (this update)

• Fixed the owner/far-side uniqueness check that had been backwards in the HasOneThrough cardinality
  decision, and the GCC member-naming collision above.
• GetPrimaryKeyField/GetPrimaryKeyFields no longer silently return the wrong field and no longer
  scan O(K²).
• GenerateAutoAssignPrimaryKey now counts auto-assigned GUID keys, not just incrementable ones.
• Added operator<=>/operator== to CompositeForeignKey/Connection/Loader so composite-FK
  relations participate in CollectDifferences like every other relation type.
• Regenerated the test_chinook golden-file entities (never refreshed since relation generation
  landed on this branch) against a live Chinook database, and added a regression test asserting a
  relation member never collides with its own referenced struct's name.
• Fixed the C++26 reflection build (LIGHTWEIGHT_CXX26_REFLECTION): Utils.hpp's MemberIndexOf
  called parent_of unqualified (undeclared under that build), and the composite-FK test fixtures
  passed raw &Class::field pointer-to-member values into Connection<...> instead of the existing
  Member(x) macro (^^x under reflection, &x otherwise) that BelongsTo's own fixtures already
  use — std::meta::parent_of needs an actual std::meta::info, not a member pointer. Both fixed;
  the reflection CI job is green.

Risk

• Per-DBMS: no dialect-specific code touched. Loading reuses QuerySingle, so no new SQL is
  generated and no new binding path exists.
• ABI / existing records: additive. Records without the new relation are byte-identical, and the
  single-key identity helpers are unchanged.
• One behavioural restriction: GenerateAutoAssignPrimaryKey now rejects more than one
  auto-assigned key member, because auto-assignment yields a single value that SetId() writes into
  every key member. Scoped to the value types it actually generates for (GUIDs and incrementable
  ones), so the pre-existing two-AutoAssign-string-keys case still compiles.

Warning

clang-cl 22.1.3 miscompiles records holding a CompositeForeignKey — the same defect already
documented for a self-referential BelongsTo: an impossible stack frame and a fault in the function
prologue, eight frames deep with no runtime recursion. The identical code compiles and every case
passes under MSVC cl, so CompositeForeignKeyTests.cpp is excluded from compilation on that
toolchain with a [!shouldfail] placeholder standing in — Windows-clangcl-debug is green because
of that guard, not because the defect is fixed. Reducing this for an upstream LLVM report is still
outstanding.

Testing

Full suite run against every supported database, plus the compiler/configuration matrix CI actually
uses — see AGENT.md's "Testing every database is not enough" section for why both matter:

Compiler / config	Databases	Result
clang-debug (ASan/UBSan/TSan, clang-tidy)	sqlite3, mssql2022, postgres	1350 passed, 1 skipped
gcc-release	sqlite3, mssql2022, postgres	pass (CI)
MSVC cl-debug	sqlite3	pass (CI)
clang-cl debug	sqlite3	pass (CI; composite-FK tests excluded on this toolchain, see warning above)
LIGHTWEIGHT_CXX26_REFLECTION (clang, experimental)	sqlite3	pass (CI)
Windows (LocalDB, ODBC 17/18, PostgreSQL, SQLite3)	—	pass (CI)
macOS (Homebrew LLVM)	sqlite3	pass (CI)

ddl2cpp was also run against the real 686-table schema: 1770 relations generated (1660
HasMany, 104 HasManyThrough, 6 HasOneThrough, alongside 1496 BelongsTo), and a slice of the
generated headers was compiled to confirm the emitted relations instantiate. test_chinook's golden
files were regenerated against a live database and diff clean.

Codecov: patch coverage 95.81% (9/215 new lines uncovered — mostly hard-to-hit defensive paths, e.g.
the "relation genuinely not loadable" throw in CompositeForeignKey::RequireLoaded()); project
coverage 91.05% → 91.11%.

Deferred, tracked in the docs rather than silently skipped

• ddl2cpp emitting CompositeForeignKey declarations — mechanical now that the spelling is fixed,
  since the schema reader already reports both ordered column lists
• the inverse of a composite relation (HasMany needing a list-valued selector)
• AutoAssign / ServerSideAutoIncrement semantics across several key columns

🤖 Generated with Claude Code

https://claude.ai/code/session_01TVec3YeQg2FZnToiPQwcQH

[codecov]

Codecov Report

❌ Patch coverage is 95.81395% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/Lightweight/DataMapper/DataMapper.hpp	81.48%	5 Missing ⚠️
src/Lightweight/Tools/CxxModelPrinter.cpp	97.76%	3 Missing ⚠️
src/Lightweight/DataMapper/CompositeForeignKey.hpp	97.50%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!