@voxgig/sdkgen 4.21.0 → 4.22.0

package/project/.sdk/tm/go/feature/secrets_feature.go

@@ -15,58 +15,17 @@ import (
 	sekreto "GOMODULE/feature/secrets/sekreto"
 )
 
-// Secret access via a vendored @voxgig/sekreto provider chain, and the
-// access-token exchange some APIs require on top of it. The go port of
-// tm/ts/src/feature/secrets/SecretsFeature.ts - same contract, go idiom.
-//
-// The SDK's `apikey` option keeps exactly its old meaning: an explicit
-// credential given in code. This feature makes it ONE SOURCE among several
-// rather than the only one: when active, the apikey is resolved through a
-// sekreto chain in which the explicit option (when set) is the FIRST
-// provider - a `memory` store named `options` - so an explicit value always
-// wins, by sekreto's own first-hit rule rather than by special-case logic.
-//
-// Resolution is effectively ASYNC (providers do IO), and the auth header is
-// built by the synchronous prepareAuth inside makeSpec. The bridge is the
-// feature hook pipeline: every entity op runs featureHook("PreSpec") before
-// makeSpec, so the PreSpec hook below resolves the secret once and writes
-// it into the LIVE options map where prepareAuth already looks (ctx.Options
-// on the root context IS the options map the client clones for OptionsMap).
-// Concurrent operations share the single in-flight resolution.
-//
-// MISS vs ERROR (sekreto's invariant): a provider MISS falls through - the
-// op proceeds, unauthenticated if nothing else supplies a credential. A
-// provider ERROR (unreachable vault, bad creds) must FAIL the op: a broken
-// vault never degrades into an unauthenticated request. go's feature hooks
-// are synchronous and cannot fail an operation from PreSpec the way ts's
-// awaited hook rejection can - so, unlike ts, the transport is wrapped
-// WHENEVER the feature is active, and the wrapper refuses to send while
-// the last resolution stands failed. Fail-closed at the one seam every
-// request must pass.
-//
-// EXCHANGE: some APIs will not take a long-lived credential at all. What
-// the chain resolves is then a REFRESH token, which buys a short-lived
-// ACCESS token from a token endpoint (`exchange.path`, relative to
-// options.base); the access token is what every request carries, and when
-// a response status in `exchange.statuses` (401) says it is spent the
-// wrapper buys another and retries the same request once. Concurrent
-// purchases share the one in-flight exchange; test mode buys nothing and
-// answers with a deterministic fake token.
 type SecretsFeature struct {
 	BaseFeature
 	client  *core.ProjectNameSDK
 	options map[string]any
 
-	// The LIVE options map (root ctx options), where the resolved value
-	// lands so the sync prepareAuth sees it.
 	liveopts map[string]any
 
 	secretname string
 	cache      bool
 	sek        *sekreto.Sekreto
 
-	// Exchange state: nil config when off; the refresh credential the
-	// chain resolved; the single in-flight purchase.
 	exchange *secretsExchange
 	refresh  string
 
@@ -75,16 +34,6 @@ type SecretsFeature struct {
 	buying    *secretsBuy
 	initerr   error
 
-	// The RESOLVED credential, held in feature state and injected into
-	// each request at the transport seam - NEVER written into the shared
-	// live options map. This is go's structural deviation from the ts
-	// reference (which writes options.apikey): the go request path reads
-	// ctx.Options raw on every operation goroutine, so a feature that
-	// mutated that map would race every concurrent operation. With the
-	// feature as sole holder, the options map is frozen after
-	// construction and every raw read is safe; the header the wire sees
-	// is identical, because the transport wrapper rewrites it from this
-	// value the same way prepareAuth builds it.
 	cred string
 }
 
@@ -97,7 +46,6 @@ type secretsExchange struct {
 	retries  int
 }
 
-// One shared in-flight resolution: late arrivals wait on done and read err.
 type secretsCall struct {
 	done chan struct{}
 	err  error
@@ -127,8 +75,6 @@ func (f *SecretsFeature) Sekreto() *sekreto.Sekreto {
 	return f.sek
 }
 
-// Init is sync by feature contract: build the chain, never look anything
-// up here.
 func (f *SecretsFeature) Init(ctx *core.Context, options map[string]any) {
 	f.client = ctx.Client
 	f.options = options
@@ -145,8 +91,6 @@ func (f *SecretsFeature) Init(ctx *core.Context, options map[string]any) {
 	}
 	f.cache = foptBool(options, "cache", true)
 
-	// Exchange config, normalised once. Nil when off, so every later
-	// decision is a nil check.
 	xopts := foptMap(options, "exchange")
 	if foptBool(xopts, "active", false) {
 		statuses := []int{}
@@ -166,14 +110,6 @@ func (f *SecretsFeature) Init(ctx *core.Context, options map[string]any) {
 		}
 	}
 
-	// The explicit credential, when set, is the first store in the chain.
-	//
-	// WHICH option that is depends on the exchange. Without one, the
-	// secret being resolved IS the credential the transport sends, so
-	// `apikey` is it. With one, the secret is a REFRESH token and `apikey`
-	// means the opposite thing - an access token the caller already holds
-	// - so the explicit seat belongs to `exchange.refresh`, and apikey is
-	// left alone to serve as the starting access token (see resolveonce).
 	explicit := ""
 	if nil == f.exchange {
 		explicit, _ = f.liveopts["apikey"].(string)
@@ -199,7 +135,6 @@ func (f *SecretsFeature) Init(ctx *core.Context, options map[string]any) {
 		case *sekreto.ProviderSpec:
 			specs = append(specs, v)
 		case sekreto.Provider:
-			// A provider already built joins the chain as it is.
 			specs = append(specs, &sekreto.ProviderSpec{Provider: v})
 		case map[string]any:
 			spec, err := sekreto.SpecOf(v)
@@ -209,18 +144,6 @@ func (f *SecretsFeature) Init(ctx *core.Context, options map[string]any) {
 			}
 			specs = append(specs, spec)
 		default:
-			// ANYTHING ELSE is refused, fail-closed - a bare kind name
-			// ("hashicorp"), a nil, a number. DELIBERATE DIVERGENCE from
-			// ts/kotlin: those push every entry through to Sekreto's
-			// constructor, whose dynamic providers list refuses it with this
-			// message. Go's Options.Providers is a typed slice, so there is
-			// nothing to push a string through; the feature raises the
-			// library's own error here instead, via sekreto.Fail with the
-			// constructor's own wording, and the transport gate below refuses
-			// to send. A switch without this arm silently DROPPED the entry,
-			// which SHORTENED the chain instead of failing it - a
-			// misconfigured providers list then sent ordinary unauthenticated
-			// requests, the exact fail-open the gate exists to prevent.
 			f.initerr = sekreto.Fail(
 				"sekreto: not a provider or a provider spec: " + fmt.Sprint(v))
 		}
@@ -253,10 +176,6 @@ func (f *SecretsFeature) Init(ctx *core.Context, options map[string]any) {
 	}
 	f.sek = sek
 
-	// Wrap the transport: the fail-closed gate needs the seam whenever the
-	// feature is active, and the exchange (when on) additionally needs to
-	// SEE responses - expiry is only ever discovered from one, and this is
-	// the one place a response can be seen and the request tried again.
 	self := f
 	inner := ctx.Utility.Fetcher
 	ctx.Utility.Fetcher = func(ctx2 *core.Context, url string, fetchdef map[string]any) (any, error) {
@@ -264,19 +183,6 @@ func (f *SecretsFeature) Init(ctx *core.Context, options map[string]any) {
 	}
 }
 
-// resolve runs one resolution, shared by every concurrent caller. A
-// settled HIT is kept only when caching is on (`cache: false` means every
-// resolve asks the chain again); a FAILURE is always cleared, so a
-// transient vault outage never poisons the client permanently - the next
-// operation asks the chain again.
-//
-// A MISS is cleared too, however caching is set. That rule is sekreto's,
-// not this feature's: `A miss is never cached: the next read asks again`,
-// in sekreto's own source. Retaining a settled miss here would override
-// that from the layer above, and a secret provisioned after startup - a
-// mounted file, a policy granted a minute late - would never be picked up
-// for the life of the client. `cache` is about caching a HIT; it was never
-// a promise to keep saying no.
 func (f *SecretsFeature) resolve() error {
 	if nil != f.initerr {
 		return f.initerr
@@ -315,8 +221,6 @@ func (f *SecretsFeature) resolveonce() (bool, error) {
 
 	found, has, err := f.sek.Try(f.secretname)
 	if nil != err {
-		// A provider ERROR fails the op (via the transport gate); only a
-		// MISS falls through.
 		return false, err
 	}
 
@@ -325,12 +229,6 @@ func (f *SecretsFeature) resolveonce() (bool, error) {
 		if has {
 			f.cred = found
 		} else {
-			// An UNCACHED miss after an earlier hit is a revocation: the
-			// chain now says no provider has the secret, so the resolved
-			// value must not keep going out on the wire. (An explicit
-			// apikey OPTION is never lost here - it seats FIRST in the
-			// chain as a memory provider, so the chain HITS while one is
-			// set and the miss branch is unreachable.)
 			f.cred = ""
 		}
 		f.mu.Unlock()
@@ -350,27 +248,15 @@ func (f *SecretsFeature) resolveonce() (bool, error) {
 	apikey := f.cred
 	f.mu.Unlock()
 	if "" == apikey {
-		// A starting access token supplied as the OPTION: read from the
-		// frozen options map (no feature ever writes it).
 		apikey, _ = f.liveopts["apikey"].(string)
 		f.mu.Lock()
 		f.cred = apikey
 		f.mu.Unlock()
 	}
 	if "" != apikey {
-		// A starting access token was supplied. Spend it: if it is stale
-		// the API answers with an expiry status and the transport wrapper
-		// buys another, which is the same path expiry takes anyway.
 		return true, nil
 	}
 
-	// `auth: nil` is the documented way to send NO credential, and a
-	// purchase is a credential-bearing call: the refresh token goes to the
-	// token endpoint in the request body. withrefresh honours suppression
-	// for the RETRY, but it runs after this - by then the refresh token has
-	// already left the process, and no later check can call it back. The
-	// suppression has to be honoured here, before the first purchase, or it
-	// only ever half-held.
 	if nil == f.liveopts["auth"] {
 		return false, nil
 	}
@@ -379,21 +265,9 @@ func (f *SecretsFeature) resolveonce() (bool, error) {
 	return nil == err, err
 }
 
-// transport wraps whatever transport was current at Init.
 func (f *SecretsFeature) transport(ctx *core.Context, url string,
 	fetchdef map[string]any, inner core.FetcherFunc) (any, error) {
 
-	// Fail-closed, at the ONE seam every wire path crosses. Entity ops,
-	// Direct, Graphql and the exchange retries all come through this
-	// wrapper, so resolving HERE is what gives the raw paths - which run
-	// no feature hooks at all - the same credential the entity pipeline
-	// gets (ts resolves in its awaited PreSpec instead; go's header is
-	// rewritten below AFTER Prepare built it, so the transport is exactly
-	// early enough). resolve() is shared and cached: concurrent callers
-	// join the in-flight attempt, a cached success is free, and with
-	// `cache: false` the chain is asked once per REQUEST, which is that
-	// option's meaning. A provider ERROR refuses the request with the
-	// provider's error - never an unauthenticated send.
 	if nil != f.initerr {
 		return nil, f.initerr
 	}
@@ -417,22 +291,9 @@ func (f *SecretsFeature) transport(ctx *core.Context, url string,
 	return f.withrefresh(ctx, url, fetchdef, inner)
 }
 
-// withrefresh buys a token and tries the request again when the API says
-// the current one is spent.
-//
-// The retry rewrites the authorization header IN PLACE on the fetchdef,
-// because the header was built by the synchronous prepareAuth before this
-// request left, and it carries the token that just failed. Rebuilt the way
-// prepareAuth builds it, from the same options auth.prefix, so the two
-// cannot drift.
 func (f *SecretsFeature) withrefresh(ctx *core.Context, url string,
 	fetchdef map[string]any, inner core.FetcherFunc) (any, error) {
 
-	// `auth: nil` is the documented way to send NO credential, and
-	// prepareAuth honours it by removing the header. A refusal of a
-	// deliberately unauthenticated request is not an expired token and
-	// cannot be fixed by buying one - retrying would transmit exactly the
-	// credential the caller suppressed.
 	if nil == f.liveopts["auth"] {
 		return inner(ctx, url, fetchdef)
 	}
@@ -441,8 +302,6 @@ func (f *SecretsFeature) withrefresh(ctx *core.Context, url string,
 	attempt := 0
 
 	for {
-		// The credential THIS attempt goes out with, captured before it
-		// leaves: it is what tells a stale refusal apart from a fresh one.
 		used := f.getcred()
 
 		res, err := inner(ctx, url, fetchdef)
@@ -451,12 +310,6 @@ func (f *SecretsFeature) withrefresh(ctx *core.Context, url string,
 			return res, err
 		}
 
-		// Another request may have bought a token while this one was in
-		// flight. Concurrent expiries share the in-flight purchase, but
-		// STAGGERED ones do not - so spend what is current before buying:
-		// a second exchange for a token that is already fresh is wasted,
-		// and on a provider that invalidates the previous credential on
-		// issuance it breaks the first request's own retry.
 		current := f.getcred()
 		token := ""
 
@@ -497,7 +350,6 @@ func (f *SecretsFeature) spent(res any) bool {
 	return false
 }
 
-// getcred reads the resolved credential under the feature mutex.
 func (f *SecretsFeature) getcred() string {
 	f.mu.Lock()
 	v := f.cred
@@ -518,12 +370,6 @@ func (f *SecretsFeature) reauth(fetchdef map[string]any, token string) {
 		return
 	}
 
-	// Suppressed auth means NO header, the same answer prepareAuth gives.
-	// Reached defensively - withrefresh does not retry at all when auth is
-	// nil - but this is the function that writes the credential, so it is
-	// where the rule has to hold.
-	// The options map is FROZEN after construction (this feature never
-	// writes it), so the raw read is safe on any goroutine.
 	rawauth := f.liveopts["auth"]
 	auth, _ := rawauth.(map[string]any)
 	if nil == rawauth || nil == auth {
@@ -543,12 +389,6 @@ func (f *SecretsFeature) reauth(fetchdef map[string]any, token string) {
 // ONE in-flight purchase; the slot is cleared once settled, so the next
 // expiry buys a fresh token rather than replaying this result.
 func (f *SecretsFeature) buy() (string, error) {
-	// TEST MODE BUYS NOTHING. The test feature replaces the transport so
-	// no request leaves the process; an exchange here would be the one
-	// HTTP call it could not stop, and it would need a live token endpoint
-	// for a suite whose whole point is not needing one. A deterministic,
-	// obviously-fake token instead - the same answer makeOptions gives a
-	// required server variable, for the same reason.
 	if "live" != f.client.Mode {
 		token := "test-" + f.exchange.response
 		f.mu.Lock()
@@ -574,8 +414,6 @@ func (f *SecretsFeature) buy() (string, error) {
 	buying.err = err
 	f.buying = nil
 	if nil == err {
-		// Publish HERE, before the waiters wake: one writer, under the
-		// mutex - waiters consume the returned value.
 		f.cred = token
 	}
 	f.mu.Unlock()
@@ -595,8 +433,6 @@ func (f *SecretsFeature) buyonce() (string, error) {
 
 	options := f.client.OptionsMap()
 
-	// The token endpoint is RELATIVE to the base, which already carries
-	// whatever account or tenant segment the server URL declares.
 	base, _ := options["base"].(string)
 	base = strings.TrimRight(base, "/")
 	url := base + "/" + strings.TrimLeft(x.path, "/")
@@ -605,11 +441,6 @@ func (f *SecretsFeature) buyonce() (string, error) {
 	fetch, _ := system["fetch"].(func(string, map[string]any) (map[string]any, error))
 
 	if nil == fetch {
-		// No custom transport supplied - the ordinary case. makeOptions
-		// leaves system.fetch unset, so the exchange gets its own raw
-		// HTTP path (mirroring the ts reference, whose system.fetch is
-		// initialized from the platform fetcher). Local and minimal on
-		// purpose: see the NOT-the-SDK-transport note below.
 		fetch = rawExchangeFetch
 	}
 
@@ -621,10 +452,6 @@ func (f *SecretsFeature) buyonce() (string, error) {
 		return "", err
 	}
 
-	// Deliberately NOT the SDK transport. The transport is what this
-	// feature wraps, and sending the token request back through it would
-	// recurse on the first expiry - and would route the exchange through
-	// the test mock, which knows nothing about it.
 	res, err := fetch(url, map[string]any{
 		"method":  x.method,
 		"headers": map[string]any{"content-type": "application/json"},

package/project/.sdk/tm/go/feature/streaming_feature.go

@@ -4,13 +4,6 @@ import (
 	"GOMODULE/core"
 )
 
-// Streaming result support. For list-style operations it attaches a
-// `Result.Stream` function yielding a channel so callers can consume items
-// incrementally with `for item := range result.Stream()` instead of
-// materialising the whole slice at once. A `chunkSize` groups items into
-// []any batches when set; a `chunkDelay` (ms) paces delivery via the
-// injectable `sleep` for offline tests. The channel is fully buffered, so
-// abandoning a stream never leaks the producing goroutine.
 type StreamingFeature struct {
 	BaseFeature
 	client  *core.ProjectNameSDK

package/project/.sdk/tm/go/feature/telemetry_feature.go

@@ -6,14 +6,6 @@ import (
 	"GOMODULE/core"
 )
 
-// Distributed-tracing telemetry. Opens a span per operation (PrePoint),
-// propagates trace context to the server as W3C `traceparent` plus
-// `X-Trace-Id` / `X-Span-Id` headers (PreRequest), and closes the span on
-// completion (PreDone) or failure (PreUnexpected). Each span closes exactly
-// once (the per-context marker in ctx.Out is consumed on close). Finished
-// spans accumulate on the feature; an `exporter` callback, when provided,
-// is invoked with each finished span. Trace/span id generation (`idgen`)
-// and the clock (`now`) are injectable for deterministic tests.
 type TelemetryFeature struct {
 	BaseFeature
 	client  *core.ProjectNameSDK

package/project/.sdk/tm/go/feature/test_feature.go

@@ -55,13 +55,6 @@ func (f *TestFeature) Init(ctx *core.Context, options map[string]any) {
 	self := f
 
 	testFetcher := func(ctx *core.Context, _fullurl string, _fetchdef map[string]any) (any, error) {
-		// Shape the mock payload the way the real API would, so the op's
-		// response transform recovers the entity from it. A point carrying
-		// `transform.res: ` + "`body.item`" + ` describes an API that answers
-		// {"item": {...}}; handing back the bare entity means the transform
-		// unwraps a property that is not there and the caller gets nil. The
-		// mock has to agree with the model, or it only ever simulates APIs
-		// whose responses happen to be unwrapped. Mirrors the ts mock.
 		envelope := func(data any) any {
 			if data == nil || ctx.Point == nil {
 				return data
@@ -78,8 +71,6 @@ func (f *TestFeature) Init(ctx *core.Context, options map[string]any) {
 			if m == nil {
 				return data
 			}
-			// Multi-segment on purpose: GraphQL ops unwrap body.data.<field>
-			// (and body.data.<field>.<entity> for mutations), not just one level.
 			segs := strings.Split(m[1], ".")
 			out := data
 			for i := len(segs) - 1; 0 <= i; i-- {
@@ -152,13 +143,6 @@ func (f *TestFeature) Init(ctx *core.Context, options map[string]any) {
 			out := vs.Clone(found)
 			return respond(200, out, nil), nil
 		} else if op.Name == "update" {
-			// Match the existing entity by id only (or its alias). Reqdata
-			// also contains the new field values, which would otherwise
-			// cause Select to filter out the entity we want to update.
-			// When reqdata has no id, fall back to the id the entity
-			// client carries from a prior create/load (in ctx.Match /
-			// ctx.Data), mirroring the TS mock where param(ctx,'id')
-			// resolves from accumulated state.
 			updateMatch := map[string]any{}
 			if ctx.Reqdata != nil {
 				if v, has := ctx.Reqdata["id"]; has {
@@ -357,13 +341,6 @@ func (f *TestFeature) buildArgs(ctx *core.Context, op *core.Operation, args map[
 	// (e.g. GET /result?trace_id=), which has no path param at all.
 	paramsPath := vs.GetPath(point, []any{"args", "params"})
 	reqdParams := vs.Select(paramsPath, map[string]any{"reqd": true})
-	// The error return Transform gained in struct go 0.1.3 is discarded
-	// DELIBERATELY here, unlike in transform_request/response: these two
-	// transform a spec the SDK itself built from the point definition, not
-	// user data, so an error means a generator bug rather than something a
-	// caller can act on — and buildArgs has no error seam to route it
-	// through. An empty result is the conservative outcome: no required
-	// fields, which is what an absent spec already produces.
 	reqdFromParams, _ := vs.Transform(reqdParams, []any{"`$EACH`", "", "`$KEY.name`"})
 	queryPath := vs.GetPath(point, []any{"args", "query"})
 	reqdQuery := vs.Select(queryPath, map[string]any{"reqd": true})

package/project/.sdk/tm/go/feature/validate_feature.go

@@ -9,27 +9,6 @@ import (
 	"GOMODULE/core"
 )
 
-// Payload validation against the model's own field types. The go port of
-// tm/ts/src/feature/validate/ValidateFeature.ts.
-//
-// The specs are NOT written here and not written in the model either: every
-// entity field already carries a canonical type sentinel (`$STRING`,
-// `$INTEGER`, the `$ONE` union for an OpenAPI multi-type), which is the same
-// vocabulary struct.Validate speaks. The generator maps them once
-// (helpers/canonSpec) and emits `core.ENTITYSPEC`, so a field whose type
-// changes in the API spec changes what this feature enforces with no edit
-// anywhere.
-//
-// WHAT IS CHECKED
-//
-//	outbound (PreSpec)  the payload the caller asked to send, against
-//	                    `spec.op[<opname>]` - the operation's request shape.
-//	inbound  (PreDone)  each record the operation returned, against
-//	                    `spec.data` - the entity's own field types.
-//
-// WHAT IS NOT. The model carries no array element types, no nested object
-// schemas, no enums, formats or bounds, so this checks the shape the model
-// knows and nothing more.
 type ValidateFeature struct {
 	BaseFeature
 	client  *core.ProjectNameSDK
@@ -63,18 +42,11 @@ func (f *ValidateFeature) Init(ctx *core.Context, options map[string]any) {
 	f.request = foptBool(options, "request", true)
 	f.response = foptBool(options, "response", false)
 
-	// FAIL CLOSED. Only the exact string "report" selects report mode, so a
-	// typo (`mode: "thow"`) still rejects rather than silently turning
-	// enforcement off. The option spec rejects the typo outright; this is
-	// what happens if it ever does not.
 	f.mode = "throw"
 	if "report" == foptStr(options, "mode", "throw") {
 		f.mode = "report"
 	}
 
-	// `strict` is applied ONCE, here, by rebuilding the spec tree without the
-	// `$OPEN` markers - rather than per call, which would clone a spec for
-	// every request an SDK ever makes.
 	f.spec = core.ENTITYSPEC
 	if foptBool(options, "strict", false) {
 		if closed, ok := validateClose(core.ENTITYSPEC).(map[string]any); ok {
@@ -83,9 +55,6 @@ func (f *ValidateFeature) Init(ctx *core.Context, options map[string]any) {
 	}
 }
 
-// Outbound. MakeSpec short-circuits on a `ctx.Out["spec"]` that is already
-// set, so assigning the error here rejects the operation before the request
-// is built - the same seam rbac uses one stage earlier.
 func (f *ValidateFeature) PreSpec(ctx *core.Context) {
 	if !f.Active || !f.request {
 		return
@@ -111,16 +80,6 @@ func (f *ValidateFeature) PreSpec(ctx *core.Context) {
 			strings.Join(errs, "; "))
 }
 
-// Inbound. PreDone rather than PreResult: the records are extracted from the
-// response body by MakeResult, which runs between the two, so at PreResult
-// there is nothing to check but the envelope.
-//
-// HOOK ORDER MATTERS HERE, and the default order is not the one you want.
-// PreDone hooks fire in feature ADD order, which defaults to `test` first and
-// then names sorted - and `validate` sorts last, after audit, cost, debug,
-// metrics and telemetry. Those observers therefore record the operation as a
-// success before this hook has looked at it. Activating features as an
-// ORDERED LIST fixes it.
 func (f *ValidateFeature) PreDone(ctx *core.Context) {
 	if !f.Active || !f.response {
 		return
@@ -168,9 +127,6 @@ func (f *ValidateFeature) PreDone(ctx *core.Context) {
 		"Invalid response for entity \""+validateEntName(ctx)+"\": "+
 			strings.Join(errs, "; "))
 
-	// BOTH, and `Ok` is the load-bearing half: Done returns Resdata whenever
-	// Result.Ok is true and never looks at Err, so setting the error alone
-	// would hand the caller the very records that failed the spec.
 	ctx.Result.Ok = false
 	ctx.Result.Err = err
 
@@ -182,14 +138,6 @@ func (f *ValidateFeature) PreDone(ctx *core.Context) {
 	ctx.Result.Resdata = nil
 }
 
-// The payload an operation is about to send.
-//
-// TWO SLOTS, AND THE OP PICKS. A body op (create/update/patch) carries the
-// caller's argument in Reqdata over the entity's Data; a match op
-// (load/list/remove) carries it in Reqmatch over Match. That is what the
-// entity operations pass to NewContext and what MakePoint reads - so reading
-// Reqdata for every op would check a `Load({id})` against the entity's STALE
-// stored match and reject it for the id the caller had just supplied.
 func (f *ValidateFeature) payload(ctx *core.Context, opname string) map[string]any {
 	body := "create" == opname || "update" == opname || "patch" == opname
 
@@ -226,9 +174,6 @@ func (f *ValidateFeature) entitySpec(ctx *core.Context) map[string]any {
 	return espec
 }
 
-// One Validate call. Errors are COLLECTED, never returned as one: struct
-// stops at the first failure unless given an errs collector, and a caller
-// fixing a payload wants every problem with it, not the first one.
 func (f *ValidateFeature) check(
 	ctx *core.Context, data any, spec any, direction string,
 ) []string {
@@ -294,12 +239,6 @@ func validateEntName(ctx *core.Context) string {
 	return ""
 }
 
-// A RESULT RECORD AS DATA.
-//
-// MakeResult turns every record of a LIST into an entity instance, so what
-// reaches PreDone for a list is wrappers, not records - and a wrapper checked
-// against a field spec fails on every required field while its actual data
-// goes unchecked. A load returns the record itself, so this handles both.
 func validateUnwrap(record any) any {
 	if ent, ok := record.(core.Entity); ok && ent != nil {
 		if data := ent.Data(); data != nil {
@@ -309,9 +248,6 @@ func validateUnwrap(record any) any {
 	return record
 }
 
-// The spec tree with every `$OPEN` marker removed, so an undeclared key is an
-// error rather than a pass. Rebuilt rather than mutated: core.ENTITYSPEC is a
-// package constant shared by every client in the process.
 func validateClose(node any) any {
 	switch n := node.(type) {
 	case []any:
@@ -322,8 +258,6 @@ func validateClose(node any) any {
 		return out
 
 	case map[string]any:
-		// Sorted, so a rebuilt spec is byte-stable when it is printed in an
-		// error - go map order is randomised per run.
 		keys := make([]string, 0, len(n))
 		for k := range n {
 			if validateOpenKey != k {

package/project/.sdk/tm/go/test/custom_utility_test.go

@@ -78,15 +78,6 @@ func TestCustomUtility(t *testing.T) {
 		}
 	})
 
-	// The half the subtest above cannot see. Those keys are ALIASES - `auth`,
-	// `body`, `spec` - and no utility member has those names, so landing in
-	// Custom is the right outcome for them and the assertion passes whether or
-	// not overriding works at all.
-	//
-	// A key that DOES name a member must replace it. That is the documented
-	// contract, it is what ts does, and it was silently absent here: every
-	// entry went to Custom, which nothing reads, so `utility: {"fetcher": ...}`
-	// did nothing while ts honoured it.
 	t.Run("a real utility member is replaced, not shelved", func(t *testing.T) {
 		reached := 0
 		scripted := func(ctx *sdk.Context, fullurl string, fetchdef map[string]any) (any, error) {
@@ -99,20 +90,6 @@ func TestCustomUtility(t *testing.T) {
 			}, nil
 		}
 
-		// NewProjectNameSDK, not TestSDK. The `test` feature is
-		// transport: 'base' - it REPLACES the transport by design - so a client
-		// in test mode would shadow the scripted fetcher and this would assert
-		// nothing.
-		//
-		// `scripted` is passed AS DECLARED, with no conversion to
-		// sdk.FetcherFunc. That is how a caller writes it, and it is the case
-		// that was broken: a plain function literal in a map[string]any has the
-		// unnamed signature, so an override that only accepted the named type
-		// shelved it in Custom. Converting here would have hidden that.
-		// "test" is the OPTION, not the `test` FEATURE: it says "this client
-		// is not live", so a REQUIRED OpenAPI server variable resolves to a
-		// deterministic test-<name> instead of panicking at construction. It
-		// installs no transport, so the override under test still stands.
 		client := sdk.NewProjectNameSDK(map[string]any{
 			"test":    map[string]any{"active": true},
 			"utility": map[string]any{"fetcher": scripted},
@@ -137,10 +114,6 @@ func TestCustomUtility(t *testing.T) {
 		}
 	})
 
-	// The other spelling of the same value. A caller who names the exported
-	// type gets a value whose dynamic type is core.FetcherFunc, which asserts
-	// to the named type and NOT to the unnamed signature - the mirror image of
-	// the subtest above, and broken by any fix that swaps one for the other.
 	t.Run("a converted fetcher is accepted too", func(t *testing.T) {
 		reached := 0
 		// "test" is the OPTION, not the `test` FEATURE: it says "this client
@@ -178,8 +151,6 @@ func TestCustomUtility(t *testing.T) {
 		}
 	})
 
-	// An unknown key must still be attached rather than dropped, so the two
-	// halves cannot be satisfied by a switch that also swallows extras.
 	t.Run("an unknown key is still attached", func(t *testing.T) {
 		// "test" is the OPTION, not the `test` FEATURE: it says "this client
 		// is not live", so a REQUIRED OpenAPI server variable resolves to a