@voxgig/sdkgen 4.10.0 → 4.11.0

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

@@ -0,0 +1,205 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/env.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.
+/* Environment overrides (§9.5) — level 7 of the ladder.
+ *
+ * One prefix, so nothing drifts: `VOXGIG_PLUGIN_*`.
+ *
+ *   VOXGIG_PLUGIN_PROFILE            the profile name
+ *   VOXGIG_PLUGIN_<REF>_<PATH>       one option
+ *   VOXGIG_PLUGIN_ACTIVE/INACTIVE    comma-separated refs, INACTIVE wins
+ *
+ * THE ENCODING IS LOSSY, AND THIS SAYS SO RATHER THAN PRETENDING
+ * OTHERWISE. Ref and path are upper-snake with `$` -> `__` and `.` ->
+ * `_`. But `_` is legal in a name and in a tag, and the mapping folds
+ * case, so `retry$fast` and `retry__fast` both encode to `RETRY__FAST`.
+ *
+ * Rather than restrict a grammar the rest of the stack already uses,
+ * the host DETECTS THE COLLISION: it encodes every ref it holds, and a
+ * key two refs claim is `plugin_env_ambiguous`, naming both. */
+
+#include "env.hpp"
+
+#include <algorithm>
+
+#include "ref.hpp"
+
+namespace plugin {
+
+static const char* const PREFIX = "VOXGIG_PLUGIN_";
+
+std::string encoderef(const std::string& ref) {
+  std::string out;
+  out.reserve(ref.size() * 2);
+  for (char c : ref) {
+    if ('$' == c) out += "__";
+    else if ('.' == c) out += '_';
+    else if ('a' <= c && 'z' >= c) out += static_cast<char>(c - 'a' + 'A');
+    else out += c;
+  }
+  return out;
+}
+
+static void checkreserved(const std::string& ref, const V& reserved) {
+  if (!islist(reserved) || 0 == len(reserved)) return;
+  const std::string name = refname(ref);
+  for (size_t i = 0; i < len(reserved); i++) {
+    if (isstr(at(reserved, i)) && asstr(at(reserved, i)) == name) {
+      fail("plugin_ref_reserved", "ref is reserved by the host: " + ref,
+           details1("ref", vstr(ref)));
+    }
+  }
+}
+
+/* Values parse as JSON, FALLING BACK TO STRING — 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. */
+static V parsevalue(const std::string& v) {
+  std::string err;
+  V parsed = parsejson(v, err);
+  return parsed ? parsed : vstr(v);
+}
+
+static std::string lower(std::string s) {
+  for (char& c : s) {
+    if ('A' <= c && 'Z' >= c) c = static_cast<char>(c - 'A' + 'a');
+  }
+  return s;
+}
+
+V applyenv(const V& input) {
+  V env = get(input, "env");
+  if (!ismap(env)) env = vmap();
+  V refsin = get(input, "refs");
+  V reserved = get(input, "reserved");
+
+  V out = vmap();
+  V options = vmap();
+  V active = vlist();
+  V inactive = vlist();
+  set(out, "options", options);
+  set(out, "active", active);
+  set(out, "inactive", inactive);
+
+  /* Encode every ref the host holds, and refuse a key that two of them
+   * claim. Done UP FRONT so the collision is reported even when no
+   * environment variable exercises it — a latent ambiguity is still an
+   * ambiguity, and finding it at deploy time is the failure this exists
+   * to prevent. */
+  V byencoded = vmap();
+  if (islist(refsin)) {
+    for (size_t i = 0; i < len(refsin); i++) {
+      const std::string r = canonref(at(refsin, i));
+      const std::string e = encoderef(r);
+      V list = get(byencoded, e);
+      if (isnull(list)) { list = vlist(); set(byencoded, e, list); }
+      push(list, vstr(r));
+    }
+  }
+
+  auto encs = sortedkeys(byencoded);
+  for (const auto& e : encs) {
+    V claims = get(byencoded, e);
+    if (1 < len(claims)) {
+      std::string a = asstr(at(claims, 0));
+      std::string b = asstr(at(claims, 1));
+      const std::string& lo = a <= b ? a : b;
+      const std::string& hi = a <= b ? b : a;
+      V pair = vlist();
+      push(pair, vstr(lo));
+      push(pair, vstr(hi));
+      V d = vmap();
+      set(d, "encoded", vstr(e));
+      set(d, "refs", pair);
+      fail("plugin_env_ambiguous",
+           "refs collide in the environment encoding as " + e + ": " + lo +
+               ", " + hi,
+           d);
+    }
+  }
+
+  /* LONGEST encoded ref first, so `retry$fast` wins over `retry` on
+   * `RETRY__FAST_MIN`. Shortest-first would read the tag as a path. */
+  auto order = encs;
+  std::sort(order.begin(), order.end(),
+            [](const std::string& a, const std::string& b) {
+              if (a.size() != b.size()) return a.size() > b.size();
+              return a < b;
+            });
+
+  const size_t plen = std::string(PREFIX).size();
+
+  for (const auto& key : sortedkeys(env)) {
+    if (0 != key.compare(0, plen, PREFIX)) continue;
+    const std::string rest = key.substr(plen);
+    const std::string val = asstr(get(env, key));
+
+    if ("PROFILE" == rest) {
+      set(out, "profile", vstr(val));
+      continue;
+    }
+
+    if ("ACTIVE" == rest || "INACTIVE" == rest) {
+      bool isactive = "ACTIVE" == rest;
+      size_t p = 0;
+      while (p <= val.size()) {
+        size_t comma = val.find(',', p);
+        size_t end = (std::string::npos == comma) ? val.size() : comma;
+        size_t s = p;
+        while (s < end && (' ' == val[s] || '\t' == val[s])) s++;
+        size_t e = end;
+        while (e > s && (' ' == val[e - 1] || '\t' == val[e - 1])) e--;
+        if (e > s) {
+          const std::string c = canonref(vstr(val.substr(s, e - s)));
+          /* The reservation covers EVERY input layer (§9.1).
+           * VOXGIG_PLUGIN_INACTIVE=station is easier to set than
+           * editing a config file, and INACTIVE has the final word — so
+           * guarding documents alone would leave the one lever this
+           * mechanism exists to deny wide open. */
+          checkreserved(c, reserved);
+          push(isactive ? active : inactive, vstr(c));
+        }
+        if (std::string::npos == comma) break;
+        p = comma + 1;
+      }
+      continue;
+    }
+
+    std::string enc;
+    bool found = false;
+    for (const auto& cand : order) {
+      if (rest == cand ||
+          (rest.size() > cand.size() &&
+           0 == rest.compare(0, cand.size(), cand) && '_' == rest[cand.size()])) {
+        enc = cand;
+        found = true;
+        break;
+      }
+    }
+    if (!found) continue;   /* not for any ref this host holds */
+
+    const std::string ref = asstr(at(get(byencoded, enc), 0));
+    checkreserved(ref, reserved);
+
+    if (rest == enc) continue;   /* a ref with no path sets nothing */
+
+    std::string pathtext = rest.substr(enc.size() + 1);
+    V node = get(options, ref);
+    if (isnull(node)) { node = vmap(); set(options, ref, node); }
+
+    for (;;) {
+      size_t dot = pathtext.find('_');
+      if (std::string::npos == dot) break;
+      const std::string piece = lower(pathtext.substr(0, dot));
+      V next = get(node, piece);
+      if (!ismap(next)) { next = vmap(); set(node, piece, next); }
+      node = next;
+      pathtext = pathtext.substr(dot + 1);
+    }
+    set(node, lower(pathtext), parsevalue(val));
+  }
+
+  return out;
+}
+
+}  // namespace plugin

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

