@voxgig/sdkgen 4.8.3 → 4.10.0

package/project/.sdk/tm/rb/feature/secrets/voxgig_plugin/capability.rb

@@ -0,0 +1,118 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ruby/lib/voxgig_plugin/capability.rb)
+# 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.
+# frozen_string_literal: true
+
+# Capabilities (section 11.1).
+#
+# A DEPENDENCY IS ON A CAPABILITY, NOT ON A REF - because it is a
+# dependency on something that can do the job, and which instance is
+# doing it is exactly the configuration detail a plugin must not care
+# about.
+#
+# But A BINDING IS TO AN INSTANCE, not to a capability, which is what
+# decides behaviour when the bound provider leaves while another match
+# remains.
+
+require_relative 'types'
+require_relative 'version'
+
+module VoxgigPlugin
+  # Rank the matching live providers and return them best-first: highest
+  # `version`, then LOWEST `priority` (default 0), then declaration
+  # position `pos` ascending.
+  #
+  # `priority` is a field on the capability rather than section 7's
+  # `order` band, because bands live on POINT BINDINGS: a provider may
+  # have several bindings with different bands, or none at all, so a rank
+  # reaching for one would be undefined in the common case.
+  #
+  # Without a total rank, "any provider satisfies" is true of the GRAPH
+  # and useless to the PLUGIN - two ports could bind different `store`
+  # instances, both resolve green, and behave differently, which is
+  # precisely the divergence a shared corpus exists to catch.
+  def self.resolve_capability(req, candidates)
+    hits = candidates.select { |c| matches(req, c['provides'] || {}) }
+    # STABLE: Ruby's sort is not, and the rank falls through to `pos`.
+    Util.stable_sort_by(hits) { |c| rank_key(c) }
+  end
+
+  def self.rank_key(cand)
+    prov = cand['provides'] || {}
+    version = prov['version']
+    # An ABSENT version sorts LAST, whatever the other is - "no version"
+    # loses to every version rather than being read as 0.0.0. The leading
+    # flag is what expresses that in a sort KEY rather than a comparator.
+    [version.nil? ? 1 : 0,
+     version.nil? ? [0, 0, 0] : version_parts(version).map { |n| -n },
+     prov['priority'] || 0,
+     cand['pos'] || 0]
+  end
+
+  def self.matches(req, prov)
+    return false if req['name'] != prov['name']
+
+    unless req['range'].nil?
+      return false if prov['version'].nil?
+      return false unless satisfiesq(prov['version'], req['range'])
+    end
+
+    # `match` is checked against the provider's `attrs`, key by key. A
+    # key the provider does not carry is a miss, not a pass: a
+    # requirement asking for `transactional: true` must not be satisfied
+    # by a provider that never said.
+    unless req['match'].nil?
+      attrs = prov['attrs'] || {}
+      req['match'].each do |k, want|
+        return false unless attrs.key?(k)
+        return false unless matchvalue(want, attrs[k])
+      end
+    end
+
+    true
+  end
+
+  # PARTIAL MATCH, RECURSING INTO MAPS (section 11.1).
+  #
+  # Section 11.1 defines `match` as "a partial match against `attrs`,
+  # with exactly the semantics voxgig/struct and the omni corpus already
+  # define for `match` - every leaf in the requirement must be present
+  # and equal in the capability, keys not mentioned are not checked."
+  #
+  # Equality is by JSON TYPE as well as value: `transactional: 1` does
+  # not satisfy `transactional: true`. RUBY NEEDS NO GUARD FOR THAT -
+  # `true == 1` is already false, because TrueClass and Integer are
+  # different classes with no coercion between them. Python, PHP, Perl
+  # and Lua all need one, and `capability/match` pins the behaviour for
+  # every port rather than trusting each language's `==`.
+  #
+  # An explicit `boolean?(want) != boolean?(got)` check was written here
+  # first and then removed: it could never fire, and a guard that cannot
+  # fire is dead code that reads as protection. A mutation deleting it
+  # survived the corpus, which is what a non-mutation looks like.
+  #
+  # A LIST IS COMPARED LEAF-WISE AT THE SAME LENGTH, not as a subset.
+  def self.matchvalue(want, got)
+    if want.is_a?(Hash)
+      return false unless got.is_a?(Hash)
+
+      want.each do |k, v|
+        return false unless got.key?(k)
+        return false unless matchvalue(v, got[k])
+      end
+      return true
+    end
+
+    if want.is_a?(Array)
+      return false unless got.is_a?(Array) && want.length == got.length
+
+      return want.each_with_index.all? { |v, i| matchvalue(v, got[i]) }
+    end
+
+    want == got
+  end
+
+  def self.version_parts(text)
+    text.split('.').map(&:to_i)
+  end
+end

