stateup.h

#ifndef STATEUP_H
#define STATEUP_H

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

/**
 * Default per-thread recursion limit, mirroring the C++ value.
 */
#define DEFAULT_MAX_RECURSION_DEPTH 1000

/**
 * We need `StateupBbEventKind` defined before the typedef above uses
 * it, so declare it here — the "real" enum body is a little further
 * down where the observer API is defined.
 */
typedef enum {
  STATEUP_BB_EVENT_KIND_STATEUP_BB_EVENT_KIND_SET = 0,
  STATEUP_BB_EVENT_KIND_STATEUP_BB_EVENT_KIND_GET = 1,
  STATEUP_BB_EVENT_KIND_STATEUP_BB_EVENT_KIND_REMOVE = 2,
  STATEUP_BB_EVENT_KIND_STATEUP_BB_EVENT_KIND_CLEAR = 3,
  STATEUP_BB_EVENT_KIND_STATEUP_BB_EVENT_KIND_SCOPE_PUSHED = 4,
  STATEUP_BB_EVENT_KIND_STATEUP_BB_EVENT_KIND_SCOPE_POPPED = 5,
} StateupBbEventKind;

typedef enum {
  STATEUP_MEMORY_POLICY_STATEUP_MEMORY_POLICY_REMEMBER_SUCCESS = 0,
  STATEUP_MEMORY_POLICY_STATEUP_MEMORY_POLICY_REMEMBER_FAILURE = 1,
  STATEUP_MEMORY_POLICY_STATEUP_MEMORY_POLICY_REMEMBER_FINISHED = 2,
  STATEUP_MEMORY_POLICY_STATEUP_MEMORY_POLICY_REMEMBER_ALL = 3,
} StateupMemoryPolicy;

typedef enum {
  STATEUP_STATUS_STATEUP_STATUS_SUCCESS = 0,
  STATEUP_STATUS_STATEUP_STATUS_FAILURE = 1,
  STATEUP_STATUS_STATEUP_STATUS_RUNNING = 2,
  STATEUP_STATUS_STATEUP_STATUS_IDLE = 3,
} StateupStatus;

typedef struct StateupBlackboard StateupBlackboard;

typedef struct StateupSmBuilder StateupSmBuilder;

typedef struct StateupStateMachine StateupStateMachine;

/**
 * Opaque runnable behavior-tree handle.
 */
typedef struct StateupTree StateupTree;

/**
 * Opaque tree-builder handle. Create → add nodes → build → consume.
 */
typedef struct StateupTreeBuilder StateupTreeBuilder;

typedef void (*StateupBbObserverFn)(StateupBbEventKind kind, const char *key, void *userdata);

typedef int (*StateupBoolFn)(StateupBlackboard *bb, void *userdata);

typedef StateupStatus (*StateupActionFn)(StateupBlackboard *bb, void *userdata);

typedef void (*StateupHookFn)(StateupBlackboard *bb, void *userdata);

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

const char *stateup_last_error_message(void);

void stateup_string_free(char *s);

StateupBlackboard *stateup_blackboard_new(void);

void stateup_blackboard_free(StateupBlackboard *bb);

int stateup_blackboard_set_int(StateupBlackboard *bb, const char *key, int64_t value);

int stateup_blackboard_set_double(StateupBlackboard *bb, const char *key, double value);

int stateup_blackboard_set_bool(StateupBlackboard *bb, const char *key, int value);

int stateup_blackboard_set_string(StateupBlackboard *bb, const char *key, const char *value);

int stateup_blackboard_get_int(const StateupBlackboard *bb, const char *key, int64_t *out);

int stateup_blackboard_get_double(const StateupBlackboard *bb, const char *key, double *out);

int stateup_blackboard_get_bool(const StateupBlackboard *bb, const char *key, int *out);

/**
 * Returns a newly-allocated string; caller owns it and must free with
 * [`stateup_string_free`]. Returns NULL on miss.
 */
char *stateup_blackboard_get_string(const StateupBlackboard *bb, const char *key);

int stateup_blackboard_has(const StateupBlackboard *bb, const char *key);

int stateup_blackboard_remove(StateupBlackboard *bb, const char *key);

int stateup_blackboard_clear(StateupBlackboard *bb);

