@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Depend.kt

@@ -0,0 +1,227 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Depend.kt)
+// 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 KOTLINPACKAGE.feature.secrets.plugin
+
+/**
+ * Dependency cardinality, policy, and the restart graph (section 11.3).
+ *
+ * TWO AXES, BOTH DECLARED BY THE DEFINITION THAT HAS THE REQUIREMENT, because
+ * only it knows what it can cope with:
+ *
+ *                | static (default)          | dynamic
+ *   -------------|---------------------------|--------------------------
+ *   mandatory    | unmet -> pending;         | unmet -> pending;
+ *   (default)    | lost  -> pending,         | lost  -> STAYS LIVE,
+ *                |          recursively      |          notified
+ *   -------------|---------------------------|--------------------------
+ *   optional:true| never gates activation;   | never gates activation;
+ *                | a change deactivates and  | a change is a
+ *                | reactivates               | notification, nothing else
+ *
+ * `dynamic` means the plugin has said, IN WRITING, that it can survive its
+ * provider being swapped underneath it. It is not the default because most
+ * plugins cannot, and the cost of wrongly assuming they can is a live instance
+ * holding a dead reference.
+ *
+ * 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.
+ */
+
+/** One node of the requirement graph. An internal shape, never a corpus value. */
+data class GraphNode(
+    val ref: String,
+    val provides: List<String>,
+    val requires: List<Map<String, Any?>>
+)
+
+object Depend {
+
+    /** A bare string is shorthand for `{name}`. */
+    fun normRequire(raw: Any?): MutableMap<String, Any?> {
+        val out = java.util.TreeMap<String, Any?>()
+        if (raw is String) {
+            out["name"] = raw
+            return out
+        }
+        if (raw is Map<*, *>) {
+            for (k in Types.keys(raw)) out[k] = Types.get(raw, k)
+        }
+        return out
+    }
+
+    /**
+     * The requirements a definition declared, normalized.
+     *
+     * BOTH AXES ARE READ AT TWO LEVELS, AND THE PER-REQUIREMENT ONE WINS.
+     *
+     * The instance-level `policy` and `optional` list are how a DOCUMENT
+     * states the axis without editing the definition, and they apply to every
+     * requirement. The per-requirement form is the one section 11.1's object
+     * syntax exists for, and it is strictly more expressive: an instance that
+     * is `static` on its store and `dynamic` on its metrics cannot be written
+     * at all at the instance level.
+     *
+     * `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".
+     */
+    fun requirements(options: Any?): List<Map<String, Any?>> {
+        val raw = (Types.get(options, "requires") ?: emptyList<Any?>()) as List<*>
+        val marked = Types.get(options, "optional")
+        val fallback = Types.get(options, "policy")
+
+        return raw.map { item ->
+            val req = normRequire(item)
+            if (Types.truthy(req["optional"]) ||
+                (marked is List<*> && marked.contains(req["name"]))
+            ) {
+                req["optional"] = true
+            }
+            if (null == req["policy"] && null != fallback) req["policy"] = fallback
+            req
+        }
+    }
+
+    /**
+     * Does losing this requirement's SELECTED provider restart the consumer?
+     * The mandatory ones under `static`, and the `static` optional ones - both
+     * make a capability change deactivate and reactivate. `dynamic` never
+     * restarts.
+     */
+    fun restartsOnLoss(req: Any?): Boolean =
+        "dynamic" != (Types.get(req, "policy") ?: "static")
+
+    /**
+     * Does an unmet requirement keep the consumer out of `live`?
+     *
+     * Cardinality alone decides this, NOT policy. `dynamic` is a statement
+     * about surviving a SWAP, not about starting without the thing at all - a
+     * mandatory-dynamic consumer still waits in `pending` for its first
+     * provider.
+     */
+    fun gatesActivation(req: Any?): Boolean = true != Types.get(req, "optional")
+
+    /**
+     * Edges that can cause a restart, which is exactly the set a cycle must be
+     * detected over (section 11.3).
+     *
+     * ONLY `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. An earlier draft of section 11.3
+     * excluded EVERY optional edge and thereby admitted the non-terminating
+     * case it was trying to permit.
+     */
+    fun restartCausing(req: Any?): Boolean = gatesActivation(req) || restartsOnLoss(req)
+
+    /**
+     * A cycle through restart-causing requirements is
+     * `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.
+     *
+     * 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 (section 11.1), which is why the ref is
+     * a provider of itself here.
+     */
+    fun dependencyCycle(nodes: List<GraphNode>): List<String>? {
+        // 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.
+        val bycap = HashMap<String, MutableList<String>>()
+        val isref = HashSet<String>()
+        for (n in nodes) {
+            isref.add(n.ref)
+            for (cap in n.provides) {
+                bycap.getOrPut(cap) { ArrayList() }.add(n.ref)
+            }
+        }
+
+        val edges = HashMap<String, List<String>>()
+        for (n in nodes) {
+            val out = ArrayList<String>()
+            for (req in n.requires) {
+                if (!restartCausing(req)) continue
+                val reqname = Types.get(req, "name")
+                val from = ArrayList<String>(bycap[reqname] ?: emptyList<String>())
+                // 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.
+                val asref = Refs.canon(reqname)
+                if (isref.contains(asref) && !from.contains(asref)) from.add(asref)
+                for (p in from) {
+                    if (p != n.ref && !out.contains(p)) out.add(p)
+                }
+            }
+            edges[n.ref] = out.sorted()
+        }
+
+        // Iterative DFS with an explicit stack: twenty ports, and several of
+        // them have no recursion budget worth relying on.
+        val white = 0
+        val grey = 1
+        val black = 2
+        val colour = HashMap<String, Int>()
+        for (n in nodes) colour[n.ref] = white
+
+        for (start in edges.keys.sorted()) {
+            if (white != colour[start]) continue
+
+            val path = ArrayList<String>()
+            path.add(start)
+            val stack = ArrayList<IntArray>()
+            val nodeAt = ArrayList<String>()
+            stack.add(intArrayOf(0))
+            nodeAt.add(start)
+            colour[start] = grey
+
+            while (stack.isNotEmpty()) {
+                val node = nodeAt[nodeAt.size - 1]
+                val cursor = stack[stack.size - 1]
+                val outs = edges[node]!!
+                if (cursor[0] >= outs.size) {
+                    colour[node] = black
+                    stack.removeAt(stack.size - 1)
+                    nodeAt.removeAt(nodeAt.size - 1)
+                    path.removeAt(path.size - 1)
+                    continue
+                }
+                val next = outs[cursor[0]]
+                cursor[0]++
+                if (grey == colour[next]) {
+                    // Report the cycle itself, not the walk that found it.
+                    return path.subList(path.indexOf(next), path.size).toList() + next
+                }
+                if (black == colour[next]) continue
+                colour[next] = grey
+                path.add(next)
+                stack.add(intArrayOf(0))
+                nodeAt.add(next)
+            }
+        }
+        return null
+    }
+
+    /**
+     * Raise on a cycle, naming it. Separate from the detector so the detector
+     * stays pure and corpus-testable.
+     */
+    fun checkCycle(nodes: List<GraphNode>) {
+        val cycle = dependencyCycle(nodes) ?: return
+        Types.fail(
+            "plugin_dependency_cycle", "requirements cycle: ${cycle.joinToString(" -> ")}",
+            mapOf("cycle" to cycle)
+        )
+    }
+}

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Env.kt

