diff --git a/idl/IGCObject_DTypeVar.json5 b/idl/IGCObject_DTypeVar.json5
new file mode 100644
index 0000000..7e45e22
--- /dev/null
+++ b/idl/IGCObject_DTypeVar.json5
@@ -0,0 +1,16 @@
+{
+    mode: "implementation",
+    output_cpp_dir: "src/type",
+    output_hpp_dir: "include/xo/type",
+    output_impl_subdir: "typevar",
+    includes: [
+    ],
+    local_types: [ ],
+    namespace1: "xo",
+    namespace2: "scm",
+    facet_idl: "idl/GCObject.json5",
+    brief: "provide AGCObject interface for DTypeVar",
+    using_doxygen: true,
+    repr: "DTypeVar",
+    doc: [ "implement AGCObject for DTypeVar" ],
+}
diff --git a/idl/IGCObject_DTypeVarRef.json5 b/idl/IGCObject_DTypeVarRef.json5
new file mode 100644
index 0000000..e75802b
--- /dev/null
+++ b/idl/IGCObject_DTypeVarRef.json5
@@ -0,0 +1,16 @@
+{
+    mode: "implementation",
+    output_cpp_dir: "src/type",
+    output_hpp_dir: "include/xo/type",
+    output_impl_subdir: "typevar",
+    includes: [
+    ],
+    local_types: [ ],
+    namespace1: "xo",
+    namespace2: "scm",
+    facet_idl: "idl/GCObject.json5",
+    brief: "provide AGCObject interface for DTypeVarRef",
+    using_doxygen: true,
+    repr: "DTypeVarRef",
+    doc: [ "implement AGCObject for DTypeVarRef" ],
+}
diff --git a/idl/IType_DTypeVarRef.json5 b/idl/IType_DTypeVarRef.json5
new file mode 100644
index 0000000..245b597
--- /dev/null
+++ b/idl/IType_DTypeVarRef.json5
@@ -0,0 +1,16 @@
+{
+    mode: "implementation",
+    output_cpp_dir: "src/type",
+    output_hpp_dir: "include/xo/type",
+    output_impl_subdir: "typevar",
+    includes: [],
+    local_types: [],
+    namespace1: "xo",
+    namespace2: "scm",
+
+    facet_idl: "idl/Type.json5",
+    brief: "provide AType interface for DTypeVarRef",
+    using_doxygen: true,
+    repr: "DTypeVarRef",
+    doc: [ "implement AType for DTypeVarRef" ],
+}
diff --git a/include/xo/type/TypeVarRef.hpp b/include/xo/type/TypeVarRef.hpp
new file mode 100644
index 0000000..10b80b1
--- /dev/null
+++ b/include/xo/type/TypeVarRef.hpp
@@ -0,0 +1,12 @@
+/** @file TypeVarRef.hpp
+ *
+ *  @author Roland Conybeare, Mar 2026
+ **/
+
+#pragma once
+
+#include "typevar/DTypeVarRef.hpp"
+#include "typevar/IGCObject_DTypeVarRef.hpp"
+#include "typevar/IType_DTypeVarRef.hpp"
+
+/* end TypeVarRef.hpp */
diff --git a/include/xo/type/typevar/DTypeVarRef.hpp b/include/xo/type/typevar/DTypeVarRef.hpp
new file mode 100644
index 0000000..0f67ee1
--- /dev/null
+++ b/include/xo/type/typevar/DTypeVarRef.hpp
@@ -0,0 +1,72 @@
+/** @file DTypeVarRef.hpp
+ *
+ *  @author Roland Conybeare, Mar 2026
+ **/
+
+#pragma once
+
+#include "Type.hpp"
+#include "Metatype.hpp"
+#include <xo/alloc2/Collector.hpp>
+#include <xo/alloc2/Allocator.hpp>
+#include <xo/stringtable2/UniqueString.hpp>
+
+namespace xo {
+    namespace scm {
+        /** @brief An atomic schematika type
+         *
+         *  Types that are not parameterized by types or values.
+         *  For example
+         *    unit, bool, i64, f64
+         *  are atomic in this sense.
+         **/
+        class DTypeVarRef {
+        public:
+            using ACollector = xo::mm::ACollector;
+            using AAllocator = xo::mm::AAllocator;
+            using TypeDescr = xo::reflect::TypeDescr;
+
+        public:
+            /** @defgroup xo-scm-typevarref-ctors constructors **/
+            ///@{
+
+            explicit DTypeVarRef(const DUniqueString * name) : name_{name} {}
+
+            /** create instance using memory from @p mm with metatype @p mtype **/
+            static DTypeVarRef * _make(obj<AAllocator> mm, const DUniqueString * name);
+            /** create instance **/
+            static obj<AType,DTypeVarRef> make(obj<AAllocator> mm, const DUniqueString * name);
+
+            ///@}
+            /** @defgroup xo-scm-typevarref-general-methods general methods **/
+            ///@{
+
+            const DUniqueString * name() const noexcept { return name_; }
+
+            ///@}
+            /** @defgroup xo-scm-atomictype-type-facet **/
+            ///@{
+            Metatype metatype() const noexcept;
+            TypeDescr repr_td() const noexcept;
+            bool is_equal_to(const obj<AType> & y) const noexcept;
+            bool is_subtype_of(const obj<AType> & y) const noexcept;
+            ///@}
+            /** @defgroup xo-scm-atomictype-gcobject-facet **/
+            ///@{
+            std::size_t shallow_size() const noexcept;
+            DTypeVarRef * shallow_copy(obj<AAllocator> mm) const noexcept;
+            std::size_t forward_children(obj<ACollector> gc) noexcept;
+            ///@}
+
+        private:
+            /** unique type-variable name **/
+            const DUniqueString * name_ = nullptr;
+
+            /** resolved type (if/when established) **/
+            obj<AType> type_;
+        };
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end DTypeVarRef.hpp */
diff --git a/include/xo/type/typevar/IGCObject_DTypeVarRef.hpp b/include/xo/type/typevar/IGCObject_DTypeVarRef.hpp
new file mode 100644
index 0000000..876caaa
--- /dev/null
+++ b/include/xo/type/typevar/IGCObject_DTypeVarRef.hpp
@@ -0,0 +1,65 @@
+/** @file IGCObject_DTypeVarRef.hpp
+ *
+ *  Generated automagically from ingredients:
+ *  1. code generator:
+ *       [xo-facet/codegen/genfacet]
+ *     arguments:
+ *       --input [idl/IGCObject_DTypeVarRef.json5]
+ *  2. jinja2 template for abstract facet .hpp file:
+ *       [iface_facet_repr.hpp.j2]
+ *  3. idl for facet methods
+ *       [idl/IGCObject_DTypeVarRef.json5]
+ **/
+
+#pragma once
+
+#include "GCObject.hpp"
+#include "DTypeVarRef.hpp"
+
+namespace xo { namespace scm { class IGCObject_DTypeVarRef; } }
+
+namespace xo {
+    namespace facet {
+        template <>
+        struct FacetImplementation<xo::mm::AGCObject,
+                                   xo::scm::DTypeVarRef>
+        {
+            using ImplType = xo::mm::IGCObject_Xfer
+              <xo::scm::DTypeVarRef,
+               xo::scm::IGCObject_DTypeVarRef>;
+        };
+    }
+}
+
+namespace xo {
+    namespace scm {
+        /** @class IGCObject_DTypeVarRef
+         **/
+        class IGCObject_DTypeVarRef {
+        public:
+            /** @defgroup scm-gcobject-dtypevarref-type-traits **/
+            ///@{
+            using size_type = xo::mm::AGCObject::size_type;
+            using AAllocator = xo::mm::AGCObject::AAllocator;
+            using ACollector = xo::mm::AGCObject::ACollector;
+            using Copaque = xo::mm::AGCObject::Copaque;
+            using Opaque = xo::mm::AGCObject::Opaque;
+            ///@}
+            /** @defgroup scm-gcobject-dtypevarref-methods **/
+            ///@{
+            // const methods
+            /** memory consumption for this instance **/
+            static size_type shallow_size(const DTypeVarRef & self) noexcept;
+            /** copy instance using allocator **/
+            static Opaque shallow_copy(const DTypeVarRef & self, obj<AAllocator> mm) noexcept;
+
+            // non-const methods
+            /** during GC: forward immdiate children **/
+            static size_type forward_children(DTypeVarRef & self, obj<ACollector> gc) noexcept;
+            ///@}
+        };
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end */
\ No newline at end of file
diff --git a/include/xo/type/typevar/IType_DTypeVarRef.hpp b/include/xo/type/typevar/IType_DTypeVarRef.hpp
new file mode 100644
index 0000000..5386a28
--- /dev/null
+++ b/include/xo/type/typevar/IType_DTypeVarRef.hpp
@@ -0,0 +1,66 @@
+/** @file IType_DTypeVarRef.hpp
+ *
+ *  Generated automagically from ingredients:
+ *  1. code generator:
+ *       [xo-facet/codegen/genfacet]
+ *     arguments:
+ *       --input [idl/IType_DTypeVarRef.json5]
+ *  2. jinja2 template for abstract facet .hpp file:
+ *       [iface_facet_repr.hpp.j2]
+ *  3. idl for facet methods
+ *       [idl/IType_DTypeVarRef.json5]
+ **/
+
+#pragma once
+
+#include "Type.hpp"
+#include "DTypeVarRef.hpp"
+
+namespace xo { namespace scm { class IType_DTypeVarRef; } }
+
+namespace xo {
+    namespace facet {
+        template <>
+        struct FacetImplementation<xo::scm::AType,
+                                   xo::scm::DTypeVarRef>
+        {
+            using ImplType = xo::scm::IType_Xfer
+              <xo::scm::DTypeVarRef,
+               xo::scm::IType_DTypeVarRef>;
+        };
+    }
+}
+
+namespace xo {
+    namespace scm {
+        /** @class IType_DTypeVarRef
+         **/
+        class IType_DTypeVarRef {
+        public:
+            /** @defgroup scm-type-dtypevarref-type-traits **/
+            ///@{
+            using obj_AType = xo::scm::AType::obj_AType;
+            using TypeDescr = xo::scm::AType::TypeDescr;
+            using Copaque = xo::scm::AType::Copaque;
+            using Opaque = xo::scm::AType::Opaque;
+            ///@}
+            /** @defgroup scm-type-dtypevarref-methods **/
+            ///@{
+            // const methods
+            /** category for this type **/
+            static Metatype metatype(const DTypeVarRef & self) noexcept;
+            /** reflected representation for instances of this type **/
+            static TypeDescr repr_td(const DTypeVarRef & self) noexcept;
+            /** true iff this type is equal to y **/
+            static bool is_equal_to(const DTypeVarRef & self, const obj_AType & y);
+            /** true iff this is a subtype of y **/
+            static bool is_subtype_of(const DTypeVarRef & self, const obj_AType & y);
+
+            // non-const methods
+            ///@}
+        };
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end */
\ No newline at end of file
diff --git a/src/type/DTypeVarRef.cpp b/src/type/DTypeVarRef.cpp
new file mode 100644
index 0000000..88223ee
--- /dev/null
+++ b/src/type/DTypeVarRef.cpp
@@ -0,0 +1,103 @@
+/** @file DTypeVarRef.cpp
+ *
+ *  @author Roland Conybeare, Mar 2026
+ **/
+
+#include "Metatype.hpp"
+#include "TypeVarRef.hpp"
+#include <xo/reflect/Reflect.hpp>
+#include <xo/facet/FacetRegistry.hpp>
+
+namespace xo {
+    using xo::mm::AGCObject;
+    using xo::reflect::Reflect;
+    using xo::reflect::TypeDescr;
+    using xo::facet::FacetRegistry;
+
+    namespace scm {
+
+        DTypeVarRef *
+        DTypeVarRef::_make(obj<AAllocator> mm, const DUniqueString * name)
+        {
+            void * mem = mm.alloc_for<DTypeVarRef>();
+
+            return new (mem) DTypeVarRef(name);
+        }
+
+        obj<AType,DTypeVarRef>
+        DTypeVarRef::make(obj<AAllocator> mm, const DUniqueString * name)
+        {
+            return obj<AType,DTypeVarRef>(_make(mm, name));
+        }
+
+        // ----- Type facet -----
+
+        Metatype
+        DTypeVarRef::metatype() const noexcept
+        {
+            if (type_) {
+                // resolved typevar reference
+
+                return type_.metatype();
+            } else {
+                // type var reference, not yet resolved
+
+                return Metatype::t_any();
+            }
+        }
+
+        TypeDescr
+        DTypeVarRef::repr_td() const noexcept
+        {
+            return Reflect::require<void *>();
+        }
+
+        bool
+        DTypeVarRef::is_equal_to(const obj<AType> & y) const noexcept
+        {
+            // not really well-defined until types are resolved
+
+            return (this->metatype().code() == y.metatype().code());
+        }
+
+        bool
+        DTypeVarRef::is_subtype_of(const obj<AType> & y) const noexcept
+        {
+            Metatype x_mtype = this->metatype();
+            Metatype y_mtype = y.metatype();
+
+            if (y_mtype.code() == Metatype::code::t_any)
+                return true;
+
+            return (x_mtype.code() == y_mtype.code());
+        }
+
+        // ----- GCObject facet -----
+
+        std::size_t
+        DTypeVarRef::shallow_size() const noexcept
+        {
+            return sizeof(DTypeVarRef);
+        }
+
+        DTypeVarRef *
+        DTypeVarRef::shallow_copy(obj<AAllocator> mm) const noexcept
+        {
+            return mm.std_copy_for(this);
+        }
+
+        std::size_t
+        DTypeVarRef::forward_children(obj<ACollector> gc) noexcept
+        {
+            {
+                auto e = FacetRegistry::instance().variant<AGCObject,AType>(type_);
+                gc.forward_inplace(e.iface(), (void **)&type_.data_);
+            }
+
+            return this->shallow_size();
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end DTypeVarRef.cpp */
diff --git a/src/type/IGCObject_DTypeVar.cpp b/src/type/IGCObject_DTypeVar.cpp
new file mode 100644
index 0000000..799cf66
--- /dev/null
+++ b/src/type/IGCObject_DTypeVar.cpp
@@ -0,0 +1,39 @@
+/** @file IGCObject_DTypeVar.cpp
+ *
+ *  Generated automagically from ingredients:
+ *  1. code generator:
+ *       [xo-facet/codegen/genfacet]
+ *     arguments:
+ *       --input [idl/IGCObject_DTypeVar.json5]
+ *  2. jinja2 template for abstract facet .hpp file:
+ *       [iface_facet_any.hpp.j2]
+ *  3. idl for facet methods
+ *       [idl/IGCObject_DTypeVar.json5]
+**/
+
+#include "typevar/IGCObject_DTypeVar.hpp"
+
+namespace xo {
+    namespace scm {
+        auto
+        IGCObject_DTypeVar::shallow_size(const DTypeVar & self) noexcept -> size_type
+        {
+            return self.shallow_size();
+        }
+
+        auto
+        IGCObject_DTypeVar::shallow_copy(const DTypeVar & self, obj<AAllocator> mm) noexcept -> Opaque
+        {
+            return self.shallow_copy(mm);
+        }
+
+        auto
+        IGCObject_DTypeVar::forward_children(DTypeVar & self, obj<ACollector> gc) noexcept -> size_type
+        {
+            return self.forward_children(gc);
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end IGCObject_DTypeVar.cpp */
diff --git a/src/type/IGCObject_DTypeVarRef.cpp b/src/type/IGCObject_DTypeVarRef.cpp
new file mode 100644
index 0000000..c0aeb3b
--- /dev/null
+++ b/src/type/IGCObject_DTypeVarRef.cpp
@@ -0,0 +1,39 @@
+/** @file IGCObject_DTypeVarRef.cpp
+ *
+ *  Generated automagically from ingredients:
+ *  1. code generator:
+ *       [xo-facet/codegen/genfacet]
+ *     arguments:
+ *       --input [idl/IGCObject_DTypeVarRef.json5]
+ *  2. jinja2 template for abstract facet .hpp file:
+ *       [iface_facet_any.hpp.j2]
+ *  3. idl for facet methods
+ *       [idl/IGCObject_DTypeVarRef.json5]
+**/
+
+#include "typevar/IGCObject_DTypeVarRef.hpp"
+
+namespace xo {
+    namespace scm {
+        auto
+        IGCObject_DTypeVarRef::shallow_size(const DTypeVarRef & self) noexcept -> size_type
+        {
+            return self.shallow_size();
+        }
+
+        auto
+        IGCObject_DTypeVarRef::shallow_copy(const DTypeVarRef & self, obj<AAllocator> mm) noexcept -> Opaque
+        {
+            return self.shallow_copy(mm);
+        }
+
+        auto
+        IGCObject_DTypeVarRef::forward_children(DTypeVarRef & self, obj<ACollector> gc) noexcept -> size_type
+        {
+            return self.forward_children(gc);
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end IGCObject_DTypeVarRef.cpp */
diff --git a/src/type/IType_DTypeVar.cpp b/src/type/IType_DTypeVar.cpp
new file mode 100644
index 0000000..16397be
--- /dev/null
+++ b/src/type/IType_DTypeVar.cpp
@@ -0,0 +1,46 @@
+/** @file IType_DTypeVar.cpp
+ *
+ *  Generated automagically from ingredients:
+ *  1. code generator:
+ *       [xo-facet/codegen/genfacet]
+ *     arguments:
+ *       --input [idl/IType_DTypeVar.json5]
+ *  2. jinja2 template for abstract facet .hpp file:
+ *       [iface_facet_any.hpp.j2]
+ *  3. idl for facet methods
+ *       [idl/IType_DTypeVar.json5]
+**/
+
+#include "typevar/IType_DTypeVar.hpp"
+
+namespace xo {
+    namespace scm {
+        auto
+        IType_DTypeVar::metatype(const DTypeVar & self) noexcept -> Metatype
+        {
+            return self.metatype();
+        }
+
+        auto
+        IType_DTypeVar::repr_td(const DTypeVar & self) noexcept -> TypeDescr
+        {
+            return self.repr_td();
+        }
+
+        auto
+        IType_DTypeVar::is_equal_to(const DTypeVar & self, const obj_AType & y) -> bool
+        {
+            return self.is_equal_to(y);
+        }
+
+        auto
+        IType_DTypeVar::is_subtype_of(const DTypeVar & self, const obj_AType & y) -> bool
+        {
+            return self.is_subtype_of(y);
+        }
+
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end IType_DTypeVar.cpp */
diff --git a/src/type/IType_DTypeVarRef.cpp b/src/type/IType_DTypeVarRef.cpp
new file mode 100644
index 0000000..f1ce54c
--- /dev/null
+++ b/src/type/IType_DTypeVarRef.cpp
@@ -0,0 +1,46 @@
+/** @file IType_DTypeVarRef.cpp
+ *
+ *  Generated automagically from ingredients:
+ *  1. code generator:
+ *       [xo-facet/codegen/genfacet]
+ *     arguments:
+ *       --input [idl/IType_DTypeVarRef.json5]
+ *  2. jinja2 template for abstract facet .hpp file:
+ *       [iface_facet_any.hpp.j2]
+ *  3. idl for facet methods
+ *       [idl/IType_DTypeVarRef.json5]
+**/
+
+#include "typevar/IType_DTypeVarRef.hpp"
+
+namespace xo {
+    namespace scm {
+        auto
+        IType_DTypeVarRef::metatype(const DTypeVarRef & self) noexcept -> Metatype
+        {
+            return self.metatype();
+        }
+
+        auto
+        IType_DTypeVarRef::repr_td(const DTypeVarRef & self) noexcept -> TypeDescr
+        {
+            return self.repr_td();
+        }
+
+        auto
+        IType_DTypeVarRef::is_equal_to(const DTypeVarRef & self, const obj_AType & y) -> bool
+        {
+            return self.is_equal_to(y);
+        }
+
+        auto
+        IType_DTypeVarRef::is_subtype_of(const DTypeVarRef & self, const obj_AType & y) -> bool
+        {
+            return self.is_subtype_of(y);
+        }
+
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end IType_DTypeVarRef.cpp */