sdk: make 'vsql' top-level namespace

This provides a clearer delineation between the new and old APIs, and
should make errors harder to introduce.

Issue #429

Author: malone-at-work

mysql-test/suite/villagesql/std_data/aggregate_vdf.cc

@@ -125,7 +125,7 @@ void vdf_max_clear(vef_context_t *, vef_vdf_args_t *args) {
 void vdf_max_accumulate(vef_context_t *ctx, vef_vdf_args_t *args,
                         vef_vdf_result_t *) {
   auto *state = static_cast<MaxState *>(args->user_data);
-  vef_invalue_t val = villagesql::func_builder::get_invalue(ctx, args, 0);
+  vef_invalue_t val = vsql::func_builder::get_invalue(ctx, args, 0);
   if (!val.is_null) {
     if (!state->has_value || val.int_value > state->max_val) {
       state->max_val = val.int_value;

villagesql/examples/vsql-complex/src/complex.cc

@@ -104,8 +104,8 @@ size_t fnv1a_hash(const unsigned char *data, size_t len) {
 
 // COMPLEX encode: "(real,imag)" -> 16 bytes (with canonicalization of -0.0)
 // STRING -> COMPLEX
-bool complex_from_string(std::string_view from,
-                         villagesql::Span<unsigned char> buf, size_t *length) {
+bool complex_from_string(std::string_view from, vsql::Span<unsigned char> buf,
+                         size_t *length) {
   if (buf.size() < kComplexSize) return true;
   Complex cx;
   std::string from_str(from);
@@ -121,8 +121,8 @@ bool complex_from_string(std::string_view from,
 // COMPLEX2 encode: "(real,imag)" -> 16 bytes (without canonicalization,
 // preserves -0.0 in binary form)
 // STRING -> COMPLEX2
-bool complex2_from_string(std::string_view from,
-                          villagesql::Span<unsigned char> buf, size_t *length) {
+bool complex2_from_string(std::string_view from, vsql::Span<unsigned char> buf,
+                          size_t *length) {
   if (buf.size() < kComplexSize) return true;
   Complex cx;
   std::string from_str(from);
@@ -138,8 +138,8 @@ bool complex2_from_string(std::string_view from,
 
 // Decode: 16 bytes -> "(real,imag)" string
 // COMPLEX -> STRING
-bool complex_to_string(villagesql::Span<const unsigned char> data,
-                       villagesql::Span<char> out, size_t *out_len) {
+bool complex_to_string(vsql::Span<const unsigned char> data,
+                       vsql::Span<char> out, size_t *out_len) {
   if (data.size() != kComplexSize) return true;
   Complex cx = load_complex(data.data());
   int written = snprintf(out.data(), out.size(), "(%g,%g)", cx.re, cx.im);
@@ -149,8 +149,8 @@ bool complex_to_string(villagesql::Span<const unsigned char> data,
 }
 
 // Compare: (COMPLEX, COMPLEX) -> INT for ORDER BY, indexes
-int complex_compare(villagesql::Span<const unsigned char> a,
-                    villagesql::Span<const unsigned char> b) {
+int complex_compare(vsql::Span<const unsigned char> a,
+                    vsql::Span<const unsigned char> b) {
   if (a.size() != kComplexSize || b.size() != kComplexSize) return 0;
   Complex lhs = load_complex(a.data());
   Complex rhs = load_complex(b.data());
@@ -168,7 +168,7 @@ int complex_compare(villagesql::Span<const unsigned char> a,
 // Canonicalizes -0 to +0 before hashing so that -0.0 and +0.0 hash to the
 // same bucket. This allows COMPLEX2 to preserve -0 in storage while still
 // working correctly with hash joins and EXCEPT operations.
-size_t complex2_hash(villagesql::Span<const unsigned char> data) {
+size_t complex2_hash(vsql::Span<const unsigned char> data) {
   if (data.size() != kComplexSize) return 0;
   Complex cx = load_complex(data.data());
   cx.canonicalize();

villagesql/examples/vsql-keyring-reader/src/extension.cc

@@ -47,7 +47,7 @@ void keyring_read(StringArg data_id, StringArg auth_id, StringResult out) {
   }
 
   std::string value;
-  vef_keyring_result_t kr = villagesql::keyring::read(
+  vef_keyring_result_t kr = vsql::keyring::read(
       data_id.value(), auth_id.is_null() ? "" : auth_id.value(), value);
   if (kr == VEF_KEYRING_UNAVAILABLE) {
     out.error("No keyring component is installed");
@@ -74,7 +74,7 @@ void keyring_store(StringArg data_id, StringArg auth_id, StringArg value,
     return;
   }
 
-  vef_keyring_result_t kr = villagesql::keyring::write(
+  vef_keyring_result_t kr = vsql::keyring::write(
       data_id.value(), auth_id.is_null() ? "" : auth_id.value(), value.value());
   if (kr == VEF_KEYRING_UNAVAILABLE) {
     out.error("No keyring component is installed");

villagesql/examples/vsql-tvector/src/tvector.cc

@@ -136,8 +136,7 @@ bool tvector_int_to_params(int64_t value,
 
 // Validate type parameters and compute storage characteristics.
 bool tvector_resolve_params(const std::map<std::string, std::string> &params,
-                            villagesql::ResolvedTypeParams *result,
-                            char *error_msg) {
+                            vsql::ResolvedTypeParams *result, char *error_msg) {
   auto it = params.find("dimension");
   if (it == params.end()) {
     snprintf(error_msg, VEF_MAX_ERROR_LEN,
@@ -178,7 +177,7 @@ bool tvector_resolve_params(const std::map<std::string, std::string> &params,
 // STRING -> TVECTOR
 // Dimension and element type are read from type parameters.
 bool tvector_from_string(const TVectorParams &p, std::string_view from,
-                         villagesql::Span<unsigned char> buf, size_t *length) {
+                         vsql::Span<unsigned char> buf, size_t *length) {
   // Computed values could be cached in the TVectorParams
   size_t byte_size = static_cast<size_t>(p.dimension) * p.bytes_per_elem;
   if (buf.size() < byte_size) return true;
@@ -229,8 +228,8 @@ bool tvector_from_string(const TVectorParams &p, std::string_view from,
 // TVECTOR -> STRING
 // Dimension and element type are read from type parameters.
 bool tvector_to_string(const TVectorParams &p,
-                       villagesql::Span<const unsigned char> data,
-                       villagesql::Span<char> out, size_t *out_len) {
+                       vsql::Span<const unsigned char> data,
+                       vsql::Span<char> out, size_t *out_len) {
   const size_t bpe = p.bytes_per_elem;
   if (data.size() != static_cast<size_t>(p.dimension) * bpe) return true;
 
@@ -268,9 +267,8 @@ bool tvector_to_string(const TVectorParams &p,
 // TODO(villagesql-performance): we can also consider having templated versions
 // of these functions instead of using branches, then selecting the version to
 // use with one branch.
-int tvector_compare(const TVectorParams &p,
-                    villagesql::Span<const unsigned char> a,
-                    villagesql::Span<const unsigned char> b) {
+int tvector_compare(const TVectorParams &p, vsql::Span<const unsigned char> a,
+                    vsql::Span<const unsigned char> b) {
   for (int64_t i = 0; i < p.dimension; i++) {
     if (p.bytes_per_elem == 8) {
       double v1 = load_double(a.data() + i * p.bytes_per_elem);
@@ -301,9 +299,9 @@ std::string tvector_default(const TVectorParams &p, char * /*error_msg*/) {
 
 // Dot product: (TVECTOR, TVECTOR) -> REAL
 // Returns the sum of element-wise products of two vectors of the same type.
-void tvector_dot_product(villagesql::CustomArgWith<TVectorParams> a,
-                         villagesql::CustomArgWith<TVectorParams> b,
-                         villagesql::RealResult out) {
+void tvector_dot_product(vsql::CustomArgWith<TVectorParams> a,
+                         vsql::CustomArgWith<TVectorParams> b,
+                         vsql::RealResult out) {
   if (a.is_null() || b.is_null()) {
     out.set_null();
     return;
@@ -331,9 +329,9 @@ void tvector_dot_product(villagesql::CustomArgWith<TVectorParams> a,
 
 // Element-wise add: (TVECTOR, TVECTOR) -> TVECTOR
 // Vectors must have the same dimension and element type.
-void tvector_add(villagesql::CustomArgWith<TVectorParams> a,
-                 villagesql::CustomArgWith<TVectorParams> b,
-                 villagesql::CustomResultWith<TVectorParams> out) {
+void tvector_add(vsql::CustomArgWith<TVectorParams> a,
+                 vsql::CustomArgWith<TVectorParams> b,
+                 vsql::CustomResultWith<TVectorParams> out) {
   if (a.is_null() || b.is_null()) {
     out.set_null();
     return;
@@ -365,9 +363,8 @@ void tvector_add(villagesql::CustomArgWith<TVectorParams> a,
 }
 
 // Scalar multiply: (TVECTOR, REAL) -> TVECTOR
-void tvector_scale(villagesql::CustomArgWith<TVectorParams> a,
-                   villagesql::RealArg scalar,
-                   villagesql::CustomResultWith<TVectorParams> out) {
+void tvector_scale(vsql::CustomArgWith<TVectorParams> a, vsql::RealArg scalar,
+                   vsql::CustomResultWith<TVectorParams> out) {
   if (a.is_null() || scalar.is_null()) {
     out.set_null();
     return;

villagesql/sdk/include/villagesql/detail/vef_register.h

@@ -28,7 +28,7 @@
 #include <villagesql/abi/types.h>
 #include <villagesql/sdk_version.h>
 
-namespace villagesql {
+namespace vsql {
 
 // Forward-declare the vsql globals so that name lookup succeeds inside the
 // `if constexpr (Ext::kHasVsqlGlobals)` block even when only the base
@@ -43,20 +43,48 @@ extern vef_read_keyring_fn g_read_keyring;
 extern vef_write_keyring_fn g_write_keyring;
 }  // namespace keyring
 
-// Forward-declare materialize_func_desc so the helpers below can reference it
-// without requiring func_builder.h to be included first.
+// Define materialize_func_desc here so it is available to both old
+// (villagesql::func_builder) and new (vsql::func_builder) API users without
+// requiring an additional include.  villagesql/func_builder.h re-exports this
+// as villagesql::func_builder::materialize_func_desc via a using-declaration,
+// so ADL on old-API types and the explicit using in vef_fill_func_ptrs both
+// resolve to the same entity — eliminating overload ambiguity.
 namespace func_builder {
 template <typename FuncData, size_t Index>
-vef_func_desc_t *materialize_func_desc(const FuncData &func_data);
+__attribute__((visibility("hidden"))) vef_func_desc_t *materialize_func_desc(
+    const FuncData &func_data) {
+  static vef_signature_t signature;
+  static vef_func_desc_t desc;
+
+  signature.param_count = static_cast<unsigned int>(func_data.num_params());
+  signature.params = func_data.num_params() > 0 ? func_data.params() : nullptr;
+  signature.return_type = func_data.return_type();
+
+  desc.protocol = VEF_PROTOCOL_2;
+  desc.name = func_data.name();
+  desc.signature = &signature;
+  desc.vdf = func_data.vdf();
+  desc.prerun = func_data.prerun();
+  desc.postrun = func_data.postrun();
+  desc.buffer_size = func_data.buffer_size();
+  desc.deterministic = func_data.deterministic();
+  desc.clear = func_data.clear();
+  desc.accumulate = func_data.accumulate();
+
+  return &desc;
+}
 }  // namespace func_builder
 
+}  // namespace vsql
+
+namespace villagesql {
 namespace detail {
 
 // Fills arr[I] with the materialized vef_func_desc_t* for each function.
 template <typename Ext, size_t... Is>
 void vef_fill_func_ptrs(vef_func_desc_t **arr, const Ext &e,
                         std::index_sequence<Is...>) {
-  using villagesql::func_builder::materialize_func_desc;
+  using vsql::func_builder::materialize_func_desc;
   ((arr[Is] = materialize_func_desc<decltype(e.template func_at<Is>()), Is>(
         e.template func_at<Is>())),
    ...);
@@ -157,10 +185,10 @@ vef_registration_t *vef_register_impl(vef_registration_t &reg,
   // vsql headers in scope.
   if constexpr (Ext::kHasVsqlGlobals) {
     if (arg->protocol >= VEF_PROTOCOL_2) {
-      villagesql::sys_var::g_get_variable = arg->get_variable;
-      villagesql::sys_var::g_set_variable = arg->set_variable;
-      villagesql::keyring::g_read_keyring = arg->read_keyring;
-      villagesql::keyring::g_write_keyring = arg->write_keyring;
+      vsql::sys_var::g_get_variable = arg->get_variable;
+      vsql::sys_var::g_set_variable = arg->set_variable;
+      vsql::keyring::g_read_keyring = arg->read_keyring;
+      vsql::keyring::g_write_keyring = arg->write_keyring;
     }
   }
 

villagesql/sdk/include/villagesql/extension_builder.h

@@ -30,6 +30,7 @@
 #include <utility>
 
 #include <villagesql/detail/vef_register.h>
+#include <villagesql/func_builder.h>
 #include <villagesql/type_builder.h>
 
 namespace villagesql {

villagesql/sdk/include/villagesql/func_builder.h

@@ -31,6 +31,18 @@
 
 #include <villagesql/abi/types.h>
 
+// Forward-declare materialize_func_desc in vsql::func_builder.  The definition
+// lives in vef_register.h.  The using-declaration below makes
+// villagesql::func_builder::materialize_func_desc an alias to the same entity,
+// so ADL on old-API types and the explicit using in vef_fill_func_ptrs both
+// resolve to one function — eliminating overload ambiguity.
+namespace vsql {
+namespace func_builder {
+template <typename FuncData, size_t Index>
+vef_func_desc_t *materialize_func_desc(const FuncData &func_data);
+}  // namespace func_builder
+}  // namespace vsql
+
 namespace villagesql {
 namespace func_builder {
 
@@ -267,29 +279,7 @@ struct StaticFuncDesc {
   constexpr void init_name() const {}
 };
 
-template <typename FuncData, size_t Index>
-__attribute__((visibility("hidden"))) vef_func_desc_t *materialize_func_desc(
-    const FuncData &func_data) {
-  static vef_signature_t signature;
-  static vef_func_desc_t desc;
-
-  signature.param_count = static_cast<unsigned int>(func_data.num_params());
-  signature.params = func_data.num_params() > 0 ? func_data.params() : nullptr;
-  signature.return_type = func_data.return_type();
-
-  desc.protocol = VEF_PROTOCOL_2;
-  desc.name = func_data.name();
-  desc.signature = &signature;
-  desc.vdf = func_data.vdf();
-  desc.prerun = func_data.prerun();
-  desc.postrun = func_data.postrun();
-  desc.buffer_size = func_data.buffer_size();
-  desc.deterministic = func_data.deterministic();
-  desc.clear = func_data.clear();
-  desc.accumulate = func_data.accumulate();
-
-  return &desc;
-}
+using vsql::func_builder::materialize_func_desc;
 
 // =============================================================================
 // FuncBuilder (V1 — raw vef_vdf_func_t only)

villagesql/sdk/include/villagesql/preview/ping.h

@@ -63,7 +63,7 @@ struct preview_ping {
   static constexpr auto bind(Inner builder) {
     using Cap = ping::Capability;
     return builder.required_capability(
-        {Cap::kName, &::villagesql::vsql::cap_receive<Cap, &cap>,
+        {Cap::kName, &::vsql::cap_receive<Cap, &cap>,
          ::villagesql::detail::abi_type_hash<decltype(cap.abi_)>()});
   }
 };

villagesql/sdk/include/villagesql/vsql.h

@@ -33,11 +33,11 @@
 //
 //   // 1. Implement your type operations
 //   bool complex_from_string(std::string_view s,
-//                            villagesql::Span<unsigned char> buf, size_t* len);
-//   bool complex_to_string(villagesql::Span<const unsigned char> data,
-//                          villagesql::Span<char> out, size_t* out_len);
-//   int  complex_compare(villagesql::Span<const unsigned char> a,
-//                        villagesql::Span<const unsigned char> b);
+//                            vsql::Span<unsigned char> buf, size_t* len);
+//   bool complex_to_string(vsql::Span<const unsigned char> data,
+//                          vsql::Span<char> out, size_t* out_len);
+//   int  complex_compare(vsql::Span<const unsigned char> a,
+//                        vsql::Span<const unsigned char> b);
 //
 //   // 2. Define the type as a constexpr object
 //   static constexpr const char kComplexTypeName[] = "COMPLEX";
@@ -90,49 +90,27 @@
 
 namespace vsql {
 
-// Re-export make_extension from villagesql::vsql (extended version)
-using villagesql::vsql::make_extension;
-
-// Re-export make_func and type-operation entry points from the typed builder
-using villagesql::func_builder::make_func;
-using villagesql::func_builder::make_int_to_params;
-using villagesql::func_builder::make_intrinsic_default;
-using villagesql::func_builder::make_resolve_params;
-using villagesql::func_builder::make_type_compare;
-using villagesql::func_builder::make_type_decode;
-using villagesql::func_builder::make_type_encode;
-using villagesql::func_builder::make_type_hash;
-
-// Re-export sys_var and keyring namespaces
-namespace sys_var = villagesql::sys_var;
-namespace keyring = villagesql::keyring;
-using villagesql::status_var_builder::make_status_var_double;
-using villagesql::status_var_builder::make_status_var_int;
-using villagesql::sys_var_builder::make_sys_var_bool;
-using villagesql::sys_var_builder::make_sys_var_double;
-using villagesql::sys_var_builder::make_sys_var_int;
-using villagesql::sys_var_builder::make_sys_var_str;
-
-// Re-export typed argument/result wrappers
-using villagesql::CustomArg;
-using villagesql::CustomArgWith;
-using villagesql::CustomResult;
-using villagesql::CustomResultWith;
-using villagesql::IntArg;
-using villagesql::IntResult;
-using villagesql::RealArg;
-using villagesql::RealResult;
-using villagesql::Span;
-using villagesql::StringArg;
-using villagesql::StringResult;
-
-// Re-export built-in type name constants
-using villagesql::func_builder::INT;
-using villagesql::func_builder::REAL;
-using villagesql::func_builder::STRING;
-
-// Re-export sys_var change wrapper
-using villagesql::sys_var_builder::SysVarChange;
+// Re-export from func_builder sub-namespace into the flat vsql:: namespace
+using func_builder::INT;
+using func_builder::make_func;
+using func_builder::make_int_to_params;
+using func_builder::make_intrinsic_default;
+using func_builder::make_resolve_params;
+using func_builder::make_type_compare;
+using func_builder::make_type_decode;
+using func_builder::make_type_encode;
+using func_builder::make_type_hash;
+using func_builder::REAL;
+using func_builder::STRING;
+
+// Re-export from sys_var_builder and status_var_builder sub-namespaces
+using status_var_builder::make_status_var_double;
+using status_var_builder::make_status_var_int;
+using sys_var_builder::make_sys_var_bool;
+using sys_var_builder::make_sys_var_double;
+using sys_var_builder::make_sys_var_int;
+using sys_var_builder::make_sys_var_str;
+using sys_var_builder::SysVarChange;
 
 }  // namespace vsql