Add Unmarshal support for structs using established syntax

[andreimerlescu]

Unmarshal Functionality

This is the unmarshal.go file that can be placed into the branch for testing. Thank you Claude for generating this.

// In types.go or figtree.go — add to the Fruit interface
type Fruit interface {
    // ... existing methods ...
    Unmarshal(target interface{}) error
}

The Unmarshal(target interface()) error method

// unmarshal.go
package figtree

import (
	"fmt"
	"reflect"
	"strconv"
	"strings"
	"time"
)

// ============================================================================
// TAG CONSTANTS — freeze these, they are public API
// ============================================================================

const (
	tagFig    = "fig"
	tagAssure = "assure"

	// Shared across multiple mutageneses (resolved by field type)
	tokenNotEmpty  = "notEmpty"
	tokenPositive  = "positive"
	tokenNegative  = "negative"
	tokenLength    = "length"
	tokenNotLength = "notLength"
	tokenInRange   = "inRange"
	tokenGt        = "gt"
	tokenLt        = "lt"
	tokenMin       = "min"
	tokenMax       = "max"
	tokenContains  = "contains"
	tokenNotContains = "notContains"
	tokenMinLength = "minLength"

	// String-only
	tokenSubstring   = "substring"
	tokenHasPrefix   = "hasPrefix"
	tokenHasSuffix   = "hasSuffix"
	tokenNoPrefix    = "noPrefix"
	tokenNoSuffix    = "noSuffix"
	tokenNoPrefixes  = "noPrefixes"
	tokenNoSuffixes  = "noSuffixes"

	// Bool-only
	tokenTrue  = "true"
	tokenFalse = "false"

	// Float64-only
	tokenNotNaN = "notNaN"

	// Duration-only (gt/lt/min/max reused, resolved by type)

	// List-only
	tokenContainsKey = "containsKey"

	// Map-only
	tokenHasKey      = "hasKey"
	tokenHasKeys     = "hasKeys"
	tokenValueMatches = "valueMatches"
)

// ============================================================================
// UNMARSHAL ERRORS
// ============================================================================

// UnmarshalError describes a failure during Unmarshal, including which
// struct field and which assure token caused the problem.
type UnmarshalError struct {
	Field     string // struct field name
	FigKey    string // fig tag value
	Token     string // assure token that failed, empty if not a validation error
	Cause     error
}

func (e *UnmarshalError) Error() string {
	if e.Token != "" {
		return fmt.Sprintf(
			"figtree: unmarshal validation failed on field %q (fig:%q) token %q: %v",
			e.Field, e.FigKey, e.Token, e.Cause,
		)
	}
	return fmt.Sprintf(
		"figtree: unmarshal failed on field %q (fig:%q): %v",
		e.Field, e.FigKey, e.Cause,
	)
}

func (e *UnmarshalError) Unwrap() error { return e.Cause }

// ============================================================================
// UNMARSHAL — primary entry point
// ============================================================================

// Unmarshal populates a struct from the figtree using `fig` and `assure`
// struct tags. The target must be a non-nil pointer to a struct.
//
// Example:
//
//	type Config struct {
//	    Host    string        `fig:"host"    assure:"notEmpty|hasPrefix=https://"`
//	    Port    int           `fig:"port"    assure:"gt=1023|lt=65536"`
//	    Timeout time.Duration `fig:"timeout" assure:"min=5s|max=2m"`
//	}
//	var cfg Config
//	err := figs.Unmarshal(&cfg)
func (t *tree) Unmarshal(target interface{}) error {
	if target == nil {
		return fmt.Errorf("figtree: Unmarshal target must not be nil")
	}

	rv := reflect.ValueOf(target)
	if rv.Kind() != reflect.Ptr || rv.IsNil() {
		return fmt.Errorf("figtree: Unmarshal target must be a non-nil pointer to a struct")
	}

	rv = rv.Elem()
	if rv.Kind() != reflect.Struct {
		return fmt.Errorf("figtree: Unmarshal target must point to a struct, got %s", rv.Kind())
	}

	return t.unmarshalStruct(rv)
}

// unmarshalStruct walks every field of a struct via reflection.
func (t *tree) unmarshalStruct(rv reflect.Value) error {
	rt := rv.Type()

	for i := 0; i < rt.NumField(); i++ {
		field := rt.Field(i)
		fieldVal := rv.Field(i)

		// Skip unexported fields
		if !fieldVal.CanSet() {
			continue
		}

		// Recurse into embedded or nested structs that have no fig tag
		figKey := strings.TrimSpace(field.Tag.Get(tagFig))
		if figKey == "" {
			if field.Type.Kind() == reflect.Struct {
				if err := t.unmarshalStruct(fieldVal); err != nil {
					return err
				}
			}
			continue
		}

		assureTag := strings.TrimSpace(field.Tag.Get(tagAssure))

		if err := t.unmarshalField(field, fieldVal, figKey, assureTag); err != nil {
			return err
		}
	}

	return nil
}

// unmarshalField resolves the fig value, sets the field, then validates.
func (t *tree) unmarshalField(
	field reflect.StructField,
	fieldVal reflect.Value,
	figKey string,
	assureTag string,
) error {
	fieldType := field.Type

	// Resolve the raw value from the tree by field type
	if err := t.setFieldFromTree(field, fieldVal, figKey, fieldType); err != nil {
		return &UnmarshalError{
			Field:  field.Name,
			FigKey: figKey,
			Cause:  err,
		}
	}

	// Run assure validators if tag is present
	if assureTag == "" {
		return nil
	}

	tokens := strings.Split(assureTag, "|")
	for _, raw := range tokens {
		raw = strings.TrimSpace(raw)
		if raw == "" {
			continue
		}
		validator, err := resolveToken(raw, fieldType, fieldVal)
		if err != nil {
			return &UnmarshalError{
				Field:  field.Name,
				FigKey: figKey,
				Token:  raw,
				Cause:  err,
			}
		}
		if err := validator(fieldVal.Interface()); err != nil {
			return &UnmarshalError{
				Field:  field.Name,
				FigKey: figKey,
				Token:  raw,
				Cause:  err,
			}
		}
	}

	return nil
}

// ============================================================================
// SET FIELD FROM TREE
// ============================================================================

var durationType = reflect.TypeOf(time.Duration(0))
var listFlagType = reflect.TypeOf((*ListFlag)(nil))
var mapFlagType  = reflect.TypeOf((*MapFlag)(nil))

// setFieldFromTree reads the registered fig value and sets it onto the
// reflected struct field. Supported field types mirror the mutagenesis table.
func (t *tree) setFieldFromTree(
	field reflect.StructField,
	fieldVal reflect.Value,
	figKey string,
	fieldType reflect.Type,
) error {
	switch {
	// ---- string ----
	case fieldType.Kind() == reflect.String:
		p := t.String(figKey)
		if p == nil {
			return nil
		}
		fieldVal.SetString(*p)

	// ---- bool ----
	case fieldType.Kind() == reflect.Bool:
		p := t.Bool(figKey)
		if p == nil {
			return nil
		}
		fieldVal.SetBool(*p)

	// ---- int ----
	case fieldType.Kind() == reflect.Int &&
		fieldType != durationType:
		p := t.Int(figKey)
		if p == nil {
			return nil
		}
		fieldVal.SetInt(int64(*p))

	// ---- int64 ----
	case fieldType.Kind() == reflect.Int64 &&
		fieldType != durationType:
		p := t.Int64(figKey)
		if p == nil {
			return nil
		}
		fieldVal.SetInt(*p)

	// ---- float64 ----
	case fieldType.Kind() == reflect.Float64:
		p := t.Float64(figKey)
		if p == nil {
			return nil
		}
		fieldVal.SetFloat(*p)

	// ---- time.Duration ----
	case fieldType == durationType:
		p := t.Duration(figKey)
		if p == nil {
			return nil
		}
		fieldVal.Set(reflect.ValueOf(*p))

	// ---- []string / *[]string / *ListFlag ----
	case fieldType == reflect.TypeOf([]string{}):
		p := t.List(figKey)
		if p == nil {
			return nil
		}
		fieldVal.Set(reflect.ValueOf(*p))

	case fieldType == reflect.TypeOf(map[string]string{}):
		p := t.Map(figKey)
		if p == nil {
			return nil
		}
		fieldVal.Set(reflect.ValueOf(*p))

	default:
		return fmt.Errorf("unsupported field type %s for fig key %q", fieldType, figKey)
	}

	return nil
}

// ============================================================================
// TOKEN RESOLVER
// ============================================================================

