@voxgig/sdkgen 4.9.0 → 4.11.0

package/project/.sdk/tm/scala/feature/secrets/plugin/Capability.scala

@@ -0,0 +1,96 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Capability.scala)
+// 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 voxgig.plugin
+
+/** 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.
+  */
+object Capability {
+
+  /** 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 resolveCapability(req: Value, candidates: Value): List[Value] =
+    Types.stableSortBy(candidates.items.filter(c => matches(req, c.at("provides"))))(rankKey)
+
+  /** 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.
+    */
+  def rankKey(cand: Value): List[SortKey] = {
+    val prov = cand.at("provides")
+    val version = prov.at("version")
+    val absent = version.isNull
+    List(
+      KNum(if (absent) 1 else 0),
+      KList(
+        if (absent) List(KNum(0), KNum(0), KNum(0))
+        else Version.versionParts(version).map(n => KNum(-n))
+      ),
+      KNum(prov.at("priority").asDouble.getOrElse(0.0)),
+      KNum(cand.at("pos").asDouble.getOrElse(0.0))
+    )
+  }
+
+  def matches(req: Value, prov: Value): Boolean = {
+    if (req.at("name") != prov.at("name")) return false
+
+    val range = req.at("range")
+    if (!range.isNull) {
+      val version = prov.at("version")
+      if (version.isNull) return false
+      if (!Version.satisfiesq(version, range)) return false
+    }
+
+    // `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.
+    val want = req.at("match")
+    if (!want.isNull) {
+      val attrs = prov.at("attrs")
+      return want.keys.forall(k => attrs.has(k) && matchValue(want.at(k), attrs.at(k)))
+    }
+    true
+  }
+
+  /** PARTIAL MATCH, RECURSING INTO MAPS (section 11.1).
+    *
+    * 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`. SCALA
+    * NEEDS NO GUARD FOR THAT - `Value` is a sealed hierarchy, and `VBool(true)`
+    * and `VNum(1)` are different case classes that cannot compare equal however
+    * hard a reading tries. Python, PHP, Perl and Lua all need one, and
+    * `capability/match` pins the behaviour for every port rather than trusting
+    * each language's equality.
+    *
+    * A LIST IS COMPARED LEAF-WISE AT THE SAME LENGTH, not as a subset.
+    */
+  def matchValue(want: Value, got: Value): Boolean = (want, got) match {
+    case (VMap(_), VMap(_)) =>
+      want.keys.forall(k => got.has(k) && matchValue(want.at(k), got.at(k)))
+    case (VMap(_), _) => false
+    case (VList(w), VList(g)) =>
+      w.length == g.length && w.zip(g).forall { case (x, y) => matchValue(x, y) }
+    case (VList(_), _) => false
+    case _             => want == got
+  }
+}

package/project/.sdk/tm/scala/feature/secrets/plugin/Config.scala

