feat: persistent-zval helpers (deep-copy zval trees across threads)

Second step of the split suggested in #2287: land the persistent-zval
subsystem as a standalone, reviewable header, independent of background
workers. This is the subsystem most likely to hide latent refcount or
memory-lifetime bugs; reviewing it in isolation is higher-signal than
finding issues inside a 3k-line diff.

- persistent_zval.h (renamed from the bg_worker_vars.h draft, prefix
  dropped for generality):
  - persistent_zval_validate: whitelist (scalars, arrays of allowed
    values, enum instances). Everything else fails fast.
  - persistent_zval_persist: deep-copy request -> persistent (pemalloc)
    memory. Fast paths baked in: interned strings shared, opcache-
    immutable arrays passed by pointer without copying or owning.
  - persistent_zval_free: deep-free; skips interned strings and
    immutable arrays (borrowed, not owned).
  - persistent_zval_to_request: deep-copy persistent -> fresh request
    memory. Enums re-resolved by class + case name on each read.

- frankenphp.c: header included only when FRANKENPHP_TEST_HOOKS is
  defined. First real consumer (background workers) drops the guard.

- Test hook gated on FRANKENPHP_TEST_HOOKS:
  - PHP function frankenphp_test_persist_roundtrip(mixed): mixed runs
    validate -> persist -> to_request -> free and returns the result.
  - Registered via zend_register_functions at MINIT so it never
    appears in ext_functions[] and never ships in production builds.

- CI workflows set -DFRANKENPHP_TEST_HOOKS in CGO_CFLAGS
  (tests.yaml + sanitizers.yaml). windows.yaml is the release build,
  not a test runner, and stays untouched.

- Build verified both without the flag (production path, no
  unused-function warnings) and with it (test path).
- The FRANKENPHP_TEST_HOOKS guard around the header include goes
  away in the PR that lands the first real caller; the test hook
  itself goes away in that same step once end-to-end tests cover the
  code paths.

Author: nicolas-grekas

.github/workflows/sanitizers.yaml

@@ -108,7 +108,7 @@ jobs:
       - name: Set CGO flags
         run: |
           {
-            echo "CGO_CFLAGS=$CFLAGS -I${PWD}/watcher/target/include $(php-config --includes)"
+            echo "CGO_CFLAGS=$CFLAGS -I${PWD}/watcher/target/include -DFRANKENPHP_TEST $(php-config --includes)"
             echo "CGO_LDFLAGS=$LDFLAGS $(php-config --ldflags) $(php-config --libs)"
           } >> "$GITHUB_ENV"
       - name: Run tests

.github/workflows/tests.yaml

@@ -59,7 +59,7 @@ jobs:
       - name: Install e-dant/watcher
         uses: ./.github/actions/watcher
       - name: Set CGO flags
-        run: echo "CGO_CFLAGS=-I${PWD}/watcher/target/include $(php-config --includes)" >> "${GITHUB_ENV}"
+        run: echo "CGO_CFLAGS=-I${PWD}/watcher/target/include -DFRANKENPHP_TEST $(php-config --includes)" >> "${GITHUB_ENV}"
       - name: Build
         run: go build
       - name: Build testcli binary
@@ -135,7 +135,7 @@ jobs:
           echo "GEN_STUB_SCRIPT=${PWD}/php-${PHP_VERSION}/build/gen_stub.php" >> "${GITHUB_ENV}"
       - name: Set CGO flags
         run: |
-          echo "CGO_CFLAGS=$(php-config --includes)" >> "${GITHUB_ENV}"
+          echo "CGO_CFLAGS=-DFRANKENPHP_TEST $(php-config --includes)" >> "${GITHUB_ENV}"
           echo "CGO_LDFLAGS=$(php-config --ldflags) $(php-config --libs)" >> "${GITHUB_ENV}"
       - name: Install gotestsum
         run: go install gotest.tools/gotestsum@latest
@@ -172,7 +172,7 @@ jobs:
       - name: Set CGO flags
         run: |
           {
-           echo "CGO_CFLAGS=-I/opt/homebrew/include/ $(php-config --includes)"
+           echo "CGO_CFLAGS=-I/opt/homebrew/include/ -DFRANKENPHP_TEST $(php-config --includes)"
            echo "CGO_LDFLAGS=-L/opt/homebrew/lib/ $(php-config --ldflags) $(php-config --libs)"
           } >> "${GITHUB_ENV}"
       - name: Build

frankenphp.c

@@ -37,6 +37,12 @@
 
 #include "_cgo_export.h"
 #include "frankenphp_arginfo.h"
+#ifdef FRANKENPHP_TEST
+/* The persistent_zval helpers are only compiled in when a consumer needs
+ * them. The step that lands the first real caller (background workers)
+ * will drop this guard. */
+#include "zval.h"
+#endif
 
 #if defined(PHP_WIN32) && defined(ZTS)
 ZEND_TSRMLS_CACHE_DEFINE()
@@ -712,12 +718,55 @@ PHP_FUNCTION(frankenphp_log) {
   }
 }
 