// resolveToken parses a single pipe-segment from the assure tag and returns
// a ValidatorFunc bound to any arguments extracted from the token.
// The fieldType is used to disambiguate shared token names (e.g. "positive",
// "notEmpty", "length") that apply to multiple mutageneses.
func resolveToken(token string, fieldType reflect.Type, fieldVal reflect.Value) (ValidatorFunc, error) {
	// Split on first '=' to separate name from argument(s)
	name, arg, hasArg := strings.Cut(token, "=")
	name = strings.ToLower(strings.TrimSpace(name))

	kind := fieldType.Kind()
	isDuration := fieldType == durationType
	isList := fieldType == reflect.TypeOf([]string{})
	isMap  := fieldType == reflect.TypeOf(map[string]string{})

	switch name {

	// =========================================================
	// SHARED: notEmpty
	// =========================================================
	case tokenNotEmpty:
		switch {
		case kind == reflect.String:
			return wrapAssure(token, AssureStringNotEmpty), nil
		case isList:
			return wrapAssure(token, AssureListNotEmpty), nil
		case isMap:
			return wrapAssure(token, AssureMapNotEmpty), nil
		default:
			return nil, fmt.Errorf("token %q not applicable to type %s", token, fieldType)
		}

	// =========================================================
	// SHARED: positive
	// =========================================================
	case tokenPositive:
		switch {
		case kind == reflect.Int:
			return wrapAssure(token, AssurePositiveInt), nil
		case kind == reflect.Int64 && !isDuration:
			return wrapAssure(token, AssurePositiveInt64), nil
		case kind == reflect.Float64:
			return wrapAssure(token, AssureFloat64Positive), nil
		case isDuration:
			return wrapAssure(token, AssureDurationPositive), nil
		default:
			return nil, fmt.Errorf("token %q not applicable to type %s", token, fieldType)
		}

	// =========================================================
	// SHARED: negative
	// =========================================================
	case tokenNegative:
		switch {
		case kind == reflect.Int:
			return wrapAssure(token, AssureNegativeInt), nil
		default:
			return nil, fmt.Errorf("token %q only applies to tInt, got %s", token, fieldType)
		}

	// =========================================================
	// SHARED: length=N
	// =========================================================
	case tokenLength:
		n, err := requireInt(token, arg, hasArg)
		if err != nil {
			return nil, err
		}
		switch {
		case kind == reflect.String:
			return wrapAssure(token, AssureStringLength(n)), nil
		case isList:
			return wrapAssure(token, AssureListLength(n)), nil
		case isMap:
			return wrapAssure(token, AssureMapLength(n)), nil
		default:
			return nil, fmt.Errorf("token %q not applicable to type %s", token, fieldType)
		}

	// =========================================================
	// SHARED: notLength=N
	// =========================================================
	case tokenNotLength:
		n, err := requireInt(token, arg, hasArg)
		if err != nil {
			return nil, err
		}
		switch {
		case kind == reflect.String:
			return wrapAssure(token, AssureStringNotLength(n)), nil
		case isList:
			return wrapAssure(token, AssureListNotLength(n)), nil
		case isMap:
			return wrapAssure(token, AssureMapNotLength(n)), nil
		default:
			return nil, fmt.Errorf("token %q not applicable to type %s", token, fieldType)
		}

	// =========================================================
	// SHARED: gt=N (Int, Int64, Float64, Duration)
	// =========================================================
	case tokenGt:
		switch {
		case kind == reflect.Int:
			n, err := requireInt(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureIntGreaterThan(n)), nil
		case kind == reflect.Int64 && !isDuration:
			n, err := requireInt64(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureInt64GreaterThan(n)), nil
		case kind == reflect.Float64:
			f, err := requireFloat64(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureFloat64GreaterThan(f)), nil
		case isDuration:
			d, err := requireDuration(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureDurationGreaterThan(d)), nil
		default:
			return nil, fmt.Errorf("token %q not applicable to type %s", token, fieldType)
		}

	// =========================================================
	// SHARED: lt=N (Int, Int64, Float64, Duration)
	// =========================================================
	case tokenLt:
		switch {
		case kind == reflect.Int:
			n, err := requireInt(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureIntLessThan(n)), nil
		case kind == reflect.Int64 && !isDuration:
			n, err := requireInt64(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureInt64LessThan(n)), nil
		case kind == reflect.Float64:
			f, err := requireFloat64(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureFloat64LessThan(f)), nil
		case isDuration:
			d, err := requireDuration(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureDurationLessThan(d)), nil
		default:
			return nil, fmt.Errorf("token %q not applicable to type %s", token, fieldType)
		}

	// =========================================================
	// SHARED: inRange=N,M (Int, Int64, Float64)
	// =========================================================
	case tokenInRange:
		switch {
		case kind == reflect.Int:
			lo, hi, err := requireIntRange(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureIntInRange(lo, hi)), nil
		case kind == reflect.Int64 && !isDuration:
			lo, hi, err := requireInt64Range(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureInt64InRange(lo, hi)), nil
		case kind == reflect.Float64:
			lo, hi, err := requireFloat64Range(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureFloat64InRange(lo, hi)), nil
		default:
			return nil, fmt.Errorf("token %q not applicable to type %s", token, fieldType)
		}

	// =========================================================
	// SHARED: min=X (Duration only — Int uses gt/inRange)
	// =========================================================
	case tokenMin:
		switch {
		case isDuration:
			d, err := requireDuration(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureDurationMin(d)), nil
		default:
			return nil, fmt.Errorf("token %q only applies to Duration, got %s", token, fieldType)
		}

	// =========================================================
	// SHARED: max=X (Duration only)
	// =========================================================
	case tokenMax:
		switch {
		case isDuration:
			d, err := requireDuration(token, arg, hasArg)
			if err != nil {
				return nil, err
			}
			return wrapAssure(token, AssureDurationMax(d)), nil
		default:
			return nil, fmt.Errorf("token %q only applies to Duration, got %s", token, fieldType)
		}

	// =========================================================
	// SHARED: contains=X (String, List)
	// =========================================================
	case tokenContains:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a value argument", token)
		}
		switch {
		case kind == reflect.String:
			return wrapAssure(token, AssureStringContains(arg)), nil
		case isList:
			return wrapAssure(token, AssureListContains(arg)), nil
		default:
			return nil, fmt.Errorf("token %q not applicable to type %s", token, fieldType)
		}

	// =========================================================
	// SHARED: notContains=X (String, List)
	// =========================================================
	case tokenNotContains:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a value argument", token)
		}
		switch {
		case kind == reflect.String:
			return wrapAssure(token, AssureStringNotContains(arg)), nil
		case isList:
			return wrapAssure(token, AssureListNotContains(arg)), nil
		default:
			return nil, fmt.Errorf("token %q not applicable to type %s", token, fieldType)
		}

	// =========================================================
	// SHARED: minLength=N (List only — String uses length)
	// =========================================================
	case tokenMinLength:
		n, err := requireInt(token, arg, hasArg)
		if err != nil {
			return nil, err
		}
		switch {
		case isList:
			return wrapAssure(token, AssureListMinLength(n)), nil
		default:
			return nil, fmt.Errorf("token %q only applies to tList, got %s", token, fieldType)
		}

	// =========================================================
	// STRING ONLY
	// =========================================================
	case tokenSubstring:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a value argument", token)
		}
		if kind != reflect.String {
			return nil, fmt.Errorf("token %q only applies to tString, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureStringSubstring(arg)), nil

	case tokenHasPrefix:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a value argument", token)
		}
		if kind != reflect.String {
			return nil, fmt.Errorf("token %q only applies to tString, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureStringHasPrefix(arg)), nil

	case tokenHasSuffix:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a value argument", token)
		}
		if kind != reflect.String {
			return nil, fmt.Errorf("token %q only applies to tString, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureStringHasSuffix(arg)), nil

	case tokenNoPrefix:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a value argument", token)
		}
		if kind != reflect.String {
			return nil, fmt.Errorf("token %q only applies to tString, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureStringNoPrefix(arg)), nil

	case tokenNoSuffix:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a value argument", token)
		}
		if kind != reflect.String {
			return nil, fmt.Errorf("token %q only applies to tString, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureStringNoSuffix(arg)), nil

	case tokenNoPrefixes:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a comma-separated value argument", token)
		}
		if kind != reflect.String {
			return nil, fmt.Errorf("token %q only applies to tString, got %s", token, fieldType)
		}
		parts := splitComma(arg)
		return wrapAssure(token, AssureStringNoPrefixes(parts)), nil

	case tokenNoSuffixes:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a comma-separated value argument", token)
		}
		if kind != reflect.String {
			return nil, fmt.Errorf("token %q only applies to tString, got %s", token, fieldType)
		}
		parts := splitComma(arg)
		return wrapAssure(token, AssureStringNoSuffixes(parts)), nil

	// =========================================================
	// BOOL ONLY
	// =========================================================
	case tokenTrue:
		if kind != reflect.Bool {
			return nil, fmt.Errorf("token %q only applies to tBool, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureBoolTrue), nil

	case tokenFalse:
		if kind != reflect.Bool {
			return nil, fmt.Errorf("token %q only applies to tBool, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureBoolFalse), nil

	// =========================================================
	// FLOAT64 ONLY
	// =========================================================
	case tokenNotNaN:
		if kind != reflect.Float64 {
			return nil, fmt.Errorf("token %q only applies to tFloat64, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureFloat64NotNaN), nil

	// =========================================================
	// LIST ONLY
	// =========================================================
	case tokenContainsKey:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a value argument", token)
		}
		if !isList {
			return nil, fmt.Errorf("token %q only applies to tList, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureListContainsKey(arg)), nil

	// =========================================================
	// MAP ONLY
	// =========================================================
	case tokenHasKey:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a value argument", token)
		}
		if !isMap {
			return nil, fmt.Errorf("token %q only applies to tMap, got %s", token, fieldType)
		}
		return wrapAssure(token, AssureMapHasKey(arg)), nil

	case tokenHasKeys:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a comma-separated value argument", token)
		}
		if !isMap {
			return nil, fmt.Errorf("token %q only applies to tMap, got %s", token, fieldType)
		}
		parts := splitComma(arg)
		return wrapAssure(token, AssureMapHasKeys(parts)), nil

	case tokenValueMatches:
		if !hasArg {
			return nil, fmt.Errorf("token %q requires a K:V argument", token)
		}
		if !isMap {
			return nil, fmt.Errorf("token %q only applies to tMap, got %s", token, fieldType)
		}
		k, v, ok := strings.Cut(arg, ":")
		if !ok {
			return nil, fmt.Errorf("token %q argument must be K:V format, got %q", token, arg)
		}
		return wrapAssure(token, AssureMapValueMatches(k, v)), nil

	default:
		return nil, fmt.Errorf("figtree: unknown assure token %q for type %s", token, fieldType)
	}
}

// ============================================================================
// ARGUMENT PARSERS — helpers for typed argument extraction
// ============================================================================

func requireInt(token, arg string, hasArg bool) (int, error) {
	if !hasArg || arg == "" {
		return 0, fmt.Errorf("token %q requires an integer argument", token)
	}
	n, err := strconv.Atoi(strings.TrimSpace(arg))
	if err != nil {
		return 0, fmt.Errorf("token %q argument %q is not a valid integer: %w", token, arg, err)
	}
	return n, nil
}

func requireInt64(token, arg string, hasArg bool) (int64, error) {
	if !hasArg || arg == "" {
		return 0, fmt.Errorf("token %q requires an int64 argument", token)
	}
	n, err := strconv.ParseInt(strings.TrimSpace(arg), 10, 64)
	if err != nil {
		return 0, fmt.Errorf("token %q argument %q is not a valid int64: %w", token, arg, err)
	}
	return n, nil
}

func requireFloat64(token, arg string, hasArg bool) (float64, error) {
	if !hasArg || arg == "" {
		return 0, fmt.Errorf("token %q requires a float64 argument", token)
	}
	f, err := strconv.ParseFloat(strings.TrimSpace(arg), 64)
	if err != nil {
		return 0, fmt.Errorf("token %q argument %q is not a valid float64: %w", token, arg, err)
	}
	return f, nil
}

func requireDuration(token, arg string, hasArg bool) (time.Duration, error) {
	if !hasArg || arg == "" {
		return 0, fmt.Errorf("token %q requires a duration argument (e.g. 5s, 2m, 1h)", token)
	}
	d, err := time.ParseDuration(strings.TrimSpace(arg))
	if err != nil {
		return 0, fmt.Errorf("token %q argument %q is not a valid duration: %w", token, arg, err)
	}
	return d, nil
}

func requireIntRange(token, arg string, hasArg bool) (int, int, error) {
	if !hasArg || arg == "" {
		return 0, 0, fmt.Errorf("token %q requires a N,M range argument", token)
	}
	lo, hi, err := splitRange(arg)
	if err != nil {
		return 0, 0, fmt.Errorf("token %q: %w", token, err)
	}
	loN, err := strconv.Atoi(lo)
	if err != nil {
		return 0, 0, fmt.Errorf("token %q lower bound %q is not a valid integer: %w", token, lo, err)
	}
	hiN, err := strconv.Atoi(hi)
	if err != nil {
		return 0, 0, fmt.Errorf("token %q upper bound %q is not a valid integer: %w", token, hi, err)
	}
	return loN, hiN, nil
}

func requireInt64Range(token, arg string, hasArg bool) (int64, int64, error) {
	lo, hi, err := splitRange(arg)
	if err != nil {
		return 0, 0, fmt.Errorf("token %q: %w", token, err)
	}
	loN, err := strconv.ParseInt(lo, 10, 64)
	if err != nil {
		return 0, 0, fmt.Errorf("token %q lower bound %q is not a valid int64: %w", token, lo, err)
	}
	hiN, err := strconv.ParseInt(hi, 10, 64)
	if err != nil {
		return 0, 0, fmt.Errorf("token %q upper bound %q is not a valid int64: %w", token, hi, err)
	}
	return loN, hiN, nil
}

func requireFloat64Range(token, arg string, hasArg bool) (float64, float64, error) {
	lo, hi, err := splitRange(arg)
	if err != nil {
		return 0, 0, fmt.Errorf("token %q: %w", token, err)
	}
	loF, err := strconv.ParseFloat(lo, 64)
	if err != nil {
		return 0, 0, fmt.Errorf("token %q lower bound %q is not a valid float64: %w", token, lo, err)
	}
	hiF, err := strconv.ParseFloat(hi, 64)
	if err != nil {
		return 0, 0, fmt.Errorf("token %q upper bound %q is not a valid float64: %w", token, hi, err)
	}
	return loF, hiF, nil
}

// splitRange splits "N,M" into ("N", "M") with whitespace trimmed.
func splitRange(arg string) (string, string, error) {
	parts := strings.SplitN(arg, ",", 2)
	if len(parts) != 2 {
		return "", "", fmt.Errorf("range argument %q must be in N,M format", arg)
	}
	return strings.TrimSpace(parts[0]), strings.TrimSpace(parts[1]), nil
}

// splitComma splits "A,B,C" into ["A","B","C"] with whitespace trimmed.
func splitComma(arg string) []string {
	parts := strings.Split(arg, ",")
	out := make([]string, 0, len(parts))
	for _, p := range parts {
		p = strings.TrimSpace(p)
		if p != "" {
			out = append(out, p)
		}
	}
	return out
}

// ============================================================================
// WRAP ASSURE
// ============================================================================

// wrapAssure adapts any figtree AssureFunc into a ValidatorFunc that receives
// the already-reflected interface{} value from the struct field. This is the
// bridge between the tag-parsed validators and the existing assure system.
func wrapAssure(token string, fn ValidatorFunc) (ValidatorFunc, error) {
	if fn == nil {
		return nil, fmt.Errorf("figtree: nil ValidatorFunc for token %q", token)
	}
	return fn, nil
}

All 36 Validators as Struct Tags

Here is the full mapping of every existing AssureFunc into the proposed assure:"" tag DSL, with the tag token, its equivalent function, and example usage.

String Validators (tString)

Tag Token	Equivalent AssureFunc	Example Tag
notEmpty	AssureStringNotEmpty	assure:"notEmpty"
length=N	AssureStringLength(N)	assure:"length=8"
notLength=N	AssureStringNotLength(N)	assure:"notLength=0"
contains=X	AssureStringContains(X)	assure:"contains=admin"
notContains=X	AssureStringNotContains(X)	assure:"notContains=drop"
substring=X	AssureStringSubstring(X)	assure:"substring=https"
hasPrefix=X	AssureStringHasPrefix(X)	assure:"hasPrefix=https://"
hasSuffix=X	AssureStringHasSuffix(X)	assure:"hasSuffix=.com"
noPrefix=X	AssureStringNoPrefix(X)	assure:"noPrefix=http://"
noSuffix=X	AssureStringNoSuffix(X)	assure:"noSuffix=.exe"
noPrefixes=X,Y	AssureStringNoPrefixes([]string)	assure:"noPrefixes=http://,ftp://"
noSuffixes=X,Y	AssureStringNoSuffixes([]string)	assure:"noSuffixes=.exe,.bat"

Pipe-chained example:

type ServerConfig struct {
    Endpoint string `fig:"endpoint" assure:"notEmpty|hasPrefix=https://|hasSuffix=.com|notContains=localhost"`
}

Bool Validators (tBool)

Tag Token	Equivalent AssureFunc	Example Tag
true	AssureBoolTrue	assure:"true"
false	AssureBoolFalse	assure:"false"

Example:

type FeatureFlags struct {
    ProductionMode bool `fig:"production" assure:"true"`
    DebugMode      bool `fig:"debug"      assure:"false"`
}

Int Validators (tInt)

Tag Token	Equivalent AssureFunc	Example Tag
positive	AssurePositiveInt	assure:"positive"
negative	AssureNegativeInt	assure:"negative"
gt=N	AssureIntGreaterThan(N)	assure:"gt=0"
lt=N	AssureIntLessThan(N)	assure:"lt=65535"
inRange=N,M	AssureIntInRange(N,M)	assure:"inRange=1024,49151"

Example:

type NetworkConfig struct {
    Port    int `fig:"port"    assure:"gt=1023|lt=65536"`
    Workers int `fig:"workers" assure:"positive|inRange=1,128"`
}

Int64 Validators (tInt64)

Tag Token	Equivalent AssureFunc	Example Tag
positive	AssurePositiveInt64	assure:"positive"
gt=N	AssureInt64GreaterThan(N)	assure:"gt=0"
lt=N	AssureInt64LessThan(N)	assure:"lt=1000000"
inRange=N,M	AssureInt64InRange(N,M)	assure:"inRange=1,9999999"

Note: positive and negative are shared token names with tInt — the parser resolves which AssureFunc to call based on the struct field’s reflected type, so there’s no collision.

Example:

type RetryConfig struct {
    MaxAttempts int64 `fig:"maxRetries" assure:"positive|lt=100"`
    BackoffMs   int64 `fig:"backoffMs"  assure:"gt=0|inRange=100,30000"`
}

Float64 Validators (tFloat64)

Tag Token	Equivalent AssureFunc	Example Tag
positive	AssureFloat64Positive	assure:"positive"
notNaN	AssureFloat64NotNaN	assure:"notNaN"
gt=N	AssureFloat64GreaterThan(N)	assure:"gt=0.0"
lt=N	AssureFloat64LessThan(N)	assure:"lt=1.0"
inRange=N,M	AssureFloat64InRange(N,M)	assure:"inRange=0.0,1.0"

Example:

type ThresholdConfig struct {
    Confidence float64 `fig:"confidence" assure:"notNaN|positive|inRange=0.0,1.0"`
    SampleRate float64 `fig:"sampleRate"  assure:"gt=0.0|lt=100.0"`
}

Duration Validators (tDuration / tUnitDuration)

Tag Token	Equivalent AssureFunc	Example Tag
positive	AssureDurationPositive	assure:"positive"
gt=Xs	AssureDurationGreaterThan(d)	assure:"gt=5s"
lt=Xs	AssureDurationLessThan(d)	assure:"lt=1h"
min=Xs	AssureDurationMin(d)	assure:"min=10s"
max=Xs	AssureDurationMax(d)	assure:"max=12h"

The duration token values use Go’s native time.ParseDuration format (5s, 2m, 1h30m, etc.) so no new syntax is needed.

Example:

type TimeoutConfig struct {
    RequestTimeout time.Duration `fig:"timeout"  assure:"positive|min=5s|max=2m"`
    PollInterval   time.Duration `fig:"interval" assure:"gt=30s|lt=1h"`
}

List Validators (tList)

Tag Token	Equivalent AssureFunc	Example Tag
notEmpty	AssureListNotEmpty	assure:"notEmpty"
minLength=N	AssureListMinLength(N)	assure:"minLength=1"
length=N	AssureListLength(N)	assure:"length=3"
notLength=N	AssureListNotLength(N)	assure:"notLength=0"
contains=X	AssureListContains(X)	assure:"contains=primary"
notContains=X	AssureListNotContains(X)	assure:"notContains=localhost"
containsKey=X	AssureListContainsKey(X)	assure:"containsKey=admin"

Example:

type ClusterConfig struct {
    Servers []string `fig:"servers" assure:"notEmpty|minLength=2|notContains=localhost"`
}

Map Validators (tMap)

Tag Token	Equivalent AssureFunc	Example Tag
notEmpty	AssureMapNotEmpty	assure:"notEmpty"
hasKey=X	AssureMapHasKey(X)	assure:"hasKey=env"
hasKeys=X,Y	AssureMapHasKeys([]string)	assure:"hasKeys=env,version"
length=N	AssureMapLength(N)	assure:"length=2"
notLength=N	AssureMapNotLength(N)	assure:"notLength=0"
valueMatches=K:V	AssureMapValueMatches(K,V)	assure:"valueMatches=env:prod"

Example:

type MetaConfig struct {
    Labels map[string]string `fig:"labels" assure:"notEmpty|hasKeys=env,version|valueMatches=env:prod"`
}

Token Parser Design

The internal parser for the assure tag would work like this:

func parseAssureTag(tag string, fieldType reflect.Type) ([]ValidatorFunc, error) {
    tokens := strings.Split(tag, "|")
    var validators []ValidatorFunc
    for _, token := range tokens {
        fn, err := resolveToken(token, fieldType)
        if err != nil {
            return nil, fmt.Errorf("unknown assure token %q for type %s", token, fieldType)
        }
        validators = append(validators, fn)
    }
    return validators, nil
}

resolveToken does a two-pass lookup: first by token prefix (e.g., gt=, hasKey=, inRange=), then by exact match (notEmpty, positive, true). Type is used to disambiguate shared token names like positive and notEmpty which appear across multiple mutageneses.

The Critical Constraint You Already Identified
The DSL you freeze now is a public API. Every token name is a promise. Before shipping this, the recommendation is to write the complete token registry as a const block — one const per token string — so that any future rename is a compile-time break rather than a silent behavioral change. Something like:

const (
    AssureNotEmpty    = "notEmpty"
    AssureLength      = "length"
    AssureGt          = "gt"
    AssureLt          = "lt"
    AssureInRange     = "inRange"
    AssureHasPrefix   = "hasPrefix"
    // ...
)

That way the DSL is defined in one place, documented in one place, and testable as a table in one place. It also makes the fig:"name" and assure:"notEmpty" struct tag story feel as intentional and complete as encoding/json does — which is exactly the standard library bar you want to clear.​​​​​​​​​​​​​​​​

Example of All 36 Validators In Use

package main

import (
    "log"
    "time"
    "github.com/andreimerlescu/figtree/v2"
)

// All 36 validators exercised across a realistic config struct

type DatabaseConfig struct {
    Host     string `fig:"db-host" assure:"notEmpty|hasPrefix=postgres://|noSuffix=.test"`
    Name     string `fig:"db-name" assure:"notEmpty|length=8|notContains=drop"`
    Schema   string `fig:"db-schema" assure:"hasPrefix=sc_|hasSuffix=_v1|notEmpty"`
    Password string `fig:"db-password" assure:"notEmpty|noPrefix=password|noPrefixes=pass,secret,admin"`
    Encoding string `fig:"db-encoding" assure:"hasSuffix=8|noSuffixes=ascii,latin1"`
    Tag      string `fig:"db-tag" assure:"substring=prod"`
}

type WorkerConfig struct {
    Count      int           `fig:"workers"    assure:"positive|inRange=1,128"`
    Port       int           `fig:"port"       assure:"gt=1023|lt=65536"`
    Offset     int           `fig:"offset"     assure:"negative"`
    MaxRetries int64         `fig:"maxRetries" assure:"positive|gt=0|lt=100"`
    BatchSize  int64         `fig:"batchSize"  assure:"inRange=1,10000"`
    Timeout    time.Duration `fig:"timeout"    assure:"positive|min=5s|max=2m"`
    Interval   time.Duration `fig:"interval"   assure:"gt=30s|lt=1h"`
}

type ThresholdConfig struct {
    Confidence float64 `fig:"confidence" assure:"positive|notNaN|inRange=0.0,1.0"`
    SampleRate float64 `fig:"sampleRate" assure:"gt=0.0|lt=100.0"`
}

type FeatureConfig struct {
    ProductionMode bool `fig:"production" assure:"true"`
    DebugMode      bool `fig:"debug"      assure:"false"`
}

type InfraConfig struct {
    Servers []string          `fig:"servers"  assure:"notEmpty|minLength=2|notContains=localhost|containsKey=primary"`
    Labels  map[string]string `fig:"labels"   assure:"notEmpty|hasKeys=env,version|hasKey=region|valueMatches=env:prod"`
}

type AppConfig struct {
    Database   DatabaseConfig
    Workers    WorkerConfig
    Thresholds ThresholdConfig
    Features   FeatureConfig
    Infra      InfraConfig
}

func main() {
    figs := figtree.Grow()

    // Register all figs
    figs.NewString("db-host", "postgres://localhost/mydb", "Database host")
    figs.NewString("db-name", "mydbname", "Database name")
    figs.NewString("db-schema", "sc_public_v1", "Database schema")
    figs.NewString("db-password", "s3cur3pass!", "Database password")
    figs.NewString("db-encoding", "utf8", "Database encoding")
    figs.NewString("db-tag", "prod-replica", "Database tag")
    figs.NewInt("workers", 8, "Worker count")
    figs.NewInt("port", 5432, "Port")
    figs.NewInt("offset", -1, "Offset")
    figs.NewInt64("maxRetries", 5, "Max retries")
    figs.NewInt64("batchSize", 500, "Batch size")
    figs.NewDuration("timeout", 30*time.Second, "Request timeout")
    figs.NewDuration("interval", 2*time.Minute, "Poll interval")
    figs.NewFloat64("confidence", 0.95, "Confidence threshold")
    figs.NewFloat64("sampleRate", 10.0, "Sample rate")
    figs.NewBool("production", true, "Production mode")
    figs.NewBool("debug", false, "Debug mode")
    figs.NewList("servers", []string{"primary", "replica-1"}, "Server list")
    figs.NewMap("labels", map[string]string{
        "env":     "prod",
        "version": "2.0",
        "region":  "us-east-1",
    }, "Infra labels")

    if err := figs.Parse(); err != nil {
        log.Fatal(err)
    }

    var cfg AppConfig
    if err := figs.Unmarshal(&cfg); err != nil {
        log.Fatalf("config invalid: %v", err)
    }

    log.Printf("Database host: %s", cfg.Database.Host)
    log.Printf("Workers: %d", cfg.Workers.Count)
    log.Printf("Confidence: %.2f", cfg.Thresholds.Confidence)
}

[andreimerlescu]

Testing Unmarshal unmarshal_test.go

package figtree

import (
	"testing"
	"time"

	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/require"
)

// ============================================================================
// TEST STRUCTS
// All structs in this file are the living documentation of how to use
// Unmarshal() with the assure tag DSL. Each struct is intentionally named
// and commented so that future consumers can read the test file as a guide.
// ============================================================================

// --- String structs ---

type unmarshalStringNotEmpty struct {
	Name string `fig:"name" assure:"notEmpty"`
}

type unmarshalStringLength struct {
	Code string `fig:"code" assure:"length=4"`
}

type unmarshalStringNotLength struct {
	Tag string `fig:"tag" assure:"notLength=0"`
}

type unmarshalStringContains struct {
	Email string `fig:"email" assure:"contains=@"`
}

type unmarshalStringNotContains struct {
	Query string `fig:"query" assure:"notContains=drop"`
}

type unmarshalStringSubstring struct {
	URL string `fig:"url" assure:"substring=https"`
}

type unmarshalStringHasPrefix struct {
	Endpoint string `fig:"endpoint" assure:"hasPrefix=https://"`
}

type unmarshalStringHasSuffix struct {
	Domain string `fig:"domain" assure:"hasSuffix=.com"`
}

type unmarshalStringNoPrefix struct {
	Endpoint string `fig:"endpoint" assure:"noPrefix=http://"`
}

type unmarshalStringNoSuffix struct {
	Filename string `fig:"filename" assure:"noSuffix=.exe"`
}

type unmarshalStringNoPrefixes struct {
	Endpoint string `fig:"endpoint" assure:"noPrefixes=http://,ftp://"`
}

type unmarshalStringNoSuffixes struct {
	Filename string `fig:"filename" assure:"noSuffixes=.exe,.bat"`
}

// --- Bool structs ---

type unmarshalBoolTrue struct {
	Production bool `fig:"production" assure:"true"`
}

type unmarshalBoolFalse struct {
	Debug bool `fig:"debug" assure:"false"`
}

// --- Int structs ---

type unmarshalIntPositive struct {
	Workers int `fig:"workers" assure:"positive"`
}

type unmarshalIntNegative struct {
	Offset int `fig:"offset" assure:"negative"`
}

type unmarshalIntGt struct {
	Port int `fig:"port" assure:"gt=1023"`
}

type unmarshalIntLt struct {
	Port int `fig:"port" assure:"lt=65536"`
}

type unmarshalIntInRange struct {
	Port int `fig:"port" assure:"inRange=1024,65535"`
}

// --- Int64 structs ---

type unmarshalInt64Positive struct {
	MaxRetries int64 `fig:"maxRetries" assure:"positive"`
}

type unmarshalInt64Gt struct {
	BatchSize int64 `fig:"batchSize" assure:"gt=0"`
}

type unmarshalInt64Lt struct {
	BatchSize int64 `fig:"batchSize" assure:"lt=10001"`
}

type unmarshalInt64InRange struct {
	BatchSize int64 `fig:"batchSize" assure:"inRange=1,10000"`
}

// --- Float64 structs ---

type unmarshalFloat64Positive struct {
	Rate float64 `fig:"rate" assure:"positive"`
}

type unmarshalFloat64NotNaN struct {
	Score float64 `fig:"score" assure:"notNaN"`
}

type unmarshalFloat64Gt struct {
	Confidence float64 `fig:"confidence" assure:"gt=0.0"`
}

type unmarshalFloat64Lt struct {
	Confidence float64 `fig:"confidence" assure:"lt=1.1"`
}

type unmarshalFloat64InRange struct {
	Confidence float64 `fig:"confidence" assure:"inRange=0.0,1.0"`
}

// --- Duration structs ---

type unmarshalDurationPositive struct {
	Timeout time.Duration `fig:"timeout" assure:"positive"`
}

type unmarshalDurationGt struct {
	Timeout time.Duration `fig:"timeout" assure:"gt=4s"`
}

type unmarshalDurationLt struct {
	Timeout time.Duration `fig:"timeout" assure:"lt=2m"`
}

type unmarshalDurationMin struct {
	Timeout time.Duration `fig:"timeout" assure:"min=5s"`
}

type unmarshalDurationMax struct {
	Timeout time.Duration `fig:"timeout" assure:"max=12h"`
}

// --- List structs ---

type unmarshalListNotEmpty struct {
	Servers []string `fig:"servers" assure:"notEmpty"`
}

type unmarshalListMinLength struct {
	Servers []string `fig:"servers" assure:"minLength=2"`
}

type unmarshalListLength struct {
	Servers []string `fig:"servers" assure:"length=3"`
}

type unmarshalListNotLength struct {
	Servers []string `fig:"servers" assure:"notLength=0"`
}

type unmarshalListContains struct {
	Servers []string `fig:"servers" assure:"contains=primary"`
}

type unmarshalListNotContains struct {
	Servers []string `fig:"servers" assure:"notContains=localhost"`
}

type unmarshalListContainsKey struct {
	Roles []string `fig:"roles" assure:"containsKey=admin"`
}

// --- Map structs ---

type unmarshalMapNotEmpty struct {
	Labels map[string]string `fig:"labels" assure:"notEmpty"`
}

type unmarshalMapHasKey struct {
	Labels map[string]string `fig:"labels" assure:"hasKey=env"`
}

type unmarshalMapHasKeys struct {
	Labels map[string]string `fig:"labels" assure:"hasKeys=env,version"`
}

type unmarshalMapLength struct {
	Labels map[string]string `fig:"labels" assure:"length=2"`
}

type unmarshalMapNotLength struct {
	Labels map[string]string `fig:"labels" assure:"notLength=0"`
}

type unmarshalMapValueMatches struct {
	Labels map[string]string `fig:"labels" assure:"valueMatches=env:prod"`
}

// --- Nested struct (documents recursion behaviour) ---

type unmarshalNestedInner struct {
	Port int `fig:"port" assure:"gt=1023|lt=65536"`
}

type unmarshalNestedOuter struct {
	Name  string               `fig:"name" assure:"notEmpty"`
	Inner unmarshalNestedInner // no fig tag — recursed into automatically
}

// --- Chained validators (documents pipe syntax) ---

type unmarshalChainedString struct {
	Endpoint string `fig:"endpoint" assure:"notEmpty|hasPrefix=https://|hasSuffix=.com|notContains=localhost"`
}

type unmarshalChainedInt struct {
	Port int `fig:"port" assure:"gt=1023|lt=65536|positive"`
}

// --- Full AppConfig (living documentation of real-world usage) ---

type unmarshalDatabaseConfig struct {
	Host     string `fig:"db-host"     assure:"notEmpty|hasPrefix=postgres://|noSuffix=.test"`
	Name     string `fig:"db-name"     assure:"notEmpty|notContains=drop"`
	Schema   string `fig:"db-schema"   assure:"hasPrefix=sc_|hasSuffix=_v1|notEmpty"`
	Password string `fig:"db-password" assure:"notEmpty|noPrefix=password|noPrefixes=pass,secret,admin"`
	Encoding string `fig:"db-encoding" assure:"hasSuffix=8|noSuffixes=ascii,latin1"`
	Tag      string `fig:"db-tag"      assure:"substring=prod"`
}

type unmarshalWorkerConfig struct {
	Count      int           `fig:"workers"    assure:"positive|inRange=1,128"`
	Port       int           `fig:"port"       assure:"gt=1023|lt=65536"`
	Offset     int           `fig:"offset"     assure:"negative"`
	MaxRetries int64         `fig:"maxRetries" assure:"positive|gt=0|lt=100"`
	BatchSize  int64         `fig:"batchSize"  assure:"inRange=1,10000"`
	Timeout    time.Duration `fig:"timeout"    assure:"positive|min=5s|max=2m"`
	Interval   time.Duration `fig:"interval"   assure:"gt=30s|lt=1h"`
}

type unmarshalThresholdConfig struct {
	Confidence float64 `fig:"confidence" assure:"positive|notNaN|inRange=0.0,1.0"`
	SampleRate float64 `fig:"sampleRate" assure:"gt=0.0|lt=100.0"`
}

type unmarshalFeatureConfig struct {
	ProductionMode bool `fig:"production" assure:"true"`
	DebugMode      bool `fig:"debug"      assure:"false"`
}

type unmarshalInfraConfig struct {
	Servers []string          `fig:"servers" assure:"notEmpty|minLength=2|notContains=localhost|containsKey=primary"`
	Labels  map[string]string `fig:"labels"  assure:"notEmpty|hasKeys=env,version|hasKey=region|valueMatches=env:prod"`
}

type unmarshalAppConfig struct {
	Database   unmarshalDatabaseConfig
	Workers    unmarshalWorkerConfig
	Thresholds unmarshalThresholdConfig
	Features   unmarshalFeatureConfig
	Infra      unmarshalInfraConfig
}

// ============================================================================
// HELPERS
// ============================================================================

// buildAppFigs registers all figs needed by unmarshalAppConfig and returns
// a parsed Plant. It is the canonical "full registration" example.
func buildAppFigs(t *testing.T) Plant {
	t.Helper()
	figs := With(Options{Germinate: true})
	figs = figs.NewString("db-host", "postgres://db.example.com/mydb", "Database host")
	figs = figs.NewString("db-name", "mydbname", "Database name")
	figs = figs.NewString("db-schema", "sc_public_v1", "Database schema")
	figs = figs.NewString("db-password", "s3cur3pass!", "Database password")
	figs = figs.NewString("db-encoding", "utf8", "Database encoding")
	figs = figs.NewString("db-tag", "prod-replica", "Database tag")
	figs = figs.NewInt("workers", 8, "Worker count")
	figs = figs.NewInt("port", 5432, "Port")
	figs = figs.NewInt("offset", -1, "Offset")
	figs = figs.NewInt64("maxRetries", 5, "Max retries")
	figs = figs.NewInt64("batchSize", 500, "Batch size")
	figs = figs.NewDuration("timeout", 30*time.Second, "Request timeout")
	figs = figs.NewDuration("interval", 2*time.Minute, "Poll interval")
	figs = figs.NewFloat64("confidence", 0.95, "Confidence threshold")
	figs = figs.NewFloat64("sampleRate", 10.0, "Sample rate")
	figs = figs.NewBool("production", true, "Production mode")
	figs = figs.NewBool("debug", false, "Debug mode")
	figs = figs.NewList("servers", []string{"primary", "replica-1"}, "Server list")
	figs = figs.NewMap("labels", map[string]string{
		"env":     "prod",
		"version": "2.0",
		"region":  "us-east-1",
	}, "Infra labels")
	require.NoError(t, figs.Parse())
	return figs
}

// ============================================================================
// GUARD TESTS — Unmarshal() input validation
// ============================================================================

func TestUnmarshal_NilTarget_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	require.NoError(t, figs.Parse())
	err := figs.Unmarshal(nil)
	assert.Error(t, err)
	assert.Contains(t, err.Error(), "nil")
}

func TestUnmarshal_NonPointerTarget_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	require.NoError(t, figs.Parse())
	type S struct{ Name string `fig:"name"` }
	err := figs.Unmarshal(S{})
	assert.Error(t, err)
	assert.Contains(t, err.Error(), "pointer")
}

func TestUnmarshal_PointerToNonStruct_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	require.NoError(t, figs.Parse())
	s := "not a struct"
	err := figs.Unmarshal(&s)
	assert.Error(t, err)
	assert.Contains(t, err.Error(), "struct")
}

func TestUnmarshal_NilPointer_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	require.NoError(t, figs.Parse())
	type S struct{ Name string `fig:"name"` }
	var s *S
	err := figs.Unmarshal(s)
	assert.Error(t, err)
}

func TestUnmarshal_UnknownToken_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "andrei", "name")
	require.NoError(t, figs.Parse())
	type S struct {
		Name string `fig:"name" assure:"doesNotExist"`
	}
	var s S
	err := figs.Unmarshal(&s)
	assert.Error(t, err)
	assert.Contains(t, err.Error(), "doesNotExist")
}

func TestUnmarshal_UnexportedFieldsSkipped(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "andrei", "name")
	require.NoError(t, figs.Parse())
	type S struct {
		Name    string `fig:"name"`
		private string `fig:"name"` //nolint:unused
	}
	var s S
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, "andrei", s.Name)
}

