// Package helpers is a set of useful functions when working with async state
// machines.
package helpers

import (
	
	
	
	
	
	
	
	
	
	
	
	
	
	
	
	

	
	
	

	
	am 
	ssam 
	ampipe 
	
)

const (
	// EnvAmLogPrint prints machine log to stdout.
	EnvAmLogPrint = "AM_LOG_PRINT"
	// EnvAmHealthcheck enables a healthcheck ticker for every debugged machine.
	EnvAmHealthcheck = "AM_HEALTHCHECK"
	// EnvAmTestRunner indicates the main test tunner, disables any telemetry.
	EnvAmTestRunner = "AM_TEST_RUNNER"
	// EnvAmLogFull enables all the features of [am.SemLogger].
	EnvAmLogFull = "AM_LOG_FULL"
	// EnvAmLogSteps logs transition steps.
	// See [am.SemLogger.EnableSteps].
	// "1" | "" (default)
	EnvAmLogSteps = "AM_LOG_STEPS"
	// EnvAmLogGraph logs the graph structure (mutation traces, pipes, RPC, etc).
	// See [am.SemLogger.EnableGraph].
	// "1" | "" (default)
	EnvAmLogGraph = "AM_LOG_GRAPH"
	// EnvAmLogChecks logs Can methods. See [am.SemLogger.EnableCan].
	// "1" | "" (default)
	EnvAmLogChecks = "AM_LOG_CHECKS"
	// EnvAmLogQueued logs queued mutations. See [am.SemLogger.EnableQueued].
	// "1" | "" (default)
	EnvAmLogQueued = "AM_LOG_QUEUED"
	// EnvAmLogArgs logs mutation args. See [am.SemLogger.EnableArgs].
	// "1" | "" (default)
	EnvAmLogArgs = "AM_LOG_ARGS"
	// EnvAmLogWhen logs When methods. See [am.SemLogger.EnableWhen].
	// "1" | "" (default)
	EnvAmLogWhen = "AM_LOG_WHEN"
	// EnvAmLogStateCtx logs state ctxs. See [am.SemLogger.EnableStateCtx].
	// "1" | "" (default)
	EnvAmLogStateCtx = "AM_LOG_STATE_CTX"
	// EnvAmLogFile enables file logging (using machine ID as the name).
	// "1" | "" (default)
	EnvAmLogFile = "AM_LOG_FILE"

	healthcheckInterval = 30 * time.Second
)

type (
	S      = am.S
	A      = am.A
	Schema = am.Schema
)

// sync add

// Add1Sync is [AddSync] for a single state.
func (
	 context.Context,  am.Api,  string,  ...am.A,
) bool {
	return EvAddSync(, nil, , S{}, ...)
}

// AddSync activates a state and waits until it becomes activate, or canceled.
// Supports queued rejections, expiration ctx and returns as [am.Canceled].
func (
	 context.Context,  am.Api,  S,  ...am.A,
) bool {
	return EvAddSync(, nil, , , ...)
}

// EvAdd1Sync is [Add1Sync] with an [am.Event] trace.
func (
	 context.Context,  *am.Event,  am.Api,  string,  ...am.A,
) bool {
	return EvAddSync(, , , S{}, ...)
}

// EvAddSync is [AddSync] with an [am.Event] trace.
func (
	 context.Context,  *am.Event,  am.Api,  S,  ...am.A,
) bool {
	 := .EvAdd(, , am.OptArgs())
	// fmt.Printf("wait on %d\n", res)
	switch  {
	case am.Executed:
		return true
	case am.Canceled:
		return false
	default:
		// wait
		select {
		case <-.Done():
			return false
		case <-.WhenQueue():
			if .Is() {
				return true
			}
			return false
		}
	}
}

// Add1Async is [AddAsync] for a single state.
func (
	 context.Context,  am.Api,  string,
	 string,  ...am.A,
) bool {
	return EvAddAsync(, nil, , , S{}, am.OptArgs())
}

// async add

// AddAsync add initial states from an async op and waits for the final state
// to become active (can be a Multi state).
func (
	 context.Context,  am.Api,  string,
	 S,  ...am.A,
) bool {
	return EvAddAsync(, nil, , , , am.OptArgs())
}

func (
	 context.Context,  *am.Event,  am.Api,  string,
	 string,  ...am.A,
) bool {
	return EvAddAsync(, , , , S{}, am.OptArgs())
}

func (
	 context.Context,  *am.Event,  am.Api,  string,
	 S,  ...am.A,
) bool {
	,  := context.WithCancel()
	defer ()

	 := .Tick()
	 := am.NextActiveIn()
	 := .WhenTicks(, , )
	if .EvAdd(, , am.OptArgs()) == am.Canceled {
		return false
	}

	// wait
	select {
	case <-:
		return true
	case <-.Done():
		return false
	}
}

// sync remove

// Remove1Sync is [RemoveSync] for a single state.
func (
	 context.Context,  am.Api,  string,  ...am.A,
) bool {
	return EvRemoveSync(, nil, , S{}, ...)
}

// RemoveSync activates a state and waits until it becomes activate, or
// canceled. Supports queued rejections, expiration ctx and returns as
// [am.Canceled].
func (
	 context.Context,  am.Api,  S,  ...am.A,
) bool {
	return EvRemoveSync(, nil, , , ...)
}

// EvRemove1Sync is [Remove1Sync] with an [am.Event] trace.
func (
	 context.Context,  *am.Event,  am.Api,  string,  ...am.A,
) bool {
	return EvRemoveSync(, , , S{}, ...)
}

// EvRemoveSync is [RemoveSync] with an [am.Event] trace.
func (
	 context.Context,  *am.Event,  am.Api,  S,  ...am.A,
) bool {
	 := .EvRemove(, , am.OptArgs())
	switch  {
	case am.Executed:
		return true
	case am.Canceled:
		return false
	default:
		// wait
		select {
		case <-.Done():
			return false
		case <-.WhenQueue():
			if .Not() {
				return true
			}
			return true
		}
	}
}

// IsMulti returns true if a state is a multi state.
func ( am.Api,  string) bool {
	// TODO safeguard
	return .Schema()[].Multi
}

