carriage.hpp

Go to the documentation of this file.

#pragma once
#include <array>
#include <cstddef>
#include <meta>
#include <type_traits>
#include <utility>
 
#include <welder/bind_traits.hpp> // what-binds selection layer
#include <welder/bindable.hpp>    // bindability gate + caster_oracle
#include <welder/concepts.hpp>    // the welder::rod contract
#include <welder/doc.hpp>         // doc_of (class / namespace docstrings)
#include <welder/naming.hpp>      // naming::none + name_of (weld_as + name styling)
#include <welder/reflect.hpp>     // welded_for / policy_of / member_bound

 
namespace welder::inline v0 {
 
namespace detail {

template <class Resolution, std::meta::info Ns, std::meta::info Alias>
consteval bool sole_alias_of_target(lang L, policy_kind pol) {
    for (auto m :
         std::meta::members_of(Ns, std::meta::access_context::unchecked())) {
        if (!welder::names_template_specialization(m))
            continue;
        // Self-identity by NAME, not by `==`: gcc-16 compares two alias
        // reflections of the same underlying type as equal, which would make the
        // duplicate invisible. Two aliases cannot share an identifier in one
        // namespace, so the identifier is the reliable identity here.
        if (std::meta::identifier_of(m) == std::meta::identifier_of(Alias))
            continue;
        if (std::meta::dealias(m) == std::meta::dealias(Alias) &&
            Resolution::alias_participates(m, L, pol, Ns))
            return false;
    }
    return true;
}

template <std::meta::info Alias, lang L, class Style,
          ent_kind Kind = ent_kind::class_>
consteval const char* alias_bound_name() {
    if constexpr (welder::weld_as_of<Alias, L>() != nullptr)
        return welder::weld_as_of<Alias, L>();
    else if constexpr (welder::weld_as_of<std::meta::dealias(Alias), L>() !=
                       nullptr)
        return welder::weld_as_of<std::meta::dealias(Alias), L>();
    else
        return welder::name_of<Alias, L, Style, Kind>();
}
 
} // namespace detail

consteval bool is_nested_type(std::meta::info type) {
    const std::meta::info outer{std::meta::parent_of(type)};
    return std::meta::is_type(outer) && std::meta::is_class_type(outer);
}
 
namespace detail {

template <class Resolution>
consteval bool nested_type_registered(std::meta::info type, lang L) {
    const std::meta::info outer{std::meta::parent_of(type)};
    return std::meta::has_identifier(type) && std::meta::is_complete_type(type) &&
           detail::member_access_admitted<Resolution>(type, L, outer) &&
           member_bound(type, L, policy_of(outer)) &&
           Resolution::counts_as_registered(outer, L);
}

template <class Resolution, std::meta::info Outer, std::meta::info Alias>
consteval bool sole_member_alias_of_target(lang L, policy_kind pol) {
    for (auto m : std::meta::members_of(Outer,
                                        std::meta::access_context::unchecked())) {
        if (!std::meta::is_type_alias(m) || !std::meta::has_identifier(m))
            continue;
        // Self-identity by NAME (== collapses alias reflections on gcc-16; two
        // member aliases cannot share an identifier in one class).
        if (std::meta::identifier_of(m) == std::meta::identifier_of(Alias))
            continue;
        if (std::meta::dealias(m) == std::meta::dealias(Alias) &&
            member_access_admitted<Resolution>(m, L, Outer) &&
            Resolution::class_member_participates(m, L, pol, Outer))
            return false;
    }
    return true;
}

template <class Resolution>
consteval bool registered_by_member_alias(std::meta::info scope,
                                          std::meta::info type, lang L) {
    const policy_kind pol{policy_of(scope)};
    for (auto m : std::meta::members_of(scope,
                                        std::meta::access_context::unchecked())) {
        if (!std::meta::is_type_alias(m) || !std::meta::has_identifier(m))
            continue;
        if (std::meta::dealias(m) != type)
            continue;
        if (member_access_admitted<Resolution>(m, L, scope) &&
            Resolution::class_member_participates(m, L, pol, scope))
            return true;
    }
    return false;
}

template <class Resolution, std::meta::info Scope>
struct scoped_registration : Resolution {
    static consteval bool counts_as_registered(std::meta::info type, lang L) {
        if (Resolution::counts_as_registered(type, L))
            return true;
        if (!(std::meta::is_class_type(type) || std::meta::is_enum_type(type)))
            return false;
        // The nested chain, alias-aware: a nested type of an alias-registered
        // target resolves through this oracle again.
        if (welder::is_nested_type(type) &&
            nested_type_registered<scoped_registration>(type, L))
            return true;
        return registered_by_member_alias<Resolution>(Scope, type, L);
    }
};
 
} // namespace detail
 
namespace carriages {
 
// --- resolution policies ----------------------------------------------------
//
// A carriage's *resolution* decides **which** entities participate — the reading of
// welder's markers — kept separate from *how* they are emitted (the carriage body)
// and *whether* they are representable (the bindability gate, which both share). Two
// ship: `marker_resolution` (honor `weld`/`policy`/marks — the default) and
// `greedy_resolution` (ignore the markers, bind everything — tack welding).

struct marker_resolution {
    static consteval bool participates(std::meta::info entity, lang L) {
        return welder::welded_for(entity, L);
    }

