@voxgig/sdkgen 4.8.2 → 4.8.3

package/project/.sdk/tm/go/test/struct_utility_test.go

@@ -5,6 +5,7 @@
 package sdktest
 
 import (
+	"encoding/json"
 	"fmt"
 	"math"
 	"reflect"
@@ -58,11 +59,11 @@ func TestStructUtility(t *testing.T) {
 			"getelem": voxgigstruct.GetElem,
 			"getprop": voxgigstruct.GetProp,
 
-			"getpath":  voxgigstruct.GetPath,
-			"haskey":   voxgigstruct.HasKey,
-			"inject":   voxgigstruct.Inject,
-			"isempty":  voxgigstruct.IsEmpty,
-			"isfunc":   voxgigstruct.IsFunc,
+			"getpath": voxgigstruct.GetPath,
+			"haskey":  voxgigstruct.HasKey,
+			"inject":  voxgigstruct.Inject,
+			"isempty": voxgigstruct.IsEmpty,
+			"isfunc":  voxgigstruct.IsFunc,
 
 			"iskey":  voxgigstruct.IsKey,
 			"islist": voxgigstruct.IsList,
@@ -70,18 +71,18 @@ func TestStructUtility(t *testing.T) {
 			"isnode": voxgigstruct.IsNode,
 			"items":  voxgigstruct.Items,
 
-			"joinurl":   voxgigstruct.JoinUrl,
-			"jsonify":   voxgigstruct.Jsonify,
-			"keysof":    voxgigstruct.KeysOf,
-			"merge":     voxgigstruct.Merge,
-			"pad":       voxgigstruct.Pad,
-			"pathify":   voxgigstruct.Pathify,
+			"joinurl": voxgigstruct.JoinUrl,
+			"jsonify": voxgigstruct.Jsonify,
+			"keysof":  voxgigstruct.KeysOf,
+			"merge":   voxgigstruct.Merge,
+			"pad":     voxgigstruct.Pad,
+			"pathify": voxgigstruct.Pathify,
 
-			"select":    voxgigstruct.Select,
-			"setpath":   voxgigstruct.SetPath,
-			"size":      voxgigstruct.Size,
-			"slice":     voxgigstruct.Slice,
-			"setprop":   voxgigstruct.SetProp,
+			"select":  voxgigstruct.Select,
+			"setpath": voxgigstruct.SetPath,
+			"size":    voxgigstruct.Size,
+			"slice":   voxgigstruct.Slice,
+			"setprop": voxgigstruct.SetProp,
 
 			"strkey":    voxgigstruct.StrKey,
 			"stringify": voxgigstruct.Stringify,
@@ -349,6 +350,53 @@ func TestStructUtility(t *testing.T) {
 		structRunSet(t, minorSpec["keysof"], voxgigstruct.KeysOf)
 	})
 
+	// The struct.nullsem section: does a PRESENT key holding a JSON null
+	// read as "no value"? Opt-in per target (create-sdkgen ships it; an
+	// older project corpus may predate it - the skip below says so OUT
+	// LOUD rather than passing vacuously). All lanes run {null: false}.
+	t.Run("nullsem", func(t *testing.T) {
+		nullsemRaw, has := spec["nullsem"]
+		if !has {
+			t.Skip("corpus predates struct.nullsem - refresh .sdk/test/struct from create-sdkgen")
+		}
+		nullsemSpec := nullsemRaw.(map[string]any)
+
+		structRunSetFlags(t, nullsemSpec["getprop"], map[string]bool{"null": false},
+			func(v any) any {
+				m := v.(map[string]any)
+				alt, hasAlt := m["alt"]
+				if !hasAlt {
+					return voxgigstruct.GetProp(m["val"], m["key"])
+				}
+				return voxgigstruct.GetProp(m["val"], m["key"], alt)
+			})
+
+		structRunSetFlags(t, nullsemSpec["getelem"], map[string]bool{"null": false},
+			func(v any) any {
+				m := v.(map[string]any)
+				alt, hasAlt := m["alt"]
+				if !hasAlt {
+					return voxgigstruct.GetElem(m["val"], m["key"])
+				}
+				return voxgigstruct.GetElem(m["val"], m["key"], alt)
+			})
+
+		structRunSetFlags(t, nullsemSpec["getpath"], map[string]bool{"null": false},
+			func(v any) any {
+				m := v.(map[string]any)
+				return voxgigstruct.GetPath(m["store"], m["path"])
+			})
+
+		structRunSetFlags(t, nullsemSpec["haskey"], map[string]bool{"null": false},
+			func(v any) any {
+				m := v.(map[string]any)
+				return voxgigstruct.HasKey(m["src"], m["key"])
+			})
+
+		structRunSetFlags(t, nullsemSpec["keysof"], map[string]bool{"null": false},
+			voxgigstruct.KeysOf)
+	})
+
 	t.Run("minor-filter", func(t *testing.T) {
 		checkmap := map[string]func([2]any) bool{
 			"gt3": func(n [2]any) bool {
@@ -1457,3 +1505,262 @@ func IsSameFunc(target any, candidate any) bool {
 
 	return reflect.ValueOf(target).Pointer() == reflect.ValueOf(candidate).Pointer()
 }
+
+// ---------------------------------------------------------------------
+// Struct-corpus SUPPORT, retained from the retired struct_runner_test.go
+// (its engine half is superseded by the vendored omni runner driven
+// through omniresolver_test.go). The StructSDK below is the client the
+// runner wraps for the struct sections; NullModifier names struct's own
+// *voxgigstruct.Injection and so cannot live in the language-neutral
+// resolver; Fdt/ToJSONString are debug helpers, not runner API.
+
+type StructUtility struct {
+	IsNode     func(val any) bool
+	Clone      func(val any) any
+	CloneFlags func(val any, flags map[string]bool) any
+	GetPath    func(store any, path any, injdefs ...*voxgigstruct.Injection) any
+	Inject     func(val any, store any, injdefs ...*voxgigstruct.Injection) any
+	Items      func(val any) [][2]any
+	Stringify  func(val any, maxlen ...int) string
+	Walk       func(val any, apply voxgigstruct.WalkApply, opts ...any) any
+
+	DelProp   func(parent any, key any) any
+	EscRe     func(s string) string
+	EscUrl    func(s string) string
+	Filter    func(val any, check func([2]any) bool) []any
+	Flatten   func(list any, depths ...int) any
+	GetDef    func(val any, alt any) any
+	GetElem   func(val any, key any, alts ...any) any
+	GetProp   func(val any, key any, alts ...any) any
+	HasKey    func(val any, key any) bool
+	IsEmpty   func(val any) bool
+	IsFunc    func(val any) bool
+	IsKey     func(val any) bool
+	IsList    func(val any) bool
+	IsMap     func(val any) bool
+	Join      func(arr []any, args ...any) string
+	Jsonify   func(val any, flags ...map[string]any) string
+	KeysOf    func(val any) []string
+	Merge     func(val any, maxdepths ...int) any
+	Pad       func(str any, args ...any) string
+	Pathify   func(val any, from ...int) string
+	Select    func(children any, query any) []any
+	SetPath   func(store any, path any, val any, injdefs ...map[string]any) any
+	SetProp   func(parent any, key any, newval any) any
+	Size      func(val any) int
+	Slice     func(val any, args ...any) any
+	StrKey    func(key any) string
+	Transform func(data any, spec any, injdefs ...*voxgigstruct.Injection) (any, error)
+	Typify    func(value any) int
+	Typename  func(t int) string
+	Validate  func(data any, spec any, injdefs ...*voxgigstruct.Injection) (any, error)
+
+	SKIP   any
+	DELETE any
+
+	Jm func(kv ...any) map[string]any
+	Jt func(v ...any) []any
+
+	CheckPlacement func(modes int, ijname string, parentTypes int, inj *voxgigstruct.Injection) bool
+	InjectorArgs   func(argTypes []int, args []any) []any
+	InjectChild    func(child any, store any, inj *voxgigstruct.Injection) *voxgigstruct.Injection
+}
+
+func NullModifier(
+	val any,
+	key any,
+	parent any,
+	inj *voxgigstruct.Injection,
+	store any,
+) {
+	switch v := val.(type) {
+	case string:
+		if NULLMARK == v {
+			_ = voxgigstruct.SetProp(parent, key, nil)
+		} else if UNDEFMARK == v {
+			_ = voxgigstruct.SetProp(parent, key, nil)
+		} else if EXISTSMARK == v {
+			// For EXISTSMARK, no transform needed
+		} else {
+			_ = voxgigstruct.SetProp(parent, key,
+				strings.ReplaceAll(v, NULLMARK, "null"))
+		}
+	}
+}
+
+func Fdt(data any) string {
+	return fdti(data, "")
+}
+
+func fdti(data any, indent string) string {
+	result := ""
+
+	switch v := data.(type) {
+	case map[string]any:
+		result += indent + "{\n"
+		for key, value := range v {
+			result += fmt.Sprintf("%s  \"%s\": %s", indent, key, fdti(value, indent+"  "))
+		}
+		result += indent + "}\n"
+
+	case []any:
+		result += indent + "[\n"
+		for _, value := range v {
+			result += fmt.Sprintf("%s  - %s", indent, fdti(value, indent+"  "))
+		}
+		result += indent + "]\n"
+
+	default:
+		result += fmt.Sprintf("%v (%s)\n", v, reflect.TypeOf(v))
+	}
+
+	return result
+}
+
+func ToJSONString(data any) string {
+	jsonBytes, err := json.Marshal(data)
+	if err != nil {
+		return ""
+	}
+	return string(jsonBytes)
+}
+
+// StructSDK is the test SDK client for the struct runner
+type StructSDK struct {
+	opts    map[string]any
+	utility *StructSDKUtility
+}
+
+// StructSDKUtility is the utility container the resolver reaches by
+// reflection (Struct / Contextify / Check).
+type StructSDKUtility struct {
+	sdk     *StructSDK
+	structu *StructUtility
+}
+
+// Struct returns the StructUtility
+func (u *StructSDKUtility) Struct() *StructUtility {
+	return u.structu
+}
+
+// Contextify implements the contextify function
+func (u *StructSDKUtility) Contextify(ctxmap map[string]any) map[string]any {
+	return ctxmap
+}
+
+// Check implements the check function
+func (u *StructSDKUtility) Check(ctx map[string]any) map[string]any {
+	zed := "ZED"
+	if u.sdk.opts != nil {
+		if foo, ok := u.sdk.opts["foo"]; ok && foo != nil {
+			zed += fmt.Sprint(foo)
+		}
+	}
+	zed += "_"
+
+	if ctx == nil {
+		zed += "0"
+	} else if meta, ok := ctx["meta"].(map[string]any); ok && meta != nil {
+		if bar, ok := meta["bar"]; ok && bar != nil {
+			zed += fmt.Sprint(bar)
+		} else {
+			zed += "0"
+		}
+	} else {
+		zed += "0"
+	}
+
+	return map[string]any{
+		"zed": zed,
+	}
+}
+
+// NewStructSDK creates a new StructSDK instance with the given options
+func NewStructSDK(opts map[string]any) *StructSDK {
+	if opts == nil {
+		opts = map[string]any{}
+	}
+
+	sdk := &StructSDK{
+		opts: opts,
+	}
+
+	// Create the StructUtility
+	structUtil := &StructUtility{
+		IsNode:     voxgigstruct.IsNode,
+		Clone:      voxgigstruct.Clone,
+		CloneFlags: voxgigstruct.CloneFlags,
+		GetPath:    voxgigstruct.GetPath,
+		Inject:     voxgigstruct.Inject,
+		Items:      voxgigstruct.Items,
+		Stringify:  voxgigstruct.Stringify,
+		Walk:       voxgigstruct.Walk,
+
+		DelProp:   voxgigstruct.DelProp,
+		EscRe:     voxgigstruct.EscRe,
+		EscUrl:    voxgigstruct.EscUrl,
+		Filter:    voxgigstruct.Filter,
+		Flatten:   voxgigstruct.Flatten,
+		GetDef:    voxgigstruct.GetDef,
+		GetElem:   voxgigstruct.GetElem,
+		GetProp:   voxgigstruct.GetProp,
+		HasKey:    voxgigstruct.HasKey,
+		IsEmpty:   voxgigstruct.IsEmpty,
+		IsFunc:    voxgigstruct.IsFunc,
+		IsKey:     voxgigstruct.IsKey,
+		IsList:    voxgigstruct.IsList,
+		IsMap:     voxgigstruct.IsMap,
+		Join:      voxgigstruct.Join,
+		Jsonify:   voxgigstruct.Jsonify,
+		KeysOf:    voxgigstruct.KeysOf,
+		Merge:     voxgigstruct.Merge,
+		Pad:       voxgigstruct.Pad,
+		Pathify:   voxgigstruct.Pathify,
+		Select:    voxgigstruct.Select,
+		SetPath:   voxgigstruct.SetPath,
+		SetProp:   voxgigstruct.SetProp,
+		Size:      voxgigstruct.Size,
+		Slice:     voxgigstruct.Slice,
+		StrKey:    voxgigstruct.StrKey,
+		Transform: voxgigstruct.Transform,
+		Typify:    voxgigstruct.Typify,
+		Typename:  voxgigstruct.Typename,
+		Validate:  voxgigstruct.Validate,
+
+		SKIP:   voxgigstruct.SKIP,
+		DELETE: voxgigstruct.DELETE,
+
+		Jm: voxgigstruct.Jm,
+		Jt: voxgigstruct.Jt,
+
+		CheckPlacement: voxgigstruct.CheckPlacement,
+		InjectorArgs:   voxgigstruct.InjectorArgs,
+		InjectChild:    voxgigstruct.InjectChild,
+	}
+
+	// Create the utility
+	sdk.utility = &StructSDKUtility{
+		sdk:     sdk,
+		structu: structUtil,
+	}
+
+	return sdk
+}
+
+// MakeTestStructSDK creates a new StructSDK instance for testing
+func MakeTestStructSDK(opts map[string]any) (*StructSDK, error) {
+	return NewStructSDK(opts), nil
+}
+
+// Tester creates a new StructSDK instance with options or default options
+func (s *StructSDK) Tester(opts map[string]any) (*StructSDK, error) {
+	if opts == nil {
+		opts = s.opts
+	}
+	return NewStructSDK(opts), nil
+}
+
+// Utility returns the utility object
+func (s *StructSDK) Utility() *StructSDKUtility {
+	return s.utility
+}

package/project/.sdk/tm/go/test/testsupport_test.go

@@ -0,0 +1,294 @@
+// SDK test SUPPORT: the helpers the generated entity/direct tests and the
+// corpus call sites share - env loading, the sdk-test-control.json skip and
+// pacing machinery, corpus access, and entity-data conversion.
+//
+// Split out of the retired runner_test.go (vendor-tag rollout: the corpus
+// ENGINE half of that file is superseded by the vendored omni runner driven
+// through the resolver in omniresolver_test.go; this support half is
+// retained). Same package, same names - the emitted call sites did not move.
+
+package sdktest
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"testing"
+
+	sdk "GOMODULE"
+)
+
+var envLocalOnce sync.Once
+
+func loadEnvLocal() {
+	envLocalOnce.Do(func() {
+		_, filename, _, _ := runtime.Caller(0)
+		dir := filepath.Dir(filename)
+		envFile := filepath.Join(dir, "..", "..", ".env.local")
+
+		data, err := os.ReadFile(envFile)
+		if err != nil {
+			return
+		}
+		for _, line := range strings.Split(string(data), "\n") {
+			line = strings.TrimSpace(line)
+			if line == "" || strings.HasPrefix(line, "#") {
+				continue
+			}
+			parts := strings.SplitN(line, "=", 2)
+			if len(parts) == 2 {
+				key := strings.TrimSpace(parts[0])
+				val := strings.TrimSpace(parts[1])
+				os.Setenv(key, val)
+			}
+		}
+	})
+}
+
+func envOverride(m map[string]any) map[string]any {
+	if os.Getenv("PROJECTENV_TEST_LIVE") == "TRUE" ||
+		os.Getenv("PROJECTENV_TEST_OVERRIDE") == "TRUE" {
+		for key := range m {
+			envval := os.Getenv(key)
+			if envval != "" {
+				envval = strings.TrimSpace(envval)
+				if strings.HasPrefix(envval, "{") {
+					var parsed any
+					if err := json.Unmarshal([]byte(envval), &parsed); err == nil {
+						m[key] = parsed
+						continue
+					}
+				}
+				m[key] = envval
+			}
+		}
+	}
+
+	if explain := os.Getenv("PROJECTENV_TEST_EXPLAIN"); explain != "" {
+		m["PROJECTENV_TEST_EXPLAIN"] = explain
+	}
+
+	return m
+}
+
+type entityTestSetup struct {
+	client        *sdk.ProjectNameSDK
+	data          map[string]any
+	idmap         map[string]any
+	env           map[string]any
+	explain       bool
+	live          bool
+	syntheticOnly bool
+	now           int64
+}
+
+var (
+	cachedTestControl     map[string]any
+	cachedTestControlOnce sync.Once
+)
+
+// loadTestControl reads sdk-test-control.json from this test dir; caches
+// after first read. Returns an empty-skip default if the file is missing
+// or invalid so tests never crash on a bad config.
+func loadTestControl() map[string]any {
+	cachedTestControlOnce.Do(func() {
+		_, filename, _, _ := runtime.Caller(0)
+		dir := filepath.Dir(filename)
+		ctrlPath := filepath.Join(dir, "sdk-test-control.json")
+		def := map[string]any{
+			"version": 1,
+			"test": map[string]any{"skip": map[string]any{
+				"live": map[string]any{"direct": []any{}, "entityOp": []any{}},
+				"unit": map[string]any{"direct": []any{}, "entityOp": []any{}},
+			}},
+		}
+		data, err := os.ReadFile(ctrlPath)
+		if err != nil {
+			cachedTestControl = def
+			return
+		}
+		var parsed map[string]any
+		if err := json.Unmarshal(data, &parsed); err != nil {
+			cachedTestControl = def
+			return
+		}
+		cachedTestControl = parsed
+	})
+	return cachedTestControl
+}
+
+// isControlSkipped checks sdk-test-control.json for a skip entry.
+// Returns (skip, reason).
+func isControlSkipped(kind, name, mode string) (bool, string) {
+	ctrl := loadTestControl()
+	test, _ := ctrl["test"].(map[string]any)
+	if test == nil {
+		return false, ""
+	}
+	skip, _ := test["skip"].(map[string]any)
+	if skip == nil {
+		return false, ""
+	}
+	modeMap, _ := skip[mode].(map[string]any)
+	if modeMap == nil {
+		return false, ""
+	}
+	items, _ := modeMap[kind].([]any)
+	for _, raw := range items {
+		item, _ := raw.(map[string]any)
+		if item == nil {
+			continue
+		}
+		reason, _ := item["reason"].(string)
+		if kind == "direct" {
+			if t, _ := item["test"].(string); t == name {
+				return true, reason
+			}
+		}
+		if kind == "entityOp" {
+			ent, _ := item["entity"].(string)
+			op, _ := item["op"].(string)
+			if ent+"."+op == name {
+				return true, reason
+			}
+		}
+	}
+	return false, ""
+}
+
+// liveDelayMs returns the configured per-test live delay in ms; default 500.
+// liveClientOptions returns the extra SDK options every LIVE client is
+// constructed with, from sdk-test-control.json `test.client.options`.
+//
+// The generated live client knows two things: the base URL (from the spec)
+// and the credential (from the environment). Everything else about how a
+// particular API wants to be talked to - which features to switch on, and
+// with what settings - is a property of THAT API, known to the project and
+// to nothing in the toolchain.
+//
+// Merged UNDER the generated fields, so the suite's own base/apikey/server
+// values win: this ADDS to the live client, it does not redirect it.
+//
+// That contract is enforced HERE rather than left to each merge site: the
+// generated map only names a field when the model calls for one, so a
+// "base" in this block would face no competing value and would silently
+// redirect the whole suite - credential included - to another host.
+var liveReserved = map[string]bool{
+	"base": true, "prefix": true, "suffix": true,
+	"server": true, "apikey": true, "secret": true,
+}
+
+func liveClientOptions() map[string]any {
+	ctrl := loadTestControl()
+	test, _ := ctrl["test"].(map[string]any)
+	if test == nil {
+		return map[string]any{}
+	}
+	client, _ := test["client"].(map[string]any)
+	if client == nil {
+		return map[string]any{}
+	}
+	opts, _ := client["options"].(map[string]any)
+	if opts == nil {
+		return map[string]any{}
+	}
+
+	out := map[string]any{}
+	for k, v := range opts {
+		if !liveReserved[k] {
+			out[k] = v
+		}
+	}
+	return out
+}
+
+func liveDelayMs() int {
+	ctrl := loadTestControl()
+	test, _ := ctrl["test"].(map[string]any)
+	if test == nil {
+		return 500
+	}
+	live, _ := test["live"].(map[string]any)
+	if live == nil {
+		return 500
+	}
+	switch v := live["delayMs"].(type) {
+	case float64:
+		if v >= 0 {
+			return int(v)
+		}
+	case int:
+		if v >= 0 {
+			return v
+		}
+	}
+	return 500
+}
+
+var cachedTestSpec map[string]any
+
+func loadTestSpec(t *testing.T) map[string]any {
+	t.Helper()
+	if cachedTestSpec != nil {
+		return cachedTestSpec
+	}
+	data, err := os.ReadFile("../../.sdk/test/test.json")
+	if err != nil {
+		t.Fatalf("Failed to load test.json: %v", err)
+	}
+	var spec map[string]any
+	if err := json.Unmarshal(data, &spec); err != nil {
+		t.Fatalf("Failed to parse test.json: %v", err)
+	}
+	cachedTestSpec = spec
+	return spec
+}
+
+func getSpec(spec map[string]any, keys ...string) map[string]any {
+	var cur any = spec
+	for _, key := range keys {
+		if m, ok := cur.(map[string]any); ok {
+			cur = m[key]
+		} else {
+			return nil
+		}
+	}
+	if m, ok := cur.(map[string]any); ok {
+		return m
+	}
+	return nil
+}
+
+// entityData extracts the data map from an op result.
+//
+// Every entity operation resolves to the ENTITY (see AGENTS.md), so a flow
+// test that wants the record takes this hop. A plain map passes through
+// unchanged, so this is safe for the direct/prepare results too.
+func entityData(v any) any {
+	if ent, ok := v.(sdk.Entity); ok {
+		return ent.Data()
+	}
+	return v
+}
+
+// entityListToData extracts data maps from a list of Entity objects.
+func entityListToData(list []any) []any {
+	var out []any
+	for _, item := range list {
+		if ent, ok := item.(sdk.Entity); ok {
+			d := ent.Data()
+			if dm, ok := d.(map[string]any); ok {
+				out = append(out, dm)
+			}
+		} else if m, ok := item.(map[string]any); ok {
+			out = append(out, m)
+		}
+	}
+	if out == nil {
+		out = []any{}
+	}
+	return out
+}

package/project/.sdk/tm/go/utility/make_options.go

@@ -122,7 +122,14 @@ func makeOptionsUtil(ctx *core.Context) map[string]any {
 			},
 		},
 		"utility": map[string]any{},
-		"system":  map[string]any{},
+		// Feature INSTANCES supplied at construction (the station adopt
+		// path): consumed by the constructor's featureAdd loop, so they
+		// are class instances, not data - `$ANY` accepts them verbatim.
+		// Without this entry the seam is dead: the constructor reads
+		// options.extend, but validate rejected the key (mirrors
+		// MakeOptionsUtility.ts).
+		"extend": "`$ANY`",
+		"system": map[string]any{},
 		"test": map[string]any{
 			"active": false,
 			"entity": map[string]any{

package/project/.sdk/tm/go/utility/prepare_method.go

@@ -30,5 +30,9 @@ func prepareMethodUtil(ctx *core.Context) string {
 	if m, ok := methodMap[opname]; ok {
 		return m
 	}
-	return "GET"
+
+	// An op the API does not define resolves NO method - ts answers
+	// undefined here, and "" is go's spelling of the same "no value"
+	// (the corpus pins this via primary.prepareMethod).
+	return ""
 }

package/project/.sdk/tm/go/utility/struct/voxgigstruct.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/struct 0.1.3 (go/voxgigstruct.go)
-// Source: https://github.com/voxgig/struct @ 94409354d0a60fda8098c83e290583b7dee76c84
+// VENDORED: @voxgig/struct 0.1.0 (go/voxgigstruct.go)
+// Source: https://github.com/voxgig/struct @ 2caf7f448f265144c18dd6fab6ba270a7f3bca07  [tag: sdk-20260904-1610-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* Copyright (c) 2025 Voxgig Ltd. MIT LICENSE. */