func TestUnmarshal_NoFigTag_FieldSkipped(t *testing.T) {
	figs := With(Options{Germinate: true})
	require.NoError(t, figs.Parse())
	type S struct {
		Ignored string // no fig tag
	}
	var s S
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Empty(t, s.Ignored)
}

func TestUnmarshal_UnregisteredFigKey_FieldLeftZero(t *testing.T) {
	// A fig tag pointing to an unregistered key must not error —
	// the field is simply left at its zero value.
	figs := With(Options{Germinate: true})
	require.NoError(t, figs.Parse())
	type S struct {
		Missing string `fig:"does-not-exist"`
	}
	var s S
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Empty(t, s.Missing)
}

// ============================================================================
// STRING VALIDATORS — all 12
// ============================================================================

func TestUnmarshal_String_NotEmpty_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "andrei", "name")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNotEmpty
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, "andrei", s.Name)
}

func TestUnmarshal_String_NotEmpty_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNotEmpty
	err := figs.Unmarshal(&s)
	assert.Error(t, err)
	assert.Contains(t, err.Error(), "notEmpty")
}

func TestUnmarshal_String_Length_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("code", "AB12", "code")
	require.NoError(t, figs.Parse())
	var s unmarshalStringLength
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, "AB12", s.Code)
}

func TestUnmarshal_String_Length_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("code", "AB", "code")
	require.NoError(t, figs.Parse())
	var s unmarshalStringLength
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NotLength_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("tag", "v1", "tag")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNotLength
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NotLength_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("tag", "", "tag")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNotLength
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_Contains_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("email", "andrei@example.com", "email")
	require.NoError(t, figs.Parse())
	var s unmarshalStringContains
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, "andrei@example.com", s.Email)
}

