@voxgig/sdkgen 4.8.3 → 4.10.0

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

@@ -0,0 +1,156 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Json.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 JSON parser.
+  *
+  * A hundred and fifty lines, and a hundred and fifty lines is cheaper than a
+  * `libraryDependencies` line every embedding host inherits - and it keeps this
+  * port buildable by `scalac` alone, with no sbt and no resolver.
+  */
+object Json {
+
+  def parse(text: String): Value = {
+    val parser = new Parser(text)
+    parser.skipws()
+    val value = parser.value()
+    parser.skipws()
+    if (parser.at < parser.chars.length) {
+      Types.fail("plugin_json", "trailing input at " + parser.at)
+    }
+    value
+  }
+
+  private class Parser(text: String) {
+    val chars: Array[Char] = text.toCharArray
+    var at: Int = 0
+
+    def skipws(): Unit =
+      while (at < chars.length &&
+        (chars(at) == ' ' || chars(at) == '\t' ||
+          chars(at) == '\n' || chars(at) == '\r')) {
+        at += 1
+      }
+
+    def value(): Value = {
+      if (at >= chars.length) Types.fail("plugin_json", "unexpected end of input")
+      chars(at) match {
+        case '{'  => map()
+        case '['  => list()
+        case '"'  => VStr(string())
+        case 't'  => literal("true", VBool(true))
+        case 'f'  => literal("false", VBool(false))
+        case 'n'  => literal("null", VNull)
+        case _    => number()
+      }
+    }
+
+    def literal(word: String, out: Value): Value = {
+      if (at + word.length > chars.length ||
+        new String(chars, at, word.length) != word) {
+        Types.fail("plugin_json", "unexpected input at " + at)
+      }
+      at += word.length
+      out
+    }
+
+    def map(): Value = {
+      var out = Map.empty[String, Value]
+      at += 1
+      skipws()
+      if (chars(at) == '}') {
+        at += 1
+        return VMap(out)
+      }
+      var done = false
+      while (!done) {
+        skipws()
+        val key = string()
+        skipws()
+        if (chars(at) != ':') Types.fail("plugin_json", "expected : at " + at)
+        at += 1
+        skipws()
+        out = out + (key -> value())
+        skipws()
+        if (chars(at) == ',') {
+          at += 1
+        } else if (chars(at) == '}') {
+          at += 1
+          done = true
+        } else {
+          Types.fail("plugin_json", "expected } at " + at)
+        }
+      }
+      VMap(out)
+    }
+
+    def list(): Value = {
+      val out = List.newBuilder[Value]
+      at += 1
+      skipws()
+      if (chars(at) == ']') {
+        at += 1
+        return VList(Nil)
+      }
+      var done = false
+      while (!done) {
+        skipws()
+        out += value()
+        skipws()
+        if (chars(at) == ',') {
+          at += 1
+        } else if (chars(at) == ']') {
+          at += 1
+          done = true
+        } else {
+          Types.fail("plugin_json", "expected ] at " + at)
+        }
+      }
+      VList(out.result())
+    }
+
+    def string(): String = {
+      if (chars(at) != '"') Types.fail("plugin_json", "expected string at " + at)
+      at += 1
+      val out = new StringBuilder
+      var done = false
+      while (!done) {
+        if (at >= chars.length) Types.fail("plugin_json", "unterminated string")
+        val c = chars(at)
+        if (c == '"') {
+          at += 1
+          done = true
+        } else if (c == '\\') {
+          at += 1
+          chars(at) match {
+            case 'n' => out.append('\n')
+            case 't' => out.append('\t')
+            case 'r' => out.append('\r')
+            case 'b' => out.append('\b')
+            case 'f' => out.append('\f')
+            case 'u' =>
+              out.append(Integer.parseInt(new String(chars, at + 1, 4), 16).toChar)
+              at += 4
+            case e => out.append(e)
+          }
+          at += 1
+        } else {
+          out.append(c)
+          at += 1
+        }
+      }
+      out.toString
+    }
+
+    def number(): Value = {
+      val start = at
+      while (at < chars.length && isNumeric(chars(at))) at += 1
+      if (start == at) Types.fail("plugin_json", "unexpected input at " + at)
+      VNum(new String(chars, start, at - start).toDouble)
+    }
+
+    def isNumeric(c: Char): Boolean =
+      c.isDigit || c == '-' || c == '+' || c == '.' || c == 'e' || c == 'E'
+  }
+}

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

