sdk: typed prerun/postrun (#551)

* sdk: typed prerun/postrun hooks

Introduce typed C++ wrappers for the per-statement lifecycle hooks
(prerun and postrun). Extension authors no longer touch raw ABI
structs to write these hooks; only the typed signatures are accepted.

Why
---
Extension authors writing prerun/postrun previously had to:

  void my_prerun(vef_context_t *, vef_prerun_args_t *args,
                 vef_prerun_result_t *result) {
    if (args->arg_count == 0) {
      result->type = VEF_RESULT_ERROR;
      snprintf(result->error_msg, VEF_MAX_ERROR_LEN, "...");
      return;
    }
    result->result_buffer_size = N;
    result->user_data = new MyState{};
  }

Two problems: raw ABI in the user-facing API (against the SDK's
direction; see #548) and bespoke error-reporting plumbing.

After this PR:

  void my_prerun(vsql::PrerunArgs args, vsql::PrerunResult out) {
    if (args.size() == 0) {
      out.error("at least one argument required");
      return;
    }
    out.request_buffer_size(N);
    out.set_user_data(new MyState{});
  }

  void my_postrun(vsql::PostrunArgs args) {
    args.delete_state<MyState>();
  }

  void my_vdf(MyState &state, IntResult out) { ... }

State lifetime stays explicit in this PR: prerun stashes the pointer,
postrun frees it. A follow-up will add auto-cleanup via .state<T>()
(implementable without ABI changes; see TODO in pre_post_run.h).

Where to start reviewing
------------------------
Read the layers in this order:

1. villagesql/sdk/include/villagesql/vsql/pre_post_run.h
   New public types: PrerunArgs, PrerunArgType, PrerunResult,
   PostrunArgs. This is what extension authors see.

2. villagesql/examples/vsql-simple/src/extension.cc
   The ba_call_index demo: set_user_data in prerun, mutable State&
   in the VDF, delete_state in postrun.

3. mysql-test/suite/villagesql/extension/t/extension_simple_type_usage.test
   What it looks like at the SQL surface.

4. villagesql/sdk/include/villagesql/extension.h
   Refreshed user-facing docs for the typed hook shape.

The remaining file is SDK plumbing:

5. villagesql/sdk/include/villagesql/vsql/func_builder.h
   - .prerun<>() / .postrun<>() are typed-only; static_assert
     rejects raw vef_prerun_func_t / vef_postrun_func_t.
   - FuncBuilder gained a HasPrerun template flag; .prerun<>() flips
     it true, and build() static_asserts that void(State&,...) and
     void(void*,...) signatures require it. Registering a state-style
     VDF without a prerun is a compile error, not a runtime null deref.
   - WrapperTypedState / WrapperVoidState dispatch on the first
     param of the VDF: State& / const State& / void* selects how
     user_data is forwarded.
   - typed_prerun_thunk / typed_postrun_thunk adapt the user's
     typed signature to the raw ABI shape the server invokes.

Not in this PR
--------------
- A `.state<T>()` builder that records State at the template level
  and routes typed signatures of the form `void(T&, ...)`. The SDK
  would install both prerun and postrun thunks to manage the typed
  state's lifetime via the existing user_data slot — no ABI side
  channel needed. Will land as a follow-up.
- Typed VarArgs/AnyArg wrappers for varargs VDFs (the other raw-ABI
  place in extension code, only reached via PR #254).
- vef_postrun_result_t is empty in the ABI today, so there is no
  PostrunResult wrapper. Will add when the struct grows.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* demo: state_writeback test showing void* user_data writeback gap

* fix previous VDF

* vef: convert ba_concat_all_prerun to typed PrerunArgs/PrerunResult

---------

Author: dbentley-vsql

mysql-test/suite/villagesql/extension/r/extension_simple_type_usage.result

@@ -108,6 +108,12 @@ SELECT vsql_simple.ba_concat_all(t1.data, 'abc') AS with_str
 FROM test_bytearray t1 WHERE t1.id = 1;
 with_str
 NULL
+# Test ba_call_index (exercises typed prerun/postrun + state-passing VDF)
+SELECT vsql_simple.ba_call_index() as idx FROM test_bytearray ORDER BY id;
+idx
+1
+2
+3
 # Clean up
 DROP TABLE test_bytearray;
 # Uninstall the extension

mysql-test/suite/villagesql/extension/r/extension_vdf_state_writeback.result

@@ -0,0 +1,25 @@
+# restart: --veb-dir=MYSQLTEST_VARDIR/veb
+Creating extension test_state_writeback using SDK...
+Created test_state_writeback.veb
+INSTALL EXTENSION test_state_writeback;
+CREATE TABLE seq (id INT PRIMARY KEY, s VARCHAR(16));
+INSERT INTO seq VALUES
+(1, 'a'),
+(2, 'bb'),
+(3, 'ccc'),
+(4, 'dd'),
+(5, 'ee'),
+(6, 'ffffffff');
+# First row prev is NULL; later rows reflect prior s.
+# Rows 4-5 reuse the same buffer (shorter than capacity);
+# row 6 reallocs because 'ffffffff' doesn't fit.
+SELECT id, s, test_state_writeback.previous(s) AS prev FROM seq ORDER BY id;
+id	s	prev
+1	a	NULL
+2	bb	a
+3	ccc	bb
+4	dd	ccc
+5	ee	dd
+6	ffffffff	ee
+DROP TABLE seq;
+UNINSTALL EXTENSION test_state_writeback;

mysql-test/suite/villagesql/extension/t/extension_simple_type_usage.test

@@ -79,6 +79,9 @@ FROM test_bytearray t1 WHERE t1.id = 1;
 SELECT vsql_simple.ba_concat_all(t1.data, 'abc') AS with_str
 FROM test_bytearray t1 WHERE t1.id = 1;
 
+--echo # Test ba_call_index (exercises typed prerun/postrun + state-passing VDF)
+SELECT vsql_simple.ba_call_index() as idx FROM test_bytearray ORDER BY id;
+
 --echo # Clean up
 DROP TABLE test_bytearray;
 

mysql-test/suite/villagesql/extension/t/extension_vdf_state_writeback.test

@@ -0,0 +1,38 @@
+# previous(s) returns the s passed to the previous row (or NULL on the
+# first row). Implemented via the typed prerun/postrun + `void*&` user_data
+# slot (WrapperVoidStarRefState) introduced in #551.
+#
+# The VDF mallocs storage on first need, reuses it when subsequent strings
+# fit, and reallocates when a longer string arrives. Postrun frees the
+# final buffer.
+
+# Setup VEB directory for testing
+--let $veb_dir = $MYSQLTEST_VARDIR/veb
+--exec mkdir -p $veb_dir
+--replace_result $MYSQLTEST_VARDIR MYSQLTEST_VARDIR
+--let $restart_parameters = restart: --veb-dir=$veb_dir
+--source include/restart_mysqld.inc
+
+--let $extension_name = test_state_writeback
+--let $extension_version = 1.0.0
+--let $extension_source = $MYSQL_TEST_DIR/suite/villagesql/std_data/state_writeback_vdf.cc
+--source include/villagesql/create_extension_sdk.inc
+
+INSTALL EXTENSION test_state_writeback;
+
+CREATE TABLE seq (id INT PRIMARY KEY, s VARCHAR(16));
+INSERT INTO seq VALUES
+  (1, 'a'),
+  (2, 'bb'),
+  (3, 'ccc'),
+  (4, 'dd'),
+  (5, 'ee'),
+  (6, 'ffffffff');
+
+--echo # First row prev is NULL; later rows reflect prior s.
+--echo # Rows 4-5 reuse the same buffer (shorter than capacity);
+--echo # row 6 reallocs because 'ffffffff' doesn't fit.
+SELECT id, s, test_state_writeback.previous(s) AS prev FROM seq ORDER BY id;
+
+DROP TABLE seq;
+UNINSTALL EXTENSION test_state_writeback;

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

@@ -0,0 +1,83 @@
+/* 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 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/>.
+ */
+
+// Test-only extension demonstrating the typed prerun/postrun + `void*&`
+// user_data slot (WrapperVoidStarRefState) from PR #551.
+//
+// previous(s) returns the s passed to the previous row, or NULL on the
+// first row. Storage is a malloc'd buffer laid out as:
+//   [size_t capacity][size_t length][capacity bytes of payload]
+// capacity is the payload bytes currently available; length is how many
+// of those are in use. When a longer string arrives we free the buffer
+// and malloc a new one; shorter strings reuse the existing allocation.
+
+#include <villagesql/vsql.h>
+
+#include <cstdlib>
+#include <cstring>
+
+using namespace vsql;
+
+struct Hdr {
+  size_t capacity;
+  size_t length;
+};
+
+static void previous_prerun(PrerunArgs, PrerunResult out) {
+  out.set_user_data(nullptr);
+}
+
+void previous_vdf(void *&user_data, StringArg s, StringResult out) {
+  // Emit the previous value, if any.
+  if (user_data != nullptr) {
+    auto *hdr = static_cast<Hdr *>(user_data);
+    const char *bytes = reinterpret_cast<const char *>(hdr) + sizeof(Hdr);
+    out.set(std::string_view(bytes, hdr->length));
+  } else {
+    out.set_null();
+  }
+
+  // Stash the current row's value for the next call. A NULL input clears
+  // the slot (and frees any buffer we were carrying).
+  if (s.is_null()) {
+    std::free(user_data);
+    user_data = nullptr;
+    return;
+  }
+
+  auto sv = s.value();
+  size_t needed = sv.size();
+  auto *hdr = static_cast<Hdr *>(user_data);
+  if (hdr == nullptr || hdr->capacity < needed) {
+    std::free(user_data);
+    hdr = static_cast<Hdr *>(std::malloc(sizeof(Hdr) + needed));
+    hdr->capacity = needed;
+  }
+  hdr->length = needed;
+  std::memcpy(reinterpret_cast<char *>(hdr) + sizeof(Hdr), sv.data(), needed);
+  user_data = hdr;
+}
+
+static void previous_postrun(PostrunArgs args) { std::free(args.user_data()); }
+
+VEF_GENERATE_ENTRY_POINTS(
+    make_extension().func(make_func<&previous_vdf>("previous")
+                              .returns(STRING)
+                              .param(STRING)
+                              .buffer_size(1024)
+                              .prerun<&previous_prerun>()
+                              .postrun<&previous_postrun>()
+                              .build()))

villagesql/examples/vsql-simple/src/extension.cc

@@ -112,6 +112,28 @@ void odd_chars(CustomArg in, CustomResult out) {
   out.set_length(kBytearrayLen);
 }
 
+// BA_CALL_INDEX: return the 1-based index of this call within the current
+// statement. Demonstrates the typed prerun/postrun + State& pattern: prerun
+// allocates a counter, each row reads-and-increments via the VDF's State&
+// first parameter, and postrun frees.
+
+struct CallCounter {
+  long long n = 0;
+};
+
+void ba_call_index_prerun(PrerunArgs, PrerunResult out) {
+  out.set_user_data(new CallCounter{});
+}
+
+void ba_call_index(CallCounter &state, IntResult out) {
+  state.n++;
+  out.set(state.n);
+}
+
+void ba_call_index_postrun(PostrunArgs args) {
+  args.delete_state<CallCounter>();
+}
+
 // BA_CONCAT: concatenate two bytearrays (returns STRING with 16 bytes)
 void ba_concat(CustomArg a, CustomArg b, StringResult out) {
   if (a.is_null() || b.is_null()) {
@@ -136,24 +158,20 @@ void ba_len(IntResult out) { out.set(static_cast<long long>(kBytearrayLen)); }
 // Prerun: validate that all arguments are BYTEARRAY (or NULL literals,
 // which appear as VEF_TYPE_STRING in the prerun arg-type array) and ask
 // the server to allocate arg_count * kBytearrayLen bytes of result buffer.
-void ba_concat_all_prerun(vef_context_t *, vef_prerun_args_t *args,
-                          vef_prerun_result_t *result) {
-  if (args->arg_count == 0) {
-    result->type = VEF_RESULT_ERROR;
-    snprintf(result->error_msg, VEF_MAX_ERROR_LEN,
-             "ba_concat_all requires at least one argument");
+void ba_concat_all_prerun(vsql::PrerunArgs args, vsql::PrerunResult out) {
+  if (args.size() == 0) {
+    out.error("ba_concat_all requires at least one argument");
     return;
   }
-  for (unsigned int i = 0; i < args->arg_count; i++) {
-    vef_type_id id = args->arg_types[i].id;
-    if (id != VEF_TYPE_CUSTOM && id != VEF_TYPE_STRING) {
-      result->type = VEF_RESULT_ERROR;
-      snprintf(result->error_msg, VEF_MAX_ERROR_LEN,
-               "ba_concat_all: argument %u must be BYTEARRAY", i);
+  for (size_t i = 0; i < args.size(); i++) {
+    auto t = args.type_at(i);
+    if (!t.is_custom() && !t.is_str()) {
+      out.error("ba_concat_all: argument " + std::to_string(i) +
+                " must be BYTEARRAY");
       return;
     }
   }
-  result->result_buffer_size = args->arg_count * kBytearrayLen;
+  out.request_buffer_size(args.size() * kBytearrayLen);
 }
 
 void ba_concat_all(VarArgs args, StringResult out) {
@@ -205,6 +223,12 @@ VEF_GENERATE_ENTRY_POINTS(
                   .param(BYTEARRAY)
                   .param(BYTEARRAY)
                   .build())
+        .func(make_func<&ba_call_index>("ba_call_index")
+                  .returns(INT)
+                  .param()
+                  .prerun<&ba_call_index_prerun>()
+                  .postrun<&ba_call_index_postrun>()
+                  .build())
         .func(make_func<&ba_len>("ba_len").returns(INT).param().build())
         .func(make_func<&ba_concat_all>("ba_concat_all")
                   .returns(STRING)