@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/depend.ex

@@ -0,0 +1,205 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/depend.ex)
+# 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.
+defmodule Voxgig.Plugin.Depend do
+  @moduledoc """
+  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: a mandatory-static
+  requirement gates activation and restarts on loss; a mandatory-dynamic
+  one gates but survives a swap; an optional-static one never gates but
+  restarts on a change; an optional-dynamic one is a notification and
+  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.
+  """
+
+  alias Voxgig.Plugin.Ref
+  alias Voxgig.Plugin.Types
+
+  @doc "A bare string is shorthand for `{name}`."
+  def normrequire(raw) when is_binary(raw), do: %{"name" => raw}
+  def normrequire(raw) when is_map(raw), do: raw
+  def normrequire(_), do: %{}
+
+  @doc """
+  The requirements a definition declared, normalized.
+
+  BOTH AXES ARE READ AT TWO LEVELS, AND THE PER-REQUIREMENT ONE WINS.
+  `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".
+  """
+  def requirements(options) do
+    raw = Types.get(options, "requires") || []
+    marked = Types.get(options, "optional")
+    fallback = Types.get(options, "policy")
+
+    Enum.map(raw, fn item ->
+      req = normrequire(item)
+      ismarked = is_list(marked) and Types.get(req, "name") in marked
+
+      req =
+        if Types.truthy(Types.get(req, "optional")) or ismarked do
+          Map.put(req, "optional", true)
+        else
+          req
+        end
+
+      if is_nil(Types.get(req, "policy")) and not is_nil(fallback) do
+        Map.put(req, "policy", fallback)
+      else
+        req
+      end
+    end)
+  end
+
+  @doc """
+  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.
+  """
+  def restartsonloss(req), do: "dynamic" != (Types.get(req, "policy") || "static")
+
+  @doc """
+  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.
+  """
+  def gatesactivation(req), do: true != Types.get(req, "optional")
+
+  @doc """
+  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
+  - an earlier draft excluded EVERY optional edge and thereby admitted the
+  non-terminating case it was trying to permit.
+  """
+  def restartcausing(req), do: gatesactivation(req) or restartsonloss(req)
+
+  @doc """
+  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.
+
+  `nodes` is a list of `%{ref:, provides:, requires:}`.
+  """
+  def dependencycycle(nodes) do
+    # 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.
+    bycap =
+      Enum.reduce(nodes, %{}, fn n, acc ->
+        Enum.reduce(n.provides, acc, fn cap, a ->
+          Map.update(a, cap, [n.ref], &(&1 ++ [n.ref]))
+        end)
+      end)
+
+    isref = MapSet.new(nodes, & &1.ref)
+
+    edges =
+      Map.new(nodes, fn n ->
+        outs =
+          n.requires
+          |> Enum.filter(&restartcausing/1)
+          |> Enum.flat_map(fn req ->
+            reqname = Types.get(req, "name")
+            from = Map.get(bycap, reqname) || []
+            # 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.
+            asref = Ref.canon(reqname)
+            if MapSet.member?(isref, asref), do: from ++ [asref], else: from
+          end)
+          |> Enum.reject(&(&1 == n.ref))
+          |> Enum.uniq()
+          |> Enum.sort()
+
+        {n.ref, outs}
+      end)
+
+    # Iterative DFS with an explicit stack: twenty ports, and several of
+    # them have no recursion budget worth relying on. Elixir's stack is
+    # fine, but the shape stays the same so the ports read alike.
+    colour = Map.new(nodes, fn n -> {n.ref, :white} end)
+    starts = edges |> Map.keys() |> Enum.sort()
+    Enum.reduce_while(starts, nil, fn start, _ ->
+      case dfs(start, edges, colour) do
+        {:cycle, cycle} -> {:halt, cycle}
+        {:done, colour} -> {:cont, colour} |> then(fn {_, c} -> {:cont, c} end)
+      end
+    end)
+    |> case do
+      cycle when is_list(cycle) -> cycle
+      _ -> nil
+    end
+  end
+
+  defp dfs(start, edges, colour) do
+    if :white != Map.get(colour, start) do
+      {:done, colour}
+    else
+      walk([{start, 0}], [start], Map.put(colour, start, :grey), edges)
+    end
+  end
+
+  defp walk([], _path, colour, _edges), do: {:done, colour}
+
+  defp walk([{node, index} | rest], path, colour, edges) do
+    outs = Map.get(edges, node)
+
+    if index >= length(outs) do
+      walk(rest, Enum.drop(path, -1), Map.put(colour, node, :black), edges)
+    else
+      nxt = Enum.at(outs, index)
+      stack = [{node, index + 1} | rest]
+
+      case Map.get(colour, nxt) do
+        :grey ->
+          # Report the cycle itself, not the walk that found it.
+          at = Enum.find_index(path, &(&1 == nxt))
+          {:cycle, Enum.drop(path, at) ++ [nxt]}
+
+        :black ->
+          walk(stack, path, colour, edges)
+
+        _ ->
+          walk([{nxt, 0} | stack], path ++ [nxt], Map.put(colour, nxt, :grey), edges)
+      end
+    end
+  end
+
+  @doc """
+  Raise on a cycle, naming it. Separate from the detector so the detector
+  stays pure and corpus-testable.
+  """
+  def checkcycle(nodes) do
+    case dependencycycle(nodes) do
+      nil ->
+        :ok
+
+      cycle ->
+        Types.fail("plugin_dependency_cycle",
+                   "requirements cycle: #{Enum.join(cycle, " -> ")}", %{"cycle" => cycle})
+    end
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/env.ex