    static consteval bool is_native_base(std::meta::info base, lang L,
                                         std::meta::info /*bound_into*/) {
        return welder::welded_for(base, L);
    }

    template <std::meta::info T, lang L>
    static consteval auto native_bases() {
        return detail::native_base_types<T, L>();
    }

    static consteval bool member_participates(std::meta::info mem, lang L,
                                              policy_kind pol,
                                              std::meta::info /*bound_into*/) {
        return welder::welded_for(mem, L) && member_bound(mem, L, pol);
    }

    static consteval bool alias_participates(std::meta::info mem, lang L,
                                             policy_kind pol,
                                             std::meta::info /*bound_into*/) {
        return welder::alias_welded_for(mem, L) &&
               member_bound(std::meta::dealias(mem), L, pol);
    }

    static consteval bool class_member_participates(std::meta::info mem, lang L,
                                                    policy_kind pol,
                                                    std::meta::info /*bound_into*/) {
        return member_bound(mem, L, pol);
    }

    static consteval bool protected_participates(std::meta::info mem, lang L,
                                                 std::meta::info /*bound_into*/) {
        return welder::protected_welded(std::meta::parent_of(mem), L);
    }

    static consteval bool namespace_participates(std::meta::info ns, lang L,
                                                 policy_kind pol,
                                                 std::meta::info /*bound_into*/) {
        return member_bound(ns, L, pol) && detail::namespace_has_bound(ns, L);
    }

    static consteval bool counts_as_registered(std::meta::info type, lang L) {
        if (welder::welded_for(type, L))
            return true;
        if ((std::meta::is_class_type(type) || std::meta::is_enum_type(type)) &&
            welder::is_nested_type(type))
            return detail::nested_type_registered<marker_resolution>(type, L);
        return false;
    }
};

template <bool WeldProtected = false>
struct greedy_resolution {
    static consteval bool participates(std::meta::info, lang) { return true; }
    static consteval bool is_native_base(std::meta::info, lang,
                                         std::meta::info /*bound_into*/) {
        return false;
    }
    template <std::meta::info, lang>
    static consteval auto native_bases() {
        return std::array<std::meta::info, 0>{};
    }
    static consteval bool member_participates(std::meta::info mem, lang L,
                                              policy_kind pol,
                                              std::meta::info /*bound_into*/) {
        return member_bound(mem, L, pol);
    }

    static consteval bool alias_participates(std::meta::info mem, lang L,
                                             policy_kind pol,
                                             std::meta::info /*bound_into*/) {
        return member_bound(std::meta::dealias(mem), L, pol);
    }

    static consteval bool class_member_participates(std::meta::info mem, lang L,
                                                    policy_kind pol,
                                                    std::meta::info /*bound_into*/) {
        return member_bound(mem, L, pol);
    }

    static consteval bool protected_participates(std::meta::info mem, lang L,
                                                 std::meta::info /*bound_into*/) {
        return WeldProtected ||
               welder::protected_welded(std::meta::parent_of(mem), L);
    }
    static consteval bool namespace_participates(std::meta::info ns, lang L,
                                                 policy_kind pol,
                                                 std::meta::info /*bound_into*/) {
        return member_bound(ns, L, pol) && detail::namespace_has_bindable(ns, L);
    }