@@ -0,0 +1,163 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Env.kt)
+// 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 KOTLINPACKAGE.feature.secrets.plugin
+
+import java.util.TreeMap
+
+/**
+ * Environment overrides (section 9.5) - level 7 of the ladder.
+ *
+ * One prefix, so nothing drifts: `VOXGIG_PLUGIN_*`.
+ *
+ *   VOXGIG_PLUGIN_PROFILE            the profile name
+ *   VOXGIG_PLUGIN_<REF>_<PATH>       one option
+ *   VOXGIG_PLUGIN_ACTIVE/INACTIVE    comma-separated refs, INACTIVE wins
+ *
+ * THE ENCODING IS LOSSY, AND THIS SAYS SO RATHER THAN PRETENDING OTHERWISE.
+ * Ref and path are upper-snake with `$` -> `__` and `.` -> `_`. But `_` is
+ * legal in a name and in a tag, and the mapping folds case, so `retry$fast`
+ * and `retry__fast` both encode to `RETRY__FAST`.
+ *
+ * Rather than restrict a grammar the rest of the stack already uses, the host
+ * DETECTS THE COLLISION: it encodes every ref it holds, and a key two refs
+ * claim is `plugin_env_ambiguous`, naming both.
+ */
+object Env {
+
+    private const val PREFIX = "VOXGIG_PLUGIN_"
+
+    /** `retry$fast` -> `RETRY__FAST`. */
+    fun encodeRef(ref: String): String =
+        upperAscii(ref.replace("$", "__").replace(".", "_"))
+
+    // ASCII, AND SPELLED THE LONG WAY, FOR TWO REASONS.
+    //
+    // LOCALE: an environment variable name must not depend on the JVM's
+    // default locale. `String.toUpperCase()` does -- in tr-TR it maps "i" to
+    // "\u0130", so `retry$fast` would encode to a name no shell can set.
+    //
+    // COMPILER: the fix the deprecation warning suggests, `uppercase()`, is
+    // Kotlin 1.5+. CI compiles this port with ubuntu's `kotlin` package,
+    // which is 1.3.31, where that name does not resolve at all. `toUpperCase`
+    // is deprecated from 1.5 and the Makefile builds with -Werror, so the
+    // stdlib call fails on ONE of the two compilers whichever one is chosen.
+    // A char range resolves on both and warns on neither.
+    private fun upperAscii(s: String): String =
+        buildString(s.length) { for (c in s) append(if (c in 'a'..'z') c - 32 else c) }
+
+    private fun lowerAscii(s: String): String =
+        buildString(s.length) { for (c in s) append(if (c in 'A'..'Z') c + 32 else c) }
+
+    /**
+     * Values parse as JSON, FALLING BACK TO STRING - so `8080` is a number,
+     * `true` is a boolean, `{"a":1}` is a map, and `hello` is the string it
+     * looks like rather than a parse error.
+     */
+    private fun parseValue(value: Any?): Any? = try {
+        Json.parse(value as String)
+    } catch (e: Exception) {
+        value
+    }
+
+    private fun split(value: Any?): List<String> =
+        value.toString().split(",").map { it.trim() }.filter { "" != it }
+
+    private fun checkReserved(ref: String, reserved: List<*>) {
+        if (!reserved.contains(Refs.refName(ref))) return
+        Types.fail(
+            "plugin_ref_reserved", "ref is reserved by the host: $ref",
+            mapOf("ref" to ref)
+        )
+    }
+
+    fun applyEnv(input: Any?): Map<String, Any?> {
+        val env = Types.get(input, "env") ?: emptyMap<String, Any?>()
+        val refs = ((Types.get(input, "refs") ?: emptyList<Any?>()) as List<*>)
+            .map { Refs.canonRef(it) }
+        val reserved = (Types.get(input, "reserved") ?: emptyList<Any?>()) as List<*>
+
+        val options = TreeMap<String, Any?>()
+        val active = ArrayList<String>()
+        val inactive = ArrayList<String>()
+        val out = TreeMap<String, Any?>()
+        out["options"] = options
+        out["active"] = active
+        out["inactive"] = inactive
+
+        // Encode every ref the host holds, and refuse a key that two of them
+        // claim. Done up front so the collision is reported even when no
+        // environment variable exercises it - a latent ambiguity is still an
+        // ambiguity, and finding it at deploy time is the failure this exists
+        // to prevent.
+        val byencoded = TreeMap<String, MutableList<String>>()
+        for (ref in refs) byencoded.getOrPut(encodeRef(ref)) { ArrayList() }.add(ref)
+        for ((e, group) in byencoded) {
+            if (1 >= group.size) continue
+            val pair = group.sorted()
+            Types.fail(
+                "plugin_env_ambiguous",
+                "refs collide in the environment encoding as $e: ${pair.joinToString(", ")}",
+                mapOf("encoded" to e, "refs" to pair)
+            )
+        }
+
+        // Longest encoded ref first, so `retry$fast` wins over `retry` on
+        // `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+        val encoded = Types.stableSortBy(byencoded.keys.toList()) { listOf(-it.length) }
+
+        for (key in Types.keys(env)) {
+            if (!key.startsWith(PREFIX)) continue
+            val rest = key.substring(PREFIX.length)
+
+            if ("PROFILE" == rest) {
+                out["profile"] = Types.get(env, key)
+                continue
+            }
+
+            if ("ACTIVE" == rest || "INACTIVE" == rest) {
+                for (raw in split(Types.get(env, key))) {
+                    val ref = Refs.canonRef(raw)
+                    // The reservation covers EVERY input layer (section 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)
+                    if ("ACTIVE" == rest) active.add(ref) else inactive.add(ref)
+                }
+                continue
+            }
+
+            val enc = encoded.firstOrNull { rest == it || rest.startsWith(it + "_") }
+                ?: continue // not for any ref this host holds
+
+            val ref = byencoded[enc]!![0]
+            checkReserved(ref, reserved)
+
+            if (rest == enc) continue // a ref with no path sets nothing
+
+            val path = lowerAscii(rest.substring(enc.length + 1)).split("_")
+
+            var node = options[ref]
+            if (node !is MutableMap<*, *>) {
+                node = TreeMap<String, Any?>()
+                options[ref] = node
+            }
+            @Suppress("UNCHECKED_CAST")
+            var cursor = node as MutableMap<String, Any?>
+            for (i in 0 until path.size - 1) {
+                var child = cursor[path[i]]
+                if (child !is MutableMap<*, *>) {
+                    child = TreeMap<String, Any?>()
+                    cursor[path[i]] = child
+                }
+                @Suppress("UNCHECKED_CAST")
+                cursor = child as MutableMap<String, Any?>
+            }
+            cursor[path[path.size - 1]] = parseValue(Types.get(env, key))
+        }
+
+        return out
+    }
+}

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Export.kt

