@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/secrets/plugin/Json.swift

@@ -0,0 +1,192 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (swift/src/Json.swift)
+// 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.
+/// The JSON parser.
+///
+/// A hundred and fifty lines, and a hundred and fifty lines is cheaper than an
+/// `import Foundation` in a library whose whole value model is an enum
+/// `JSONSerialization` cannot produce.
+public enum Json {
+
+    public static func parse(_ text: String) throws -> Value {
+        var parser = Parser(Array(text.unicodeScalars))
+        parser.skipws()
+        let value = try parser.value()
+        parser.skipws()
+        if parser.at < parser.chars.count {
+            throw PluginError("plugin_json", "trailing input at \(parser.at)", [:])
+        }
+        return value
+    }
+
+    struct Parser {
+        let chars: [Unicode.Scalar]
+        var at: Int = 0
+
+        init(_ chars: [Unicode.Scalar]) { self.chars = chars }
+
+        mutating func skipws() {
+            while at < chars.count,
+                  chars[at] == " " || chars[at] == "\t" ||
+                  chars[at] == "\n" || chars[at] == "\r" {
+                at += 1
+            }
+        }
+
+        mutating func value() throws -> Value {
+            guard at < chars.count else {
+                throw PluginError("plugin_json", "unexpected end of input", [:])
+            }
+            switch chars[at] {
+            case "{": return try map()
+            case "[": return try list()
+            case "\"": return .str(try string())
+            case "t": return try literal("true", .bool(true))
+            case "f": return try literal("false", .bool(false))
+            case "n": return try literal("null", .null)
+            default: return try number()
+            }
+        }
+
+        mutating func literal(_ word: String, _ value: Value) throws -> Value {
+            let scalars = Array(word.unicodeScalars)
+            guard at + scalars.count <= chars.count,
+                  Array(chars[at ..< at + scalars.count]) == scalars else {
+                throw PluginError("plugin_json", "unexpected input at \(at)", [:])
+            }
+            at += scalars.count
+            return value
+        }
+
+        mutating func map() throws -> Value {
+            var out: [String: Value] = [:]
+            at += 1
+            skipws()
+            if at < chars.count, chars[at] == "}" {
+                at += 1
+                return .map(out)
+            }
+            while true {
+                skipws()
+                let key = try string()
+                skipws()
+                guard at < chars.count, chars[at] == ":" else {
+                    throw PluginError("plugin_json", "expected : at \(at)", [:])
+                }
+                at += 1
+                skipws()
+                out[key] = try value()
+                skipws()
+                guard at < chars.count else {
+                    throw PluginError("plugin_json", "unterminated map", [:])
+                }
+                if chars[at] == "," { at += 1; continue }
+                guard chars[at] == "}" else {
+                    throw PluginError("plugin_json", "expected } at \(at)", [:])
+                }
+                at += 1
+                return .map(out)
+            }
+        }
+
+        mutating func list() throws -> Value {
+            var out: [Value] = []
+            at += 1
+            skipws()
+            if at < chars.count, chars[at] == "]" {
+                at += 1
+                return .list(out)
+            }
+            while true {
+                skipws()
+                out.append(try value())
+                skipws()
+                guard at < chars.count else {
+                    throw PluginError("plugin_json", "unterminated list", [:])
+                }
+                if chars[at] == "," { at += 1; continue }
+                guard chars[at] == "]" else {
+                    throw PluginError("plugin_json", "expected ] at \(at)", [:])
+                }
+                at += 1
+                return .list(out)
+            }
+        }
+
+        mutating func string() throws -> String {
+            guard at < chars.count, chars[at] == "\"" else {
+                throw PluginError("plugin_json", "expected string at \(at)", [:])
+            }
+            at += 1
+            var out = String.UnicodeScalarView()
+            while true {
+                guard at < chars.count else {
+                    throw PluginError("plugin_json", "unterminated string", [:])
+                }
+                let c = chars[at]
+                if c == "\"" {
+                    at += 1
+                    return String(out)
+                }
+                if c == "\\" {
+                    at += 1
+                    guard at < chars.count else {
+                        throw PluginError("plugin_json", "unterminated escape", [:])
+                    }
+                    switch chars[at] {
+                    case "n": out.append("\n")
+                    case "t": out.append("\t")
+                    case "r": out.append("\r")
+                    case "b": out.append(Unicode.Scalar(8))
+                    case "f": out.append(Unicode.Scalar(12))
+                    case "u":
+                        var code: UInt32 = 0
+                        for k in 1 ... 4 {
+                            guard at + k < chars.count,
+                                  let digit = chars[at + k].hexDigitValue else {
+                                throw PluginError("plugin_json", "bad \\u escape", [:])
+                            }
+                            code = code * 16 + UInt32(digit)
+                        }
+                        guard let scalar = Unicode.Scalar(code) else {
+                            throw PluginError("plugin_json", "bad \\u escape", [:])
+                        }
+                        out.append(scalar)
+                        at += 4
+                    default: out.append(chars[at])
+                    }
+                    at += 1
+                    continue
+                }
+                out.append(c)
+                at += 1
+            }
+        }
+
+        mutating func number() throws -> Value {
+            let start = at
+            while at < chars.count, Json.isNumeric(chars[at]) { at += 1 }
+            guard start != at, let n = Double(String(String.UnicodeScalarView(chars[start ..< at])))
+            else {
+                throw PluginError("plugin_json", "unexpected input at \(at)", [:])
+            }
+            return .num(n)
+        }
+    }
+
+    static func isNumeric(_ c: Unicode.Scalar) -> Bool {
+        return ("0" ... "9").contains(c) ||
+            c == "-" || c == "+" || c == "." || c == "e" || c == "E"
+    }
+}
+
+extension Unicode.Scalar {
+    var hexDigitValue: Int? {
+        switch self {
+        case "0" ... "9": return Int(value - 48)
+        case "a" ... "f": return Int(value - 87)
+        case "A" ... "F": return Int(value - 55)
+        default: return nil
+        }
+    }
+}

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/secrets/plugin/Order.swift

