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>

Author: dbentley-vsql

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

@@ -79,7 +79,7 @@ ERROR HY000: Cannot initialize function 'ba_concat': wrong number of arguments (
 SELECT vsql_simple.ba_concat_all(t.data) AS one
 FROM test_bytearray t WHERE t.id = 1;
 one
-hello   
+hello
 SELECT vsql_simple.ba_concat_all(t1.data, t2.data, t3.data) AS three
 FROM test_bytearray t1, test_bytearray t2, test_bytearray t3
 WHERE t1.id = 1 AND t2.id = 2 AND t3.id = 3;
@@ -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/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;
 

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()) {
@@ -205,6 +227,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)

villagesql/sdk/include/villagesql/detail/func_builder.h

@@ -33,6 +33,7 @@
 
 #include <villagesql/abi/types.h>
 #include <villagesql/vsql/func_types.h>
+#include <villagesql/vsql/pre_post_run.h>
 #include <villagesql/vsql/type_params.h>
 #include <villagesql/vsql/var_args.h>
 
@@ -378,6 +379,47 @@ struct AggResultWithOutputWrapper {
   }
 };
 
+// Wrappers that convert a typed user prerun/postrun (void(PrerunArgs,
+// PrerunResult) / void(PostrunArgs)) into the raw vef_*_func_t ABI shape.
+// Used by FuncBuilder::prerun/postrun when the user's hook is typed.
+
+template <auto Hook>
+void typed_prerun_wrapper(vef_context_t *, vef_prerun_args_t *args,
+                          vef_prerun_result_t *result) {
+  Hook(PrerunArgs(args), PrerunResult(result));
+}
+
+template <auto Hook>
+void typed_postrun_wrapper(vef_context_t *, vef_postrun_args_t *args,
+                           vef_postrun_result_t *) {
+  Hook(PostrunArgs(args));
+}
+
+// Predicates used by FuncBuilder::prerun/postrun to decide which wrapper
+// (if any) to install. Each is true exactly when the hook's signature
+// matches the typed shape for its slot.
+
+template <auto Hook>
+constexpr bool is_typed_prerun() {
+  using Params = typename FuncParamTypes<decltype(Hook)>::type;
+  if constexpr (std::tuple_size_v<Params> != 2) {
+    return false;
+  } else {
+    return std::is_same_v<std::tuple_element_t<0, Params>, PrerunArgs> &&
+           std::is_same_v<std::tuple_element_t<1, Params>, PrerunResult>;
+  }
+}
+
+template <auto Hook>
+constexpr bool is_typed_postrun() {
+  using Params = typename FuncParamTypes<decltype(Hook)>::type;
+  if constexpr (std::tuple_size_v<Params> != 1) {
+    return false;
+  } else {
+    return std::is_same_v<std::tuple_element_t<0, Params>, PostrunArgs>;
+  }
+}
+
 // Generates a vef_vdf_func_t that unpacks vef_vdf_args_t and adapts each
 // argument and result to the declared typed wrapper parameter of Func.
 //
@@ -443,6 +485,80 @@ struct VarArgsWrapper {
   }
 };
 
+// Wrapper for VDFs whose first parameter is `State&` — typed per-statement
+// state allocated in prerun via PrerunResult::emplace_state<State>. The
+// wrapper dereferences args->user_data as State* and forwards a reference.
+//
+// Param tuple shape: <State&, TypedArg..., ResultWrapper>. NumParams is the
+// SQL argument count (not counting state or result), so typed args live at
+// indices [1, NumParams].
+template <auto Func, typename State, size_t NumParams>
+struct WrapperTypedState {
+  static void invoke(vef_context_t *ctx, vef_vdf_args_t *args,
+                     vef_vdf_result_t *result) {
+    invoke_impl(ctx, args, result, std::make_index_sequence<NumParams>{});
+  }
+
+ private:
+  template <size_t... Is>
+  static void invoke_impl(vef_context_t *ctx, vef_vdf_args_t *args,
+                          vef_vdf_result_t *result,
+                          std::index_sequence<Is...>) {
+    using Params = typename FuncParamTypes<decltype(Func)>::type;
+    State &state = *static_cast<State *>(args->user_data);
+    std::array<vef_invalue_t, NumParams> vals{
+        get_invalue(ctx, args, static_cast<unsigned int>(Is))...};
+    Func(state, make_arg<std::tuple_element_t<1 + Is, Params>>(&vals[Is])...,
+         make_result<std::tuple_element_t<1 + NumParams, Params>>(result));
+  }
+
+  template <typename T>
+  static T make_arg(vef_invalue_t *v) {
+    return T(v);
+  }
+  template <typename T>
+  static T make_result(vef_vdf_result_t *r) {
+    return T(r);
+  }
+};
+
+// Wrapper for VDFs whose first parameter is `void*` — raw escape hatch for
+// extensions that manage state with custom allocators, polymorphic state,
+// or anything that doesn't fit emplace_state<T>. The wrapper forwards
+// args->user_data straight through.
+//
+// Param tuple shape: <void*, TypedArg..., ResultWrapper>. Same indexing as
+// WrapperTypedState.
+template <auto Func, size_t NumParams>
+struct WrapperVoidState {
+  static void invoke(vef_context_t *ctx, vef_vdf_args_t *args,
+                     vef_vdf_result_t *result) {
+    invoke_impl(ctx, args, result, std::make_index_sequence<NumParams>{});
+  }
+
+ private:
+  template <size_t... Is>
+  static void invoke_impl(vef_context_t *ctx, vef_vdf_args_t *args,
+                          vef_vdf_result_t *result,
+                          std::index_sequence<Is...>) {
+    using Params = typename FuncParamTypes<decltype(Func)>::type;
+    std::array<vef_invalue_t, NumParams> vals{
+        get_invalue(ctx, args, static_cast<unsigned int>(Is))...};
+    Func(args->user_data,
+         make_arg<std::tuple_element_t<1 + Is, Params>>(&vals[Is])...,
+         make_result<std::tuple_element_t<1 + NumParams, Params>>(result));
+  }
+
+  template <typename T>
+  static T make_arg(vef_invalue_t *v) {
+    return T(v);
+  }
+  template <typename T>
+  static T make_result(vef_vdf_result_t *r) {
+    return T(r);
+  }
+};
+
 // Pre-fills result->type / result->error_msg with a default
 // "failed to encode '<input>'" warning, truncating long inputs. Both encode
 // wrappers call this before invoking the extension's from_string so that an

villagesql/sdk/include/villagesql/vsql.h

@@ -60,7 +60,9 @@
 //           .build()))
 //
 // For aggregate VDFs (SQL SUM, COUNT, etc.), see make_aggregate_func in
-// vsql/func_builder.h. For full documentation see the individual headers below.
+// vsql/func_builder.h. For per-statement lifecycle hooks (prerun/postrun),
+// see vsql/pre_post_run.h. For full documentation see the individual
+// headers below.
 
 // Typed function and type-operation builders (rejects raw ABI signatures).
 #include <villagesql/vsql/func_builder.h>