@@ -0,0 +1,169 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Order.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
+
+/** Ordering (section 7) - one rule, one place.
+  *
+  * sdkgen grew two special cases in `makeOptions` (`test`, then `station`) and
+  * the third was not far off. This sort is the whole replacement, and the tiers
+  * are in this order for a reason:
+  *
+  *   1 constraints   before/after edges, by ref or by name
+  *   2 bands         integer, lower first, default 0
+  *   3 declaration   ties break by `pos`
+  *
+  * CONSTRAINTS BEAT BANDS precisely so the correct tool wins when both are
+  * present. A band expresses a genuine cross-cutting layer; a constraint
+  * expresses a relationship between two specific things; and a band chosen by
+  * trial and error to fix an ordering bug is a bug wearing a number.
+  */
+
+/** One node of the sort. An internal shape, never a corpus value. */
+final case class OrderNode(ref: String, pos: Int, order: Value)
+
+object Order {
+
+  def orderBand(b: OrderNode): Int = b.order.at("band").asInt.getOrElse(0)
+
+  /** Was a constraint stated? An absent value and an EMPTY LIST are both
+    * no-constraint - and an empty list is TRUTHY in most languages, which is
+    * exactly how this class of bug survives a reading.
+    */
+  def orderDeclared(spec: Value): Boolean = spec match {
+    case VNull    => false
+    case VList(l) => l.exists(_ != VStr(""))
+    case other    => other != VStr("")
+  }
+
+  /** One spelling or a LIST of them. A list fans out to the UNION of what each
+    * names, so after: ['a','b'] means after BOTH, and the same instance named
+    * twice - once by name, once by ref - is one edge.
+    *
+    * Matching is by REF, or by NAME across all of that definition's instances
+    * (section 7) - which is the whole reason the two spellings exist.
+    */
+  def orderTargets(spec: Value, nodes: List[OrderNode]): List[String] = {
+    val specs = spec match {
+      case VList(l) => l
+      case other    => List(other)
+    }
+    specs.flatMap { one =>
+      nodes
+        .filter(b => VStr(b.ref) == one || VStr(Refs.refName(VStr(b.ref))) == one)
+        .map(_.ref)
+    }.distinct
+  }
+
+  def resolveOrder(bindings: List[OrderNode], pin: Value = VNull): List[String] = {
+    val byref = bindings.map(b => b.ref -> b).toMap
+
+    // Constraints are edges. A constraint naming an ABSENT binding is satisfied
+    // VACUOUSLY (section 7) - a plugin ordered `after: 'test'` must load in a
+    // host with no test plugin. That is sdkgen's __after__ behaviour, kept.
+    val edges = mutable.LinkedHashMap[String, mutable.ListBuffer[String]]()
+    bindings.foreach(b => edges(b.ref) = mutable.ListBuffer.empty)
+
+    bindings.foreach { b =>
+      val block = b.order
+      if (orderDeclared(block.at("after"))) {
+        orderTargets(block.at("after"), bindings).foreach(t => edges(t) += b.ref)
+      }
+      if (orderDeclared(block.at("before"))) {
+        edges(b.ref) ++= orderTargets(block.at("before"), bindings)
+      }
+    }
+
+    val indeg = mutable.Map[String, Int]()
+    bindings.foreach(b => indeg(b.ref) = 0)
+    edges.values.foreach(_.foreach(to => indeg(to) = indeg(to) + 1))
+
+    // Stable topological sort. Among ready nodes, band first (lower runs
+    // first), then `pos` - the position the DOCUMENT visibly states, not the
+    // order instances happened to load and not the incarnation `seq`.
+    val out = mutable.ListBuffer[String]()
+    var ready = bindings.filter(b => indeg(b.ref) == 0)
+
+    while (ready.nonEmpty) {
+      val sorted = Types.stableSortBy(ready)(b => List(KNum(orderBand(b)), KNum(b.pos)))
+      val next = sorted.head
+      var rest = sorted.tail
+      out += next.ref
+      edges(next.ref).foreach { to =>
+        indeg(to) = indeg(to) - 1
+        if (indeg(to) == 0) rest = rest :+ byref(to)
+      }
+      ready = rest
+    }
+
+    if (out.length != bindings.length) {
+      val stuck = bindings.filterNot(b => out.contains(b.ref)).map(_.ref)
+      Types.fail(
+        "plugin_order_cycle",
+        "before/after constraints cycle: " + stuck.mkString(" -> "),
+        Map("cycle" -> VList(stuck.map(VStr.apply)))
+      )
+    }
+
+    applyPin(out.toList, edges.map { case (k, v) => k -> v.toList }.toMap, pin)
+  }
+
+  /** A PIN IS NOT A CONSTRAINT (section 7).
+    *
+    * Constraints and bands are negotiable by definition - they are what plugins
+    * and documents say they want, and the sort's job is to satisfy them all. A
+    * pin is the host stating a structural invariant of its own architecture,
+    * which is a different kind of claim and must not lose a tie to a document.
+    *
+    * So a pin PLACES the binding at the named end, and an ordering that would
+    * move it away is `plugin_order_pinned` - rejected, not honoured into a
+    * broken wrap.
+    */
+  def applyPin(order: List[String], edges: Map[String, List[String]], pin: Value)
+      : List[String] = {
+    if (pin.isNull) return order
+
+    // SORTED, not insertion order. A pin map is data - it can arrive from a
+    // host's own construction options in any order, and two names pinned to the
+    // same end are order-sensitive (`{b:'first', a:'first'}` and
+    // `{a:'first', b:'first'}` give different results). A scala `Map` past four
+    // entries has no order at all, so leaving it unstated made the same
+    // declaration mean different things in different ports.
+    val out = pin.keys.foldLeft(order) { (acc, name) =>
+      val want = pin.at(name).asString
+      acc.indexWhere(ref => Refs.refName(VStr(ref)) == name) match {
+        case -1 => acc
+        case idx =>
+          // `first`/`outermost` is index 0; `last`/`innermost` is the end.
+          // Section 6.2 makes the first chain binding outermost, which is why
+          // the vocabulary is positional and why the two spellings pair this
+          // way.
+          val ref = acc(idx)
+          val rest = acc.patch(idx, Nil, 1)
+          if (want.contains("first") || want.contains("outermost")) ref :: rest
+          else rest :+ ref
+      }
+    }
+
+    // Now check that the placement did not break a constraint. This is the half
+    // that makes a pin a rejection rather than an override: the host wins on
+    // position, but it does not get to silently discard a relationship a plugin
+    // declared.
+    val at = out.zipWithIndex.toMap
+    edges.keys.toList.sorted.foreach { from =>
+      edges(from).foreach { to =>
+        if (at(from) > at(to)) {
+          Types.fail(
+            "plugin_order_pinned",
+            "a pin would move a binding an ordering constrains: " +
+              from + " must precede " + to,
+            Map("before" -> VStr(from), "after" -> VStr(to))
+          )
+        }
+      }
+    }
+    out
+  }
+}

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