package/project/.sdk/tm/rb/feature/secrets/voxgig_plugin/catalog.rb

@@ -0,0 +1,55 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ruby/lib/voxgig_plugin/catalog.rb)
+# 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.
+# frozen_string_literal: true
+
+# The definition catalog (section 10.1).
+#
+# A definition is registered once and may back many instances. Option
+# shapes are validated AT REGISTRATION, not when a document happens to
+# exercise a key - so a malformed shape fails once, and in the same place
+# everywhere (section 9.4).
+
+require_relative 'types'
+require_relative 'ref'
+require_relative 'config'
+
+module VoxgigPlugin
+  class Catalog
+    def initialize
+      @defs = {}
+    end
+
+    def add(definition)
+      unless definition.is_a?(Hash) && VoxgigPlugin.check_name(definition['name'])
+        name = definition.is_a?(Hash) ? definition['name'] : definition
+        VoxgigPlugin.fail_with('plugin_definition_name',
+                               "invalid definition name: #{name}")
+      end
+      # Validate the shape HERE. Deferring it to resolution time means a
+      # malformed shape surfaces at a different moment in every host that
+      # loads it, which is the divergence the stated domain exists to
+      # prevent.
+      VoxgigPlugin.check_shape(definition['shape']) if definition['shape']
+      @defs[definition['name']] = definition
+    end
+
+    def get(name)
+      @defs[name]
+    end
+
+    def has?(name)
+      @defs.key?(name)
+    end
+
+    def names
+      @defs.keys.sort
+    end
+  end
+
+  def self.make_catalog(definitions = nil)
+    catalog = Catalog.new
+    (definitions || []).each { |d| catalog.add(d) }
+    catalog
+  end
+end

package/project/.sdk/tm/rb/feature/secrets/voxgig_plugin/config.rb