// StatesToIndexes converts a list of state names to a list of state indexes,
// for the given machine. It returns -1 for unknown states.
func ( am.S,  am.S) []int {
	 := make([]int, len())
	for ,  := range  {
		[] = slices.Index(, )
	}

	return 
}

// IndexesToStates converts a list of state indexes to a list of state names,
// for a given machine.
func ( am.S,  []int) am.S {
	 := make(am.S, len())
	for ,  := range  {
		if  == -1 ||  >= len() {
			[] = "unknown" + strconv.Itoa()
			continue
		}
		[] = []
	}

	return 
}

// MachDebug exports transition telemetry to an am-dbg instance listening at
// [amDbgAddr].
func (
	 am.Api,  string,  am.LogLevel,  bool,
	 *am.SemConfig,
) error {
	// expand the default addr to TCP port
	if  == "1" {
		 = dbg.DbgAddr
	}

	// no debug for CI
	if IsTestRunner() {
		return nil
	}

	,  := semLogInit(.SemLogger(), , , ,
		)
	if  {
		return 
	}

	 = dbg.TransitionsToDbg(, )
	if  != nil {
		return 
	}

	if os.Getenv(EnvAmHealthcheck) != "" {
		Healthcheck()
	}

	return nil
}

// MachDebugWs exports transition telemetry to an am-dbg instance
// listening on a WebSicjet at [amDbgAddr]. Useful for WASM.
func (
	 am.Api,  string,  am.LogLevel,  bool,
	 *am.SemConfig,
) error {
	// expand the default addr to HTTP port
	if  == "1" {
		 = dbg.DbgAddrWeb
	}

	// no debug for CI
	if IsTestRunner() {
		return nil
	}

	,  := semLogInit(.SemLogger(), , , ,
		)
	if  {
		return 
	}

	// tracer for telemetry
	 = dbg.TransitionsToDbg(, , &dbg.Opts{
		WebSocket: true,
	})
	if  != nil {
		return 
	}

	if os.Getenv(EnvAmHealthcheck) != "" {
		Healthcheck()
	}

	return nil
}

func semLogInit(
	 am.SemLogger,  string,  am.LogLevel,  bool,
	 *am.SemConfig,
) (error, bool) {
	if  {
		.SetLevel()
	} else {
		.SetEmpty()
	}

	if  == "" {
		return nil, true
	}

	// semantic logging
	if .Steps {
		.EnableSteps(true)
	}
	if .Graph {
		.EnableGraph(true)
	}
	if .Can {
		.EnableCan(true)
	}
	if .Queued {
		.EnableQueued(true)
	}
	if .StateCtx {
		.EnableStateCtx(true)
	}
	if .Can {
		.EnableCan(true)
	}
	if .When {
		.EnableWhen(true)
	}
	if .Args {
		.EnableArgs(true)
	}
	return nil, false
}

// SemConfigEnv returns a SemConfigEnv based on env vars, or the [forceFull]
// flag.
func ( bool) *am.SemConfig {
	// TODO rename to SemConfigEnv

	// full override
	if os.Getenv(EnvAmLogFull) != "" ||  {
		return &am.SemConfig{
			Steps:    true,
			Graph:    true,
			Can:      true,
			Queued:   true,
			StateCtx: true,
			When:     true,
			Args:     true,
		}
	}

	// selective logging
	return &am.SemConfig{
		Steps:    os.Getenv(EnvAmLogSteps) != "",
		Graph:    os.Getenv(EnvAmLogGraph) != "",
		Can:      os.Getenv(EnvAmLogChecks) != "",
		Queued:   os.Getenv(EnvAmLogQueued) != "",
		StateCtx: os.Getenv(EnvAmLogStateCtx) != "",
		When:     os.Getenv(EnvAmLogWhen) != "",
		Args:     os.Getenv(EnvAmLogArgs) != "",
	}
}

// MachDebugEnv sets up a machine for debugging, based on env vars only:
// AM_DBG_ADDR, AM_LOG, AM_LOG_*, and AM_DEBUG. This function should be called
// right after the machine is created (to catch all the log entries).
func ( am.Api) error {
	 := os.Getenv(dbg.EnvAmDbgAddr)
	 := am.EnvLogLevel("")
	 := os.Getenv(EnvAmLogPrint) != ""

	if IsWasm() {
		return MachDebugWs(, , , , SemConfigEnv(false))
	}

	return MachDebug(, , , , SemConfigEnv(false))
}

// Healthcheck adds a state to a machine every 5 seconds, until the context is
// done. This makes sure all the logs are pushed to the telemetry server.
// TODO use machine scheduler (once available))
func ( am.Api) {
	if !.Has1(ssam.BasicStates.Healthcheck) {
		return
	}

	go func() {
		for {
			// static delay
			if !Wait(.Context(), healthcheckInterval) {
				break
			}

			// ping
			.Add1(ssam.BasicStates.Healthcheck, nil)
		}
	}()
}

// TODO StableWhen(dur, states, ctx) - like When, but makes sure the state is
//  stable for the duration.

// NewReqAdd creates a new failsafe request to add states to a machine. See
// See MutRequest for more info and NewMutRequest for the defaults.
func ( am.Api,  am.S,  am.A) *MutRequest {
	return NewMutRequest(, am.MutationAdd, , )
}

// NewReqAdd1 creates a new failsafe request to add a single state to a machine.
// See MutRequest for more info and NewMutRequest for the defaults.
func ( am.Api,  string,  am.A) *MutRequest {
	return NewReqAdd(, am.S{}, )
}

// NewReqRemove creates a new failsafe request to remove states from a machine.
// See MutRequest for more info and NewMutRequest for the defaults.
func ( am.Api,  am.S,  am.A) *MutRequest {
	return NewMutRequest(, am.MutationRemove, , )
}

// NewReqRemove1 creates a new failsafe request to remove a single state from a
// machine. See MutRequest for more info and NewMutRequest for the defaults.
func ( am.Api,  string,  am.A) *MutRequest {
	return NewReqRemove(, am.S{}, )
}