@@ -0,0 +1,47 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Plugin.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 canonical surface `make parity` checks (AGENTS.md section 4). Small on
+  * purpose (section 19): everything else is methods on the host and instance
+  * types, because a library that grows a second public entry point per feature
+  * is a library twenty ports pay for twice.
+  *
+  * ELEVEN NAMES, AND THEY FORWARD. The implementation lives in the object named
+  * for its design section, so a reader who arrives at `resolveOrder` from the
+  * corpus lands in `Order` where section 7 is quoted.
+  */
+object Plugin {
+
+  // host construction
+  def makeHost(options: HostOptions = HostOptions()): Host = new Host(options)
+
+  def makeCatalog(definitions: List[Definition] = Nil): Catalog = {
+    val catalog = new Catalog
+    definitions.foreach(catalog.add)
+    catalog
+  }
+
+  // refs - the first thing a new port implements (section 4)
+  def parseRef(str: Value): Value = Refs.parseRef(str)
+
+  def formatRef(name: Value, tag: Value = VNull): String = Refs.formatRef(name, tag)
+
+  def checkName(name: Value): Boolean = Refs.checkName(name)
+
+  def checkTag(tag: Value): Boolean = Refs.checkTag(tag)
+
+  // pure functions over documents and definitions
+  def normalizeConfig(input: Value): Value = Config.normalizeConfig(input)
+
+  def resolveOptions(input: Value): Value = Config.resolveOptions(input)
+
+  def resolveOrder(bindings: List[OrderNode], pin: Value = VNull): List[String] =
+    Order.resolveOrder(bindings, pin)
+
+  def resolveCandidates(name: String, sources: Value = VNull): List[String] =
+    Resolve.resolveCandidates(name, sources)
+
+  def applyEnv(input: Value): Value = Env.applyEnv(input)
+}

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

