@voxgig/sdkgen 4.9.0 → 4.11.0

package/project/.sdk/tm/clojure/feature/secrets/voxgig/plugin/json.clj

@@ -0,0 +1,106 @@
+;; VENDORED: @voxgig/plugin sdk-20260908-1556-0 (clojure/src/voxgig/plugin/json.clj)
+;; Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+;; License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+(ns voxgig.plugin.json
+  "The JSON parser, and the only one this port has.
+
+  NO clojure.data.json AND NO cheshire (section 16). The library is
+  allowed exactly one runtime dependency, `voxgig/struct`, which has no
+  clojure port; everything else is what ships with clojure itself.
+  Parsing the corpus is a hundred and fifty lines, and a hundred and fifty
+  lines is cheaper than a `deps.edn` `:deps` map every embedding host
+  inherits.
+
+  Numbers parse as LONG when they are written as integers and DOUBLE
+  otherwise, so `(integer? v)` answers section 7's band question without
+  a second thought."
+  (:require [voxgig.plugin.types :as t]))
+
+(defn- ws? [c] (contains? #{\space \tab \newline \return} c))
+
+(defn- skip [^String s at]
+  (loop [at at]
+    (if (and (< at (count s)) (ws? (.charAt s at))) (recur (inc at)) at)))
+
+(declare parse-value)
+
+(defn- parse-string [^String s at]
+  ;; at points at the opening quote.
+  (loop [at (inc at) b (StringBuilder.)]
+    (when (<= (count s) at) (throw (ex-info "unterminated string" {})))
+    (let [c (.charAt s at)]
+      (cond
+        (= \" c) [(str b) (inc at)]
+        (= \\ c)
+        (let [e (.charAt s (inc at))]
+          (case e
+            \u (do (.append b (char (Integer/parseInt (subs s (+ at 2) (+ at 6)) 16)))
+                   (recur (+ at 6) b))
+            (do (.append b (case e \n \newline \t \tab \r \return \b \backspace
+                                   \f \formfeed e))
+                (recur (+ at 2) b))))
+        :else (do (.append b c) (recur (inc at) b))))))
+
+(defn- parse-number [^String s at]
+  (let [end (loop [i at]
+              (if (and (< i (count s))
+                       (or (Character/isDigit (.charAt s i))
+                           (contains? #{\- \+ \. \e \E} (.charAt s i))))
+                (recur (inc i))
+                i))
+        body (subs s at end)]
+    (when (empty? body) (throw (ex-info (str "unexpected input at " at) {})))
+    [(if (re-find #"[.eE]" body) (Double/parseDouble body) (Long/parseLong body)) end]))
+
+(defn- parse-seq
+  "Both containers, since the only differences are the closing character
+  and what each element contributes."
+  [^String s at ^Character close step init]
+  (loop [at (skip s (inc at)) acc init]
+    (if (= close (.charAt s at))
+      [acc (inc at)]
+      (let [[acc at] (step s at acc)
+            at (skip s at)]
+        (case (.charAt s at)
+          \, (recur (skip s (inc at)) acc)
+          (do (when (not= close (.charAt s at))
+                (throw (ex-info (str "expected " close " at " at) {})))
+              [acc (inc at)]))))))
+
+(defn- parse-entry [^String s at acc]
+  (let [[k at] (parse-string s (skip s at))
+        at (skip s at)]
+    (when (not= \: (.charAt s at)) (throw (ex-info (str "expected : at " at) {})))
+    (let [[v at] (parse-value s (skip s (inc at)))]
+      [(assoc acc k v) at])))
+
+(defn- parse-element [^String s at acc]
+  (let [[v at] (parse-value s (skip s at))]
+    [(conj acc v) at]))
+
+(defn- parse-value [^String s at]
+  (let [c (.charAt s at)]
+    (cond
+      (= \{ c) (parse-seq s at \} parse-entry {})
+      (= \[ c) (parse-seq s at \] parse-element [])
+      (= \" c) (parse-string s at)
+      (.startsWith (subs s at) "true") [true (+ at 4)]
+      (.startsWith (subs s at) "false") [false (+ at 5)]
+      (.startsWith (subs s at) "null") [nil (+ at 4)]
+      :else (parse-number s at))))
+
+(defn parse
+  "Parse a JSON document. Throws on malformed input."
+  [^String text]
+  (let [[v at] (parse-value text (skip text 0))
+        at (skip text at)]
+    (when (not= at (count text))
+      (throw (ex-info (str "trailing input at " at) {})))
+    v))
+
+(defn parse-scalar
+  "Parse, FALLING BACK TO THE STRING ITSELF - so `8080` is a number, `true`
+  is a boolean, `{\"a\":1}` is a map, and `hello` is the string it looks
+  like rather than a parse error. Section 9.5's environment values."
+  [text]
+  (try (parse text) (catch Exception _ text)))

package/project/.sdk/tm/clojure/feature/secrets/voxgig/plugin/order.clj

@@ -0,0 +1,157 @@
+;; VENDORED: @voxgig/plugin sdk-20260908-1556-0 (clojure/src/voxgig/plugin/order.clj)
+;; Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+;; License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+(ns voxgig.plugin.order
+  "Ordering (section 7) - one rule, one place.
+
+  sdkgen grew two special cases in `makeOptions` (`test`, then `station`)
+  and the third was not far off. This sort is the whole replacement, and
+  the tiers are in this order for a reason:
+
+    1 constraints   before/after edges, by ref or by name
+    2 bands         integer, lower first, default 0
+    3 declaration   ties break by `pos`
+
+  CONSTRAINTS BEAT BANDS precisely so the correct tool wins when both are
+  present. A band expresses a genuine cross-cutting layer; a constraint
+  expresses a relationship between two specific things; and a band chosen
+  by trial and error to fix an ordering bug is a bug wearing a number."
+  (:require [voxgig.plugin.types :as t]
+            [voxgig.plugin.ref :as r]))
+
+(defn order-band
+  "An integer, and only an integer: `true` and `\"2\"` are not bands."
+  [binding]
+  (or (t/asint (t/get (or (:order binding) {}) "band")) 0))
+
+(defn order-declared?
+  "Was a constraint stated? An absent value and an EMPTY LIST are both
+  no-constraint - and an empty list is TRUTHY in most languages, which is
+  exactly how this class of bug survives a reading."
+  [spec]
+  (cond
+    (nil? spec) false
+    (sequential? spec) (boolean (some #(not= "" %) spec))
+    :else (not= "" spec)))
+
+(defn order-targets
+  "One spelling or a LIST of them. A list fans out to the UNION of what
+  each names, so after: ['a','b'] means after BOTH, and the same instance
+  named twice - once by name, once by ref - is one edge.
+
+  Matching is by REF, or by NAME across all of that definition's instances
+  (section 7) - which is the whole reason the two spellings exist."
+  [spec nodes]
+  (let [specs (if (sequential? spec) spec [spec])]
+    (vec (distinct (for [one specs
+                         b nodes
+                         :when (or (= (:ref b) one) (= (r/ref-name (:ref b)) one))]
+                     (:ref b))))))
+
+(defn- build-edges [nodes]
+  (reduce (fn [edges b]
+            (let [block (or (:order b) {})
+                  edges (if (order-declared? (t/get block "after"))
+                          (reduce #(update %1 %2 conj (:ref b))
+                                  edges
+                                  (order-targets (t/get block "after") nodes))
+                          edges)]
+              (if (order-declared? (t/get block "before"))
+                (update edges (:ref b) into (order-targets (t/get block "before") nodes))
+                edges)))
+          (zipmap (map :ref nodes) (repeat []))
+          nodes))
+
+(defn- walk
+  "Stable topological sort. Among ready nodes, band first (lower runs
+  first), then `pos` - the position the DOCUMENT visibly states, not the
+  order instances happened to load and not the incarnation `seq`."
+  [ready indeg edges byref out]
+  (if (empty? ready)
+    out
+    (let [[nxt & rest] (t/stable-sort-by (fn [b] [(order-band b) (or (:pos b) 0)]) ready)
+          [indeg added] (reduce (fn [[ind acc] to]
+                                  (let [ind (update ind to dec)]
+                                    (if (zero? (ind to))
+                                      [ind (conj acc (byref to))]
+                                      [ind acc])))
+                                [indeg []]
+                                (edges (:ref nxt)))]
+      (recur (concat rest added) indeg edges byref (conj out (:ref nxt))))))
+
+(declare apply-pin)
+
+(defn resolve-order
+  "`bindings` is a list of `{:ref :pos :order}` - an internal shape, never
+  a corpus value, so it uses keyword keys where the data does not."
+  ([bindings] (resolve-order bindings nil))
+  ([bindings pin]
+   (let [nodes (vec bindings)
+         byref (zipmap (map :ref nodes) nodes)
+         ;; Constraints are edges. A constraint naming an ABSENT binding
+         ;; is satisfied VACUOUSLY (section 7) - a plugin ordered
+         ;; `after: 'test'` must load in a host with no test plugin. That
+         ;; is sdkgen's __after__ behaviour, kept.
+         edges (build-edges nodes)
+         indeg (reduce (fn [ind tos] (reduce #(update %1 %2 inc) ind tos))
+                       (zipmap (map :ref nodes) (repeat 0))
+                       (vals edges))
+         out (walk (filter #(zero? (indeg (:ref %))) nodes) indeg edges byref [])]
+     (when (not= (count out) (count nodes))
+       (let [stuck (vec (remove (set out) (map :ref nodes)))]
+         (t/fail "plugin_order_cycle"
+                 (str "before/after constraints cycle: " (clojure.string/join " -> " stuck))
+                 {"cycle" stuck})))
+     (apply-pin out edges pin))))
+
+(defn- place [out nm want]
+  (let [idx (first (keep-indexed #(when (= (r/ref-name %2) nm) %1) out))]
+    (if (nil? idx)
+      out
+      ;; `first`/`outermost` is index 0; `last`/`innermost` is the end.
+      ;; Section 6.2 makes the first chain binding outermost, which is why
+      ;; the vocabulary is positional and why the two spellings pair this
+      ;; way.
+      (let [ref (out idx)
+            rest (vec (concat (subvec out 0 idx) (subvec out (inc idx))))]
+        (if (contains? #{"first" "outermost"} want)
+          (vec (cons ref rest))
+          (conj rest ref))))))
+
+(defn apply-pin
+  "A PIN IS NOT A CONSTRAINT (section 7).
+
+  Constraints and bands are negotiable by definition - they are what
+  plugins and documents say they want, and the sort's job is to satisfy
+  them all. A pin is the host stating a structural invariant of its own
+  architecture, which is a different kind of claim and must not lose a tie
+  to a document.
+
+  So a pin PLACES the binding at the named end, and an ordering that would
+  move it away is `plugin_order_pinned` - rejected, not honoured into a
+  broken wrap."
+  [order edges pin]
+  (if (nil? pin)
+    (vec order)
+    ;; SORTED, not insertion order. A pin map is data - it can arrive from
+    ;; a host's own construction options in any order, and two names
+    ;; pinned to the same end are order-sensitive (`{b:'first',
+    ;; a:'first'}` and `{a:'first', b:'first'}` give different results).
+    ;; A clojure hash-map has no order at all, so leaving it unstated made
+    ;; the same declaration mean different things in different ports.
+    (let [out (reduce (fn [acc nm] (place acc nm (t/get pin nm)))
+                      (vec order)
+                      (t/sorted-keys pin))
+          ;; Now check that the placement did not break a constraint. This
+          ;; is the half that makes a pin a rejection rather than an
+          ;; override: the host wins on position, but it does not get to
+          ;; silently discard a relationship a plugin declared.
+          at (zipmap out (range))]
+      (doseq [[from tos] edges
+              to tos
+              :when (< (at to) (at from))]
+        (t/fail "plugin_order_pinned"
+                (str "a pin would move a binding an ordering constrains: "
+                     from " must precede " to)
+                {"before" from "after" to}))
+      out)))

package/project/.sdk/tm/clojure/feature/secrets/voxgig/plugin/point.clj

@@ -0,0 +1,77 @@
+;; VENDORED: @voxgig/plugin sdk-20260908-1556-0 (clojure/src/voxgig/plugin/point.clj)
+;; Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+;; License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+(ns voxgig.plugin.point
+  "Extension points (section 6). Three kinds, chosen because they are what
+  the two existing systems actually needed, and no more.
+
+  A PLUGIN NEVER MUTATES THE HOST. That inversion is what makes
+  deactivation possible: sdkgen's `utility.fetcher = wrapped` is not
+  undoable, but \"this instance holds slot 3 of the request chain\" is
+  undoable in O(1). OSGi named it the whiteboard pattern in 2004, in a
+  paper called *Listeners Considered Harmful*, and for exactly this
+  reason."
+  (:require [voxgig.plugin.types :as t]))
+
+(def modes
+  "Section 6.1: \"fan-out\" is not one answer but four. In a language with
+  asynchrony, \"call every binding\" hides a decision - start them all and
+  wait, await each in turn, or do not wait - and a design that leaves it
+  unsaid gets four different answers from four ports, in the concurrency
+  behaviour of production code no corpus entry happens to cover.
+
+  Clojure has `pmap` and `future` right there, and using either for `emit`
+  would make every hook point concurrent and every ordering assertion a
+  race. The host stays sequential (section 5.2) and the modes stay data."
+  ["emit" "parallel" "serial" "bail"])
+
+(defn point-emit
+  "Fan-out. Return values are ignored except in `bail`."
+  [bindings mode arg]
+  (cond
+    (= "bail" mode)
+    ;; Stops at the first binding that RETURNS A VALUE - the "handled,
+    ;; stop" case. A `nil` RETURN DECLINES (section 6.1): clojure has one
+    ;; way to say nothing, and the model's rule is written to that rather
+    ;; than to JavaScript's null/undefined pair. `some?`, NOT truthiness -
+    ;; `false` is a value.
+    (first (keep #((:fn %) nil arg) bindings))
+
+    ;; `emit` raises synchronously; the collecting modes gather.
+    (= "emit" mode)
+    (do (doseq [b bindings] ((:fn b) nil arg)) nil)
+
+    :else
+    (vec (keep (fn [b] (try ((:fn b) nil arg) nil
+                            (catch Exception e (t/message-of e))))
+               bindings))))
+
+(defn compose
+  "Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (section 6.2).
+
+  Recomputed by the host whenever the live set changes, and cached between
+  changes. Plugins receive `next` as an argument; they never see or store
+  the previous value of anything. A plugin that stashes `next` and calls
+  it after deactivation is a bug the host cannot prevent, and this says so
+  rather than pretending otherwise."
+  [bindings base]
+  (reduce (fn [inner b] (fn [arg] ((:fn b) inner arg)))
+          base
+          (reverse bindings)))
+
+(defn point-provider
+  "At most one live implementation (section 6.3). The winner is the highest
+  band, ties broken by ref sort, and THE LOSERS ARE VISIBLE rather than
+  silently ignored."
+  [bindings spec]
+  (if (empty? bindings)
+    {:winner nil :shadowed []}
+    (do
+      (when (and (t/truthy (t/get spec "exclusive")) (< 1 (count bindings)))
+        (let [refs (sort (map :ref bindings))]
+          (t/fail "plugin_point_exclusive"
+                  (str "point is exclusive and has " (count bindings) " bindings: "
+                       (clojure.string/join ", " refs))
+                  {"refs" (vec refs)})))
+      (let [ranked (t/stable-sort-by (fn [b] [(- (:band b)) (:ref b)]) bindings)]
+        {:winner (first ranked) :shadowed (vec (map :ref (rest ranked)))}))))

package/project/.sdk/tm/clojure/feature/secrets/voxgig/plugin/ref.clj

@@ -0,0 +1,92 @@
+;; VENDORED: @voxgig/plugin sdk-20260908-1556-0 (clojure/src/voxgig/plugin/ref.clj)
+;; Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+;; License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+(ns voxgig.plugin.ref
+  "Identity: name+tag, written `name$tag` (section 4).
+
+  The four pure functions, and the whole of what `ref` pins. They are the
+  first thing a new port implements and the first corpus section it
+  passes."
+  (:require [voxgig.plugin.types :as t]))
+
+(def ^:private name-re
+  "Section 4: `^[a-zA-Z@][a-zA-Z0-9.~_\\-/]*$`, max 1024.
+
+  `\\A` and `\\z`, NOT `^` and `$`. Java's `$` matches at the end of input
+  AND just before a final line terminator, so `^...$` would admit
+  \"stripe\\n\" - a ref grammar with a newline in it, admitted by exactly
+  the ports whose regex idiom differs from javascript's."
+  #"\A[a-zA-Z@][a-zA-Z0-9.~_\-/]*\z")
+
+(def ^:private tag-re
+  "Section 4: `^[a-zA-Z0-9.~_-]+$`, max 1024, or empty.
+
+  The asymmetry with a name is deliberate: a tag MAY start with a digit
+  because auto-tagging assigns integer tags (`stripe$1`), and a tag admits
+  neither `@` nor `/` because a name is a package specifier and a tag is
+  not."
+  #"\A[a-zA-Z0-9.~_-]+\z")
+
+(def ^:private ref-max 1024)
+
+(defn check-name [nm]
+  (boolean (and (string? nm)
+                (seq nm)
+                (>= ref-max (count nm))
+                (re-matches name-re nm))))
+
+(defn check-tag [tag]
+  (boolean (and (string? tag)
+                ;; The empty tag is an ordinary tag (section 4 rule 2). The
+                ;; single-instance case writes no tag and never learns tags
+                ;; exist.
+                (or (empty? tag)
+                    (and (>= ref-max (count tag)) (re-matches tag-re tag))))))
+
+(defn parse-ref
+  "`name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both give
+  tag \"\"."
+  [s]
+  (when-not (string? s) (t/fail "plugin_bad_name" "ref must be a string"))
+  ;; Split on the FIRST `$`. Nothing in the grammar decides this - `$` is
+  ;; in neither character class - so the corpus is the arbiter (section 4
+  ;; rule 5), and it picks the split that blames the part actually at
+  ;; fault: `a$b$c` is a good name with a bad tag, not the reverse.
+  (let [cut (.indexOf ^String s "$")
+        nm (if (neg? cut) s (subs s 0 cut))
+        tag (if (neg? cut) "" (subs s (inc cut)))]
+    (when-not (check-name nm)
+      (t/fail "plugin_bad_name" (str "invalid plugin name: " nm) {"name" nm}))
+    (when-not (check-tag tag)
+      (t/fail "plugin_bad_tag" (str "invalid plugin tag: " tag) {"name" nm "tag" tag}))
+    {"name" nm "tag" tag}))
+
+(defn format-ref
+  "The pair -> `name$tag`. An empty tag NEVER writes the separator, which
+  is the half of canonicalization `format-ref` owns: parse tolerates
+  `stripe$`, format never produces it, so a round trip is idempotent."
+  ([nm] (format-ref nm nil))
+  ([nm tag]
+   (let [tag (or tag "")]
+     (when-not (check-name nm)
+       (t/fail "plugin_bad_name" (str "invalid plugin name: " nm) {"name" nm}))
+     (when-not (check-tag tag)
+       (t/fail "plugin_bad_tag" (str "invalid plugin tag: " tag) {"name" nm "tag" tag}))
+     (if (empty? tag) nm (str nm "$" tag)))))
+
+(defn canon-ref
+  "The canonical spelling of a ref. Section 4 rule 5: ports must
+  canonicalize before comparison."
+  [s]
+  (let [r (parse-ref s)]
+    (format-ref (r "name") (r "tag"))))
+
+(defn canon
+  "`canon-ref` for the internal callers that want the input back unchanged
+  when it is not well formed. NEVER use it where a bad ref must be
+  reported - the corpus pins plugin_bad_name at every public entry."
+  [s]
+  (try (canon-ref s) (catch clojure.lang.ExceptionInfo _ s)))
+
+(defn ref-name [s]
+  (try ((parse-ref s) "name") (catch clojure.lang.ExceptionInfo _ s)))

package/project/.sdk/tm/clojure/feature/secrets/voxgig/plugin/resolve.clj

@@ -0,0 +1,46 @@
+;; VENDORED: @voxgig/plugin sdk-20260908-1556-0 (clojure/src/voxgig/plugin/resolve.clj)
+;; Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+;; License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+(ns voxgig.plugin.resolve
+  "Dynamic resolution (section 10.2) - name to candidate module ids.
+
+  PURE. It returns the ids a host WOULD try, in order; it does not load
+  anything. That separation is what lets the corpus pin resolution in
+  every language including those with no dynamic loading at all, and it is
+  why section 15.4 puts real module loading in per-port integration tests
+  rather than here."
+  (:require [voxgig.plugin.types :as t]
+            [clojure.string :as str]))
+
+(def default-sources
+  [{"kind" "module" "prefix" ["@voxgig/plugin-" "voxgig-plugin-" "plugin-" ""]}])
+
+(defn- ids-for [src nm]
+  (case (t/get src "kind")
+    "module" (let [prefixes (t/get src "prefix")
+                   prefixes (if (empty? prefixes) [""] prefixes)]
+               (map #(str % nm) prefixes))
+    "path" [(str (str/replace (t/get src "dir") #"/+\z" "") "/" nm)]
+    []))
+
+(defn resolve-candidates
+  ([nm] (resolve-candidates nm nil))
+  ([nm sources]
+   ;; A SCOPED NAME RESOLVES VERBATIM ONLY (section 10.2). `@acme/thing`
+   ;; is already a package id; prefixing it produces
+   ;; `@voxgig/plugin-@acme/thing`, which is not a thing that can exist.
+   (if (str/starts-with? nm "@")
+     [nm]
+     (->> (if (empty? sources) default-sources sources)
+          (mapcat #(ids-for % nm))
+          distinct
+          vec))))
+
+(defn resolve-from
+  "A MODULE PATH IS NOT A NAME (section 10.2). The ref grammar starts a
+  name with a letter or `@`, so `./local/thing` is not a ref and never
+  reaches candidate generation - seneca allows a path where a plugin name
+  goes, and this design deliberately does not, because a ref is an ADDRESS
+  WITHIN A HOST and a path is a LOCATION ON A DISK."
+  [from]
+  [from])

package/project/.sdk/tm/clojure/feature/secrets/voxgig/plugin/types.clj

@@ -0,0 +1,177 @@
+;; VENDORED: @voxgig/plugin sdk-20260908-1556-0 (clojure/src/voxgig/plugin/types.clj)
+;; Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+;; License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+(ns voxgig.plugin.types
+  "The value model, the error type, and the JSON writer.
+
+  CLOJURE IS THE PORT WHERE THE VALUE MODEL COSTS NOTHING. Maps are not
+  vectors, `nil` is a value a map can hold, `contains?` separates an
+  authored null from an absent key, and `(= true 1)` is false. Every trap
+  php, perl, lua and java document is absent here, so what is left is the
+  two things clojure does make you decide.
+
+  KEYS ARE STRINGS, NOT KEYWORDS. Idiomatic clojure would read
+  `(:status entry)`, and every corpus value would then need converting on
+  the way in and back on the way out - two conversions whose only job is
+  to make a foreign document look native, and which lose the distinction
+  between the key \"a\" and the keyword :a in a document that used both.
+  The corpus is JSON; this port holds JSON.
+
+  ORDER IS NEVER THE MAP'S. A clojure map past eight entries is a hash-map
+  and `keys` on one is unordered, so every walk of a map goes through
+  `sorted-keys`. That is not tidiness: without it a teardown order changes
+  between two runs of the same process."
+  (:refer-clojure :exclude [get]))
+
+(def statuses
+  "Section 5.1's seven statuses, and no more."
+  ["declared" "loaded" "pending" "live" "failed" "loading" "closing"])
+
+(def detail-order
+  "Section 12's detail keys, in the order a message renders them. FIXED,
+  not the map's: a message is a searchable log line, and a line whose
+  fields move between runs is not."
+  ["ref" "point" "name" "key" "spec" "refs" "kind" "directive" "cycle"
+   "holders" "cause"])
+
+(defn get
+  "The value at a key, or nil. Absence and null read the same here."
+  [m k]
+  (when (map? m) (clojure.core/get m k)))
+
+(defn has?
+  "PRESENCE, which is what distinguishes an authored null from absence."
+  [m k]
+  (and (map? m) (contains? m k) true))
+
+(defn sorted-keys
+  "The keys of a map, SORTED - every walk of a map goes through here."
+  [m]
+  (if (map? m) (sort (keys m)) []))
+
+(defn truthy
+  "JSON truthiness, which clojure already agrees with: nil and false are
+  its only falsey values, so 0 and \"\" count. It exists so the ports read
+  alike at the sites that need it, and so a reader does not have to check
+  whether the zero case was considered."
+  [v]
+  (not (or (nil? v) (false? v))))
+
+(defn asint
+  "An INTEGER, and only when the value is one. Section 7's band is an
+  integer the document wrote as one; `true` and `\"2\"` are not bands, and
+  clojure's `integer?` excludes both."
+  [v]
+  (cond
+    (integer? v) (long v)
+    (and (number? v) (== v (Math/floor (double v)))) (long v)
+    :else nil))
+
+(defn stable-sort-by
+  "A STABLE sort by a key function.
+
+  `sort-by` IS stable - it is `java.util.Arrays/sort` over an object array,
+  documented stable. Stability is load-bearing: section 7's comparators
+  fall through to a `pos` or ref tie-break that javascript's stable sort
+  resolves BY POSITION, and a port that shuffled equal keys would order a
+  teardown differently between two runs of one process. The name is kept
+  so that one place in the port says so."
+  [keyfn coll]
+  (sort-by keyfn coll))
+
+(defn same
+  "JSON equality: same type, then same value.
+
+  Clojure's `=` is type-strict across booleans, numbers and strings -
+  `(= true 1)` and `(= \"1\" 1)` are both false - and it is STRICTER than
+  javascript on numbers: `(= 1 1.0)` is false. `==` is the numeric
+  comparison, so the two spellings of one number agree, which is what
+  every other port does."
+  [a b]
+  (cond
+    (and (number? a) (number? b)) (== a b)
+    (and (map? a) (map? b))
+    (and (= (count a) (count b))
+         (every? (fn [[k v]] (and (contains? b k) (same v (clojure.core/get b k)))) a))
+    (and (sequential? a) (sequential? b))
+    (and (= (count a) (count b)) (every? identity (map same a b)))
+    (or (sequential? a) (sequential? b) (map? a) (map? b)) false
+    :else (= a b)))
+
+;; --- JSON out ------------------------------------------------------
+;;
+;; The writer only. The parser is in `voxgig.plugin.json`, and neither is
+;; `clojure.data.json`: section 16 permits ONE runtime dependency and
+;; clojure has no port of it, so a `deps.edn` with a `:deps` map would be
+;; a dependency every embedding host inherits for a hundred and fifty
+;; lines of parser.
+
+(defn- escape [^String s]
+  (let [b (StringBuilder.)]
+    (doseq [c s]
+      (case c
+        \" (.append b "\\\"")
+        \\ (.append b "\\\\")
+        \newline (.append b "\\n")
+        \return (.append b "\\r")
+        \tab (.append b "\\t")
+        (if (< (int c) 0x20)
+          (.append b (format "\\u%04x" (int c)))
+          (.append b c))))
+    (str b)))
+
+(defn encode
+  "COMPACT JSON. A number that is a whole double renders without its
+  fraction, so `1.0` and `1` spell the same - the corpus writes both and a
+  message quoting one must not depend on which."
+  [v]
+  (cond
+    (nil? v) "null"
+    (true? v) "true"
+    (false? v) "false"
+    (string? v) (str "\"" (escape v) "\"")
+    (integer? v) (str v)
+    (number? v) (let [d (double v)]
+                  (if (== d (Math/floor d)) (str (long d)) (str d)))
+    (map? v) (str "{" (clojure.string/join
+                       ","
+                       (map #(str "\"" (escape (str %)) "\":" (encode (clojure.core/get v %)))
+                            (sorted-keys v)))
+                  "}")
+    (sequential? v) (str "[" (clojure.string/join "," (map encode v)) "]")
+    :else "\"(opaque)\""))
+
+;; --- errors --------------------------------------------------------
+
+(defn format-error
+  "`plugin/<code>: <text> [<key>=<value> ...]`
+
+  Values render as COMPACT JSON, so a value containing a space or a
+  bracket cannot break the parse, and a list renders as a JSON array. The
+  bracket is absent entirely when no field applies."
+  [code text details]
+  (let [parts (for [k detail-order :when (has? details k)]
+                (str k "=" (encode (get details k))))]
+    (str "plugin/" code ": " text
+         (if (empty? parts) "" (str " [" (clojure.string/join " " parts) "]")))))
+
+(defn fail
+  "Throw a section 12 error. One spelling, so every raise site reads the
+  same. `ex-info` carries the code as DATA, which is what lets the corpus
+  runner compare by code without parsing a message."
+  ([code text] (fail code text {}))
+  ([code text details]
+   (throw (ex-info (format-error code text details)
+                   {:plugin true :code code :text text :details details}))))
+
+(defn code-of
+  "The section 12 code of an error, or \"\" for one this library did not
+  throw. The corpus compares by code, so the driver needs one place that
+  knows how to read it."
+  [e]
+  (or (when (instance? clojure.lang.ExceptionInfo e)
+        (:code (ex-data e)))
+      ""))
+
+(defn message-of [e]
+  (if (instance? Throwable e) (or (.getMessage ^Throwable e) (str e)) (str e)))