// MutRequest is a failsafe request for a machine mutation. It supports retries,
// backoff, max duration, delay, and timeout policies. It will try to mutate
// the machine until the context is done, or the max duration is reached. Queued
// mutations are considered supported a success.
type MutRequest struct {
	Mach    am.Api
	MutType am.MutationType
	States  am.S
	Args    am.A
	Event   *am.Event

	// PolicyRetries is the max number of retries.
	PolicyRetries int
	// PolicyDelay is the delay before the first retry, then doubles.
	PolicyDelay time.Duration
	// PolicyBackoff is the max time to wait between retries.
	PolicyBackoff time.Duration
	// PolicyMaxDuration is the max time to wait for the mutation to be accepted.
	PolicyMaxDuration time.Duration
}

// NewMutRequest creates a new MutRequest with defaults - 10 retries, 100ms
// delay, 5s backoff, and 5s max duration.
func (
	 am.Api,  am.MutationType,  am.S,  am.A,
) *MutRequest {
	// TODO increase duration for AM_DEBUG

	return &MutRequest{
		Mach:    ,
		MutType: ,
		States:  ,
		Args:    ,

		// defaults

		PolicyRetries:     10,
		PolicyDelay:       100 * time.Millisecond,
		PolicyBackoff:     5 * time.Second,
		PolicyMaxDuration: 5 * time.Second,
	}
}

func ( *MutRequest) (
	 am.Api,  am.MutationType,  am.S,  am.A,
) *MutRequest {
	return &MutRequest{
		Mach:    ,
		MutType: ,
		States:  ,
		Args:    ,

		PolicyRetries:     .PolicyRetries,
		PolicyBackoff:     .PolicyBackoff,
		PolicyMaxDuration: .PolicyMaxDuration,
		PolicyDelay:       .PolicyDelay,
	}
}

func ( *MutRequest) ( int) *MutRequest {
	.PolicyRetries = 
	return 
}

func ( *MutRequest) ( time.Duration) *MutRequest {
	.PolicyBackoff = 
	return 
}

func ( *MutRequest) ( time.Duration) *MutRequest {
	.PolicyMaxDuration = 
	return 
}

func ( *MutRequest) ( time.Duration) *MutRequest {
	.PolicyDelay = 
	return 
}

// Run blocks and executes the request. Returns when the transition wasn't
// [am.Canceled], or until too many errors.
func ( *MutRequest) ( context.Context) (am.Result, error) {
	// policies
	 := retrypolicy.Builder[am.Result]().
		WithMaxDuration(.PolicyMaxDuration).
		WithMaxRetries(.PolicyRetries)

	if .PolicyBackoff != 0 {
		 = .WithBackoff(.PolicyDelay, .PolicyBackoff)
	} else {
		 = .WithDelay(.PolicyDelay)
	}

	,  := failsafe.NewExecutor[am.Result](.Build()).WithContext().
		Get(.get)

	return , 
}

func ( *MutRequest) () (am.Result, error) {
	var  am.Result
	if .MutType == am.MutationAdd {
		 = .Mach.EvAdd(.Event, .States, .Args)
	} else {
		 = .Mach.EvRemove(.Event, .States, .Args)
	}

	return , ResultToErr()
}

// Wait waits for a duration, or until the context is done. Returns true if the
// duration has passed, or false if ctx is done.
func ( context.Context,  time.Duration) bool {
	 := time.After()

	select {
	case <-.Done():
		return false
	case <-:
		return true
	}
}

// Interval runs a function at a given interval, for a given duration, or until
// the context is done. Returns nil if the duration has passed, or err is ctx is
// done. The function should return false to stop the interval.
func (
	 context.Context,  time.Duration,  time.Duration,
	 func() bool,
) error {
	 := time.Now().Add()
	 := time.NewTicker()
	defer .Stop()

	for {
		select {

		case <-.Done():
			return .Err()

		case <-.C:
			if time.Now().After() {
				return nil
			}

			if !() {
				return nil
			}
		}
	}
}

// WaitForAll waits for a list of channels to close, or until the context is
// done, or until the timeout is reached. Returns nil if all channels are
// closed, or ErrTimeout, or ctx.Err().
//
// It's advised to check the state ctx after this call, as it usually means
// expiration and not a timeout.
func (
	 context.Context,  time.Duration,  ...<-chan struct{},
) error {
	// TODO test
	// TODO support mach disposal via am.ErrDisposed

	// exit early
	if len() == 0 {
		return nil
	}
	if .Err() != nil {
		return .Err()
	}

	// timeout
	if IsDebug() {
		 = 100 * 
	}
	 := time.After()

	// wait on all chans
	for ,  := range  {
		select {
		case <-.Done():
			// TODO check and log state ctx name
			return .Err()
		case <-:
			return am.ErrTimeout
		case <-:
			// pass
		}
	}

	return nil
}

// WaitForErrAll is like WaitForAll, but also waits on WhenErr of a passed
// machine. For state machines with error handling (like retry) it's recommended
// to use [WaitForAll] and measure ticks of [am.StateException] instead.
func (
	 context.Context,  time.Duration,  am.Api,
	 ...<-chan struct{},
) error {
	// TODO test

	// exit early
	if len() == 0 {
		return nil
	}
	if .Err() != nil {
		return .Err()
	}

	// timeout
	if IsDebug() {
		 = 100 * 
	}
	 := time.After()
	 := .WhenErr()

	// wait on all chans
	for ,  := range  {
		select {
		case <-.Done():
			// TODO check and log state ctx name
			return .Err()
		case <-:
			return fmt.Errorf("%s: %w", am.StateException, .Err())
		case <-:
			return am.ErrTimeout
		case <-:
			// pass
		}
	}

	return nil
}

// WaitForErrStateAll