@@ -0,0 +1,166 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/env.ex)
+# 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.
+defmodule Voxgig.Plugin.Env do
+  @moduledoc """
+  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.
+  """
+
+  alias Voxgig.Plugin.Json
+  alias Voxgig.Plugin.Ref
+  alias Voxgig.Plugin.Types
+
+  @prefix "VOXGIG_PLUGIN_"
+
+  @doc "`retry$fast` -> `RETRY__FAST`."
+  def encode_ref(ref) do
+    ref |> String.replace("$", "__") |> String.replace(".", "_") |> String.upcase()
+  end
+
+  def apply_env(input) do
+    input = input || %{}
+    env = Types.get(input, "env") || %{}
+    reserved = Types.get(input, "reserved") || []
+    refs = Enum.map(Types.get(input, "refs") || [], &Ref.canon_ref/1)
+
+    # 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.
+    byencoded = Enum.group_by(refs, &encode_ref/1)
+
+    for e <- Types.keys(byencoded), 1 < length(Map.get(byencoded, e)) do
+      pair = Enum.sort(Map.get(byencoded, e))
+
+      Types.fail("plugin_env_ambiguous",
+                 "refs collide in the environment encoding as #{e}: #{Enum.join(pair, ", ")}",
+                 %{"encoded" => e, "refs" => pair})
+    end
+
+    # Longest encoded ref first, so `retry$fast` wins over `retry` on
+    # `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+    encoded = byencoded |> Types.keys() |> Types.stable_sort_by(&(-byte_size(&1)))
+
+    start = %{"options" => %{}, "active" => [], "inactive" => []}
+
+    Enum.reduce(Types.keys(env), start, fn key, acc ->
+      if String.starts_with?(key, @prefix) do
+        onekey(acc, key, String.replace_prefix(key, @prefix, ""), env, encoded, byencoded,
+               reserved)
+      else
+        acc
+      end
+    end)
+  end
+
+  defp onekey(acc, key, "PROFILE", env, _encoded, _byencoded, _reserved) do
+    Map.put(acc, "profile", Map.get(env, key))
+  end
+
+  defp onekey(acc, key, rest, env, _encoded, _byencoded, reserved)
+       when rest in ["ACTIVE", "INACTIVE"] do
+    field = if "ACTIVE" == rest, do: "active", else: "inactive"
+
+    added =
+      env
+      |> Map.get(key)
+      |> split()
+      |> Enum.map(fn raw ->
+        ref = Ref.canon_ref(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)
+        ref
+      end)
+
+    Map.put(acc, field, Map.get(acc, field) ++ added)
+  end
+
+  defp onekey(acc, key, rest, env, encoded, byencoded, reserved) do
+    enc = Enum.find(encoded, fn e -> rest == e or String.starts_with?(rest, e <> "_") end)
+
+    cond do
+      is_nil(enc) ->
+        # not for any ref this host holds
+        acc
+
+      true ->
+        ref = hd(Map.get(byencoded, enc))
+        checkreserved(ref, reserved)
+
+        if rest == enc do
+          # a ref with no path sets nothing
+          acc
+        else
+          path =
+            rest
+            |> String.replace_prefix(enc <> "_", "")
+            |> String.downcase()
+            |> String.split("_")
+
+          value = parsevalue(Map.get(env, key))
+          options = Map.get(acc, "options")
+          node = Map.get(options, ref)
+          node = if is_map(node), do: node, else: %{}
+          Map.put(acc, "options", Map.put(options, ref, setpath(node, path, value)))
+        end
+    end
+  end
+
+  # Write a value at a path, creating maps on the way down. A scalar in the
+  # way is REPLACED, which is the same rule every other port applies -
+  # spelled recursively here because elixir has no in-place write.
+  defp setpath(node, [last], value), do: Map.put(node, last, value)
+
+  defp setpath(node, [step | rest], value) do
+    child = Map.get(node, step)
+    child = if is_map(child), do: child, else: %{}
+    Map.put(node, step, setpath(child, rest, value))
+  end
+
+  defp split(value) when is_binary(value) do
+    value |> String.split(",") |> Enum.map(&String.trim/1) |> Enum.reject(&("" == &1))
+  end
+
+  defp split(_), do: []
+
+  defp checkreserved(_ref, []), do: :ok
+
+  defp checkreserved(ref, reserved) do
+    if Ref.refname(ref) in reserved do
+      Types.fail("plugin_ref_reserved", "ref is reserved by the host: #{ref}", %{"ref" => ref})
+    end
+
+    :ok
+  end
+
+  # 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.
+  defp parsevalue(value) when is_binary(value) do
+    Json.parse(value)
+  rescue
+    _ -> value
+  end
+
+  defp parsevalue(value), do: value
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/error.ex

