@voxgig/sdkgen 4.9.0 → 4.10.0

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

@@ -0,0 +1,187 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Order.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::Order;
+
+# 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.
+
+use strict;
+use warnings;
+use sort 'stable';
+use Voxgig::Plugin::Types qw(fail_with jsontype ismap islist sortedkeys stable_sort_by);
+use Voxgig::Plugin::Ref qw(refname);
+
+use Exporter 'import';
+our @EXPORT_OK = qw(resolve_order order_band order_declared order_targets applypin);
+
+sub resolve_order {
+    my ($bindings, $pin) = @_;
+    my @nodes = @$bindings;
+    my %byref = map { $_->{ref} => $_ } @nodes;
+
+    # 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.
+    my %edges = map { $_->{ref} => [] } @nodes;
+
+    for my $b (@nodes) {
+        my $block = ismap($b->{order}) ? $b->{order} : {};
+        # An ABSENT constraint and an EMPTY LIST are both "no constraint".
+        if (order_declared($block->{after})) {
+            push @{ $edges{$_} }, $b->{ref}
+                for @{ order_targets($block->{after}, \@nodes) };
+        }
+        if (order_declared($block->{before})) {
+            push @{ $edges{ $b->{ref} } }, @{ order_targets($block->{before}, \@nodes) };
+        }
+    }
+
+    # 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`.
+    my %indeg = map { $_->{ref} => 0 } @nodes;
+    for my $tos (values %edges) {
+        $indeg{$_}++ for @$tos;
+    }
+
+    my @out;
+    my $ready = [ grep { 0 == $indeg{ $_->{ref} } } @nodes ];
+
+    while (@$ready) {
+        $ready = stable_sort_by($ready,
+            sub { [ order_band($_[0]), $_[0]->{pos} // 0 ] });
+        my $nxt = shift @$ready;
+        push @out, $nxt->{ref};
+        for my $to (@{ $edges{ $nxt->{ref} } }) {
+            $indeg{$to}--;
+            push @$ready, $byref{$to} if 0 == $indeg{$to};
+        }
+    }
+
+    if (@out != @nodes) {
+        my %placed = map { $_ => 1 } @out;
+        my @stuck = map { $_->{ref} } grep { !$placed{ $_->{ref} } } @nodes;
+        fail_with('plugin_order_cycle',
+                  'before/after constraints cycle: ' . join(' -> ', @stuck),
+                  { cycle => \@stuck });
+    }
+
+    return applypin(\@out, \%edges, $pin);
+}
+
+sub order_band {
+    my ($binding) = @_;
+    my $block = ismap($binding->{order}) ? $binding->{order} : {};
+    my $value = $block->{band};
+    # A JSON number, not a numeric string and not a boolean: perl would read
+    # `"3"` and `!!1` as 3 and 1 in arithmetic, and section 7's band is an
+    # integer the document wrote as one.
+    return 'num' eq jsontype($value) ? int($value) : 0;
+}
+
+# Was a constraint stated? An absent value and an EMPTY LIST are both
+# no-constraint - and an empty list is TRUE in ruby and FALSE in php, which
+# is exactly why this tests the spelling rather than the truth of it.
+sub order_declared {
+    my ($spec) = @_;
+    return 0 if !defined $spec;
+    if (islist($spec)) {
+        return (grep { '' ne $_ } @$spec) ? 1 : 0;
+    }
+    return '' ne $spec ? 1 : 0;
+}
+
+# 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.
+sub order_targets {
+    my ($spec, $nodes) = @_;
+    my @specs = islist($spec) ? @$spec : ($spec);
+    my @hit;
+    my %seen;
+    for my $one (@specs) {
+        for my $b (@$nodes) {
+            next if $seen{ $b->{ref} };
+            if ($b->{ref} eq $one || refname($b->{ref}) eq $one) {
+                $seen{ $b->{ref} } = 1;
+                push @hit, $b->{ref};
+            }
+        }
+    }
+    return \@hit;
+}
+
+# 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.
+sub applypin {
+    my ($order, $edges, $pin) = @_;
+    return $order if !defined $pin;
+
+    my @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 perl hash has no
+    # order at all, which makes leaving it unstated worse here than
+    # anywhere else.
+    for my $name (sortedkeys($pin)) {
+        my $want = $pin->{$name};
+        my $idx;
+        for my $i (0 .. $#out) {
+            if (refname($out[$i]) eq $name) { $idx = $i; last }
+        }
+        next if !defined $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.
+        my $wantfirst = ('first' eq $want || 'outermost' eq $want) ? 1 : 0;
+        my ($ref) = splice(@out, $idx, 1);
+        if ($wantfirst) { unshift @out, $ref } else { push @out, $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.
+    my %at;
+    $at{ $out[$_] } = $_ for 0 .. $#out;
+    for my $from (sortedkeys($edges)) {
+        for my $to (@{ $edges->{$from} }) {
+            next if $at{$from} <= $at{$to};
+            fail_with('plugin_order_pinned',
+                      'a pin would move a binding an ordering constrains: '
+                      . "$from must precede $to",
+                      { before => $from, after => $to });
+        }
+    }
+
+    return \@out;
+}
+
+1;

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

@@ -0,0 +1,100 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Point.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::Point;
+
+# 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.
+
+use strict;
+use warnings;
+use sort 'stable';
+use Voxgig::Plugin::Types qw(fail_with truthy sortstrings stable_sort_by);
+
+use Exporter 'import';
+our @EXPORT_OK = qw(point_emit compose point_provider);
+
+# 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.
+our @MODES = qw(emit parallel serial bail);
+
+# Fan-out. Return values are ignored except in `bail`.
+sub point_emit {
+    my ($bindings, $mode, $arg) = @_;
+
+    if ('bail' eq $mode) {
+        # Stops at the first binding that RETURNS A VALUE - the "handled,
+        # stop" case. An UNDEF RETURN DECLINES (section 6.1): perl has one
+        # way to say nothing, and the model's rule is written to that
+        # rather than to JavaScript's null/undefined pair. `defined`, NOT
+        # truth - `0`, `""` and `false` are values.
+        for my $b (@$bindings) {
+            my $v = $b->{fn}->($arg);
+            return $v if defined $v;
+        }
+        return undef;
+    }
+
+    my @errors;
+    for my $b (@$bindings) {
+        my $ok = eval { $b->{fn}->($arg); 1 };
+        next if $ok;
+        my $err = $@;
+        # `emit` raises synchronously; the collecting modes gather.
+        die $err if 'emit' eq $mode;
+        push @errors, $err;
+    }
+    return 'emit' eq $mode ? undef : \@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.
+sub compose {
+    my ($bindings, $base) = @_;
+    my $nxt = $base;
+    for (my $i = $#$bindings; $i >= 0; $i--) {
+        # Fresh lexicals per iteration, so each layer closes over its own
+        # pair - perl gives that for free where ruby's blocks do not.
+        my $fn = $bindings->[$i]{fn};
+        my $inner = $nxt;
+        $nxt = sub { return $fn->($inner, @_) };
+    }
+    return $nxt;
+}
+
+# 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.
+sub point_provider {
+    my ($bindings, $spec) = @_;
+    return { winner => undef, shadowed => [] } if !@$bindings;
+
+    if (truthy($spec->{exclusive}) && 1 < @$bindings) {
+        my @refs = sortstrings(map { $_->{ref} } @$bindings);
+        fail_with('plugin_point_exclusive',
+                  'point is exclusive and has ' . scalar(@$bindings)
+                  . ' bindings: ' . join(', ', @refs),
+                  { refs => \@refs });
+    }
+
+    my $ranked = stable_sort_by($bindings,
+        sub { [ -$_[0]->{band}, $_[0]->{ref} ] });
+    return { winner => $ranked->[0],
+             shadowed => [ map { $_->{ref} } @{$ranked}[1 .. $#$ranked] ] };
+}
+
+1;

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

@@ -0,0 +1,119 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Ref.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::Ref;
+
+# 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.
+
+use strict;
+use warnings;
+use Voxgig::Plugin::Types qw(fail_with jsontype);
+
+use Exporter 'import';
+our @EXPORT_OK = qw(check_name check_tag parse_ref format_ref canon_ref canon refname);
+
+# Section 4: `^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`, max 1024.
+#
+# \A and \z, NOT ^ and $. Perl's `$` matches BEFORE A TRAILING NEWLINE, so
+# a `^...$` spelling admits "stripe\n" as a name - the same hole the ruby
+# port surfaced in python, and the reason four `#trailing-newline` entries
+# exist.
+our $NAME_RE = qr/\A[a-zA-Z\@][a-zA-Z0-9.~_\-\/]*\z/;
+
+# 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.
+our $TAG_RE = qr/\A[a-zA-Z0-9.~_-]+\z/;
+
+our $REF_MAX = 1024;
+
+sub check_name {
+    my ($name) = @_;
+    return !!0 if 'str' ne jsontype($name);
+    return !!0 if '' eq $name || $REF_MAX < length $name;
+    return $name =~ $NAME_RE ? !!1 : !!0;
+}
+
+sub check_tag {
+    my ($tag) = @_;
+    return !!0 if 'str' ne jsontype($tag);
+    # The empty tag is an ordinary tag (section 4 rule 2). The
+    # single-instance case writes no tag and never learns tags exist.
+    return !!1 if '' eq $tag;
+    return !!0 if $REF_MAX < length $tag;
+    return $tag =~ $TAG_RE ? !!1 : !!0;
+}
+
+# `name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both give
+# tag ''.
+sub parse_ref {
+    my ($str) = @_;
+    fail_with('plugin_bad_name', 'ref must be a string')
+        if 'str' ne jsontype($str);
+
+    # 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.
+    my $cut = index($str, '$');
+    my $name = $cut < 0 ? $str : substr($str, 0, $cut);
+    my $tag  = $cut < 0 ? ''   : substr($str, $cut + 1);
+
+    fail_with('plugin_bad_name', "invalid plugin name: $name", { name => $name })
+        if !check_name($name);
+    fail_with('plugin_bad_tag', "invalid plugin tag: $tag",
+              { name => $name, tag => $tag })
+        if !check_tag($tag);
+
+    return { name => $name, tag => $tag };
+}
+
+# The pair -> `name$tag`. An empty tag NEVER writes the separator, which is
+# the half of canonicalization format_ref owns: parse tolerates `stripe$`,
+# format never produces it, so a round trip is idempotent.
+sub format_ref {
+    my ($name, $tag) = @_;
+    $tag = '' if !defined $tag;
+    if (!check_name($name)) {
+        my $shown = defined $name && !ref $name ? $name : '(not a name)';
+        fail_with('plugin_bad_name', "invalid plugin name: $shown",
+                  { name => $name });
+    }
+    if (!check_tag($tag)) {
+        my $shown = defined $tag && !ref $tag ? $tag : '(not a tag)';
+        fail_with('plugin_bad_tag', "invalid plugin tag: $shown",
+                  { name => $name, tag => $tag });
+    }
+    return '' eq $tag ? $name : "$name\$$tag";
+}
+
+# The canonical spelling of a ref. Section 4 rule 5: ports must
+# canonicalize before comparison.
+sub canon_ref {
+    my ($str) = @_;
+    my $r = parse_ref($str);
+    return format_ref($r->{name}, $r->{tag});
+}
+
+# canon_ref 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.
+sub canon {
+    my ($str) = @_;
+    my $out = eval { canon_ref($str) };
+    return defined $out ? $out : $str;
+}
+
+sub refname {
+    my ($str) = @_;
+    my $out = eval { parse_ref($str)->{name} };
+    return defined $out ? $out : $str;
+}
+
+1;

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

@@ -0,0 +1,71 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Resolve.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::Resolve;
+
+# 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.
+
+use strict;
+use warnings;
+
+use Exporter 'import';
+our @EXPORT_OK = qw(resolve_candidates resolve_from);
+
+our @DEFAULT_SOURCES = (
+    { kind => 'module',
+      prefix => [ '@voxgig/plugin-', 'voxgig-plugin-', 'plugin-', '' ] },
+);
+
+sub resolve_candidates {
+    my ($name, $sources) = @_;
+    my @out;
+    my %seen;
+
+    # 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.
+    return [$name] if 0 == index($name, '@');
+
+    my $list = (!defined $sources || 0 == @$sources)
+        ? \@DEFAULT_SOURCES : $sources;
+
+    for my $src (@$list) {
+        my $kind = $src->{kind} // '';
+        if ('module' eq $kind) {
+            my $prefixes = $src->{prefix};
+            $prefixes = [''] if !defined $prefixes || 0 == @$prefixes;
+            for my $p (@$prefixes) {
+                my $id = $p . $name;
+                next if $seen{$id}++;
+                push @out, $id;
+            }
+        }
+        elsif ('path' eq $kind) {
+            my $dir = $src->{dir} // '';
+            $dir =~ s{/+\z}{};
+            my $id = "$dir/$name";
+            next if $seen{$id}++;
+            push @out, $id;
+        }
+    }
+
+    return \@out;
+}
+
+# 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.
+sub resolve_from {
+    my ($from) = @_;
+    return [$from];
+}
+
+1;