@@ -0,0 +1,107 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Point.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
+
+/** Extension points (section 6). Three kinds, chosen because they are what the
+  * two existing systems actually needed, and no more.
+  *
+  * A PLUGIN NEVER MUTATES THE HOST. That inversion is what makes deactivation
+  * possible: sdkgen's `utility.fetcher = wrapped` is not undoable, but "this
+  * instance holds slot 3 of the request chain" is undoable in O(1). OSGi named
+  * it the whiteboard pattern in 2004, in a paper called *Listeners Considered
+  * Harmful*, and for exactly this reason.
+  */
+
+/** A live binding. An internal shape, never a corpus value.
+  *
+  * EVERY BINDING IS ARITY TWO, `(next, arg)`, hook and chain alike. `next` is
+  * None for a hook. One signature means `Point` does not have to know which
+  * kind of point it is holding - and the kind is the HOST's property, not the
+  * binding's.
+  */
+final case class Binding(
+    ref: String,
+    point: String,
+    fn: (Option[Value => Value], Value) => Value,
+    band: Int
+)
+
+/** The winner and the losers on a provider point. */
+final case class Picked(winner: Option[Binding], shadowed: List[String])
+
+object Point {
+
+  /** Section 6.1: "fan-out" is not one answer but four. In a language with
+    * asynchrony, "call every binding" hides a decision - start them all and
+    * wait, await each in turn, or do not wait - and a design that leaves it
+    * unsaid gets four different answers from four ports, in the concurrency
+    * behaviour of production code no corpus entry happens to cover.
+    *
+    * SCALA IS A PORT WHERE THAT IS LOUD: `Future` and an implicit
+    * `ExecutionContext` are one import away, and using either for `emit` would
+    * make every hook point a scheduling decision and every ordering assertion a
+    * race. The host stays synchronous (section 5.2) and the modes stay data.
+    */
+  val modes = List("emit", "parallel", "serial", "bail")
+
+  /** Fan-out. Return values are ignored except in `bail`. */
+  def pointEmit(bindings: List[Binding], mode: String, arg: Value): Value = {
+    if (mode == "bail") {
+      // Stops at the first binding that RETURNS A VALUE - the "handled, stop"
+      // case. A `VNull` RETURN DECLINES (section 6.1): scala has one way to say
+      // nothing here, and the model's rule is written to that rather than to
+      // JavaScript's null/undefined pair. `!isNull`, NOT truthiness - `false`
+      // is a value.
+      return bindings.view.map(b => b.fn(None, arg)).find(!_.isNull).getOrElse(VNull)
+    }
+
+    val errors = List.newBuilder[Value]
+    bindings.foreach { b =>
+      try b.fn(None, arg)
+      catch {
+        case e: Exception =>
+          // `emit` raises synchronously; the collecting modes gather.
+          if (mode == "emit") throw e
+          errors += VStr(Types.messageOf(e))
+      }
+    }
+    if (mode == "emit") VNull else VList(errors.result())
+  }
+
+  /** Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (section 6.2).
+    *
+    * Recomputed by the host whenever the live set changes, and cached between
+    * changes. Plugins receive `next` as an argument; they never see or store
+    * the previous value of anything. A plugin that stashes `next` and calls it
+    * after deactivation is a bug the host cannot prevent, and this says so
+    * rather than pretending otherwise.
+    */
+  def compose(bindings: List[Binding], base: Value => Value): Value => Value =
+    // `foldRight` builds the chain outermost-LAST, so the fold runs from the
+    // base outward and the FIRST binding ends up the outermost call. Each layer
+    // closes over its own `inner`, which a `var` reused across iterations would
+    // not.
+    bindings.foldRight(base) { (b, inner) => (arg: Value) => b.fn(Some(inner), arg) }
+
+  /** At most one live implementation (section 6.3). The winner is the highest
+    * band, ties broken by ref sort, and THE LOSERS ARE VISIBLE rather than
+    * silently ignored.
+    */
+  def pointProvider(bindings: List[Binding], spec: Value): Picked = {
+    if (bindings.isEmpty) return Picked(None, Nil)
+
+    if (spec.at("exclusive").truthy && bindings.length > 1) {
+      val refs = bindings.map(_.ref).sorted
+      Types.fail(
+        "plugin_point_exclusive",
+        "point is exclusive and has " + bindings.length + " bindings: " +
+          refs.mkString(", "),
+        Map("refs" -> VList(refs.map(VStr.apply)))
+      )
+    }
+
+    val ranked = Types.stableSortBy(bindings)(b => List(KNum(-b.band), KText(b.ref)))
+    Picked(Some(ranked.head), ranked.tail.map(_.ref))
+  }
+}

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