@@ -0,0 +1,13 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/error.ex)
+# 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.
+defmodule Voxgig.Plugin.Error do
+  @moduledoc """
+  Every error carries a section 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.
+  """
+  defexception [:code, :text, :details, :message]
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/export.ex

@@ -0,0 +1,73 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/export.ex)
+# 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.
+defmodule Voxgig.Plugin.Export do
+  @moduledoc """
+  Exports (section 11).
+
+  An instance publishes values for other plugins and for the application.
+
+  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.
+  """
+
+  alias Voxgig.Plugin.Ref
+  alias Voxgig.Plugin.Types
+
+  @doc """
+  `exported` is a list of `%{ref:, key:, value:}` - an internal shape,
+  never a corpus value, so it uses atom keys where the data does not.
+  """
+  def resolve_export(spec, exported) do
+    case :binary.match(spec, "/") do
+      :nomatch ->
+        Types.fail("plugin_export_ambiguous", "export spec needs a key: #{spec}",
+                   %{"spec" => spec})
+
+      {at, _} ->
+        head = binary_part(spec, 0, at)
+        key = binary_part(spec, at + 1, byte_size(spec) - at - 1)
+        lookup(spec, head, key, exported)
+    end
+  end
+
+  defp lookup(spec, head, key, exported) do
+    want = Ref.canon(head)
+
+    # A fully qualified ref: exactly one answer or none.
+    qualified = Enum.find(exported, fn e -> e.ref == want and e.key == key end)
+
+    if qualified do
+      qualified.value
+    else
+      # An alias: the name, not a ref. Look at every instance of it.
+      byname = Enum.filter(exported, fn e -> Ref.refname(e.ref) == head and e.key == key end)
+      alias_of(spec, byname)
+    end
+  end
+
+  defp alias_of(_spec, []), do: nil
+
+  defp alias_of(spec, byname) do
+    untagged = Enum.find(byname, fn e -> "" == Ref.parse_ref(e.ref)["tag"] end)
+
+    cond do
+      untagged ->
+        untagged.value
+
+      1 == length(byname) ->
+        hd(byname).value
+
+      true ->
+        refs = byname |> Enum.map(& &1.ref) |> Enum.sort()
+
+        Types.fail("plugin_export_ambiguous",
+                   "alias #{spec} matches #{length(refs)} instances: #{Enum.join(refs, ", ")}",
+                   %{"spec" => spec, "refs" => refs})
+    end
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/graph.ex

