@voxgig/sdkgen 4.8.1 → 4.8.3

package/project/.sdk/tm/php/test/PrimaryUtilityTest.php

@@ -2,304 +2,95 @@
 declare(strict_types=1);
 
 // ProjectName SDK primary utility test
+//
+// Corpus sections run through the vendored omni runner, via the resolver
+// in test/Omni.php (struct-runner shape over native Voxgig\Omni). The
+// inline corpus engine this file used to carry is retired: omni resolves
+// arguments, applies the null rules, and enforces out/err/match - the
+// subjects below only adapt each utility's calling convention.
+//
+// Three conventions to know when adding a section:
+//
+// - Utilities that answer as a (value, err) TUPLE go through
+//   ProjectNameOmni::unwrap, which throws the err so omni can match it
+//   against `err:` expectations. Utilities that answer bare values (or
+//   throw) are returned straight.
+//
+// - Contexts stay MAPS across the runner (Omni.php decision 2): a subject
+//   builds the typed context with ProjectNameOmni::ctx_from_map, runs the
+//   utility, and writes the observable state back with
+//   ProjectNameOmni::sync_ctx BEFORE throwing any error - that map is
+//   where a `match: {ctx: ...}` assertion reads.
+//
+// - `runsection` fails loudly when a section would run ZERO cases; a
+//   deliberately-empty (pending) section is named in PENDING.
 
 require_once __DIR__ . '/../projectname_sdk.php';
 require_once __DIR__ . '/Runner.php';
+require_once __DIR__ . '/Omni.php';
 
 use PHPUnit\Framework\TestCase;