@@ -0,0 +1,131 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Refs.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
+
+/** Identity: name+tag, written `name$tag` (section 4).
+  *
+  * The four pure functions, and the whole of what `ref` pins. They are the
+  * first thing a new port implements and the first corpus section it passes.
+  */
+object Refs {
+
+  val refMax = 1024
+
+  /** Section 4: `^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`, max 1024.
+    *
+    * A CHARACTER LOOP RATHER THAN A REGULAR EXPRESSION, for the same reason the
+    * swift port uses one: a grammar this small is clearer as the two character
+    * classes it actually is, and it removes the whole `^`/`$`-versus-`\A`/`\z`
+    * trap that ruby, java and dart each document from a different side. There
+    * is no anchor to get wrong, because there is no search, and `"abc\n"` fails
+    * on the newline like any other character outside the class.
+    */
+  def checkName(name: Value): Boolean = name.asString match {
+    // The parenthesis around the first-character test is LOAD-BEARING: scala
+    // binds `match` tighter than `||`, so `a || b match {...}` reads as
+    // `a || (b match {...})` and a name starting with a letter would
+    // short-circuit to true without the rest ever being checked.
+    case Some(s) if s.nonEmpty && s.length <= refMax =>
+      (isAlpha(s.charAt(0)) || s.charAt(0) == '@') && s.drop(1).forall(nameChar)
+    case _ => false
+  }
+
+  private def nameChar(c: Char): Boolean =
+    isAlpha(c) || c.isDigit || c == '.' || c == '~' || c == '_' || c == '-' || c == '/'
+
+  /** Section 4: `^[a-zA-Z0-9.~_-]+$`, max 1024, or empty.
+    *
+    * The asymmetry with a name is deliberate: a tag MAY start with a digit
+    * because auto-tagging assigns integer tags (`stripe$1`), and a tag admits
+    * neither `@` nor `/` because a name is a package specifier and a tag is not.
+    */
+  def checkTag(tag: Value): Boolean = tag.asString match {
+    // The empty tag is an ordinary tag (section 4 rule 2). The single-instance
+    // case writes no tag and never learns tags exist.
+    case Some("")                        => true
+    case Some(s) if s.length <= refMax   => s.forall(tagChar)
+    case _                               => false
+  }
+
+  private def tagChar(c: Char): Boolean =
+    isAlpha(c) || c.isDigit || c == '.' || c == '~' || c == '_' || c == '-'
+
+  def isAlpha(c: Char): Boolean = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')
+
+  /** `name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both give
+    * tag "".
+    */
+  def parseRef(str: Value): Value = {
+    val s = str.asString.getOrElse(
+      Types.fail("plugin_bad_name", "ref must be a string")
+    )
+    // Split on the FIRST `$`. Nothing in the grammar decides this - `$` is in
+    // neither character class - so the corpus is the arbiter (section 4 rule
+    // 5), and it picks the split that blames the part actually at fault:
+    // `a$b$c` is a good name with a bad tag, not the reverse.
+    val cut = s.indexOf('$')
+    val name = if (cut < 0) s else s.substring(0, cut)
+    val tag = if (cut < 0) "" else s.substring(cut + 1)
+
+    if (!checkName(VStr(name))) {
+      Types.fail(
+        "plugin_bad_name", "invalid plugin name: " + name, Map("name" -> VStr(name))
+      )
+    }
+    if (!checkTag(VStr(tag))) {
+      Types.fail(
+        "plugin_bad_tag", "invalid plugin tag: " + tag,
+        Map("name" -> VStr(name), "tag" -> VStr(tag))
+      )
+    }
+    Value.map("name" -> VStr(name), "tag" -> VStr(tag))
+  }
+
+  /** The pair -> `name$tag`. An empty tag NEVER writes the separator, which is
+    * the half of canonicalization `formatRef` owns: parse tolerates `stripe$`,
+    * format never produces it, so a round trip is idempotent.
+    */
+  def formatRef(name: Value, tag: Value = VNull): String = {
+    val t = if (tag.isNull) VStr("") else tag
+    if (!checkName(name)) {
+      Types.fail(
+        "plugin_bad_name", "invalid plugin name: " + show(name), Map("name" -> name)
+      )
+    }
+    if (!checkTag(t)) {
+      Types.fail(
+        "plugin_bad_tag", "invalid plugin tag: " + show(t),
+        Map("name" -> name, "tag" -> t)
+      )
+    }
+    val n = name.asString.get
+    val ts = t.asString.get
+    if (ts.isEmpty) n else n + "$" + ts
+  }
+
+  /** A value as a message would show it: a string bare, anything else as JSON.
+    * Interpolating a `Value` directly would print the case class.
+    */
+  def show(v: Value): String = v.asString.getOrElse(v.json)
+
+  /** The canonical spelling of a ref. Section 4 rule 5: ports must canonicalize
+    * before comparison.
+    */
+  def canonRef(str: Value): String = {
+    val r = parseRef(str)
+    formatRef(r.at("name"), r.at("tag"))
+  }
+
+  /** `canonRef` for the internal callers that want the input back unchanged
+    * when it is not well formed. NEVER use it where a bad ref must be reported
+    * - the corpus pins plugin_bad_name at every public entry.
+    */
+  def canon(str: Value): String =
+    try canonRef(str)
+    catch { case _: PluginError => show(str) }
+
+  def refName(str: Value): String =
+    try parseRef(str).at("name").asString.get
+    catch { case _: PluginError => show(str) }
+}

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