func TestUnmarshal_String_Contains_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("email", "notanemail", "email")
	require.NoError(t, figs.Parse())
	var s unmarshalStringContains
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NotContains_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("query", "SELECT name FROM users", "query")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNotContains
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NotContains_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("query", "drop table users", "query")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNotContains
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_Substring_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("url", "https://example.com", "url")
	require.NoError(t, figs.Parse())
	var s unmarshalStringSubstring
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_Substring_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("url", "http://example.com", "url")
	require.NoError(t, figs.Parse())
	var s unmarshalStringSubstring
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_HasPrefix_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "https://api.example.com", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalStringHasPrefix
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_HasPrefix_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "http://api.example.com", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalStringHasPrefix
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_HasSuffix_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("domain", "example.com", "domain")
	require.NoError(t, figs.Parse())
	var s unmarshalStringHasSuffix
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_HasSuffix_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("domain", "example.org", "domain")
	require.NoError(t, figs.Parse())
	var s unmarshalStringHasSuffix
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NoPrefix_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "https://api.example.com", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNoPrefix
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NoPrefix_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "http://api.example.com", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNoPrefix
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NoSuffix_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("filename", "report.pdf", "filename")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNoSuffix
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NoSuffix_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("filename", "install.exe", "filename")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNoSuffix
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NoPrefixes_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "https://api.example.com", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNoPrefixes
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NoPrefixes_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "ftp://files.example.com", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNoPrefixes
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NoSuffixes_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("filename", "report.pdf", "filename")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNoSuffixes
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_String_NoSuffixes_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("filename", "malware.bat", "filename")
	require.NoError(t, figs.Parse())
	var s unmarshalStringNoSuffixes
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// BOOL VALIDATORS — 2
// ============================================================================

