@voxgig/sdkgen 4.8.2 → 4.8.3

package/project/.sdk/tm/go/feature/secrets/plugin/order.go

@@ -0,0 +1,248 @@
+// VENDORED: @voxgig/plugin 0.1.6 (go/plugin/order.go)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* Ordering (§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. */
+
+package plugin
+
+import (
+	"sort"
+	"strings"
+)
+
+type Binding struct {
+	Ref   string      `json:"ref"`
+	Pos   int         `json:"pos"`
+	Order *OrderBlock `json:"order,omitempty"`
+}
+
+// Pin is where a host has pinned a binding. Positional, not ordinal:
+// §6.2 composes b1(b2(b3(base))) with the FIRST binding OUTERMOST, so
+// `first` and `innermost` are opposites, and a pin spelled in sort terms
+// would be read backwards by exactly the people it protects.
+type Pin map[string]string
+
+func ResolveOrder(bindings []Binding, pin Pin) ([]string, error) {
+	nodes := append([]Binding{}, bindings...)
+	byref := map[string]Binding{}
+	for _, b := range nodes {
+		byref[b.Ref] = b
+	}
+
+	// Constraints are edges. A constraint naming an ABSENT binding is
+	// satisfied VACUOUSLY (§7) — a plugin ordered `after: 'test'` must
+	// load in a host with no test plugin. That is sdkgen's __after__
+	// behaviour, kept.
+	edges := map[string][]string{}
+	for _, b := range nodes {
+		edges[b.Ref] = []string{}
+	}
+
+	for _, b := range nodes {
+		if nil == b.Order {
+			continue
+		}
+		// An ABSENT constraint and an EMPTY LIST are both "no constraint".
+		if declared(b.Order.After) {
+			for _, t := range targets(b.Order.After, nodes) {
+				edges[t] = append(edges[t], b.Ref)
+			}
+		}
+		if declared(b.Order.Before) {
+			for _, t := range targets(b.Order.Before, nodes) {
+				edges[b.Ref] = append(edges[b.Ref], t)
+			}
+		}
+	}
+
+	// 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`.
+	indeg := map[string]int{}
+	for _, b := range nodes {
+		indeg[b.Ref] = 0
+	}
+	for _, from := range sortedkeys(edges) {
+		for _, to := range edges[from] {
+			indeg[to] = indeg[to] + 1
+		}
+	}
+
+	out := []string{}
+	ready := []Binding{}
+	for _, b := range nodes {
+		if 0 == indeg[b.Ref] {
+			ready = append(ready, b)
+		}
+	}
+
+	for 0 < len(ready) {
+		sort.SliceStable(ready, rankless(ready))
+		next := ready[0]
+		ready = ready[1:]
+		out = append(out, next.Ref)
+		for _, to := range edges[next.Ref] {
+			indeg[to] = indeg[to] - 1
+			if 0 == indeg[to] {
+				ready = append(ready, byref[to])
+			}
+		}
+	}
+
+	if len(out) != len(nodes) {
+		stuck := []string{}
+		for _, b := range nodes {
+			if !hasstring(out, b.Ref) {
+				stuck = append(stuck, b.Ref)
+			}
+		}
+		return nil, Fail("plugin_order_cycle",
+			"before/after constraints cycle: "+strings.Join(stuck, " -> "),
+			map[string]any{"cycle": stuck})
+	}
+
+	return applypin(out, edges, pin)
+}
+
+func rankless(l []Binding) func(i, j int) bool {
+	return func(i, j int) bool {
+		a, b := l[i], l[j]
+		if ab, bb := band(a), band(b); ab != bb {
+			return ab < bb
+		}
+		return a.Pos < b.Pos
+	}
+}
+
+func band(b Binding) int {
+	if nil == b.Order || nil == b.Order.Band {
+		return 0
+	}
+	return *b.Order.Band
+}
+
+// targets: matching is by REF, or by NAME across all of that
+// definition's instances (§7) — which is the whole reason the two
+// spellings exist.
+func targets(spec OrderRef, nodes []Binding) []string {
+	hit := []string{}
+	// A list fans out to the UNION of what each spelling names, so
+	// `after: ['a','b']` means after BOTH, and the same instance named
+	// twice - once by name, once by ref - is one edge, not two.
+	for _, one := range spec.list {
+		for _, b := range nodes {
+			if seen(hit, b.Ref) {
+				continue
+			}
+			if b.Ref == one {
+				hit = append(hit, b.Ref)
+				continue
+			}
+			if refname(b.Ref) == one {
+				hit = append(hit, b.Ref)
+			}
+		}
+	}
+	return hit
+}
+
+// declared: was a constraint actually stated? An empty list is not one.
+func declared(spec OrderRef) bool {
+	for _, one := range spec.list {
+		if "" != one {
+			return true
+		}
+	}
+	return false
+}
+
+func seen(hit []string, ref string) bool {
+	for _, h := range hit {
+		if h == ref {
+			return true
+		}
+	}
+	return false
+}
+
+/* A PIN IS NOT A CONSTRAINT (§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. Station's transport adapter must sit immediately
+ * outside the base transport; an `order` list that moves it has to be an
+ * error rather than a preference. */
+func applypin(order []string, edges map[string][]string, pin Pin) ([]string, error) {
+	if nil == pin {
+		return order, nil
+	}
+	out := append([]string{}, order...)
+
+	for _, name := range sortedkeys(pin) {
+		want := pin[name]
+		idx := -1
+		for i, r := range out {
+			if refname(r) == name {
+				idx = i
+				break
+			}
+		}
+		if -1 == idx {
+			continue
+		}
+
+		// `first`/`outermost` is index 0; `last`/`innermost` is the end.
+		// §6.2 makes the first chain binding outermost, which is why the
+		// vocabulary is positional and why the two spellings pair this
+		// way.
+		wantfirst := "first" == want || "outermost" == want
+		ref := out[idx]
+		out = append(out[:idx], out[idx+1:]...)
+		if wantfirst {
+			out = append([]string{ref}, out...)
+		} else {
+			out = append(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.
+	at := map[string]int{}
+	for i, r := range out {
+		at[r] = i
+	}
+	for _, from := range sortedkeys(edges) {
+		for _, to := range edges[from] {
+			if at[from] > at[to] {
+				return nil, Fail("plugin_order_pinned",
+					"a pin would move a binding an ordering constrains: "+
+						from+" must precede "+to,
+					map[string]any{"before": from, "after": to})
+			}
+		}
+	}
+
+	return out, nil
+}

package/project/.sdk/tm/go/feature/secrets/plugin/point.go

@@ -0,0 +1,184 @@
+// VENDORED: @voxgig/plugin 0.1.6 (go/plugin/point.go)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* Extension points (§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. */
+
+package plugin
+
+import "sort"
+
+type Kind string
+
+const (
+	KindHook     Kind = "hook"
+	KindChain    Kind = "chain"
+	KindProvider Kind = "provider"
+)
+
+// Mode is §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.
+type Mode string
+
+const (
+	ModeEmit     Mode = "emit"
+	ModeParallel Mode = "parallel"
+	ModeSerial   Mode = "serial"
+	ModeBail     Mode = "bail"
+)
+
+/* BindFn IS ONE TYPE FOR ALL THREE KINDS, AND THAT IS A PORT DECISION
+ * WORTH STATING.
+ *
+ * The canonical calls `fn(arg)` for a hook, `fn(next, ...args)` for a
+ * chain and `fn(...args)` for a provider — three arities on one
+ * untyped slot. Go could give each kind its own func type, but then
+ * `bind` needs three spellings and a probe that binds the same
+ * function to a hook point in one corpus entry and a provider point in
+ * the next (which `point/bail` and `point/provider` do, with the same
+ * `provider` probe) could not be written at all.
+ *
+ * So one variadic signature carries all three, and a chain's `next` is
+ * simply its first argument — exactly as in the canonical.
+ *
+ * A BINDING CANNOT RAISE IN GO. It RETURNS an error value instead, and
+ * §6.1's collecting modes gather those. */
+type BindFn func(args ...any) any
+
+type Spec struct {
+	Kind Kind `json:"kind,omitempty"`
+	Mode Mode `json:"mode,omitempty"`
+	// Base is `chain` only: the host owns the base, and a plugin cannot
+	// replace it (§6.2). One that wants to SUBSTITUTE rather than wrap
+	// binds innermost and simply does not call `next`.
+	Base BindFn `json:"-"`
+	// Exclusive is `provider` only: a second binding is an error rather
+	// than a shadow.
+	Exclusive bool `json:"exclusive,omitempty"`
+	// Default is `provider` only: the host's fallback.
+	Default any `json:"default,omitempty"`
+	Pin     Pin `json:"pin,omitempty"`
+}
+
+type Bound struct {
+	Ref   string
+	Point string
+	Fn    BindFn
+	// Band: `provider` ranks by HIGHEST band, unlike hook and chain
+	// which run lowest first. Kept as declared so the two rules stay
+	// visibly different rather than one being derived from the other by
+	// a reader who then gets it backwards.
+	Band int
+}
+
+// Emit is fan-out. Return values are ignored except in `bail`.
+//
+// The second return is the canonical's synchronous throw under
+// `mode: emit`; the first is the collected error list under the
+// gathering modes, and the bailing value under `bail`.
+func Emit(bindings []Bound, mode Mode, arg any) (any, error) {
+	if ModeBail == mode {
+		// Stops at the first binding that RETURNS A VALUE — the
+		// "handled, stop" case. A NIL RETURN DECLINES (§6.1): go has one
+		// way to say nothing, and the model's rule is written to that
+		// rather than to JavaScript's null/undefined pair.
+		for _, b := range bindings {
+			if v := b.Fn(arg); nil != v {
+				if err, bad := v.(error); bad {
+					return nil, err
+				}
+				return v, nil
+			}
+		}
+		return nil, nil
+	}
+
+	errors := []any{}
+	for _, b := range bindings {
+		v := b.Fn(arg)
+		err, bad := v.(error)
+		if !bad {
+			continue
+		}
+		// `emit` raises synchronously; the collecting modes gather.
+		if ModeEmit == mode {
+			return nil, err
+		}
+		errors = append(errors, err)
+	}
+	if ModeEmit == mode {
+		return nil, nil
+	}
+	return errors, nil
+}
+
+// Compose is b1(b2(b3(base))), FIRST BINDING OUTERMOST (§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.
+func Compose(bindings []Bound, base BindFn) BindFn {
+	next := base
+	for i := len(bindings) - 1; 0 <= i; i-- {
+		fn := bindings[i].Fn
+		inner := next
+		next = func(args ...any) any {
+			return fn(append([]any{inner}, args...)...)
+		}
+	}
+	return next
+}
+
+type Picked struct {
+	Winner   *Bound
+	Shadowed []string
+}
+
+// Provider selects at most one live implementation (§6.3). The winner is
+// the highest band, ties broken by ref sort, and THE LOSERS ARE VISIBLE
+// rather than silently ignored.
+func Provider(bindings []Bound, spec Spec) (Picked, error) {
+	if 0 == len(bindings) {
+		return Picked{Shadowed: []string{}}, nil
+	}
+
+	if spec.Exclusive && 1 < len(bindings) {
+		refs := []string{}
+		for _, b := range bindings {
+			refs = append(refs, b.Ref)
+		}
+		sort.Strings(refs)
+		return Picked{}, Fail("plugin_point_exclusive",
+			"point is exclusive and has "+itoa(len(bindings))+" bindings: "+
+				join(refs, ", "),
+			map[string]any{"refs": refs})
+	}
+
+	ranked := append([]Bound{}, bindings...)
+	sort.SliceStable(ranked, func(i, j int) bool {
+		a, b := ranked[i], ranked[j]
+		if a.Band != b.Band {
+			return a.Band > b.Band // HIGHEST band wins
+		}
+		return a.Ref < b.Ref
+	})
+
+	shadowed := []string{}
+	for _, b := range ranked[1:] {
+		shadowed = append(shadowed, b.Ref)
+	}
+	winner := ranked[0]
+	return Picked{Winner: &winner, Shadowed: shadowed}, nil
+}

package/project/.sdk/tm/go/feature/secrets/plugin/ref.go

@@ -0,0 +1,123 @@
+// VENDORED: @voxgig/plugin 0.1.6 (go/plugin/ref.go)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* Identity: name+tag, written `name$tag` (§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. */
+
+package plugin
+
+import (
+	"regexp"
+	"strings"
+)
+
+// §4: `^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`, max 1024.
+var nameRe = regexp.MustCompile(`^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`)
+
+// §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.
+var tagRe = regexp.MustCompile(`^[a-zA-Z0-9.~_-]+$`)
+
+const refMax = 1024
+
+func CheckName(name string) bool {
+	if 0 == len(name) || refMax < len(name) {
+		return false
+	}
+	return nameRe.MatchString(name)
+}
+
+func CheckTag(tag string) bool {
+	// The empty tag is an ordinary tag (§4 rule 2). The single-instance
+	// case writes no tag and never learns tags exist.
+	if 0 == len(tag) {
+		return true
+	}
+	if refMax < len(tag) {
+		return false
+	}
+	return tagRe.MatchString(tag)
+}
+
+// ParseRef turns `name$tag` into the pair. Canonicalizing: `stripe$` and
+// `stripe` both give tag "".
+func ParseRef(str string) (Ref, error) {
+	// Split on the FIRST `$`. Nothing in the grammar decides this — `$`
+	// is in neither character class — so the corpus is the arbiter (§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.
+	name := str
+	tag := ""
+	if cut := strings.Index(str, "$"); -1 != cut {
+		name = str[:cut]
+		tag = str[cut+1:]
+	}
+
+	if !CheckName(name) {
+		return Ref{}, Fail("plugin_bad_name", "invalid plugin name: "+name,
+			map[string]any{"name": name})
+	}
+	if !CheckTag(tag) {
+		return Ref{}, Fail("plugin_bad_tag", "invalid plugin tag: "+tag,
+			map[string]any{"name": name, "tag": tag})
+	}
+
+	return Ref{Name: name, Tag: tag}, nil
+}
+
+// FormatRef turns the pair into `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.
+func FormatRef(name string, tag string) (string, error) {
+	if !CheckName(name) {
+		return "", Fail("plugin_bad_name", "invalid plugin name: "+name,
+			map[string]any{"name": name})
+	}
+	if !CheckTag(tag) {
+		return "", Fail("plugin_bad_tag", "invalid plugin tag: "+tag,
+			map[string]any{"name": name, "tag": tag})
+	}
+	if "" == tag {
+		return name, nil
+	}
+	return name + "$" + tag, nil
+}
+
+// CanonRef is the canonical spelling of a ref. §4 rule 5: ports must
+// canonicalize before comparison.
+func CanonRef(str string) (string, error) {
+	r, err := ParseRef(str)
+	if nil != err {
+		return "", err
+	}
+	return FormatRef(r.Name, r.Tag)
+}
+
+// canon is CanonRef for the many internal callers that have already
+// established the ref is well formed, or that want the input back
+// unchanged when it is not. NEVER use it where a bad ref must be
+// reported — the corpus pins plugin_bad_name at every public entry.
+func canon(str string) string {
+	c, err := CanonRef(str)
+	if nil != err {
+		return str
+	}
+	return c
+}
+
+// refname is the name half, for the internal callers that only compare.
+func refname(str string) string {
+	r, err := ParseRef(str)
+	if nil != err {
+		return str
+	}
+	return r.Name
+}

package/project/.sdk/tm/go/feature/secrets/plugin/resolve.go

@@ -0,0 +1,79 @@
+// VENDORED: @voxgig/plugin 0.1.6 (go/plugin/resolve.go)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* Dynamic resolution (§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 §15.4 puts real module loading in per-port integration tests
+ * rather than here.
+ *
+ * GO IS TIER S (§10.3): static-only, registration through `init()` or
+ * an explicit list handed to MakeHost. That changes nothing here —
+ * candidate generation is what the corpus pins, and a port with no
+ * dynamic loading at all still answers it identically. */
+
+package plugin
+
+import "strings"
+
+type Source struct {
+	Kind   string   `json:"kind"`
+	Prefix []string `json:"prefix,omitempty"`
+	Dir    string   `json:"dir,omitempty"`
+}
+
+func ResolveCandidates(name string, sources []Source) []string {
+	out := []string{}
+
+	// A SCOPED NAME RESOLVES VERBATIM ONLY (§10.2). `@acme/thing` is
+	// already a package id; prefixing it produces
+	// `@voxgig/plugin-@acme/thing`, which is not a thing that can exist.
+	if strings.HasPrefix(name, "@") {
+		return []string{name}
+	}
+
+	list := sources
+	if 0 == len(list) {
+		list = defaultSources
+	}
+
+	for _, src := range list {
+		if "module" == src.Kind {
+			prefixes := src.Prefix
+			if 0 == len(prefixes) {
+				prefixes = []string{""}
+			}
+			for _, p := range prefixes {
+				if id := p + name; !hasstring(out, id) {
+					out = append(out, id)
+				}
+			}
+		} else if "path" == src.Kind {
+			if id := strings.TrimRight(src.Dir, "/") + "/" + name; !hasstring(out, id) {
+				out = append(out, id)
+			}
+		}
+	}
+
+	return out
+}
+
+var defaultSources = []Source{
+	{Kind: "module", Prefix: []string{"@voxgig/plugin-", "voxgig-plugin-", "plugin-", ""}},
+}
+
+// ResolveFrom: A MODULE PATH IS NOT A NAME (§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.
+//
+// Loading from an explicit location is a separate field that bypasses
+// candidate generation entirely: `from` is passed to the resolver
+// verbatim, and a resolver that cannot honour a location raises
+// plugin_resolve_failed.
+func ResolveFrom(from string) []string {
+	return []string{from}
+}