@@ -0,0 +1,57 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Export.kt)
+// 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 KOTLINPACKAGE.feature.secrets.plugin
+
+/**
+ * Exports (section 11).
+ *
+ * An instance publishes values for other plugins and for the application.
+ * Read with `host.exports("retry$fast/client")`.
+ *
+ * THE UNQUALIFIED ALIAS IS THE INTERESTING PART. `retry/client` resolves to
+ * the UNTAGGED instance if one exists; if not, and exactly one tagged
+ * instance exports that key, it resolves to that one; if two do, it is
+ * `plugin_export_ambiguous` - deliberately diverging from seneca's silent
+ * last-wins, because with multi-instance as a headline feature an ambiguous
+ * alias is a defect waiting for production.
+ */
+object Export {
+
+    /** One published value. An internal shape, never a corpus value. */
+    data class Exported(val ref: String, val key: String, val value: Any?)
+
+    fun resolveExport(spec: String, exported: List<Exported>): Any? {
+        val cut = spec.indexOf('/')
+        if (0 > cut) {
+            Types.fail(
+                "plugin_export_ambiguous", "export spec needs a key: $spec",
+                mapOf("spec" to spec)
+            )
+        }
+        val head = spec.substring(0, cut)
+        val key = spec.substring(cut + 1)
+
+        // A fully qualified ref: exactly one answer or none.
+        val want = Refs.canon(head)
+        for (e in exported) {
+            if (e.ref == want && e.key == key) return e.value
+        }
+
+        // An alias: the name, not a ref. Look at every instance of it.
+        val byname = exported.filter { Refs.refName(it.ref) == head && it.key == key }
+        if (byname.isEmpty()) return null
+
+        for (e in byname) {
+            if ("" == Refs.parseRef(e.ref)["tag"]) return e.value
+        }
+        if (1 == byname.size) return byname[0].value
+
+        val refs = byname.map { it.ref }.sorted()
+        Types.fail(
+            "plugin_export_ambiguous",
+            "alias $spec matches ${refs.size} instances: ${refs.joinToString(", ")}",
+            mapOf("spec" to spec, "refs" to refs)
+        )
+    }
+}

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Graph.kt

