@voxgig/sdkgen 4.10.0 → 4.11.0

package/project/.sdk/tm/clojure/feature/secrets/sdk/feature/secrets.clj

@@ -268,8 +268,11 @@
 ;; Resolution.
 ;; ---------------------------------------------------------------------------
 
+;; Resolve once, answering whether a credential came out of it. That
+;; boolean is the whole of what resolve! needs to tell a cacheable HIT from
+;; a miss it must not keep.
 (defn- resolve-once [fa]
-  (when-let [s (st fa :sek)]
+  (if-let [s (st fa :sek)]
     ;; tryget: nil for a MISS, THROWS for a provider ERROR.
     (let [found (sekreto/tryget s (st fa :secretname))]
       (if (nil? (st fa :exchange))
@@ -278,7 +281,9 @@
         ;; going out on the wire. (An explicit apikey OPTION is never lost
         ;; here - it seats FIRST in the chain as a memory store, so the
         ;; chain HITS while one is set and this branch is unreachable.)
-        (swap! fa assoc :cred (if (string? found) found ""))
+        (do
+          (swap! fa assoc :cred (if (string? found) found ""))
+          (string? found))
 
         ;; Exchanging: what the chain resolved is the REFRESH token, kept
         ;; for every later purchase. A miss is not fatal - an explicit
@@ -292,19 +297,41 @@
                          (let [k (vs/getprop (liveopts fa) "apikey")]
                            (if (string? k) k "")))]
             (swap! fa assoc :cred apikey)
-            (when-not (seq apikey)
+            (cond
+              (seq apikey) true
+
+              ;; `auth: nil` is the documented way to send NO credential,
+              ;; and a purchase is a credential-bearing call: the refresh
+              ;; token goes to the token endpoint in the request body.
+              ;; with-refresh honours suppression for the RETRY, but it runs
+              ;; after this - by then the refresh token has already left the
+              ;; process, and no later check can call it back. The
+              ;; suppression has to be honoured here, before the first
+              ;; purchase, or it only ever half-held.
+              (nil? (auth-of fa)) false
+
+              :else
               ;; No starting access token: buy one now. A failure here is a
               ;; failure of the operation - fail closed.
-              (buy fa))))))))
+              (do (buy fa) true))))))
+    false))
 
 
 ;; One resolution, shared by every concurrent caller.
 ;;
-;; Returns nil on success, or the Throwable that failed it. A settled
-;; SUCCESS is kept only when caching is on (`cache: false` means every
-;; request asks the chain again); a FAILURE is NEVER kept, so a transient
-;; vault outage cannot poison the client permanently - the next operation
-;; asks the chain again and recovers.
+;; Returns nil on success, or the Throwable that failed it. A settled HIT is
+;; kept only when caching is on (`cache: false` means every request asks the
+;; chain again); a FAILURE is NEVER kept, so a transient vault outage cannot
+;; poison the client permanently - the next operation asks the chain again
+;; and recovers.
+;;
+;; A MISS is not kept either, however caching is set. That rule is
+;; sekreto's, not this feature's: `A miss is never cached: the next read
+;; asks again`, in sekreto's own source. Keeping a settled miss here would
+;; override that from the layer above, and a secret provisioned after
+;; startup - a mounted file, a policy granted a minute late - would never be
+;; picked up for the life of the client. `cache` is about caching a HIT; it
+;; was never a promise to keep saying no.
 (defn- resolve! [fa]
   (if-let [e (st fa :initerr)]
     e
@@ -312,8 +339,8 @@
       (if (and (st fa :cache) (st fa :resolved))
         nil
         (try
-          (resolve-once fa)
-          (swap! fa assoc :resolved true)
+          (let [hit (resolve-once fa)]
+            (swap! fa assoc :resolved (boolean hit)))
           nil
           (catch Throwable e
             (swap! fa assoc :resolved false)

package/project/.sdk/tm/clojure/test/sdk/test/feature/secrets.clj

@@ -461,6 +461,33 @@
              (credential-is (:auth (call-at stub 0)) "ROT01" "first")
              (credential-is (:auth (call-at stub 1)) "ROT02" "asked again"))))
 
+    ;; A MISS IS NOT A CACHEABLE ANSWER - sekreto's own rule, which this
+    ;; feature used to override from the layer above. DEFAULT caching here,
+    ;; which is the whole point: `cache: true` is about holding a HIT (the
+    ;; test above pins that half), and keeping the settled resolution after
+    ;; a miss meant the chain was never asked again for the life of the
+    ;; client - a secret provisioned after startup was invisible forever.
+    (chk "secrets-cache-true-re-asks-after-a-miss"
+         (fn []
+           (let [present (atom false)
+                 n (atom 0)
+                 late (reify provider/Provider
+                        (lookup [_ _]
+                          (swap! n inc)
+                          (when @present "LATEKEY01"))
+                        (describe [_] "late:test"))
+                 stub (counting-fetch)
+                 sdk (live-sdk stub :secrets (sekopts "providers" (vs/jt late)))]
+             (client/direct sdk (vs/jm "path" "/thing"))
+             (t/is-nil (:auth (call-at stub 0))
+                       "the chain has nothing yet, so no credential should go out")
+             (let [asked @n]
+               (reset! present true)
+               (client/direct sdk (vs/jm "path" "/thing"))
+               (t/is-eq (< asked @n) true
+                        "the MISS was cached: a secret that appears later can never be picked up")
+               (credential-is (:auth (call-at stub 1)) "LATEKEY01" "late secret")))))
+
     ;; ---- auth: nil SUPPRESSES, chain or no chain ----
 
     (chk "secrets-auth-nil-suppresses-the-credential"
@@ -518,7 +545,7 @@
                (credential-is (:auth (call-at stub 1)) "ACCESS01" "attempt 1")
                (credential-is (:auth (call-at stub 3)) "ACCESS02" "the retry"))))
 
