@voxgig/sdkgen 4.10.0 → 4.12.0

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

@@ -0,0 +1,230 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/depend.cpp)
+// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* Dependency cardinality, policy, and the restart graph (§11.3).
+ *
+ * TWO AXES, BOTH DECLARED BY THE DEFINITION THAT HAS THE REQUIREMENT,
+ * because only it knows what it can cope with:
+ *
+ *                | static (default)          | dynamic
+ *   -------------|---------------------------|--------------------------
+ *   mandatory    | unmet -> pending;         | unmet -> pending;
+ *   (default)    | lost  -> pending,         | lost  -> STAYS LIVE,
+ *                |          recursively      |          notified
+ *   -------------|---------------------------|--------------------------
+ *   optional:true| never gates activation;   | never gates activation;
+ *                | a change deactivates and  | a change is a
+ *                | reactivates               | notification, nothing else
+ *
+ * `dynamic` means the plugin has said, IN WRITING, that it can survive
+ * its provider being swapped underneath it. It is not the default
+ * because most plugins cannot, and the cost of wrongly assuming they
+ * can is a live instance holding a dead reference. */
+
+#include "depend.hpp"
+
+#include <algorithm>
+
+#include "ref.hpp"
+
+namespace plugin {
+
+/* A bare string is shorthand for `{name}`. */
+V normrequire(const V& r) {
+  if (isstr(r)) {
+    V out = vmap();
+    set(out, "name", r);
+    return out;
+  }
+  return ismap(r) ? r : vmap();
+}
+
+/* BOTH AXES ARE READ AT TWO LEVELS, AND THE PER-REQUIREMENT ONE WINS.
+ *
+ * The instance-level `policy` and `optional` list are how a DOCUMENT
+ * states the axis without editing the definition, and they apply to
+ * every requirement. The per-requirement form is strictly more
+ * expressive: an instance that is `static` on its store and `dynamic`
+ * on its metrics cannot be written at all at the instance level, and
+ * that is the ordinary case rather than an exotic one.
+ *
+ * `optional` UNIONS rather than overriding — both spellings say this
+ * requirement need not gate activation, and there is no reading under
+ * which one of them means "actually, mandatory". */
+V requirements(const V& options) {
+  V raw = get(options, "requires");
+  V marked = get(options, "optional");
+  V fallback = get(options, "policy");
+
+  V out = vlist();
+  for (size_t i = 0; i < len(raw); i++) {
+    V r = normrequire(at(raw, i));
+    V o = vmap();
+    for (const auto& k : keys(r)) set(o, k, get(r, k));
+
+    bool opt = truthy(get(r, "optional"));
+    if (!opt && islist(marked)) {
+      for (size_t j = 0; j < len(marked); j++) {
+        if (same(at(marked, j), get(r, "name"))) { opt = true; break; }
+      }
+    }
+    if (opt) set(o, "optional", vbool(true));
+
+    if (isnull(get(o, "policy")) && !isnull(fallback)) set(o, "policy", fallback);
+    push(out, o);
+  }
+  return out;
+}
+
+/* Does losing this requirement's SELECTED provider restart the
+ * consumer? The mandatory ones under `static`, and the `static`
+ * optional ones — both make a capability change deactivate and
+ * reactivate. `dynamic` never restarts. */
+bool restartsonloss(const V& r) {
+  V p = get(r, "policy");
+  const std::string policy = isstr(p) ? asstr(p) : "static";
+  return "dynamic" != policy;
+}
+
+/* Does an unmet requirement keep the consumer out of `live`?
+ *
+ * CARDINALITY ALONE DECIDES THIS, NOT POLICY. `dynamic` is a statement
+ * about surviving a SWAP, not about starting without the thing at all —
+ * a mandatory-dynamic consumer still waits in `pending` for its first
+ * provider. Conflating the two would let a plugin that declared it can
+ * cope with replacement activate with nothing to call. */
+bool gatesactivation(const V& r) { return true != asbool(get(r, "optional")); }
+
+/* Edges that can cause a restart, which is exactly the set a cycle must
+ * be detected over (§11.3): the mandatory requirements AND THE `static`
+ * OPTIONAL ONES, because both make a capability change deactivate and
+ * reactivate the consumer — and a cycle of restarts does not settle.
+ *
+ * ONLY `dynamic` OPTIONAL EDGES ARE EXCLUDED, and they are the ones the
+ * exclusion was for. An earlier draft of §11.3 excluded EVERY optional
+ * edge and thereby admitted the non-terminating case it was trying to
+ * permit. */
+bool restartcausing(const V& r) {
+  return gatesactivation(r) || restartsonloss(r);
+}
+
+V dependencycycle(const V& nodes) {
+  /* TWO INDEXES, NOT ONE MERGED MAP. Capability names and refs are
+   * matched differently — a capability by its exact name, a ref through
+   * the canonical spelling (§4 rule 5) — and one map keyed by both can
+   * only do one of them. Keyed by both and looked up raw, a cycle
+   * spelled `a$`/`b$` finds no providers and EVADES the load-time check
+   * that exists to catch a non-terminating reconcile. */
+  V bycap = vmap();
+  V isref = vmap();
+  for (size_t i = 0; i < len(nodes); i++) {
+    V n = at(nodes, i);
+    const std::string nref = asstr(get(n, "ref"));
+    set(isref, nref, vbool(true));
+    V provides = get(n, "provides");
+    for (size_t j = 0; j < len(provides); j++) {
+      const std::string cap = asstr(at(provides, j));
+      V l = get(bycap, cap);
+      if (isnull(l)) { l = vlist(); set(bycap, cap, l); }
+      push(l, vstr(nref));
+    }
+  }
+
+  V edges = vmap();
+  for (size_t i = 0; i < len(nodes); i++) {
+    V n = at(nodes, i);
+    const std::string nref = asstr(get(n, "ref"));
+    std::vector<std::string> out;
+    V reqs = get(n, "requires");
+    for (size_t j = 0; j < len(reqs); j++) {
+      V r = at(reqs, j);
+      if (!restartcausing(r)) continue;
+      const std::string rname = asstr(get(r, "name"));
+      std::vector<std::string> from;
+      V caps = get(bycap, rname);
+      for (size_t k = 0; k < len(caps); k++) from.push_back(asstr(at(caps, k)));
+      /* A node satisfies its own name AS A REF (§11.1), canonically —
+       * exactly what `providersof` does at runtime, so the load-time
+       * graph and the running one agree about what an edge is. */
+      std::string asref;
+      if (tryref(rname, asref) && has(isref, asref) &&
+          from.end() == std::find(from.begin(), from.end(), asref)) {
+        from.push_back(asref);
+      }
+      for (const auto& p : from) {
+        if (p != nref && out.end() == std::find(out.begin(), out.end(), p)) {
+          out.push_back(p);
+        }
+      }
+    }
+    std::sort(out.begin(), out.end());
+    V sorted = vlist();
+    for (const auto& p : out) push(sorted, vstr(p));
+    set(edges, nref, sorted);
+  }
+
+  /* Iterative DFS with an explicit stack: twenty ports, and several of
+   * them have no recursion budget worth relying on. */
+  enum { WHITE = 0, GREY = 1, BLACK = 2 };
+  V colour = vmap();
+  for (size_t i = 0; i < len(nodes); i++) {
+    set(colour, asstr(get(at(nodes, i), "ref")), vnum(WHITE));
+  }
+
+  for (const auto& start : sortedkeys(edges)) {
+    if (WHITE != static_cast<int>(asnum(get(colour, start)))) continue;
+
+    std::vector<std::string> path{start};
+    std::vector<std::pair<std::string, size_t>> stack{{start, 0}};
+    set(colour, start, vnum(GREY));
+
+    while (!stack.empty()) {
+      auto& top = stack.back();
+      V tos = get(edges, top.first);
+
+      if (top.second >= len(tos)) {
+        set(colour, top.first, vnum(BLACK));
+        stack.pop_back();
+        path.pop_back();
+        continue;
+      }
+
+      const std::string next = asstr(at(tos, top.second));
+      top.second++;
+      int c = static_cast<int>(asnum(get(colour, next)));
+
+      if (GREY == c) {
+        /* Report the cycle itself, not the walk that found it. */
+        V cycle = vlist();
+        bool started = false;
+        for (const auto& p : path) {
+          if (!started && p == next) started = true;
+          if (started) push(cycle, vstr(p));
+        }
+        push(cycle, vstr(next));
+        return cycle;
+      }
+      if (BLACK == c) continue;
+
+      set(colour, next, vnum(GREY));
+      path.push_back(next);
+      stack.push_back({next, 0});
+    }
+  }
+
+  return nullptr;
+}
+
+void checkcycle(const V& nodes) {
+  V cycle = dependencycycle(nodes);
+  if (!cycle) return;
+  std::string names;
+  for (size_t i = 0; i < len(cycle); i++) {
+    if (0 < i) names += " -> ";
+    names += asstr(at(cycle, i));
+  }
+  fail("plugin_dependency_cycle", "requirements cycle: " + names,
+       details1("cycle", cycle));
+}
+
+}  // namespace plugin

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

@@ -0,0 +1,31 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/depend.hpp)
+// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* Dependency cardinality, policy, and the restart graph (§11.3). Two
+ * axes, both declared by the definition that has the requirement,
+ * because only it knows what it can cope with. See depend.cpp. */
+
+#ifndef VOXGIG_PLUGIN_DEPEND_HPP
+#define VOXGIG_PLUGIN_DEPEND_HPP
+
+#include "types.hpp"
+#include "value.hpp"
+
+namespace plugin {
+
+V normrequire(const V& r);
+V requirements(const V& options);
+
+bool restartsonloss(const V& r);
+bool gatesactivation(const V& r);
+bool restartcausing(const V& r);
+
+/* [{ref, provides:[name], requires:[req]}] -> the cycle, or nullptr. */
+V dependencycycle(const V& nodes);
+/* Raise on a cycle, naming it. Separate from the detector so the
+ * detector stays pure and corpus-testable. */
+void checkcycle(const V& nodes);
+
+}  // namespace plugin
+
+#endif

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 @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-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 @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-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 @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-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 @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-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