    static consteval bool counts_as_registered(std::meta::info type, lang L) {
        if (!(std::meta::is_class_type(type) || std::meta::is_enum_type(type)))
            return false;
        if (!std::meta::is_complete_type(type))
            return false;
        if (welder::is_nested_type(type))
            return detail::nested_type_registered<greedy_resolution>(type, L);
        return member_bound(type, L, policy_kind::automatic);
    }
};

template <resolution Resolution>
struct basic_carriage {
  private:
    template <rod B, std::meta::info BoundInto, std::meta::info Src, class Style,
              class Cls>
    static void bind_members(Cls& cls) {
        constexpr lang L{B::language};
        constexpr auto ctx{std::meta::access_context::unchecked()};
 
        template for (constexpr auto base :
                      std::define_static_array(welder::public_bases(Src))) {
            if constexpr (!Resolution::is_native_base(base, L, Src))
                bind_members<B, BoundInto, base, Style>(cls);
        }
 
        constexpr policy_kind pol{policy_of(Src)};
 
        // The gate for class members runs through the SCOPE-AWARE oracle: the
        // bound-into type's own member aliases register types the plain oracle
        // cannot see (an alias is unrecoverable from the type it names).
        using Reg = detail::scoped_registration<Resolution, BoundInto>;
 
        template for (constexpr auto mem : std::define_static_array(
                          std::meta::nonstatic_data_members_of(Src, ctx))) {
            if constexpr (detail::member_access_admitted<Resolution>(mem, L,
                                                                     BoundInto) &&
                          Resolution::class_member_participates(mem, L, pol,
                                                                BoundInto)) {
                welder::assert_member_bindable<B, mem, L, Reg>();
                B::template add_field<mem, Style>(cls);
            }
        }
 
        // Methods and operators are emitted as whole OVERLOAD GROUPS: the walk
        // fires on each group's first participating overload (the leader),
        // gathers the resolution-admitted set, gates every member, and hands the
        // group to the rod in one call — so one-value-per-name frameworks (the
        // Lua rods) register a complete set, and per-overload marks / bespoke
        // resolutions shape the group identically on every rod.
        template for (constexpr auto fn :
                      std::define_static_array(std::meta::members_of(Src, ctx))) {
            if constexpr (detail::is_method_candidate(fn) &&
                          detail::member_access_admitted<Resolution>(fn, L,
                                                                     BoundInto) &&
                          Resolution::class_member_participates(fn, L, pol,
                                                                BoundInto)) {
                if constexpr (detail::is_overload_leader<
                                  detail::method_overload_set<Resolution>>(
                                  fn, L, BoundInto)) {
                    constexpr auto grp{detail::overload_group<
                        detail::method_overload_set<Resolution>, fn, L,
                        BoundInto>()};
                    template for (constexpr auto member :
                                  std::define_static_array(grp)) {
                        welder::assert_callable_bindable<B, member, L, Reg>();
                    }
                    if constexpr (std::meta::is_static_member(fn))
                        B::template add_static_method<grp, Style>(cls);
                    else
                        B::template add_method<grp, Style>(cls);
                }
            } else if constexpr (detail::is_operator_candidate(fn) &&
                                 detail::member_access_admitted<Resolution>(
                                     fn, L, BoundInto) &&
                                 Resolution::class_member_participates(fn, L, pol,
                                                                       BoundInto) &&
                                 B::special_method_name(fn) != nullptr) {
                // A member operator group binds under the backend's special-method
                // name (operator+ -> __add__, ...); unary/binary forms are distinct
                // groups (distinct arity), so they never collide.
                if constexpr (detail::is_overload_leader<
                                  detail::operator_overload_set<Resolution>>(
                                  fn, L, BoundInto)) {
                    constexpr auto grp{detail::overload_group<
                        detail::operator_overload_set<Resolution>, fn, L,
                        BoundInto>()};
                    template for (constexpr auto member :
                                  std::define_static_array(grp)) {
                        welder::assert_callable_bindable<B, member, L, Reg>();
                    }
                    B::template add_operator<grp>(cls);
                }
            }
            // A member function TEMPLATE falls through every branch: not a
            // bindable entity (welder cannot invent its template arguments) —
            // bind an instantiation by chaining it onto the class handle
            // weld_type returns. A participation mark on one is inert, and NOT
            // diagnosable: P2996 refuses annotations_of on an uninstantiated
            // template (the mark is readable only through an instantiation), so
            // welder cannot even see it here to fail fast.
        }
    }

