@voxgig/sdkgen 4.10.0 → 4.11.0

package/project/.sdk/tm/ocaml/feature/secrets/plugin/order.ml

@@ -0,0 +1,202 @@
+(* VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ocaml/src/order.ml) *)
+(* 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. *)
+(* Ordering (§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. *)
+
+module V = Value
+
+let bandof b =
+  (* A NUMBER, not a numeric string. `order.band` accepting "1" was a
+     surviving mutation in more than one port: the corpus pins the type
+     because two ports disagreeing about whether "1" is a band is
+     exactly the divergence a shared corpus exists to remove. *)
+  let band = V.get (V.get b "order") "band" in
+  if V.is_num band then V.as_num band else 0.0
+
+let posof b =
+  let p = V.get b "pos" in
+  if V.is_num p then V.as_num p else 0.0
+
+(* 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`. *)
+let rank a b =
+  let ab = bandof a and bb = bandof b in
+  if ab <> bb then compare ab bb else compare (posof a) (posof b)
+
+(* Was a constraint actually declared? An ABSENT one and an EMPTY LIST
+   are both "no constraint"; only a non-empty spelling is an edge. *)
+let declared spec =
+  if V.is_list spec then 0 < V.len spec
+  else if V.is_str spec then "" <> V.as_str spec
+  else false
+
+(* Matching is by REF, or by NAME across all of that definition's
+   instances (§7) — which is the whole reason the two spellings
+   exist. *)
+let targets spec nodes =
+  let specs = if V.is_list spec then V.items spec else [ spec ] in
+  let hit = ref [] in
+  List.iter
+    (fun oneval ->
+      if V.is_str oneval then begin
+        let one = V.as_str oneval in
+        List.iter
+          (fun node ->
+            let r = V.as_str (V.get node "ref") in
+            if (not (List.mem r !hit)) && (r = one || Ref.refname r = one) then
+              hit := !hit @ [ r ])
+          (V.items nodes)
+      end)
+    specs;
+  !hit
+
+(* A PIN IS NOT A CONSTRAINT (§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. *)
+let applypin order edges pin =
+  if not (V.is_map pin) then order
+  else begin
+    let out = ref (List.map V.as_str (V.items order)) in
+    (* 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. Sorted is the
+       one order every language agrees on, and `order/pin#two-names`
+       pins it. *)
+    List.iter
+      (fun name ->
+        let want = V.as_str (V.get pin name) in
+        match List.find_opt (fun r -> Ref.refname r = name) !out with
+        | None -> ()
+        | Some r ->
+          (* `first`/`outermost` is index 0; `last`/`innermost` is the
+             end. §6.2 makes the first chain binding outermost, which
+             is why the vocabulary is positional and why the two
+             spellings pair this way. *)
+          let wantfirst = "first" = want || "outermost" = want in
+          let rest = List.filter (fun x -> x <> r) !out in
+          out := (if wantfirst then r :: rest else rest @ [ r ]))
+      (V.sortedkeys 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. *)
+    let index = V.vmap () in
+    List.iteri (fun i r -> V.set index r (V.vnum (float_of_int i))) !out;
+    List.iter
+      (fun from ->
+        List.iter
+          (fun tov ->
+            let t = V.as_str tov in
+            if V.as_num (V.get index from) > V.as_num (V.get index t) then begin
+              let d = V.vmap () in
+              V.set d "before" (V.vstr from);
+              V.set d "after" (V.vstr t);
+              Types.fail "plugin_order_pinned"
+                ("a pin would move a binding an ordering constrains: " ^ from
+                 ^ " must precede " ^ t)
+                ~details:d
+            end)
+          (V.items (V.get edges from)))
+      (V.sortedkeys edges);
+
+    V.oflist (List.map V.vstr !out)
+  end
+
+let resolveorder bindings pin =
+  let nodes = V.items bindings in
+  let n = List.length nodes in
+
+  let byref = V.vmap () in
+  List.iter (fun b -> V.set byref (V.as_str (V.get b "ref")) b) nodes;
+
+  (* Constraints are edges. A constraint naming an ABSENT binding is
+     satisfied VACUOUSLY (§7) — a plugin ordered `after: 'test'` must
+     load in a host with no test plugin. That is sdkgen's __after__
+     behaviour, kept. *)
+  let edges = V.vmap () in
+  List.iter (fun b -> V.set edges (V.as_str (V.get b "ref")) (V.vlist ())) nodes;
+
+  List.iter
+    (fun b ->
+      let bref = V.as_str (V.get b "ref") in
+      let o = V.get b "order" in
+      let after = V.get o "after" and before = V.get o "before" in
+      if declared after then
+        List.iter (fun t -> V.push (V.get edges t) (V.vstr bref))
+          (targets after bindings);
+      if declared before then
+        List.iter (fun t -> V.push (V.get edges bref) (V.vstr t))
+          (targets before bindings))
+    nodes;
+
+  (* Stable topological sort. *)
+  let indeg = V.vmap () in
+  List.iter (fun b -> V.set indeg (V.as_str (V.get b "ref")) (V.vnum 0.0)) nodes;
+  List.iter
+    (fun from ->
+      List.iter
+        (fun tov ->
+          let t = V.as_str tov in
+          V.set indeg t (V.vnum (V.as_num (V.get indeg t) +. 1.0)))
+        (V.items (V.get edges from)))
+    (V.keys edges);
+
+  let ready =
+    ref (List.filter
+           (fun b -> 0.0 = V.as_num (V.get indeg (V.as_str (V.get b "ref"))))
+           nodes)
+  in
+  let out = ref [] in
+  while [] <> !ready do
+    let sorted = List.stable_sort rank !ready in
+    let next = List.hd sorted in
+    ready := List.tl sorted;
+    let nref = V.as_str (V.get next "ref") in
+    out := !out @ [ nref ];
+    List.iter
+      (fun tov ->
+        let t = V.as_str tov in
+        let d = V.as_num (V.get indeg t) -. 1.0 in
+        V.set indeg t (V.vnum d);
+        if 0.0 = d then ready := !ready @ [ V.get byref t ])
+      (V.items (V.get edges nref))
+  done;
+
+  if List.length !out <> n then begin
+    let stuck =
+      List.filter_map
+        (fun b ->
+          let r = V.as_str (V.get b "ref") in
+          if List.mem r !out then None else Some r)
+        nodes
+    in
+    Types.fail "plugin_order_cycle"
+      ("before/after constraints cycle: " ^ String.concat " -> " stuck)
+      ~details:(Types.details1 "cycle" (V.oflist (List.map V.vstr stuck)))
+  end;
+
+  applypin (V.oflist (List.map V.vstr !out)) edges pin

package/project/.sdk/tm/ocaml/feature/secrets/plugin/point.ml

@@ -0,0 +1,138 @@
+(* VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ocaml/src/point.ml) *)
+(* 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. *)
+(* Extension points (§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.
+
+   A CLOSURE IS A CLOSURE, which is the whole difference from the `c`
+   port: a chain binding receives its `next` as a function the
+   composition built — the same shape the canonical writes — instead of
+   c's explicit `Chain *` walked by index. *)
+
+module V = Value
+
+(* A binding answers with an option: None DECLINES, Some v answers.
+   `bail` needs the distinction and c reaches it with a NULL pointer;
+   here it is the type. *)
+type hook = V.t -> V.t option
+
+(* The remaining composition, as seen by one chain binding. A binding
+   may CALL it and must not store it — a plugin that stashes `next` and
+   calls it after deactivation is a bug the host cannot prevent, and
+   saying so is better than pretending otherwise (§6.2). *)
+type next = V.t -> V.t
+type chainfn = next -> V.t -> V.t
+
+type bound = {
+  bref : string;
+  bpoint : string;
+  (* `provider` ranks by HIGHEST band, unlike hook and chain which run
+     lowest first. Kept as declared so the two rules stay visibly
+     different rather than one being derived from the other by a reader
+     who then gets it backwards. *)
+  mutable band : float;
+  bhook : hook option;
+  bchain : chainfn option;
+}
+
+(* Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (§6.2). *)
+let pointcall bindings base arg =
+  let rec callat bs a =
+    match bs with
+    | [] -> (match base with Some f -> f a | None -> a)
+    | b :: rest ->
+      (match b.bchain with
+       | Some c -> c (fun x -> callat rest x) a
+       | None -> callat rest a)
+  in
+  callat bindings arg
+
+let callhook b arg = match b.bhook with Some h -> h arg | None -> None
+
+(* Fan-out. Return values are ignored except in `bail`.
+
+   §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. This port is synchronous, so all four modes are sequential
+   here and only the ERROR and RETURN handling distinguishes them.
+
+   Answers (result, errors). *)
+let pointemit bindings mode arg =
+  let errors = V.vlist () in
+  if "bail" = mode then begin
+    (* Stops at the first binding that RETURNS A VALUE — the "handled,
+       stop" case. NONE, AND A JSON NULL, BOTH DECLINE.
+
+       JavaScript can tell null from undefined and almost nothing else
+       in the target set can — Go, Python, Ruby, PHP, Lua, Java and C#
+       each have exactly one way to say nothing. Making the distinction
+       load-bearing would cost every one of them a wrapper type carried
+       through the whole dispatch path, to express a difference their
+       plugin authors cannot write. §18's budget settles it (§6.1). *)
+    let rec go = function
+      | [] -> (None, errors)
+      | b :: rest -> (
+        match callhook b arg with
+        | Some v when not (V.is_null v) -> (Some v, errors)
+        | _ -> go rest)
+    in
+    go bindings
+  end
+  else begin
+    let raising = "emit" = mode in
+    List.iter
+      (fun b ->
+        if raising then ignore (callhook b arg)
+        else
+          (* `emit` raises synchronously; the collecting modes
+             gather. *)
+          try ignore (callhook b arg) with
+          | Types.Plugin_error e ->
+            let rec_ = V.vmap () in
+            V.set rec_ "code" (V.vstr e.Types.code);
+            V.set rec_ "message" (V.vstr e.Types.message);
+            V.push errors rec_)
+      bindings;
+    (None, errors)
+  end
+
+(* At most one live implementation (§6.3). The winner is the highest
+   band, ties broken by ref sort, and THE LOSERS ARE VISIBLE rather
+   than silently ignored. Answers (winner, shadowed refs). *)
+let pointprovider bindings exclusive =
+  if [] = bindings then (None, V.vlist ())
+  else begin
+    if exclusive && 1 < List.length bindings then begin
+      (* Sorted, so the message names the same pair whatever order the
+         bindings arrived in. *)
+      let refs = List.sort compare (List.map (fun b -> b.bref) bindings) in
+      Types.fail "plugin_point_exclusive"
+        ("point is exclusive and has "
+         ^ string_of_int (List.length bindings)
+         ^ " bindings: " ^ String.concat ", " refs)
+        ~details:(Types.details1 "refs" (V.oflist (List.map V.vstr refs)))
+    end;
+    (* HIGHEST band wins, unlike hook and chain; ties break by ref
+       sort, which is a TOTAL order. *)
+    let ranked =
+      List.stable_sort
+        (fun a b ->
+          if a.band <> b.band then compare b.band a.band
+          else compare a.bref b.bref)
+        bindings
+    in
+    let shadowed =
+      V.oflist (List.map (fun b -> V.vstr b.bref) (List.tl ranked))
+    in
+    (Some (List.hd ranked), shadowed)
+  end

package/project/.sdk/tm/ocaml/feature/secrets/plugin/ref.ml

@@ -0,0 +1,126 @@
+(* VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ocaml/src/ref.ml) *)
+(* 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. *)
+(* Identity: name+tag, written `name$tag` (§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. *)
+
+module V = Value
+
+let max_ref = 1024
+
+let isnamehead c =
+  ('a' <= c && c <= 'z') || ('A' <= c && c <= 'Z') || '@' = c
+
+let isnamebody c =
+  ('a' <= c && c <= 'z')
+  || ('A' <= c && c <= 'Z')
+  || ('0' <= c && c <= '9')
+  || '.' = c || '~' = c || '_' = c || '-' = c || '/' = c
+
+let istagchar c =
+  ('a' <= c && c <= 'z')
+  || ('A' <= c && c <= 'Z')
+  || ('0' <= c && c <= '9')
+  || '.' = c || '~' = c || '_' = c || '-' = c
+
+let namely name =
+  let n = String.length name in
+  n > 0 && n <= max_ref
+  && isnamehead name.[0]
+  &&
+  let ok = ref true in
+  String.iteri (fun i c -> if 0 < i && not (isnamebody c) then ok := false) name;
+  !ok
+
+let tagly tag =
+  let n = String.length tag in
+  (* The empty tag is an ordinary tag (§4 rule 2). The single-instance
+     case writes no tag and never learns tags exist. *)
+  if 0 = n then true
+  else if n > max_ref then false
+  else
+    let ok = ref true in
+    String.iter (fun c -> if not (istagchar c) then ok := false) tag;
+    !ok
+
+(* A non-string is not a name. Every port has to answer this the same
+   way, and `ref/name` pins it for numbers, nulls and maps alike. *)
+let checkname name = V.is_str name && namely (V.as_str name)
+let checktag tag = V.is_str tag && tagly (V.as_str tag)
+
+(* Split on the FIRST `$`. Nothing in the grammar decides this — `$` is
+   in neither character class — so the corpus is the arbiter (§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 split s =
+  match String.index_opt s '$' with
+  | None -> (s, "")
+  | Some cut ->
+    (String.sub s 0 cut, String.sub s (cut + 1) (String.length s - cut - 1))
+
+let parseref str =
+  if not (V.is_str str) then Types.fail "plugin_bad_name" "ref must be a string";
+  let name, tag = split (V.as_str str) in
+  if not (namely name) then
+    Types.fail "plugin_bad_name"
+      ("invalid plugin name: " ^ name)
+      ~details:(Types.details1 "name" (V.vstr name));
+  if not (tagly tag) then
+    Types.fail "plugin_bad_tag"
+      ("invalid plugin tag: " ^ tag)
+      ~details:(Types.details2 "name" (V.vstr name) "tag" (V.vstr tag));
+  let out = V.vmap () in
+  V.set out "name" (V.vstr name);
+  V.set out "tag" (V.vstr tag);
+  out
+
+(* An empty tag NEVER writes the separator, which is the half of
+   canonicalization formatref owns: parse tolerates `stripe$`, format
+   never produces it, so a round trip is idempotent. *)
+let formatref name tag =
+  let tagok = V.is_null tag || V.is_str tag in
+  let t = if V.is_str tag then V.as_str tag else "" in
+  if not (checkname name) then
+    Types.fail "plugin_bad_name"
+      ("invalid plugin name: " ^ (if V.is_str name then V.as_str name else ""))
+      ~details:
+        (Types.details1 "name" (if V.is_null name then V.vnull else name));
+  if (not tagok) || not (tagly t) then
+    Types.fail "plugin_bad_tag"
+      ("invalid plugin tag: " ^ t)
+      ~details:
+        (Types.details2 "name" name "tag"
+           (if V.is_null tag then V.vstr "" else tag));
+  if "" = t then V.as_str name else V.as_str name ^ "$" ^ t
+
+let canonref str =
+  let r = parseref str in
+  formatref (V.get r "name") (V.get r "tag")
+
+let canonrefs str = canonref (V.vstr str)
+
+(* The canonical ref this string denotes, or None if it denotes none —
+   the TOLERANT half of `canonref`, and the one a requirement name
+   needs (§11.1). Capability names are free-form, so `2fa` is a good one
+   and no ref could be called that; `canonref` RAISES on those, and
+   asking it "is this a ref?" made a legal document kill the host.
+
+   An `option`, so a caller cannot mistake "not a ref" for "the empty
+   ref". *)
+let tryref str =
+  let name, tag = split str in
+  if (not (namely name)) || not (tagly tag) then None
+  else Some (if "" = tag then name else name ^ "$" ^ tag)
+
+(* `canonref` for internal callers that want the input back unchanged
+   when it is not well formed. NEVER use where a bad ref must be
+   reported — the corpus pins plugin_bad_name at every public entry. *)
+let canon str = match tryref str with Some r -> r | None -> str
+
+(* The name half, for internal callers that only compare. *)
+let refname str =
+  let name, _ = split str in
+  if namely name then name else str

package/project/.sdk/tm/ocaml/feature/secrets/plugin/resolve.ml

@@ -0,0 +1,62 @@
+(* VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ocaml/src/resolve.ml) *)
+(* 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. *)
+(* Dynamic resolution (§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 — ocaml among them — and it is why §15.4 puts real module
+   loading in per-port integration tests rather than here. *)
+
+module V = Value
+
+let pushuniq out id =
+  if not (List.exists (fun v -> V.as_str v = id) (V.items out)) then
+    V.push out (V.vstr id)
+
+let default_prefix = [ "@voxgig/plugin-"; "voxgig-plugin-"; "plugin-"; "" ]
+
+let resolvecandidates name sources =
+  let out = V.vlist () in
+  let n = if V.is_str name then V.as_str name else "" in
+  (* A SCOPED NAME RESOLVES VERBATIM ONLY (§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 0 < String.length n && '@' = n.[0] then (V.push out (V.vstr n); out)
+  else if not (V.is_list sources && 0 < V.len sources) then begin
+    List.iter (fun p -> pushuniq out (p ^ n)) default_prefix;
+    out
+  end
+  else begin
+    List.iter
+      (fun src ->
+        let kind = V.as_str (V.get src "kind") in
+        if "module" = kind then begin
+          let prefix = V.get src "prefix" in
+          if V.is_list prefix && 0 < V.len prefix then
+            List.iter (fun p -> pushuniq out (V.as_str p ^ n)) (V.items prefix)
+          else pushuniq out n
+        end
+        else if "path" = kind then begin
+          let dir = V.as_str (V.get src "dir") in
+          (* Trailing slashes are trimmed, so `lib/` and `lib` give one
+             id rather than two spellings of it. *)
+          let e = ref (String.length dir) in
+          while 0 < !e && '/' = dir.[!e - 1] do decr e done;
+          pushuniq out (String.sub dir 0 !e ^ "/" ^ n)
+        end)
+      (V.items sources);
+    out
+  end
+
+(* A MODULE PATH IS NOT A NAME (§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.
+
+   Loading from an explicit location bypasses candidate generation
+   entirely: `from` is passed to the resolver verbatim. *)
+let resolvefrom from = V.oflist [ (if V.is_null from then V.vnull else from) ]

package/project/.sdk/tm/ocaml/feature/secrets/plugin/types.ml

@@ -0,0 +1,97 @@
+(* VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ocaml/src/types.ml) *)
+(* 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. *)
+(* Errors, and the raise mechanism (§12).
+
+   A REAL EXCEPTION. The canonical raises: a failing call abandons the
+   rest of the function, and the corpus is full of entries that assert
+   exactly what survived a raise mid-sequence (`resource/unwind`,
+   `lifecycle/fail`). OCaml has exceptions, so the port uses them —
+   unlike `c`, which has to build the same semantics out of
+   `setjmp`/`longjmp` and an arena.
+
+   Ports compare by CODE and never by message: wording is a port's own
+   business. The FORMAT is pinned, because a parseable message is what
+   makes a log searchable across twenty languages. *)
+
+module V = Value
+
+type error = {
+  code : string;
+  text : string;
+  details : V.t;
+  message : string;
+}
+
+exception Plugin_error of error
+
+(* §12's detail fields, IN THIS FIXED ORDER. The order is part of the
+   contract: an earlier draft named six fields while other sections
+   promised diagnostics with nowhere to go, which would have left each
+   port inventing its own order and breaking message parity. *)
+let detail_order =
+  [ "host"; "ref"; "name"; "tag"; "point"; "key"; "capability";
+    "range"; "version"; "match"; "candidates"; "cycle"; "holders";
+    "refs"; "path"; "cause" ]
+
+let formaterror code text details =
+  (* Values render as COMPACT JSON, so a value containing a space or a
+     bracket cannot break the parse and a list renders as an array. The
+     bracket is absent entirely when no field applies. *)
+  let parts =
+    List.filter_map
+      (fun k ->
+        if V.has details k then Some (k ^ "=" ^ V.json (V.get details k))
+        else None)
+      detail_order
+  in
+  let head = "plugin/" ^ code ^ ": " ^ text in
+  match parts with
+  | [] -> head
+  | _ -> head ^ " [" ^ String.concat " " parts ^ "]"
+
+let fail ?details code text =
+  let details = match details with Some d -> d | None -> V.vmap () in
+  raise
+    (Plugin_error
+       { code; text; details; message = formaterror code text details })
+
+let details1 k v =
+  let d = V.vmap () in
+  V.set d k v;
+  d
+
+let details2 k1 v1 k2 v2 =
+  let d = V.vmap () in
+  V.set d k1 v1;
+  V.set d k2 v2;
+  d
+
+(* Deep merge, struct's semantics: maps merge, everything else
+   replaces. §16 permits voxgig/struct for this and OCaml has no port
+   of it. *)
+let rec mergevalue a b =
+  if not (V.is_map a && V.is_map b) then b
+  else begin
+    let out = V.vmap () in
+    List.iter (fun k -> V.set out k (V.get a k)) (V.keys a);
+    List.iter
+      (fun k ->
+        let bv = V.get b k in
+        let av = V.get out k in
+        if V.is_map av && V.is_map bv then V.set out k (mergevalue av bv)
+        else V.set out k bv)
+      (V.keys b);
+    out
+  end
+
+(* §11.1's partial match: every leaf in `want` must be present and
+   equal in `have`; keys not mentioned are not checked. *)
+let rec matchvalue want have =
+  if V.is_null want then true
+  else if V.is_map want then
+    V.is_map have
+    && List.for_all
+         (fun k -> V.has have k && matchvalue (V.get want k) (V.get have k))
+         (V.keys want)
+  else V.same want have