@voxgig/sdkgen 4.29.0 → 4.30.1

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

@@ -1,21 +1,8 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/catalog.go)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
-/* The definition catalog (§10.1).
- *
- * A definition is registered once and may back many instances. Option
- * shapes are validated AT REGISTRATION, not when a document happens to
- * exercise a key — so a malformed shape fails once, and in the same
- * place everywhere (§9.4). */
-
 package plugin
 
-// Definition is what a plugin author writes.
-//
-// GO RETURNS ERRORS FROM LIFECYCLE CALLBACKS (§18, P4). The canonical
-// throws; a Go callback returns `error`, and the host treats a non-nil
-// return exactly as the canonical treats a throw — including
-// `plugin_activate_failed`'s unwind and the `failed` status.
 type Definition struct {
 	Name        string
 	Shape       any
@@ -30,12 +17,6 @@ type Catalog struct {
 	defs map[string]Definition
 }
 
-// MakeCatalog builds a catalog, adding each definition in turn.
-//
-// GO IS TIER S (§10.3): "package `init()` registration ... or an
-// explicit list handed to makeHost", and both spellings land here. A Go
-// developer's experience is "add the import, add one line to the config"
-// rather than "write a factory".
 func MakeCatalog(defs ...Definition) (*Catalog, error) {
 	c := &Catalog{defs: map[string]Definition{}}
 	for _, d := range defs {

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

@@ -1,21 +1,6 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/config.go)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
-/* The declarative document (§9): normalization, and the ten-level
- * precedence ladder.
- *
- * TWO FUNCTIONS, AND THE SPLIT BETWEEN THEM IS FORCED.
- *
- * NormalizeConfig normalizes STRUCTURE and ENTRY KEYS. It does not
- * merge options, and cannot: §9.4 makes merge behaviour a property of
- * the definition's option SHAPE, which normalization has never seen. A
- * normalizer that flattened the option layers would make
- * `$MERGE: append` unimplementable at load time, because the layers it
- * must concatenate would already be collapsed.
- *
- * ResolveOptions applies the ladder, and it is the only place that
- * knows the shape. */
-
 package plugin
 
 import "sort"
@@ -30,12 +15,9 @@ type Keys struct {
 }
 
 type NormalizeInput struct {
-	Doc     any    `json:"doc"`
-	Profile string `json:"profile,omitempty"`
-	// Keys is §9.1: a host may rename `instance` and `default` into its
-	// own vocabulary.
-	Keys Keys `json:"keys,omitempty"`
-	// Reserved is §9.1: refs the host declares itself and always wins on.
+	Doc      any      `json:"doc"`
+	Profile  string   `json:"profile,omitempty"`
+	Keys     Keys     `json:"keys,omitempty"`
 	Reserved []string `json:"reserved,omitempty"`
 }
 
@@ -45,12 +27,6 @@ func NormalizeConfig(input NormalizeInput) (Normalized, error) {
 	dkey := or(input.Keys.Default, "default")
 	reserved := input.Reserved
 
-	// The rename is applied at TWO PLACES AND NO OTHERS: the document
-	// root, and every profile.<name> overlay root (§9.1). A rename
-	// applied only at the root would leave `profile.prod.sdk`
-	// untranslated and silently drop every environment override the host
-	// depends on. Recursing further would be worse: option data is the
-	// definition's.
 	baseinst := doc[ikey]
 	basedef := asmap(doc[dkey])
 
@@ -109,17 +85,10 @@ func NormalizeConfig(input NormalizeInput) (Normalized, error) {
 		b := base.emap[ref]
 		o := over.emap[ref]
 
-		// MERGE THE ENTRIES AS AUTHORED, THEN APPLY DEFAULTS TO THE
-		// RESULT (§9.3). A safety rule, not a tidiness one: if the
-		// overlay had its defaults filled in before merging it would
-		// carry a synthesized active:true and overwrite a base's false —
-		// silently re-enabling a deliberately disabled integration in
-		// production.
 		active := asbool(pick(o, "active", pick(b, "active", true)), true)
 		start := asstring(pick(o, "start", pick(b, "start", "eager")), "eager")
 		ord := pick(o, "order", pick(b, "order", nil))
 
-		// Option layers, levels 3-6, IN LADDER ORDER. Never merged here.
 		layers := []any{}
 		nm := refname(ref)
 		if v, ok := asmap(basedef[nm])["options"]; ok {
@@ -218,22 +187,16 @@ func checkreservedref(ref string, reserved []string) error {
 	return nil
 }
 
-// ---------------------------------------------------------------------
-// ResolveOptions — §9.3's ten levels, and §9.4's merge directives
-// ---------------------------------------------------------------------
-
 type ResolveInput struct {
-	Ref string `json:"ref"`
-	// Shape is level 1 — the definition's option shape. Also carries the
-	// $MERGE directives, which is why merging cannot happen without it.
+	Ref          string `json:"ref"`
 	Shape        any    `json:"shape,omitempty"`
-	HostDefaults any    `json:"hostdefaults,omitempty"` // 2
-	Doc          any    `json:"doc,omitempty"`          // 3-6
+	HostDefaults any    `json:"hostdefaults,omitempty"`
+	Doc          any    `json:"doc,omitempty"`
 	Profile      string `json:"profile,omitempty"`
-	Env          any    `json:"env,omitempty"`         // 7
-	HostOptions  any    `json:"hostoptions,omitempty"` // 8
-	LoadOptions  any    `json:"loadoptions,omitempty"` // 9
-	Patch        any    `json:"patch,omitempty"`       // 10
+	Env          any    `json:"env,omitempty"`
+	HostOptions  any    `json:"hostoptions,omitempty"`
+	LoadOptions  any    `json:"loadoptions,omitempty"`
+	Patch        any    `json:"patch,omitempty"`
 }
 
 func ResolveOptions(input ResolveInput) (map[string]any, error) {
@@ -254,11 +217,6 @@ func ResolveOptions(input ResolveInput) (map[string]any, error) {
 		overlay = asmap(asmap(doc["profile"])[input.Profile])
 	}
 
-	// ONE ordered merge, lowest to highest. Levels 3-6 are not two
-	// namespaces collapsed separately and composed afterwards: that
-	// inverts the rule that PROFILE SPECIFICITY OUTRANKS DEFINITION
-	// SPECIFICITY, so a prod per-definition default would lose to a base
-	// instance value.
 	lo3, err := optsof(doc["default"], name)
 	if nil != err {
 		return nil, err
@@ -277,13 +235,13 @@ func ResolveOptions(input ResolveInput) (map[string]any, error) {
 	}
 
 	layers := []any{
-		defaultsof(shape),  // 1
-		input.HostDefaults, // 2
-		lo3, lo4, lo5, lo6, // 3-6
-		input.Env,         // 7
-		input.HostOptions, // 8
-		input.LoadOptions, // 9
-		input.Patch,       // 10
+		defaultsof(shape),
+		input.HostDefaults,
+		lo3, lo4, lo5, lo6,
+		input.Env,
+		input.HostOptions,
+		input.LoadOptions,
+		input.Patch,
 	}
 
 	var out any = map[string]any{}
@@ -296,7 +254,6 @@ func ResolveOptions(input ResolveInput) (map[string]any, error) {
 	return asmap(out), nil
 }
 
-// defaultsof: the shape's non-directive values are the level-1 defaults.
 func defaultsof(shape map[string]any) map[string]any {
 	out := map[string]any{}
 	for _, k := range sortedkeys(shape) {
@@ -315,7 +272,6 @@ func optsof(src any, key string) (any, error) {
 	if nil == src {
 		return nil, nil
 	}
-	// The array form is equivalent to the map form (§9.1).
 	if list, ok := aslist(src); ok {
 		for _, item := range list {
 			raw, _ := asmap(item)["ref"]
@@ -351,10 +307,6 @@ func optsof(src any, key string) (any, error) {
 	return nil, nil
 }
 
-// mergeone merges ONE layer onto the accumulator, honouring the shape's
-// directives. The directive holds at EVERY precedence level, not only
-// between document levels — §9.4 makes it a property of the shape, which
-// does not know which layer a value arrived from.
 func mergeone(base any, over any, shape map[string]any) any {
 	if nil == over {
 		return base
@@ -411,7 +363,6 @@ func mergeone(base any, over any, shape map[string]any) any {
 	return out
 }
 
-// deepto merges N levels below this key, replacing below that.
 func deepto(base any, over any, n int) any {
 	if 0 >= n {
 		return clonevalue(over)
@@ -430,14 +381,6 @@ func deepto(base any, over any, n int) any {
 	return out
 }
 
-// §9.4: N is an integer of at least 1, and everything else is an error.
-//
-// `{"deep": 0}` is rejected DESPITE having an obvious reading, because
-// "replace at this key" already has a spelling and two spellings for one
-// behaviour is the defect class this repo exists to avoid. Without the
-// stated domain each port picks its own reading — reject, replace,
-// unlimited merge, or clamp to 1 — and the same document resolves
-// differently per language.
 var mergeWords = []string{"replace", "append"}
 
 func CheckShape(shape any) error {
@@ -570,25 +513,6 @@ func isposint(v any) bool {
 	return f == float64(int(f)) && 1 <= f
 }
 
-// asorderref reads ONE spelling or a LIST of them into an OrderRef, and
-// KEEPS THE AUTHORED VALUE so normalization can hand it back untouched.
-//
-// It used to be a bare asstring(), so a list decoded to "" and the
-// constraint was SILENTLY DROPPED - the sort ran as if nothing had been
-// declared.
-//
-// `stated` is separate from the value because an ABSENT key and a key
-// authored as `null` are different documents, and a map index alone
-// cannot tell them apart.
-//
-// The other four ports have no type like this at all: they carry the
-// authored block straight through (`ent.order = ord`), so every spelling
-// survives normalization by construction. Go is the only port that
-// decodes and rebuilds, and a rebuild loses whatever it does not model -
-// first the list form, then scalar-vs-one-element-list, then an authored
-// empty list, then an authored null. One cause, four parity breaks, none
-// of which the corpus could see until `config/normorder` was written.
-// Keeping the authored value ends the class rather than the instance.
 func asorderref(v any, stated bool) OrderRef {
 	if !stated {
 		return OrderRef{}

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

@@ -1,31 +1,6 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/depend.go)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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"
@@ -48,21 +23,6 @@ func NormRequire(r any) Required {
 	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"])
@@ -86,11 +46,6 @@ func Requirements(options map[string]any) []Required {
 	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 {
@@ -99,64 +54,21 @@ func RestartsOnLoss(r Required) bool {
 	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 {
@@ -174,12 +86,6 @@ func DependencyCycle(nodes []DependNode) []string {
 				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)
 			}
@@ -193,8 +99,6 @@ func DependencyCycle(nodes []DependNode) []string {
 		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 {

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

@@ -1,29 +1,6 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/env.go)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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 (
@@ -42,15 +19,11 @@ type EnvResult struct {
 }
 
 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"`
+	Env      map[string]string `json:"env"`
+	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, ".", "_")
@@ -89,11 +62,6 @@ func ApplyEnv(input EnvInput) (EnvResult, error) {
 		}
 	}
 
-	// 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])
@@ -116,11 +84,6 @@ func ApplyEnv(input EnvInput) (EnvResult, error) {
 				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
 				}
@@ -182,9 +145,6 @@ func splitlist(v string) []string {
 	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 {

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

@@ -1,18 +1,6 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/export.go)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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 (

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

@@ -1,25 +1,6 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/graph.go)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
-/* Whole-graph resolution (§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. */
-
 package plugin
 
 import "sort"
@@ -38,9 +19,6 @@ type Blocked struct {
 	Why   Why    `json:"why"`
 }
 
-// Why is the tagged union §11.4 pins. Go has no sum type, so the fields
-// carry `omitempty` and the corpus pins which are present per `kind` —
-// the same discrimination the canonical gets from its union.
 type Why struct {
 	Kind string `json:"kind"`
 	// kind: version
@@ -57,12 +35,6 @@ type Why struct {
 	Chain []string `json:"chain,omitempty"`
 }
 
-// MarshalJSON exists for one reason: `why.found` is a LIST OF VERSIONS
-// under `kind: version` and a SINGLE ATTRIBUTE VALUE under `kind:
-// match`. The canonical's union gives each variant its own `found`;
-// Go's struct cannot, so the two are separate fields that render to one
-// name. A `found` of `false` or `null` under `kind: match` must still
-// appear, which is why it is not merely another omitempty field.
 func (w Why) MarshalJSON() ([]byte, error) {
 	out := map[string]any{"kind": w.Kind}
 	switch w.Kind {
@@ -93,10 +65,6 @@ func ResolveGraph(nodes []Node) Resolution {
 	resolved := map[string]bool{}
 	blocked := map[string]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.
 	for moved := true; moved; {
 		moved = false
 		for _, n := range nodes {
@@ -130,13 +98,6 @@ func ResolveGraph(nodes []Node) Resolution {
 	return res
 }
 
-// firstunmet returns 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.
-//
-// The second return is the canonical's `null` — Go has no nullable
-// struct without a pointer, and a bool says what it means.
 func firstunmet(n Node, byref map[string]Node, resolved map[string]bool) (Blocked, bool) {
 	for _, req := range n.Requires {
 		if req.Optional {