@voxgig/sdkgen 4.10.0 → 4.11.0

package/project/.sdk/tm/cpp/feature/secrets/plugin/host.hpp

@@ -0,0 +1,250 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/host.hpp)
+// 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.
+/* The host: the lifecycle state machine (§5), extension points (§6),
+ * and resource capture (§8).
+ *
+ * TWO RULES SHAPE EVERY METHOD BELOW.
+ *
+ * Transitions are SEQUENTIAL (§5.2). One at a time, in call order,
+ * never interleaved; a transition triggered from inside a lifecycle
+ * callback is `plugin_reentrant`. A hard rule, because it is the only
+ * way the semantics can be identical in Go, in Ruby and in
+ * single-threaded JavaScript — and in C++, which has no event loop to
+ * hide behind.
+ *
+ * Reconciliation is EAGER (§18's portability budget). A transition
+ * settles by running the state machine to a fixed point, not by
+ * suspending on a future. */
+
+#ifndef VOXGIG_PLUGIN_HOST_HPP
+#define VOXGIG_PLUGIN_HOST_HPP
+
+#include <functional>
+#include <map>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "catalog.hpp"
+#include "point.hpp"
+#include "types.hpp"
+#include "value.hpp"
+
+namespace plugin {
+
+class Host;
+using HostPtr = std::shared_ptr<Host>;
+
+/* A scope release: a closure, so an instance's teardown captures
+ * whatever it needs rather than being handed a void* the way c must. */
+using Release = std::function<void()>;
+
+struct HostOptions {
+  CatalogPtr catalog;
+  V reserved;        /* list of names */
+  V keys;            /* {instance, default} */
+  V defaults;        /* {name -> options} */
+  V profile;
+  /* {point -> {kind, mode, exclusive, default, pin}}; the chain base is
+   * a function, so it rides alongside rather than inside the map. */
+  V points;
+  std::map<std::string, Hook> bases;
+  /* §11.3. `restart` (the default) treats provider replacement as an
+   * ordinary runtime operation. `hold` is the strict reading —
+   * deactivating a required instance is `plugin_dependency_held`. NOT
+   * the default, because a station that cannot swap a provider without
+   * a restart has lost the argument for having a plugin system. */
+  std::string dependency;
+};
+
+struct DeclareSpec {
+  std::string definition;
+  V options;
+  V order;
+  bool haspos = false;
+  double pos = 0;
+  std::string tag;
+  /* §9.1: set ONLY by `hostdeclare` — "the host declares those
+   * instances itself, after the user merge, and always wins". */
+  bool hostowned = false;
+};
+
+/* A scope entry. `acquire` hands back a shared_ptr to one so a plugin
+ * can release early; the scope keeps the entry, and unwinding it twice
+ * is a no-op. */
+struct ScopeEntry {
+  Release fn;
+  bool done = false;
+  /* `acquire` and `release` both count toward `open`; a nested host's
+   * teardown does NOT — a teardown is not an acquisition, and the inner
+   * host keeps its own counter (`nest/open`). */
+  bool counts = true;
+};
+using AcquireHandle = std::shared_ptr<ScopeEntry>;
+
+class Inst {
+ public:
+  /* --- identity and configuration, as callbacks see it -------------- */
+  const std::string& ref() const { return ref_; }
+  std::string name() const;
+  std::string tag() const;
+  const V& options() const { return options_; }
+  const V& state() const { return state_; }
+  Host& host() const { return *owner_; }
+
+  /* --- what a definition declares ----------------------------------- */
+  void bind(const std::string& point, Hook hook, ChainFn chain, const V& band);
+  void bindhook(const std::string& point, Hook hook, const V& band);
+  void bindchain(const std::string& point, ChainFn chain, const V& band);
+  void exportvalue(const std::string& key, const V& value);
+  void provides(const V& p);
+  /* Returns a handle a plugin can hand back early. The scope still
+   * holds the entry and unwinding it twice is a no-op — releasing early
+   * must not make teardown wrong. */
+  AcquireHandle acquire();
+  void giveback(const AcquireHandle& handle);
+  void release(Release fn);
+  V position(const std::string& point) const;
+  HostPtr nest(const HostOptions& opts);
+
+  /* --- observation --------------------------------------------------- */
+  const std::string& status() const { return status_; }
+  double seq() const { return seq_; }
+  double pos() const { return pos_; }
+  HostPtr inner() const { return inner_; }
+
+ private:
+  friend class Host;
+
+  std::string ref_;
+  DefinitionPtr def_;
+  std::string status_ = "declared";
+  double pos_ = 0;
+  double seq_ = 0;
+  V options_ = vmap();
+  V state_ = vmap();
+  V order_;
+  /* §11.4's ALWAYS-RELUCTANT rebinding, made concrete: the provider ref
+   * this instance's activation actually selected, per requirement name.
+   * Recomputing the best candidate on every question silently re-points
+   * a live consumer at any better-ranked newcomer, and then losing the
+   * provider it was really using does not restart it. */
+  V selected_ = vmap();
+  /* §9.6's `active: false`. THE BAR OUTLIVES THE APPLY THAT SET IT: a
+   * flag consulted only while `apply` ran let a later direct `ready`
+   * bring the instance live, which is the config switch it exists to be
+   * silently ignored. */
+  bool barred_ = false;
+  V unmet_ = vlist();
+  std::vector<AcquireHandle> scope_;
+  /* Declared in `define`, inserted only when activation SUCCEEDS
+   * (§8.1). Holding them until then is what makes a failed activate
+   * leave nothing behind. */
+  std::vector<Bound> bindings_;
+  HostPtr inner_;
+  /* Declared in `define`, and VISIBLE while merely `loaded` (§11): they
+   * are data, and hiding them would make the loaded state useless for
+   * introspection. */
+  V exports_ = vmap();
+  V provides_ = vlist();
+  Host* owner_ = nullptr;
+};
+
+using InstPtr = std::shared_ptr<Inst>;
+
+class Host {
+ public:
+  explicit Host(const HostOptions& opts);
+
+  Catalog& catalog() { return *catalog_; }
+  CatalogPtr catalogptr() { return catalog_; }
+  void define(const DefinitionPtr& def) { catalog_->add(def); }
+
+  /* --- the state machine -------------------------------------------- */
+  InstPtr declare(const std::string& ref, const DeclareSpec& spec);
+  InstPtr load(const std::string& ref, const DeclareSpec& spec);
+  InstPtr activate(const std::string& ref);
+  InstPtr deactivate(const std::string& ref);
+  void unload(const std::string& ref);
+  InstPtr ready(const std::string& ref);
+  void close();
+  void apply(const V& doc, const V& profile);
+  void setoptions(const std::string& ref, const V& patch);
+  std::string autotag(const std::string& name) const;
+
+  /* --- observation --------------------------------------------------- */
+  /* Introspection NEVER advances the state (§5.2). A status page must
+   * not be a way to accidentally import twenty packages. */
+  V list() const;
+  InstPtr instance(const std::string& ref) const;
+  V observable(const V& result, bool hasresult) const;
+  /* A COPY, not the live list: the canonical is `trace: () => events.slice()`, and `observable` already copies the log. Returning the live list lets a caller append to or delete from the host's own event record — application observation code fabricating or erasing lifecycle history. */
+  V trace() const;
+  V order(const std::string& point) const;
+  V positionof(const std::string& ref, const std::string& point) const;
+
+  /* --- points --------------------------------------------------------- */
+  V emit(const std::string& point, const V& arg);
+  V call(const std::string& point, const V& arg);
+  V provider(const std::string& point, const V& arg);
+  V shadowed(const std::string& point) const;
+  V exports(const std::string& spec) const;
+  V capability(const std::string& name) const;
+
+ private:
+  friend class Inst;
+
+  InstPtr find(const std::string& ref) const;
+  std::vector<std::string> sortedrefs() const;
+  void guard() const;
+  InstPtr need(const std::string& ref) const;
+  void checkreserved(const std::string& ref) const;
+  void run(const InstPtr& e, const std::string& at);
+  V unwind(const InstPtr& e);
+  void releasecheck(const InstPtr& e, const V& errors);
+  V providersof(const V& req) const;
+  V unmetof(const InstPtr& e) const;
+  std::string chosen(const InstPtr& e, const V& req, bool remember) const;
+  V boundproviders(const InstPtr& e) const;
+  V consumersof(const std::string& ref) const;
+  V holdersof(const std::string& ref) const;
+  void held(const InstPtr& e) const;
+  V graphnodes() const;
+  std::vector<Bound> boundon(const std::string& point) const;
+  V pointspec(const std::string& point) const;
+  void cascade(const InstPtr& provider, const V& seen);
+  void reconcile();
+  V shapeof(const std::string& ref) const;
+
+  CatalogPtr catalog_;
+  V reserved_;
+  V keys_;
+  V defaults_;
+  V profile_;
+  V points_;
+  std::map<std::string, Hook> bases_;
+  std::string dependency_ = "restart";
+  /* Set for the duration of a bulk teardown, so `held` knows this is a
+   * coordinated operation rather than an ad-hoc deactivation. */
+  bool coordinated_ = false;
+
+  std::vector<InstPtr> instances_;
+  V log_ = vlist();
+  V events_ = vlist();
+  double seqn_ = 0;
+  double open_ = 0;
+  bool intransition_ = false;
+  /* WHICH callback is running, not merely that one is. §8.1 puts
+   * resource capture in `activate` and §8.3 says `release` outside
+   * `activate` is `plugin_release_scope` — and a boolean alone cannot
+   * tell `activate` from `define`, so it admitted an acquire in
+   * `define` whose scope `unload` would never unwind. */
+  std::string phase_;
+};
+
+HostPtr makehost(const HostOptions& opts);
+
+}  // namespace plugin
+
+#endif