@@ -0,0 +1,270 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Config.scala)
+// 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 voxgig.plugin
+
+/** The declarative document (section 9): normalization, and the ten-level
+  * precedence ladder.
+  *
+  * TWO FUNCTIONS, AND THE SPLIT BETWEEN THEM IS FORCED.
+  *
+  * `normalizeConfig` 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.
+  *
+  * `resolveOptions` applies the ladder, and it is the only place that knows the
+  * shape.
+  */
+object Config {
+
+  private val mergeWords = List("replace", "append")
+
+  private final case class Entries(map: Map[String, Value], order: List[String])
+
+  /** 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.
+    */
+  private def entriesOf(src: Value): Entries = src match {
+    case VNull => Entries(Map.empty, Nil)
+
+    case VList(items) =>
+      val refs = items.map(item => Refs.canonRef(item.at("ref")))
+      Entries(refs.zip(items).toMap, refs)
+
+    case _ =>
+      // Map-form refs arrive as KEYS, through a different path than an array
+      // element's `ref` field - and must canonicalize the same way.
+      val m = src.keys.map(k => Refs.canonRef(VStr(k)) -> src.at(k)).toMap
+      // 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. Scala's
+      // `String` ordering is `compareTo`, which is exactly that.
+      Entries(m, m.keys.toList.sorted)
+  }
+
+  private def checkReserved(ref: String, reserved: Value): Unit = {
+    if (reserved.items.contains(VStr(Refs.refName(VStr(ref))))) {
+      Types.fail(
+        "plugin_ref_reserved", "ref is reserved by the host: " + ref,
+        Map("ref" -> VStr(ref))
+      )
+    }
+  }
+
+  /** PRESENCE decides, not truthiness and not null. A JSON `null` is a present
+    * value in JavaScript (`undefined !== null`), so it must be one here.
+    */
+  private def pick(src: Option[Value], key: String, dflt: Value): Value = src match {
+    case Some(s) if s.has(key) => s.at(key)
+    case _                     => dflt
+  }
+
+  def normalizeConfig(input: Value): Value = {
+    val doc = input.at("doc")
+    val keys = input.at("keys")
+    val ikey = keys.at("instance").asString.getOrElse("instance")
+    val dkey = keys.at("default").asString.getOrElse("default")
+    val reserved = input.at("reserved")
+    val profile = input.at("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.
+    val basedef = doc.at(dkey)
+    val overlay = profile.asString.map(doc.at("profile").at(_)).filter(_.isMap)
+      .getOrElse(VMap(Map.empty))
+    val overdef = overlay.at(dkey)
+
+    val base = entriesOf(doc.at(ikey))
+    val over = entriesOf(overlay.at(ikey))
+
+    List(base.map.keys.toList.sorted, over.map.keys.toList.sorted,
+      basedef.keys, overdef.keys)
+      .foreach(_.foreach(ref => checkReserved(ref, reserved)))
+
+    // 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. The remainder keeps the BASE's
+    // own order.
+    val order = (over.order ++ base.order).distinct
+
+    val instance = order.zipWithIndex.map { case (ref, i) =>
+      val b = base.map.get(ref)
+      val o = over.map.get(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.
+      val block = pick(o, "order", pick(b, "order", VNull))
+
+      // Option layers, levels 3-6, IN LADDER ORDER. Never merged here.
+      val nm = Refs.refName(VStr(ref))
+      val layers = List(basedef.get(nm), b, overdef.get(nm), o)
+        .flatten.filter(_.has("options")).map(_.at("options"))
+
+      val ent = Map[String, Value](
+        "pos" -> VNum(i.toDouble),
+        "active" -> pick(o, "active", pick(b, "active", VBool(true))),
+        "start" -> pick(o, "start", pick(b, "start", VStr("eager"))),
+        "optionlayers" -> VList(layers)
+      )
+      ref -> VMap(if (block.isNull) ent else ent + ("order" -> block))
+    }.toMap
+
+    // `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.
+    val defout = basedef.entries ++ overdef.entries
+
+    Value.map(
+      "instance" -> VMap(instance),
+      "order" -> VList(order.map(VStr.apply)),
+      "default" -> VMap(defout)
+    )
+  }
+
+  /** 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 checkShape(shape: Value): Unit = {
+    if (!shape.isMap) return
+    shape.keys.foreach { k =>
+      val v = shape.at(k)
+      if (v.has("$MERGE")) {
+        val directive = v.at("$MERGE")
+        directive match {
+          case VStr(word) if mergeWords.contains(word) => ()
+          case VStr(word) =>
+            Types.fail(
+              "plugin_shape_invalid", "invalid $MERGE directive at " + k + ": " + word,
+              Map("key" -> VStr(k), "directive" -> directive)
+            )
+          case d if d.has("deep") =>
+            val n = d.at("deep")
+            // `VBool(true)` is a different case class from `VNum`, so the
+            // boolean falls out for free here - unlike python, where it does
+            // not.
+            if (!n.asInt.exists(_ >= 1)) {
+              Types.fail(
+                "plugin_shape_invalid",
+                "invalid $MERGE deep at " + k + ": " + n.json,
+                Map("key" -> VStr(k), "directive" -> directive)
+              )
+            }
+          case _ =>
+            Types.fail(
+              "plugin_shape_invalid",
+              "invalid $MERGE directive at " + k + ": " + directive.json,
+              Map("key" -> VStr(k), "directive" -> directive)
+            )
+        }
+      }
+    }
+  }
+
+  /** The shape's non-directive values are the level-1 defaults. */
+  private def defaultsOf(shape: Value): Value =
+    VMap(shape.keys.filterNot(k => shape.at(k).has("$MERGE"))
+      .map(k => k -> shape.at(k)).toMap)
+
+  private def optsOf(src: Value, key: String): Option[Value] = src match {
+    case VNull => None
+    // The array form is equivalent to the map form (section 9.1).
+    case VList(items) =>
+      items.find(item => Refs.canonRef(item.at("ref")) == key).flatMap(_.get("options"))
+    case _ =>
+      src.keys.find(k => Refs.canonRef(VStr(k)) == key).flatMap { k =>
+        val entry = src.at(k)
+        if (entry.isMap) entry.get("options") else None
+      }
+  }
+
+  /** Merge N levels below this key, replace below that. */
+  private def deepTo(base: Value, over: Value, n: Int): Value = {
+    if (n <= 0 || !base.isMap || !over.isMap) return over
+    VMap(over.keys.foldLeft(base.entries) { (acc, k) =>
+      acc + (k -> deepTo(acc.getOrElse(k, VNull), over.at(k), n - 1))
+    })
+  }
+
+  /** 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.
+    */
+  private def mergeOne(base: Value, over: Value, shape: Value): Value = {
+    if (over.isNull) return base
+    if (!base.isMap || !over.isMap) return over
+
+    VMap(over.keys.foldLeft(base.entries) { (acc, k) =>
+      val ov = over.at(k)
+      val bv = acc.getOrElse(k, VNull)
+      val directive = shape.at(k).at("$MERGE")
+
+      val merged =
+        if (directive == VStr("replace")) {
+          ov
+        } else if (directive == VStr("append")) {
+          val bl = if (bv.isList) bv.items else Nil
+          val ol = if (ov.isList) ov.items else List(ov)
+          VList(bl ++ ol)
+        } else if (directive.has("deep")) {
+          deepTo(bv, ov, directive.at("deep").asInt.getOrElse(0))
+        } else if (bv.isMap && ov.isMap) {
+          // 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.
+          mergeOne(bv, ov, VNull)
+        } else {
+          ov
+        }
+      acc + (k -> merged)
+    })
+  }
+
+  def resolveOptions(input: Value): Value = {
+    val shape = input.at("shape")
+    checkShape(shape)
+
+    val ref = Refs.canonRef(input.at("ref"))
+    val name = Refs.refName(VStr(ref))
+    val doc = input.at("doc")
+    val overlay = input.at("profile").asString.map(doc.at("profile").at(_))
+      .filter(_.isMap).getOrElse(VMap(Map.empty))
+
+    // 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.
+    val layers = List(
+      Some(defaultsOf(shape)),                        // 1
+      input.get("hostdefaults"),                      // 2
+      optsOf(doc.at("default"), name),                // 3
+      optsOf(doc.at("instance"), ref),                // 4
+      optsOf(overlay.at("default"), name),            // 5
+      optsOf(overlay.at("instance"), ref),            // 6
+      input.get("env"),                               // 7
+      input.get("hostoptions"),                       // 8
+      input.get("loadoptions"),                       // 9
+      input.get("patch")                              // 10
+    )
+
+    layers.flatten.filterNot(_.isNull)
+      .foldLeft(VMap(Map.empty): Value)((acc, layer) => mergeOne(acc, layer, shape))
+  }
+}

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

@@ -0,0 +1,216 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Depend.scala)
+// 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 voxgig.plugin
+
+import scala.collection.mutable
+
+/** 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. */
+final case class GraphNode(ref: String, provides: List[String], requires: List[Value])
+
+object Depend {
+
+  /** A bare string is shorthand for `{name}`. */
+  def normRequire(raw: Value): Value = raw match {
+    case VStr(s) => Value.map("name" -> VStr(s))
+    case VMap(_) => raw
+    case _       => VMap(Map.empty)
+  }
+
+  /** 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 requirements(options: Value): List[Value] = {
+    val marked = options.at("optional")
+    val fallback = options.at("policy")
+
+    options.at("requires").items.map { item =>
+      val req = normRequire(item)
+      val listed = marked.isList && marked.items.contains(req.at("name"))
+      val withOptional =
+        if (req.at("optional").truthy || listed) req.setting("optional", VBool(true))
+        else req
+      if (!withOptional.has("policy") && !fallback.isNull) {
+        withOptional.setting("policy", fallback)
+      } else {
+        withOptional
+      }
+    }
+  }
+
+  /** 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: Value): Boolean = req.at("policy") match {
+    case VNull => true
+    case p     => p != VStr("dynamic")
+  }
+
+  /** 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: Value): Boolean = req.at("optional") != VBool(true)
+
+  /** 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 restartCausing(req: Value): 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.
+    */
+  def dependencyCycle(nodes: List[GraphNode]): Option[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 = mutable.Map[String, mutable.ListBuffer[String]]()
+    val isref = nodes.map(_.ref).toSet
+    nodes.foreach { n =>
+      n.provides.foreach { cap =>
+        bycap.getOrElseUpdate(cap, mutable.ListBuffer.empty) += n.ref
+      }
+    }
+
+    val edges = nodes.map { n =>
+      val out = n.requires
+        .filter(restartCausing)
+        .flatMap { req =>
+          val reqname = req.at("name").asString.getOrElse("")
+          val from = bycap.getOrElse(reqname, Nil).toList
+          // 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(VStr(reqname))
+          if (isref.contains(asref)) from :+ asref else from
+        }
+        .filter(_ != n.ref)
+        .distinct
+        .sorted
+      n.ref -> out
+    }.toMap
+
+    // 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 = mutable.Map[String, Int]()
+    nodes.foreach(n => colour(n.ref) = white)
+
+    // NO `return` OUT OF A LAMBDA. Scala 2 compiles one into a
+    // `NonLocalReturnControl` thrown through the closure; scala 3 deprecates
+    // that and points at `boundary`/`boundary.break`, which 2.11 has no port
+    // of. A `found` cell that both loop conditions read is the one shape both
+    // compilers take, and it leaves the walk at the same instant the `return`
+    // did -- the DFS state is never observed again once it is set.
+    var found: Option[List[String]] = None
+    val starts = edges.keys.toList.sorted.iterator
+
+    while (found.isEmpty && starts.hasNext) {
+      val start = starts.next()
+      if (colour(start) == white) {
+        val path = mutable.ListBuffer[String](start)
+        val stack = mutable.ArrayBuffer[(String, Int)]((start, 0))
+        colour(start) = grey
+
+        while (found.isEmpty && stack.nonEmpty) {
+          val (node, cursor) = stack(stack.length - 1)
+          val outs = edges(node)
+          if (cursor >= outs.length) {
+            colour(node) = black
+            stack.remove(stack.length - 1)
+            path.remove(path.length - 1)
+          } else {
+            val next = outs(cursor)
+            stack(stack.length - 1) = (node, cursor + 1)
+            if (colour(next) == grey) {
+              // Report the cycle itself, not the walk that found it.
+              found = Some(path.drop(path.indexOf(next)).toList :+ next)
+            } else if (colour(next) != black) {
+              colour(next) = grey
+              path += next
+              stack += ((next, 0))
+            }
+          }
+        }
+      }
+    }
+    found
+  }
+
+  /** Raise on a cycle, naming it. Separate from the detector so the detector
+    * stays pure and corpus-testable.
+    */
+  def checkCycle(nodes: List[GraphNode]): Unit = dependencyCycle(nodes) match {
+    case None => ()
+    case Some(cycle) =>
+      Types.fail(
+        "plugin_dependency_cycle", "requirements cycle: " + cycle.mkString(" -> "),
+        Map("cycle" -> VList(cycle.map(VStr.apply)))
+      )
+  }
+}