@ttsc/win32-arm64 0.33.0 → 0.34.0

package/bin/go/src/encoding/json/v2/{arshal_inlined.go → arshal_embedded.go}

@@ -19,30 +19,30 @@ import (
 	"encoding/json/jsontext"
 )
 
-// This package supports "inlining" a Go struct field, where the contents
+// This package supports "embedding" a Go struct field, where the contents
 // of the serialized field (which must be a JSON object) are treated as if
 // they are part of the parent Go struct (which represents a JSON object).
 //
-// Generally, inlined fields are of a Go struct type, where the fields of the
+// Generally, embedded fields are of a Go struct type, where the fields of the
 // nested struct are virtually hoisted up to the parent struct using rules
 // similar to how Go embedding works (but operating within the JSON namespace).
 //
-// However, inlined fields may also be of a Go map type with a string key or
-// a jsontext.Value. Such inlined fields are called "fallback" fields since they
+// However, embedded fields may also be of a Go map type with a string key or
+// a jsontext.Value. Such embedded fields are called "fallback" fields since they
 // represent any arbitrary JSON object member. Explicitly named fields take
-// precedence over the inlined fallback. Only one inlined fallback is allowed.
+// precedence over the embedded fallback. Only one embedded fallback is allowed.
 
-var errRawInlinedNotObject = errors.New("inlined raw value must be a JSON object")
+var errRawEmbedNotObject = errors.New("embedded raw value must be a JSON object")
 
 var jsontextValueType = reflect.TypeFor[jsontext.Value]()
 