@@ -0,0 +1,53 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Resolve.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
+
+/** Dynamic resolution (section 10.2) - name to candidate module ids.
+  *
+  * PURE. It returns the ids a host WOULD try, in order; it does not load
+  * anything. That separation is what lets the corpus pin resolution in every
+  * language including those with no dynamic loading at all, and it is why
+  * section 15.4 puts real module loading in per-port integration tests rather
+  * than here.
+  */
+object Resolve {
+
+  val defaultSources: Value = Value.list(
+    Value.map(
+      "kind" -> VStr("module"),
+      "prefix" -> Value.list(
+        VStr("@voxgig/plugin-"), VStr("voxgig-plugin-"), VStr("plugin-"), VStr("")
+      )
+    )
+  )
+
+  def resolveCandidates(name: String, sources: Value = VNull): List[String] = {
+    // A SCOPED NAME RESOLVES VERBATIM ONLY (section 10.2). `@acme/thing` is
+    // already a package id; prefixing it produces `@voxgig/plugin-@acme/thing`,
+    // which is not a thing that can exist.
+    if (name.startsWith("@")) return List(name)
+
+    val list = if (sources.items.isEmpty) defaultSources else sources
+    val ids = list.items.flatMap { src =>
+      src.at("kind").asString match {
+        case Some("module") =>
+          val declared = src.at("prefix").items
+          val prefixes = if (declared.isEmpty) List(VStr("")) else declared
+          prefixes.map(p => p.asString.getOrElse("") + name)
+        case Some("path") =>
+          List(src.at("dir").asString.getOrElse("").replaceAll("/+$", "") + "/" + name)
+        case _ => Nil
+      }
+    }
+    ids.distinct
+  }
+
+  /** A MODULE PATH IS NOT A NAME (section 10.2). The ref grammar starts a name
+    * with a letter or `@`, so `./local/thing` is not a ref and never reaches
+    * candidate generation - seneca allows a path where a plugin name goes, and
+    * this design deliberately does not, because a ref is an ADDRESS WITHIN A
+    * HOST and a path is a LOCATION ON A DISK.
+    */
+  def resolveFrom(from: Value): List[Value] = List(from)
+}