func TestUnmarshal_Bool_True_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewBool("production", true, "production")
	require.NoError(t, figs.Parse())
	var s unmarshalBoolTrue
	assert.NoError(t, figs.Unmarshal(&s))
	assert.True(t, s.Production)
}

func TestUnmarshal_Bool_True_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewBool("production", false, "production")
	require.NoError(t, figs.Parse())
	var s unmarshalBoolTrue
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Bool_False_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewBool("debug", false, "debug")
	require.NoError(t, figs.Parse())
	var s unmarshalBoolFalse
	assert.NoError(t, figs.Unmarshal(&s))
	assert.False(t, s.Debug)
}

func TestUnmarshal_Bool_False_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewBool("debug", true, "debug")
	require.NoError(t, figs.Parse())
	var s unmarshalBoolFalse
	assert.Error(t, figs.Unmarshal(&s))
}

// Bool token applied to wrong type must error at resolve time
func TestUnmarshal_Bool_TokenOnWrongType_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "andrei", "name")
	require.NoError(t, figs.Parse())
	type S struct {
		Name string `fig:"name" assure:"true"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// INT VALIDATORS — 5
// ============================================================================

func TestUnmarshal_Int_Positive_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("workers", 8, "workers")
	require.NoError(t, figs.Parse())
	var s unmarshalIntPositive
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, 8, s.Workers)
}

func TestUnmarshal_Int_Positive_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("workers", -1, "workers")
	require.NoError(t, figs.Parse())
	var s unmarshalIntPositive
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int_Negative_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("offset", -5, "offset")
	require.NoError(t, figs.Parse())
	var s unmarshalIntNegative
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, -5, s.Offset)
}

func TestUnmarshal_Int_Negative_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("offset", 5, "offset")
	require.NoError(t, figs.Parse())
	var s unmarshalIntNegative
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int_Gt_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	var s unmarshalIntGt
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int_Gt_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 80, "port")
	require.NoError(t, figs.Parse())
	var s unmarshalIntGt
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int_Lt_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	var s unmarshalIntLt
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int_Lt_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 70000, "port")
	require.NoError(t, figs.Parse())
	var s unmarshalIntLt
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int_InRange_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	var s unmarshalIntInRange
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int_InRange_Fail_Low(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 80, "port")
	require.NoError(t, figs.Parse())
	var s unmarshalIntInRange
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int_InRange_Fail_High(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 70000, "port")
	require.NoError(t, figs.Parse())
	var s unmarshalIntInRange
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// INT64 VALIDATORS — 4
// ============================================================================

func TestUnmarshal_Int64_Positive_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt64("maxRetries", 5, "maxRetries")
	require.NoError(t, figs.Parse())
	var s unmarshalInt64Positive
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, int64(5), s.MaxRetries)
}

func TestUnmarshal_Int64_Positive_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt64("maxRetries", -1, "maxRetries")
	require.NoError(t, figs.Parse())
	var s unmarshalInt64Positive
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int64_Gt_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt64("batchSize", 100, "batchSize")
	require.NoError(t, figs.Parse())
	var s unmarshalInt64Gt
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int64_Gt_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt64("batchSize", 0, "batchSize")
	require.NoError(t, figs.Parse())
	var s unmarshalInt64Gt
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int64_Lt_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt64("batchSize", 500, "batchSize")
	require.NoError(t, figs.Parse())
	var s unmarshalInt64Lt
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int64_Lt_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt64("batchSize", 20000, "batchSize")
	require.NoError(t, figs.Parse())
	var s unmarshalInt64Lt
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int64_InRange_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt64("batchSize", 500, "batchSize")
	require.NoError(t, figs.Parse())
	var s unmarshalInt64InRange
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Int64_InRange_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt64("batchSize", 0, "batchSize")
	require.NoError(t, figs.Parse())
	var s unmarshalInt64InRange
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// FLOAT64 VALIDATORS — 5
// ============================================================================

func TestUnmarshal_Float64_Positive_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewFloat64("rate", 1.5, "rate")
	require.NoError(t, figs.Parse())
	var s unmarshalFloat64Positive
	assert.NoError(t, figs.Unmarshal(&s))
	assert.InDelta(t, 1.5, s.Rate, 0.001)
}

func TestUnmarshal_Float64_Positive_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewFloat64("rate", -0.5, "rate")
	require.NoError(t, figs.Parse())
	var s unmarshalFloat64Positive
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Float64_NotNaN_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewFloat64("score", 0.85, "score")
	require.NoError(t, figs.Parse())
	var s unmarshalFloat64NotNaN
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Float64_Gt_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewFloat64("confidence", 0.5, "confidence")
	require.NoError(t, figs.Parse())
	var s unmarshalFloat64Gt
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Float64_Gt_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewFloat64("confidence", 0.0, "confidence")
	require.NoError(t, figs.Parse())
	var s unmarshalFloat64Gt
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Float64_Lt_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewFloat64("confidence", 0.5, "confidence")
	require.NoError(t, figs.Parse())
	var s unmarshalFloat64Lt
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Float64_Lt_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewFloat64("confidence", 2.0, "confidence")
	require.NoError(t, figs.Parse())
	var s unmarshalFloat64Lt
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Float64_InRange_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewFloat64("confidence", 0.75, "confidence")
	require.NoError(t, figs.Parse())
	var s unmarshalFloat64InRange
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Float64_InRange_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewFloat64("confidence", 1.5, "confidence")
	require.NoError(t, figs.Parse())
	var s unmarshalFloat64InRange
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// DURATION VALIDATORS — 5
// ============================================================================

func TestUnmarshal_Duration_Positive_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", 30*time.Second, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationPositive
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, 30*time.Second, s.Timeout)
}

func TestUnmarshal_Duration_Positive_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", -1*time.Second, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationPositive
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Duration_Gt_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", 10*time.Second, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationGt
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Duration_Gt_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", 1*time.Second, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationGt
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Duration_Lt_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", 30*time.Second, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationLt
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Duration_Lt_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", 5*time.Minute, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationLt
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Duration_Min_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", 10*time.Second, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationMin
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Duration_Min_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", 1*time.Second, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationMin
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Duration_Max_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", 30*time.Second, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationMax
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Duration_Max_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewDuration("timeout", 24*time.Hour, "timeout")
	require.NoError(t, figs.Parse())
	var s unmarshalDurationMax
	assert.Error(t, figs.Unmarshal(&s))
}

// Duration token applied to non-duration must error
func TestUnmarshal_Duration_MinToken_OnWrongType_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "andrei", "name")
	require.NoError(t, figs.Parse())
	type S struct {
		Name string `fig:"name" assure:"min=5s"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// LIST VALIDATORS — 7
// ============================================================================

func TestUnmarshal_List_NotEmpty_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"primary"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListNotEmpty
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, []string{"primary"}, s.Servers)
}