@@ -0,0 +1,315 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ruby/lib/voxgig_plugin/config.rb)
+# 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.
+# frozen_string_literal: true
+
+# The declarative document (section 9): normalization, and the ten-level
+# precedence ladder.
+#
+# TWO FUNCTIONS, AND THE SPLIT BETWEEN THEM IS FORCED.
+#
+# `normalize_config` normalizes STRUCTURE and ENTRY KEYS. It does not
+# merge options, and cannot: section 9.4 makes merge behaviour a property
+# of the definition's option SHAPE, which normalization has never seen. A
+# normalizer that flattened the option layers would make `$MERGE: append`
+# unimplementable at load time, because the layers it must concatenate
+# would already be collapsed.
+#
+# `resolve_options` applies the ladder, and it is the only place that
+# knows the shape.
+
+require_relative 'types'
+require_relative 'ref'
+
+module VoxgigPlugin
+  MERGE_WORDS = %w[replace append].freeze
+
+  def self.normalize_config(input)
+    input ||= {}
+    doc = input['doc'] || {}
+    keys = input['keys'] || {}
+    ikey = keys['instance'] || 'instance'
+    dkey = keys['default'] || 'default'
+    reserved = input['reserved'] || []
+    profile = input['profile']
+
+    # The rename is applied at TWO PLACES AND NO OTHERS: the document
+    # root, and every profile.<name> overlay root (section 9.1). A rename
+    # applied only at the root would leave `profile.prod.sdk`
+    # untranslated and silently drop every environment override the host
+    # depends on. Recursing further would be worse: option data is the
+    # definition's.
+    baseinst = doc[ikey]
+    basedef = doc[dkey] || {}
+
+    overlay = nil
+    overlay = (doc['profile'] || {})[profile] if profile
+    overlay = {} unless overlay.is_a?(Hash)
+    overinst = overlay[ikey]
+    overdef = overlay[dkey] || {}
+
+    # Entry layers, base then overlay, each as {ref -> entry} plus the
+    # order the form implies.
+    base = config_entries(baseinst)
+    over = config_entries(overinst)
+
+    [base[:map].keys, over[:map].keys, basedef.keys, overdef.keys].each do |group|
+      group.each { |r| config_checkreserved(r, reserved) }
+    end
+
+    # A PARTIAL ARRAY IS NOT A FILTER (section 9.1). sdkgen learned this
+    # the hard way: deriving order from a partial array silently dropped
+    # config-activated features. Refs in the base but absent from the
+    # overlay still load, in sorted position AFTER the listed ones. A
+    # profile may also INTRODUCE a ref the base never declared.
+    order = []
+    over[:order].each { |r| order << r unless order.include?(r) }
+    # The remainder keeps the BASE's own order - array position for the
+    # array form, sorted refs for the map form.
+    base[:order].each { |r| order << r unless order.include?(r) }
+
+    instance = {}
+    order.each_with_index do |ref, i|
+      b = base[:map][ref]
+      o = over[:map][ref]
+
+      # MERGE THE ENTRIES AS AUTHORED, THEN APPLY DEFAULTS TO THE RESULT
+      # (section 9.3). A safety rule, not a tidiness one: if the overlay
+      # had its defaults filled in before merging it would carry a
+      # synthesized active:true and overwrite a base's false - silently
+      # re-enabling a deliberately disabled integration in production.
+      active = config_pick(o, 'active', config_pick(b, 'active', true))
+      start = config_pick(o, 'start', config_pick(b, 'start', 'eager'))
+      block = config_pick(o, 'order', config_pick(b, 'order', nil))
+
+      # Option layers, levels 3-6, IN LADDER ORDER. Never merged here.
+      layers = []
+      nm = refname(ref)
+      [basedef[nm], b, overdef[nm], o].each do |src|
+        layers << src['options'] if src.is_a?(Hash) && src.key?('options')
+      end
+
+      ent = { 'pos' => i, 'active' => active, 'start' => start,
+              'optionlayers' => layers }
+      ent['order'] = block unless block.nil?
+      instance[ref] = ent
+    end
+
+    # `default` DECLARES NOTHING (section 9.3). It is a base for every
+    # instance of that definition; it does not create one, and an entry
+    # for a name with no instances is inert rather than an error - which
+    # is what makes a shared library of defaults shippable.
+    defout = {}
+    basedef.each { |n, v| defout[n] = v }
+    overdef.each { |n, v| defout[n] = v }
+
+    { 'instance' => instance, 'order' => order, 'default' => defout }
+  end
+
+  # Both document forms reduce to {ref -> entry} plus the order the form
+  # implies: array POSITION for the array form, sorted refs for the map
+  # form.
+  def self.config_entries(src)
+    out = { map: {}, order: [] }
+    return out if src.nil?
+
+    if src.is_a?(Array)
+      src.each do |item|
+        ref = canon_ref(item['ref'])
+        out[:map][ref] = item
+        out[:order] << ref
+      end
+      return out
+    end
+
+    # Map-form refs arrive as KEYS, through a different path than an
+    # array element's `ref` field - and must canonicalize the same way.
+    src.each_key { |key| out[:map][canon_ref(key)] = src[key] }
+    # Byte-wise, NOT locale-aware and NOT case-folded. All-lowercase refs
+    # sort identically under all three, so only mixed input
+    # discriminates: '@' is 0x40, uppercase 0x41-0x5A, lowercase
+    # 0x61-0x7A. Ruby's String#<=> is bytewise, which is exactly that.
+    out[:order] = out[:map].keys.sort
+    out
+  end
+
+  # Section 9.1: reservation is all-or-nothing per NAME, so the tagged
+  # forms go too. A configuration surface that can disable the thing
+  # reading it is not a surface, it is a trap.
+  def self.config_checkreserved(ref, reserved)
+    return if reserved.empty?
+    return unless reserved.include?(refname(ref))
+
+    fail_with('plugin_ref_reserved', "ref is reserved by the host: #{ref}",
+              { 'ref' => ref })
+  end
+
+  # PRESENCE decides, not truthiness and not nil. A JSON `null` is a
+  # present value in JavaScript (`undefined !== null`), so it must be one
+  # here.
+  def self.config_pick(src, key, dflt)
+    src.is_a?(Hash) && src.key?(key) ? src[key] : dflt
+  end
+
+  # -------------------------------------------------------------------
+  # resolve_options - section 9.3's ten levels, and 9.4's directives
+  # -------------------------------------------------------------------
+
+  def self.resolve_options(input)
+    shape = input['shape'] || {}
+    check_shape(shape)
+
+    ref = canon_ref(input['ref'])
+    name = refname(ref)
+    doc = input['doc'] || {}
+    profile = input['profile']
+
+    overlay = nil
+    overlay = (doc['profile'] || {})[profile] if profile
+    overlay = {} unless overlay.is_a?(Hash)
+
+    # ONE ordered merge, lowest to highest. Levels 3-6 are not two
+    # namespaces collapsed separately and composed afterwards: that
+    # inverts the rule that PROFILE SPECIFICITY OUTRANKS DEFINITION
+    # SPECIFICITY, so a prod per-definition default would lose to a base
+    # instance value.
+    layers = [
+      config_defaultsof(shape),                     # 1
+      input['hostdefaults'],                        # 2
+      config_optsof(doc['default'], name),          # 3
+      config_optsof(doc['instance'], ref),          # 4
+      config_optsof(overlay['default'], name),      # 5
+      config_optsof(overlay['instance'], ref),      # 6
+      input['env'],                                 # 7
+      input['hostoptions'],                         # 8
+      input['loadoptions'],                         # 9
+      input['patch']                                # 10
+    ]
+
+    out = {}
+    layers.each do |layer|
+      next if layer.nil?
+
+      out = config_mergeone(out, layer, shape)
+    end
+    out
+  end
+
+  # The shape's non-directive values are the level-1 defaults.
+  def self.config_defaultsof(shape)
+    out = {}
+    shape.each do |k, v|
+      next if v.is_a?(Hash) && v.key?('$MERGE')
+
+      out[k] = v
+    end
+    out
+  end
+
+  def self.config_optsof(src, key)
+    return nil if src.nil?
+
+    # The array form is equivalent to the map form (section 9.1).
+    if src.is_a?(Array)
+      src.each do |item|
+        return item['options'] if canon_ref(item['ref']) == key
+      end
+      return nil
+    end
+
+    src.each_key do |k|
+      next unless canon_ref(k) == key
+
+      entry = src[k]
+      return entry.is_a?(Hash) ? entry['options'] : nil
+    end
+    nil
+  end
+
+  # Merge ONE layer onto the accumulator, honouring the shape's
+  # directives. The directive holds at EVERY precedence level, not only
+  # between document levels - section 9.4 makes it a property of the
+  # shape, which does not know which layer a value arrived from.
+  def self.config_mergeone(base, over, shape)
+    return base if over.nil?
+    return Util.clone_value(over) unless base.is_a?(Hash) && over.is_a?(Hash)
+
+    out = base.dup
+
+    over.each do |k, o|
+      directive = nil
+      directive = shape[k]['$MERGE'] if shape.is_a?(Hash) && shape[k].is_a?(Hash)
+      b = out[k]
+
+      if directive == 'replace'
+        out[k] = Util.clone_value(o)
+      elsif directive == 'append'
+        bl = b.is_a?(Array) ? b : []
+        ol = o.is_a?(Array) ? o : [o]
+        out[k] = bl + ol
+      elsif directive.is_a?(Hash) && directive.key?('deep')
+        out[k] = config_deepto(b, o, directive['deep'])
+      else
+        # Library default: deep for maps, REPLACE for lists. struct.merge
+        # is element-wise by index, which for option maps is nearly
+        # always wrong - ["a"] over ["x","y","z"] yielding ["a","y","z"]
+        # is the defect station hit on secrets.providers.
+        out[k] = if b.is_a?(Hash) && o.is_a?(Hash)
+                   config_mergeone(b, o, nil)
+                 else
+                   Util.clone_value(o)
+                 end
+      end
+    end
+    out
+  end
+
+  # Merge N levels below this key, replace below that.
+  def self.config_deepto(base, over, n)
+    return Util.clone_value(over) if n <= 0
+    return Util.clone_value(over) unless base.is_a?(Hash) && over.is_a?(Hash)
+
+    out = base.dup
+    over.each { |k, v| out[k] = config_deepto(out[k], v, n - 1) }
+    out
+  end
+
+  # Section 9.4: N is an integer of at least 1, and everything else is an
+  # error.
+  #
+  # `{"deep": 0}` is rejected DESPITE having an obvious reading, because
+  # "replace at this key" already has a spelling and two spellings for
+  # one behaviour is the defect class this repo exists to avoid.
+  def self.check_shape(shape)
+    return unless shape.is_a?(Hash)
+
+    shape.each do |k, v|
+      next unless v.is_a?(Hash) && v.key?('$MERGE')
+
+      directive = v['$MERGE']
+
+      if directive.is_a?(String)
+        next if MERGE_WORDS.include?(directive)
+
+        fail_with('plugin_shape_invalid',
+                  "invalid $MERGE directive at #{k}: #{directive}",
+                  { 'key' => k, 'directive' => directive })
+      end
+
+      if directive.is_a?(Hash) && directive.key?('deep')
+        n = directive['deep']
+        # `true.is_a?(Integer)` is false in ruby, so the boolean case
+        # falls out for free here - unlike python, where it does not.
+        next if n.is_a?(Integer) && n >= 1
+
+        fail_with('plugin_shape_invalid',
+                  "invalid $MERGE deep at #{k}: #{JSON.generate(n)}",
+                  { 'key' => k, 'directive' => directive })
+      end
+
+      fail_with('plugin_shape_invalid',
+                "invalid $MERGE directive at #{k}: #{JSON.generate(directive)}",
+                { 'key' => k, 'directive' => directive })
+    end
+  end
+end