// WaitForAny waits for any of the channels to close, or until the context is
// done, or until the timeout is reached. Returns nil if any channel is
// closed, or ErrTimeout, or ctx.Err().
//
// It's advised to check the state ctx after this call, as it usually means
// expiration and not a timeout.
//
// This function uses reflection to wait for multiple channels at once.
func (
	 context.Context,  time.Duration,  ...<-chan struct{},
) error {
	// TODO test
	// TODO reflection-less selectes for 1/2/3 chans
	// exit early
	if .Err() != nil {
		return .Err()
	}
	if IsDebug() {
		 = 100 * 
	}
	 := time.After()

	// create select cases
	 := make([]reflect.SelectCase, 2+len())
	[0] = reflect.SelectCase{
		Dir:  reflect.SelectRecv,
		Chan: reflect.ValueOf(.Done()),
	}
	[1] = reflect.SelectCase{
		Dir:  reflect.SelectRecv,
		Chan: reflect.ValueOf(),
	}
	for ,  := range  {
		[+2] = reflect.SelectCase{
			Dir:  reflect.SelectRecv,
			Chan: reflect.ValueOf(),
		}
	}

	// wait
	, ,  := reflect.Select()

	switch  {
	case 0:
		// TODO check and log state ctx name
		return .Err()
	case 1:
		return am.ErrTimeout
	default:
		return nil
	}
}

// WaitForErrAny is like WaitForAny, but also waits on WhenErr of a passed
// machine. For state machines with error handling (like retry) it's recommended
// to use [WaitForAny] and measure ticks of [am.StateException] instead.
func (
	 context.Context,  time.Duration,  *am.Machine,
	 ...<-chan struct{},
) error {
	// TODO test
	// TODO reflection-less selectes for 1/2/3 chans
	// exit early
	if .Err() != nil {
		return .Err()
	}
	if IsDebug() {
		 = 100 * 
	}
	 := time.After()

	// create select cases
	 := 3
	 := make([]reflect.SelectCase, +len())
	[0] = reflect.SelectCase{
		Dir:  reflect.SelectRecv,
		Chan: reflect.ValueOf(.Done()),
	}
	[1] = reflect.SelectCase{
		Dir:  reflect.SelectRecv,
		Chan: reflect.ValueOf(),
	}
	[2] = reflect.SelectCase{
		Dir:  reflect.SelectRecv,
		Chan: reflect.ValueOf(),
	}
	for ,  := range  {
		[+] = reflect.SelectCase{
			Dir:  reflect.SelectRecv,
			Chan: reflect.ValueOf(),
		}
	}

	// wait
	, ,  := reflect.Select()

	switch  {
	case 0:
		// TODO check and log state ctx name (if any)
		return .Err()
	case 1:
		return am.ErrTimeout
	case 2:
		return .Err()
	default:
		return nil
	}
}

// TODO WaitForErrStateAny

// Activations return the number of state activations from the number of ticks
// passed.
func ( uint64) int {
	return int(( + 1) / 2)
}

// ExecAndClose closes the chan when the function ends.
func ( func()) <-chan struct{} {
	 := make(chan struct{})
	go func() {
		()
		close()
	}()

	return 
}

// EnableDebugging sets env vars for debugging tested machines with am-dbg on
// port 6831.
func ( bool) {
	// skip for test runner
	if os.Getenv(am.EnvAmTestRunner) != "" {
		return
	}

	_ = os.Setenv(am.EnvAmDebug, "1")
	if  {
		_ = os.Setenv(EnvAmLogPrint, "1")
	}
	_ = os.Setenv(dbg.EnvAmDbgAddr, "1")
	_ = os.Setenv(EnvAmLogFull, "1")
	SetEnvLogLevel(am.LogOps)
	// _ = os.Setenv(EnvAmHealthcheck, "1")
}

// SetEnvLogLevel sets AM_LOG env var to the passed log level. It will affect
// all future state machines using MachDebugEnv.
func ( am.LogLevel) {
	_ = os.Setenv(am.EnvAmLog, strconv.Itoa(int()))
}

// Implements checks is statesChecked implement statesNeeded. It's an equivalent
// of Machine.Has(), but for slices of state names, and with better error msgs.
func (,  am.S) error {
	for ,  := range  {
		if !slices.Contains(, ) {
			return errors.New("missing state: " + )
		}
	}

	return nil
}

// LogArgs runs [ArgsToLogMap] on each [am.A] entry and returns a full log arg
// map. Useful for logging typed arguments.
func ( am.A,  int) map[string]string {
	 := map[string]string{}
	for ,  := range  {
		for ,  := range ArgsToLogMap(, ) {
			[] = 
		}
	}

	return 
}

// LogArgsMapper is [LogArgs] implementing [am.LogArgsMapperFn], so it fits into
// [am.SemLogger]. Typed args only.
func ( am.A) map[string]string {
	return LogArgs(, 0)
}

// ArgsToLogMap converts a typed arguments struct to a map of strings using
// `log` tags as keys, and their casted string values.
func ( any,  int) map[string]string {
	if  == 0 {
		 = max(4, am.LogArgsMaxLen)
	}
	 := false
	 := make(map[string]string)

	// ptr or value
	 := reflect.ValueOf()
	if .Kind() == reflect.Ptr {
		 = .Elem()
	}
	if !.IsValid() || .Kind() != reflect.Struct {
		return 
	}
	 := .Type()

	for  := 0;  < .NumField(); ++ {
		 := .Field()
		 := .Field().Tag.Get("log")
		if  == "" {
			continue
		}

		// check if the field is of a known type
		switch v := .Interface().(type) {
		// strings
		case string:
			if  == "" {
				continue
			}
			[] = 
		case []string:
			// combine []string into a single comma-separated string
			if len() == 0 {
				continue
			}
			 = true
			 := ""

			 := 0
			for ,  := range  {
				// check nil ptr
				 := reflect.ValueOf()
				if .Kind() == reflect.Ptr && .IsNil() {
					continue
				}

				if  != "" {
					 += ", "
				}

				 += `"` + utils.TruncateStr(, /2) + `"`
				if  >= /2 {
					 += fmt.Sprintf(" ... (%d more)", len()-)
					break
				}

				++
			}
			if  == "" {
				continue
			}
			[] = 

		case bool:
			// skip default
			if ! {
				continue
			}
			[] = fmt.Sprintf("%v", )
		case []bool:
			// combine []bool into a single comma-separated string
			if len() == 0 {
				continue
			}
			[] = fmt.Sprintf("%v", )
			// TODO fix highlighting issues in am-dbg
			[] = strings.Trim([], "[]")

		case int:
			// skip default
			if  == 0 {
				continue
			}
			[] = fmt.Sprintf("%d", )
		case []int:
			// combine []int into a single comma-separated string
			if len() == 0 {
				continue
			}
			[] = fmt.Sprintf("%d", )
			// TODO fix highlighting issues in am-dbg
			[] = strings.Trim([], "[]")

			// duration
		case time.Duration:
			if .Seconds() == 0 {
				continue
			}
			[] = .String()

			// MutString() method
		case fmt.Stringer:
			// check nil ptr
			 := reflect.ValueOf()
			if .Kind() == reflect.Ptr && .IsNil() {
				continue
			}

			// string
			 := .String()
			if  == "" {
				continue
			}
			[] = 

			// skip unknown types, besides []fmt.Stringer
		default:
			if .Kind() != reflect.Slice {
				continue
			}

			 := .Len()
			 = true
			 := ""
			 := 0

			for  := 0;  < ; ++ {
				 := .Index().Interface()
				,  := .(fmt.Stringer)
				if  && .String() != "" {
					if  != "" {
						 += ", "
					}
					 += `"` + utils.TruncateStr(.String(), /2) + `"`
					if  >= /2 {
						 += fmt.Sprintf(" ... (%d more)", -)
						break
					}
				}

				++
			}

			if  == "" {
				continue
			}
			[] = 
		}

		[] = strings.ReplaceAll([], "\n", " ")
		if ! && len([]) >  {
			[] = utils.TruncateStr([], )
		}
	}

	return 
}