func TestUnmarshal_List_NotEmpty_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListNotEmpty
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_MinLength_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"primary", "replica"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListMinLength
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_MinLength_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"primary"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListMinLength
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_Length_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"a", "b", "c"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListLength
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_Length_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"a", "b"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListLength
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_NotLength_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"primary"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListNotLength
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_NotLength_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListNotLength
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_Contains_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"primary", "replica"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListContains
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_Contains_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"replica-1", "replica-2"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListContains
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_NotContains_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"primary", "replica"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListNotContains
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_NotContains_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("servers", []string{"primary", "localhost"}, "servers")
	require.NoError(t, figs.Parse())
	var s unmarshalListNotContains
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_ContainsKey_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("roles", []string{"admin", "editor"}, "roles")
	require.NoError(t, figs.Parse())
	var s unmarshalListContainsKey
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_List_ContainsKey_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewList("roles", []string{"editor", "viewer"}, "roles")
	require.NoError(t, figs.Parse())
	var s unmarshalListContainsKey
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// MAP VALIDATORS — 6
// ============================================================================

func TestUnmarshal_Map_NotEmpty_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "prod"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapNotEmpty
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, "prod", s.Labels["env"])
}

func TestUnmarshal_Map_NotEmpty_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapNotEmpty
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_HasKey_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "prod", "version": "1"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapHasKey
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_HasKey_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"version": "1"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapHasKey
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_HasKeys_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "prod", "version": "2"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapHasKeys
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_HasKeys_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "prod"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapHasKeys
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_Length_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "prod", "version": "1"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapLength
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_Length_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "prod"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapLength
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_NotLength_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "prod"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapNotLength
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_NotLength_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapNotLength
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_ValueMatches_Pass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "prod", "version": "2"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapValueMatches
	assert.NoError(t, figs.Unmarshal(&s))
}

func TestUnmarshal_Map_ValueMatches_Fail(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "staging", "version": "2"}, "labels")
	require.NoError(t, figs.Parse())
	var s unmarshalMapValueMatches
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// WRONG TYPE ERRORS — token applied to incompatible field type
// ============================================================================