-use Voxgig\Struct\Struct;
 
 class PrimaryUtilityTest extends TestCase
 {
-    private static ?array $test_spec = null;
-
-    private static function load_test_spec(): array
-    {
-        if (self::$test_spec !== null) {
-            return self::$test_spec;
-        }
-        $path = __DIR__ . '/../../.sdk/test/test.json';
-        $content = file_get_contents($path);
-        if ($content === false) {
-            throw new RuntimeException("Failed to load test.json: $path");
+    // Resolved against test/Omni.php's own directory, so the suite works
+    // from any working directory.
+    private const TEST_JSON_FILE = '../../.sdk/test/test.json';
+
+    // Sections deliberately left empty in the shared corpus
+    // (.sdk/test/primary/<name>.aon carries a PENDING header). Everything
+    // else MUST contribute cases.
+    private const PENDING = [
+        'fetcher', 'makeFetchDef', 'makeResult',
+        'featureAdd', 'featureHook', 'featureInit',
+    ];
+
+    private static ?array $run = null;
+
+    /** The 'primary' runpack, built once for the whole class. */
+    private static function runpack(): array
+    {
+        if (self::$run === null) {
+            $runner = ProjectNameOmni::makeRunner(
+                self::TEST_JSON_FILE, ProjectNameSDK::test(null, null));
+            self::$run = $runner('primary');
         }
-        $data = json_decode($content, true);
-        if (json_last_error() !== JSON_ERROR_NONE) {
-            throw new RuntimeException("Failed to parse test.json: " . json_last_error_msg());
-        }
-        self::$test_spec = $data;
-        return $data;
+        return self::$run;
     }
 
-    private static function get_spec(?array $spec, string ...$keys): ?array
+    /** The live SDK behind the runpack's provider client. */
+    private static function client(): ProjectNameSDK
     {
-        $cur = $spec;
-        foreach ($keys as $key) {
-            if (!is_array($cur) || !array_key_exists($key, $cur)) {
-                return null;
-            }
-            $cur = $cur[$key];
-        }
-        return is_array($cur) ? $cur : null;
+        return self::runpack()['client']['sdk'];
     }
 
-    private function runset(?array $testspec, callable $subject): void
+    /**
+     * Run one corpus section, failing loudly when it would run ZERO
+     * cases. A renamed section or a fixture that compiled to an empty
+     * `set` used to pass silently, which defeats the point of a shared
+     * oracle. EVERY corpus-backed test goes through here (mirrors ts/py).
+     */
+    private function runsection(string $name, callable $subject): void
     {
-        if ($testspec === null || !isset($testspec['set']) || !is_array($testspec['set'])) {
-            return;
-        }
-        $set = $testspec['set'];
-
-        foreach ($set as $i => $entry) {
-            if (!is_array($entry)) {
-                continue;
-            }
-
-            $mark = '';
-            if (isset($entry['mark'])) {
-                $mark = " (mark={$entry['mark']})";
-            }
-
-            $result = null;
-            $err = null;
-
-            try {
-                [$result, $err] = $subject($entry);
-            } catch (\Throwable $e) {
-                $err = $e;
-            }
-
-            $expected_err = $entry['err'] ?? null;
-
-            if ($err !== null) {
-                if ($expected_err !== null) {
-                    $err_msg = ($err instanceof \Throwable) ? $err->getMessage() : (string)$err;
-                    if (is_string($expected_err)) {
-                        $this->assertTrue(
-                            $this->match_string($expected_err, $err_msg),
-                            "entry {$i}{$mark}: error mismatch: got \"{$err_msg}\", want contains \"{$expected_err}\""
-                        );
-                    }
-                    // err: true means any error is acceptable
-
-                    if (isset($entry['match']) && is_array($entry['match'])) {
-                        $result_map = [
-                            'in' => $entry['in'] ?? null,
-                            'out' => $this->json_normalize($result),
-                            'err' => ['message' => ($err instanceof \Throwable) ? $err->getMessage() : (string)$err],
-                        ];
-                        $this->match_deep($i, $mark, $entry['match'], $result_map, '');
-                    }
-                    continue;
-                }
-                $err_msg = ($err instanceof \Throwable) ? $err->getMessage() : (string)$err;
-                $this->fail("entry {$i}{$mark}: unexpected error: {$err_msg}");
-                continue;
-            }
-
-            if ($expected_err !== null) {
-                $this->fail(
-                    "entry {$i}{$mark}: expected error containing \"{$expected_err}\" but got result: "
-                    . json_encode($result)
-                );
-                continue;
-            }
-
-            $matched = false;
-            if (isset($entry['match']) && is_array($entry['match'])) {
-                $result_map = [
-                    'in' => $entry['in'] ?? null,
-                    'out' => $this->json_normalize($result),
-                ];
-                if (isset($entry['args'])) {
-                    $result_map['args'] = $entry['args'];
-                } elseif (isset($entry['in'])) {
-                    $result_map['args'] = [$entry['in']];
-                }
-                if (isset($entry['ctx'])) {
-                    $result_map['ctx'] = $entry['ctx'];
-                }
-                $this->match_deep($i, $mark, $entry['match'], $result_map, '');
-                $this->assertTrue(true, "entry {$i}{$mark}: match completed");
-                $matched = true;
-            }
-
-            $expected_out = $entry['out'] ?? null;
-            if ($expected_out === null && $matched) {
-                continue;
-            }
-            if ($expected_out !== null) {
-                $norm_result = $this->json_normalize($result);
-                $norm_expected = $this->json_normalize($expected_out);
-                $this->assertEquals(
-                    $norm_expected,
-                    $norm_result,
-                    "entry {$i}{$mark}: output mismatch"
-                );
-            }
-        }
-    }
-
-    private function json_normalize(mixed $val): mixed
-    {
-        if ($val === null) {
-            return null;
-        }
-        $j = json_encode($val);
-        if ($j === false) {
-            return $val;
-        }
-        return json_decode($j, true);
-    }
-
-    private function match_deep(int $entry_idx, string $mark, mixed $check, mixed $base, string $path): void
-    {
-        if ($check === null) {
-            return;
-        }
+        $R = self::runpack();
+        $spec = $R['spec'];
 
-        if (is_array($check) && !$this->is_list($check)) {
-            // Associative array (map)
-            foreach ($check as $key => $check_val) {
-                $child_path = $path . '.' . $key;
-                $base_val = null;
-                if (is_array($base) && array_key_exists($key, $base)) {
-                    $base_val = $base[$key];
-                }
-                $this->match_deep($entry_idx, $mark, $check_val, $base_val, $child_path);
-            }
-        } elseif (is_array($check) && $this->is_list($check)) {
-            // Indexed array (list)
-            foreach ($check as $i => $check_val) {
-                $child_path = $path . "[{$i}]";
-                $base_val = null;
-                if (is_array($base) && isset($base[$i])) {
-                    $base_val = $base[$i];
-                }
-                $this->match_deep($entry_idx, $mark, $check_val, $base_val, $child_path);
-            }
-        } else {
-            if (is_string($check) && $check === '__EXISTS__') {
-                $this->assertNotNull(
-                    $base,
-                    "entry {$entry_idx}{$mark}: match {$path}: expected value to exist but got null"
-                );
-                return;
-            }
-            if (is_string($check) && $check === '__UNDEF__') {
-                $this->assertNull(
-                    $base,
-                    "entry {$entry_idx}{$mark}: match {$path}: expected null but got " . json_encode($base)
-                );
-                return;
-            }
-
-            $norm_check = $this->json_normalize($check);
-            $norm_base = $this->json_normalize($base);
-
-            if ($norm_check !== $norm_base) {
-                if (is_string($check) && $check !== '') {
-                    $base_str = Struct::stringify($base);
-                    if ($this->match_string($check, $base_str)) {
-                        return;
-                    }
-                }
-                $this->assertEquals(
-                    $norm_check,
-                    $norm_base,
-                    "entry {$entry_idx}{$mark}: match {$path}"
-                );
-            }
-        }
-    }
-
-    private function match_string(string $pattern, string $val): bool
-    {
-        if (strlen($pattern) >= 2 && $pattern[0] === '/' && $pattern[strlen($pattern) - 1] === '/') {
-            $re = substr($pattern, 1, -1);
-            return (bool)preg_match('/' . $re . '/', $val);
-        }
-        return str_contains(strtolower($val), strtolower($pattern));
-    }
-
-    private function is_list(array $arr): bool
-    {
-        if (empty($arr)) {
-            return true;
-        }
-        return array_keys($arr) === range(0, count($arr) - 1);
-    }
-
-    private static function make_ctx_from_map(
-        ?array $ctxmap,
-        ProjectNameSDK $client,
-        ProjectNameUtility $utility
-    ): ProjectNameContext {
-        if ($ctxmap === null) {
-            $ctxmap = [];
-        }
-
-        $ctx = new ProjectNameContext($ctxmap, null);
-
-        $ctx->client = $client;
-        $ctx->utility = $utility;
-
-        if ($ctx->options === null) {
-            $ctx->options = $client->options_map();
-        }
-
-        // Handle spec from JSON map
-        if (isset($ctxmap['spec']) && is_array($ctxmap['spec'])) {
-            $ctx->spec = new ProjectNameSpec($ctxmap['spec']);
-        }
-
-        // Handle result from JSON map
-        if (isset($ctxmap['result']) && is_array($ctxmap['result'])) {
-            $ctx->result = new ProjectNameResult($ctxmap['result']);
-            if (isset($ctxmap['result']['err']) && is_array($ctxmap['result']['err'])) {
-                $msg = $ctxmap['result']['err']['message'] ?? '';
-                $ctx->result->err = new ProjectNameError('', $msg);
-            }
-        }
-
-        // Handle response from JSON map
-        if (isset($ctxmap['response']) && is_array($ctxmap['response'])) {
-            $ctx->response = new ProjectNameResponse($ctxmap['response']);
-            if (isset($ctxmap['response']['body'])) {
-                $body_copy = $ctxmap['response']['body'];
-                $ctx->response->json_func = function () use ($body_copy) { return $body_copy; };
-                $ctx->response->body = $body_copy;
-            }
-            if (isset($ctxmap['response']['headers']) && is_array($ctxmap['response']['headers'])) {
-                $lower_headers = [];
-                foreach ($ctxmap['response']['headers'] as $k => $v) {
-                    $lower_headers[strtolower($k)] = $v;
-                }
-                $ctx->response->headers = $lower_headers;
-            }
-        }
+        $section = is_array($spec) ? ($spec[$name] ?? null) : null;
+        $this->assertIsArray($section,
+            "test corpus section '{$name}' missing - check the name against .sdk/test/primary/");
 
-        return $ctx;
-    }
+        $basic = $section['basic'] ?? null;
+        $this->assertTrue(is_array($basic) && is_array($basic['set'] ?? null),
+            "test corpus section '{$name}' has no basic.set list");
 
-    private static function fixctx(ProjectNameContext $ctx, ProjectNameSDK $client): void
-    {
-        if ($ctx->client !== null && $ctx->options === null) {
-            $ctx->options = $ctx->client->options_map();
+        if (0 === count($basic['set']) && !in_array($name, self::PENDING, true)) {
+            $this->fail(
+                "test corpus section '{$name}' is EMPTY - zero cases would run; " .
+                "add cases, or mark the fixture PENDING in .sdk/test/primary/");
         }
-    }
 
-    private static function err_from_map(?array $m): ?ProjectNameError
-    {
-        if ($m === null) {
-            return null;
-        }
-        $msg = $m['message'] ?? '';
-        if ($msg === '') {
-            return null;
-        }
-        $code = $m['code'] ?? '';
-        return new ProjectNameError($code, $msg);
+        $R['runset']($basic, $subject);
+        $this->assertTrue(true, "corpus section '{$name}' completed");
     }
 
     private static function make_test_ctx(
@@ -396,20 +187,14 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_done_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'done', 'basic'), function (array $entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            self::fixctx($ctx, $client);
-            // done now returns the bare result data (or raises on error, which
-            // runset catches). Re-wrap success into a (result, err) tuple so the
-            // data-driven spec matcher keeps working.
-            $out = ($utility->done)($ctx);
-            return [$out, null];
+        $this->runsection('done', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
+            // done returns the bare result data, or raises on error - which
+            // omni matches against the entry's `err`.
+            return ($utility->done)($ctx);
         });
     }
 
@@ -418,34 +203,17 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_make_error_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'makeError', 'basic'), function (array $entry) use ($client, $utility) {
-            $args = $entry['args'] ?? [];
-            if (empty($args)) {
-                $args = [[]];
-            }
-
-            $ctxmap = $args[0] ?? [];
-            if (!is_array($ctxmap)) {
-                $ctxmap = [];
-            }
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            self::fixctx($ctx, $client);
-
-            $err = null;
-            if (count($args) > 1 && is_array($args[1])) {
-                $err = self::err_from_map($args[1]);
-            }
-
-            // make_error now RAISES the constructed exception (default throw
-            // path); runset catches it. On the no-throw path it returns the
-            // bare result data, which we re-wrap into a (result, err) tuple.
-            $out = ($utility->make_error)($ctx, $err);
-            return [$out, null];
+        $this->runsection('makeError', function ($ctxmap = null, $errmap = null) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map(
+                is_array($ctxmap) ? $ctxmap : [], $client, $utility);
+            $err = ProjectNameOmni::err_from_map(is_array($errmap) ? $errmap : null);
+            // make_error RAISES the constructed exception on the default
+            // (throw) path; omni matches it against the entry's err. On the
+            // no-throw path it returns the bare result data.
+            return ($utility->make_error)($ctx, $err);
         });
     }
 
@@ -649,27 +417,23 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_make_context_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
-        $utility = $client->get_utility();
+        $utility = self::client()->get_utility();
 
-        $this->runset(self::get_spec($primary, 'makeContext', 'basic'), function (array $entry) use ($client, $utility) {
-            $in = $entry['in'] ?? null;
-            if (is_array($in)) {
-                $ctx = ($utility->make_context)($in, null);
-                $out = [
-                    'id' => $ctx->id,
+        $this->runsection('makeContext', function ($vin = null) use ($utility) {
+            if (!is_array($vin)) {
+                return null;
+            }
+            $ctx = ($utility->make_context)($vin, null);
+            $out = [
+                'id' => $ctx->id,
+            ];
+            if ($ctx->op !== null) {
+                $out['op'] = [
+                    'name' => $ctx->op->name,
+                    'input' => $ctx->op->input,
                 ];
-                if ($ctx->op !== null) {
-                    $out['op'] = [
-                        'name' => $ctx->op->name,
-                        'input' => $ctx->op->input,
-                    ];
-                }
-                return [$out, null];
             }
-            return [null, null];
+            return $out;
         });
     }
 
@@ -740,20 +504,20 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_make_options_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'makeOptions', 'basic'), function (array $entry) use ($client, $utility) {
-            $in = $entry['in'] ?? [];
+        $this->runsection('makeOptions', function ($vin = null) use ($client, $utility) {
+            if (!is_array($vin)) {
+                $vin = [];
+            }
             $ctx = ($utility->make_context)([
-                'options' => $in['options'] ?? null,
-                'config' => $in['config'] ?? null,
+                'options' => $vin['options'] ?? null,
+                'config' => $vin['config'] ?? null,
             ], null);
             $ctx->client = $client;
             $ctx->utility = $utility;
-            return [($utility->make_options)($ctx), null];
+            return ($utility->make_options)($ctx);
         });
     }
 
@@ -762,27 +526,20 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_make_request_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'makeRequest', 'basic'), function (array &$entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
+        $this->runsection('makeRequest', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
             $ctx->options = $client->options_map();
 
             [$_, $err] = ($utility->make_request)($ctx);
 
-            // Update entry ctx for match checking
-            if ($ctx->response !== null) {
-                $entry['ctx']['response'] = 'exists';
-            }
-            if ($ctx->result !== null) {
-                $entry['ctx']['result'] = 'exists';
+            ProjectNameOmni::sync_ctx($ctxmap, $ctx);
+            if ($err !== null) {
+                throw $err;
             }
-
-            return [null, $err];
+            return null;
         });
     }
 
@@ -791,30 +548,19 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_make_response_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'makeResponse', 'basic'), function (array &$entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            self::fixctx($ctx, $client);
+        $this->runsection('makeResponse', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
 
             [$_, $err] = ($utility->make_response)($ctx);
 
-            // Update entry ctx for match with result data
-            if ($ctx->result !== null) {
-                $entry['ctx']['result'] = [
-                    'ok' => $ctx->result->ok,
-                    'status' => $ctx->result->status,
-                    'statusText' => $ctx->result->status_text,
-                    'headers' => $ctx->result->headers,
-                    'body' => $ctx->result->body,
-                ];
+            ProjectNameOmni::sync_ctx($ctxmap, $ctx);
+            if ($err !== null) {
+                throw $err;
             }
-
-            return [null, $err];
+            return null;
         });
     }
 
@@ -891,36 +637,23 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_make_spec_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $setup_opts = self::get_spec($primary, 'makeSpec', 'DEF', 'setup', 'a');
-        $spec_client = ProjectNameSDK::test(null, $setup_opts);
+        $R = self::runpack();
+        $setup = $R['spec']['makeSpec']['DEF']['setup']['a'] ?? null;
+        $spec_client = ProjectNameSDK::test(null, is_array($setup) ? $setup : null);
         $spec_utility = $spec_client->get_utility();
-        $client = ProjectNameSDK::test(null, null);
-        $utility = $client->get_utility();
+        $utility = self::client()->get_utility();
 
-        $this->runset(self::get_spec($primary, 'makeSpec', 'basic'), function (array &$entry) use ($spec_client, $spec_utility, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $spec_client, $spec_utility);
+        $this->runsection('makeSpec', function (array $ctxmap) use ($spec_client, $spec_utility, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $spec_client, $spec_utility);
             $ctx->options = $spec_client->options_map();
 
             [$_, $err] = ($utility->make_spec)($ctx);
 
-            // Update entry ctx for match
-            if ($ctx->spec !== null) {
-                $entry['ctx']['spec'] = [
-                    'base' => $ctx->spec->base,
-                    'prefix' => $ctx->spec->prefix,
-                    'suffix' => $ctx->spec->suffix,
-                    'method' => $ctx->spec->method,
-                    'params' => $ctx->spec->params,
-                    'query' => $ctx->spec->query,
-                    'headers' => $ctx->spec->headers,
-                    'step' => $ctx->spec->step,
-                ];
+            ProjectNameOmni::sync_ctx($ctxmap, $ctx);
+            if ($err !== null) {
+                throw $err;
             }
-
-            return [null, $err];
+            return null;
         });
     }
 
@@ -953,18 +686,15 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_make_url_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'makeUrl', 'basic'), function (array $entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
+        $this->runsection('makeUrl', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
             if ($ctx->result === null) {
                 $ctx->result = new ProjectNameResult([]);
             }
-            return ($utility->make_url)($ctx);
+            return ProjectNameOmni::unwrap(($utility->make_url)($ctx));
         });
     }
 
