@voxgig/sdkgen 4.9.0 → 4.10.0

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

@@ -0,0 +1,209 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (swift/src/Depend.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.
+/// 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.
+public struct GraphNode {
+    public let ref: String
+    public let provides: [String]
+    public let requires: [Value]
+
+    public init(_ ref: String, _ provides: [String], _ requires: [Value]) {
+        self.ref = ref
+        self.provides = provides
+        self.requires = requires
+    }
+}
+
+public enum Depend {
+
+    /// A bare string is shorthand for `{name}`.
+    public static func normRequire(_ raw: Value) -> Value {
+        if let s = raw.asString { return .map(["name": .str(s)]) }
+        if raw.isMap { return raw }
+        return .map([:])
+    }
+
+    /// 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".
+    public static func requirements(_ options: Value) -> [Value] {
+        let raw = options.at("requires").items
+        let marked = options.at("optional")
+        let fallback = options.get("policy")
+
+        return raw.map { item -> Value in
+            var req = normRequire(item)
+            let listed = marked.isList && marked.items.contains(req.at("name"))
+            if req.at("optional").truthy || listed {
+                req = req.setting("optional", .bool(true))
+            }
+            if !req.has("policy"), let f = fallback, !f.isNull {
+                req = req.setting("policy", f)
+            }
+            return req
+        }
+    }
+
+    /// 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.
+    public static func restartsOnLoss(_ req: Value) -> Bool {
+        let policy = req.get("policy")
+        return (policy?.isNull ?? true) ? true : policy!.asString != "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.
+    public static func gatesActivation(_ req: Value) -> Bool {
+        return req.at("optional") != .bool(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.
+    public static func restartCausing(_ req: Value) -> Bool {
+        return 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.
+    public static func dependencyCycle(_ nodes: [GraphNode]) -> [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.
+        var bycap: [String: [String]] = [:]
+        var isref: Set<String> = []
+        for n in nodes {
+            isref.insert(n.ref)
+            for cap in n.provides {
+                bycap[cap, default: []].append(n.ref)
+            }
+        }
+
+        var edges: [String: [String]] = [:]
+        for n in nodes {
+            var out: [String] = []
+            for req in n.requires where restartCausing(req) {
+                let reqname = req.at("name").asString ?? ""
+                var from = bycap[reqname] ?? []
+                // A node satisfies its own name AS A REF (section 11.1),
+                // canonically - exactly what `providersOf` does at
+                // runtime. `canon` hands back a name no ref could have
+                // unchanged, and no instance ref can equal one.
+                let asref = Refs.canon(.str(reqname))
+                if isref.contains(asref) && !from.contains(asref) {
+                    from.append(asref)
+                }
+                for p in from {
+                    if p != n.ref && !out.contains(p) { out.append(p) }
+                }
+            }
+            edges[n.ref] = out.sorted()
+        }
+
+        // Iterative DFS with an explicit stack: twenty ports, and several of
+        // them have no recursion budget worth relying on.
+        let white = 0, grey = 1, black = 2
+        var colour: [String: Int] = [:]
+        for n in nodes { colour[n.ref] = white }
+
+        for start in edges.keys.sorted() where colour[start] == white {
+            var path = [start]
+            var stack: [(String, Int)] = [(start, 0)]
+            colour[start] = grey
+
+            while !stack.isEmpty {
+                let (node, cursor) = stack[stack.count - 1]
+                let outs = edges[node]!
+                if cursor >= outs.count {
+                    colour[node] = black
+                    stack.removeLast()
+                    path.removeLast()
+                    continue
+                }
+                let next = outs[cursor]
+                stack[stack.count - 1] = (node, cursor + 1)
+                if colour[next] == grey {
+                    // Report the cycle itself, not the walk that found it.
+                    return Array(path[path.firstIndex(of: next)!...]) + [next]
+                }
+                if colour[next] == black { continue }
+                colour[next] = grey
+                path.append(next)
+                stack.append((next, 0))
+            }
+        }
+        return nil
+    }
+
+    /// Raise on a cycle, naming it. Separate from the detector so the detector
+    /// stays pure and corpus-testable.
+    public static func checkCycle(_ nodes: [GraphNode]) throws {
+        guard let cycle = dependencyCycle(nodes) else { return }
+        throw Types.fail(
+            "plugin_dependency_cycle",
+            "requirements cycle: " + cycle.joined(separator: " -> "),
+            ["cycle": .list(cycle.map { .str($0) })]
+        )
+    }
+}

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

@@ -0,0 +1,191 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (swift/src/Env.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.
+/// Environment overrides (section 9.5) - level 7 of the ladder.
+///
+/// One prefix, so nothing drifts: `VOXGIG_PLUGIN_*`.
+///
+///   VOXGIG_PLUGIN_PROFILE            the profile name
+///   VOXGIG_PLUGIN_<REF>_<PATH>       one option
+///   VOXGIG_PLUGIN_ACTIVE/INACTIVE    comma-separated refs, INACTIVE wins
+///
+/// THE ENCODING IS LOSSY, AND THIS SAYS SO RATHER THAN PRETENDING OTHERWISE.
+/// Ref and path are upper-snake with `$` -> `__` and `.` -> `_`. But `_` is
+/// legal in a name and in a tag, and the mapping folds case, so `retry$fast`
+/// and `retry__fast` both encode to `RETRY__FAST`.
+///
+/// Rather than restrict a grammar the rest of the stack already uses, the host
+/// DETECTS THE COLLISION: it encodes every ref it holds, and a key two refs
+/// claim is `plugin_env_ambiguous`, naming both.
+public enum Env {
+
+    static let prefix = "VOXGIG_PLUGIN_"
+
+    /// `retry$fast` -> `RETRY__FAST`.
+    public static func encodeRef(_ ref: String) -> String {
+        return ref.replacingOccurrences(of: "$", with: "__")
+            .replacingOccurrences(of: ".", with: "_")
+            .uppercased()
+    }
+
+    /// Values parse as JSON, FALLING BACK TO STRING - so `8080` is a number,
+    /// `true` is a boolean, `{"a":1}` is a map, and `hello` is the string it
+    /// looks like rather than a parse error.
+    static func parseValue(_ value: Value) -> Value {
+        guard let s = value.asString else { return value }
+        return (try? Json.parse(s)) ?? value
+    }
+
+    static func split(_ value: Value) -> [String] {
+        let text = value.asString ?? value.json
+        return text.split(separator: ",", omittingEmptySubsequences: false)
+            .map { $0.trimmed }
+            .filter { !$0.isEmpty }
+    }
+
+    static func checkReserved(_ ref: String, _ reserved: Value) throws {
+        guard reserved.items.contains(.str(Refs.refName(.str(ref)))) else { return }
+        throw Types.fail(
+            "plugin_ref_reserved", "ref is reserved by the host: \(ref)",
+            ["ref": .str(ref)]
+        )
+    }
+
+    public static func applyEnv(_ input: Value) throws -> Value {
+        let env = input.at("env")
+        let refs = try input.at("refs").items.map { try Refs.canonRef($0) }
+        let reserved = input.at("reserved")
+
+        var options: [String: Value] = [:]
+        var active: [Value] = []
+        var inactive: [Value] = []
+        var profile: Value?
+
+        // Encode every ref the host holds, and refuse a key that two of them
+        // claim. Done up front so the collision is reported even when no
+        // environment variable exercises it - a latent ambiguity is still an
+        // ambiguity, and finding it at deploy time is the failure this exists to
+        // prevent.
+        var byencoded: [String: [String]] = [:]
+        for ref in refs { byencoded[encodeRef(ref), default: []].append(ref) }
+        for e in byencoded.keys.sorted() where byencoded[e]!.count > 1 {
+            let pair = byencoded[e]!.sorted()
+            throw Types.fail(
+                "plugin_env_ambiguous",
+                "refs collide in the environment encoding as \(e): "
+                    + pair.joined(separator: ", "),
+                ["encoded": .str(e), "refs": .list(pair.map { .str($0) })]
+            )
+        }
+
+        // Longest encoded ref first, so `retry$fast` wins over `retry` on
+        // `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+        let encoded = Types.stableSortBy(byencoded.keys.sorted()) {
+            [SortKey.num(Double(-$0.count))]
+        }
+
+        for key in env.keys {
+            guard key.hasPrefix(prefix) else { continue }
+            let rest = String(key.dropFirst(prefix.count))
+
+            if rest == "PROFILE" {
+                profile = env.at(key)
+                continue
+            }
+
+            if rest == "ACTIVE" || rest == "INACTIVE" {
+                for raw in split(env.at(key)) {
+                    let ref = try Refs.canonRef(.str(raw))
+                    // The reservation covers EVERY input layer (section 9.1).
+                    // VOXGIG_PLUGIN_INACTIVE=station is easier to set than
+                    // editing a config file, and INACTIVE has the final word -
+                    // so guarding documents alone would leave the one lever this
+                    // mechanism exists to deny wide open.
+                    try checkReserved(ref, reserved)
+                    if rest == "ACTIVE" { active.append(.str(ref)) }
+                    else { inactive.append(.str(ref)) }
+                }
+                continue
+            }
+
+            guard let enc = encoded.first(where: { rest == $0 || rest.hasPrefix($0 + "_") })
+            else { continue } // not for any ref this host holds
+
+            let ref = byencoded[enc]![0]
+            try checkReserved(ref, reserved)
+
+            if rest == enc { continue } // a ref with no path sets nothing
+
+            let path = String(rest.dropFirst(enc.count + 1)).lowercased()
+                .split(separator: "_", omittingEmptySubsequences: false).map(String.init)
+
+            options[ref] = write(options[ref] ?? .map([:]), path, parseValue(env.at(key)))
+        }
+
+        var out: [String: Value] = [
+            "options": .map(options),
+            "active": .list(active),
+            "inactive": .list(inactive),
+        ]
+        if let p = profile { out["profile"] = p }
+        return .map(out)
+    }
+
+    /// Write one option at a dotted path, creating maps as it goes. A step whose
+    /// current value is not a map is REPLACED, because a scalar written by a
+    /// shallower variable cannot also be a container.
+    static func write(_ node: Value, _ path: [String], _ value: Value) -> Value {
+        let base = node.isMap ? node : .map([:])
+        if path.count == 1 { return base.setting(path[0], value) }
+        let child = base.at(path[0])
+        return base.setting(path[0], write(child, Array(path.dropFirst()), value))
+    }
+}
+
+extension Substring {
+    var trimmed: String {
+        var s = self
+        while let f = s.first, f == " " || f == "\t" || f == "\n" || f == "\r" {
+            s = s.dropFirst()
+        }
+        while let l = s.last, l == " " || l == "\t" || l == "\n" || l == "\r" {
+            s = s.dropLast()
+        }
+        return String(s)
+    }
+}
+
+extension String {
+    /// The library imports no Foundation, so the two string replacements
+    /// `encodeRef` needs are written here rather than taken from it.
+    func replacingOccurrences(of needle: String, with replacement: String) -> String {
+        guard !needle.isEmpty else { return self }
+        var out = ""
+        var rest = Substring(self)
+        while let r = rest.range(of: needle) {
+            out += rest[rest.startIndex ..< r.lowerBound]
+            out += replacement
+            rest = rest[r.upperBound...]
+        }
+        return out + rest
+    }
+}
+
+extension Substring {
+    func range(of needle: String) -> Range<Index>? {
+        let n = Array(needle)
+        guard !n.isEmpty else { return nil }
+        var i = startIndex
+        while i < endIndex {
+            var j = i
+            var k = 0
+            while k < n.count, j < endIndex, self[j] == n[k] {
+                j = index(after: j)
+                k += 1
+            }
+            if k == n.count { return i ..< j }
+            i = index(after: i)
+        }
+        return nil
+    }
+}

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

@@ -0,0 +1,63 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (swift/src/Export.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.
+/// Exports (section 11).
+///
+/// An instance publishes values for other plugins and for the application.
+/// Read with `host.exports("retry$fast/client")`.
+///
+/// THE UNQUALIFIED ALIAS IS THE INTERESTING PART. `retry/client` resolves to
+/// the UNTAGGED instance if one exists; if not, and exactly one tagged instance
+/// exports that key, it resolves to that one; if two do, it is
+/// `plugin_export_ambiguous` - deliberately diverging from seneca's silent
+/// last-wins, because with multi-instance as a headline feature an ambiguous
+/// alias is a defect waiting for production.
+public enum Export {
+
+    /// One published value. An internal shape, never a corpus value.
+    public struct Exported {
+        public let ref: String
+        public let key: String
+        public let value: Value
+
+        public init(_ ref: String, _ key: String, _ value: Value) {
+            self.ref = ref
+            self.key = key
+            self.value = value
+        }
+    }
+
+    public static func resolveExport(_ spec: String, _ exported: [Exported]) throws -> Value {
+        guard let cut = spec.firstIndex(of: "/") else {
+            throw Types.fail(
+                "plugin_export_ambiguous", "export spec needs a key: \(spec)",
+                ["spec": .str(spec)]
+            )
+        }
+        let head = String(spec[spec.startIndex ..< cut])
+        let key = String(spec[spec.index(after: cut)...])
+
+        // A fully qualified ref: exactly one answer or none.
+        let want = Refs.canon(.str(head))
+        for e in exported where e.ref == want && e.key == key { return e.value }
+
+        // An alias: the name, not a ref. Look at every instance of it.
+        let byname = exported.filter { Refs.refName(.str($0.ref)) == head && $0.key == key }
+        if byname.isEmpty { return .null }
+
+        for e in byname {
+            if let parsed = try? Refs.parseRef(.str(e.ref)),
+               parsed.at("tag").asString == "" {
+                return e.value
+            }
+        }
+        if byname.count == 1 { return byname[0].value }
+
+        let refs = byname.map { $0.ref }.sorted()
+        throw Types.fail(
+            "plugin_export_ambiguous",
+            "alias \(spec) matches \(refs.count) instances: \(refs.joined(separator: ", "))",
+            ["spec": .str(spec), "refs": .list(refs.map { .str($0) })]
+        )
+    }
+}

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

@@ -0,0 +1,158 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (swift/src/Graph.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.
+/// Whole-graph resolution (section 11.4) - a phase, not a discovery.
+///
+/// "Activate, and wait in `pending` if you must" is correct and, on its own,
+/// produces a terrible experience: apply twenty instances against a registry
+/// missing one thing and you get NINETEEN pending rows and no statement of what
+/// is actually wrong.
+///
+/// `resolveGraph` is a PURE FUNCTION of the registry and the intended
+/// activation set. No callbacks run, no state changes, nothing is touched. It
+/// answers for the whole graph at once which instances can be live, and for
+/// each blocked one THE SPECIFIC REQUIREMENT that is unmet, and why.
+///
+/// The failure mode being designed against is a famous one: OSGi's resolver is
+/// correct and its diagnostics are legendarily unusable. A resolver that says
+/// "blocked" without saying WHY has moved the problem rather than solved it, so
+/// `why` is part of the contract and the corpus pins its shape.
+public enum Graph {
+
+    public static func resolveGraph(_ nodes: Value) -> Value {
+        var byref: [String: Value] = [:]
+        for n in nodes.items { byref[n.at("ref").asString ?? ""] = n }
+
+        var resolved: Set<String> = []
+
+        // Fixed point: a node resolves when every mandatory requirement is met
+        // by an ALREADY-RESOLVED provider. Iterating to a fixed point is what
+        // makes a provider that is itself blocked propagate, rather than each
+        // node being judged against the raw registry.
+        var moved = true
+        while moved {
+            moved = false
+            for n in nodes.items {
+                let ref = n.at("ref").asString ?? ""
+                if resolved.contains(ref) { continue }
+                if firstUnmet(n, byref, resolved) != nil { continue }
+                resolved.insert(ref)
+                moved = true
+            }
+        }
+
+        var blocked: [String: Value] = [:]
+        for n in nodes.items {
+            let ref = n.at("ref").asString ?? ""
+            if resolved.contains(ref) { continue }
+            guard let why = firstUnmet(n, byref, resolved) else { continue }
+            blocked[ref] = why
+        }
+
+        return .map([
+            "resolved": .list(resolved.sorted().map { .str($0) }),
+            "blocked": .list(blocked.keys.sorted().map { blocked[$0]! }),
+        ])
+    }
+
+    /// The FIRST unmet requirement, with the most specific explanation
+    /// available. Order matters: "no provider at all" and "a provider at the
+    /// wrong version" are different problems and a reader must not have to guess
+    /// which they have.
+    public static func firstUnmet(
+        _ node: Value, _ byref: [String: Value], _ resolved: Set<String>
+    ) -> Value? {
+        for req in node.at("requires").items {
+            if req.at("optional").truthy { continue }
+            let name = req.at("name").asString ?? ""
+
+            let all = graphCandidates(byref, name)
+            if all.isEmpty { return why(node, name, .map(["kind": .str("absent")])) }
+
+            let ok = Capability.resolveCapability(req, .list(all))
+            if !ok.isEmpty {
+                // A provider exists and matches - but if none of them is itself
+                // resolved, this node is blocked BEHIND it, and the chain is the
+                // useful answer rather than "unmet".
+                if ok.contains(where: { resolved.contains($0.at("ref").asString ?? "") }) {
+                    continue
+                }
+                let chain = ok.map { $0.at("ref").asString ?? "" }.sorted()
+                return why(node, name, .map([
+                    "kind": .str("blocked"),
+                    "chain": .list(chain.map { .str($0) }),
+                ]))
+            }
+
+            // Providers exist and none matched. Say which test failed.
+            if let range = req.get("range"), !range.isNull {
+                let versions = all
+                    .map { $0.at("provides").at("version") }
+                    .filter { $0.isNull || !Version.satisfiesq($0, range) }
+                    .map { $0.asString ?? "(none)" }
+                if !versions.isEmpty {
+                    return why(node, name, .map([
+                        "kind": .str("version"),
+                        "range": range,
+                        "found": .list(versions.sorted().map { .str($0) }),
+                    ]))
+                }
+            }
+
+            if let match = req.get("match"), !match.isNull {
+                for c in all {
+                    let attrs = c.at("provides").at("attrs")
+                    for k in match.keys {
+                        if attrs.has(k),
+                           Capability.matchValue(match.at(k), attrs.at(k)) { continue }
+                        return why(node, name, .map([
+                            "kind": .str("match"),
+                            "failing": .str(k),
+                            "want": match.at(k),
+                            "found": attrs.at(k),
+                        ]))
+                    }
+                }
+            }
+
+            return why(node, name, .map(["kind": .str("absent")]))
+        }
+        return nil
+    }
+
+    static func why(_ node: Value, _ name: String, _ reason: Value) -> Value {
+        return .map(["ref": node.at("ref"), "unmet": .str(name), "why": reason])
+    }
+
+    public static func graphCandidates(_ byref: [String: Value], _ name: String) -> [Value] {
+        var out: [Value] = []
+        // A NODE SATISFIES ITS OWN REF (section 11.1), and the graph
+        // learned it here. Considering only declared capabilities made
+        // `resolve` answer `absent` about a provider sitting right there
+        // and live - section 11.4's job is explaining the graph the
+        // runtime reconciles, and it was explaining a different one.
+        let asref = Refs.canon(.str(name))
+        for ref in byref.keys.sorted() {
+            let node = byref[ref]!
+            // The ref match WINS OUTRIGHT for that node, as at runtime:
+            // one candidate, not two, for a node both named `b` and
+            // providing `b`.
+            if ref == asref {
+                out.append(.map([
+                    "ref": node.at("ref"),
+                    "pos": node.get("pos") ?? .num(0),
+                    "provides": .map(["name": .str(name)]),
+                ]))
+                continue
+            }
+            for prov in node.at("provides").items where prov.at("name").asString == name {
+                out.append(.map([
+                    "ref": node.at("ref"),
+                    "pos": node.get("pos") ?? .num(0),
+                    "provides": prov,
+                ]))
+            }
+        }
+        return out
+    }
+}