    template <rod B, class E, class Style, class EnumHandle>
    static void emit_enumerators(EnumHandle& e) {
        constexpr lang L{B::language};
        constexpr policy_kind pol{policy_of(^^E)};
        template for (constexpr auto en :
                      std::define_static_array(std::meta::enumerators_of(^^E))) {
            if constexpr (Resolution::class_member_participates(en, L, pol, ^^E))
                B::template add_enumerator<en, Style>(e);
        }
    }

    template <rod B, class T, class Style, class Cls>
    static void bind_class_interior(typename B::module_type& m, Cls& cls) {
        constexpr lang L{B::language};
 
        // Nested member types (classes + enums declared inside T) — recursive:
        // each one's own interior runs this walk again.
        bind_nested_types<B, ^^T, Style>(m, cls);
 
        // Constructors, handed to the rod as ONE participating set (several
        // frameworks want them all at once — sol2's sol::constructors, LuaBridge3's
        // addConstructor). Three carriage-computed pieces:
        //  - the default constructor: constructibility is decided against the type
        //    welder actually constructs, which may be a rod-nominated substitute —
        //    a Python trampoline standing in for an abstract base — exposed as an
        //    optional `B::construction_type<T>` (fall back to T when a rod names
        //    none); a *declared* default constructor's explicit marks are honored
        //    (default_ctor_admitted);
        //  - each participating public non-copy/move constructor — resolved
        //    SYMMETRICALLY with every other member (the type's policy + the
        //    constructor's own marks, per constructor) — each gated for
        //    bindability;
        //  - for a baseless aggregate whose fields all participate, a synthesized
        //    field constructor.
        constexpr bool has_default{
            [] {
                if constexpr (requires {
                                  typename B::template construction_type<T>;
                              })
                    return std::is_default_constructible_v<
                        typename B::template construction_type<T>>;
                else
                    return std::is_default_constructible_v<T>;
            }() &&
            detail::default_ctor_admitted<Resolution, ^^T, L>()};
        constexpr auto ctors{
            detail::ctor_group<Resolution, ^^T, L, policy_of(^^T)>()};
        template for (constexpr auto ctor : std::define_static_array(ctors)) {
            // Scope-aware gate: T's own member aliases may register a
            // parameter's type (see bind_members' Reg).
            welder::assert_callable_bindable<
                B, ctor, L, detail::scoped_registration<Resolution, ^^T>>();
        }
        constexpr bool aggregate{
            detail::aggregate_initializable<T, L, Resolution>()};
        // The fail-safe against SILENT uninstantiability: if the policy filtering
        // left T with no constructor at all, but this same resolution would have
        // admitted some under `automatic`, the emptiness came from a default (an
        // opt_in type whose constructors nobody marked) rather than a decision —
        // hard error. Explicit emptiness passes: mark::exclude-ing the
        // constructors zeroes the automatic baseline too (factory-only intent),
        // and a type automatic would also leave bare (private/deleted ctors, an
        // abstract base) was never instantiable to begin with.
        static_assert(
            has_default || aggregate || ctors.size() != 0 ||
                detail::ctor_group<Resolution, ^^T, L,
                                   policy_kind::automatic>()
                        .size() == 0,
            "welder: policy filtering left this type with NO constructor — it "
            "would be silently uninstantiable from the target language. Mark a "
            "constructor [[=welder::mark::include]] (opt_in binds only marked "
            "members, constructors included), or mark them all "
            "[[=welder::mark::exclude]] to make a factory-only surface explicit. "
            "The type is the T of this bind_type<B, T, Style> instantiation.");
        B::template add_constructors<T, ctors, has_default, aggregate>(cls);
 
        // Data members + methods + operators (T's own, plus flattened bases).
        bind_members<B, ^^T, ^^T, Style>(cls);
    }

