@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/tm/lean/test/TFeature.lean

@@ -0,0 +1,268 @@
+/- ProjectName SDK feature test.
+
+   Verifies the feature catalog's OBSERVABLE behaviour. Each feature records
+   into the client's `track` bucket under its own name, so a test activates a
+   feature, runs an operation against the offline (test-mode) transport, and
+   asserts the bucket. Features that wrap the transport are additionally
+   checked for the effect they have on the request or the result. -/
+
+import VoxgigStruct
+import SdkJson
+import SdkUtility
+import SdkFeature
+import SdkFeatures
+import SdkClient
+
+open VoxgigStruct
+
+initialize npass : IO.Ref Nat ← IO.mkRef 0
+initialize nfail : IO.Ref Nat ← IO.mkRef 0
+
+def pass (msg : String) : SIO Unit := do
+  npass.modify (· + 1)
+  IO.println s!"ok   - {msg}"
+
+def fail (msg : String) : SIO Unit := do
+  nfail.modify (· + 1)
+  IO.println s!"FAIL - {msg}"
+
+def check (cond : Bool) (msg : String) : SIO Unit := do
+  if cond then pass msg else fail msg
+
+def gp := SdkUtility.gp
+def gpS := SdkUtility.gpS
+
+def numAt (v : Value) (k : String) : SIO Float := do
+  match (← gp v k) with
+  | .num n => pure n
+  | _ => pure 0.0
+
+/-- A test-mode client with the named features activated. -/
+def clientWith (seed : Value) (feats : Array (String × Value)) : SIO Value := do
+  let fmap ← emptyMap
+  for (n, o) in feats do
+    SdkUtility.sp fmap n o
+  let opts ← emptyMap
+  SdkUtility.sp opts "feature" fmap
+  Sdk.testSdk seed opts
+
+def onOpts (extra : Array (String × Value)) : SIO Value := do
+  let o ← newMap #[("active", .bool true)]
+  for (k, v) in extra do
+    SdkUtility.sp o k v
+  pure o
+
+/-- The bucket a feature records into. -/
+def bucketOf (client : Value) (name : String) : SIO Value := do
+  gp (← gp client "track") name
+
+/-- The first entity that has a `list` op AND generated seed data: the feature
+    suite is entity-agnostic, so it discovers its subject from the config. -/
+def findSubject : SIO (Option (String × Value)) := do
+  let config ← SdkJson.jsonRead SdkConfig.configJson
+  let ents ← gp config "entity"
+  for name in (← keysof ents) do
+    let e ← gp ents name
+    let hasList ← (match (← gp (← gp e "op") "list") with
+      | .map _ => pure true
+      | _ => pure false)
+    if hasList then
+      let Name := name.capitalize
+      let seedPath := "../.sdk/test/entity/" ++ name ++ "/" ++ Name ++ "TestData.json"
+      if ← System.FilePath.pathExists seedPath then
+        let seed ← SdkJson.jsonRead (← IO.FS.readFile seedPath)
+        return some (name, seed)
+  pure none
+
+def main : IO UInt32 := do
+  let sctx ← mkCtx
+  let go : SIO Unit := do
+    match (← findSubject) with
+    | none => IO.println "skip - no entity with list op and seed data"
+    | some (ent, seed) => do
+    let mt ← emptyMap
+
+    -- log: counts requests
+    (do
+      let c ← clientWith seed #[("log", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "log"
+      check ((← numAt b "calls") == 1.0) "log: counts one request")
+
+    -- metrics: totals and a per-op bucket
+    (do
+      let c ← clientWith seed #[("metrics", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "metrics"
+      let total ← gp b "total"
+      check ((← numAt total "count") == 2.0) "metrics: counts two operations"
+      check ((← numAt total "ok") == 2.0) "metrics: both recorded ok"
+      let ops ← gp b "ops"
+      check ((← keysof ops).size >= 1) "metrics: per-op bucket created")
+
+    -- telemetry: one span per operation, closed out
+    (do
+      let c ← clientWith seed #[("telemetry", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "telemetry"
+      let spans ← gp b "spans"
+      let n ← (match spans with | .list i => do pure (← listItems i).size | _ => pure 0)
+      check (n == 1) "telemetry: records one span"
+      check ((← numAt b "active") == 0.0) "telemetry: span closed (active back to 0)")
+
+    -- audit: one record per operation
+    (do
+      let c ← clientWith seed #[("audit", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "audit"
+      let recs ← gp b "records"
+      let n ← (match recs with | .list i => do pure (← listItems i).size | _ => pure 0)
+      check (n == 1) "audit: records one operation")
+
+    -- debug: an entry, with sensitive headers redacted
+    (do
+      let c ← clientWith seed #[("debug", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "debug"
+      let entries ← gp b "entries"
+      match entries with
+      | .list i => do
+        let its ← listItems i
+        check (its.size == 1) "debug: records one entry"
+        if its.size > 0 then do
+          let e := its[0]!
+          check ((← gpS e "op") != "") "debug: entry names the operation"
+      | _ => fail "debug: no entries list")
+
+    -- idempotency: injects a key header on mutating ops only
+    (do
+      let c ← clientWith seed #[("idempotency", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b0 ← bucketOf c "idempotency"
+      check ((← numAt b0 "issued") == 0.0) "idempotency: no key for a read op"
+      let d ← newMap #[("name", .str "idem")]
+      let _ ← SdkRuntime.opCreate c ent d mt
+      let b ← bucketOf c "idempotency"
+      check ((← numAt b "issued") == 1.0) "idempotency: issues a key for create"
+      check ((← gpS b "last") != "") "idempotency: records the issued key")
+
+    -- clienttrack: request/session headers and a request count
+    (do
+      let c ← clientWith seed #[("clienttrack", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "clienttrack"
+      check ((← numAt b "requests") == 1.0) "clienttrack: counts the request"
+      check ((← gpS b "session") != "") "clienttrack: assigns a session id"
+      check ((← gpS b "lastRequestId") != "") "clienttrack: assigns a request id")
+
+    -- rbac: denies when the required permission is absent, allows when granted
+    (do
+      let rules ← newMap #[("list", .str "read")]
+      let c ← clientWith seed #[("rbac", ← onOpts #[("rules", rules)])]
+      let denied ← (try
+          let _ ← SdkRuntime.opList c ent mt mt
+          pure false
+        catch _ => pure true)
+      check denied "rbac: denies an operation without the permission"
+      let b ← bucketOf c "rbac"
+      check ((← numAt b "denied") == 1.0) "rbac: records the denial")
+    (do
+      let rules ← newMap #[("list", .str "read")]
+      let perms ← newList #[.str "read"]
+      let c ← clientWith seed #[("rbac", ← onOpts #[("rules", rules), ("perms", perms)])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "rbac"
+      check ((← numAt b "allowed") == 1.0) "rbac: allows when the permission is granted")
+
+    -- cache: second identical read is served from the cache
+    (do
+      let c ← clientWith seed #[("cache", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "cache"
+      check ((← numAt b "miss") == 1.0) "cache: first read is a miss"
+      check ((← numAt b "hit") == 1.0) "cache: second read is a hit")
+
+    -- ratelimit: a tight burst throttles
+    (do
+      let c ← clientWith seed #[("ratelimit", ← onOpts #[("rate", .num 1.0), ("burst", .num 1.0)])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "ratelimit"
+      check ((← numAt b "throttled") >= 1.0) "ratelimit: throttles the second call")
+
+    -- netsim: offline simulation fails the request
+    (do
+      let c ← clientWith seed #[("netsim", ← onOpts #[("offline", .bool true)])]
+      let failed ← (try
+          let _ ← SdkRuntime.opList c ent mt mt
+          pure false
+        catch _ => pure true)
+      check failed "netsim: offline simulation fails the request"
+      let b ← bucketOf c "netsim"
+      check ((← numAt b "calls") == 1.0) "netsim: records the simulated call")
+
+    -- netsim: failStatus is surfaced as the response status
+    (do
+      let c ← clientWith seed #[("netsim", ← onOpts #[("failStatus", .num 503.0)])]
+      let _ ← (try
+          let _ ← SdkRuntime.opList c ent mt mt
+          pure ()
+        catch _ => pure ())
+      let b ← bucketOf c "netsim"
+      check ((← numAt b "calls") == 1.0) "netsim: failStatus simulation runs")
+
+    -- proxy: annotates the transport and records the route
+    (do
+      let c ← clientWith seed #[("proxy", ← onOpts #[("url", .str "http://proxy.local:8080")])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "proxy"
+      check ((← numAt b "routed") == 1.0) "proxy: routes the request"
+      check ((← gpS b "url") == "http://proxy.local:8080") "proxy: records the proxy url")
+
+    -- timeout: a generous budget does not trip
+    (do
+      let c ← clientWith seed #[("timeout", ← onOpts #[("ms", .num 30000.0)])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      pass "timeout: request within budget succeeds")
+
+    -- retry: a healthy transport is not retried
+    (do
+      let c ← clientWith seed #[("retry", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "retry"
+      check ((← numAt b "attempts") == 0.0) "retry: no retry on a healthy response")
+
+    -- paging: annotates the query and counts items
+    (do
+      let c ← clientWith seed #[("paging", ← onOpts #[("size", .num 2.0)])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "paging"
+      check ((← numAt b "pages") == 1.0) "paging: counts the page"
+      check ((← numAt b "items") >= 1.0) "paging: counts the returned items")
+
+    -- streaming: reports the emitted items
+    (do
+      let c ← clientWith seed #[("streaming", ← onOpts #[])]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "streaming"
+      check ((← numAt b "emitted") >= 1.0) "streaming: emits the list items"
+      check ((← numAt b "chunks") == 1.0) "streaming: reports one chunk")
+
+    -- an inactive feature records nothing
+    (do
+      let off ← newMap #[("active", .bool false)]
+      let c ← clientWith seed #[("log", off)]
+      let _ ← SdkRuntime.opList c ent mt mt
+      let b ← bucketOf c "log"
+      match b with
+      | .map _ => fail "inactive feature must not record"
+      | _ => pass "inactive feature records nothing")
+
+  go.run sctx
+  let p ← npass.get
+  let f ← nfail.get
+  IO.println ""
+  IO.println s!"feature: PASS {p}  FAIL {f}"
+  if f > 0 then return 1 else return 0

package/project/.sdk/tm/lean/test/TPrimaryUtility.lean

@@ -0,0 +1,349 @@
+/- ProjectName SDK primary utility test.
+
+   Drives the SHARED language-neutral corpus (.sdk/test/test.json, section
+   `primary`) — the same fixtures every other target executes — so this suite
+   cannot drift from the reference implementation. Each section is looked up
+   with `getSpec` and executed with `runset`, as the ts/js reference harness
+   does. -/
+
+import VoxgigStruct
+import Vregex
+import SdkJson
+import SdkUtility
+import SdkConfig
+
+open VoxgigStruct
+
+initialize npass : IO.Ref Nat ← IO.mkRef 0
+initialize nfail : IO.Ref Nat ← IO.mkRef 0
+initialize failures : IO.Ref (Array String) ← IO.mkRef #[]
+
+def pass : SIO Unit := do npass.modify (· + 1)
+
+def fail (msg : String) : SIO Unit := do
+  nfail.modify (· + 1)
+  failures.modify (·.push msg)
+
+-- ---------------------------------------------------------------------------
+-- corpus navigation
+-- ---------------------------------------------------------------------------
+
+/-- Navigate into the nested corpus map by keys. -/
+def getSpec (root : Value) (path : Array String) : SIO Value := do
+  let mut cur := root
+  for k in path do
+    cur ← SdkUtility.gp cur k
+  pure cur
+
+def itemsOf (v : Value) : SIO (Array Value) := do
+  match v with
+  | .list i => listItems i
+  | _ => pure #[]
+
+def argAt (args : Value) (i : Nat) : SIO Value := do
+  pure ((← itemsOf args)[i]?.getD .noval)
+
+-- ---------------------------------------------------------------------------
+-- comparison
+-- ---------------------------------------------------------------------------
+
+/-- Deep structural equality; an empty list and an empty map are equivalent. -/
+partial def deepEq (a b : Value) : SIO Bool := do
+  match a, b with
+  | .map ia, .map ib => do
+    let ka ← keysof (.map ia)
+    let kb ← keysof (.map ib)
+    if ka.size != kb.size then pure false
+    else do
+      let mut ok := true
+      for k in ka do
+        let va ← SdkUtility.gp (.map ia) k
+        let vb ← SdkUtility.gp (.map ib) k
+        if !(← deepEq va vb) then ok := false
+      pure ok
+  | .list ia, .list ib => do
+    let la ← listItems ia
+    let lb ← listItems ib
+    if la.size != lb.size then pure false
+    else do
+      let mut ok := true
+      for i in [0:la.size] do
+        if !(← deepEq (la[i]!) (lb[i]!)) then ok := false
+      pure ok
+  | .map ia, .list ib => do
+    pure ((← keysof (.map ia)).isEmpty && (← listItems ib).isEmpty)
+  | .list ia, .map ib => do
+    pure ((← listItems ia).isEmpty && (← keysof (.map ib)).isEmpty)
+  | x, y => pure (x == y)
+
+/-- A corpus string check: `/re/` is a regex, otherwise substring containment. -/
+def strCheck (checkStr subject : String) : Bool :=
+  if checkStr.length > 1 && checkStr.startsWith "/" && checkStr.endsWith "/" then
+    let inner := String.ofList (checkStr.toList.drop 1).dropLast
+    Vregex.testStr inner subject
+  else if checkStr == subject then true
+  else (subject.splitOn checkStr).length > 1
+
+/-- Partial deep match: every key present in `check` must hold in `base`. -/
+partial def matchDeep (check base : Value) (path : String) (errs : IO.Ref (Array String)) :
+    SIO Unit := do
+  match check with
+  | .map ic =>
+    for k in (← keysof (.map ic)) do
+      let cv ← SdkUtility.gp (.map ic) k
+      let bv ← SdkUtility.gp base k
+      matchDeep cv bv (if path == "" then k else path ++ "." ++ k) errs
+  | .list ic => do
+    let items ← listItems ic
+    let bitems ← itemsOf base
+    for i in [0:items.size] do
+      let bv := bitems[i]?.getD .noval
+      matchDeep (items[i]!) bv (path ++ "[" ++ toString i ++ "]") errs
+  | .str s =>
+    if s == "__EXISTS__" then
+      (if SdkUtility.isNov base then errs.modify (·.push (path ++ ": expected to exist")) else pure ())
+    else if s == "__UNDEF__" then
+      (if SdkUtility.isNov base then pure () else errs.modify (·.push (path ++ ": expected undefined")))
+    else do
+      let bs := SdkUtility.vs base
+      if strCheck s bs then pure ()
+      else errs.modify (·.push (path ++ ": want " ++ s ++ ", got " ++ bs))
+  | _ => do
+    if (← deepEq check base) then pure ()
+    else do
+      let cs ← stringify check
+      let bs ← stringify base
+      errs.modify (·.push (path ++ ": want " ++ cs ++ ", got " ++ bs))
+
+-- ---------------------------------------------------------------------------
+-- the runner
+-- ---------------------------------------------------------------------------
+
+abbrev Subject := Value → SIO (Value × Option Value)
+
+def runset (secname : String) (spec : Value) (subject : Subject) : SIO Unit := do
+  let entries ← itemsOf (← SdkUtility.gp spec "set")
+  for idx in [0:entries.size] do
+    let entry := entries[idx]!
+    let label := secname ++ "[" ++ toString idx ++ "]"
+    let errs ← IO.mkRef (#[] : Array String)
+    let (res, merr) ← subject entry
+    let expErr ← SdkUtility.gp entry "err"
+    let mspec ← SdkUtility.gp entry "match"
+    match merr with
+    | some e => do
+      let em ← SdkUtility.gpS e "message"
+      if SdkUtility.isNov expErr then fail (label ++ ": unexpected error: " ++ em)
+      else do
+        let ok := match expErr with
+          | .str s => strCheck s em
+          | .bool b => b
+          | _ => false
+        if !ok then fail (label ++ ": error mismatch: got " ++ em)
+        else do
+          if !(SdkUtility.isNov mspec) then do
+            let rm ← emptyMap
+            let emap ← newMap #[("message", .str em)]
+            SdkUtility.sp rm "err" emap
+            SdkUtility.sp rm "out" res
+            matchDeep mspec rm "" errs
+          let es ← errs.get
+          if es.isEmpty then pass else fail (label ++ ": " ++ String.intercalate "; " es.toList)
+    | none => do
+      if !(SdkUtility.isNov expErr) then fail (label ++ ": expected an error, got a result")
+      else do
+        if !(SdkUtility.isNov mspec) then do
+          let rm ← emptyMap
+          SdkUtility.sp rm "out" res
+          SdkUtility.sp rm "in" (← SdkUtility.gp entry "in")
+          SdkUtility.sp rm "ctx" (← SdkUtility.gp entry "ctx")
+          SdkUtility.sp rm "args" (← SdkUtility.gp entry "args")
+          matchDeep mspec rm "" errs
+        let expOut ← SdkUtility.gp entry "out"
+        if !(SdkUtility.isNov expOut) then
+          if !(← deepEq expOut res) then do
+            let rs ← stringify res
+            let os ← stringify expOut
+            errs.modify (·.push ("out: want " ++ os ++ ", got " ++ rs))
+        let es ← errs.get
+        if es.isEmpty then pass else fail (label ++ ": " ++ String.intercalate "; " es.toList)
+
+-- ---------------------------------------------------------------------------
+-- context construction
+-- ---------------------------------------------------------------------------
+
+/-- The entry's own `ctx` map (created and attached when absent), wired to the
+    client options/config so the utilities see them. -/
+def entryCtx (entry options config : Value) : SIO Value := do
+  let ctx ← match (← SdkUtility.gp entry "ctx") with
+    | .map i => pure (Value.map i)
+    | _ => do
+      let m ← emptyMap
+      SdkUtility.sp entry "ctx" m
+      pure m
+  SdkUtility.sp ctx "options" options
+  SdkUtility.sp ctx "config" config
+  pure ctx
+
+/-- A ctx from a bare map (args-style sections); published back onto the entry
+    as `ctx` so a `match: ctx:` assertion sees the mutated context. -/
+def mapCtx (entry v options config : Value) : SIO Value := do
+  let ctx ← match v with
+    | .map i => pure (Value.map i)
+    | _ => emptyMap
+  SdkUtility.sp ctx "options" options
+  SdkUtility.sp ctx "config" config
+  SdkUtility.sp entry "ctx" ctx
+  pure ctx
+
+-- ---------------------------------------------------------------------------
+-- main
+-- ---------------------------------------------------------------------------
+
+def specPaths : Array String :=
+  #["../.sdk/test/test.json", ".sdk/test/test.json", "test/test.json"]
+
+def readSpecFile : IO String := do
+  match (← IO.getEnv "SDK_TEST_SPEC") with
+  | some p => IO.FS.readFile p
+  | none => do
+    for p in specPaths do
+      if ← System.FilePath.pathExists p then
+        return (← IO.FS.readFile p)
+    throw (IO.userError "cannot find .sdk/test/test.json (set SDK_TEST_SPEC)")
+
+def main : IO UInt32 := do
+  let raw ← readSpecFile
+  let sctx ← mkCtx
+  let go : SIO Unit := do
+    let root ← SdkJson.jsonRead raw
+    let primary ← SdkUtility.gp root "primary"
+    let config ← SdkJson.jsonRead SdkConfig.configJson
+    let opts ← SdkUtility.makeOptions config (← emptyMap)
+
+    runset "done" (← getSpec primary #["done", "basic"]) fun entry => do
+      SdkUtility.done (← entryCtx entry opts config)
+
+    runset "makeContext" (← getSpec primary #["makeContext", "basic"]) fun entry => do
+      let ctx ← mapCtx entry (← SdkUtility.gp entry "in") opts config
+      pure ((← SdkUtility.makeContext ctx), none)
+
+    runset "makeError" (← getSpec primary #["makeError", "basic"]) fun entry => do
+      let args ← SdkUtility.gp entry "args"
+      let ctx ← mapCtx entry (← argAt args 0) opts config
+      pure (.noval, some (← SdkUtility.makeError ctx (← argAt args 1)))
+
+    runset "makeOptions" (← getSpec primary #["makeOptions", "basic"]) fun entry => do
+      let inv ← SdkUtility.gp entry "in"
+      pure ((← SdkUtility.makeOptions (← SdkUtility.gp inv "config") (← SdkUtility.gp inv "options")), none)
+
+    runset "makeRequest" (← getSpec primary #["makeRequest", "basic"]) fun entry => do
+      SdkUtility.makeRequest (← entryCtx entry opts config)
+
+    runset "makeResponse" (← getSpec primary #["makeResponse", "basic"]) fun entry => do
+      SdkUtility.makeResponse (← entryCtx entry opts config)
+
+    let specOpts ← SdkUtility.makeOptions config (← getSpec primary #["makeSpec", "DEF", "setup", "a"])
+    runset "makeSpec" (← getSpec primary #["makeSpec", "basic"]) fun entry => do
+      SdkUtility.makeSpec (← entryCtx entry specOpts config)
+
+    runset "makeUrl" (← getSpec primary #["makeUrl", "basic"]) fun entry => do
+      SdkUtility.makeUrl (← entryCtx entry opts config)
+
+    runset "operator" (← getSpec primary #["operator", "basic"]) fun entry => do
+      pure ((← SdkUtility.operator (← SdkUtility.gp entry "in")), none)
+
+    runset "param" (← getSpec primary #["param", "basic"]) fun entry => do
+      let args ← SdkUtility.gp entry "args"
+      let ctx ← mapCtx entry (← argAt args 0) opts config
+      pure ((← SdkUtility.param ctx (← argAt args 1)), none)
+
+    let authOpts ← SdkUtility.makeOptions config (← getSpec primary #["prepareAuth", "DEF", "setup", "a"])
+    runset "prepareAuth" (← getSpec primary #["prepareAuth", "basic"]) fun entry => do
+      SdkUtility.prepareAuth (← entryCtx entry authOpts config)
+
+    runset "prepareBody" (← getSpec primary #["prepareBody", "basic"]) fun entry => do
+      pure ((← SdkUtility.prepareBody (← entryCtx entry opts config)), none)
+
+    runset "prepareHeaders" (← getSpec primary #["prepareHeaders", "basic"]) fun entry => do
+      pure ((← SdkUtility.prepareHeaders (← entryCtx entry opts config)), none)
+
+    runset "prepareMethod" (← getSpec primary #["prepareMethod", "basic"]) fun entry => do
+      let m ← SdkUtility.prepareMethod (← entryCtx entry opts config)
+      pure (.str m, none)
+
+    runset "prepareParams" (← getSpec primary #["prepareParams", "basic"]) fun entry => do
+      pure ((← SdkUtility.prepareParams (← entryCtx entry opts config)), none)
+
+    runset "preparePath" (← getSpec primary #["preparePath", "basic"]) fun entry => do
+      let p ← SdkUtility.preparePath (← entryCtx entry opts config)
+      pure (.str p, none)
+
+    runset "prepareQuery" (← getSpec primary #["prepareQuery", "basic"]) fun entry => do
+      pure ((← SdkUtility.prepareQuery (← entryCtx entry opts config)), none)
+
+    runset "resultBasic" (← getSpec primary #["resultBasic", "basic"]) fun entry => do
+      let ctx ← entryCtx entry opts config
+      SdkUtility.resultBasic ctx
+      pure ((← SdkUtility.gp ctx "result"), none)
+
+    runset "resultBody" (← getSpec primary #["resultBody", "basic"]) fun entry => do
+      let ctx ← entryCtx entry opts config
+      SdkUtility.resultBody ctx
+      pure ((← SdkUtility.gp ctx "result"), none)
+
+    runset "resultHeaders" (← getSpec primary #["resultHeaders", "basic"]) fun entry => do
+      let ctx ← entryCtx entry opts config
+      SdkUtility.resultHeaders ctx
+      pure ((← SdkUtility.gp ctx "result"), none)
+
+    runset "transformRequest" (← getSpec primary #["transformRequest", "basic"]) fun entry => do
+      pure ((← SdkUtility.transformRequest (← entryCtx entry opts config)), none)
+
+    runset "transformResponse" (← getSpec primary #["transformResponse", "basic"]) fun entry => do
+      pure ((← SdkUtility.transformResponse (← entryCtx entry opts config)), none)
+
+    -- The remaining corpus sections. They carry no cases in this project's
+    -- corpus, but are driven here so any future fixture runs against Lean too.
+
+    runset "clean" (← getSpec primary #["clean", "basic"]) fun entry => do
+      let ctx ← entryCtx entry opts config
+      pure ((← SdkUtility.clean ctx (← SdkUtility.gp entry "in")), none)
+
+    runset "makeResult" (← getSpec primary #["makeResult", "basic"]) fun entry => do
+      pure ((← SdkUtility.makeResult (← entryCtx entry opts config)), none)
+
+    runset "makePoint" (← getSpec primary #["makePoint", "basic"]) fun entry => do
+      pure ((← SdkUtility.makePoint (← entryCtx entry opts config)), none)
+
+    runset "makeFetchDef" (← getSpec primary #["makeFetchDef", "basic"]) fun entry => do
+      pure ((← SdkUtility.makeFetchDef (← entryCtx entry opts config)), none)
+
+    runset "fetcher" (← getSpec primary #["fetcher", "basic"]) fun entry => do
+      let ctx ← entryCtx entry opts config
+      let url ← SdkUtility.gpS entry "url"
+      pure ((← SdkUtility.fetcher ctx url (← SdkUtility.gp entry "fetchdef")), none)
+
+    runset "featureAdd" (← getSpec primary #["featureAdd", "basic"]) fun entry => do
+      let client ← emptyMap
+      SdkUtility.featureAdd client (← SdkUtility.gp entry "in")
+      pure ((← SdkUtility.gp client "features"), none)
+
+    runset "featureInit" (← getSpec primary #["featureInit", "basic"]) fun entry => do
+      let client ← emptyMap
+      SdkUtility.featureInit client (← entryCtx entry opts config)
+      pure ((← SdkUtility.gp client "features"), none)
+
+    runset "featureHook" (← getSpec primary #["featureHook", "basic"]) fun entry => do
+      let client ← emptyMap
+      SdkUtility.featureHook client (← SdkUtility.gpS entry "stage") (← entryCtx entry opts config)
+      pure ((← SdkUtility.gp client "features"), none)
+
+  go.run sctx
+  for f in (← failures.get) do
+    IO.println ("FAIL - " ++ f)
+  let p ← npass.get
+  let f ← nfail.get
+  IO.println ""
+  IO.println s!"primary-utility: PASS {p}  FAIL {f}"
+  if f > 0 then return 1 else return 0

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

@@ -1052,14 +1052,16 @@ describe("PrimaryUtility", function()
 
 
   it("preparePath-basic", function()
-    local ctx = make_test_full_ctx(client, utility)
-    ctx.point = {
-      parts = { "api", "planet", "{id}" },
-      args = { params = {} },
-    }
-
-    local path = utility.prepare_path(ctx)
-    assert.are.equal("api/planet/{id}", path)
+    -- Was hand-written cases that had drifted out of the shared corpus
+    -- (the preparePath fixture shipped as an empty `set: []`).
+    runset(get_spec(primary, "preparePath", "basic"), function(entry)
+      local ctxmap = entry["ctx"]
+      if type(ctxmap) ~= "table" then
+        ctxmap = {}
+      end
+      local ctx = make_ctx_from_map(ctxmap, client, utility)
+      return utility.prepare_path(ctx), nil
+    end)
   end)
 
 

package/project/.sdk/tm/ocaml/Makefile

@@ -23,11 +23,15 @@ SDK = $(RUNTIME) sdk_config.ml $(ENTITIES) sdk_client.ml sdk_error.ml
 
 ENTITY_TESTS = $(sort $(wildcard test/*_entity_test.ml) $(wildcard test/*_direct_test.ml))
 
+# Doc-example structural gate (present only when the readme phase generated it).
+# Wildcard so an absent file is simply skipped, never a missing-target error.
+DOC_TESTS = $(sort $(wildcard test/readme_examples_test.ml))
+
 # Fixed test order: harness deps first, generated/behaviour tests, summary last.
 SDK_TEST = $(RUNTIME) sdk_config.ml $(ENTITIES) sdk_client.ml sdk_error.ml \
   test/testutil.ml test/harness.ml \
   test/t_pipeline.ml test/t_feature.ml test/custom_utility.ml \
-  $(ENTITY_TESTS) test/t_main.ml
+  $(ENTITY_TESTS) $(DOC_TESTS) test/t_main.ml
 
 CORPUS_SRC = utility/vregex.ml utility/voxgig_struct.ml test/struct_corpus.ml