type ArgsUnmarshallerFn func(args am.A) am.A

// ArgsUnmarshal deserializes JSON [args] into an instance of [def] under
// a "State.Arg" index. Useful for REPLs.
func [ am.ArgsApi]( am.A,  ) am.A {
	 := am.A{}
	// for all registered types
	 := map[string]string{}
	// find all prefix matches for state, eg "State.Arg"
	for ,  := range  {
		,  := strings.CutPrefix(, .ArgsState()+".")
		if ! {
			continue
		}
		,  := .(string)
		if ! {
			continue
		}
		[] = 
	}

	// decode string-json-byte-struct
	 := 
	,  := json.Marshal()
	if  != nil {
		return 
	}
	 = json.Unmarshal(, &)
	if  != nil {
		return 
	}

	// proper form
	[am.ArgIndex()] = &

	return 
}

// ArgsNames collect a flat list of names from a slice of typesafe arguments.
// Uses JSON encoding, useful for REPLs.
func ( []am.ArgsApi) ([]string, error) {
	var  []string
	for ,  := range  {
		// TODO optimize: custom func, json optional
		,  := json.Marshal()
		if  != nil {
			return nil, 
		}
		 := map[string]any{}
		if  := json.Unmarshal(, &);  != nil {
			return nil, 
		}

		// all arg names for this state
		for  := range  {
			// TODO better encoding
			 = append(, .ArgsState()+"."+)
		}
	}

	return , nil
}

// NewArgsUnmarshaller creates a new unmarshalling function for the
// provided argument
// [defs].
func ( []am.ArgsApi) ArgsUnmarshallerFn {
	return func( am.A) am.A {
		 := make([]am.A, len())
		for ,  := range  {
			[] = ArgsUnmarshal(, )
		}

		// return combined args
		return am.PassMerge(...)
	}
}

// IsDebug returns true if the process is in a "simple debug mode" via AM_DEBUG.
func () bool {
	return os.Getenv(am.EnvAmDebug) != "" && !IsTestRunner()
}

// IsWasm is true for browser WASM.
func () bool {
	return runtime.GOARCH == "wasm" && runtime.GOOS == "js"
}

// IsWasi is true for WASI envs.
func () bool {
	return runtime.GOARCH == "wasm" &&
		(runtime.GOOS == "wasip1" || runtime.GOOS == "wasip2")
}

// IsTelemetry returns true if the process is in telemetry debug mode.
func () bool {
	return os.Getenv(dbg.EnvAmDbgAddr) != "" && !IsTestRunner()
}

func () bool {
	return os.Getenv(EnvAmTestRunner) != ""
}

// GroupWhen1 will create wait channels for the same state in a group of
// machines, or return a [am.ErrStateMissing].
func (
	 []am.Api,  string,  context.Context,
) ([]<-chan struct{}, error) {
	// validate states
	for ,  := range  {
		if !.Has1() {
			return nil, fmt.Errorf(
				"%w: %s in machine %s", am.ErrStateMissing, , .Id(),
			)
		}
	}

	// create chans
	var  []<-chan struct{}
	for ,  := range  {
		 = append(, .When1(, ))
	}

	return , nil
}

// TODO func WhenAny1(mach am.Api, states am.S, ctx context.Context)
//  []<-chan struct{}

// RemoveMulti creates a final handler which removes a multi state from a
// machine. Useful to avoid FooState-Remove1-Foo repetition.
func ( am.Api,  string) am.HandlerFinal {
	return func( *am.Event) {
		.Remove1(, nil)
	}
}

// GetTransitionStates will extract added, removed, and touched states from
// transition's clock values and steps. Requires a state names index.
// Collecting touched states requires transition steps.
//
// See also [am.Transition.TimeIndexDiff] and
// [am.Transition.TimeIndexTouched].
func (
	 *am.Transition,  am.S,
) ( am.S,  am.S,  am.S) {
	 := .TimeBefore
	 := .TimeAfter

	 := func( am.Time,  int) bool {
		return  != nil && am.IsActiveTick(.Tick())
	}

	for ,  := range  {
		if (, ) && !(, ) {
			 = append(, )
		} else if !(, ) && (, ) {
			 = append(, )
		} else if  != nil && .Tick() != .Tick() {
			// treat multi states as added
			 = append(, )
		}
	}

	// touched
	 = am.S{}
	for ,  := range .Steps {
		if  := .GetFromState();  != "" {
			 = append(, )
		}
		if  := .GetToState();  != "" {
			 = append(, )
		}
	}

	return , , utils.SlicesUniq()
}

// TODO batch and merge with am-dbg
// func Batch(input <-chan any, state string, arg string, window time.Duration,
//   maxElement int) {
//
// }

func ( am.Result) error {
	switch  {
	case am.Canceled:
		return am.ErrCanceled
	// case am.Queued:
	// 	return am.ErrQueued
	default:
		return nil
	}
}