@@ -0,0 +1,25 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/env.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.
+/* Environment overrides (§9.5) — level 7 of the ladder. Pure: a
+ * function over a string map and a ref set, so the corpus tests it
+ * without touching a real environment. */
+
+#ifndef VOXGIG_PLUGIN_ENV_HPP
+#define VOXGIG_PLUGIN_ENV_HPP
+
+#include <string>
+
+#include "types.hpp"
+#include "value.hpp"
+
+namespace plugin {
+
+/* `retry$fast` -> `RETRY__FAST`. Lossy on purpose; see env.cpp. */
+std::string encoderef(const std::string& ref);
+
+V applyenv(const V& input);
+
+}  // namespace plugin
+
+#endif

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

@@ -0,0 +1,84 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/export.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.
+/* Exports (§11).
+ *
+ * THE UNQUALIFIED ALIAS IS THE INTERESTING PART. `retry/client`
+ * resolves to the UNTAGGED instance if one exists; if not, and exactly
+ * one tagged instance exports that key, it resolves to that one; if two
+ * do, it is `plugin_export_ambiguous` — deliberately diverging from
+ * seneca's silent last-wins, because with multi-instance as a headline
+ * feature an ambiguous alias is a defect waiting for production. */
+
+#include "export.hpp"
+
+#include <algorithm>
+
+#include "ref.hpp"
+
+namespace plugin {
+
+V resolveexport(const V& spec, const V& exported) {
+  const std::string s = isstr(spec) ? asstr(spec) : "";
+  size_t cut = s.find('/');
+  if (std::string::npos == cut) {
+    fail("plugin_export_ambiguous", "export spec needs a key: " + s,
+         details1("spec", vstr(s)));
+  }
+  const std::string head = s.substr(0, cut);
+  const std::string key = s.substr(cut + 1);
+
+  /* A fully qualified ref: exactly one answer or none.
+   *
+   * VALIDATING, not tolerant. The canonical calls `canonref(head)`,
+   * which RAISES — so `retry$bad!/client` is `plugin_bad_tag` and
+   * `2fa/client` is `plugin_bad_name`. Reading it with `tryref` turned
+   * a configuration typo into an ordinary missing export, which is the
+   * error the caller most needs to see, silently swallowed. */
+  const std::string want = canonref(head);
+  {
+    for (size_t i = 0; i < len(exported); i++) {
+      V e = at(exported, i);
+      if (asstr(get(e, "ref")) == want && asstr(get(e, "key")) == key) {
+        return get(e, "value");
+      }
+    }
+  }
+
+  /* An alias: the NAME, not a ref. Look at every instance of it. */
+  std::vector<V> byname;
+  for (size_t i = 0; i < len(exported); i++) {
+    V e = at(exported, i);
+    const std::string eref = asstr(get(e, "ref"));
+    if (refname(eref) == head && asstr(get(e, "key")) == key) byname.push_back(e);
+  }
+  if (byname.empty()) return nullptr;
+
+  /* The untagged instance wins outright when there is one. */
+  for (const auto& e : byname) {
+    if (std::string::npos == asstr(get(e, "ref")).find('$')) return get(e, "value");
+  }
+
+  if (1 == byname.size()) return get(byname[0], "value");
+
+  std::vector<std::string> refs;
+  for (const auto& e : byname) refs.push_back(asstr(get(e, "ref")));
+  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]));
+  }
+  V d = vmap();
+  set(d, "spec", vstr(s));
+  set(d, "refs", list);
+  fail("plugin_export_ambiguous",
+       "alias " + s + " matches " + std::to_string(byname.size()) +
+           " instances: " + names,
+       d);
+}
+
+}  // namespace plugin

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

