@voxgig/sdkgen 1.3.7 → 1.3.9

package/project/.sdk/tm/clojure/src/sdk/core.clj

@@ -0,0 +1,901 @@
+;; ProjectName SDK core runtime (generated by @voxgig/sdkgen).
+;;
+;; Clojure is functional with immutable values, but the operation pipeline is
+;; a shared-mutable-state machine: feature hooks observe and modify the
+;; context, result and control across pipeline stages, and transport-wrapping
+;; features replace the fetcher in place. That shared mutable state is modelled
+;; with atoms — the context and every mutable sub-object (control, spec,
+;; result, response, operation, the `out` short-circuit map, the utility
+;; object and the client) are atoms wrapping a map. The DATA those atoms carry
+;; (options, config, headers, request/response bodies, match/data) are struct
+;; value nodes (java.util.LinkedHashMap / ArrayList) built and manipulated by
+;; the vendored voxgig.struct library, exactly as the reference SDK uses
+;; mutable hashes/arrays.
+
+(ns sdk.core
+  (:require [voxgig.struct :as vs]
+            [clojure.string :as str]))
+
+(def SDK-NAME "ProjectName")
+
+;; ---------------------------------------------------------------------------
+;; Minimal JSON reader -> struct nodes (LinkedHashMap / ArrayList / Long /
+;; Double / String / Boolean / nil). Shared by the live transport and tests.
+;; ---------------------------------------------------------------------------
+
+(defn json-parse [^String s]
+  (let [n (count s) pos (int-array 1)]
+    (letfn [(peek-c [] (when (< (aget pos 0) n) (.charAt s (aget pos 0))))
+            (next-c [] (let [c (.charAt s (aget pos 0))] (aset pos 0 (inc (aget pos 0))) c))
+            (skip-ws [] (while (and (< (aget pos 0) n) (Character/isWhitespace (.charAt s (aget pos 0))))
+                          (aset pos 0 (inc (aget pos 0)))))
+            (parse-val []
+              (skip-ws)
+              (let [c (peek-c)]
+                (cond (= c \{) (parse-obj) (= c \[) (parse-arr) (= c \") (parse-str)
+                      (or (= c \t) (= c \f)) (parse-bool) (= c \n) (parse-null) :else (parse-num))))
+            (parse-obj []
+              (next-c)
+              (let [m (java.util.LinkedHashMap.)]
+                (skip-ws)
+                (if (= (peek-c) \}) (do (next-c) m)
+                    (loop [] (skip-ws)
+                      (let [k (parse-str)] (skip-ws) (next-c)
+                        (.put m k (parse-val)) (skip-ws)
+                        (if (= (next-c) \,) (recur) m))))))
+            (parse-arr []
+              (next-c)
+              (let [a (java.util.ArrayList.)]
+                (skip-ws)
+                (if (= (peek-c) \]) (do (next-c) a)
+                    (loop [] (.add a (parse-val)) (skip-ws)
+                      (if (= (next-c) \,) (recur) a)))))
+            (parse-str []
+              (next-c)
+              (let [sb (StringBuilder.)]
+                (loop []
+                  (let [c (next-c)]
+                    (cond
+                      (= c \") (.toString sb)
+                      (= c \\) (let [e (next-c)]
+                                 (case e
+                                   \" (.append sb \") \\ (.append sb \\) \/ (.append sb \/)
+                                   \n (.append sb \newline) \t (.append sb \tab) \r (.append sb \return)
+                                   \b (.append sb \backspace) \f (.append sb \formfeed)
+                                   \u (let [hex (subs s (aget pos 0) (+ (aget pos 0) 4))]
+                                        (aset pos 0 (+ (aget pos 0) 4))
+                                        (.append sb (char (Integer/parseInt hex 16))))
+                                   (.append sb e))
+                                 (recur))
+                      :else (do (.append sb c) (recur)))))))
+            (parse-bool []
+              (if (= (peek-c) \t) (do (aset pos 0 (+ (aget pos 0) 4)) true)
+                  (do (aset pos 0 (+ (aget pos 0) 5)) false)))
+            (parse-null [] (aset pos 0 (+ (aget pos 0) 4)) nil)
+            (parse-num []
+              (let [start (aget pos 0)]
+                (while (and (< (aget pos 0) n)
+                            (let [c (.charAt s (aget pos 0))]
+                              (or (Character/isDigit c) (= c \-) (= c \+) (= c \.) (= c \e) (= c \E))))
+                  (aset pos 0 (inc (aget pos 0))))
+                (let [tok (subs s start (aget pos 0))]
+                  (if (or (.contains tok ".") (.contains tok "e") (.contains tok "E"))
+                    (Double/parseDouble tok) (Long/parseLong tok)))))]
+      (parse-val))))
+
+;; ---------------------------------------------------------------------------
+;; Atom-object helpers. Every mutable "object" is an atom wrapping a map.
+;; ---------------------------------------------------------------------------
+
+(defn oget
+  ([a k] (get (deref a) k))
+  ([a k d] (let [v (get (deref a) k)] (if (nil? v) d v))))
+
+(defn oset! [a k v] (swap! a assoc k v) v)
+(defn oupd! [a k f & args] (swap! a (fn [m] (assoc m k (apply f (get m k) args)))))
+
+;; Read a value from a java.util.Map (both clojure maps and LinkedHashMap
+;; implement java.util.Map, so this is uniform for struct nodes and literals).
+(defn mget
+  ([m k] (when (instance? java.util.Map m) (.get ^java.util.Map m k)))
+  ([m k d] (let [v (mget m k)] (if (nil? v) d v))))
+
+(defn to-map [v] (when (vs/ismap v) v))
+(defn to-int [v] (if (number? v) (long v) -1))
+
+;; ---------------------------------------------------------------------------
+;; SDK error. Represented as a plain map flowing through [value err] tuples;
+;; raised (where the reference implementation raises) via ex-info carrying the
+;; error map under ::sdk-error.
+;; ---------------------------------------------------------------------------
+
+(defn make-error-obj
+  ([code msg] (make-error-obj code msg nil))
+  ([code msg ctx]
+   {:sdk-error true :sdk SDK-NAME :code (or code "") :msg (or msg "")
+    :ctx ctx :result nil :spec nil}))
+
+(defn sdk-error? [x] (and (map? x) (true? (:sdk-error x))))
+(defn err-msg [e] (cond (sdk-error? e) (:msg e) (instance? Throwable e) (.getMessage ^Throwable e) :else (str e)))
+(defn err-code [e] (when (sdk-error? e) (:code e)))
+(defn sdk-throw [e] (throw (ex-info (err-msg e) {::sdk-error (if (sdk-error? e) e (make-error-obj "" (str e)))})))
+(defn ex->sdk [t] (::sdk-error (ex-data t)))
+
+;; ctx.make_error(code, msg)
+(defn ctx-error [ctx code msg] (make-error-obj code msg ctx))
+
+;; ---------------------------------------------------------------------------
+;; Client accessors. A client is a plain map holding atoms (so it is shared by
+;; reference; the atoms carry the mutable slots).
+;; ---------------------------------------------------------------------------
+
+(defn client-mode [client] (deref (:mode client)))
+(defn client-set-mode! [client m] (reset! (:mode client) m))
+(defn client-features [client] (:features client)) ;; atom of vector
+(defn client-options-map [client]
+  (let [o (vs/clone (deref (:options client)))] (if (vs/ismap o) o (vs/jm))))
+(defn client-track [client k] (get (deref (:store client)) k))
+(defn client-track-set! [client k v] (swap! (:store client) assoc k v) v)
+(defn client-track-update! [client k f] (swap! (:store client) update k f))
+(defn client-root-ctx [client] (deref (:root-ctx client)))
+(defn client-utility [client] (:utility client))
+
+;; ---------------------------------------------------------------------------
+;; Utility object: an atom wrapping a map of pipeline functions plus :struct,
+;; :custom and the swappable :fetcher. Sibling functions are always looked up
+;; through the atom (uget) so a feature-wrapped fetcher or an overridden member
+;; is honoured.
+;; ---------------------------------------------------------------------------
+
+(declare base-utility-map)
+
+(defn make-utility []
+  (atom (assoc (base-utility-map) :struct (vs/struct-utility) :custom (vs/jm))))
+
+(defn utility-copy [u]
+  (let [m (deref u)]
+    (atom (assoc m :custom (let [c (:custom m)] (if (vs/ismap c) (vs/clone c) (vs/jm)))))))
+
+;; get_utility: entity clients operate through a private copy of the utility.
+(defn get-utility [client] (utility-copy (:utility client)))
+
+(defn uget [ctx k] (get (deref (oget ctx :utility)) k))
+(defn ucall [ctx k & args] (apply (uget ctx k) ctx args))
+
+;; ---------------------------------------------------------------------------
+;; Operation (atom-map): entity, name, input, points, alias.
+;; ---------------------------------------------------------------------------
+
+(defn make-operation [opmap]
+  (let [opmap (or opmap (vs/jm))
+        e (vs/getprop opmap "entity")
+        n (vs/getprop opmap "name")
+        i (vs/getprop opmap "input")
+        raw-points (vs/getprop opmap "points")
+        raw-alias (vs/getprop opmap "alias")]
+    (atom {:entity (if (and (string? e) (seq e)) e "_")
+           :name   (if (and (string? n) (seq n)) n "_")
+           :input  (if (and (string? i) (seq i)) i "_")
+           :points (cond (vs/islist raw-points)
+                         (let [a (vs/jt)] (doseq [t raw-points] (when (vs/ismap t) (.add ^java.util.List a t))) a)
+                         :else (vs/jt))
+           :alias  (when (vs/ismap raw-alias) raw-alias)})))
+
+(defn op-name [op] (when op (:name (deref op))))
+(defn op-entity [op] (when op (:entity (deref op))))
+(defn op-input [op] (when op (:input (deref op))))
+(defn op-points [op] (when op (:points (deref op))))
+(defn op-alias [op] (when op (:alias (deref op))))
+
+;; ---------------------------------------------------------------------------
+;; Spec (atom-map).
+;; ---------------------------------------------------------------------------
+
+(defn make-spec [specmap]
+  (let [m (or specmap (vs/jm))
+        g (fn [k d] (let [v (mget m k)] (if (nil? v) d v)))]
+    (atom {:parts   (g "parts" (vs/jt))
+           :headers (g "headers" (vs/jm))
+           :alias   (g "alias" (vs/jm))
+           :base    (g "base" "")
+           :prefix  (g "prefix" "")
+           :suffix  (g "suffix" "")
+           :params  (g "params" (vs/jm))
+           :query   (g "query" (vs/jm))
+           :step    (g "step" "start")
+           :method  (g "method" "GET")
+           :body    (g "body" nil)
+           :url     (g "url" "")
+           :path    (g "path" "")})))
+
+;; ---------------------------------------------------------------------------
+;; Result (atom-map).
+;; ---------------------------------------------------------------------------
+
+(defn make-result [resmap]
+  (let [m (or resmap (vs/jm))
+        g (fn [k] (mget m k))
+        s (g "status")
+        st (g "statusText")
+        h (g "headers")
+        rm (g "resmatch")]
+    (atom {:ok (= true (g "ok"))
+           :status (if (number? s) (long s) -1)
+           :status-text (if (string? st) st "")
+           :headers (if (vs/ismap h) h (vs/jm))
+           :body (g "body")
+           :err (g "err")
+           :resdata (g "resdata")
+           :resmatch (when (vs/ismap rm) rm)
+           :paging nil :streaming nil :stream nil})))
+
+;; ---------------------------------------------------------------------------
+;; Response (atom-map).
+;; ---------------------------------------------------------------------------
+
+(defn make-response [resmap]
+  (let [m (or resmap (vs/jm))
+        g (fn [k] (mget m k))
+        s (g "status")
+        st (g "statusText")
+        jf (g "json")]
+    (atom {:status (if (number? s) (long s) -1)
+           :status-text (if (string? st) st "")
+           :headers (g "headers")
+           :json (when (vs/isfunc jf) jf)
+           :body (g "body")
+           :err (g "err")})))
+
+;; ---------------------------------------------------------------------------
+;; Control (atom-map). Shared with the base context when not overridden.
+;; ---------------------------------------------------------------------------
+
+(defn make-control [] (atom {:throw nil :err nil :explain nil :actor nil :paging nil}))
+
+;; ---------------------------------------------------------------------------
+;; Context (atom-map).
+;; ---------------------------------------------------------------------------
+
+(declare resolve-op)
+
+(defn make-context [ctxmap basectx]
+  (let [ctxmap (or ctxmap (vs/jm))
+        bget (fn [k] (when basectx (oget basectx k)))
+        cprop (fn [k] (mget ctxmap k))
+        client (or (cprop "client") (bget :client))
+        utility (or (cprop "utility") (bget :utility))
+        ;; ctrl: explicit ctrl map -> fresh control; else share base ctrl.
+        ctrl-raw (cprop "ctrl")
+        ctrl (cond
+               (vs/ismap ctrl-raw)
+               (let [c (make-control)]
+                 (when (contains? (into #{} (vs/keysof ctrl-raw)) "throw") (oset! c :throw (mget ctrl-raw "throw")))
+                 (when (vs/ismap (mget ctrl-raw "explain")) (oset! c :explain (mget ctrl-raw "explain")))
+                 (when (contains? (into #{} (vs/keysof ctrl-raw)) "actor") (oset! c :actor (mget ctrl-raw "actor")))
+                 (when (vs/ismap (mget ctrl-raw "paging")) (oset! c :paging (mget ctrl-raw "paging")))
+                 c)
+               (bget :ctrl) (bget :ctrl)
+               :else (make-control))
+        meta (let [m (cprop "meta")] (if (vs/ismap m) m (or (bget :meta) (vs/jm))))
+        config (let [c (cprop "config")] (if (vs/ismap c) c (bget :config)))
+        entopts (let [e (cprop "entopts")] (if (vs/ismap e) e (bget :entopts)))
+        options (let [o (cprop "options")] (if (vs/ismap o) o (bget :options)))
+        entity (or (cprop "entity") (bget :entity))
+        shared (let [s (cprop "shared")] (if (vs/ismap s) s (bget :shared)))
+        opmap (or (cprop "opmap") (bget :opmap) (atom {}))
+        dmap (fn [k] (let [v (mget ctxmap k)] (if (vs/ismap v) v (vs/jm))))
+        point (let [p (cprop "point")] (if (vs/ismap p) p (bget :point)))
+        spec (let [s (cprop "spec")] (if (some? s) s (bget :spec)))
+        result (let [r (cprop "result")] (if (some? r) r (bget :result)))
+        response (let [r (cprop "response")] (if (some? r) r (bget :response)))
+        opname (or (cprop "opname") "")
+        ctx (atom {:id (str "C" (+ 10000000 (rand-int 89999999)))
+                   :out (atom (vs/jm))
+                   :client client :utility utility :ctrl ctrl :meta meta
+                   :config config :entopts entopts :options options :entity entity
+                   :shared shared :opmap opmap
+                   :data (dmap "data") :reqdata (dmap "reqdata")
+                   :match (dmap "match") :reqmatch (dmap "reqmatch")
+                   :point point :spec spec :result result :response response
+                   :op nil})]
+    (oset! ctx :op (resolve-op ctx opname))
+    ctx))
+
+(defn ctx-out [ctx] (oget ctx :out))
+(defn out-get [ctx k] (mget (deref (ctx-out ctx)) k))
+(defn out-set! [ctx k v] (.put ^java.util.Map (deref (ctx-out ctx)) k v))
+
+(defn resolve-op [ctx opname]
+  (let [entity (oget ctx :entity)
+        config (oget ctx :config)
+        opmap (oget ctx :opmap)
+        entname (if (and entity (:get-name entity)) ((:get-name entity)) "_")
+        cache-key (str entname ":" opname)]
+    (cond
+      (get (deref opmap) cache-key) (get (deref opmap) cache-key)
+      (or (nil? opname) (= "" opname)) (make-operation (vs/jm))
+      :else
+      (let [opcfg (vs/getpath config (str "entity." entname ".op." opname))
+            input (if (or (= opname "update") (= opname "create")) "data" "match")
+            points (let [t (when (vs/ismap opcfg) (vs/getprop opcfg "points"))]
+                     (if (vs/islist t) t (vs/jt)))
+            op (make-operation (vs/jm "entity" entname "name" opname "input" input "points" points))]
+        (swap! opmap assoc cache-key op)
+        op))))
+
+;; ---------------------------------------------------------------------------
+;; Feature dispatch.
+;; ---------------------------------------------------------------------------
+
+(defn feature-hook [ctx name]
+  (when-let [client (oget ctx :client)]
+    (when-let [feats (client-features client)]
+      (doseq [f (deref feats)]
+        (let [hf (get (deref f) name)]
+          (when (fn? hf) (hf ctx)))))))
+
+(defn feature-get-name [f] (:name (deref f)))
+(defn feature-get-active [f] (:active (deref f)))
+(defn feature-get-version [f] (:version (deref f)))
+
+;; feature_add: position via _options (__before__/__after__/__replace__),
+;; first match wins, else append. (gotcha #4 — ordering carrier is the
+;; feature's :_options map.)
+(defn feature-add [ctx f]
+  (let [feats (client-features (oget ctx :client))
+        fopts (or (:_options (deref f)) (vs/jm))
+        before (mget fopts "__before__")
+        after (mget fopts "__after__")
+        replace (mget fopts "__replace__")]
+    (if (or before after replace)
+      (let [cur (deref feats)
+            idx (first (keep-indexed (fn [i ef]
+                                       (let [nm (feature-get-name ef)]
+                                         (when (or (= before nm) (= after nm) (= replace nm)) i)))
+                                     cur))]
+        (if (nil? idx)
+          (swap! feats conj f)
+          (let [nm (feature-get-name (nth cur idx))]
+            (cond
+              (= before nm) (reset! feats (vec (concat (subvec cur 0 idx) [f] (subvec cur idx))))
+              (= after nm)  (reset! feats (vec (concat (subvec cur 0 (inc idx)) [f] (subvec cur (inc idx)))))
+              (= replace nm) (reset! feats (assoc cur idx f))))))
+      (swap! feats conj f))
+    nil))
+
+(defn feature-init [ctx f]
+  (let [fname (feature-get-name f)
+        opts (oget ctx :options)
+        feature-opts (when opts (vs/getprop opts "feature"))
+        fopts (let [fo (when (vs/ismap feature-opts) (vs/getprop feature-opts fname))]
+                (if (vs/ismap fo) fo (vs/jm)))]
+    (when (= true (mget fopts "active"))
+      ((get (deref f) "init") ctx fopts))))
+
+;; ---------------------------------------------------------------------------
+;; Entity helpers. An entity instance is a plain map carrying atoms plus fn
+;; slots (:make / :data-set / :data-get / :get-name) so the generic pipeline
+;; (make_result list-wrapping) can construct and populate siblings.
+;; ---------------------------------------------------------------------------
+
+(defn entity-get-name [ent] (when (and ent (:get-name ent)) ((:get-name ent))))
+
+;; ---------------------------------------------------------------------------
+;; Pipeline utilities. Each takes ctx; sibling steps are reached via ucall so
+;; overrides / feature-wrapped fetchers are honoured.
+;; ---------------------------------------------------------------------------
+
+(def METHOD-MAP {"create" "POST" "update" "PUT" "load" "GET" "list" "GET" "remove" "DELETE" "patch" "PATCH"})
+
+(defn u-clean [_ctx val] val)
+
+(defn u-prepare-method [ctx] (get METHOD-MAP (op-name (oget ctx :op)) "GET"))
+
+(defn u-prepare-headers [ctx]
+  (let [options (client-options-map (oget ctx :client))
+        headers (vs/getprop options "headers")]
+    (if (nil? headers) (vs/jm)
+        (let [o (vs/clone headers)] (if (vs/ismap o) o (vs/jm))))))
+
+(defn u-param [ctx paramdef]
+  (let [point (oget ctx :point)
+        spec (oget ctx :spec)
+        match (oget ctx :match)
+        reqmatch (oget ctx :reqmatch)
+        data (oget ctx :data)
+        reqdata (oget ctx :reqdata)
+        pt (vs/typify paramdef)
+        key (if (pos? (bit-and vs/T_string pt)) paramdef
+                (let [k (vs/getprop paramdef "name")] (if (string? k) k "")))
+        akey (let [am (when point (to-map (vs/getprop point "alias")))]
+               (if am (let [ak (vs/getprop am key)] (if (string? ak) ak "")) ""))
+        v (atom (vs/getprop reqmatch key))]
+    (when (nil? @v) (reset! v (vs/getprop match key)))
+    (when (and (nil? @v) (seq akey))
+      (when spec (.put ^java.util.Map (oget spec :alias) akey key))
+      (reset! v (vs/getprop reqmatch akey)))
+    (when (nil? @v) (reset! v (vs/getprop reqdata key)))
+    (when (nil? @v) (reset! v (vs/getprop data key)))
+    (when (and (nil? @v) (seq akey))
+      (reset! v (vs/getprop reqdata akey))
+      (when (nil? @v) (reset! v (vs/getprop data akey))))
+    @v))
+
+(defn u-prepare-params [ctx]
+  (let [point (oget ctx :point)
+        params (let [args (when point (vs/getprop point "args"))
+                     p (when (vs/ismap args) (vs/getprop args "params"))]
+                 (if (vs/islist p) p (vs/jt)))
+        out (vs/jm)]
+    (doseq [pd (vec params)]
+      (let [val (ucall ctx :param pd)]
+        (when (and (some? val) (vs/ismap pd))
+          (let [name (vs/getprop pd "name")]
+            (when (and (string? name) (seq name)) (.put ^java.util.Map out name val))))))
+    out))
+
+(defn u-prepare-path [ctx]
+  (let [point (oget ctx :point)
+        parts (let [p (when point (vs/getprop point "parts"))] (if (vs/islist p) p (vs/jt)))]
+    (vs/join parts "/" true)))
+
+(defn u-prepare-query [ctx]
+  (let [point (oget ctx :point)
+        reqmatch (or (oget ctx :reqmatch) (vs/jm))
+        params (let [p (when point (vs/getprop point "params"))] (if (vs/islist p) p (vs/jt)))
+        pset (into #{} (vec params))
+        out (vs/jm)]
+    (doseq [item (or (vs/items reqmatch) [])]
+      (let [k (vs/getprop item 0) v (vs/getprop item 1)]
+        (when (and (some? v) (string? k) (not (contains? pset k)))
+          (.put ^java.util.Map out k v))))
+    out))
+
+(defn u-transform-request [ctx]
+  (let [spec (oget ctx :spec) point (oget ctx :point)]
+    (when spec (oset! spec :step "reqform"))
+    (let [transform (to-map (vs/getprop point "transform"))]
+      (if (nil? transform) (oget ctx :reqdata)
+          (let [reqform (vs/getprop transform "req")]
+            (if (nil? reqform) (oget ctx :reqdata)
+                (vs/transform (vs/jm "reqdata" (oget ctx :reqdata)) reqform)))))))
+
+(defn u-prepare-body [ctx]
+  (if (= "data" (op-input (oget ctx :op))) (ucall ctx :transform-request) nil))
+
+(def HEADER-AUTH "authorization")
+(def OPTION-APIKEY "apikey")
+(def NOT-FOUND "__NOTFOUND__")
+
+(defn u-prepare-auth [ctx]
+  (let [spec (oget ctx :spec)]
+    (if (nil? spec) [nil (ctx-error ctx "auth_no_spec" "Expected context spec property to be defined.")]
+        (let [headers (oget spec :headers)
+              options (client-options-map (oget ctx :client))]
+          (if (nil? (vs/getprop options "auth"))
+            (do (vs/delprop headers HEADER-AUTH) [spec nil])
+            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+              (if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
+                (vs/delprop headers HEADER-AUTH)
+                (let [auth-prefix (or (vs/getpath options "auth.prefix") "")
+                      apikey-val (if (string? apikey) apikey "")]
+                  (.put ^java.util.Map headers HEADER-AUTH
+                        (if (= auth-prefix "") apikey-val (str auth-prefix " " apikey-val)))))
+              [spec nil]))))))
+
+(defn u-make-point [ctx]
+  (let [preset (out-get ctx "point")]
+    (if (some? preset)
+      (if (sdk-error? preset)
+        [nil preset]
+        (do (oset! ctx :point preset) [(oget ctx :point) nil]))
+      (let [op (oget ctx :op)
+            options (oget ctx :options)
+            allow-op (or (vs/getpath options "allow.op") "")]
+        (cond
+          (not (str/includes? allow-op (op-name op)))
+          [nil (ctx-error ctx "point_op_allow"
+                          (str "Operation \"" (op-name op) "\" not allowed by SDK option allow.op value: \"" allow-op "\""))]
+          (zero? (vs/size (op-points op)))
+          [nil (ctx-error ctx "point_no_points"
+                          (str "Operation \"" (op-name op) "\" has no endpoint definitions."))]
+          (= 1 (vs/size (op-points op)))
+          (do (oset! ctx :point (vs/getelem (op-points op) 0)) [(oget ctx :point) nil])
+          :else
+          (let [datainput (= (op-input op) "data")
+                reqselector (if datainput (oget ctx :reqdata) (oget ctx :reqmatch))
+                selector (if datainput (oget ctx :data) (oget ctx :match))
+                point-matches?
+                (fn [p]
+                  (let [select-def (to-map (vs/getprop p "select"))
+                        found (atom true)]
+                    (when (and selector select-def)
+                      (let [exist (vs/getprop select-def "exist")]
+                        (when (vs/islist exist)
+                          (doseq [ek (vec exist)]
+                            (when @found
+                              (let [rv (vs/getprop reqselector (str ek))
+                                    sv (vs/getprop selector (str ek))]
+                                (when (and (nil? rv) (nil? sv)) (reset! found false))))))))
+                    (when @found
+                      (let [ra (vs/getprop reqselector "$action")
+                            sa (vs/getprop select-def "$action")]
+                        (when (not= ra sa) (reset! found false))))
+                    @found))
+                ;; "first matching point, else the last point" (mirrors the
+                ;; reference loop that keeps the last-visited point).
+                chosen (loop [ps (vec (op-points op)) last nil]
+                         (if (empty? ps) last
+                             (let [p (first ps)]
+                               (if (point-matches? p) p (recur (rest ps) p)))))
+                req-action (vs/getprop reqselector "$action")]
+            (if (and reqselector req-action chosen)
+              (let [point-select (to-map (vs/getprop chosen "select"))
+                    point-action (vs/getprop point-select "$action")]
+                (if (not= req-action point-action)
+                  [nil (ctx-error ctx "point_action_invalid"
+                                  (str "Operation \"" (op-name op) "\" action \"" (vs/stringify req-action) "\" is not valid."))]
+                  (do (oset! ctx :point chosen) [(oget ctx :point) nil])))
+              (do (oset! ctx :point chosen) [(oget ctx :point) nil]))))))))
+
+(defn u-make-spec [ctx]
+  (if (some? (out-get ctx "spec"))
+    (do (oset! ctx :spec (out-get ctx "spec")) [(oget ctx :spec) nil])
+    (let [point (oget ctx :point)
+          options (oget ctx :options)
+          base (or (vs/getprop options "base") "")
+          prefix (or (vs/getprop options "prefix") "")
+          suffix (or (vs/getprop options "suffix") "")
+          parts (let [p (when point (vs/getprop point "parts"))] (if (vs/islist p) p (vs/jt)))
+          spec (make-spec (vs/jm "base" base "prefix" prefix "parts" parts "suffix" suffix "step" "start"))]
+      (oset! ctx :spec spec)
+      (oset! spec :method (ucall ctx :prepare-method))
+      (let [allow-method (or (vs/getpath options "allow.method") "")]
+        (if (not (str/includes? allow-method (oget spec :method)))
+          [nil (ctx-error ctx "spec_method_allow"
+                          (str "Method \"" (oget spec :method) "\" not allowed by SDK option allow.method value: \"" allow-method "\""))]
+          (do
+            (oset! spec :params (ucall ctx :prepare-params))
+            (oset! spec :query (ucall ctx :prepare-query))
+            (oset! spec :headers (ucall ctx :prepare-headers))
+            (oset! spec :body (ucall ctx :prepare-body))
+            (oset! spec :path (ucall ctx :prepare-path))
+            (when-let [ex (oget (oget ctx :ctrl) :explain)] (.put ^java.util.Map ex "spec" spec))
+            (let [[s err] (ucall ctx :prepare-auth)]
+              (if err [nil err] (do (oset! ctx :spec s) [s nil])))))))))
+
+(defn u-make-url [ctx]
+  (let [spec (oget ctx :spec) result (oget ctx :result)]
+    (cond
+      (nil? spec) ["" (ctx-error ctx "url_no_spec" "Expected context spec property to be defined.")]
+      (nil? result) ["" (ctx-error ctx "url_no_result" "Expected context result property to be defined.")]
+      :else
+      (let [url (atom (vs/join (vs/jt (oget spec :base) (oget spec :prefix) (oget spec :path) (oget spec :suffix)) "/" true))
+            resmatch (vs/jm)]
+        (doseq [item (or (vs/items (oget spec :params)) [])]
+          (let [k (vs/getprop item 0) v (vs/getprop item 1)]
+            (when (and (some? v) (string? k))
+              (let [placeholder (str "{" k "}")
+                    val-str (if (string? v) v (vs/stringify v))
+                    encoded (vs/escurl val-str)]
+                (reset! url (str/replace @url placeholder encoded))
+                (.put ^java.util.Map resmatch k v)))))
+        (let [qsep (atom "?")]
+          (doseq [item (or (vs/items (oget spec :query)) [])]
+            (let [k (vs/getprop item 0) v (vs/getprop item 1)]
+              (when (and (some? v) (string? k))
+                (let [val-str (if (string? v) v (vs/stringify v))]
+                  (reset! url (str @url @qsep (vs/escurl k) "=" (vs/escurl val-str)))
+                  (reset! qsep "&")
+                  (.put ^java.util.Map resmatch k v))))))
+        (oset! result :resmatch resmatch)
+        [@url nil]))))
+
+(defn u-make-fetch-def [ctx]
+  (let [spec (oget ctx :spec)]
+    (if (nil? spec) [nil (ctx-error ctx "fetchdef_no_spec" "Expected context spec property to be defined.")]
+        (do
+          (when (nil? (oget ctx :result)) (oset! ctx :result (make-result (vs/jm))))
+          (oset! spec :step "prepare")
+          (let [[url err] (ucall ctx :make-url)]
+            (if err [nil err]
+                (do
+                  (oset! spec :url url)
+                  (let [fetchdef (vs/jm "url" url "method" (oget spec :method) "headers" (oget spec :headers))
+                        body (oget spec :body)]
+                    (when (some? body)
+                      (.put ^java.util.Map fetchdef "body" (if (vs/ismap body) (vs/jsonify body) body)))
+                    [fetchdef nil]))))))))
+
+(defn u-make-request [ctx]
+  (if (some? (out-get ctx "request")) [(out-get ctx "request") nil]
+      (let [spec (oget ctx :spec)
+            response (make-response (vs/jm))
+            result (make-result (vs/jm))]
+        (oset! ctx :result result)
+        (if (nil? spec) [nil (ctx-error ctx "request_no_spec" "Expected context spec property to be defined.")]
+            (let [[fetchdef err] (ucall ctx :make-fetch-def)]
+              (if err
+                (do (oset! response :err err) (oset! ctx :response response) (oset! spec :step "postrequest") [response nil])
+                (do
+                  (when-let [ex (oget (oget ctx :ctrl) :explain)] (.put ^java.util.Map ex "fetchdef" fetchdef))
+                  (oset! spec :step "prerequest")
+                  (let [url (or (vs/getprop fetchdef "url") "")
+                        [fetched fetch-err] ((uget ctx :fetcher) ctx url fetchdef)
+                        resp (cond
+                               fetch-err (do (oset! response :err fetch-err) response)
+                               (nil? fetched) (make-response (vs/jm "err" (ctx-error ctx "request_no_response" "response: undefined")))
+                               (vs/ismap fetched) (make-response fetched)
+                               :else (do (oset! response :err (ctx-error ctx "request_invalid_response" "response: invalid type")) response))]
+                    (oset! spec :step "postrequest")
+                    (oset! ctx :response resp)
+                    [resp nil]))))))))
+
+(defn u-result-basic [ctx]
+  (let [response (oget ctx :response) result (oget ctx :result)]
+    (when (and result response)
+      (oset! result :status (oget response :status))
+      (oset! result :status-text (oget response :status-text))
+      (cond
+        (>= (oget result :status) 400)
+        (let [msg (str "request: " (oget result :status) ": " (oget result :status-text))
+              prev (oget result :err)]
+          (if prev
+            (oset! result :err (ctx-error ctx "request_status" (str (err-msg prev) ": " msg)))
+            (oset! result :err (ctx-error ctx "request_status" msg))))
+        (oget response :err) (oset! result :err (oget response :err))))
+    result))
+
+(defn u-result-headers [ctx]
+  (let [response (oget ctx :response) result (oget ctx :result)]
+    (when result
+      (oset! result :headers (if (and response (vs/ismap (oget response :headers))) (oget response :headers) (vs/jm))))
+    result))
+
+(defn u-result-body [ctx]
+  (let [response (oget ctx :response) result (oget ctx :result)]
+    (when (and result response (oget response :json) (oget response :body))
+      (oset! result :body ((oget response :json))))
+    result))
+
+(defn u-transform-response [ctx]
+  (let [spec (oget ctx :spec) result (oget ctx :result) point (oget ctx :point)]
+    (when spec (oset! spec :step "resform"))
+    (if (or (nil? result) (not (oget result :ok))) nil
+        (let [transform (to-map (vs/getprop point "transform"))]
+          (if (nil? transform) nil
+              (let [resform (vs/getprop transform "res")]
+                (if (nil? resform) nil
+                    (let [resdata (vs/transform
+                                   (vs/jm "ok" (oget result :ok) "status" (oget result :status)
+                                          "statusText" (oget result :status-text) "headers" (oget result :headers)
+                                          "body" (oget result :body) "err" (oget result :err)
+                                          "resdata" (oget result :resdata) "resmatch" (oget result :resmatch))
+                                   resform)]
+                      (oset! result :resdata resdata)
+                      resdata))))))))
+
+(defn u-make-response [ctx]
+  (if (some? (out-get ctx "response")) [(out-get ctx "response") nil]
+      (let [spec (oget ctx :spec) result (oget ctx :result) response (oget ctx :response)]
+        (cond
+          (nil? spec) [nil (ctx-error ctx "response_no_spec" "Expected context spec property to be defined.")]
+          (nil? response) [nil (ctx-error ctx "response_no_response" "Expected context response property to be defined.")]
+          (nil? result) [nil (ctx-error ctx "response_no_result" "Expected context result property to be defined.")]
+          :else
+          (do
+            (oset! spec :step "response")
+            (ucall ctx :result-basic)
+            (ucall ctx :result-headers)
+            (ucall ctx :result-body)
+            (ucall ctx :transform-response)
+            (when (nil? (oget result :err)) (oset! result :ok true))
+            (when-let [ex (oget (oget ctx :ctrl) :explain)] (.put ^java.util.Map ex "result" result))
+            [response nil])))))
+
+(defn u-make-result [ctx]
+  (if (some? (out-get ctx "result")) [(out-get ctx "result") nil]
+      (let [op (oget ctx :op) entity (oget ctx :entity) spec (oget ctx :spec) result (oget ctx :result)]
+        (cond
+          (nil? spec) [nil (ctx-error ctx "result_no_spec" "Expected context spec property to be defined.")]
+          (nil? result) [nil (ctx-error ctx "result_no_result" "Expected context result property to be defined.")]
+          :else
+          (do
+            (oset! spec :step "result")
+            (ucall ctx :transform-response)
+            (when (= "list" (op-name op))
+              (let [resdata (oget result :resdata)]
+                (oset! result :resdata (vs/jt))
+                (when (and (vs/islist resdata) (pos? (vs/size resdata)) entity)
+                  (let [out (vs/jt)]
+                    (doseq [entry (vec resdata)]
+                      (let [e ((:make entity))]
+                        (when (vs/ismap entry) ((:data-set e) entry))
+                        (.add ^java.util.List out e)))
+                    (oset! result :resdata out)))))
+            (when-let [ex (oget (oget ctx :ctrl) :explain)] (.put ^java.util.Map ex "result" result))
+            [result nil])))))
+
+(defn u-make-error [ctx err]
+  (let [ctx (or ctx (make-context (vs/jm) nil))
+        op (or (oget ctx :op) (make-operation (vs/jm)))
+        opname0 (op-name op)
+        opname (if (or (= opname0 "") (= opname0 "_")) "unknown operation" opname0)
+        result (or (oget ctx :result) (make-result (vs/jm)))]
+    (oset! result :ok false)
+    (oset! ctx :result result)
+    (let [err (or err (oget result :err) (ctx-error ctx "unknown" "unknown error"))
+          errmsg (err-msg err)
+          msg0 (str SDK-NAME "SDK: " opname ": " errmsg)
+          msg (ucall ctx :clean msg0)
+          spec (oget ctx :spec)]
+      (oset! result :err nil)
+      (when-let [ex (oget (oget ctx :ctrl) :explain)] (.put ^java.util.Map ex "err" (vs/jm "message" msg)))
+      (let [sdk-err (assoc (make-error-obj "" msg ctx)
+                           :result (ucall ctx :clean result)
+                           :spec (ucall ctx :clean spec)
+                           :code (if (sdk-error? err) (:code err) ""))]
+        (oset! (oget ctx :ctrl) :err sdk-err)
+        ;; Fire PreUnexpected so observability features (metrics, telemetry,
+        ;; audit, debug) close/record error paths that never reach PreDone
+        ;; (e.g. a PrePoint rbac short-circuit). Fires after ctrl.err is set so
+        ;; hooks can read the error; features guard against double-recording
+        ;; when PreDone already fired.
+        (when (oget ctx :utility)
+          (ucall ctx :feature-hook "PreUnexpected"))
+        (if (= false (oget (oget ctx :ctrl) :throw))
+          (oget result :resdata)
+          (sdk-throw sdk-err))))))
+
+(defn u-done [ctx]
+  (let [ctrl (oget ctx :ctrl)]
+    (when-let [ex (oget ctrl :explain)]
+      (let [cleaned (ucall ctx :clean ex)]
+        (oset! ctrl :explain cleaned)
+        (let [er (mget cleaned "result")] (when (vs/ismap er) (vs/delprop er "err")))))
+    (let [result (oget ctx :result)]
+      (if (and result (oget result :ok))
+        (oget result :resdata)
+        (ucall ctx :make-error nil)))))
+
+(defn u-make-options [ctx]
+  (let [options (or (oget ctx :options) (vs/jm))
+        custom-utils (vs/getprop options "utility")]
+    (when (and (vs/ismap custom-utils) (oget ctx :utility))
+      (doseq [item (or (vs/items custom-utils) [])]
+        (.put ^java.util.Map (oget (oget ctx :utility) :custom) (vs/getprop item 0) (vs/getprop item 1))))
+    (let [opts0 (let [c (vs/clone options)] (if (vs/ismap c) c (vs/jm)))
+          ;; Feature add-order. options.feature may be given as an ordered
+          ;; ARRAY of {name active ...opts} entries (array position = add
+          ;; order) or a {name {opts}} map. Normalize an array to a map (so
+          ;; merge/validate/init are unchanged) and remember the explicit
+          ;; order; a map defaults to test-first so the `test` mock transport
+          ;; is the base of the transport wrapper chain.
+          explicit-order
+          (let [feature-raw (vs/getprop opts0 "feature")]
+            (when (vs/islist feature-raw)
+              (let [fmap (vs/jm) order (vs/jt)]
+                (doseq [entry (vec feature-raw)]
+                  (when (vs/ismap entry)
+                    (let [nm (vs/getprop entry "name")]
+                      (when (string? nm)
+                        (let [fopts (vs/clone entry)]
+                          (vs/delprop fopts "name")
+                          (.put ^java.util.Map fmap nm fopts)
+                          (.add ^java.util.List order nm))))))
+                (.put ^java.util.Map opts0 "feature" fmap)
+                order)))
+          config (or (oget ctx :config) (vs/jm))
+          cfgopts (let [c (vs/getprop config "options")] (if (vs/ismap c) c (vs/jm)))
+          optspec (vs/jm
+                   "apikey" "" "base" "http://localhost:8000" "prefix" "" "suffix" ""
+                   "auth" (vs/jm "prefix" "")
+                   "headers" (vs/jm "`$CHILD`" "`$STRING`")
+                   "allow" (vs/jm "method" "GET,PUT,POST,PATCH,DELETE,OPTIONS"
+                                  "op" "create,update,load,list,remove,command,direct")
+                   "entity" (vs/jm "`$CHILD`" (vs/jm "`$OPEN`" true "active" false "alias" (vs/jm)))
+                   "feature" (vs/jm "`$CHILD`" (vs/jm "`$OPEN`" true "active" false))
+                   "utility" (vs/jm)
+                   "system" (vs/jm)
+                   "test" (vs/jm "active" false "entity" (vs/jm "`$OPEN`" true))
+                   "clean" (vs/jm "keys" "key,token,id"))
+          sys-fetch (vs/getpath opts0 "system.fetch")
+          merged (vs/merge (vs/jt (vs/jm) cfgopts opts0))
+          validated (vs/validate merged optspec)
+          opts (if (vs/ismap validated) validated (vs/jm))]
+      (when sys-fetch
+        (when (not (vs/ismap (vs/getprop opts "system"))) (.put ^java.util.Map opts "system" (vs/jm)))
+        (.put ^java.util.Map (vs/getprop opts "system") "fetch" sys-fetch))
+      (let [clean-keys (let [k (vs/getpath opts "clean.keys")] (if (string? k) k "key,token,id"))
+            parts (->> (str/split clean-keys #",") (map str/trim) (remove empty?) (map vs/escre))
+            keyre (str/join "|" parts)
+            ;; Resolve the feature add-order: an explicit array order (above)
+            ;; wins; otherwise order the map test-first, then the remaining
+            ;; names sorted, so the outcome is deterministic and `test` is
+            ;; always the base transport.
+            feature-order
+            (if explicit-order
+              explicit-order
+              (let [fmap (let [f (vs/getprop opts "feature")] (if (vs/ismap f) f (vs/jm)))
+                    names (vec (sort (map str (or (vs/keysof fmap) []))))
+                    order (vs/jt)]
+                (when (some #(= % "test") names) (.add ^java.util.List order "test"))
+                (doseq [n names] (when (not= n "test") (.add ^java.util.List order n)))
+                order))
+            derived (vs/jm "clean" (if (empty? keyre) (vs/jm) (vs/jm "keyre" keyre))
+                           "featureorder" feature-order)]
+        (.put ^java.util.Map opts "__derived__" derived)
+        opts))))
+
+;; ---------------------------------------------------------------------------
+;; Default transport + fetcher gate.
+;; ---------------------------------------------------------------------------
+
+(defn default-http-fetch [fullurl fetchdef]
+  (let [method-str (or (vs/getprop fetchdef "method") "GET")
+        body-str (vs/getprop fetchdef "body")
+        headers (or (vs/getprop fetchdef "headers") (vs/jm))]
+    (try
+      (let [url (java.net.URL. fullurl)
+            conn (.openConnection url)]
+        (.setRequestMethod ^java.net.HttpURLConnection conn (str/upper-case method-str))
+        (let [has-ua (atom false)]
+          (doseq [item (or (vs/items headers) [])]
+            (let [k (vs/getprop item 0) v (vs/getprop item 1)]
+              (when (string? v)
+                (when (= (str/lower-case (str k)) "user-agent") (reset! has-ua true))
+                (.setRequestProperty ^java.net.HttpURLConnection conn (str k) v))))
+          (when-not @has-ua
+            (.setRequestProperty ^java.net.HttpURLConnection conn "User-Agent"
+                                 (str "Mozilla/5.0 (compatible; " SDK-NAME "SDK/1.0)"))))
+        (when (string? body-str)
+          (.setDoOutput ^java.net.HttpURLConnection conn true)
+          (with-open [os (.getOutputStream ^java.net.HttpURLConnection conn)]
+            (.write os (.getBytes ^String body-str "UTF-8"))))
+        (let [code (.getResponseCode ^java.net.HttpURLConnection conn)
+              is (try (.getInputStream ^java.net.HttpURLConnection conn) (catch Exception _ (.getErrorStream ^java.net.HttpURLConnection conn)))
+              body (when is (slurp is))
+              resp-headers (vs/jm)]
+          (doseq [[k vlist] (.getHeaderFields ^java.net.HttpURLConnection conn)]
+            (when k (.put ^java.util.Map resp-headers (str/lower-case k) (str/join "," vlist))))
+          (let [json-body (try (when (and body (seq body)) (json-parse body)) (catch Exception _ nil))]
+            [(vs/jm "status" code "statusText" "" "headers" resp-headers
+                    "json" (fn [] json-body) "body" body) nil])))
+      (catch Throwable e
+        [(vs/jm "status" 0 "statusText" (str (.getName (class e)) ": " (.getMessage e))
+                "headers" (vs/jm) "json" (fn [] nil) "body" nil) nil]))))
+
+(defn u-fetcher [ctx fullurl fetchdef]
+  (let [client (oget ctx :client)]
+    (if (not= (client-mode client) "live")
+      [nil (ctx-error ctx "fetch_mode_block"
+                      (str "Request blocked by mode: \"" (client-mode client) "\" (URL was: \"" fullurl "\")"))]
+      (let [options (client-options-map client)]
+        (if (= true (vs/getpath options "feature.test.active"))
+          [nil (ctx-error ctx "fetch_test_block"
+                          (str "Request blocked as test feature is active (URL was: \"" fullurl "\")"))]
+          (let [sys-fetch (vs/getpath options "system.fetch")]
+            (cond
+              (nil? sys-fetch) (default-http-fetch fullurl fetchdef)
+              (vs/isfunc sys-fetch) (sys-fetch fullurl fetchdef)
+              :else [nil (ctx-error ctx "fetch_invalid" "system.fetch is not a valid function")])))))))
+
+;; ---------------------------------------------------------------------------
+;; The base utility map (keys mirror the reference utility members).
+;; ---------------------------------------------------------------------------
+
+(defn base-utility-map []
+  {:clean u-clean :done u-done :make-error u-make-error
+   :feature-add feature-add :feature-hook feature-hook :feature-init feature-init
+   :fetcher u-fetcher :make-fetch-def u-make-fetch-def :make-context (fn [cm bc] (make-context cm bc))
+   :make-options u-make-options :make-request u-make-request :make-response u-make-response
+   :make-result u-make-result :make-point u-make-point :make-spec u-make-spec :make-url u-make-url
+   :param u-param :prepare-auth u-prepare-auth :prepare-body u-prepare-body
+   :prepare-headers u-prepare-headers :prepare-method u-prepare-method :prepare-params u-prepare-params
+   :prepare-path u-prepare-path :prepare-query u-prepare-query
+   :result-basic u-result-basic :result-body u-result-body :result-headers u-result-headers
+   :transform-request u-transform-request :transform-response u-transform-response})
+
+;; feature-hook needs to be reachable via the utility atom too (some callers
+;; invoke it through the utility object).
+(defn feature-hook-call [ctx name] (feature-hook ctx name))