func TestUnmarshal_WrongType_NotEmpty_OnInt_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	type S struct {
		Port int `fig:"port" assure:"notEmpty"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_WrongType_HasPrefix_OnInt_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	type S struct {
		Port int `fig:"port" assure:"hasPrefix=https://"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_WrongType_ContainsKey_OnString_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "admin", "name")
	require.NoError(t, figs.Parse())
	type S struct {
		Name string `fig:"name" assure:"containsKey=admin"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_WrongType_HasKey_OnString_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "admin", "name")
	require.NoError(t, figs.Parse())
	type S struct {
		Name string `fig:"name" assure:"hasKey=env"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// MISSING ARGUMENT ERRORS — tokens that require =arg but none given
// ============================================================================

func TestUnmarshal_MissingArg_Length_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "andrei", "name")
	require.NoError(t, figs.Parse())
	type S struct {
		Name string `fig:"name" assure:"length"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_MissingArg_Gt_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	type S struct {
		Port int `fig:"port" assure:"gt"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_MissingArg_InRange_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	type S struct {
		Port int `fig:"port" assure:"inRange"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_MalformedArg_InRange_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	type S struct {
		Port int `fig:"port" assure:"inRange=notanumber"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

func TestUnmarshal_MalformedArg_ValueMatches_MissingColon_ReturnsError(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewMap("labels", map[string]string{"env": "prod"}, "labels")
	require.NoError(t, figs.Parse())
	type S struct {
		Labels map[string]string `fig:"labels" assure:"valueMatches=envprod"`
	}
	var s S
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// NESTED STRUCT RECURSION
// ============================================================================

func TestUnmarshal_NestedStruct_PopulatesInnerFields(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "andrei", "name")
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	var s unmarshalNestedOuter
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, "andrei", s.Name)
	assert.Equal(t, 8080, s.Inner.Port)
}

func TestUnmarshal_NestedStruct_InnerValidatorFails(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "andrei", "name")
	figs = figs.NewInt("port", 80, "port") // below gt=1023
	require.NoError(t, figs.Parse())
	var s unmarshalNestedOuter
	assert.Error(t, figs.Unmarshal(&s))
}

// ============================================================================
// CHAINED VALIDATORS — pipe syntax
// ============================================================================

func TestUnmarshal_ChainedString_AllPass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "https://api.example.com", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalChainedString
	assert.NoError(t, figs.Unmarshal(&s))
	assert.Equal(t, "https://api.example.com", s.Endpoint)
}

func TestUnmarshal_ChainedString_FirstTokenFails(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalChainedString
	err := figs.Unmarshal(&s)
	assert.Error(t, err)
	assert.Contains(t, err.Error(), "notEmpty")
}

func TestUnmarshal_ChainedString_MiddleTokenFails(t *testing.T) {
	// Passes notEmpty, fails hasPrefix
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "http://api.example.com", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalChainedString
	err := figs.Unmarshal(&s)
	assert.Error(t, err)
	assert.Contains(t, err.Error(), "hasPrefix")
}

func TestUnmarshal_ChainedString_LastTokenFails(t *testing.T) {
	// Passes notEmpty, hasPrefix, hasSuffix — fails notContains because localhost
	figs := With(Options{Germinate: true})
	figs = figs.NewString("endpoint", "https://localhost.com", "endpoint")
	require.NoError(t, figs.Parse())
	var s unmarshalChainedString
	err := figs.Unmarshal(&s)
	assert.Error(t, err)
	assert.Contains(t, err.Error(), "notContains")
}

func TestUnmarshal_ChainedInt_AllPass(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewInt("port", 8080, "port")
	require.NoError(t, figs.Parse())
	var s unmarshalChainedInt
	assert.NoError(t, figs.Unmarshal(&s))
}

// ============================================================================
// UNMARSHALERROR TYPE — error wrapping and field attribution
// ============================================================================

func TestUnmarshal_ErrorType_FieldAndKeyPresent(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.Parse())
	type S struct {
		Name string `fig:"name" assure:"notEmpty"`
	}
	var s S
	err := figs.Unmarshal(&s)
	require.Error(t, err)
	var ue *UnmarshalError
	require.ErrorAs(t, err, &ue)
	assert.Equal(t, "Name", ue.Field)
	assert.Equal(t, "name", ue.FigKey)
	assert.Equal(t, "notEmpty", ue.Token)
	assert.NotNil(t, ue.Cause)
}

func TestUnmarshal_ErrorType_Unwrap_ReturnsCause(t *testing.T) {
	figs := With(Options{Germinate: true})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.Parse())
	type S struct {
		Name string `fig:"name" assure:"notEmpty"`
	}
	var s S
	err := figs.Unmarshal(&s)
	require.Error(t, err)
	var ue *UnmarshalError
	require.ErrorAs(t, err, &ue)
	assert.NotNil(t, ue.Unwrap())
}

func TestUnmarshal_ErrorType_NoToken_WhenSetFieldFails(t *testing.T) {
	// Token is empty when the error comes from setFieldFromTree, not a validator
	figs := With(Options{Germinate: true})
	require.NoError(t, figs.Parse())
	// Request an unsupported type — channel is not in the mutagenesis table
	type S struct {
		Ch chan int `fig:"ch"`
	}
	var s S
	err := figs.Unmarshal(&s)
	require.Error(t, err)
	var ue *UnmarshalError
	require.ErrorAs(t, err, &ue)
	assert.Empty(t, ue.Token, "token should be empty when error is from setFieldFromTree")
}

// ============================================================================
// FULL APPCONFIG — integration test documenting real-world usage
// ============================================================================

func TestUnmarshal_AppConfig_AllValidatorsPass(t *testing.T) {
	figs := buildAppFigs(t)
	var cfg unmarshalAppConfig
	assert.NoError(t, figs.Unmarshal(&cfg))

	// Database
	assert.Equal(t, "postgres://db.example.com/mydb", cfg.Database.Host)
	assert.Equal(t, "mydbname", cfg.Database.Name)
	assert.Equal(t, "sc_public_v1", cfg.Database.Schema)
	assert.Equal(t, "s3cur3pass!", cfg.Database.Password)
	assert.Equal(t, "utf8", cfg.Database.Encoding)
	assert.Equal(t, "prod-replica", cfg.Database.Tag)

	// Workers
	assert.Equal(t, 8, cfg.Workers.Count)
	assert.Equal(t, 5432, cfg.Workers.Port)
	assert.Equal(t, -1, cfg.Workers.Offset)
	assert.Equal(t, int64(5), cfg.Workers.MaxRetries)
	assert.Equal(t, int64(500), cfg.Workers.BatchSize)
	assert.Equal(t, 30*time.Second, cfg.Workers.Timeout)
	assert.Equal(t, 2*time.Minute, cfg.Workers.Interval)

	// Thresholds
	assert.InDelta(t, 0.95, cfg.Thresholds.Confidence, 0.001)
	assert.InDelta(t, 10.0, cfg.Thresholds.SampleRate, 0.001)

	// Features
	assert.True(t, cfg.Features.ProductionMode)
	assert.False(t, cfg.Features.DebugMode)

	// Infra
	assert.Contains(t, cfg.Infra.Servers, "primary")
	assert.Equal(t, "prod", cfg.Infra.Labels["env"])
	assert.Equal(t, "2.0", cfg.Infra.Labels["version"])
	assert.Equal(t, "us-east-1", cfg.Infra.Labels["region"])
}

func TestUnmarshal_AppConfig_InvalidDbHost_FailsValidation(t *testing.T) {
	figs := With(Options{Germinate: true})
	// Intentionally bad host — fails hasPrefix=postgres://
	figs = figs.NewString("db-host", "mysql://db.example.com/mydb", "Database host")
	figs = figs.NewString("db-name", "mydbname", "Database name")
	figs = figs.NewString("db-schema", "sc_public_v1", "Database schema")
	figs = figs.NewString("db-password", "s3cur3pass!", "Database password")
	figs = figs.NewString("db-encoding", "utf8", "Database encoding")
	figs = figs.NewString("db-tag", "prod-replica", "Database tag")
	figs = figs.NewInt("workers", 8, "Worker count")
	figs = figs.NewInt("port", 5432, "Port")
	figs = figs.NewInt("offset", -1, "Offset")
	figs = figs.NewInt64("maxRetries", 5, "Max retries")
	figs = figs.NewInt64("batchSize", 500, "Batch size")
	figs = figs.NewDuration("timeout", 30*time.Second, "Request timeout")
	figs = figs.NewDuration("interval", 2*time.Minute, "Poll interval")
	figs = figs.NewFloat64("confidence", 0.95, "Confidence threshold")
	figs = figs.NewFloat64("sampleRate", 10.0, "Sample rate")
	figs = figs.NewBool("production", true, "Production mode")
	figs = figs.NewBool("debug", false, "Debug mode")
	figs = figs.NewList("servers", []string{"primary", "replica-1"}, "Server list")
	figs = figs.NewMap("labels", map[string]string{
		"env": "prod", "version": "2.0", "region": "us-east-1",
	}, "Infra labels")
	require.NoError(t, figs.Parse())

	var cfg unmarshalAppConfig
	err := figs.Unmarshal(&cfg)
	require.Error(t, err)
	var ue *UnmarshalError
	require.ErrorAs(t, err, &ue)
	assert.Equal(t, "Host", ue.Field)
	assert.Equal(t, "db-host", ue.FigKey)
	assert.Contains(t, ue.Token, "hasPrefix")
}

[andreimerlescu]

1. types.go — three changes

Add Branch []string to Mutation, add Unmarshal to the Plant interface, add NewBranch to CoreAbilities, and add the branch.go structs:

// Mutation — add Branch field
type Mutation struct {
    Property    string
    Branch      []string  // empty for root, ["db"] for branch, ["db","replica"] for nested
    Mutagenesis string
    Way         string
    Old         interface{}
    New         interface{}
    When        time.Time
    Error       error
}

// Path is a convenience method for logging and routing
func (m Mutation) Path() string {
    if len(m.Branch) == 0 {
        return m.Property
    }
    return strings.Join(append(m.Branch, m.Property), ".")
}

Add Unmarshal to the Core interface:

type Core interface {
    FigFlesh(name string) Flesh
    ErrorFor(name string) error
    Usage()
    UsageString() string
    Unmarshal(target interface{}) error  // ADD THIS
}

Add NewBranch and HasTreeRule/RemoveTreeRule to CoreAbilities:

type CoreAbilities interface {
    Withables
    Savable
    Readable
    Parsable
    Mutable
    Loadable
    Divine
    NewBranch(name string) Plant          // ADD
    HasTreeRule(rule RuleKind) bool       // ADD
    RemoveTreeRule(rule RuleKind) error   // ADD
}

Add branches and branchPrefix fields to figTree:

type figTree struct {
    ConfigFilePath string
    GlobalRules    []RuleKind
    harvest        int
    pollinate      bool
    figs           map[string]*figFruit
    values         *sync.Map
    withered       map[string]witheredFig
    aliases        map[string]string
    sourceLocker   sync.RWMutex
    mu             sync.RWMutex
    tracking       bool
    problems       []error
    mutationsCh    chan Mutation
    flagSet        *flag.FlagSet
    filterTests    bool
    angel          *atomic.Bool
    ignoreEnv      bool
    branches       map[string]*figTree   // ADD
    branchPrefix   []string              // ADD — empty for root
}

2. branch.go — new file

package figtree

import (
    "flag"
    "fmt"
    "os"
    "strings"
    "sync"
    "sync/atomic"
)

// NewBranch creates a named child figtree that shares the root mutation
// channel. All mutations emitted by the branch carry their path in
// Mutation.Branch so consumers can route by domain.
//
// Example:
//
//   figs := figtree.Grow()
//   figsDb := figs.NewBranch("db")
//   figsDb.NewString("host", "", "DB Host")
//   figsDb.WithTreeRule(figtree.RuleNoFlags)
//   figsDb.WithTreeRule(figtree.RulePreventChange)
//   err := figs.Parse()
func (t *figTree) NewBranch(name string) Plant {
    t.mu.Lock()
    defer t.mu.Unlock()

    if t.branches == nil {
        t.branches = make(map[string]*figTree)
    }

    // Build the branch prefix by appending name to parent prefix
    prefix := make([]string, len(t.branchPrefix)+1)
    copy(prefix, t.branchPrefix)
    prefix[len(t.branchPrefix)] = name

    angel := atomic.Bool{}
    angel.Store(false)

    branch := &figTree{
        ConfigFilePath: t.ConfigFilePath,
        ignoreEnv:      t.ignoreEnv,
        filterTests:    t.filterTests,
        pollinate:      t.pollinate,
        tracking:       t.tracking,
        harvest:        t.harvest,
        angel:          &angel,
        problems:       make([]error, 0),
        aliases:        make(map[string]string),
        figs:           make(map[string]*figFruit),
        values:         &sync.Map{},
        withered:       make(map[string]witheredFig),
        mu:             sync.RWMutex{},
        mutationsCh:    t.mutationsCh, // shared root channel
        flagSet:        flag.NewFlagSet(os.Args[0], flag.ContinueOnError),
        branches:       make(map[string]*figTree),
        branchPrefix:   prefix,
    }

    branch.flagSet.Usage = branch.Usage
    t.branches[name] = branch
    return branch
}

// HasTreeRule reports whether a specific RuleKind is currently active on this tree.
func (t *figTree) HasTreeRule(rule RuleKind) bool {
    t.mu.RLock()
    defer t.mu.RUnlock()
    for _, r := range t.GlobalRules {
        if r == rule {
            return true
        }
    }
    return false
}

// RemoveTreeRule removes a RuleKind from the tree's global rules.
// Returns an error if the rule is not present.
func (t *figTree) RemoveTreeRule(rule RuleKind) error {
    t.mu.Lock()
    defer t.mu.Unlock()
    for i, r := range t.GlobalRules {
        if r == rule {
            t.GlobalRules = append(t.GlobalRules[:i], t.GlobalRules[i+1:]...)
            return nil
        }
    }
    return fmt.Errorf("figtree: rule %q not found on tree", rule)
}

// emitMutation sends a mutation onto the shared root channel,
// injecting the branch path so consumers can route by domain.
func (t *figTree) emitMutation(m Mutation) {
    if !t.tracking {
        return
    }
    m.Branch = t.branchPrefix
    select {
    case t.mutationsCh <- m:
    default:
        // channel full — harvest needs tuning
    }
}

// BranchNames returns the names of all direct child branches.
func (t *figTree) BranchNames() []string {
    t.mu.RLock()
    defer t.mu.RUnlock()
    names := make([]string, 0, len(t.branches))
    for name := range t.branches {
        names = append(names, name)
    }
    return names
}

// Branch returns a child branch by name, or nil if not found.
func (t *figTree) Branch(name string) Plant {
    t.mu.RLock()
    defer t.mu.RUnlock()
    if b, ok := t.branches[name]; ok {
        return b
    }
    return nil
}

// envPrefix converts the branch path into an environment variable prefix.
// ["db"] -> "DB_", ["db","replica"] -> "DB_REPLICA_"
func (t *figTree) envPrefix() string {
    if len(t.branchPrefix) == 0 {
        return ""
    }
    return strings.ToUpper(strings.Join(t.branchPrefix, "_")) + "_"
}

3. unmarshal.go — one method change

The Unmarshal method on *tree needs to become a method on *figTree to match the actual struct name in the codebase. Looking at types.go, the concrete type is figTree not tree. Change the receiver throughout unmarshal.go:

// Every occurrence of (t *tree) becomes (t *figTree)
func (t *figTree) Unmarshal(target interface{}) error { ... }
func (t *figTree) unmarshalStruct(rv reflect.Value) error { ... }
func (t *figTree) unmarshalField(...) error { ... }
func (t *figTree) setFieldFromTree(...) error { ... }

The setFieldFromTree method also needs to respect branch-scoped env var resolution. The env lookup for a branch fig should use the branch prefix. Add this to setFieldFromTree before each getter call — replace for example:

// before
p := t.String(figKey)

// after — branch env prefix is prepended automatically
// because t.String() already calls os.Getenv via pollinate,
// and the branch's envPrefix() is applied at registration time
// via NewString. No change needed here IF registration uses envPrefix.

The env prefix wiring happens at NewString/NewInt etc registration time, not at read time, so setFieldFromTree needs no change. The branch’s envPrefix() just needs to be used when the branch registers figs — add this to NewString and all New methods in the branch:

// In each New<Mutagenesis> method, prepend envPrefix to the key
// used for os.Getenv lookup. The simplest approach is to store
// the envPrefix on figTree and use it in the loading.go / parsing.go
// where os.Getenv is called.

That’s a loading.go concern — add one line there:

// In loading.go wherever os.Getenv(name) is called:

envKey := t.envPrefix() + strings.ToUpper(name)
val := os.Getenv(envKey)

4. unmarshal_test.go — add branch tests

Add this block at the end of the test file:

// ============================================================================
// BRANCH TESTS — Unmarshal scoped to a branch
// ============================================================================

type unmarshalBranchDb struct {
    Host string `fig:"host" assure:"notEmpty|hasPrefix=postgres://"`
    Port int    `fig:"port" assure:"gt=1023|lt=65536"`
}

func TestUnmarshal_Branch_PopulatesFromBranchScope(t *testing.T) {
    figs := With(Options{Germinate: true})
    figsDb := figs.NewBranch("db")
    figsDb.NewString("host", "postgres://db.example.com", "DB Host")
    figsDb.NewInt("port", 5432, "DB Port")
    require.NoError(t, figs.Parse())

    var db unmarshalBranchDb
    assert.NoError(t, figsDb.Unmarshal(&db))
    assert.Equal(t, "postgres://db.example.com", db.Host)
    assert.Equal(t, 5432, db.Port)
}

func TestUnmarshal_Branch_ValidatorFailsOnBranchFig(t *testing.T) {
    figs := With(Options{Germinate: true})
    figsDb := figs.NewBranch("db")
    figsDb.NewString("host", "mysql://db.example.com", "DB Host")
    figsDb.NewInt("port", 5432, "DB Port")
    require.NoError(t, figs.Parse())

    var db unmarshalBranchDb
    err := figsDb.Unmarshal(&db)
    assert.Error(t, err)
    var ue *UnmarshalError
    require.ErrorAs(t, err, &ue)
    assert.Equal(t, "Host", ue.Field)
    assert.Contains(t, ue.Token, "hasPrefix")
}

func TestUnmarshal_Branch_DoesNotSeeRootFigs(t *testing.T) {
    figs := With(Options{Germinate: true})
    figs.NewString("host", "should-not-be-visible", "Root host")
    figsDb := figs.NewBranch("db")
    figsDb.NewString("host", "postgres://db.example.com", "DB Host")
    figsDb.NewInt("port", 5432, "DB Port")
    require.NoError(t, figs.Parse())

    var db unmarshalBranchDb
    assert.NoError(t, figsDb.Unmarshal(&db))
    // branch host, not root host
    assert.Equal(t, "postgres://db.example.com", db.Host)
}

func TestUnmarshal_Branch_MutationCarriesBranchPath(t *testing.T) {
    figs := With(Options{Tracking: true, Germinate: true})
    figsDb := figs.NewBranch("db")
    figsDb.NewString("host", "postgres://db.example.com", "DB Host")
    require.NoError(t, figs.Parse())

    figsDb.StoreString("host", "postgres://new.example.com")

    select {
    case m := <-figs.Mutations():
        assert.Equal(t, []string{"db"}, m.Branch)
        assert.Equal(t, "host", m.Property)
        assert.Equal(t, "db.host", m.Path())
    default:
        t.Fatal("expected mutation not received")
    }
}

func TestNewBranch_HasTreeRule_RemoveTreeRule(t *testing.T) {
    figs := With(Options{Germinate: true})
    figsDb := figs.NewBranch("db")
    figsDb.NewString("host", "postgres://db.example.com", "DB Host")
    require.NoError(t, figs.Parse())

    // not present yet
    assert.False(t, figsDb.HasTreeRule(RulePreventChange))

    // add it
    figsDb.WithTreeRule(RulePreventChange)
    assert.True(t, figsDb.HasTreeRule(RulePreventChange))

    // remove it
    err := figsDb.RemoveTreeRule(RulePreventChange)
    assert.NoError(t, err)
    assert.False(t, figsDb.HasTreeRule(RulePreventChange))

    // remove again — should error
    err = figsDb.RemoveTreeRule(RulePreventChange)
    assert.Error(t, err)
}

Summary of files touched:
∙ types.go — Mutation struct, Core interface, CoreAbilities interface, figTree struct
∙ branch.go — new file, all branching logic
∙ unmarshal.go — receiver rename from *tree to *figTree throughout
∙ loading.go — one line per os.Getenv call to prepend t.envPrefix()
∙ unmarshal_test.go — five new branch tests appended​​​​​​​​​​​​​​​​