package/project/.sdk/tm/rb/feature/secrets/voxgig_plugin/depend.rb

@@ -0,0 +1,197 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ruby/lib/voxgig_plugin/depend.rb)
+# 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.
+# frozen_string_literal: true
+
+# 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.
+
+require_relative 'types'
+
+module VoxgigPlugin
+  # A bare string is shorthand for `{name}`.
+  def self.normrequire(raw)
+    return { 'name' => raw } if raw.is_a?(String)
+
+    (raw || {}).dup
+  end
+
+  # 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".
+  def self.requirements(options)
+    options ||= {}
+    raw = options['requires'] || []
+    marked = options['optional'] || []
+    fallback = options['policy']
+
+    raw.map do |item|
+      req = normrequire(item)
+      req['optional'] = true if req['optional'] || marked.include?(req['name'])
+      req['policy'] = fallback if req['policy'].nil? && !fallback.nil?
+      req
+    end
+  end
+
+  # 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 self.restartsonloss(req)
+    (req['policy'] || 'static') != 'dynamic'
+  end
+
+  # 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 self.gatesactivation(req)
+    req['optional'] != true
+  end
+
+  # 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.
+  def self.restartcausing(req)
+    gatesactivation(req) || restartsonloss(req)
+  end
+
+  # 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.
+  def self.dependencycycle(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.
+    bycap = {}
+    isref = {}
+    nodes.each do |n|
+      isref[n['ref']] = true
+      n['provides'].each do |cap|
+        (bycap[cap] ||= []) << n['ref']
+      end
+    end
+
+    edges = {}
+    nodes.each do |n|
+      out = []
+      n['requires'].each do |req|
+        next unless restartcausing(req)
+
+        from = (bycap[req['name']] || []).dup
+        # 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 here.
+        asref = VoxgigPlugin.canon(req['name'])
+        from << asref if isref[asref] && !from.include?(asref)
+        from.each do |p|
+          out << p if p != n['ref'] && !out.include?(p)
+        end
+      end
+      edges[n['ref']] = out.sort
+    end
+
+    # Iterative DFS with an explicit stack: twenty ports, and several of
+    # them have no recursion budget worth relying on.
+    white = 0
+    grey = 1
+    black = 2
+    colour = {}
+    nodes.each { |n| colour[n['ref']] = white }
+
+    edges.keys.sort.each do |start|
+      next unless colour[start] == white
+
+      path = [start]
+      stack = [[start, 0]]
+      colour[start] = grey
+
+      until stack.empty?
+        top = stack[-1]
+        if top[1] >= edges[top[0]].length
+          colour[top[0]] = black
+          stack.pop
+          path.pop
+          next
+        end
+        nxt = edges[top[0]][top[1]]
+        top[1] += 1
+        if colour[nxt] == grey
+          # Report the cycle itself, not the walk that found it.
+          return path[path.index(nxt)..] + [nxt]
+        end
+        next if colour[nxt] == black
+
+        colour[nxt] = grey
+        path << nxt
+        stack << [nxt, 0]
+      end
+    end
+    nil
+  end
+
+  # Raise on a cycle, naming it. Separate from the detector so the
+  # detector stays pure and corpus-testable.
+  def self.checkcycle(nodes)
+    cycle = dependencycycle(nodes)
+    return if cycle.nil?
+
+    fail_with('plugin_dependency_cycle',
+              "requirements cycle: #{cycle.join(' -> ')}", { 'cycle' => cycle })
+  end
+end