    template <rod B, std::meta::info Outer, class Style, class Cls>
    static void bind_nested_types(typename B::module_type& m, Cls& cls) {
        constexpr lang L{B::language};
        constexpr auto ctx{std::meta::access_context::unchecked()};
        constexpr policy_kind pol{policy_of(Outer)};
        template for (constexpr auto mem : std::define_static_array(
                          std::meta::members_of(Outer, ctx))) {
            if constexpr (std::meta::is_type(mem) &&
                          !std::meta::is_type_alias(mem) &&
                          (std::meta::is_class_type(mem) ||
                           std::meta::is_enum_type(mem)) &&
                          std::meta::has_identifier(mem) &&
                          std::meta::is_complete_type(mem)) {
                if constexpr (detail::member_access_admitted<Resolution>(
                                  mem, L, Outer) &&
                              Resolution::class_member_participates(mem, L, pol,
                                                                    Outer)) {
                    if constexpr (std::meta::is_enum_type(mem))
                        bind_nested_enum<B, typename [:mem:], Style>(m, cls);
                    else
                        bind_nested_type<B, typename [:mem:], Style>(m, cls);
                }
            } else if constexpr (std::meta::is_type_alias(mem) &&
                                 std::meta::has_identifier(mem) &&
                                 (std::meta::is_class_type(
                                      std::meta::dealias(mem)) ||
                                  std::meta::is_enum_type(
                                      std::meta::dealias(mem))) &&
                                 std::meta::is_complete_type(
                                     std::meta::dealias(mem))) {
                // A MEMBER TYPE ALIAS: participates by the member rules (the
                // outer's policy + the alias's own marks), with the bindability
                // gate as the register-or-skip arbiter — a target the gate
                // already passes (natively castable, a bindable STL wrapper,
                // welded, otherwise registered, or trusted) converts without
                // this registration, so registering it again would be redundant
                // or an outright duplicate. The rule registers exactly the
                // types that otherwise could not cross the boundary — nested
                // under the outer, named by the alias (its weld_as → the
                // target's → the styled identifier). Under greedy resolution
                // every complete type passes the gate, so member aliases never
                // participate in a tack weld, by construction.
                static_assert(
                    welder::member_alias_marks_admissible(mem),
                    "welder: only weld_as / exclude / include / only may be "
                    "attached to a member type alias; policy and doc marks "
                    "belong on the target type, and weld / trust_bindable have "
                    "no meaning here (participation follows the outer's policy "
                    "and the bindability gate)");
                if constexpr (detail::member_access_admitted<Resolution>(
                                  mem, L, Outer) &&
                              Resolution::class_member_participates(mem, L, pol,
                                                                    Outer) &&
                              !welder::bindable<
                                  B, typename [:std::meta::dealias(mem):], L,
                                  Resolution>()) {
                    static_assert(
                        detail::sole_member_alias_of_target<Resolution, Outer,
                                                            mem>(L, pol),
                        "welder: two member aliases in this class weld the SAME "
                        "target type — each target may be registered under "
                        "exactly one name; mark::exclude one of them");
                    if constexpr (std::meta::is_enum_type(
                                      std::meta::dealias(mem)))
                        bind_nested_enum<B, typename [:std::meta::dealias(mem):],
                                         Style>(
                            m, cls,
                            detail::alias_bound_name<mem, L, Style,
                                                     ent_kind::enum_>());
                    else
                        bind_nested_type<B, typename [:std::meta::dealias(mem):],
                                         Style, mem>(
                            m, cls, detail::alias_bound_name<mem, L, Style>());
                }
            }
        }
    }

    template <rod B, class T, class Style, std::meta::info Decl = std::meta::info{},
              class OuterCls>
    static void bind_nested_type(typename B::module_type& m, OuterCls& outer,
                                 const char* name = nullptr) {
        constexpr lang L{B::language};
        // name_of_or, not `name ? name : name_of<…>`: the consteval fallback
        // must only be compiled when T is statically nameable — an alias-welded
        // specialization has no identifier and always arrives with an override.
        const char* cls_name{
            welder::name_of_or<^^T, L, Style, ent_kind::class_>(name)};
        auto cls{make_nested_class_of<B, T, Decl,
                                      Resolution::template native_bases<^^T, L>()>(
            m, outer, cls_name, welder::doc_of<^^T>())};
        bind_class_interior<B, T, Style>(m, cls);
        // A second OPTIONAL rod hook, after the interior: a rod whose class
        // handle re-opens the class by name/path (LuaBridge3) cannot move the
        // class under the outer at creation time — every later add_* call would
        // re-open a key that no longer exists — so it finalizes the placement
        // here, once the interior (nested types included, so innermost first)
        // is fully registered.
        if constexpr (requires {
                          B::template finish_nested_class<T>(m, outer, cls,
                                                             cls_name);
                      })
            B::template finish_nested_class<T>(m, outer, cls, cls_name);
    }