-// marshalInlinedFallbackAll marshals all the members in an inlined fallback.
-func marshalInlinedFallbackAll(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct, f *structField, insertUnquotedName func([]byte) bool) error {
+// marshalEmbeddedFallbackAll marshals all the members in an embedded fallback.
+func marshalEmbeddedFallbackAll(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct, f *structField, insertUnquotedName func([]byte) bool) error {
 	v := addressableValue{va.Field(f.index0), va.forcedAddr} // addressable if struct value is addressable
 	if len(f.index) > 0 {
 		v = v.fieldByIndex(f.index, false)
 		if !v.IsValid() {
-			return nil // implies a nil inlined field
+			return nil // implies a nil embedded field
 		}
 	}
 	v = v.indirect(false)
@@ -69,7 +69,7 @@ func marshalInlinedFallbackAll(enc *jsontext.Encoder, va addressableValue, mo *j
 			return newMarshalErrorBefore(enc, v.Type(), err)
 		}
 		if tok.Kind() != '{' {
-			return newMarshalErrorBefore(enc, v.Type(), errRawInlinedNotObject)
+			return newMarshalErrorBefore(enc, v.Type(), errRawEmbedNotObject)
 		}
 		for dec.PeekKind() != '}' {
 			// Parse the JSON object name.
@@ -113,7 +113,7 @@ func marshalInlinedFallbackAll(enc *jsontext.Encoder, va addressableValue, mo *j
 		mk := newAddressableValue(m.Type().Key())
 		mv := newAddressableValue(m.Type().Elem())
 		marshalKey := func(mk addressableValue) error {
-			b, err := jsonwire.AppendQuote(enc.AvailableBuffer(), mk.String(), &mo.Flags)
+			b, err := jsonwire.AppendQuote(enc.AvailableBuffer(), []byte(mk.String()), &mo.Flags)
 			if err != nil {
 				return newMarshalErrorBefore(enc, m.Type().Key(), err)
 			}
@@ -165,8 +165,8 @@ func marshalInlinedFallbackAll(enc *jsontext.Encoder, va addressableValue, mo *j
 	}
 }
 
-// unmarshalInlinedFallbackNext unmarshals only the next member in an inlined fallback.
-func unmarshalInlinedFallbackNext(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct, f *structField, quotedName, unquotedName []byte) error {
+// unmarshalEmbeddedFallbackNext unmarshals only the next member in an embedded fallback.
+func unmarshalEmbeddedFallbackNext(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct, f *structField, quotedName, unquotedName []byte) error {
 	v := addressableValue{va.Field(f.index0), va.forcedAddr} // addressable if struct value is addressable
 	if len(f.index) > 0 {
 		v = v.fieldByIndex(f.index, true)
@@ -188,7 +188,7 @@ func unmarshalInlinedFallbackNext(dec *jsontext.Decoder, va addressableValue, uo
 					*b = append(*b, ',')
 				}
 			} else {
-				return newUnmarshalErrorAfterWithSkipping(dec, v.Type(), errRawInlinedNotObject)
+				return newUnmarshalErrorAfterWithSkipping(dec, v.Type(), errRawEmbedNotObject)
 			}
 		}
 		*b = append(*b, quotedName...)

package/bin/go/src/encoding/json/v2/arshal_funcs.go

@@ -19,16 +19,7 @@ import (
 	"encoding/json/jsontext"
 )
 
-// SkipFunc may be returned by [MarshalToFunc] and [UnmarshalFromFunc] functions.
-//
-// Any function that returns SkipFunc must not cause observable side effects
-// on the provided [jsontext.Encoder] or [jsontext.Decoder].
-// For example, it is permissible to call [jsontext.Decoder.PeekKind],
-// but not permissible to call [jsontext.Decoder.ReadToken] or
-// [jsontext.Encoder.WriteToken] since such methods mutate the state.
-var SkipFunc = errors.New("json: skip function")
-
-var errSkipMutation = errors.New("must not read or write any tokens when skipping")
+var errUnsupportedMutation = errors.New("unsupported calls must not read or write any tokens")
 var errNonSingularValue = errors.New("must read or write exactly one value")
 
 // Marshalers is a list of functions that may override the marshal behavior
@@ -41,7 +32,8 @@ type Marshalers = typedMarshalers
 // JoinMarshalers constructs a flattened list of marshal functions.
 // If multiple functions in the list are applicable for a value of a given type,
 // then those earlier in the list take precedence over those that come later.
-// If a function returns [SkipFunc], then the next applicable function is called,
+// If a function returns [errors.ErrUnsupported],
+// then the next applicable function is called,
 // otherwise the default marshaling behavior is used.
 //
 // For example:
@@ -63,7 +55,8 @@ type Unmarshalers = typedUnmarshalers
 // JoinUnmarshalers constructs a flattened list of unmarshal functions.
 // If multiple functions in the list are applicable for a value of a given type,
 // then those earlier in the list take precedence over those that come later.
-// If a function returns [SkipFunc], then the next applicable function is called,
+// If a function returns [errors.ErrUnsupported],
+// then the next applicable function is called,
 // otherwise the default unmarshaling behavior is used.
 //
 // For example:
@@ -151,7 +144,7 @@ func (a *typedArshalers[Coder]) lookup(fnc func(*Coder, addressableValue, *jsono
 	fncDefault := fnc
 	fnc = func(c *Coder, v addressableValue, o *jsonopts.Struct) error {
 		for _, fnc := range fncs {
-			if err := fnc(c, v, o); err != SkipFunc {
+			if err := fnc(c, v, o); !errors.Is(err, errors.ErrUnsupported) {
 				return err // may be nil or non-nil
 			}
 		}
@@ -169,9 +162,9 @@ func (a *typedArshalers[Coder]) lookup(fnc func(*Coder, addressableValue, *jsono
 // The function is always provided with a non-nil pointer value
 // if T is an interface or pointer type.
 //
-// The function must marshal exactly one JSON value.
-// The value of T must not be retained outside the function call.
-// It may not return [SkipFunc].
+// Implementations must follow the requirements of [Marshaler].
+//
+// Implementations must not retain the value of T.
 func MarshalFunc[T any](fn func(T) ([]byte, error)) *Marshalers {
 	t := reflect.TypeFor[T]()
 	assertCastableTo(t, true)
@@ -181,7 +174,7 @@ func MarshalFunc[T any](fn func(T) ([]byte, error)) *Marshalers {
 			v, _ := reflect.TypeAssert[T](va.castTo(t))
 			val, err := fn(v)
 			if err != nil {
-				err = wrapSkipFunc(err, "marshal function of type func(T) ([]byte, error)")
+				err = wrapErrUnsupported(err, "marshal function of type func(T) ([]byte, error)")
 				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalFunc") // unlike unmarshal, always wrapped
 				}
@@ -209,12 +202,10 @@ func MarshalFunc[T any](fn func(T) ([]byte, error)) *Marshalers {
 // The function is always provided with a non-nil pointer value
 // if T is an interface or pointer type.
 //
-// The function must marshal exactly one JSON value by calling write methods
-// on the provided encoder. It may return [SkipFunc] such that marshaling can
-// move on to the next marshal function. However, no mutable method calls may
-// be called on the encoder if [SkipFunc] is returned.
-// The pointer to [jsontext.Encoder] and the value of T
-// must not be retained outside the function call.
+// Implementations must follow the requirements of [MarshalerTo].
+//
+// Implementations must not retain the pointer to [jsontext.Encoder] or the
+// value of T.
 func MarshalToFunc[T any](fn func(*jsontext.Encoder, T) error) *Marshalers {
 	t := reflect.TypeFor[T]()
 	assertCastableTo(t, true)
@@ -232,11 +223,11 @@ func MarshalToFunc[T any](fn func(*jsontext.Encoder, T) error) *Marshalers {
 				err = errNonSingularValue
 			}
 			if err != nil {
-				if err == SkipFunc {
+				if errors.Is(err, errors.ErrUnsupported) {
 					if prevDepth == currDepth && prevLength == currLength {
-						return SkipFunc
+						return err // forward [errors.ErrUnsupported]
 					}
-					err = errSkipMutation
+					err = errUnsupportedMutation
 				}
 				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalToFunc") // unlike unmarshal, always wrapped
@@ -258,10 +249,9 @@ func MarshalToFunc[T any](fn func(*jsontext.Encoder, T) error) *Marshalers {
 // T must be an unnamed pointer or an interface type.
 // The function is always provided with a non-nil pointer value.
 //
-// The function must unmarshal exactly one JSON value.
-// The input []byte must not be mutated.
-// The input []byte and value T must not be retained outside the function call.
-// It may not return [SkipFunc].
+// Implementations must follow the requirements of [Unmarshaler].
+//
+// Implementations must not retain the value of T.
 func UnmarshalFunc[T any](fn func([]byte, T) error) *Unmarshalers {
 	t := reflect.TypeFor[T]()
 	assertCastableTo(t, false)
@@ -275,7 +265,7 @@ func UnmarshalFunc[T any](fn func([]byte, T) error) *Unmarshalers {
 			v, _ := reflect.TypeAssert[T](va.castTo(t))
 			err = fn(val, v)
 			if err != nil {
-				err = wrapSkipFunc(err, "unmarshal function of type func([]byte, T) error")
+				err = wrapErrUnsupported(err, "unmarshal function of type func([]byte, T) error")
 				if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return err // unlike marshal, never wrapped
 				}
@@ -293,12 +283,10 @@ func UnmarshalFunc[T any](fn func([]byte, T) error) *Unmarshalers {
 // T must be an unnamed pointer or an interface type.
 // The function is always provided with a non-nil pointer value.
 //
-// The function must unmarshal exactly one JSON value by calling read methods
-// on the provided decoder. It may return [SkipFunc] such that unmarshaling can
-// move on to the next unmarshal function. However, no mutable method calls may
-// be called on the decoder if [SkipFunc] is returned.
-// The pointer to [jsontext.Decoder] and the value of T
-// must not be retained outside the function call.
+// Implementations must follow the requirements of [UnmarshalerFrom].
+//
+// Implementations must not retain the pointer to [jsontext.Decoder] or the
+// value of T.
 func UnmarshalFromFunc[T any](fn func(*jsontext.Decoder, T) error) *Unmarshalers {
 	t := reflect.TypeFor[T]()
 	assertCastableTo(t, false)
@@ -319,11 +307,11 @@ func UnmarshalFromFunc[T any](fn func(*jsontext.Decoder, T) error) *Unmarshalers
 				err = errNonSingularValue
 			}
 			if err != nil {
-				if err == SkipFunc {
+				if errors.Is(err, errors.ErrUnsupported) {
 					if prevDepth == currDepth && prevLength == currLength {
-						return SkipFunc
+						return err // forward [errors.ErrUnsupported]
 					}
-					err = errSkipMutation
+					err = errUnsupportedMutation
 				}
 				if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					if err2 := xd.SkipUntil(prevDepth, prevLength+1); err2 != nil {
@@ -431,10 +419,3 @@ func castableToFromAny(to reflect.Type) bool {
 	}
 	return false
 }
-
-func wrapSkipFunc(err error, what string) error {
-	if err == SkipFunc {
-		return errors.New(what + " cannot be skipped")
-	}
-	return err
-}

package/bin/go/src/encoding/json/v2/arshal_methods.go

@@ -38,51 +38,81 @@ var (
 
 // Marshaler is implemented by types that can marshal themselves.
 // It is recommended that types implement [MarshalerTo] unless the implementation
-// is trying to avoid a hard dependency on the "jsontext" package.
+// is trying to avoid directly depending on the "jsontext" package.
 //
-// It is recommended that implementations return a buffer that is safe
+// Implementations should return a buffer that is safe
 // for the caller to retain and potentially mutate.
 //
+// Implementations must not return [errors.ErrUnsupported].
+//
 // If the returned error is a [SemanticError], then unpopulated fields
 // of the error may be populated by [json] with additional context.
 // Errors of other types are wrapped within a [SemanticError].
+//
+// Implementations should assume [Deterministic] is true and return
+// deterministic output.
 type Marshaler interface {
 	MarshalJSON() ([]byte, error)
 }
 
 // MarshalerTo is implemented by types that can marshal themselves.
 // It is recommended that types implement MarshalerTo instead of [Marshaler]
-// since this is both more performant and flexible.
+// since it is both more performant and more flexible.
 // If a type implements both Marshaler and MarshalerTo,
 // then MarshalerTo takes precedence. In such a case, both implementations
 // should aim to have equivalent behavior for the default marshal options.
 //
-// The implementation must write only one JSON value to the Encoder and
-// must not retain the pointer to [jsontext.Encoder].
+// The implementation must write only one JSON value to the Encoder.
+// Alternatively, it may return [errors.ErrUnsupported] without mutating
+// the Encoder. The "json" package calling the method will
+// use the next available JSON representation for the receiver type,
+// as described in [Marshal].
+// Implementations must not retain the pointer to [jsontext.Encoder].
 //
 // If the returned error is a [SemanticError], then unpopulated fields
 // of the error may be populated by [json] with additional context.
 // Errors of other types are wrapped within a [SemanticError],
-// unless it is an IO error.
+// except for IO errors.
+//
+// The MarshalJSONTo method should not be called directly as it may
+// return sentinel errors that need special handling.
+// Users should instead call [MarshalEncode], which handles such cases.
+//
+// Implementations should inspect the marshal options from
+// [jsontext.Encoder.Options] and adjust behavior to respect the options as
+// necessary.
+//
+// The following options may be relevant to MarshalerTo implementations:
+//
+// - [Deterministic]: if the implementation may produce non-deterministic output
+// - [StringifyNumbers]: if the type is represented as a JSON number
+//
+// Several options, such as [FormatNilSliceAsNull], apply only to native Go
+// types. Thus, these options are typically not directly relevant to
+// MarshalerTo implementations. However, types representing a composite type
+// should marshal contained types using [MarshalEncode] to ensure these options
+// apply to the contained types. Similarly, [WithMarshalers] may influence
+// marshaling of any contained type within a composite type.
+//
+// All other options are automatically handled outside of the MarshalerTo
+// implementation, and thus are not relevant to implementations.
 type MarshalerTo interface {
 	MarshalJSONTo(*jsontext.Encoder) error
-
-	// TODO: Should users call the MarshalEncode function or
-	// should/can they call this method directly? Does it matter?
 }
 
 // Unmarshaler is implemented by types that can unmarshal themselves.
 // It is recommended that types implement [UnmarshalerFrom] unless the implementation
-// is trying to avoid a hard dependency on the "jsontext" package.
+// is trying to avoid a direct dependency on the "jsontext" package.
 //
 // The input can be assumed to be a valid encoding of a JSON value
 // if called from unmarshal functionality in this package.
-// UnmarshalJSON must copy the JSON data if it is retained after returning.
-// It is recommended that UnmarshalJSON implement merge semantics when
-// unmarshaling into a pre-populated value.
+// It is recommended that UnmarshalJSON implement merge semantics
+// when unmarshaling into a pre-populated value, as described in [Unmarshal].
 //
 // Implementations must not retain or mutate the input []byte.
 //
+// Implementations must not return [errors.ErrUnsupported].
+//
 // If the returned error is a [SemanticError], then unpopulated fields
 // of the error may be populated by [json] with additional context.
 // Errors of other types are wrapped within a [SemanticError].
@@ -92,26 +122,47 @@ type Unmarshaler interface {
 
 // UnmarshalerFrom is implemented by types that can unmarshal themselves.
 // It is recommended that types implement UnmarshalerFrom instead of [Unmarshaler]
-// since this is both more performant and flexible.
+// since this is both more performant and more flexible.
 // If a type implements both Unmarshaler and UnmarshalerFrom,
 // then UnmarshalerFrom takes precedence. In such a case, both implementations
 // should aim to have equivalent behavior for the default unmarshal options.
 //
 // The implementation must read only one JSON value from the Decoder.
 // It is recommended that UnmarshalJSONFrom implement merge semantics when
-// unmarshaling into a pre-populated value.
-//
+// unmarshaling into a pre-populated value, as described in [Unmarshal].
+// Alternatively, it may return [errors.ErrUnsupported] without mutating
+// the Decoder. The "json" package calling the method will
+// use the next available JSON representation for the receiver type.
 // Implementations must not retain the pointer to [jsontext.Decoder].
 //
 // If the returned error is a [SemanticError], then unpopulated fields
 // of the error may be populated by [json] with additional context.
 // Errors of other types are wrapped within a [SemanticError],
-// unless it is a [jsontext.SyntacticError] or an IO error.
+// except for [jsontext.SyntacticError]s and IO errors.
+//
+// The UnmarshalJSONFrom method should not be called directly as it may
+// return sentinel errors that need special handling.
+// Users should instead call [UnmarshalDecode], which handles such cases.
+//
+// Implementations should inspect the unmarshal options from
+// [jsontext.Decoder.Options] and adjust behavior to respect the options as
+// necessary.
+//
+// The following options may be relevant to UnmarshalerFrom implementations:
+//
+// - [StringifyNumbers]: if the type is represented as a JSON number
+//
+// Several options, such as [FormatNilSliceAsNull], apply only to native Go
+// types. Thus, these options are typically not directly relevant to
+// UnmarshalerFrom implementations. However, types representing a composite
+// type should unmarshal contained types using [UnmarshalDecode] to ensure
+// these options apply to the contained types. Similarly, [WithUnmarshalers]
+// may influence unmarshaling of any contained type within a composite type.
+//
+// All other options are automatically handled outside of the UnmarshalerFrom
+// implementation, and thus are not relevant to implementations.
 type UnmarshalerFrom interface {
 	UnmarshalJSONFrom(*jsontext.Decoder) error
-
-	// TODO: Should users call the UnmarshalDecode function or
-	// should/can they call this method directly? Does it matter?
 }
 
 func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
@@ -127,7 +178,9 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		prevMarshal := fncs.marshal
 		fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
 			if mo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
-				(needAddr && va.forcedAddr) {
+				((needAddr && va.forcedAddr) ||
+					(export.Encoder(enc).Tokens.Last.NeedObjectName()) && t.Kind() == reflect.String) {
+				// Do not call MarshalText on unaddressable values and map keys of string kind.
 				return prevMarshal(enc, va, mo)
 			}
 			marshaler, _ := reflect.TypeAssert[encoding.TextMarshaler](va.Addr())
@@ -135,7 +188,7 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 				b2, err := marshaler.MarshalText()
 				return append(b, b2...), err
 			}); err != nil {
-				err = wrapSkipFunc(err, "marshal method")
+				err = wrapErrUnsupported(err, "MarshalText method")
 				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalText") // unlike unmarshal, always wrapped
 				}
@@ -153,12 +206,14 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		prevMarshal := fncs.marshal
 		fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) (err error) {
 			if mo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
-				(needAddr && va.forcedAddr) {
+				((needAddr && va.forcedAddr) ||
+					(export.Encoder(enc).Tokens.Last.NeedObjectName()) && t.Kind() == reflect.String) {
+				// Do not call AppendText on unaddressable values and map keys of string kind.
 				return prevMarshal(enc, va, mo)
 			}
 			appender, _ := reflect.TypeAssert[encoding.TextAppender](va.Addr())
 			if err := export.Encoder(enc).AppendRaw('"', false, appender.AppendText); err != nil {
-				err = wrapSkipFunc(err, "append method")
+				err = wrapErrUnsupported(err, "AppendText method")
 				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return internal.NewMarshalerError(va.Addr().Interface(), err, "AppendText") // unlike unmarshal, always wrapped
 				}
@@ -177,12 +232,13 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
 			if mo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
 				((needAddr && va.forcedAddr) || export.Encoder(enc).Tokens.Last.NeedObjectName()) {
+				// Do not call MarshalJSON on unaddressable values and map keys.
 				return prevMarshal(enc, va, mo)
 			}
 			marshaler, _ := reflect.TypeAssert[Marshaler](va.Addr())
 			val, err := marshaler.MarshalJSON()
 			if err != nil {
-				err = wrapSkipFunc(err, "marshal method")
+				err = wrapErrUnsupported(err, "MarshalJSON method")
 				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalJSON") // unlike unmarshal, always wrapped
 				}
@@ -208,6 +264,7 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
 			if mo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
 				((needAddr && va.forcedAddr) || export.Encoder(enc).Tokens.Last.NeedObjectName()) {
+				// Do not call MarshalJSONTo on unaddressable values and map keys.
 				return prevMarshal(enc, va, mo)
 			}
 			xe := export.Encoder(enc)
@@ -221,7 +278,12 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 				err = errNonSingularValue
 			}
 			if err != nil {
-				err = wrapSkipFunc(err, "marshal method")
+				if errors.Is(err, errors.ErrUnsupported) {
+					if prevDepth == currDepth && prevLength == currLength {
+						return prevMarshal(enc, va, mo)
+					}
+					err = errUnsupportedMutation
+				}
 				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalJSONTo") // unlike unmarshal, always wrapped
 				}
@@ -255,7 +317,7 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 			s := jsonwire.UnquoteMayCopy(val, flags.IsVerbatim())
 			unmarshaler, _ := reflect.TypeAssert[encoding.TextUnmarshaler](va.Addr())
 			if err := unmarshaler.UnmarshalText(s); err != nil {
-				err = wrapSkipFunc(err, "unmarshal method")
+				err = wrapErrUnsupported(err, "UnmarshalText method")
 				if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return err // unlike marshal, never wrapped
 				}
@@ -274,6 +336,7 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		fncs.unmarshal = func(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct) error {
 			if uo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
 				export.Decoder(dec).Tokens.Last.NeedObjectName() {
+				// Do not call UnmarshalJSON on map keys.
 				return prevUnmarshal(dec, va, uo)
 			}
 			val, err := dec.ReadValue()
@@ -282,7 +345,7 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 			}
 			unmarshaler, _ := reflect.TypeAssert[Unmarshaler](va.Addr())
 			if err := unmarshaler.UnmarshalJSON(val); err != nil {
-				err = wrapSkipFunc(err, "unmarshal method")
+				err = wrapErrUnsupported(err, "UnmarshalJSON method")
 				if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return err // unlike marshal, never wrapped
 				}
@@ -299,6 +362,7 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		fncs.unmarshal = func(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct) error {
 			if uo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
 				export.Decoder(dec).Tokens.Last.NeedObjectName() {
+				// Do not call UnmarshalJSONFrom on map keys.
 				return prevUnmarshal(dec, va, uo)
 			}
 			xd := export.Decoder(dec)
@@ -315,7 +379,12 @@ func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 				err = errNonSingularValue
 			}
 			if err != nil {
-				err = wrapSkipFunc(err, "unmarshal method")
+				if errors.Is(err, errors.ErrUnsupported) {
+					if prevDepth == currDepth && prevLength == currLength {
+						return prevUnmarshal(dec, va, uo)
+					}
+					err = errUnsupportedMutation
+				}
 				if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					if err2 := xd.SkipUntil(prevDepth, prevLength+1); err2 != nil {
 						return err2

package/bin/go/src/encoding/json/v2/arshal_time.go

@@ -46,7 +46,7 @@ func makeTimeArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
 			xe := export.Encoder(enc)
 			var m durationArshaler
-			if mo.Format != "" && mo.FormatDepth == xe.Tokens.Depth() {
+			if mo.Flags.Has(jsonflags.FormatTag) {
 				if !m.initFormat(mo.Format) {
 					return newInvalidFormatError(enc, t)
 				}
@@ -54,11 +54,18 @@ func makeTimeArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 				return marshalNano(enc, va, mo)
 			} else {
 				// TODO(https://go.dev/issue/71631): Decide on default duration representation.
-				return newMarshalErrorBefore(enc, t, errors.New("no default representation (see https://go.dev/issue/71631); specify an explicit format"))
+				var workaround string
+				if mo.Flags.Get(jsonflags.FormatTagSupported) {
+					workaround = "; specify an explicit format"
+				}
+				return newMarshalErrorBefore(enc, t, errors.New("no default representation"+workaround))
+			}
+			if mo.Flags.Get(jsonflags.StringTag) && !m.isNumeric() && !mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
+				return newMarshalErrorBefore(enc, t, errInvalidStringTag)
 			}
 
 			m.td, _ = reflect.TypeAssert[time.Duration](va.Value)
-			k := stringOrNumberKind(!m.isNumeric() || xe.Tokens.Last.NeedObjectName() || mo.Flags.Get(jsonflags.StringifyNumbers))
+			k := stringOrNumberKind(!m.isNumeric() || xe.Tokens.Last.NeedObjectName() || mo.Flags.Get(jsonflags.StringifyNumbers|jsonflags.StringTag))
 			if err := xe.AppendRaw(k, true, m.appendMarshal); err != nil {
 				if !isSyntacticError(err) && !export.IsIOError(err) {
 					err = newMarshalErrorBefore(enc, t, err)
@@ -71,7 +78,7 @@ func makeTimeArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		fncs.unmarshal = func(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct) error {
 			xd := export.Decoder(dec)
 			var u durationArshaler
-			if uo.Format != "" && uo.FormatDepth == xd.Tokens.Depth() {
+			if uo.Flags.Has(jsonflags.FormatTag) {
 				if !u.initFormat(uo.Format) {
 					return newInvalidFormatError(dec, t)
 				}
@@ -79,10 +86,17 @@ func makeTimeArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 				return unmarshalNano(dec, va, uo)
 			} else {
 				// TODO(https://go.dev/issue/71631): Decide on default duration representation.
-				return newUnmarshalErrorBeforeWithSkipping(dec, t, errors.New("no default representation (see https://go.dev/issue/71631); specify an explicit format"))
+				var workaround string
+				if uo.Flags.Get(jsonflags.FormatTagSupported) {
+					workaround = "; specify an explicit format"
+				}
+				return newUnmarshalErrorBeforeWithSkipping(dec, t, errors.New("no default representation"+workaround))
+			}
+			if uo.Flags.Get(jsonflags.StringTag) && !u.isNumeric() && !uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
+				return newUnmarshalErrorBeforeWithSkipping(dec, t, errInvalidStringTag)
 			}
 
-			stringify := !u.isNumeric() || xd.Tokens.Last.NeedObjectName() || uo.Flags.Get(jsonflags.StringifyNumbers)
+			stringify := !u.isNumeric() || xd.Tokens.Last.NeedObjectName() || uo.Flags.Get(jsonflags.StringifyNumbers|jsonflags.StringTag)
 			var flags jsonwire.ValueFlags
 			td, _ := reflect.TypeAssert[*time.Duration](va.Addr())
 			val, err := xd.ReadValue(&flags)
@@ -122,14 +136,17 @@ func makeTimeArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) (err error) {
 			xe := export.Encoder(enc)
 			var m timeArshaler
-			if mo.Format != "" && mo.FormatDepth == xe.Tokens.Depth() {
+			if mo.Flags.Has(jsonflags.FormatTag) {
 				if !m.initFormat(mo.Format) {
 					return newInvalidFormatError(enc, t)
 				}
 			}
+			if mo.Flags.Get(jsonflags.StringTag) && !m.isNumeric() && !mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
+				return newMarshalErrorBefore(enc, t, errInvalidStringTag)
+			}
 
 			m.tt, _ = reflect.TypeAssert[time.Time](va.Value)
-			k := stringOrNumberKind(!m.isNumeric() || xe.Tokens.Last.NeedObjectName() || mo.Flags.Get(jsonflags.StringifyNumbers))
+			k := stringOrNumberKind(!m.isNumeric() || xe.Tokens.Last.NeedObjectName() || mo.Flags.Get(jsonflags.StringifyNumbers|jsonflags.StringTag))
 			if err := xe.AppendRaw(k, !m.hasCustomFormat(), m.appendMarshal); err != nil {
 				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
 					return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalJSON") // unlike unmarshal, always wrapped
@@ -144,15 +161,18 @@ func makeTimeArshaler(fncs *arshaler, t reflect.Type) *arshaler {
 		fncs.unmarshal = func(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct) (err error) {
 			xd := export.Decoder(dec)
 			var u timeArshaler
-			if uo.Format != "" && uo.FormatDepth == xd.Tokens.Depth() {
+			if uo.Flags.Has(jsonflags.FormatTag) {
 				if !u.initFormat(uo.Format) {
 					return newInvalidFormatError(dec, t)
 				}
 			} else if uo.Flags.Get(jsonflags.ParseTimeWithLooseRFC3339) {
 				u.looseRFC3339 = true
 			}
+			if uo.Flags.Get(jsonflags.StringTag) && !u.isNumeric() && !uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
+				return newUnmarshalErrorBeforeWithSkipping(dec, t, errInvalidStringTag)
+			}
 
-			stringify := !u.isNumeric() || xd.Tokens.Last.NeedObjectName() || uo.Flags.Get(jsonflags.StringifyNumbers)
+			stringify := !u.isNumeric() || xd.Tokens.Last.NeedObjectName() || uo.Flags.Get(jsonflags.StringifyNumbers|jsonflags.StringTag)
 			var flags jsonwire.ValueFlags
 			tt, _ := reflect.TypeAssert[*time.Time](va.Addr())
 			val, err := xd.ReadValue(&flags)
@@ -494,7 +514,7 @@ var errInaccurateDateUnits = errors.New("inaccurate year, month, week, or day un
 //     between the integer part and fraction part of a number,
 //     as specified in ISO 8601-1:2019, section 3.2.6.
 //     While ISO 8601 recommends comma as the default separator,
-//     most formatters uses a period.
+//     most formatters use a period.
 //
 //   - Leading zeros are ignored. This is not required by ISO 8601,
 //     but also not forbidden by the standard. Many parsers support this.
@@ -512,7 +532,7 @@ var errInaccurateDateUnits = errors.New("inaccurate year, month, week, or day un
 // We follow JavaScript's grammar as JSON itself is derived from JavaScript.
 // The Temporal.Duration.toJSON method is guaranteed to produce an output
 // that can be parsed by this function so long as arithmetic in JavaScript
-// do not use a largestUnit value higher than "hours" (which is the default).
+// does not use a largestUnit value higher than "hours" (which is the default).
 // Even if it does, this will do a best-effort parsing with inaccurate units,
 // but report [errInaccurateDateUnits].
 func parseDurationISO8601(b []byte) (time.Duration, error) {
@@ -539,7 +559,7 @@ func parseDurationISO8601(b []byte) (time.Duration, error) {
 		}
 
 		// Parse the number.
-		// A fraction allowed for the accurate units in the last part.
+		// A fraction is allowed for the accurate units in the last part.
 		whole, frac, ok := cutBytes(number, '.', ',')
 		if ok {
 			sawFrac = true