@@ -973,18 +703,17 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_operator_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-
-        $this->runset(self::get_spec($primary, 'operator', 'basic'), function (array $entry) {
-            $in = $entry['in'] ?? [];
-            $op = new ProjectNameOperation($in);
-            return [[
+        $this->runsection('operator', function ($vin = null) {
+            if (!is_array($vin)) {
+                $vin = [];
+            }
+            $op = new ProjectNameOperation($vin);
+            return [
                 'entity' => $op->entity,
                 'name' => $op->name,
                 'input' => $op->input,
                 'points' => $op->points,
-            ], null];
+            ];
         });
     }
 
@@ -993,46 +722,19 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_param_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'param', 'basic'), function (array &$entry) use ($client, $utility) {
-            $args = $entry['args'] ?? [];
-            if (count($args) < 2) {
-                return [null, null];
-            }
+        $this->runsection('param', function ($ctxmap = null, $name = null) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map(
+                is_array($ctxmap) ? $ctxmap : [], $client, $utility);
 
-            $ctxmap = $args[0] ?? [];
-            if (!is_array($ctxmap)) {
-                $ctxmap = [];
-            }
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            $paramdef = $args[1];
-
-            $result = ($utility->param)($ctx, $paramdef);
-
-            // Update entry ctx for match
-            if (isset($entry['match']) && is_array($entry['match'])) {
-                if (isset($entry['match']['ctx']) && is_array($entry['match']['ctx'])) {
-                    $ctx_match = $entry['match']['ctx'];
-                    if (!isset($entry['ctx'])) {
-                        $entry['ctx'] = [];
-                    }
-                    if (isset($ctx_match['spec']) && is_array($ctx_match['spec'])) {
-                        if ($ctx->spec !== null) {
-                            if (isset($ctx_match['spec']['alias'])) {
-                                $entry['ctx']['spec'] = [
-                                    'alias' => $ctx->spec->alias_map,
-                                ];
-                            }
-                        }
-                    }
-                }
-            }
+            $result = ($utility->param)($ctx, $name);
 
-            return [$result, null];
+            if (is_array($ctxmap)) {
+                ProjectNameOmni::sync_ctx($ctxmap, $ctx);
+            }
+            return $result;
         });
     }
 