@@ -0,0 +1,185 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/graph.ex)
+# 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.
+defmodule Voxgig.Plugin.Graph do
+  @moduledoc """
+  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.
+
+  `resolve_graph` 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.
+  """
+
+  alias Voxgig.Plugin.Capability
+  alias Voxgig.Plugin.Ref
+  alias Voxgig.Plugin.Types
+  alias Voxgig.Plugin.Version
+
+  def resolve_graph(nodes) do
+    byref = Map.new(nodes, &{Types.get(&1, "ref"), &1})
+
+    resolved = fixedpoint(nodes, byref, MapSet.new())
+
+    blocked =
+      nodes
+      |> Enum.reject(&MapSet.member?(resolved, Types.get(&1, "ref")))
+      |> Enum.map(&{Types.get(&1, "ref"), firstunmet(&1, byref, resolved)})
+      |> Enum.reject(&is_nil(elem(&1, 1)))
+      |> Enum.sort_by(&elem(&1, 0))
+      |> Enum.map(&elem(&1, 1))
+
+    %{"resolved" => resolved |> MapSet.to_list() |> Enum.sort(), "blocked" => blocked}
+  end
+
+  # 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.
+  defp fixedpoint(nodes, byref, resolved) do
+    next =
+      Enum.reduce(nodes, resolved, fn node, acc ->
+        ref = Types.get(node, "ref")
+
+        if MapSet.member?(acc, ref) or not is_nil(firstunmet(node, byref, acc)) do
+          acc
+        else
+          MapSet.put(acc, ref)
+        end
+      end)
+
+    if MapSet.size(next) == MapSet.size(resolved),
+      do: resolved,
+      else: fixedpoint(nodes, byref, next)
+  end
+
+  @doc """
+  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.
+  """
+  def firstunmet(node, byref, resolved) do
+    (Types.get(node, "requires") || [])
+    |> Enum.reject(&Types.get(&1, "optional"))
+    |> Enum.find_value(&unmet(node, &1, byref, resolved))
+  end
+
+  defp unmet(node, req, byref, resolved) do
+    name = Types.get(req, "name")
+    all = graph_candidates(byref, name)
+    ok = Capability.resolve_capability(req, all)
+
+    cond do
+      all == [] ->
+        why(node, name, %{"kind" => "absent"})
+
+      ok == [] ->
+        # Providers exist and none matched. Say which test failed.
+        whynomatch(node, req, all) || why(node, name, %{"kind" => "absent"})
+
+      Enum.any?(ok, &MapSet.member?(resolved, Types.get(&1, "ref"))) ->
+        nil
+
+      true ->
+        # 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".
+        chain = ok |> Enum.map(&Types.get(&1, "ref")) |> Enum.sort()
+        why(node, name, %{"kind" => "blocked", "chain" => chain})
+    end
+  end
+
+  defp whynomatch(node, req, all) do
+    range = Types.get(req, "range")
+    match = Types.get(req, "match")
+    bad = if is_nil(range), do: [], else: badversions(all, range)
+
+    cond do
+      [] != bad ->
+        why(node, Types.get(req, "name"), %{
+          "kind" => "version",
+          "range" => range,
+          "found" => Enum.sort(bad)
+        })
+
+      not is_nil(match) ->
+        Enum.find_value(all, &badattr(node, req, match, &1))
+
+      true ->
+        nil
+    end
+  end
+
+  defp badversions(all, range) do
+    all
+    |> Enum.map(&(Types.get(&1, "provides") |> Types.get("version")))
+    |> Enum.filter(&(is_nil(&1) or not Version.satisfiesq(&1, range)))
+    |> Enum.map(&(&1 || "(none)"))
+  end
+
+  defp badattr(node, req, match, cand) do
+    attrs = Types.get(Types.get(cand, "provides"), "attrs") || %{}
+
+    match
+    |> Types.keys()
+    |> Enum.find_value(fn k ->
+      want = Types.get(match, k)
+
+      if Types.has(attrs, k) and Capability.matchvalue(want, Types.get(attrs, k)) do
+        nil
+      else
+        why(node, Types.get(req, "name"), %{
+          "kind" => "match",
+          "failing" => k,
+          "want" => want,
+          "found" => Types.get(attrs, k)
+        })
+      end
+    end)
+  end
+
+  defp why(node, name, reason),
+    do: %{"ref" => Types.get(node, "ref"), "unmet" => name, "why" => reason}
+
+  def graph_candidates(byref, name) do
+    # 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.
+    asref = Ref.canon(name)
+
+    byref
+    |> Types.keys()
+    |> Enum.flat_map(fn ref ->
+      node = Types.get(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 do
+        [%{"ref" => Types.get(node, "ref"), "pos" => Types.get(node, "pos") || 0,
+           "provides" => %{"name" => name}}]
+      else
+        Types.get(node, "provides")
+        |> Kernel.||([])
+        |> Enum.filter(&(Types.get(&1, "name") == name))
+        |> Enum.map(fn prov ->
+          %{"ref" => Types.get(node, "ref"), "pos" => Types.get(node, "pos") || 0,
+            "provides" => prov}
+        end)
+      end
+    end)
+  end
+end