@voxgig/sdkgen 4.8.3 → 4.10.0

package/project/.sdk/tm/java/feature/secrets/plugin/Order.java

@@ -0,0 +1,274 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (java/src/voxgig/plugin/Order.java)
+// 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.
+package JAVAPACKAGE.feature.secrets.plugin;
+
+import static JAVAPACKAGE.feature.secrets.plugin.Types.asint;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.details;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.fail;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.get;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.keys;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.list;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.str;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+
+/**
+ * Ordering (§7) - one rule, one place.
+ *
+ * <p>sdkgen grew two special cases in {@code makeOptions} ({@code test},
+ * then {@code station}) and the third was not far off. This sort is the
+ * whole replacement, and the tiers are in this order for a reason:
+ *
+ * <pre>
+ *   1 constraints   before/after edges, by ref or by name
+ *   2 bands         integer, lower first, default 0
+ *   3 declaration   ties break by `pos`
+ * </pre>
+ *
+ * <p>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.
+ */
+public final class Order {
+
+  private Order() {}
+
+  /** One thing to place: its ref, its position, and its block as authored. */
+  public static final class Binding {
+    public final String ref;
+    public final double pos;
+    public final Object order;
+
+    public Binding(String ref, double pos, Object order) {
+      this.ref = ref;
+      this.pos = pos;
+      this.order = order;
+    }
+  }
+
+  public static List<String> resolveOrder(List<Binding> bindings, Object pin) {
+    Map<String, Binding> byref = new LinkedHashMap<>();
+    for (Binding b : bindings) {
+      byref.put(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.
+    Map<String, List<String>> edges = new TreeMap<>();
+    for (Binding b : bindings) {
+      edges.put(b.ref, new ArrayList<>());
+    }
+
+    for (Binding b : bindings) {
+      Object block = b.order;
+      // An ABSENT constraint and an EMPTY LIST are both "no constraint".
+      if (declared(get(block, "after"))) {
+        for (String t : targets(get(block, "after"), bindings)) {
+          edges.get(t).add(b.ref);
+        }
+      }
+      if (declared(get(block, "before"))) {
+        edges.get(b.ref).addAll(targets(get(block, "before"), bindings));
+      }
+    }
+
+    // Stable topological sort. Among ready nodes, 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`.
+    Map<String, Integer> indeg = new TreeMap<>();
+    for (Binding b : bindings) {
+      indeg.put(b.ref, 0);
+    }
+    for (List<String> tos : edges.values()) {
+      for (String to : tos) {
+        indeg.put(to, indeg.get(to) + 1);
+      }
+    }
+
+    List<String> out = new ArrayList<>();
+    List<Binding> ready = new ArrayList<>();
+    for (Binding b : bindings) {
+      if (0 == indeg.get(b.ref)) {
+        ready.add(b);
+      }
+    }
+
+    while (!ready.isEmpty()) {
+      // List.sort is stable, which is what the fall-through to `pos`
+      // needs.
+      ready.sort(
+          (x, y) -> {
+            long bx = band(x.order);
+            long by = band(y.order);
+            if (bx != by) {
+              return bx < by ? -1 : 1;
+            }
+            return Double.compare(x.pos, y.pos);
+          });
+      Binding next = ready.remove(0);
+      out.add(next.ref);
+      for (String to : edges.get(next.ref)) {
+        indeg.put(to, indeg.get(to) - 1);
+        if (0 == indeg.get(to)) {
+          ready.add(byref.get(to));
+        }
+      }
+    }
+
+    if (out.size() != bindings.size()) {
+      List<String> stuck = new ArrayList<>();
+      for (Binding b : bindings) {
+        if (!out.contains(b.ref)) {
+          stuck.add(b.ref);
+        }
+      }
+      fail(
+          "plugin_order_cycle",
+          "before/after constraints cycle: " + String.join(" -> ", stuck),
+          details("cycle", Types.strings(stuck)));
+    }
+
+    return applypin(out, edges, pin);
+  }
+
+  /** An integer, and only an integer: {@code true} and {@code "2"} are not bands. */
+  public static long band(Object block) {
+    Long value = asint(get(block, "band"));
+    return null == value ? 0 : value;
+  }
+
+  /**
+   * Was a constraint stated? An absent value and an EMPTY LIST are both
+   * no-constraint - and an empty list is TRUTHY in most languages, which
+   * is exactly how this class of bug survives a reading.
+   */
+  public static boolean declared(Object spec) {
+    if (null == spec) {
+      return false;
+    }
+    List<Object> l = list(spec);
+    if (null != l) {
+      for (Object one : l) {
+        if (!"".equals(one)) {
+          return true;
+        }
+      }
+      return false;
+    }
+    return !"".equals(spec);
+  }
+
+  /**
+   * One spelling or a LIST of them. A list fans out to the UNION of what
+   * each names, so after: ['a','b'] means after BOTH, and the same
+   * instance named twice - once by name, once by ref - is one edge.
+   */
+  public static List<String> targets(Object spec, List<Binding> nodes) {
+    List<Object> specs = list(spec);
+    if (null == specs) {
+      specs = new ArrayList<>();
+      specs.add(spec);
+    }
+    List<String> hit = new ArrayList<>();
+    for (Object one : specs) {
+      String want = str(one);
+      if (null == want) {
+        continue;
+      }
+      for (Binding b : nodes) {
+        if (hit.contains(b.ref)) {
+          continue;
+        }
+        if (b.ref.equals(want) || Refs.refname(b.ref).equals(want)) {
+          hit.add(b.ref);
+        }
+      }
+    }
+    return hit;
+  }
+
+  /**
+   * A PIN IS NOT A CONSTRAINT (§7).
+   *
+   * <p>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.
+   *
+   * <p>So a pin PLACES the binding at the named end, and an ordering that
+   * would move it away is {@code plugin_order_pinned} - rejected, not
+   * honoured into a broken wrap.
+   */
+  private static List<String> applypin(
+      List<String> order, Map<String, List<String>> edges, Object pin) {
+    if (null == pin) {
+      return order;
+    }
+
+    List<String> out = new ArrayList<>(order);
+
+    // 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. A TreeMap is sorted by
+    // construction, which is why the parser builds one.
+    for (String name : keys(pin)) {
+      Object want = get(pin, name);
+      int idx = -1;
+      for (int i = 0; i < out.size(); i++) {
+        if (Refs.refname(out.get(i)).equals(name)) {
+          idx = i;
+          break;
+        }
+      }
+      if (idx < 0) {
+        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.
+      boolean wantfirst = "first".equals(want) || "outermost".equals(want);
+      String ref = out.remove(idx);
+      if (wantfirst) {
+        out.add(0, ref);
+      } else {
+        out.add(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.
+    Map<String, Integer> at = new LinkedHashMap<>();
+    for (int i = 0; i < out.size(); i++) {
+      at.put(out.get(i), i);
+    }
+    for (Map.Entry<String, List<String>> e : edges.entrySet()) {
+      for (String to : e.getValue()) {
+        if (at.get(e.getKey()) <= at.get(to)) {
+          continue;
+        }
+        fail(
+            "plugin_order_pinned",
+            "a pin would move a binding an ordering constrains: "
+                + e.getKey()
+                + " must precede "
+                + to,
+            details("before", e.getKey(), "after", to));
+      }
+    }
+
+    return out;
+  }
+}

package/project/.sdk/tm/java/feature/secrets/plugin/Plugin.java

@@ -0,0 +1,94 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (java/src/voxgig/plugin/Plugin.java)
+// 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.
+package JAVAPACKAGE.feature.secrets.plugin;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * The canonical surface {@code make parity} checks (AGENTS.md §4).
+ *
+ * <p>Small on purpose (§19): everything else is methods on {@link Host}
+ * and {@link Inst}, because a library that grows a second public entry
+ * point per feature is a library twenty ports pay for twice.
+ *
+ * <p>This class FORWARDS rather than implements. The surface is visible in
+ * one place, and a name that stops existing stops existing here loudly.
+ */
+public final class Plugin {
+
+  private Plugin() {}
+
+  public static Host makeHost(Object options) {
+    return Host.makeHost(options);
+  }
+
+  public static Catalog makeCatalog(List<Definition> definitions) {
+    return Catalog.makeCatalog(definitions);
+  }
+
+  public static Map<String, Object> parseRef(Object ref) {
+    return Refs.parseRef(ref);
+  }
+
+  public static String formatRef(Object name, Object tag) {
+    return Refs.formatRef(name, tag);
+  }
+
+  public static boolean checkName(Object name) {
+    return Refs.checkName(name);
+  }
+
+  public static boolean checkTag(Object tag) {
+    return Refs.checkTag(tag);
+  }
+
+  public static String canonRef(Object ref) {
+    return Refs.canonRef(ref);
+  }
+
+  public static Map<String, Object> normalizeConfig(Object input) {
+    return Config.normalizeConfig(input);
+  }
+
+  public static Map<String, Object> resolveOptions(Object input) {
+    return Config.resolveOptions(input);
+  }
+
+  public static List<String> resolveOrder(List<Order.Binding> bindings, Object pin) {
+    return Order.resolveOrder(bindings, pin);
+  }
+
+  public static List<Object> resolveCandidates(String name, Object sources) {
+    return Resolve.resolveCandidates(name, sources);
+  }
+
+  public static List<Object> resolveFrom(Object from) {
+    return Resolve.resolveFrom(from);
+  }
+
+  public static List<Object> resolveCapability(Object req, List<Object> candidates) {
+    return Capability.resolveCapability(req, candidates);
+  }
+
+  public static Map<String, Object> resolveGraph(Object nodes) {
+    return Graph.resolveGraph(nodes);
+  }
+
+  public static Map<String, Object> applyEnv(Object input) {
+    return Env.applyEnv(input);
+  }
+
+  public static Map<String, Object> parseRange(Object range) {
+    return Version.parseRange(range);
+  }
+
+  public static boolean satisfies(Object version, Object range) {
+    return Version.satisfies(version, range);
+  }
+
+  public static String codeof(Throwable err) {
+    return Types.codeof(err);
+  }
+}

package/project/.sdk/tm/java/feature/secrets/plugin/PluginException.java

@@ -0,0 +1,37 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (java/src/voxgig/plugin/PluginException.java)
+// 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.
+package JAVAPACKAGE.feature.secrets.plugin;
+
+/**
+ * Every error carries a §12 code. Ports compare by CODE and never by
+ * message: wording is a port's own business, and pinning the words would
+ * make every translation a corpus change. The FORMAT, however, is pinned -
+ * a parseable message is what makes a log searchable across twenty
+ * languages.
+ *
+ * <p>UNCHECKED, deliberately. A checked exception would put {@code throws}
+ * on every lifecycle callback signature in every plugin ever written, and
+ * §19's budget is a library that stays small for the people embedding it.
+ */
+public class PluginException extends RuntimeException {
+
+  private static final long serialVersionUID = 1L;
+
+  public final String code;
+  public final String text;
+
+  /**
+   * TRANSIENT because it is a live JSON value, not a serializable field:
+   * nothing in this library or its suite serializes an exception, and
+   * `-Xlint:serial` is right to ask rather than be silenced.
+   */
+  public final transient Object details;
+
+  public PluginException(String code, String text, Object details) {
+    super(Types.formaterror(code, text, details));
+    this.code = code;
+    this.text = text;
+    this.details = details;
+  }
+}

package/project/.sdk/tm/java/feature/secrets/plugin/Point.java

@@ -0,0 +1,172 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (java/src/voxgig/plugin/Point.java)
+// 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.
+package JAVAPACKAGE.feature.secrets.plugin;
+
+import static JAVAPACKAGE.feature.secrets.plugin.Types.details;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.fail;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.get;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.str;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.truthy;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Extension points (§6). Three kinds, chosen because they are what the two
+ * existing systems actually needed, and no more.
+ *
+ * <p>A PLUGIN NEVER MUTATES THE HOST. That inversion is what makes
+ * deactivation possible: sdkgen's {@code 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 <i>Listeners Considered Harmful</i>, and for exactly this
+ * reason.
+ */
+public final class Point {
+
+  private Point() {}
+
+  /** The next link of a chain (§6.2), or the base at the end of it. */
+  public interface NextFn {
+    Object call(Object[] args);
+  }
+
+  /**
+   * EVERY binding has one signature, whatever kind of point it is on: a
+   * hook and a provider ignore the {@code next} they are handed, a chain
+   * uses it. One signature is what lets {@code bound} return a single list
+   * the three callers share, rather than three parallel registries that
+   * can disagree about which instance holds slot 3.
+   */
+  public interface BindFn {
+    Object call(NextFn next, Object[] args);
+  }
+
+  public static final class Bound {
+    public final String ref;
+    public final String point;
+    public final BindFn func;
+    public long band;
+
+    public Bound(String ref, String point, BindFn func, long band) {
+      this.ref = ref;
+      this.point = point;
+      this.func = func;
+      this.band = band;
+    }
+
+    public Bound withBand(long band) {
+      return new Bound(this.ref, this.point, this.func, band);
+    }
+  }
+
+  /**
+   * §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.
+   */
+  public static final List<String> MODES = List.of("emit", "parallel", "serial", "bail");
+
+  /** Fan-out. Return values are ignored except in {@code bail}. */
+  public static Object emit(List<Bound> bindings, String mode, Object arg) {
+    if ("bail".equals(mode)) {
+      // Stops at the first binding that RETURNS A VALUE - the "handled,
+      // stop" case. A `null` RETURN DECLINES (§6.1): java has one way to
+      // say nothing, and the model's rule is written to that rather than
+      // to JavaScript's null/undefined pair. Not truthiness - `false`, `0`
+      // and `""` are values.
+      for (Bound b : bindings) {
+        Object v = b.func.call(null, new Object[] {arg});
+        if (null != v) {
+          return v;
+        }
+      }
+      return null;
+    }
+
+    List<Object> errors = new ArrayList<>();
+    for (Bound b : bindings) {
+      try {
+        b.func.call(null, new Object[] {arg});
+      } catch (RuntimeException e) {
+        // `emit` raises synchronously; the collecting modes gather.
+        if ("emit".equals(mode)) {
+          throw e;
+        }
+        errors.add(e.getMessage());
+      }
+    }
+    return "emit".equals(mode) ? null : errors;
+  }
+
+  /**
+   * Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (§6.2).
+   *
+   * <p>Recomputed by the host whenever the live set changes, and cached
+   * between changes. Plugins receive {@code next} as an argument; they
+   * never see or store the previous value of anything. A plugin that
+   * stashes {@code next} and calls it after deactivation is a bug the host
+   * cannot prevent, and this says so rather than pretending otherwise.
+   */
+  public static NextFn compose(List<Bound> bindings, NextFn base) {
+    NextFn next = base;
+    for (int i = bindings.size() - 1; 0 <= i; i--) {
+      final BindFn func = bindings.get(i).func;
+      final NextFn inner = next;
+      // `final` locals per iteration, so each layer closes over its own
+      // pair - java gives that for free where ruby's blocks do not.
+      next = args -> func.call(inner, args);
+    }
+    return next;
+  }
+
+  /**
+   * 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.
+   */
+  public static final class Picked {
+    public final Bound winner;
+    public final List<String> shadowed;
+
+    Picked(Bound winner, List<String> shadowed) {
+      this.winner = winner;
+      this.shadowed = shadowed;
+    }
+  }
+
+  public static Picked provider(List<Bound> bindings, Object spec) {
+    if (bindings.isEmpty()) {
+      return new Picked(null, new ArrayList<>());
+    }
+
+    if (truthy(get(spec, "exclusive")) && 1 < bindings.size()) {
+      List<String> refs = new ArrayList<>();
+      for (Bound b : bindings) {
+        refs.add(b.ref);
+      }
+      refs.sort(null);
+      fail(
+          "plugin_point_exclusive",
+          "point is exclusive and has " + bindings.size() + " bindings: " + String.join(", ", refs),
+          details("refs", Types.strings(refs)));
+    }
+
+    List<Bound> ranked = new ArrayList<>(bindings);
+    ranked.sort(
+        (a, b) -> {
+          if (a.band != b.band) {
+            return a.band < b.band ? 1 : -1; // higher band first
+          }
+          return a.ref.compareTo(b.ref);
+        });
+    List<String> shadowed = new ArrayList<>();
+    for (int i = 1; i < ranked.size(); i++) {
+      shadowed.add(ranked.get(i).ref);
+    }
+    return new Picked(ranked.get(0), shadowed);
+  }
+}