@@ -1041,29 +743,22 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_prepare_auth_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $setup_opts = self::get_spec($primary, 'prepareAuth', 'DEF', 'setup', 'a');
-        $auth_client = ProjectNameSDK::test(null, $setup_opts);
+        $R = self::runpack();
+        $setup = $R['spec']['prepareAuth']['DEF']['setup']['a'] ?? null;
+        $auth_client = ProjectNameSDK::test(null, is_array($setup) ? $setup : null);
         $auth_utility = $auth_client->get_utility();
-        $client = ProjectNameSDK::test(null, null);
-        $utility = $client->get_utility();
+        $utility = self::client()->get_utility();
 
-        $this->runset(self::get_spec($primary, 'prepareAuth', 'basic'), function (array &$entry) use ($auth_client, $auth_utility, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $auth_client, $auth_utility);
-            self::fixctx($ctx, $auth_client);
+        $this->runsection('prepareAuth', function (array $ctxmap) use ($auth_client, $auth_utility, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $auth_client, $auth_utility);
 
             [$_, $err] = ($utility->prepare_auth)($ctx);
 
-            // Update entry ctx for match
-            if ($ctx->spec !== null) {
-                $entry['ctx']['spec'] = [
-                    'headers' => $ctx->spec->headers,
-                ];
+            ProjectNameOmni::sync_ctx($ctxmap, $ctx);
+            if ($err !== null) {
+                throw $err;
             }
-
-            return [null, $err];
+            return null;
         });
     }
 
