@voxgig/sdkgen 4.8.2 → 4.8.3

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

@@ -0,0 +1,250 @@
+// VENDORED: @voxgig/plugin 0.1.6 (go/plugin/depend.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.
+/* Dependency cardinality, policy, and the restart graph (§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. */
+
+package plugin
+
+import "sort"
+
+// NormRequire: a bare string is shorthand for `{name}`.
+func NormRequire(r any) Required {
+	if s, ok := r.(string); ok {
+		return Required{Name: s}
+	}
+	m := asmap(r)
+	out := Required{
+		Name:   asstring(m["name"], ""),
+		Range:  asstring(m["range"], ""),
+		Policy: asstring(m["policy"], ""),
+	}
+	if v, ok := m["match"].(map[string]any); ok {
+		out.Match = v
+	}
+	out.Optional = asbool(m["optional"], false)
+	return out
+}
+
+/* Requirements are 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 §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, and that is the ordinary case
+ * rather than an exotic one.
+ *
+ * `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". */
+func Requirements(options map[string]any) []Required {
+	raw, _ := aslist(options["requires"])
+	markedraw, _ := aslist(options["optional"])
+	marked := []string{}
+	for _, m := range markedraw {
+		marked = append(marked, asstring(m, ""))
+	}
+	fallback := asstring(options["policy"], "")
+
+	out := []Required{}
+	for _, r := range raw {
+		req := NormRequire(r)
+		if req.Optional || hasstring(marked, req.Name) {
+			req.Optional = true
+		}
+		if "" == req.Policy && "" != fallback {
+			req.Policy = fallback
+		}
+		out = append(out, req)
+	}
+	return out
+}
+
+// RestartsOnLoss: 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: mandatory-dynamic stays live and
+// is notified, optional-dynamic is a notification and nothing else.
+func RestartsOnLoss(r Required) bool {
+	policy := r.Policy
+	if "" == policy {
+		policy = "static"
+	}
+	return "dynamic" != policy
+}
+
+// GatesActivation: 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. Conflating the two would let a plugin that declared it can
+// cope with replacement activate with nothing to call.
+func GatesActivation(r Required) bool {
+	return !r.Optional
+}
+
+/* RestartCausing marks the edges that can cause a restart, which is
+ * exactly the set a cycle must be detected over (§11.3).
+ *
+ * Those are the mandatory requirements AND THE `static` OPTIONAL ONES,
+ * because both make a capability change deactivate and reactivate the
+ * consumer — and a cycle of restarts does not settle: A comes up, B
+ * restarts, which changes B's capability, which restarts A,
+ * indefinitely.
+ *
+ * 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 §11.3 excluded EVERY optional edge and thereby
+ * admitted the non-terminating case it was trying to permit. */
+func RestartCausing(r Required) bool {
+	return GatesActivation(r) || RestartsOnLoss(r)
+}
+
+// DependNode is the requirement graph as plain data, for the pure
+// detector.
+type DependNode struct {
+	Ref      string
+	Provides []string
+	Requires []Required
+}
+
+/* DependencyCycle: 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 (§11.1), which is why the ref is a
+ * provider of itself here. */
+func DependencyCycle(nodes []DependNode) []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 (§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.
+	bycap := map[string][]string{}
+	isref := map[string]bool{}
+	for _, n := range nodes {
+		isref[n.Ref] = true
+		for _, cap := range n.Provides {
+			bycap[cap] = append(bycap[cap], n.Ref)
+		}
+	}
+
+	edges := map[string][]string{}
+	for _, n := range nodes {
+		out := []string{}
+		for _, r := range n.Requires {
+			if !RestartCausing(r) {
+				continue
+			}
+			from := append([]string{}, bycap[r.Name]...)
+			// A node satisfies its own name AS A REF (§11.1),
+			// canonically — exactly what `providersof` does at runtime,
+			// so the load-time graph and the running one agree about
+			// what an edge is. `canon` hands back a name no ref could
+			// have unchanged, and no instance ref can equal one, so it
+			// is the tolerant test this needs.
+			if asref := canon(r.Name); isref[asref] && !hasstring(from, asref) {
+				from = append(from, asref)
+			}
+			for _, p := range from {
+				if p != n.Ref && !hasstring(out, p) {
+					out = append(out, p)
+				}
+			}
+		}
+		sort.Strings(out)
+		edges[n.Ref] = out
+	}
+
+	// Iterative DFS with an explicit stack: twenty ports, and several of
+	// them have no recursion budget worth relying on.
+	const white, grey, black = 0, 1, 2
+	colour := map[string]int{}
+	for _, n := range nodes {
+		colour[n.Ref] = white
+	}
+
+	for _, start := range sortedkeys(edges) {
+		if white != colour[start] {
+			continue
+		}
+		path := []string{start}
+		type frame struct {
+			ref string
+			i   int
+		}
+		stack := []frame{{ref: start, i: 0}}
+		colour[start] = grey
+
+		for 0 < len(stack) {
+			top := &stack[len(stack)-1]
+			if top.i >= len(edges[top.ref]) {
+				colour[top.ref] = black
+				stack = stack[:len(stack)-1]
+				path = path[:len(path)-1]
+				continue
+			}
+			next := edges[top.ref][top.i]
+			top.i++
+			if grey == colour[next] {
+				// Report the cycle itself, not the walk that found it.
+				return append(append([]string{}, path[indexof(path, next):]...), next)
+			}
+			if black == colour[next] {
+				continue
+			}
+			colour[next] = grey
+			path = append(path, next)
+			stack = append(stack, frame{ref: next, i: 0})
+		}
+	}
+	return nil
+}
+
+// CheckCycle raises on a cycle, naming it. Separate from the detector so
+// the detector stays pure and corpus-testable.
+func CheckCycle(nodes []DependNode) error {
+	if cycle := DependencyCycle(nodes); nil != cycle {
+		return Fail("plugin_dependency_cycle",
+			"requirements cycle: "+join(cycle, " -> "),
+			map[string]any{"cycle": cycle})
+	}
+	return nil
+}

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