type MachGroup []am.Api

func ( *MachGroup) ( string) bool {
	if  == nil {
		return false
	}

	for ,  := range * {
		if .Not1() {
			return false
		}
	}

	return true
}

// Pool creates a highly configurable pond pool. Use SubmitErr or Submit on the
// result.
func ( context.Context,  int) pond.TaskGroup {
	 := pond.NewPool()
	return .NewGroupContext()
}

// ///// ///// /////

// ///// CONDITION

// ///// ///// /////

// Cond is a set of state conditions, which when all met make the condition
// true.
type Cond struct {
	// TODO IsMatch, AnyMatch, ... for regexps

	// Only if all these states are active.
	Is S
	// Only if any of these groups of states are active.
	Any []S
	// Only if any of these states is active.
	Any1 S
	// Only if none of these states are active.
	Not S
	// Only if the clock is equal or higher then.
	Clock am.Clock

	// TODO time queries
	// Query string
	// AnyQuery string
	// NotQuery string
}

func ( Cond) () string {
	return fmt.Sprintf("is: %s, any: %s, not: %s, clock: %v",
		.Is, .Any1, .Not, .Clock)
}

// Check compares the specified conditions against the passed machine. When mach
// is nil, Check returns false.
func ( Cond) ( am.Api) bool {
	if  == nil {
		return false
	}

	if !.Is(.Is) {
		return false
	}
	if .Any1(.Not...) {
		return false
	}
	if len(.Any1) > 0 && !.Any1(.Any1...) {
		return false
	}
	if len(.Any) > 0 && !.Any(.Any...) {
		return false
	}
	if !.WasClock(.Clock) {
		return false
	}

	return true
}

// IsEmpty returns false if no condition is defined.
func ( Cond) () bool {
	return .Is == nil && .Any1 == nil && .Not == nil && .Clock == nil
}

// ///// ///// /////

// ///// STATE LOOP

// ///// ///// /////

// TODO thread safety via atomics
type StateLoop struct {
	ResetInterval time.Duration
	// max ticks
	Threshold int

	loopState string
	ctxStates am.S
	mach      am.Api
	ended     bool
	check     func() bool

	// last seen machine time
	lastMTime uint64
	lastHTime time.Time
	// machine time of [ctxStates] when started
	startMTime uint64
	// Start Human Time
	startHTime time.Time
}

func ( *StateLoop) () string {
	 := "ok"
	if .ended {
		 = "ended"
	}

	return fmt.Sprintf("StateLoop: %s for %s/%s", , .mach.Id(), .loopState)
}

// Break breaks the loop.
func ( *StateLoop) () {
	.ended = true
	.mach.Log(.String())
}

// Sum returns a sum of state time from all context states.
func ( *StateLoop) () uint64 {
	return .mach.Time(.ctxStates).Sum(nil)
}

// Ok returns true if the loop should continue.
func ( *StateLoop) ( context.Context) bool {
	if .ended {
		return false
	} else if  != nil && .Err() != nil {
		 := fmt.Errorf("loop: arg ctx expired for %s/%s", .mach.Id(),
			.loopState)
		.mach.AddErr(, nil)
		.ended = true

		return false

	} else if .mach.Not1(.loopState) {
		 := fmt.Errorf("loop: state ctx expired for %s/%s", .mach.Id(),
			.loopState)
		.mach.AddErr(, nil)
		.ended = true

		return false
	}

	// stop on a function check
	if .check != nil && !.check() {
		.ended = true

		return false
	}

	// reset counters on a new interval window
	 := .mach.Time(.ctxStates).Sum(nil)
	if time.Since(.lastHTime) > .ResetInterval {
		.lastHTime = time.Now()
		.lastMTime = 

		return true

		// check the current interval window
	} else if int() > .Threshold {
		 := fmt.Errorf("loop: threshold exceeded for %s/%s", .mach.Id(),
			.loopState)
		.mach.AddErr(, nil)
		.ended = true

		return false
	}

	.lastMTime = 

	return true
}

// Ended returns the ended flag, but does not any context. Useful for
// negotiation handles which don't have state context yet.
func ( *StateLoop) () bool {
	return .ended
}

// NewStateLoop helper creates a state loop guard bound to a specific state
// (eg Heartbeat), preventing infinite loops. It monitors context, off states,
// ticks of related "context states", and an optional check function. We can
// adjust Threshold and ResetInterval.
// Not thread safe ATM.
func (
	 *am.Machine,  string,  func() bool,
) *StateLoop {
	 := .Schema()
	if !.Has1() {
		return &StateLoop{ended: true}
	}

	// collect related states
	 := S{}

	// collect dependencies of the loopState
	 = append(, [].Require...)

	// collect states adding the loop state TODO auto states from the tx?
	 := .Resolver()
	,  := .InboundRelationsOf()
	for ,  := range  {
		,  := .RelationsBetween(, )
		if len() > 0 {
			 = append(, )
		}
	}

	 := &StateLoop{
		ResetInterval: time.Second,
		Threshold:     500,

		loopState:  ,
		mach:       ,
		ctxStates:  ,
		startHTime: time.Now(),
		startMTime: .Time().Sum(nil),
		check:      ,
	}
	.Log(.String())

	return 
}

// ///// ///// /////

// ///// LOGGING

// ///// ///// /////

// SlogToMachLogOpts complements SlogToMachLog.
var SlogToMachLogOpts = &slog.HandlerOptions{
	ReplaceAttr: func( []string,  slog.Attr) slog.Attr {
		// omit these
		if .Key == slog.TimeKey || .Key == slog.LevelKey {
			return slog.Attr{}
		}
		return 
	},
}

// SlogToMachLog allows to use the machine logger as a slog sink.
//
//	a.loggerMach = slog.New(slog.NewTextHandler(
//		amhelp.SlogToMachLog{Mach: mach}, amhelp.SlogToMachLogOpts))
type SlogToMachLog struct {
	Mach am.Api
}

func ( SlogToMachLog) ( []byte) ( int,  error) {
	,  := strings.CutPrefix(string(), "msg=")
	.Mach.Log()
	return len(), nil
}