@@ -0,0 +1,24 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/export.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.
+/* Exports (§11). An instance publishes values for other plugins and for
+ * the application. THE UNQUALIFIED ALIAS IS THE INTERESTING PART; see
+ * export.cpp. */
+
+#ifndef VOXGIG_PLUGIN_EXPORT_HPP
+#define VOXGIG_PLUGIN_EXPORT_HPP
+
+#include "types.hpp"
+#include "value.hpp"
+
+namespace plugin {
+
+/* `retry$fast/client` or the alias `retry/client`, against a list of
+ * {ref, key, value}. Answers nullptr for "no such export", which is not
+ * an error — `export/missing` pins that, and is why the answer is a
+ * nullptr rather than a null Value. */
+V resolveexport(const V& spec, const V& exported);
+
+}  // namespace plugin
+
+#endif

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

@@ -0,0 +1,222 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/graph.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.
+/* Whole-graph resolution (§11.4) — a phase, not a discovery.
+ *
+ * "Activate, and wait in `pending` if you must" is correct and, on its
+ * own, produces a terrible experience: apply twenty instances against a
+ * registry missing one thing and you get NINETEEN pending rows and no
+ * statement of what is actually wrong.
+ *
+ * `resolvegraph` is a PURE FUNCTION of the registry and the intended
+ * activation set. No callbacks run, no state changes, nothing is
+ * touched. It answers for the whole graph at once which instances can
+ * be live, and for each blocked one THE SPECIFIC REQUIREMENT that is
+ * unmet, and why.
+ *
+ * The failure mode being designed against is a famous one: OSGi's
+ * resolver is correct and its diagnostics are legendarily unusable. A
+ * resolver that says "blocked" without saying WHY has moved the problem
+ * rather than solved it, so `why` is part of the contract. */
+
+#include "graph.hpp"
+
+#include <algorithm>
+
+#include "capability.hpp"
+#include "ref.hpp"
+#include "version.hpp"
+
+namespace plugin {
+
+static V candidates(const V& byref, const V& name) {
+  V out = vlist();
+  /* A NODE SATISFIES ITS OWN REF (§11.1), and this is where the graph
+   * learned it. Considering only declared capabilities made `resolve`
+   * answer `absent` about a provider sitting right there and live —
+   * §11.4's whole job is explaining the graph the runtime reconciles,
+   * and it was explaining a different one. Canonical (§4 rule 5), and
+   * tolerant, because a capability name need not be a well-formed ref. */
+  std::string asref;
+  bool isaref = isstr(name) && tryref(asstr(name), asref);
+
+  for (const auto& r : sortedkeys(byref)) {
+    V node = get(byref, r);
+    V pos = get(node, "pos");
+    /* The ref match WINS OUTRIGHT for that node, as at runtime: one
+     * candidate, not two, for a node both named `b` and providing `b` —
+     * without the skip the blocked-chain explanation named it twice. */
+    if (isaref && r == asref) {
+      V prov = vmap();
+      set(prov, "name", name);
+      V cand = vmap();
+      set(cand, "ref", get(node, "ref"));
+      set(cand, "pos", isnum(pos) ? pos : vnum(0));
+      set(cand, "provides", prov);
+      push(out, cand);
+      continue;
+    }
+    V provides = get(node, "provides");
+    for (size_t j = 0; j < len(provides); j++) {
+      V p = at(provides, j);
+      if (same(get(p, "name"), name)) {
+        V cand = vmap();
+        set(cand, "ref", get(node, "ref"));
+        set(cand, "pos", isnum(pos) ? pos : vnum(0));
+        set(cand, "provides", p);
+        push(out, cand);
+      }
+    }
+  }
+  return out;
+}
+
+static V blockedof(const V& node, const V& unmet, const V& why) {
+  V out = vmap();
+  set(out, "ref", get(node, "ref"));
+  set(out, "unmet", unmet);
+  set(out, "why", why);
+  return out;
+}
+
+static V why1(const std::string& kind) {
+  V w = vmap();
+  set(w, "kind", vstr(kind));
+  return w;
+}
+
+static V sortedstrings(std::vector<std::string> v) {
+  std::sort(v.begin(), v.end());
+  V out = vlist();
+  for (const auto& s : v) push(out, vstr(s));
+  return out;
+}
+
+/* The FIRST unmet requirement, with the most specific explanation
+ * available. Order matters: "no provider at all" and "a provider at the
+ * wrong version" are different problems and a reader must not have to
+ * guess which they have. */
+static V firstunmet(const V& node, const V& byref, const V& resolved) {
+  V reqs = get(node, "requires");
+  for (size_t ri = 0; ri < len(reqs); ri++) {
+    V req = at(reqs, ri);
+    if (truthy(get(req, "optional"))) continue;
+
+    V name = get(req, "name");
+    V all = candidates(byref, name);
+    if (0 == len(all)) return blockedof(node, name, why1("absent"));
+
+    V ok = resolvecapability(req, all);
+    if (0 < len(ok)) {
+      /* A provider exists and matches — but if none of them is itself
+       * resolved, this node is blocked BEHIND it, and the chain is the
+       * useful answer rather than "unmet". */
+      bool live = false;
+      for (size_t i = 0; i < len(ok); i++) {
+        if (has(resolved, asstr(get(at(ok, i), "ref")))) { live = true; break; }
+      }
+      if (live) continue;
+
+      std::vector<std::string> chain;
+      for (size_t i = 0; i < len(ok); i++) {
+        chain.push_back(asstr(get(at(ok, i), "ref")));
+      }
+      V w = why1("blocked");
+      set(w, "chain", sortedstrings(chain));
+      return blockedof(node, name, w);
+    }
+
+    /* Providers exist and none matched. Say which test failed. */
+    V range = get(req, "range");
+    if (!isnull(range)) {
+      std::vector<std::string> found;
+      for (size_t i = 0; i < len(all); i++) {
+        V prov = get(at(all, i), "provides");
+        V version = get(prov, "version");
+        if (isnull(version) || !satisfiesq(version, range)) {
+          found.push_back(isnull(version) ? "(none)" : asstr(version));
+        }
+      }
+      if (!found.empty()) {
+        V w = why1("version");
+        set(w, "range", range);
+        set(w, "found", sortedstrings(found));
+        return blockedof(node, name, w);
+      }
+    }
+
+    V match = get(req, "match");
+    if (!isnull(match)) {
+      for (size_t i = 0; i < len(all); i++) {
+        V prov = get(at(all, i), "provides");
+        V attrs = get(prov, "attrs");
+        if (isnull(attrs)) attrs = vmap();
+        for (const auto& k : sortedkeys(match)) {
+          /* The same recursive partial match the selection applies, so
+           * a nested requirement that FAILED the selection is also the
+           * one the diagnosis names (§11.4). */
+          if (!has(attrs, k) || !capmatchvalue(get(match, k), get(attrs, k))) {
+            V w = why1("match");
+            set(w, "failing", vstr(k));
+            set(w, "want", get(match, k));
+            set(w, "found", get(attrs, k));
+            return blockedof(node, name, w);
+          }
+        }
+      }
+    }
+
+    return blockedof(node, name, why1("absent"));
+  }
+  return nullptr;
+}
+
+V resolvegraph(const V& nodes) {
+  V byref = vmap();
+  for (size_t i = 0; i < len(nodes); i++) {
+    V n = at(nodes, i);
+    set(byref, asstr(get(n, "ref")), n);
+  }
+
+  V resolved = vmap();
+
+  /* Fixed point: a node resolves when every mandatory requirement is
+   * met by an ALREADY-RESOLVED provider. Iterating to a fixed point is
+   * what makes a provider that is itself blocked propagate, rather than
+   * each node being judged against the raw registry. */
+  bool moved = true;
+  while (moved) {
+    moved = false;
+    for (size_t i = 0; i < len(nodes); i++) {
+      V n = at(nodes, i);
+      const std::string ref = asstr(get(n, "ref"));
+      if (has(resolved, ref)) continue;
+      if (!firstunmet(n, byref, resolved)) {
+        set(resolved, ref, vbool(true));
+        moved = true;
+      }
+    }
+  }
+
+  V blocked = vmap();
+  for (size_t i = 0; i < len(nodes); i++) {
+    V n = at(nodes, i);
+    const std::string ref = asstr(get(n, "ref"));
+    if (has(resolved, ref)) continue;
+    V why = firstunmet(n, byref, resolved);
+    if (why) set(blocked, ref, why);
+  }
+
+  V resolvedlist = vlist();
+  for (const auto& k : sortedkeys(resolved)) push(resolvedlist, vstr(k));
+
+  V blockedlist = vlist();
+  for (const auto& k : sortedkeys(blocked)) push(blockedlist, get(blocked, k));
+
+  V out = vmap();
+  set(out, "resolved", resolvedlist);
+  set(out, "blocked", blockedlist);
+  return out;
+}
+
+}  // namespace plugin

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

@@ -0,0 +1,21 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/graph.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.
+/* Whole-graph resolution (§11.4) — a pure function of the registry that
+ * answers which instances can be live, and for each blocked one THE
+ * SPECIFIC requirement that is unmet, and why. See graph.cpp. */
+
+#ifndef VOXGIG_PLUGIN_GRAPH_HPP
+#define VOXGIG_PLUGIN_GRAPH_HPP
+
+#include "types.hpp"
+#include "value.hpp"
+
+namespace plugin {
+
+/* [{ref, pos, provides?, requires?}] -> {resolved: [ref], blocked: [...]} */
+V resolvegraph(const V& nodes);
+
+}  // namespace plugin
+
+#endif