@@ -0,0 +1,194 @@
+// VENDORED: @voxgig/plugin 0.1.6 (go/plugin/env.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.
+/* Environment overrides (§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`,
+ * as do `Retry$fast` and `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. The affected
+ * pair stays configurable by document and by API, just not by
+ * environment — which is the honest trade.
+ *
+ * Pure: a function over a string map and a ref set. The corpus tests it
+ * without touching a real environment. */
+
+package plugin
+
+import (
+	"encoding/json"
+	"sort"
+	"strings"
+)
+
+const envPrefix = "VOXGIG_PLUGIN_"
+
+type EnvResult struct {
+	Profile  string         `json:"profile,omitempty"`
+	Options  map[string]any `json:"options"`
+	Active   []string       `json:"active"`
+	Inactive []string       `json:"inactive"`
+}
+
+type EnvInput struct {
+	Env map[string]string `json:"env"`
+	// Refs is every ref the host holds. Needed because the encoding is
+	// lossy: without the set there is no way to know where the ref ends
+	// and the path begins in `RETRY__FAST_MIN_DELAY`.
+	Refs     []string `json:"refs,omitempty"`
+	Reserved []string `json:"reserved,omitempty"`
+}
+
+// EncodeRef: `retry$fast` -> `RETRY__FAST`.
+func EncodeRef(ref string) string {
+	s := strings.ReplaceAll(ref, "$", "__")
+	s = strings.ReplaceAll(s, ".", "_")
+	return strings.ToUpper(s)
+}
+
+func ApplyEnv(input EnvInput) (EnvResult, error) {
+	out := EnvResult{Options: map[string]any{}, Active: []string{}, Inactive: []string{}}
+
+	refs := []string{}
+	for _, r := range input.Refs {
+		c, err := CanonRef(r)
+		if nil != err {
+			return out, err
+		}
+		refs = append(refs, c)
+	}
+
+	// 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.
+	byencoded := map[string][]string{}
+	for _, r := range refs {
+		e := EncodeRef(r)
+		byencoded[e] = append(byencoded[e], r)
+	}
+	for _, e := range sortedkeys(byencoded) {
+		if 1 < len(byencoded[e]) {
+			pair := append([]string{}, byencoded[e]...)
+			sort.Strings(pair)
+			return out, Fail("plugin_env_ambiguous",
+				"refs collide in the environment encoding as "+e+": "+strings.Join(pair, ", "),
+				map[string]any{"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.
+	// Equal lengths break bytewise: the canonical leans on JavaScript's
+	// stable sort over insertion order, which a Go map cannot reproduce
+	// and which no entry can distinguish anyway.
+	encoded := sortedkeys(byencoded)
+	sort.SliceStable(encoded, func(i, j int) bool {
+		return len(encoded[i]) > len(encoded[j])
+	})
+
+	for _, key := range sortedkeys(input.Env) {
+		if !strings.HasPrefix(key, envPrefix) {
+			continue
+		}
+		rest := key[len(envPrefix):]
+
+		if "PROFILE" == rest {
+			out.Profile = input.Env[key]
+			continue
+		}
+
+		if "ACTIVE" == rest || "INACTIVE" == rest {
+			for _, r := range splitlist(input.Env[key]) {
+				c, err := CanonRef(r)
+				if nil != err {
+					return out, err
+				}
+				// The reservation covers EVERY input layer (§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.
+				if err := checkreservedref(c, input.Reserved); nil != err {
+					return out, err
+				}
+				if "ACTIVE" == rest {
+					out.Active = append(out.Active, c)
+				} else {
+					out.Inactive = append(out.Inactive, c)
+				}
+			}
+			continue
+		}
+
+		enc := ""
+		for _, e := range encoded {
+			if rest == e || strings.HasPrefix(rest, e+"_") {
+				enc = e
+				break
+			}
+		}
+		if "" == enc {
+			continue // not for any ref this host holds
+		}
+		ref := byencoded[enc][0]
+		if err := checkreservedref(ref, input.Reserved); nil != err {
+			return out, err
+		}
+
+		if rest == enc {
+			continue // a ref with no path sets nothing
+		}
+		path := strings.Split(strings.ToLower(rest[len(enc)+1:]), "_")
+
+		node, ok := out.Options[ref].(map[string]any)
+		if !ok {
+			node = map[string]any{}
+			out.Options[ref] = node
+		}
+		for i := 0; i < len(path)-1; i++ {
+			child, ok := node[path[i]].(map[string]any)
+			if !ok {
+				child = map[string]any{}
+				node[path[i]] = child
+			}
+			node = child
+		}
+		node[path[len(path)-1]] = parsevalue(input.Env[key])
+	}
+
+	return out, nil
+}
+
+func splitlist(v string) []string {
+	out := []string{}
+	for _, s := range strings.Split(v, ",") {
+		if t := strings.TrimSpace(s); 0 < len(t) {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+// parsevalue: 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.
+func parsevalue(v string) any {
+	var out any
+	if err := json.Unmarshal([]byte(v), &out); nil != err {
+		return v
+	}
+	return out
+}

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

@@ -0,0 +1,80 @@
+// VENDORED: @voxgig/plugin 0.1.6 (go/plugin/export.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.
+/* Exports (§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. */
+
+package plugin
+
+import (
+	"sort"
+	"strconv"
+	"strings"
+)
+
+type Exported struct {
+	Ref   string
+	Key   string
+	Value any
+}
+
+func ResolveExport(spec string, exported []Exported) (any, error) {
+	cut := strings.Index(spec, "/")
+	if -1 == cut {
+		return nil, Fail("plugin_export_ambiguous", "export spec needs a key: "+spec,
+			map[string]any{"spec": spec})
+	}
+	head := spec[:cut]
+	key := spec[cut+1:]
+
+	// A fully qualified ref: exactly one answer or none.
+	want := canon(head)
+	for _, e := range exported {
+		if e.Ref == want && e.Key == key {
+			return e.Value, nil
+		}
+	}
+
+	// An alias: the name, not a ref. Look at every instance of it.
+	byname := []Exported{}
+	for _, e := range exported {
+		if refname(e.Ref) == head && e.Key == key {
+			byname = append(byname, e)
+		}
+	}
+	if 0 == len(byname) {
+		return nil, nil
+	}
+
+	for _, e := range byname {
+		if r, err := ParseRef(e.Ref); nil == err && "" == r.Tag {
+			return e.Value, nil
+		}
+	}
+
+	if 1 == len(byname) {
+		return byname[0].Value, nil
+	}
+
+	refs := []string{}
+	for _, e := range byname {
+		refs = append(refs, e.Ref)
+	}
+	sort.Strings(refs)
+	return nil, Fail("plugin_export_ambiguous",
+		"alias "+spec+" matches "+itoa(len(refs))+" instances: "+join(refs, ", "),
+		map[string]any{"spec": spec, "refs": refs})
+}
+
+func itoa(n int) string { return strconv.Itoa(n) }
+
+func join(l []string, sep string) string { return strings.Join(l, sep) }