@@ -0,0 +1,179 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Graph.kt)
+// 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 KOTLINPACKAGE.feature.secrets.plugin
+
+import java.util.TreeMap
+
+/**
+ * Whole-graph resolution (section 11.4) - a phase, not a discovery.
+ *
+ * "Activate, and wait in `pending` if you must" is correct and, on its own,
+ * produces a terrible experience: apply twenty instances against a registry
+ * missing one thing and you get NINETEEN pending rows and no statement of what
+ * is actually wrong.
+ *
+ * `resolveGraph` is a PURE FUNCTION of the registry and the intended
+ * activation set. No callbacks run, no state changes, nothing is touched. It
+ * answers for the whole graph at once which instances can be live, and for
+ * each blocked one THE SPECIFIC REQUIREMENT that is unmet, and why.
+ *
+ * The failure mode being designed against is a famous one: OSGi's resolver is
+ * correct and its diagnostics are legendarily unusable. A resolver that says
+ * "blocked" without saying WHY has moved the problem rather than solved it, so
+ * `why` is part of the contract and the corpus pins its shape.
+ */
+object Graph {
+
+    fun resolveGraph(nodes: Any?): Map<String, Any?> {
+        val list = nodes as List<*>
+        val byref = TreeMap<String, Any?>()
+        for (n in list) byref[Types.get(n, "ref") as String] = n
+
+        val resolved = HashSet<String>()
+
+        // Fixed point: a node resolves when every mandatory requirement is met
+        // by an ALREADY-RESOLVED provider. Iterating to a fixed point is what
+        // makes a provider that is itself blocked propagate, rather than each
+        // node being judged against the raw registry.
+        var moved = true
+        while (moved) {
+            moved = false
+            for (n in list) {
+                val ref = Types.get(n, "ref") as String
+                if (resolved.contains(ref)) continue
+                if (null != firstUnmet(n, byref, resolved)) continue
+                resolved.add(ref)
+                moved = true
+            }
+        }
+
+        val blocked = TreeMap<String, Any?>()
+        for (n in list) {
+            val ref = Types.get(n, "ref") as String
+            if (resolved.contains(ref)) continue
+            val why = firstUnmet(n, byref, resolved) ?: continue
+            blocked[ref] = why
+        }
+
+        val out = TreeMap<String, Any?>()
+        out["resolved"] = resolved.sorted()
+        out["blocked"] = blocked.values.toList()
+        return out
+    }
+
+    /**
+     * The FIRST unmet requirement, with the most specific explanation
+     * available. Order matters: "no provider at all" and "a provider at the
+     * wrong version" are different problems and a reader must not have to
+     * guess which they have.
+     */
+    fun firstUnmet(node: Any?, byref: Map<String, Any?>, resolved: Set<String>): Any? {
+        for (req in (Types.get(node, "requires") ?: emptyList<Any?>()) as List<*>) {
+            if (Types.truthy(Types.get(req, "optional"))) continue
+            val name = Types.get(req, "name") as String
+
+            val all = graphCandidates(byref, name)
+            if (all.isEmpty()) return why(node, name, reason("absent"))
+
+            val ok = Capability.resolveCapability(req, all)
+            if (ok.isNotEmpty()) {
+                // A provider exists and matches - but if none of them is itself
+                // resolved, this node is blocked BEHIND it, and the chain is
+                // the useful answer rather than "unmet".
+                if (ok.any { resolved.contains(Types.get(it, "ref")) }) continue
+                val chain = ok.map { Types.get(it, "ref") as String }.sorted()
+                val r = reason("blocked")
+                r["chain"] = chain
+                return why(node, name, r)
+            }
+
+            // Providers exist and none matched. Say which test failed.
+            val range = Types.get(req, "range")
+            if (null != range) {
+                val versions = all
+                    .map { Types.get(Types.get(it, "provides"), "version") }
+                    .filter { null == it || !Version.satisfiesq(it, range) }
+                    .map { (it ?: "(none)") as String }
+                if (versions.isNotEmpty()) {
+                    val r = reason("version")
+                    r["range"] = range
+                    r["found"] = versions.sorted()
+                    return why(node, name, r)
+                }
+            }
+
+            val match = Types.get(req, "match")
+            if (null != match) {
+                for (c in all) {
+                    val attrs = Types.get(Types.get(c, "provides"), "attrs")
+                        ?: emptyMap<String, Any?>()
+                    for (k in Types.keys(match)) {
+                        if (Types.has(attrs, k) &&
+                            Capability.matchValue(Types.get(match, k), Types.get(attrs, k))
+                        ) {
+                            continue
+                        }
+                        val r = reason("match")
+                        r["failing"] = k
+                        r["want"] = Types.get(match, k)
+                        r["found"] = Types.get(attrs, k)
+                        return why(node, name, r)
+                    }
+                }
+            }
+
+            return why(node, name, reason("absent"))
+        }
+        return null
+    }
+
+    private fun reason(kind: String): TreeMap<String, Any?> {
+        val out = TreeMap<String, Any?>()
+        out["kind"] = kind
+        return out
+    }
+
+    private fun why(node: Any?, name: String, reason: Any?): Map<String, Any?> {
+        val out = TreeMap<String, Any?>()
+        out["ref"] = Types.get(node, "ref")
+        out["unmet"] = name
+        out["why"] = reason
+        return out
+    }
+
+    fun graphCandidates(byref: Map<String, Any?>, name: String): List<Any?> {
+        val out = ArrayList<Any?>()
+        // A NODE SATISFIES ITS OWN REF (section 11.1), and the graph
+        // learned it here. Considering only declared capabilities made
+        // `resolve` answer `absent` about a provider sitting right there
+        // and live - section 11.4's job is explaining the graph the
+        // runtime reconciles, and it was explaining a different one.
+        val asref = Refs.canon(name)
+        for (ref in Types.keys(byref)) {
+            val node = byref[ref]
+            // The ref match WINS OUTRIGHT for that node, as at runtime:
+            // one candidate, not two, for a node both named `b` and
+            // providing `b`.
+            if (ref == asref) {
+                val rc = TreeMap<String, Any?>()
+                rc["ref"] = Types.get(node, "ref")
+                rc["pos"] = Types.get(node, "pos") ?: 0.0
+                val prov0 = TreeMap<String, Any?>()
+                prov0["name"] = name
+                rc["provides"] = prov0
+                out.add(rc)
+                continue
+            }
+            for (prov in (Types.get(node, "provides") ?: emptyList<Any?>()) as List<*>) {
+                if (Types.get(prov, "name") != name) continue
+                val c = TreeMap<String, Any?>()
+                c["ref"] = Types.get(node, "ref")
+                c["pos"] = Types.get(node, "pos") ?: 0.0
+                c["provides"] = prov
+                out.add(c)
+            }
+        }
+        return out
+    }
+}