/**
 * Returns the number of top-level keys. Pass a buffer of `cap` pointers
 * in `out_keys` — the library writes up to `cap` heap-allocated
 * NUL-terminated strings into it (caller frees each with
 * [`stateup_string_free`]).
 */
uintptr_t stateup_blackboard_keys(const StateupBlackboard *bb, char **out_keys, uintptr_t cap);

/**
 * Push a new blackboard scope. Nested scopes shadow their parent.
 */
int stateup_blackboard_push_scope(StateupBlackboard *bb);

/**
 * Install a C-callable observer on a standalone `StateupBlackboard`.
 * Observers on shared-mode blackboards (the ones passed to callbacks)
 * are not supported — install the observer before handing the
 * blackboard to a tree or state machine.
 */
int stateup_blackboard_set_observer(StateupBlackboard *bb,
                                    StateupBbObserverFn func,
                                    void *userdata);

StateupTreeBuilder *stateup_tree_builder_new(void);

void stateup_tree_builder_free(StateupTreeBuilder *b);

int stateup_tree_builder_sequence(StateupTreeBuilder *b);

int stateup_tree_builder_selector(StateupTreeBuilder *b);

int stateup_tree_builder_parallel(StateupTreeBuilder *b,
                                  uintptr_t success,
                                  int failure_enabled,
                                  uintptr_t failure);

int stateup_tree_builder_random_selector(StateupTreeBuilder *b);

int stateup_tree_builder_probability_selector(StateupTreeBuilder *b);

int stateup_tree_builder_weighted_random_selector(StateupTreeBuilder *b);

int stateup_tree_builder_one_shot_sequence(StateupTreeBuilder *b);

int stateup_tree_builder_reactive_sequence(StateupTreeBuilder *b);

int stateup_tree_builder_inverter(StateupTreeBuilder *b);

int stateup_tree_builder_succeeder(StateupTreeBuilder *b);

int stateup_tree_builder_failer(StateupTreeBuilder *b);

int stateup_tree_builder_repeat(StateupTreeBuilder *b, uintptr_t n);

int stateup_tree_builder_retry(StateupTreeBuilder *b, uintptr_t n);

int stateup_tree_builder_retry_with_backoff(StateupTreeBuilder *b,
                                            uintptr_t attempts,
                                            uint64_t base_ms,
                                            float multiplier,
                                            uint64_t cap_ms);

int stateup_tree_builder_timeout_ms(StateupTreeBuilder *b, uint64_t ms);

int stateup_tree_builder_cooldown_ms(StateupTreeBuilder *b, uint64_t ms);

int stateup_tree_builder_cooldown_with_jitter_ms(StateupTreeBuilder *b,
                                                 uint64_t base_ms,
                                                 uint64_t jitter_ms);

int stateup_tree_builder_for_loop(StateupTreeBuilder *b, uintptr_t count);

int stateup_tree_builder_memory(StateupTreeBuilder *b, StateupMemoryPolicy policy);

int stateup_tree_builder_while_loop(StateupTreeBuilder *b, StateupBoolFn cond, void *userdata);

int stateup_tree_builder_with_score(StateupTreeBuilder *b, double score);

int stateup_tree_builder_with_weight(StateupTreeBuilder *b, double weight);

int stateup_tree_builder_with_probability(StateupTreeBuilder *b, double prob);

int stateup_tree_builder_with_priority(StateupTreeBuilder *b, int64_t priority);

int stateup_tree_builder_action(StateupTreeBuilder *b, StateupActionFn func, void *userdata);

int stateup_tree_builder_named_action(StateupTreeBuilder *b,
                                      const char *name,
                                      StateupActionFn func,
                                      void *userdata);

int stateup_tree_builder_end(StateupTreeBuilder *b);

StateupTree *stateup_tree_builder_build(StateupTreeBuilder *b);

StateupTree *stateup_tree_from_json(const char *json);

void stateup_tree_free(StateupTree *tree);

StateupStatus stateup_tree_tick(StateupTree *tree);

void stateup_tree_reset(StateupTree *tree);

void stateup_tree_halt(StateupTree *tree);

int stateup_tree_bb_set_int(StateupTree *tree, const char *key, int64_t value);

int stateup_tree_bb_set_double(StateupTree *tree, const char *key, double value);

int stateup_tree_bb_set_bool(StateupTree *tree, const char *key, int value);

