Use Kubernetes declarative validation (#1215)

This mostly eliminates the need to hand-write validation code.

This PR is a long series of commits which add DV for most of Actor and
all of Atespace.

Here is a map to the commits:
* The first few take a dep on a new Kubernetes tag, import the code into
third_party, and apply a single patch. Because we have different Go
modules for tools, I had to do it twice. When that patch lands, we can
revert these commits, but that won't be until the 1.38 cycle in a few
months.
* The next commits slowly add DV support, so a human can review each of
them in a reasonable amount of time. The emphasis is on great test
cases.
* I made a bad choice early on as to where to generate the code into, so
I moved it. Rebasing on that was exceedingly hard, so I left it as a
move.
* This required changing update/go-generate -> update/codegen -- we need
to get the ordering of tools right, which `go generate` does not
guarantee.
* Then I added a "middle" layer called "ServiceImpl" between the RPC and
storage layers. This allows things like workflow to call the same
business logic as the RPC layer, including validation. Lots of test
fixes.
* Then I finished the Create() and Update() paths for Actor. Those
represent the "right" (or closest to) way to implement resources, and
tests for validation.

I strongly encourage reviewers to read it commit-by-commit. Rebasing
this is VERY tedious, so the sooner it lands or dies completely, the
better. Then we can start converting the rest.

`./hack/run-tool.sh validation-gen --docs` will produce some docs on the
tool and the available tags.

@laoj2 @juli4n @EItanya @HavenXia
@lalitc375 @yongruilin @jpbetz  FYI

vendor/github.com/go-openapi/jsonpointer/pointer.go

@@ -11,8 +11,6 @@ import (
 	"reflect"
 	"strconv"
 	"strings"
-
-	"github.com/go-openapi/swag/jsonname"
 )
 
 const (
@@ -20,20 +18,6 @@ const (
 	pointerSeparator = `/`
 )
 
-// JSONPointable is an interface for structs to implement,
-// when they need to customize the json pointer process or want to avoid the use of reflection.
-type JSONPointable interface {
-	// JSONLookup returns a value pointed at this (unescaped) key.
-	JSONLookup(key string) (any, error)
-}
-
-// JSONSetable is an interface for structs to implement,
-// when they need to customize the json pointer process or want to avoid the use of reflection.
-type JSONSetable interface {
-	// JSONSet sets the value pointed at the (unescaped) key.
-	JSONSet(key string, value any) error
-}
-
 // Pointer is a representation of a json pointer.
 //
 // Use [Pointer.Get] to retrieve a value or [Pointer.Set] to set a value.
@@ -41,7 +25,7 @@ type JSONSetable interface {
 // It works with any go type interpreted as a JSON document, which means:
 //
 //   - if a type implements [JSONPointable], its [JSONPointable.JSONLookup] method is used to resolve [Pointer.Get]
-//   - if a type implements [JSONSetable], its [JSONPointable.JSONSet] method is used to resolve [Pointer.Set]
+//   - if a type implements [JSONSetable], its [JSONSetable.JSONSet] method is used to resolve [Pointer.Set]
 //   - a go map[K]V is interpreted as an object, with type K assignable to a string
 //   - a go slice []T is interpreted as an array
 //   - a go struct is interpreted as an object, with exported fields interpreted as keys
@@ -50,7 +34,8 @@ type JSONSetable interface {
 //
 // For struct s resolved by reflection, key mappings honor the conventional struct tag `json`.
 //
-// Fields that do not specify a `json` tag, or specify an empty one, or are tagged as `json:"-"` are ignored.
+// Fields that do not specify a `json` tag, or specify an empty one, or are tagged as `json:"-"` are
+// ignored.
 //
 // # Limitations
 //
@@ -71,16 +56,36 @@ func New(jsonPointerString string) (Pointer, error) {
 // Get uses the pointer to retrieve a value from a JSON document.
 //
 // It returns the value with its type as a [reflect.Kind] or an error.
-func (p *Pointer) Get(document any) (any, reflect.Kind, error) {
-	return p.get(document, jsonname.DefaultJSONNameProvider)
+func (p *Pointer) Get(document any, opts ...Option) (any, reflect.Kind, error) {
+	o := optionsWithDefaults(opts)
+
+	return p.get(document, o.provider)
 }
 
-// Set uses the pointer to set a value from a data type
-// that represent a JSON document.
+// Set uses the pointer to set a value from a data type that represent a JSON document.
 //
-// It returns the updated document.
-func (p *Pointer) Set(document any, value any) (any, error) {
-	return document, p.set(document, value, jsonname.DefaultJSONNameProvider)
+// # Mutation contract
+//
+// Set mutates the provided document in place whenever Go's type system allows it: when document is
+// a map, a pointer, or when the targeted value is reached through an addressable ancestor (e.g. a
+// struct field traversed via a pointer, a slice element).
+//
+// Callers that rely on this in-place behavior may continue to ignore the returned document.
+//
+// The returned document is only load-bearing when Set cannot mutate in place.
+//
+// This happens in one specific case: appending to a top-level slice passed by value (e.g. document
+// of type []T rather than *[]T) via the RFC 6901 "-" terminal token. reflect.Append produces a new
+// slice header that the library cannot rebind into the caller's variable; the updated document is
+// returned instead.
+//
+// Pass *[]T if you want in-place rebind for that case as well.
+//
+// See [ErrDashToken] for the semantics of the "-" token.
+func (p *Pointer) Set(document any, value any, opts ...Option) (any, error) {
+	o := optionsWithDefaults(opts)
+
+	return p.set(document, value, o.provider)
 }
 
 // DecodedTokens returns the decoded (unescaped) tokens of this JSON pointer.
@@ -109,6 +114,46 @@ func (p *Pointer) String() string {
 	return pointerSeparator + strings.Join(p.referenceTokens, pointerSeparator)
 }
 
+// Offset returns the byte offset, in the raw JSON text of document, of the location referenced by
+// this pointer's terminal token.
+//
+// Unlike [Pointer.Get] and [Pointer.Set], which operate on a decoded Go value, Offset operates
+// directly on the textual JSON source.
+//
+// It drives an [encoding/json.Decoder] over the string and stops at the terminal token, returning
+// the position at which the decoder was about to read that token.
+//
+// It is primarily intended for tooling that needs to map a pointer back to a region of the original
+// source: reporting line/column for validation or parse diagnostics, extracting a sub-document by
+// slicing the raw bytes, or highlighting the referenced span in an editor.
+//
+// # Offset semantics
+//
+// The meaning of the returned offset depends on whether the terminal token addresses an object
+// property or an array element:
+//
+//   - Object property: the offset points to the first byte of the key (its
+//     opening quote character), not to the associated value. For example,
+//     pointer "/foo/bar" against {"foo": {"bar": 21}} returns 9, the index of
+//     the opening quote of "bar".
+//   - Array element: the offset points to the first byte of the value at that
+//     index. For example, pointer "/0/1" against [[1,2], [3,4]] returns 4,
+//     the index of the digit 2.
+//
+// # Errors
+//
+// Offset returns an error in any of these cases:
+//
+//   - document is not syntactically valid JSON;
+//   - the structure of document does not match the pointer (e.g. traversing
+//     into a scalar, or a token that is neither a valid key nor a valid
+//     numeric index);
+//   - a referenced key or index does not exist in document;
+//   - the pointer's terminal token is the RFC 6901 "-" array token, which
+//     designates a nonexistent element and therefore has no offset in the
+//     source. The returned error wraps [ErrDashToken].
+//
+// All errors wrap [ErrPointer].
 func (p *Pointer) Offset(document string) (int64, error) {
 	dec := json.NewDecoder(strings.NewReader(document))
 	var offset int64
@@ -137,7 +182,34 @@ func (p *Pointer) Offset(document string) (int64, error) {
 			return 0, fmt.Errorf("invalid token %#v: %w", tk, ErrPointer)
 		}
 	}
-	return offset, nil
+	return skipJSONSeparator(document, offset), nil
+}
+
+// skipJSONSeparator advances offset past trailing JSON whitespace and at most one value separator
+// (comma) in document, so the result points at the first byte of the next JSON token.
+//
+// The streaming decoder's InputOffset sits right after the most recently consumed token, which
+// between values is the comma (or whitespace) — not the following token.
+//
+// Normalizing here keeps Offset's contract uniform: for both object keys and array elements, and
+// regardless of position within the parent container, the returned offset always points at the
+// first byte of the addressed token.
+func skipJSONSeparator(document string, offset int64) int64 {
+	n := int64(len(document))
+	for offset < n && isJSONWhitespace(document[offset]) {
+		offset++
+	}
+	if offset < n && document[offset] == ',' {
+		offset++
+	}
+	for offset < n && isJSONWhitespace(document[offset]) {
+		offset++
+	}
+	return offset
+}
+
+func isJSONWhitespace(c byte) bool {
+	return c == ' ' || c == '\t' || c == '\n' || c == '\r'
 }
 
 // "Constructor", parses the given string JSON pointer.
@@ -157,9 +229,9 @@ func (p *Pointer) parse(jsonPointerString string) error {
 	return nil
 }
 
-func (p *Pointer) get(node any, nameProvider *jsonname.NameProvider) (any, reflect.Kind, error) {
+func (p *Pointer) get(node any, nameProvider NameProvider) (any, reflect.Kind, error) {
 	if nameProvider == nil {
-		nameProvider = jsonname.DefaultJSONNameProvider
+		nameProvider = defaultOptions.provider
 	}
 
 	kind := reflect.Invalid
@@ -185,50 +257,128 @@ func (p *Pointer) get(node any, nameProvider *jsonname.NameProvider) (any, refle
 	return node, kind, nil
 }
 
-func (p *Pointer) set(node, data any, nameProvider *jsonname.NameProvider) error {
+func (p *Pointer) set(node, data any, nameProvider NameProvider) (any, error) {
 	knd := reflect.ValueOf(node).Kind()
 
 	if knd != reflect.Pointer && knd != reflect.Struct && knd != reflect.Map && knd != reflect.Slice && knd != reflect.Array {
-		return errors.Join(
+		return node, errors.Join(
 			fmt.Errorf("unexpected type: %T", node), //nolint:err113 // err wrapping is carried out by errors.Join, not fmt.Errorf.
 			ErrUnsupportedValueType,
 			ErrPointer,
 		)
 	}
 
-	l := len(p.referenceTokens)
-
 	// full document when empty
-	if l == 0 {
-		return nil
+	if len(p.referenceTokens) == 0 {
+		return node, nil
 	}
 
 	if nameProvider == nil {
-		nameProvider = jsonname.DefaultJSONNameProvider
+		nameProvider = defaultOptions.provider
 	}
 
-	var decodedToken string
-	lastIndex := l - 1
-
-	if lastIndex > 0 { // skip if we only have one token in pointer
-		for _, token := range p.referenceTokens[:lastIndex] {
-			decodedToken = Unescape(token)
-			next, err := p.resolveNodeForToken(node, decodedToken, nameProvider)
-			if err != nil {
-				return err
-			}
-
-			node = next
-		}
-	}
-
-	// last token
-	decodedToken = Unescape(p.referenceTokens[lastIndex])
-
-	return setSingleImpl(node, data, decodedToken, nameProvider)
+	return p.setAt(node, p.referenceTokens, data, nameProvider)
 }
 
-func (p *Pointer) resolveNodeForToken(node any, decodedToken string, nameProvider *jsonname.NameProvider) (next any, err error) {
+// setAt recursively walks the token list, setting the data at the terminal token and rebinding any
+// new child reference (e.g. a slice header returned by an "-" append) into its parent on the way
+// back up.
+//
+// Returning the (possibly new) node at each level is what makes append work at any depth without
+// requiring the caller to pass a pointer to the containing slice: the new slice header propagates
+// up and each parent rebinds it via the appropriate kind-specific setter.
+func (p *Pointer) setAt(node any, tokens []string, data any, nameProvider NameProvider) (any, error) {
+	decodedToken := Unescape(tokens[0])
+
+	if len(tokens) == 1 {
+		return setSingleImpl(node, data, decodedToken, nameProvider)
+	}
+
+	child, err := p.resolveNodeForToken(node, decodedToken, nameProvider)
+	if err != nil {
+		return node, err
+	}
+
+	newChild, err := p.setAt(child, tokens[1:], data, nameProvider)
+	if err != nil {
+		return node, err
+	}
+
+	return rebindChild(node, decodedToken, newChild, nameProvider)
+}
+
+// rebindChild writes newChild back into node at decodedToken.
+//
+// For cases where the child was already mutated in place (pointer aliasing, addressable slice
+// elements) the rebind is a safe no-op.
+//
+// For cases where the child was returned by value (map entries holding a slice, slices reached
+// through a non-addressable ancestor), the rebind propagates the new value into the parent.
+//
+// Parents implementing [JSONPointable] are left alone: they took ownership of the child via
+// JSONLookup and did not opt into a JSONSet-based rebind on intermediate tokens.
+func rebindChild(node any, decodedToken string, newChild any, nameProvider NameProvider) (any, error) {
+	if _, ok := node.(JSONPointable); ok {
+		return node, nil
+	}
+
+	rValue := reflect.Indirect(reflect.ValueOf(node))
+
+	switch rValue.Kind() {
+	case reflect.Struct:
+		nm, ok := nameProvider.GetGoNameForType(rValue.Type(), decodedToken)
+		if !ok {
+			return node, fmt.Errorf("object has no field %q: %w", decodedToken, ErrPointer)
+		}
+		fld := rValue.FieldByName(nm)
+		if !fld.CanSet() {
+			return node, nil
+		}
+		assignReflectValue(fld, newChild)
+		return node, nil
+
+	case reflect.Map:
+		rValue.SetMapIndex(reflect.ValueOf(decodedToken), reflect.ValueOf(newChild))
+		return node, nil
+
+	case reflect.Slice:
+		if decodedToken == dashToken {
+			return node, errDashIntermediate()
+		}
+		idx, err := strconv.Atoi(decodedToken)
+		if err != nil {
+			return node, errors.Join(err, ErrPointer)
+		}
+		elem := rValue.Index(idx)
+		if !elem.CanSet() {
+			return node, nil
+		}
+		assignReflectValue(elem, newChild)
+		return node, nil
+
+	default:
+		return node, errInvalidReference(decodedToken)
+	}
+}
+
+// assignReflectValue assigns src into dst, unwrapping a pointer when dst expects the pointee type.
+//
+// This tolerates the pointer-wrapping performed by [typeFromValue] for addressable fields.
+func assignReflectValue(dst reflect.Value, src any) {
+	nv := reflect.ValueOf(src)
+	if !nv.IsValid() {
+		return
+	}
+	if nv.Type().AssignableTo(dst.Type()) {
+		dst.Set(nv)
+		return
+	}
+	if nv.Kind() == reflect.Pointer && nv.Elem().Type().AssignableTo(dst.Type()) {
+		dst.Set(nv.Elem())
+	}
+}
+
+func (p *Pointer) resolveNodeForToken(node any, decodedToken string, nameProvider NameProvider) (next any, err error) {
 	// check for nil during traversal
 	if isNil(node) {
 		return nil, fmt.Errorf("cannot traverse through nil value at %q: %w", decodedToken, ErrPointer)
@@ -272,6 +422,9 @@ func (p *Pointer) resolveNodeForToken(node any, decodedToken string, nameProvide
 		return typeFromValue(mv), nil
 
 	case reflect.Slice:
+		if decodedToken == dashToken {
+			return nil, errDashIntermediate()
+		}
 		tokenIndex, err := strconv.Atoi(decodedToken)
 		if err != nil {
 			return nil, errors.Join(err, ErrPointer)
@@ -312,16 +465,23 @@ func typeFromValue(v reflect.Value) any {
 }
 
 // GetForToken gets a value for a json pointer token 1 level deep.
-func GetForToken(document any, decodedToken string) (any, reflect.Kind, error) {
-	return getSingleImpl(document, decodedToken, jsonname.DefaultJSONNameProvider)
+func GetForToken(document any, decodedToken string, opts ...Option) (any, reflect.Kind, error) {
+	o := optionsWithDefaults(opts)
+
+	return getSingleImpl(document, decodedToken, o.provider)
 }
 
 // SetForToken sets a value for a json pointer token 1 level deep.
-func SetForToken(document any, decodedToken string, value any) (any, error) {
-	return document, setSingleImpl(document, value, decodedToken, jsonname.DefaultJSONNameProvider)
+//
+// See [Pointer.Set] for the mutation contract, in particular the handling of the RFC 6901 "-" token
+// on slices.
+func SetForToken(document any, decodedToken string, value any, opts ...Option) (any, error) {
+	o := optionsWithDefaults(opts)
+
+	return setSingleImpl(document, value, decodedToken, o.provider)
 }
 
-func getSingleImpl(node any, decodedToken string, nameProvider *jsonname.NameProvider) (any, reflect.Kind, error) {
+func getSingleImpl(node any, decodedToken string, nameProvider NameProvider) (any, reflect.Kind, error) {
 	rValue := reflect.Indirect(reflect.ValueOf(node))
 	kind := rValue.Kind()
 	if isNil(node) {
@@ -361,6 +521,9 @@ func getSingleImpl(node any, decodedToken string, nameProvider *jsonname.NamePro
 		return nil, kind, errNoKey(decodedToken)
 
 	case reflect.Slice:
+		if decodedToken == dashToken {
+			return nil, kind, errDashOnGet()
+		}
 		tokenIndex, err := strconv.Atoi(decodedToken)
 		if err != nil {
 			return nil, kind, errors.Join(err, ErrPointer)
@@ -378,14 +541,14 @@ func getSingleImpl(node any, decodedToken string, nameProvider *jsonname.NamePro
 	}
 }
 
-func setSingleImpl(node, data any, decodedToken string, nameProvider *jsonname.NameProvider) error {
+func setSingleImpl(node, data any, decodedToken string, nameProvider NameProvider) (any, error) {
 	// check for nil to prevent panic when calling rValue.Type()
 	if isNil(node) {
-		return fmt.Errorf("cannot set field %q on nil value: %w", decodedToken, ErrPointer)
+		return node, fmt.Errorf("cannot set field %q on nil value: %w", decodedToken, ErrPointer)
 	}
 
 	if ns, ok := node.(JSONSetable); ok {
-		return ns.JSONSet(decodedToken, data)
+		return node, ns.JSONSet(decodedToken, data)
 	}
 
 	rValue := reflect.Indirect(reflect.ValueOf(node))
@@ -394,12 +557,12 @@ func setSingleImpl(node, data any, decodedToken string, nameProvider *jsonname.N
 	case reflect.Struct:
 		nm, ok := nameProvider.GetGoNameForType(rValue.Type(), decodedToken)
 		if !ok {
-			return fmt.Errorf("object has no field %q: %w", decodedToken, ErrPointer)
+			return node, fmt.Errorf("object has no field %q: %w", decodedToken, ErrPointer)
 		}
 
 		fld := rValue.FieldByName(nm)
 		if !fld.CanSet() {
-			return fmt.Errorf("can't set struct field %s to %v: %w", nm, data, ErrPointer)
+			return node, fmt.Errorf("can't set struct field %s to %v: %w", nm, data, ErrPointer)
 		}
 
 		value := reflect.ValueOf(data)
@@ -407,33 +570,51 @@ func setSingleImpl(node, data any, decodedToken string, nameProvider *jsonname.N
 		assignedType := fld.Type()
 
 		if !valueType.AssignableTo(assignedType) {
-			return fmt.Errorf("can't set value with type %T to field %s with type %v: %w", data, nm, assignedType, ErrPointer)
+			return node, fmt.Errorf("can't set value with type %T to field %s with type %v: %w", data, nm, assignedType, ErrPointer)
 		}
 
 		fld.Set(value)
 
-		return nil
+		return node, nil
 
 	case reflect.Map:
 		kv := reflect.ValueOf(decodedToken)
 		rValue.SetMapIndex(kv, reflect.ValueOf(data))
 
-		return nil
+		return node, nil
 
 	case reflect.Slice:
+		if decodedToken == dashToken {
+			// RFC 6901 §4 / RFC 6902 append semantics: terminal "-" appends the value to the slice.
+			//
+			// We rebind in place when the slice is reachable via an addressable ancestor; otherwise we
+			// return the new slice header for the parent (or the public Set) to rebind.
+			value := reflect.ValueOf(data)
+			elemType := rValue.Type().Elem()
+			if !value.Type().AssignableTo(elemType) {
+				return node, fmt.Errorf("can't append value of type %T to slice of %v: %w", data, elemType, ErrPointer)
+			}
+			newSlice := reflect.Append(rValue, value)
+			if rValue.CanSet() {
+				rValue.Set(newSlice)
+				return node, nil
+			}
+			return newSlice.Interface(), nil
+		}
+
 		tokenIndex, err := strconv.Atoi(decodedToken)
 		if err != nil {
-			return errors.Join(err, ErrPointer)
+			return node, errors.Join(err, ErrPointer)
 		}
 
 		sLength := rValue.Len()
 		if tokenIndex < 0 || tokenIndex >= sLength {
-			return errOutOfBounds(sLength, tokenIndex)
+			return node, errOutOfBounds(sLength, tokenIndex)
 		}
 
 		elem := rValue.Index(tokenIndex)
 		if !elem.CanSet() {
-			return fmt.Errorf("can't set slice index %s to %v: %w", decodedToken, data, ErrPointer)
+			return node, fmt.Errorf("can't set slice index %s to %v: %w", decodedToken, data, ErrPointer)
 		}
 
 		value := reflect.ValueOf(data)
@@ -441,15 +622,15 @@ func setSingleImpl(node, data any, decodedToken string, nameProvider *jsonname.N
 		assignedType := elem.Type()
 
 		if !valueType.AssignableTo(assignedType) {
-			return fmt.Errorf("can't set value with type %T to slice element %d with type %v: %w", data, tokenIndex, assignedType, ErrPointer)
+			return node, fmt.Errorf("can't set value with type %T to slice element %d with type %v: %w", data, tokenIndex, assignedType, ErrPointer)
 		}
 
 		elem.Set(value)
 
-		return nil
+		return node, nil
 
 	default:
-		return errInvalidReference(decodedToken)
+		return node, errInvalidReference(decodedToken)
 	}
 }
 
@@ -460,24 +641,27 @@ func offsetSingleObject(dec *json.Decoder, decodedToken string) (int64, error) {
 		if err != nil {
 			return 0, err
 		}
-		switch tk := tk.(type) {
-		case json.Delim:
-			switch tk {
-			case '{':
-				if err = drainSingle(dec); err != nil {
-					return 0, err
-				}
-			case '[':
+		key, ok := tk.(string)
+		if !ok {
+			return 0, fmt.Errorf("invalid key token %#v: %w", tk, ErrPointer)
+		}
+		if key == decodedToken {
+			return offset, nil
+		}
+
+		// Consume the associated value.
+		// Scalars are fully read by a single Token() call; composite values must be drained.
+		tk, err = dec.Token()
+		if err != nil {
+			return 0, err
+		}
+		if delim, isDelim := tk.(json.Delim); isDelim {
+			switch delim {
+			case '{', '[':
 				if err = drainSingle(dec); err != nil {
 					return 0, err
 				}
 			}
-		case string:
-			if tk == decodedToken {
-				return offset, nil
-			}
-		default:
-			return 0, fmt.Errorf("invalid token %#v: %w", tk, ErrPointer)
 		}
 	}
 
@@ -485,6 +669,9 @@ func offsetSingleObject(dec *json.Decoder, decodedToken string) (int64, error) {
 }
 
 func offsetSingleArray(dec *json.Decoder, decodedToken string) (int64, error) {
+	if decodedToken == dashToken {
+		return 0, errDashOnOffset()
+	}
 	idx, err := strconv.Atoi(decodedToken)
 	if err != nil {
 		return 0, fmt.Errorf("token reference %q is not a number: %w: %w", decodedToken, err, ErrPointer)
@@ -548,10 +735,7 @@ func drainSingle(dec *json.Decoder) error {
 	return nil
 }
 
-// JSON pointer encoding:
-// ~0 => ~
-// ~1 => /
-// ... and vice versa
+// JSON pointer encoding: ~0 => ~ ~1 => / ... and vice versa.
 
 const (
 	encRefTok0 = `~0`