    template <rod B, class E, class Style, class OuterCls>
    static void bind_nested_enum(typename B::module_type& m, OuterCls& outer,
                                 const char* name = nullptr) {
        constexpr lang L{B::language};
        const char* enum_name{
            welder::name_of_or<^^E, L, Style, ent_kind::enum_>(name)};
        auto e{make_nested_enum_of<B, E>(m, outer, enum_name,
                                         welder::doc_of<^^E>())};
        emit_enumerators<B, E, Style>(e);
        B::template finish_enum<E>(e);
    }

    template <rod B, class T, std::meta::info Decl, auto Bases, class OuterCls>
    static auto make_nested_class_of(typename B::module_type& m, OuterCls& outer,
                                     const char* cls_name, const char* doc) {
        constexpr std::meta::info decl{Decl == std::meta::info{} ? ^^T : Decl};
        if constexpr (requires {
                          B::template make_nested_class<T, decl, Bases>(
                              m, outer, cls_name, doc,
                              std::make_index_sequence<Bases.size()>{});
                      })
            return B::template make_nested_class<T, decl, Bases>(
                m, outer, cls_name, doc,
                std::make_index_sequence<Bases.size()>{});
        else if constexpr (requires {
                               B::template make_nested_class<T, Bases>(
                                   m, outer, cls_name, doc,
                                   std::make_index_sequence<Bases.size()>{});
                           })
            return B::template make_nested_class<T, Bases>(
                m, outer, cls_name, doc,
                std::make_index_sequence<Bases.size()>{});
        else
            return make_class_of<B, T, decl, Bases>(m, cls_name, doc);
    }

    template <rod B, class E, class OuterCls>
    static auto make_nested_enum_of(typename B::module_type& m, OuterCls& outer,
                                    const char* name, const char* doc) {
        if constexpr (requires {
                          B::template make_nested_enum<E>(m, outer, name, doc);
                      })
            return B::template make_nested_enum<E>(m, outer, name, doc);
        else
            return B::template make_enum<E>(m, name, doc);
    }
 
  public:
    template <rod B, class E, class Style = naming::none>
    static auto bind_enum(typename B::module_type& m, const char* name = nullptr) {
        constexpr lang L{B::language};
        static_assert(Resolution::participates(^^E, L),
                      "welder: weld_type<E>: enum E is not welded for this backend's "
                      "language; annotate it with [[=welder::weld(...)]]");
        const char* enum_name{
            welder::name_of_or<^^E, L, Style, ent_kind::enum_>(name)};
        auto e{B::template make_enum<E>(m, enum_name, welder::doc_of<^^E>())};
        emit_enumerators<B, E, Style>(e);
        B::template finish_enum<E>(e);
        return e;
    }

    template <rod B, class T, std::meta::info Decl, auto Bases>
    static auto make_class_of(typename B::module_type& m, const char* cls_name,
                              const char* doc) {
        if constexpr (requires {
                          B::template make_class<T, Decl, Bases>(
                              m, cls_name, doc,
                              std::make_index_sequence<Bases.size()>{});
                      })
            return B::template make_class<T, Decl, Bases>(
                m, cls_name, doc, std::make_index_sequence<Bases.size()>{});
        else
            return B::template make_class<T, Bases>(
                m, cls_name, doc, std::make_index_sequence<Bases.size()>{});
    }

    template <rod B, class T, class Style = naming::none,
              std::meta::info Decl = std::meta::info{}>
    static auto bind_type(typename B::module_type& m, const char* name = nullptr) {
        constexpr lang L{B::language};
        // Decl is the *declaring* entity when it differs from ^^T: the namespace-
        // scope alias through which a class-template specialization was welded
        // (bind_namespace's alias branch, which has already resolved participation
        // — the alias's own `weld` counts there, so ^^T alone can't be re-checked).
        static_assert(Decl != std::meta::info{} || Resolution::participates(^^T, L),
                      "welder: weld_type<T>: T is not welded for this backend's "
                      "language; annotate it with [[=welder::weld(...)]]");
        constexpr auto ctx{std::meta::access_context::unchecked()};
 
        const char* cls_name{
            welder::name_of_or<^^T, L, Style, ent_kind::class_>(name)};
 
        // Native bases → bases of the class handle; the user binds them first.
        // A text-emitting rod that must *spell* the type in C++ (the trampoline
        // generator) declares the extended, declaring-entity-aware make_class; it
        // receives Decl — the alias, the one C++ name a specialization has — or
        // ^^T itself for a directly-declared class. Detected via requires, so the
        // runtime rods keep the plain form (they need only T + the bound name).
        constexpr auto bases{Resolution::template native_bases<^^T, L>()};
        auto cls{make_class_of<B, T, (Decl == std::meta::info{} ? ^^T : Decl),
                               bases>(m, cls_name, welder::doc_of<^^T>())};
 
        // Nested member types, constructors, data members / methods / operators
        // (shared with bind_nested_type — nesting recurses through it).
        bind_class_interior<B, T, Style>(m, cls);
 
        return cls;
    }

