@voxgig/sdkgen 4.8.2 → 4.9.0

package/project/.sdk/src/cmp/zig/Package_zig.ts

@@ -12,7 +12,7 @@ import type {
 } from '@voxgig/apidef'
 
 
-import { zigModuleName } from './utility_zig'
+import { zigModuleName, zigPackageFingerprint } from './utility_zig'
 
 
 // build.zig.zon — the Zig package manifest. Zig has no central package
@@ -24,16 +24,19 @@ import { zigModuleName } from './utility_zig'
 //
 // The `.paths` allow-list mirrors the (registry-less) template: it only
 // matters when packaging for a registry, which zig does not do, so it is kept
-// stable. `.name` is a plain string here rather than the newer enum-literal +
-// fingerprint form.
+// stable.
 //
-// TOOLCHAIN PIN: the string form REQUIRES zig <= 0.13. Zig 0.14 rejects it
-// outright — `build.zig.zon:2:13: error: expected enum literal` — so the
-// generated SDK will not build at all on a newer toolchain. The consumer CI
-// job pins 0.13.0 to match (create-sdkgen
-// project/standard/.github/workflows/ci.yml). Moving to a newer zig means
-// changing BOTH: `.name = .${name}` plus a `.fingerprint` here, and the CI
-// pin there.
+// TOOLCHAIN: zig 0.16. `.name` is an ENUM LITERAL (`.solar_sdk`), and a
+// `.fingerprint` is required beside it. That pairing is what a modern zig
+// wants: 0.14 rejects the older plain-string form outright —
+// `build.zig.zon:2:13: error: expected enum literal` — and 0.13 rejects the
+// enum-literal form, so the two cannot both be supported from one generator.
+// A move BACK to 0.13 would mean reverting both fields here and the CI pin in
+// create-sdkgen project/standard/.github/workflows/ci.yml together.
+//
+// The fingerprint is derived from the package name, not random, so
+// regenerating the same model does not rewrite this file — see
+// zigPackageFingerprint for why, and for what zig checks.
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
   const target = props.target