package/project/.sdk/tm/cpp/feature/secrets/plugin/order.cpp

@@ -0,0 +1,250 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/order.cpp)
+// 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. */
+
+#include "order.hpp"
+
+#include <algorithm>
+
+#include "ref.hpp"
+
+namespace plugin {
+
+static double bandof(const V& 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. */
+  V band = get(get(b, "order"), "band");
+  return isnum(band) ? asnum(band) : 0.0;
+}
+
+static double posof(const V& b) {
+  V p = get(b, "pos");
+  return isnum(p) ? asnum(p) : 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`. */
+struct Ready {
+  V binding;
+  size_t seq;
+};
+
+/* THE RANK IS TOTAL, and the third key is why. Band and pos can both
+   tie — `declare` defaults `pos` to the registry size, so an unload
+   followed by a fresh declare reuses a surviving instance's — and
+   `std::sort` is not stable, so the topological order would differ from
+   every other port's. The DECLARATION SEQUENCE (the index `order` fed
+   them in) breaks the last tie, which is what the stable-sort ports get
+   for free. */
+static bool ranks(const Ready& x, const Ready& y) {
+  double ab = bandof(x.binding), bb = bandof(y.binding);
+  if (ab != bb) return ab < bb;
+  double ap = posof(x.binding), bp = posof(y.binding);
+  if (ap != bp) return ap < bp;
+  return x.seq < y.seq;
+}
+
+/* Was a constraint actually declared? An ABSENT one and an EMPTY LIST
+ * are both "no constraint"; only a non-empty spelling is an edge. */
+static bool declared(const V& spec) {
+  if (islist(spec)) return 0 < len(spec);
+  if (isstr(spec)) return !asstr(spec).empty();
+  return 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. */
+static std::vector<std::string> targets(const V& spec, const V& nodes) {
+  std::vector<std::string> hit;
+  size_t sn = islist(spec) ? len(spec) : 1;
+  for (size_t si = 0; si < sn; si++) {
+    V oneval = islist(spec) ? at(spec, si) : spec;
+    if (!isstr(oneval)) continue;
+    const std::string one = asstr(oneval);
+    for (size_t i = 0; i < len(nodes); i++) {
+      const std::string ref = asstr(get(at(nodes, i), "ref"));
+      if (hit.end() != std::find(hit.begin(), hit.end(), ref)) continue;
+      if (ref == one || refname(ref) == one) hit.push_back(ref);
+    }
+  }
+  return 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. */
+static V applypin(const V& order, const V& edges, const V& pin) {
+  if (!ismap(pin)) return order;
+
+  std::vector<std::string> out;
+  for (size_t i = 0; i < len(order); i++) out.push_back(asstr(at(order, i)));
+
+  /* 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. */
+  for (const auto& name : sortedkeys(pin)) {
+    const std::string want = asstr(get(pin, name));
+    size_t idx = out.size();
+    for (size_t j = 0; j < out.size(); j++) {
+      if (refname(out[j]) == name) { idx = j; break; }
+    }
+    if (out.size() == idx) continue;
+
+    /* `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. */
+    bool wantfirst = "first" == want || "outermost" == want;
+    std::string ref = out[idx];
+    out.erase(out.begin() + static_cast<long>(idx));
+    if (wantfirst) out.insert(out.begin(), ref);
+    else out.push_back(ref);
+  }
+
+  /* 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. */
+  V index = vmap();
+  for (size_t i = 0; i < out.size(); i++) {
+    set(index, out[i], vnum(static_cast<double>(i)));
+  }
+  for (const auto& from : sortedkeys(edges)) {
+    V tos = get(edges, from);
+    for (size_t j = 0; j < len(tos); j++) {
+      const std::string to = asstr(at(tos, j));
+      if (asnum(get(index, from)) > asnum(get(index, to))) {
+        V d = vmap();
+        set(d, "before", vstr(from));
+        set(d, "after", vstr(to));
+        fail("plugin_order_pinned",
+             "a pin would move a binding an ordering constrains: " + from +
+                 " must precede " + to,
+             d);
+      }
+    }
+  }
+
+  V result = vlist();
+  for (const auto& r : out) push(result, vstr(r));
+  return result;
+}
+
+V resolveorder(const V& bindings, const V& pin) {
+  const size_t n = len(bindings);
+
+  V byref = vmap();
+  for (size_t i = 0; i < n; i++) {
+    set(byref, asstr(get(at(bindings, i), "ref")), at(bindings, i));
+  }
+
+  /* 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. */
+  V edges = vmap();
+  for (size_t i = 0; i < n; i++) {
+    set(edges, asstr(get(at(bindings, i), "ref")), vlist());
+  }
+
+  for (size_t i = 0; i < n; i++) {
+    V b = at(bindings, i);
+    const std::string bref = asstr(get(b, "ref"));
+    V o = get(b, "order");
+    V after = get(o, "after");
+    V before = get(o, "before");
+    if (declared(after)) {
+      for (const auto& t : targets(after, bindings)) push(get(edges, t), vstr(bref));
+    }
+    if (declared(before)) {
+      for (const auto& t : targets(before, bindings)) push(get(edges, bref), vstr(t));
+    }
+  }
+
+  /* Stable topological sort. */
+  V indeg = vmap();
+  for (size_t i = 0; i < n; i++) {
+    set(indeg, asstr(get(at(bindings, i), "ref")), vnum(0));
+  }
+  for (const auto& from : keys(edges)) {
+    V tos = get(edges, from);
+    for (size_t j = 0; j < len(tos); j++) {
+      const std::string to = asstr(at(tos, j));
+      set(indeg, to, vnum(asnum(get(indeg, to)) + 1));
+    }
+  }
+
+  /* `seq` is the index the binding arrived at, and it never repeats: a
+     binding enters `ready` exactly once, either up front or when its
+     last edge clears. */
+  std::vector<Ready> ready;
+  size_t seq = 0;
+  for (size_t i = 0; i < n; i++) {
+    V b = at(bindings, i);
+    if (0 == asnum(get(indeg, asstr(get(b, "ref"))))) ready.push_back({b, seq++});
+  }
+
+  std::vector<std::string> out;
+  while (!ready.empty()) {
+    std::sort(ready.begin(), ready.end(), ranks);
+    V next = ready.front().binding;
+    ready.erase(ready.begin());
+
+    const std::string nref = asstr(get(next, "ref"));
+    out.push_back(nref);
+    V tos = get(edges, nref);
+    for (size_t j = 0; j < len(tos); j++) {
+      const std::string to = asstr(at(tos, j));
+      double d = asnum(get(indeg, to)) - 1;
+      set(indeg, to, vnum(d));
+      if (0 == d) ready.push_back({get(byref, to), seq++});
+    }
+  }
+
+  if (out.size() != n) {
+    V stuck = vlist();
+    std::string names;
+    for (size_t i = 0; i < n; i++) {
+      const std::string ref = asstr(get(at(bindings, i), "ref"));
+      if (out.end() != std::find(out.begin(), out.end(), ref)) continue;
+      if (0 < len(stuck)) names += " -> ";
+      names += ref;
+      push(stuck, vstr(ref));
+    }
+    fail("plugin_order_cycle", "before/after constraints cycle: " + names,
+         details1("cycle", stuck));
+  }
+
+  V ordered = vlist();
+  for (const auto& r : out) push(ordered, vstr(r));
+  return applypin(ordered, edges, pin);
+}
+
+}  // namespace plugin

