@voxgig/sdkgen 4.8.3 → 4.10.0

package/project/.sdk/tm/perl/feature/secrets/plugin/Voxgig/Plugin/Depend.pm

@@ -0,0 +1,216 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Depend.pm)
+# 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::Depend;
+
+# 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.
+
+use strict;
+use warnings;
+use Voxgig::Plugin::Types qw(fail_with truthy ismap islist sortstrings sortedkeys);
+use Voxgig::Plugin::Ref qw(canon);
+
+use Exporter 'import';
+our @EXPORT_OK = qw(normrequire requirements restartsonloss gatesactivation
+                    restartcausing dependencycycle checkcycle);
+
+# A bare string is shorthand for `{name}`.
+sub normrequire {
+    my ($raw) = @_;
+    return { name => $raw } if !ref $raw;
+    return ismap($raw) ? { %$raw } : {};
+}
+
+# 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".
+sub requirements {
+    my ($options) = @_;
+    $options //= {};
+    my $raw = $options->{requires} // [];
+    my $marked = $options->{optional} // [];
+    my $fallback = $options->{policy};
+
+    my @out;
+    for my $item (@$raw) {
+        my $req = normrequire($item);
+        my $ismarked = islist($marked)
+            && grep { defined $req->{name} && $_ eq $req->{name} } @$marked;
+        $req->{optional} = !!1 if truthy($req->{optional}) || $ismarked;
+        $req->{policy} = $fallback
+            if !defined $req->{policy} && defined $fallback;
+        push @out, $req;
+    }
+    return \@out;
+}
+
+# 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.
+sub restartsonloss {
+    my ($req) = @_;
+    return 'dynamic' ne ($req->{policy} // 'static') ? 1 : 0;
+}
+
+# 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.
+sub gatesactivation {
+    my ($req) = @_;
+    return truthy($req->{optional}) ? 0 : 1;
+}
+
+# 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.
+sub restartcausing {
+    my ($req) = @_;
+    return (gatesactivation($req) || restartsonloss($req)) ? 1 : 0;
+}
+
+# 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.
+sub dependencycycle {
+    my ($nodes) = @_;
+    # TWO INDEXES, NOT ONE MERGED MAP. Capability names and refs are
+    # matched differently - a capability by its exact name, a ref through
+    # the canonical spelling (section 4 rule 5) - and one map keyed by
+    # both can only do one of them. Keyed by both and looked up raw, as
+    # this was, a cycle spelled `a$`/`b$` found no providers and EVADED
+    # the load-time check that exists to catch a non-terminating
+    # reconcile.
+    my (%bycap, %isref);
+    for my $n (@$nodes) {
+        $isref{ $n->{ref} } = 1;
+        for my $cap (@{ $n->{provides} }) {
+            push @{ $bycap{$cap} }, $n->{ref};
+        }
+    }
+
+    my %edges;
+    for my $n (@$nodes) {
+        my @out;
+        my %seen;
+        for my $req (@{ $n->{requires} }) {
+            next if !restartcausing($req);
+            my @from = @{ $bycap{ $req->{name} } // [] };
+            # A node satisfies its own name AS A REF (section 11.1),
+            # canonically - exactly what `providersof` does at runtime.
+            # `canon` hands back a name no ref could have unchanged, and
+            # no instance ref can equal one, so it is the tolerant test.
+            my $asref = canon($req->{name});
+            push @from, $asref
+                if $isref{$asref} && !grep { $_ eq $asref } @from;
+            for my $p (@from) {
+                next if $p eq $n->{ref} || $seen{$p}++;
+                push @out, $p;
+            }
+        }
+        $edges{ $n->{ref} } = [ sortstrings(@out) ];
+    }
+
+    # Iterative DFS with an explicit stack: twenty ports, and several of
+    # them have no recursion budget worth relying on.
+    my ($WHITE, $GREY, $BLACK) = (0, 1, 2);
+    my %colour = map { $_->{ref} => $WHITE } @$nodes;
+
+    for my $start (sortedkeys(\%edges)) {
+        next if $colour{$start} != $WHITE;
+
+        my @path = ($start);
+        my @stack = ([ $start, 0 ]);
+        $colour{$start} = $GREY;
+
+        while (@stack) {
+            my $top = $stack[-1];
+            if ($top->[1] >= scalar @{ $edges{ $top->[0] } }) {
+                $colour{ $top->[0] } = $BLACK;
+                pop @stack;
+                pop @path;
+                next;
+            }
+            my $nxt = $edges{ $top->[0] }[ $top->[1] ];
+            $top->[1]++;
+            if ($colour{$nxt} == $GREY) {
+                # Report the cycle itself, not the walk that found it.
+                my $at = 0;
+                $at++ while $at < @path && $path[$at] ne $nxt;
+                return [ @path[ $at .. $#path ], $nxt ];
+            }
+            next if $colour{$nxt} == $BLACK;
+
+            $colour{$nxt} = $GREY;
+            push @path, $nxt;
+            push @stack, [ $nxt, 0 ];
+        }
+    }
+    return undef;
+}
+
+# Raise on a cycle, naming it. Separate from the detector so the detector
+# stays pure and corpus-testable.
+sub checkcycle {
+    my ($nodes) = @_;
+    my $cycle = dependencycycle($nodes);
+    return if !defined $cycle;
+
+    fail_with('plugin_dependency_cycle',
+              'requirements cycle: ' . join(' -> ', @$cycle),
+              { cycle => $cycle });
+}
+
+1;

package/project/.sdk/tm/perl/feature/secrets/plugin/Voxgig/Plugin/Env.pm

@@ -0,0 +1,176 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Env.pm)
+# 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::Env;
+
+# 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.
+
+use strict;
+use warnings;
+use sort 'stable';
+use JSON::PP ();
+use Scalar::Util qw(looks_like_number);
+use Voxgig::Plugin::Types qw(fail_with ismap jsontype sortstrings sortedkeys stable_sort_by);
+use Voxgig::Plugin::Ref qw(canon_ref refname);
+
+use Exporter 'import';
+our @EXPORT_OK = qw(apply_env encode_ref);
+
+our $ENV_PREFIX = 'VOXGIG_PLUGIN_';
+
+# `retry$fast` -> `RETRY__FAST`.
+sub encode_ref {
+    my ($ref) = @_;
+    my $out = $ref;
+    $out =~ s/\$/__/g;
+    $out =~ s/\./_/g;
+    return uc $out;
+}
+
+sub apply_env {
+    my ($input) = @_;
+    $input //= {};
+    my $env = $input->{env} // {};
+    my @refs = map { canon_ref($_) } @{ $input->{refs} // [] };
+    my $reserved = $input->{reserved} // [];
+    my $out = { options => {}, active => [], inactive => [] };
+
+    # 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.
+    my %byencoded;
+    push @{ $byencoded{ encode_ref($_) } }, $_ for @refs;
+    for my $e (sortedkeys(\%byencoded)) {
+        next if 1 >= @{ $byencoded{$e} };
+        my @pair = sortstrings(@{ $byencoded{$e} });
+        fail_with('plugin_env_ambiguous',
+                  "refs collide in the environment encoding as $e: "
+                  . join(', ', @pair),
+                  { encoded => $e, refs => \@pair });
+    }
+
+    # Longest encoded ref first, so `retry$fast` wins over `retry` on
+    # `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+    my $encoded = stable_sort_by([ sortedkeys(\%byencoded) ],
+        sub { [ -length $_[0] ] });
+
+    for my $key (sortedkeys($env)) {
+        next if 0 != index($key, $ENV_PREFIX);
+
+        my $rest = substr($key, length $ENV_PREFIX);
+
+        if ('PROFILE' eq $rest) {
+            $out->{profile} = $env->{$key};
+            next;
+        }
+
+        if ('ACTIVE' eq $rest || 'INACTIVE' eq $rest) {
+            for my $raw (env_split($env->{$key})) {
+                my $ref = canon_ref($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.
+                env_checkreserved($ref, $reserved);
+                push @{ $out->{ 'ACTIVE' eq $rest ? 'active' : 'inactive' } },
+                    $ref;
+            }
+            next;
+        }
+
+        my $enc;
+        for my $e (@$encoded) {
+            if ($rest eq $e || 0 == index($rest, $e . '_')) { $enc = $e; last }
+        }
+        next if !defined $enc;          # not for any ref this host holds
+
+        my $ref = $byencoded{$enc}[0];
+        env_checkreserved($ref, $reserved);
+
+        next if $rest eq $enc;          # a ref with no path sets nothing
+
+        my @path = split /_/, lc substr($rest, length($enc) + 1);
+
+        my $node = $out->{options};
+        $node->{$ref} = {} if !ismap($node->{$ref});
+        $node = $node->{$ref};
+        for my $step (@path[ 0 .. $#path - 1 ]) {
+            $node->{$step} = {} if !ismap($node->{$step});
+            $node = $node->{$step};
+        }
+        $node->{ $path[-1] } = env_parsevalue($env->{$key});
+    }
+
+    return $out;
+}
+
+sub env_split {
+    my ($value) = @_;
+    my @out;
+    for my $part (split /,/, defined $value ? "$value" : '') {
+        $part =~ s/\A\s+//;
+        $part =~ s/\s+\z//;
+        push @out, $part if '' ne $part;
+    }
+    return @out;
+}
+
+sub env_checkreserved {
+    my ($ref, $reserved) = @_;
+    return if !@$reserved;
+    my $name = refname($ref);
+    return if !grep { $_ eq $name } @$reserved;
+
+    fail_with('plugin_ref_reserved', "ref is reserved by the host: $ref",
+              { ref => $ref });
+}
+
+# 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.
+#
+# JSON::PP is CORE (since 5.14), so this is not a third-party dependency
+# any more than ruby's `json` is; `allow_nonref` is what admits a bare
+# scalar at the top level, which RFC 7159 does and JSON::PP's default
+# constructor does not.
+sub env_parsevalue {
+    my ($value) = @_;
+    return $value if ref $value;
+    my $parsed = eval {
+        JSON::PP->new->allow_nonref->decode(defined $value ? $value : '')
+    };
+    return $value if $@;
+
+    # A JSON INTEGER WIDER THAN PERL'S IV COMES BACK AS A STRING. JSON::PP
+    # cannot hold `922337203685477580812345` in an IV or an NV without
+    # loss, so it hands back the digits as a plain scalar - and `jsontype`
+    # then reads `str` where the canonical's `JSON.parse` publishes a
+    # number. Numify it: javascript loses the same precision at 2**53 and
+    # still calls the result a number, so this agrees with the canonical
+    # on the TYPE, which is what the ladder and every capability
+    # comparison actually read.
+    if ('str' eq jsontype($parsed) && $value =~ /\A\s*-?[0-9]/ && looks_like_number($value)) {
+        return 0 + $parsed;
+    }
+    return $parsed;
+}
+
+1;

package/project/.sdk/tm/perl/feature/secrets/plugin/Voxgig/Plugin/Export.pm

@@ -0,0 +1,59 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Export.pm)
+# 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::Export;
+
+# 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.
+
+use strict;
+use warnings;
+use Voxgig::Plugin::Types qw(fail_with sortstrings);
+use Voxgig::Plugin::Ref qw(canon parse_ref refname);
+
+use Exporter 'import';
+our @EXPORT_OK = qw(resolve_export);
+
+sub resolve_export {
+    my ($spec, $exported) = @_;
+    my $cut = index($spec, '/');
+    fail_with('plugin_export_ambiguous', "export spec needs a key: $spec",
+              { spec => $spec })
+        if $cut < 0;
+    my $head = substr($spec, 0, $cut);
+    my $key  = substr($spec, $cut + 1);
+
+    # A fully qualified ref: exactly one answer or none.
+    my $want = canon($head);
+    for my $e (@$exported) {
+        return $e->{value} if $e->{ref} eq $want && $e->{key} eq $key;
+    }
+
+    # An alias: the name, not a ref. Look at every instance of it.
+    my @byname = grep { refname($_->{ref}) eq $head && $_->{key} eq $key }
+        @$exported;
+    return undef if !@byname;
+
+    for my $e (@byname) {
+        return $e->{value} if '' eq parse_ref($e->{ref})->{tag};
+    }
+
+    return $byname[0]{value} if 1 == @byname;
+
+    my @refs = sortstrings(map { $_->{ref} } @byname);
+    fail_with('plugin_export_ambiguous',
+              "alias $spec matches " . scalar(@refs) . ' instances: '
+              . join(', ', @refs),
+              { spec => $spec, refs => \@refs });
+}
+
+1;

package/project/.sdk/tm/perl/feature/secrets/plugin/Voxgig/Plugin/Graph.pm

@@ -0,0 +1,157 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Graph.pm)
+# 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::Graph;
+
+# 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.
+#
+# `resolve_graph` 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.
+
+use strict;
+use warnings;
+use Voxgig::Plugin::Types qw(truthy sortstrings sortedkeys);
+use Voxgig::Plugin::Ref qw(canon);
+use Voxgig::Plugin::Capability qw(resolve_capability matchvalue);
+use Voxgig::Plugin::Version qw(satisfiesq);
+
+use Exporter 'import';
+our @EXPORT_OK = qw(resolve_graph);
+
+sub resolve_graph {
+    my ($nodes) = @_;
+    my %byref = map { $_->{ref} => $_ } @$nodes;
+
+    my %resolved;
+    my %blocked;
+
+    # 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.
+    my $moved = 1;
+    while ($moved) {
+        $moved = 0;
+        for my $n (@$nodes) {
+            next if $resolved{ $n->{ref} };
+            next if defined firstunmet($n, \%byref, \%resolved);
+            $resolved{ $n->{ref} } = 1;
+            $moved = 1;
+        }
+    }
+
+    for my $n (@$nodes) {
+        next if $resolved{ $n->{ref} };
+        my $why = firstunmet($n, \%byref, \%resolved);
+        $blocked{ $n->{ref} } = $why if defined $why;
+    }
+
+    return {
+        resolved => [ sortedkeys(\%resolved) ],
+        blocked  => [ map { $blocked{$_} } sortedkeys(\%blocked) ],
+    };
+}
+
+# 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.
+sub firstunmet {
+    my ($node, $byref, $resolved) = @_;
+    for my $req (@{ $node->{requires} // [] }) {
+        next if truthy($req->{optional});
+
+        my $all = graph_candidates($byref, $req->{name});
+        if (!@$all) {
+            return { ref => $node->{ref}, unmet => $req->{name},
+                     why => { kind => 'absent' } };
+        }
+
+        my $ok = resolve_capability($req, $all);
+        if (@$ok) {
+            # 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".
+            next if grep { $resolved->{ $_->{ref} } } @$ok;
+
+            return { ref => $node->{ref}, unmet => $req->{name},
+                     why => { kind => 'blocked',
+                              chain => [ sortstrings(map { $_->{ref} } @$ok) ] } };
+        }
+
+        # Providers exist and none matched. Say which test failed.
+        if (defined $req->{range}) {
+            my @versions;
+            for my $c (@$all) {
+                my $have = $c->{provides}{version};
+                push @versions, (defined $have ? $have : '(none)')
+                    if !defined $have || !satisfiesq($have, $req->{range});
+            }
+            if (@versions) {
+                return { ref => $node->{ref}, unmet => $req->{name},
+                         why => { kind => 'version', range => $req->{range},
+                                  found => [ sortstrings(@versions) ] } };
+            }
+        }
+
+        if (defined $req->{match}) {
+            for my $c (@$all) {
+                my $attrs = $c->{provides}{attrs} // {};
+                for my $k (sortedkeys($req->{match})) {
+                    next if exists $attrs->{$k}
+                        && matchvalue($req->{match}{$k}, $attrs->{$k});
+
+                    return { ref => $node->{ref}, unmet => $req->{name},
+                             why => { kind => 'match', failing => $k,
+                                      want => $req->{match}{$k},
+                                      found => $attrs->{$k} } };
+                }
+            }
+        }
+
+        return { ref => $node->{ref}, unmet => $req->{name},
+                 why => { kind => 'absent' } };
+    }
+    return undef;
+}
+
+sub graph_candidates {
+    my ($byref, $name) = @_;
+    my @out;
+    # 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.
+    my $asref = canon($name);
+    for my $ref (sortedkeys($byref)) {
+        my $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 eq $asref) {
+            push @out, { ref => $node->{ref}, pos => $node->{pos} // 0,
+                         provides => { name => $name } };
+            next;
+        }
+        for my $prov (@{ $node->{provides} // [] }) {
+            next if ($prov->{name} // '') ne $name;
+            push @out, { ref => $node->{ref}, pos => $node->{pos} // 0,
+                         provides => $prov };
+        }
+    }
+    return \@out;
+}
+
+1;