first cut

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tomas-villagesql

mysql-test/suite/villagesql/extension/vsql-preview-ping-test/r/preview_ping_basic.result

@@ -0,0 +1,10 @@
+INSTALL EXTENSION vsql_preview_ping_test;
+# ping() returns a positive integer
+SELECT vsql_preview_ping_test.ping() > 0 AS ping_positive;
+ping_positive
+1
+# Consecutive calls return strictly increasing values
+SELECT vsql_preview_ping_test.ping() < vsql_preview_ping_test.ping() AS ping_increases;
+ping_increases
+1
+UNINSTALL EXTENSION vsql_preview_ping_test;

mysql-test/suite/villagesql/extension/vsql-preview-ping-test/t/preview_ping_basic.test

@@ -0,0 +1,13 @@
+# Test the preview ping capability for vsql_preview_ping_test extension.
+# Verifies that the ping() VDF returns an incrementing counter, proving
+# the server-side preview capability was populated correctly.
+
+INSTALL EXTENSION vsql_preview_ping_test;
+
+--echo # ping() returns a positive integer
+SELECT vsql_preview_ping_test.ping() > 0 AS ping_positive;
+
+--echo # Consecutive calls return strictly increasing values
+SELECT vsql_preview_ping_test.ping() < vsql_preview_ping_test.ping() AS ping_increases;
+
+UNINSTALL EXTENSION vsql_preview_ping_test;

villagesql/CMakeLists.txt

@@ -382,4 +382,6 @@ IF(NOT WITHOUT_SERVER)
 
   add_custom_target(storage_test_veb ALL)
   add_dependencies(storage_test_veb copy_vsql_storage_test_veb)
+
+  include(test-extensions/CMakeLists.txt)
 ENDIF()

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

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 VillageSQL Contributors
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License
+// as published by the Free Software Foundation; either version 2
+// of the License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License, version 2.0, for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, see <https://www.gnu.org/licenses/>.
+
+#ifndef VILLAGESQL_ABI_PREVIEW_PING_H
+#define VILLAGESQL_ABI_PREVIEW_PING_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Preview capability: "vsql::ping"
+//
+// A trivial capability used to exercise and test the preview capability
+// registration system. The server provides a single ping() function that
+// returns a monotonically incrementing counter.
+//
+// Capability name:    VEF_PREVIEW_PING_NAME
+// Capability version: VEF_PREVIEW_PING_VERSION
+
+#define VEF_PREVIEW_PING_NAME "vsql::ping"
+#define VEF_PREVIEW_PING_VERSION 1
+
+// Returns a monotonically incrementing counter. Used to verify that the
+// capability system is wired up correctly end-to-end.
+typedef uint64_t (*vef_ping_fn)(void);
+
+typedef struct {
+  vef_ping_fn ping;
+} vef_preview_ping_t;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // VILLAGESQL_ABI_PREVIEW_PING_H

villagesql/sdk/include/villagesql/abi/types.h

@@ -173,6 +173,12 @@ typedef enum : unsigned int {
                    // + get_variable/set_variable/read_keyring/write_keyring
                    //   function pointers in vef_register_arg_t: access to
                    //   MySQL system variables and keyring component.
+                   // + Preview capability system: extensions declare named
+                   //   capabilities they require in vef_registration_t;
+                   //   the server populates their function pointers before
+                   //   vef_register() returns.
+                   //   (vef_required_capability_t, required_capabilities,
+                   //   required_capability_count in vef_registration_t)
 } vef_protocol_t;
 
 // Max length of error messages in caller-provided buffers.
@@ -872,6 +878,21 @@ typedef struct {
   };
 } vef_status_var_desc_t;
 
+// A single preview capability request in
+// vef_registration_t.required_capabilities. The extension sets name, version,
+// and the capability pointer. The server then populates the function pointers
+// inside the struct pointed to by capability.
+typedef struct {
+  // Capability name, e.g. "vsql::ping". Must remain valid for the lifetime
+  // of the extension (use a string literal).
+  const char *name;
+  // Version of the capability struct the extension was compiled against.
+  uint32_t version;
+  // Pointer to the extension's capability struct (e.g. vef_preview_ping_t*).
+  // The server writes function pointers into this struct.
+  void *capability;
+} vef_required_capability_t;
+
 typedef struct {
   // protocol >= VEF_PROTOCOL_1
   vef_protocol_t protocol;
@@ -899,6 +920,15 @@ typedef struct {
   // protocol >= VEF_PROTOCOL_2
   unsigned int status_var_count;
   vef_status_var_desc_t **status_vars;
+
+  // protocol >= VEF_PROTOCOL_2
+  // Preview capabilities required by this extension. Each entry names a
+  // capability the extension needs (e.g. "vsql::ping"). The server populates
+  // the capability struct pointed to by each entry before vef_register()
+  // returns. If a capability is unavailable or the version is unsupported,
+  // its function pointers are left as nullptr.
+  unsigned int required_capability_count;
+  const vef_required_capability_t *required_capabilities;
 } vef_registration_t;
 
 // The returned objects can be freed when the registration is passed to the