@voxgig/sdkgen 4.9.0 → 4.10.0

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

@@ -0,0 +1,54 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (java/src/voxgig/plugin/Definition.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;
+
+/**
+ * What a catalog registers: a name, an option shape, and the lifecycle
+ * callbacks (§10.1).
+ *
+ * <p>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 - and an abstract
+ * base class would make every plugin a subclass of this library.
+ */
+public final class Definition {
+
+  /** A lifecycle callback. It RAISES on failure, as the canonical does. */
+  public interface Callback {
+    void run(Inst inst);
+  }
+
+  /** §9.4's cheap path: the host hands the new options and the old ones. */
+  public interface Reconfigure {
+    void run(Inst inst, Object now, Object previous);
+  }
+
+  public final String name;
+  public Object shape;
+  public Callback define;
+  public Callback activate;
+  public Callback deactivate;
+  public Callback close;
+  public Reconfigure reconfigure;
+
+  public Definition(String name) {
+    this.name = name;
+  }
+
+  /** The callback for a phase, by the name the log and the corpus use. */
+  public Callback callback(String at) {
+    switch (at) {
+      case "define":
+        return define;
+      case "activate":
+        return activate;
+      case "deactivate":
+        return deactivate;
+      case "close":
+        return close;
+      default:
+        return null;
+    }
+  }
+}

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

@@ -0,0 +1,292 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (java/src/voxgig/plugin/Depend.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.list;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.map;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.newmap;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.same;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.str;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.truthy;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.TreeSet;
+
+/**
+ * Dependency cardinality, policy, and the restart graph (§11.3).
+ *
+ * <p>TWO AXES, BOTH DECLARED BY THE DEFINITION THAT HAS THE REQUIREMENT,
+ * because only it knows what it can cope with:
+ *
+ * <pre>
+ *                | static (default)          | dynamic
+ *   -------------|---------------------------|--------------------------
+ *   mandatory    | unmet -&gt; pending;         | unmet -&gt; pending;
+ *   (default)    | lost  -&gt; pending,         | lost  -&gt; STAYS LIVE,
+ *                |          recursively      |          notified
+ *   -------------|---------------------------|--------------------------
+ *   optional:true| never gates activation;   | never gates activation;
+ *                | a change deactivates and  | a change is a
+ *                | reactivates               | notification, nothing else
+ * </pre>
+ *
+ * <p>{@code 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.
+ *
+ * <p>The rebinding-preference axis is deliberately omitted. OSGi has
+ * reluctant vs greedy and it is a knob every author must understand to
+ * read anyone else's component; we take always-reluctant. Three axes were
+ * more than the model can carry across twenty ports.
+ */
+public final class Depend {
+
+  private Depend() {}
+
+  /** A node of the requirement graph, as plain data for the detector. */
+  public static final class Node {
+    public final String ref;
+    public final List<String> provides;
+    public final List<Object> requires;
+
+    public Node(String ref, List<String> provides, List<Object> requires) {
+      this.ref = ref;
+      this.provides = provides;
+      this.requires = requires;
+    }
+  }
+
+  /** A bare string is shorthand for {@code {name}}. */
+  public static Map<String, Object> normrequire(Object raw) {
+    Map<String, Object> out = newmap();
+    if (raw instanceof String) {
+      out.put("name", raw);
+      return out;
+    }
+    Map<String, Object> m = map(raw);
+    if (null != m) {
+      out.putAll(m);
+    }
+    return out;
+  }
+
+  /**
+   * The requirements a definition declared, normalized.
+   *
+   * <p>BOTH AXES ARE READ AT TWO LEVELS, AND THE PER-REQUIREMENT ONE WINS.
+   *
+   * <p>The instance-level {@code policy} and {@code optional} list are how
+   * a DOCUMENT states the axis without editing the definition, and they
+   * apply to every requirement. The per-requirement form is the one
+   * §11.1's object syntax exists for, and it is strictly more expressive:
+   * an instance that is {@code static} on its store and {@code dynamic} on
+   * its metrics cannot be written at all at the instance level.
+   *
+   * <p>{@code optional} unions rather than overriding - both spellings are
+   * statements that this requirement need not gate activation, and there
+   * is no reading under which one of them means "actually, mandatory".
+   */
+  public static List<Object> requirements(Object options) {
+    List<Object> raw = list(get(options, "requires"));
+    raw = null == raw ? new ArrayList<>() : raw;
+    List<Object> marked = list(get(options, "optional"));
+    Object fallback = get(options, "policy");
+
+    List<Object> out = new ArrayList<>();
+    for (Object item : raw) {
+      Map<String, Object> req = normrequire(item);
+      boolean ismarked = false;
+      if (null != marked) {
+        for (Object m : marked) {
+          if (same(m, req.get("name"))) {
+            ismarked = true;
+            break;
+          }
+        }
+      }
+      if (truthy(req.get("optional")) || ismarked) {
+        req.put("optional", Boolean.TRUE);
+      }
+      if (null == req.get("policy") && null != fallback) {
+        req.put("policy", fallback);
+      }
+      out.add(req);
+    }
+    return out;
+  }
+
+  /**
+   * Does losing this requirement's SELECTED provider restart the consumer?
+   * The mandatory ones under {@code static}, and the {@code static}
+   * optional ones - both make a capability change deactivate and
+   * reactivate. {@code dynamic} never restarts.
+   */
+  public static boolean restartsonloss(Object req) {
+    String policy = str(get(req, "policy"));
+    return !"dynamic".equals(null == policy ? "static" : policy);
+  }
+
+  /**
+   * Does an unmet requirement keep the consumer out of {@code live}?
+   *
+   * <p>Cardinality alone decides this, NOT policy. {@code dynamic} is a
+   * statement about surviving a SWAP, not about starting without the thing
+   * at all - a mandatory-dynamic consumer still waits in {@code pending}
+   * for its first provider.
+   */
+  public static boolean gatesactivation(Object req) {
+    return !Boolean.TRUE.equals(get(req, "optional"));
+  }
+
+  /**
+   * Edges that can cause a restart, which is exactly the set a cycle must
+   * be detected over (§11.3).
+   *
+   * <p>ONLY {@code dynamic} OPTIONAL EDGES ARE EXCLUDED, and they are the
+   * ones the exclusion was for: two plugins that optionally and
+   * dynamically consume each other's capabilities both activate happily,
+   * neither gates on the other, and each is merely notified when the other
+   * appears. Nothing restarts, so nothing oscillates.
+   *
+   * <p>An earlier draft of §11.3 excluded EVERY optional edge and thereby
+   * admitted the non-terminating case it was trying to permit.
+   */
+  public static boolean restartcausing(Object req) {
+    return gatesactivation(req) || restartsonloss(req);
+  }
+
+  /**
+   * A cycle through restart-causing requirements is {@code
+   * plugin_dependency_cycle}, detected AT LOAD - before anything runs,
+   * because the failure it describes is a non-terminating reconcile and
+   * the only safe time to report that is before it starts.
+   *
+   * <p>The graph is over capabilities, not refs: an edge runs from a
+   * consumer to EVERY node that provides what it needs, because any of
+   * them could be the one selected and a cycle through any is a cycle. A
+   * node also satisfies its own name as a ref (§11.1), which is why the
+   * ref is a provider of itself here.
+   */
+  public static List<String> dependencycycle(List<Node> 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 (section 4 rule 5) - and one map keyed by
+    // both can only do one of them. Keyed by both and looked up raw, as
+    // this was, a cycle spelled `a$`/`b$` found no providers and EVADED
+    // the load-time check that exists to catch a non-terminating
+    // reconcile.
+    Map<String, List<String>> bycap = new TreeMap<>();
+    Set<String> isref = new TreeSet<>();
+    for (Node n : nodes) {
+      isref.add(n.ref);
+      for (String cap : n.provides) {
+        bycap.computeIfAbsent(cap, k -> new ArrayList<>()).add(n.ref);
+      }
+    }
+
+    Map<String, List<String>> edges = new TreeMap<>();
+    for (Node n : nodes) {
+      List<String> out = new ArrayList<>();
+      for (Object req : n.requires) {
+        if (!restartcausing(req)) {
+          continue;
+        }
+        String reqname = str(get(req, "name"));
+        List<String> from = new ArrayList<>();
+        List<String> list = bycap.get(reqname);
+        if (null != list) {
+          from.addAll(list);
+        }
+        // A node satisfies its own name AS A REF (section 11.1),
+        // canonically - exactly what `providersof` does at runtime.
+        // `canon` hands back a name no ref could have unchanged, and no
+        // instance ref can equal one, so it is the tolerant test.
+        String asref = Refs.canon(null == reqname ? "" : reqname);
+        if (isref.contains(asref) && !from.contains(asref)) {
+          from.add(asref);
+        }
+        for (String p : from) {
+          if (!p.equals(n.ref) && !out.contains(p)) {
+            out.add(p);
+          }
+        }
+      }
+      out.sort(null);
+      edges.put(n.ref, out);
+    }
+
+    // Iterative DFS with an explicit stack: twenty ports, and several of
+    // them have no recursion budget worth relying on.
+    final int white = 0;
+    final int grey = 1;
+    final int black = 2;
+    Map<String, Integer> colour = new TreeMap<>();
+    for (Node n : nodes) {
+      colour.put(n.ref, white);
+    }
+
+    for (String start : new ArrayList<>(edges.keySet())) {
+      if (white != colour.get(start)) {
+        continue;
+      }
+
+      List<String> path = new ArrayList<>();
+      path.add(start);
+      List<Object[]> stack = new ArrayList<>();
+      stack.add(new Object[] {start, 0});
+      colour.put(start, grey);
+
+      while (!stack.isEmpty()) {
+        Object[] top = stack.get(stack.size() - 1);
+        String node = (String) top[0];
+        int index = (Integer) top[1];
+        List<String> outs = edges.get(node);
+        if (outs.size() <= index) {
+          colour.put(node, black);
+          stack.remove(stack.size() - 1);
+          path.remove(path.size() - 1);
+          continue;
+        }
+        String next = outs.get(index);
+        top[1] = index + 1;
+        if (grey == colour.get(next)) {
+          // Report the cycle itself, not the walk that found it.
+          List<String> cycle = new ArrayList<>(path.subList(path.indexOf(next), path.size()));
+          cycle.add(next);
+          return cycle;
+        }
+        if (black == colour.get(next)) {
+          continue;
+        }
+        colour.put(next, grey);
+        path.add(next);
+        stack.add(new Object[] {next, 0});
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Raise on a cycle, naming it. Separate from the detector so the
+   * detector stays pure and corpus-testable.
+   */
+  public static void checkcycle(List<Node> nodes) {
+    List<String> cycle = dependencycycle(nodes);
+    if (null == cycle) {
+      return;
+    }
+    fail(
+        "plugin_dependency_cycle",
+        "requirements cycle: " + String.join(" -> ", cycle),
+        details("cycle", Types.strings(cycle)));
+  }
+}

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

@@ -0,0 +1,49 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (java/src/voxgig/plugin/Entry.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.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+
+/** One instance's record. Mutable, and owned by the host. */
+public final class Entry {
+
+  /** A registered teardown (§8.3). */
+  public interface ScopeFn {
+    void run();
+  }
+
+  public final String ref;
+  public final Definition def;
+  public String status = "declared";
+  public double pos;
+  public double seq;
+  public Object options = Types.newmap();
+  public final Map<String, Object> state = new TreeMap<>();
+  public Object order;
+  public List<String> unmet = new ArrayList<>();
+  public List<ScopeFn> scope = new ArrayList<>();
+
+  /**
+   * §11.4's ALWAYS-RELUCTANT rebinding made concrete: the provider ref
+   * this instance's activation actually chose, per requirement name.
+   * Re-ranking on every question silently re-points a live consumer at any
+   * better newcomer, and then losing the provider it was really using does
+   * not restart it.
+   */
+  public Map<String, String> selected = new TreeMap<>();
+
+  public List<Point.Bound> bindings = new ArrayList<>();
+  public final Map<String, Object> exports = new TreeMap<>();
+  public List<Object> provides = new ArrayList<>();
+  public Host inner;
+  public boolean barred;
+
+  public Entry(String ref, Definition def) {
+    this.ref = ref;
+    this.def = def;
+  }
+}

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

@@ -0,0 +1,204 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (java/src/voxgig/plugin/Env.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.keys;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.list;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.map;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.newmap;
+import static JAVAPACKAGE.feature.secrets.plugin.Types.str;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+
+/**
+ * Environment overrides (§9.5) - level 7 of the ladder.
+ *
+ * <p>One prefix, so nothing drifts: {@code VOXGIG_PLUGIN_*}.
+ *
+ * <pre>
+ *   VOXGIG_PLUGIN_PROFILE            the profile name
+ *   VOXGIG_PLUGIN_&lt;REF&gt;_&lt;PATH&gt;       one option
+ *   VOXGIG_PLUGIN_ACTIVE/INACTIVE    comma-separated refs, INACTIVE wins
+ * </pre>
+ *
+ * <p>THE ENCODING IS LOSSY, AND THIS SAYS SO RATHER THAN PRETENDING
+ * OTHERWISE. Ref and path are upper-snake with {@code $} -&gt; {@code __}
+ * and {@code .} -&gt; {@code _}. But {@code _} is legal in a name and in a
+ * tag, and the mapping folds case, so {@code retry$fast} and {@code
+ * retry__fast} both encode to {@code RETRY__FAST}.
+ *
+ * <p>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 {@code plugin_env_ambiguous}, naming both.
+ */
+public final class Env {
+
+  private Env() {}
+
+  public static final String ENV_PREFIX = "VOXGIG_PLUGIN_";
+
+  /** {@code retry$fast} -&gt; {@code RETRY__FAST}. */
+  public static String encodeRef(String ref) {
+    return ref.replace("$", "__").replace(".", "_").toUpperCase(java.util.Locale.ROOT);
+  }
+
+  public static Map<String, Object> applyEnv(Object input) {
+    Object env = get(input, "env");
+    Object reserved = get(input, "reserved");
+
+    List<String> refs = new ArrayList<>();
+    List<Object> given = list(get(input, "refs"));
+    if (null != given) {
+      for (Object r : given) {
+        refs.add(Refs.canonRef(r));
+      }
+    }
+
+    Map<String, Object> out = newmap();
+    Map<String, Object> options = newmap();
+    out.put("options", options);
+    out.put("active", new ArrayList<>());
+    out.put("inactive", new ArrayList<>());
+
+    // 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.
+    Map<String, List<String>> byencoded = new TreeMap<>();
+    for (String r : refs) {
+      byencoded.computeIfAbsent(encodeRef(r), k -> new ArrayList<>()).add(r);
+    }
+    for (Map.Entry<String, List<String>> e : byencoded.entrySet()) {
+      if (e.getValue().size() <= 1) {
+        continue;
+      }
+      List<String> pair = new ArrayList<>(e.getValue());
+      pair.sort(null);
+      fail(
+          "plugin_env_ambiguous",
+          "refs collide in the environment encoding as "
+              + e.getKey()
+              + ": "
+              + String.join(", ", pair),
+          details("refs", Types.strings(pair)));
+    }
+
+    // Longest encoded ref first, so `retry$fast` wins over `retry` on
+    // `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+    List<String> encoded = new ArrayList<>(byencoded.keySet());
+    encoded.sort((a, b) -> Integer.compare(b.length(), a.length()));
+
+    for (String key : keys(env)) {
+      if (!key.startsWith(ENV_PREFIX)) {
+        continue;
+      }
+      String rest = key.substring(ENV_PREFIX.length());
+
+      if ("PROFILE".equals(rest)) {
+        out.put("profile", get(env, key));
+        continue;
+      }
+
+      if ("ACTIVE".equals(rest) || "INACTIVE".equals(rest)) {
+        List<Object> target = list(out.get("ACTIVE".equals(rest) ? "active" : "inactive"));
+        for (String raw : split(get(env, key))) {
+          String ref = Refs.canonRef(raw);
+          // 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(ref, reserved);
+          target.add(ref);
+        }
+        continue;
+      }
+
+      String enc = null;
+      for (String e : encoded) {
+        if (rest.equals(e) || rest.startsWith(e + "_")) {
+          enc = e;
+          break;
+        }
+      }
+      if (null == enc) {
+        continue; // not for any ref this host holds
+      }
+
+      String ref = byencoded.get(enc).get(0);
+      checkreserved(ref, reserved);
+
+      if (rest.equals(enc)) {
+        continue; // a ref with no path sets nothing
+      }
+
+      String[] path =
+          rest.substring(enc.length() + 1).toLowerCase(java.util.Locale.ROOT).split("_", -1);
+
+      if (null == map(options.get(ref))) {
+        options.put(ref, newmap());
+      }
+      Map<String, Object> node = map(options.get(ref));
+      for (int i = 0; i < path.length - 1; i++) {
+        if (null == map(node.get(path[i]))) {
+          node.put(path[i], newmap());
+        }
+        node = map(node.get(path[i]));
+      }
+      node.put(path[path.length - 1], parsevalue(get(env, key)));
+    }
+
+    return out;
+  }
+
+  private static List<String> split(Object value) {
+    List<String> out = new ArrayList<>();
+    String text = str(value);
+    if (null == text) {
+      return out;
+    }
+    for (String part : text.split(",", -1)) {
+      String trimmed = part.trim();
+      if (!trimmed.isEmpty()) {
+        out.add(trimmed);
+      }
+    }
+    return out;
+  }
+
+  private static void checkreserved(String ref, Object reserved) {
+    List<Object> list = list(reserved);
+    if (null == list || list.isEmpty()) {
+      return;
+    }
+    if (!list.contains(Refs.refname(ref))) {
+      return;
+    }
+    fail("plugin_ref_reserved", "ref is reserved by the host: " + ref, details("ref", ref));
+  }
+
+  /**
+   * Values parse as JSON, FALLING BACK TO STRING - so {@code 8080} is a
+   * number, {@code true} is a boolean, {@code {"a":1}} is a map, and
+   * {@code hello} is the string it looks like rather than a parse error.
+   */
+  private static Object parsevalue(Object value) {
+    String text = str(value);
+    if (null == text) {
+      return value;
+    }
+    try {
+      return Json.parse(text);
+    } catch (RuntimeException e) {
+      return value;
+    }
+  }
+}

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

@@ -0,0 +1,93 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (java/src/voxgig/plugin/Export.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.str;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Exports (§11).
+ *
+ * <p>An instance publishes values for other plugins and for the
+ * application. Read with {@code host.exports("retry$fast/client")}.
+ *
+ * <p>THE UNQUALIFIED ALIAS IS THE INTERESTING PART. {@code 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 {@code 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.
+ */
+public final class Export {
+
+  private Export() {}
+
+  /** One published value: which instance, under which key. */
+  public static final class Exported {
+    public final String ref;
+    public final String key;
+    public final Object value;
+
+    public Exported(String ref, String key, Object value) {
+      this.ref = ref;
+      this.key = key;
+      this.value = value;
+    }
+  }
+
+  public static Object resolveExport(String spec, List<Exported> exported) {
+    int cut = spec.indexOf('/');
+    if (cut < 0) {
+      fail("plugin_export_ambiguous", "export spec needs a key: " + spec, details("spec", spec));
+    }
+    String head = spec.substring(0, cut);
+    String key = spec.substring(cut + 1);
+
+    // A fully qualified ref: exactly one answer or none.
+    String want = Refs.canon(head);
+    for (Exported e : exported) {
+      if (e.ref.equals(want) && e.key.equals(key)) {
+        return e.value;
+      }
+    }
+
+    // An alias: the name, not a ref. Look at every instance of it.
+    List<Exported> byname = new ArrayList<>();
+    for (Exported e : exported) {
+      if (Refs.refname(e.ref).equals(head) && e.key.equals(key)) {
+        byname.add(e);
+      }
+    }
+    if (byname.isEmpty()) {
+      return null;
+    }
+
+    for (Exported e : byname) {
+      if (str(Refs.parseRef(e.ref).get("tag")).isEmpty()) {
+        return e.value;
+      }
+    }
+
+    if (1 == byname.size()) {
+      return byname.get(0).value;
+    }
+
+    List<String> refs = new ArrayList<>();
+    for (Exported e : byname) {
+      refs.add(e.ref);
+    }
+    refs.sort(null);
+    fail(
+        "plugin_export_ambiguous",
+        "alias " + spec + " matches " + refs.size() + " instances: " + String.join(", ", refs),
+        // `spec` is not one of §12's fields, so it does not render - the
+        // same detail map every other port builds, and the same message.
+        details("spec", spec, "refs", Types.strings(refs)));
+    return null;
+  }
+}