@@ -1072,16 +767,12 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_prepare_body_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'prepareBody', 'basic'), function (array $entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            self::fixctx($ctx, $client);
-            return [($utility->prepare_body)($ctx), null];
+        $this->runsection('prepareBody', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
+            return ($utility->prepare_body)($ctx);
         });
     }
 
@@ -1090,15 +781,12 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_prepare_headers_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'prepareHeaders', 'basic'), function (array $entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            return [($utility->prepare_headers)($ctx), null];
+        $this->runsection('prepareHeaders', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
+            return ($utility->prepare_headers)($ctx);
         });
     }
 
@@ -1107,15 +795,12 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_prepare_method_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'prepareMethod', 'basic'), function (array $entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            return [($utility->prepare_method)($ctx), null];
+        $this->runsection('prepareMethod', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
+            return ($utility->prepare_method)($ctx);
         });
     }
 
@@ -1124,15 +809,12 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_prepare_params_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'prepareParams', 'basic'), function (array $entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            return [($utility->prepare_params)($ctx), null];
+        $this->runsection('prepareParams', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
+            return ($utility->prepare_params)($ctx);
         });
     }
 
@@ -1141,17 +823,12 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_prepare_path_basic(): void
     {
-        // Was hand-written cases that had drifted out of the shared corpus
-        // (the preparePath fixture shipped as an empty `set: []`).
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'preparePath', 'basic'), function (array $entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            return [($utility->prepare_path)($ctx), null];
+        $this->runsection('preparePath', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
+            return ($utility->prepare_path)($ctx);
         });
     }
 