@@ -43,8 +46,9 @@ const Package = cmp(async function Package(props: any) {
 
   File({ name: 'build.zig.zon' }, () => {
     Content(`.{
-    .name = "${name}",
+    .name = .${name},
     .version = "${packageVersion(model, target.name)}",
+    .fingerprint = ${zigPackageFingerprint(name)},
     .dependencies = .{},
     .paths = .{
         "src",

package/project/.sdk/src/cmp/zig/fragment/Entity.fragment.zig

@@ -231,9 +231,9 @@ pub const EntyClass = struct {
         if (data == .array) {
             return data.array.data.items;
         } else if (!h.is_noval(data)) {
-            var out = std.ArrayList(Value).init(h.A());
-            out.append(data) catch {};
-            return out.toOwnedSlice() catch &.{};
+            var out: std.ArrayList(Value) = .empty;
+            out.append(h.A(), data) catch {};
+            return out.toOwnedSlice(h.A()) catch &.{};
         }
         return &.{};
     }

package/project/.sdk/src/cmp/zig/fragment/EntityListOp.fragment.zig

@@ -16,18 +16,18 @@ pub fn list(self: *EntyClass, reqmatch: Value, ctrl: Value) EntListResult {
     // `list` resolves to one ENTITY per record. make_result cannot build them
     // here — it works in Value, which has no slot for an entity — so the op
     // does, mirroring what the dynamic targets get from make_result.
-    var items = std.ArrayList(*EntyClass).init(h.A());
+    var items: std.ArrayList(*EntyClass) = .empty;
     if (out == .array) {
         for (out.array.data.items) |entry| {
             const ent = EntyClass.new(self.client, h.clone(self.entopts));
             if (entry == .object) {
                 _ = ent.data_impl(entry);
             }
-            items.append(ent) catch {};
+            items.append(h.A(), ent) catch {};
         }
     }
 
-    return EntListResult{ .ok = items.toOwnedSlice() catch &[_]*EntyClass{} };
+    return EntListResult{ .ok = items.toOwnedSlice(h.A()) catch &[_]*EntyClass{} };
 }
 
 fn list_post_done(self: *EntyClass, ctx: *Context) void {

package/project/.sdk/src/cmp/zig/fragment/Main.fragment.zig

@@ -45,7 +45,7 @@ pub const ProjectNameSDK = struct {
             .mode = "live",
             .options = h.vnull(),
             .sdkUtility = Utility.new(),
-            .features = std.ArrayList(Feature).init(h.A()),
+            .features = .empty,
             .rootctx = null,
         };
 
@@ -93,8 +93,8 @@ pub const ProjectNameSDK = struct {
         }
 
         // Initialize features.
-        var snap = std.ArrayList(Feature).init(h.A());
-        for (sdk.features.items) |f| snap.append(f) catch {};
+        var snap: std.ArrayList(Feature) = .empty;
+        for (sdk.features.items) |f| snap.append(h.A(), f) catch {};
         for (snap.items) |f| sdk.sdkUtility.feature_init(rootctx, f);
 
         sdk.sdkUtility.feature_hook(rootctx, "PostConstruct");

package/project/.sdk/src/cmp/zig/utility_zig.ts

@@ -26,8 +26,56 @@ function zigVarName(name: string): string {
 
 // The zig module identifier, e.g. solar_sdk (informational; the build module
 // is named "sdk").
+//
+// It is also the `.name` of build.zig.zon, which zig 0.16 reads as an enum
+// literal and requires to be a BARE identifier — `.@"2fa_sdk"` is rejected as
+// firmly as `.2fa_sdk` is — so a model name starting with a digit is given a
+// leading underscore. Nothing else in the target derives an identifier from
+// this, and the alternative for such a model is a package that does not build.
 function zigModuleName(model: any): string {
-  return `${model.name}_sdk`.toLowerCase().replace(/[^a-z0-9_]/g, '_')
+  const name = `${model.name}_sdk`.toLowerCase().replace(/[^a-z0-9_]/g, '_')
+  return /^[0-9]/.test(name) ? '_' + name : name
+}
+
+
+// The `.fingerprint` zig 0.14+ requires in build.zig.zon, as a 0x-prefixed
+// 16-digit hex literal.
+//
+// Zig reads the field as a packed struct of two u32s: the LOW half is a free
+// `id`, and the HIGH half is a `checksum` that must equal the CRC-32 (IEEE, as
+// zlib computes it) of the package name. Get the checksum wrong and zig
+// refuses to build, printing the value it wanted; get it right and any id in
+// [1, 0xfffffffe] is accepted.
+//
+// The id exists so a fork can be told apart from what it forked. A generated
+// SDK gets a DERIVED one — FNV-1a over the same name — rather than a random
+// one, because this file is regenerated on every run: a random id would
+// rewrite build.zig.zon each time and churn the consumer's diff, and a package
+// that changes identity between two generations of the same model is worse
+// than one that shares an id with a fork of itself. Distinct names still get
+// distinct ids.
+function zigPackageFingerprint(name: string): string {
+  // CRC-32 (IEEE 802.3, reflected, poly 0xEDB88320) — the one zig's
+  // std.hash.Crc32 and zlib both compute.
+  let crc = 0xffffffff
+  for (let i = 0; i < name.length; i++) {
+    crc ^= name.charCodeAt(i) & 0xff
+    for (let b = 0; b < 8; b++) {
+      crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1))
+    }
+  }
+  const checksum = (crc ^ 0xffffffff) >>> 0
+
+  // FNV-1a 32-bit, folded into the 1..0xfffffffe zig accepts.
+  let fnv = 0x811c9dc5
+  for (let i = 0; i < name.length; i++) {
+    fnv ^= name.charCodeAt(i) & 0xff
+    fnv = Math.imul(fnv, 0x01000193) >>> 0
+  }
+  const id = (fnv % 0xfffffffd) + 1
+
+  const hex = (n: number) => n.toString(16).padStart(8, '0')
+  return `0x${hex(checksum)}${hex(id)}`
 }
 
 
@@ -142,5 +190,6 @@ export {
   clean,
   formatZigValue,
   zigModuleName,
+  zigPackageFingerprint,
   zigVarName,
 }

package/project/.sdk/tm/c/Makefile

@@ -5,6 +5,10 @@
 CC ?= gcc
 CFLAGS ?= -std=c11 -Wall -Wextra -Wno-unused-parameter -D_GNU_SOURCE -O0 -g
 INC := -I core -I utility/struct
+# The vendored omni test runner (tests/vendor/omni) is TEST-ONLY: it is
+# reachable from tests/ alone, never from LIB_SRCS, so it cannot enter the
+# shipped libsdk.a. That is why it lives under tests/ and not utility/.
+OMNI_INC := -I tests -I tests/vendor/omni
 LDLIBS := -lm
 
 # feature/*/*.c: a feature may carry a vendored library payload in its own
@@ -15,9 +19,14 @@ LDLIBS := -lm
 LIB_SRCS := $(wildcard core/*.c utility/*.c utility/struct/*.c feature/*.c feature/*/*.c entity/*.c)
 LIB_OBJS := $(LIB_SRCS:.c=.o)
 
+# Single-level on purpose: the vendored omni sources under
+# tests/vendor/omni have no main() and must not become test binaries.
 TEST_SRCS := $(wildcard tests/*.c)
 TEST_BINS := $(TEST_SRCS:.c=.out)
 
+OMNI_SRCS := $(wildcard tests/vendor/omni/*.c)
+OMNI_OBJS := $(OMNI_SRCS:.c=.o)
+
 .PHONY: all build test clean publish
 
 all: build
@@ -30,15 +39,40 @@ build: libsdk.a
 libsdk.a: $(LIB_OBJS)
 	ar rcs $@ $(LIB_OBJS)
 
+# omni's util.c includes <regex.h>. CFLAGS is `?=`, so an operator override
+# can drop the -D_GNU_SOURCE that exposes it; -D_POSIX_C_SOURCE is the
+# minimum omni itself compiles under (its own test/run.c sets exactly this).
+# _DARWIN_C_SOURCE is needed BESIDE it, not instead of it: on Darwin,
+# defining _POSIX_C_SOURCE alone LOWERS __DARWIN_C_LEVEL and hides regex_t,
+# so the same flag that exposes the header on glibc hides it on macOS. Each
+# platform ignores the other's macro.
+tests/vendor/omni/%.o: tests/vendor/omni/%.c
+	$(CC) $(CFLAGS) -D_POSIX_C_SOURCE=200809L -D_DARWIN_C_SOURCE -c $< -o $@
+
+libomni.a: $(OMNI_OBJS)
+	ar rcs $@ $(OMNI_OBJS)
+
+# Only the corpus drivers and the smoke test reach for omni, and the generic
+# rule must stay free of it: omni's util.c needs POSIX <regex.h>, which
+# Windows does not have at all. Linking it into EVERY test binary broke the
+# auth-null probe the generator's own suite builds on windows and macos,
+# neither of which runs a corpus.
+OMNI_TESTS := tests/struct_corpus_test.out tests/primary_corpus_test.out \
+  tests/omni_smoke_test.out
+
+$(OMNI_TESTS): tests/%.out: tests/%.c libsdk.a libomni.a
+	$(CC) $(CFLAGS) $(INC) $(OMNI_INC) $< libsdk.a libomni.a -o $@ $(LDLIBS)
+
 tests/%.out: tests/%.c libsdk.a
 	$(CC) $(CFLAGS) $(INC) $< libsdk.a -o $@ $(LDLIBS)
 
 # Build and run every test; aggregate pass/fail.
-test: libsdk.a
+test: libsdk.a libomni.a
 	@fail=0; total=0; \
 	for src in $(TEST_SRCS); do \
 	  bin=$${src%.c}.out; \
-	  $(CC) $(CFLAGS) $(INC) $$src libsdk.a -o $$bin $(LDLIBS) || { echo "BUILD FAIL: $$src"; fail=1; continue; }; \
+	  case " $(OMNI_TESTS) " in *" $$bin "*) omni="libomni.a"; oinc="$(OMNI_INC)";; *) omni=""; oinc="";; esac; \
+	  $(CC) $(CFLAGS) $(INC) $$oinc $$src libsdk.a $$omni -o $$bin $(LDLIBS) || { echo "BUILD FAIL: $$src"; fail=1; continue; }; \
 	  total=$$((total+1)); \
 	  if ./$$bin; then :; else echo "TEST FAIL: $$bin"; fail=1; fi; \
 	done; \
@@ -47,7 +81,8 @@ test: libsdk.a
 	exit $$fail
 
 clean:
-	rm -f $(LIB_OBJS) libsdk.a $(TEST_BINS) tests/*.out corpus-scoreboard.json
+	rm -f $(LIB_OBJS) libsdk.a $(OMNI_OBJS) libomni.a $(TEST_BINS) tests/*.out \
+	  corpus-scoreboard.json
 
 # C has no central registry — publishing IS the git tag.
 VERSION := $(shell cat VERSION 2>/dev/null || echo 0.0.1)

package/project/.sdk/tm/c/tests/omni_resolver.h

@@ -0,0 +1,361 @@
+/* The corpus test runner: vendored @voxgig/omni driven through its NATIVE
+ * API (omni_make_runner / omni_runner_run / omni_runsetflags, see
+ * tests/vendor/omni/omni.h), adapted to the subject shapes the corpus
+ * drivers already use. No compat shim is vendored: the adapter below IS
+ * the whole bridge, per language, per the vendor-tag rollout
+ * (docs/design/vendor-tag-rollout.md, Decision 4). It supersedes the whole
+ * of the retired tests/runner.h - both its engine half (run_subject) and
+ * its support half (normalize / deep_equal / brief / null_substitute,
+ * subsumed by omni_deepequal / omni_matchval / omni_stringify).
+ *
+ * C-specific decisions, each load-bearing:
+ *
+ * 1. TWO VALUE MODELS, ONE BIDIRECTIONAL BRIDGE. Every other migrated
+ *    target shares one value model with its omni port and needs only a
+ *    sentinel swap. C does not: omni carries its OWN arena-allocated model
+ *    (omni_json + omni_pool, tests/vendor/omni/json.c) while the SDK uses
+ *    the refcounted voxgig_value of utility/struct. So omnivx_tovx and
+ *    omnivx_tomni below convert whole values in both directions, and the
+ *    ownership rule is the SDK's own (core/sdk.h): omni values are
+ *    pool-owned and freed in one go by omni_pool_free; voxgig values the
+ *    bridge creates for a subject are released after the call, and values
+ *    the SDK pipeline builds are never released at all.
+ *
+ * 2. "NO ARGUMENT" AND "NULL" ARE NATIVELY DISTINCT. The corpus carries
+ *    entries with no `in`, `args` or `ctx`, meaning "call the subject with
+ *    NO argument". The vendored C port already distinguishes that case:
+ *    omni_map_get on a missing key answers a value of type OMNI_ABSENT,
+ *    omni_clone preserves it, and such an entry arrives as one OMNI_ABSENT
+ *    argument. So C needs neither go's novalargs spec rewrite nor a compat
+ *    shim - the ONE conversion is the sentinel swap at the call boundary:
+ *    OMNI_ABSENT -> voxgig_new_undef() inbound, VOXGIG_VAL_UNDEF ->
+ *    omni_absent() outbound, walked, because getpath can leave an undef
+ *    inside a partially-resolved node.
+ *
+ * 3. THE ARGUMENT IS WRITTEN BACK. `struct.minor.setpath` asserts
+ *    `match: {args: {0: {store: ...}}}` - that the subject mutated the
+ *    container it was handed - and `struct.merge.integrity` asserts the
+ *    opposite for merge. The bridge hands the subject a fresh voxgig copy,
+ *    so after the call omnivx_writeback rewrites the CONTENTS of the omni
+ *    argument node in place (its identity is preserved, because the runner
+ *    also stores it as `entry.ctx`). The retired runner.h could not check
+ *    either assertion: it ignored `match` entirely.
+ *
+ * 4. NUMBERS ARE RE-TYPED ON THE WAY IN. voxgig distinguishes integer from
+ *    decimal (minor.typify / minor.typename assert on it) while omni_json
+ *    holds one double. The bridge classifies an integral finite double as
+ *    VOXGIG_VAL_INT, which is exactly what voxgig_parse_json_file did for
+ *    a literal with no '.' and no exponent - and the shared corpus holds
+ *    no integral-valued decimal literal, so the two readings agree case
+ *    for case.
+ *
+ * 5. VALUES OMNI CANNOT EXPRESS ARE RENDERED AS voxgig's OWN JSON FORM.
+ *    VAL_FUNC (injector/modify) and the SKIP/DELETE sentinels have no omni
+ *    type. Rather than let them read as "absent", the bridge renders them
+ *    the way voxgig_jsonify does - a function as null, a sentinel as
+ *    {"`$NAME`": true} - so an assertion that meets one sees the same text
+ *    it would have seen through stringify.
+ *
+ * 6. NO EXCEPTIONS, SO NO OmniError. omni_runset returns non-zero and sets
+ *    *errout to a pool-owned message; a subject reports failure by setting
+ *    its `char **err` out-param, which the bridge copies into
+ *    omni_result.err. This is the one documented parity exemption for the
+ *    C port (tests/vendor/omni README, c:55-56).
+ *
+ * 7. omni#54 GAP 1 IS PRESENT in the vendored C port: omni_jsonstr has no
+ *    cycle guard. Mitigation is java's: typed SDK state is kept OUT of the
+ *    entries (a corpus subject builds its typed Context at the call site
+ *    and publishes only plain data back), and the bridge carries its own
+ *    depth bound, OMNIVX_MAXDEPTH, so a cyclic value becomes a marker
+ *    string instead of a hang.
+ *
+ * Header-only; every helper is `static` + unused-safe, so a test binary
+ * may include it and use only part of it.
+ */
+
+#ifndef PROJECTNAME_OMNI_RESOLVER_H
+#define PROJECTNAME_OMNI_RESOLVER_H
+
+#include "vendor/omni/omni.h"
+#include "voxgig_struct.h"
+
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define OMNIVX __attribute__((unused)) static
+
+/* Deeper than any corpus value; a cyclic one is cut here rather than
+ * followed (decision 7). */
+#define OMNIVX_MAXDEPTH 64
+#define OMNIVX_DEPTHMARK "__DEPTH__"
+
+/* ---- value bridge: omni -> voxgig ---------------------------------- */
+
+OMNIVX int omnivx_isintegral(double num) {
+  /* The range test keeps the (int64_t) cast defined; outside it the value
+   * can only have come from a decimal literal anyway. */
+  return isfinite(num) && floor(num) == num && -9.0e18 <= num && num <= 9.0e18;
+}
+
+OMNIVX voxgig_value* omnivx_tovx_at(const omni_json* val, int depth);
+
+OMNIVX voxgig_value* omnivx_tovx(const omni_json* val) { return omnivx_tovx_at(val, 0); }
+
+OMNIVX voxgig_value* omnivx_tovx_at(const omni_json* val, int depth) {
+  size_t at;
+
+  if (NULL == val) {
+    return voxgig_new_undef();
+  }
+  if (OMNIVX_MAXDEPTH < depth) {
+    return voxgig_new_string(OMNIVX_DEPTHMARK);
+  }
+
+  switch (val->type) {
+  case OMNI_ABSENT:
+    return voxgig_new_undef();
+  case OMNI_NULL:
+    return voxgig_new_null();
+  case OMNI_BOOL:
+    return voxgig_new_bool(0 != val->boolval);
+  case OMNI_NUM:
+    return omnivx_isintegral(val->numval) ? voxgig_new_int((int64_t)val->numval)
+                                          : voxgig_new_double(val->numval);
+  case OMNI_STR:
+    return voxgig_new_string(NULL == val->strval ? "" : val->strval);
+  case OMNI_LIST: {
+    voxgig_value* out = voxgig_new_list();
+    for (at = 0; at < val->listlen; at++) {
+      voxgig_list_push(voxgig_as_list(out), omnivx_tovx_at(val->list[at], depth + 1));
+    }
+    return out;
+  }
+  case OMNI_MAP: {
+    voxgig_value* out = voxgig_new_map();
+    for (at = 0; at < val->maplen; at++) {
+      voxgig_map_set(voxgig_as_map(out), val->keys[at], omnivx_tovx_at(val->vals[at], depth + 1));
+    }
+    return out;
+  }
+  }
+
+  return voxgig_new_undef();
+}
+
+/* ---- value bridge: voxgig -> omni ---------------------------------- */
+
+OMNIVX omni_json* omnivx_tomni_at(omni_pool* pool, voxgig_value* val, int depth);
+
+OMNIVX omni_json* omnivx_tomni(omni_pool* pool, voxgig_value* val) {
+  return omnivx_tomni_at(pool, val, 0);
+}
+
+OMNIVX omni_json* omnivx_tomni_at(omni_pool* pool, voxgig_value* val, int depth) {
+  size_t at;
+
+  if (NULL == val) {
+    return omni_absent(pool);
+  }
+  if (OMNIVX_MAXDEPTH < depth) {
+    return omni_str(pool, OMNIVX_DEPTHMARK);
+  }
+
+  switch (val->kind) {
+  case VOXGIG_VAL_UNDEF:
+    return omni_absent(pool);
+  case VOXGIG_VAL_NULL:
+    return omni_null(pool);
+  case VOXGIG_VAL_BOOL:
+    return omni_bool(pool, voxgig_as_bool(val) ? 1 : 0);
+  case VOXGIG_VAL_INT:
+    return omni_num(pool, (double)voxgig_as_int(val));
+  case VOXGIG_VAL_DOUBLE:
+    return omni_num(pool, voxgig_as_double(val));
+  case VOXGIG_VAL_STRING: {
+    const char* str = voxgig_as_string(val);
+    return omni_str(pool, NULL == str ? "" : str);
+  }
+  case VOXGIG_VAL_LIST: {
+    voxgig_list* list = voxgig_as_list(val);
+    omni_json* out = omni_list(pool);
+    for (at = 0; at < list->len; at++) {
+      omni_list_push(out, omnivx_tomni_at(pool, list->items[at], depth + 1));
+    }
+    return out;
+  }
+  case VOXGIG_VAL_MAP: {
+    voxgig_map* map = voxgig_as_map(val);
+    omni_json* out = omni_map(pool);
+    for (at = 0; at < map->len; at++) {
+      omni_map_set(out, map->entries[at].key,
+                   omnivx_tomni_at(pool, map->entries[at].value, depth + 1));
+    }
+    return out;
+  }
+  case VOXGIG_VAL_FUNC:
+    /* voxgig_jsonify renders a callable as null; so does the bridge. */
+    return omni_null(pool);
+  case VOXGIG_VAL_SENTINEL: {
+    /* voxgig_jsonify renders a sentinel as {"`$NAME`": true}. */
+    const voxgig_sentinel* sent = voxgig_as_sentinel(val);
+    omni_json* out = omni_map(pool);
+    char key[64];
+    snprintf(key, sizeof(key), "`$%s`", (NULL != sent && NULL != sent->name) ? sent->name : "?");
+    omni_map_set(out, key, omni_bool(pool, 1));
+    return out;
+  }
+  }
+
+  return omni_absent(pool);
+}
+
+/* ---- argument write-back (decision 3) ------------------------------ */
+
+/* Rewrite the CONTENTS of `dst` from `src`, keeping dst's identity: the
+ * runner stored that very node as the entry's `args[0]` and `ctx`, and a
+ * `match` assertion reads through it. Containers only - a scalar argument
+ * cannot be mutated by the subject in a way the corpus can observe. */
+OMNIVX void omnivx_writeback(omni_pool* pool, omni_json* dst, voxgig_value* src) {
+  size_t at;
+
+  if (NULL == dst || NULL == src) {
+    return;
+  }
+
+  if (OMNI_MAP == dst->type && voxgig_is_map(src)) {
+    voxgig_map* map = voxgig_as_map(src);
+    dst->maplen = 0;
+    for (at = 0; at < map->len; at++) {
+      omni_map_set(dst, map->entries[at].key, omnivx_tomni_at(pool, map->entries[at].value, 1));
+    }
+    return;
+  }
+
+  if (OMNI_LIST == dst->type && voxgig_is_list(src)) {
+    voxgig_list* list = voxgig_as_list(src);
+    dst->listlen = 0;
+    for (at = 0; at < list->len; at++) {
+      omni_list_push(dst, omnivx_tomni_at(pool, list->items[at], 1));
+    }
+    return;
+  }
+}
+
+/* ---- subjects ------------------------------------------------------ */
+
+/* The struct-corpus subject shape: one value in, one value out, with an
+ * optional error message. Unchanged from the retired runner.h, so every
+ * corpus subject in tests/struct_corpus_test.c crossed over verbatim. */
+typedef voxgig_value* (*omnivx_subject_fn)(voxgig_value* in, char** err, void* ud);
+
+typedef struct omnivx_holder {
+  omni_subject sub; /* FIRST: `sub.data` points back at the holder */
+  omni_pool* pool;
+  omnivx_subject_fn fn;
+  void* ud;
+} omnivx_holder;
+
+OMNIVX omni_result omnivx_call(omni_subject* self, omni_json** args, size_t nargs) {
+  omnivx_holder* holder = (omnivx_holder*)self->data;
+  omni_result out;
+  voxgig_value* in;
+  voxgig_value* got;
+  char* err = NULL;
+
+  out.val = NULL;
+  out.err = NULL;
+
+  /* nargs is 1 with an OMNI_ABSENT argument for a no-argument entry
+   * (decision 2); nargs is 0 only for an explicit `args: []`. */
+  in = 0 < nargs ? omnivx_tovx(args[0]) : voxgig_new_undef();
+
+  got = holder->fn(in, &err, holder->ud);
+
+  if (0 < nargs) {
+    omnivx_writeback(holder->pool, args[0], in);
+  }
+
+  if (NULL != err) {
+    out.err = omni_pool_strdup(holder->pool, err);
+    free(err);
+  } else {
+    out.val = omnivx_tomni(holder->pool, got);
+  }
+
+  voxgig_release(got);
+  voxgig_release(in);
+
+  return out;
+}
+
+OMNIVX omni_subject* omnivx_subject(omni_pool* pool, omnivx_subject_fn fn, void* ud) {
+  omnivx_holder* holder = (omnivx_holder*)omni_pool_alloc(pool, sizeof(omnivx_holder));
+  holder->sub.call = omnivx_call;
+  holder->sub.data = holder;
+  holder->pool = pool;
+  holder->fn = fn;
+  holder->ud = ud;
+  return &holder->sub;
+}
+
+/* The raw subject shape: omni values straight through. The primary corpus
+ * uses it because its entries assert on `ctx`, which the subject must
+ * publish back into the very omni map the runner handed it (java's
+ * decision 1: contexts stay MAPS across the runner, and the typed Context
+ * is built and synced at the call site). */
+typedef omni_result (*omnivx_raw_fn)(omni_pool* pool, omni_json** args, size_t nargs, void* ud);
+
+typedef struct omnivx_rawholder {
+  omni_subject sub; /* FIRST */
+  omni_pool* pool;
+  omnivx_raw_fn fn;
+  void* ud;
+} omnivx_rawholder;
+
+OMNIVX omni_result omnivx_rawcall(omni_subject* self, omni_json** args, size_t nargs) {
+  omnivx_rawholder* holder = (omnivx_rawholder*)self->data;
+  return holder->fn(holder->pool, args, nargs, holder->ud);
+}
+
+OMNIVX omni_subject* omnivx_rawsubject(omni_pool* pool, omnivx_raw_fn fn, void* ud) {
+  omnivx_rawholder* holder = (omnivx_rawholder*)omni_pool_alloc(pool, sizeof(omnivx_rawholder));
+  holder->sub.call = omnivx_rawcall;
+  holder->sub.data = holder;
+  holder->pool = pool;
+  holder->fn = fn;
+  holder->ud = ud;
+  return &holder->sub;
+}
+
+/* ---- spec helpers -------------------------------------------------- */
+
+/* How many entries a resolved test spec holds. Zero for a spec that is
+ * absent, or that carries no `set` list - which the corpus drivers report
+ * as a FAILURE, because a section that runs no case proves nothing. */
+OMNIVX size_t omnivx_setsize(const omni_json* testspec) {
+  const omni_json* set = omni_map_get(testspec, "set");
+  return omni_islist(set) ? set->listlen : 0;
+}
+
+/* Wrap a bare {in, out} node - `struct.merge.basic` and
+ * `struct.inject.basic` are authored that way, with no `set` - as a
+ * one-entry set the runner can drive. Without this they scored 0/0 and
+ * asserted nothing. */
+OMNIVX omni_json* omnivx_oneset(omni_pool* pool, omni_json* entry) {
+  omni_json* spec = omni_map(pool);
+  omni_json* set = omni_list(pool);
+  omni_list_push(set, entry);
+  omni_map_set(spec, "set", set);
+  return spec;
+}
+
+/* omni's flags, with the failure-message label filled in. */
+OMNIVX omni_flags omnivx_flags(int donull, const char* name) {
+  omni_flags flags = donull ? omni_flags_default() : omni_flags_nonull();
+  flags.name = name;
+  return flags;
+}
+
+#endif /* PROJECTNAME_OMNI_RESOLVER_H */