int stateup_tree_bb_set_string(StateupTree *tree, const char *key, const char *value);

int stateup_tree_bb_get_int(const StateupTree *tree, const char *key, int64_t *out);

int stateup_tree_bb_get_double(const StateupTree *tree, const char *key, double *out);

int stateup_tree_bb_get_bool(const StateupTree *tree, const char *key, int *out);

char *stateup_tree_bb_get_string(const StateupTree *tree, const char *key);

char *stateup_tree_to_dot(const StateupTree *tree);

char *stateup_tree_to_mermaid(const StateupTree *tree);

StateupSmBuilder *stateup_sm_builder_new(void);

void stateup_sm_builder_free(StateupSmBuilder *b);

int stateup_sm_builder_initial(StateupSmBuilder *b, const char *name);

int stateup_sm_builder_state(StateupSmBuilder *b, const char *name);

int stateup_sm_builder_on_enter(StateupSmBuilder *b, StateupHookFn func, void *userdata);

int stateup_sm_builder_on_update(StateupSmBuilder *b, StateupHookFn func, void *userdata);

int stateup_sm_builder_on_exit(StateupSmBuilder *b, StateupHookFn func, void *userdata);

int stateup_sm_builder_on_guard(StateupSmBuilder *b, StateupBoolFn func, void *userdata);

int stateup_sm_builder_transition_to(StateupSmBuilder *b,
                                     const char *target,
                                     StateupBoolFn guard,
                                     void *userdata);

int stateup_sm_builder_transition_to_after_ms(StateupSmBuilder *b,
                                              const char *target,
                                              uint64_t duration_ms,
                                              StateupBoolFn guard,
                                              void *userdata);

int stateup_sm_builder_with_action(StateupSmBuilder *b, StateupHookFn func, void *userdata);

int stateup_sm_builder_with_priority(StateupSmBuilder *b, int32_t priority);

int stateup_sm_builder_with_probability(StateupSmBuilder *b, float prob);

int stateup_sm_builder_with_weight(StateupSmBuilder *b, float w);

int stateup_sm_builder_internal(StateupSmBuilder *b);

int stateup_sm_builder_ignore_event(StateupSmBuilder *b);

int stateup_sm_builder_cannot_happen(StateupSmBuilder *b);

int stateup_sm_builder_on_event(StateupSmBuilder *b, const char *event_name, const char *target);

int stateup_sm_builder_on_event_from_any(StateupSmBuilder *b,
                                         const char *event_name,
                                         const char *target);

StateupStateMachine *stateup_sm_builder_build(StateupSmBuilder *b);

void stateup_state_machine_free(StateupStateMachine *sm);

int stateup_state_machine_tick(StateupStateMachine *sm);

void stateup_state_machine_reset(StateupStateMachine *sm);

char *stateup_state_machine_current_state(const StateupStateMachine *sm);

int stateup_state_machine_go_to_previous(StateupStateMachine *sm);

int stateup_state_machine_handle_event(StateupStateMachine *sm, const char *event_name);

int stateup_state_machine_enable_history(StateupStateMachine *sm, int enable);

uintptr_t stateup_state_machine_state_history_len(const StateupStateMachine *sm);

char *stateup_state_machine_state_history_at(const StateupStateMachine *sm, uintptr_t index);

/**
 * Blackboard accessors mirroring the tree side.
 */
int stateup_state_machine_bb_set_int(StateupStateMachine *sm, const char *key, int64_t value);

int stateup_state_machine_bb_set_bool(StateupStateMachine *sm, const char *key, int value);

int stateup_state_machine_bb_set_string(StateupStateMachine *sm,
                                        const char *key,
                                        const char *value);

int stateup_state_machine_bb_get_int(const StateupStateMachine *sm, const char *key, int64_t *out);

int stateup_state_machine_bb_get_bool(const StateupStateMachine *sm, const char *key, int *out);

char *stateup_state_machine_bb_get_string(const StateupStateMachine *sm, const char *key);

char *stateup_state_machine_to_dot(const StateupStateMachine *sm);

char *stateup_state_machine_to_mermaid(const StateupStateMachine *sm);

char *stateup_state_machine_snapshot_json(const StateupStateMachine *sm);

int stateup_state_machine_restore_json(StateupStateMachine *sm, const char *json);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* STATEUP_H */