@@ -0,0 +1,183 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (swift/src/Order.swift)
+// 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.
+/// 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.
+public struct OrderNode {
+    public let ref: String
+    public let pos: Int
+    public let order: Value
+
+    public init(_ ref: String, _ pos: Int, _ order: Value) {
+        self.ref = ref
+        self.pos = pos
+        self.order = order
+    }
+}
+
+public enum Order {
+
+    public static func orderBand(_ b: OrderNode) -> Int {
+        return b.order.at("band").asInt ?? 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.
+    public static func orderDeclared(_ spec: Value) -> Bool {
+        if spec.isNull { return false }
+        if case .list(let l) = spec { return l.contains { $0 != .str("") } }
+        return spec != .str("")
+    }
+
+    /// 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.
+    public static func orderTargets(_ spec: Value, _ nodes: [OrderNode]) -> [String] {
+        let specs: [Value] = spec.isList ? spec.items : [spec]
+        var hit: [String] = []
+        for one in specs {
+            for b in nodes {
+                if hit.contains(b.ref) { continue }
+                if .str(b.ref) == one || .str(Refs.refName(.str(b.ref))) == one {
+                    hit.append(b.ref)
+                }
+            }
+        }
+        return hit
+    }
+
+    public static func resolveOrder(_ bindings: [OrderNode], _ pin: Value = .null) throws
+        -> [String] {
+        var byref: [String: OrderNode] = [:]
+        for b in bindings { byref[b.ref] = b }
+
+        // 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.
+        var edges: [String: [String]] = [:]
+        for b in bindings { edges[b.ref] = [] }
+
+        for b in bindings {
+            let block = b.order
+            if orderDeclared(block.at("after")) {
+                for target in orderTargets(block.at("after"), bindings) {
+                    edges[target]!.append(b.ref)
+                }
+            }
+            if orderDeclared(block.at("before")) {
+                edges[b.ref]!.append(contentsOf: orderTargets(block.at("before"), bindings))
+            }
+        }
+
+        var indeg: [String: Int] = [:]
+        for b in bindings { indeg[b.ref] = 0 }
+        for (_, tos) in edges {
+            for to in tos { 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`.
+        var out: [String] = []
+        var ready = bindings.filter { indeg[$0.ref] == 0 }
+
+        while !ready.isEmpty {
+            ready = Types.stableSortBy(ready) {
+                [SortKey.num(Double(orderBand($0))), SortKey.num(Double($0.pos))]
+            }
+            let next = ready.removeFirst()
+            out.append(next.ref)
+            for to in edges[next.ref]! {
+                indeg[to]! -= 1
+                if indeg[to] == 0 { ready.append(byref[to]!) }
+            }
+        }
+
+        if out.count != bindings.count {
+            let stuck = bindings.filter { !out.contains($0.ref) }.map { $0.ref }
+            throw Types.fail(
+                "plugin_order_cycle",
+                "before/after constraints cycle: " + stuck.joined(separator: " -> "),
+                ["cycle": .list(stuck.map { .str($0) })]
+            )
+        }
+
+        return try applyPin(out, edges, 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.
+    public static func applyPin(
+        _ order: [String], _ edges: [String: [String]], _ pin: Value
+    ) throws -> [String] {
+        if pin.isNull { return order }
+        var out = 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 swift dictionary
+        // has no order at all, so leaving it unstated made the same declaration
+        // mean different things in different ports.
+        for name in pin.keys {
+            let want = pin.at(name).asString
+            guard let idx = out.firstIndex(where: { Refs.refName(.str($0)) == name })
+            else { continue }
+
+            // `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.
+            let wantFirst = want == "first" || want == "outermost"
+            let ref = out.remove(at: idx)
+            if wantFirst { out.insert(ref, at: 0) } else { out.append(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.
+        var at: [String: Int] = [:]
+        for (i, ref) in out.enumerated() { at[ref] = i }
+        for from in edges.keys.sorted() {
+            for to in edges[from]! {
+                if at[from]! <= at[to]! { continue }
+                throw Types.fail(
+                    "plugin_order_pinned",
+                    "a pin would move a binding an ordering constrains: "
+                        + "\(from) must precede \(to)",
+                    ["before": .str(from), "after": .str(to)]
+                )
+            }
+        }
+        return out
+    }
+}

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/secrets/plugin/Point.swift

@@ -0,0 +1,130 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (swift/src/Point.swift)
+// 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.
+/// 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.
+
+/// EVERY BINDING IS ARITY TWO, `(next, arg)`, hook and chain alike. `next` is
+/// nil 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. It `throws`, because a plugin's callback can fail and swift makes
+/// that part of the type.
+public typealias NextFn = (Value) throws -> Value
+public typealias BindingFn = (NextFn?, Value) throws -> Value
+
+/// A live binding. An internal shape, never a corpus value.
+public struct Binding {
+    public let ref: String
+    public let point: String
+    public let fn: BindingFn
+    public var band: Int
+
+    public init(_ ref: String, _ point: String, _ fn: @escaping BindingFn, _ band: Int) {
+        self.ref = ref
+        self.point = point
+        self.fn = fn
+        self.band = band
+    }
+}
+
+/// The winner and the losers on a provider point.
+public struct Picked {
+    public let winner: Binding?
+    public let shadowed: [String]
+}
+
+public enum 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.
+    ///
+    /// SWIFT IS A PORT WHERE THAT IS LOUD: `async` and a `TaskGroup` are one
+    /// keyword away, and using either for `emit` would make every hook point a
+    /// suspension point and every ordering assertion a race. The host stays
+    /// synchronous (section 5.2) and the modes stay data.
+    public static let modes = ["emit", "parallel", "serial", "bail"]
+
+    /// Fan-out. Return values are ignored except in `bail`.
+    public static func pointEmit(
+        _ bindings: [Binding], _ mode: String, _ arg: Value
+    ) throws -> Value {
+        if mode == "bail" {
+            // Stops at the first binding that RETURNS A VALUE - the "handled,
+            // stop" case. A `.null` RETURN DECLINES (section 6.1): swift 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.
+            for b in bindings {
+                let v = try b.fn(nil, arg)
+                if !v.isNull { return v }
+            }
+            return .null
+        }
+
+        var errors: [Value] = []
+        for b in bindings {
+            do {
+                _ = try b.fn(nil, arg)
+            } catch {
+                // `emit` raises synchronously; the collecting modes gather.
+                if mode == "emit" { throw error }
+                errors.append(.str(Types.messageOf(error)))
+            }
+        }
+        return mode == "emit" ? .null : .list(errors)
+    }
+
+    /// 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.
+    public static func compose(
+        _ bindings: [Binding], _ base: @escaping NextFn
+    ) -> NextFn {
+        var next = base
+        for i in stride(from: bindings.count - 1, through: 0, by: -1) {
+            // `fn` and `inner` are declared INSIDE the loop, so each layer
+            // closes over its own pair. Swift captures the variable rather than
+            // the value, and hoisting either would leave every layer calling the
+            // last one.
+            let fn = bindings[i].fn
+            let inner = next
+            next = { arg in try fn(inner, arg) }
+        }
+        return next
+    }
+
+    /// 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.
+    public static func pointProvider(_ bindings: [Binding], _ spec: Value) throws -> Picked {
+        if bindings.isEmpty { return Picked(winner: nil, shadowed: []) }
+
+        if spec.at("exclusive").truthy && bindings.count > 1 {
+            let refs = bindings.map { $0.ref }.sorted()
+            throw Types.fail(
+                "plugin_point_exclusive",
+                "point is exclusive and has \(bindings.count) bindings: "
+                    + refs.joined(separator: ", "),
+                ["refs": .list(refs.map { .str($0) })]
+            )
+        }
+
+        let ranked = Types.stableSortBy(bindings) {
+            [SortKey.num(Double(-$0.band)), SortKey.text($0.ref)]
+        }
+        return Picked(winner: ranked[0], shadowed: ranked.dropFirst().map { $0.ref })
+    }
+}

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/secrets/plugin/Refs.swift

@@ -0,0 +1,141 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (swift/src/Refs.swift)
+// 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.
+/// 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.
+public enum Refs {
+
+    static let refMax = 1024
+
+    /// Section 4: `^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`, max 1024.
+    ///
+    /// A CHARACTER LOOP RATHER THAN A REGULAR EXPRESSION. Swift's stdlib has
+    /// no regex on Linux - `NSRegularExpression` lives in Foundation, and this
+    /// library imports Foundation nowhere - and a grammar this small is
+    /// clearer as the two character classes it actually is. It also 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.
+    public static func checkName(_ name: Value) -> Bool {
+        guard let s = name.asString, !s.isEmpty, s.unicodeScalars.count <= refMax
+        else { return false }
+        var first = true
+        for c in s.unicodeScalars {
+            if first {
+                guard isAlpha(c) || c == "@" else { return false }
+                first = false
+                continue
+            }
+            guard isAlpha(c) || isDigit(c) || c == "." || c == "~" ||
+                c == "_" || c == "-" || c == "/" else { return false }
+        }
+        return true
+    }
+
+    /// 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.
+    public static func checkTag(_ tag: Value) -> Bool {
+        guard let s = tag.asString else { return false }
+        // The empty tag is an ordinary tag (section 4 rule 2). The
+        // single-instance case writes no tag and never learns tags exist.
+        if s.isEmpty { return true }
+        guard s.unicodeScalars.count <= refMax else { return false }
+        for c in s.unicodeScalars {
+            guard isAlpha(c) || isDigit(c) || c == "." || c == "~" ||
+                c == "_" || c == "-" else { return false }
+        }
+        return true
+    }
+
+    static func isAlpha(_ c: Unicode.Scalar) -> Bool {
+        return ("a" ... "z").contains(c) || ("A" ... "Z").contains(c)
+    }
+
+    static func isDigit(_ c: Unicode.Scalar) -> Bool {
+        return ("0" ... "9").contains(c)
+    }
+
+    /// `name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both give
+    /// tag "".
+    public static func parseRef(_ str: Value) throws -> Value {
+        guard let s = str.asString else {
+            throw 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.
+        let scalars = Array(s.unicodeScalars)
+        let cut = scalars.firstIndex(of: "$")
+        let name = cut == nil ? s : String(String.UnicodeScalarView(scalars[0 ..< cut!]))
+        let tag = cut == nil
+            ? ""
+            : String(String.UnicodeScalarView(scalars[(cut! + 1)...]))
+
+        guard checkName(.str(name)) else {
+            throw Types.fail(
+                "plugin_bad_name", "invalid plugin name: \(name)", ["name": .str(name)]
+            )
+        }
+        guard checkTag(.str(tag)) else {
+            throw Types.fail(
+                "plugin_bad_tag", "invalid plugin tag: \(tag)",
+                ["name": .str(name), "tag": .str(tag)]
+            )
+        }
+        return .map(["name": .str(name), "tag": .str(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.
+    public static func formatRef(_ name: Value, _ tag: Value = .null) throws -> String {
+        let t = tag.isNull ? Value.str("") : tag
+        guard checkName(name) else {
+            throw Types.fail(
+                "plugin_bad_name", "invalid plugin name: \(show(name))", ["name": name]
+            )
+        }
+        guard checkTag(t) else {
+            throw Types.fail(
+                "plugin_bad_tag", "invalid plugin tag: \(show(t))",
+                ["name": name, "tag": t]
+            )
+        }
+        let n = name.asString!
+        let ts = t.asString!
+        return ts.isEmpty ? n : "\(n)$\(ts)"
+    }
+
+    /// A value as a message would show it: a string bare, anything else as
+    /// JSON. Interpolating a `Value` directly would print the enum case.
+    static func show(_ v: Value) -> String {
+        return v.asString ?? v.json
+    }
+
+    /// The canonical spelling of a ref. Section 4 rule 5: ports must
+    /// canonicalize before comparison.
+    public static func canonRef(_ str: Value) throws -> String {
+        let r = try parseRef(str)
+        return try 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.
+    public static func canon(_ str: Value) -> String {
+        return (try? canonRef(str)) ?? (str.asString ?? str.json)
+    }
+
+    public static func refName(_ str: Value) -> String {
+        if let r = try? parseRef(str), let n = r.at("name").asString { return n }
+        return str.asString ?? str.json
+    }
+}