+#ifdef FRANKENPHP_TEST
+/* Test-only entry point that exercises zval.h end-to-end:
+ * validate -> persist (request -> persistent memory) ->
+ * to_request (persistent -> fresh request memory) -> free persistent copy.
+ * Compiled only when FRANKENPHP_TEST is defined; never registered
+ * in production builds. */
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(
+    arginfo_frankenphp_test_persist_roundtrip, 0, 1, IS_MIXED, 0)
+ZEND_ARG_TYPE_INFO(0, value, IS_MIXED, 0)
+ZEND_END_ARG_INFO()
+
+PHP_FUNCTION(frankenphp_test_persist_roundtrip) {
+  zval *input;
+  ZEND_PARSE_PARAMETERS_START(1, 1)
+  Z_PARAM_ZVAL(input)
+  ZEND_PARSE_PARAMETERS_END();
+
+  if (!persistent_zval_validate(input)) {
+    zend_throw_exception(spl_ce_LogicException,
+                         "persistent_zval: value type not supported "
+                         "(only scalars, arrays, and enums are allowed)",
+                         0);
+    RETURN_THROWS();
+  }
+
+  zval persistent;
+  persistent_zval_persist(&persistent, input);
+  persistent_zval_to_request(return_value, &persistent);
+  persistent_zval_free(&persistent);
+}
+
+static const zend_function_entry frankenphp_test_hook_functions[] = {
+    PHP_FE(frankenphp_test_persist_roundtrip,
+           arginfo_frankenphp_test_persist_roundtrip) PHP_FE_END};
+#endif
+
 PHP_MINIT_FUNCTION(frankenphp) {
   register_frankenphp_symbols(module_number);
 #ifndef PHP_WIN32
   pthread_atfork(NULL, NULL, frankenphp_fork_child);
 #endif
 
+#ifdef FRANKENPHP_TEST
+  if (zend_register_functions(NULL, frankenphp_test_hook_functions, NULL,
+                              MODULE_PERSISTENT) == FAILURE) {
+    return FAILURE;
+  }
+#endif
+
   zend_function *func;
 
   // Override putenv

testdata/persist-roundtrip.php

@@ -0,0 +1,88 @@
+<?php
+
+// Exercises frankenphp_test_persist_roundtrip (only registered when
+// FRANKENPHP_TEST_HOOKS is defined at build time). The script runs as a
+// plain non-worker request; the Go harness asserts the combined output.
+
+enum Status: string {
+    case Active = 'active';
+    case Paused = 'paused';
+}
+
+function same(mixed $actual, mixed $expected, string $label): void {
+    if ($actual !== $expected) {
+        echo "FAIL $label: expected ";
+        var_export($expected);
+        echo ' got ';
+        var_export($actual);
+        echo "\n";
+        return;
+    }
+    echo "OK $label\n";
+}
+
+$rt = 'frankenphp_test_persist_roundtrip';
+if (!function_exists($rt)) {
+    echo "SKIP frankenphp_test_persist_roundtrip not registered\n";
+    return;
+}
+
+// Scalars.
+same($rt(null), null, 'null');
+same($rt(false), false, 'false');
+same($rt(true), true, 'true');
+same($rt(0), 0, 'int zero');
+same($rt(42), 42, 'int');
+same($rt(-1), -1, 'int negative');
+same($rt(1.5), 1.5, 'float');
+same($rt(''), '', 'empty string');
+same($rt('hello'), 'hello', 'short string');
+
+// Long (non-interned) string: forces the allocation path.
+$long = str_repeat('x', 1024);
+same($rt($long), $long, 'long string');
+
+// Nested arrays, mixed keys.
+$arr = [
+    'name' => 'alice',
+    'age' => 30,
+    'tags' => ['admin', 'editor'],
+    'meta' => ['created' => 1234567890, 'flags' => [true, false, null]],
+    0 => 'first',
+    1 => 'second',
+];
+same($rt($arr), $arr, 'nested array');
+
+// Enum roundtrip: identity (===) must be preserved because the enum is
+// re-resolved to the same singleton case on the read side.
+same($rt(Status::Active), Status::Active, 'enum active');
+same($rt(Status::Paused), Status::Paused, 'enum paused');
+
+// Array containing an enum.
+same(
+    $rt(['status' => Status::Active, 'count' => 7]),
+    ['status' => Status::Active, 'count' => 7],
+    'array with enum',
+);
+
+// Invalid inputs throw LogicException.
+try {
+    $rt(new stdClass());
+    echo "FAIL stdClass should throw\n";
+} catch (\LogicException) {
+    echo "OK stdClass rejected\n";
+}
+
+try {
+    $rt(fopen('php://memory', 'r'));
+    echo "FAIL resource should throw\n";
+} catch (\LogicException) {
+    echo "OK resource rejected\n";
+}
+
+try {
+    $rt(['ok' => 1, 'bad' => new stdClass()]);
+    echo "FAIL nested stdClass should throw\n";
+} catch (\LogicException) {
+    echo "OK nested stdClass rejected\n";
+}