    template <rod B, std::meta::info Fn, class Style = naming::none>
    static auto bind_function(typename B::module_type& m, const char* name = nullptr) {
        constexpr lang L{B::language};
        static_assert(std::meta::is_function(Fn),
                      "welder: weld_function<Fn>: Fn must reflect a (free) function");
        static_assert(Resolution::participates(Fn, L),
                      "welder: weld_function<Fn>: Fn is not welded for this backend's "
                      "language; annotate it with [[=welder::weld(...)]]");
        constexpr auto grp{detail::manual_function_group<Resolution, Fn, L>()};
        template for (constexpr auto member : std::define_static_array(grp)) {
            welder::assert_callable_bindable<B, member, L, Resolution>();
        }
        // Forward the rod's handle (the bound function object, where the
        // framework has one); a void-returning rod makes this void too.
        return B::template add_function<grp, Style>(m, name);
    }

    template <rod B, std::meta::info Var, class Style = naming::none>
    static auto bind_variable(typename B::module_type& m, const char* name = nullptr) {
        constexpr lang L{B::language};
        static_assert(std::meta::is_variable(Var),
                      "welder: weld_variable<Var>: Var must reflect a namespace "
                      "variable");
        static_assert(Resolution::participates(Var, L),
                      "welder: weld_variable<Var>: Var is not welded for this "
                      "backend's language; annotate it with [[=welder::weld(...)]]");
        welder::assert_member_bindable<B, Var, L, Resolution>();
        auto session{B::open_module(m)};
        // Forward the rod's handle if its add_variable yields one (the shipped
        // rods return void — a bound constant is a snapshot, a mutable global a
        // module property; neither has a framework object worth returning), but
        // the session must still close after the registration.
        if constexpr (std::is_void_v<decltype(B::template add_variable<Var, Style>(
                          m, session, name))>) {
            B::template add_variable<Var, Style>(m, session, name);
            B::close_module(m, session);
        } else {
            auto handle{B::template add_variable<Var, Style>(m, session, name)};
            B::close_module(m, session);
            return handle;
        }
    }

