@voxgig/sdkgen 1.3.17 → 1.3.18

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

@@ -1,6 +1,7 @@
 package sdktest
 
 import (
+	"fmt"
 	"strings"
 	"testing"
 
@@ -119,7 +120,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("done-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "done", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "done", getSpec(primary, "done", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			fixctx(ctx, client)
@@ -128,7 +129,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("makeError-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "makeError", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "makeError", getSpec(primary, "makeError", "basic"), func(entry map[string]any) (any, error) {
 			args, _ := entry["args"].([]any)
 			if len(args) == 0 {
 				args = []any{map[string]any{}}
@@ -306,7 +307,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("makeContext-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "makeContext", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "makeContext", getSpec(primary, "makeContext", "basic"), func(entry map[string]any) (any, error) {
 			in := entry["in"]
 			if inMap, ok := in.(map[string]any); ok {
 				ctx := utility.MakeContext(inMap, nil)
@@ -395,7 +396,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("makeOptions-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "makeOptions", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "makeOptions", getSpec(primary, "makeOptions", "basic"), func(entry map[string]any) (any, error) {
 			in, _ := entry["in"].(map[string]any)
 			ctx := utility.MakeContext(map[string]any{
 				"options": in["options"],
@@ -408,7 +409,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("makeRequest-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "makeRequest", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "makeRequest", getSpec(primary, "makeRequest", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			ctx.Options = client.OptionsMap()
@@ -432,7 +433,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("makeResponse-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "makeResponse", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "makeResponse", getSpec(primary, "makeResponse", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			fixctx(ctx, client)
@@ -521,7 +522,7 @@ func TestPrimaryUtility(t *testing.T) {
 		specClient := sdk.TestSDK(nil, setupOpts)
 		specUtility := specClient.GetUtility()
 
-		runset(t, getSpec(primary, "makeSpec", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "makeSpec", getSpec(primary, "makeSpec", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, specClient, specUtility)
 			ctx.Options = specClient.OptionsMap()
@@ -574,7 +575,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("makeUrl-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "makeUrl", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "makeUrl", getSpec(primary, "makeUrl", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			if ctx.Result == nil {
@@ -585,7 +586,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("operator-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "operator", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "operator", getSpec(primary, "operator", "basic"), func(entry map[string]any) (any, error) {
 			in, _ := entry["in"].(map[string]any)
 			op := sdk.NewOperation(in)
 			return map[string]any{
@@ -598,7 +599,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("param-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "param", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "param", getSpec(primary, "param", "basic"), func(entry map[string]any) (any, error) {
 			args, _ := entry["args"].([]any)
 			if len(args) < 2 {
 				return nil, nil
@@ -647,7 +648,7 @@ func TestPrimaryUtility(t *testing.T) {
 		authClient := sdk.TestSDK(nil, setupOpts)
 		authUtility := authClient.GetUtility()
 
-		runset(t, getSpec(primary, "prepareAuth", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "prepareAuth", getSpec(primary, "prepareAuth", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, authClient, authUtility)
 			fixctx(ctx, authClient)
@@ -670,7 +671,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("prepareBody-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "prepareBody", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "prepareBody", getSpec(primary, "prepareBody", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			fixctx(ctx, client)
@@ -679,7 +680,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("prepareHeaders-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "prepareHeaders", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "prepareHeaders", getSpec(primary, "prepareHeaders", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			return utility.PrepareHeaders(ctx), nil
@@ -687,7 +688,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("prepareMethod-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "prepareMethod", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "prepareMethod", getSpec(primary, "prepareMethod", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			return utility.PrepareMethod(ctx), nil
@@ -695,41 +696,39 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("prepareParams-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "prepareParams", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "prepareParams", getSpec(primary, "prepareParams", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			return utility.PrepareParams(ctx), nil
 		})
 	})
 
+	// Was two hand-written cases that had drifted out of the shared corpus
+	// (the preparePath fixture shipped as an empty `set: []`). Now driven by
+	// the corpus like every other section, so all ports assert the same
+	// separator/blank-segment behaviour.
 	t.Run("preparePath-basic", func(t *testing.T) {
-		ctx := makeTestFullCtx(client, utility)
-		ctx.Point = map[string]any{
-			"parts": []any{"api", "planet", "{id}"},
-			"args":  map[string]any{"params": []any{}},
-		}
-
-		path := utility.PreparePath(ctx)
-		if path != "api/planet/{id}" {
-			t.Errorf("expected api/planet/{id}, got %s", path)
-		}
+		runsetNamed(t, "preparePath", getSpec(primary, "preparePath", "basic"), func(entry map[string]any) (any, error) {
+			ctxmap, _ := entry["ctx"].(map[string]any)
+			ctx := makeCtxFromMap(ctxmap, client, utility)
+			return utility.PreparePath(ctx), nil
+		})
 	})
 
-	t.Run("preparePath-single", func(t *testing.T) {
-		ctx := makeTestFullCtx(client, utility)
-		ctx.Point = map[string]any{
-			"parts": []any{"items"},
-			"args":  map[string]any{"params": []any{}},
-		}
-
-		path := utility.PreparePath(ctx)
-		if path != "items" {
-			t.Errorf("expected items, got %s", path)
-		}
+	t.Run("clean-corpus", func(t *testing.T) {
+		runsetNamed(t, "clean", getSpec(primary, "clean", "basic"), func(entry map[string]any) (any, error) {
+			args, _ := entry["args"].([]any)
+			if 2 != len(args) {
+				return nil, fmt.Errorf("clean: expected 2 args, got %d", len(args))
+			}
+			ctxmap, _ := args[0].(map[string]any)
+			ctx := makeCtxFromMap(ctxmap, client, utility)
+			return utility.Clean(ctx, args[1]), nil
+		})
 	})
 
 	t.Run("prepareQuery-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "prepareQuery", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "prepareQuery", getSpec(primary, "prepareQuery", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			return utility.PrepareQuery(ctx), nil
@@ -737,7 +736,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("resultBasic-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "resultBasic", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "resultBasic", getSpec(primary, "resultBasic", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 			fixctx(ctx, client)
@@ -759,7 +758,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("resultBody-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "resultBody", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "resultBody", getSpec(primary, "resultBody", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 
@@ -778,7 +777,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("resultHeaders-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "resultHeaders", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "resultHeaders", getSpec(primary, "resultHeaders", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 
@@ -797,7 +796,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("transformRequest-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "transformRequest", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "transformRequest", getSpec(primary, "transformRequest", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 
@@ -816,7 +815,7 @@ func TestPrimaryUtility(t *testing.T) {
 	})
 
 	t.Run("transformResponse-basic", func(t *testing.T) {
-		runset(t, getSpec(primary, "transformResponse", "basic"), func(entry map[string]any) (any, error) {
+		runsetNamed(t, "transformResponse", getSpec(primary, "transformResponse", "basic"), func(entry map[string]any) (any, error) {
 			ctxmap, _ := entry["ctx"].(map[string]any)
 			ctx := makeCtxFromMap(ctxmap, client, utility)
 

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

@@ -215,11 +215,40 @@ func getSpec(spec map[string]any, keys ...string) map[string]any {
 
 type RunSubject func(entry map[string]any) (any, error)
 
+// PENDING sections are the ones deliberately left empty in the shared corpus
+// (.sdk/test/primary/<name>.aontu). Everything else MUST contribute cases.
+var pendingSections = map[string]bool{
+	"fetcher": true, "makeFetchDef": true, "makePoint": true, "makeResult": true,
+	"featureAdd": true, "featureHook": true, "featureInit": true,
+}
+
+// runset drives one section of the shared test corpus.
+//
+// It used to `return` silently when "set" was missing or not a list, so a
+// renamed section, a fixture that failed to compile, or an empty set reported
+// PASS while running zero assertions — the whole point of a shared oracle
+// lost without a single red test. Both conditions are now fatal, except for
+// the sections explicitly marked PENDING in the corpus.
 func runset(t *testing.T, testspec map[string]any, subject RunSubject) {
 	t.Helper()
+	runsetNamed(t, "", testspec, subject)
+}
+
+func runsetNamed(t *testing.T, name string, testspec map[string]any, subject RunSubject) {
+	t.Helper()
+
+	if testspec == nil {
+		t.Fatalf("test corpus section %q missing — check the name against .sdk/test/primary/", name)
+	}
+
 	set, ok := testspec["set"].([]any)
 	if !ok {
-		return
+		t.Fatalf("test corpus section %q has no `set` list — zero cases would run", name)
+	}
+
+	if 0 == len(set) && !pendingSections[name] {
+		t.Fatalf("test corpus section %q is EMPTY — zero cases would run; "+
+			"add cases, or mark the fixture PENDING in .sdk/test/primary/", name)
 	}
 
 	for i, e := range set {

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

@@ -717,32 +717,15 @@ public class PrimaryUtilityTest {
 
   @Test
   public void preparePathBasic() {
+    // Was two hand-written cases that had drifted out of the shared corpus
+    // (the preparePath fixture shipped as an empty `set: []`).
     ProjectNameSDK client = client();
     Utility utility = client.getUtility();
-    Context ctx = makeTestFullCtx(client, utility);
-    List<Object> parts = new ArrayList<>();
-    parts.add("api");
-    parts.add("planet");
-    parts.add("{id}");
-    ctx.point = fhMap(
-        "parts", parts,
-        "args", fhMap("params", new ArrayList<>()));
-
-    assertEquals("api/planet/{id}", utility.preparePath.apply(ctx));
-  }
-
-  @Test
-  public void preparePathSingle() {
-    ProjectNameSDK client = client();
-    Utility utility = client.getUtility();
-    Context ctx = makeTestFullCtx(client, utility);
-    List<Object> parts = new ArrayList<>();
-    parts.add("items");
-    ctx.point = fhMap(
-        "parts", parts,
-        "args", fhMap("params", new ArrayList<>()));
-
-    assertEquals("items", utility.preparePath.apply(ctx));
+    runset(getSpec(primary(), "preparePath", "basic"), (entry) -> {
+      Map<String, Object> ctxmap = Helpers.toMapAny(entry.get("ctx"));
+      Context ctx = makeCtxFromMap(ctxmap, client, utility);
+      return utility.preparePath.apply(ctx);
+    });
   }
 
   @Test

package/project/.sdk/tm/js/src/feature/test/TestFeature.js

@@ -49,12 +49,29 @@ class TestFeature extends BaseFeature {
       const delprop = struct.delprop
       const getdef = struct.getdef
 
+      // Shape the mock payload the way the real API would, so the op's
+      // response transform recovers the entity from it. A point carrying
+      // `transform.res: \`body.item\`` describes an API that answers
+      // `{item: {...}}`; handing back the bare entity means the transform
+      // unwraps a property that is not there and the caller gets undefined.
+      // The mock has to agree with the model, or it only ever simulates APIs
+      // whose responses happen to be unwrapped.
+      function envelope(data) {
+        const restf = getprop(getprop(ctx.point, 'transform', {}), 'res')
+        if (null == data || 'string' !== typeof restf) {
+          return data
+        }
+        const m = restf.match(/^`body\.([^`.]+)`$/)
+        return null == m ? data : { [m[1]]: data }
+      }
+
       function respond(status, data, res) {
+        const payload = envelope(data)
         const out = merge([
           {
             status,
             statusText: 'OK',
-            json: async () => data,
+            json: async () => payload,
             body: 'not-used',
           },
           getdef(res, {})

package/project/.sdk/tm/js/test/utility/PrimaryUtility.test.js

@@ -96,6 +96,14 @@ describe('PrimaryUtility', async () => {
   })
 
 
+  // preparePath shipped as an empty `set: []`, so no port drove it and several
+  // kept private hand-written cases instead. Corpus-driven like every other
+  // section now.
+  test('path-basic', async () => {
+    await runset(spec.preparePath.basic, utility.preparePath)
+  })
+
+
   test('body-basic', async () => {
     await runset(spec.prepareBody.basic, (ctx) => {
       fixctx(ctx)

package/project/.sdk/tm/kotlin/test/PrimaryUtilityTest.kt

@@ -694,28 +694,15 @@ class PrimaryUtilityTest {
 
   @Test
   fun preparePathBasic() {
+    // Was two hand-written cases that had drifted out of the shared corpus
+    // (the preparePath fixture shipped as an empty `set: []`).
     val client = client()
     val utility = client.getUtility()
-    val ctx = makeTestFullCtx(client, utility)
-    val parts = mutableListOf<Any?>()
-    parts.add("api")
-    parts.add("planet")
-    parts.add("{id}")
-    ctx.point = fhMap("parts", parts, "args", fhMap("params", mutableListOf<Any?>()))
-
-    assertEquals("api/planet/{id}", utility.preparePath(ctx))
-  }
-
-  @Test
-  fun preparePathSingle() {
-    val client = client()
-    val utility = client.getUtility()
-    val ctx = makeTestFullCtx(client, utility)
-    val parts = mutableListOf<Any?>()
-    parts.add("items")
-    ctx.point = fhMap("parts", parts, "args", fhMap("params", mutableListOf<Any?>()))
-
-    assertEquals("items", utility.preparePath(ctx))
+    runset(getSpec(primary(), "preparePath", "basic")) { entry ->
+      val ctxmap = Helpers.toMapAny(entry["ctx"])
+      val ctx = makeCtxFromMap(ctxmap, client, utility)
+      utility.preparePath(ctx)
+    }
   }
 
   @Test

package/project/.sdk/tm/lean/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 voxgig
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/project/.sdk/tm/lean/VERSION

@@ -0,0 +1 @@
+0.0.1

package/project/.sdk/tm/lean/src/SdkFeature.lean

@@ -0,0 +1,171 @@
+/- ProjectName SDK feature catalog.
+
+   A feature observes and modifies the operation pipeline in two ways:
+
+   - by WRAPPING THE TRANSPORT: `init` replaces the client's fetcher with one
+     that calls the previous fetcher (retry, timeout, ratelimit, cache, proxy,
+     netsim, test all do this), so features compose as a middleware chain in
+     add order;
+   - by HANDLING A HOOK: a pipeline stage (PrePoint, PreSpec, PreRequest,
+     PreResponse, PreResult, PreDone, PreUnexpected) dispatched to every active
+     feature.
+
+   Lean cannot put closures inside the struct `Value` model, so features and
+   fetchers live in module-level registries and the client `Value` carries their
+   indices. Timing uses the monotonic clock; where the donors use randomness we
+   use a deterministic counter, which keeps generated suites reproducible. -/
+
+import VoxgigStruct
+import SdkJson
+import SdkUtility
+
+open VoxgigStruct
+
+namespace SdkFeature
+
+/-- Transport: ctx -> url -> fetchdef -> (response, error). -/
+abbrev Fetcher := Value → String → Value → SIO (Value × Option Value)
+
+structure Feature where
+  name : String
+  version : String := "0.0.1"
+  /-- init ctx options -/
+  init : Value → Value → SIO Unit := fun _ _ => pure ()
+  /-- hook stage ctx -/
+  hook : String → Value → SIO Unit := fun _ _ => pure ()
+
+initialize featureReg : IO.Ref (Array Feature) ← IO.mkRef #[]
+initialize fetcherReg : IO.Ref (Array Fetcher) ← IO.mkRef #[]
+initialize seqRef : IO.Ref Nat ← IO.mkRef 0
+
+def nextSeq : SIO Nat := do seqRef.modifyGet fun n => (n + 1, n + 1)
+
+def nowMs : SIO Float := do pure (← IO.monoMsNow).toFloat
+
+def sleepMs (ms : Float) : SIO Unit := do
+  if ms > 0.0 then IO.sleep (ms.toUInt32) else pure ()
+
+/-- Deterministic id (no RNG: reproducible suites). -/
+def genId : SIO String := do pure ("k" ++ toString (← nextSeq))
+
+-- ---------------------------------------------------------------------------
+-- option readers
+-- ---------------------------------------------------------------------------
+
+def optActive (opts : Value) : SIO Bool := do
+  match (← SdkUtility.gp opts "active") with
+  | .bool b => pure b
+  | _ => pure false
+
+def optNum (opts : Value) (k : String) (d : Float) : SIO Float := do
+  match (← SdkUtility.gp opts k) with
+  | .num n => pure n
+  | _ => pure d
+
+def optInt (opts : Value) (k : String) (d : Int) : SIO Int := do
+  match (← SdkUtility.gp opts k) with
+  | .num n => pure (fToInt n)
+  | _ => pure d
+
+def optStr (opts : Value) (k d : String) : SIO String := do
+  let s ← SdkUtility.gpS opts k
+  pure (if s == "" then d else s)
+
+def optStrList (opts : Value) (k : String) (d : Array String) : SIO (Array String) := do
+  match (← SdkUtility.gp opts k) with
+  | .list i => do
+    let its ← listItems i
+    pure (its.map SdkUtility.vs)
+  | _ => pure d
+
+/-- The feature's own options map (the client passes `{active, ...}`). -/
+def toOptsMap (opts : Value) : SIO Value := do
+  match opts with
+  | .map i => pure (.map i)
+  | _ => emptyMap
+
+def upper (s : String) : String := s.toUpper
+def lower (s : String) : String := s.toLower
+
+/-- Case-insensitive header lookup. -/
+def headerCI (headers : Value) (name : String) : SIO Value := do
+  match headers with
+  | .map i => do
+    let want := lower name
+    for k in (← keysof (.map i)) do
+      if lower k == want then return (← SdkUtility.gp (.map i) k)
+    pure .noval
+  | _ => pure .noval
+
+-- ---------------------------------------------------------------------------
+-- client wiring: fetcher chain + tracking buckets
+-- ---------------------------------------------------------------------------
+
+def registerFetcher (f : Fetcher) : SIO Nat := do
+  fetcherReg.modifyGet fun a => (a.size, a.push f)
+
+def getFetcher (client : Value) : SIO Fetcher := do
+  match (← SdkUtility.gp client "fetcher") with
+  | .num n => do
+    let reg ← fetcherReg.get
+    pure (reg[fToInt n |>.toNat]!)
+  | _ => pure (fun _ _ _ => do pure (.noval, none))
+
+def setFetcher (client : Value) (f : Fetcher) : SIO Unit := do
+  let id ← registerFetcher f
+  SdkUtility.sp client "fetcher" (.num id.toFloat)
+
+/-- The client of a ctx. -/
+def clientOf (ctx : Value) : SIO Value := do SdkUtility.gp ctx "client"
+
+/-- A named metrics bucket on the client's `track` map. -/
+def trackBucket (client : Value) (name : String) (mk : SIO Value) : SIO Value := do
+  let track ← SdkUtility.gpMap client "track"
+  match (← SdkUtility.gp track name) with
+  | .map i => pure (.map i)
+  | _ => do
+    let b ← mk
+    SdkUtility.sp track name b
+    pure b
+
+def bumpNum (bucket : Value) (k : String) (n : Float) : SIO Unit := do
+  let cur ← SdkUtility.gp bucket k
+  let v := (match cur with | .num x => x | _ => 0.0) + n
+  SdkUtility.sp bucket k (.num v)
+
+def trackCtx (ctx : Value) (name : String) (mk : SIO Value) : SIO Value := do
+  trackBucket (← clientOf ctx) name mk
+
+-- ---------------------------------------------------------------------------
+-- feature registry / dispatch
+-- ---------------------------------------------------------------------------
+
+def registerFeature (f : Feature) : SIO Nat := do
+  featureReg.modifyGet fun a => (a.size, a.push f)
+
+def clientFeatures (client : Value) : SIO (Array (Nat × Feature)) := do
+  let reg ← featureReg.get
+  let mut out : Array (Nat × Feature) := #[]
+  match (← SdkUtility.gp client "features") with
+  | .list i =>
+    for fv in (← listItems i) do
+      match fv with
+      | .num n => do
+        let idx := fToInt n |>.toNat
+        if h : idx < reg.size then out := out.push (idx, reg[idx])
+      | _ => pure ()
+  | _ => pure ()
+  pure out
+
+/-- Is the named feature active on this client? -/
+def isActive (client : Value) (name : String) : SIO Bool := do
+  let fo ← SdkUtility.gp (← SdkUtility.gp client "featureopts") name
+  optActive fo
+
+/-- Dispatch a pipeline stage to every active feature. -/
+def dispatch (client : Value) (stage : String) (ctx : Value) : SIO Unit := do
+  for (_, f) in (← clientFeatures client) do
+    if (← isActive client f.name) then
+      f.hook stage ctx
+
+end SdkFeature