package/project/.sdk/tm/cpp/feature/secrets/plugin/order.hpp

@@ -0,0 +1,22 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/order.hpp)
+// 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) — constraints, then bands, then declaration position.
+ * CONSTRAINTS BEAT BANDS so the correct tool wins when both are
+ * present; a band chosen by trial and error to fix an ordering bug is a
+ * bug wearing a number. See order.cpp. */
+
+#ifndef VOXGIG_PLUGIN_ORDER_HPP
+#define VOXGIG_PLUGIN_ORDER_HPP
+
+#include "types.hpp"
+#include "value.hpp"
+
+namespace plugin {
+
+/* [{ref, pos, order?}] plus an optional host pin -> [ref] */
+V resolveorder(const V& bindings, const V& pin);
+
+}  // namespace plugin
+
+#endif

package/project/.sdk/tm/cpp/feature/secrets/plugin/point.cpp

@@ -0,0 +1,110 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/point.cpp)
+// 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). See point.hpp for the closure representation. */
+
+#include "point.hpp"
+
+#include <algorithm>
+
+namespace plugin {
+
+/* The composition, built as nested closures rather than walked by
+ * index: `next` is a real callable, so a binding writes `next(arg)` the
+ * way the canonical does. Identical to `b1(b2(b3(base)))`. */
+static V callat(const std::vector<Bound>& bs, size_t i, const Hook& base,
+                const V& arg) {
+  if (i >= bs.size()) return base ? base(arg) : arg;
+  Next next = [&bs, i, &base](const V& a) { return callat(bs, i + 1, base, a); };
+  return bs[i].chain(next, arg);
+}
+
+V pointcall(const std::vector<Bound>& bindings, const Hook& base, const V& arg) {
+  return callat(bindings, 0, base, arg);
+}
+
+V pointemit(const std::vector<Bound>& bindings, const std::string& mode,
+            const V& arg, V& errors) {
+  errors = vlist();
+
+  if ("bail" == mode) {
+    /* Stops at the first binding that RETURNS A VALUE — the "handled,
+     * stop" case. A NULLPTR OR A NULL DECLINES.
+     *
+     * 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, and C++ has one too.
+     * 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). */
+    for (const auto& b : bindings) {
+      V v = b.hook(arg);
+      if (!isnull(v)) return v;
+    }
+    return nullptr;
+  }
+
+  bool raising = "emit" == mode;
+  for (const auto& b : bindings) {
+    if (raising) {
+      /* `emit` raises synchronously; the collecting modes gather. */
+      b.hook(arg);
+      continue;
+    }
+    try {
+      b.hook(arg);
+    }
+    catch (const PluginError& e) {
+      V rec = vmap();
+      set(rec, "code", vstr(e.code));
+      set(rec, "message", vstr(e.message));
+      push(errors, rec);
+    }
+  }
+  return nullptr;
+}
+
+long pointprovider(const std::vector<Bound>& bindings, bool exclusive,
+                   V& shadowed) {
+  shadowed = vlist();
+  if (bindings.empty()) return -1;
+
+  std::vector<size_t> ranked(bindings.size());
+  for (size_t i = 0; i < bindings.size(); i++) ranked[i] = i;
+
+  if (exclusive && 1 < bindings.size()) {
+    std::vector<std::string> refs;
+    for (const auto& b : bindings) refs.push_back(b.ref);
+    /* Sorted, so the message names the same pair whatever order the
+     * bindings arrived in. */
+    std::sort(refs.begin(), refs.end());
+    V list = vlist();
+    std::string names;
+    for (size_t i = 0; i < refs.size(); i++) {
+      if (0 < i) names += ", ";
+      names += refs[i];
+      push(list, vstr(refs[i]));
+    }
+    fail("plugin_point_exclusive",
+         "point is exclusive and has " + std::to_string(bindings.size()) +
+             " bindings: " + names,
+         details1("refs", list));
+  }
+
+  /* HIGHEST band wins, unlike hook and chain; ties break by ref sort,
+   * which is a TOTAL order, so the unstable sort cannot show. */
+  std::sort(ranked.begin(), ranked.end(), [&bindings](size_t a, size_t b) {
+    if (bindings[a].band != bindings[b].band) {
+      return bindings[a].band > bindings[b].band;
+    }
+    return bindings[a].ref < bindings[b].ref;
+  });
+
+  for (size_t i = 1; i < ranked.size(); i++) {
+    push(shadowed, vstr(bindings[ranked[i]].ref));
+  }
+  return static_cast<long>(ranked[0]);
+}
+
+}  // namespace plugin