    template <rod B, std::meta::info Ns, class Style = naming::none>
    static void bind_namespace(typename B::module_type& m) {
        static_assert(std::meta::is_namespace(Ns),
                      "welder: weld_namespace<Ns>: Ns must reflect a namespace");
        constexpr lang L{B::language};
        constexpr auto ctx{std::meta::access_context::unchecked()};
        constexpr policy_kind pol{policy_of(Ns)};
 
        // A [[=welder::doc]] on the namespace becomes the (sub)module docstring.
        if (const char* nsdoc{welder::doc_of<Ns>()})
            B::set_module_doc(m, nsdoc);
 
        // The backend's per-module session: scratch state for attributes it emits in
        // one batch at the end (e.g. live variable properties). Opened before the
        // walk, finalized by close_module after it.
        auto session{B::open_module(m)};
 
        template for (constexpr auto mem :
                      std::define_static_array(std::meta::members_of(Ns, ctx))) {
            // The alias branch must come first: type predicates (is_class_type)
            // look through an alias, so the class branch below would swallow it.
            if constexpr (std::meta::is_type_alias(mem)) {
                if constexpr (welder::names_template_specialization(mem)) {
                    // The one way an *instantiation* enters a sweep (members_of
                    // enumerates the template, never its specializations): the
                    // alias is both the C++ spelling and the target-language name.
                    static_assert(
                        welder::alias_marks_admissible(mem),
                        "welder: only weld / weld_as may be attached to a "
                        "namespace-scope alias; every other mark belongs on the "
                        "class template, where it applies to all instantiations");
                    if constexpr (Resolution::alias_participates(mem, L, pol, Ns)) {
                        static_assert(
                            detail::sole_alias_of_target<Resolution, Ns, mem>(L,
                                                                              pol),
                            "welder: two aliases in this namespace weld the SAME "
                            "template specialization — each specialization may be "
                            "welded under exactly one name");
                        bind_type<B, typename [:mem:], Style, mem>(
                            m, detail::alias_bound_name<mem, L, Style>());
                    }
                } else {
                    // An alias to a plain (non-template) type: binding it would
                    // register the type a second time under the alias name — a
                    // welded target makes the alias a likely mistake, diagnosed
                    // rather than silently skipped. (Rename with weld_as instead.)
                    static_assert(
                        !((std::meta::is_class_type(std::meta::dealias(mem)) ||
                           std::meta::is_enum_type(std::meta::dealias(mem))) &&
                          welder::alias_welded_for(mem, L)),
                        "welder: a namespace-scope alias to a welded NON-template "
                        "type would bind the type twice (it already binds under "
                        "its own name); remove the alias's weld, or rename the "
                        "type with [[=welder::weld_as(...)]]");
                }
            } else if constexpr (std::meta::is_type(mem) &&
                                 std::meta::is_class_type(mem)) {
                if constexpr (Resolution::member_participates(mem, L, pol, Ns))
                    bind_type<B, typename [:mem:], Style>(m, nullptr);
            } else if constexpr (std::meta::is_type(mem) && std::meta::is_enum_type(mem)) {
                if constexpr (Resolution::member_participates(mem, L, pol, Ns))
                    bind_enum<B, typename [:mem:], Style>(m, nullptr);
            } else if constexpr (std::meta::is_function(mem)) {
                // Free functions bind as whole overload groups, emitted at the
                // group's first participating overload (see bind_members).
                if constexpr (Resolution::member_participates(mem, L, pol, Ns)) {
                    if constexpr (detail::is_overload_leader<
                                      detail::function_overload_set<Resolution>>(
                                      mem, L, Ns)) {
                        constexpr auto grp{detail::overload_group<
                            detail::function_overload_set<Resolution>, mem, L,
                            Ns>()};
                        template for (constexpr auto member :
                                      std::define_static_array(grp)) {
                            welder::assert_callable_bindable<B, member, L,
                                                             Resolution>();
                        }
                        B::template add_function<grp, Style>(m);
                    }
                }
            } else if constexpr (std::meta::is_variable(mem)) {
                if constexpr (Resolution::member_participates(mem, L, pol, Ns)) {
                    welder::assert_member_bindable<B, mem, L, Resolution>();
                    B::template add_variable<mem, Style>(m, session);
                }
            } else if constexpr (std::meta::is_namespace(mem)) {
                // A nested namespace resolves like a leaf under the parent policy (but
                // is never welded): it becomes a submodule when it holds participating
                // content (then resolved under its *own* policy).
                if constexpr (Resolution::namespace_participates(mem, L, pol, Ns)) {
                    auto sub{B::add_submodule(
                        m, welder::name_of<mem, L, Style, ent_kind::submodule>())};
                    bind_namespace<B, mem, Style>(sub);
                }
            }
        }
 
        B::close_module(m, session);
    }

    template <rod B, std::meta::info Ns, class Style = naming::none>
    static typename B::module_type bind_namespace_as_submodule(
        typename B::module_type& m, const char* name = nullptr) {
        static_assert(std::meta::is_namespace(Ns),
                      "welder: weld_namespace_as_submodule<Ns>: Ns must reflect a "
                      "namespace");
        typename B::module_type sub{B::add_submodule(
            m,
            welder::name_of_or<Ns, B::language, Style, ent_kind::submodule>(name))};
        bind_namespace<B, Ns, Style>(sub);
        return sub;
    }

    template <rod B, std::meta::info Ns, class Style = naming::none, class Pre,
              class Post>
    static void build_module(typename B::module_type& m, Pre pre, Post post) {
        static_assert(std::meta::is_namespace(Ns),
                      "welder: weld_module<Ns>: Ns must reflect a namespace");
        static_assert(std::meta::parent_of(Ns) == ^^::,
                      "welder: weld_module<Ns>: Ns must be a top-level namespace (its "
                      "name is meant to be the module name)");
        pre(m);
        bind_namespace<B, Ns, Style>(m);
        post(m);
    }
};
 
} // namespace carriages

using stitch_welding_carriage = carriages::basic_carriage<carriages::marker_resolution>;

using tack_welding_carriage =
    carriages::basic_carriage<carriages::greedy_resolution<>>;

using carriage = stitch_welding_carriage;
 
} // namespace welder