// MachToSlog exposes machine logger as [slog.Logger].
func ( am.Api) *slog.Logger {
	return slog.New(slog.NewTextHandler(
		SlogToMachLog{Mach: }, SlogToMachLogOpts,
	))
}

// ///// ///// /////

// ///// STATE UTILS

// ///// ///// /////

// TagValue returns the value part from a text tag "key:value". For tag without
// value, it returns the tag name.
func ( []string,  string) string {
	for ,  := range  {
		// no value
		if  ==  {
			return 
		}

		// check value
		 :=  + ":"
		if !strings.HasPrefix(, ) {
			continue
		}

		,  := strings.CutPrefix(, )
		return 
	}

	return ""
}

// TagValueInt is like TagValue, but returns a formatted int.
func ( []string,  string) int {
	 := TagValue(, )
	if  == "" {
		return -1
	}
	,  := strconv.Atoi()
	return 
}

// CountRelations will count all referenced states in all relations of the
// given state.
func ( *am.State) int {
	return len(.Remove) + len(.Add) + len(.Require) +
		len(.After)
}

// NewMirror creates a submachine which mirrors the given source machine. If
// [flat] is true, only mutations changing the state will be propagated, along
// with the currently active states.
//
// At this point, the handlers' struct needs to be defined manually with fields
// of type `am.HandlerFinal`.
//
// [id] is optional.
func (
	 string,  bool,  *am.Machine,  any,  am.S,
) (*am.Machine, error) {
	// TODO create handlers
	// TODO dont create a new machine, add to an existing one

	 := reflect.ValueOf()
	if .Kind() != reflect.Ptr || .Elem().Kind() != reflect.Struct {
		return nil, errors.New("BindHandlers expects a pointer to a struct")
	}
	 := .Elem()

	// detect methods
	var  []string
	,  := listHandlers(, )
	if  != nil {
		return nil, fmt.Errorf("listing handlers: %w", )
	}

	// TODO support am.Api
	if  == "" {
		 = "mirror-" + .Id()
	}
	 := .Schema()
	 := am.S{am.StateException}
	 := am.Schema{}
	for ,  := range  {
		[] = am.State{
			Multi: [].Multi,
		}
		 = append(, )
	}
	 := am.New(.Context(), , &am.Opts{
		Id:     ,
		Parent: ,
	})

	// set up pipes TODO loop over handlers
	for ,  := range  {
		var  string
		var  bool
		 := .FieldByName()

		// check handler method
		if strings.HasSuffix(, am.SuffixState) {
			 = [:len()-len(am.SuffixState)]
			 = true
		} else if strings.HasSuffix(, am.SuffixEnd) {
			 = [:len()-len(am.SuffixEnd)]
		} else {
			return nil, fmt.Errorf("unsupported handler %s for %s", , )
		}

		// pipe
		var  am.HandlerFinal
		if  {
			// sync active for flats
			if .Is1() {
				.Add1(, nil)
			}
			if  {
				 = ampipe.AddFlat(, , , "")
			} else {
				 = ampipe.RemoveFlat(, , , "")
			}

		} else {
			if  {
				 = ampipe.Add(, , , "")
			} else {
				 = ampipe.Remove(, , , "")
			}
		}

		.Set(reflect.ValueOf())
	}

	// bind pipe handlers
	if ,  := .HandlersBind();  != nil {
		return nil, 
	}

	return , nil
}

// ListHandlers returns a list of handler method names from a handler struct,
// limited to [states].
func listHandlers( any,  S) ([]string, error) {
	var  []string
	var  []error

	 := func( string) {
		,  := am.IsHandler(, )
		if  != "" && !slices.Contains(, ) {
			 = append(, fmt.Errorf(
				"%w: %s from handler %s", am.ErrStateMissing, , ,
			))
		}
		if  != "" && !slices.Contains(, ) {
			 = append(, fmt.Errorf(
				"%w: %s from handler %s", am.ErrStateMissing, , ,
			))
		}

		if  != "" ||  == am.StateAny+am.SuffixEnter ||
			 == am.StateAny+am.SuffixState {

			 = append(, )
			// TODO verify method signatures early (returns and params)
		}
	}

	// methods
	 := reflect.TypeOf()
	for  := 0;  < .NumMethod(); ++ {
		 := .Method().Name
		()
	}

	// fields
	 := reflect.ValueOf().Elem()
	 := .Type()
	for  := 0;  < .NumField(); ++ {
		 := .Field().Type.Kind()
		if  != reflect.Func {
			continue
		}
		 := .Field().Name
		()
	}

	return , errors.Join(...)
}

// CopySchema copies states from the source to target schema, from the passed
// list of states. Returns a list of copied states, and an error. CopySchema
// verifies states.
func ( am.Schema,  *am.Machine,  am.S) error {
	if len() == 0 {
		return nil
	}

	 := .Schema()
	for ,  := range  {
		if ,  := []; ! {
			return fmt.Errorf("%w: state %s in source schema",
				am.ErrStateMissing, )
		}

		[] = []
	}
	 := utils.SlicesUniq(slices.Concat(.StateNames(), ))

	return .SetSchema(, )
}

// SchemaHash computes an MD5 hash of the passed schema. The order of states
// is not important.
func ( am.Schema) string {
	 := ""
	if  == nil {
		return ""
	}

	 := slices.Collect(maps.Keys())
	sort.Strings()

	for ,  := range  {
		 +=  + ":"

		// properties
		if [].Auto {
			 += "a,"
		}
		if [].Multi {
			 += "m,"
		}

		// relations
		 := slices.Clone([].After)
		sort.Strings()
		for ,  := range  {
			 +=  + ","
		}
		 += ";"

		 := slices.Clone([].Remove)
		sort.Strings()
		for ,  := range  {
			 +=  + ","
		}
		 += ";"

		 := slices.Clone([].Add)
		sort.Strings()
		for ,  := range  {
			 +=  + ","
		}
		 += ";"

		 := slices.Clone([].Require)
		sort.Strings()
		for ,  := range  {
			 +=  + ","
		}
		 += ";"
	}

	return am.Hash(, 6)
}

// TODO MachHash(...)