@@ -1177,15 +854,12 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_prepare_query_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'prepareQuery', 'basic'), function (array $entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            return [($utility->prepare_query)($ctx), null];
+        $this->runsection('prepareQuery', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
+            return ($utility->prepare_query)($ctx);
         });
     }
 
@@ -1194,15 +868,11 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_result_basic_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'resultBasic', 'basic'), function (array $entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
-            self::fixctx($ctx, $client);
+        $this->runsection('resultBasic', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
 
             $result = ($utility->result_basic)($ctx);
 
@@ -1211,11 +881,12 @@ class PrimaryUtilityTest extends TestCase
                 'statusText' => $result->status_text,
             ];
             if ($result->err !== null) {
-                $err_msg = ($result->err instanceof ProjectNameError) ? $result->err->msg : (string)$result->err;
+                $err_msg = ($result->err instanceof ProjectNameError)
+                    ? $result->err->msg : (string) $result->err;
                 $out['err'] = ['message' => $err_msg];
             }
 
-            return [$out, null];
+            return $out;
         });
     }
 
@@ -1224,25 +895,16 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_result_body_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'resultBody', 'basic'), function (array &$entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
+        $this->runsection('resultBody', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
 
             ($utility->result_body)($ctx);
 
-            // Update entry ctx for match
-            if ($ctx->result !== null) {
-                $entry['ctx']['result'] = [
-                    'body' => $ctx->result->body,
-                ];
-            }
-
-            return [null, null];
+            ProjectNameOmni::sync_ctx($ctxmap, $ctx);
+            return null;
         });
     }
 
