@voxgig/sdkgen 4.10.0 → 4.12.0

package/project/.sdk/tm/c/feature/secrets/plugin/host.h

@@ -0,0 +1,135 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (c/src/host.h)
+// 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.
+/* The host: the lifecycle state machine (§5), extension points (§6),
+ * and resource capture (§8).
+ *
+ * TWO RULES SHAPE EVERY FUNCTION 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 promise. */
+
+#ifndef VOXGIG_PLUGIN_HOST_H
+#define VOXGIG_PLUGIN_HOST_H
+
+#include <stdbool.h>
+
+#include "catalog.h"
+#include "point.h"
+#include "types.h"
+#include "value.h"
+
+typedef struct Host Host;
+
+/* A scope release. C has no closures, so a release is a function plus
+ * its context — the same pairing `point.h` uses for bindings. */
+typedef void (*ReleaseFn)(void *ctx);
+
+typedef struct HostOptions {
+  Catalog *catalog;
+  Value *reserved;     /* list of names */
+  Value *keys;         /* {instance, default} */
+  Value *defaults;     /* {name -> options} */
+  Value *profile;
+  /* {point -> {kind, mode, exclusive, default, pin}}; the chain base
+   * and provider default are functions, so they ride alongside. */
+  Value *points;
+  HookFn *basefns;     /* parallel to `basepoints` */
+  Value *basepoints;   /* list of point names having a base fn */
+  /* §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. */
+  const char *dependency;
+} HostOptions;
+
+Host *makehost(HostOptions *opts);
+
+Catalog *host_catalog(Host *h);
+void host_define(Host *h, Definition *def);
+
+/* --- the state machine --------------------------------------------- */
+
+typedef struct DeclareSpec {
+  const char *definition;
+  Value *options;
+  Value *order;
+  bool haspos;
+  double pos;
+  const char *tag;
+  /* §9.1: set ONLY by `hostdeclare` — "the host declares those
+   * instances itself, after the user merge, and always wins". */
+  bool hostowned;
+} DeclareSpec;
+
+Inst *host_declare(Host *h, const char *ref, DeclareSpec *spec);
+Inst *host_load(Host *h, const char *ref, DeclareSpec *spec);
+Inst *host_activate(Host *h, const char *ref);
+Inst *host_deactivate(Host *h, const char *ref);
+void host_unload(Host *h, const char *ref);
+Inst *host_ready(Host *h, const char *ref);
+void host_close(Host *h);
+void host_apply(Host *h, Value *doc, Value *profile);
+void host_setoptions(Host *h, const char *ref, Value *patch);
+const char *host_autotag(Host *h, const char *name);
+
+/* --- observation ---------------------------------------------------- */
+
+/* Introspection NEVER advances the state (§5.2). A status page must not
+ * be a way to accidentally import twenty packages. */
+Value *host_list(Host *h);
+Inst *host_instance(Host *h, const char *ref);
+Value *host_observable(Host *h, Value *result, bool hasresult);
+Value *host_trace(Host *h);
+Value *host_order(Host *h, const char *point);
+Value *host_positionof(Host *h, const char *ref, const char *point);
+
+/* --- points --------------------------------------------------------- */
+
+Value *host_emit(Host *h, const char *point, Value *arg);
+Value *host_call(Host *h, const char *point, Value *arg);
+Value *host_provider(Host *h, const char *point, Value *arg);
+Value *host_shadowed(Host *h, const char *point);
+Value *host_exports(Host *h, const char *spec);
+Value *host_capability(Host *h, const char *name);
+
+/* --- the instance api, as callbacks see it -------------------------- */
+
+const char *inst_ref(Inst *i);
+const char *inst_name(Inst *i);
+const char *inst_tag(Inst *i);
+Value *inst_options(Inst *i);
+Value *inst_state(Inst *i);
+Host *inst_host(Inst *i);
+Inst *inst_of(Host *h, const char *ref);
+
+void inst_bind(Inst *i, const char *point, HookFn hook, ChainFn chain,
+               void *ctx, Value *band);
+void inst_export(Inst *i, const char *key, Value *value);
+void inst_provides(Inst *i, Value *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. */
+typedef struct ScopeEntry AcquireHandle;
+AcquireHandle *inst_acquire(Inst *i);
+void inst_giveback(Inst *i, AcquireHandle *handle);
+void inst_release(Inst *i, ReleaseFn fn, void *ctx);
+Value *inst_position(Inst *i, const char *point);
+Host *inst_nest(Inst *i, HostOptions *opts);
+
+/* The driver reads these to build §4.5's observable. */
+Value *inst_status(Inst *i);
+double inst_seq(Inst *i);
+double inst_pos(Inst *i);
+Host *inst_inner(Inst *i);
+
+#endif

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

@@ -0,0 +1,288 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (c/src/order.c)
+// 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.
+/* 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 <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "order.h"
+#include "ref.h"
+
+static double bandof(Value *b) {
+  Value *o = vget(b, "order");
+  Value *band = vget(o, "band");
+  /* 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. */
+  return visnum(band) ? vasnum(band) : 0.0;
+}
+
+static double posof(Value *b) {
+  Value *p = vget(b, "pos");
+  return visnum(p) ? vasnum(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`. */
+typedef struct Ready { Value *binding; size_t seq; } Ready;
+
+/* 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
+ * `qsort` is not stable, so on a libc that reorders equal elements the
+ * topological order would differ from every other port's. The
+ * DECLARATION SEQUENCE (the index `host_order` fed them in) breaks the
+ * last tie, which is what the stable-sort ports get for free. */
+static int rank(const void *pa, const void *pb) {
+  const Ready *x = (const Ready *)pa;
+  const Ready *y = (const Ready *)pb;
+  double ab = bandof(x->binding), bb = bandof(y->binding);
+  if (ab != bb) return ab < bb ? -1 : 1;
+  double ap = posof(x->binding), bp = posof(y->binding);
+  if (ap != bp) return ap < bp ? -1 : 1;
+  if (x->seq != y->seq) return x->seq < y->seq ? -1 : 1;
+  return 0;
+}
+
+/* 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(Value *spec) {
+  if (vislist(spec)) return 0 < vlen(spec);
+  if (visstr(spec)) return '\0' != vasstr(spec)[0];
+  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 Value *targets(Value *spec, Value *nodes) {
+  Value *hit = vlist();
+  Value *specs = vislist(spec) ? spec : NULL;
+  size_t sn = NULL == specs ? 1 : vlen(specs);
+  for (size_t si = 0; si < sn; si++) {
+    Value *oneval = NULL == specs ? spec : vat(specs, si);
+    if (!visstr(oneval)) continue;
+    const char *one = vasstr(oneval);
+    for (size_t i = 0; i < vlen(nodes); i++) {
+      const char *ref = vasstr(vget(vat(nodes, i), "ref"));
+      bool already = false;
+      for (size_t j = 0; j < vlen(hit); j++) {
+        if (0 == strcmp(vasstr(vat(hit, j)), ref)) { already = true; break; }
+      }
+      if (already) continue;
+      if (0 == strcmp(ref, one)) { vpush(hit, vstr(ref)); continue; }
+      if (0 == strcmp(refname(ref), one)) vpush(hit, vstr(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 Value *applypin(Value *order, Value *edges, Value *pin) {
+  if (!vismap(pin)) return order;
+
+  Value *out = vlist();
+  for (size_t i = 0; i < vlen(order); i++) vpush(out, vat(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. */
+  const char **names;
+  size_t pn = vsortedkeys(pin, &names);
+  for (size_t i = 0; i < pn; i++) {
+    Value *wantv = vget(pin, names[i]);
+    const char *want = visstr(wantv) ? vasstr(wantv) : "";
+    size_t idx = (size_t)-1;
+    for (size_t j = 0; j < vlen(out); j++) {
+      if (0 == strcmp(refname(vasstr(vat(out, j))), names[i])) { idx = j; break; }
+    }
+    if ((size_t)-1 == 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 = 0 == strcmp(want, "first") || 0 == strcmp(want, "outermost");
+    Value *ref = vat(out, idx);
+    Value *moved = vlist();
+    if (wantfirst) vpush(moved, ref);
+    for (size_t j = 0; j < vlen(out); j++) {
+      if (j != idx) vpush(moved, vat(out, j));
+    }
+    if (!wantfirst) vpush(moved, ref);
+    out = moved;
+  }
+
+  /* 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. */
+  Value *at = vmap();
+  for (size_t i = 0; i < vlen(out); i++) {
+    vset(at, vasstr(vat(out, i)), vnum((double)i));
+  }
+  const char **froms;
+  size_t fn = vsortedkeys(edges, &froms);
+  for (size_t i = 0; i < fn; i++) {
+    Value *tos = vget(edges, froms[i]);
+    for (size_t j = 0; j < vlen(tos); j++) {
+      const char *to = vasstr(vat(tos, j));
+      double a = vasnum(vget(at, froms[i]));
+      double b = vasnum(vget(at, to));
+      if (a > b) {
+        size_t sz = strlen(froms[i]) + strlen(to) + 96;
+        char *text = (char *)arena_alloc(sz);
+        snprintf(text, sz,
+                 "a pin would move a binding an ordering constrains: %s must precede %s",
+                 froms[i], to);
+        Value *d = vmap();
+        vset(d, "before", vstr(froms[i]));
+        vset(d, "after", vstr(to));
+        fail("plugin_order_pinned", text, d);
+      }
+    }
+  }
+
+  return out;
+}
+
+Value *resolveorder(Value *bindings, Value *pin) {
+  size_t n = vlen(bindings);
+
+  Value *byref = vmap();
+  for (size_t i = 0; i < n; i++) {
+    Value *b = vat(bindings, i);
+    vset(byref, vasstr(vget(b, "ref")), b);
+  }
+
+  /* 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. */
+  Value *edges = vmap();
+  for (size_t i = 0; i < n; i++) {
+    vset(edges, vasstr(vget(vat(bindings, i), "ref")), vlist());
+  }
+
+  for (size_t i = 0; i < n; i++) {
+    Value *b = vat(bindings, i);
+    const char *bref = vasstr(vget(b, "ref"));
+    Value *o = vget(b, "order");
+    Value *after = vget(o, "after");
+    Value *before = vget(o, "before");
+    if (declared(after)) {
+      Value *ts = targets(after, bindings);
+      for (size_t j = 0; j < vlen(ts); j++) {
+        vpush(vget(edges, vasstr(vat(ts, j))), vstr(bref));
+      }
+    }
+    if (declared(before)) {
+      Value *ts = targets(before, bindings);
+      for (size_t j = 0; j < vlen(ts); j++) {
+        vpush(vget(edges, bref), vat(ts, j));
+      }
+    }
+  }
+
+  /* Stable topological sort. */
+  Value *indeg = vmap();
+  for (size_t i = 0; i < n; i++) {
+    vset(indeg, vasstr(vget(vat(bindings, i), "ref")), vnum(0));
+  }
+  const char **froms;
+  size_t fn = vkeys(edges, &froms);
+  for (size_t i = 0; i < fn; i++) {
+    Value *tos = vget(edges, froms[i]);
+    for (size_t j = 0; j < vlen(tos); j++) {
+      const char *to = vasstr(vat(tos, j));
+      vset(indeg, to, vnum(vasnum(vget(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. */
+  Ready *ready = (Ready *)arena_alloc(sizeof(Ready) * (n + 1));
+  size_t rn = 0;
+  size_t seq = 0;
+  for (size_t i = 0; i < n; i++) {
+    Value *b = vat(bindings, i);
+    if (0 == vasnum(vget(indeg, vasstr(vget(b, "ref"))))) {
+      ready[rn].binding = b;
+      ready[rn].seq = seq++;
+      rn++;
+    }
+  }
+
+  Value *out = vlist();
+  while (0 < rn) {
+    if (1 < rn) qsort(ready, rn, sizeof(Ready), rank);
+    Value *next = ready[0].binding;
+    for (size_t i = 1; i < rn; i++) ready[i - 1] = ready[i];
+    rn--;
+
+    const char *nref = vasstr(vget(next, "ref"));
+    vpush(out, vstr(nref));
+    Value *tos = vget(edges, nref);
+    for (size_t j = 0; j < vlen(tos); j++) {
+      const char *to = vasstr(vat(tos, j));
+      double d = vasnum(vget(indeg, to)) - 1;
+      vset(indeg, to, vnum(d));
+      if (0 == d) {
+        ready[rn].binding = vget(byref, to);
+        ready[rn].seq = seq++;
+        rn++;
+      }
+    }
+  }
+
+  if (vlen(out) != n) {
+    Value *stuck = vlist();
+    size_t sz = 64;
+    for (size_t i = 0; i < n; i++) {
+      const char *ref = vasstr(vget(vat(bindings, i), "ref"));
+      bool placed = false;
+      for (size_t j = 0; j < vlen(out); j++) {
+        if (0 == strcmp(vasstr(vat(out, j)), ref)) { placed = true; break; }
+      }
+      if (!placed) { vpush(stuck, vstr(ref)); sz += strlen(ref) + 8; }
+    }
+    char *text = (char *)arena_alloc(sz);
+    size_t used = (size_t)snprintf(text, sz, "before/after constraints cycle: ");
+    for (size_t i = 0; i < vlen(stuck); i++) {
+      used += (size_t)snprintf(text + used, sz - used, "%s%s",
+                               0 < i ? " -> " : "", vasstr(vat(stuck, i)));
+    }
+    fail("plugin_order_cycle", text, details1("cycle", stuck));
+  }
+
+  return applypin(out, edges, pin);
+}

package/project/.sdk/tm/c/feature/secrets/plugin/order.h

@@ -0,0 +1,18 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (c/src/order.h)
+// 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.
+/* 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.c. */
+
+#ifndef VOXGIG_PLUGIN_ORDER_H
+#define VOXGIG_PLUGIN_ORDER_H
+
+#include "types.h"
+#include "value.h"
+
+/* [{ref, pos, order?}] plus an optional host pin -> [ref] */
+Value *resolveorder(Value *bindings, Value *pin);
+
+#endif

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

@@ -0,0 +1,141 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (c/src/point.c)
+// 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.
+/* Extension points (§6). See point.h for the closure representation. */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "point.h"
+
+/* The composition, walked by index rather than built as nested
+ * closures. `chain_next` advances one step and calls the binding there;
+ * the base runs when the bindings are exhausted. Identical to
+ * `b1(b2(b3(base)))` and it needs no allocation per layer. */
+struct Chain {
+  Bound **bindings;
+  size_t n;
+  size_t i;
+  HookFn base;
+  void *basectx;
+};
+
+Value *chain_next(Chain *c, Value *arg) {
+  if (NULL == c) return arg;
+  if (c->i >= c->n) {
+    return NULL == c->base ? arg : c->base(arg, c->basectx);
+  }
+  Bound *b = c->bindings[c->i];
+  Chain rest;
+  rest.bindings = c->bindings;
+  rest.n = c->n;
+  rest.i = c->i + 1;
+  rest.base = c->base;
+  rest.basectx = c->basectx;
+  return b->chain(&rest, arg, b->ctx);
+}
+
+Value *point_call(Bound **bindings, size_t n, HookFn base, void *basectx,
+                  Value *arg) {
+  Chain c;
+  c.bindings = bindings;
+  c.n = n;
+  c.i = 0;
+  c.base = base;
+  c.basectx = basectx;
+  return chain_next(&c, arg);
+}
+
+Value *point_emit(Bound **bindings, size_t n, const char *mode, Value *arg,
+                  Value **errors) {
+  if (NULL != errors) *errors = vlist();
+
+  if (0 == strcmp(mode, "bail")) {
+    /* Stops at the first binding that RETURNS A VALUE — the "handled,
+     * stop" case. 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 (size_t i = 0; i < n; i++) {
+      Value *v = bindings[i]->hook(arg, bindings[i]->ctx);
+      if (!visnull(v)) return v;
+    }
+    return NULL;
+  }
+
+  bool raising = 0 == strcmp(mode, "emit");
+  for (size_t i = 0; i < n; i++) {
+    if (raising) {
+      /* `emit` raises synchronously; the collecting modes gather. */
+      bindings[i]->hook(arg, bindings[i]->ctx);
+      continue;
+    }
+    CatchFrame f;
+    if (0 == PLUGIN_TRY(&f)) {
+      bindings[i]->hook(arg, bindings[i]->ctx);
+      PLUGIN_END(&f);
+    }
+    else if (NULL != errors) {
+      Value *e = vmap();
+      vset(e, "code", vstr(plugin_caught()->code));
+      vset(e, "message", vstr(plugin_caught()->message));
+      vpush(*errors, e);
+    }
+  }
+  return NULL;
+}
+
+static int provrank(const void *pa, const void *pb) {
+  Bound *a = *(Bound *const *)pa;
+  Bound *b = *(Bound *const *)pb;
+  /* HIGHEST band wins, unlike hook and chain. */
+  if (a->band != b->band) return a->band > b->band ? -1 : 1;
+  return strcmp(a->ref, b->ref);
+}
+
+Bound *point_provider(Bound **bindings, size_t n, bool exclusive,
+                      Value **shadowed) {
+  if (NULL != shadowed) *shadowed = vlist();
+  if (0 == n) return NULL;
+
+  Bound **ranked = (Bound **)arena_alloc(sizeof(Bound *) * n);
+  memcpy(ranked, bindings, sizeof(Bound *) * n);
+
+  if (exclusive && 1 < n) {
+    const char **refs = (const char **)arena_alloc(sizeof(char *) * n);
+    size_t sz = 96;
+    for (size_t i = 0; i < n; i++) { refs[i] = bindings[i]->ref; sz += strlen(refs[i]) + 4; }
+    /* Sorted, so the message names the same pair whatever order the
+     * bindings arrived in. */
+    for (size_t i = 0; i + 1 < n; i++) {
+      for (size_t j = i + 1; j < n; j++) {
+        if (0 < strcmp(refs[i], refs[j])) {
+          const char *t = refs[i]; refs[i] = refs[j]; refs[j] = t;
+        }
+      }
+    }
+    Value *list = vlist();
+    for (size_t i = 0; i < n; i++) vpush(list, vstr(refs[i]));
+    char *text = (char *)arena_alloc(sz);
+    size_t used = (size_t)snprintf(text, sz,
+        "point is exclusive and has %zu bindings: ", n);
+    for (size_t i = 0; i < n; i++) {
+      used += (size_t)snprintf(text + used, sz - used, "%s%s",
+                               0 < i ? ", " : "", refs[i]);
+    }
+    fail("plugin_point_exclusive", text, details1("refs", list));
+  }
+
+  if (1 < n) qsort(ranked, n, sizeof(Bound *), provrank);
+
+  if (NULL != shadowed) {
+    for (size_t i = 1; i < n; i++) vpush(*shadowed, vstr(ranked[i]->ref));
+  }
+  return ranked[0];
+}

package/project/.sdk/tm/c/feature/secrets/plugin/point.h

@@ -0,0 +1,80 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (c/src/point.h)
+// 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.
+/* 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 IN C IS A FUNCTION POINTER PLUS A CONTEXT, and that is the
+ * whole of what this header adds over the canonical. `chain` needs to
+ * hand a binding its `next`, which in every other port is a closure the
+ * composition builds; here `next` is an explicit `Chain *` the binding
+ * calls back into. Same composition, same order, no hidden state. */
+
+#ifndef VOXGIG_PLUGIN_POINT_H
+#define VOXGIG_PLUGIN_POINT_H
+
+#include <stdbool.h>
+
+#include "types.h"
+#include "value.h"
+
+/* The remaining composition, as seen by one chain binding. Opaque: 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). */
+typedef struct Chain Chain;
+
+/* A hook or provider binding. */
+typedef Value *(*HookFn)(Value *arg, void *ctx);
+/* A chain binding: it receives its `next` and the argument. */
+typedef Value *(*ChainFn)(Chain *next, Value *arg, void *ctx);
+
+typedef struct Bound {
+  const char *ref;
+  const char *point;
+  /* `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. */
+  double band;
+  HookFn hook;
+  ChainFn chain;
+  void *ctx;
+} Bound;
+
+/* Call the rest of the composition. */
+Value *chain_next(Chain *c, Value *arg);
+
+/* 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. C has no asynchrony, so all four modes are sequential here and
+ * only the ERROR and RETURN handling distinguishes them.
+ *
+ * `errors` receives the collected raises for the gathering modes. */
+Value *point_emit(Bound **bindings, size_t n, const char *mode, Value *arg,
+                  Value **errors);
+
+/* Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (§6.2). */
+Value *point_call(Bound **bindings, size_t n, HookFn base, void *basectx,
+                  Value *arg);
+
+/* 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. Returns the winner (or NULL) and fills `shadowed`
+ * with the losing refs, in sorted order. */
+Bound *point_provider(Bound **bindings, size_t n, bool exclusive,
+                      Value **shadowed);
+
+#endif