// EvalGetter is a syntax sugar for creating getters via Eval functions. Like
// any eval, it can end with ErrEvalTimeout. Getting values via channels passed
// to mutations is recommended and allows for a custom timeout.
func [ any](
	 context.Context,  string,  int,  *am.Machine,
	 func() (, error),
) (, error) {
	//

	var  
	var  error
	 := func() {
		// getter err
		,  = ()
	}

	// try at least once
	for range min(, 1) {
		if !.Eval("Get/"+, , ) {
			// eval err
			 = fmt.Errorf("%w: EvalGet/%s", am.ErrEvalTimeout, )
		} else {
			break
		}
	}

	return , 
}

func (
	 context.Context,  string,  int,  *am.Machine,
	 func() error,
) error {
	//

	var  error
	 := func() {
		// setter err
		 = ()
	}

	// try at least once
	for range min(, 1) {
		if !.Eval("Set/"+, , ) {
			// eval err
			 = fmt.Errorf("%w: EvalSet/%s", am.ErrEvalTimeout, )
		} else {
			break
		}
	}

	return 
}

// TODO ChanGetter

// ///// ///// /////

// ///// CAN

// ///// ///// /////

// CantAdd will confirm that the mutation is impossible. Blocks.
func ( am.Api,  am.S,  am.A) bool {
	 := &am.ACheck{
		CheckDone: make(chan struct{}),
	}
	.CanAdd(, am.PassMerge(, am.Pass()))
	<-.CheckDone

	return !.Canceled
}

// CantAdd1 is a single-state version of [CantAdd].
func ( am.Api,  string,  am.A) bool {
	return .CanAdd(am.S{}, ) == am.Canceled
}

// CantRemove will confirm that the mutation is impossible. Blocks.
func ( am.Api,  am.S,  am.A) bool {
	 := &am.ACheck{
		CheckDone: make(chan struct{}),
	}
	.CanRemove(, am.PassMerge(, am.Pass()))
	<-.CheckDone

	return .Canceled
}

// CantRemove1 is a single-state version of [CantRemove].
func ( am.Api,  string,  am.A) bool {
	return .CanRemove(am.S{}, ) == am.Canceled
}

// AskAdd will first check if a mutation isn't impossible and only then try
// to mutate the state machine. Causes the negotiation phase to execute twice.
// AskAdd BLOCKS. Useful to avoid canceled transitions.
//
// See also [am.Machine.CanAdd] and [CantAdd].
func ( am.Api,  am.S,  am.A) am.Result {
	return AskEvAdd(nil, , , )
}

// AskEvAdd is a traced version of [AskAdd].
func ( *am.Event,  am.Api,  am.S,  am.A) am.Result {
	// only if not impossible
	if !CantAdd(, , ) {
		return .EvAdd(, , )
	}

	return am.Canceled
}

// AskAdd1 is a single-state version of [AskAdd].
func ( am.Api,  string,  am.A) am.Result {
	return AskAdd(, S{}, )
}

// AskEvAdd1 is a traced version of [AskAdd] for a single state.
func ( *am.Event,  am.Api,  string,  am.A) am.Result {
	return AskEvAdd(, , S{}, )
}

// AskRemove will first check if a mutation isn't impossible and only then try
// to mutate the state machine. Causes the negotiation phase to execute twice.
// AskRemove BLOCKS. Useful to avoid canceled transitions.
//
// See also [am.Machine.CanRemove] and [CantRemove].
func ( am.Api,  am.S,  am.A) am.Result {
	return AskEvRemove(nil, , , )
}

// AskEvRemove is a traced version of [AskRemove].
func ( *am.Event,  am.Api,  am.S,  am.A) am.Result {
	// only if not impossible
	if !CantRemove(, , ) {
		return .EvRemove(, , )
	}

	return am.Canceled
}

// AskRemove1 is a single-state version of [AskRemove].
func ( am.Api,  string,  am.A) am.Result {
	return AskRemove(, S{}, )
}

// AskEvRemove1 is a traced version of [AskRemove] for a single state.
func ( *am.Event,  am.Api,  string,  am.A) am.Result {
	return AskEvRemove(, , S{}, )
}

// DisposeBind registers a disposal handler, using either the dedicated state
// set or the machine directly.
func ( am.Api,  am.HandlerDispose) {
	// via DisposedStates
	 := ssam.DisposedStates.RegisterDisposal
	if .Has1() {
		.Add1(, am.A{
			ssam.DisposedArgHandler: ,
		})

		return
	}

	// directly
	.OnDispose()
}

// Dispose triggers a machine disposal, using either the dedicated state set
// or the machine directly.
func ( am.Api) {
	// via DisposedStates
	 := ssam.DisposedStates.Disposing
	if .Has1() {
		.Add1(, nil)

		return
	}

	// directly
	.Dispose()
}

// DisposeEv is like [DisposeEv], but accepts a source event.
func ( am.Api,  *am.Event) {
	// via DisposedStates
	 := ssam.DisposedStates.Disposing
	if .Has1() {
		.EvAdd1(, , nil)

		return
	}

	// directly
	.Dispose()
}

// SchemaImplements checks if a given schema implements a certain set of states.
func ( am.Schema,  am.S) error {
	return Implements(.Names(), )
}

// HandlerToState returns a state name from a handler name.
func ( string) string {
	return strings.TrimSuffix(
		strings.TrimSuffix(
			strings.TrimSuffix(
				strings.TrimSuffix(,
					am.SuffixState), am.SuffixEnter,
			), am.SuffixEnd,
		), am.SuffixExit,
	)
}

// RandId generates a random ID of the given length (defaults to 8).
func ( int) string {
	if  == 0 {
		 = 16
	}
	++
	 =  / 2

	 := make([]byte, )
	,  := rand.Read()
	if  != nil {
		return "error"
	}

	return hex.EncodeToString()
}

// WhenFunc converts a blocking call to a broadcast channel, which can be used
// in `select`.
func ( func()) <-chan struct{} {
	 := make(chan struct{})

	go func() {
		()
		close()
	}()

	return 
}

// WhenFuncOk converts a blocking call to a bool send channel, which can be used
// in `select`.
func ( func() bool) <-chan bool {
	 := make(chan bool)

	go func() {
		if () {
			 <- true
		}
		close()
	}()

	return 
}