@@ -1251,25 +913,16 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_result_headers_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'resultHeaders', 'basic'), function (array &$entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
+        $this->runsection('resultHeaders', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
 
             ($utility->result_headers)($ctx);
 
-            // Update entry ctx for match
-            if ($ctx->result !== null) {
-                $entry['ctx']['result'] = [
-                    'headers' => $ctx->result->headers,
-                ];
-            }
-
-            return [null, null];
+            ProjectNameOmni::sync_ctx($ctxmap, $ctx);
+            return null;
         });
     }
 
@@ -1278,23 +931,16 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_transform_request_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'transformRequest', 'basic'), function (array &$entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
+        $this->runsection('transformRequest', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
 
             $result = ($utility->transform_request)($ctx);
 
-            // Update entry ctx for match (step changed)
-            if ($ctx->spec !== null && isset($entry['ctx']['spec']) && is_array($entry['ctx']['spec'])) {
-                $entry['ctx']['spec']['step'] = $ctx->spec->step;
-            }
-
-            return [$result, null];
+            ProjectNameOmni::sync_ctx($ctxmap, $ctx);
+            return $result;
         });
     }
 
@@ -1303,23 +949,16 @@ class PrimaryUtilityTest extends TestCase
 
     public function test_transform_response_basic(): void
     {
-        $spec = self::load_test_spec();
-        $primary = self::get_spec($spec, 'primary');
-        $client = ProjectNameSDK::test(null, null);
+        $client = self::client();
         $utility = $client->get_utility();
 
-        $this->runset(self::get_spec($primary, 'transformResponse', 'basic'), function (array &$entry) use ($client, $utility) {
-            $ctxmap = $entry['ctx'] ?? [];
-            $ctx = self::make_ctx_from_map($ctxmap, $client, $utility);
+        $this->runsection('transformResponse', function (array $ctxmap) use ($client, $utility) {
+            $ctx = ProjectNameOmni::ctx_from_map($ctxmap, $client, $utility);
 
             $result = ($utility->transform_response)($ctx);
 
-            // Update entry ctx for match (step changed)
-            if ($ctx->spec !== null && isset($entry['ctx']['spec']) && is_array($entry['ctx']['spec'])) {
-                $entry['ctx']['spec']['step'] = $ctx->spec->step;
-            }
-
-            return [$result, null];
+            ProjectNameOmni::sync_ctx($ctxmap, $ctx);
+            return $result;
         });
     }
 }