-      (chk "secrets-exchange-with-auth-nil-never-retries"
+      (chk "secrets-exchange-with-auth-nil-never-buys-or-retries"
            (fn []
              (let [stub (counting-fetch
                          (fn [_n url _fd]
@@ -527,11 +554,18 @@
                              [(response 401 (vs/jm "err" "expired")) nil])))
                    sdk (live-sdk stub :auth-nil true :secrets (xsecrets))]
                (client/direct sdk (vs/jm "path" "/thing"))
-               ;; The token was bought at resolution, and the API request
-               ;; went out ONCE: a deliberately unauthenticated request that
-               ;; is refused is not an expired token.
-               (t/is-eq (sent stub) 2 (str "token + one API call only: " (wire stub)))
-               (t/is-nil (:auth (call-at stub 1)) "no authorization header"))))
+               ;; NOTHING IS BOUGHT, and the API request goes out ONCE.
+               ;;
+               ;; This used to read "token + one API call only": the token
+               ;; WAS bought at resolution, because resolve! ran before
+               ;; with-refresh's suppression check. A purchase is a
+               ;; credential-bearing call - the refresh token travels to the
+               ;; token endpoint in the request body - so `auth: nil` was
+               ;; only ever half-held, and stopping the retry could not
+               ;; unsend it. The suppression is now honoured before the
+               ;; first purchase.
+               (t/is-eq (sent stub) 1 (str "one API call, no purchase: " (wire stub)))
+               (t/is-nil (:auth (call-at stub 0)) "no authorization header"))))
 
       (chk "secrets-exchange-with-no-refresh-token-fails-closed"
            (fn []

package/project/.sdk/tm/cpp/Makefile

@@ -3,11 +3,40 @@
 # Header-only runtime (core/, utility/, feature/, entity/); each test/*.cpp is
 # an independent executable. `make test` compiles and runs them all, failing
 # if any test binary exits non-zero. Mirrors the struct/cpp and tm/rust build.
+#
+# The ONE exception to header-only is a gated feature's vendored payload
+# (below): a multi-translation-unit library, compiled into an archive the
+# test executables link - and only while that feature is wired in.
 
 CXX ?= g++
 CXXFLAGS ?= -std=c++17 -O0 -g -Wall -Wextra -Wno-unused-parameter -pthread
 
-TEST_SRCS := $(wildcard test/*.cpp)
+# ---- gated feature payloads (model/feature/<name>.aon plugin groups) --------
+#
+# A gated feature's vendored payload sits two levels under feature/
+# (feature/<name>/<lib>/*.cpp), as .cpp/.hpp pairs that cannot ride inside
+# a test's single translation unit. What of it is built is decided by a
+# GENERATED make fragment, feature/<name>/kinds.mk, that the feature's
+# Config component emits beside its generated wiring file only when the
+# model activates the feature for this target. The fragment appends the
+# payload sources to FEATURE_SRCS, the feature's suite to FEATURE_TEST_SRCS,
+# and - only when a plugin group is active - the plugin layer and the
+# external libraries it brings to FEATURE_LIBS. Nothing here names a
+# feature: a tree whose model never activated one has no fragment, carries
+# its payload as inert source, and links libstdc++ alone, and a project's
+# `target add` trims it outright. `ldd` on any test binary shows which case
+# this tree is. Every quoted include inside a payload is either
+# same-directory or an explicit sibling path written at vendoring time
+# (ts/vendor/routes.json), so NO -I is needed and a payload's types.hpp or
+# value.hpp can never shadow core/types.hpp.
+FEATURE_SRCS :=
+FEATURE_TEST_SRCS :=
+FEATURE_LIBS :=
+-include $(wildcard feature/*/kinds.mk)
+FEATURE_OBJS := $(FEATURE_SRCS:.cpp=.o)
+FEATURE_ARCHIVE := $(if $(strip $(FEATURE_SRCS)),libsdkfeature.a,)
+
+TEST_SRCS := $(wildcard test/*.cpp) $(FEATURE_TEST_SRCS)
 TEST_BINS := $(TEST_SRCS:.cpp=.out)
 
 # REBUILD WHEN A HEADER CHANGES. The runtime is header-only, so a test binary
@@ -20,7 +49,9 @@ TEST_BINS := $(TEST_SRCS:.cpp=.out)
 # test/ is listed too: the corpus suites are driven by test/*.hpp (the omni
 # resolver and the retained runner support) and by the vendored omni headers
 # under test/vendor/omni/, none of which the pattern rule below names either.
+# feature/*/ and feature/*/*/ cover a gated feature's vendored headers.
 SDK_HDRS := $(wildcard core/*.hpp entity/*.hpp feature/*.hpp \
+                       feature/*/*.hpp feature/*/*/*.hpp \
                        utility/*.hpp utility/*/*.hpp *.hpp \
                        test/*.hpp test/vendor/omni/*.hpp)
 
@@ -37,11 +68,24 @@ test: build
 	if [ $$fail -ne 0 ]; then echo "SOME TESTS FAILED"; exit 1; fi; \
 	echo "ALL TESTS PASSED"
 
-test/%.out: test/%.cpp $(SDK_HDRS)
-	$(CXX) $(CXXFLAGS) $< -o $@
+# The payload archive. `ar r` REPLACES a member by basename on an archive it
+# finds and KEEPS every other one, so a stale member from a removed source
+# would outlive it; one cold `ar rcs` keeps exactly the current members
+# (upstream sekreto's own Makefile deletes first for the same reason).
+%.o: %.cpp
+	$(CXX) $(CXXFLAGS) -c $< -o $@
+
+libsdkfeature.a: $(FEATURE_OBJS)
+	@rm -f $@
+	ar rcs $@ $(FEATURE_OBJS)
+
+# $(FEATURE_ARCHIVE) and $(FEATURE_LIBS) are empty unless a gated feature is
+# wired in, so this rule is byte-for-byte the header-only build otherwise.
+test/%.out: test/%.cpp $(SDK_HDRS) $(FEATURE_ARCHIVE)
+	$(CXX) $(CXXFLAGS) $< -o $@ $(FEATURE_ARCHIVE) $(FEATURE_LIBS)
 
 clean:
-	rm -f test/*.out
+	rm -f test/*.out test/*/*/*.out $(FEATURE_OBJS) libsdkfeature.a
 
 # --- Release: tag cpp/vX.Y.Z (header-only; no registry) --------------------
 VERSION := $(shell cat VERSION 2>/dev/null || echo 0.0.1)

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

@@ -0,0 +1,121 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/capability.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.
+/* Capabilities (§11.1). */
+
+#include "capability.hpp"
+
+#include <algorithm>
+
+#include "version.hpp"
+
+namespace plugin {
+
+bool capmatchvalue(const V& want, const V& got) {
+  /* THIS FUNCTION IS WHAT "EVERY LEAF" MEANS, and an earlier draft of
+   * the canonical did not have it: the check was a scalar compare,
+   * which for any compound value is reference identity in JavaScript. A
+   * requirement and a capability are declared in different places and
+   * are never the same object, so `match: {limits: {max: 5}}` could not
+   * be satisfied by ANY provider — including one declaring exactly
+   * that. Invisible while every corpus entry is scalar, which is why
+   * the go port found it and P2 did not. */
+  if (ismap(want)) {
+    if (!ismap(got)) return false;
+    for (const auto& k : keys(want)) {
+      if (!has(got, k)) return false;
+      if (!capmatchvalue(get(want, k), get(got, k))) return false;
+    }
+    return true;
+  }
+  if (islist(want)) {
+    if (!islist(got) || len(want) != len(got)) return false;
+    for (size_t i = 0; i < len(want); i++) {
+      if (!capmatchvalue(at(want, i), at(got, i))) return false;
+    }
+    return true;
+  }
+  return same(want, got);
+}
+
+bool capmatches(const V& req, const V& prov) {
+  if (!same(get(req, "name"), get(prov, "name"))) return false;
+
+  V range = get(req, "range");
+  if (!isnull(range)) {
+    V version = get(prov, "version");
+    if (isnull(version)) return false;
+    if (!satisfiesq(version, range)) return false;
+  }
+
+  /* `match` is checked against the provider's `attrs`, key by key. A
+   * key the provider does not carry is a MISS, not a pass: a
+   * requirement asking for `transactional: true` must not be satisfied
+   * by a provider that never said. */
+  V match = get(req, "match");
+  if (!isnull(match)) {
+    V attrs = get(prov, "attrs");
+    if (isnull(attrs)) attrs = vmap();
+    for (const auto& k : keys(match)) {
+      if (!has(attrs, k)) return false;
+      if (!capmatchvalue(get(match, k), get(attrs, k))) return false;
+    }
+  }
+
+  return true;
+}
+
+/* The rank, as a strict weak ordering over two candidates. Ordering is
+ * a TOTAL rank on purpose: without one, "any provider satisfies" is
+ * true of the GRAPH and useless to the PLUGIN — two ports could bind
+ * different `store` instances, both resolve green, and behave
+ * differently, which is precisely the divergence a shared corpus exists
+ * to catch. */
+static bool better(const V& a, const V& b) {
+  V ap = get(a, "provides");
+  V bp = get(b, "provides");
+
+  V av = get(ap, "version");
+  V bv = get(bp, "version");
+  bool ahas = !isnull(av), bhas = !isnull(bv);
+  if (ahas != bhas) return ahas;             /* a version beats none */
+  if (ahas && bhas) {
+    int c = 0;
+    try {
+      /* HIGHEST version first, so the comparison is reversed. */
+      c = vercmp(parseversion(bv), parseversion(av));
+    }
+    catch (const PluginError&) {
+      c = 0;
+    }
+    if (0 != c) return 0 > c;
+  }
+
+  double apri = isnum(get(ap, "priority")) ? asnum(get(ap, "priority")) : 0.0;
+  double bpri = isnum(get(bp, "priority")) ? asnum(get(bp, "priority")) : 0.0;
+  if (apri != bpri) return apri < bpri;      /* LOWEST priority first */
+
+  return asnum(get(a, "pos")) < asnum(get(b, "pos"));
+}
+
+V resolvecapability(const V& req, const V& candidates) {
+  std::vector<V> hits;
+  for (size_t i = 0; i < len(candidates); i++) {
+    V c = at(candidates, i);
+    if (capmatches(req, get(c, "provides"))) hits.push_back(c);
+  }
+
+  /* `std::sort` is not stable, and §6.3's tie rules make the order
+   * observable — so `better` is a TOTAL order (it falls through to
+   * `pos`, which is unique) and stability is not relied on. An earlier
+   * reading that stopped at `priority` would have left ties to the
+   * sort's discretion, which is exactly the per-port divergence the
+   * ranking exists to remove. */
+  std::sort(hits.begin(), hits.end(), better);
+
+  V out = vlist();
+  for (const auto& h : hits) push(out, h);
+  return out;
+}
+
+}  // namespace plugin

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

@@ -0,0 +1,41 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/capability.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.
+/* Capabilities (§11.1).
+ *
+ * A DEPENDENCY IS ON A CAPABILITY, NOT ON A REF — because it is a
+ * dependency on something that can do the job, and which instance is
+ * doing it is exactly the configuration detail a plugin must not care
+ * about. (§11.1 makes one narrow exception for a ref, and `host.cpp`
+ * implements it; the ranking here is capabilities only.)
+ *
+ * But A BINDING IS TO AN INSTANCE, not to a capability, which is what
+ * decides behaviour when the bound provider leaves while another match
+ * remains. */
+
+#ifndef VOXGIG_PLUGIN_CAPABILITY_HPP
+#define VOXGIG_PLUGIN_CAPABILITY_HPP
+
+#include "types.hpp"
+#include "value.hpp"
+
+namespace plugin {
+
+/* Rank the matching providers best-first: highest `version`, then
+ * LOWEST `priority` (default 0), then declaration position `pos`
+ * ascending. `candidates` is a list of {ref, pos, provides}. */
+V resolvecapability(const V& req, const V& candidates);
+
+/* Does one provider satisfy one requirement? */
+bool capmatches(const V& req, const V& prov);
+
+/* PARTIAL MATCH, RECURSING INTO MAPS (§11.1): every leaf in the
+ * requirement must be present and equal in the capability, keys not
+ * mentioned are not checked. A LIST IS COMPARED LEAF-WISE AT THE SAME
+ * LENGTH, not as a subset — "the first two of your three regions" is
+ * not something `match` can say. */
+bool capmatchvalue(const V& want, const V& got);
+
+}  // namespace plugin
+
+#endif

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

@@ -0,0 +1,60 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/catalog.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.
+/* The definition catalog (§10.1). */
+
+#include "catalog.hpp"
+
+#include "config.hpp"
+#include "ref.hpp"
+
+namespace plugin {
+
+CatalogPtr makecatalog() { return std::make_shared<Catalog>(); }
+
+void Catalog::add(const DefinitionPtr& def) {
+  if (!def || !checkname(vstr(def->name))) {
+    fail("plugin_definition_name",
+         "invalid definition name: " + (def ? def->name : std::string()));
+  }
+
+  /* Validate the shape HERE. Deferring it to resolution time means a
+   * malformed shape surfaces at a different moment in every host that
+   * loads it, which is the divergence the stated domain exists to
+   * prevent. */
+  if (!isnull(def->shape)) checkshape(def->shape);
+
+  for (auto& e : defs_) {
+    if (e.first == def->name) { e.second = def; return; }
+  }
+  defs_.emplace_back(def->name, def);
+}
+
+DefinitionPtr Catalog::get(const std::string& name) const {
+  for (const auto& e : defs_) {
+    if (e.first == name) return e.second;
+  }
+  return nullptr;
+}
+
+bool Catalog::has(const std::string& name) const { return nullptr != get(name); }
+
+V Catalog::names() const {
+  V m = vmap();
+  for (const auto& e : defs_) set(m, e.first, vbool(true));
+  V out = vlist();
+  for (const auto& k : sortedkeys(m)) push(out, vstr(k));
+  return out;
+}
+
+const Lifecycle* definitioncallback(const DefinitionPtr& d,
+                                    const std::string& at) {
+  if (!d) return nullptr;
+  if ("define" == at) return &d->define;
+  if ("activate" == at) return &d->activate;
+  if ("deactivate" == at) return &d->deactivate;
+  if ("close" == at) return &d->close;
+  return nullptr;
+}
+
+}  // namespace plugin

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

@@ -0,0 +1,66 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (cpp/src/catalog.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 definition catalog (§10.1).
+ *
+ * A definition is registered once and may back many instances. Option
+ * shapes are validated AT REGISTRATION, not when a document happens to
+ * exercise a key — so a malformed shape fails once, and in the same
+ * place everywhere (§9.4). `declare/shape` pins that timing. */
+
+#ifndef VOXGIG_PLUGIN_CATALOG_HPP
+#define VOXGIG_PLUGIN_CATALOG_HPP
+
+#include <functional>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "types.hpp"
+#include "value.hpp"
+
+namespace plugin {
+
+class Inst;
+
+/* A DEFINITION IS DATA WITH FUNCTIONS IN IT, not a class to extend. A
+ * document could produce one, which is the property that makes a
+ * catalog a data structure rather than a compile-time registry. */
+using Lifecycle = std::function<void(Inst&)>;
+using Reconfigure = std::function<void(Inst&, const V& now, const V& previous)>;
+
+struct Definition {
+  std::string name;
+  V shape;
+  Lifecycle define;
+  Lifecycle activate;
+  Lifecycle deactivate;
+  Lifecycle close;
+  Reconfigure reconfigure;
+};
+
+using DefinitionPtr = std::shared_ptr<Definition>;
+
+class Catalog {
+ public:
+  void add(const DefinitionPtr& def);
+  DefinitionPtr get(const std::string& name) const;
+  bool has(const std::string& name) const;
+  V names() const;
+
+ private:
+  std::vector<std::pair<std::string, DefinitionPtr>> defs_;
+};
+
+using CatalogPtr = std::shared_ptr<Catalog>;
+
+CatalogPtr makecatalog();
+
+/* The callback for a phase, by the name the log and the corpus use. */
+const Lifecycle* definitioncallback(const DefinitionPtr& d,
+                                    const std::string& at);
+
+}  // namespace plugin
+
+#endif